omakase-agents 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c9bb739c426cb0b979359a772e7cdcbe84019c303d10c0d1c0b27fe8b8d00c0
-  data.tar.gz: 88c343d1a654d19be11b6071658e962be3f64dc477e8be1aa767520c3c7ac13f
+  metadata.gz: d0a1114c3a9af5c41d3111880844a2a74a182b23696226533c3d5076b3a3ce63
+  data.tar.gz: '049c62448ea9e6d3b96177bda1564b294cb47d08cc7aa7a514db321d0f617394'
 SHA512:
-  metadata.gz: 8d02d96784acf426a52dc5eb2207d3a426e9beddb1106cd96195941781557019823be03502e9c580253ff249a8dfa7df0d4210e7eace17a6cfaca1d362321151
-  data.tar.gz: 6fb9221fb891f4a9b0898b8924ec2705e093acfeba76367c57bde8d56810227da3ea9667036638360515797ceda2bf1d5edd442766f1fb87f44aeeaa75265166
+  metadata.gz: c1fb9143de3b2b934eb183e6c396a81a06d64ac8b505f28f0a311c2411aea56c09e64207f3c5789554f88bca34bbc0a9fe7654c276775383e559769f269d4775
+  data.tar.gz: 94f16e8c77584c2a0c120e93f470acd5ba46991c7503be695d267c4dae95b8e7124360121a0186ace47c8c4dea17caf4cb147d1abc3d86d8b07e6594c4cd3321

data/CHANGELOG.md

@@ -0,0 +1,99 @@
+# Changelog
+
+One entry per released version, written when the gem is pushed. Until `1.0`, a minor version may
+move the API — what breaks is listed first, so an upgrade is a decision rather than a surprise.
+
+## 0.3.0
+
+One thing changes under you: a generation may no longer call itself. The rest is additions — a real
+signature for the inputs, a trace to read a run by, a seam for the chat, and your own validations
+enforced on the way out.
+
+### Breaking
+
+- A generation may not re-enter itself. While `SupportAgent#reply` is running on an object, that
+  object's `reply` raises `Omakase::Error` instead of opening a second run. Generated code can see
+  the method and call it, and each nested call opened its own chat with its own tool budget — so the
+  budget bounded nothing. A *fresh* agent may still recurse: that is the sub-agents pattern, one
+  object per node of a tree, and the tree is the thing that ends.
+
+### Added
+
+- `takes:` names the keyword arguments, and then Ruby checks them:
+  `generates :translate, takes: %i[text language]`. A missing or misspelled argument is an
+  `ArgumentError` at the call rather than noise in a prompt, and the model reads the names instead
+  of `**inputs`. `with:` stays available for attachments. Anything that is not a plain keyword name
+  is refused where it is declared.
+- `Omakase::Trace` — the listener printed for a human: `Omakase.listener = Omakase::Trace.new`. A run
+  reads top to bottom: the call, the code the model wrote, the answer. Colour when the stream is a
+  terminal, plain when it is a log.
+- `Omakase.chat_factory` — how an agent gets a chat when none was injected. One line in
+  `test_helper.rb` keeps a whole suite off the network, including the class-level calls a job makes,
+  which have no seam to inject through. Anything answering `call(**options)` will do, and an
+  injected `chat:` still wins.
+- A `returns:` class that answers `valid?` and `errors` — which is every ActiveModel — is asked
+  before the answer is handed back, and an invalid one is refused. Under `:code_act` the refusal
+  reaches the model as `finish rejected: Post is invalid: …`, and it corrects itself inside the same
+  loop. Your validations are the contract, and they stay where you wrote them.
+- `doc(object)` takes a class as well as an instance: what an object of that type would offer, plus
+  the column names when it is a record. The model asks before it builds a type it has only been told
+  the name of.
+
+### Fixed
+
+- What generated code printed before `finish` is no longer lost — `Executor::Answer` carries it, so a
+  trace shows the working and not only the answer. `printed:` defaults, so a replacement executor
+  that knows the value alone still satisfies the seam.
+
+## 0.2.0
+
+Nothing breaks. Four additions, each one a keyword or a seam that costs nothing when unused.
+
+### Added
+
+- A prompt can be a block: `generates :translate, -> { "Translate to #{@language}." }`. It is read
+  at call time, on the agent, so one declaration serves an object however it is configured. A prompt
+  that is neither a String nor a block is refused where it is declared. In the capability list a
+  block-prompted method shows its signature alone — `describe` it to say more.
+- `generates :classify, model: "claude-haiku-4-5"` — a generation method can name its own model, a
+  cheap one beside a strong one. The id lands on top of the class's chat options, so the provider
+  stays the class's; an injected `chat:` still wins.
+- `Omakase.listener` — one callback for every step as it happens: `:generation` (`agent:, name:,
+  inputs:`), `:ruby` (`agent:, code:, outcome:`), `:answer` (`agent:, name:, value:`). Anything
+  answering `call(event, **payload)` will do; nil, the default, costs nothing.
+- `with:` is a reserved argument: it is not rendered into the prompt but passed to RubyLLM's
+  `ask(with:)` as attachments — images, audio, PDFs, as paths, URLs or IO. `FakeChat` records them.
+
+## 0.1.0
+
+First stable release. `0.0.x` was a prerelease and needed `gem install --pre`; this does not.
+
+### Breaking
+
+- `:code_act` with a Ruby class return type (`returns: SomeClass`) no longer falls back to
+  `:predict` when the model does not call `finish`. It could not have worked — a class cannot be
+  expressed as a JSON schema — and the fallback raised `returns: X needs the :code_act strategy`
+  from inside the wrong strategy. It now raises `ContractError` naming the method and the shape it
+  never returned. Schemas declared with a block or a scalar still fall back as before.
+- `doc(object)` stops at `ActiveRecord::Base` and prints a record's columns as state rather than as
+  methods. Output for an `ActiveRecord` object goes from several hundred lines of framework
+  internals to its associations, your methods, and the values it holds.
+- The prompt asks for `finish(Refund.new(order_id:, amount:, reason:))` where it used to say
+  `finish(a Refund)`, for any return type that answers `members` (a `Struct` or a `Data`).
+
+### Added
+
+- `mcp` — an MCP server's tools become methods on the agent, via `ruby_llm-mcp` (an optional
+  dependency; `require` it and options pass through verbatim).
+- `skill` — a `SKILL.md` directory becomes one described method: the front matter's description
+  joins the agent's capabilities, the body arrives only when the model calls it.
+- `memory` — `remember(text)` and `recall(query)` over RubyLLM embeddings, with the store as a
+  field, so it marshals with the agent.
+- `context` — an instance method to override; whatever it returns is appended to the class's
+  instructions on every call. The chat stays fresh per call, deliberately.
+- `Marshal.dump(agent)` is the session: an agent marshals like any object, minus its live chat.
+
+## 0.0.2.alpha, 0.0.1.alpha
+
+Prereleases. `Agent`, `generates`, `describe`, the `:predict` and `:code_act` strategies,
+`finish(value)`, `returns: SomeClass`, `doc`, per-thread output, `FakeChat`, and the Rails notes.

data/README.md

@@ -1,9 +1,9 @@
 # Omakase
 
-A light agent framework — about 700 lines of library. *Omakase* (お任せ): you name what you want,
+A light agent framework — about 800 lines of library. *Omakase* (お任せ): you name what you want,
 the rest is left to the chef.
 
-**[esshka.github.io/omakase](https://esshka.github.io/omakase/)** · [rubygems](https://rubygems.org/gems/omakase-agents) ![gem](https://img.shields.io/gem/v/omakase-agents?color=c8452e&label=)
+**[esshka.github.io/omakase](https://esshka.github.io/omakase/)** · [rubygems](https://rubygems.org/gems/omakase-agents) · [changelog](CHANGELOG.md) ![gem](https://img.shields.io/gem/v/omakase-agents?color=c8452e&label=)
 
 The whole philosophy: **an agent is an object**. Its fields are state, its methods are what the
 model can call, and the methods it *declares without a body* are written by the model at runtime —
@@ -54,7 +54,7 @@ method; deleting one is deleting a method.
 ## Why this
 
 Against **RubyLLM alone**: the tool loop, the schema plumbing, and the correction turn after a bad
-answer are what these 700 lines are. Everything else — providers, keys, models, streaming, tracing —
+answer are what these 800 lines are. Everything else — providers, keys, models, streaming, tracing —
 is still RubyLLM's, and stays reachable.
 
 Against **a framework with a tool registry**: there is nothing to register and nothing to keep in
@@ -79,6 +79,53 @@ gem "omakase-agents"     # the library is `Omakase`
 gem install omakase-agents
 ```
 
+## Quickstart
+
+One file, one working agent. Five minutes.
+
+**1.** Install the gem and set a key:
+
+```bash
+gem install omakase-agents
+export OPENROUTER_API_KEY=sk-or-...
+```
+
+**2.** Save this as `triage.rb`:
+
+```ruby
+require "omakase"
+
+Omakase.configure_from_env
+
+class TriageAgent < Omakase::Agent
+  model "meta/muse-glimmer-30b", provider: :openrouter
+  instructions "You triage customer support messages."
+  strategy :predict
+
+  generates :triage do
+    string :severity, enum: %w[low medium high]
+    string :summary
+  end
+end
+
+pp TriageAgent.triage(message: "The app crashes every time I open my invoices")
+```
+
+**3.** Run it:
+
+```bash
+ruby triage.rb
+```
+
+A Ruby Hash comes back, matching the schema you declared:
+
+```ruby
+{severity: "high", summary: "App crashes on opening invoices"}
+```
+
+You wrote no JSON parsing and registered no tool. Next: [Usage](#usage) for the rest of the
+API, or [How it works](#how-it-works) for why it is built this way.
+
 ## Usage
 
 The whole API, in one class:
@@ -136,9 +183,37 @@ FeedbackAgent.analyze(text: "Great product, but shipping was slow")
 FeedbackAgent.new.analyze(text: "…")
 ```
 
+By default they take whatever you pass. Name them with `takes:` and they become a real Ruby
+signature, so a missing or misspelled argument is an `ArgumentError` at the call rather than noise
+in a prompt — and the model reads the names instead of `**inputs`:
+
+```ruby
+generates :decide, "Decide this refund.", takes: %i[email complaint], returns: Refund
+
+RefundAgent.decide(email: "ada@example.com")                 # => ArgumentError: missing keyword: :complaint
+RefundAgent.decide(emial: "…", complaint: "…")               # => ArgumentError: unknown keyword: :emial
+```
+
+`with:` stays available on a named signature, since attachments are not part of the prompt.
 `describe` above an ordinary method is the docstring Ruby does not have — it is what the model reads
 when it decides what to call.
 
+A prompt given as a block is read at call time, on the agent, so one declaration serves an object
+however it happens to be configured:
+
+```ruby
+class TranslatorAgent < ApplicationAgent
+  def initialize(language, **options)
+    super(**options)
+    @language = language
+  end
+
+  generates :translate, -> { "Translate to #{@language}, naturally and idiomatically." }
+end
+
+TranslatorAgent.new("Spanish").translate(text: "good morning")   # => "buenos días"
+```
+
 ### Return types
 
 The block is a [schematist](https://github.com/crmne/schematist) schema and becomes the provider's
@@ -151,7 +226,23 @@ generates :count_items, returns: :integer      # :string (default), :integer, :n
 
 Both forms are the same mechanism: a schema whose only property is `result` unwraps to that value.
 A Ruby class works too — `returns: Ticket` — and then the method hands back the object rather than
-data; see [`:code_act`](#strategies) for what that requires.
+data; see [`:code_act`](#strategies) for what that requires. If that object can say whether it is
+well-formed — anything answering `valid?` and `errors`, which is every ActiveModel — it is asked, and
+an invalid one is refused.
+
+### Attachments
+
+`with:` is a reserved argument: it is not rendered into the prompt but sent as attachments —
+images, audio, PDFs — exactly as RubyLLM's `ask(with:)` takes them (paths, URLs, IO objects):
+
+```ruby
+class VisionAgent < ApplicationAgent
+  generates :caption, "Describe the photo.", strategy: :predict
+end
+
+VisionAgent.caption(with: "photo.jpg")
+VisionAgent.caption(question: "what breed?", with: ["a.png", "b.png"])
+```
 
 ### Models and providers
 
@@ -170,6 +261,13 @@ end
 Naming a provider implies `assume_model_exists: true`; any other RubyLLM chat option passes through.
 Subclasses inherit the setting and can override it, so one `ApplicationAgent` configures the lot.
 
+A generation method can name its own model — a cheap one for classification beside a strong one
+for reasoning. The id lands on top of the class's options, so the provider stays the class's:
+
+```ruby
+generates :classify, "Sort this ticket into a queue.", model: "claude-haiku-4-5"
+```
+
 Credentials come from the environment — one call covers every provider:
 
 ```ruby
@@ -206,6 +304,10 @@ The connection opens when the class is defined and the tools are read from the s
 tool's arguments reach the model as documentation. A failed call raises, which the model sees and
 can correct. Only text comes back: an image or audio result is dropped.
 
+That it happens at class-definition time has a cost worth knowing: under `config.eager_load = true`
+an unreachable server fails the boot, and every reload in development reconnects. If a deploy must
+not wait on a sidecar, keep MCP agents out of the eager-loaded paths.
+
 ### Skills
 
 A skill is a directory with a `SKILL.md` — the same YAML front matter Claude Code and friends use.
@@ -220,6 +322,10 @@ class CommitAgent < ApplicationAgent
 end
 ```
 
+The path is expanded against the working directory, which is `Rails.root` until something — a job
+runner, a systemd unit — decides otherwise, so `Rails.root.join("app/agents/skills/commit_style")`
+is the spelling that keeps working.
+
 That is the whole of “loaded on demand”: the one-line description is in the prompt, the body only
 reaches the model if the generated code calls `commit_style`. Anything else the skill ships —
 scripts, templates — sits in the same directory, and the body ends with its path, so generated Ruby
@@ -283,13 +389,61 @@ them — `remember("Shipping to Canada takes three weeks")` on the way out, `rec
 on the way in. The store is a field, so what the agent learned marshals with it and is there on the
 next run.
 
-Embeddings come from RubyLLM (`Omakase.embedder` if you want another source — a fake one keeps
-tests offline), and the search is a dot product over unit vectors. That holds for the few hundred
+Embeddings come from RubyLLM, and `Omakase.embedder` is the seam if you want another source — a
+fake one keeps tests offline, and any provider fits through it:
+
+```ruby
+# RubyLLM defaults to an OpenAI embedding model; OpenRouter serves embeddings too,
+# it just does not list them, so the model is named on trust.
+Omakase.embedder = ->(text) do
+  RubyLLM.embed(text, model: "qwen/qwen3-embedding-4b", provider: :openrouter,
+    assume_model_exists: true).vectors
+end
+```
+
+The search is a dot product over unit vectors. That holds for the few hundred
 things one agent learns about its work; past that it is your database's job — pgvector and the
 [`neighbor`](https://github.com/ankane/neighbor) gem — and `Omakase::Memory` is the interface to
 reimplement against it. And for a few dozen facts, `@notes.grep(/shipping/)` beats every word of
 this.
 
+### Sub-agents
+
+Some work is a tree, and the tree is usually already in your database — a comment thread, a category
+tree, a bill of materials. One agent per node folds it from the leaves up, and the recursion belongs
+to the data: a node with no children is the base case, so nothing has to invent how deep to go.
+
+```ruby
+class ThreadAgent < ApplicationAgent
+  instructions "You sum up a discussion for someone who has not read it."
+  strategy :predict
+
+  def initialize(comment, **options)
+    super(**options)
+    @comment = comment
+  end
+
+  def roll_up
+    return said if @comment.replies.empty?
+
+    summarise(comment: said, replies: @comment.replies.map { |reply| self.class.new(reply).roll_up })
+  end
+
+  generates :summarise, "Sum up this comment together with the replies it drew.", returns: :string
+
+  private
+
+  def said = "#{@comment.author}: #{@comment.body}"
+end
+```
+
+A leaf is its own summary, so the model is asked only where there is something to fold. A fresh
+agent per branch is not ceremony either: siblings then share no state, and one object may not
+re-enter a generation it is already inside. That is refused, because a nested run opens its own chat
+with its own tool budget — nothing would bound the spend. Generated code can start a sub-agent the
+same way. [`examples/recursive_agent.rb`](examples/recursive_agent.rb) is the runnable version: four
+comments, two of them leaves, two generations.
+
 ### Testing
 
 `Omakase::Agent.new(chat:)` takes any object that quacks like a `RubyLLM::Chat`, and one ships with
@@ -305,6 +459,58 @@ chat = Omakase::FakeChat.new { |fake| fake.run("finish(stock_of(:apple))") }
 
 It records `instructions`, `schema`, `tools` and `tasks`, so the prompt is assertable too.
 
+Injecting a chat covers the agent you are testing. A suite covers everything else, including the
+class-level calls a job makes — `SupportAgent.triage(message:)` builds its own agent and has no seam
+to inject through. `Omakase.chat_factory` is that seam, and one line in `test_helper.rb` puts the
+whole suite off the network:
+
+```ruby
+# test/test_helper.rb
+Omakase.chat_factory = ->(**) { Omakase::FakeChat.new { raise "an agent asked for a model" } }
+```
+
+Make it raise, and any generation you forgot to stub fails loudly instead of quietly calling a
+provider from CI. An injected `chat:` still wins, so the tests that mean to run an agent keep
+working. Anything answering `call(**options)` will do; the options are the class's chat options, so
+a factory can assert the model too.
+
+### Listening in
+
+One callback hears every step as it happens: a generation starting, model-written code running,
+an answer landing. Wire it to a logger or a tracer; nil, the default, costs nothing.
+
+```ruby
+Omakase.listener = ->(event, **payload) { Rails.logger.info("#{event} #{payload.except(:agent)}") }
+```
+
+`:generation` carries `agent:, name:, inputs:` · `:ruby` carries `agent:, code:, outcome:` ·
+`:answer` carries `agent:, name:, value:`.
+
+One listener is included, for reading a run rather than storing it: it prints each step to stderr,
+in colour when stderr is a terminal.
+
+```ruby
+Omakase.listener = Omakase::Trace.new
+
+# → SupportAgent#triage
+#     message: "my mug arrived cracked"
+# · ruby
+#     order = order_db.find(1)
+#     puts "eligible: #{refund_eligible?(order)}"
+#     finish(Ticket.new("A-1", :high))
+#     eligible: true
+#     finish #<struct Ticket id="A-1", severity=:high>
+# ← SupportAgent#triage
+#     #<struct Ticket id="A-1", severity=:high>
+```
+
+In Rails there is already a bus for this, and one line puts the events on it — subscribers and your
+APM pick them up with nothing further:
+
+```ruby
+Omakase.listener = ->(event, **payload) { ActiveSupport::Notifications.instrument("#{event}.omakase", payload) }
+```
+
 ## Rails
 
 Agents live in `app/agents` — Rails autoloads it, and reloading is safe because everything a
@@ -344,17 +550,107 @@ Jobs move data, not objects: arguments and results have to serialize, so a `retu
 answer — a live Ruby object — does not survive the trip. [`examples/support_job.rb`](examples/support_job.rb)
 is the runnable version, three tickets triaged concurrently by the async adapter.
 
+**Validations are the contract.** A `returns:` class that answers `valid?` and `errors` gets asked
+before the answer is handed back, so a generation cannot return a record your own validations
+reject:
+
+```ruby
+class Post < ApplicationRecord
+  validates :slug, format: {with: /\A[a-z0-9-]+\z/}, length: {maximum: 12}
+end
+
+class BlogAgent < ApplicationAgent
+  generates :write, "Write a post about the topic.", returns: Post
+end
+```
+
+Nothing about the slug is in the prompt. Under `:code_act` the refusal goes back to the model as
+`finish rejected: Post is invalid: Slug is too long (maximum is 12 characters)`, and it corrects
+itself inside the same loop, within its call budget. Your rules stay in the model, where the rest of
+the application already reads them.
+
 **Threads.** Puma is multi-threaded and so is this: printing from generated code goes to a
 per-thread buffer, and each call gets its own chat and its own agent instance. Concurrent calls are
-just threads:
+threads — wrapped in the Rails executor, which is what returns the connection to the pool and makes
+autoloading safe off the request thread:
 
 ```ruby
-ids.map { |id| Thread.new { WarehouseAgent.appraise(item_id: id) } }.map(&:value)
+ids.map do |id|
+  Thread.new { Rails.application.executor.wrap { WarehouseAgent.appraise(item_id: id) } }
+end.map(&:value)
 ```
 
 Sharing one agent instance across threads is your business as usual — its state is yours. Do not
 turn on RubyLLM's `tool_concurrency`: that runs generated code against the same agent in parallel.
 
+**The pool.** A generation holds its thread for the whole run, and the moment generated code touches
+`ActiveRecord` it holds a database connection with it — through every provider round-trip of a
+`:code_act` loop, not just the queries. Size `pool:` by concurrent agent runs, not by request rate.
+
+**Multi-turn, many pods.** Identity is a row, state is your tables, and the agent is a value —
+rebuilt from them for one turn and thrown away. The chat is fresh per call anyway, so nothing
+sticks to a process: any pod serves any turn, and multi-turn is nothing more than `context`
+reading the history back.
+
+```ruby
+class SupportAgent < ApplicationAgent
+  instructions "You are the support desk. Decide from the customer's own data."
+
+  def initialize(conversation, **options)
+    super(**options)
+    @conversation = conversation
+  end
+
+  # the whole of multi-turn: history is context, rebuilt every turn
+  def context
+    @conversation.messages.order(:created_at).last(30)
+      .map { |message| "#{message.role}: #{message.content}" }.join("\n")
+  end
+
+  describe "Refund an order; refuses anything above the paid total"
+  def refund!(order_id, amount)                       # invariants live here, not in the prompt
+    order = @conversation.user.orders.find(order_id)  # scoping is authorization
+    raise ArgumentError, "over paid total" if amount > order.total
+    Refunds.issue!(order, amount)
+  end
+
+  generates :reply, "Answer the customer's last message.", returns: :string
+end
+
+class TurnJob < ApplicationJob
+  limits_concurrency key: ->(conversation) { conversation }   # one turn per conversation at a time
+
+  def perform(conversation)
+    reply = SupportAgent.new(conversation).reply              # no transaction open across this
+    conversation.messages.create!(role: "assistant", content: reply)
+  end
+end
+```
+
+`limits_concurrency` is Solid Queue's; Sidekiq and GoodJob have their own. What matters is that the
+lock lives in the queue: `with_lock` around a generation would hold a transaction open for the whole
+provider round-trip — a pinned connection, a long-running transaction, and every other turn on that
+row waiting behind it.
+
+[`examples/conversation_agent.rb`](examples/conversation_agent.rb) is all of this running: two turns
+of one conversation, each crossing the queue, with nothing but an id and a String travelling between
+them. The second turn answers from the first because the history is a table, not a process.
+
+Marshal-into-a-column is the escape hatch for resuming a run mid-flight, not the default: rows can
+be queried and migrated, blobs cannot.
+
+**The console.** An agent is a plain object, so `rails console` is already the harness:
+
+```ruby
+agent = SupportAgent.new(Conversation.find(42))
+agent.context    # exactly what the model will read
+agent.reply      # one real generation, right here
+```
+
+The same value the job builds, built by hand — and every tool is an ordinary method, so
+`agent.refund!(order_id, 20)` runs with no model in the room. Nothing to boot, nothing to mock: the
+console session that debugs your models debugs your agents.
+
 **Errors.** Everything raised at the boundary is an `Omakase::Error`:
 
 | | |
@@ -394,12 +690,20 @@ turn naming what was wrong. No code runs. Right for classification, extraction,
 is `instance_eval`d on the agent, so the agent’s methods and state are the API; anything printed and
 the value of the last expression come back as the observation, and the loop repeats until the model
 calls `finish(value)`. `Capabilities` lists the agent’s own methods (with their `describe` text) in
-the system prompt, minus the method being written, so it cannot recurse into itself. A failure comes
-back with the line that raised, `doc(object)` prints what an object of an unfamiliar type offers, and
+the system prompt, minus the method being written. Leaving it out is not enough on its own, since
+generated code can still find the method, so a generation already running refuses to start again — a
+nested one would open its own chat with its own budget, and nothing would bound the spend. A failure
+comes back with the line that raised, `doc(object)` prints what an object — or a class — offers, and
 an answer that misses the contract is rejected into the same loop — the model corrects itself without
 another request. Nothing in the provider bounds a tool loop, so the tool does: ten calls, then a turn
 to answer with what it has.
 
+Generation methods are public methods like any other, so generated code can call them — a
+`:code_act` loop handing a classification to a `:predict` method, or an agent calling another agent
+it holds in a field. And because the code runs on the object, the model can leave state for
+`context` to read on the next call, or define itself a helper method — self-extension is just
+`instance_eval`.
+
 Because the answer is computed rather than retyped, the return type can be a Ruby class and the
 method hands back the object itself:
 
@@ -441,6 +745,7 @@ generates :plan, strategy: CriticStrategy
     lib/omakase/skills.rb          a SKILL.md directory, as one described method
     lib/omakase/memory.rb          remember and recall, by meaning
     lib/omakase/fake_chat.rb       the stand-in chat for tests
+    lib/omakase/trace.rb           those events, printed for a human
     lib/omakase/strategies/        code_act, predict
 
 ## Examples
@@ -456,13 +761,15 @@ Copy `.env.example` to `.env` and fill in a key; `MODEL` and `PROVIDER` there pi
 | [`support_agent.rb`](examples/support_agent.rb) | plain Ruby orchestrating generated methods |
 | [`support_job.rb`](examples/support_job.rb) | generation off the request thread, via ActiveJob |
 | [`rails_app.rb`](examples/rails_app.rb) | a whole Rails app in one file: initializer, agent, controller |
+| [`conversation_agent.rb`](examples/conversation_agent.rb) | multi-turn over ActiveRecord, one turn per job, no process state |
 | [`mcp_agent.rb`](examples/mcp_agent.rb) | an MCP server's tools as methods on the agent |
 | [`skill_agent.rb`](examples/skill_agent.rb) | a SKILL.md directory the model loads when it needs it |
 | [`interview_agent.rb`](examples/interview_agent.rb) | remembering across calls, without a shared chat |
 | [`memory_agent.rb`](examples/memory_agent.rb) | recall by meaning, kept across a marshalled run |
+| [`recursive_agent.rb`](examples/recursive_agent.rb) | a comment thread folded from the leaves up, one agent per node |
 
 ```bash
-bundle exec rake                     # tests, no network
+bundle exec rake                     # tests and Standard, no network
 ruby examples/inventory_agent.rb
 ```
 
@@ -477,9 +784,12 @@ too. Two rules follow:
 - **A marshalled agent is your data, never user input.** `Marshal.load` on bytes someone else can
   write is remote code execution, resumed run or not.
 
-What is bounded: ten tool calls per generation, a 30-second timeout per execution, and 4KB of
-observation. What is not: what the code can reach. For real isolation, swap the executor —
-anything answering `call(agent, code, timeout:)` will do:
+What is bounded: ten tool calls per generation, one run of a generation at a time, a 30-second
+timeout per execution, and 4KB of observation. That timeout is Ruby's `Timeout`, which raises
+wherever the code has got to — inside a database driver it can leave the connection unusable — one
+more reason anything long-running belongs in an executor of your own. What is not bounded: what the
+code can reach. For real isolation, swap the executor — anything answering `call(agent, code,
+timeout:)` will do:
 
 ```ruby
 Omakase.executor = MySubprocessExecutor    # returns an observation String or Executor::Answer

data/lib/omakase/agent.rb

@@ -4,6 +4,8 @@ module Omakase
   # Fields are state, methods are what the model can call, `generates` declares
   # the methods the model implements.
   class Agent
+    # The generations this thread is inside, so one cannot re-enter itself.
+    RUNNING = :omakase_running
     class << self
       # The model and any RubyLLM chat option. Naming a provider takes the model
       # id on trust, since providers like OpenRouter or Ollama serve ids that are
@@ -46,20 +48,34 @@ module Omakase
         describe "Search what you remember, by meaning; the closest few come back"
         define_method(:recall) { |query, limit: 5| (@memory ||= Memory.new).recall(query, limit:) }
       end
+
       # Documents the method defined next — the docstring Ruby does not have.
       def describe(text)
         @pending_description = text
       end
 
-      # Without a prompt, the method name is the prompt.
-      def generates(name, prompt = nil, returns: nil, strategy: nil, &schema)
+      # Without a prompt, the method name is the prompt. A block instead of a
+      # string is a prompt read at call time, on the agent. `takes:` names the
+      # keyword arguments, and then Ruby checks them.
+      def generates(name, prompt = nil, takes: nil, returns: nil, strategy: nil, model: nil, &schema)
+        # Redeclaring an inherited generation is how a subclass specialises one.
+        # Landing on a method you wrote is not that, and would replace it unseen.
+        if Capabilities.names(self).include?(name) && !generations.key?(name)
+          raise Error, "#{self}##{name} is already a method — generates would replace it"
+        end
+
+        unless prompt.nil? || prompt.is_a?(String) || prompt.is_a?(Proc)
+          raise Error, "#{self}##{name}: a prompt is a String or a block returning one, got #{prompt.class}"
+        end
+
         generations[name] = Generation.new(
           name:,
           prompt: prompt || humanize(name),
           schema: Schema.define(returns:, &schema),
-          strategy: Strategies.fetch(strategy || self.strategy)
+          strategy: Strategies.fetch(strategy || self.strategy),
+          model:
         )
-        define_method(name) { |**inputs| generate(name, inputs) }
+        define_generation_method(name, takes)
         define_singleton_method(name) { |**inputs| new.public_send(name, **inputs) }
       end
 
@@ -71,6 +87,25 @@ module Omakase
 
       private
 
+      # Named inputs become a real signature, so a missing or misspelled argument
+      # is an ArgumentError at the call rather than noise in a prompt — and the
+      # model reads the names too, instead of `**inputs`.
+      def define_generation_method(name, takes)
+        return define_method(name) { |**inputs| generate(name, inputs) } if takes.nil?
+
+        keywords = Array(takes)
+        bad = [name.to_s.chomp("?").chomp("!"), *keywords].reject { |word| /\A[a-z_]\w*\z/.match?(word.to_s) }
+        raise Error, "#{self}##{name}: takes: needs plain keyword names, got #{bad.inspect}" if bad.any?
+
+        class_eval <<~RUBY, __FILE__, __LINE__ + 1
+          def #{name}(#{keywords.map { |key| "#{key}:" }.join(", ")}, with: nil)
+            inputs = {#{keywords.map { |key| "#{key}: #{key}" }.join(", ")}}
+            inputs[:with] = with unless with.nil?
+            generate(:#{name}, inputs)
+          end
+        RUBY
+      end
+
       def humanize(name)
         text = name.to_s.tr("_", " ").capitalize
         text.end_with?("?", "!") ? text : "#{text}."
@@ -99,7 +134,8 @@ module Omakase
 
     # A fresh conversation per call — two threads calling one agent must not
     # share a mutable chat. What carries between calls is the object's own state.
-    def chat = @chat || RubyLLM.chat(**self.class.chat_options)
+    # Overrides land on top of the class's options; an injected chat ignores them.
+    def chat(**overrides) = @chat || Omakase.chat_factory.call(**self.class.chat_options.merge(overrides))
 
     # That state, as the model should read it: rebuilt on every call, and added
     # to the class's instructions. Override it to remember anything.
@@ -125,7 +161,7 @@ module Omakase
 
     def p(*args)
       args.each { |arg| omakase_output.puts(arg.inspect) }
-      args.size <= 1 ? args.first : args
+      (args.size <= 1) ? args.first : args
     end
 
     alias_method :pp, :p
@@ -136,9 +172,24 @@ module Omakase
 
     def generate(name, inputs)
       generation = self.class.generations.fetch(name)
-      generation.strategy.call(Request.new(agent: self, generation:, inputs:))
-    rescue RubyLLM::Error, RubyLLM::ConfigurationError, RubyLLM::ModelNotFoundError => e
-      raise ProviderError, "#{self.class}##{name}: #{e.message}"
+      running = (Thread.current[RUNNING] ||= [])
+      key = [object_id, name]
+
+      # Generated code can see this method and call it. Each nested call opens its
+      # own chat with its own tool budget, so the budget would bound nothing.
+      raise Error, "#{self.class}##{name} is already running — it cannot call itself" if running.include?(key)
+
+      running.push(key)
+      begin
+        Omakase.emit(:generation, agent: self, name:, inputs:)
+        value = generation.strategy.call(Request.new(agent: self, generation:, inputs:))
+        Omakase.emit(:answer, agent: self, name:, value:)
+        value
+      rescue RubyLLM::Error, RubyLLM::ConfigurationError, RubyLLM::ModelNotFoundError => e
+        raise ProviderError, "#{self.class}##{name}: #{e.message}"
+      ensure
+        running.delete(key)
+      end
     end
   end
 end

data/lib/omakase/capabilities.rb

@@ -19,7 +19,9 @@ module Omakase
 
     def entry(agent_class, name)
       signature = "#{name}(#{parameters(agent_class.instance_method(name))})"
-      description = agent_class.descriptions[name] || agent_class.generations[name]&.prompt
+      # A prompt written as a block needs an instance to read; `describe` it instead.
+      prompt = agent_class.generations[name]&.prompt
+      description = agent_class.descriptions[name] || (prompt unless prompt.is_a?(Proc))
       description ? "#{signature} — #{description}" : signature
     end
 

data/lib/omakase/doc.rb

@@ -13,7 +13,23 @@ module Omakase
     # and the methods you wrote.
     def boundary = defined?(ActiveRecord::Base) ? [*CORE, ActiveRecord::Base] : CORE
 
-    def of(object) = [object.class.to_s, *signatures(object), *state(object)].join("\n")
+    def of(object)
+      return of_class(object) if object.is_a?(Module)
+
+      [object.class.to_s, *signatures(object.class) { |name| object.method(name) }, *state(object)].join("\n")
+    end
+
+    # A class, not an instance: what one would have. The model asks this before it
+    # builds an object of a type it has only been told the name of.
+    def of_class(klass)
+      [klass.to_s, *signatures(klass) { |name| klass.instance_method(name) }, *columns(klass)].join("\n")
+    end
+
+    def columns(klass)
+      return [] unless klass.respond_to?(:column_names)
+
+      klass.column_names.map { |name| "  #{name}" }
+    end
 
     # An object that answers `attributes` says what it holds better than its
     # instance variables do — and a record's columns are state, not API.
@@ -24,14 +40,14 @@ module Omakase
 
     def ivars(object) = object.instance_variables.to_h { |name| [name, object.instance_variable_get(name)] }
 
-    def signatures(object)
-      object.class.ancestors
+    def signatures(klass, &getter)
+      klass.ancestors
         .take_while { |mod| !boundary.include?(mod) }
         .reject { |mod| mod.to_s.end_with?("GeneratedAttributeMethods") }
         .flat_map { |mod| mod.public_instance_methods(false) }
         .uniq.sort
         .reject { |name| name.match?(/\A_|_associated_records_for_/) }
-        .map { |name| "  #{name}(#{Capabilities.parameters(object.method(name))})" }
+        .map { |name| "  #{name}(#{Capabilities.parameters(getter.call(name))})" }
     end
   end
 end

data/lib/omakase/executor.rb

@@ -8,10 +8,15 @@ module Omakase
     RESULT = :omakase_result
     OUTPUT = :omakase_output
     TIMEOUT = 30
+    TRACE = /\A#{Regexp.escape(SOURCE)}:\d+/
     MAX_OUTPUT = 4_000
 
-    # What `finish(value)` handed back: the answer as a Ruby value, not as text.
-    Answer = Data.define(:value)
+    # What `finish(value)` handed back: the answer as a Ruby value, not as text,
+    # and whatever the code printed on the way there. `printed` defaults, so a
+    # replacement executor that only knows the value still satisfies the seam.
+    Answer = Data.define(:value, :printed) do
+      def initialize(value:, printed: "") = super
+    end
 
     module_function
 
@@ -21,14 +26,14 @@ module Omakase
         value = capturing(printed) { Timeout.timeout(timeout) { agent.instance_eval(code, SOURCE, 1) } }
         return observation([printed.string.chomp, "=> #{value.inspect}"])
       end
-      Answer.new(value: answer)
+      Answer.new(value: answer, printed: printed.string.chomp)
     rescue ScriptError, StandardError => e
       observation([printed.string.chomp, failure(e, code)])
     end
 
     # The model can only fix what it can locate, so point at the line.
     def failure(error, code)
-      line = error.backtrace&.grep(/\A#{Regexp.escape(SOURCE)}:\d+/)&.first&.slice(/:(\d+)/, 1)&.to_i
+      line = error.backtrace&.grep(TRACE)&.first&.slice(/:(\d+)/, 1)&.to_i
       source = code.lines[line - 1]&.strip if line&.positive?
       ["#{error.class}: #{error.message}", ("line #{line}: #{source}" if source)].compact.join("\n")
     end

data/lib/omakase/fake_chat.rb

@@ -12,13 +12,14 @@ module Omakase
   class FakeChat
     Response = Struct.new(:content)
 
-    attr_reader :instructions, :schema, :tools, :tasks
+    attr_reader :instructions, :schema, :tools, :tasks, :attachments
 
     def initialize(&script)
       @script = script
       @instructions = []
       @tools = []
       @tasks = []
+      @attachments = []
     end
 
     def with_instructions(text) = tap { @instructions << text }
@@ -27,8 +28,9 @@ module Omakase
 
     def with_tool(tool, **) = tap { @tools << tool }
 
-    def ask(task)
+    def ask(task, with: nil)
       @tasks << task
+      @attachments << with if with
       Response.new(@script.call(self))
     end
 

data/lib/omakase/generation.rb

@@ -2,6 +2,7 @@
 
 module Omakase
   # A method the agent declares but does not implement: the prompt is its body,
-  # the schema is its return type, the strategy is how it gets there.
-  Generation = Data.define(:name, :prompt, :schema, :strategy)
+  # the schema is its return type, the strategy is how it gets there. A model
+  # named here overrides the class's, for this method alone.
+  Generation = Data.define(:name, :prompt, :schema, :strategy, :model)
 end

data/lib/omakase/request.rb

@@ -3,17 +3,29 @@
 module Omakase
   # One invocation of a generation method: all a strategy may depend on.
   Request = Data.define(:agent, :generation, :inputs) do
-    def chat = agent.chat
+    def chat = agent.chat(**{model: generation.model}.compact)
 
     def schema = generation.schema
 
     def instructions = [agent.class.instructions, agent.context].reject { |text| text.to_s.empty? }.join("\n\n")
 
+    # `with:` is reserved: files for the model to look at, passed through to
+    # RubyLLM's `ask(with:)` as attachments rather than rendered into the text.
+    def attachments = inputs[:with]
+
     def task
-      return generation.prompt if inputs.empty?
+      arguments = inputs.except(:with)
+      return prompt if arguments.empty?
+
+      lines = arguments.map { |name, value| "- #{name}: #{value.inspect}" }
+      "#{prompt}\n\nInputs:\n#{lines.join("\n")}"
+    end
 
-      arguments = inputs.map { |name, value| "- #{name}: #{value.inspect}" }
-      "#{generation.prompt}\n\nInputs:\n#{arguments.join("\n")}"
+    # A prompt written as a block is read at call time, on the agent — so one
+    # declaration serves an object however it happens to be configured.
+    def prompt
+      text = generation.prompt
+      text.is_a?(Proc) ? agent.instance_exec(&text) : text
     end
   end
 end

data/lib/omakase/schema.rb

@@ -12,6 +12,9 @@ module Omakase
     }.freeze
 
     def self.define(returns: nil, &block)
+      # Two contracts in one declaration: one of them would be dropped, silently.
+      raise Error, "returns: and a schema block are two different contracts — declare one" if returns && block
+
       return new(Schematist::Schema.create(&block)) if block
       return Type.new(returns) if returns.is_a?(Module)
 
@@ -65,7 +68,7 @@ module Omakase
     def properties = json.fetch("properties")
 
     def demand(value, type)
-      matched = type == "boolean" ? [true, false].include?(value) : value.is_a?(RUBY_TYPES.fetch(type))
+      matched = (type == "boolean") ? [true, false].include?(value) : value.is_a?(RUBY_TYPES.fetch(type))
       raise ContractError, "expected <#{type}>, got #{value.inspect}" unless matched
 
       value

data/lib/omakase/strategies/code_act.rb

@@ -12,7 +12,7 @@ module Omakase
         notes = request.chat
           .with_instructions(instructions(request))
           .with_tool(tool)
-          .ask(request.task)
+          .ask(request.task, with: request.attachments)
           .content
 
         return tool.answer.value if tool.answer
@@ -33,7 +33,7 @@ module Omakase
 
           #{capabilities(request).join("\n")}
 
-          `doc(object)` prints what an object of an unfamiliar type offers.
+          `doc(object)` prints what an object of an unfamiliar type offers; a class works too.
 
           Return the answer from inside the code, never as a message — the last thing you run is:
 

data/lib/omakase/strategies/predict.rb

@@ -13,7 +13,7 @@ module Omakase
           .with_instructions(instructions(request))
           .with_schema(request.schema.definition)
 
-        request.schema.cast(chat.ask(task).content)
+        request.schema.cast(chat.ask(task, with: request.attachments).content)
       rescue ContractError => e
         # One correction turn, told exactly what was wrong with the last answer.
         request.schema.cast(chat.ask("#{e.message}\n\n#{CORRECTION}").content)

data/lib/omakase/tools/ruby.rb

@@ -36,12 +36,16 @@ module Omakase
         return halt("Tool budget spent.") if @calls > @budget + 1
 
         outcome = @executor.call(@agent, code, timeout: @timeout)
-        return outcome unless outcome.is_a?(Executor::Answer)
+        Omakase.emit(:ruby, agent: @agent, code:, outcome:)
+        return outcome if outcome.is_a?(String)
+        # The seam's contract, checked here so a wrong executor cannot reach the model.
+        raise Error, "executor must return a String or Executor::Answer, got #{outcome.class}" unless outcome.is_a?(Executor::Answer)
 
-        @answer = Executor::Answer.new(value: @schema.take(outcome.value))
+        @answer = Executor::Answer.new(value: @schema.take(outcome.value), printed: outcome.printed)
         halt("Answer accepted.")
-      rescue Error => e
+      rescue ContractError => e
         # Off-contract answers are corrected inside the same loop, not by another request.
+        # Anything else — a broken executor, a bad configuration — is not the model's to fix.
         "finish rejected: #{e.message}"
       end
     end

data/lib/omakase/trace.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Omakase
+  # The listener, printed for a human: `Omakase.listener = Omakase::Trace.new`.
+  # A run reads top to bottom — the call, the code the model wrote, the answer.
+  # Colour when the stream is a terminal, plain when it is a log.
+  class Trace
+    COLOURS = {generation: 36, ruby: 33, answer: 32}.freeze
+    LIMIT = 800
+
+    def initialize(io: $stderr)
+      @io = io
+      @colour = io.respond_to?(:tty?) && io.tty?
+    end
+
+    def call(event, agent:, **payload)
+      head, body = case event
+      when :generation then ["→ #{agent.class}##{payload[:name]}", inputs(payload[:inputs])]
+      when :ruby then ["· ruby", "#{payload[:code].strip}\n#{outcome(payload[:outcome])}"]
+      when :answer then ["← #{agent.class}##{payload[:name]}", truncate(payload[:value].inspect)]
+      else return # a listener that raises takes the run down with it
+      end
+
+      @io.puts(paint(event, head))
+      @io.puts(body.gsub(/^/, "    ")) unless body.empty?
+    end
+
+    private
+
+    def inputs(inputs) = inputs.map { |name, value| "#{name}: #{truncate(value.inspect)}" }.join("\n")
+
+    # An Answer is `finish(value)` ending the run — with anything printed before it,
+    # which the tool result never carries because the run is over. Otherwise the
+    # outcome is already the text the model reads.
+    def outcome(outcome)
+      return truncate(outcome.to_s) unless outcome.is_a?(Executor::Answer)
+
+      truncate([outcome.printed, "finish #{outcome.value.inspect}"].reject(&:empty?).join("\n"))
+    end
+
+    def truncate(text) = (text.length > LIMIT) ? "#{text[0, LIMIT]}…" : text
+
+    def paint(event, text) = @colour ? "\e[#{COLOURS.fetch(event)}m#{text}\e[0m" : text
+  end
+end

data/lib/omakase/type.rb

@@ -20,9 +20,9 @@ module Omakase
     def code_only? = true
 
     def take(value)
-      return value if value.is_a?(@klass)
+      raise ContractError, "expected #{describe}, got #{value.class}" unless value.is_a?(@klass)
 
-      raise ContractError, "expected #{describe}, got #{value.class}"
+      well_formed(value)
     end
 
     def definition
@@ -30,5 +30,18 @@ module Omakase
     end
 
     alias_method :json, :definition
+
+    private
+
+    # An object that can say whether it is well-formed gets asked — ActiveModel,
+    # ActiveRecord, anything of that shape. The refusal reaches the model as an
+    # observation, so your own validations are what it has to satisfy, and they
+    # stay where you wrote them instead of being retyped into a prompt.
+    def well_formed(value)
+      return value unless value.respond_to?(:valid?) && value.respond_to?(:errors)
+      return value if value.valid?
+
+      raise ContractError, "#{@klass} is invalid: #{value.errors.full_messages.join("; ")}"
+    end
   end
 end

data/lib/omakase/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Omakase
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/omakase.rb

@@ -46,14 +46,47 @@ module Omakase
 
     # Where generated code runs. Anything answering `call(agent, code, timeout:)`
     # will do — swap in a subprocess or a container to get real isolation.
-    attr_writer :executor
+    def executor=(executor)
+      @executor = callable!(executor, "executor")
+    end
 
     def executor = @executor ||= Executor
 
     # How text becomes a vector, for Memory. Anything answering `call(text)`
     # will do; the model and its provider are RubyLLM's to configure.
-    attr_writer :embedder
+    def embedder=(embedder)
+      @embedder = callable!(embedder, "embedder")
+    end
 
     def embedder = @embedder ||= ->(text) { RubyLLM.embed(text).vectors }
+
+    # How an agent gets a chat when none was injected. Anything answering
+    # `call(**options)` will do — one line in test_helper.rb keeps a whole suite
+    # off the network, including the class-level calls a job makes.
+    def chat_factory=(factory)
+      @chat_factory = callable!(factory, "chat_factory")
+    end
+
+    def chat_factory = @chat_factory ||= ->(**options) { RubyLLM.chat(**options) }
+
+    # Every step, as it happens: a generation starts, model-written code runs,
+    # an answer lands. Anything answering `call(event, **payload)` will do —
+    # a logger, a tracer, a test. Nil, the default, costs nothing.
+    def listener=(listener)
+      @listener = callable!(listener, "listener")
+    end
+
+    attr_reader :listener
+
+    def emit(event, **payload) = @listener&.call(event, **payload)
+
+    private
+
+    # Fail where the swap is made, not deep inside a generation.
+    def callable!(object, name)
+      return object if object.nil? || object.respond_to?(:call)
+
+      raise Error, "#{name} must answer call, got #{object.class}"
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: omakase-agents
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - eugeny
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-13 00:00:00.000000000 Z
+date: 2026-08-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -63,6 +63,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - lib/omakase-agents.rb
@@ -82,6 +83,7 @@ files:
 - lib/omakase/strategies/code_act.rb
 - lib/omakase/strategies/predict.rb
 - lib/omakase/tools/ruby.rb
+- lib/omakase/trace.rb
 - lib/omakase/type.rb
 - lib/omakase/version.rb
 homepage: https://github.com/esshka/omakase
@@ -91,6 +93,7 @@ metadata:
   homepage_uri: https://github.com/esshka/omakase
   source_code_uri: https://github.com/esshka/omakase
   bug_tracker_uri: https://github.com/esshka/omakase/issues
+  changelog_uri: https://github.com/esshka/omakase/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []