little_ghost 0.2.1 → 0.4.0

data/docs/guides/core_concepts.md

@@ -1,148 +1,156 @@
 # Core Concepts
 
-LittleGhost gives Ruby software two ways to compose AI behavior. Agents can choose among validated tools and delegated specialists, while agentic workflows keep required ordering and branching under application control. The customer support example makes that boundary visible: ModelResolver chooses provider-backed models, CustomerSupportAgent owns behavior, HelpCenterLookupTool exposes a narrow help center lookup, ResearchAgent handles delegated investigation, and ResponseWorkflow imposes a deterministic sequence when the surrounding system requires one.
-
-```text
-shared configuration
-└── ModelResolver ── resolves model selections ──> provider clients
-
-one request
-└── Run
-    ├── CustomerSupportAgent
-    │   ├── HelpCenterLookupTool
-    │   └── ResearchAgent subagent (model-directed)
-    └── sessions, resources, usage, events, and terminal result
-
-one deterministic request
-└── Run ──> ResponseWorkflow ──> ResearchAgent ──> CustomerSupportAgent
-```
-
-## Models can be selected directly or by role
-
-An agent can name a canonical target directly when the choice belongs beside its behavior:
+Build one model-driven behavior in a Ruby class, then call it like Ruby. That is the idea LittleGhost grows from.
 
 ```ruby
 class CustomerSupportAgent < LittleGhost::Agent
-  model "openai:gpt-5.6-luna"
+  model "openrouter:openai/gpt-5.6-luna"
+  system_prompt "Answer customer questions clearly."
+  tools HelpCenterLookupTool
 end
+
+run = CustomerSupportAgent.ask("Where is my order?")
+run.response
 ```
 
-It can also attach trusted model settings without defining a shared profile:
+From there, add only what the work needs. Give the agent a tool. Let it ask a specialist for help. Or coordinate several agents while the rest of your application keeps making the same call.
 
-```ruby
-class DeliberateSupportAgent < LittleGhost::Agent
-  model(provider: "openai", model: "gpt-5.6-luna", reasoning_effort: "high")
-end
+## An Agent owns one model loop
+
+An **Agent** defines one model-driven behavior. It chooses the model, supplies the instructions and tools, and carries one request through to an answer.
+
+The class holds the behavior you want to reuse. Each call brings its own input, history, context, settings, and attachments. Request data never needs to live on the class.
+
+```text
+CustomerSupportAgent
+├── model selection
+├── system prompt
+├── HelpCenterLookupTool
+└── limits and optional capabilities
 ```
 
-In both forms, `provider` is the name of a configured connection. A role such as `customer_support` adds stable application vocabulary when several agents or deployments should share routing policy:
+An Agent can return text or checked, structured data. Later, you can add streaming, sessions, or callbacks. None of them are required to begin.
+
+## A Tool connects the model to Ruby
+
+A **Tool** is one focused thing an agent can ask your application to do. It has a name, a description, an input schema, and the Ruby code that does the work.
 
 ```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"}
-  }
+class HelpCenterLookupTool < LittleGhost::Tool
+  description "Look up a help center entry by topic."
+  input_schema(
+    type: "object",
+    properties: {topic: {type: "string"}},
+    required: ["topic"],
+    additionalProperties: false
+  )
+
+  def call(input)
+    {"refunds" => "Refunds are available within 30 days."}
+      .fetch(input.fetch("topic"))
+  end
 end
 ```
 
+LittleGhost checks the model's arguments, calls the tool, and gives the result back to the model. The schema checks shape, not permission. Authorize sensitive reads and actions inside the tool with trusted application context.
+
+## A Run owns one top-level execution
+
+Every `.ask` or `.stream_ask` creates a **Run**. Think of it as the record of one trip through LittleGhost. It opens what the request needs, records how the work ended, and closes the resources it owns.
+
 ```ruby
-class CustomerSupportAgent < LittleGhost::Agent
-  model :customer_support
-end
+run = CustomerSupportAgent.ask("Where is order 481?")
+
+run.completed? # => true
+run.response
+# One possible response: Order 481 is out for delivery.
+run.usage      # => normalized token usage
+run.result     # => the complete LittleGhost::RunResult
 ```
 
-Strings and symbols without a colon are roles; strings containing a colon are canonical targets; mappings require `provider` and `model`, with remaining keys treated as model settings. Role names cannot contain a colon. Direct targets and mappings bypass role inheritance and overlays.
+The Agent defines reusable behavior; the Run records what happened this time.
 
-Dotted roles inherit from the nearest registered parent. `ResearchAgent` can request `customer_support.research` and initially use the `customer_support` profile; registering `customer_support.research` later specializes it. A resolver caller may pass an explicit `profiles:` overlay without mutating the configured profiles or agent class. Because an overlay can select a different registered provider, model, and settings, it is trusted application configuration and must be constructed or allowlisted by the application rather than copied from unchecked request data. The base resolver does not inspect application-specific invocation fields.
+### Follow one request
 
-The provider performs model I/O. `LittleGhost::ModelResolver` resolves application intent into a `LittleGhost::Model`, which carries the provider, target, settings, details, and role for a run.
+One Run owns the trip from request to result:
 
-## Agents declare behavior
+```text
+Run
+├── Invocation: caller input, history, and application context
+├── RunContext: mutable working state for this execution
+└── Agent and Tools ──> RunResult
+```
 
-An agent class declares application behavior:
+An **Invocation** is the request in LittleGhost's standard shape. Its `context` contains current request values supplied by your application. A Tool can read those values through `run.invocation.context` when it authorizes work.
 
-```ruby
-class CustomerSupportAgent < LittleGhost::Agent
-  description "Answers customer support questions."
-  model "customer_support"
-  system_prompt "Answer clearly. Check the help center before stating company guidance."
-  tools HelpCenterLookupTool
-  subagent ResearchAgent, kind: "research"
-end
-```
+The **RunContext** carries mutable working state in `context.state`. At the top level, saved Session state is loaded first, then current Invocation context is added. Child Assemblies may receive a copy, a mapped value, or no context at all. Recheck saved values before using them for permission decisions.
 
-The class-level DSL is inheritable. It can declare prompts, limits, callbacks, tool classes, structured results, context management, skills, and delegation. A capability mixin may be included in `LittleGhost::Agent`, but its behavior remains inactive until the corresponding DSL is called.
+A Tool's **Binding** gives the Tool access to objects created for this run, including the Agent, Run, workspace, and sandbox. These objects are separate from the arguments chosen by the model.
 
-`CustomerSupportAgent.ask` creates a standalone entrypoint, builds and consumes a `LittleGhost::Run`, and returns that run. `CustomerSupportAgent.stream_ask` creates the same kind of entrypoint and yields the run's events. Create `CustomerSupportAgent.new(runtime:)` explicitly when several calls should reuse one runtime. Agents built by a runtime are instead scoped to their owning run and return a `LittleGhost::RunResult` from `#call`.
+The final **RunResult** keeps the complete assembly result. Its `text` is the final text answer. Its `output` returns structured data when the Agent declared a result schema, and text otherwise. The top-level `Run#response` is always the caller-facing text.
 
-That distinction explains two useful return paths:
+### See how a call ended
 
-```ruby
-run = CustomerSupportAgent.ask("Can I get a refund?")
-run.response       # final text from the top-level execution
-run.result.output  # text, or a validated structured value when declared
-```
+Top-level calls normally return a Run, even when execution fails. The terminal event carries the same outcome when you stream:
 
-## Runs own top-level lifecycle
+| What happened | Run outcome | Terminal event | What Ruby does |
+| --- | --- | --- | --- |
+| The assembly completed | `completed` | `:run_stop` | Returns the Run |
+| Model, provider, or assembly execution failed | `failed` | `:run_error` | Returns the Run; inspect `run.error` |
+| The deadline stopped work | `partial` | `:run_partial` | Returns the Run with any response produced so far |
+| Cancellation stopped work | `cancelled` | `:run_cancel` | Returns the Run without a response |
+| Tool input or a `ToolError` failed | The model may recover | No terminal event by itself | Gives a safe error result back to the model |
+| Input, configuration, or resources failed before a Run could start | No Run exists | None | Raises the exception |
 
-A `LittleGhost::Run` owns one top-level agent or workflow execution. It opens the session, workspace, sandbox, entrypoint, and registered resources, then closes owned resources in reverse order.
+Unexpected Tool exception messages are hidden from the model. The original exception remains available to trusted application callbacks and diagnostics.
 
-The run is both executable and enumerable. `#call` consumes it; `#each` streams `LittleGhost::StreamEvent` objects. After termination, the run reports one outcome: completed, failed, partial at a deadline, or cancelled. It also exposes the final response, result, usage, and error.
+Failures while closing resources, delivering events, or reporting instrumentation sit outside the normal result path. They raise a Ruby exception because LittleGhost can no longer promise that it delivered a clean ending. [Running in Production](production.md) covers that boundary where applications supervise and shut down work.
 
-An `Invocation` is the request envelope. It normalizes the current message and history, generates missing identifiers, and retains application-specific fields with indifferent string and symbol keys. Caller identity remains explicit. If session persistence needs tenant isolation, derive its actor from trusted authentication state; never trust a model-supplied or unverified request field.
+## An Assembly can look like one Agent
 
-## Tools are validated application boundaries
+One model loop is not always enough. LittleGhost calls any unit that a caller can invoke like an Agent an **Assembly**.
 
-`HelpCenterLookupTool` exposes exactly one operation to the model:
+An Agent is the smallest Assembly. Workflow, Swarm, and Graph coordinate several participants while preserving the same entrypoints:
 
 ```ruby
-class HelpCenterLookupTool < LittleGhost::Tool
-  description "Look up a help center entry by topic."
-  input_schema(
-    type: "object",
-    properties: {topic: {type: "string"}},
-    required: ["topic"],
-    additionalProperties: false
-  )
-
-  def call(input)
-    HelpCenterRepository.fetch(input.fetch("topic"))
-  end
-end
+CustomerSupportAgent.ask(question)
+ResponseWorkflow.ask(question)
+ProblemSolverSwarm.ask(question)
+SupportFlowGraph.ask(question)
 ```
 
-LittleGhost validates the model's input before invoking `#call`. Hashes and arrays returned by a tool are JSON-encoded; other values become text. Expected application failures can raise `LittleGhost::ToolError`; unexpected exception messages are sanitized before they reach model context.
+That shared calling style is what makes composition feel natural. A controller, job, or CLI does not need to know whether one Agent answered or a whole support process worked together.
 
-Validation is not authorization. A tool that reads customer records, writes files, executes processes, or calls a network service must enforce the application's trust rules itself. The built-in unrestricted sandbox executes with the Ruby process's permissions and is not a security boundary. Configure an isolated sandbox before exposing filesystem or shell tools to untrusted work.
+## Choose who controls the next step
 
-## Subagents are model-directed delegation
+The coordination types differ mainly in who decides what happens next:
 
-Declaring `ResearchAgent` as a subagent gives `CustomerSupportAgent` a configured set of tools for spawning, messaging, interrupting, waiting for, and listing research work:
+| Need | Choose | Who controls the next step? |
+| --- | --- | --- |
+| One model-driven behavior | Agent | The active model loop |
+| A model should delegate a named task | Subagent | The parent model |
+| Ruby should enforce ordering or branching | Workflow | The workflow's Ruby code |
+| Specialists should choose permitted handoffs | Swarm | The active agent |
+| Allowed routes should be visible in advance | Graph | Declared nodes and edges |
 
-```ruby
-class ResearchAgent < LittleGhost::Agent
-  description "Investigates support questions that need broader research."
-  model "customer_support.research"
-  system_prompt "Return a concise evidence summary."
-end
+### Subagents bring in a specialist
+
+A **subagent** is a specialist that a parent Agent can call for help. The parent model chooses when to delegate, reads the result, and then continues its own answer.
 
+```ruby
 class CustomerSupportAgent < LittleGhost::Agent
-  model "customer_support"
-  tools HelpCenterLookupTool
+  model "openrouter:openai/gpt-5.6-luna"
   subagent ResearchAgent, kind: "research"
 end
 ```
 
-The model decides whether to delegate and how to use the returned research. Each child declares its own tools, so access remains visible at the class receiving it. Subagent work can run concurrently and respects the configured turn, concurrency, depth, and time limits. Conversations can persist when a session store exists; `persist: false` keeps a declaration invocation-local.
+Use a subagent when delegation is part of one model's decision-making. Use a Workflow when application code must guarantee that a step happens.
 
-Use an agent as an ordinary tool with `agent_as_tool` when one request and one result is enough. Use a subagent when the parent needs an addressable worker with follow-ups, progress, interruption, or durable conversation identity.
+### Workflows make Ruby the coordinator
 
-## Workflows are application-directed composition
+A **Workflow** coordinates work with ordinary Ruby. Its `perform` method can call an Agent or another Assembly, read a result, choose a branch, or run independent steps together.
 
-Some customer support requests must always be researched before a response is written. Put that invariant in Ruby rather than asking the model to remember it:
+`invoke` prepares a lazy child call. Reading `.output` runs an intermediate child. Return the final `invoke` itself, without reading its output, so that answer can stream to the caller.
 
 ```ruby
 class ResponseWorkflow < LittleGhost::Workflow
@@ -150,9 +158,7 @@ class ResponseWorkflow < LittleGhost::Workflow
 
   def perform
     research = invoke(ResearchAgent).output
-
     invoke CustomerSupportAgent, input: <<~PROMPT
-      Customer request:
       #{input.text}
 
       Research:
@@ -162,62 +168,80 @@ class ResponseWorkflow < LittleGhost::Workflow
 end
 ```
 
-`#invoke` builds a lazy agent invocation. Calling `#output` consumes an intermediate invocation; `#perform` must return its final invocation unconsumed so LittleGhost can stream that agent to the original caller. Input, history, state, settings, cancellation, deadline, template values, and trace parentage flow through the workflow, while intermediate usage is added to the terminal result.
+Workflow children receive the caller's history and application context by default. Pass `history: []`, `context: {}`, or redacted values when a participant should receive less.
 
-A workflow is an explicit entrypoint on a run:
+### Swarms let agents hand work to one another
+
+A **Swarm** is a group of Agents that can hand work to one another. One member is active at a time. It can answer the caller or choose one of its allowed specialists.
 
 ```ruby
-runtime = LittleGhost::Runtime.new(configuration: LittleGhost.configuration)
-run = runtime.build_run(
-  {message: "Review this unusual refund request"},
-  agent_class: CustomerSupportAgent,
-  entrypoint_class: ResponseWorkflow
-).call
-
-puts run.response
+class ProblemSolverSwarm < LittleGhost::Swarm
+  member TriageAgent
+  member BillingAgent
+  member AccountAgent
+
+  start TriageAgent
+  handoff TriageAgent, to: [BillingAgent, AccountAgent]
+end
 ```
 
-Choose a subagent when delegation is part of the model's judgment. Choose a workflow when ordering and branching are application invariants. They can coexist: `ResponseWorkflow` can always collect baseline research, while `CustomerSupportAgent` can still delegate a new question that arises while drafting the response.
+A Swarm is intentionally agent-to-agent. Its members are Agents, not other kinds of Assembly. Caller history and application context stay hidden unless a member opts in. Treat every handoff message as untrusted model input.
 
-## Structured results separate data from prose
+### Graphs make routes visible
 
-An agent that feeds application code can declare a strict JSON object schema:
+A **Graph** connects named Assembly nodes with declared edges. Nodes can contain Agents, Workflows, Swarms, or other Graphs.
 
 ```ruby
-class ResearchAgent < LittleGhost::Agent
-  model "customer_support.research"
-  result_schema(
-    {
-      type: "object",
-      properties: {
-        summary: {type: "string"},
-        sources: {type: "array", items: {type: "string"}}
-      },
-      required: %w[summary sources],
-      additionalProperties: false
-    },
-    name: "support_research"
-  )
+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
 ```
 
-LittleGhost selects provider-native structured output when the resolved model advertises it, or a strict terminal tool when supported. The locally validated value is available through `RunResult#structured_result` and `RunResult#output`. Invalid output receives one repair attempt, then raises `LittleGhost::StructuredResultError`.
+Graph nodes do not receive caller history or application context unless they opt in. They still receive the original request and the outputs routed to them. Use edge input mappers to choose or redact what moves forward.
+
+## Class definitions first, builders when needed
+
+Named classes are the default way to organize reusable behavior. They are readable, load through normal Ruby conventions, and give the coordination style a visible name such as `ResponseWorkflow` or `SupportFlowGraph`.
 
-Use structured results when code consumes fields. Keep ordinary text when a human is the final consumer.
+Every assembly class can also produce a mutable builder:
 
-## Sessions preserve conversation, streams expose progress
+```ruby
+graph = SupportFlowGraph.to_builder
+graph.node :audit, AuditAgent
+graph.edge :respond, :audit
+graph.finish :audit
+graph.validate!
+run = graph.ask("Review order 481")
+```
 
-The default session store is in-memory. A configured `SessionStore` can load history and state before an agent runs and checkpoint coherent turns as work progresses. The application must supply stable session and actor identifiers when it wants continuity and isolation.
+Use a builder when trusted application configuration decides the participants or routes. Each run gets a fixed copy of the builder as it looked when the run began, so later edits affect later runs. Ruby callbacks still see any application objects they captured.
 
-Streams expose generic framework events rather than provider wire formats. Consumers can render text deltas, observe tool or subagent activity, collect usage, and react to terminal outcomes without coupling to OpenAI, OpenRouter, or Bedrock. The optional AG-UI adapter translates the same events at an interface boundary.
+## One result, including the journey
 
-## Keep the boundary visible
+Every assembly produces the same top-level `Run` and final `RunResult`. Composite assemblies also keep a size-limited record of the participants that ran:
+
+```ruby
+run = SupportFlowGraph.ask("Why was I charged twice?")
+
+run.response
+run.result.steps
+run.result.trajectory.transitions
+```
 
-The core design can be summarized as four choices:
+This shows callers which participants ran without including raw provider responses. A Swarm or Graph may hide intermediate model events from the public stream so the response stays coherent. That is a presentation choice, not a privacy boundary: routed outputs and step summaries still exist.
 
-- Put shared construction and provider policy in configuration; use inline declarations or independent YAML files according to the application's needs.
-- Put model behavior and available capabilities on agent classes.
-- Put privileged application operations behind narrow, authorized tools.
-- Put mandatory ordering in workflows; leave optional delegation to subagents.
+The pieces now fit together: Agents define behavior. Tools connect them to Ruby. Runs record one execution. Assemblies let the system grow without changing the caller.
 
-Return to [Getting Started](getting_started.md) for the complete first-run setup. The API reference covers exact signatures and lifecycle details for `LittleGhost::Runtime`, `LittleGhost::Run`, `LittleGhost::Agent`, `LittleGhost::Tool`, `LittleGhost::Workflow`, and `LittleGhost::ModelResolver`.
+Continue with [Compose Agents](assemblies.md) to put several agents to work together. If you are ready to connect the feature to a real application, jump to [Running in Production](production.md).