omakase-agents 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c14f0a611e4eacd12ed77e2944f0af6e8b5f51a908ecceff832418bb7c4f6c7e
-  data.tar.gz: 7bdeb3cef506c2eda19939a51782c24a87347158b660c83d79f2fb643720131a
+  metadata.gz: d0a1114c3a9af5c41d3111880844a2a74a182b23696226533c3d5076b3a3ce63
+  data.tar.gz: '049c62448ea9e6d3b96177bda1564b294cb47d08cc7aa7a514db321d0f617394'
 SHA512:
-  metadata.gz: 88399ffa0b1b73c20b1983d87c70fe09ef90db58ca2b9f527a7762c1294dbde90ebbac000ea3e297c6195cbb3bbf5614951b472769bfd573abb26909068f2962
-  data.tar.gz: 5089d67312535691c5d65407492e2fd046a0979bf42ad87f196b7579df515356de364b75050012f38da7e16be3c192912ac5fe101b20b699f29ea4f9819de8a4
+  metadata.gz: c1fb9143de3b2b934eb183e6c396a81a06d64ac8b505f28f0a311c2411aea56c09e64207f3c5789554f88bca34bbc0a9fe7654c276775383e559769f269d4775
+  data.tar.gz: 94f16e8c77584c2a0c120e93f470acd5ba46991c7503be695d267c4dae95b8e7124360121a0186ace47c8c4dea17caf4cb147d1abc3d86d8b07e6594c4cd3321

data/CHANGELOG.md

@@ -3,6 +3,48 @@
 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.

data/README.md

@@ -1,6 +1,6 @@
 # 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) · [changelog](CHANGELOG.md) ![gem](https://img.shields.io/gem/v/omakase-agents?color=c8452e&label=)
@@ -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,6 +183,18 @@ 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.
 
@@ -167,7 +226,9 @@ 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
 
@@ -243,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.
@@ -257,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
@@ -338,6 +407,43 @@ things one agent learns about its work; past that it is your database's job —
 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
@@ -353,6 +459,21 @@ 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,
@@ -365,6 +486,31 @@ Omakase.listener = ->(event, **payload) { Rails.logger.info("#{event} #{payload.
 `: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
@@ -404,17 +550,43 @@ 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`
@@ -446,18 +618,39 @@ class SupportAgent < ApplicationAgent
 end
 
 class TurnJob < ApplicationJob
+  limits_concurrency key: ->(conversation) { conversation }   # one turn per conversation at a time
+
   def perform(conversation)
-    conversation.with_lock do                         # turns on one conversation stay serial
-      reply = SupportAgent.new(conversation).reply
-      conversation.messages.create!(role: "assistant", content: reply)
-    end
+    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`:
 
 | | |
@@ -497,8 +690,10 @@ 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.
@@ -550,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
@@ -565,10 +761,12 @@ 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 and Standard, no network
@@ -586,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
@@ -53,8 +55,9 @@ module Omakase
       end
 
       # 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.
-      def generates(name, prompt = nil, returns: nil, strategy: nil, model: nil, &schema)
+      # 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)
@@ -72,7 +75,7 @@ module Omakase
           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
 
@@ -84,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}."
@@ -113,7 +135,7 @@ 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.
     # Overrides land on top of the class's options; an injected chat ignores them.
-    def chat(**overrides) = @chat || RubyLLM.chat(**self.class.chat_options.merge(overrides))
+    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.
@@ -150,12 +172,24 @@ module Omakase
 
     def generate(name, inputs)
       generation = self.class.generations.fetch(name)
-      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}"
+      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/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

@@ -11,8 +11,12 @@ module Omakase
     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
 
@@ -22,7 +26,7 @@ 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

data/lib/omakase/strategies/code_act.rb

@@ -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/tools/ruby.rb

@@ -41,7 +41,7 @@ module Omakase
         # 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 ContractError => e
         # Off-contract answers are corrected inside the same loop, not by another request.

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.2.0"
+  VERSION = "0.3.0"
 end

data/lib/omakase.rb

@@ -60,6 +60,15 @@ module Omakase
 
     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.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: omakase-agents
 version: !ruby/object:Gem::Version
-  version: 0.2.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
@@ -83,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