little_ghost 0.3.0 → 0.5.0

data/docs/guides/getting_started.md

@@ -1,33 +1,62 @@
-# Getting Started with LittleGhost
+# Getting Started
 
-This guide builds a customer support agent that checks a small help center before answering. It focuses on the Ruby objects needed for one useful run: a tool, an agent, and the call that starts it.
+In this guide, you'll run an agent, connect it to a small help center, and stream its answer. The whole feature stays in ordinary Ruby.
 
-LittleGhost runs inside your Ruby process. It does not choose how your application is hosted or where these definitions live.
+## Install the gem
 
-## Install LittleGhost
-
-LittleGhost requires Ruby 3.3 or newer. Add the gem to your `Gemfile`:
+LittleGhost requires Ruby 3.3 or newer. Add the gem to your `Gemfile`, install it, and set a provider credential:
 
 ```ruby
 gem "little_ghost"
 ```
 
-Install the bundle and set a provider credential:
-
 ```sh
 $ bundle install
-$ export OPENAI_API_KEY="..."
+$ export OPENROUTER_API_KEY="..."
 ```
 
-With `OPENAI_API_KEY` present, LittleGhost can connect the `openai` provider name used below. OpenRouter credentials work as well. Use application secret management outside a local shell, and do not commit provider credentials.
+Use your application's secret manager outside a local shell, and never commit provider credentials.
+
+This guide uses OpenRouter because one credential is enough to begin. LittleGhost can use other provider connections too; you will configure those in [Running in Production](production.md).
 
-## Give the agent a tool
+## See your first answer
 
-Start by requiring LittleGhost and defining a narrow help center lookup:
+Create `customer_support_agent.rb`:
 
 ```ruby
 require "little_ghost"
 
+class CustomerSupportAgent < LittleGhost::Agent
+  model "openrouter:openai/gpt-5.6-luna"
+  system_prompt "Answer customer questions clearly and concisely."
+end
+
+run = CustomerSupportAgent.ask("Can I change the address on my order?")
+
+if run.completed?
+  puts run.response
+else
+  warn "Support request ended as #{run.outcome}: #{run.error&.class}"
+end
+```
+
+Run the file and you have a working AI feature:
+
+```sh
+$ ruby customer_support_agent.rb
+```
+
+`CustomerSupportAgent.ask` creates a `LittleGhost::Run` for this request. When the work finishes, the Run holds the outcome and response.
+
+The inline prompt keeps this first example visible in one place. When the instructions grow, [Prompts as Views](prompt_views.md) moves them into a conventional ERB file without adding setup to the Agent.
+
+The selected external provider may receive system instructions, caller input, conversation history, tool results, and attachments. Model wording can vary, so use application code—not a prompt—when a rule must always hold.
+
+## Connect the agent to your application
+
+The first agent can answer general questions. A **tool** gives it a focused operation backed by your Ruby code:
+
+```ruby
 class HelpCenterLookupTool < LittleGhost::Tool
   HELP_CENTER_ENTRIES = {
     "refunds" => "Refunds are available within 30 days of purchase.",
@@ -50,119 +79,128 @@ class HelpCenterLookupTool < LittleGhost::Tool
 end
 ```
 
-A tool gives the model one application operation with a name, description, and validated JSON input. LittleGhost validates the input before calling `#call` and turns the returned value into model context.
-
-The schema checks shape, not authorization. A tool that reads customer data or performs an action must enforce the application's trust rules inside its implementation.
-
-## Define the agent
-
-Now describe the agent's behavior and make the lookup available to it:
+Make the tool available to the agent and tell the model when to use it:
 
 ```ruby
 class CustomerSupportAgent < LittleGhost::Agent
   description "Answers customer support questions."
-  model "openai:gpt-5.6-luna"
+  model "openrouter:openai/gpt-5.6-luna"
   system_prompt <<~PROMPT
     Answer clearly and do not invent company guidance.
-    Use the help center lookup tool before stating company guidance.
+    Check the help center before stating company guidance.
   PROMPT
-
   tools HelpCenterLookupTool
 end
-```
-
-An agent class is a reusable behavior definition. It owns its prompt, tools, model selection, limits, and other capabilities. This agent names an OpenAI connection and model directly, so the first example does not need a separate model profile.
 
-## Ask a question
-
-Call the agent class to run one request to completion:
-
-```ruby
 run = CustomerSupportAgent.ask(
   "I bought an item two weeks ago. Can I get a refund?"
 )
 
-if run.completed?
-  puts run.response
-else
-  warn "Support request ended as #{run.outcome}: #{run.error&.class}"
-end
+run.response
+# One possible response:
+# Refunds are available within 30 days, so your purchase is eligible.
 ```
 
-`CustomerSupportAgent.ask` creates and consumes a `LittleGhost::Run`. A successful run exposes its final text through `#response`; it also retains the normalized result, outcome, usage, messages, and any terminal error.
+LittleGhost checks the model's arguments before it calls
+`HelpCenterLookupTool#call`. The Tool's result then becomes context for the
+model.
 
-The model can call `HelpCenterLookupTool` with `{"topic":"refunds"}` and answer along these lines:
+### Use application context for private data
 
-```text
-Refunds are available within 30 days, so a purchase from two weeks ago is eligible.
-```
+The schema checks shape, not permission. When a Tool reads private data or
+changes something, use identity and account information established by your
+application rather than asking the model to supply it.
 
-Model wording and tool selection are not deterministic. The prompt directs the agent to ground company guidance in the validated lookup; applications that must enforce a lookup should put that ordering in a workflow.
+While an Agent is working, LittleGhost binds each Tool instance to the current
+Run. The Tool can read request values through its `run` accessor:
 
-## Stream the same agent
+```ruby
+class OrderStatusTool < LittleGhost::Tool
+  ORDER_STATUSES = {
+    ["user-7", "account-2", "481"] => "out for delivery"
+  }.freeze
 
-Use `.stream_ask` when a console, HTTP response, or user interface should receive progress while the run is active:
+  description "Look up an order that belongs to the current customer."
+  input_schema(
+    type: "object",
+    properties: {order_number: {type: "string"}},
+    required: ["order_number"],
+    additionalProperties: false
+  )
 
-```ruby
-CustomerSupportAgent.stream_ask("Can I get a refund?").each do |event|
-  case event.type
-  when :text_delta
-    print event.data.fetch(:text)
-  when :run_error
-    warn event.data.fetch(:message)
+  def call(input)
+    lookup = [
+      run.invocation.actor_id,
+      run.invocation.context.fetch("account_id"),
+      input.fetch("order_number")
+    ]
+
+    ORDER_STATUSES.fetch(lookup) do
+      raise LittleGhost::ToolError, "Order not found"
+    end
   end
 end
-```
 
-The stream yields `LittleGhost::StreamEvent` objects. Text, tool activity, usage, traces, and terminal lifecycle facts share this interface, so callers do not need provider-specific response handling.
+class CustomerSupportAgent < LittleGhost::Agent
+  tools HelpCenterLookupTool, OrderStatusTool
+end
 
-Both calls use the same agent definition and active LittleGhost configuration. Core Concepts explains reusable runtimes when an application needs more control over shared services.
+run = CustomerSupportAgent.ask(
+  "Where is order 481?",
+  actor_id: "user-7",
+  context: {account_id: "account-2"}
+)
+```
 
-## Add a model role when the application grows
+Here, `order_number` came from the model. The application supplied `actor_id`
+and `account_id` after authenticating the caller. LittleGhost places those
+request values on `run.invocation`; context keys become strings.
 
-Direct targets keep a small application's model choice beside its behavior. A larger application can give the same selection a stable role, then change the underlying provider, model, and defaults without editing each agent class:
+> **Safety note:** Treat model-selected Tool arguments like any other external
+> input. Check permission using the current user and account before returning
+> private data or performing a write.
 
-```ruby
-LittleGhost.configure do |config|
-  config.providers = {
-    openai: {adapter: :openai, api_key: ENV.fetch("OPENAI_API_KEY")}
-  }
-  config.models = {
-    customer_support: {
-      target: "openai:gpt-5.6-luna",
-      settings: {temperature: 0.2}
-    }
-  }
-  config.default_model = :customer_support
-end
+That is enough to authorize the first Tool safely. [Core Concepts](core_concepts.md) names the request and working-state objects behind `run`, and [Running in Production](production.md) explains what changes when you add saved conversations.
 
-class CustomerSupportAgent < LittleGhost::Agent
-  model :customer_support
-end
-```
+## Stream the same agent
 
-An agent may also keep a small amount of model-specific configuration beside its behavior:
+Use `.stream_ask` when a console, HTTP response, or user interface should receive progress as it happens:
 
 ```ruby
-class DeliberateSupportAgent < LittleGhost::Agent
-  model(
-    provider: "openai",
-    model: "gpt-5.6-luna",
-    reasoning_effort: "high"
-  )
+stream = CustomerSupportAgent.stream_ask("Can I get a refund?")
+
+run = stream.each do |event|
+  case event.type
+  when :text_delta
+    print event.data.fetch(:text)
+  when :run_error
+    warn event.data.fetch(:message)
+  end
 end
-```
 
-Here, `provider` names a configured connection and every other key after `model` is a trusted model setting. Provider connections and model profiles may instead come from independent YAML files under `config/little_ghost`, or from paths selected in `LittleGhost.configure`. Inline declarations take precedence over explicit paths, which take precedence over conventional files; environment-based selection and the built-in default are the final fallback. `LittleGhost::Agent` and `LittleGhost::Configuration` document the complete shapes and precedence.
+puts "\n#{run.response}" if run.completed?
+warn run.error.class.name if run.failed?
+```
 
-## Fit the agent into your application
+The stream yields `LittleGhost::StreamEvent` values. Text, tool activity, usage, and completion all look the same across providers. When enumeration finishes, `.each` returns the same `LittleGhost::Run` that now holds the final outcome and response.
 
-LittleGhost does not require an application layout. Keep agents and tools beside related application code when your framework or loader already has a home for them. If you want LittleGhost to eager-load definitions, use `app/agents` for agents and `app/tools` for tools.
+## Give the code a home
 
-The agent in this guide owns one model loop. A larger feature may coordinate several participants while preserving the same `ask` and `stream_ask` entrypoints. LittleGhost calls any such callable unit an **assembly**. Workflows, swarms, and graphs are three kinds of coordinated assembly, and they conventionally live in `app/assemblies`. Their class names should state the coordination style, such as `DevelopmentWorkflow`, `ProblemSolverSwarm`, or `SupportFlowGraph`.
+LittleGhost does not require an application layout. Keep definitions beside related application code, or use these optional conventions:
 
-Classes are the default way to organize reusable definitions. Core Concepts first explains when to choose each assembly type, then introduces builders for definitions discovered at runtime.
+```text
+app/
+├── agents/
+│   └── customer_support_agent.rb
+├── assemblies/
+│   └── response_workflow.rb
+├── prompts/
+│   └── customer_support/
+│       └── system.erb
+└── tools/
+    └── help_center_lookup_tool.rb
+```
 
-Hosting remains the surrounding application's responsibility. A Rails controller, Rack endpoint, background job, CLI, or another Ruby entrypoint can call the same agent APIs shown above.
+You now have the smallest useful LittleGhost application: one Agent, one Tool, and one familiar Ruby call.
 
-Read [Core Concepts](core_concepts.md) next. It begins with the agent you built here, then adds model selection, runs, assemblies, subagents, workflows, swarms, graphs, builders, sessions, and the boundaries between them. The API reference covers exact signatures for `LittleGhost::Agent`, `LittleGhost::Tool`, `LittleGhost::Run`, and the coordination classes.
+When the feature grows, the calling style stays the same. An **assembly** lets one or more agents work as a unit while keeping `.ask` and `.stream_ask`. Read [Core Concepts](core_concepts.md) next and grow this Agent into a larger system.

data/docs/guides/integrations.md

@@ -0,0 +1,217 @@
+# Connect MCP, AG-UI, and OpenTelemetry
+
+LittleGhost can load Tools from an MCP server, translate a Run stream for an
+interactive interface, and publish traces. Each integration uses the same
+Agents and Runs you already have.
+
+## Load Tools from an MCP server
+
+An MCP Toolset connects to one server and turns its published operations into
+LittleGhost Tool classes. Add the Toolset through the same Agent `tools`
+declaration used for local Tools:
+
+```ruby
+require "little_ghost/mcp"
+
+class HelpCenterTools < LittleGhost::MCP::Toolset
+  connection url: "https://mcp.example/rpc", timeout: 20
+end
+
+class CustomerSupportAgent < LittleGhost::Agent
+  system_prompt "Use help-center tools for published guidance."
+  tools HelpCenterTools
+end
+
+run = CustomerSupportAgent.ask("How long do refunds take?")
+run.response
+```
+
+`connection` requires `url` and also accepts `headers`, `timeout`, `signer`,
+`allow_insecure_http`, and `max_response_bytes`. Pass a block when credentials
+depend on the current Agent run:
+
+```ruby
+connection do |binding|
+  token = McpAccessTokens.for_actor(binding.run.invocation.actor_id)
+  {
+    url: "https://mcp.example/rpc",
+    headers: {"Authorization" => "Bearer #{token}"},
+    timeout: 20
+  }
+end
+```
+
+The block's `binding` gives it access to the current Run. LittleGhost evaluates
+the block before opening the MCP session, so each Agent run can use credentials
+for its authenticated caller.
+
+By default, the Agent receives every operation published by the server. Their
+normalized server names, such as `search` and `fetch`, become Tool names.
+
+Use `map_tool` when the Agent should receive only part of the server catalog or
+when a generated Tool needs a different name or configuration:
+
+```ruby
+class CuratedHelpCenterTools < LittleGhost::MCP::Toolset
+  connection url: "https://mcp.example/rpc", timeout: 20
+
+  map_tool do |tool_class, definition:, binding:|
+    next unless %w[search fetch].include?(definition.source_name)
+
+    tool_class.tool_name "help_center_#{definition.source_name}"
+    tool_class
+  end
+end
+```
+
+`definition` describes the operation published by the server, and `binding`
+identifies the current Agent run. Return the class after configuring it, or
+return `nil` to omit the operation. Renaming a generated Tool does not change
+the original `Definition#source_name` sent back to the server.
+
+The Agent can call the generated Tools like local Tools. LittleGhost uses one
+local client and transport for the Toolset during the Agent run. The built-in
+HTTP transport does not send an MCP session-termination request. Configure
+server-side expiry, or arrange explicit remote cleanup when the server requires
+it.
+
+Most MCP results need no mapping. LittleGhost returns `structuredContent` as a
+Ruby Hash when present, otherwise it returns the server's text. Server images
+become Artifacts.
+
+Use `map_result` when one operation needs application-specific conversion. This
+example turns the server's download identifier into a deferred Artifact:
+
+```ruby
+map_result do |result, call:, binding:|
+  next result unless call.definition.source_name == "export"
+
+  LittleGhost::Tool::Result.new(
+    value: result.structured_content,
+    artifacts: [
+      LittleGhost::Artifact.deferred(
+        reference: result.metadata.fetch("download_id"),
+        media_type: "application/octet-stream"
+      )
+    ]
+  )
+end
+```
+
+`map_result` receives the complete `MCP::Result`, the `MCP::Call` that produced
+it, and the current binding. Return any Ruby value or `Tool::Result`. Returning
+the supplied result unchanged keeps the default conversion described above.
+MCP images and local Tool artifacts use the same storage and presentation
+rules when `Configuration#artifacts` is enabled. Images and documents are sent
+as model content; their stored references are fallback information rather than
+a second representation. LittleGhost also checks results against
+server-advertised JSON Schema Draft 2020-12 output schemas.
+
+An optional server can fail discovery without preventing Agent construction:
+
+```ruby
+class HelpCenterTools < LittleGhost::MCP::Toolset
+  connection { |binding| McpConnections.help_center(binding) }
+  optional true
+  on_error do |error, binding:|
+    McpAvailability.report(error, run_id: binding.run.invocation.run_id)
+  end
+end
+```
+
+`optional true` converts expected provider and protocol discovery failures
+into an empty Tool set. `on_error` observes only those caught failures.
+Cancellation, deadlines, configuration errors, and application callback
+failures still propagate.
+
+LittleGhost limits the number and total size of discovered operations, the
+complexity of their schemas, and the size and number of returned images.
+`HTTPTransport` also limits each HTTP response and requires HTTPS unless local
+HTTP is explicitly enabled.
+
+> **Safety note:** An MCP server supplies descriptions and results that the model
+> can see. Structural validation does not make that content trustworthy or
+> authorize an operation it suggests. Expose only the operations the Agent
+> needs, use narrowly scoped credentials, and have the server authorize every
+> sensitive call. If a result becomes a deferred Artifact, its resolver must
+> verify that the referenced file belongs to the authenticated caller, fetch
+> only from an intended service, and limit the response size before returning
+> bytes to LittleGhost.
+
+LittleGhost implements its documented client behavior for the [MCP 2025-06-18
+specification](https://modelcontextprotocol.io/specification/2025-06-18).
+
+Use `LittleGhost::MCP::HTTPTransport` and `LittleGhost::MCP::Client` directly
+when you need a custom transport. They produce the same generated Tool classes
+and accept the same mapping callbacks as Toolset.
+
+## Send a Run stream through AG-UI
+
+The AG-UI adapter converts LittleGhost events into protocol event hashes:
+
+```ruby
+require "json"
+require "little_ghost/ag_ui"
+
+source = CustomerSupportAgent.stream_ask(
+  question,
+  actor_id: authenticated_user.id,
+  context: {account_id: authenticated_user.account_id}
+)
+
+events = LittleGhost::AGUI::Adapter.new.stream(
+  source,
+  thread_id: conversation.id,
+  run_id: request.request_id
+)
+
+events.each { |event| websocket.write(JSON.generate(event)) }
+```
+
+The adapter translates text, reasoning, Tool activity, usage, retries, trace
+context, subagent activity, and terminal outcomes. It is stateless between
+calls. Your application still owns the connection, thread storage,
+backpressure, and disconnect behavior.
+
+LittleGhost also emits namespaced custom events. Consumers should preserve or
+deliberately ignore event types they don't recognize. See the [AG-UI event
+documentation](https://docs.ag-ui.com/concepts/events) when implementing the
+client.
+
+> **Safety note:** A Run stream can include model output, Tool arguments and
+> results, errors, and participant activity. Check that the connected user may
+> see the complete Run, then filter fields before sending or storing events.
+
+Enumeration drives the source stream on the current thread. When a client
+disconnects, stop enumerating and apply the cancellation behavior your
+application needs. Closing the socket can't undo Tool work that already ran.
+
+## Trace Runs with OpenTelemetry
+
+Configure an OpenTelemetry SDK and exporter in the application, then register
+the LittleGhost subscriber before the first Agent call:
+
+```ruby
+LittleGhost.configure do |config|
+  config.instrument LittleGhost::Tracing::OpenTelemetry.new
+end
+```
+
+LittleGhost depends on `opentelemetry-api`, leaving the SDK, processor, and
+exporter up to the application. It emits spans and events for Runs, Agents,
+model calls, Tools, assemblies, sessions, usage, and failures. Active operations
+can propagate W3C `traceparent` and `tracestate` fields.
+
+Prompts, messages, responses, Tool arguments, and exception content are omitted
+by default. If you intentionally need some of that content, install a
+`LittleGhost::Support::ContentCapture` with a scrubber before enabling capture.
+Avoid putting raw user, order, session, or request IDs in span attributes.
+
+Attribute names follow the evolving [OpenTelemetry GenAI semantic
+conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) where they
+apply. Flush or shut down `LittleGhost::Instrumentation` during application
+shutdown when your backend buffers data.
+
+See [Running in Production](production.md) for startup, shutdown, and observability,
+[Tools](tools.md) for local and remote Tool behavior, and [Workspaces and
+Sandboxes](sandboxing.md) for child processes and files.

data/docs/guides/models_and_providers.md

@@ -0,0 +1,125 @@
+# Choose Models and Providers
+
+An Agent needs a model target: a configured provider connection plus the
+provider's model identifier. You can write that target directly while getting
+started, then give it an application-facing name when several Agents share it.
+
+## Start with one direct target
+
+A direct target has the form `connection:model-id`:
+
+```ruby
+class CustomerSupportAgent < LittleGhost::Agent
+  model "openrouter:openai/gpt-5.6-luna"
+  system_prompt "Answer customer questions clearly and concisely."
+end
+```
+
+`openrouter` names a connection configured by the application. The remainder
+is the model identifier understood by that provider. This is a good fit when
+one Agent owns one stable choice.
+
+## Give shared choices a role
+
+A model role lets several Agents share a choice without knowing its provider
+or model identifier:
+
+```ruby
+LittleGhost.configure do |config|
+  config.providers = {
+    primary: {
+      adapter: :openrouter,
+      api_key: ENV.fetch("OPENROUTER_API_KEY")
+    }
+  }
+  config.models = {
+    customer_support: {
+      target: "primary:openai/gpt-5.6-luna",
+      settings: {temperature: 0.2}
+    }
+  }
+  config.default_model = :customer_support
+end
+
+class CustomerSupportAgent < LittleGhost::Agent
+  model :customer_support
+end
+```
+
+Here `customer_support` is the role, `primary` is the connection, and
+`openrouter` is the adapter. You can move the role to another model or provider
+without editing the Agent.
+
+Profile settings are defaults. An individual call can override them:
+
+```ruby
+run = CustomerSupportAgent.ask(
+  "Explain the refund decision.",
+  settings: {temperature: 0.0}
+)
+```
+
+Build these settings in application code instead of passing request parameters
+through unchanged. Settings can affect cost, latency, and model behavior.
+
+## Configure connections in one place
+
+LittleGhost includes adapters for OpenRouter, OpenAI-compatible APIs,
+Anthropic, Gemini, Vertex AI, and Bedrock. Connections may live in an
+initializer or in the conventional files under `config/little_ghost`.
+
+Keep credentials in your application's secret manager. Agents refer to a role
+or configured connection; they don't need to contain credentials. If your
+application obtains short-lived credentials at runtime, configure a credential
+resolver that returns them for the selected connection.
+
+> **Safety note:** The selected provider may receive system instructions,
+> caller input, conversation history, Tool results, schemas, and attachments.
+> Choose a provider that is appropriate for that data, and keep credentials and
+> provider endpoints under application control.
+
+## Choose a role for each request
+
+An Agent can select between configured roles using its `Invocation`:
+
+```ruby
+class CustomerSupportAgent < LittleGhost::Agent
+  model do |invocation|
+    invocation.fetch(:premium_account, false) ? :premium_support : :customer_support
+  end
+end
+```
+
+Set `premium_account` from application state when creating the invocation. If
+a public request offers a model choice, map that choice to one of your
+configured roles rather than accepting an arbitrary provider target.
+
+Trusted application code may also declare a selection inline:
+
+```ruby
+class ResearchAgent < LittleGhost::Agent
+  model(
+    provider: "primary",
+    model: "openai/gpt-5.6-luna",
+    reasoning_effort: "high"
+  )
+end
+```
+
+`provider` still names a configured connection. The inline settings change the
+selection; they don't create a new connection.
+
+## Use model capabilities
+
+`LittleGhost::ModelResolver` turns a role or target into an executable
+`LittleGhost::Model`. Its catalog describes capabilities such as supported
+input types, output limits, and structured results. LittleGhost uses that
+information to reject unsupported attachments, constrain output limits, and
+choose a structured-result strategy.
+
+Provider capabilities can change. Handle failed Runs and provider errors even
+when the catalog says a feature is supported.
+
+Continue with [Prompts as Views](prompt_views.md) when an Agent's instructions
+outgrow one string. See [Structured Results and Content](structured_outputs_and_content.md)
+when you need checked result shapes, images, or documents.