module LittleGhost

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.

Constants

VERSION: Current LittleGhost gem version.

Public Class Methods

configuration ()

Source

# File lib/little_ghost.rb, line 134
def configuration
  ExecutionState[:configuration] || (@configuration ||= Configuration.new)
end

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

configure (&block)

Source

# File lib/little_ghost.rb, line 143
def configure(&block)
  configuration.configure(&block)
end

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.

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

Source

# File lib/little_ghost.rb, line 177
def embed(...) = runtime.embed(...)

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.

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

Source

# File lib/little_ghost.rb, line 168
def generate(...) = runtime.generate(...)

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.

model_resolver ()

Source

# File lib/little_ghost.rb, line 155
def model_resolver = configuration.model_resolver

Returns the model resolver owned by the active process configuration.

offload_blocking { ... } → object

Source

# File lib/little_ghost.rb, line 126
def offload_blocking(&operation)
  raise ArgumentError, "a blocking operation block is required" unless operation

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

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.

runtime ()

Source

# File lib/little_ghost.rb, line 152
def runtime = configuration.runtime

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.

with_configuration (configuration) { || ... }

Source

# File lib/little_ghost.rb, line 184
def with_configuration(configuration)
  ExecutionState.with(configuration:) { yield }
end

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.