omnibot-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 075266e9395d95dedce797206f30b73cdfd972aa59a97813f87e1b6b7f6ce75b
+  data.tar.gz: 4cda42ac155f91a4422000ebc2773c328062694cef3e9867292c47d8d5e7e393
+SHA512:
+  metadata.gz: 2bbf2240ffcae6a4225abf426d0e0799e075cff632b10cb3357bd03383263564af5706f71bc205a7c8d7adb6111bd863c857087a0efadf8008288907c7be5b36
+  data.tar.gz: ff9256f23f891d0664f2e476c797b02462bbd3dd2c2f9ff41c1a70ce4f509c56c1769d8ac171e146fe957b244ace503dfa3dbacf137b57c964d6b40065489b59

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Johannes Dwicahyo
+
+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,209 @@
+# omnibot-ruby
+
+Rails-first LLM agents for Ruby.
+
+## Why
+
+`omnibot-ruby` is a Rails-idiomatic agent framework built on [`ruby_llm`](https://github.com/crmne/ruby_llm) — a class DSL for bounded tool-calling agents that lives in your Rails app, not a Python sidecar you have to deploy, proxy, and keep in sync. It ships two primitives: **Agent** (v0.1, available now — a bounded tool-calling loop with fast paths, structured extraction, and streaming) and **Workflow** (coming in v0.2 — a durable, ActiveRecord-checkpointed graph engine for multi-step conversations with human handover, so long-running flows survive restarts without a Redis checkpointer). Everything runs in-process, which means token streaming to ActionCable/Turbo is a callback away instead of blocked behind an HTTP hop.
+
+## Install
+
+```bash
+bundle add omnibot-ruby
+rails g omnibot:install
+```
+
+The install generator writes `config/initializers/omnibot.rb`, where you set your default model:
+
+```ruby
+Omnibot.configure do |config|
+  config.default_model = "gpt-4o-mini"
+  # config.on_tool_error = :capture  # or :raise
+end
+```
+
+Scaffold an agent with:
+
+```bash
+rails g omnibot:agent Support
+```
+
+This creates `app/agents/support_agent.rb` and a matching spec in `spec/agents/`.
+
+## Quick start
+
+```ruby
+class SupportAgent < Omnibot::Agent
+  model "claude-sonnet-5"                                # any ruby_llm model string
+  instructions "You help customers of {{company}}."      # {{var}} interpolates from context
+  max_turns 3
+
+  tool :lookup_order, "Find an order" do |order_id:|
+    "order #{order_id}: shipped"
+  end
+end
+
+result = SupportAgent.run("where is order #123?",
+  history: conversation.recent_messages,   # app-owned, app-windowed
+  context: { company: "Wokku" })
+
+result.text          # => "Order 123 is shipped!"
+result.tool_calls     # => [#<struct Omnibot::ToolCallRecord name="lookup_order", arguments={:order_id=>123}>]
+result.usage.input_tokens
+```
+
+Semantics worth knowing:
+
+- The loop is: send → execute tool calls → append results → repeat, up to `max_turns`. On the final turn, tools are unbound so the model is forced to answer instead of looping forever. `max_turns` bounds the number of tool executions in a run (parallel tool calls each count) — not conversation rounds.
+- `instructions` support `{{var}}` interpolation from `context`; a missing variable raises `KeyError`.
+- `history` is a plain array of `{ role:, content: }` hashes (or anything that responds to `#role`/`#content`) — the gem never persists conversations itself.
+- A custom `Omnibot.chat_factory` lambda must accept extra kwargs (e.g. `->(model:, **) { ... }`) — Agent always calls it with `agent_class:` in addition to `model:`.
+- Block-tool params are always JSON type `"string"` — models send `"123"`, not `123`. Declare param types via class-form tools (`param :n, type: "integer"`) when types matter.
+- Class-form tools must declare `param` explicitly — the wrapper that adds error capture shadows `#execute`'s signature, so ruby_llm's automatic param inference doesn't see your keyword args:
+
+  ```ruby
+  class AddTool < Omnibot::Tool
+    description "Adds two numbers"
+    param :a, desc: "First"
+    param :b, desc: "Second"
+
+    def execute(a:, b:) = a + b
+  end
+
+  class SupportAgent < Omnibot::Agent
+    tool AddTool
+  end
+  ```
+
+## Fast paths
+
+Fast paths run in declaration order *before* any LLM call. Call `reply(text)` to short-circuit with zero token usage; return `nil` (or don't call `reply`) to fall through to the next fast path, and eventually to the LLM. Override `tools_for(context)` to gate which tools are attached per run.
+
+```ruby
+class SupportAgent < Omnibot::Agent
+  instructions "support"
+
+  fast_path do |message, _context|
+    reply("Halo! Ada yang bisa dibantu?") if message.match?(/\A(hi|halo|hai)\b/i)
+  end
+
+  fast_path do |_message, context|
+    reply("VIP line") if context[:vip]
+  end
+
+  tool(:escalate, "Escalate") { |**| "escalated" }
+  tool(:lookup, "Lookup")     { |**| "found" }
+
+  def tools_for(context)
+    context[:angry] ? self.class.tools.reject { |t| t.new.name == "escalate" } : super
+  end
+end
+
+result = SupportAgent.run("halo kak")
+result.text         # => "Halo! Ada yang bisa dibantu?"
+result.fast_path?   # => true
+result.usage.input_tokens # => 0
+```
+
+## Structured extraction
+
+`Agent.extract(input, schema:)` runs a single-shot structured extraction. Pass a [`RubyLLM::Schema`](https://github.com/crmne/ruby_llm) subclass describing the shape you want; on invalid JSON, omnibot automatically retries once with a repair prompt before raising `Omnibot::ExtractionError`.
+
+```ruby
+class DepositProof < RubyLLM::Schema
+  string :bank
+  integer :amount
+end
+
+class ProofAgent < Omnibot::Agent
+  instructions "Extract the bank name and amount from the customer's message."
+end
+
+result = ProofAgent.extract("transfer 50rb via BCA", schema: DepositProof)
+result # => { amount: 50_000, bank: "BCA" }
+```
+
+Note for testing: `Omnibot::Testing`'s fake chat ignores whatever you pass as `schema:` — it just parses the scripted reply as JSON (or passes a scripted Hash straight through via `then_extract`). Schema-driven provider-side structured output only kicks in against a real LLM.
+
+## Streaming
+
+Pass `stream:` to `run` and it's called with each response chunk as a plain `String`, as it arrives:
+
+```ruby
+chunks = []
+result = SupportAgent.run("hi", stream: ->(chunk) { chunks << chunk })
+chunks.join    # => the full reply text, assembled from chunks
+result.text    # => the same full text once the run completes
+```
+
+Fast-path replies are never streamed — they short-circuit before any LLM call, so `stream` is simply not invoked for that run.
+
+Broadcasting to the browser is a plain app-side recipe, not framework code:
+
+```ruby
+result = SupportAgent.run(message.body,
+  context: { company: current_account.name },
+  stream: ->(chunk) {
+    ActionCable.server.broadcast("conversation_#{conversation.id}", chunk: chunk)
+  })
+```
+
+## Testing your agents
+
+`Omnibot::Testing.fake!` swaps in a deterministic scripted fake LLM so specs never hit a real provider. Script tool calls and replies with `stub_agent`, include `Omnibot::Testing::Helpers` for the `stub_agent` method, and reset after each example.
+
+```ruby
+RSpec.describe SupportAgent do
+  include Omnibot::Testing::Helpers
+
+  before { Omnibot::Testing.fake! }
+  after  { Omnibot::Testing.reset! }
+
+  it "looks up the order and replies" do
+    stub_agent(SupportAgent)
+      .to_call_tool(:lookup_order, order_id: 123)
+      .then_reply("Order 123 is shipped!")
+
+    result = SupportAgent.run("where is order 123?", context: { company: "Wokku" })
+
+    expect(result.text).to eq("Order 123 is shipped!")
+    expect(result.tool_calls.map(&:name)).to eq(["lookup_order"])
+  end
+end
+```
+
+The fake replays your script in order: `to_call_tool` asserts a tool is called and actually executes it (so bugs in your tool body still surface), `then_reply` ends the turn with a text reply, and `then_extract` ends it with a Hash for `Agent.extract` specs. If the script runs out, unscripted calls get a default `"(fake) <message>"` reply so runaway loops fail loudly instead of hanging. Class-form tools are plain Ruby objects — unit-test them directly, no fake required.
+
+## Instrumentation
+
+Everything is instrumented via `ActiveSupport::Notifications`, so you can wire usage logging, cost caps, or a dashboard without touching the gem:
+
+| Event | Payload keys |
+|---|---|
+| `omnibot.llm.call` | `agent:` (agent class), `model:` (String), `usage:` (`Omnibot::Usage` — `input_tokens`/`output_tokens`) |
+| `omnibot.tool.call` | `tool:` (tool class), `name:` (String), `args:` (Hash), `error:` (String, present only on failure) |
+| `omnibot.agent.run` | `agent:` (agent class), `fast_path:` (Boolean), `usage:` (`Omnibot::Usage`) |
+
+`omnibot.llm.call`'s `usage:` is per-call (that one provider round trip's final response). `omnibot.agent.run`'s `usage:` is the run total, summed across every provider round trip in the run — a single `Agent.run` can be several `omnibot.llm.call`s deep when the tool-calling loop goes more than one turn.
+
+Timing is available on the event object itself (`event.duration`) for any subscribed event — it is not a payload key. Workflow events (`omnibot.workflow.*`) arrive with Workflow in v0.2.
+
+A minimal usage-log subscriber — the whole recipe is 4 lines:
+
+```ruby
+usage_log = []
+ActiveSupport::Notifications.subscribe("omnibot.llm.call") do |event|
+  usage_log << { model: event.payload[:model], tokens: event.payload[:usage].input_tokens }
+end
+```
+
+Nothing in the gem phones home, ever — instrumentation is a local seam you subscribe to yourself.
+
+## Roadmap
+
+- **v0.2 — Workflow.** A durable, ActiveRecord-checkpointed graph engine for multi-step conversations: steps as nodes, transitions as edges, `wait_for_input` to checkpoint and pause for the next inbound message, `handover!` to page a human. State persists as jsonb on a gem-owned `omnibot_workflow_runs` table, so a workflow survives a deploy or a restart mid-conversation without a Redis checkpointer.
+- **Later — hosted observability.** A subscriber gem plus a hosted dashboard, built entirely on the instrumentation events above. Paid, optional, and no core changes required to adopt it.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/lib/generators/omnibot/agent/agent_generator.rb

@@ -0,0 +1,14 @@
+require "rails/generators"
+
+module Omnibot
+  module Generators
+    class AgentGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      def create_agent
+        template "agent.rb.tt", "app/agents/#{file_name}_agent.rb"
+        template "agent_spec.rb.tt", "spec/agents/#{file_name}_agent_spec.rb"
+      end
+    end
+  end
+end

data/lib/generators/omnibot/agent/templates/agent.rb.tt

@@ -0,0 +1,8 @@
+class <%= class_name %>Agent < Omnibot::Agent
+  instructions "You are a helpful assistant."
+  max_turns 5
+
+  # tool :lookup_order, "Find an order by ID" do |order_id:|
+  #   Order.find(order_id).summary
+  # end
+end

data/lib/generators/omnibot/agent/templates/agent_spec.rb.tt

@@ -0,0 +1,14 @@
+require "rails_helper"
+
+RSpec.describe <%= class_name %>Agent do
+  include Omnibot::Testing::Helpers
+
+  before { Omnibot::Testing.fake! }
+  after  { Omnibot::Testing.reset! }
+
+  it "replies" do
+    stub_agent(<%= class_name %>Agent).then_reply("hello!")
+    result = <%= class_name %>Agent.run("hi")
+    expect(result.text).to eq("hello!")
+  end
+end

data/lib/generators/omnibot/install/install_generator.rb

@@ -0,0 +1,13 @@
+require "rails/generators"
+
+module Omnibot
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def create_initializer
+        template "initializer.rb.tt", "config/initializers/omnibot.rb"
+      end
+    end
+  end
+end

data/lib/generators/omnibot/install/templates/initializer.rb.tt

@@ -0,0 +1,4 @@
+Omnibot.configure do |config|
+  config.default_model = "gpt-4o-mini"
+  # config.on_tool_error = :capture  # or :raise
+end

data/lib/omnibot/agent.rb

@@ -0,0 +1,246 @@
+module Omnibot
+  class Agent
+    class TurnLimit < StandardError; end
+
+    FAST_REPLY = :__omnibot_fast_reply
+
+    class << self
+      def model(value = nil)
+        value ? @model = value : (@model || Omnibot.config.default_model)
+      end
+
+      def instructions(value = nil)
+        value ? @instructions = value : @instructions
+      end
+
+      # Bounds the number of tool executions in a run, not conversation rounds —
+      # the before_tool_call hook counts each call, so parallel tool calls in a
+      # single round each count separately.
+      def max_turns(value = nil)
+        value ? @max_turns = value : (@max_turns || 5)
+      end
+
+      def tool(name_or_class, description = nil, &block)
+        tools << (block ? Tool.from_block(name_or_class, description, &block) : name_or_class)
+      end
+
+      def tools = @tools ||= []
+      def fast_paths = @fast_paths ||= []
+      def fast_path(&block) = fast_paths << block
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@model, @model)
+        subclass.instance_variable_set(:@instructions, @instructions)
+        subclass.instance_variable_set(:@max_turns, @max_turns)
+        subclass.instance_variable_set(:@tools, tools.dup)
+        subclass.instance_variable_set(:@fast_paths, fast_paths.dup)
+      end
+
+      def run(message, history: [], context: {}, stream: nil)
+        new(context).run(message, history: history, stream: stream)
+      end
+
+      def extract(input, schema:, context: {})
+        new(context).extract(input, schema: schema)
+      end
+    end
+
+    attr_reader :context
+
+    def initialize(context = {})
+      @context = context
+    end
+
+    def run(message, history: [], stream: nil)
+      ActiveSupport::Notifications.instrument("omnibot.agent.run", agent: self.class) do |payload|
+        payload[:fast_path] = false
+        result = run_loop(message, history, stream)
+        payload[:fast_path] = result.fast_path?
+        payload[:usage] = result.usage
+        result
+      end
+    end
+
+    # Override in subclasses to gate tools per run (context-aware).
+    def tools_for(_context) = self.class.tools
+
+    # Called from within a fast_path block to short-circuit the run loop.
+    def reply(text) = throw(FAST_REPLY, text)
+
+    def extract(input, schema:)
+      chat = Omnibot.chat_factory.call(model: self.class.model, agent_class: self.class)
+      chat.with_instructions(interpolated_instructions) if self.class.instructions
+      chat.with_schema(schema)
+
+      response = instrument_llm { chat.ask(input.to_s) }
+      parse_extraction(response.content) do |error|
+        repair = instrument_llm do
+          chat.ask("Your previous output was not valid JSON (#{error.message}). " \
+                    "Respond again with ONLY valid JSON matching the schema.")
+        end
+        parse_extraction(repair.content) do |_error|
+          raise ExtractionError, "extraction failed after repair: #{repair.content.to_s.truncate(200)}"
+        end
+      end
+    end
+
+    private
+
+    def run_loop(message, history, stream)
+      if (text = try_fast_paths(message))
+        return Result.new(text: text, tool_calls: [], usage: Usage.new(0, 0),
+                           messages: [], fast_path: true)
+      end
+
+      @history_for_build = history
+      chat = build_chat
+      tool_calls = []
+      turns = 0
+
+      chat.before_tool_call do |tc|
+        turns += 1
+        raise TurnLimit if turns > self.class.max_turns
+        tool_calls << ToolCallRecord.new(tc.name.to_s, tc.arguments)
+      end
+
+      response =
+        begin
+          instrument_llm { chat.ask(message, &wrap_stream(stream)) }
+        rescue TurnLimit
+          strip_tools(chat)
+          synthesize_pending_tool_results(chat)
+          instrument_llm do
+            chat.ask("Answer the user now with the information you already have. Do not call tools.",
+                     &wrap_stream(stream))
+          end
+        end
+
+      Result.new(
+        text: response.content.to_s,
+        tool_calls: tool_calls,
+        usage: run_usage(chat, response),
+        messages: chat.messages.map { |m| normalize_message(m) },
+        fast_path: false
+      )
+    end
+
+    def try_fast_paths(message)
+      self.class.fast_paths.each do |block|
+        result = catch(FAST_REPLY) do
+          instance_exec(message, context, &block)
+          nil
+        end
+        return result if result
+      end
+      nil
+    end
+
+    def build_chat
+      chat = Omnibot.chat_factory.call(model: self.class.model, agent_class: self.class)
+      chat.with_instructions(interpolated_instructions) if self.class.instructions
+      attach_history(chat)
+      tools = tools_for(context).map { |t| t.is_a?(Class) ? t.new(context) : t }
+      chat.with_tools(*tools) if tools.any?
+      chat
+    end
+
+    def interpolated_instructions
+      self.class.instructions.gsub(/\{\{(\w+)\}\}/) do
+        context.fetch(Regexp.last_match(1).to_sym).to_s
+      end
+    end
+
+    def attach_history(chat)
+      # accepts hashes or role/content duck-typed objects (e.g. AR models)
+      Array(@history_for_build).each do |m|
+        role    = m.respond_to?(:role)    ? m.role    : m[:role]
+        content = m.respond_to?(:content) ? m.content : m[:content]
+        chat.add_message(role: role.to_sym, content: content)
+      end
+    end
+
+    def wrap_stream(stream)
+      return nil unless stream
+      ->(chunk) { stream.call(chunk.content) if chunk.content && !chunk.content.empty? }
+    end
+
+    def instrument_llm(&)
+      ActiveSupport::Notifications.instrument(
+        "omnibot.llm.call", agent: self.class, model: self.class.model
+      ) do |payload|
+        response = yield
+        payload[:usage] = usage_from(response)
+        response
+      end
+    end
+
+    # Per-call usage (used for the omnibot.llm.call event): just the final response.
+    def usage_from(response)
+      tokens = response.respond_to?(:tokens) ? response.tokens : nil
+      Usage.new(tokens&.input || 0, tokens&.output || 0)
+    end
+
+    # Run-level usage (Result#usage / omnibot.agent.run): one real `ask` can be N
+    # provider round trips (tool-calling loop), so sum tokens across every message
+    # that carries them. FakeChat's plain-hash messages never respond to #tokens,
+    # so that falls back to the final response's usage — keeps fake-based specs green.
+    def run_usage(chat, response)
+      token_messages = chat.messages.select { |m| m.respond_to?(:tokens) && m.tokens }
+      return usage_from(response) if token_messages.empty?
+
+      Usage.new(
+        token_messages.sum { |m| m.tokens.input || 0 },
+        token_messages.sum { |m| m.tokens.output || 0 }
+      )
+    end
+
+    def strip_tools(chat)
+      chat.with_tools(replace: true)
+    end
+
+    # C1: against real ruby_llm, complete_once appends the assistant message
+    # (with tool_calls) BEFORE before_tool_call fires, so raising TurnLimit out of
+    # that hook leaves unanswered tool_call(s) in chat history. The follow-up
+    # "answer now" user-role ask then 400s on OpenAI/Anthropic because every
+    # tool_call must have a matching tool-result message. With parallel tool
+    # calls, some of the batch may already have results while the rest dangle.
+    # Duck-typed defensively: FakeChat's messages are plain hashes that don't
+    # respond to #tool_calls, so this is a safe no-op there.
+    def synthesize_pending_tool_results(chat)
+      last_call_message = chat.messages.reverse_each.find do |m|
+        m.respond_to?(:tool_calls) && m.tool_calls && !m.tool_calls.empty?
+      end
+      return unless last_call_message
+
+      answered_ids = chat.messages.filter_map { |m| m.tool_call_id if m.respond_to?(:tool_call_id) && m.tool_call_id }
+
+      last_call_message.tool_calls.each_value do |tc|
+        next if answered_ids.include?(tc.id)
+        chat.add_message(role: :tool, content: "(turn limit reached)", tool_call_id: tc.id)
+      end
+    end
+
+    def parse_extraction(content)
+      case content
+      when Hash then content.deep_symbolize_keys
+      when String
+        begin
+          JSON.parse(content, symbolize_names: true)
+        rescue JSON::ParserError => e
+          yield e
+        end
+      else
+        yield JSON::ParserError.new("expected a JSON string or Hash, got #{content.class}")
+      end
+    end
+
+    def normalize_message(m)
+      if m.is_a?(Hash)
+        { role: m[:role].to_sym, content: m[:content] }
+      else
+        { role: m.role.to_sym, content: m.content }
+      end
+    end
+  end
+end

data/lib/omnibot/config.rb

@@ -0,0 +1,21 @@
+module Omnibot
+  class Config
+    attr_accessor :default_model, :on_tool_error
+
+    def initialize
+      @default_model = "gpt-4o-mini"
+      @on_tool_error = :capture
+    end
+  end
+
+  class << self
+    def config = @config ||= Config.new
+    def configure = yield(config)
+    def reset_config! = @config = nil
+
+    def chat_factory
+      @chat_factory ||= ->(model:, **) { RubyLLM.chat(model: model) }
+    end
+    attr_writer :chat_factory
+  end
+end

data/lib/omnibot/errors.rb

@@ -0,0 +1,7 @@
+module Omnibot
+  class Error < StandardError; end
+  class LLMError < Error; end
+  class ToolError < Error; end
+  class ExtractionError < Error; end
+  class WorkflowError < Error; end
+end

data/lib/omnibot/result.rb

@@ -0,0 +1,8 @@
+module Omnibot
+  Usage          = Struct.new(:input_tokens, :output_tokens)
+  ToolCallRecord = Struct.new(:name, :arguments)
+
+  Result = Struct.new(:text, :tool_calls, :usage, :messages, :fast_path, keyword_init: true) do
+    def fast_path? = !!fast_path
+  end
+end

data/lib/omnibot/testing.rb

@@ -0,0 +1,118 @@
+module Omnibot
+  module Testing
+    FakeTokens   = Struct.new(:input, :output)
+    FakeMessage  = Struct.new(:content, :tokens)
+    FakeToolCall = Struct.new(:name, :arguments)
+
+    class << self
+      def fake!
+        @original_factory ||= Omnibot.chat_factory
+        Omnibot.chat_factory = ->(model:, agent_class: nil, **) {
+          FakeChat.new(agent_class: agent_class)
+        }
+      end
+
+      def reset!
+        Omnibot.chat_factory = @original_factory if @original_factory
+        @original_factory = nil
+        scripts.clear
+      end
+
+      def scripts = @scripts ||= {}
+      def script_for(agent_class) = scripts[agent_class] ||= []
+    end
+
+    class StubBuilder
+      def initialize(agent_class) = @script = Testing.script_for(agent_class)
+
+      def to_call_tool(name, **args)
+        @script << [:tool, name.to_s, args]
+        self
+      end
+
+      def then_reply(text)
+        @script << [:reply, text]
+        self
+      end
+
+      def then_extract(hash)
+        @script << [:reply, hash]
+        self
+      end
+    end
+
+    module Helpers
+      def stub_agent(agent_class) = StubBuilder.new(agent_class)
+    end
+
+    class FakeChat
+      attr_reader :messages, :tool_results
+
+      def initialize(agent_class: nil)
+        @agent_class = agent_class
+        @messages = []
+        @tools = []
+        @before_tool_call_hooks = []
+        @tool_results = []
+      end
+
+      def with_instructions(text, **)
+        @messages << { role: :system, content: text }
+        self
+      end
+
+      def with_tools(*tools, replace: false)
+        @tools = [] if replace
+        @tools.concat(tools)
+        self
+      end
+
+      def add_message(role:, content:)
+        @messages << { role: role, content: content }
+        self
+      end
+
+      def before_tool_call(&blk)
+        @before_tool_call_hooks << blk
+        self
+      end
+
+      def with_schema(schema)
+        @schema = schema
+        self
+      end
+
+      def ask(message, &stream_block)
+        @messages << { role: :user, content: message }
+        script = Testing.script_for(@agent_class)
+
+        while (step = script.shift)
+          kind, a, b = step
+          case kind
+          when :tool
+            tool_call = FakeToolCall.new(a, b)
+            @before_tool_call_hooks.each { |h| h.call(tool_call) }
+            tool = @tools.find { |t| t.name.to_s == a }
+            raise Omnibot::Error, "FakeChat: no tool #{a.inspect} attached" unless tool
+            @tool_results << tool.execute(**b)
+          when :reply
+            return emit_reply(a, stream_block)
+          end
+        end
+
+        emit_reply("(fake) #{message}", stream_block)
+      end
+
+      private
+
+      def emit_reply(text, stream_block)
+        if stream_block && text.is_a?(String)
+          text.split(/(?<= )/).each { |chunk| stream_block.call(FakeMessage.new(chunk, nil)) }
+        end
+        msg = FakeMessage.new(text, FakeTokens.new(10, 10))
+        @messages << { role: :assistant, content: text }
+        msg
+      end
+    end
+  end
+end

data/lib/omnibot/tool.rb

@@ -0,0 +1,48 @@
+module Omnibot
+  class Tool < RubyLLM::Tool
+    attr_reader :context
+
+    def initialize(context = {})
+      super()
+      @context = context
+    end
+
+    # Wrap every subclass's #execute with error capture + instrumentation.
+    def self.inherited(subclass)
+      super
+      subclass.prepend(SafeExecute) unless subclass.ancestors.include?(SafeExecute)
+    end
+
+    def self.from_block(name_sym, description_str, &block)
+      Class.new(self) do
+        description(description_str)
+        define_method(:execute, &block)
+        define_method(:name) { name_sym.to_s }
+        # Declare params from the block's own signature: SafeExecute shadows
+        # #execute with (**kwargs), so ruby_llm's signature inference sees no
+        # keywords and would emit an empty schema.
+        block.parameters.each do |kind, pname|
+          param(pname) if kind == :keyreq
+          param(pname, required: false) if kind == :key
+        end
+      end
+    end
+
+    # NOTE: this wrapper shadows execute's signature (method(:execute).parameters
+    # becomes [[:keyrest, :kwargs]]), so ruby_llm signature inference cannot be
+    # relied on — class-form tools must declare `param` explicitly.
+    module SafeExecute
+      def execute(**kwargs)
+        ActiveSupport::Notifications.instrument(
+          "omnibot.tool.call", tool: self.class, name: name, args: kwargs
+        ) do |payload|
+          super
+        rescue StandardError => e
+          payload[:error] = e.message
+          raise Omnibot::ToolError, e.message if Omnibot.config.on_tool_error == :raise
+          { error: e.message }
+        end
+      end
+    end
+  end
+end

data/lib/omnibot/version.rb

@@ -0,0 +1,3 @@
+module Omnibot
+  VERSION = "0.1.0"
+end

data/lib/omnibot.rb

@@ -0,0 +1,13 @@
+require "json"
+require "active_support"
+require "active_support/core_ext"
+require "active_support/notifications"
+require "ruby_llm"
+
+require_relative "omnibot/version"
+require_relative "omnibot/errors"
+require_relative "omnibot/config"
+require_relative "omnibot/tool"
+require_relative "omnibot/result"
+require_relative "omnibot/agent"
+require_relative "omnibot/testing"

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: omnibot-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Johannes Dwicahyo
+bindir: bin
+cert_chain: []
+date: 1980-01-02 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.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+description: 'Agent framework for Rails: bounded tool-calling loops, fast paths, structured
+  extraction, and (v0.2) durable workflows on ActiveRecord. Built on ruby_llm.'
+email:
+- johannesdwicahyo@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/generators/omnibot/agent/agent_generator.rb
+- lib/generators/omnibot/agent/templates/agent.rb.tt
+- lib/generators/omnibot/agent/templates/agent_spec.rb.tt
+- lib/generators/omnibot/install/install_generator.rb
+- lib/generators/omnibot/install/templates/initializer.rb.tt
+- lib/omnibot.rb
+- lib/omnibot/agent.rb
+- lib/omnibot/config.rb
+- lib/omnibot/errors.rb
+- lib/omnibot/result.rb
+- lib/omnibot/testing.rb
+- lib/omnibot/tool.rb
+- lib/omnibot/version.rb
+homepage: https://github.com/johannesdwicahyo/omnibot-ruby
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/johannesdwicahyo/omnibot-ruby
+  rubygems_mfa_required: 'true'
+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: '0'
+requirements: []
+rubygems_version: 4.0.13
+specification_version: 4
+summary: Rails-first LLM agents for Ruby
+test_files: []