phronomy 0.29.0 → 0.30.0

data/sig/phronomy/generation/generator_verifier.rbs

@@ -0,0 +1,70 @@
+module Phronomy
+  class GeneratorVerifier
+    DEFAULT_CONFIDENCE_THRESHOLD: Float
+    DEFAULT_MAX_ITERATIONS: Integer
+
+    interface _ApprovalListener
+      def call: (Approval approval) -> untyped
+    end
+
+    def self.open: [R] (**untyped options) { (GeneratorVerifier pipeline) -> (R | TaskResult[R]) } -> R
+    def initialize: (draft_agent: singleton(Agent::Base), review_agent: singleton(Agent::Base),
+      draft_prompt_builder: untyped, review_prompt_builder: untyped,
+      ?citation_schema: Hash[String | Symbol, untyped],
+      ?confidence_threshold: Numeric, ?max_iterations: Integer,
+      ?raise_if_unaccepted: bool, ?on_approval: _ApprovalListener?) -> void
+    def invoke: (untyped input, ?config: Hash[Symbol, untyped]) -> Result
+    def invoke_async: (untyped input, ?config: Hash[Symbol, untyped]) -> TaskResult[Result]
+    def approval_requests: () -> Array[Approval]
+    def cancel_async: () -> TaskResult[bool]
+    def release!: () -> bool
+
+    class Approval
+      attr_reader invocation_id: String
+      attr_reader phase: (:draft | :review)
+      attr_reader request: Agent::ToolApprovalRequest
+      def respond_async: (approved: bool) -> TaskResult[nil]
+      def to_h: () -> Hash[Symbol, untyped]
+    end
+
+    class Result
+      FIELDS: Array[Symbol]
+      attr_reader output: String?
+      attr_reader confidence: Float?
+      attr_reader citations: Array[Hash[String, untyped]]
+      attr_reader iterations: Integer
+      attr_reader review_notes: Array[String]
+      attr_reader confidence_threshold: Float
+      attr_reader review_approved: bool?
+      attr_reader termination_reason: String
+      attr_reader interrupted_phase: String?
+      attr_reader failure: Hash[String, untyped]?
+      def self.accepted?: (confidence: Numeric?, confidence_threshold: Numeric, review_approved: bool?) -> bool
+      def self.from_h: (Hash[untyped, untyped]) -> Result
+      def initialize: (output: String?, confidence: Numeric?,
+        citations: Array[Hash[untyped, untyped]], iterations: Integer, review_notes: Array[String],
+        confidence_threshold: Numeric, review_approved: bool?,
+        termination_reason: String | Symbol, ?interrupted_phase: String | Symbol | nil, ?failure: Hash[String | Symbol, untyped]?) -> void
+      def accepted?: () -> bool
+      def to_h: () -> Hash[Symbol, untyped]
+      def ==: (untyped other) -> bool
+      def eql?: (untyped other) -> bool
+      def hash: () -> Integer
+    end
+
+    class UnacceptedResultError < Phronomy::Error
+      attr_reader result: Result
+      def initialize: (Result result, ?code: String?) -> void
+    end
+
+    class CleanupError < Phronomy::Error
+      attr_reader pipeline: GeneratorVerifier
+      attr_reader failures: Array[{ phase: (:draft | :review | nil), error: Exception }]
+      attr_reader result: untyped
+      attr_reader primary_error: Exception?
+      def initialize: (pipeline: GeneratorVerifier,
+        failures: Array[{ phase: (:draft | :review | nil), error: Exception }],
+        ?result: untyped, ?primary_error: Exception?, ?code: String?) -> void
+    end
+  end
+end

data/sig/phronomy/llm_adapter/backends/lm_studio.rbs

@@ -0,0 +1,8 @@
+module Phronomy
+  module LLMAdapter
+    class LMStudio < RubyLLM
+      PARSE_FAILURE_CODE: String
+      def initialize: (context: untyped, ?max_parse_retries: Integer, ?on_attempt: (^(Hash[Symbol, untyped]) -> void)?) -> void
+    end
+  end
+end

data/sig/phronomy/llm_adapter/backends/ruby_llm.rbs

@@ -1,6 +1,7 @@
 module Phronomy
   module LLMAdapter
     class RubyLLM < Base
+      def initialize: (?context: untyped) -> void
     end
   end
 end

data/sig/phronomy/llm_adapter/values.rbs

@@ -6,7 +6,8 @@ module Phronomy
       attr_reader messages: Array[Message]
       attr_reader tools: Array[Hash[String, untyped]]
       attr_reader message: String?
-      def initialize: (?model_config: Hash[String | Symbol, untyped], ?system: String?, ?messages: Array[Message], ?tools: Array[Hash[String, untyped]], ?message: String?) -> void
+      attr_reader response_schema: Hash[String, untyped]?
+      def initialize: (?model_config: Hash[String | Symbol, untyped], ?system: String?, ?messages: Array[Message], ?tools: Array[Hash[String, untyped]], ?message: String?, ?response_schema: Hash[String | Symbol, untyped]?) -> void
     end
     class Message
       attr_reader role: Symbol
@@ -21,7 +22,9 @@ module Phronomy
     end
     class Response < Message
       attr_reader usage: TokenUsage
-      def initialize: (?content: json_value, ?tool_calls: Array[Tool::CallRequest], ?usage: TokenUsage, ?metadata: Hash[String, json_value], ?role: String | Symbol) -> void
+      attr_reader finish_reason: Symbol
+      attr_reader refusal: String?
+      def initialize: (?content: json_value, ?tool_calls: Array[Tool::CallRequest], ?usage: TokenUsage, ?metadata: Hash[String, json_value], ?role: String | Symbol, ?finish_reason: String | Symbol, ?refusal: String?) -> void
       def self.from_h: (Hash[String | Symbol, untyped] value) -> Response
       def to_h: () -> Hash[String, untyped]
     end
@@ -29,6 +32,9 @@ module Phronomy
       attr_reader content: String?
       def initialize: (content: String?) -> void
     end
+    class StructuredOutputUnsupportedError < Error
+      def initialize: (?String message) -> void
+    end
     class InvalidResultError < Error
     end
     class TransportError < Error

data/sig/phronomy/tracing/observation.rbs

@@ -1,7 +1,7 @@
 module Phronomy
   module Tracing
     module Observation
-      def self.trace: [A] (String name, ?input: untyped, **untyped meta) { (untyped span) -> [A, LLMAdapter::TokenUsage?] } -> A
+      def self.trace: [A] (String name, ?input: untyped, **untyped meta) { (untyped span) -> [A, Hash[Symbol, Integer?]?] } -> A
     end
   end
 end

data/sig/phronomy.rbs

@@ -9,6 +9,8 @@ module Phronomy
   end
 
   class ParseError < Error
+    attr_reader details: Array[Hash[String, untyped]]
+    def initialize: (?untyped message, ?code: String?, ?details: Array[Hash[String, untyped]]) -> void
   end
 
   class ToolError < Error

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.29.0
+  version: 0.30.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-12 00:00:00.000000000 Z
+date: 2026-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -30,14 +30,40 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '2.14'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.14.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '2.14'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.14.4
+- !ruby/object:Gem::Dependency
+  name: faraday-net_http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.4.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.4.4
 - !ruby/object:Gem::Dependency
   name: schematist
   requirement: !ruby/object:Gem::Requirement
@@ -118,6 +144,9 @@ dependencies:
   name: json
   requirement: !ruby/object:Gem::Requirement
     requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.21.2
     - - "<"
       - !ruby/object:Gem::Version
         version: '3'
@@ -125,6 +154,9 @@ dependencies:
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.21.2
     - - "<"
       - !ruby/object:Gem::Version
         version: '3'
@@ -160,6 +192,7 @@ files:
 - docs/architecture/agent-chat-and-state-ownership.md
 - docs/architecture/agent-configuration-and-tool-binding.md
 - docs/architecture/agent-context.md
+- docs/architecture/agent-iteration-budget.md
 - docs/architecture/agent-transition-ownership.md
 - docs/architecture/backend-groups.md
 - docs/architecture/before-llm-input.md
@@ -172,8 +205,11 @@ files:
 - docs/architecture/execution-abstraction-review.md
 - docs/architecture/execution-boundaries.md
 - docs/architecture/execution-metadata-and-values.md
+- docs/architecture/generator-verifier-lifecycle-result.md
 - docs/architecture/generator-verifier-ownership.md
 - docs/architecture/knowledge-and-rag.md
+- docs/architecture/llm-continuation-metadata.md
+- docs/architecture/lm-studio-output-failures.md
 - docs/architecture/multi-agent-handoff.md
 - docs/architecture/persistence-refactoring-plan.md
 - docs/architecture/persistence.md
@@ -206,8 +242,11 @@ files:
 - docs/architecture/rubyllm-2-token-ownership.md
 - docs/architecture/security-boundaries.md
 - docs/architecture/storage-execution-boundaries.md
+- docs/architecture/structured-output-and-scope.md
 - docs/architecture/tool-schema-recording-gap.md
 - docs/architecture/tracing.md
+- docs/architecture/transport-error-boundaries.md
+- docs/architecture/trust-acceptance-followup.md
 - docs/architecture/workflow-terminal-ownership-design.md
 - docs/archive/design/archived/04_api_design.md
 - docs/archive/design/archived/09_guardrails.md
@@ -371,6 +410,7 @@ files:
 - lib/phronomy/agent/execution/initial_preparation.rb
 - lib/phronomy/agent/execution/invocation_actions.rb
 - lib/phronomy/agent/execution/invocation_transitions.rb
+- lib/phronomy/agent/execution/iteration_budget.rb
 - lib/phronomy/agent/execution/llm_operation_result.rb
 - lib/phronomy/agent/execution/runtime_record_encoder.rb
 - lib/phronomy/agent/execution_change.rb
@@ -394,6 +434,8 @@ files:
 - lib/phronomy/agent/lifecycle/scope.rb
 - lib/phronomy/agent/lifecycle/scope_cleanup_error.rb
 - lib/phronomy/agent/lifecycle/unload_transition.rb
+- lib/phronomy/agent/output_contract.rb
+- lib/phronomy/agent/output_error.rb
 - lib/phronomy/agent/persistence/agent_repository.rb
 - lib/phronomy/agent/persistence/cancellation_repository.rb
 - lib/phronomy/agent/persistence/codec.rb
@@ -522,15 +564,21 @@ files:
 - lib/phronomy/generation/generator_verifier.rb
 - lib/phronomy/generation/generator_verifier/agent_operation.rb
 - lib/phronomy/generation/generator_verifier/agent_result_receiver.rb
-- lib/phronomy/generation/generator_verifier/default_parser.rb
+- lib/phronomy/generation/generator_verifier/approval.rb
+- lib/phronomy/generation/generator_verifier/cleanup_error.rb
+- lib/phronomy/generation/generator_verifier/invocation.rb
 - lib/phronomy/generation/generator_verifier/pipeline_state.rb
+- lib/phronomy/generation/generator_verifier/protocol.rb
+- lib/phronomy/generation/generator_verifier/result.rb
+- lib/phronomy/generation/generator_verifier/unaccepted_result_error.rb
 - lib/phronomy/generation/generator_verifier/workflow_builder.rb
-- lib/phronomy/generation/low_confidence_error.rb
 - lib/phronomy/integrations/ordered_event_delivery.rb
 - lib/phronomy/llm_adapter.rb
 - lib/phronomy/llm_adapter/async/async_client.rb
 - lib/phronomy/llm_adapter/authentication_error.rb
+- lib/phronomy/llm_adapter/backends/lm_studio.rb
 - lib/phronomy/llm_adapter/backends/ruby_llm.rb
+- lib/phronomy/llm_adapter/backends/structured_response_capture.rb
 - lib/phronomy/llm_adapter/base.rb
 - lib/phronomy/llm_adapter/context_length_error.rb
 - lib/phronomy/llm_adapter/invalid_result_error.rb
@@ -539,6 +587,7 @@ files:
 - lib/phronomy/llm_adapter/request.rb
 - lib/phronomy/llm_adapter/response.rb
 - lib/phronomy/llm_adapter/stream_chunk.rb
+- lib/phronomy/llm_adapter/structured_output_unsupported_error.rb
 - lib/phronomy/llm_adapter/token_usage.rb
 - lib/phronomy/llm_adapter/transport_error.rb
 - lib/phronomy/llm_context_window/token_budget.rb
@@ -572,6 +621,7 @@ files:
 - lib/phronomy/output_parser.rb
 - lib/phronomy/output_parser/base.rb
 - lib/phronomy/output_parser/json_parser.rb
+- lib/phronomy/output_parser/json_schema_parser.rb
 - lib/phronomy/output_parser/parse_error.rb
 - lib/phronomy/output_parser/structured_parser.rb
 - lib/phronomy/persistence/content_repository.rb
@@ -590,7 +640,6 @@ files:
 - lib/phronomy/runtime_composition/configuration_defaults.rb
 - lib/phronomy/runtime_composition/evaluation_defaults.rb
 - lib/phronomy/runtime_composition/execution_defaults.rb
-- lib/phronomy/runtime_composition/generation_defaults.rb
 - lib/phronomy/runtime_composition/global_configuration.rb
 - lib/phronomy/runtime_composition/global_runtime.rb
 - lib/phronomy/runtime_composition/multi_agent_defaults.rb
@@ -696,6 +745,7 @@ files:
 - scripts/check_api_annotations.rb
 - scripts/check_readme_ruby.rb
 - scripts/check_readme_runnable.rb
+- scripts/migrate_generator_verifier_result.rb
 - scripts/migrate_spec_agent_definition.rb
 - scripts/migrate_spec_agent_definition_pass2.rb
 - scripts/migrate_spec_inline_pass3.rb
@@ -744,9 +794,10 @@ files:
 - sig/phronomy/execution/task_result.rbs
 - sig/phronomy/extensions.rbs
 - sig/phronomy/filter/filter_block_error.rbs
-- sig/phronomy/generation/low_confidence_error.rbs
+- sig/phronomy/generation/generator_verifier.rbs
 - sig/phronomy/handoff.rbs
 - sig/phronomy/integrations.rbs
+- sig/phronomy/llm_adapter/backends/lm_studio.rbs
 - sig/phronomy/llm_adapter/backends/ruby_llm.rbs
 - sig/phronomy/llm_adapter/base.rbs
 - sig/phronomy/llm_adapter/usage.rbs

data/lib/phronomy/generation/generator_verifier/default_parser.rb

@@ -1,27 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  class GeneratorVerifier
-    # Boot supplies the default concrete parser. The generation algorithm owns
-    # its output interpretation and fallback, not the concrete parser selection.
-    # @api private
-    module DefaultParser
-      FACTORIES = {}
-      private_constant :FACTORIES
-
-      # Private one-time composition binding; not an application registry.
-      # @api private
-      def self.install_factory(factory)
-        raise ArgumentError, "factory must respond to call" unless factory.respond_to?(:call)
-
-        FACTORIES.replace(parser: factory).freeze
-        nil
-      end
-
-      # @api private
-      def self.build
-        FACTORIES.fetch(:parser).call
-      end
-    end
-  end
-end

data/lib/phronomy/generation/low_confidence_error.rb

@@ -1,14 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../common/error"
-
-module Phronomy
-  class LowConfidenceError < Error
-    attr_reader :result
-
-    def initialize(result, code: nil)
-      @result = result
-      super("Answer confidence #{result.confidence} is below the required threshold", code: code)
-    end
-  end
-end

data/lib/phronomy/runtime_composition/generation_defaults.rb

@@ -1,6 +0,0 @@
-# frozen_string_literal: true
-
-# Select the existing default without constructing a parser during boot.
-Phronomy::GeneratorVerifier::DefaultParser.install_factory(
-  -> { Phronomy::OutputParser::JsonParser.new }
-)

data/sig/phronomy/generation/low_confidence_error.rbs

@@ -1,6 +0,0 @@
-module Phronomy
-  class LowConfidenceError < Error
-    attr_reader result: untyped
-    def initialize: (untyped result, ?code: String?) -> void
-  end
-end