little_ghost 0.7.0 → 0.8.0

data/docs/guides/models_and_providers.md

@@ -62,11 +62,11 @@ run = CustomerSupportAgent.ask(
 Build these settings in application code instead of passing request parameters
 through unchanged. Settings can affect cost, latency, and model behavior.
 
-## Configure connections in one place
+## Connect the provider you chose
 
-LittleGhost includes adapters for OpenRouter, OpenAI-compatible APIs,
-Anthropic, Gemini, Vertex AI, and Bedrock. Connections may live in an
-initializer or in the conventional files under `config/little_ghost`.
+Connections may live in an initializer or in the conventional files under
+`config/little_ghost`. [Provider Support](providers.md) has copyable settings
+for each built-in adapter, compatible endpoints, Ollama, and LM Studio.
 
 Keep credentials in your application's secret manager. Agents refer to a role
 or configured connection; they don't need to contain credentials. If your
@@ -120,6 +120,11 @@ choose a structured-result strategy.
 Provider capabilities can change. Handle failed Runs and provider errors even
 when the catalog says a feature is supported.
 
+Most application code does not call the resolver directly. Declaring an
+Agent's model, or passing `model:` to generation or embedding, resolves the
+selection for you. Inspect model details when an interface needs to explain
+limits or your application wants to check an attachment before sending it.
+
 ## Call a model without an Agent
 
 Some application work needs one model response rather than an Agent. Use
@@ -141,57 +146,23 @@ response.usage.total_tokens
 ```
 
 The operation returns a `LittleGhost::RunResult`, the same result type returned
-by an Agent invocation, so
-application code can read `output`, `usage`, and the final message in the same
-way. Plain generation makes one model request without starting an Agent or
-creating a Run. Structured generation may make one additional repair request.
-
-Pass a strict object schema when application code needs checked JSON:
+by an Agent invocation. Application code can read `output`, `usage`, and the
+final message in the same way. Plain generation makes one model request without
+starting an Agent or creating a Run.
 
-```ruby
-response = LittleGhost.generate(
-  model: :customer_support,
-  messages: [{role: :user, content: "My transfer is still pending."}],
-  result_schema: {
-    name: "classification",
-    description: "Classify one support request",
-    schema: {
-      type: "object",
-      properties: {category: {type: "string"}},
-      required: ["category"],
-      additionalProperties: false
-    }
-  }
-)
-
-response.output
-```
-
-LittleGhost checks the result against the schema and gives the model one repair
-attempt by default. Add `structured_result_repair_attempts: 3` to the call
-above when a checked result warrants additional attempts. The setting accepts
-integers from zero through three.
-
-Read the checked value through `response.output`. If every permitted attempt is
-invalid, the call raises `LittleGhost::StructuredResultError`.
-
-A schema checks the shape of a value, not whether your application should act
-on it. Check identifiers, permissions, and business rules before using the
-result to change application state.
+Pass `result_schema:` when application code needs checked JSON. [Structured
+Results and Content](structured_outputs_and_content.md) covers strict schemas,
+provider strategies, repair behavior, and the application checks that still
+belong outside the schema.
 
 ## Create embeddings
 
 Use `LittleGhost.embed` when your application needs numeric representations for
 search, clustering, or another similarity-based feature:
 
-The example assumes application startup maps `search_embeddings` to an
-embedding model, following the role configuration shown earlier on this page.
-The selected provider adapter's API reference lists the model-specific
-settings.
-
 ```ruby
 response = LittleGhost.embed(
-  model: :search_embeddings,
+  model: "primary:openai/text-embedding-3-small",
   inputs: ["Reset a password", "Track a transfer"]
 )
 
@@ -202,14 +173,10 @@ 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.
-Choose the embedding model and request settings in trusted application
-configuration, and keep each call within a workload size your application can
-retry safely.
-
-Embedding text is sent to the selected provider. Choose a provider that is
-appropriate for that data, just as you would for an Agent request. See
-`LittleGhost::Embeddings::Request` and your provider adapter's API reference for
-the supported settings and request bounds.
+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.
 
 Continue with [Prompts as Views](prompt_views.md) when an Agent's instructions
 outgrow one string. See [Structured Results and Content](structured_outputs_and_content.md)

data/docs/guides/production.md

@@ -37,7 +37,15 @@ class CustomerSupportAgent < LittleGhost::Agent
 end
 ```
 
-Provider connections and model roles can also live in YAML files under `config/little_ghost`, or in files you select explicitly. Values set in Ruby take priority. An explicitly selected file comes next, followed by conventional files and environment defaults. See `LittleGhost::Configuration` when you need every supported source and override.
+Provider connections and model roles can live in the Ruby initializer or in
+YAML under `config/little_ghost`. Values set in Ruby take priority. See
+`LittleGhost::Configuration` for custom files and the full precedence order.
+
+[Provider Support](providers.md) lists the credentials and endpoint settings
+for hosted and local providers. Choose connection names, model identifiers,
+and custom headers during application startup. Read secrets from deployment
+configuration or a secret manager; do not copy request parameters into these
+settings.
 
 Prompts, caller input and history, Tool results, and attachments may go to the
 selected provider. Choose configured providers that are appropriate for that
@@ -289,14 +297,15 @@ LittleGhost.configure do |config|
   end
   config.sandbox = {
     provider: :native,
-    files: {root: :read_write},
-    root_filesystem: :isolated,
-    environment: {inherit: false, set: {"LANG" => "C.UTF-8"}},
-    network: :none
+    files: {root: :read_write}
   }
 end
 ```
 
+The native backend isolates the host root, removes child-process network
+access, and starts with a scrubbed child environment unless you configure a
+different policy.
+
 The temporary Workspace above is useful when files should live for one Run. Use application-managed storage, with tenant isolation and concurrency control, when files must persist or several Runs share a root.
 
 The Run opens a Runtime-created Workspace before its Sandbox and closes them in reverse order after every outcome. Closing a Workspace invokes its configured teardown; it does not delete files by default. Cleanup failures raise because LittleGhost cannot confirm a clean shutdown of every owned resource. Existing instances passed by the application remain caller-owned.

data/docs/guides/providers.md

@@ -0,0 +1,275 @@
+# Provider Support
+
+Use this page to connect a hosted provider or local model server. If you are
+still deciding how Agents should choose models, start with [Models and
+Providers](models_and_providers.md).
+
+## Compare provider support
+
+Every connection uses the same configuration shape:
+
+```ruby
+LittleGhost.configure do |config|
+  config.providers = {
+    primary: {
+      adapter: :openrouter,
+      api_key: ENV.fetch("OPENROUTER_API_KEY")
+    }
+  }
+end
+```
+
+`primary` is a name chosen by the application, and `adapter` selects the wire
+protocol. An Agent can now use a target such as
+`primary:openai/gpt-5.6-luna`.
+
+| Provider or endpoint | Adapter | Generation | Embeddings |
+| --- | --- | --- | --- |
+| OpenRouter | `:openrouter` | Chat Completions | When the model supports it |
+| OpenAI | `:openai` | Responses or Chat Completions | Yes |
+| Compatible API | `:openai_compatible` | Responses or Chat Completions | When the endpoint implements it |
+| Ollama | `:openai_compatible` | Responses or Chat Completions | When the model supports it |
+| Anthropic | `:anthropic` | Messages | No |
+| Gemini | `:gemini` | Gemini API | No |
+| Vertex AI | `:vertex_ai` | Gemini on Vertex AI | No |
+| Bedrock | `:bedrock` | Converse | Titan Text Embeddings V2 |
+| LM Studio | `:lm_studio` | Responses or Chat Completions | Yes |
+
+Capabilities can vary by model, account, and server version. Handle provider
+failures even when a model is expected to support a feature.
+
+## Hosted providers
+
+### OpenRouter
+
+OpenRouter gives one connection access to models from several providers:
+
+```ruby
+config.providers = {
+  openrouter: {
+    adapter: :openrouter,
+    api_key: ENV.fetch("OPENROUTER_API_KEY"),
+    app_name: "Support Console",
+    site_url: "https://support.example.com"
+  }
+}
+```
+
+Use OpenRouter's `publisher/model` form, such as
+`openrouter:anthropic/claude-sonnet-4`. `app_name` and `site_url` are optional.
+The selected model must support embeddings before you call
+`LittleGhost.embed`.
+
+### OpenAI
+
+```ruby
+config.providers = {
+  openai: {
+    adapter: :openai,
+    api_key: ENV.fetch("OPENAI_API_KEY")
+  }
+}
+```
+
+Generation uses the Responses API by default. Use `openai:gpt-5.6-luna` for
+generation or `openai:text-embedding-3-small` for embeddings. Set
+`api: :chat_completions` only when required.
+
+### Anthropic
+
+```ruby
+config.providers = {
+  anthropic: {
+    adapter: :anthropic,
+    api_key: ENV.fetch("ANTHROPIC_API_KEY")
+  }
+}
+```
+
+Use a target such as `anthropic:claude-sonnet-4-6`. The adapter uses the
+Messages API. LittleGhost does not provide Anthropic embeddings.
+
+### Gemini
+
+```ruby
+config.providers = {
+  gemini: {
+    adapter: :gemini,
+    api_key: ENV.fetch("GEMINI_API_KEY")
+  }
+}
+```
+
+Use `gemini:gemini-2.5-flash`, for example. LittleGhost does not provide Gemini
+embeddings.
+
+### Vertex AI
+
+Vertex AI uses Gemini's request format with a Google Cloud project and
+location:
+
+```ruby
+config.providers = {
+  vertex: {
+    adapter: :vertex_ai,
+    project: ENV.fetch("GOOGLE_CLOUD_PROJECT"),
+    location: "global"
+  }
+}
+```
+
+Use a target such as `vertex:gemini-2.5-flash`. The credential resolver can
+obtain Google credentials, or startup can supply an access token. LittleGhost
+does not provide Vertex AI embeddings.
+
+### Amazon Bedrock
+
+```ruby
+config.providers = {
+  bedrock: {
+    adapter: :bedrock,
+    region: ENV.fetch("AWS_REGION")
+  }
+}
+```
+
+Use a model available in the region, such as
+`bedrock:us.anthropic.claude-sonnet-4-6-v1:0`. The adapter resolves AWS
+credentials and signs requests without an AWS SDK.
+
+Bedrock embeddings support `amazon.titan-embed-text-v2:0`. Its `dimensions`
+setting accepts 256, 512, or 1024, and `normalize` defaults to `true`.
+
+## Compatible APIs and local servers
+
+### Another OpenAI-compatible API
+
+Use `:openai_compatible` for a hosted service, gateway, or local server that
+implements OpenAI-style endpoints:
+
+```ruby
+config.providers = {
+  models: {
+    adapter: :openai_compatible,
+    base_url: "https://models.example.com/v1/",
+    api_key: ENV.fetch("MODEL_API_KEY"),
+    api: :responses
+  }
+}
+```
+
+Use the model identifier expected by the endpoint, such as
+`models:example-model`. Choose `api: :responses` or
+`api: :chat_completions` to match the server. `LittleGhost.embed` uses the
+connection's `embeddings` endpoint and supports `dimensions` when the server
+and model accept it.
+
+Tool calls, structured results, reasoning, attachments, and embeddings depend
+on the compatible server and model.
+
+Ollama and LM Studio normally listen on loopback HTTP. LittleGhost requires
+`allow_insecure_http: true` as an explicit opt-in because HTTP does not protect
+prompts, output, or credentials in transit. Use this setting only for a local
+or otherwise trusted endpoint; use HTTPS for a remote server.
+
+### Ollama
+
+Pull a model, start Ollama, and use the existing OpenAI-compatible adapter:
+
+```sh
+$ ollama pull qwen3
+```
+
+```ruby
+config.providers = {
+  ollama: {
+    adapter: :openai_compatible,
+    base_url: "http://localhost:11434/v1/",
+    api_key: "ollama",
+    api: :responses,
+    allow_insecure_http: true
+  }
+}
+```
+
+Use the pulled model name in the target, such as `ollama:qwen3`. The `api_key`
+is a placeholder for a local server without authentication.
+
+Ollama added its Responses endpoint in version 0.13.3. Set
+`api: :chat_completions` for an earlier release or when the selected model does
+not support the Responses features you need. See Ollama's [OpenAI compatibility
+reference](https://docs.ollama.com/api/openai-compatibility) for release-specific
+fields.
+
+For embeddings, pull an embedding model and pass its target to
+`LittleGhost.embed`. LittleGhost does not list, pull, or delete Ollama models.
+
+### LM Studio
+
+Start LM Studio's local server after downloading or loading the model you want
+to use. The dedicated adapter supplies the usual local endpoint and a
+placeholder credential:
+
+```ruby
+config.providers = {
+  lm_studio: {
+    adapter: :lm_studio,
+    allow_insecure_http: true
+  }
+}
+```
+
+Use the model key shown by LM Studio, for example
+`lm_studio:google/gemma-3-4b`. Generation uses the Responses API by default.
+
+Set `api: :chat_completions` with LM Studio releases earlier than 0.3.29, or
+when required by the selected model. `LittleGhost.embed` uses the same
+connection with an embedding model. See LM Studio's [compatibility
+reference](https://lmstudio.ai/docs/developer/openai-compat) for its current
+generation and embedding endpoints.
+
+When LM Studio authentication is enabled, add
+`api_key: ENV.fetch("LM_STUDIO_API_TOKEN")` to the connection.
+
+The native model list and API-token authentication require LM Studio 0.4.0 or
+newer. LittleGhost reads the list; it does not load, unload, or download models.
+
+## Discover current model details
+
+Call `refresh!` when you need current availability, loaded state, or
+capabilities. Ordinary model requests do not make discovery calls.
+
+```ruby
+resolver = LittleGhost.model_resolver
+result = resolver.refresh!(target: "lm_studio:google/gemma-3-4b")
+result[:errors]
+
+details = resolver.details("lm_studio:google/gemma-3-4b")
+details[:loaded]
+details.context_window
+details.input_modalities
+details.supported_parameters
+```
+
+Pass `target:` for one model, or omit it for every configured source. On
+failure, `result[:errors]` describes the problem and previous details remain.
+
+Hosted adapters can combine models.dev data with their provider's model API.
+LM Studio reads its native model list. The generic compatible adapter and
+Ollama do not have built-in model discovery.
+
+LM Studio details can include downloaded and loaded state, active context
+length, input types, tools, and reasoning. An unloaded model has no active
+context length. See `LittleGhost::Models::Details` for every field.
+
+## Keep connection settings in application code
+
+Choose keys, tokens, headers, base URLs, model identifiers, and API variants at
+startup. Read secrets from deployment configuration or a secret manager. Do
+not copy public request parameters into provider settings.
+
+The selected provider may receive prompts, conversation history, Tool results,
+schemas, and attachments. Choose one appropriate for that data.
+
+Continue with [Running in Production](production.md) to place connections,
+roles, sessions, and observability into a long-running application.

data/docs/guides/sandboxing.md

@@ -23,10 +23,7 @@ LittleGhost.configure do |config|
 
   config.sandbox = {
     provider: :native,
-    files: {root: :read_write},
-    root_filesystem: :isolated,
-    environment: {inherit: false, set: {"LANG" => "C.UTF-8"}},
-    network: :none
+    files: {root: :read_write}
   }
 end
 ```
@@ -34,7 +31,9 @@ end
 This example gives each Run a temporary writable root and removes it during
 teardown. The `:native` Sandbox backend selects Seatbelt on macOS or Bubblewrap on
 Linux. It raises instead of running without isolation when the native backend
-is unavailable.
+is unavailable. Unless you configure otherwise, it isolates the host root,
+removes child-process network access, and starts child processes without
+inheriting the host environment.
 
 `LittleGhost::Tools::Filesystem` and `LittleGhost::Tools::Shell` use the Sandbox
 assigned to the current Run. Code-mode interpreters also run inside their own
@@ -148,8 +147,7 @@ config.sandbox = {
   },
   runtime_paths: {
     home: :read_write
-  },
-  network: :none
+  }
 }
 ```
 
@@ -200,6 +198,39 @@ Workspace paths:
 On Seatbelt, host-visible modes permit subprocesses because development tools
 often need them. A Scope can remove `process_spawn` for a command that does not.
 
+## Start child processes with only the values they need
+
+When `environment` is omitted, sandboxed processes do not inherit the host
+environment. LittleGhost starts with `LANG`, `LC_ALL`, and `PATH`, then adds
+`LITTLE_GHOST_WORKSPACE_*` variables so the child can locate its Workspace.
+Locale values come from the host when present and otherwise use `C.UTF-8`.
+`PATH` keeps the host's absolute entries, removes empty, relative, and duplicate
+entries, and falls back to `/usr/local/bin:/usr/bin:/bin` when nothing remains.
+Credentials, provider keys, package-manager settings, and home-directory
+variables are not copied into the child.
+
+> **Safety note:** An absolute directory is not necessarily a trusted one. A
+> host `PATH` may include project directories, temporary directories, or
+> user-managed shims. Configure a fixed `PATH` when a model can invoke commands
+> by name and you do not trust every host entry.
+
+Declaring `environment` replaces the locale and path baseline instead of
+merging with it. Use an empty Hash to omit all configurable values, or set
+exactly what the process needs. Workspace routing variables remain available:
+
+```ruby
+config.sandbox = {
+  provider: :native,
+  environment: {
+    inherit: false,
+    set: {"LANG" => "C.UTF-8", "PATH" => "/opt/my-tool/bin:/usr/bin"}
+  }
+}
+```
+
+Host inheritance requires both `inherit: true` in the Sandbox policy and an
+individual process call that opts into inheritance.
+
 ## Choose an enforcement backend
 
 | Sandbox backend | Host | What it enforces |
@@ -260,6 +291,10 @@ Sandbox networking has three modes:
 - `:allowlist` requires an enforcing gateway: a supervised proxy that permits
   only configured destinations.
 
+Seatbelt, Bubblewrap, and `:native` default to `:none`; declare a network mode
+only when the child needs a different policy. The unrestricted backend uses
+`:inherit` because it is not a security boundary.
+
 Proxy environment variables alone are not an allowlist. An external gateway
 uses named, process-only Workspace paths and verifies that they still point to
 the configured directories; it does not create a virtual path mapping.

data/docs/guides/skills.md

@@ -107,9 +107,7 @@ LittleGhost.configure do |config|
 
   config.sandbox = {
     provider: :native,
-    files: {root: :read_write, skills: :read_only},
-    root_filesystem: :isolated,
-    network: :none
+    files: {root: :read_write, skills: :read_only}
   }
 end
 ```

data/docs/guides/tools.md

@@ -79,6 +79,8 @@ end
 Prefer `available_if` on an individual Tool when only that operation is
 conditional. Use a provider when the collection itself owns discovery,
 construction, or shared setup for an application or remote service.
+The [MCP guide](mcp.md) shows how a Model Context Protocol server provides a
+Toolset through the official Ruby client.
 
 LittleGhost does not enforce class names. A useful application convention is
 to end one model-callable operation with `Tool` and a provider of multiple

data/exe/little_ghost

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+lib = File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require "little_ghost/cli"
+
+source_path = File.expand_path("..", __dir__)
+source_path = nil unless File.file?(File.join(source_path, "little_ghost.gemspec"))
+
+exit LittleGhost::CLI.new(ARGV, source_path:).run

data/lib/little_ghost/assembly.rb

@@ -50,7 +50,8 @@ module LittleGhost
       # +context+, +settings+, +metadata+, +session_id+, +actor_id+, and
       # +deadline_at+.
       def ask(message, **options)
-        definition.implementation.new.ask(message, **options)
+        snapshot = definition
+        snapshot.implementation.new.bind_assembly_definition(snapshot).ask(message, **options)
       end
 
       # Lazily streams +message+ through a fresh standalone assembly.
@@ -66,7 +67,7 @@ module LittleGhost
         snapshot = definition
         stream = nil
         Enumerator.new do |events|
-          stream ||= snapshot.implementation.new.stream_ask(message, **options)
+          stream ||= snapshot.implementation.new.bind_assembly_definition(snapshot).stream_ask(message, **options)
           stream.each { |event| events << event }
         end
       end
@@ -157,6 +158,7 @@ module LittleGhost
       @runtime = runtime || run&.runtime || LittleGhost.runtime
       @workspace = workspace || run&.workspace
       @sandbox = sandbox || run&.sandbox
+      @assembly_definition = nil
       @standalone = standalone
       @assembly_mutex = Mutex.new
       @assembly_closed = false
@@ -169,6 +171,11 @@ module LittleGhost
       self
     end
 
+    def bind_assembly_definition(definition) # :nodoc:
+      @assembly_definition = definition
+      self
+    end
+
     # Builds the top-level Run used by a standalone assembly.
     def build_run(payload = nil, include_agent_events_by_default: false, **payload_options) # :nodoc:
       payload = entrypoint_payload(payload, payload_options) unless payload_options.empty?
@@ -178,7 +185,8 @@ module LittleGhost
       end
       source_class = run_entrypoint_class
       options = {entrypoint_class: source_class}
-      options[:execution_class] = self.class unless source_class.equal?(self.class)
+      execution = @assembly_definition || self.class
+      options[:execution_class] = execution unless source_class.equal?(execution)
       options[:agent_class] = source_class if is_a?(Agent)
       options[:cancellation_token] = cancellation_token if cancellation_token
       options[:workspace] = workspace if workspace

data/lib/little_ghost/assembly_builder.rb

@@ -123,7 +123,7 @@ module LittleGhost
       snapshot = definition
       return (runtime || run.runtime).build_assembly(snapshot, run:) if run
 
-      snapshot.implementation.new(runtime:)
+      snapshot.implementation.new(runtime:).bind_assembly_definition(snapshot)
     end
 
     # Executes the current declarations and returns their Run.
@@ -133,7 +133,7 @@ module LittleGhost
     def stream_ask(message, **options)
       snapshot = definition
       Enumerator.new do |events|
-        snapshot.implementation.new(runtime:).stream_ask(message, **options).each { |event| events << event }
+        snapshot.implementation.new(runtime:).bind_assembly_definition(snapshot).stream_ask(message, **options).each { |event| events << event }
       end
     end