little_ghost 0.7.0 → 0.9.0

data/docs/guides/prompt_views.md

@@ -1,8 +1,9 @@
 # Prompts as Views
 
-A short prompt fits nicely inside an Agent class. As the instructions grow, move them into a **prompt view**: an ERB file that LittleGhost finds and renders for the Agent.
-
-This keeps the Agent definition focused. It also gives shared instructions and application values a natural home.
+Keep growing Agent instructions readable by moving them into a **prompt view**:
+an ERB file that LittleGhost finds and renders for the Agent. The Agent prepares
+any application values the prompt needs, while the view holds the instructions
+sent to the model.
 
 ## Start with the inline prompt
 
@@ -28,7 +29,7 @@ class CustomerSupportAgent < LittleGhost::Agent
 end
 ```
 
-Then create `app/prompts/customer_support/system.erb`:
+Then create `app/prompts/customer_support/system_prompt.erb`:
 
 ```erb
 You help customers understand their orders and account.
@@ -38,57 +39,115 @@ Never invent company guidance. Check the help center when policy matters.
 Use the order status tool before making a claim about a private order.
 ```
 
-That is enough. `CustomerSupportAgent` becomes `customer_support`, so LittleGhost looks for `customer_support/system.erb` under `app/prompts`.
+That is enough. LittleGhost turns `CustomerSupportAgent` into the logical path
+`customer_support` and looks for
+`app/prompts/customer_support/system_prompt.erb`.
 
-The prompt is still a system instruction sent to the selected model provider. Keeping it in a view improves organization; it does not keep the content inside your process.
+The prompt is still a system instruction sent to the selected model provider.
+Keeping it in a view improves organization; it does not keep the content inside
+your process.
 
-## Give the view application values
+## Prepare application values with Ruby
 
-Use `prompt_local` for a value the application owns:
+Define `system_prompt` as an instance method when the view needs values from
+your application. Assign those values to instance variables:
 
 ```ruby
 class CustomerSupportAgent < LittleGhost::Agent
-  prompt_local :company_name, "Northstar"
+  def system_prompt
+    @company_name = "Northstar"
+    @policy_version = SupportPolicy.current_version
+  end
 end
 ```
 
-The local is available by name in the view:
+LittleGhost calls the method before it renders the view. The instance variables
+are available there by the same names:
 
 ```erb
-You are a customer support agent for <%= company_name %>.
+You are a customer support agent for <%= @company_name %>.
+Follow support policy <%= @policy_version %>.
 Answer clearly and concisely.
 ```
 
-A block can resolve a trusted value for each Agent instance. Add it to the Agent class too:
+If you know Rails controllers, the pairing is familiar: the method prepares
+values, and the ERB file presents them. The method's return value is ignored. If
+it raises an exception, the Run fails in the usual way.
+
+An inline `system_prompt` declaration still takes precedence over a view. Remove
+the inline declaration when you want LittleGhost to call the instance method and
+render `system_prompt.erb`.
+
+Subclass actions can call `super` before adding their own values:
 
 ```ruby
-class CustomerSupportAgent < LittleGhost::Agent
-  prompt_local(:policy_version) { SupportPolicy.current_version }
+class BillingSupportAgent < CustomerSupportAgent
+  def system_prompt
+    super
+    @billing_region = "US"
+  end
 end
 ```
 
-Prompt views also receive `invocation`, `run`, and `agent`. Reach for those when the instruction truly depends on the current request. Keep user wording in the caller message unless you deliberately want it inside the system instruction.
+Prompt views also receive three built-in local variables: `invocation` for the
+current request, `run` for its lifecycle, and `agent` for the run-scoped Agent.
+Use them when an instruction genuinely depends on the current request. Keep the
+customer's wording in the caller message unless it belongs in the system
+instruction.
 
-Every rendered value may be sent to the model provider. Pass only data that belongs in the prompt.
+Every rendered value may be sent to the model provider. Put only data that
+belongs in the prompt into the view.
 
 ## Share a small partial
 
 Partials keep repeated instructions in one place. Create `app/prompts/shared/_voice.erb`:
 
 ```erb
-Use a warm, direct voice for <%= company_name %>.
+Use a warm, direct voice for <%= @company_name %>.
 Prefer one clear next step over a long list of possibilities.
 ```
 
 Render it from the Agent's system view:
 
 ```erb
-You are a customer support agent for <%= company_name %>.
+You are a customer support agent for <%= @company_name %>.
+
+<%= partial "shared/voice" %>
+```
+
+The underscore marks a partial. Partials share the Agent's instance variables,
+so `@company_name` remains available without extra wiring.
+
+Use an explicit local for a value that belongs only to one partial. For example,
+create `app/prompts/shared/_closing.erb`:
+
+```erb
+Offer one clear next step for <%= audience %>.
+```
+
+Then pass `audience` when you render it:
 
-<%= partial "shared/voice", locals: {company_name: company_name} %>
+```erb
+<%= partial "shared/closing", locals: {audience: "account owners"} %>
 ```
 
-The underscore marks a partial. Its locals are explicit, so it does not quietly inherit everything available to the parent view.
+Locals do not flow into nested partials unless you pass them again.
+
+## Keep repeated renders predictable
+
+LittleGhost calls `system_prompt` once for each file-backed prompt render. Each
+call starts with the instance variables captured after LittleGhost's
+`after_initialize` callbacks finish. Values left behind by a later callback,
+Tool, or earlier render do not become prompt assigns by accident.
+
+After preparing the view, LittleGhost restores the Agent's live instance
+variables. The objects assigned to the view are still ordinary Ruby objects,
+though, so the view sees the same mutable objects. Treat them as read-only, or
+duplicate a value before assigning it when the template needs an isolated copy.
+
+For state that should change across invocations, read from `run`, a session, or
+an application object in `system_prompt` instead of relying on an earlier
+prompt render.
 
 ## Choose a different template path
 
@@ -104,10 +163,154 @@ LittleGhost chooses one prompt source in this order:
 
 1. An inline `system_prompt`
 2. An explicit `system_template`
-3. The Agent's conventional `system.erb` view
+3. The Agent's conventional `system_prompt.erb` view
 
 Applications can add prompt lookup roots through `Configuration#prompt_paths`.
-Earlier roots win, which lets application code override a shared prompt package.
+Earlier roots win, so an application can override a view from a shared prompt
+package.
+
+## Customize LittleGhost's framework prompts
+
+You can change LittleGhost's own model-facing language without replacing its
+Ruby behavior. Tool descriptions, structured-result repair requests, context
+summaries, code-mode instructions, and other framework messages all come from
+bundled prompt views under the `little_ghost/` namespace.
+
+### Decide when to customize
+
+Models can respond differently to the same instruction, even when the Tool,
+schema, and task stay the same. Wording that works well with one model may lead
+another model to miss a Tool constraint, mishandle a repair request, or recover
+less reliably from a failed call. Adjusting the relevant framework prompt gives
+you a direct way to improve that interaction without forking LittleGhost.
+
+An override can also align framework language with your application's
+terminology and voice. Start with the narrowest template that covers the
+behavior you want to change, and evaluate it with the models your application
+uses. Keep protocol checks, authorization, and execution limits in Ruby;
+prompt wording guides the model but does not enforce those boundaries.
+
+### Find the prompt you want to change
+
+Browse the catalog from your application:
+
+```sh
+$ little_ghost prompts list
+$ little_ghost prompts list structured_output
+$ little_ghost prompts list structured_output/repair
+$ little_ghost prompts show structured_output/repair/request
+```
+
+The bare `list` command shows top-level features with template counts. Pass a
+feature or component path to browse its immediate children, or use `list --all`
+to print every template key. Keys follow `feature/component/purpose`. For
+example, built-in Tool descriptions live under `tools/built_in`, while JSON
+Schema feedback lives under `tools/validation/schema`. Directories named
+`feedback` contain conditions the model can correct. Directories named `errors`
+contain operational failures.
+
+`show` prints the bundled ERB source. Every bundled template starts with a
+structured ERB comment that explains where LittleGhost renders it, its locals,
+and any formatting constraints. These headers use `<%# ... -%>`, so neither the
+comment nor its trailing newline enters the rendered prompt. Each interior line
+also starts with `#` so Ruby-aware editors recognize the whole header as a
+comment. A `#` line outside `<%# ... -%>` and an HTML comment are output text and
+would be sent to the model.
+
+Bundled prompts use plain text and Markdown. When a prompt needs headings or
+structured sections, the default template uses Markdown headings and lists
+rather than XML-like wrapper tags.
+
+### Copy an override into your application
+
+Copy one template into the default application prompt root before editing it:
+
+```sh
+$ little_ghost prompts copy structured_output/repair/request
+```
+
+That creates
+`app/prompts/little_ghost/structured_output/repair/request.erb`. Use `--root` when the
+application configures a different prompt root:
+
+```sh
+$ little_ghost prompts copy structured_output/repair/request --root config/prompts
+```
+
+Use `--agent` when one Agent needs different wording from the rest of the
+application. Pass the Agent's logical path, which is its underscored class name
+without the `Agent` suffix:
+
+```sh
+$ little_ghost prompts copy structured_output/repair/request --agent customer_support
+```
+
+That creates
+`app/prompts/customer_support/little_ghost/structured_output/repair/request.erb`.
+Namespaced classes use a namespaced logical path, such as
+`Admin::CustomerSupportAgent` becoming `admin/customer_support`.
+
+Copy the complete catalog when an application deliberately wants to own every
+piece of framework wording:
+
+```sh
+$ little_ghost prompts copy --all
+```
+
+Copy commands refuse to overwrite any existing destination. With `--all`, the
+command checks every destination before it starts writing. Copied templates
+retain their invisible documentation headers so the override remains
+self-explanatory in the application.
+
+### Choose the override scope
+
+For every framework prompt that applies to an Agent invocation, LittleGhost
+uses the first matching template in this order:
+
+1. An invocation-specific `TrustedPath` root
+2. The Agent-scoped directory inside a configured prompt root
+3. The runtime-wide directory inside a configured prompt root
+4. The template bundled with LittleGhost
+
+Each root keeps the same `little_ghost/<key>.erb` namespace. Agent scope inserts
+the logical path before that namespace.
+
+Runtime-wide overrides normally live in the default `app/prompts` root. Add or
+replace configured roots when the application uses another location:
+
+```ruby
+LittleGhost.configure do |config|
+  config.prompt_paths = ["config/prompts", "app/prompts"]
+end
+```
+
+The uncommon invocation-specific layer is explicit because it can change model
+instructions for only one call. From `config/little_ghost.rb`:
+
+```ruby
+campaign_prompts = LittleGhost::TrustedPath.new(
+  path: File.expand_path("campaign_prompts", __dir__)
+)
+
+CustomerSupportAgent.ask(
+  "Where is my order?",
+  template_paths: [campaign_prompts]
+)
+```
+
+The invocation root contains
+`little_ghost/structured_output/repair/request.erb`, as a runtime root does.
+Direct `LittleGhost.generate` calls accept the same `template_paths:` option.
+
+### Know what an override can change
+
+Framework templates control model-facing language, not protocol roles, Tool
+names, schemas, validation behavior, security checks, or execution limits. A
+required template cannot render as blank.
+
+LittleGhost is pre-1.0. Template keys and their documented locals are maintained
+on a best-effort basis until 1.0, so review release notes and copied overrides
+when upgrading.
 
 ## Treat views as application code
 
@@ -115,13 +318,16 @@ Prompt views run as ERB inside the Ruby process and can call Ruby. Keep prompt
 directories with the rest of your application code rather than letting a
 request choose one.
 
-`TrustedPath` is available for the uncommon case where application code selects
-a request-specific root. It marks that choice explicitly; it does not inspect
-or restrict the directory.
+Use `TrustedPath` only when application code needs to select a request-specific
+root. Do not derive its path from a request parameter, model output, or Tool
+argument. The wrapper confirms that the directory exists and resolves symbolic
+links. It does not inspect who can edit the directory or restrict what its ERB
+can execute.
 
 ## Build request-specific input in a Workflow
 
-A prompt view defines reusable instructions for one Agent. A Workflow may still build request-specific input for that Agent:
+A prompt view defines reusable instructions for one Agent. A Workflow may still
+build request-specific input for that Agent:
 
 ```ruby
 invoke CustomerSupportAgent, input: <<~MESSAGE
@@ -132,7 +338,8 @@ invoke CustomerSupportAgent, input: <<~MESSAGE
 MESSAGE
 ```
 
-The Workflow is composing this request. `CustomerSupportAgent` still receives its own system prompt view when it runs.
+The Workflow is composing this request. `CustomerSupportAgent` still receives
+its own system prompt view when it runs.
 
 Continue with [Tools](tools.md) to give those Agents application capabilities
 while keeping model input, trusted context, and delegated sandbox operations

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.