little_ghost 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50e597abbf025721200897c852c8ea72e244c0b5bb2f1b50aa58084e55d5d0df
-  data.tar.gz: be4d63e81003723c9a916a61359ae508a8d35a16a02b8c7e11f14dc5a3bcd12b
+  metadata.gz: a7758c8ce1e1ee404d86fe7dd76065dbd983a0abb660cedd82f7a6ffac0a3509
+  data.tar.gz: 485a32b90c723ed4a3c8b064151495e92d8679527f408d39e91145c2f3aaea09
 SHA512:
-  metadata.gz: f546cd196e43eb53f6e3ab812c362a9bfb5d81e5408b0608c14ba20ca865a77196c6a801ed3b8980f38e098b6e468555dc2520ee32d9ee72373b4307686b9768
-  data.tar.gz: 18294764bb5ada766b993993172cccef4e077bf7d2cb886e7f76f1a3bda7ce60a8c448547b056f55eadd2775761457f8a725d3ab895d268f9785cdc2eebac22b
+  metadata.gz: bb412e0ec1ff688067bdbb14d34e62a72713f617a4d487188ca40ef2d05c2b3c18262b6b9da1e286a977f8251fb65b4818078d4a044c2d9566b1836876634b6e
+  data.tar.gz: c79396a4608f4643415a0ac50ca30f23e7a26cc5688a8ac593bf6674e7d8005185068c6e6107f205d53c834289a4aac390350f3e4e5deffea72d57ed76bddb19

data/README.md

@@ -73,7 +73,9 @@ The source checkout also includes a complete
 [single-file Agent](https://github.com/littleghostai/little_ghost/tree/main/examples/basic_agent)
 and
 [coding harness](https://github.com/littleghostai/little_ghost/tree/main/examples/coding_harness),
-both configured for local Ollama.
+both configured for local Ollama. The
+[decision example](https://github.com/littleghostai/little_ghost/tree/main/examples/decision)
+shows typed questions with Jev through OpenRouter.
 
 ## Give an agent real capabilities
 
@@ -160,6 +162,8 @@ upgrading, because interfaces may change between releases.
 - [Structured Results and Content](docs/guides/structured_outputs_and_content.md) covers checked result shapes, images, and documents.
 - [Compose Agents](docs/guides/assemblies.md) walks through workflows, swarms, graphs, nesting, and builders.
 - [Skills](docs/guides/skills.md) organizes reusable instructions and supporting resources.
+- [Decisions](docs/guides/decisions.md) explains typed questions and structured answers.
+- [Embeddings](docs/guides/embeddings.md) explains text representations for similarity-based features.
 - [Workspaces and Sandboxes](docs/guides/sandboxing.md) gives files and child processes a deliberate place to run.
 - [Code Mode](docs/guides/code_mode.md) lets a model compose Tools in sandboxed Ruby or optional JavaScript.
 - [Integrations](docs/guides/integrations.md) connects Run streams to AG-UI and OpenTelemetry.

data/docs/guides/decisions.md

@@ -0,0 +1,69 @@
+# Decisions
+
+Use a decision model when an application needs typed answers to a small set of
+questions. `LittleGhost.decide` returns the answers and token usage without
+starting an Agent or creating a Run. Jev supports Choice, Score, and Noul
+(yes/no probability) questions:
+
+```ruby
+result = LittleGhost.decide(
+  model: "primary:~typesafe/jev-latest",
+  state: {payout_status: "failed", failed_days: 3},
+  questions: [
+    {
+      id: "route",
+      type: :choice,
+      instructions: "Choose a route",
+      criteria: {
+        review: "Needs more investigation",
+        approve: "Meets the criteria",
+        decline: "Does not meet the criteria"
+      }
+    },
+    {id: "urgent", type: :noul, instructions: "Does this need same-day attention?"}
+  ]
+)
+
+result.answers.fetch("route").choice
+result.answers.fetch("urgent").noul
+```
+
+Choice answers contain the selected label. Noul answers contain the
+probability of yes from 0 to 1. Score answers contain a probability-weighted
+value across the declared levels. Choice and Score answers also include the
+probability distribution and confidence; Score answers include the level
+legend.
+
+For reusable decisions, declare questions once on a `Decision` class. A class
+can mix question types:
+
+```ruby
+class ApplicationTriage < LittleGhost::Decision
+  model "primary:~typesafe/jev-latest"
+  choice :route, instructions: "Choose a route", criteria: {
+    review: "Needs more investigation",
+    approve: "Meets the criteria",
+    decline: "Does not meet the criteria"
+  }
+  noul :urgent, instructions: "Does this need same-day attention?"
+  score :quality, instructions: "Rate the quality", criteria: ["accuracy", "completeness"]
+end
+
+application_state = {payout_status: "failed", failed_days: 3}
+result = ApplicationTriage.ask(application_state)
+result.answers.fetch("quality").score
+```
+
+The class-level `.ask` and an instance's `#ask` return
+`LittleGhost::DecisionResult`. Read a typed value with
+`LittleGhost::DecisionAnswer#value` or its type-specific reader (`choice`,
+`noul`, or `score`).
+
+The selected provider receives the state and question text. Choose a provider
+that is appropriate for that data.
+
+Decisions require a TypeSafe connection or an OpenRouter connection configured
+for a Jev decision endpoint. Other providers raise
+`UnsupportedModelOperationError`. See [Provider Support](providers.md) for
+connection setup and [Models and Providers](models_and_providers.md) for model
+targets, shared roles, and capabilities.

data/docs/guides/embeddings.md

@@ -0,0 +1,23 @@
+# Embeddings
+
+Use `LittleGhost.embed` to turn text into numeric representations for search,
+clustering, or another similarity-based feature:
+
+```ruby
+response = LittleGhost.embed(
+  model: "primary:openai/text-embedding-3-small",
+  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.
+Embedding text is sent to the selected provider, so choose one appropriate for
+that data. [Provider Support](providers.md) identifies adapters with embedding
+support; `LittleGhost::Embeddings::Request` documents settings and request
+bounds. See [Models and Providers](models_and_providers.md) for model targets,
+shared roles, and capabilities.

data/docs/guides/models_and_providers.md

@@ -74,9 +74,10 @@ application obtains short-lived credentials at runtime, configure a credential
 resolver that returns them for the selected connection.
 
 > **Safety note:** The selected provider may receive system instructions,
-> caller input, conversation history, Tool results, schemas, and attachments.
-> Choose a provider that is appropriate for that data, and keep credentials and
-> provider endpoints under application control.
+> caller input, application state, question text, conversation
+> history, Tool results, schemas, and attachments. Choose a provider that is
+> appropriate for that data, and keep credentials and provider endpoints under
+> application control.
 
 ## Choose a role for each request
 
@@ -155,29 +156,9 @@ Results and Content](structured_outputs_and_content.md) covers strict schemas,
 provider strategies, repair behavior, and the application checks that still
 belong outside the schema.
 
-## Create embeddings
-
-Use `LittleGhost.embed` when your application needs numeric representations for
-search, clustering, or another similarity-based feature:
-
-```ruby
-response = LittleGhost.embed(
-  model: "primary:openai/text-embedding-3-small",
-  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.
-Embedding text is sent to the selected provider, so choose one appropriate for
-that data. [Provider Support](providers.md) identifies adapters with embedding
-support; `LittleGhost::Embeddings::Request` documents 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.
+Continue with [Decisions](decisions.md) for typed, structured answers or
+[Embeddings](embeddings.md) for text representations. [Prompts as
+Views](prompt_views.md) moves growing Agent instructions into conventional ERB
+files. See [Structured Results and
+Content](structured_outputs_and_content.md) for checked result shapes, images,
+or documents.

data/docs/guides/providers.md

@@ -23,17 +23,24 @@ end
 protocol. An Agent can now use a target such as
 `primary:openai/gpt-5.6-luna`.
 
-| Provider or endpoint | Adapter | Generation | Embeddings |
-| --- | --- | --- | --- |
-| OpenRouter | `:openrouter` | Chat Completions | When the model supports it |
-| OpenAI | `:openai` | Responses or Chat Completions | Yes |
-| Compatible API | `:openai_compatible` | Responses or Chat Completions | When the endpoint implements it |
-| Ollama | `:openai_compatible` | Responses or Chat Completions | When the model supports it |
-| Anthropic | `:anthropic` | Messages | No |
-| Gemini | `:gemini` | Gemini API | No |
-| Vertex AI | `:vertex_ai` | Gemini on Vertex AI | No |
-| Bedrock | `:bedrock` | Converse | Titan Text Embeddings V2 |
-| LM Studio | `:lm_studio` | Responses or Chat Completions | Yes |
+| Provider or endpoint | Adapter | Generation | Decisions | Embeddings |
+| --- | --- | --- | --- | --- |
+| OpenRouter | `:openrouter` | Chat Completions | Typed decision endpoints | When the model supports it |
+| TypeSafe | `:typesafe` | No | System One decisions | No |
+| OpenAI | `:openai` | Responses or Chat Completions | No | Yes |
+| Compatible API | `:openai_compatible` | Responses or Chat Completions | No | When the endpoint implements it |
+| Ollama | `:openai_compatible` | Responses or Chat Completions | No | When the model supports it |
+| Anthropic | `:anthropic` | Messages | No | No |
+| Gemini | `:gemini` | Gemini API | No | No |
+| Vertex AI | `:vertex_ai` | Gemini on Vertex AI | No | No |
+| Bedrock | `:bedrock` | Converse | No | Titan Text Embeddings V2 |
+| LM Studio | `:lm_studio` | Responses or Chat Completions | No | Yes |
+
+TypeSafe Jev is a decision model that returns structured answers to typed
+questions. Its API and OpenRouter's Jev routes support the same question
+types.
+These operations return structured answers directly and do not create an Agent
+Run. See [Decisions](decisions.md) for the question and answer model.
 
 Capabilities can vary by model, account, and server version. Handle provider
 failures even when a model is expected to support a feature.
@@ -60,6 +67,46 @@ Use OpenRouter's `publisher/model` form, such as
 The selected model must support embeddings before you call
 `LittleGhost.embed`.
 
+For Jev decisions, OpenRouter supports both decision endpoints. The default
+uses the Decisions API and namespaced model identifiers such as
+`openrouter:~typesafe/jev-latest`:
+
+```ruby
+LittleGhost.configure do |config|
+  config.providers = {
+    openrouter: {
+      adapter: :openrouter,
+      api_key: ENV.fetch("OPENROUTER_API_KEY"),
+      decision_api: :decisions
+    }
+  }
+end
+```
+
+Set `decision_api: :system_one` to use `/api/v1/systemone`; that route
+accepts a bare TypeSafe model identifier such as `jev-latest`, used as
+`openrouter:jev-latest`.
+OpenRouter describes these routes in its [Jev guide](https://openrouter.ai/blog/insights/what-is-jev/).
+
+### TypeSafe
+
+Connect directly to TypeSafe's System One endpoint with a TypeSafe API key:
+
+```ruby
+LittleGhost.configure do |config|
+  config.providers = {
+    typesafe: {
+      adapter: :typesafe,
+      api_key: ENV.fetch("TYPESAFE_API_KEY")
+    }
+  }
+end
+```
+
+Use a Jev identifier such as `typesafe:jev-latest`. This adapter supports
+typed decisions only. See the [TypeSafe API reference](https://docs.typesafe.ai/api)
+for question and answer fields.
+
 ### OpenAI
 
 ```ruby

data/lib/little_ghost/assembly_builder.rb

@@ -176,7 +176,7 @@ module LittleGhost
         value = implementation.instance_variable_get(name)
         implementation.instance_variable_set(name, deep_freeze_snapshot_value(value))
       end
-      implementation.methods.grep(/_value\z/).each do |reader|
+      implementation.methods.grep(/_values?\z/).each do |reader|
         writer = :"#{reader}="
         next unless implementation.respond_to?(writer)
 
@@ -232,7 +232,7 @@ module LittleGhost
       value.instance_variables.each do |name|
         snapshot.instance_variable_set(name, Support.deep_dup(value.instance_variable_get(name)))
       end
-      value.methods.grep(/_value\z/).each do |reader|
+      value.methods.grep(/_values?\z/).each do |reader|
         writer = :"#{reader}="
         next unless snapshot.respond_to?(writer)
 

data/lib/little_ghost/code_mode/javascript/client.rb

@@ -222,7 +222,7 @@ module LittleGhost
       def observe(owner:, program_id:, timeout:, max_tokens:, context: nil)
         program = owned_program(owner, program_id)
         result = program.observe(timeout:, max_tokens:, context:)
-        release_program(program) if program.terminal?
+        release_program(program) unless result.fetch(:status) == "still_working"
         result
       end
 

data/lib/little_ghost/code_mode/session.rb

@@ -16,6 +16,9 @@ module LittleGhost
     # +:still_working+ when an observation interval elapsed, +:terminated+ after
     # requested termination, and +:error+ for a model-program error. +wait+
     # observes an active program without pausing, resuming, or restarting it.
+    # A +:still_working+ result keeps the program available for another observation,
+    # even if it finishes immediately afterward. Collect output from every result;
+    # the terminal result contains only output not returned by earlier observations.
     # Lifecycle, host, and cleanup failures raise rather than becoming a result.
     #
     #   ProgramResult.new(

data/lib/little_ghost/decision.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  # Provider-neutral inputs for one typed decision operation.
+  #
+  # State and questions are trusted application inputs. Question ids are
+  # normalized to strings and must be unique.
+  DecisionRequest = Data.define(:state, :questions, :cancellation_token, :deadline) do # :nodoc:
+    def initialize(state:, questions:, cancellation_token: Support::CancellationToken.new, deadline: nil)
+      unless state.is_a?(String) || state.is_a?(Hash) || state.is_a?(Array)
+        raise ArgumentError, "decision state must be a string, mapping, or array"
+      end
+      entries = questions.is_a?(Hash) ? questions.map { |id, value| value.to_h.merge(id:) } : Array(questions)
+      normalized = entries.map do |question|
+        raise ArgumentError, "decision questions must be mappings" unless question.is_a?(Hash)
+
+        item = question.to_h.transform_keys(&:to_sym)
+        type = item[:type]&.to_sym
+        raise ArgumentError, "decision question type must be :choice, :noul, or :score" unless %i[choice noul score].include?(type)
+        item[:type] = type
+        item[:id] = item[:id].to_s
+        raise ArgumentError, "decision question id is required" if item[:id].empty?
+        unless item[:instructions].is_a?(String) || item[:instructions].is_a?(Hash) || item[:instructions].is_a?(Array)
+          raise ArgumentError, "decision question instructions are required"
+        end
+        if type == :choice
+          criteria = item[:criteria]
+          raise ArgumentError, "choice criteria must be a mapping or array" unless criteria.is_a?(Hash) || criteria.is_a?(Array)
+          raise ArgumentError, "choice criteria must contain between one and 255 options" unless (1..255).cover?(criteria.length)
+          if criteria.is_a?(Array)
+            labels = criteria.map(&:to_s)
+            raise ArgumentError, "choice criteria labels must be unique" unless labels.uniq.length == labels.length
+
+            item[:criteria] = labels.to_h { |label| [label, nil] }
+          else
+            labels = criteria.keys.map(&:to_s)
+            raise ArgumentError, "choice criteria labels must be unique" unless labels.uniq.length == labels.length
+
+            valid_criteria = criteria.all? do |label, description|
+              valid_label = label.is_a?(String) || label.is_a?(Symbol)
+              valid_description = description.nil? || description.is_a?(String) ||
+                description.is_a?(Hash) || description.is_a?(Array)
+              valid_label && valid_description
+            end
+            raise ArgumentError, "choice criteria must map labels to descriptions" unless valid_criteria
+          end
+        elsif type == :score
+          criteria = item[:criteria]
+          raise ArgumentError, "score criteria must contain between two and ten levels" unless criteria.is_a?(Array) && (2..10).cover?(criteria.length)
+          valid_levels = criteria.all? { |level| level.is_a?(String) || level.is_a?(Hash) || level.is_a?(Array) }
+          raise ArgumentError, "score criteria must be descriptions" unless valid_levels
+        elsif !item[:criteria].nil?
+          criteria = item[:criteria]
+          valid_criteria = criteria.is_a?(Hash) && criteria.all? do |key, description|
+            %w[true false].include?(key.to_s) &&
+              (description.is_a?(String) || description.is_a?(Hash) || description.is_a?(Array))
+          end
+          raise ArgumentError, "noul criteria must map true or false to descriptions" unless valid_criteria
+        end
+        item.freeze
+      end
+      raise ArgumentError, "at least one decision question is required" if normalized.empty?
+      ids = normalized.map { |item| item[:id] }
+      raise ArgumentError, "decision question ids must be unique" unless ids.uniq.length == ids.length
+
+      super(state:, questions: normalized.freeze, cancellation_token:, deadline:)
+    end
+  end
+
+  # Carries the state, questions, and request controls passed to a decision
+  # provider.
+  class DecisionRequest < Data # :doc:
+    ##
+    # :attr_reader: state
+    # Application state evaluated by the provider.
+
+    ##
+    # :attr_reader: questions
+    # Frozen question declarations, each with a string +id+.
+
+    ##
+    # :attr_reader: cancellation_token
+    # Token the provider checks while the request runs.
+
+    ##
+    # :attr_reader: deadline
+    # Optional request deadline passed to the provider.
+
+    ##
+    # :singleton-method: new
+    # :call-seq:
+    #   new(state:, questions:, cancellation_token: Support::CancellationToken.new, deadline: nil) -> DecisionRequest
+    #
+    # Validates and freezes question declarations before a provider request.
+  end
+
+  # A validated, provider-neutral answer to a typed decision question.
+  #
+  # +value+ contains the choice label, a numeric noul probability from 0 to 1,
+  # or a numeric score according to +type+. The type-specific readers return
+  # +nil+ for other answer types.
+  DecisionAnswer = Data.define(:type, :value, :probabilities, :confidence, :legend) do # :nodoc:
+    def choice
+      value if type == :choice
+    end
+
+    def noul
+      value if type == :noul
+    end
+
+    def score
+      value if type == :score
+    end
+  end
+
+  # One typed answer returned by a decision provider.
+  class DecisionAnswer < Data # :doc:
+    ##
+    # :attr_reader: type
+    # Answer type: +:choice+, +:noul+, or +:score+.
+
+    ##
+    # :attr_reader: value
+    # Selected label, yes probability, or probability-weighted score.
+
+    ##
+    # :attr_reader: probabilities
+    # Option or level probabilities for Choice and Score answers.
+
+    ##
+    # :attr_reader: confidence
+    # Confidence value for Choice and Score answers.
+
+    ##
+    # :attr_reader: legend
+    # Level descriptions for Score answers.
+
+    ##
+    # :method: choice
+    # Returns the selected label for a Choice answer, or +nil+ for another type.
+
+    ##
+    # :method: noul
+    # Returns the yes probability from 0 to 1 for a Noul answer, or +nil+ for another type.
+
+    ##
+    # :method: score
+    # Returns the probability-weighted value for a Score answer, or +nil+ for another type.
+  end
+
+  # Results returned by a decision model, keyed by question id.
+  #
+  # Provider metadata contains bounded response identifiers, model details,
+  # and reported cost when available; it excludes request state and question text.
+  DecisionResult = Data.define(:answers, :usage, :metadata) do # :nodoc:
+    def initialize(answers:, usage: Usage.new, metadata: {})
+      super(answers: answers.to_h.freeze, usage:, metadata: metadata.to_h.freeze)
+    end
+  end
+
+  # Carries validated answers and token usage from one decision call.
+  class DecisionResult < Data # :doc:
+    ##
+    # :attr_reader: answers
+    # Frozen question-id to DecisionAnswer mapping.
+
+    ##
+    # :attr_reader: usage
+    # Normalized token usage for the provider request.
+
+    ##
+    # :attr_reader: metadata
+    # Frozen provider metadata such as model, request id, provider, and cost.
+  end
+
+  # Declarative collection of typed questions for one decision request.
+  #
+  # Subclass and declare a model plus one or more typed questions, then call
+  # +.ask(state)+ or instantiate the class and call +#ask(state)+.
+  class Decision
+    class << self
+      def inherited(child) # :nodoc:
+        child.instance_variable_set(:@questions, questions.map(&:dup))
+        child.instance_variable_set(:@model, model)
+      end
+
+      # Selects a direct target or configured model role for this decision.
+      def model(value = :__read__)
+        return @model if value == :__read__
+
+        @model = value
+      end
+
+      # Declares a choice question. Criteria may be an array of labels or a
+      # mapping from labels to their descriptions.
+      def choice(id, instructions:, criteria:, **options) = add_question(:choice, id, instructions:, criteria:, **options)
+      # Declares a yes/no (noul) question, optionally with decision criteria.
+      def noul(id, instructions:, criteria: nil, **options) = add_question(:noul, id, instructions:, criteria:, **options)
+      # Declares a score question with ordered scoring criteria.
+      def score(id, instructions:, criteria:, **options) = add_question(:score, id, instructions:, criteria:, **options)
+
+      # Runs all declared questions against +state+.
+      def ask(state, **options)
+        LittleGhost.decide(model: model || raise(ConfigurationError, "Decision model is required"), state:, questions:, **options)
+      end
+
+      # Returns the immutable question declarations for this class.
+      def questions = (@questions ||= []).map(&:dup).freeze
+
+      private
+
+      def add_question(type, id, **attributes)
+        raise ArgumentError, "question id is required" if id.to_s.empty?
+        raise ArgumentError, "duplicate decision question id: #{id}" if questions.any? { |question| question[:id] == id.to_s }
+
+        (@questions ||= []) << attributes.merge(type:, id: id.to_s).freeze
+      end
+    end
+
+    # Binds this decision instance to a Runtime.
+    def initialize(runtime: LittleGhost.runtime)
+      @runtime = runtime
+    end
+
+    # Runs this decision's questions against +state+.
+    def ask(state, **options)
+      @runtime.decide(model: self.class.model || raise(ConfigurationError, "Decision model is required"), state:, questions: self.class.questions, **options)
+    end
+  end
+end

data/lib/little_ghost/model.rb

@@ -96,6 +96,11 @@ module LittleGhost
       response
     end
 
+    # Executes a typed decision through this model's provider.
+    def decide(request)
+      provider.decide(request)
+    end
+
     # Uses advertised provider capabilities.
     def capabilities
       @capabilities ||= provider.capabilities(metadata: details.attributes)

data/lib/little_ghost/model_operations.rb

@@ -89,6 +89,20 @@ module LittleGhost
       raise
     end
 
+    def decide(model:, state:, questions:, cancellation_token: Support::CancellationToken.new, deadline: nil)
+      request = DecisionRequest.new(state:, questions:, cancellation_token:, deadline:)
+      resolved = @model_resolver.resolve(model)
+      handle = Instrumentation.start(:decision, model_provider: resolved.target.provider, model_id: resolved.model_id, question_count: request.questions.length)
+      result = resolved.decide(request)
+      raise ProtocolError, "Decision provider returned an unexpected result" unless result.is_a?(DecisionResult)
+
+      handle.finish(outcome: :success, **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:, invocation_paths:, cancellation_token:, deadline:)

data/lib/little_ghost/provider_registry.rb

@@ -14,6 +14,7 @@ module LittleGhost
       "openai" => Providers::OpenAI,
       "lm_studio" => Providers::LMStudio,
       "openrouter" => Providers::OpenRouter,
+      "typesafe" => Providers::Typesafe,
       "anthropic" => Providers::Anthropic,
       "gemini" => Providers::Gemini,
       "vertex_ai" => Providers::VertexAI,

data/lib/little_ghost/providers/base.rb

@@ -47,6 +47,11 @@ module LittleGhost
         raise UnsupportedModelOperationError, "#{self.class} does not support embeddings"
       end
 
+      # Executes a typed decision request when the adapter supports it.
+      def decide(_request)
+        raise UnsupportedModelOperationError, "#{self.class} does not support decisions"
+      end
+
       # Applies provider-specific capability constraints before streaming.
       def prepare_request(request, capabilities:)
         request

data/lib/little_ghost/providers/decision_http.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module LittleGhost
+  module Providers
+    module DecisionHTTP # :nodoc:
+      private
+
+      def send_decision(request, endpoint:, model:, api_key:)
+        request.cancellation_token&.raise_if_cancelled!
+        base_url = @decision_base_url.to_s
+        base_url += "/" unless base_url.end_with?("/")
+        payload = {
+          model:,
+          state: request.state,
+          questions: request.questions.to_h do |question|
+            id = question.fetch(:id)
+            fields = question.except(:id).reject { |name, value| name == :criteria && value.nil? }
+            [id, fields]
+          end
+        }
+        body = (@decision_transport || @transport).request(
+          uri: URI.join(base_url, endpoint),
+          method: :post,
+          headers: {"Authorization" => "Bearer #{api_key}", "Content-Type" => "application/json"},
+          body: JSON.generate(payload),
+          cancellation_token: request.cancellation_token,
+          deadline: request.deadline,
+          label: "Decision request"
+        )
+        data = JSON.parse(body)
+        answers = data.fetch("answers")
+        expected_ids = request.questions.map { |question| question.fetch(:id) }.sort
+        unless answers.is_a?(Hash) && answers.keys.sort == expected_ids
+          raise ProtocolError, "Decision provider returned unexpected or incomplete answers"
+        end
+        normalized = answers.to_h do |id, answer|
+          question = request.questions.find { |item| item.fetch(:id) == id }
+          [id, normalize_answer(question, answer)]
+        end
+        usage_data = data["usage"] || {}
+        cost = usage_data["cost"] || data["cost"]
+        DecisionResult.new(
+          answers: normalized,
+          usage: Usage.new(input_tokens: usage_data["input_tokens"], output_tokens: usage_data["output_tokens"]),
+          metadata: {model: data["model"], id: data["id"], provider: data["provider"], cost:}
+        )
+      rescue JSON::ParserError, KeyError, TypeError => error
+        raise ProtocolError, "Decision provider returned an invalid response (#{error.class})"
+      end
+
+      def normalize_answer(question, raw)
+        raise ProtocolError, "Decision provider returned an invalid answer" unless raw.is_a?(Hash)
+
+        field = question.fetch(:type).to_s
+        raise ProtocolError, "Decision provider returned an answer with the wrong type" unless raw["type"] == field
+
+        value = raw[field]
+        valid = case field
+        when "choice"
+          criteria = question[:criteria]
+          options = criteria.is_a?(Hash) ? criteria.keys : Array(criteria)
+          value.is_a?(String) && options.any? { |item| item.to_s == value }
+        when "noul" then value.is_a?(Numeric) && value.finite? && value.between?(0, 1)
+        when "score" then value.is_a?(Numeric) && value.finite?
+        end
+        raise ProtocolError, "Decision provider returned an invalid #{field} answer" unless valid
+
+        if %w[choice score].include?(field)
+          confidence = raw["confidence"]
+          probabilities = raw["probabilities"]
+          unless confidence.is_a?(Numeric) && confidence.finite? && confidence.between?(0, 1) &&
+              probabilities.is_a?(Hash) && probabilities.values.all? { |probability| probability.is_a?(Numeric) && probability.finite? && probability.between?(0, 1) }
+            raise ProtocolError, "Decision provider returned invalid #{field} probabilities"
+          end
+          raise ProtocolError, "Decision provider returned an invalid score legend" if field == "score" && !raw["legend"].is_a?(Hash)
+        end
+
+        DecisionAnswer.new(
+          type: question.fetch(:type),
+          value:,
+          probabilities: raw["probabilities"] || {},
+          confidence: raw["confidence"],
+          legend: raw["legend"]
+        )
+      end
+    end
+  end
+end

data/lib/little_ghost/providers/gemini.rb

@@ -2,6 +2,7 @@
 
 require "base64"
 require "json"
+require "securerandom"
 require "uri"
 require_relative "../support/http_client"
 require_relative "../support/sse_parser"
@@ -17,6 +18,18 @@ module LittleGhost
     # LittleGhost StreamEvents. HTTP and response-shape failures become
     # ProviderError subclasses. It uses the built-in HTTP client and does not
     # require Google's SDK.
+    #
+    # Gemini attaches an opaque +thoughtSignature+ to a function-call response
+    # part and expects it echoed back on the next request's matching
+    # +functionCall+. The adapter preserves these opaque values in the response
+    # Message metadata under +gemini/thought_signatures+, keyed by tool-call ID.
+    # Preserve the full assistant Message, including this provider replay metadata,
+    # when storing or rebuilding conversation history. Signatures survive provider
+    # recreation and Message#without_reasoning and replay with their original calls.
+    #
+    # Tool results use the function name from their preceding ToolUse in the
+    # request history. Keep each tool call before its result when restoring history.
+    # Results without a preceding call retain their tool-use ID as the name.
     class Gemini < Base
       # Request policy supported by Gemini and Vertex AI HTTP clients.
       def self.request_options = %i[max_response_bytes open_timeout read_timeout].freeze
@@ -75,7 +88,8 @@ module LittleGhost
 
       def request_body(request)
         system, messages = request.messages.partition { |message| message.role == :system }
-        body = {contents: messages.map { |message| google_message(message) }}
+        tool_names = {}
+        body = {contents: messages.map { |message| google_message(message, tool_names) }}
         body[:systemInstruction] = {parts: system.flat_map { |message| message.content.grep(Content::Text).map { |block| {text: block.text} } }} unless system.empty?
         body[:tools] = [{functionDeclarations: request.tools.map { |tool| google_tool(tool) }}] unless request.tools.empty?
         body[:toolConfig] = google_tool_choice(request.tool_choice) if request.tool_choice
@@ -92,23 +106,32 @@ module LittleGhost
         {max_tokens: :maxOutputTokens, top_p: :topP, top_k: :topK, stop_sequences: :stopSequences}[key.to_sym] || key.to_sym
       end
 
-      def google_message(message)
-        {role: (message.role == :assistant) ? "model" : "user", parts: message.content.map { |block| google_content(block) }}
+      def google_message(message, tool_names)
+        signatures = message.metadata.dig(:gemini, :thought_signatures) || {}
+        {role: (message.role == :assistant) ? "model" : "user", parts: message.content.map { |block| google_content(block, signatures, tool_names) }}
       end
 
-      def google_content(block)
+      def google_content(block, thought_signatures, tool_names)
         case block
         when Content::Text then {text: block.text}
         when Content::Image, Content::Document
           {inlineData: {mimeType: block.media_type, data: Base64.strict_encode64(block.data)}}
-        when Content::ToolUse then {functionCall: {id: block.id, name: block.name, args: block.input}}
+        when Content::ToolUse
+          tool_names[block.id] = block.name
+          google_tool_use(block, thought_signatures)
         when Content::ToolResult
-          {functionResponse: {id: block.tool_use_id, name: block.tool_use_id, response: {output: Array(block.content).join("\n")}}}
+          {functionResponse: {id: block.tool_use_id, name: tool_names.fetch(block.tool_use_id, block.tool_use_id), response: {output: Array(block.content).join("\n")}}}
         when Content::Reasoning then {text: block.text, thought: true}
         else raise ConfigurationError, "Unsupported Google content block: #{block.class}"
         end
       end
 
+      def google_tool_use(block, thought_signatures)
+        call = {id: block.id, name: block.name, args: block.input}
+        signature = thought_signatures[block.id]
+        signature ? {functionCall: call, thoughtSignature: signature} : {functionCall: call}
+      end
+
       def google_tool(tool)
         value = tool.is_a?(Hash) ? tool.transform_keys(&:to_sym) : {name: tool.name, description: tool.description, input_schema: tool.input_schema}
         {name: value.fetch(:name), description: value[:description], parametersJsonSchema: value[:input_schema] || {}}
@@ -123,6 +146,7 @@ module LittleGhost
       class Normalizer # :nodoc:
         def initialize(model:)
           @model = model
+          @thought_signatures = {}
           @text = +""
           @reasoning = +""
           @tools = []
@@ -161,7 +185,8 @@ module LittleGhost
           blocks << Content::Reasoning.new(text: @reasoning) unless @reasoning.empty?
           blocks << Content::Text.new(text: @text) unless @text.empty?
           blocks.concat(@tools)
-          response = ModelResponse.new(message: Message.new(role: :assistant, content: blocks),
+          metadata = @thought_signatures.empty? ? {} : {gemini: {thought_signatures: @thought_signatures}}
+          response = ModelResponse.new(message: Message.new(role: :assistant, content: blocks, metadata:),
             stop_reason: @stop_reason, usage: @usage, metadata: {model: @model})
           [StreamEvent.build(:message_stop, response:)]
         end
@@ -172,8 +197,9 @@ module LittleGhost
           if part["functionCall"]
             call = part.fetch("functionCall")
             index = @tools.length
-            tool = Content::ToolUse.new(id: call["id"] || "call-#{index}", name: call.fetch("name"), input: call["args"] || {})
+            tool = Content::ToolUse.new(id: call["id"] || SecureRandom.uuid, name: call.fetch("name"), input: call["args"] || {})
             @tools << tool
+            @thought_signatures[tool.id] = part["thoughtSignature"] if part["thoughtSignature"]
             [
               StreamEvent.build(:tool_call_start, index:, id: tool.id, name: tool.name),
               StreamEvent.build(:tool_call_stop, index:, tool_use: tool)

data/lib/little_ghost/providers/open_router.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "openai_compatible"
+require_relative "decision_http"
 require_relative "open_router/catalog_source"
 
 module LittleGhost
@@ -20,6 +21,8 @@ module LittleGhost
     # Requests that need a capability ask OpenRouter to route only to providers
     # that advertise it.
     class OpenRouter < OpenAICompatible
+      include DecisionHTTP
+
       # Adds OpenRouter attribution to the shared OpenAI-compatible policy.
       def self.request_options = (super + [:app_name]).freeze
 
@@ -38,12 +41,26 @@ module LittleGhost
 
       # Configures an OpenRouter client. All OpenAICompatible options, including
       # +api_key+, +model+, retry limits, timeouts, and custom transport, apply.
-      def initialize(site_url: nil, app_name: nil, base_url: DEFAULT_BASE_URL, **arguments)
+      def initialize(site_url: nil, app_name: nil, base_url: DEFAULT_BASE_URL, decision_api: :decisions, **arguments)
         @site_url = site_url
         @app_name = app_name
+        @decision_api = decision_api.to_sym
+        raise ConfigurationError, "decision_api must be :decisions or :system_one" unless %i[decisions system_one].include?(@decision_api)
+        @decision_base_url = base_url
         super(base_url:, api: :chat_completions, **arguments)
       end
 
+      # Executes typed decisions through OpenRouter's selected Jev endpoint.
+      def decide(request)
+        base_url = @decision_base_url.end_with?("/") ? @decision_base_url : "#{@decision_base_url}/"
+        endpoint = if @decision_api == :decisions
+          URI.join(base_url, "../alpha/decisions").to_s
+        else
+          URI.join(base_url, "systemone").to_s
+        end
+        send_decision(request, endpoint:, model:, api_key: @api_key)
+      end
+
       # Reads model capabilities from OpenRouter +supported_parameters+ metadata.
       # Missing metadata produces ModelCapabilities.unknown.
       def capabilities(metadata: {})

data/lib/little_ghost/providers/typesafe.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "decision_http"
+
+module LittleGhost
+  module Providers
+    # Direct TypeSafe Jev decision API connection.
+    class Typesafe < Base
+      include DecisionHTTP
+
+      # The TypeSafe API base URL.
+      DEFAULT_BASE_URL = "https://api.typesafe.ai/v1/"
+
+      # Configures a direct Jev connection. Pass +transport+ to supply a custom
+      # bounded HTTP client.
+      def initialize(api_key:, model:, base_url: DEFAULT_BASE_URL, transport: nil,
+        open_timeout: 10, read_timeout: 120, max_response_bytes: Support::HTTPClient::DEFAULT_MAX_RESPONSE_BYTES)
+        @model = model
+        @decision_api_key = api_key
+        @decision_base_url = base_url
+        @decision_transport = transport || Support::HTTPClient.new(
+          base_url:, open_timeout:, read_timeout:, max_response_bytes:
+        )
+      end
+
+      def decide(request)
+        send_decision(request, endpoint: "systemone", model: @model, api_key: @decision_api_key)
+      end
+
+      def stream(_request)
+        raise UnsupportedModelOperationError, "TypeSafe supports decisions only"
+      end
+    end
+  end
+end

data/lib/little_ghost/runtime.rb

@@ -208,6 +208,11 @@ module LittleGhost
       @model_operations.embed(**arguments)
     end
 
+    # Runs typed decision questions without creating a Run.
+    def decide(**arguments)
+      @model_operations.decide(**arguments)
+    end
+
     # Creates a Run that owns any workspace and sandbox built for the request.
     #
     # +include_agent_events_by_default+ defaults to +true+, exposing source-tagged

data/lib/little_ghost/version.rb

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

data/lib/little_ghost.rb

@@ -23,6 +23,7 @@ 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/decision"
 require_relative "little_ghost/model_capabilities"
 require_relative "little_ghost/models/target"
 require_relative "little_ghost/models/details"
@@ -37,6 +38,7 @@ require_relative "little_ghost/providers/openai_compatible"
 require_relative "little_ghost/providers/openai"
 require_relative "little_ghost/providers/lm_studio"
 require_relative "little_ghost/providers/open_router"
+require_relative "little_ghost/providers/typesafe"
 require_relative "little_ghost/providers/bedrock"
 require_relative "little_ghost/providers/anthropic"
 require_relative "little_ghost/providers/gemini"
@@ -180,6 +182,9 @@ module LittleGhost
     # controls. The operation raises rather than returning a partial batch.
     def embed(...) = runtime.embed(...)
 
+    # Runs typed choice, noul, or score questions against a decision model.
+    def decide(...) = runtime.decide(...)
+
     # 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.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Matt Robinson
@@ -191,6 +191,8 @@ files:
 - docs/guides/assemblies.md
 - docs/guides/code_mode.md
 - docs/guides/core_concepts.md
+- docs/guides/decisions.md
+- docs/guides/embeddings.md
 - docs/guides/getting_started.md
 - docs/guides/integrations.md
 - docs/guides/mcp.md
@@ -245,6 +247,7 @@ files:
 - lib/little_ghost/content.rb
 - lib/little_ghost/data/model_catalog.json
 - lib/little_ghost/data_map.rb
+- lib/little_ghost/decision.rb
 - lib/little_ghost/embeddings/request.rb
 - lib/little_ghost/embeddings/response.rb
 - lib/little_ghost/errors.rb
@@ -484,6 +487,7 @@ files:
 - lib/little_ghost/providers/bedrock/credential_resolver.rb
 - lib/little_ghost/providers/bedrock/http_client.rb
 - lib/little_ghost/providers/configuration.rb
+- lib/little_ghost/providers/decision_http.rb
 - lib/little_ghost/providers/gemini.rb
 - lib/little_ghost/providers/gemini/catalog_source.rb
 - lib/little_ghost/providers/lm_studio.rb
@@ -492,6 +496,7 @@ files:
 - lib/little_ghost/providers/open_router/catalog_source.rb
 - lib/little_ghost/providers/openai.rb
 - lib/little_ghost/providers/openai_compatible.rb
+- lib/little_ghost/providers/typesafe.rb
 - lib/little_ghost/providers/vertex_ai.rb
 - lib/little_ghost/providers/vertex_ai/credential_resolver.rb
 - lib/little_ghost/run.rb