omakase-agents 0.0.2.alpha → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96b04f8669c6e6bf4f176d19b779ca495fb1b2fde034952c48175eb2999647b3
-  data.tar.gz: 32d2d58018dd35cf63590c889f6c9e5a8bca214e1ccfcd9989c0f90c157bec70
+  metadata.gz: 9c9bb739c426cb0b979359a772e7cdcbe84019c303d10c0d1c0b27fe8b8d00c0
+  data.tar.gz: 88c343d1a654d19be11b6071658e962be3f64dc477e8be1aa767520c3c7ac13f
 SHA512:
-  metadata.gz: e596c18452218540f3a92c7f2542cbf1ea7e5b4fe0314c359e784d14fe331defdaf40f642cd4679667ed0e6ca5c8e42bd171cb940b2b2bd6b3fd47faba41bf97
-  data.tar.gz: 18e626683d93029d7d29da409b9f456800cf4b0579e9e478636d4b8ff2902f628ef34460cf3dd935b164e76d057bc3b01bb22c3a4b58fe9c15c354befbdc9cf9
+  metadata.gz: 8d02d96784acf426a52dc5eb2207d3a426e9beddb1106cd96195941781557019823be03502e9c580253ff249a8dfa7df0d4210e7eace17a6cfaca1d362321151
+  data.tar.gz: 6fb9221fb891f4a9b0898b8924ec2705e093acfeba76367c57bde8d56810227da3ea9667036638360515797ceda2bf1d5edd442766f1fb87f44aeeaa75265166

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) ![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
@@ -150,7 +205,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 +224,74 @@ 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 (`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
+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:
 
@@ -317,6 +439,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,12 +451,15 @@ 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
@@ -348,6 +474,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 +485,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,6 +37,15 @@ 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
@@ -88,9 +97,20 @@ module Omakase
       @chat = chat
     end
 
-    # A fresh conversation per call.
+    # 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)
 
+    # 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))
 

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/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

@@ -7,7 +7,7 @@ module Omakase
 
     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")
 
     def task
       return generation.prompt if inputs.empty?

data/lib/omakase/schema.rb

@@ -29,6 +29,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?

data/lib/omakase/strategies/code_act.rb

@@ -17,8 +17,11 @@ module Omakase
 
         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/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.1.0"
 end

data/lib/omakase.rb

@@ -49,5 +49,11 @@ module Omakase
     attr_writer :executor
 
     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 ||= ->(text) { RubyLLM.embed(text).vectors }
   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.1.0
 platform: ruby
 authors:
 - eugeny
@@ -74,6 +74,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
@@ -102,9 +103,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: