Module: LittleGhost

Defined in:
lib/little_ghost.rb,
lib/little_ghost/run.rb,
lib/little_ghost/tool.rb,
lib/little_ghost/agent.rb,
lib/little_ghost/graph.rb,
lib/little_ghost/model.rb,
lib/little_ghost/swarm.rb,
lib/little_ghost/usage.rb,
lib/little_ghost/errors.rb,
lib/little_ghost/events.rb,
lib/little_ghost/lookup.rb,
lib/little_ghost/content.rb,
lib/little_ghost/message.rb,
lib/little_ghost/network.rb,
lib/little_ghost/runtime.rb,
lib/little_ghost/sandbox.rb,
lib/little_ghost/session.rb,
lib/little_ghost/support.rb,
lib/little_ghost/version.rb,
lib/little_ghost/artifact.rb,
lib/little_ghost/assembly.rb,
lib/little_ghost/data_map.rb,
lib/little_ghost/path_set.rb,
lib/little_ghost/workflow.rb,
lib/little_ghost/artifacts.rb,
lib/little_ghost/code_mode.rb,
lib/little_ghost/execution.rb,
lib/little_ghost/mcp/types.rb,
lib/little_ghost/workspace.rb,
lib/little_ghost/invocation.rb,
lib/little_ghost/mcp/client.rb,
lib/little_ghost/run_result.rb,
lib/little_ghost/mcp/toolset.rb,
lib/little_ghost/run_context.rb,
lib/little_ghost/tools/shell.rb,
lib/little_ghost/agent/skills.rb,
lib/little_ghost/runtime/hook.rb,
lib/little_ghost/skills/skill.rb,
lib/little_ghost/stream_event.rb,
lib/little_ghost/ag_ui/adapter.rb,
lib/little_ghost/agent_builder.rb,
lib/little_ghost/configuration.rb,
lib/little_ghost/model_request.rb,
lib/little_ghost/models/target.rb,
lib/little_ghost/sandbox/mount.rb,
lib/little_ghost/sandbox/scope.rb,
lib/little_ghost/session_store.rb,
lib/little_ghost/tool_registry.rb,
lib/little_ghost/model_resolver.rb,
lib/little_ghost/model_response.rb,
lib/little_ghost/models/catalog.rb,
lib/little_ghost/models/details.rb,
lib/little_ghost/providers/base.rb,
lib/little_ghost/sandbox/limits.rb,
lib/little_ghost/sandbox/policy.rb,
lib/little_ghost/skills/catalog.rb,
lib/little_ghost/support/loader.rb,
lib/little_ghost/tool_execution.rb,
lib/little_ghost/agent/tool_loop.rb,
lib/little_ghost/code_mode/types.rb,
lib/little_ghost/execution_state.rb,
lib/little_ghost/instrumentation.rb,
lib/little_ghost/prompt_resolver.rb,
lib/little_ghost/agent/delegation.rb,
lib/little_ghost/assembly_builder.rb,
lib/little_ghost/code_mode/broker.rb,
lib/little_ghost/code_mode/engine.rb,
lib/little_ghost/providers/gemini.rb,
lib/little_ghost/providers/openai.rb,
lib/little_ghost/sandboxes/native.rb,
lib/little_ghost/support/executor.rb,
lib/little_ghost/support/redactor.rb,
lib/little_ghost/tools/filesystem.rb,
lib/little_ghost/code_mode/catalog.rb,
lib/little_ghost/code_mode/runtime.rb,
lib/little_ghost/code_mode/session.rb,
lib/little_ghost/provider_registry.rb,
lib/little_ghost/providers/bedrock.rb,
lib/little_ghost/structured_output.rb,
lib/little_ghost/subagents/manager.rb,
lib/little_ghost/support/callbacks.rb,
lib/little_ghost/tools/write_todos.rb,
lib/little_ghost/assembly_execution.rb,
lib/little_ghost/code_mode/protocol.rb,
lib/little_ghost/model_capabilities.rb,
lib/little_ghost/sandbox/filesystem.rb,
lib/little_ghost/sandboxes/seatbelt.rb,
lib/little_ghost/support/sse_parser.rb,
lib/little_ghost/agent_interjections.rb,
lib/little_ghost/agent_stream_source.rb,
lib/little_ghost/code_mode/ruby/host.rb,
lib/little_ghost/providers/anthropic.rb,
lib/little_ghost/providers/vertex_ai.rb,
lib/little_ghost/support/http_client.rb,
lib/little_ghost/models/configuration.rb,
lib/little_ghost/network/envoy_config.rb,
lib/little_ghost/sandbox/capabilities.rb,
lib/little_ghost/sandboxes/bubblewrap.rb,
lib/little_ghost/skills/resource_root.rb,
lib/little_ghost/subagents/agent_path.rb,
lib/little_ghost/subagents/definition.rb,
lib/little_ghost/code_mode/ruby_engine.rb,
lib/little_ghost/models/catalog/source.rb,
lib/little_ghost/network/envoy_gateway.rb,
lib/little_ghost/providers/open_router.rb,
lib/little_ghost/session_stores/memory.rb,
lib/little_ghost/code_mode/ruby/catalog.rb,
lib/little_ghost/code_mode/ruby/session.rb,
lib/little_ghost/sandbox/network_policy.rb,
lib/little_ghost/sandbox/process_runner.rb,
lib/little_ghost/sandboxes/unrestricted.rb,
lib/little_ghost/subagents/control_tool.rb,
lib/little_ghost/tracing/open_telemetry.rb,
lib/little_ghost/models/catalog_snapshot.rb,
lib/little_ghost/providers/configuration.rb,
lib/little_ghost/runtime/hooks/artifacts.rb,
lib/little_ghost/sandbox/process_session.rb,
lib/little_ghost/support/content_capture.rb,
lib/little_ghost/agent/context_management.rb,
lib/little_ghost/network/external_gateway.rb,
lib/little_ghost/sandbox/isolated_backend.rb,
lib/little_ghost/support/class_attributes.rb,
lib/little_ghost/artifacts/workspace_store.rb,
lib/little_ghost/code_mode/javascript/host.rb,
lib/little_ghost/network/authorizer_server.rb,
lib/little_ghost/session_stores/filesystem.rb,
lib/little_ghost/support/output_truncation.rb,
lib/little_ghost/sandbox/environment_policy.rb,
lib/little_ghost/support/cancellation_token.rb,
lib/little_ghost/code_mode/javascript/client.rb,
lib/little_ghost/code_mode/javascript_engine.rb,
lib/little_ghost/code_mode/javascript_engine.rb,
lib/little_ghost/providers/openai_compatible.rb,
lib/little_ghost/code_mode/javascript/catalog.rb,
lib/little_ghost/code_mode/javascript/session.rb,
lib/little_ghost/support/interruptible_stream.rb,
lib/little_ghost/artifacts/presentation_budget.rb,
lib/little_ghost/network/certificate_authority.rb,
lib/little_ghost/providers/bedrock/http_client.rb,
lib/little_ghost/providers/bedrock/aws_protocol.rb,
lib/little_ghost/providers/gemini/catalog_source.rb,
lib/little_ghost/models/catalog/models_dev_source.rb,
lib/little_ghost/providers/bedrock/catalog_source.rb,
lib/little_ghost/session_stores/agent_core_memory.rb,
lib/little_ghost/providers/anthropic/catalog_source.rb,
lib/little_ghost/providers/open_router/catalog_source.rb,
lib/little_ghost/providers/bedrock/credential_resolver.rb,
lib/little_ghost/providers/vertex_ai/credential_resolver.rb

Overview

Build AI features as ordinary Ruby classes. An Agent owns one model conversation. Larger units called Assemblies coordinate several Agents while keeping the same ask and stream_ask entrypoints.

Start with one model-driven behavior:

class CustomerSupportAgent < LittleGhost::Agent
description "Handles support requests"
model "openrouter:openai/gpt-5.6-luna"
system_prompt "Answer customer questions clearly."
end

run = CustomerSupportAgent.ask("Why is transfer 481 still pending?")
run.completed? # => true
run.response
# One possible response: Transfer 481 is waiting for the receiving bank.

The class holds reusable behavior. Each call creates a Run, which records the result and closes the resources opened for that request. Workflow, Swarm, and Graph are Assembly types for coordinating more than one participant.

Configure LittleGhost before the first call. The first standalone call builds a shared Runtime from that configuration. with_configuration can select an independent configuration for one execution context.

Defined Under Namespace

Modules: AGUI, AgentStreamSnapshot, Artifacts, CodeMode, Content, Events, ExecutionState, Instrumentation, Lookup, MCP, ModelInterface, Models, Network, Providers, Sandboxes, SessionStores, Skills, StructuredOutput, Subagents, Support, Tools, Tracing Classes: AbstractMethodError, AdapterLoadError, Agent, AgentBuilder, AgentFactory, AgentInterjectionError, AgentInterjections, AgentStreamSink, AgentStreamSource, AgentStreamStep, Artifact, Assembly, AssemblyBuilder, AssemblyDefinition, AssemblyError, AssemblyLimitError, AssemblyRoutingError, AssemblyStepTimeoutError, CancelledError, CapabilityError, CleanupError, Configuration, ConfigurationError, ContextWindowOverflowError, CredentialError, DataMap, DeadlineExceededError, DependencyError, Error, Execution, Graph, GraphBuilder, InvalidPromptTemplateError, Invocation, InvocationError, MalformedToolCallError, Message, MissingPromptLocalError, MissingPromptTemplateError, Model, ModelCapabilities, ModelRequest, ModelResolver, ModelResponse, OutputLimitError, PathSet, PolicyError, PromptResolver, PromptTemplateError, ProtocolError, ProviderError, ProviderRegistry, Run, RunContext, RunResult, Runtime, Sandbox, SandboxConfigurationError, Session, SessionStore, StreamEvent, StructuredResult, StructuredResultError, Swarm, SwarmBuilder, Tool, ToolError, ToolExecution, ToolLoopError, ToolRegistry, TrustedPath, UnsupportedInputError, UnsupportedPlatformError, Usage, Workflow, WorkflowBuilder, Workspace

Constant Summary collapse

VERSION =

Current LittleGhost gem version.

"0.5.0"

Class Method Summary collapse

Class Method Details

.configuration ⇒ Object

The configuration active in the current execution context, falling back to the process-wide default.



114
115
116
 
# File 'lib/little_ghost.rb', line 114

def configuration
  ExecutionState[:configuration] || (@configuration ||= Configuration.new)
end

.configure(&block) ⇒ Object

Opens the active Configuration for application setup and returns it.

Configuration files are loaded lazily when a runtime is first built, so make application-level changes before invoking an agent. Once the shared Runtime is ready, later mutations raise ConfigurationError.



123
124
125
 
# File 'lib/little_ghost.rb', line 123

def configure(&block)
  configuration.configure(&block)
end

.model_resolver ⇒ Object

Returns the model resolver owned by the active process configuration.



135
 
# File 'lib/little_ghost.rb', line 135

def model_resolver = configuration.model_resolver

.runtime ⇒ Object

Returns the shared Runtime for the active Configuration.

Most applications do not need to call this method. Standalone Agent and Assembly entrypoints use it automatically. Runtime construction is lazy, thread-safe, and locks the active Configuration after it succeeds.



132
 
# File 'lib/little_ghost.rb', line 132

def runtime = configuration.runtime

.with_configuration(configuration) ⇒ Object

Makes configuration and its independent shared Runtime current only while the block runs.

Execution state restores the previous configuration even when the block raises. Other execution contexts continue to see their own configuration.



142
143
144
 
# File 'lib/little_ghost.rb', line 142

def with_configuration(configuration)
  ExecutionState.with(configuration:) { yield }
end