class LittleGhost::Configuration

Configure shared services and lookup rules before agents start. A configuration collects model profiles, persistence, paths, instrumentation, and runtime hooks for an application.

LittleGhost.configure do |config|
  config.models CustomerSupportModels
  config.default_model :customer_support
  config.service_name "support-api"
end

LittleGhost.configuration.default_model # => "customer_support"
LittleGhost.configuration.service_name  # => "support-api"

Prompt and skill lookup paths default to app/prompts and app/skills under the application root. Applications may append shared roots or replace the arrays entirely.

Configuration is a mutable builder, while each Runtime owns a settings snapshot. The first runtime for a root loads config/little_ghost.rb once; later mutations do not alter that runtime, and one configuration cannot load files for two different roots.

Session actor resolvers belong at an authentication boundary. Multi-tenant applications should derive actor identity from trusted authenticated state, not from an unverified request field.

Public Class Methods

new (values = {})

Source

# File lib/little_ghost/configuration.rb, line 111
def initialize(values = {})
  @configuration_values = {
    prompt_paths: DEFAULT_PROMPT_PATHS.dup,
    skill_paths: DEFAULT_SKILL_PATHS.dup,
    skill_resource_root: nil,
    workspace: nil,
    sandbox: nil,
    instrumentation_subscribers: [],
    runtime_hooks: []
  }.merge(values)
  @configuration_values[:prompt_paths] = Array(@configuration_values[:prompt_paths]).dup
  @configuration_values[:skill_paths] = Array(@configuration_values[:skill_paths]).dup
  @configuration_values[:instrumentation_subscribers] = Array(
    @configuration_values[:instrumentation_subscribers]
  ).dup
  @configuration_values[:runtime_hooks] = Array(@configuration_values[:runtime_hooks]).dup
end

Starts a mutable builder with optional values.

Prompt paths default to app/prompts and skill paths to app/skills. Collection settings are copied so callers can safely reuse their input arrays after construction.

Public Instance Methods

[] (name)

Source

# File lib/little_ghost/configuration.rb, line 166
def [](name)
  configuration_values.fetch(name.to_sym)
end

Looks up an arbitrary setting by symbol or string-compatible name.

[]= (name, value)

Source

# File lib/little_ghost/configuration.rb, line 171
def []=(name, value)
  configuration_values[name.to_sym] = value
end

Adds or replaces an arbitrary setting.

configure () { |self| ... }

Source

# File lib/little_ghost/configuration.rb, line 130
def configure
  yield self if block_given?
  self
end

Yields this builder for setup and returns the same instance.

default_model() → String, nil

default_model(value) → String

Source

# File lib/little_ghost/configuration.rb, line 59

The fallback logical model role for agents without an explicit role. Values are normalized to strings.

default_model=(value) → String

Source

# File lib/little_ghost/configuration.rb, line 93

Replaces the fallback logical model role and normalizes it to a String.

instrument (subscriber)

Source

# File lib/little_ghost/configuration.rb, line 181
def instrument(subscriber)
  unless subscriber.is_a?(Instrumentation::Subscriber)
    raise ArgumentError, "instrumentation subscriber must be a LittleGhost::Instrumentation::Subscriber"
  end

  configuration_values[:instrumentation_subscribers] << subscriber
  subscriber
end

Adds an Instrumentation::Subscriber to each new runtime and returns it.

invocation() → value

invocation(value) → value

Source

# File lib/little_ghost/configuration.rb, line 40

The request envelope class used to parse application payloads.

invocation=(value) → value

Source

# File lib/little_ghost/configuration.rb, line 81

Replaces the request envelope class for subsequently built runtimes.

log_events_to() → :stdout, :stderr, nil

log_events_to(destination) → destination

Source

# File lib/little_ghost/configuration.rb, line 200
def log_events_to(destination = :__read__)
  return Events.console_output if destination == :__read__

  Events.console_output = destination
end

Sends structured framework events to :stdout or :stderr. This setting controls the process-wide Events console destination; the most recent setting replaces it without changing other event listeners. By default, events have no console destination. Passing nil disables console output. The console listener redacts sensitive values and writes one JSON object per line.

log_events_to= (destination)

Source

# File lib/little_ghost/configuration.rb, line 207
def log_events_to=(destination)
  log_events_to(destination)
end

Replaces the console destination for structured framework events.

models() → value

models(value) → value

Source

# File lib/little_ghost/configuration.rb, line 50

The model registry class or instance used to resolve logical roles. By default, DefaultModelRegistry selects a built-in provider from supported environment variables.

models=(value) → value

Source

# File lib/little_ghost/configuration.rb, line 87

Replaces the model registry declaration for subsequently built runtimes.

prompt_paths ()

Source

# File lib/little_ghost/configuration.rb, line 259
def prompt_paths = configuration_values[:prompt_paths]

Mutable prompt lookup paths, in precedence order.

prompt_paths= (value)

Source

# File lib/little_ghost/configuration.rb, line 262
def prompt_paths=(value)
  configuration_values[:prompt_paths] = Array(value)
end

Replaces prompt lookup paths with value converted to an Array.

root() → Pathname

root(path) → Pathname

Source

# File lib/little_ghost/configuration.rb, line 249
def root(value = :__read__)
  if value != :__read__
    return configuration_values[:root] = canonical_root(value)
  end

  configured = configuration_values[:root]
  configured ? canonical_root(configured) : inferred_root
end

The resolved application root, defaulting to Dir.pwd.

Setting or reading an invalid root raises ConfigurationError. Symlinks are resolved so runtimes and lookup paths share one stable boundary.

root= (value)

Source

# File lib/little_ghost/configuration.rb, line 176
def root=(value)
  root(value)
end

Replaces the application root after resolving it to a stable real path.

runtime_hook (hook_class)

Source

# File lib/little_ghost/configuration.rb, line 212
def runtime_hook(hook_class)
  unless hook_class.is_a?(Class) && hook_class <= Runtime::Hook
    raise ArgumentError, "runtime_hook must be a LittleGhost::Runtime::Hook class"
  end

  configuration_values[:runtime_hooks] << hook_class
  hook_class
end

Adds a Runtime::Hook subclass to each new runtime and returns it.

sandbox ()

Source

# File lib/little_ghost/configuration.rb, line 138
def sandbox = configuration_values[:sandbox]

Sandbox declaration used for subsequently built runtimes.

sandbox= (value)

Source

# File lib/little_ghost/configuration.rb, line 148
def sandbox=(value)
  @configuration_values[:sandbox] = component_class(value, Sandbox, :sandbox)
end

Selects the Sandbox subclass instantiated around each run’s workspace.

service_name() → value

service_name(value) → value

Source

# File lib/little_ghost/configuration.rb, line 71
CONFIGURATION_KEYS.each do |name|
  define_method(name) do |value = :__read__|
    return configuration_values[name] if value == :__read__

    configuration_values[name] = (name == :default_model) ? value.to_s : value
  end
end

The low-cardinality service name attached to instrumentation.

service_name=(value) → value

Source

# File lib/little_ghost/configuration.rb, line 102
CONFIGURATION_KEYS.each do |name|
  define_method("#{name}=") { |value| public_send(name, value) }
end

Replaces the service name attached to telemetry from new runtimes.

session_actor() → callable, nil

session_actor(callable) → callable

session_actor { |invocation| ... } → callable

Source

# File lib/little_ghost/configuration.rb, line 230
def session_actor(value = :__read__, &resolver)
  return configuration_values[:session_actor] if value == :__read__ && !resolver

  raise ArgumentError, "Provide a session actor resolver or a block, not both" if value != :__read__ && resolver

  configured = resolver || value
  raise ArgumentError, "session_actor must be callable" unless configured.respond_to?(:call)

  configuration_values[:session_actor] = configured
end

The callable that derives the persistence actor for each invocation.

Pass either a callable or a block. The configured resolver should use trusted authenticated identity in multi-tenant applications.

session_store ()

Source

# File lib/little_ghost/configuration.rb, line 140
def session_store = configuration_values[:session_store]

Session-store declaration used for subsequently built runtimes.

session_store= (value)

Source

# File lib/little_ghost/configuration.rb, line 156
def session_store=(value)
  unless value.is_a?(Hash)
    raise ArgumentError, "session_store must be a hash with a provider"
  end

  provider = value[:provider]
  @configuration_values[:session_store] = value.merge(provider: component_class(provider, SessionStore, :session_store))
end

Selects session persistence with a :provider and its constructor options.

The provider must be a SessionStore subclass. Runtime construction creates and owns the store instance.

skill_paths ()

Source

# File lib/little_ghost/configuration.rb, line 267
def skill_paths = configuration_values[:skill_paths]

Mutable skill lookup paths, in precedence order.

skill_paths= (value)

Source

# File lib/little_ghost/configuration.rb, line 270
def skill_paths=(value)
  configuration_values[:skill_paths] = Array(value)
end

Replaces skill lookup paths with value converted to an Array.

skill_resource_root ()

Source

# File lib/little_ghost/configuration.rb, line 275
def skill_resource_root = configuration_values[:skill_resource_root]

Optional trusted root exposed to skills for resource lookup.

skill_resource_root= (value)

Source

# File lib/little_ghost/configuration.rb, line 278
def skill_resource_root=(value)
  configuration_values[:skill_resource_root] = value
end

Replaces the trusted skill resource root for new runtimes.

workspace ()

Source

# File lib/little_ghost/configuration.rb, line 136
def workspace = configuration_values[:workspace]

Workspace declaration used for subsequently built runtimes.

workspace= (value)

Source

# File lib/little_ghost/configuration.rb, line 143
def workspace=(value)
  @configuration_values[:workspace] = component_class(value, Workspace, :workspace)
end

Selects the Workspace subclass instantiated for each run.