omakase-agents 0.0.1.alpha

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c1cd37ac842736548d6501feab0ad139df3bad22437902f19ead73ed5eae819c
+  data.tar.gz: 733def6d93d950e7bd1507240877d90447dd7359255ba4e3c5bc3d93ce3794c6
+SHA512:
+  metadata.gz: 78f54588fa331091f7e604bab6637a31a9f7f14298b0f513df78e243f851079f9181c2c71c627f0a33d5069ec541711adee81e17516916077990b5e1495a4533
+  data.tar.gz: 4c97ef7304cce538f6dd4b9d95d6c7053bc6fff9ee6cab88a02b9d44ccdc38e78edfcf95d669a3a9a20fd9f94557d28e05b714eeac3405957d47e1e615f89592

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 eugeny
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,336 @@
+# Omakase
+
+A light agent framework — about 600 lines of library. *Omakase* (お任せ): you name what you want,
+the rest is left to the chef.
+
+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."
+
+  describe "Units of an item on hand"
+  def stock_of(item) = STOCK.dig(item, :stock) || 0
+
+  describe "Unit price of an item"
+  def price_of(item) = STOCK.dig(item, :price) || 0.0
+
+  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
+end
+
+InventoryAgent.can_fulfill_order(items: %w[apple banana orange], budget: 5.0)
+# => {can_fulfill: false, total_cost: 2.05, unavailable: ["orange"]}
+```
+
+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.
+
+## Installation
+
+Ruby 3.2+.
+
+```ruby
+gem "omakase-agents"     # the library is `Omakase`
+```
+
+Alpha (`0.0.1.alpha`) and not on RubyGems yet, so until it is, build it from a checkout:
+
+```bash
+git clone https://github.com/esshka/omakase
+cd omakase
+gem build omakase-agents.gemspec
+gem install ./omakase-agents-*.gem
+```
+
+## Usage
+
+### Declaring an agent
+
+```ruby
+class ApplicationAgent < Omakase::Agent            # every agent inherits the configuration
+  model "claude-sonnet-4-5"
+end
+
+class FeedbackAgent < ApplicationAgent
+  instructions "You analyze customer feedback."   # the system prompt
+  strategy :predict                               # :code_act (default) or :predict
+
+  generates :summarize                            # no prompt given: the method name is the prompt
+  generates :score, returns: :integer
+  generates :analyze, "Analyze the feedback." do
+    string :sentiment, enum: %w[positive negative neutral mixed]
+    array :topics, of: :string
+  end
+end
+```
+
+Generation methods take keyword arguments, which are rendered into the prompt, and are callable on
+the instance or on the class:
+
+```ruby
+FeedbackAgent.analyze(text: "Great product, but shipping was slow")
+# => {sentiment: "mixed", topics: ["product quality", "shipping speed"]}
+
+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.
+
+### Return types
+
+The block is a [schematist](https://github.com/crmne/schematist) schema and becomes the provider's
+structured-output contract, so a generation method returns validated data, never text to parse.
+For a single value, name the type instead:
+
+```ruby
+generates :count_items, returns: :integer      # :string (default), :integer, :number, :boolean
+```
+
+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.
+
+### Models and providers
+
+Any provider RubyLLM supports — Anthropic, OpenAI, Gemini, Bedrock, Azure, Mistral, DeepSeek, xAI,
+Perplexity, OpenRouter, Ollama, GPUStack, VertexAI. Give the model id, and the provider when the id
+is not one RubyLLM has in its registry:
+
+```ruby
+class ApplicationAgent < Omakase::Agent
+  model "claude-sonnet-4-5"                                    # resolved from the registry
+  model "meta/muse-glimmer-30b", provider: :openrouter         # taken on trust
+  model "qwen3:1.7b", provider: :ollama                        # local
+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.
+
+Credentials come from the environment — one call covers every provider:
+
+```ruby
+Omakase.configure_from_env    # ANTHROPIC_API_KEY, OPENROUTER_API_KEY, OLLAMA_API_BASE, …
+```
+
+Or set them yourself; `configure` is RubyLLM's, with all of its options:
+
+```ruby
+Omakase.configure do |config|
+  config.anthropic_api_key = Rails.application.credentials.anthropic_api_key
+  config.default_model = "claude-sonnet-4-5"   # used by agents that declare no model
+  config.request_timeout = 120
+end
+```
+
+### 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:
+
+```ruby
+chat = Omakase::FakeChat.new { {"severity" => "high", "summary" => "…"} }
+assert_equal "high", SupportAgent.new(chat:).triage(message: "broken")[:severity]
+
+# drive the tool the way a model would
+chat = Omakase::FakeChat.new { |fake| fake.run("finish(stock_of(:apple))") }
+```
+
+It records `instructions`, `schema`, `tools` and `tasks`, so the prompt is assertable too.
+
+## Rails
+
+Agents live in `app/agents` — Rails autoloads it, and reloading is safe because everything a
+generation method needs is rebuilt when the class is. [`examples/rails_app.rb`](examples/rails_app.rb)
+is all of this as one runnable file: initializer, agent, controller, one request.
+
+```ruby
+# config/initializers/omakase.rb
+Omakase.configure do |config|
+  config.anthropic_api_key = Rails.application.credentials.anthropic_api_key
+  config.default_model = "claude-sonnet-4-5"
+  config.request_timeout = 60          # RubyLLM's default is 300s — too long for a web request
+  config.max_retries = 3               # transient provider failures, with backoff
+  config.logger = Rails.logger
+  config.instrumenter = ActiveSupport::Notifications
+end
+```
+
+That last line puts every call on the notification bus, so tokens, cost and latency land in your
+logs and APM without any code of ours:
+
+```ruby
+ActiveSupport::Notifications.subscribe("chat.ruby_llm") do |*, payload|
+  Rails.logger.info(model: payload[:model], input: payload[:input_tokens], output: payload[:output_tokens])
+end
+```
+
+A generation call takes seconds, so keep it off the request thread:
+
+```ruby
+class TriageJob < ApplicationJob
+  def perform(ticket) = ticket.update!(SupportAgent.triage(message: ticket.body))
+end
+```
+
+Jobs move data, not objects: arguments and results have to serialize, so a `returns: SomeClass`
+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.
+
+**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:
+
+```ruby
+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.
+
+**Errors.** Everything raised at the boundary is an `Omakase::Error`:
+
+| | |
+| --- | --- |
+| `Omakase::ContractError` | the answer did not match the declared return type, twice |
+| `Omakase::ProviderError` | the provider failed — rate limit, overload, bad key — after RubyLLM's retries |
+
+Inside a `:code_act` loop neither reaches you: a contract miss and a raised exception both come back
+to the model as an observation, and it tries again within its call budget.
+
+## How it works
+
+Calling a generation method does four things:
+
+1. **Builds a request.** `Request` carries the agent, the generation (prompt, schema, strategy), the
+   keyword arguments, and a fresh chat — one conversation per call, no accumulated history.
+2. **Renders the prompt.** The agent's `instructions` are the system prompt; the method's prompt and
+   its arguments are the user message.
+3. **Runs the strategy** (below), which is where the LLM work happens.
+4. **Holds it to the contract.** Whether the answer arrived as JSON or as a Ruby value from
+   `finish`, it is symbolized, unwrapped if it is a lone `result`, and refused if it is off-contract.
+
+### Strategies
+
+A strategy is *how* a generation method gets its answer — one call, a code loop, your own
+retry-and-critique scheme. It is an execution detail, not part of the method's contract: swapping
+one for another changes cost and capability, and no caller changes.
+
+Formally, a strategy is anything that responds to `call(request)` and returns the cast value. Two
+ship with the library:
+
+**`:predict`** — one call. The chat is configured with the instructions and the schema, the task
+goes in, structured output comes back; an answer that misses the schema gets one correction
+turn naming what was wrong. No code runs. Right for classification, extraction, rewriting — anything the model can answer from the prompt alone.
+
+**`:code_act`** *(default)* — the model acts by writing Ruby. It gets one tool, `ruby`, whose code
+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
+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.
+
+Because the answer is computed rather than retyped, the return type can be a Ruby class and the
+method hands back the object itself:
+
+```ruby
+generates :file_ticket, "File a ticket for the message.", returns: Ticket
+# => #<struct Ticket id="A-1", severity="high">
+```
+
+That needs `:code_act` — `:predict` has no code in which to build one. If the model never calls
+`finish`, the strategy falls back to a tool-free turn under the JSON schema.
+
+Set the default per agent with `strategy :predict`, per method with
+`generates :triage, strategy: :predict`, or pass your own object:
+
+```ruby
+module CriticStrategy
+  def self.call(request)
+    draft = Omakase::Strategies::CodeAct.call(request)
+    ...
+  end
+end
+
+generates :plan, strategy: CriticStrategy
+```
+
+### Layout
+
+    lib/omakase.rb                 configuration
+    lib/omakase/agent.rb           the DSL: model, instructions, describe, generates
+    lib/omakase/generation.rb      a declared method: prompt, schema, strategy
+    lib/omakase/request.rb         one invocation of one
+    lib/omakase/schema.rb          return types the provider enforces
+    lib/omakase/type.rb            return types that are a Ruby class
+    lib/omakase/capabilities.rb    the agent’s own methods, listed for the model
+    lib/omakase/doc.rb             what an unfamiliar object offers, for generated code
+    lib/omakase/executor.rb        runs generated Ruby against the agent
+    lib/omakase/tools/ruby.rb      that executor, as a RubyLLM tool, with a call budget
+    lib/omakase/fake_chat.rb       the stand-in chat for tests
+    lib/omakase/strategies/        code_act, predict
+
+## Examples
+
+Copy `.env.example` to `.env` and fill in a key; `MODEL` and `PROVIDER` there pick the backend.
+
+| File | Shows |
+| --- | --- |
+| [`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 |
+| [`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 |
+
+```bash
+bundle exec rake                     # tests, no network
+ruby examples/inventory_agent.rb
+```
+
+## Safety
+
+Generated code runs with `instance_eval` in your process. In a Rails app that means it can reach
+`ActiveRecord`, `ENV`, and the filesystem — a container does not help, because your app is inside it
+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.
+
+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:
+
+```ruby
+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.
+- [ ] **MCP tools** — external tools over the Model Context Protocol, via `ruby_llm-mcp`. Cheap to
+      add, since generated code can call anything the agent exposes.
+- [ ] **Skills** — capabilities as markdown files with front matter, loaded on demand rather than
+      all sitting in the system prompt.
+- [ ] **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.

data/lib/omakase/agent.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Omakase
+  # Fields are state, methods are what the model can call, `generates` declares
+  # the methods the model implements.
+  class Agent
+    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
+      # not in RubyLLM's registry.
+      def model(id = nil, **options)
+        return chat_options if id.nil? && options.empty?
+
+        options = {assume_model_exists: true, **options} if options[:provider]
+        @chat_options = {model: id, **options}.compact
+      end
+
+      def instructions(text = nil)
+        return @instructions.to_s if text.nil?
+
+        @instructions = text
+      end
+
+      def strategy(name = nil)
+        return @strategy || :code_act if name.nil?
+
+        @strategy = name
+      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)
+        generations[name] = Generation.new(
+          name:,
+          prompt: prompt || humanize(name),
+          schema: Schema.define(returns:, &schema),
+          strategy: Strategies.fetch(strategy || self.strategy)
+        )
+        define_method(name) { |**inputs| generate(name, inputs) }
+        define_singleton_method(name) { |**inputs| new.public_send(name, **inputs) }
+      end
+
+      def generations = @generations ||= {}
+
+      def descriptions = @descriptions ||= {}
+
+      def chat_options = @chat_options ||= {}
+
+      private
+
+      def humanize(name)
+        text = name.to_s.tr("_", " ").capitalize
+        text.end_with?("?", "!") ? text : "#{text}."
+      end
+
+      def method_added(name)
+        super
+        descriptions[name] = @pending_description if @pending_description
+        @pending_description = nil
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@chat_options, chat_options.dup)
+        subclass.instructions(instructions) unless instructions.empty?
+        subclass.strategy(@strategy) if @strategy
+        subclass.generations.merge!(generations)
+        subclass.descriptions.merge!(descriptions)
+      end
+    end
+
+    # `chat:` injects a prepared RubyLLM::Chat — the seam for tests.
+    def initialize(chat: nil)
+      @chat = chat
+    end
+
+    # A fresh conversation per call.
+    def chat = @chat || RubyLLM.chat(**self.class.chat_options)
+
+    # For generated code meeting an object whose type it does not know.
+    def doc(object) = puts(Doc.of(object))
+
+    # How generated code answers: with the value itself.
+    def finish(value) = throw(Executor::RESULT, value)
+
+    # Printing from generated code goes to the observation, not to the process's
+    # stdout — and the buffer is per thread, so concurrent agents stay separate.
+    def puts(*args) = omakase_output.puts(*args)
+
+    def print(*args) = omakase_output.print(*args)
+
+    def p(*args)
+      args.each { |arg| omakase_output.puts(arg.inspect) }
+      args.size <= 1 ? args.first : args
+    end
+
+    alias_method :pp, :p
+
+    private
+
+    def omakase_output = Thread.current[Executor::OUTPUT] || $stdout
+
+    def generate(name, inputs)
+      generation = self.class.generations.fetch(name)
+      generation.strategy.call(Request.new(agent: self, generation:, inputs:))
+    rescue RubyLLM::Error, RubyLLM::ConfigurationError, RubyLLM::ModelNotFoundError => e
+      raise ProviderError, "#{self.class}##{name}: #{e.message}"
+    end
+  end
+end

data/lib/omakase/capabilities.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Omakase
+  # The agent's own methods, written out for the model. Adding a tool is adding
+  # a method.
+  module Capabilities
+    module_function
+
+    def of(agent_class, except: nil)
+      (names(agent_class) - [except]).sort.map { |name| entry(agent_class, name) }
+    end
+
+    def names(agent_class)
+      agent_class.ancestors
+        .take_while { |mod| mod != Agent }
+        .flat_map { |mod| mod.public_instance_methods(false) }
+        .uniq
+    end
+
+    def entry(agent_class, name)
+      signature = "#{name}(#{parameters(agent_class.instance_method(name))})"
+      description = agent_class.descriptions[name] || agent_class.generations[name]&.prompt
+      description ? "#{signature} — #{description}" : signature
+    end
+
+    def parameters(method)
+      method.parameters.map do |kind, name|
+        case kind
+        when :key, :keyreq then "#{name}:"
+        when :keyrest then "**#{name}"
+        when :rest then "*#{name}"
+        when :opt then "#{name} = ..."
+        else name.to_s
+        end
+      end.join(", ")
+    end
+  end
+end

data/lib/omakase/doc.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Omakase
+  # What an object offers, for a model that has never seen its type: what the
+  # object's own classes define, not what Ruby gives everything.
+  module Doc
+    CORE = [Object, Kernel, BasicObject, Struct, Data, Enumerable, Comparable].freeze
+
+    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")
+    end
+
+    def signatures(object)
+      object.class.ancestors
+        .take_while { |mod| !CORE.include?(mod) }
+        .flat_map { |mod| mod.public_instance_methods(false) }
+        .uniq.sort
+        .map { |name| "  #{name}(#{Capabilities.parameters(object.method(name))})" }
+    end
+  end
+end

data/lib/omakase/executor.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Omakase
+  # Runs model-written Ruby in the agent's own context.
+  # ponytail: instance_eval is not a sandbox — see Omakase.executor to swap it.
+  module Executor
+    SOURCE = "(generated)"
+    RESULT = :omakase_result
+    OUTPUT = :omakase_output
+    TIMEOUT = 30
+    MAX_OUTPUT = 4_000
+
+    # What `finish(value)` handed back: the answer as a Ruby value, not as text.
+    Answer = Data.define(:value)
+
+    module_function
+
+    def call(agent, code, timeout: TIMEOUT)
+      printed = StringIO.new
+      answer = catch(RESULT) do
+        value = capturing(printed) { Timeout.timeout(timeout) { agent.instance_eval(code, SOURCE, 1) } }
+        return observation([printed.string.chomp, "=> #{value.inspect}"])
+      end
+      Answer.new(value: answer)
+    rescue ScriptError, StandardError => e
+      observation([printed.string.chomp, failure(e, code)])
+    end
+
+    # The model can only fix what it can locate, so point at the line.
+    def failure(error, code)
+      line = error.backtrace&.grep(/\A#{Regexp.escape(SOURCE)}:\d+/)&.first&.slice(/:(\d+)/, 1)&.to_i
+      source = code.lines[line - 1]&.strip if line&.positive?
+      ["#{error.class}: #{error.message}", ("line #{line}: #{source}" if source)].compact.join("\n")
+    end
+
+    def observation(parts)
+      text = parts.reject(&:empty?).join("\n")
+      text = "#{text[0, MAX_OUTPUT]}\n… (truncated)" if text.length > MAX_OUTPUT
+      text.empty? ? "(no output)" : text
+    end
+
+    # Thread-local, so concurrent agents never share a buffer. Agent#puts reads it.
+    def capturing(io)
+      previous = Thread.current[OUTPUT]
+      Thread.current[OUTPUT] = io
+      yield
+    ensure
+      Thread.current[OUTPUT] = previous
+    end
+  end
+end

data/lib/omakase/fake_chat.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Omakase
+  # Stands in for a RubyLLM::Chat so agents can be tested without a network:
+  # records how the chat was configured, then runs the script you gave it.
+  #
+  #   agent = SupportAgent.new(chat: Omakase::FakeChat.new { {"severity" => "high"} })
+  #
+  # The script receives the chat, so it can drive the tool the way a model would:
+  #
+  #   Omakase::FakeChat.new { |chat| chat.run("finish(42)") }
+  class FakeChat
+    Response = Struct.new(:content)
+
+    attr_reader :instructions, :schema, :tools, :tasks
+
+    def initialize(&script)
+      @script = script
+      @instructions = []
+      @tools = []
+      @tasks = []
+    end
+
+    def with_instructions(text) = tap { @instructions << text }
+
+    def with_schema(schema) = tap { @schema = schema }
+
+    def with_tool(tool, **) = tap { @tools << tool }
+
+    def ask(task)
+      @tasks << task
+      Response.new(@script.call(self))
+    end
+
+    # Run code the way the model would, through the agent's one tool.
+    def run(code) = tools.fetch(0).call(code:)
+  end
+end

data/lib/omakase/generation.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+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)
+end

data/lib/omakase/request.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+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 schema = generation.schema
+
+    def instructions = agent.class.instructions
+
+    def task
+      return generation.prompt if inputs.empty?
+
+      arguments = inputs.map { |name, value| "- #{name}: #{value.inspect}" }
+      "#{generation.prompt}\n\nInputs:\n#{arguments.join("\n")}"
+    end
+  end
+end

data/lib/omakase/schema.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Omakase
+  # The declared return type, enforced by the provider. A schema whose only
+  # property is `result` unwraps to that value.
+  class Schema
+    RESULT = :result
+    SCALARS = %i[string integer number boolean].freeze
+    RUBY_TYPES = {
+      "string" => String, "integer" => Integer, "number" => Numeric,
+      "array" => Array, "object" => Hash
+    }.freeze
+
+    def self.define(returns: nil, &block)
+      return new(Schematist::Schema.create(&block)) if block
+      return Type.new(returns) if returns.is_a?(Module)
+
+      type = returns || :string
+      raise Error, "returns: must be one of #{SCALARS.join(", ")}, a class, or a block" unless SCALARS.include?(type)
+
+      new(Schematist::Schema.create { public_send(type, RESULT) })
+    end
+
+    attr_reader :definition
+
+    def initialize(definition)
+      @definition = definition
+    end
+
+    def json = @json ||= definition.new.to_json_schema
+
+    # The shape, in the shorthand the model writes back: `{city: <string>}`.
+    def describe
+      return "<#{properties.fetch("result")["type"]}>" if wrapped?
+
+      "{#{properties.map { |name, spec| "#{name}: <#{spec["type"]}>" }.join(", ")}}"
+    end
+
+    # From the provider's JSON: unwrap first, then hold it to the contract.
+    def cast(content)
+      raise ContractError, "expected JSON matching #{JSON.generate(json)}, got #{content.inspect}" unless content.is_a?(Hash)
+
+      data = RubyLLM::Utils.deep_symbolize_keys(content)
+      take(wrapped? ? data.fetch(RESULT) { raise ContractError, %(missing "result" in #{data.inspect}) } : data)
+    end
+
+    # From a Ruby value the generated code computed.
+    def take(value)
+      return demand(value, properties.fetch("result")["type"]) if wrapped?
+      raise ContractError, "expected #{describe}, got #{value.inspect}" unless value.is_a?(Hash)
+
+      data = RubyLLM::Utils.deep_symbolize_keys(value)
+      missing = json.fetch("required").map(&:to_sym) - data.keys
+      raise ContractError, "missing #{missing.join(", ")} — expected #{describe}" if missing.any?
+
+      data
+    end
+
+    def wrapped? = definition.properties.keys == [RESULT]
+
+    private
+
+    def properties = json.fetch("properties")
+
+    def demand(value, 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
+    end
+  end
+end

data/lib/omakase/strategies/code_act.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Omakase
+  module Strategies
+    # The model acts by writing Ruby against the agent object and answers with
+    # `finish(value)` — the answer is computed, not retyped.
+    module CodeAct
+      module_function
+
+      def call(request)
+        tool = Tools::Ruby.new(request.agent, request.schema)
+        notes = request.chat
+          .with_instructions(instructions(request))
+          .with_tool(tool)
+          .ask(request.task)
+          .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}")
+      end
+
+      def instructions(request)
+        <<~TEXT
+          #{request.instructions}
+
+          You act by writing Ruby: call the `ruby` tool with code that is evaluated on the
+          agent object, so its methods and state are available on self.
+
+          #{capabilities(request).join("\n")}
+
+          `doc(object)` prints what an object of an unfamiliar type offers.
+
+          Return the answer from inside the code, never as a message — the last thing you run is:
+
+              finish(#{request.schema.describe})
+
+          Work in as few tool calls as you can.
+        TEXT
+      end
+
+      def capabilities(request)
+        Capabilities.of(request.agent.class, except: request.generation.name).map { |entry| "- #{entry}" }
+      end
+    end
+  end
+end

data/lib/omakase/strategies/predict.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Omakase
+  module Strategies
+    # One call, no code execution: the model answers straight into the schema.
+    module Predict
+      CORRECTION = "Answer again as JSON, and nothing else."
+
+      module_function
+
+      def call(request, task: request.task)
+        chat = request.chat
+          .with_instructions(instructions(request))
+          .with_schema(request.schema.definition)
+
+        request.schema.cast(chat.ask(task).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)
+      end
+
+      # Weaker providers treat the schema as a hint, so it goes in the prompt too.
+      def instructions(request)
+        "#{request.instructions}\n\nAnswer as JSON matching this schema:\n#{JSON.generate(request.schema.json)}"
+      end
+    end
+  end
+end

data/lib/omakase/strategies.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Omakase
+  # How a generation method gets its answer. Named ones are looked up by symbol
+  # (`strategy :predict`); anything that responds to `call(request)` also works,
+  # which is the seam for your own.
+  module Strategies
+    module_function
+
+    def fetch(strategy)
+      return strategy if strategy.respond_to?(:call)
+
+      const_get(strategy.to_s.split("_").map(&:capitalize).join)
+    rescue NameError
+      raise Error, "unknown strategy #{strategy.inspect}"
+    end
+  end
+end

data/lib/omakase/tools/ruby.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Omakase
+  module Tools
+    # The model's one tool. Every capability of the agent reaches the model
+    # through it, so the model composes calls in code instead of one per turn.
+    class Ruby < RubyLLM::Tool
+      BUDGET = 10
+
+      description <<~TEXT
+        Evaluate Ruby in the context of the agent object: its methods and state are
+        directly available on self. Anything printed, plus the value of the last
+        expression, is returned to you. Call finish(value) to answer.
+      TEXT
+
+      param :code, desc: "Ruby source to evaluate."
+
+      attr_reader :answer
+
+      def initialize(agent, schema, budget: BUDGET, timeout: Executor::TIMEOUT, executor: Omakase.executor)
+        super()
+        @agent = agent
+        @schema = schema
+        @budget = budget
+        @timeout = timeout
+        @executor = executor
+        @calls = 0
+      end
+
+      def name = "ruby"
+
+      def execute(code:)
+        # Nothing bounds the provider's tool loop, so the budget does.
+        @calls += 1
+        return "No tool calls left — answer with what you have." if @calls == @budget + 1
+        return halt("Tool budget spent.") if @calls > @budget + 1
+
+        outcome = @executor.call(@agent, code, timeout: @timeout)
+        return outcome unless outcome.is_a?(Executor::Answer)
+
+        @answer = Executor::Answer.new(value: @schema.take(outcome.value))
+        halt("Answer accepted.")
+      rescue Error => e
+        # Off-contract answers are corrected inside the same loop, not by another request.
+        "finish rejected: #{e.message}"
+      end
+    end
+  end
+end

data/lib/omakase/type.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Omakase
+  # A return type that is a Ruby class: the model builds the object in code and
+  # hands the object itself back, so nothing goes through JSON.
+  class Type
+    def initialize(klass)
+      @klass = klass
+    end
+
+    def describe = "a #{@klass}"
+
+    def take(value)
+      return value if value.is_a?(@klass)
+
+      raise ContractError, "expected #{describe}, got #{value.class}"
+    end
+
+    def definition
+      raise Error, "returns: #{@klass} needs the :code_act strategy — the model has to build the object in code"
+    end
+
+    alias_method :json, :definition
+  end
+end

data/lib/omakase/version.rb

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

data/lib/omakase-agents.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# The gem is `omakase-agents`; the library is `Omakase`.
+require_relative "omakase"

data/lib/omakase.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# Object-oriented agents: an agent is a Ruby object. Its methods are its tools,
+# and the methods it *declares* but does not implement are written by an LLM.
+require "json"
+require "ruby_llm"
+require "schematist"
+require "stringio"
+require "timeout"
+require "zeitwerk"
+
+loader = Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
+loader.ignore("#{__dir__}/omakase-agents.rb")
+loader.setup
+
+module Omakase
+  Error = Class.new(StandardError)
+  # The answer did not match the declared return type.
+  ContractError = Class.new(Error)
+  # The model or its provider failed. RubyLLM has already retried what it retries.
+  ProviderError = Class.new(Error)
+
+  class << self
+    # Providers, keys, default model, timeouts, logging — all of it is RubyLLM's.
+    def configure(&) = RubyLLM.configure(&)
+
+    # Reads every provider credential RubyLLM knows from the environment:
+    # ANTHROPIC_API_KEY, OPENROUTER_API_KEY, OLLAMA_API_BASE, VERTEXAI_PROJECT_ID, …
+    def configure_from_env(env = ENV)
+      configure do |config|
+        provider_options.each do |option|
+          value = env[option.to_s.upcase]
+          config.public_send(:"#{option}=", value) if value
+        end
+      end
+    end
+
+    def provider_options
+      slugs = RubyLLM::Provider.providers.keys
+      RubyLLM::Configuration.options.select do |option|
+        slugs.any? { |slug| option.to_s.start_with?("#{slug}_") }
+      end
+    end
+
+    # 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
+  end
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: omakase-agents
+version: !ruby/object:Gem::Version
+  version: 0.0.1.alpha
+platform: ruby
+authors:
+- eugeny
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: schematist
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+description: |
+  A light agent framework on top of RubyLLM. 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. The model acts by writing Ruby that runs on the agent itself.
+email:
+- esshka@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/omakase-agents.rb
+- lib/omakase.rb
+- lib/omakase/agent.rb
+- lib/omakase/capabilities.rb
+- lib/omakase/doc.rb
+- lib/omakase/executor.rb
+- lib/omakase/fake_chat.rb
+- lib/omakase/generation.rb
+- lib/omakase/request.rb
+- lib/omakase/schema.rb
+- lib/omakase/strategies.rb
+- lib/omakase/strategies/code_act.rb
+- lib/omakase/strategies/predict.rb
+- lib/omakase/tools/ruby.rb
+- lib/omakase/type.rb
+- lib/omakase/version.rb
+homepage: https://github.com/esshka/omakase
+licenses:
+- MIT
+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
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Agents as plain Ruby objects.
+test_files: []