little_ghost 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 16d2003f8e5b79a2532ab16b9a0a1d95a9ee65b21025371290aeccacacd0f8a1
+  data.tar.gz: 0c4db0710a8650ebb1ae159bc59a62078c442a035b64c3f549cbfb686c881c32
+SHA512:
+  metadata.gz: c435a0f6ef9b9d4508d66f72610b32b58f45ed724af5d8b9fbf8cc20fc27eaa8a41dcffc1c4fe0e109fbfc3603dffdf393f0bc38444a554009b41d8302b74f1a
+  data.tar.gz: 1945188f5019cd2b115f74df481a344124d793eaa74ace0e6efc57b84d9bc117ee20879a2764818c78918e1dcd0609f3c1230e27b9a6b2885b4db4288a9e8b6b

data/LICENSE.txt

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Matt Robinson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -0,0 +1,122 @@
+# Build AI features with LittleGhost
+
+<hr>
+
+**Growing in public.** LittleGhost is under active development, and interfaces may evolve between releases. Pin the gem version and review the release notes when upgrading.
+
+<hr>
+
+Bring agents and agentic workflows into an existing Ruby system, or use them as the core of a dedicated AI service. LittleGhost brings model providers, tools, streaming, sessions, delegation, deterministic composition, and observability together behind one coherent set of Ruby APIs.
+
+Here is the shape of a small customer support agent. `CustomerSupportModels` keeps provider details out of agent behavior, `HelpCenterLookupTool` exposes one narrow, validated help center lookup, and `CustomerSupportAgent` brings them together:
+
+```ruby
+require "little_ghost"
+
+class CustomerSupportModels < LittleGhost::ModelRegistry
+  def initialize
+    super
+    provider(:openai) do |model:, **|
+      LittleGhost::Providers::OpenAI.new(
+        api_key: ENV.fetch("OPENAI_API_KEY"),
+        model:
+      )
+    end
+    profile "customer_support", provider: :openai, model: "gpt-5"
+  end
+end
+
+class HelpCenterLookupTool < LittleGhost::Tool
+  description "Look up a help center entry by topic."
+  input_schema(
+    type: "object",
+    properties: {topic: {type: "string"}},
+    required: ["topic"],
+    additionalProperties: false
+  )
+
+  def call(input)
+    {"refunds" => "Refunds are available within 30 days."}
+      .fetch(input.fetch("topic"), "No help center entry found.")
+  end
+end
+
+class CustomerSupportAgent < LittleGhost::Agent
+  description "Answers customer support questions."
+  model "customer_support"
+  system_prompt "Answer clearly. Check the help center before stating company guidance."
+  tools HelpCenterLookupTool
+end
+
+LittleGhost.configure { |config| config.models CustomerSupportModels }
+
+run = CustomerSupportAgent.ask("Can I get a refund after two weeks?")
+puts run.response
+# One possible response:
+# Refunds are available within 30 days, so your purchase is eligible.
+```
+
+The result is a normal Ruby object. You can inspect its outcome, final response, normalized messages, token usage, and error instead of parsing provider-specific payloads.
+
+LittleGhost keeps the model loop provider-neutral. Tools can run in parallel, mutating tools can opt into a run-wide exclusive lock, and oversized tool results are truncated to the configured limit before they enter model context. Strict result schemas, cancellation, deadlines, session checkpoints, structured events, and OpenTelemetry integration are available when an application needs them; none are required to define the first agent.
+
+The core stays dependency-light, while provider SDKs and deployment choices remain with the application.
+
+## How it fits together
+
+```text
+application configuration ──> CustomerSupportModels ──> provider
+                                      │
+request ──> CustomerSupportAgent ──> HelpCenterLookupTool
+                  │
+                  └────────> ResearchAgent (when delegated)
+
+request ──> ResponseWorkflow ──> ResearchAgent ──> CustomerSupportAgent
+```
+
+Configuration owns shared services such as model registries, sessions, lookup paths, workspaces, sandboxes, and instrumentation. Agent classes own behavior: their logical model role, prompt, tools, limits, structured result, and delegation policy. A tool is a validated boundary around application code. A subagent lets the model delegate work within configured turn, concurrency, and depth limits; a workflow uses ordinary Ruby when your application must choose the sequence.
+
+`CustomerSupportAgent.ask(...)` creates a standalone entrypoint, consumes its run, and returns the completed `LittleGhost::Run`. Create an instance explicitly when reusing a runtime or when an interface should render progress as `LittleGhost::StreamEvent` objects:
+
+`LittleGhost::Agent.ask("hi")` uses the built-in default model selection and the system prompt `You are a helpful agent.` for a general-purpose agent.
+
+```ruby
+CustomerSupportAgent.new.stream_ask("Can I get a refund?").each do |event|
+  print event.data[:text] if event.type == :text_delta
+end
+```
+
+Applications can add a `ResearchAgent` as a subagent for open-ended investigation, or place both agents behind a deterministic `ResponseWorkflow`. The same run lifecycle checkpoints session state, closes owned resources, aggregates usage, and emits framework events in each form.
+
+## Installation
+
+LittleGhost requires Ruby 3.3 or newer. Add it to your bundle:
+
+```ruby
+gem "little_ghost"
+```
+
+Then run `bundle install`. Provider SDKs and OpenTelemetry exporters are optional application dependencies. The built-in OpenAI, OpenAI-compatible, OpenRouter, and Amazon Bedrock integrations normalize their responses into the same LittleGhost protocol.
+
+By default, LittleGhost maps the `default` role to GPT-5.6 Terra. It selects the first nonblank API key from `LITTLEGHOST_OPENROUTER_API_KEY`, `LITTLEGHOST_OPENAI_API_KEY`, `OPENROUTER_API_KEY`, and `OPENAI_API_KEY`, in that order. Setting one of these keys authorizes model inputs—including prompts, conversation history, tool data, and attachments—to be sent to the selected external provider. Applications with provider or data-residency requirements should configure a model registry explicitly.
+
+By default, structured framework events have no console destination. Hosted applications can emit redacted JSON lines to standard output with `LittleGhost.configure { |config| config.log_events_to :stdout }`; `:stderr` selects standard error instead, and `nil` disables a configured destination. Event emission and severity levels are the same with or without a console destination.
+
+Prompts can stay inline while an agent is small, then move into conventional ERB templates under `app/prompts`. Agents and tools under `app/agents` and `app/tools` are loaded from the configured application root, keeping framework setup separate from product behavior.
+
+## Documentation
+
+- [LittleGhost website](https://mattyr.github.io/little_ghost/) is the quickest way to meet the framework and find your next step.
+- [Getting Started](docs/guides/Getting%20Started.md) builds the customer support example from an empty application and runs it.
+- [Core Concepts](docs/guides/Core%20Concepts.md) explains models, agents, tools, delegation, workflows, sessions, and streaming through the same example.
+- [API reference](rdoc-ref:LittleGhost) covers exact signatures, options, and lifecycle details.
+
+LittleGhost is licensed under the MIT License.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test
+bundle exec standardrb --no-fix
+```

data/docs/guides/Core Concepts.md

@@ -0,0 +1,203 @@
+# Core Concepts
+
+LittleGhost gives Ruby software two ways to compose AI behavior. Agents can choose among validated tools and delegated specialists, while agentic workflows keep required ordering and branching under application control. The customer support example makes that boundary visible: CustomerSupportModels chooses provider-backed models, CustomerSupportAgent owns behavior, HelpCenterLookupTool exposes a narrow help center lookup, ResearchAgent handles delegated investigation, and ResponseWorkflow imposes a deterministic sequence when the surrounding system requires one.
+
+```text
+shared configuration
+└── CustomerSupportModels ── resolves logical roles ──> provider clients
+
+one request
+└── Run
+    ├── CustomerSupportAgent
+    │   ├── HelpCenterLookupTool
+    │   └── ResearchAgent subagent (model-directed)
+    └── sessions, resources, usage, events, and terminal result
+
+one deterministic request
+└── Run ──> ResponseWorkflow ──> ResearchAgent ──> CustomerSupportAgent
+```
+
+## Models are selected by role
+
+An agent names a logical role such as `customer_support`, not a vendor model. `CustomerSupportModels` maps that stable application vocabulary to a provider and model identifier:
+
+```ruby
+class CustomerSupportModels < LittleGhost::ModelRegistry
+  def initialize
+    super
+    provider(:openai) do |model:, **|
+      LittleGhost::Providers::OpenAI.new(
+        api_key: ENV.fetch("OPENAI_API_KEY"),
+        model:
+      )
+    end
+    profile "customer_support", provider: :openai, model: "gpt-5"
+  end
+end
+```
+
+Dotted roles inherit from the nearest registered parent. `ResearchAgent` can request `customer_support.research` and initially use the `customer_support` profile; registering `customer_support.research` later specializes it. Per-invocation profile overrides can vary a request without mutating the registry or agent class. Because an override can select a different registered provider, model, and settings, it is trusted application configuration and must be constructed or allowlisted by the application rather than copied from unchecked request data.
+
+The provider performs model I/O. The registry resolves application intent into a `LittleGhost::Model`, which carries the provider, settings, metadata, model identifier, and role for a run.
+
+## Agents declare behavior
+
+An agent class declares application behavior:
+
+```ruby
+class CustomerSupportAgent < LittleGhost::Agent
+  description "Answers customer support questions."
+  model "customer_support"
+  system_prompt "Answer clearly. Check the help center before stating company guidance."
+  tools HelpCenterLookupTool
+  subagent ResearchAgent, kind: "research"
+end
+```
+
+The class-level DSL is inheritable. It can declare prompts, limits, callbacks, tool classes, structured results, context management, skills, and delegation. A capability mixin may be included in `LittleGhost::Agent`, but its behavior remains inactive until the corresponding DSL is called.
+
+`CustomerSupportAgent.ask` creates a standalone, console-friendly entrypoint, builds and consumes a `LittleGhost::Run`, and returns that run. Create `CustomerSupportAgent.new` explicitly to reuse a runtime or call `#stream_ask` for the run's events. Agents built by a runtime are instead scoped to their owning run and return a `LittleGhost::RunResult` from `#call`.
+
+That distinction explains two useful return paths:
+
+```ruby
+run = CustomerSupportAgent.ask("Can I get a refund?")
+run.response       # final text from the top-level execution
+run.result.output  # text, or a validated structured value when declared
+```
+
+## Runs own top-level lifecycle
+
+A `LittleGhost::Run` owns one top-level agent or workflow execution. It opens the session, workspace, sandbox, entrypoint, and registered resources, then closes owned resources in reverse order.
+
+The run is both executable and enumerable. `#call` consumes it; `#each` streams `LittleGhost::StreamEvent` objects. After termination, the run reports one outcome: completed, failed, partial at a deadline, or cancelled. It also exposes the final response, result, usage, and error.
+
+An `Invocation` is the request envelope. It normalizes the current message and history, generates missing identifiers, and retains application-specific fields with indifferent string and symbol keys. Caller identity remains explicit. If session persistence needs tenant isolation, derive its actor from trusted authentication state; never trust a model-supplied or unverified request field.
+
+## Tools are validated application boundaries
+
+`HelpCenterLookupTool` exposes exactly one operation to the model:
+
+```ruby
+class HelpCenterLookupTool < LittleGhost::Tool
+  description "Look up a help center entry by topic."
+  input_schema(
+    type: "object",
+    properties: {topic: {type: "string"}},
+    required: ["topic"],
+    additionalProperties: false
+  )
+
+  def call(input)
+    HelpCenterRepository.fetch(input.fetch("topic"))
+  end
+end
+```
+
+LittleGhost validates the model's input before invoking `#call`. Hashes and arrays returned by a tool are JSON-encoded; other values become text. Expected application failures can raise `LittleGhost::ToolError`; unexpected exception messages are sanitized before they reach model context.
+
+Validation is not authorization. A tool that reads customer records, writes files, executes processes, or calls a network service must enforce the application's trust rules itself. The built-in unrestricted sandbox executes with the Ruby process's permissions and is not a security boundary. Configure an isolated sandbox before exposing filesystem or shell tools to untrusted work.
+
+## Subagents are model-directed delegation
+
+Declaring `ResearchAgent` as a subagent gives `CustomerSupportAgent` a configured set of tools for spawning, messaging, interrupting, waiting for, and listing research work:
+
+```ruby
+class ResearchAgent < LittleGhost::Agent
+  description "Investigates support questions that need broader research."
+  model "customer_support.research"
+  system_prompt "Return a concise evidence summary."
+end
+
+class CustomerSupportAgent < LittleGhost::Agent
+  model "customer_support"
+  tools HelpCenterLookupTool
+  subagent ResearchAgent, kind: "research"
+end
+```
+
+The model decides whether to delegate and how to use the returned research. Each child declares its own tools, so access remains visible at the class receiving it. Subagent work can run concurrently and respects the configured turn, concurrency, depth, and time limits. Conversations can persist when a session store exists; `persist: false` keeps a declaration invocation-local.
+
+Use an agent as an ordinary tool with `agent_as_tool` when one request and one result is enough. Use a subagent when the parent needs an addressable worker with follow-ups, progress, interruption, or durable conversation identity.
+
+## Workflows are application-directed composition
+
+Some customer support requests must always be researched before a response is written. Put that invariant in Ruby rather than asking the model to remember it:
+
+```ruby
+class ResponseWorkflow < LittleGhost::Workflow
+  private
+
+  def perform
+    research = invoke(ResearchAgent).output
+
+    invoke CustomerSupportAgent, input: <<~PROMPT
+      Customer request:
+      #{input.text}
+
+      Research:
+      #{research}
+    PROMPT
+  end
+end
+```
+
+`#invoke` builds a lazy agent invocation. Calling `#output` consumes an intermediate invocation; `#perform` must return its final invocation unconsumed so LittleGhost can stream that agent to the original caller. Input, history, state, settings, cancellation, deadline, template values, and trace parentage flow through the workflow, while intermediate usage is added to the terminal result.
+
+A workflow is an explicit entrypoint on a run:
+
+```ruby
+runtime = LittleGhost::Runtime.new(configuration: LittleGhost.configuration)
+run = runtime.build_run(
+  {message: "Review this unusual refund request"},
+  agent_class: CustomerSupportAgent,
+  entrypoint_class: ResponseWorkflow
+).call
+
+puts run.response
+```
+
+Choose a subagent when delegation is part of the model's judgment. Choose a workflow when ordering and branching are application invariants. They can coexist: `ResponseWorkflow` can always collect baseline research, while `CustomerSupportAgent` can still delegate a new question that arises while drafting the response.
+
+## Structured results separate data from prose
+
+An agent that feeds application code can declare a strict JSON object schema:
+
+```ruby
+class ResearchAgent < LittleGhost::Agent
+  model "customer_support.research"
+  result_schema(
+    {
+      type: "object",
+      properties: {
+        summary: {type: "string"},
+        sources: {type: "array", items: {type: "string"}}
+      },
+      required: %w[summary sources],
+      additionalProperties: false
+    },
+    name: "support_research"
+  )
+end
+```
+
+LittleGhost selects provider-native structured output when the resolved model advertises it, or a strict terminal tool when supported. The locally validated value is available through `RunResult#structured_result` and `RunResult#output`. Invalid output receives one repair attempt, then raises `LittleGhost::StructuredResultError`.
+
+Use structured results when code consumes fields. Keep ordinary text when a human is the final consumer.
+
+## Sessions preserve conversation, streams expose progress
+
+The default session store is in-memory. A configured `SessionStore` can load history and state before an agent runs and checkpoint coherent turns as work progresses. The application must supply stable session and actor identifiers when it wants continuity and isolation.
+
+Streams expose generic framework events rather than provider wire formats. Consumers can render text deltas, observe tool or subagent activity, collect usage, and react to terminal outcomes without coupling to OpenAI, OpenRouter, or Bedrock. The optional AG-UI adapter translates the same events at an interface boundary.
+
+## Keep the boundary visible
+
+The core design can be summarized as four choices:
+
+- Put shared construction and provider policy in configuration and model registries.
+- Put model behavior and available capabilities on agent classes.
+- Put privileged application operations behind narrow, authorized tools.
+- Put mandatory ordering in workflows; leave optional delegation to subagents.
+
+Return to [Getting Started](Getting%20Started.md) for the complete first-run setup. The API reference covers exact signatures and lifecycle details for `LittleGhost::Runtime`, `LittleGhost::Run`, `LittleGhost::Agent`, `LittleGhost::Tool`, `LittleGhost::Workflow`, and `LittleGhost::ModelRegistry`.

data/docs/guides/Getting Started.md

@@ -0,0 +1,187 @@
+# Getting Started with LittleGhost
+
+This guide builds a small AI customer support feature around an agent that checks an in-memory help center and returns a normal Ruby result. By the end, you will have configured a model provider, declared a validated tool, run `CustomerSupportAgent`, and streamed the same request as events.
+
+The example uses OpenAI, but the agent and tool do not depend on that choice. A `ModelRegistry` keeps the provider boundary behind the logical model role `customer_support`.
+
+## Before you begin
+
+LittleGhost requires Ruby 3.3 or newer. Add the gem to your `Gemfile`:
+
+```ruby
+gem "little_ghost"
+```
+
+Install the bundle and provide the credential used by this example:
+
+```sh
+$ bundle install
+$ export OPENAI_API_KEY="..."
+```
+
+Use application-specific secret management outside a local shell. Do not commit provider credentials.
+
+## Create the application shape
+
+LittleGhost looks for agents, tools, prompts, and skills under conventional application directories. This example needs four files:
+
+```text
+customer_support_app/
+├── app/
+│   ├── agents/
+│   │   ├── research_agent.rb
+│   │   └── customer_support_agent.rb
+│   └── tools/
+│       └── help_center_lookup_tool.rb
+└── config/
+    └── little_ghost.rb
+```
+
+Run the application from `customer_support_app/`, or set the configuration root explicitly before the first runtime is built. The runtime loads `config/little_ghost.rb` lazily and eager-loads conventional application code.
+
+## Configure a logical model role
+
+Define `CustomerSupportModels` in `config/little_ghost.rb` and register it with LittleGhost:
+
+```ruby
+require "little_ghost"
+
+class CustomerSupportModels < LittleGhost::ModelRegistry
+  def initialize
+    super
+
+    provider(:openai) do |model:, **|
+      LittleGhost::Providers::OpenAI.new(
+        api_key: ENV.fetch("OPENAI_API_KEY"),
+        model:
+      )
+    end
+
+    profile "customer_support",
+      provider: :openai,
+      model: "gpt-5",
+      settings: {temperature: 0.2}
+  end
+end
+
+LittleGhost.configure do |config|
+  config.models CustomerSupportModels
+end
+```
+
+The agent will ask for the role `customer_support`; it never needs the provider name or provider model identifier. This separation lets an application change providers or override a profile for one invocation without changing agent classes. Treat model settings and profile overrides as trusted application configuration: construct or allowlist them server-side instead of copying unchecked request fields.
+
+## Give the agent one validated tool
+
+Create `app/tools/help_center_lookup_tool.rb`:
+
+```ruby
+class HelpCenterLookupTool < LittleGhost::Tool
+  HELP_CENTER_ENTRIES = {
+    "refunds" => "Refunds are available within 30 days of purchase.",
+    "shipping" => "Standard shipping takes three to five business days."
+  }.freeze
+
+  description "Look up a help center entry by topic."
+  input_schema(
+    type: "object",
+    properties: {
+      topic: {type: "string", enum: HELP_CENTER_ENTRIES.keys}
+    },
+    required: ["topic"],
+    additionalProperties: false
+  )
+
+  def call(input)
+    HELP_CENTER_ENTRIES.fetch(input.fetch("topic"))
+  end
+end
+```
+
+A tool exposes a name, description, JSON input schema, and implementation. `HelpCenterLookupTool` gets its default model-visible name from the class name. LittleGhost validates input before calling `#call` and turns the returned value into text for model context.
+
+This boundary is also the right place for application authorization. If lookup behavior or results depended on an account or tenant, `#call` would verify trusted run context before reading them. A schema validates shape; it does not authorize access.
+
+## Define the agents
+
+Create `app/agents/research_agent.rb`:
+
+```ruby
+class ResearchAgent < LittleGhost::Agent
+  description "Investigates support questions that need broader research."
+  model "customer_support.research"
+  system_prompt "Research the question and return a concise evidence summary."
+end
+```
+
+There is no separate `customer_support.research` profile yet. Dotted roles fall back to the nearest registered parent, so this role resolves through `customer_support`. You can add a specialized profile later without changing `ResearchAgent`.
+
+Now create `app/agents/customer_support_agent.rb`:
+
+```ruby
+class CustomerSupportAgent < LittleGhost::Agent
+  description "Answers customer support questions."
+  model "customer_support"
+  system_prompt <<~PROMPT
+    Answer clearly and do not invent company guidance.
+    Use the help center lookup tool before stating company guidance.
+    Delegate open-ended investigation to the research agent.
+  PROMPT
+
+  tools HelpCenterLookupTool
+  subagent ResearchAgent, kind: "research"
+end
+```
+
+The class is a readable behavior boundary. It declares which model role, prompt, tools, and subagent capabilities can participate in a `CustomerSupportAgent` run. Declaring `ResearchAgent` as a subagent gives the model tools for delegation, with the turn, concurrency, and depth limits configured by the surrounding system; it does not force every request through research.
+
+## Run the agent
+
+From the application root, start a Ruby process that requires LittleGhost and asks the agent a question:
+
+```ruby
+require "little_ghost"
+
+runtime = LittleGhost::Runtime.new(configuration: LittleGhost.configuration)
+customer_support_agent = CustomerSupportAgent.new(runtime:)
+run = customer_support_agent.ask(
+  "I bought an item two weeks ago. Can I get a refund?"
+)
+
+if run.completed?
+  puts run.response
+else
+  warn "Support request ended as #{run.outcome}: #{run.error&.class}"
+end
+```
+
+`#ask` consumes the invocation and returns its owning `LittleGhost::Run`. A successful run exposes the final text through `#response` and the normalized terminal value through `#result`. It also retains outcome, usage, messages, and any terminal error.
+
+The model can call `HelpCenterLookupTool` with `{"topic":"refunds"}` and answer along these lines:
+
+```text
+Refunds are available within 30 days, so a purchase from two weeks ago is eligible.
+```
+
+Model wording is not deterministic. The important outcome is that the refund guidance comes from the validated tool result rather than from an unverified guess.
+
+## Stream the response
+
+Use `#stream_ask` when a console, web response, or UI should receive progress before the run completes:
+
+```ruby
+CustomerSupportAgent.new(runtime:).stream_ask("Can I get a refund?").each do |event|
+  case event.type
+  when :text_delta
+    print event.data.fetch(:text)
+  when :run_error
+    warn event.data.fetch(:message)
+  end
+end
+```
+
+The enumerator yields `LittleGhost::StreamEvent` objects. Text, tool activity, usage, traces, subagent activity, and terminal lifecycle facts share that interface, so adapters can translate one framework stream into a console, HTTP stream, or AG-UI transport.
+
+## Where to go next
+
+Read [Core Concepts](Core%20Concepts.md) for the distinction between model-directed subagents and application-directed workflows, how sessions and runs divide ownership, and when `ResponseWorkflow` is a better fit than delegation. The API reference covers exact signatures for `LittleGhost::Agent`, `LittleGhost::Tool`, `LittleGhost::ModelRegistry`, and `LittleGhost::Run`.