little_ghost 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 271908b0fc40900504fb25cd57d2cbcc8d987ac1ab32a0db58353562793446fc
-  data.tar.gz: 507e5d747e8b341dd60b1edce8811e0dc5b2d41f98cb970e801284b2a326a49f
+  metadata.gz: a7758c8ce1e1ee404d86fe7dd76065dbd983a0abb660cedd82f7a6ffac0a3509
+  data.tar.gz: 485a32b90c723ed4a3c8b064151495e92d8679527f408d39e91145c2f3aaea09
 SHA512:
-  metadata.gz: 830edf81e2d4892e7b72def07ba1d1be85843c8abf5cbb25d744ad520e8586fe9de2ae1cb32084ce832bb1eb866f4fa083af95b93e59df2b3e2c47f4e5c7aea9
-  data.tar.gz: a8dba3d880bdc6adc4271daac984f9ab6384d34520a5be2071e66d1d746f4979952c13e7743364e2de2f2c2aa721057e12e54ca29c83a382b6506e49889ee43e
+  metadata.gz: bb412e0ec1ff688067bdbb14d34e62a72713f617a4d487188ca40ef2d05c2b3c18262b6b9da1e286a977f8251fb65b4818078d4a044c2d9566b1836876634b6e
+  data.tar.gz: c79396a4608f4643415a0ac50ca30f23e7a26cc5688a8ac593bf6674e7d8005185068c6e6107f205d53c834289a4aac390350f3e4e5deffea72d57ed76bddb19

data/README.md

@@ -1,11 +1,16 @@
 # Build AI features that feel at home in Ruby
 
+LittleGhost is a Ruby library for adding AI features to an existing application
+or building a dedicated AI service. An **agent** combines a model with
+instructions and Ruby operations it can call. Agents can work together in an
+**assembly**, which your application calls like a single agent.
+
 > **Using a coding agent?** Start with
 > [`llms.txt`](https://littleghostai.org/llms.txt) for a concise map
 > of the guides and API. [`llms-full.txt`](https://littleghostai.org/llms-full.txt)
 > contains the complete documentation in one file.
 
-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:
+With the gem installed and `OPENROUTER_API_KEY` set, start with one class:
 
 ```ruby
 require "little_ghost"
@@ -68,7 +73,9 @@ The source checkout also includes a complete
 [single-file Agent](https://github.com/littleghostai/little_ghost/tree/main/examples/basic_agent)
 and
 [coding harness](https://github.com/littleghostai/little_ghost/tree/main/examples/coding_harness),
-both configured for local Ollama.
+both configured for local Ollama. The
+[decision example](https://github.com/littleghostai/little_ghost/tree/main/examples/decision)
+shows typed questions with Jev through OpenRouter.
 
 ## Give an agent real capabilities
 
@@ -100,14 +107,13 @@ end
 The schema checks the shape of the input. Your Ruby code still decides whether
 the operation is allowed. The result goes back to the model as context.
 
-An ordinary Tool runs in your Ruby process. When a Tool needs files or child
-processes, it can delegate that work through a Sandbox. Code mode goes one step
-further: a sandboxed interpreter can compose several Tools, while every Tool
-call still returns to your Ruby Tool for validation and permission checks.
+An ordinary Tool runs in your Ruby process. For operations that need files or
+child processes, see [Workspaces and Sandboxes](docs/guides/sandboxing.md).
 
 ## 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:
+When a task needs several agents, choose how they work together. These example
+classes use different coordination styles, but their callers all use `.ask`:
 
 ```ruby
 CustomerSupportAgent.ask(question)
@@ -118,12 +124,12 @@ SupportFlowGraph.ask(question)
 
 Choose the coordination style that matches who should control the next step:
 
-- A **subagent** lets a model delegate an addressable task.
+- A **subagent** is a specialist an agent can ask for help.
 - 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.
 
-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.
+A Workflow or Graph can contain agents, other assemblies, or both.
 
 ```text
 request ──> CustomerSupportAgent
@@ -137,7 +143,9 @@ request ──> SupportFlowGraph ──> TriageAgent ──edge──> ResponseA
 
 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.
+participants ran. Use `.stream_ask` to watch the work as it happens and choose
+which participants to display. [Getting Started](docs/guides/getting_started.md)
+shows how to stream an Agent's answer and read the completed result.
 
 LittleGhost is pre-1.0. Pin the gem version and review release notes before
 upgrading, because interfaces may change between releases.
@@ -154,6 +162,8 @@ upgrading, because interfaces may change between releases.
 - [Structured Results and Content](docs/guides/structured_outputs_and_content.md) covers checked result shapes, images, and documents.
 - [Compose Agents](docs/guides/assemblies.md) walks through workflows, swarms, graphs, nesting, and builders.
 - [Skills](docs/guides/skills.md) organizes reusable instructions and supporting resources.
+- [Decisions](docs/guides/decisions.md) explains typed questions and structured answers.
+- [Embeddings](docs/guides/embeddings.md) explains text representations for similarity-based features.
 - [Workspaces and Sandboxes](docs/guides/sandboxing.md) gives files and child processes a deliberate place to run.
 - [Code Mode](docs/guides/code_mode.md) lets a model compose Tools in sandboxed Ruby or optional JavaScript.
 - [Integrations](docs/guides/integrations.md) connects Run streams to AG-UI and OpenTelemetry.

data/docs/guides/assemblies.md

@@ -15,7 +15,12 @@ run = entrypoint.ask(question)
 
 ## 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, or return a value that Ruby computes from the intermediate answers.
+A Workflow's `perform` method is ordinary Ruby. Inside it, `invoke` prepares a
+child call. Read `.output` for its text or structured answer, or `.result` for
+the complete `RunResult`. Return an invocation to select its answer as the
+Workflow result. You can inspect that answer first, or return a value that Ruby
+computes from intermediate answers. Every participating Agent publishes live
+progress regardless of how you access or select results.
 
 ```ruby
 class ResponseWorkflow < LittleGhost::Workflow
@@ -41,7 +46,7 @@ Every participant passed to `invoke` can be an Agent or another Assembly. By def
 
 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 when its events should become the Workflow's public stream. Return that `invoke` without consuming it:
+When one child should supply the final answer, return its invocation:
 
 ```ruby
 def perform
@@ -49,6 +54,38 @@ def perform
 end
 ```
 
+To inspect an answer before selecting it, keep the invocation, read its output,
+and return the same invocation after your checks. For example, given a
+`ReviewAgent` whose structured result includes an `approved` boolean:
+
+```ruby
+class ReviewedResponseWorkflow < LittleGhost::Workflow
+  private
+
+  def perform
+    candidate = invoke(CustomerSupportAgent)
+    review = invoke(ReviewAgent, input: candidate.output, history: [], context: {}).output
+
+    review.fetch("approved") ? candidate : invoke(EscalationAgent)
+  end
+end
+```
+
+Returning the candidate does not repeat the work or replay its text. The final
+result preserves its conversation, state, and structured value. Usage and steps
+include both the candidate and the review. Repeated `.result` or `.output` reads
+reuse the completed result. An invocation must belong to the workflow returning
+it and must complete successfully.
+
+You can watch each Agent while the Workflow runs, including while an answer is
+being reviewed. Reviewing an answer does not hide its progress. Choose which
+participants your audience may see, as described in
+[Watch every agent](#watch-every-agent-in-an-assembly).
+
+Cancellation and deadlines apply before each child runs and before the Workflow
+returns its answer. They also apply if a checkpoint callback cancels the run or
+finishes after the deadline.
+
 When Ruby should compute the caller-visible result, consume every child and return the computed value:
 
 ```ruby
@@ -67,11 +104,11 @@ class EvidenceWorkflow < LittleGhost::Workflow
 end
 ```
 
-A returned String becomes the Workflow's textual response. Arrays, mappings, numbers, and booleans become a structured result available through `RunResult#output`, including when the Workflow is exposed with `assembly_as_tool`. Direct structured results must be JSON-compatible and stay within LittleGhost's structured-result size, depth, and complexity limits. Return an explicit value: `nil` remains a `ProtocolError`, which catches forgotten returns.
+A returned String becomes the Workflow's textual response. Arrays, mappings, numbers, and booleans become a structured result available through `RunResult#output`, including when the Workflow is exposed with `assembly_as_tool`. Computed values appear in the final result, not as synthetic text-delta events. Direct structured results must be JSON-compatible and stay within LittleGhost's structured-result size, depth, and complexity limits. Return an explicit value: `nil` remains a `ProtocolError`, which catches forgotten returns.
 
 ### Choose a branch in Ruby
 
-Each branch should end with its final unconsumed invocation or a directly computed value:
+Each branch should end with its final invocation or a directly computed value:
 
 ```ruby
 class RoutedResponseWorkflow < LittleGhost::Workflow
@@ -305,7 +342,9 @@ Retries start at zero. When `retries` is greater than zero, `retry_on` must list
 
 ## Watch every agent in an assembly
 
-Follow each participant while a composite assembly runs by handling its contextual `:agent_stream` events. These events arrive alongside the coherent public answer and assembly lifecycle events:
+Follow each participant by handling source-tagged `:agent_stream` events. Every
+Run uses this same progress channel, from one root Agent to nested assemblies
+and subagents. Lifecycle events and the final result remain separate:
 
 ```ruby
 stream = SupportFlowGraph.stream_ask("Why was I charged twice?")
@@ -333,19 +372,31 @@ run.completed? # => true
 
 `source.agent_id` identifies the Agent class, `source.agent_path` distinguishes managed subagents, and `source.operation_id` groups one invocation. `source.assembly_path` lists the enclosing Workflow, Swarm, or Graph steps from the outside inward.
 
+An Agent or Assembly invoked as a Tool within the Run adds a `:tool` step to that path. The
+step identifies the invoking Agent and Tool name, and its descendants retain
+the boundary. Tool-invoked Agents therefore remain distinct from the root
+Agent even when their managed-subagent path is `/root`.
+
 The routed input and inner event are copied and frozen before they reach the
 observer, so changing an event can't affect the running assembly. Parallel
 participants can interleave. Events from each Agent retain their order, and
 LittleGhost never calls the stream block concurrently.
 
-The contextual wrapper arrives before the corresponding ordinary event. An assembly's final Agent therefore appears through both projections. Filter for `:agent_stream` when building an all-agent view, or handle ordinary events when rendering only the final answer. Pass `include_agent_events: false` when a composite assembly caller only wants the ordinary public stream. Standalone Agent streams keep their ordinary events by default and accept `include_agent_events: true` when source metadata is useful.
+Agent progress appears only through `:agent_stream`, without duplicate raw
+events. Returning an invocation selects its result; it does not replay that
+Agent's progress. Handle the terminal Run event or read `run.result` for the
+complete answer and aggregate usage. Pass `include_agent_events: false` to omit
+all Agent progress without changing execution, lifecycle events, or results.
 
-The AG-UI adapter ignores contextual wrappers. Translate them explicitly if an AG-UI client should receive participant activity.
+The [AG-UI adapter](integrations.md) displays root Agent progress by default.
+Supply its `source_filter:` callable when a client should see selected assembly
+participants.
 
-> **Safety note:** A composite stream can include inputs, reasoning, Tool
-> arguments and results, errors, and output from every participant. Check that
-> the destination may see the complete Run, or filter the events before sending
-> or storing them.
+> **Safety note:** Every Run stream can include inputs, reasoning, Tool arguments
+> and results, errors, and private output from nested participants. The example
+> above observes the complete Run. Before sending or storing events for a
+> narrower audience, select allowed sources and filter their fields. Result
+> selection does not authorize disclosure of a participant's progress.
 
 ## Inspect what the assembly did
 
@@ -362,7 +413,8 @@ 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
+The trajectory retains step outputs, not a transcript of streaming events.
+Step outputs and final results have size limits. Use your application's
 instrumentation when you need deeper diagnostics.
 
 ## Compose assemblies inside assemblies

data/docs/guides/core_concepts.md

@@ -1,6 +1,9 @@
 # Core Concepts
 
-Define an Agent in a Ruby class, then call it with `.ask`.
+Start with an Agent: a Ruby class that gives a model instructions and operations
+it can call. This guide builds on the help center example in
+[Getting Started](getting_started.md), including its `HelpCenterLookupTool` and
+provider setup.
 
 ```ruby
 class CustomerSupportAgent < LittleGhost::Agent
@@ -9,16 +12,20 @@ class CustomerSupportAgent < LittleGhost::Agent
   tools HelpCenterLookupTool
 end
 
-run = CustomerSupportAgent.ask("Where is my order?")
+run = CustomerSupportAgent.ask("What is the refund policy?")
 run.response
 ```
 
 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.
 
-## An Agent owns one model loop
+## An Agent carries a request through to an answer
 
 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 model can answer immediately or ask to call a Tool. LittleGhost runs the
+Tool and sends its result back to the model, which can continue working. That
+back-and-forth is the **model loop**.
+
 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
@@ -60,71 +67,32 @@ inside the Tool using identity and account information from your application.
 [Tools](tools.md) follows that path from model input to application code,
 including run-scoped bindings, concurrency, retries, and sandbox delegation.
 
-## A Run owns one top-level execution
+## A Run records one request
 
 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
-run = CustomerSupportAgent.ask("Where is order 481?")
+run = CustomerSupportAgent.ask("What is the refund policy?")
 
 run.completed? # => true
 run.response
-# One possible response: Order 481 is out for delivery.
-run.usage      # => normalized token usage
+# One possible response: Refunds are available within 30 days.
+run.usage      # Token counts reported by the model provider.
 run.result     # => the complete LittleGhost::RunResult
 ```
 
 The Agent defines reusable behavior; the Run records what happened this time.
 
-### Follow one request
-
-One Run owns the trip from request to result:
-
-```text
-Run
-├── Invocation: caller input, history, and application context
-├── RunContext: mutable working state for this execution
-└── Agent and Tools ──> RunResult
-```
-
-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 checks permission.
-
-A **Session** stores conversation state between Runs when persistence is
-configured. The **RunContext** carries mutable working state in `context.state`
-during one Run. LittleGhost loads saved Session state before adding the current
-Invocation context. Recheck saved values before using them for permission
-decisions.
-
-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 arguments chosen by the model. [Tools](tools.md) explains the binding;
-[Workspaces and Sandboxes](sandboxing.md) explains delegated files and child
-processes.
-
-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.
-
-### See how a call ended
-
-Top-level calls normally return a Run, even when execution fails. The terminal event carries the same outcome when you stream:
+The final **RunResult**, available through `run.result`, holds the answer and
+details such as token usage. Its `output` returns text unless you configured
+the Agent to return checked data, such as a hash of named fields. See
+[Structured Results and Content](structured_outputs_and_content.md) for that
+alternative. Use `run.response` when you want the text answer.
 
-| 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 |
-
-Unexpected Tool exception messages are hidden from the model. The original
-exception remains available to application callbacks and diagnostics.
-
-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 supervision and shutdown.
+When a Tool needs to know who is asking, pass information from your application
+with the request. [Tools](tools.md) explains how it reaches the Tool. When a
+conversation should continue across requests, a **Session** saves its history
+and working state; [Running in Production](production.md) covers that setup.
 
 ## An Assembly can look like one Agent
 
@@ -157,6 +125,10 @@ The coordination types differ mainly in who decides what happens next:
 
 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.
 
+The examples below omit the specialist Agent definitions. Each is an Agent
+class like `CustomerSupportAgent`, with instructions and tools suited to its
+task. [Compose Agents](assemblies.md) expands on these coordination patterns.
+
 ```ruby
 class CustomerSupportAgent < LittleGhost::Agent
   model "openrouter:openai/gpt-5.6-luna"
@@ -166,15 +138,13 @@ end
 
 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.
 
-When an Agent also uses code mode, subagent controls stay in the Agent's
-conversation. Code-mode programs can compose ordinary Tools, while spawning,
-messaging, and checking on subagents remain decisions for the parent model.
-
 ### Workflows make Ruby the coordinator
 
 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.
 
-`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.
+`invoke` prepares a participant's call without running it yet. Read `.output`
+to run it and use its answer in Ruby. Return the final `invoke` call to use
+that participant's answer as the Workflow's result.
 
 ```ruby
 class ResponseWorkflow < LittleGhost::Workflow
@@ -192,6 +162,13 @@ class ResponseWorkflow < LittleGhost::Workflow
 end
 ```
 
+In this example, research finishes before the support Agent begins. `input.text`
+is the original question; the Workflow adds the research to it.
+
+You can also inspect an answer before choosing it as the final result, without
+running the participant again. [Compose Agents](assemblies.md) shows how, along
+with ways to display each participant's progress.
+
 Workflow children receive the caller's history and application context by default. Pass `history: []`, `context: {}`, or redacted values when a participant should receive less.
 
 ### Swarms let agents hand work to one another
@@ -216,7 +193,8 @@ Agent should use it as context rather than proof that an action is permitted.
 
 ### Graphs make routes visible
 
-A **Graph** connects named Assembly nodes with declared edges. Nodes can contain Agents, Workflows, Swarms, or other Graphs.
+A **Graph** lays out the steps and routes through a task. Each named **node**
+runs an Agent or another Assembly. An **edge** says which node can run next.
 
 ```ruby
 class SupportFlowGraph < LittleGhost::Graph
@@ -236,6 +214,10 @@ class SupportFlowGraph < LittleGhost::Graph
 end
 ```
 
+Here, `TriageAgent` is expected to answer `billing` for billing questions.
+That answer selects the conditional billing route. Otherwise, the unconditional
+general route is the fallback; it does not run alongside the billing route.
+
 Graph nodes receive the original task and results from the nodes immediately
 before them. They do not receive caller history or application context unless
 their declarations opt in. [Compose Agents](assemblies.md) explains parallel
@@ -256,6 +238,28 @@ run.result.trajectory.transitions
 This record shows which participants ran. [Compose Agents](assemblies.md)
 explains builders, detailed routing records, and live events from nested Agents.
 
+## Handle the outcome
+
+An Agent or coordinated Assembly normally returns a Run even when the work
+fails. Check its outcome before using the answer:
+
+| What happened | Run outcome | What to inspect |
+| --- | --- | --- |
+| Work completed | `completed` | `run.response` or `run.result` |
+| Model, provider, or assembly execution failed | `failed` | `run.error` |
+| The deadline stopped work | `partial` | Any response produced so far |
+| Cancellation stopped work | `cancelled` | No response is returned |
+
+A Tool error need not end the Run: LittleGhost can give the model a safe error
+result so it can try again. Unexpected exception messages stay in application
+diagnostics rather than going to the model.
+
+Some failures raise Ruby exceptions instead of returning a Run, including
+invalid setup before work starts and failures while closing resources or
+delivering events. [Running in Production](production.md) covers error handling
+and shutdown; [Run](rdoc-ref:LittleGhost::Run) lists the streaming events for
+each outcome.
+
 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.
 
 Continue with [Models and Providers](models_and_providers.md) to choose model

data/docs/guides/decisions.md

@@ -0,0 +1,69 @@
+# Decisions
+
+Use a decision model when an application needs typed answers to a small set of
+questions. `LittleGhost.decide` returns the answers and token usage without
+starting an Agent or creating a Run. Jev supports Choice, Score, and Noul
+(yes/no probability) questions:
+
+```ruby
+result = LittleGhost.decide(
+  model: "primary:~typesafe/jev-latest",
+  state: {payout_status: "failed", failed_days: 3},
+  questions: [
+    {
+      id: "route",
+      type: :choice,
+      instructions: "Choose a route",
+      criteria: {
+        review: "Needs more investigation",
+        approve: "Meets the criteria",
+        decline: "Does not meet the criteria"
+      }
+    },
+    {id: "urgent", type: :noul, instructions: "Does this need same-day attention?"}
+  ]
+)
+
+result.answers.fetch("route").choice
+result.answers.fetch("urgent").noul
+```
+
+Choice answers contain the selected label. Noul answers contain the
+probability of yes from 0 to 1. Score answers contain a probability-weighted
+value across the declared levels. Choice and Score answers also include the
+probability distribution and confidence; Score answers include the level
+legend.
+
+For reusable decisions, declare questions once on a `Decision` class. A class
+can mix question types:
+
+```ruby
+class ApplicationTriage < LittleGhost::Decision
+  model "primary:~typesafe/jev-latest"
+  choice :route, instructions: "Choose a route", criteria: {
+    review: "Needs more investigation",
+    approve: "Meets the criteria",
+    decline: "Does not meet the criteria"
+  }
+  noul :urgent, instructions: "Does this need same-day attention?"
+  score :quality, instructions: "Rate the quality", criteria: ["accuracy", "completeness"]
+end
+
+application_state = {payout_status: "failed", failed_days: 3}
+result = ApplicationTriage.ask(application_state)
+result.answers.fetch("quality").score
+```
+
+The class-level `.ask` and an instance's `#ask` return
+`LittleGhost::DecisionResult`. Read a typed value with
+`LittleGhost::DecisionAnswer#value` or its type-specific reader (`choice`,
+`noul`, or `score`).
+
+The selected provider receives the state and question text. Choose a provider
+that is appropriate for that data.
+
+Decisions require a TypeSafe connection or an OpenRouter connection configured
+for a Jev decision endpoint. Other providers raise
+`UnsupportedModelOperationError`. See [Provider Support](providers.md) for
+connection setup and [Models and Providers](models_and_providers.md) for model
+targets, shared roles, and capabilities.

data/docs/guides/embeddings.md

@@ -0,0 +1,23 @@
+# Embeddings
+
+Use `LittleGhost.embed` to turn text into numeric representations for search,
+clustering, or another similarity-based feature:
+
+```ruby
+response = LittleGhost.embed(
+  model: "primary:openai/text-embedding-3-small",
+  inputs: ["Reset a password", "Track a transfer"]
+)
+
+response.vectors.length # => 2
+response.dimensions
+response.usage.input_tokens
+```
+
+The response keeps vectors in the same order as the inputs. LittleGhost rejects
+an incomplete or malformed response instead of returning a partial batch.
+Embedding text is sent to the selected provider, so choose one appropriate for
+that data. [Provider Support](providers.md) identifies adapters with embedding
+support; `LittleGhost::Embeddings::Request` documents settings and request
+bounds. See [Models and Providers](models_and_providers.md) for model targets,
+shared roles, and capabilities.