little_ghost 0.1.0 → 0.2.0

data/docs/guides/Getting Started.md

@@ -1,187 +0,0 @@
-# Getting Started with LittleGhost
-
-This guide builds a small AI customer support feature around an agent that checks an in-memory help center and returns a normal Ruby result. By the end, you will have configured a model provider, declared a validated tool, run `CustomerSupportAgent`, and streamed the same request as events.
-
-The example uses OpenAI, but the agent and tool do not depend on that choice. A `ModelRegistry` keeps the provider boundary behind the logical model role `customer_support`.
-
-## Before you begin
-
-LittleGhost requires Ruby 3.3 or newer. Add the gem to your `Gemfile`:
-
-```ruby
-gem "little_ghost"
-```
-
-Install the bundle and provide the credential used by this example:
-
-```sh
-$ bundle install
-$ export OPENAI_API_KEY="..."
-```
-
-Use application-specific secret management outside a local shell. Do not commit provider credentials.
-
-## Create the application shape
-
-LittleGhost looks for agents, tools, prompts, and skills under conventional application directories. This example needs four files:
-
-```text
-customer_support_app/
-├── app/
-│   ├── agents/
-│   │   ├── research_agent.rb
-│   │   └── customer_support_agent.rb
-│   └── tools/
-│       └── help_center_lookup_tool.rb
-└── config/
-    └── little_ghost.rb
-```
-
-Run the application from `customer_support_app/`, or set the configuration root explicitly before the first runtime is built. The runtime loads `config/little_ghost.rb` lazily and eager-loads conventional application code.
-
-## Configure a logical model role
-
-Define `CustomerSupportModels` in `config/little_ghost.rb` and register it with LittleGhost:
-
-```ruby
-require "little_ghost"
-
-class CustomerSupportModels < LittleGhost::ModelRegistry
-  def initialize
-    super
-
-    provider(:openai) do |model:, **|
-      LittleGhost::Providers::OpenAI.new(
-        api_key: ENV.fetch("OPENAI_API_KEY"),
-        model:
-      )
-    end
-
-    profile "customer_support",
-      provider: :openai,
-      model: "gpt-5",
-      settings: {temperature: 0.2}
-  end
-end
-
-LittleGhost.configure do |config|
-  config.models CustomerSupportModels
-end
-```
-
-The agent will ask for the role `customer_support`; it never needs the provider name or provider model identifier. This separation lets an application change providers or override a profile for one invocation without changing agent classes. Treat model settings and profile overrides as trusted application configuration: construct or allowlist them server-side instead of copying unchecked request fields.
-
-## Give the agent one validated tool
-
-Create `app/tools/help_center_lookup_tool.rb`:
-
-```ruby
-class HelpCenterLookupTool < LittleGhost::Tool
-  HELP_CENTER_ENTRIES = {
-    "refunds" => "Refunds are available within 30 days of purchase.",
-    "shipping" => "Standard shipping takes three to five business days."
-  }.freeze
-
-  description "Look up a help center entry by topic."
-  input_schema(
-    type: "object",
-    properties: {
-      topic: {type: "string", enum: HELP_CENTER_ENTRIES.keys}
-    },
-    required: ["topic"],
-    additionalProperties: false
-  )
-
-  def call(input)
-    HELP_CENTER_ENTRIES.fetch(input.fetch("topic"))
-  end
-end
-```
-
-A tool exposes a name, description, JSON input schema, and implementation. `HelpCenterLookupTool` gets its default model-visible name from the class name. LittleGhost validates input before calling `#call` and turns the returned value into text for model context.
-
-This boundary is also the right place for application authorization. If lookup behavior or results depended on an account or tenant, `#call` would verify trusted run context before reading them. A schema validates shape; it does not authorize access.
-
-## Define the agents
-
-Create `app/agents/research_agent.rb`:
-
-```ruby
-class ResearchAgent < LittleGhost::Agent
-  description "Investigates support questions that need broader research."
-  model "customer_support.research"
-  system_prompt "Research the question and return a concise evidence summary."
-end
-```
-
-There is no separate `customer_support.research` profile yet. Dotted roles fall back to the nearest registered parent, so this role resolves through `customer_support`. You can add a specialized profile later without changing `ResearchAgent`.
-
-Now create `app/agents/customer_support_agent.rb`:
-
-```ruby
-class CustomerSupportAgent < LittleGhost::Agent
-  description "Answers customer support questions."
-  model "customer_support"
-  system_prompt <<~PROMPT
-    Answer clearly and do not invent company guidance.
-    Use the help center lookup tool before stating company guidance.
-    Delegate open-ended investigation to the research agent.
-  PROMPT
-
-  tools HelpCenterLookupTool
-  subagent ResearchAgent, kind: "research"
-end
-```
-
-The class is a readable behavior boundary. It declares which model role, prompt, tools, and subagent capabilities can participate in a `CustomerSupportAgent` run. Declaring `ResearchAgent` as a subagent gives the model tools for delegation, with the turn, concurrency, and depth limits configured by the surrounding system; it does not force every request through research.
-
-## Run the agent
-
-From the application root, start a Ruby process that requires LittleGhost and asks the agent a question:
-
-```ruby
-require "little_ghost"
-
-runtime = LittleGhost::Runtime.new(configuration: LittleGhost.configuration)
-customer_support_agent = CustomerSupportAgent.new(runtime:)
-run = customer_support_agent.ask(
-  "I bought an item two weeks ago. Can I get a refund?"
-)
-
-if run.completed?
-  puts run.response
-else
-  warn "Support request ended as #{run.outcome}: #{run.error&.class}"
-end
-```
-
-`#ask` consumes the invocation and returns its owning `LittleGhost::Run`. A successful run exposes the final text through `#response` and the normalized terminal value through `#result`. It also retains outcome, usage, messages, and any terminal error.
-
-The model can call `HelpCenterLookupTool` with `{"topic":"refunds"}` and answer along these lines:
-
-```text
-Refunds are available within 30 days, so a purchase from two weeks ago is eligible.
-```
-
-Model wording is not deterministic. The important outcome is that the refund guidance comes from the validated tool result rather than from an unverified guess.
-
-## Stream the response
-
-Use `#stream_ask` when a console, web response, or UI should receive progress before the run completes:
-
-```ruby
-CustomerSupportAgent.new(runtime:).stream_ask("Can I get a refund?").each do |event|
-  case event.type
-  when :text_delta
-    print event.data.fetch(:text)
-  when :run_error
-    warn event.data.fetch(:message)
-  end
-end
-```
-
-The enumerator yields `LittleGhost::StreamEvent` objects. Text, tool activity, usage, traces, subagent activity, and terminal lifecycle facts share that interface, so adapters can translate one framework stream into a console, HTTP stream, or AG-UI transport.
-
-## Where to go next
-
-Read [Core Concepts](Core%20Concepts.md) for the distinction between model-directed subagents and application-directed workflows, how sessions and runs divide ownership, and when `ResponseWorkflow` is a better fit than delegation. The API reference covers exact signatures for `LittleGhost::Agent`, `LittleGhost::Tool`, `LittleGhost::ModelRegistry`, and `LittleGhost::Run`.

data/lib/little_ghost/default_model_registry.rb

@@ -1,71 +0,0 @@
-# frozen_string_literal: true
-
-module LittleGhost
-  # Supplies LittleGhost's ready-to-use model selection. The registry maps the
-  # +default+ role to GPT-5.6 Terra on OpenRouter or OpenAI and keeps the selected
-  # provider stable for its runtime.
-  #
-  # Prefixed credentials take precedence over conventional provider variables:
-  #
-  # 1. +LITTLEGHOST_OPENROUTER_API_KEY+
-  # 2. +LITTLEGHOST_OPENAI_API_KEY+
-  # 3. +OPENROUTER_API_KEY+
-  # 4. +OPENAI_API_KEY+
-  #
-  # Blank values are ignored. Resolving the +default+ role requires one supported
-  # key and raises ConfigurationError with the available choices otherwise. The
-  # environment is read when the registry is created, so build a new Runtime
-  # after changing credentials. Configure a ModelRegistry explicitly when the
-  # application needs another provider, model, or logical role.
-  #
-  # *Warning:* Setting any supported key authorizes LittleGhost to send model
-  # inputs, including prompts, conversation history, tool data, and attachments,
-  # to the selected external provider. When more than one key is present, the
-  # precedence above determines that destination. Applications with provider or
-  # data-residency requirements should configure a ModelRegistry explicitly.
-  class DefaultModelRegistry < ModelRegistry
-    CREDENTIALS = [
-      ["LITTLEGHOST_OPENROUTER_API_KEY", :openrouter],
-      ["LITTLEGHOST_OPENAI_API_KEY", :openai],
-      ["OPENROUTER_API_KEY", :openrouter],
-      ["OPENAI_API_KEY", :openai]
-    ].freeze # :nodoc:
-    MODELS = {
-      openrouter: "openai/gpt-5.6-terra",
-      openai: "gpt-5.6-terra"
-    }.freeze # :nodoc:
-    PROVIDERS = {
-      openrouter: Providers::OpenRouter,
-      openai: Providers::OpenAI
-    }.freeze # :nodoc:
-    MISSING_CREDENTIAL_MESSAGE =
-      "No API key is configured for the default model. Set " \
-      "LITTLEGHOST_OPENROUTER_API_KEY, LITTLEGHOST_OPENAI_API_KEY, " \
-      "OPENROUTER_API_KEY, or OPENAI_API_KEY, or configure a custom " \
-      "model registry with LittleGhost.configure." # :nodoc:
-
-    # Selects one provider from the current environment and registers the
-    # +default+ profile. The selection remains fixed for this registry instance.
-    def initialize
-      super
-      variable, provider_name = CREDENTIALS.find { |name, _provider| !ENV[name].to_s.strip.empty? }
-      if variable
-        api_key = ENV.fetch(variable)
-        provider_class = PROVIDERS.fetch(provider_name)
-        provider(provider_name) do |model:, **|
-          provider_class.new(api_key:, model:)
-        end
-        profile("default", provider: provider_name, model: MODELS.fetch(provider_name))
-      else
-        configure_missing_credential
-      end
-    end
-
-    private
-
-    def configure_missing_credential
-      provider(:unconfigured) { |**| raise ConfigurationError, MISSING_CREDENTIAL_MESSAGE }
-      profile("default", provider: :unconfigured, model: MODELS.fetch(:openai))
-    end
-  end
-end

data/lib/little_ghost/model_registry.rb

@@ -1,173 +0,0 @@
-# frozen_string_literal: true
-
-module LittleGhost
-  # Give application roles stable model choices without coupling agents to vendors.
-  # A registry joins provider factories with named, inheritable profiles.
-  #
-  # A support application can keep its general and research agents on related
-  # profiles while selecting one provider in one place:
-  #
-  #   class CustomerSupportModels < LittleGhost::ModelRegistry
-  #     def initialize
-  #       super
-  #       provider(:openai) do |model:, **|
-  #         LittleGhost::Providers::OpenAI.new(
-  #           api_key: ENV.fetch("OPENAI_API_KEY"), model: model
-  #         )
-  #       end
-  #       profile "customer_support", provider: :openai, model: "gpt-5"
-  #       profile "customer_support.research", inherit: "customer_support",
-  #         settings: {temperature: 0.1}
-  #     end
-  #   end
-  #
-  #   model = CustomerSupportModels.new.resolve("customer_support.research")
-  #   model.id       # => "gpt-5"
-  #   model.settings # => {temperature: 0.1}
-  #
-  # Dotted roles resolve from the exact role toward shorter registered parents.
-  # Explicit profile inheritance supplies provider, model, settings, and metadata;
-  # per-invocation overrides then layer from inherited parents through the exact
-  # requested role. A final +override+ passed to +resolve+ wins over both.
-  # Settings and overrides are control-plane input: construct or allowlist them
-  # in application code rather than copying unchecked request fields. An
-  # override can select a different registered provider or model and change the
-  # destination, capability, and cost of a request.
-  #
-  # Provider factories receive the resolved identity, settings, metadata,
-  # invocation, run context, and forwarding options. Resolution raises
-  # ConfigurationError for missing roles, providers, models, factories, or
-  # circular inheritance; exceptions raised inside a factory are not masked.
-  class ModelRegistry
-    # Starts an empty registry ready for provider factories and model profiles.
-    def initialize
-      @providers = {}
-      @profiles = {}
-    end
-
-    # Associates +name+ with a provider factory and returns +self+.
-    #
-    # The factory receives the resolved +model+, logical +role+, profile
-    # +settings+ and +metadata+, invocation, run context, and resolution options.
-    def provider(name, callable = nil, &factory)
-      @providers[name.to_sym] = factory || callable || raise(ArgumentError, "provider factory is required")
-      self
-    end
-
-    # Adds an inheritable model profile named +name+ and returns +self+.
-    #
-    # Parent settings and metadata merge into the child. A child may inherit its
-    # provider and model or replace either one.
-    def profile(name, provider: nil, model: nil, settings: {}, metadata: {}, inherit: nil)
-      @profiles[name.to_s] = {
-        provider: provider&.to_sym,
-        model: model&.to_s,
-        settings: settings.to_h.transform_keys(&:to_sym),
-        metadata: metadata.to_h,
-        inherit: inherit&.to_s
-      }
-      self
-    end
-
-    # Materializes +name+ as a configured Model for the current invocation.
-    #
-    # +override+ applies after registered profiles and invocation profile
-    # overrides. +context+ takes precedence over the legacy +run+ argument when
-    # passed to the provider factory.
-    def resolve(name, invocation: nil, override: nil, run: nil, context: nil, **options)
-      role = name.to_s
-      profile_name = profile_for(role)
-      configuration = resolved_profile(profile_name)
-      override_profiles(profile_name, role).each do |profile|
-        configuration = merge(configuration, profile_override(invocation, profile))
-      end
-      configuration = merge(configuration, override)
-      provider_name = configuration[:provider]
-      model_id = configuration[:model]
-      raise ConfigurationError, "Model profile #{profile_name} does not define a provider" unless provider_name
-      raise ConfigurationError, "Model profile #{profile_name} does not define a model" unless model_id
-
-      factory = @providers.fetch(provider_name) do
-        raise ConfigurationError, "No provider is registered for #{provider_name}"
-      end
-      provider = factory.call(
-        model: model_id,
-        role:,
-        settings: configuration.fetch(:settings),
-        metadata: configuration.fetch(:metadata),
-        invocation:,
-        context: context || run,
-        **options
-      )
-      Model.new(
-        provider:,
-        provider_name:,
-        model: model_id,
-        settings: configuration.fetch(:settings),
-        metadata: configuration.fetch(:metadata),
-        role:
-      )
-    end
-
-    private
-
-    def merge(configuration, override)
-      values = (override || {}).to_h.transform_keys(&:to_sym)
-      settings = values.fetch(:settings, values.fetch(:parameters, {})).to_h.transform_keys(&:to_sym)
-      configuration
-        .merge(values.except(:settings, :parameters, :model_id))
-        .merge(
-          provider: values.key?(:provider) ? values[:provider]&.to_sym : configuration[:provider],
-          model: values.fetch(:model, values.fetch(:model_id, configuration[:model])),
-          settings: configuration.fetch(:settings).merge(settings),
-          metadata: configuration.fetch(:metadata).merge(values.fetch(:metadata, {}))
-        )
-    end
-
-    def profile_for(role)
-      parts = role.to_s.split(".")
-      until parts.empty?
-        candidate = parts.join(".")
-        return candidate if @profiles.key?(candidate)
-
-        parts.pop
-      end
-      raise ConfigurationError, "Unknown model profile: #{role}"
-    end
-
-    def resolved_profile(name, seen = [])
-      raise ConfigurationError, "Circular model profile inheritance: #{[*seen, name].join(" -> ")}" if seen.include?(name)
-
-      profile = @profiles.fetch(name) do
-        raise ConfigurationError, "Unknown model profile: #{name}"
-      end
-      parent_name = profile.fetch(:inherit)
-      return profile unless parent_name
-
-      parent = resolved_profile(parent_name, [*seen, name])
-      {
-        provider: profile.fetch(:provider) || parent.fetch(:provider),
-        model: profile.fetch(:model) || parent.fetch(:model),
-        settings: parent.fetch(:settings).merge(profile.fetch(:settings)),
-        metadata: parent.fetch(:metadata).merge(profile.fetch(:metadata)),
-        inherit: parent_name
-      }
-    end
-
-    def override_profiles(profile_name, role)
-      names = []
-      current = profile_name
-      while current
-        names.unshift(current)
-        current = @profiles.fetch(current).fetch(:inherit)
-      end
-      names << role unless names.include?(role)
-      names
-    end
-
-    def profile_override(invocation, role)
-      profiles = invocation&.model_profiles || {}
-      profiles[role.to_s] || {}
-    end
-  end
-end

data/lib/little_ghost/providers/http_transport.rb

@@ -1,149 +0,0 @@
-# frozen_string_literal: true
-
-require "net/http"
-require "openssl"
-require "uri"
-
-module LittleGhost
-  module Providers
-    # Reports an HTTP or network failure from a provider transport.
-    class HTTPError < ProviderError
-      # HTTP status and bounded response body, when the server supplied them.
-      attr_reader :status, :body
-
-      # Creates an error with optional response details.
-      def initialize(message, status: nil, body: nil)
-        @status = status
-        @body = body
-        super(message)
-      end
-
-      # Indicates whether a provider client may retry the request.
-      def retryable?
-        status.nil? || status == 408 || status == 409 || status == 429 || status >= 500
-      end
-    end
-
-    # HTTPTransport gives provider clients a shared, bounded streaming HTTP layer.
-    # It applies cancellation, deadlines, timeouts, and response-size limits while
-    # yielding response chunks as they arrive.
-    #
-    # === Security and trust
-    #
-    # HTTPS is required by default. Enabling +allow_insecure_http+ can expose API
-    # keys and model content in transit; use it only with a trusted local
-    # development endpoint.
-    class HTTPTransport
-      # Default upper bound for a complete provider response (50 MiB).
-      DEFAULT_MAX_RESPONSE_BYTES = 50 * 1024 * 1024
-      DEFAULT_MAX_ERROR_BODY_BYTES = 4 * 1024 # :nodoc:
-      TRANSIENT_NETWORK_ERRORS = [
-        Net::OpenTimeout,
-        Net::ReadTimeout,
-        Net::WriteTimeout,
-        EOFError,
-        SocketError,
-        SystemCallError,
-        IOError,
-        OpenSSL::SSL::SSLError,
-        Net::ProtocolError,
-        Net::HTTPBadResponse,
-        Net::HTTPHeaderSyntaxError
-      ].freeze # :nodoc:
-
-      # Configures +base_url+ with connection, read, and response
-      # size limits.
-      def initialize(
-        base_url:,
-        open_timeout:,
-        read_timeout:,
-        allow_insecure_http: false,
-        max_response_bytes: DEFAULT_MAX_RESPONSE_BYTES,
-        max_error_body_bytes: DEFAULT_MAX_ERROR_BODY_BYTES
-      )
-        @base_url = URI(base_url.end_with?("/") ? base_url : "#{base_url}/")
-        unless %w[http https].include?(@base_url.scheme) && @base_url.host
-          raise ConfigurationError, "Provider base_url must be an HTTP(S) URL"
-        end
-        if @base_url.scheme == "http" && !allow_insecure_http
-          raise ConfigurationError, "Provider base_url must use HTTPS unless allow_insecure_http is enabled"
-        end
-
-        @open_timeout = open_timeout
-        @read_timeout = read_timeout
-        @max_response_bytes = positive_integer(max_response_bytes, :max_response_bytes)
-        @max_error_body_bytes = positive_integer(max_error_body_bytes, :max_error_body_bytes)
-      end
-
-      # Posts +body+ and yields response chunks until completion.
-      #
-      # Cancellation and +deadline+ interrupt the request. Without a block, this
-      # method returns an Enumerator.
-      def stream(path:, headers:, body:, cancellation_token:, deadline: nil)
-        return enum_for(__method__, path:, headers:, body:, cancellation_token:, deadline:) unless block_given?
-
-        stream = Support::InterruptibleStream.new(cancellation_token:, deadline:) do |emit|
-          uri = URI.join(@base_url.to_s, path.sub(%r{\A/}, ""))
-          request = Net::HTTP::Post.new(uri)
-          headers.each { |name, value| request[name] = value }
-          request.body = body
-
-          http = Net::HTTP.new(uri.host, uri.port)
-          http.use_ssl = uri.scheme == "https"
-          http.open_timeout = remaining_timeout(deadline, @open_timeout)
-          http.read_timeout = remaining_timeout(deadline, @read_timeout)
-          http.write_timeout = remaining_timeout(deadline, @read_timeout)
-
-          http.request(request) do |response|
-            unless response.is_a?(Net::HTTPSuccess)
-              response_body = read_limited(response, @max_error_body_bytes)
-              raise HTTPError.new(
-                "Provider request failed with HTTP #{response.code}",
-                status: response.code.to_i,
-                body: response_body
-              )
-            end
-
-            bytes_read = 0
-            response.read_body do |chunk|
-              bytes_read += chunk.bytesize
-              raise ProtocolError, "Provider response exceeded #{@max_response_bytes} bytes" if bytes_read > @max_response_bytes
-
-              emit.call(chunk)
-            end
-          end
-        rescue *TRANSIENT_NETWORK_ERRORS => error
-          raise HTTPError, "Provider request failed (#{error.class})"
-        end
-        stream.each { |chunk| yield chunk }
-      end
-
-      private
-
-      def remaining_timeout(deadline, maximum)
-        return maximum unless deadline
-
-        remaining = deadline - Time.now
-        raise DeadlineExceededError, "The run deadline was reached" unless remaining.positive?
-
-        [remaining, maximum].min
-      end
-
-      def read_limited(response, limit)
-        body = +""
-        response.read_body do |chunk|
-          remaining = limit - body.bytesize
-          body << chunk.byteslice(0, remaining) if remaining.positive?
-        end
-        body
-      end
-
-      def positive_integer(value, name)
-        integer = Integer(value)
-        raise ArgumentError, "#{name} must be positive" unless integer.positive?
-
-        integer
-      end
-    end
-  end
-end