little_ghost 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f7e4df5249569e4b93c22c44929064ad12632ca6119667429004ffc3bc4b7f7a
-  data.tar.gz: 6ad9b9d7252c1e0749f8d4503ba820259257fb4b0e46bc638ff3bd426ed191d9
+  metadata.gz: d214ff7dd49c056712968000f9ddc127bc132dd4b97b8f0c89bb3adb2f52f3b0
+  data.tar.gz: de2f85339390969db2ae0863bf9056ab386b07e2bf05cc976f23899ae2b318d2
 SHA512:
-  metadata.gz: 0a1e7fdc5cfe228456703b0d8b383f67461f5a465f962f010cacbee5ef55a90881f7e7135c5107745f1442a0803ddbe865b4d50912485e738b21566282404c34
-  data.tar.gz: db5f637104b9c42a8d470b80079b29a877fddf8a41c1a5c110d8a4b926c136b36933ffe234870a0ab1a53f98083d5f856f2fd1c44ea967ae9852f5d7abebc878
+  metadata.gz: 48004e9b2b4c826877601f31681129f5f0434f544aa979941d2d09840ca677ccbf86e0334cdd9de60081601e039326d445a033064940049dbd3f5e27243f47ac
+  data.tar.gz: 88fc87d32cb553b047273e249685f410ff8721e32275a3f3800e00cd79a674fb43188b0ef34d2b0a2ca04c4502a18503a6da791d2634ec92f4bc539d665ad36a

data/README.md

@@ -1,8 +1,8 @@
 # Build AI features that feel at home in Ruby
 
 > **Using a coding agent?** Start with
-> [`llms.txt`](https://mattyr.github.io/little_ghost/llms.txt) for a concise map
-> of the guides and API. [`llms-full.txt`](https://mattyr.github.io/little_ghost/llms-full.txt)
+> [`llms.txt`](https://littleghostai.org/llms.txt) for a concise map
+> of the guides and API. [`llms-full.txt`](https://littleghostai.org/llms-full.txt)
 > contains the complete documentation in one file.
 
 LittleGhost is a Ruby library for building AI features with agents and composable assemblies. With `OPENROUTER_API_KEY` set, start with one class, give it a prompt, and call it like the rest of your application code:
@@ -134,7 +134,7 @@ upgrading, because interfaces may change between releases.
 
 ### For contributors
 
-See the [contributing guide](https://github.com/mattyr/little_ghost/blob/main/CONTRIBUTING.md), [Code of Conduct](https://github.com/mattyr/little_ghost/blob/main/CODE_OF_CONDUCT.md), and [security policy](https://github.com/mattyr/little_ghost/blob/main/SECURITY.md).
+See the [contributing guide](https://github.com/littleghostai/little_ghost/blob/main/CONTRIBUTING.md), [Code of Conduct](https://github.com/littleghostai/little_ghost/blob/main/CODE_OF_CONDUCT.md), and [security policy](https://github.com/littleghostai/little_ghost/blob/main/SECURITY.md).
 
 ```sh
 $ bundle install

data/docs/guides/code_mode.md

@@ -99,6 +99,8 @@ do not carry into a later `exec`. Within one program, the model can use:
   order.
 - `ALL_TOOLS` to inspect the complete runtime catalog.
 - `text(value)` to add user-visible output.
+- Ordinary Ruby output from `puts`, `print`, `printf`, and `p`, which is
+  captured as user-visible output and combined into bounded chunks.
 - The program's final expression as the completed value returned by `exec` or
   a later `wait`.
 - `finish(value)` to complete early.

data/docs/guides/models_and_providers.md

@@ -120,6 +120,97 @@ choose a structured-result strategy.
 Provider capabilities can change. Handle failed Runs and provider errors even
 when the catalog says a feature is supported.
 
+## Call a model without an Agent
+
+Some application work needs one model response rather than an Agent. Use
+`LittleGhost.generate` for tasks such as classification, extraction, or
+rewriting when your application already owns the surrounding workflow:
+
+```ruby
+response = LittleGhost.generate(
+  model: :customer_support,
+  messages: [
+    {role: :system, content: "Classify the request."},
+    {role: :user, content: "My transfer is still pending."}
+  ],
+  settings: {temperature: 0}
+)
+
+response.output
+response.usage.total_tokens
+```
+
+The operation returns a `LittleGhost::RunResult`, the same result type returned
+by an Agent invocation, so
+application code can read `output`, `usage`, and the final message in the same
+way. Plain generation makes one model request without starting an Agent or
+creating a Run. Structured generation may make one additional repair request.
+
+Pass a strict object schema when application code needs checked JSON:
+
+```ruby
+response = LittleGhost.generate(
+  model: :customer_support,
+  messages: [{role: :user, content: "My transfer is still pending."}],
+  result_schema: {
+    name: "classification",
+    description: "Classify one support request",
+    schema: {
+      type: "object",
+      properties: {category: {type: "string"}},
+      required: ["category"],
+      additionalProperties: false
+    }
+  }
+)
+
+response.output
+```
+
+LittleGhost checks the result against the schema and gives the model one repair
+attempt by default. Add `structured_result_repair_attempts: 3` to the call
+above when a checked result warrants additional attempts. The setting accepts
+integers from zero through three.
+
+Read the checked value through `response.output`. If every permitted attempt is
+invalid, the call raises `LittleGhost::StructuredResultError`.
+
+A schema checks the shape of a value, not whether your application should act
+on it. Check identifiers, permissions, and business rules before using the
+result to change application state.
+
+## Create embeddings
+
+Use `LittleGhost.embed` when your application needs numeric representations for
+search, clustering, or another similarity-based feature:
+
+The example assumes application startup maps `search_embeddings` to an
+embedding model, following the role configuration shown earlier on this page.
+The selected provider adapter's API reference lists the model-specific
+settings.
+
+```ruby
+response = LittleGhost.embed(
+  model: :search_embeddings,
+  inputs: ["Reset a password", "Track a transfer"]
+)
+
+response.vectors.length # => 2
+response.dimensions
+response.usage.input_tokens
+```
+
+The response keeps vectors in the same order as the inputs. LittleGhost rejects
+an incomplete or malformed response instead of returning a partial batch.
+Choose the embedding model and request settings in trusted application
+configuration, and keep each call within a workload size your application can
+retry safely.
+
+Embedding text is sent to the selected provider. Choose a provider that is
+appropriate for that data, just as you would for an Agent request. See
+`LittleGhost::Embeddings::Request` and your provider adapter's API reference for
+the supported settings and request bounds.
+
 Continue with [Prompts as Views](prompt_views.md) when an Agent's instructions
 outgrow one string. See [Structured Results and Content](structured_outputs_and_content.md)
 when you need checked result shapes, images, or documents.

data/lib/little_ghost/code_mode/ruby/host.rb

@@ -6,6 +6,9 @@ module LittleGhost
       module Host # :nodoc:
         SOURCE = <<~'RUBY'
             require "json"
+            protocol_output = STDOUT.dup
+            protocol_output.sync = true
+            STDOUT.reopen(STDERR)
             STDOUT.sync = true
             begin
             read_exactly = lambda do |length|
@@ -21,9 +24,9 @@ module LittleGhost
             write_frame = lambda do |value|
               payload = JSON.generate(value)
               raise "protocol frame too large" if payload.bytesize > 64 * 1024 * 1024
-              STDOUT.write([payload.bytesize].pack("N"))
-              STDOUT.write(payload)
-              STDOUT.flush
+              protocol_output.write([payload.bytesize].pack("N"))
+              protocol_output.write(payload)
+              protocol_output.flush
             end
             request = read_frame.call
             catalog = request.fetch("catalog")
@@ -32,7 +35,40 @@ module LittleGhost
             response_queues = {}
             calls = 0
             max_calls = request.fetch("tool_calls")
-            emit = ->(value) { write_lock.synchronize { write_frame.call(value) } }
+            output_buffer = +""
+            flush_output = lambda do
+              unless output_buffer.empty?
+                value = output_buffer.dup
+                output_buffer.clear
+                write_frame.call(type: "text", value: value)
+              end
+            end
+            emit = lambda do |value|
+              write_lock.synchronize do
+                flush_output.call
+                write_frame.call(value)
+              end
+            end
+            program_output = Object.new
+            program_output.define_singleton_method(:write) do |value|
+              value = String(value)
+              write_lock.synchronize do
+                output_buffer << value
+                flush_output.call if output_buffer.bytesize >= 16_384 || value.include?("\n")
+              end
+              value.bytesize
+            end
+            program_output.define_singleton_method(:flush) do
+              write_lock.synchronize { flush_output.call }
+              self
+            end
+            program_output.define_singleton_method(:sync) { false }
+            program_output.define_singleton_method(:sync=) do |value|
+              flush if value
+              value
+            end
+            program_output.define_singleton_method(:tty?) { false }
+            $stdout = program_output
             reader = Thread.new do
               loop do
                 response = read_frame.call
@@ -51,9 +87,7 @@ module LittleGhost
                 response_queues[id] = queue
                 [id, queue]
               end
-              write_lock.synchronize do
-                write_frame.call(type: "call", id: id, name: name, arguments: arguments)
-              end
+              emit.call(type: "call", id: id, name: name, arguments: arguments)
               response = queue.pop
               queues_lock.synchronize { response_queues.delete(id) }
               raise response.fetch("error") if response["error"]
@@ -75,7 +109,12 @@ module LittleGhost
             end
             Object.const_set(:ALL_TOOLS, catalog.freeze) unless Object.const_defined?(:ALL_TOOLS)
             Object.const_set(:FRAME, request["frame"].freeze) if request["frame"] && !Object.const_defined?(:FRAME)
-            context = Object.new
+            evaluation_context = Class.new do
+              def evaluate(source)
+                instance_eval(source, "(code-mode)", 1)
+              end
+            end
+            context = evaluation_context.new
             finished = false
             finish_value = nil
             context.define_singleton_method(:tools) { tools }
@@ -85,14 +124,15 @@ module LittleGhost
               finish_value = value
               throw :little_ghost_finish
             end
-            value = catch(:little_ghost_finish) { context.instance_eval(request.fetch("source"), "(code-mode)", 1) }
+            value = catch(:little_ghost_finish) { context.evaluate(request.fetch("source")) }
             value = finish_value if finished
             emit.call(type: "done", value: value)
           rescue SignalException
             exit 0
           rescue Exception => error
             STDERR.puts("#{error.class}: #{error.message}")
-            write_frame&.call(type: "error", error: "#{error.class}: #{error.message}")
+            error_frame = {type: "error", error: "#{error.class}: #{error.message}"}
+            emit ? emit.call(error_frame) : write_frame&.call(error_frame)
             exit 1
             end
         RUBY

data/lib/little_ghost/code_mode/ruby/session.rb

@@ -31,6 +31,7 @@ module LittleGhost
           @call_mutex = Mutex.new
           @call_tasks = []
           @call_errors = []
+          @tool_calls = 0
           @closing_marker = {closing: false}
           @lifecycle_mutex = Mutex.new
           @lifecycle_condition = ConditionVariable.new
@@ -191,6 +192,7 @@ module LittleGhost
           @output = +""
           @output_bytes = 0
           @buffer = +""
+          @call_mutex.synchronize { @tool_calls = 0 }
           @lifecycle_mutex.synchronize { @generation = generation }
           start_watchdog(generation, @deadline)
           [generation, @session]
@@ -272,6 +274,8 @@ module LittleGhost
           @call_mutex.synchronize do
             active = @call_tasks.count(&:alive?)
             raise ProtocolError, "code-mode concurrent tool call limit exceeded" if active >= @limits.fetch(:concurrency)
+            @tool_calls += 1
+            raise ToolError, "tool call limit exceeded" if @tool_calls > @limits.fetch(:tool_calls)
 
             call_errors = @call_errors
             closing_marker = @closing_marker

data/lib/little_ghost/code_mode/ruby_engine.rb

@@ -58,6 +58,7 @@ module LittleGhost
           Output and completion:
           - The final Ruby expression becomes the completed program value.
           - Use `text(value)` for user-visible output.
+          - Ordinary `puts`, `print`, `printf`, and `p` output is captured and combined into bounded chunks.
           - Use `finish(value)` to complete early with a value.
 
           The Sandbox controls filesystem, network, subprocess, and optional-library access. Do not assume host

data/lib/little_ghost/embeddings/request.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  # Carries provider-neutral inputs and results for text embeddings.
+  #
+  # Applications usually call LittleGhost.embed. Provider adapters receive a
+  # Request and return a Response without exposing provider response objects.
+  module Embeddings
+    DEFAULT_LIMITS = {
+      max_inputs: 128,
+      max_input_bytes: 64 * 1024,
+      max_total_bytes: 1024 * 1024
+    }.freeze # :nodoc:
+
+    Request = Data.define(:inputs, :settings, :limits, :cancellation_token, :deadline) do # :nodoc:
+      # Validates configured budgets before copying retained input strings.
+      def initialize(inputs:, settings: {}, limits: {}, cancellation_token: Support::CancellationToken.new, deadline: nil)
+        values = inputs.is_a?(String) ? [inputs] : inputs
+        unless values.is_a?(Array) && !values.empty? && values.all? { |value| value.is_a?(String) && !value.empty? }
+          raise ArgumentError, "inputs must be a nonempty String or Array of nonempty Strings"
+        end
+        raise ArgumentError, "settings must be a mapping" unless settings.respond_to?(:to_h)
+        raise ArgumentError, "limits must be a mapping" unless limits.respond_to?(:to_h)
+
+        configured_limits = DEFAULT_LIMITS.merge(limits.to_h.transform_keys(&:to_sym))
+        configured_limits.transform_values! { |value| Integer(value) }
+        unless configured_limits.values.all?(&:positive?)
+          raise ArgumentError, "embedding limits must be positive integers"
+        end
+        if values.length > configured_limits.fetch(:max_inputs)
+          raise UnsupportedInputError, "Embedding input count exceeds the configured limit"
+        end
+        total_bytes = 0
+        values.each do |value|
+          bytes = value.bytesize
+          if bytes > configured_limits.fetch(:max_input_bytes)
+            raise UnsupportedInputError, "An embedding input exceeds the configured byte limit"
+          end
+          total_bytes += bytes
+          if total_bytes > configured_limits.fetch(:max_total_bytes)
+            raise UnsupportedInputError, "Embedding inputs exceed the configured aggregate byte limit"
+          end
+        end
+
+        super(
+          inputs: values.map { |value| value.dup.freeze }.freeze,
+          settings: settings.to_h.transform_keys(&:to_sym).freeze,
+          limits: configured_limits.freeze,
+          cancellation_token:,
+          deadline:
+        )
+      end
+    end
+
+    # Carries the validated inputs and controls for one embedding operation.
+    #
+    # LittleGhost builds this value for LittleGhost.embed and passes it to the
+    # selected provider. Provider implementations may receive calls
+    # concurrently. They must observe +cancellation_token+ and +deadline+ while
+    # performing external work.
+    class Request < Data # :doc:
+      ##
+      # :singleton-method: new
+      # :call-seq:
+      #   new(inputs:, settings: {}, limits: {}, cancellation_token: Support::CancellationToken.new, deadline: nil) -> Request
+      #
+      # Validates and freezes one String or a nonempty Array of Strings.
+      #
+      # +settings+ contains trusted model settings. +limits+ may override the
+      # input budgets:
+      #
+      # [+:max_inputs+]
+      #   Number of input strings. Defaults to 128.
+      # [+:max_input_bytes+]
+      #   Bytes allowed in one input. Defaults to 64 KiB.
+      # [+:max_total_bytes+]
+      #   Bytes allowed across all inputs. Defaults to 1 MiB.
+      #
+      # Invalid shapes raise ArgumentError; inputs outside these budgets raise
+      # UnsupportedInputError.
+
+      ##
+      # :attr_reader: inputs
+      # Frozen input strings in caller order.
+
+      ##
+      # :attr_reader: settings
+      # Frozen model settings chosen by trusted application code.
+
+      ##
+      # :attr_reader: limits
+      # Frozen input budgets applied before LittleGhost retains the strings.
+
+      ##
+      # :attr_reader: cancellation_token
+      # Token that stops the provider operation when cancellation is requested.
+
+      ##
+      # :attr_reader: deadline
+      # Monotonic deadline for the provider operation, or +nil+.
+    end
+  end
+end

data/lib/little_ghost/embeddings/response.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  module Embeddings
+    Response = Data.define(:vectors, :usage, :metadata) do # :nodoc:
+      # Validates finite, consistently sized numeric vectors and freezes them.
+      def initialize(vectors:, usage: Usage.new, metadata: {})
+        values = Array(vectors)
+        unless !values.empty? && values.all? { |vector| vector.is_a?(Array) && !vector.empty? }
+          raise ProtocolError, "Embedding provider returned no vectors"
+        end
+        dimensions = values.first.length
+        unless values.all? { |vector| vector.length == dimensions && vector.all? { |number| number.is_a?(Numeric) && (!number.respond_to?(:finite?) || number.finite?) } }
+          raise ProtocolError, "Embedding provider returned invalid vectors"
+        end
+
+        frozen_vectors = values.map { |vector| vector.map(&:to_f).freeze }.freeze
+        super(vectors: frozen_vectors, usage:, metadata: metadata.to_h.merge(dimensions:).freeze)
+      end
+
+      # Number of numeric values in each vector.
+      def dimensions = metadata.fetch(:dimensions)
+    end
+
+    # Carries validated embedding vectors without provider response objects.
+    #
+    # Vectors are finite, consistently sized, frozen, and ordered like the
+    # corresponding Request inputs. LittleGhost raises ProtocolError instead of
+    # returning an invalid or partial provider response.
+    class Response < Data # :doc:
+      ##
+      # :singleton-method: new
+      # :call-seq:
+      #   new(vectors:, usage: Usage.new, metadata: {}) -> Response
+      #
+      # Validates and freezes provider-neutral vectors, usage, and metadata.
+
+      ##
+      # :attr_reader: vectors
+      # Frozen numeric vectors in request-input order.
+
+      ##
+      # :attr_reader: usage
+      # Normalized provider usage for the operation.
+
+      ##
+      # :attr_reader: metadata
+      # Frozen operation metadata, including +dimensions+.
+
+      ##
+      # :method: dimensions
+      # Number of numeric values in each vector.
+    end
+  end
+end

data/lib/little_ghost/errors.rb

@@ -36,6 +36,8 @@ module LittleGhost
   class AssemblyStepTimeoutError < AssemblyError; end
   # Raised when an invocation contains an unsupported input form.
   class UnsupportedInputError < InvocationError; end
+  # Raised when a provider does not implement the requested model operation.
+  class UnsupportedModelOperationError < ConfigurationError; end
   # Base class for provider request, response, and protocol failures. Agent Runs
   # normally record these as failed outcomes; provider retry policy may handle a
   # retryable failure before it reaches the Run.

data/lib/little_ghost/model.rb

@@ -76,6 +76,26 @@ module LittleGhost
       provider.stream(configured_request, &block)
     end
 
+    # Applies profile settings and executes an Embeddings::Request.
+    #
+    # Returns an Embeddings::Response with one vector per input. A provider that
+    # returns another shape raises ProtocolError.
+    def embed(request)
+      configured = Embeddings::Request.new(
+        inputs: request.inputs,
+        settings: settings.merge(request.settings),
+        limits: request.limits,
+        cancellation_token: request.cancellation_token,
+        deadline: request.deadline
+      )
+      response = provider.embed(configured)
+      unless response.is_a?(Embeddings::Response) && response.vectors.length == configured.inputs.length
+        raise ProtocolError, "Embedding provider returned an unexpected vector count"
+      end
+
+      response
+    end
+
     # Uses advertised provider capabilities.
     def capabilities
       @capabilities ||= provider.capabilities(metadata: details.attributes)

data/lib/little_ghost/model_operations.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require "json"
+
+module LittleGhost
+  # Executes bounded model operations without creating an Agent or Run.
+  class ModelOperations # :nodoc:
+    MAX_STRUCTURED_RESULT_BYTES = 1_000_000
+    MAX_STRUCTURED_RESULT_DEPTH = 64
+    MAX_STRUCTURED_RESULT_NODES = 100_000
+    MAX_STRUCTURED_RESULT_REPAIR_ATTEMPTS = 3
+
+    def initialize(model_resolver:)
+      @model_resolver = model_resolver
+    end
+
+    def generate(model:, messages:, result_schema: nil, settings: {}, structured_result_repair_attempts: 1, cancellation_token: Support::CancellationToken.new, deadline: nil)
+      resolved = @model_resolver.resolve(model)
+      schema = normalize_schema(result_schema)
+      repair_attempts = normalize_repair_attempts(structured_result_repair_attempts) if schema
+      strategy = StructuredOutput.resolve(schema, model: resolved, ordinary_tools: []) if schema
+      handle = Instrumentation.start(:generation, model_provider: resolved.target.provider, model_id: resolved.model_id, model_role: resolved.role, structured: !schema.nil?)
+      usage = Usage.new
+      conversation = messages.map { |message| Message.coerce(message) }
+      response = complete(resolved, messages: conversation, settings:, schema:, strategy:, repair: false, cancellation_token:, deadline:)
+      usage += response.usage
+      output, errors = schema ? parse_structured_response(response.message, schema, strategy) : [response.message.text, []]
+      conversation << (schema ? redact_structured_response(response.message, schema, strategy) : response.message)
+      repairs_remaining = repair_attempts
+      while schema && !errors.empty? && repairs_remaining.positive?
+        conversation << structured_repair_message(response.message, strategy, errors:, repairs_remaining:)
+        response = complete(resolved, messages: conversation, settings:, schema:, strategy:, repair: true, cancellation_token:, deadline:)
+        usage += response.usage
+        output, errors = parse_structured_response(response.message, schema, strategy)
+        conversation << redact_structured_response(response.message, schema, strategy)
+        repairs_remaining -= 1
+      end
+      unless errors.empty?
+        raise StructuredResultError.new(
+          "The model did not return a valid structured result after its repair attempts",
+          schema_name: schema.fetch(:name), validation_errors: errors
+        )
+      end
+      handle.finish(outcome: :success, **usage_attributes(usage))
+      structured_result = StructuredResult.new(schema_name: schema.fetch(:name), value: output) if schema
+      final_message = schema ? conversation.last : response.message
+      RunResult.new(
+        message: final_message,
+        stop_reason: schema ? :structured_result : response.stop_reason,
+        usage:,
+        messages: conversation.freeze,
+        state: DataMap.new,
+        structured_result:,
+        steps: []
+      )
+    rescue => error
+      handle&.finish(outcome: :error, error_type: error.class.name) if handle&.active?
+      raise
+    end
+
+    def embed(model:, inputs:, settings: {}, limits: {}, cancellation_token: Support::CancellationToken.new, deadline: nil)
+      request = Embeddings::Request.new(inputs:, settings:, limits:, cancellation_token:, deadline:)
+      resolved = @model_resolver.resolve(model)
+      handle = Instrumentation.start(:embedding, model_provider: resolved.target.provider, model_id: resolved.model_id, model_role: resolved.role, input_count: request.inputs.length)
+      response = resolved.embed(request)
+      metadata = response.metadata.merge(provider: resolved.target.provider, model: resolved.model_id, model_role: resolved.role, input_count: request.inputs.length).compact
+      result = Embeddings::Response.new(vectors: response.vectors, usage: response.usage, metadata:)
+      handle.finish(outcome: :success, dimensions: result.dimensions, **usage_attributes(result.usage))
+      result
+    rescue => error
+      handle&.finish(outcome: :error, error_type: error.class.name) if handle&.active?
+      raise
+    end
+
+    private
+
+    def complete(model, messages:, settings:, schema:, strategy:, repair:, cancellation_token:, deadline:)
+      request = ModelRequest.new(
+        messages:, settings:,
+        tools: strategy ? strategy.tools([]) : [],
+        output_schema: strategy&.output_schema,
+        tool_choice: direct_generation_tool_choice(strategy, repair:),
+        required_capabilities: strategy ? strategy.required_capabilities : [],
+        cancellation_token:, deadline:
+      )
+      response = nil
+      model.stream(request) do |event|
+        response = event.data[:response] if event.type == :message_stop
+      end
+      response || raise(ProtocolError, "Provider stream ended without a response")
+    end
+
+    def normalize_schema(value)
+      return unless value
+      raise ArgumentError, "result_schema must be a mapping" unless value.respond_to?(:to_h)
+
+      schema = value.to_h.transform_keys(&:to_sym)
+      name = schema.fetch(:name).to_s
+      json_schema = schema.fetch(:schema)
+      Class.new(Agent).result_schema(
+        json_schema,
+        name:,
+        description: schema[:description],
+        strategy: :auto
+      ).except(:strategy).freeze
+    end
+
+    def parse_structured_response(message, schema, strategy)
+      return parse_structured(message.text, schema) if strategy.provider?
+
+      tool_uses = message.content.grep(Content::ToolUse)
+      result_tool_uses = tool_uses.select { |tool_use| tool_use.name == strategy.schema_name }
+      return [nil, ["The structured result tool was not called"]] if result_tool_uses.empty?
+      return [nil, ["The model called the structured result tool more than once"]] if result_tool_uses.length > 1
+      return [nil, ["The structured result tool must be the only tool call in its response"]] if tool_uses.length > 1
+
+      validate_structured_value(result_tool_uses.first.input, schema)
+    end
+
+    def parse_structured(text, schema)
+      raise StructuredResultError.new("Structured result exceeds the maximum serialized size", schema_name: schema.fetch(:name)) if text.bytesize > MAX_STRUCTURED_RESULT_BYTES
+      value = JSON.parse(text)
+      validate_structured_value(value, schema)
+    rescue JSON::ParserError
+      [nil, ["Structured result is not valid JSON"]]
+    rescue StructuredResultError => error
+      [nil, [error.message]]
+    end
+
+    def validate_structured_value(value, schema)
+      validate_complexity!(value, schema.fetch(:name))
+      errors = Tool::SchemaValidator.new(schema.fetch(:schema)).validate(value)
+      [value, errors]
+    rescue StructuredResultError => error
+      [nil, [error.message]]
+    end
+
+    def structured_repair_message(message, strategy, errors:, repairs_remaining:)
+      tool_uses = message.content.grep(Content::ToolUse)
+      feedback = "The structured result did not match the required schema: #{errors.join("; ")}. Submit it again using the required schema."
+      if strategy.tool? && !tool_uses.empty?
+        return Message.new(
+          role: :tool,
+          content: tool_uses.map do |tool_use|
+            Content::ToolResult.new(
+              tool_use_id: tool_use.id,
+              content: feedback,
+              status: :error
+            )
+          end
+        )
+      end
+
+      requirement = strategy.tool? ? "Call #{strategy.schema_name} exactly once as your only tool call." : "Return only JSON matching the configured output schema."
+      attempts_description = (repairs_remaining == 1) ? "one repair attempt" : "#{repairs_remaining} repair attempts"
+      Message.new(role: :user, content: "#{requirement} You have #{attempts_description} remaining. #{feedback}")
+    end
+
+    def direct_generation_tool_choice(strategy, repair:)
+      return unless strategy
+      return {name: strategy.schema_name}.freeze if strategy.tool?
+
+      strategy.tool_choice(repair:)
+    end
+
+    def normalize_repair_attempts(value)
+      return value if value.is_a?(Integer) && value.between?(0, MAX_STRUCTURED_RESULT_REPAIR_ATTEMPTS)
+
+      raise ArgumentError, "structured_result_repair_attempts must be an integer from zero through #{MAX_STRUCTURED_RESULT_REPAIR_ATTEMPTS}"
+    end
+
+    def validate_complexity!(value, schema_name)
+      nodes = 0
+      stack = [[value, 1]]
+      until stack.empty?
+        child, depth = stack.pop
+        nodes += 1
+        raise StructuredResultError.new("Structured result exceeds the maximum nesting depth", schema_name:) if depth > MAX_STRUCTURED_RESULT_DEPTH
+        raise StructuredResultError.new("Structured result exceeds the maximum complexity", schema_name:) if nodes > MAX_STRUCTURED_RESULT_NODES
+        child.each { |key, nested| stack << [key, depth + 1] << [nested, depth + 1] } if child.is_a?(Hash)
+        child.each { |nested| stack << [nested, depth + 1] } if child.is_a?(Array)
+      end
+    end
+
+    def redact_structured_message(message, schema)
+      Message.new(
+        role: message.role,
+        content: "[Structured result #{schema.fetch(:name)} redacted]",
+        metadata: message.metadata
+      )
+    end
+
+    def redact_structured_response(message, schema, strategy)
+      tool_uses = message.content.grep(Content::ToolUse)
+      return redact_structured_message(message, schema) unless strategy.tool? && !tool_uses.empty?
+
+      Message.new(
+        role: message.role,
+        content: tool_uses.map do |tool_use|
+          Content::ToolUse.new(id: tool_use.id, name: tool_use.name, input: {})
+        end,
+        metadata: message.metadata
+      )
+    end
+
+    def usage_attributes(usage)
+      usage.to_h.except(:total_tokens)
+    end
+  end
+end

data/lib/little_ghost/providers/base.rb

@@ -21,7 +21,12 @@ module LittleGhost
     end
 
     # Shared provider contract. Provider adapters implement #stream and may
-    # override capability-sensitive request preparation.
+    # implement #embed or override capability-sensitive request preparation.
+    #
+    # LittleGhost may call one provider instance concurrently. An embedding
+    # adapter accepts Embeddings::Request, observes its cancellation and
+    # deadline, and returns Embeddings::Response. Provider failures should use a
+    # content-safe ProviderError subclass.
     class Base
       # Returns the trusted per-profile request options this adapter accepts.
       # Connection options remain authoritative and are configured separately.
@@ -32,6 +37,16 @@ module LittleGhost
         raise AbstractMethodError, "#{self.class} must implement #stream"
       end
 
+      # Executes +request+ when the adapter supports text embeddings.
+      #
+      # The default implementation raises UnsupportedModelOperationError.
+      #
+      # :call-seq:
+      #   embed(request) -> Embeddings::Response
+      def embed(_request)
+        raise UnsupportedModelOperationError, "#{self.class} does not support embeddings"
+      end
+
       # Applies provider-specific capability constraints before streaming.
       def prepare_request(request, capabilities:)
         request

data/lib/little_ghost/providers/bedrock/aws_protocol.rb

@@ -45,7 +45,7 @@ module LittleGhost
 
         def canonical_path(uri)
           path = uri.path.empty? ? "/" : uri.path
-          path.split("/", -1).map { |part| URI.encode_www_form_component(URI.decode_www_form_component(part)).gsub("+", "%20") }.join("/")
+          path.split("/", -1).map { |part| URI.encode_www_form_component(part).gsub("+", "%20") }.join("/")
         end
 
         def canonical_query(uri)

data/lib/little_ghost/providers/bedrock/http_client.rb

@@ -10,6 +10,7 @@ module LittleGhost
       # the adapter.
       class HTTPClient # :nodoc:
         Response = Data.define(:stream)
+        InvokeResponse = Data.define(:body)
         DEFAULT_MAX_RESPONSE_BYTES = 256 * 1024 * 1024
 
         def initialize(region:, credentials: nil, credential_resolver: nil, endpoint: nil,
@@ -44,33 +45,53 @@ module LittleGhost
           Response.new(stream:)
         end
 
+        def invoke_model(model_id:, body:, max_response_bytes:, cancellation_token: nil, deadline: nil)
+          payload = JSON.generate(camelize(body))
+          uri = URI.join(@endpoint.to_s, "/model/#{escape_path(model_id)}/invoke")
+          credentials = @credential_resolver.call
+          signer = AwsSigV4.new(service: "bedrock", region: @region, credentials:, clock: @clock)
+          headers = signer.headers(method: :post, uri:, headers: {"content-type" => "application/json", "accept" => "application/json"}, body: payload)
+          response = @http_client.request(
+            uri:, method: :post, headers:, body: payload,
+            cancellation_token:, deadline:, label: "Bedrock request", max_response_bytes:
+          )
+          InvokeResponse.new(body: response)
+        end
+
         private
 
         def event(headers, payload)
           value = payload.empty? ? {} : JSON.parse(payload)
           type = headers[":event-type"] || headers[":exception-type"]
-          {type.to_s.gsub(/([a-z])([A-Z])/, "\\1_\\2").downcase.to_sym => symbolize(value)}
+          {underscore(type).to_sym => normalize_event_payload(value)}
         rescue JSON::ParserError => error
           raise ProtocolError, "Bedrock returned invalid event JSON: #{error.message}"
         end
 
-        def camelize(value)
+        def camelize(value, json_schema: false, input_schema: false)
           case value
           when Hash
-            value.to_h { |key, child| [key.to_s.gsub(/_([a-z])/) { Regexp.last_match(1).upcase }, camelize(child)] }
-          when Array then value.map { |child| camelize(child) }
+            value.to_h do |key, child|
+              key = key.to_s
+              [json_schema ? key : camelize_key(key), camelize(child, json_schema: json_schema || (input_schema && key == "json"), input_schema: key == "input_schema")]
+            end
+          when Array then value.map { |child| camelize(child, json_schema:, input_schema: false) }
           else value
           end
         end
 
-        def symbolize(value)
+        def camelize_key(key) = key.gsub(/_([a-z])/) { Regexp.last_match(1).upcase }
+
+        def normalize_event_payload(value)
           case value
-          when Hash then value.to_h { |key, child| [key.to_sym, symbolize(child)] }
-          when Array then value.map { |child| symbolize(child) }
+          when Hash then value.to_h { |key, child| [underscore(key).to_sym, normalize_event_payload(child)] }
+          when Array then value.map { |child| normalize_event_payload(child) }
           else value
           end
         end
 
+        def underscore(value) = value.to_s.gsub(/([a-z0-9])([A-Z])/, "\\1_\\2").downcase
+
         def escape_path(value) = URI.encode_www_form_component(value.to_s).gsub("+", "%20")
       end
     end

data/lib/little_ghost/providers/bedrock.rb

@@ -11,9 +11,9 @@ module LittleGhost
   # request and response types. Agents select them through model configuration rather
   # than depending on a provider class directly.
   module Providers
-    # Bedrock lets LittleGhost agents use models available through Amazon Bedrock
-    # Converse. Its output follows the same streaming events as every other
-    # LittleGhost provider.
+    # Bedrock lets LittleGhost features use models available through Amazon
+    # Bedrock. Generation uses Converse and follows the same streaming events as
+    # every other LittleGhost provider.
     #
     #   provider = LittleGhost::Providers::Bedrock.new(
     #     model: ENV.fetch("BEDROCK_MODEL_ID"),
@@ -34,6 +34,7 @@ module LittleGhost
 
       INITIAL_RETRY_DELAY = 1 # :nodoc:
       MAX_RETRY_DELAY = 16 # :nodoc:
+      DEFAULT_MAX_EMBEDDING_RESPONSE_BYTES = 8 * 1024 * 1024 # :nodoc:
       TRANSIENT_STREAM_ERRORS = %w[
         internal_server_exception model_stream_error_exception service_unavailable_exception throttling_exception
       ].freeze # :nodoc:
@@ -63,15 +64,17 @@ module LittleGhost
       # Configures Bedrock for +model+.
       #
       # +region+ and remaining +client_options+ configure the built-in HTTP client.
-      # +max_retries+, +sleeper+, and +on_retry+ control retry behavior. Injecting
-      # +client+ bypasses creation of the built-in HTTP client.
+      # +max_retries+, +sleeper+, and +on_retry+ control retry behavior.
+      # +max_embedding_response_bytes+ bounds each embedding response retained in
+      # memory. Injecting +client+ bypasses creation of the built-in HTTP client.
       def initialize(model:, region: nil, client: nil, max_retries: 2, sleeper: nil,
-        on_retry: ->(*) {}, **client_options)
+        on_retry: ->(*) {}, max_embedding_response_bytes: DEFAULT_MAX_EMBEDDING_RESPONSE_BYTES, **client_options)
         @model = model
         @client = client || build_client(region:, **client_options)
         @max_retries = Integer(max_retries)
         @sleeper = sleeper
         @on_retry = on_retry
+        @max_embedding_response_bytes = positive_integer(max_embedding_response_bytes, :max_embedding_response_bytes)
       end
 
       # Streams LittleGhost StreamEvent objects for +request+.
@@ -132,6 +135,49 @@ module LittleGhost
         end
       end
 
+      # Embeds text with Amazon Titan Text Embeddings V2.
+      #
+      # The +:dimensions+ request setting accepts 256, 512, or 1024 and defaults
+      # to 1024. +:normalize+ controls vector normalization and defaults to true.
+      # Inputs are requested sequentially, and a failure raises without returning
+      # a partial batch.
+      def embed(request)
+        unless model == "amazon.titan-embed-text-v2:0"
+          raise UnsupportedModelOperationError, "Bedrock embeddings require amazon.titan-embed-text-v2:0"
+        end
+
+        dimensions = Integer(request.settings.fetch(:dimensions, 1024))
+        raise ConfigurationError, "dimensions must be 256, 512, or 1024" unless [256, 512, 1024].include?(dimensions)
+        normalize = request.settings.fetch(:normalize, true)
+        unless normalize == true || normalize == false
+          raise ConfigurationError, "normalize must be true or false"
+        end
+
+        vectors = []
+        usage = Usage.new
+        request.inputs.each do |input|
+          response = with_retries(request) do
+            @client.invoke_model(
+              model_id: model,
+              body: {input_text: input, dimensions:, normalize:},
+              cancellation_token: request.cancellation_token,
+              deadline: request.deadline,
+              max_response_bytes: @max_embedding_response_bytes
+            )
+          end
+          payload = JSON.parse(response.body)
+          vector = payload.fetch("embedding")
+          unless vector.is_a?(Array) && vector.length == dimensions
+            raise ProtocolError, "Bedrock returned an embedding with unexpected dimensions"
+          end
+          vectors << vector
+          usage += Usage.new(input_tokens: payload["inputTextTokenCount"])
+        rescue JSON::ParserError, KeyError
+          raise ProtocolError, "Bedrock returned an invalid embedding response"
+        end
+        Embeddings::Response.new(vectors:, usage:, metadata: {model:})
+      end
+
       # Reads capabilities from Bedrock +supported_parameters+ metadata. Missing
       # metadata produces ModelCapabilities.unknown.
       def capabilities(metadata: {})
@@ -149,6 +195,29 @@ module LittleGhost
 
       private
 
+      def positive_integer(value, name)
+        integer = Integer(value)
+        raise ArgumentError, "#{name} must be positive" unless integer.positive?
+
+        integer
+      end
+
+      def with_retries(request)
+        attempts = 0
+        begin
+          request.cancellation_token.raise_if_cancelled!
+          yield
+        rescue HTTPError => error
+          raise unless error.retryable? && attempts < @max_retries
+
+          attempts += 1
+          delay = capped_retry_delay(request, retry_delay(attempts))
+          @on_retry.call(attempts, error, delay)
+          wait_before_retry(request, delay)
+          retry
+        end
+      end
+
       def build_client(region:, **options)
         resolver = options.delete(:credential_resolver)
         resolver ||= CredentialResolver.new
@@ -261,9 +330,8 @@ module LittleGhost
         tool_spec = {
           name: definition.fetch(:name),
           description: definition[:description],
-          input_schema: {json: definition[:input_schema] || {}}
+          input_schema: {json: bedrock_tool_schema(definition[:input_schema] || {})}
         }
-        tool_spec[:strict] = definition[:strict] unless definition[:strict].nil?
         {
           tool_spec: {
             **tool_spec
@@ -277,6 +345,18 @@ module LittleGhost
         {tool: {name: choice.fetch(:name).to_s}}
       end
 
+      def bedrock_tool_schema(schema)
+        return schema unless nova_model?
+
+        schema.to_h.each_with_object({}) do |(key, value), result|
+          result[key] = value if %w[type properties required].include?(key.to_s)
+        end
+      end
+
+      def nova_model?
+        model.match?(/(?:^|\.)amazon\.nova(?:[-.])/)
+      end
+
       def extract_settings(settings, keys)
         keys.each_with_object({}) do |key, result|
           value = settings[key] || settings[key.to_s]
@@ -409,6 +489,10 @@ module LittleGhost
           raise ProtocolError, "Bedrock stream ended before message_stop" unless @terminal
 
           @finished = true
+          if @stop_reason == :malformed_tool_use
+            raise MalformedToolCallError, "Bedrock returned malformed_tool_use"
+          end
+
           blocks = []
           @reasoning_blocks.sort.each do |_index, reasoning|
             if !reasoning[:redacted_content].empty?
@@ -503,6 +587,7 @@ module LittleGhost
         def normalize_stop(value)
           case value
           when "tool_use" then :tool_use
+          when "malformed_tool_use" then :malformed_tool_use
           when "max_tokens" then :max_tokens
           when "guardrail_intervened", "content_filtered" then :content_filter
           else :end_turn

data/lib/little_ghost/providers/openai.rb

@@ -4,8 +4,9 @@ require_relative "openai_compatible"
 
 module LittleGhost
   module Providers
-    # OpenAI connects LittleGhost agents to OpenAI models with streaming, tools,
-    # and structured results. It uses the Responses API by default.
+    # OpenAI connects LittleGhost features to OpenAI models for generation and
+    # embeddings. Generation uses the Responses API by default and supports
+    # streaming, Tools, and structured results.
     #
     #   provider = LittleGhost::Providers::OpenAI.new(
     #     api_key: ENV.fetch("OPENAI_API_KEY"),
@@ -17,10 +18,85 @@ module LittleGhost
     class OpenAI < OpenAICompatible
       # The OpenAI API endpoint used when +base_url+ is omitted.
       DEFAULT_BASE_URL = "https://api.openai.com/v1/"
+      DEFAULT_MAX_EMBEDDING_RESPONSE_BYTES = 8 * 1024 * 1024 # :nodoc:
 
       # Uses the official OpenAI API base URL by default.
-      def initialize(base_url: DEFAULT_BASE_URL, **arguments)
-        super
+      #
+      # +max_embedding_response_bytes+ bounds the response retained for one
+      # embedding batch. Remaining +arguments+ configure the shared generation
+      # transport and retry behavior.
+      def initialize(base_url: DEFAULT_BASE_URL, max_embedding_response_bytes: DEFAULT_MAX_EMBEDDING_RESPONSE_BYTES, **arguments)
+        @max_embedding_response_bytes = Integer(max_embedding_response_bytes)
+        raise ArgumentError, "max_embedding_response_bytes must be positive" unless @max_embedding_response_bytes.positive?
+
+        super(base_url:, **arguments)
+      end
+
+      # Embeds one or more strings with the configured OpenAI model.
+      #
+      # The optional +:dimensions+ request setting selects a supported output
+      # size for models that accept it. The response preserves input order and
+      # raises ProtocolError when OpenAI returns an incomplete or invalid batch.
+      def embed(request)
+        attempts = 0
+        begin
+          request.cancellation_token.raise_if_cancelled!
+          payload = {
+            model:,
+            input: request.inputs,
+            encoding_format: "float"
+          }
+          dimensions = request.settings[:dimensions]
+          payload[:dimensions] = Integer(dimensions) if dimensions
+          body = +""
+          @transport.stream(
+            path: "embeddings",
+            headers: {"Authorization" => "Bearer #{@api_key}", "Content-Type" => "application/json"}.merge(@headers),
+            body: JSON.generate(payload),
+            cancellation_token: request.cancellation_token,
+            deadline: request.deadline
+          ) do |chunk|
+            if body.bytesize + chunk.bytesize > @max_embedding_response_bytes
+              raise ProtocolError, "OpenAI embedding response exceeded #{@max_embedding_response_bytes} bytes"
+            end
+            body << chunk
+          end
+          normalize_embedding_response(body, request.inputs.length, dimensions && Integer(dimensions))
+        rescue HTTPError => error
+          raise unless error.retryable? && attempts < @max_retries
+
+          attempts += 1
+          delay = capped_retry_delay(request, retry_delay(attempts))
+          @on_retry.call(attempts, error, delay)
+          wait_before_retry(request, delay)
+          retry
+        end
+      end
+
+      private
+
+      def normalize_embedding_response(body, input_count, expected_dimensions)
+        payload = JSON.parse(body)
+        data = payload.fetch("data")
+        raise ProtocolError, "OpenAI returned an invalid embedding count" unless data.is_a?(Array) && data.length == input_count
+
+        ordered = data.sort_by { |item| Integer(item.fetch("index")) }
+        expected = (0...input_count).to_a
+        raise ProtocolError, "OpenAI returned invalid embedding indices" unless ordered.map { |item| Integer(item.fetch("index")) } == expected
+
+        vectors = ordered.map { |item| item.fetch("embedding") }
+        if expected_dimensions && vectors.any? { |vector| !vector.is_a?(Array) || vector.length != expected_dimensions }
+          raise ProtocolError, "OpenAI returned embeddings with unexpected dimensions"
+        end
+
+        usage = payload.fetch("usage", {})
+        Embeddings::Response.new(
+          vectors:,
+          usage: Usage.new(input_tokens: usage["prompt_tokens"] || usage["input_tokens"]),
+          metadata: {model: payload["model"] || model}
+        )
+      rescue JSON::ParserError, KeyError, ArgumentError, TypeError
+        raise ProtocolError, "OpenAI returned an invalid embedding response"
       end
     end
   end

data/lib/little_ghost/runtime/hooks/artifacts.rb

@@ -91,6 +91,7 @@ module LittleGhost
             automatic: automatic_descriptor,
             oversized:
           )
+          content = append_materialized_references(content, all_descriptors)
           Tool::ExecutionResult.new(
             value: result.value,
             content:,
@@ -229,6 +230,13 @@ module LittleGhost
           end.freeze
         end
 
+        def append_materialized_references(content, artifacts)
+          references = artifacts.filter_map { |artifact| artifact.reference if artifact.bytes }
+          return content if references.empty?
+
+          "#{content}\n\nWorkspace artifacts:\n#{references.map { |reference| "- #{reference}" }.join("\n")}"
+        end
+
         def oversized_artifact(result, tool_use:)
           data, media_type, extension = serialized_value(result.value)
           Artifact.new(

data/lib/little_ghost/runtime.rb

@@ -136,6 +136,7 @@ module LittleGhost
         @invocation_class = @settings[:invocation] || Invocation
         @model_resolver = @settings.fetch(:model_resolver)
         @default_model = @settings.fetch(:default_model, "default").to_s
+        @model_operations = ModelOperations.new(model_resolver:)
 
         @startup_phase = "session_store"
         @session_store = build_session_store(@settings[:session_store])
@@ -183,6 +184,28 @@ module LittleGhost
       payload.is_a?(@invocation_class) ? payload : @invocation_class.new(payload)
     end
 
+    # :call-seq:
+    #   generate(model:, messages:, result_schema: nil, settings: {}, structured_result_repair_attempts: 1, cancellation_token: Support::CancellationToken.new, deadline: nil) -> RunResult
+    #
+    # Generates one response through this Runtime's model resolver.
+    #
+    # Returns a RunResult without creating a Run or invoking runtime hooks. See
+    # LittleGhost.generate for the operation contract.
+    def generate(**arguments)
+      @model_operations.generate(**arguments)
+    end
+
+    # :call-seq:
+    #   embed(model:, inputs:, settings: {}, limits: {}, cancellation_token: Support::CancellationToken.new, deadline: nil) -> Embeddings::Response
+    #
+    # Embeds text through this Runtime's model resolver.
+    #
+    # Returns an Embeddings::Response without creating a Run or invoking runtime
+    # hooks. See LittleGhost.embed for the operation contract.
+    def embed(**arguments)
+      @model_operations.embed(**arguments)
+    end
+
     # Creates a Run that owns any workspace and sandbox built for the request.
     #
     # +include_agent_events_by_default+ is trusted stream policy for the Run

data/lib/little_ghost/support/http_client.rb

@@ -81,7 +81,8 @@ module LittleGhost
 
       # Executes a bounded request and returns the complete response body.
       def request(uri:, method: :get, headers: {}, body: nil, allow_insecure_http: false,
-        cancellation_token: nil, deadline: nil)
+        cancellation_token: nil, deadline: nil, label: "HTTP request", max_response_bytes: @max_response_bytes)
+        response_limit = positive_integer(max_response_bytes, :max_response_bytes)
         response_body = +""
         each_chunk(
           uri:,
@@ -90,8 +91,14 @@ module LittleGhost
           body:,
           cancellation_token:,
           deadline: deadline || Time.now + @read_timeout,
-          allow_insecure_http:
-        ) { |chunk| response_body << chunk }
+          allow_insecure_http:,
+          label:
+        ) do |chunk|
+          if response_body.bytesize + chunk.bytesize > response_limit
+            raise ProtocolError, "#{label} response exceeded #{response_limit} bytes"
+          end
+          response_body << chunk
+        end
         response_body
       end
 

data/lib/little_ghost/tracing/open_telemetry.rb

@@ -61,7 +61,9 @@ module LittleGhost
         workflow: "invoke_workflow",
         swarm: "invoke_swarm",
         graph: "invoke_graph",
-        assembly: "invoke_assembly"
+        assembly: "invoke_assembly",
+        generation: "chat",
+        embedding: "embeddings"
       }.freeze # :nodoc:
       REQUEST_SETTING_ATTRIBUTES = {
         frequency_penalty: "gen_ai.request.frequency_penalty",
@@ -244,7 +246,7 @@ module LittleGhost
         end
         description = [error_type, event_attributes["exception.message"]].compact.join(": ")
         span.status = ::OpenTelemetry::Trace::Status.error(description)
-        event_name = (kind == :model) ? "gen_ai.client.operation.exception" : "exception"
+        event_name = %i[model generation embedding].include?(kind) ? "gen_ai.client.operation.exception" : "exception"
         span.add_event(event_name, attributes: event_attributes.compact)
       end
 
@@ -270,7 +272,7 @@ module LittleGhost
         when :swarm, :graph, :assembly then attributes[:assembly_id]
         when :assembly_step then attributes[:participant]
         when :agent_turn then attributes[:turn]
-        when :model then attributes[:model_id]
+        when :model, :generation, :embedding then attributes[:model_id]
         when :subagent then attributes[:subagent_id] || attributes[:kind]
         when :tool then attributes[:tool_name]
         end
@@ -448,7 +450,7 @@ module LittleGhost
       end
 
       def span_kind(kind)
-        %i[model session_store].include?(kind) ? :client : :internal
+        %i[model generation embedding session_store].include?(kind) ? :client : :internal
       end
 
       def gen_ai_usage_value(key, attributes, value)

data/lib/little_ghost/version.rb

@@ -2,5 +2,5 @@
 
 module LittleGhost
   # Current LittleGhost gem version.
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
 end

data/lib/little_ghost.rb

@@ -20,6 +20,8 @@ require_relative "little_ghost/stream_event"
 require_relative "little_ghost/agent_stream_source"
 require_relative "little_ghost/model_request"
 require_relative "little_ghost/model_response"
+require_relative "little_ghost/embeddings/request"
+require_relative "little_ghost/embeddings/response"
 require_relative "little_ghost/run_result"
 require_relative "little_ghost/model_capabilities"
 require_relative "little_ghost/models/target"
@@ -82,6 +84,7 @@ require_relative "little_ghost/agent_factory"
 require_relative "little_ghost/runtime/hook"
 require_relative "little_ghost/runtime/hooks/artifacts"
 require_relative "little_ghost/runtime"
+require_relative "little_ghost/model_operations"
 
 # Build AI features as ordinary Ruby classes. An Agent owns one model
 # conversation. Larger units called Assemblies coordinate several Agents while
@@ -151,6 +154,28 @@ module LittleGhost
     # Returns the model resolver owned by the active process configuration.
     def model_resolver = configuration.model_resolver
 
+    # :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.
+    def generate(...) = runtime.generate(...)
+
+    # :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.
+    def embed(...) = runtime.embed(...)
+
     # Makes +configuration+ and its independent shared Runtime current only
     # while the block runs.
     #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: little_ghost
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Matt Robinson
@@ -225,6 +225,8 @@ files:
 - lib/little_ghost/content.rb
 - lib/little_ghost/data/model_catalog.json
 - lib/little_ghost/data_map.rb
+- lib/little_ghost/embeddings/request.rb
+- lib/little_ghost/embeddings/response.rb
 - lib/little_ghost/errors.rb
 - lib/little_ghost/events.rb
 - lib/little_ghost/execution.rb
@@ -240,6 +242,7 @@ files:
 - lib/little_ghost/message.rb
 - lib/little_ghost/model.rb
 - lib/little_ghost/model_capabilities.rb
+- lib/little_ghost/model_operations.rb
 - lib/little_ghost/model_request.rb
 - lib/little_ghost/model_resolver.rb
 - lib/little_ghost/model_response.rb
@@ -342,14 +345,14 @@ files:
 - lib/little_ghost/version.rb
 - lib/little_ghost/workflow.rb
 - lib/little_ghost/workspace.rb
-homepage: https://github.com/mattyr/little_ghost
+homepage: https://github.com/littleghostai/little_ghost
 licenses:
 - MIT
 metadata:
-  bug_tracker_uri: https://github.com/mattyr/little_ghost/issues
-  changelog_uri: https://github.com/mattyr/little_ghost/releases
-  documentation_uri: https://mattyr.github.io/little_ghost/docs/
-  source_code_uri: https://github.com/mattyr/little_ghost
+  bug_tracker_uri: https://github.com/littleghostai/little_ghost/issues
+  changelog_uri: https://github.com/littleghostai/little_ghost/releases
+  documentation_uri: https://littleghostai.org/docs/
+  source_code_uri: https://github.com/littleghostai/little_ghost
   allowed_push_host: https://rubygems.org
   rubygems_mfa_required: 'true'
 rdoc_options: []