RubyLLM Workbench v0.1.0

RubyLLM Workbench v0.1.0

The first public release of RubyLLM Workbench is a local-first Rails reference
application for inspectable AI workflows. It connects RubyLLM's APIs to durable
Rails records, background jobs, approvals, source evidence and evaluations.
Explore the synthetic tour without provider keys, then follow the source and
tests behind each flow.

This is an independent, single-user developer workbench. It has no accounts,
team administration, billing or tenant isolation. The repository and original
Rails case-study corpus use the
MIT license.

Included in this release

• Persisted streaming Chat and structured-output comparisons, with frozen
  inputs, separate Attempts, finish reasons and lifecycle events.
• Code-registered tools with human approval, and revisioned saved Agents with
  a durable outbox, execution leases, cancellation and recovery that avoids
  silently replaying provider work.
• Knowledge ingestion, provider embeddings, lexical/semantic/hybrid retrieval
  and optional reranking, with visible source provenance and separately owned
  usage records.
• An original Mini Notes Rails corpus and cited source-answer Runs. Retrieval
  freezes source/vector revisions and bounded excerpts; answers validate exact
  quotes and can refuse locally when evidence is absent.
• Native RubyLLM::Evaluation over saved answers, using local assertions or a
  model reviewer without regenerating the original answer. A supported native
  typed Judge path also has offline protocol coverage.
• Revisioned evaluation datasets, per-case Runs, append-only human reviews,
  an experimental rubric judge and capability-gated Batch evaluation.
• Experimental speech, transcription, image and video flows; bounded,
  best-effort-redacted reproduction/event exports and upstream issue drafts.
• A separate read-only synthetic demo, source-linked learning panels,
  execution diagrams and a
  ten-minute showcase.

Install and explore

Use Ruby 4.0.2, Node.js 24.21.0, and the committed lockfiles. This release
locks Rails 8.1.4 and RubyLLM 2.1.0 and uses SQLite. Native libvips is
optional for ordinary boot; install it when using Active Storage image variants.

The release assets include a tracked-source .tar.gz and SHA256SUMS.
Download both into the same directory and run shasum -a 256 -c SHA256SUMS
before extracting. GitHub also provides source archives from the version tag.

From a clean checkout, with Ruby installed and nvm available:

git clone --branch v0.1.0 https://github.com/yorzi/rubyllm-workbench.git
cd rubyllm-workbench
nvm install && nvm use
bin/setup --skip-server
bin/rails workbench:demo
bin/dev

Open http://127.0.0.1:3000. The tour uses invented records and makes no provider
requests; its responses, usage, costs and timings are illustrative. Stop
bin/dev with Ctrl-C when finished. This tour runs inside the editable local
workbench; follow the
read-only demo guide
to prepare and serve an isolated, read-only snapshot instead.

To use providers, copy .env.example to .env and edit it locally. bin/dev
loads .env; standalone Rails, dogfood and diagnostic commands use a securely
prepared environment or installation-local Rails credentials. Keep keys out of
command arguments, commits and shared artifacts. Setup, Docker and verification
commands are in
Operations.

Verification and acceptance limits

The capability matrix
is the evidence record, including versions, dates, models, executed checks and
remaining manual acceptance. Ordinary Rails tests use fakes and block external
Ruby HTTP. CI checks browser tests, security scans, asset compilation, a clean
Linux setup with and without libvips, and normal/read-only Docker runtime
behavior. Live-provider and public deployment acceptance have separate evidence; see the
verification snapshot.

Bounded OpenRouter free acceptance on 2026-10-09 covered core flows, a linked
hybrid/reranked source answer with native assertions/reviewer, and independent
raw REST and RubyLLM/Rails speech paths. Current speech uses OpenRouter Fish;
a local TTS service is optional. Details and failed or partial attempts remain
in the dated live record.
These checks establish integration and stored protocol evidence, not model,
retrieval or voice quality. Missing usage/cost stays unknown; catalog prices and
recorded cost subtotals do not establish an account invoice.

The following remain experimental or manual:

• The complete untrusted-source case group and full two-model evaluation
  comparison have partial current-version live evidence.
• Native typed Judge live acceptance and reviewer/Judge calibration are pending.
  An OpenRouter structured reviewer uses a different API from typed Judge.
• Current-version hosted search, transcription and image acceptance remain
  manual; older RubyLLM 2.0 results do not certify this release's 2.1 adapter.
• OCR, provider Batch, live parallel tool calls and video remain unverified
  against real providers. Durable video-job restoration and its ledger
  attribution are incomplete.
• MCP client and native OpenTelemetry examples are planned; framework migration
  tables alone do not implement these integrations.

Use the Roadmap
for follow-up development. Potential gem findings are recorded with their
verification gaps in
Upstream issues.

Existing installations and deployment

Before upgrading, stop web processes, workers and schedulers. Make consistent
backups of every SQLite database and uploaded file; copying an active database
can miss its WAL. Keep the previous application and lockfiles with the backup,
install this release's dependencies, run bin/rails db:migrate, and inspect
existing Chats and Runs before restarting. Downgrade migrations have not been
validated: restore a verified backup and the previous application instead.
See the upgrade procedure.

Keep the full workbench on trusted local access. Any deployment reachable by
others needs authentication, TLS and host checks; application access can spend
configured provider keys. The read-only viewer uses a separate synthetic
database, clears provider configuration and rejects mutations, uploads,
Active Storage downloads, Cable and job execution. Public demo hosting requires
its own deployment and external acceptance.

Request logging filters sensitive free-text inputs, but does not erase older
logs or control external proxy logs. Exports still require a privacy review
before sharing. Use tracked-source archives rather than zipping a workspace
containing ignored credentials, logs, databases or uploads. Report
vulnerabilities through the private channel described in
Security.

Release integrity

Tag v0.1.0 points to commit 51f529d836473e88bbbea1f4f76525a90e83efff.
All eight CI jobs for this commit passed.
The attached source archive and SHA256SUMS were downloaded from GitHub and
verified against the locally generated tracked-source package before publication.