little_ghost 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d214ff7dd49c056712968000f9ddc127bc132dd4b97b8f0c89bb3adb2f52f3b0
-  data.tar.gz: de2f85339390969db2ae0863bf9056ab386b07e2bf05cc976f23899ae2b318d2
+  metadata.gz: 271908b0fc40900504fb25cd57d2cbcc8d987ac1ab32a0db58353562793446fc
+  data.tar.gz: 507e5d747e8b341dd60b1edce8811e0dc5b2d41f98cb970e801284b2a326a49f
 SHA512:
-  metadata.gz: 48004e9b2b4c826877601f31681129f5f0434f544aa979941d2d09840ca677ccbf86e0334cdd9de60081601e039326d445a033064940049dbd3f5e27243f47ac
-  data.tar.gz: 88fc87d32cb553b047273e249685f410ff8721e32275a3f3800e00cd79a674fb43188b0ef34d2b0a2ca04c4502a18503a6da791d2634ec92f4bc539d665ad36a
+  metadata.gz: 830edf81e2d4892e7b72def07ba1d1be85843c8abf5cbb25d744ad520e8586fe9de2ae1cb32084ce832bb1eb866f4fa083af95b93e59df2b3e2c47f4e5c7aea9
+  data.tar.gz: a8dba3d880bdc6adc4271daac984f9ab6384d34520a5be2071e66d1d746f4979952c13e7743364e2de2f2c2aa721057e12e54ca29c83a382b6506e49889ee43e

data/README.md

@@ -20,7 +20,9 @@ run.response
 # One possible response: Hi! How can I help today?
 ```
 
-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.
+That definition is a complete Agent. LittleGhost makes the model call, tracks
+usage, supports streaming, and closes request resources. Add a Tool for
+application capabilities or an Assembly as the work grows.
 
 Model requests may send system instructions, caller input, conversation history,
 Tool results, and attachments to the selected provider. Model wording can vary
@@ -40,9 +42,33 @@ $ 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.
+The introductory guides use OpenRouter so you can start with one key. Prefer
+another hosted provider or a local Ollama or LM Studio server? See [Provider
+Support](docs/guides/providers.md).
 
-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`.
+LittleGhost runs inside your Ruby process. Use it from a controller, job, CLI,
+or service.
+
+## Generate a small application
+
+Generate a conventional standalone application:
+
+```sh
+$ gem install little_ghost
+$ little_ghost new MyApp
+$ cd my_app
+$ export OPENROUTER_API_KEY="..."
+$ bin/little_ghost console
+```
+
+The generator installs the bundle. `bin/little_ghost console` runs that
+bundle's LittleGhost version and loads the application before starting IRB.
+
+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.
 
 ## Give an agent real capabilities
 
@@ -120,15 +146,17 @@ upgrading, because interfaces may change between releases.
 
 - [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.
-- [Models and Providers](docs/guides/models_and_providers.md) gives shared model choices application-facing names.
-- [Prompts as Views](docs/guides/prompt_views.md) gives growing instructions, shared pieces, and application values a natural home.
+- [Models and Providers](docs/guides/models_and_providers.md) explains targets, shared roles, and per-request model selection.
+- [Provider Support](docs/guides/providers.md) has copyable setup for hosted APIs and local model servers.
+- [Prompts as Views](docs/guides/prompt_views.md) explains Agent instructions and shared partials, including how to customize LittleGhost's bundled framework prompts.
 - [Tools](docs/guides/tools.md) explains how models call focused Ruby operations.
+- [MCP](docs/guides/mcp.md) connects agents to operations published through the Model Context Protocol.
 - [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.
 - [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 MCP, AG-UI, and OpenTelemetry.
+- [Integrations](docs/guides/integrations.md) connects Run streams to AG-UI and OpenTelemetry.
 - [Running in Production](docs/guides/production.md) covers configuration, saved conversations, supervision, and observability.
 - [API reference](rdoc-ref:LittleGhost) provides exact method signatures and ownership rules.
 

data/docs/guides/assemblies.md

@@ -15,7 +15,7 @@ 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.
+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.
 
 ```ruby
 class ResponseWorkflow < LittleGhost::Workflow
@@ -41,25 +41,37 @@ 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 because its events become the Workflow's public stream. Return that `invoke` without consuming it:
+The last child is special when its events should 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
+  invoke CustomerSupportAgent
 end
+```
 
-# Right: this returns the lazy invocation itself.
-def perform
-  invoke CustomerSupportAgent
+When Ruby should compute the caller-visible result, consume every child and return the computed value:
+
+```ruby
+class EvidenceWorkflow < LittleGhost::Workflow
+  private
+
+  def perform
+    findings = parallel(
+      invoke(LedgerResearchAgent),
+      invoke(PolicyResearchAgent),
+      max_concurrency: 2
+    )
+
+    {"findings" => findings}
+  end
 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.
+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.
 
 ### Choose a branch in Ruby
 
-Each branch should end with its final unconsumed invocation:
+Each branch should end with its final unconsumed invocation or a directly computed value:
 
 ```ruby
 class RoutedResponseWorkflow < LittleGhost::Workflow

data/docs/guides/code_mode.md

@@ -274,5 +274,5 @@ engine, but the generated program then has the same host access as the parent.
 
 See `LittleGhost::CodeMode::Engine`, `LittleGhost::CodeMode::Session`, and
 `LittleGhost::CodeMode::ProgramResult` for the extension contract. Continue
-with [Integrations](integrations.md) to connect Runs to MCP tools, AG-UI, and
-OpenTelemetry.
+with [MCP](mcp.md) to add operations from a remote server, or
+[Integrations](integrations.md) to connect Runs to AG-UI and OpenTelemetry.

data/docs/guides/getting_started.md

@@ -17,7 +17,8 @@ $ export OPENROUTER_API_KEY="..."
 
 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).
+This guide uses OpenRouter to keep setup to one key. Prefer another hosted
+provider or a local model server? Start with [Provider Support](providers.md).
 
 ## See your first answer
 
@@ -196,11 +197,35 @@ app/
 │   └── response_workflow.rb
 ├── prompts/
 │   └── customer_support/
-│       └── system.erb
+│       └── system_prompt.erb
 └── tools/
     └── help_center_lookup_tool.rb
 ```
 
+To generate this layout for a standalone application, install the gem and run
+`little_ghost new`:
+
+```sh
+$ gem install little_ghost
+$ little_ghost new MyApp
+$ cd my_app
+$ export OPENROUTER_API_KEY="..."
+$ bin/little_ghost console
+```
+
+The generator creates `my_app` with one Agent, a prompt view, configuration,
+the conventional application directories, an installed bundle, and a local
+LittleGhost command. `bin/little_ghost console` uses the generated
+application's bundle, loads its configuration and classes, and then starts
+IRB.
+
+The source repository also contains a complete
+[single-file Agent](https://github.com/littleghostai/little_ghost/tree/main/examples/basic_agent)
+and a
+[coding harness](https://github.com/littleghostai/little_ghost/tree/main/examples/coding_harness)
+that demonstrates Agents, prompt views, Tools, a Graph, a Workspace, and a
+native Sandbox.
+
 You now have the smallest useful LittleGhost application: one Agent, one Tool, and one familiar Ruby call.
 
 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

@@ -1,149 +1,8 @@
-# Connect MCP, AG-UI, and OpenTelemetry
+# Connect Runs to interfaces and tracing
 
-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.
+Use AG-UI to stream Run events to an interactive client. Use OpenTelemetry to
+publish traces to the backend your application already uses. Neither changes
+the Agent that produced the Run.
 
 ## Send a Run stream through AG-UI
 
@@ -168,13 +27,13 @@ events = LittleGhost::AGUI::Adapter.new.stream(
 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, backpressure, disconnect
-behavior, and any request state its callbacks need.
+The adapter translates the full Run, including model output, Tool activity,
+retries, subagent activity, and the final outcome. It does not keep state between
+calls. Your application owns the connection, backpressure, disconnect behavior,
+and any request state its callbacks need.
 
-LittleGhost also emits namespaced custom events. Consumers should preserve or
-deliberately ignore event types they don't recognize. See the [AG-UI event
+LittleGhost may emit event types beyond the core AG-UI set. Decide whether the
+client preserves or ignores types it does not recognize. See the [AG-UI event
 documentation](https://docs.ag-ui.com/concepts/events) when implementing the
 client.
 
@@ -183,8 +42,8 @@ client.
 > see the complete Run, then filter fields before sending or storing events.
 
 Calling `each` drives the source stream on the caller's fiber or 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.
+client disconnects, stop enumerating and decide whether the application should
+cancel the Run. Closing the socket cannot undo Tool work that already ran.
 
 ## Trace Runs with OpenTelemetry
 
@@ -197,9 +56,9 @@ LittleGhost.configure do |config|
 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
+LittleGhost includes the `opentelemetry-api` integration. Your application
+chooses the SDK, processor, and exporter. The subscriber emits spans and events
+for Runs, model calls, Tools, assemblies, sessions, usage, and failures, and it
 can propagate W3C `traceparent` and `tracestate` fields.
 
 Prompts, messages, responses, Tool arguments, and exception content are omitted
@@ -209,9 +68,9 @@ 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.
+apply. If the tracing backend buffers data, flush or shut down
+`LittleGhost::Instrumentation` before the application exits.
 
-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.
+See [Running in Production](production.md) for startup, shutdown, and
+observability, [MCP](mcp.md) for operations published by remote servers,
+and [Workspaces and Sandboxes](sandboxing.md) for child processes and files.