Module: LittleGhost

Defined in:
lib/little_ghost.rb,
lib/little_ghost/cli.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/console.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/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/support/task.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/model_operations.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/embeddings/request.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/embeddings/response.rb,
lib/little_ghost/providers/anthropic.rb,
lib/little_ghost/providers/lm_studio.rb,
lib/little_ghost/providers/vertex_ai.rb,
lib/little_ghost/support/http_client.rb,
lib/little_ghost/support/task_runner.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/support/pooled_thread_runner.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/support/serialized_dispatcher.rb,
lib/little_ghost/providers/bedrock/aws_protocol.rb,
lib/little_ghost/providers/gemini/catalog_source.rb,
lib/little_ghost/generators/application_generator.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/lm_studio/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, Embeddings, Events, ExecutionState, Generators, 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, BundleInstaller, CLI, CancelledError, CapabilityError, CleanupError, Configuration, ConfigurationError, Console, ContextWindowOverflowError, CredentialError, DataMap, DeadlineExceededError, DependencyError, Error, Execution, Graph, GraphBuilder, InvalidPromptTemplateError, Invocation, InvocationError, MalformedToolCallError, Message, MissingPromptLocalError, MissingPromptTemplateError, Model, ModelCapabilities, ModelOperations, 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, UnsupportedModelOperationError, UnsupportedPlatformError, Usage, Workflow, WorkflowBuilder, Workspace

Constant Summary collapse

VERSION =

Current LittleGhost gem version.

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



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

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.



144
145
146
 
# File 'lib/little_ghost.rb', line 144

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

.embed ⇒ Object

:call-seq:

LittleGhost.embed(model:, inputs:, settings: {}, limits: {}, cancellation_token: Support::CancellationToken.new, deadline: nil) -> Embeddings::Response

Embeds one or more strings and returns vectors in input order.

model, settings, and any raised limits are trusted application controls. The operation raises rather than returning a partial batch.



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

def embed(...) = runtime.embed(...)

.generate ⇒ Object

:call-seq:

LittleGhost.generate(model:, messages:, result_schema: nil, settings: {}, structured_result_repair_attempts: 1, cancellation_token: Support::CancellationToken.new, deadline: nil) -> RunResult

Generates one model response and returns a RunResult.

Use this entrypoint when application code owns the workflow and does not need Tools, Sessions, delegation, or agent callbacks. model and settings are trusted application controls. A result_schema checks one object result. When the result is invalid, the default permits one repair attempt. Set structured_result_repair_attempts to an integer from zero through three when a checked result warrants additional attempts.



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

def generate(...) = runtime.generate(...)

.model_resolver ⇒ Object

Returns the model resolver owned by the active process configuration.



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

def model_resolver = configuration.model_resolver

.offload_blocking(&operation) ⇒ Object

:call-seq:

LittleGhost.offload_blocking { ... } -> object

Runs a call that is known or measured to pause other fibers and can make progress on another Ruby thread. Inside a scheduled fiber, the block uses a shared thread pool. Otherwise, it runs inline. Returns the block's value.

Once the pool accepts the block, LittleGhost waits for it to finish before re-raising an interruption. The block's own exception is also re-raised. The helper does not add a timeout or cancellation mechanism, so configure those limits on the underlying operation when it supports them.

Raises:

  • (ArgumentError) 


127
128
129
130
131
 
# File 'lib/little_ghost.rb', line 127

def offload_blocking(&operation)
  raise ArgumentError, "a blocking operation block is required" unless operation

  Support::Executor.blocking.call(&operation)
end

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



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

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.



185
186
187
 
# File 'lib/little_ghost.rb', line 185

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