# Module LittleGhost

Documentation version: Edge

Canonical HTML: https://littleghostai.org/docs/LittleGhost.html

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.

## Class methods

<a id="method-c-configuration"></a>
### `.configuration`

```ruby
.configuration()
```

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

<a id="method-c-configure"></a>
### `.configure`

```ruby
.configure(&block)
```

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.

<a id="method-c-embed"></a>
### `.embed`

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

<a id="method-c-generate"></a>
### `.generate`

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

<a id="method-c-model_resolver"></a>
### `.model_resolver`

```ruby
.model_resolver()
```

Returns the model resolver owned by the active process configuration.

<a id="method-c-offload_blocking"></a>
### `.offload_blocking`

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

<a id="method-c-runtime"></a>
### `.runtime`

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

<a id="method-c-with_configuration"></a>
### `.with_configuration`

```ruby
.with_configuration(configuration)
```

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.