omni_agent 0.1.10 → 0.2.0

data/docs/agent/structured-output.md

@@ -0,0 +1,80 @@
+<!-- Generated from omniagent-docs/docs/agent/structured-output.mdx by `bundle exec rake docs:sync`. Do not edit by hand. -->
+<!-- Online version: https://omniagent.activetaskers.com/docs/agent/structured-output -->
+
+# Structured Output
+
+Declare an `output` block to make an agent return a validated object instead of free text. It uses the same DSL as a tool's [`input`](../tools.md#input-schema-dsl):
+
+```ruby
+class InvoiceAgent < OmniAgent::Agent
+  use_model "gpt-4o-mini"
+
+  output do
+    string :invoice_number, description: "Invoice identifier as printed"
+    number :total, min: 0
+    enum :currency, values: %w[USD EUR]
+    array :line_items do
+      string :description
+      number :amount
+    end
+  end
+end
+
+response = InvoiceAgent.new.run(invoice_text)
+response.structured_output
+# => { invoice_number: "A-1042", total: 120.5, currency: "USD", line_items: [ { description: "Paper", amount: 120.5 } ] }
+response.answer # the raw JSON string returned by the model
+```
+
+## How It Works
+
+1. The schema is sent to the provider with every request. OpenAI and Ollama receive it as a `json_schema` `response_format`. Providers that don't support structured output natively get the schema in the system prompt instead (see [Custom Providers](#custom-providers)).
+2. When the model gives its final answer, the JSON is parsed (a surrounding ` ```json ` fence is tolerated) and validated with the same rules as tool input: required fields, `enum` values, `min`/`max`, `min_length`/`max_length`, `pattern`, `min_items`/`max_items` and custom `validate:` procs. On top of that, every top-level value must match its declared type (`string`, `integer`, `number`, `boolean`, `array` or `hash`), so `total: "120.5"` is rejected for a `number`. Keys not declared in the schema are dropped, and `null` for an optional field is treated as absent.
+3. The result is exposed as `response.structured_output`, a hash with symbol keys. It is set before `after_generation` callbacks run, so callbacks can read it from `payload[:response]`.
+
+Type and constraint checks apply to top-level fields; nested objects are described to the model but not validated field by field.
+
+## Handling Errors
+
+If the model returns invalid JSON, the object fails validation, or a polymorphic `resolve: true` field can't be resolved, `run` raises `OmniAgent::StructuredOutputError`. The error keeps the raw model output so you can log it, retry or repair it without paying for the generation again:
+
+```ruby
+begin
+  InvoiceAgent.new.run(invoice_text)
+rescue OmniAgent::StructuredOutputError => e
+  Rails.logger.warn("Invalid invoice output: #{e.message}\n#{e.content}")
+  e.response # the full OmniAgent::Providers::Response
+end
+```
+
+## Strict Mode
+
+OpenAI's strict structured outputs are enabled automatically when the schema allows it: every field is required, every `hash` has a block, and no `min_length`/`max_length` is used. Otherwise the schema is sent with `strict: false`, so the model only treats it as guidance; in that case the schema is also added to the system prompt, and OmniAgent's validation enforces it.
+
+## Custom Providers
+
+A provider receives the schema as the `output_schema:` keyword of `#chat` (an `OmniAgent::Schema`; call `#json_schema` on it) only when it declares support:
+
+```ruby
+class MyProvider < OmniAgent::Providers::Base
+  def supports_structured_output?
+    true
+  end
+
+  def chat(messages:, tools: [], stream: nil, output_schema: nil, **options)
+    # send output_schema.json_schema in the provider's own format
+  end
+end
+```
+
+Providers that don't (the default in `OmniAgent::Providers::Base`) never receive `output_schema:`; the agent appends the JSON schema to the system prompt and asks for a JSON-only answer instead.
+
+## Inheritance
+
+`output` is inherited by subclasses, and a subclass can declare its own `output` block to replace it. This is how [stock agents](../stock-agents/overview.md) let each project decide which fields to extract.
+
+## Mock Provider
+
+With `provider :mock`, an agent that declares `output` gets placeholder JSON built from the schema (the first `enum` value, `min` for numbers, lorem ipsum for strings), so you can wire up code that reads `structured_output` before calling a real model.
+
+The placeholders can't satisfy everything. If a field has a `pattern:` the lorem text doesn't match, a custom `validate:` proc that rejects the placeholder, or is a polymorphic field with `resolve: true`, the mock raises an `OmniAgent::Error` naming the field. In those tests, stub the provider's `#chat` response instead.

data/docs/configuration.md

@@ -0,0 +1,68 @@
+<!-- Generated from omniagent-docs/docs/configuration.mdx by `bundle exec rake docs:sync`. Do not edit by hand. -->
+<!-- Online version: https://omniagent.activetaskers.com/docs/configuration -->
+
+# Configuration
+
+Omni Agent ships with sensible defaults but lets you configure global behavior through an initializer.
+
+## Global Defaults
+
+`rails generate omni_agent:install` writes `config/initializers/omni_agent.rb` with every setting commented out at its default, so you only uncomment what you change. You can also create the file yourself:
+
+```ruby
+OmniAgent.configure do |config|
+  config.default_provider = :openai
+  config.default_model = "gpt-4o-mini"
+  config.max_retries = 3
+  config.retry_base_delay = 0.5
+  config.max_tool_iterations = 10
+  config.max_delegation_depth = 5
+  config.mcp_allowed_origins = []
+  config.mcp_max_request_bytes = 1_048_576
+  config.embedding_provider = nil
+  config.embedding_model = nil
+  config.embedding_job_options = {}
+  config.document_loaders = {}
+end
+```
+
+* **`default_provider`**: The provider used by agents that don't declare their own via `provider` or `use_model`. Defaults to `:openai`.
+* **`default_model`**: The model used when an agent doesn't override it. Defaults to `"gpt-4o-mini"`.
+* **`max_retries`**: Max retry attempts for retryable provider errors (rate limits, timeouts, 5xx). Defaults to `3`.
+* **`retry_base_delay`**: Base delay in seconds for retry backoff. Delay doubles per attempt (exponential backoff). Defaults to `0.5`.
+* **`max_tool_iterations`**: Max number of tool-call round trips the agent loop will perform before giving up on a final response. Defaults to `10`.
+* **`max_delegation_depth`**: Max nesting depth for [agent delegation](agent/delegation.md) chains before raising `OmniAgent::MaxDelegationDepthError`. Defaults to `5`.
+* **`mcp_allowed_origins`**: Browser origins (Strings or Regexps) allowed to call any [MCP server](mcp/authentication.md#origin-checks) over HTTP. Requests that send any other `Origin` get `403`. Defaults to `[]`.
+* **`mcp_max_request_bytes`**: Largest MCP HTTP request body accepted. Larger requests get `413`. Defaults to `1_048_576` (1 MiB).
+* **`embedding_provider`**: The provider [`OmniAgent.embed`](rag.md#embeddings) uses. Defaults to `nil`, which falls back to `default_provider`.
+* **`embedding_model`**: The embedding model `OmniAgent.embed` uses. Defaults to `nil`, which uses the provider's default (`text-embedding-3-small` for OpenAI, `nomic-embed-text` for Ollama).
+* **`embedding_job_options`**: ActiveJob `set` options (`queue`, `priority`, `wait`, `wait_until`) for the jobs [`has_embedding later:`](rag.md#background-embedding) and [`has_chunks`](rag.md#documents) enqueue. Models can override them with `later: { ... }`. Unknown keys raise an `ArgumentError`. Defaults to `{}`.
+* **`document_loaders`**: Extra [loaders](rag.md#loaders) for `has_chunks`, by name (`{ docx: DocxLoader }`). Loaders with a `handles?` method are tried before the built-in ones when detecting a file's format. Defaults to `{}`.
+
+## Retry Behavior
+
+Providers can mark specific errors as retryable (e.g. the OpenAI provider retries `RateLimitError`, `InternalServerError`, and `APIConnectionError`). When a retryable error occurs, the provider retries up to `max_retries` times with exponential backoff (`retry_base_delay * 2^(attempt - 1)`). Non-retryable errors raise immediately.
+
+## Tool Iteration Limit
+
+The agent loop keeps calling tools until the model returns a final response. If the model keeps requesting tools past `max_tool_iterations`, the agent raises `OmniAgent::MaxToolIterationsError`. Raise `max_tool_iterations` in your initializer if your agent legitimately needs more tool round trips.
+
+## Per-Agent Overrides
+
+Any agent can override these defaults individually. See [Change an Agent's Provider or Model](agent/provider.md) for the `provider` and `use_model` DSL.
+
+## Registered Providers
+
+Providers are resolved from a registry at runtime:
+
+```ruby
+OmniAgent::Providers.registry
+# => {
+#      openai: OmniAgent::Providers::OpenAI,
+#      ollama: OmniAgent::Providers::Ollama,
+#      mock: OmniAgent::Providers::Mock,
+#      mock_judge: OmniAgent::Providers::MockJudge
+#    }
+```
+
+See [Supported Providers](supported-providers.md) for provider-specific setup. The `:mock` provider is useful for tests — it returns a canned response without making network calls.

data/docs/evals/caching.md

@@ -0,0 +1,21 @@
+<!-- Generated from omniagent-docs/docs/evals/caching.mdx by `bundle exec rake docs:sync`. Do not edit by hand. -->
+<!-- Online version: https://omniagent.activetaskers.com/docs/evals/caching -->
+
+# Caching
+
+Eval runs are cached by default, keyed on `(agent class, run_alias, input, context)`, and stored as JSON at `OmniAgent.configuration.eval_cache_path` (default `tmp/omni_agent_eval_cache.json`). Re-running the same case — e.g. while iterating on assertions — replays the cached output instead of calling the provider again, so you don't spend tokens testing the same case twice.
+
+```ruby
+OmniAgent.configure do |config|
+  config.eval_cache_enabled = true # default
+  config.eval_cache_path = "tmp/omni_agent_eval_cache.json" # default
+end
+```
+
+To force a fresh call without deleting the file yourself, clear the cache before running with `--fresh`:
+
+```bash
+bundle exec omni_agent eval evals/research_agent_eval.rb --fresh
+```
+
+The equivalent rake task takes a `fresh` arg instead: `rake "omni_agent:eval[evals/research_agent_eval.rb,fresh]"`.

data/docs/evals/generating-and-running.md

@@ -0,0 +1,87 @@
+<!-- Generated from omniagent-docs/docs/evals/generating-and-running.mdx by `bundle exec rake docs:sync`. Do not edit by hand. -->
+<!-- Online version: https://omniagent.activetaskers.com/docs/evals/generating-and-running -->
+
+# Generating and Running Evals
+
+`OmniAgent::Eval` lets you test agent *quality*, not just correctness — deterministic assertions (tool calls, output matching) plus pluggable LLM-as-judge scoring.
+
+## Defining an Eval
+
+```ruby
+class ResearchAgentEval < OmniAgent::Eval
+  agent ResearchAgent
+
+  eval_case "answers weather question" do
+    input "What's the weather in Paris?"
+    expect_tool_call :get_weather, with: { city: "Paris" }
+    expect_output to_include: "Paris"
+  end
+
+  eval_case "is polite" do
+    input "Tell me a joke"
+    judge "Is the response friendly and on-topic?", threshold: 0.7
+  end
+
+  eval_case "summarizes via the :summarize run alias" do
+    run_alias :summarize
+    input "Some long article text...", with: { tone: "casual" }
+    expect_output to_include: "summary"
+  end
+end
+```
+
+* **`agent`**: The `OmniAgent::Agent` subclass under test.
+* **`eval_case`**: Declares one scenario. `input text, with: {}` sets the message sent to the agent; `with:` is forwarded as `context:` and bound to matching instance variables during the run (e.g. `with: { tone: "casual" }` sets `@tone`).
+* **`run_alias`**: Targets a method defined via `run_aliases` (or any zero-arg run entrypoint) instead of plain `#run`. Use this when that alias renders a different prompt file (`app/agents/<agent>/<method_name>.md.erb`) and you want to eval that specific prompt.
+* **`expect_tool_call`**: Asserts a tool was called, optionally with specific arguments (`with:`).
+* **`expect_output`**: Asserts on the agent's final text output via `to_include:`, `to_match:`, or a custom block.
+* **`judge`**: Sends the output to an LLM judge with a grading criterion — see [Judge Provider](judge-provider.md) for how it picks a provider/model.
+
+For testing many input/expected-output pairs without writing a `eval_case` per row, see [Golden Sets](golden-sets.md).
+
+## Generating
+
+```bash
+rails generate omni_agent:eval ResearchAgent
+```
+
+Creates `evals/research_agent_eval.rb` with a starter `eval_case`.
+
+## Running
+
+Run evals with the `omni_agent` CLI — works like running `rspec`:
+
+```bash
+# run every *_eval.rb under evals/
+bundle exec omni_agent eval
+
+# run just one eval file
+bundle exec omni_agent eval evals/research_agent_eval.rb
+
+# bypass the cache for this run (see Caching)
+bundle exec omni_agent eval evals/research_agent_eval.rb --fresh
+```
+
+Run it from your Rails app root — it requires `config/environment.rb` to boot, same as `bin/rails`.
+
+It prints a pass/fail report per case (with failure messages) and exits non-zero if any case failed:
+
+```text
+[PASS] mentions lorem
+[FAIL] mentions something the mock never says
+  - output "Lorem ipsum dolor sit amet, consectetur adipiscing elit." does not include "this never appears"
+
+1/2 cases passed
+```
+
+Running evals calls real LLM providers — it costs money and is non-deterministic, so it is **not** wired into `bundle exec rspec` or CI. Run it manually when you want a quality check.
+
+### Rake task alternative
+
+A `rake omni_agent:eval` task does the same thing, if you'd rather not use the binstub:
+
+```bash
+bundle exec rake omni_agent:eval
+bundle exec rake "omni_agent:eval[evals/research_agent_eval.rb]"
+bundle exec rake "omni_agent:eval[evals/research_agent_eval.rb,fresh]"
+```

data/docs/evals/golden-sets.md

@@ -0,0 +1,32 @@
+<!-- Generated from omniagent-docs/docs/evals/golden-sets.mdx by `bundle exec rake docs:sync`. Do not edit by hand. -->
+<!-- Online version: https://omniagent.activetaskers.com/docs/evals/golden-sets -->
+
+# Golden Sets
+
+For many input/expected-output pairs, load a dataset file instead of writing a `eval_case` per row:
+
+```ruby
+class ResearchAgentEval < OmniAgent::Eval
+  agent ResearchAgent
+
+  golden_set "evals/golden/research_agent.yml" do |row|
+    expect_output to_include: row[:expected_output]
+    expect_tool_call row[:tool_call][:name], with: row[:tool_call][:args]
+  end
+end
+```
+
+`evals/golden/research_agent.yml`:
+
+```yaml
+- name: "paris weather"
+  input: "What's the weather in Paris?"
+  expected_output: "Paris"
+  tool_call: { name: get_weather, args: { city: Paris } }
+- name: "tokyo weather"
+  input: "What's the weather in Tokyo?"
+  expected_output: "Tokyo"
+  tool_call: { name: get_weather, args: { city: Tokyo } }
+```
+
+Each row becomes its own `eval_case` (named from `name`, or `"row <index>"` if omitted). All keys are recursively symbolized, so nested fields like `row[:tool_call][:name]` work as shown above. Rows generated from `golden_set` run through the exact same path as inline `eval_case` blocks — there's no separate reporting for them, and they're subject to the same [caching](caching.md).

data/docs/evals/judge-provider.md

@@ -0,0 +1,20 @@
+<!-- Generated from omniagent-docs/docs/evals/judge-provider.mdx by `bundle exec rake docs:sync`. Do not edit by hand. -->
+<!-- Online version: https://omniagent.activetaskers.com/docs/evals/judge-provider -->
+
+# Judge Provider
+
+`judge` resolves which provider grades the output, in this order:
+
+1. An explicit `provider:` (and optional `model:`) kwarg passed to `judge`.
+2. `OmniAgent.configuration.eval_judge_provider` / `eval_judge_model`, set once globally:
+
+   ```ruby
+   OmniAgent.configure do |config|
+     config.eval_judge_provider = :openai
+     config.eval_judge_model = "gpt-4o-mini"
+   end
+   ```
+
+3. Falls back to the **same provider/model the agent under test already uses** — no judge setup required to get started.
+
+The judge sends a fixed grading prompt asking for `{"score": 0-1, "reason": "..."}` and compares `score` against `threshold` from the `judge` call (see [Generating and Running Evals](generating-and-running.md)).

data/docs/generators.md

@@ -0,0 +1,143 @@
+<!-- Generated from omniagent-docs/docs/generators.mdx by `bundle exec rake docs:sync`. Do not edit by hand. -->
+<!-- Online version: https://omniagent.activetaskers.com/docs/generators -->
+
+# Generators
+
+Omni Agent ships seven Rails generators to scaffold your project.
+
+## Install Generator
+
+```bash
+rails generate omni_agent:install
+```
+
+Creates the `app/agents` root directory and `config/initializers/omni_agent.rb`, which lists every [configuration](configuration.md) setting commented out at its default. An existing initializer is left untouched. Run this once per application, right after installing the gem.
+
+It also adds an OmniAgent section to `AGENTS.md` (created if missing) and to `CLAUDE.md` (only if it already exists). The section tells coding agents such as Claude Code, Cursor or Codex to read the documentation bundled with the gem:
+
+```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
+```
+
+Running the generator again doesn't duplicate the section. Pass `--skip-agents-md` to leave both files alone.
+
+## Agent Generator
+
+```bash
+rails generate omni_agent:agent ResearchAgent --model gpt-4o-mini --with-tools WeatherLookup Summarize
+```
+
+Generates:
+
+```text
+app/agents/
+├── research_agent.rb
+└── research_agent/
+    ├── prompt.md.erb
+    └── tools/
+        ├── weather_lookup.rb
+        └── summarize.rb
+```
+
+### Options
+
+* **`--model`**: Sets the model used in the generated `use_model` call. If omitted, the agent uses `OmniAgent.configuration.default_model`.
+* **`--with-tools`**: Space-separated list of tool names to scaffold under `tools/`. Each is generated as a subclass of `OmniAgent::Tool` with an example `input` schema and `execute` method. If you pass `--with-tools` with no names, an `ExampleTool` is generated.
+
+```bash
+rails generate omni_agent:agent SupportAgent --with-tools
+```
+
+## Stock Agent Generator
+
+```bash
+rails generate omni_agent:stock_agent InvoiceOcr --from=ocr --fields=invoice_number:string total:number
+```
+
+Generates `app/agents/invoice_ocr.rb`, a subclass of the chosen [stock agent](stock-agents/overview.md) with an `output` block, and an optional `app/agents/invoice_ocr/prompt.md.erb` for extra instructions.
+
+### Options
+
+* **`--from`** (required): Stock agent to build on, by its `stock_name` (see `OmniAgent::StockAgents.all`).
+* **`--fields`**: Space-separated `name:type` output fields (`string`, `integer`, `number` or `boolean`). If omitted, an `example_field` is generated. Use the full [structured output DSL](agent/structured-output.md) in the generated file for enums, nested objects or optional fields.
+
+## Eval Generator
+
+```bash
+rails generate omni_agent:eval ResearchAgent
+```
+
+Generates `evals/research_agent_eval.rb` with a starter `eval_case` for `ResearchAgent`. See [Generating and Running Evals](evals/generating-and-running.md), [Golden Sets](evals/golden-sets.md), [Judge Provider](evals/judge-provider.md), and [Caching](evals/caching.md).
+
+## MCP Server Generator
+
+```bash
+rails generate omni_agent:mcp_server Support --with-tools LookupOrder RefundOrder --agents SupportAgent
+```
+
+Generates:
+
+```text
+app/mcp_servers/
+├── support_server.rb
+└── support_server/
+    └── tools/
+        ├── lookup_order.rb
+        └── refund_order.rb
+```
+
+The server is protected by bearer tokens from `SUPPORT_MCP_TOKENS`. The generator also adds this route:
+
+```ruby
+mcp_server :support
+```
+
+If `config/routes.rb` already mounts every server with a bare `mcp_servers`, the generator skips the route because the new server is mounted automatically.
+
+It then prints the commands to connect Claude Code over HTTP and stdio.
+
+### Options
+
+* **`--with-tools`**: Space-separated list of server tools to scaffold under `app/mcp_servers/<name>_server/tools/`. They are added to the server automatically. If you pass `--with-tools` with no names, an `ExampleTool` is generated.
+* **`--tools`**: Existing tool classes (for example, agent tools) to expose with `tools`.
+* **`--agents`**: Agents whose tools are all exposed with `tools_from`.
+* **`--path`**: Mount path, written as `mcp_server :support, path: "..."`. Defaults to `/mcp/<name>`.
+
+The `Server` suffix is added if you leave it out (`Support` → `SupportServer`). See [Defining MCP Servers](mcp/defining-servers.md).
+
+## Embeddings Generator
+
+```bash
+rails generate omni_agent:embeddings Document title content
+```
+
+Adds an embedding column to the `Document` model and declares `has_embedding :title, :content` on it, so the model can be searched by agents with [`searches`](rag.md#searches). The migration matches your database: a pgvector `vector` column with a cosine index on Postgres, a `binary` column plus the sqlite-vec initializer on SQLite, a `vector` column on MariaDB. The vector size is detected by embedding one string with your configured model.
+
+It then prints the commands to install the gems, migrate and backfill existing records.
+
+### Options
+
+* **`--backend`**: `pgvector`, `sqlite`, `mariadb` or `ruby`. Defaults to the one matching your database adapter. Plain MySQL is refused unless you pass `--backend=ruby`, which is [for small tables only](rag.md#ruby-fallback-small-tables-only).
+* **`--dimensions`**: Vector size. Pass it when the embedding model can't be reached (offline, no API key).
+* **`--column`**: Vector column name. Defaults to `embedding`.
+* **`--later`**: Embed in a [background job](rag.md#background-embedding) after commit instead of during `save`.
+
+## Chunks Generator
+
+```bash
+rails generate omni_agent:chunks Document file
+```
+
+Creates a `DocumentChunk` model and its table (with a vector column that matches your database, like the [embeddings generator](#embeddings-generator)) and declares `has_chunks :file` on `Document`, so its [documents are split and searched in chunks](rag.md#documents). If `file` is neither declared on the model nor a column, it's taken as an upload and `has_one_attached :file` is added too.
+
+It then prints the commands to install the gems, migrate and ingest existing records.
+
+### Options
+
+* **`--as`**: A [loader](rag.md#loaders) to enforce (`pdf`, `html`, `markdown`, `text`). Defaults to detecting each file's format.
+* **`--chunker`**: `recursive`, `markdown` or `hierarchical`. Defaults to `recursive`.
+* **`--size`** / **`--overlap`**: Chunk size and overlap, in characters.
+* **`--inline`**: Ingest right after commit instead of in a background job.
+* **`--backend`** / **`--dimensions`**: Same as the [embeddings generator](#options-3).

data/docs/index.md

@@ -0,0 +1,98 @@
+# OmniAgent Documentation
+
+Offline copy of https://omniagent.activetaskers.com/docs/intro, bundled with the `omni_agent` gem so coding
+agents (Claude Code, Cursor, Codex...) can learn how the gem works from inside
+a project that depends on it. Every page is plain Markdown; links between
+pages are relative.
+
+Locate these files from a host app with:
+
+```bash
+bundle exec omni_agent docs          # print this index
+bundle exec omni_agent docs tools    # print one page (path without .md)
+bundle exec omni_agent docs --path   # print the directory holding these files
+```
+
+## Conventions at a Glance
+
+OmniAgent is convention over configuration: classes are discovered from
+where they live, so put files where the generators put them.
+
+| What | Where | Class |
+| --- | --- | --- |
+| Global settings | `config/initializers/omni_agent.rb` (written by `omni_agent:install`) | `OmniAgent.configure` |
+| Agent | `app/agents/<name>.rb` | `<Name> < OmniAgent::Agent` |
+| Agent system prompt | `app/agents/<name>/prompt.md.erb` | |
+| Entrypoint prompt | `app/agents/<name>/<entrypoint>.md.erb` | |
+| Agent tool | `app/agents/<name>/tools/<tool>.rb` | `<Name>::Tools::<Tool> < OmniAgent::Tool` |
+| MCP server | `app/mcp_servers/<name>_server.rb` | `<Name>Server < OmniAgent::MCP::Server` |
+| MCP server tool | `app/mcp_servers/<name>_server/tools/<tool>.rb` | `<Name>Server::Tools::<Tool>` |
+| Eval | `evals/<name>_eval.rb` | `< OmniAgent::Eval` |
+
+Prefer the generators (`rails generate omni_agent:agent`, `omni_agent:mcp_server`,
+`omni_agent:stock_agent`, `omni_agent:eval`, `omni_agent:embeddings`,
+`omni_agent:chunks`) over writing these files by hand.
+See [Generators](generators.md).
+
+## Typical Flows
+
+* **Build an agent:** [Introduction](intro.md) → [Tools](tools.md) →
+  [Run Entrypoints](agent/run-entrypoints.md) → [Structured Output](agent/structured-output.md).
+* **Pick a provider or model:** [Supported Providers](supported-providers.md),
+  [Configuration](configuration.md), [Change an Agent's Provider or Model](agent/provider.md).
+* **Compose agents:** [Multi-Agent Delegation](agent/delegation.md),
+  [Stock Agents](stock-agents/overview.md).
+* **Observe a run:** [Generation Callbacks](agent/callbacks.md),
+  [Streaming Responses](agent/streaming.md).
+* **Answer from your own data (RAG):** [Retrieval-Augmented Generation](rag.md)
+  (`has_embedding`, `has_chunks` and the `searches` agent macro).
+* **Test quality:** [Generating and Running Evals](evals/generating-and-running.md) →
+  [Golden Sets](evals/golden-sets.md) → [Judge Provider](evals/judge-provider.md).
+* **Expose tools to MCP clients:** [Defining MCP Servers](mcp/defining-servers.md) →
+  [Authentication](mcp/authentication.md) → [Transports and Clients](mcp/transports.md).
+
+## All Pages
+
+### Core
+
+* [Introduction](intro.md): **Omni Agent** is a gem focused on generating agentic code the Rails way.
+* [Supported providers](supported-providers.md): This is a list of our currently supported providers.
+* [Configuration](configuration.md): Omni Agent ships with sensible defaults but lets you configure global behavior through an initializer.
+* [Tools](tools.md): Tools are how agents take action beyond generating text. Every tool is a small class that declares an input schema and implements `#execute`.
+* [Generators](generators.md): Omni Agent ships seven Rails generators to scaffold your project.
+* [Retrieval-Augmented Generation (RAG)](rag.md): RAG lets an agent answer from your own data: it searches your records for the passages relevant to a question and gives them to the model. Omni Agent keeps the vectors in your own database (or Meilisearch) and turns any searchable model into an agent tool. Records are searched whole with `has_embedding`, and files or long text in chunks with `has_chunks`.
+
+### Agents
+
+Learn about agent specific features and functionalities.
+
+* [Generation Callbacks](agent/callbacks.md): Agents support `before_generation` and `after_generation` callbacks, letting you hook into the lifecycle of a single `run` without overriding it yourself.
+* [Run Entrypoints](agent/run-entrypoints.md): `OmniAgent::Agent` always exposes the low-level `run` method, but you'll usually call an agent through one of its higher-level entrypoints.
+* [Change an Agent's Provider or Model](agent/provider.md): 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.
+* [Multi-Agent Delegation](agent/delegation.md): `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.
+* [Streaming Responses](agent/streaming.md): 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.
+* [Structured Output](agent/structured-output.md): Declare an `output` block to make an agent return a validated object instead of free text. It uses the same DSL as a tool's `input`.
+
+### Stock Agents
+
+Ready-made agents shipped with the gem that your project subclasses and customizes.
+
+* [Overview](stock-agents/overview.md): Stock agents are ready-made agents shipped with the gem under `OmniAgent::StockAgents`. They bring their own prompt, model settings and tools; your project subclasses one and declares the structured output it needs.
+* [OCR](stock-agents/ocr.md): `OmniAgent::StockAgents::OCR` reads photos, scans and PDFs with a vision model (`gpt-4o` by default). Its default output is `{ text: "..." }`, the full text in reading order; declare your own `output` to extract fields instead.
+
+### Evals
+
+Test agent quality with deterministic assertions and LLM-as-judge scoring.
+
+* [Generating and Running Evals](evals/generating-and-running.md): `OmniAgent::Eval` lets you test agent *quality*, not just correctness — deterministic assertions (tool calls, output matching) plus pluggable LLM-as-judge scoring.
+* [Golden Sets](evals/golden-sets.md): For many input/expected-output pairs, load a dataset file instead of writing a `eval_case` per row.
+* [Judge Provider](evals/judge-provider.md): `judge` resolves which provider grades the output, in this order.
+* [Caching](evals/caching.md): Eval runs are cached by default, keyed on `(agent class, run_alias, input, context)`, and stored as JSON at `OmniAgent.configuration.eval_cache_path` (default `tmp/omni_agent_eval_cache.json`). Re-running the same case — e.g. while iterating on assertions — replays the cached output instead of calling the provider again, so you don't spend tokens testing the same case twice.
+
+### MCP Servers
+
+Expose your tools and agents to Claude Code, Claude Desktop, Cursor and other MCP clients.
+
+* [Defining MCP Servers](mcp/defining-servers.md): The Model Context Protocol (MCP) lets AI clients such as Claude Code, Claude Desktop and Cursor call tools that live in your app. `OmniAgent::MCP::Server` turns the `OmniAgent::Tool` classes you already wrote for your agents — and the agents themselves — into an MCP server, with no extra gem.
+* [Authentication](mcp/authentication.md): An MCP server mounted over HTTP lets anyone who can reach the URL run your tools. For that reason, **every server must declare `authenticate`**. A server without it raises `OmniAgent::MCPError` on the first HTTP request. To make a server public on purpose, write `authenticate :none`.
+* [Transports and Clients](mcp/transports.md): OmniAgent supports both MCP transports.

data/docs/intro.md

@@ -0,0 +1,93 @@
+<!-- Generated from omniagent-docs/docs/intro.mdx by `bundle exec rake docs:sync`. Do not edit by hand. -->
+<!-- Online version: https://omniagent.activetaskers.com/docs/intro -->
+
+# Introduction
+
+**Omni Agent** is a gem focused on generating agentic code the Rails way. 
+
+It is designed to be highly opinionated, fully embracing the "convention over configuration" philosophy. 
+
+Let's get your first AI agent up and running **in less than 5 minutes**.
+
+## Getting Started
+
+### 1. Install the Gem
+First, add Omni Agent to your Rails application. You can add it directly to your `Gemfile`:
+
+```ruby
+gem 'omni_agent'
+```
+
+Or, run the following command in your terminal:
+
+```bash
+bundle add omni_agent
+```
+
+### 2. Install an AI Provider
+
+Omni Agent is provider-agnostic, meaning you need to install the specific gem for the AI provider you plan to use. You can find a full list of supported providers [here](supported-providers.md).
+
+For example, to use OpenAI:
+
+```bash
+bundle add openai
+```
+
+### 3. Run the Install Generator
+
+Prepare your project by running the Omni Agent installation generator:
+
+```bash
+rails generate omni_agent:install
+```
+
+This will set up the necessary foundation for your agents, starting by creating the core `app/agents` directory.
+
+> **Note:** As of version `0.1.4`, this command is lightweight. It lays the groundwork for more advanced configurations and planned features in future releases.
+
+## Create Your First Agent
+
+With the setup complete, you can use the built-in generator to scaffold your first agent.
+
+Run the following command to create a `DemoAgent`, specify the model, and attach a couple of tools:
+
+```bash
+rails generate omni_agent:agent DemoAgent --model gpt-4o-mini --with-tools DemoTool SecondDemoTool
+```
+
+This will generate the following directory structure inside `app/agents/`:
+
+```text
+app/agents/
+├── demo_agent.rb
+└── demo_agent/
+    ├── prompt.md.erb
+    └── tools/
+        ├── demo_tool.rb
+        └── second_demo_tool.rb
+
+```
+
+**What are these files?**
+
+* **`demo_agent.rb`**: The main configuration file dictating how your agent behaves.
+* **`prompt.md.erb`**: The core system prompt injected into your agent. It uses ERB, allowing for dynamic Ruby interpolation.
+* **`tools/`**: The directory housing the custom tools (`DemoTool`, `SecondDemoTool`) at your agent's disposal.
+
+## Calling the Agent
+
+After running the generator, your agent is ready to go out of the box. You can quickly test it in your Rails console (`rails c`) or anywhere in your app:
+
+```ruby
+DemoAgent.new.run("Hello!")
+```
+
+Congratulations - you are successfully using Omni Agent!
+
+## What Else Can It Do?
+
+* **[Tools](tools.md)** with typed, validated input schemas.
+* **[Multi-agent delegation](agent/delegation.md)**, **[streaming](agent/streaming.md)** and **[callbacks](agent/callbacks.md)**.
+* **[Evals](index.md#evals)** with golden sets and LLM-as-judge scoring.
+* **[MCP servers](index.md#mcp-servers)**: expose your tools and agents to Claude Code, Claude Desktop, Cursor and other MCP clients.