little_ghost 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9890ec252b435a45ce78f82a57b107fbfa7f1846f4cf580e0538ce3303c2d7c5
-  data.tar.gz: 47c8aa6beeaf56a8987088007fa67e56144394a3fff1dcdb8e357812725ab7e6
+  metadata.gz: a2136594414b7f1c810eba51718916646506a4816ced53cf088034e091a0af5c
+  data.tar.gz: a7a2a279680b64f936096f70772374b3dcfc1ba21dfb2e428da91be22d385af4
 SHA512:
-  metadata.gz: 92540329eaa105782f108dc52cf0e21351b7ae60c674d6b6d786a460b221e54f569ae7f3240bdb0d8a436ea6b0102ef1d14251fa543d2d9c7522aad6d9142f4a
-  data.tar.gz: 3dcb8b76e48448cbbd8088cfc0ee5ef0edcfcdb4b595c93ed741d60ee9f852a4ece504794119bdd874761ed1e40af97f7e05f6bb3f81884c9b8d4c4b0656a43a
+  metadata.gz: 3c78c760b8b9be5bb9aa3394fffdcc0735173366826b263534421c9755f0b0f458b4d14f75c65bee76bb8da839beb67917e6ce222d438073bef95f9258c23ec0
+  data.tar.gz: 6effec94de30f7b4e1ed5fcad776cd9579da8645a95ca510ebe5ee5a26921ded2c34eae8f50b70295e326c6874135cd7293de202874980da957ca73558852fe9

data/README.md

@@ -1,18 +1,46 @@
-# Build AI features with LittleGhost
+# Build AI features that feel at home in Ruby
 
-<hr>
+LittleGhost is a Ruby library for building AI features with agents and composable assemblies. With `OPENROUTER_API_KEY` set, start with one class, give it a prompt, and call it like the rest of your application code:
 
-**Growing in public.** LittleGhost is under active development, and interfaces may evolve between releases. Pin the gem version and review the release notes when upgrading.
+```ruby
+require "little_ghost"
+
+class CustomerSupportAgent < LittleGhost::Agent
+  model "openrouter:openai/gpt-5.6-luna"
+  system_prompt "Answer customer questions clearly and concisely."
+end
 
-<hr>
+run = CustomerSupportAgent.ask("Draft a friendly greeting for a customer.")
+run.response
+# One possible response: Hi! How can I help today?
+```
 
-Build an agent inside an existing Ruby system, or use LittleGhost as the core of a dedicated AI service. An agent is a reusable Ruby class that gives one model a prompt, tools, limits, and a model selection. LittleGhost connects that class to providers, streaming, sessions, delegation, and observability.
+That small definition is already a complete agent. LittleGhost makes the model call, tracks usage, supports streaming, and closes the resources it creates for the request. Add a tool when the agent needs something from your application. Bring in more agents when the work grows.
 
-Set `OPENAI_API_KEY`, then paste this customer support agent into a Ruby console or file. It selects a model directly and exposes one validated application tool:
+Model requests may send system instructions, caller input, conversation history, tool results, and attachments to the selected external provider. Model wording can vary between runs. Choose providers and the data you send them with the same care as any other external service.
+
+## Install the gem
+
+LittleGhost requires Ruby 3.3 or newer. Add it to your bundle and provide a provider credential:
 
 ```ruby
-require "little_ghost"
+gem "little_ghost"
+```
 
+```sh
+$ bundle install
+$ export OPENROUTER_API_KEY="..."
+```
+
+OpenRouter keeps the first setup to one credential. It is not required: LittleGhost also includes adapters for OpenAI-compatible APIs, Anthropic, Gemini, Vertex AI, and Bedrock. [Running in Production](docs/guides/production.md) shows how to configure providers and give model choices application-facing names.
+
+LittleGhost runs inside your Ruby process. Use it from a controller, job, CLI, or service. If you want a conventional layout, start with `app/agents`, `app/assemblies`, `app/prompts`, and `app/tools`.
+
+## Give an agent real capabilities
+
+Tools let an agent call focused parts of your application:
+
+```ruby
 class HelpCenterLookupTool < LittleGhost::Tool
   description "Look up a help center entry by topic."
   input_schema(
@@ -29,39 +57,33 @@ class HelpCenterLookupTool < LittleGhost::Tool
 end
 
 class CustomerSupportAgent < LittleGhost::Agent
-  description "Answers customer support questions."
-  model "openai:gpt-5.6-luna"
-  system_prompt "Answer clearly. Check the help center before stating company guidance."
+  model "openrouter:openai/gpt-5.6-luna"
+  system_prompt "Check the help center before stating company guidance."
   tools HelpCenterLookupTool
 end
-
-run = CustomerSupportAgent.ask("Can I get a refund after two weeks?")
-puts run.response
-# One possible response:
-# Refunds are available within 30 days, so your purchase is eligible.
 ```
 
-The completed `LittleGhost::Run` exposes its outcome, final response, normalized messages, token usage, and terminal error. Streaming callers receive `LittleGhost::StreamEvent` objects instead of provider-specific payloads:
+The schema checks the shape of the input. Your Ruby code still decides whether the operation is allowed and safe. The result goes back to the model as context.
+
+## Grow without changing the caller
+
+An **agent** owns one model loop. An **assembly** is one or more agents working as a unit. You call either one the same way:
 
 ```ruby
-CustomerSupportAgent.stream_ask("Can I get a refund?").each do |event|
-  print event.data.fetch(:text) if event.type == :text_delta
-end
+CustomerSupportAgent.ask(question)
+ResponseWorkflow.ask(question)
+ProblemSolverSwarm.ask(question)
+SupportFlowGraph.ask(question)
 ```
 
-## How the pieces fit
-
-One agent is the smallest useful LittleGhost application. A request creates a run, the agent may call a tool or delegate to a subagent, and the run records the outcome:
+Choose the coordination style that matches who should control the next step:
 
-```text
-provider connections + model selections ──> ModelResolver ──> provider
-                                               │
-request ──> CustomerSupportAgent ──> HelpCenterLookupTool
-                  │
-                  └────────> ResearchAgent subagent
-```
+- A **subagent** lets a model delegate an addressable task.
+- A **workflow** uses ordinary Ruby for ordering and branching.
+- A **swarm** lets configured agents choose permitted handoffs.
+- A **graph** makes allowed routes explicit as nodes and edges.
 
-When one model loop is not enough, LittleGhost calls the larger callable unit an **assembly**. An assembly may be one agent or a coordinated group that still looks like one agent to its caller:
+A Workflow or Graph can contain agents, other assemblies, or both. Named classes are the clearest place to begin. Builders are there when your application discovers the participants or routes at runtime.
 
 ```text
 request ──> CustomerSupportAgent
@@ -73,67 +95,29 @@ request ──> ProblemSolverSwarm ──> TriageAgent ──handoff──> Bill
 request ──> SupportFlowGraph ──> TriageAgent ──edge──> ResponseAgent
 ```
 
-A `Workflow` uses ordinary Ruby to enforce ordering and branching. A `Swarm` lets configured agents hand the request directly to one another. A `Graph` follows application-declared nodes and edges when the allowed paths should be visible in advance. These types share `ask` and `stream_ask`, so callers can depend on one entrypoint contract while the implementation grows.
-
-Class definitions are the default way to organize agents and assemblies. Builder objects support definitions whose participants or topology are discovered at runtime; the Core Concepts guide introduces them after the class-based forms.
-
-Each top-level execution owns one run lifecycle. The run checkpoints session state, closes its resources, aggregates usage, and emits framework events regardless of which assembly type is the entrypoint.
-
-## Installation and configuration
-
-LittleGhost requires Ruby 3.3 or newer. Add it to your bundle:
-
-```ruby
-gem "little_ghost"
-```
-
-Then run `bundle install`. Built-in OpenAI-compatible, OpenRouter, Anthropic, Gemini, Vertex AI, and Amazon Bedrock integrations use Ruby's standard library and normalize responses into the same protocol.
-
-Configuration does not require a particular directory layout. Provider connections and model profiles resolve independently in this order:
-
-1. An inline `config.providers` or `config.models` declaration.
-2. The corresponding explicit `config.providers_path` or `config.models_path`.
-3. The optional conventional file under `config/little_ghost/`.
-4. Environment-based provider selection and the built-in `default` profile.
-
-An explicit path must exist. A missing conventional file is valid. The conventional form keeps connection policy separate from model roles:
-
-```yaml
-# config/little_ghost/providers.yml
-providers:
-  openai:
-    adapter: openai
-    api_key: <%= ENV.fetch("OPENAI_API_KEY") %>
-```
-
-```yaml
-# config/little_ghost/models.yml
-default_model: customer_support
-models:
-  customer_support:
-    target: openai:gpt-5.6-luna
-```
-
-By default, LittleGhost maps `default` to GPT-5.6 Luna. It configures conventional OpenRouter and OpenAI connections from nonblank `LITTLEGHOST_OPENROUTER_API_KEY`, `LITTLEGHOST_OPENAI_API_KEY`, `OPENROUTER_API_KEY`, and `OPENAI_API_KEY` values; that order determines the default when more than one provider is available. Model inputs—including prompts, history, tool data, and attachments—leave the application for the selected external provider. Configure providers explicitly when provider choice or data residency matters.
-
-Applications that need custom routing can subclass `LittleGhost::ModelResolver` and install the class with `config.model_resolver`. A custom resolver owns its profiles and default role; configuring `models`, `models_path`, or `default_model` at the same time is an error. Provider configuration remains available to the resolver.
+The result stays familiar too. Every call returns a `Run` with the response,
+outcome, usage, and any final error. A coordinated assembly also records which
+participants ran. Use `.stream_ask` to watch the work as it happens.
 
-LittleGhost runs inside the surrounding Ruby process; it does not prescribe an HTTP server, CLI, job system, or application layout. `config/little_ghost`, `app/agents`, `app/assemblies`, `app/prompts`, `app/tools`, and `app/skills` are optional conventions. Keep agent classes in `app/agents`; workflow, swarm, and graph classes conventionally live in `app/assemblies`. Names should reveal the type, such as `DevelopmentWorkflow`, `ProblemSolverSwarm`, or `SupportFlowGraph`.
+**Growing in public.** LittleGhost is under active development, and interfaces may evolve between releases. Pin the gem version and review release notes when upgrading.
 
-## Documentation
+## Keep going
 
-- [Getting Started](docs/guides/getting_started.md) builds and streams the customer support example.
-- [Core Concepts](docs/guides/core_concepts.md) starts with one agent, then introduces assemblies, delegation, workflows, swarms, graphs, and dynamic builders.
-- [API reference](rdoc-ref:LittleGhost) covers exact signatures, options, and lifecycle behavior.
+- [Getting Started](docs/guides/getting_started.md) takes you from installation to a tool-backed, streaming agent.
+- [Core Concepts](docs/guides/core_concepts.md) builds the mental model from Agent to Assembly.
+- [Compose Agents](docs/guides/assemblies.md) walks through workflows, swarms, graphs, nesting, and builders.
+- [Prompts as Views](docs/guides/prompt_views.md) gives growing instructions, shared pieces, and application values a natural home.
+- [Running in Production](docs/guides/production.md) covers configuration, sessions, execution, observability, and trust boundaries.
+- [API reference](rdoc-ref:LittleGhost) provides exact signatures and lifecycle contracts.
 
-## Contributing
+### For contributors
 
 See the [contributing guide](https://github.com/mattyr/little_ghost/blob/main/CONTRIBUTING.md), [Code of Conduct](https://github.com/mattyr/little_ghost/blob/main/CODE_OF_CONDUCT.md), and [security policy](https://github.com/mattyr/little_ghost/blob/main/SECURITY.md).
 
 ```sh
-bundle install
-bundle exec rake test
-bundle exec standardrb --no-fix
+$ bundle install
+$ bundle exec rake test
+$ bundle exec standardrb --no-fix
 ```
 
-LittleGhost is licensed under the MIT License.
+LittleGhost is available under the MIT License.

data/docs/guides/assemblies.md

@@ -0,0 +1,286 @@
+# Compose Agents
+
+An Assembly lets several participants answer through the same familiar calls as one Agent. This guide grows the customer-support example through each coordination style, then shows how to nest and construct assemblies dynamically.
+
+## Start with the shared contract
+
+Callers do not need a branch for each implementation:
+
+```ruby
+entrypoint = urgent? ? EscalationWorkflow : CustomerSupportAgent
+run = entrypoint.ask(question)
+```
+
+`Agent`, `Workflow`, `Swarm`, and `Graph` all answer through the Assembly calling style. They differ in how they coordinate work, not in how your application calls them.
+
+## Use a Workflow for explicit application logic
+
+A Workflow's `perform` method is ordinary Ruby. Inside it, `invoke` prepares a child call. Read `.output` when you need an intermediate answer. Return the final `invoke` call untouched so its response can stream to the caller.
+
+```ruby
+class ResponseWorkflow < LittleGhost::Workflow
+  private
+
+  def perform
+    research = invoke(ResearchAgent).output
+
+    invoke CustomerSupportAgent, input: <<~PROMPT
+      #{input.text}
+
+      Verified research:
+      #{research}
+    PROMPT
+  end
+end
+
+run = ResponseWorkflow.ask("Why is transfer 481 pending?")
+run.response
+```
+
+Every participant passed to `invoke` can be an Agent or another Assembly. By default, each child receives the caller's history and application context. Pass `history: []`, `context: {}`, or redacted values when a child should see less.
+
+Each child Agent keeps its own [prompt view](prompt_views.md). The Workflow supplies request-specific input; it does not replace that Agent's reusable system instructions.
+
+The last child is special because its events become the Workflow's public stream. Return that `invoke` without consuming it:
+
+```ruby
+# Wrong: this returns a String after consuming the final invocation.
+def perform
+  invoke(CustomerSupportAgent).output
+end
+
+# Right: this returns the lazy invocation itself.
+def perform
+  invoke CustomerSupportAgent
+end
+```
+
+The first version produces a failed top-level Run whose error is `ProtocolError`. Use `.output` only when Ruby needs an intermediate answer before choosing the next step.
+
+### Choose a branch in Ruby
+
+Each branch should end with its final unconsumed invocation:
+
+```ruby
+class RoutedResponseWorkflow < LittleGhost::Workflow
+  private
+
+  def perform
+    route = invoke(TriageAgent, as: :triage).output
+
+    if route == "billing"
+      invoke BillingAgent, as: :billing_response
+    else
+      invoke CustomerSupportAgent, as: :general_response
+    end
+  end
+end
+```
+
+`as:` gives the child a readable participant name in steps, trajectories, and telemetry. It does not change which Assembly runs.
+
+### Run independent work in parallel
+
+Use `parallel` when several inputs can be processed independently:
+
+```ruby
+class InvestigationWorkflow < LittleGhost::Workflow
+  private
+
+  def perform
+    findings = parallel(
+      invoke(LedgerResearchAgent),
+      invoke(PolicyResearchAgent),
+      max_concurrency: 2
+    )
+
+    invoke CustomerSupportAgent, input: <<~PROMPT
+      #{input.text}
+
+      Findings:
+      #{findings.join("\n")}
+    PROMPT
+  end
+end
+```
+
+`max_concurrency` limits how many calls run at once. Each one gets its own copy of the workflow context. Cancellation still depends on the provider or tool noticing its token or deadline.
+
+## Use a Swarm for specialist handoffs
+
+A Swarm keeps one Agent active at a time. You decide which specialists it may hand work to:
+
+```ruby
+class ProblemSolverSwarm < LittleGhost::Swarm
+  member TriageAgent
+  member BillingAgent
+  member AccountAgent
+
+  start TriageAgent
+  handoff TriageAgent, to: [BillingAgent, AccountAgent]
+  handoff BillingAgent, to: TriageAgent
+  handoff AccountAgent, to: TriageAgent
+
+  max_steps 10
+  max_handoff_repeats 2
+end
+```
+
+The active model sees a handoff tool listing the members it may choose next. LittleGhost accepts only the routes you declared. `max_steps` limits total member executions. `max_handoff_repeats` limits how often the same directed handoff, such as triage to billing, may repeat.
+
+Swarm members must be Agents, so each transition stays a direct model-to-model handoff. Caller history and application context are opt-in for each member. Handoff messages come from a model; never treat them as permission to read data or perform an action.
+
+Opt in only for a member that needs the data:
+
+```ruby
+member AccountAgent, history: true, context: true
+```
+
+Intermediate model text stays out of the caller-facing stream, leaving one coherent public answer. This is not a privacy boundary. The next member receives the handoff, and the result keeps a bounded summary of the journey.
+
+## Use a Graph for guided routes
+
+A Graph names the possible stops and the routes between them. Start with a conditional route before adding parallel branches:
+
+```ruby
+class SupportFlowGraph < LittleGhost::Graph
+  node :triage, TriageAgent
+  node :billing, BillingAgent
+  node :general, CustomerSupportAgent
+  node :respond, CustomerSupportAgent
+
+  start :triage
+
+  edge :triage, :billing do |state|
+    state.result(:triage).output == "billing"
+  end
+  edge :triage, :general
+  edge :billing, :respond
+  edge :general, :respond
+  finish :respond
+end
+
+SupportFlowGraph.validate!
+```
+
+Conditions and input mappers read an immutable `Graph::State`. At most one conditional edge may match. If several match, LittleGhost raises `AssemblyRoutingError` instead of guessing which one wins. One unconditional edge can catch the request when none match.
+
+Graph nodes start without caller history or application context. They still receive the original input or the output routed from an earlier node. Map or redact that data before it moves to a provider or participant that should see less.
+
+Opt in for a trusted node when it needs caller context:
+
+```ruby
+node :account_lookup, AccountLookupAgent, context: true
+```
+
+### Fork and join bounded parallel paths
+
+Use a fork when one result should start several independent branches. A join brings their answers back together:
+
+```ruby
+class InvestigationGraph < LittleGhost::Graph
+  node :triage, TriageAgent
+  node :ledger, LedgerResearchAgent
+  node :policy, PolicyResearchAgent
+  node :respond, CustomerSupportAgent
+
+  start :triage
+  fork :triage, to: [:ledger, :policy], max_concurrency: 2
+  join(
+    [:ledger, :policy],
+    to: :respond,
+    input: ->(state) { state.branch_results.transform_values(&:output) }
+  )
+  finish :respond
+end
+```
+
+An error edge can send an expected failure to a recovery Assembly. Call `validate!` before the first run.
+
+Once the topology grows, `InvestigationGraph.to_mermaid` returns Mermaid diagram source for the routes you declared. Render it in a Mermaid-aware editor or documentation page when a picture makes the graph easier to review.
+
+## Make retries safe
+
+Workflow calls, Swarm members, and Graph nodes can set timeouts and retries. Use them for work that can safely be attempted again:
+
+```ruby
+invoke(
+  ResearchAgent,
+  timeout: 15,
+  retries: 2,
+  retry_on: [LittleGhost::ProviderError],
+  retry_delay: 0.25
+)
+```
+
+A timeout asks the running code to stop; it cannot forcibly end arbitrary Ruby or provider work. A retry repeats the whole child step. Retry only selected failures, and make sure repeated external actions are safe.
+
+Retries start at zero. When `retries` is greater than zero, `retry_on` must list the exception classes that are safe to try again. LittleGhost does not retry every failure by default.
+
+## Inspect what the assembly did
+
+A composite result remembers the steps it took. `trajectory` lets you explore them:
+
+```ruby
+run = InvestigationGraph.ask("Why is transfer 481 pending?")
+trajectory = run.result.trajectory
+
+trajectory.each { |step| puts "#{step.participant}: #{step.status}" }
+trajectory.transitions
+ledger = trajectory.find { |step| step.participant == "ledger" }
+policy = trajectory.find { |step| step.participant == "policy" }
+trajectory.concurrent?(ledger.id, policy.id)
+```
+
+Step outputs and buffered events have size limits. Use your application's instrumentation when trusted operators need deeper diagnostics.
+
+## Compose assemblies inside assemblies
+
+Workflow and Graph participants accept any Assembly definition:
+
+```ruby
+class ResolutionGraph < LittleGhost::Graph
+  node :investigate, InvestigationWorkflow
+  node :resolve, ProblemSolverSwarm
+
+  start :investigate
+  edge :investigate, :resolve
+  finish :resolve
+end
+```
+
+An Assembly can also become an Agent tool:
+
+```ruby
+class SupportCoordinatorAgent < LittleGhost::Agent
+  assembly_as_tool InvestigationGraph,
+    name: "investigate_support_request",
+    preserve_context: false
+end
+```
+
+The nested assembly receives the parent Tool's current working state. That state may include values restored from a Session. `preserve_context` controls conversation history only: when it is false, working state still passes to the nested assembly. Any nested Tool doing privileged work must authorize with values the application established for the current request or checked again after loading.
+
+## Reach for builders when definitions are dynamic
+
+Classes are the preferred form in application code. Use a builder when trusted application configuration decides the nodes or routes:
+
+```ruby
+graph = LittleGhost::GraphBuilder.new(
+  id: "support_flow",
+  description: "Routes customer support requests"
+)
+
+graph.node :triage, TriageAgent
+graph.node :respond, CustomerSupportAgent
+graph.start :triage
+graph.edge :triage, :respond
+graph.finish :respond
+graph.validate!
+
+run = graph.ask("Where is my order?")
+```
+
+Each builder uses the same declarations as its matching class. The builder stays editable, but each run gets a fixed copy of its current definition. Later edits affect later runs. Ruby callbacks still see any application objects they captured.
+
+Continue with [Prompts as Views](prompt_views.md) to give each Agent's growing instructions and shared prompt pieces a natural home.