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/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/assembly.rb,
lib/little_ghost/data_map.rb,
lib/little_ghost/path_set.rb,
lib/little_ghost/workflow.rb,
lib/little_ghost/execution.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/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/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/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/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/providers/gemini.rb,
lib/little_ghost/providers/openai.rb,
lib/little_ghost/support/executor.rb,
lib/little_ghost/support/redactor.rb,
lib/little_ghost/tools/filesystem.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/model_capabilities.rb,
lib/little_ghost/support/sse_parser.rb,
lib/little_ghost/agent_interjections.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/subagents/agent_path.rb,
lib/little_ghost/subagents/definition.rb,
lib/little_ghost/unrestricted_sandbox.rb,
lib/little_ghost/models/catalog/source.rb,
lib/little_ghost/providers/open_router.rb,
lib/little_ghost/session_stores/memory.rb,
lib/little_ghost/tracing/open_telemetry.rb,
lib/little_ghost/models/catalog_snapshot.rb,
lib/little_ghost/providers/configuration.rb,
lib/little_ghost/support/content_capture.rb,
lib/little_ghost/agent/context_management.rb,
lib/little_ghost/support/class_attributes.rb,
lib/little_ghost/session_stores/filesystem.rb,
lib/little_ghost/support/output_truncation.rb,
lib/little_ghost/support/cancellation_token.rb,
lib/little_ghost/providers/openai_compatible.rb,
lib/little_ghost/support/interruptible_stream.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

LittleGhost is a Ruby library for building AI features with reusable agents and composable assemblies. It can sit inside an existing Ruby system or support a dedicated AI service.

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.

Agent subclasses hold reusable behavior, Invocation objects carry one request, and Run objects own execution and cleanup. When one model loop is not enough, Assembly gives Agent, Workflow, Swarm, and Graph the same caller interface while each type owns a different coordination policy.

LittleGhost.configuration is process-wide unless LittleGhost.with_configuration supplies an execution-scoped replacement. The first standalone call lazily builds one shared Runtime from that configuration, so make application changes before invoking an Agent or Assembly.

Defined Under Namespace

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

Constant Summary collapse

VERSION =

Current LittleGhost gem version.

"0.4.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.



105
106
107
 
# File 'lib/little_ghost.rb', line 105

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.



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

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

.model_resolver ⇒ Object

Returns the model resolver owned by the active process configuration.



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

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.



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

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.



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

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