omakase-agents 0.0.2.alpha → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96b04f8669c6e6bf4f176d19b779ca495fb1b2fde034952c48175eb2999647b3
-  data.tar.gz: 32d2d58018dd35cf63590c889f6c9e5a8bca214e1ccfcd9989c0f90c157bec70
+  metadata.gz: c14f0a611e4eacd12ed77e2944f0af6e8b5f51a908ecceff832418bb7c4f6c7e
+  data.tar.gz: 7bdeb3cef506c2eda19939a51782c24a87347158b660c83d79f2fb643720131a
 SHA512:
-  metadata.gz: e596c18452218540f3a92c7f2542cbf1ea7e5b4fe0314c359e784d14fe331defdaf40f642cd4679667ed0e6ca5c8e42bd171cb940b2b2bd6b3fd47faba41bf97
-  data.tar.gz: 18e626683d93029d7d29da409b9f456800cf4b0579e9e478636d4b8ff2902f628ef34460cf3dd935b164e76d057bc3b01bb22c3a4b58fe9c15c354befbdc9cf9
+  metadata.gz: 88399ffa0b1b73c20b1983d87c70fe09ef90db58ca2b9f527a7762c1294dbde90ebbac000ea3e297c6195cbb3bbf5614951b472769bfd573abb26909068f2962
+  data.tar.gz: 5089d67312535691c5d65407492e2fd046a0979bf42ad87f196b7579df515356de364b75050012f38da7e16be3c192912ac5fe101b20b699f29ea4f9819de8a4

data/CHANGELOG.md

@@ -0,0 +1,57 @@
+# 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.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

@@ -3,37 +3,70 @@
 A light agent framework — about 700 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?include_prereleases&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 —
 the method name and prompt are the specification, the schema is the contract.
 
 ```ruby
-class InventoryAgent < ApplicationAgent
-  instructions "You check inventory."
+class RefundAgent < ApplicationAgent
+  instructions "You are the refund desk of an online shop. Decide from the customer’s own orders."
 
-  describe "Units of an item on hand"
-  def stock_of(item) = STOCK.dig(item, :stock) || 0
+  describe "Every order this customer placed, newest first. An Order has placed_on, items and total"
+  def orders_for(email) = Order.where(email:).order(placed_on: :desc)
 
-  describe "Unit price of an item"
-  def price_of(item) = STOCK.dig(item, :price) || 0.0
+  describe "What the policy says about a topic, such as :damage or :late"
+  def policy_on(topic) = POLICY.fetch(topic, "Refunds are allowed within 30 days.")
 
-  generates :can_fulfill_order, "Decide whether the order fits the budget and is in stock." do
-    boolean :can_fulfill
-    number :total_cost
-    array :unavailable, of: :string
-  end
+  generates :decide, "Decide this refund, and name the policy you applied.", returns: Refund
 end
 
-InventoryAgent.can_fulfill_order(items: %w[apple banana orange], budget: 5.0)
-# => {can_fulfill: false, total_cost: 2.05, unavailable: ["orange"]}
+RefundAgent.decide(email: "ada@example.com", complaint: "the mug arrived cracked")
+# => #<struct Refund order_id=1, amount=39.9,
+#      reason="Mug arrived cracked; damaged goods refunded in full including shipping per policy :damage">
 ```
 
+`Order` is your ActiveRecord model and `Refund` is your Struct. Nothing was registered anywhere, and
+nothing came back as JSON to parse — the model wrote Ruby against your objects and handed one back.
+Here is the run above, abridged:
+
+```
+ruby   orders = orders_for("ada@example.com")
+       orders.each { |o| puts "total: #{o.total}", "items: #{o.items.inspect}" }
+out    total: 39.9
+       items: [#<Item id: 1, name: "Stoneware mug", price: 34.0>, #<Item id: 2, name: "Shipping", price: 5.9>]
+ruby   puts policy_on(:damage)
+out    Damaged goods are refunded in full, including shipping, within 90 days.
+ruby   finish(Refund.new(order_id: 1, amount: 39.9, reason: "Mug arrived cracked; damaged goods …"))
+out    Answer accepted.
+```
+
+That transcript is real, and it is from `meta/muse-glimmer-30b` on OpenRouter — `:code_act` is developed
+and tested against a 30B model, because a strategy that only works on a frontier model is a demo, not
+a library. [`examples/refund_agent.rb`](examples/refund_agent.rb) is the whole thing, runnable, with
+an in-memory SQLite database.
+
 There is no tool abstraction to keep in sync: the model writes Ruby that runs on the agent object,
 reads what it printed and returned, and answers in the declared schema. Adding a tool is adding a
 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 —
+is still RubyLLM's, and stays reachable.
+
+Against **a framework with a tool registry**: there is nothing to register and nothing to keep in
+sync. The model gets one tool, `ruby`, and reaches the rest through the object. A tool's description
+is `describe`, a line above the method, instead of a JSON schema that drifts from the code it
+describes. The answer comes back as the object the code built, not as JSON you parse again.
+
+Reach for something else when the input is untrusted and you want code execution (see
+[Safety](#safety)), when a run is hundreds of steps and must resume mid-flight, when memory means a
+large corpus rather than what one agent learned, or when you want a token stream rather than a
+value.
+
 ## Installation
 
 Ruby 3.2+.
@@ -42,15 +75,37 @@ Ruby 3.2+.
 gem "omakase-agents"     # the library is `Omakase`
 ```
 
-From the command line the flag is needed — `0.0.2.alpha` is a prerelease, and RubyGems skips those
-unless asked. Bundler resolves it without one, since no stable version exists yet.
-
 ```bash
-gem install omakase-agents --pre
+gem install omakase-agents
 ```
 
 ## Usage
 
+The whole API, in one class:
+
+```ruby
+class MyAgent < Omakase::Agent
+  model "claude-sonnet-4-5"                      # any RubyLLM model and chat option
+  instructions "Who the agent is."               # the system prompt
+  strategy :code_act                             # or :predict, or anything answering call(request)
+
+  mcp :files, transport_type: :stdio, config: {} # an MCP server's tools, as methods
+  skill "skills/commit-style"                    # a SKILL.md directory, as one described method
+  memory                                         # remember(text) and recall(query)
+
+  describe "Units of an item on hand"            # the docstring Ruby does not have
+  def stock_of(item) = ...                       # any method of yours is a tool
+
+  generates :answer, "What to produce.", returns: :string   # written by the model at runtime
+
+  def context = "..."                            # live state, folded into every prompt
+end
+```
+
+Inside generated code the agent also answers `finish(value)` to return, `doc(object)` to inspect an
+unfamiliar type, and `puts` to say something the model will read back. Outside it, `Marshal.dump`
+is the session.
+
 ### Declaring an agent
 
 ```ruby
@@ -84,6 +139,22 @@ FeedbackAgent.new.analyze(text: "…")
 `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
@@ -98,6 +169,20 @@ Both forms are the same mechanism: a schema whose only property is `result` unwr
 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.
 
+### 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
 
 Any provider RubyLLM supports — Anthropic, OpenAI, Gemini, Bedrock, Azure, Mistral, DeepSeek, xAI,
@@ -115,6 +200,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
@@ -150,7 +242,6 @@ end
 The connection opens when the class is defined and the tools are read from the server then, so a
 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.
-### Testing
 
 ### Skills
 
@@ -170,6 +261,85 @@ That is the whole of “loaded on demand”: the one-line description is in the
 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
 can read or run it.
+
+### Remembering
+
+The chat is fresh on every call — two threads calling one agent must not share a mutable
+conversation. What carries between calls is the object itself: override `context`, and whatever it
+returns is appended to the instructions of the next call.
+
+```ruby
+class InterviewAgent < ApplicationAgent
+  instructions "You interview a Ruby candidate. One question at a time."
+
+  def context = @asked.empty? ? nil : "Questions you already asked:\n- #{@asked.join("\n- ")}"
+
+  generates :question_after, "Ask the next question, on a topic you have not covered yet."
+
+  def ask(answer) = @asked << question_after(answer:)
+end
+```
+
+So “what to keep” is a decision you write in Ruby rather than a policy the library guesses: keep the
+last ten, keep a summary, keep the rows you touched. State is the memory, and it is already typed,
+testable, and yours.
+
+### Resuming
+
+Because the state is the object, persisting a run is persisting the object — nothing to configure:
+
+```ruby
+Redis.current.set("interview:#{id}", Marshal.dump(agent))
+
+agent = Marshal.load(Redis.current.get("interview:#{id}"))
+agent.ask("...")                                  # picks up with everything it kept
+```
+
+The live chat is left out of the dump and rebuilt on the next call, so a resumed agent holds no
+stale connection. In Rails you usually need none of this: the state came from your models, and the
+agent is rebuilt from those rows per request.
+
+A generation in flight is not resumable — the tool loop is RubyLLM's, and a crashed one is retried
+whole, which is what `ActiveJob` does anyway.
+
+### Memory
+
+`memory` adds two more methods to the agent — one to save something, one to search it by meaning:
+
+```ruby
+class SupportAgent < ApplicationAgent
+  instructions "You help customers."
+  memory
+
+  generates :answer, "Answer the customer, using what you remember.", returns: :string
+end
+```
+
+They are listed with everything else the agent can do, so generated code decides when to reach for
+them — `remember("Shipping to Canada takes three weeks")` on the way out, `recall("delivery time")`
+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, 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.
+
+### Testing
+
 `Omakase::Agent.new(chat:)` takes any object that quacks like a `RubyLLM::Chat`, and one ships with
 the library, so agents are tested without a network:
 
@@ -183,6 +353,18 @@ chat = Omakase::FakeChat.new { |fake| fake.run("finish(stock_of(:apple))") }
 
 It records `instructions`, `schema`, `tools` and `tasks`, so the prompt is assertable 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:`.
+
 ## Rails
 
 Agents live in `app/agents` — Rails autoloads it, and reloading is safe because everything a
@@ -233,6 +415,49 @@ ids.map { |id| Thread.new { WarehouseAgent.appraise(item_id: id) } }.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.
 
+**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
+  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
+  end
+end
+```
+
+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.
+
 **Errors.** Everything raised at the boundary is an `Omakase::Error`:
 
 | | |
@@ -278,6 +503,12 @@ an answer that misses the contract is rejected into the same loop — the model
 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:
 
@@ -317,6 +548,7 @@ generates :plan, strategy: CriticStrategy
     lib/omakase/tools/ruby.rb      that executor, as a RubyLLM tool, with a call budget
     lib/omakase/mcp.rb             an MCP server’s tools, as methods on the agent
     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/strategies/        code_act, predict
 
@@ -328,15 +560,18 @@ Copy `.env.example` to `.env` and fill in a key; `MODEL` and `PROVIDER` there pi
 | --- | --- |
 | [`feedback_agent.rb`](examples/feedback_agent.rb) | structured output in one call |
 | [`inventory_agent.rb`](examples/inventory_agent.rb) | the agent's methods as the model's tools |
+| [`refund_agent.rb`](examples/refund_agent.rb) | ActiveRecord objects in, a Ruby object out |
 | [`warehouse_agent.rb`](examples/warehouse_agent.rb) | inspecting objects whose types are unknown |
 | [`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 |
 | [`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 |
 
 ```bash
-bundle exec rake                     # tests, no network
+bundle exec rake                     # tests and Standard, no network
 ruby examples/inventory_agent.rb
 ```
 
@@ -348,6 +583,8 @@ too. Two rules follow:
 
 - **Untrusted input (anything a user typed) belongs to `:predict`.** No code runs there.
 - **`:code_act` is for work you control** — internal tooling, workers, isolated environments.
+- **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 —
@@ -357,21 +594,16 @@ anything answering `call(agent, code, timeout:)` will do:
 Omakase.executor = MySubprocessExecutor    # returns an observation String or Executor::Answer
 ```
 
-## Roadmap
-
-What is not here yet, roughly in the order it would earn its place:
-
-- [x] **Live objects** — the answer is computed in code and handed back as the object, not retyped
-      as JSON. Done: `finish(value)` plus `returns: SomeClass`.
-- [x] **Tracing** — RubyLLM emits `chat.ruby_llm` and `tool_call.ruby_llm`; point `config.instrumenter`
-      at `ActiveSupport::Notifications` and subscribe. Done, by not writing it.
-- [ ] **Conversation history** — the chat is fresh per call. Keeping one per agent would let a
-      method continue where the last one left off, at the cost of deciding what to keep.
-- [ ] **Session storage** — persist that history and the agent state so a run can be resumed.
-- [x] **MCP tools** — external tools over the Model Context Protocol, via `ruby_llm-mcp`. Done:
-      `mcp :files, …` puts the server's tools on the agent, and generated code calls them.
-- [x] **Skills** — capabilities as markdown files with front matter, loaded on demand rather than
-      all sitting in the system prompt. Done: `skill "path/to/dir"`, one described method.
-- [ ] **Memory** — recall that survives across sessions, backed by vector search.
-- [x] **Concurrency** — parallel generation calls. Done: output is buffered per thread instead of
-      through `$stdout`, so threads no longer collide.
+## Not here, on purpose
+
+- **A checkpoint inside a generation.** A crashed run is retried whole. The tool loop belongs to
+  RubyLLM, and making it resumable would be a different library.
+- **Reflection and forgetting in memory.** No decay, no consolidation pass: `Memory` grows until you
+  prune it, and past a few hundred entries the answer is pgvector, not more code here.
+- **A sandbox.** `instance_eval` runs in your process. Real isolation is a swapped executor, above.
+- **Multi-agent orchestration.** An agent is an object, so one agent calling another is a method
+  call. There is nothing to add.
+- **Streaming.** A generation method returns a value, not tokens. RubyLLM streams if you need that.
+
+`1.0` lands when the API stops moving. Until then a minor version may move it, and `0.1.0` means
+the library is usable, not that it is finished.

data/lib/omakase/agent.rb

@@ -37,18 +37,40 @@ module Omakase
       # A skill directory — a SKILL.md with YAML front matter. Its description
       # joins the agent's capabilities; its body arrives when the model asks.
       def skill(path) = Skills.attach(self, path)
+
+      # Two more methods: one to save something, one to search it by meaning.
+      # The store is a field, so it marshals with the agent and outlives the run.
+      def memory
+        describe "Save something worth remembering after this run"
+        define_method(:remember) { |text| (@memory ||= Memory.new).remember(text) }
+        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.
+      def generates(name, prompt = 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_singleton_method(name) { |**inputs| new.public_send(name, **inputs) }
@@ -88,8 +110,20 @@ module Omakase
       @chat = chat
     end
 
-    # A fresh conversation per call.
-    def chat = @chat || RubyLLM.chat(**self.class.chat_options)
+    # 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))
+
+    # That state, as the model should read it: rebuilt on every call, and added
+    # to the class's instructions. Override it to remember anything.
+    def context = nil
+
+    # Resuming a run is loading the object back, so an agent marshals like any
+    # other Ruby object — minus the live chat, which is rebuilt on demand.
+    def marshal_dump = (instance_variables - [:@chat]).to_h { |name| [name, instance_variable_get(name)] }
+
+    def marshal_load(state) = state.each { |name, value| instance_variable_set(name, value) }
 
     # For generated code meeting an object whose type it does not know.
     def doc(object) = puts(Doc.of(object))
@@ -105,7 +139,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
@@ -116,7 +150,10 @@ module Omakase
 
     def generate(name, inputs)
       generation = self.class.generations.fetch(name)
-      generation.strategy.call(Request.new(agent: self, generation:, inputs:))
+      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}"
     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

@@ -8,16 +8,29 @@ module Omakase
 
     module_function
 
-    def of(object)
-      state = object.instance_variables.map { |name| "  #{name} = #{object.instance_variable_get(name).inspect}" }
-      [object.class.to_s, *signatures(object), *state].join("\n")
+    # A framework's base class defines hundreds of methods the model has no use
+    # for. What it wants is what this class adds — its columns, its associations,
+    # 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")
+
+    # An object that answers `attributes` says what it holds better than its
+    # instance variables do — and a record's columns are state, not API.
+    def state(object)
+      values = object.respond_to?(:attributes) ? object.attributes : ivars(object)
+      values.map { |name, value| "  #{name} = #{value.inspect}" }
     end
 
+    def ivars(object) = object.instance_variables.to_h { |name| [name, object.instance_variable_get(name)] }
+
     def signatures(object)
       object.class.ancestors
-        .take_while { |mod| !CORE.include?(mod) }
+        .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))})" }
     end
   end

data/lib/omakase/executor.rb

@@ -8,6 +8,7 @@ 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.
@@ -28,7 +29,7 @@ module Omakase
 
     # 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/memory.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Omakase
+  # Recall by meaning rather than by key: text goes in, the closest of it comes
+  # back out. The embeddings are RubyLLM's and the search is a dot product over
+  # an array — enough for the few hundred things one agent learns about its
+  # work. Past that it is your database's job (pgvector, the `neighbor` gem),
+  # and this is the interface to reimplement against it.
+  class Memory
+    def initialize = @entries = {}
+
+    # Keyed by the text, so remembering the same thing twice costs one entry.
+    def remember(text)
+      @entries[text] ||= unit(Omakase.embedder.call(text))
+      text
+    end
+
+    def recall(query, limit: 5)
+      return [] if empty?
+
+      vector = unit(Omakase.embedder.call(query))
+      @entries.max_by(limit) { |_, remembered| dot(vector, remembered) }.map(&:first)
+    end
+
+    def size = @entries.size
+
+    def empty? = @entries.empty?
+
+    private
+
+    def dot(one, other) = one.zip(other).sum { |a, b| a * b }
+
+    # Unit vectors, so the dot product is the cosine and lengths cannot skew it.
+    def unit(vector)
+      norm = Math.sqrt(vector.sum { |value| value * value })
+      norm.zero? ? vector : vector.map { |value| value / norm }
+    end
+  end
+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
+    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)
 
@@ -29,6 +32,8 @@ module Omakase
 
     def json = @json ||= definition.new.to_json_schema
 
+    def code_only? = false
+
     # The shape, in the shorthand the model writes back: `{city: <string>}`.
     def describe
       return "<#{properties.fetch("result")["type"]}>" if wrapped?
@@ -63,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,13 +12,16 @@ 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
 
-        # It never called finish: fall back to a tool-free turn under the schema.
-        Predict.call(request, task: "#{request.task}\n\nWork done:\n#{notes}")
+        # It never called finish. A JSON answer can still be given in a tool-free turn.
+        return Predict.call(request, task: "#{request.task}\n\nWork done:\n#{notes}") unless request.schema.code_only?
+
+        # An object cannot come back as JSON, so there is nowhere to fall back to.
+        raise ContractError, "#{request.generation.name}: the model never called finish(#{request.schema.describe})"
       end
 
       def instructions(request)

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))
         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/type.rb

@@ -8,7 +8,16 @@ module Omakase
       @klass = klass
     end
 
-    def describe = "a #{@klass}"
+    # A Struct or Data says what it holds, and the model needs that to build one:
+    # `Refund.new(order_id:, amount:, reason:)` beats `a Refund`.
+    def describe
+      return "a #{@klass}" unless @klass.respond_to?(:members)
+
+      "#{@klass}.new(#{@klass.members.map { |name| "#{name}:" }.join(", ")})"
+    end
+
+    # Only code can build it, so :predict is not a fallback.
+    def code_only? = true
 
     def take(value)
       return value if value.is_a?(@klass)

data/lib/omakase/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Omakase
-  VERSION = "0.0.2.alpha"
+  VERSION = "0.2.0"
 end

data/lib/omakase.rb

@@ -46,8 +46,38 @@ 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.
+    def embedder=(embedder)
+      @embedder = callable!(embedder, "embedder")
+    end
+
+    def embedder = @embedder ||= ->(text) { RubyLLM.embed(text).vectors }
+
+    # 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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omakase-agents
 version: !ruby/object:Gem::Version
-  version: 0.0.2.alpha
+  version: 0.2.0
 platform: ruby
 authors:
 - eugeny
@@ -63,6 +63,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - lib/omakase-agents.rb
@@ -74,6 +75,7 @@ files:
 - lib/omakase/fake_chat.rb
 - lib/omakase/generation.rb
 - lib/omakase/mcp.rb
+- lib/omakase/memory.rb
 - lib/omakase/request.rb
 - lib/omakase/schema.rb
 - lib/omakase/skills.rb
@@ -90,6 +92,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: []
@@ -102,9 +105,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubygems_version: 3.4.10
 signing_key: