omni_agent 0.1.11 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc288d35e0b6c6e5e4ea763c36d05aa37ee95d20aeb2f4b1369e15a6ba22bc92
-  data.tar.gz: 428b4d96e1b1f7ad2bf1f7cd2c99893333c0eac59d2add9a94faf18198376baa
+  metadata.gz: 619f71e19ebcd85894c197fa69aa6603f9c21eededca2c249e0a6ac3ceaa38a9
+  data.tar.gz: dcb21d896ea82f2127fe793d58668ea2e95162a3b77f12bee110ff9091d1aa96
 SHA512:
-  metadata.gz: 9c55eaf9a31782bb1c16c152d15627943cef09f5a179c6039590b412dba505196aae36ed325905992bd26df567c74553a83fec629c59062c2cfa5d4981a03bf4
-  data.tar.gz: 904fdc44a855a5b7cfe66817cd531cc86bd44d5a8f8bccd6b97c6bf3d313a4b4e4a7a2f18fb18305bf5ae5be4bca7424562c1e39f77ecbb12ee63bea4d00fcf3
+  metadata.gz: c92ffa2cc815d03ba69a6033cac9f96bfadc95725f926de704df33a31d7651f4afd586342dff02987ba86736ad52a08314308f4875ff68a18f98a4ae474c92a3
+  data.tar.gz: 00a41896240d9ef66e1cf739ae0bc693a424138fe47073ab0937a853067b274292d41ff21a193f2e5a78258d5c21977faa50fd9125a93136d6c00984e3d1ab8a

data/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.2.0](https://github.com/ACR1209/omni_agent/compare/omni_agent/v0.1.11...omni_agent/v0.2.0) (2026-10-29)
+
+
+### ⚠ BREAKING CHANGES
+
+* **agent:** agent subclasses now inherit their parent's class-level settings: `provider`/model, `options`, tags, `before_generation`/ `after_generation` callbacks, tools, delegated tools and `output`. Apps with agent hierarchies (e.g. an `ApplicationAgent` base class) will pick up the parent's settings in every subclass.
+
+### Features
+
+* add OmniAgent.embed with configurable embedding provider and model ([19214df](https://github.com/ACR1209/omni_agent/commit/19214df320c33b60559ce4eca9e65d77aedbafb8))
+* **agent:** add searches macro for semantic search tools ([764a756](https://github.com/ACR1209/omni_agent/commit/764a7568cc23c47bf42cea8719757d01fc8a3dbd))
+* **agent:** add structured output and stock agents scaffold ([c23fb4a](https://github.com/ACR1209/omni_agent/commit/c23fb4a89f30dbb55916ce886deafafd65d7dba8))
+* **agent:** address review feedback on structured output and inheritance ([143ce4b](https://github.com/ACR1209/omni_agent/commit/143ce4b5668edab2c06ed65071fd208846fd7457))
+* **agent:** search has_chunks models with searches ([b794bb2](https://github.com/ACR1209/omni_agent/commit/b794bb2d1ef0cb94f45dfec674cf3670828987b7))
+* **chunkable:** add has_chunks to chunk, embed and store documents ([414504b](https://github.com/ACR1209/omni_agent/commit/414504b3e5a26b7868a2fa1da938d48dd635518c))
+* **chunkers:** add recursive, markdown and hierarchical chunkers ([2f8a97d](https://github.com/ACR1209/omni_agent/commit/2f8a97d8b9cc7016092a0233882960fff9f9270c))
+* **docs:** bundle plain-Markdown docs in the gem for coding agents ([3cf1270](https://github.com/ACR1209/omni_agent/commit/3cf12705bef39064680463dc088322969de50518))
+* **embeddable:** add has_embedding macro for ActiveRecord models ([32d716d](https://github.com/ACR1209/omni_agent/commit/32d716dded4e9820f841a6c89fa59b9a04281bc4))
+* **embeddable:** configure embed job options globally and per model ([f4dcb39](https://github.com/ACR1209/omni_agent/commit/f4dcb39850fe53e5b80a408f548ae4b8cdea3bb4))
+* **generators:** add omni_agent:chunks to set up a chunk model ([ad60360](https://github.com/ACR1209/omni_agent/commit/ad60360f630c33eae6d32f9d2acdd3b246caad45))
+* **generators:** add omni_agent:embeddings generator ([5af765b](https://github.com/ACR1209/omni_agent/commit/5af765b454975b23f85903558d1832ba34ec32aa))
+* **generators:** write a commented initializer in omni_agent:install ([c0f22aa](https://github.com/ACR1209/omni_agent/commit/c0f22aabe3affc4e17e60548288fa855cb968764))
+* **loaders:** read PDF, HTML, Markdown and text documents with auto-detection ([c294323](https://github.com/ACR1209/omni_agent/commit/c2943237772e44983fa3bc62bb669d256ba2b4a3))
+* **providers:** add embed for text embeddings ([519f169](https://github.com/ACR1209/omni_agent/commit/519f16968896c8f0580591e2e7af6b93e26df3ae))
+* **stock_agents:** add OCR stock agent with image and PDF input ([b2683f3](https://github.com/ACR1209/omni_agent/commit/b2683f3532772e3d00a037e22d425164f8f785dd))
+* **tasks:** add omni_agent:embeddings:backfill rake task ([2aa06f7](https://github.com/ACR1209/omni_agent/commit/2aa06f7c24895caa2eb1b7ce8a1493f783e0ffe9))
+
+
+### Bug Fixes
+
+* **agent:** separate search results with a rule ([bd018cc](https://github.com/ACR1209/omni_agent/commit/bd018cc09626dcfcde524fccdbcbc2fc8222052e))
+* **chunkable:** lock the document while replacing its chunks ([5e695e6](https://github.com/ACR1209/omni_agent/commit/5e695e63384e57afbbd96571bbf59bd633a0bda7))
+* **chunkable:** skip unreadable documents in ingest_all ([9b6b68d](https://github.com/ACR1209/omni_agent/commit/9b6b68dab3cb8686d3da7c46c0c4032015b2d4d7))
+* **chunkers:** skip Markdown headings with nothing under them ([e228627](https://github.com/ACR1209/omni_agent/commit/e228627ac450902f33064f4dc1bd25c589b1f5bb))
+* **embeddable:** discard embed jobs for deleted records ([1b69efc](https://github.com/ACR1209/omni_agent/commit/1b69efcba25e26419ffadaa9721f0c888b9a856a))
+* **embeddable:** explain how to enable ActiveJob for later: true ([7f46446](https://github.com/ACR1209/omni_agent/commit/7f46446d993f036b4fa27fbb21035b65ae7bbae3))
+* **engine:** load ActiveJob with the engine ([1392629](https://github.com/ACR1209/omni_agent/commit/1392629e4892a5f6ed1c38b5a2eb34cdddda7e00))
+* **engine:** remove unused plugin scaffolding ([fa97033](https://github.com/ACR1209/omni_agent/commit/fa97033a96a7bff2ce4d4355008766d7fed7df89))
+* **generators:** explain connection errors when detecting MariaDB ([a13a770](https://github.com/ACR1209/omni_agent/commit/a13a770ba607905fad8ee4d21fb168ed91b75429))
+* **generators:** number migrations after the newest one ([01683a9](https://github.com/ACR1209/omni_agent/commit/01683a9e4efa7d05ea05e590615392ae78545180))
+* **loaders:** drop scripts and styles anywhere in HTML ([972fa94](https://github.com/ACR1209/omni_agent/commit/972fa944fd224ace1c909ccbd1c4a57d254a81f7))
+* **providers:** pass content-part arrays through to OpenAI ([22a5354](https://github.com/ACR1209/omni_agent/commit/22a535464b8053365a9fe4b8f1f850768e5a6472))
+
 ## [0.1.11](https://github.com/ACR1209/omni_agent/compare/omni_agent/v0.1.10...omni_agent/v0.1.11) (2026-10-15)
 
 

data/README.md

@@ -8,10 +8,13 @@ tool schemas, and generation lifecycle callbacks.
 
 - `OmniAgent::Agent` runtime with provider abstraction and tool-calling loop
 - `OmniAgent::Tool` DSL with JSON-schema-style input definitions
+- Structured, validated agent output declared with the same DSL as tool input
+- Stock agents: ready-made agents shipped with the gem that projects subclass and customize
 - Prompt composition from ERB files in `app/agents/<agent_name>/`
 - Agent callbacks (`before_generation`, `after_generation`)
 - Agent and tool tags to support filtering strategies
 - OpenAI provider integration out of the box, plus an Ollama provider for local models
+- RAG: `has_embedding` models, `has_chunks` documents (PDF, Markdown, HTML) and `searches` tools over pgvector, sqlite-vec, MariaDB or Meilisearch
 - MCP server support: expose tools and whole agents to Claude Code, Claude Desktop, Cursor and other MCP clients
 - Rake tasks and Rails generators for scaffolding
 
@@ -38,12 +41,14 @@ bundle install
 
 ## Quick Start
 
-1. Install base directories:
+1. Install base directories and the initializer:
 
 ```bash
 bundle exec rails generate omni_agent:install
 ```
 
+This also adds an OmniAgent section to `AGENTS.md` (and `CLAUDE.md`, if present) that points coding agents at the bundled docs. Pass `--skip-agents-md` to leave those files alone.
+
 2. Generate an agent scaffold:
 
 ```bash
@@ -108,6 +113,48 @@ module ResearchAgent::Tools
 end
 ```
 
+## Structured Output
+
+Declare an `output` block, using the same DSL as tool `input`, to get a validated object back instead of free text:
+
+```ruby
+class InvoiceAgent < OmniAgent::Agent
+	output do
+		string :invoice_number
+		number :total, min: 0
+		enum :currency, values: %w[USD EUR]
+	end
+end
+
+InvoiceAgent.new.run(invoice_text).structured_output
+# => { invoice_number: "A-1042", total: 120.5, currency: "USD" }
+```
+
+The schema is sent to the provider (as a `json_schema` `response_format` for OpenAI and Ollama), and the final answer is parsed and validated with the same rules as tool input. Invalid JSON or a schema mismatch raises `OmniAgent::StructuredOutputError`.
+
+## Stock Agents
+
+Stock agents are ready-made agents shipped with the gem under `OmniAgent::StockAgents`. Subclass one in your app and declare the output you need; the subclass keeps the stock prompt, model and tools:
+
+```bash
+rails generate omni_agent:stock_agent InvoiceOcr --from=ocr --fields=invoice_number:string total:number
+```
+
+```ruby
+class InvoiceOcr < OmniAgent::StockAgents::OCR
+	output do
+		string :invoice_number
+		number :total
+	end
+end
+
+InvoiceOcr.new.run([ Pathname("page1.jpg"), Pathname("page2.jpg") ]).structured_output
+```
+
+The OCR stock agent reads images and PDFs from paths, uploaded files, ActiveStorage attachments or URLs, one at a time or several pages together.
+
+To add a stock agent to the gem itself, run `bin/rake "stock_agent:new[name]"` from the gem repository.
+
 ## Multi-Agent Delegation
 
 `delegate_to` turns an agent into a supervisor: it wraps another agent class as a tool, so the supervisor's LLM can decide when to hand off to it. The delegated agent is a normal, independently defined agent (e.g. `app/agents/research_agent.rb`) — no manual tool file needed.
@@ -157,6 +204,41 @@ end
 
 `.stream` must come before the call (`.stream.run(...)`, not `.run(...).stream`) — without it, or without a block, behavior is unchanged and the same `Response` is returned either way. Only the `openai`, `ollama`, and `mock` providers stream today. See [Streaming Responses](omniagent-docs/docs/agent/streaming.mdx) for the full event reference.
 
+## RAG
+
+Make a model searchable and give an agent a search tool for it:
+
+```bash
+rails generate omni_agent:embeddings Document title content   # migration + has_embedding
+bin/rails db:migrate
+bin/rails "omni_agent:embeddings:backfill[Document]"
+```
+
+```ruby
+class Document < ApplicationRecord
+	has_embedding :title, :content   # embedded on save via OmniAgent.embed
+end
+
+class SupportAgent < OmniAgent::Agent
+	searches Document, scope: ->(context) { where(account_id: context[:account_id]) }
+end
+```
+
+Vectors are stored with [neighbor](https://github.com/ankane/neighbor) on Postgres (pgvector), SQLite (sqlite-vec) or MariaDB. Models using meilisearch-rails work with `searches` as they are, and so does any object with a `semantic_search(query, limit:)` method. For files and long text, `has_chunks` splits them into searchable chunks:
+
+```bash
+rails generate omni_agent:chunks Document file   # DocumentChunk model + has_chunks
+```
+
+```ruby
+class Document < ApplicationRecord
+	has_one_attached :file
+	has_chunks :file   # PDF, Markdown, HTML or text, detected per file
+end
+```
+
+See [RAG](omniagent-docs/docs/rag.mdx) for the options, loaders, chunkers, Meilisearch setup and embedding configuration.
+
 ## Evals
 
 `OmniAgent::Eval` lets you test agent quality: deterministic assertions (tool calls, output matching) and pluggable LLM-as-judge scoring.
@@ -292,7 +374,7 @@ Tools can declare MCP-only hints with `title "Get weather"` and `annotations rea
 
 ## Configuration
 
-Global defaults can be configured through `OmniAgent.configure`:
+`rails generate omni_agent:install` writes `config/initializers/omni_agent.rb` with every setting commented out at its default. Global defaults are set through `OmniAgent.configure`:
 
 ```ruby
 OmniAgent.configure do |config|
@@ -301,6 +383,18 @@ OmniAgent.configure do |config|
 end
 ```
 
+## Documentation for Coding Agents
+
+The full documentation from https://omniagent.activetaskers.com/docs/intro ships inside the gem as plain Markdown in `docs/`, so coding agents (Claude Code, Cursor, Codex...) working in your app can read it offline:
+
+```bash
+bundle exec omni_agent docs                     # index: conventions, typical flows and every page
+bundle exec omni_agent docs mcp/authentication  # one page
+bundle exec omni_agent docs --path              # directory holding the Markdown files
+```
+
+`docs/` is generated from `omniagent-docs/docs` by `bundle exec rake docs:sync`, which `rake build` runs first. It isn't committed, so a gem installed from git (`gem "omni_agent", github: ...`) doesn't include it; use the docs site instead.
+
 ## Running Tests
 
 ```bash

data/Rakefile

@@ -13,6 +13,10 @@ require "bundler/gem_tasks"
 Rake::Task["release"].clear
 task release: [ "build", "release:rubygem_push" ]
 
+# docs/ is generated from omniagent-docs/ (see rakelib/docs.rake) and not
+# committed, but the gemspec packages it, so generate it before every build.
+task build: "docs:sync"
+
 RSpec::Core::RakeTask.new(:spec)
 
 task default: :spec

data/app/jobs/omni_agent/embed_job.rb

@@ -0,0 +1,10 @@
+module OmniAgent
+  class EmbedJob < ActiveJob::Base
+    # The record was deleted before the job ran; there's nothing to embed.
+    discard_on ActiveJob::DeserializationError
+
+    def perform(record)
+      record.embed!
+    end
+  end
+end

data/app/jobs/omni_agent/ingest_job.rb

@@ -0,0 +1,12 @@
+module OmniAgent
+  class IngestJob < ActiveJob::Base
+    # The record was deleted before or while the job ran; there's nothing to ingest.
+    discard_on ActiveJob::DeserializationError, ActiveRecord::RecordNotFound
+    # No loader can read the file, so retrying won't help.
+    discard_on OmniAgent::UnsupportedDocumentError
+
+    def perform(record)
+      record.ingest!
+    end
+  end
+end

data/docs/agent/callbacks.md

@@ -0,0 +1,60 @@
+<!-- Generated from omniagent-docs/docs/agent/callbacks.mdx by `bundle exec rake docs:sync`. Do not edit by hand. -->
+<!-- Online version: https://omniagent.activetaskers.com/docs/agent/callbacks -->
+
+# Generation Callbacks
+
+Agents support `before_generation` and `after_generation` callbacks, letting you hook into the lifecycle of a single `run` without overriding it yourself.
+
+## Before Generation
+
+Runs before any provider call is made — useful for setting up instance variables that your prompt template needs.
+
+```ruby
+class ResearchAgent < OmniAgent::Agent
+  use_model "gpt-4o-mini"
+
+  before_generation :set_current_user
+
+  def set_current_user
+    @user = "Test User"
+  end
+end
+```
+
+Any instance variable you set here is automatically available inside `prompt.md.erb` via ERB interpolation.
+
+## After Generation
+
+Runs once the agent has a final response (no more tool calls to make, or a tool explicitly stopped generation).
+
+```ruby
+class ResearchAgent < OmniAgent::Agent
+  after_generation :log_response
+
+  def log_response(payload)
+    Rails.logger.info("Response: #{payload[:response].content}")
+  end
+end
+```
+
+Callback methods can take zero arguments or one. If they accept an argument, they receive a payload hash:
+
+| Key | Before generation | After generation |
+|---|---|---|
+| `input` | ✓ | ✓ |
+| `context` | ✓ | ✓ |
+| `messages` | ✓ | ✓ |
+| `generated_messages` | | ✓ |
+| `response` | | ✓ |
+
+## Multiple Callbacks
+
+Both directives accept multiple method names and are additive across calls — calling `before_generation` again appends rather than replacing:
+
+```ruby
+before_generation :set_current_user, :load_preferences
+```
+
+## Context Binding
+
+Instance variables you set inside a callback (or anywhere in the agent) are synced back into the run's `context` hash after each callback finishes, so later callbacks and the prompt template see the latest values.

data/docs/agent/delegation.md

@@ -0,0 +1,56 @@
+<!-- Generated from omniagent-docs/docs/agent/delegation.mdx by `bundle exec rake docs:sync`. Do not edit by hand. -->
+<!-- Online version: https://omniagent.activetaskers.com/docs/agent/delegation -->
+
+# Multi-Agent Delegation
+
+`delegate_to` wraps another agent as a tool your agent's LLM can call, turning your agent into a **supervisor** that routes work to sub-agents. The delegated agent is defined and used like any other agent — a normal class under `app/agents/`, not a manual tool file.
+
+```ruby
+class SupervisorAgent < OmniAgent::Agent
+  use_model "gpt-4o"
+
+  delegate_to ResearchAgent, as: :research,  description: "Look up factual info"
+  delegate_to MathAgent,     as: :calculate, description: "Do arithmetic"
+end
+```
+
+The model decides when (and whether) to call `research` or `calculate` based on the conversation, exactly like any other tool call. Each delegated agent runs its own `run` loop — including its own tool calls, if it has any — and returns its final answer as the tool result.
+
+* **`agent_class`**: Any `OmniAgent::Agent` subclass.
+* **`as:`**: Name exposed to the model as the tool/function name (e.g. `:research` → `Research`).
+* **`description:`**: Sent to the provider so the model knows when to delegate. Defaults to `"Delegate to <AgentClass>."`.
+
+## Choosing a Run Entrypoint
+
+By default, delegation calls the sub-agent's plain `#run`. Pass `run_alias:` to call a `run_aliases` method (or any zero-arg [run entrypoint](run-entrypoints.md)) instead — useful when the sub-agent should render a different prompt file for delegated calls:
+
+```ruby
+class SupervisorAgent < OmniAgent::Agent
+  delegate_to SupportAgent, as: :triage_ticket, run_alias: :triage
+end
+```
+
+## Forwarding Context
+
+Delegated agents run **isolated** by default — they get only the `input` string, none of the supervisor's context. Pass `forward:` to share part or all of it:
+
+```ruby
+class SupervisorAgent < OmniAgent::Agent
+  delegate_to ResearchAgent, as: :research,  forward: [ :user, :locale ]
+  delegate_to MathAgent,     as: :calculate, forward: true
+end
+```
+
+* **`forward: [:key, ...]`**: Only the listed context keys are passed to the sub-agent's `context:`.
+* **`forward: true`**: The entire context hash is forwarded.
+* **`forward: []`** (default): The sub-agent runs with an empty context.
+
+## Guarding Against Runaway Delegation
+
+Since a delegated agent could itself delegate (directly or through a chain of other agents), delegation depth is capped by `OmniAgent.configuration.max_delegation_depth` (default `5`). Exceeding it raises `OmniAgent::MaxDelegationDepthError` instead of recursing forever. Raise the limit in your initializer if you have legitimately deep delegation chains:
+
+```ruby
+OmniAgent.configure do |config|
+  config.max_delegation_depth = 8
+end
+```

data/docs/agent/provider.md

@@ -0,0 +1,93 @@
+<!-- Generated from omniagent-docs/docs/agent/provider.mdx by `bundle exec rake docs:sync`. Do not edit by hand. -->
+<!-- Online version: https://omniagent.activetaskers.com/docs/agent/provider -->
+
+# Change an Agent's Provider or Model
+
+By default, agents use the configured `default_provider` and `default_model`. You can override these settings on a per-agent basis using one of the following DSL directives.
+
+## Change Provider and Model
+
+Use `provider` when you want to change the provider and optionally specify a model.
+
+```ruby
+provider :openai, model: 'gpt-5.4'
+```
+
+You can also change only the provider and let it use that provider's default model:
+
+```ruby
+provider :openai
+```
+
+To run against a local model via [Ollama](../supported-providers.md#ollama) instead:
+
+```ruby
+provider :ollama, model: 'llama3.1'
+```
+
+## Change Only the Model
+
+Use `use_model` when you want to keep the current `default_provider` and only override the model.
+
+```ruby
+use_model 'gpt-5.4'
+```
+
+## Important
+
+`provider` and `use_model` are mutually exclusive within the same agent definition. You must choose **one** of the following approaches:
+
+* Change the provider (and optionally the model) with `provider`
+* Keep the default provider and change only the model with `use_model`
+
+### Valid:
+
+```ruby
+provider :openai, model: 'gpt-5.4'
+```
+
+```ruby
+provider :anthropic
+```
+
+```ruby
+use_model 'gpt-5.4'
+```
+
+### Invalid:
+
+```ruby
+provider :openai, model: 'gpt-5.4'
+use_model 'gpt-5.5'
+```
+
+The example above is not allowed because both directives are defined in the same agent.
+
+> **Note:** An agent can either override its provider using `provider` or override its model using `use_model`, but it cannot use both directives simultaneously.
+
+## Inheritance
+
+Subclasses inherit their parent agent's `provider`, model, `options`, tags, callbacks, tools and `output`, and can override any of them:
+
+```ruby
+class ApplicationAgent < OmniAgent::Agent
+  provider :openai, model: "gpt-4o"
+  options temperature: 0.2
+end
+
+class SupportAgent < ApplicationAgent
+  options max_tokens: 500 # merged: { temperature: 0.2, max_tokens: 500 }
+end
+```
+
+A subclass may call `use_model` even if its parent called `provider`. As on its own, `use_model` means "default provider + this model", so the subclass does not keep the parent's provider:
+
+```ruby
+class LocalSupportAgent < ApplicationAgent
+  use_model "llama3.1" # uses OmniAgent.configuration.default_provider, not :openai
+end
+```
+
+To keep the parent's provider and only change the model, repeat it: `provider :openai, model: "gpt-4o-mini"`.
+
+A tool in the subclass replaces a parent tool with the same name (for example `SupportAgent::Tools::Lookup` replaces `ApplicationAgent::Tools::Lookup`), and the same applies to `delegate_to ..., as:` names.

data/docs/agent/run-entrypoints.md

@@ -0,0 +1,81 @@
+<!-- Generated from omniagent-docs/docs/agent/run-entrypoints.mdx by `bundle exec rake docs:sync`. Do not edit by hand. -->
+<!-- Online version: https://omniagent.activetaskers.com/docs/agent/run-entrypoints -->
+
+# Run Entrypoints
+
+`OmniAgent::Agent` always exposes the low-level `run` method, but you'll usually call an agent through one of its higher-level entrypoints.
+
+## Implicit Entrypoints
+
+Any zero-argument instance method you define on an agent automatically becomes a runnable entrypoint:
+
+```ruby
+class ResearchAgent < OmniAgent::Agent
+  use_model "gpt-4o-mini"
+
+  def summarize
+    @message = "Summarize the latest market trends."
+  end
+end
+```
+
+Calling `ResearchAgent.new.summarize` with no arguments runs your method body and uses its return value (or `@message`, if set) as the input sent to the model. Calling it **with** arguments instead runs the agent directly:
+
+```ruby
+ResearchAgent.new.summarize                      # runs `summarize`, then calls the model
+ResearchAgent.new.summarize("Custom input")       # skips to `run` with this input
+ResearchAgent.new.summarize(context: { history: [...] })
+```
+
+This is handled by `method_added`, so it works for any method you define — no extra declaration needed. It also means the prompt file used is named after the calling method: defining `summarize` will look for `app/agents/research_agent/summarize.md.erb` in addition to the base `prompt.md.erb`.
+
+## Explicit Run Aliases
+
+If you'd rather declare entrypoints explicitly instead of relying on every zero-arg method, use `run_aliases`:
+
+```ruby
+class ResearchAgent < OmniAgent::Agent
+  run_aliases :ask, :follow_up
+end
+```
+
+This defines `ask` and `follow_up` as direct wrappers around `run`, each tagged with their own name as `prompt_method` (so they can pick up a matching `<method_name>.md.erb` prompt file).
+
+## Calling the Agent Directly
+
+The simplest way to run an agent is `.new.run(input)`:
+
+```ruby
+ResearchAgent.new.run("Hello!")
+```
+
+## Scoped Instances with `with`
+
+Use the class-level `with` helper to build a pre-configured instance without mutating the class itself:
+
+```ruby
+ResearchAgent.with(user_id: 42).run("What's new?")
+
+ResearchAgent.with(
+  provider_override: :mock,
+  model_override: "gpt-4.1-mini"
+).run("Test run")
+```
+
+`with` accepts:
+
+* **Context kwargs** (e.g. `user_id: 42`) — merged into every `run` call made on the returned instance.
+* **`provider_override`** / **`model_override`** — temporarily swap the provider or model for this instance only.
+* **`options_override`** — merged into the chat options sent to the provider.
+
+## Streaming
+
+Any of the entrypoints above can stream by prefixing the call with `.stream` and passing a block:
+
+```ruby
+ResearchAgent.with(user_id: 42).stream.run("What's new?") do |event|
+  print event.text if event.text?
+end
+```
+
+See [Streaming Responses](streaming.md) for the full event reference.

data/docs/agent/streaming.md

@@ -0,0 +1,62 @@
+<!-- Generated from omniagent-docs/docs/agent/streaming.mdx by `bundle exec rake docs:sync`. Do not edit by hand. -->
+<!-- Online version: https://omniagent.activetaskers.com/docs/agent/streaming -->
+
+# Streaming Responses
+
+Any run entrypoint — `run`, an implicit entrypoint, or a `run_aliases` method — can stream its response by prefixing the call with `.stream` and passing a block. Without `.stream` (or without a block), behavior is completely unchanged.
+
+```ruby
+agent.stream.run("Hello") do |event|
+  print event.text if event.text?
+end
+
+ResearchAgent.with(user_id: 42).stream.summarize("Latest trends") do |event|
+  # ...
+end
+```
+
+`.stream` must come **before** the call, not after — the LLM request happens synchronously inside `run`/the entrypoint, so there's nothing to stream once it returns. The call still returns the same `OmniAgent::Providers::Response` it always would; `.stream` only adds a side channel of events emitted while it runs.
+
+## Event Types
+
+Each yielded object is an `OmniAgent::Streaming::Event`:
+
+| Type | Predicate | Fields | When |
+| --- | --- | --- | --- |
+| `:text` | `text?` | `text` | A chunk of the assistant's response text |
+| `:tool_call` | `tool_call?` | `tool_name`, `tool_arguments`, `tool_id` | Right before a tool is invoked |
+| `:tool_result` | `tool_result?` | `tool_name`, `tool_id`, `content`, `error?` | Right after a tool finishes (or raises) |
+| `:done` | `done?` | `response` | Generation is complete; `response` is the final `Response` |
+
+A full tool-calling round looks like:
+
+```
+:text (any content before the tool call, if the model produced any)
+:tool_call
+:tool_result
+:text, :text, ...  (the final answer, streamed)
+:done
+```
+
+## Example: Chat UI
+
+```ruby
+TestAgent.with(user_id: 2).stream.user_query("Search and summarize") do |event|
+  case event.type
+  when :text
+    print event.text
+  when :tool_call
+    puts "\n[using #{event.tool_name}...]"
+  when :tool_result
+    puts "[#{event.error? ? "failed" : "done"}]"
+  when :done
+    puts "\n---"
+  end
+end
+```
+
+## Provider Support
+
+Streaming is implemented per-provider. The built-in `openai` provider streams via the `openai` gem's `client.chat.completions.stream` and emits `:text` events for content deltas; tool-call arguments are not streamed incrementally (a `:tool_call` event fires once the full round finishes and arguments are fully parsed — a tool can't be invoked from a partial JSON fragment). The `ollama` provider streams the same way, since it subclasses `openai` and only swaps the client's `base_url` and defaults. The `mock` provider also supports streaming, splitting its canned response into words, useful for testing UI code without a network call.
+
+Retries via `with_retries` wrap stream *creation* only — a connection drop mid-stream is not retried.