phronomy 0.28.0 → 0.30.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (157) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +96 -1
  3. data/README.md +32 -6
  4. data/docs/application-recipes.md +229 -0
  5. data/docs/architecture/agent-configuration-and-tool-binding.md +8 -0
  6. data/docs/architecture/agent-iteration-budget.md +81 -0
  7. data/docs/architecture/dx05-agent-scope.md +126 -0
  8. data/docs/architecture/dx05-workflow-task-state.md +134 -0
  9. data/docs/architecture/error-api-review.md +245 -0
  10. data/docs/architecture/generator-verifier-lifecycle-result.md +126 -0
  11. data/docs/architecture/generator-verifier-ownership.md +18 -109
  12. data/docs/architecture/llm-continuation-metadata.md +88 -0
  13. data/docs/architecture/lm-studio-output-failures.md +111 -0
  14. data/docs/architecture/r8-unit15.md +3 -0
  15. data/docs/architecture/r8-unit7.md +2 -1
  16. data/docs/architecture/structured-output-and-scope.md +183 -0
  17. data/docs/architecture/tracing.md +22 -4
  18. data/docs/architecture/transport-error-boundaries.md +103 -0
  19. data/docs/architecture/trust-acceptance-followup.md +87 -0
  20. data/docs/failure-reason-codes.md +45 -0
  21. data/docs/features.md +14 -2
  22. data/docs/getting-started.md +44 -43
  23. data/docs/migrations/r8-unit15.md +3 -0
  24. data/docs/ordered-event-delivery.md +54 -0
  25. data/docs/workflow-completion.md +92 -0
  26. data/gemfiles/http_minimum.gemfile +10 -0
  27. data/lib/phronomy/agent/admission.rb +1 -1
  28. data/lib/phronomy/agent/agent_not_found_error.rb +16 -0
  29. data/lib/phronomy/agent/agent_unloaded_error.rb +14 -0
  30. data/lib/phronomy/agent/api/agent.rb +13 -0
  31. data/lib/phronomy/agent/async_event_api.rb +121 -88
  32. data/lib/phronomy/agent/base.rb +82 -44
  33. data/lib/phronomy/agent/before_llm_input.rb +7 -1
  34. data/lib/phronomy/agent/context_importer.rb +4 -0
  35. data/lib/phronomy/agent/execution/agent_invocation.rb +6 -2
  36. data/lib/phronomy/agent/execution/dispatch_preparation.rb +6 -1
  37. data/lib/phronomy/agent/execution/exact_execution.rb +20 -9
  38. data/lib/phronomy/agent/execution/execution_cancellation.rb +1 -1
  39. data/lib/phronomy/agent/execution/execution_coordinator.rb +79 -18
  40. data/lib/phronomy/agent/execution/execution_outcome_committer.rb +24 -4
  41. data/lib/phronomy/agent/execution/execution_registry.rb +5 -1
  42. data/lib/phronomy/agent/execution/initial_preparation.rb +11 -5
  43. data/lib/phronomy/agent/execution/invocation_actions.rb +1 -1
  44. data/lib/phronomy/agent/execution/invocation_transitions.rb +4 -4
  45. data/lib/phronomy/agent/execution/iteration_budget.rb +35 -0
  46. data/lib/phronomy/agent/execution/runtime_record_encoder.rb +4 -4
  47. data/lib/phronomy/agent/execution_observation.rb +5 -5
  48. data/lib/phronomy/agent/filterable.rb +21 -15
  49. data/lib/phronomy/agent/lifecycle/lifetime_api.rb +76 -0
  50. data/lib/phronomy/agent/lifecycle/operation_lease.rb +33 -0
  51. data/lib/phronomy/agent/lifecycle/operation_result.rb +53 -0
  52. data/lib/phronomy/agent/lifecycle/ownership_registry.rb +99 -8
  53. data/lib/phronomy/agent/lifecycle/scope.rb +208 -0
  54. data/lib/phronomy/agent/lifecycle/scope_cleanup_error.rb +21 -0
  55. data/lib/phronomy/agent/lifecycle/unload_transition.rb +78 -0
  56. data/lib/phronomy/agent/output_contract.rb +64 -0
  57. data/lib/phronomy/agent/output_error.rb +53 -0
  58. data/lib/phronomy/agent/recovery/recovery_coordinator/continuation.rb +6 -6
  59. data/lib/phronomy/agent/recovery/recovery_coordinator/installation.rb +8 -7
  60. data/lib/phronomy/agent/recovery/recovery_coordinator/resolution.rb +14 -18
  61. data/lib/phronomy/agent/recovery/recovery_coordinator.rb +6 -10
  62. data/lib/phronomy/agent/recovery/recovery_support.rb +6 -8
  63. data/lib/phronomy/agent/runtime_binding/engine_session_builder.rb +2 -1
  64. data/lib/phronomy/agent/runtime_input.rb +15 -4
  65. data/lib/phronomy/agent/saved_context_reader.rb +2 -1
  66. data/lib/phronomy/agent/store.rb +10 -2
  67. data/lib/phronomy/agent/stream_callback_error.rb +2 -2
  68. data/lib/phronomy/common/error.rb +65 -1
  69. data/lib/phronomy/common/values/immutable.rb +33 -0
  70. data/lib/phronomy/content_store/base.rb +7 -2
  71. data/lib/phronomy/context/assembly.rb +18 -22
  72. data/lib/phronomy/embeddings/authentication_error.rb +11 -0
  73. data/lib/phronomy/embeddings/backends/ruby_llm_embeddings.rb +8 -2
  74. data/lib/phronomy/embeddings/rate_limit_error.rb +11 -0
  75. data/lib/phronomy/engine/fsm_session.rb +16 -1
  76. data/lib/phronomy/execution/execution_cancellation_error.rb +2 -2
  77. data/lib/phronomy/execution/execution_timeout_error.rb +2 -2
  78. data/lib/phronomy/execution/task_result.rb +7 -2
  79. data/lib/phronomy/filter/filter_block_error.rb +2 -2
  80. data/lib/phronomy/generation/generator_verifier/agent_operation.rb +28 -5
  81. data/lib/phronomy/generation/generator_verifier/agent_result_receiver.rb +14 -27
  82. data/lib/phronomy/generation/generator_verifier/approval.rb +30 -0
  83. data/lib/phronomy/generation/generator_verifier/cleanup_error.rb +15 -0
  84. data/lib/phronomy/generation/generator_verifier/invocation.rb +147 -0
  85. data/lib/phronomy/generation/generator_verifier/pipeline_state.rb +16 -0
  86. data/lib/phronomy/generation/generator_verifier/protocol.rb +55 -0
  87. data/lib/phronomy/generation/generator_verifier/result.rb +121 -0
  88. data/lib/phronomy/generation/generator_verifier/unaccepted_result_error.rb +14 -0
  89. data/lib/phronomy/generation/generator_verifier/workflow_builder.rb +13 -11
  90. data/lib/phronomy/generation/generator_verifier.rb +170 -85
  91. data/lib/phronomy/integrations/ordered_event_delivery.rb +208 -0
  92. data/lib/phronomy/llm_adapter/backends/lm_studio.rb +139 -0
  93. data/lib/phronomy/llm_adapter/backends/ruby_llm.rb +134 -12
  94. data/lib/phronomy/llm_adapter/backends/structured_response_capture.rb +41 -0
  95. data/lib/phronomy/llm_adapter/message.rb +4 -0
  96. data/lib/phronomy/llm_adapter/request.rb +17 -2
  97. data/lib/phronomy/llm_adapter/response.rb +11 -4
  98. data/lib/phronomy/llm_adapter/structured_output_unsupported_error.rb +14 -0
  99. data/lib/phronomy/llm_adapter/transport_error.rb +4 -0
  100. data/lib/phronomy/multi_agent/persistence/team_execution_repository.rb +5 -5
  101. data/lib/phronomy/multi_agent/shared_state.rb +1 -0
  102. data/lib/phronomy/multi_agent/team_busy_error.rb +18 -0
  103. data/lib/phronomy/multi_agent/team_coordinator.rb +20 -7
  104. data/lib/phronomy/multi_agent/team_not_found_error.rb +18 -0
  105. data/lib/phronomy/output_parser/json_schema_parser.rb +113 -0
  106. data/lib/phronomy/output_parser/parse_error.rb +10 -1
  107. data/lib/phronomy/runtime_composition/agent_defaults.rb +4 -0
  108. data/lib/phronomy/storage/condition_failed_error.rb +2 -2
  109. data/lib/phronomy/storage/unique_constraint_error.rb +2 -2
  110. data/lib/phronomy/testing/persistence_contract/coordination_repositories.rb +1 -1
  111. data/lib/phronomy/tool/base.rb +25 -23
  112. data/lib/phronomy/tracing/automatic.rb +14 -8
  113. data/lib/phronomy/tracing/base.rb +37 -7
  114. data/lib/phronomy/tracing/langfuse_tracer.rb +3 -3
  115. data/lib/phronomy/tracing/observation.rb +2 -1
  116. data/lib/phronomy/tracing/open_telemetry_tracer.rb +7 -32
  117. data/lib/phronomy/version.rb +1 -1
  118. data/lib/phronomy/workflow/execution/workflow.rb +30 -2
  119. data/lib/phronomy/workflow/execution/workflow_execution_environment.rb +1 -0
  120. data/lib/phronomy/workflow/execution/workflow_execution_registry.rb +74 -3
  121. data/lib/phronomy/workflow/execution/workflow_runner.rb +48 -14
  122. data/lib/phronomy/workflow/execution/workflow_task_execution.rb +153 -0
  123. data/lib/phronomy/workflow/execution/workflow_task_reception.rb +72 -0
  124. data/lib/phronomy/workflow/execution/workflow_task_resume_error.rb +14 -0
  125. data/lib/phronomy/workflow/runtime_binding/workflow_engine_environment.rb +26 -3
  126. data/lib/phronomy/workflow/runtime_binding/workflow_phase_machine_builder.rb +3 -1
  127. data/lib/phronomy/workflow/runtime_binding/workflow_task_session.rb +76 -0
  128. data/lib/phronomy.rb +7 -2
  129. data/scripts/api_snapshot.rb +15 -0
  130. data/scripts/check_readme_ruby.rb +24 -29
  131. data/scripts/check_readme_runnable.rb +92 -81
  132. data/scripts/migrate_generator_verifier_result.rb +18 -0
  133. data/sig/phronomy/agent/agent_not_found_error.rbs +6 -0
  134. data/sig/phronomy/agent/agent_unloaded_error.rbs +6 -0
  135. data/sig/phronomy/agent/execution_contract.rbs +4 -3
  136. data/sig/phronomy/agent/stream_callback_error.rbs +8 -0
  137. data/sig/phronomy/agent.rbs +36 -5
  138. data/sig/phronomy/embeddings/base.rbs +6 -0
  139. data/sig/phronomy/execution/execution.rbs +2 -2
  140. data/sig/phronomy/extensions.rbs +8 -2
  141. data/sig/phronomy/filter/filter_block_error.rbs +6 -0
  142. data/sig/phronomy/generation/generator_verifier.rbs +70 -0
  143. data/sig/phronomy/integrations.rbs +14 -0
  144. data/sig/phronomy/llm_adapter/backends/lm_studio.rbs +8 -0
  145. data/sig/phronomy/llm_adapter/backends/ruby_llm.rbs +1 -0
  146. data/sig/phronomy/llm_adapter/values.rbs +8 -2
  147. data/sig/phronomy/multi_agent/team_busy_error.rbs +8 -0
  148. data/sig/phronomy/multi_agent/team_not_found_error.rbs +8 -0
  149. data/sig/phronomy/storage/contracts.rbs +2 -2
  150. data/sig/phronomy/tracing/observation.rbs +1 -1
  151. data/sig/phronomy/workflow/execution/workflow_execution_environment.rbs +1 -0
  152. data/sig/phronomy/workflow.rbs +4 -0
  153. data/sig/phronomy.rbs +6 -0
  154. metadata +103 -5
  155. data/lib/phronomy/generation/generator_verifier/default_parser.rb +0 -27
  156. data/lib/phronomy/generation/low_confidence_error.rb +0 -14
  157. data/lib/phronomy/runtime_composition/generation_defaults.rb +0 -6
@@ -6,6 +6,11 @@ module Phronomy
6
6
  end
7
7
 
8
8
  module OutputParser
9
+ class JsonSchemaParser < Base
10
+ attr_reader json_schema: Hash[String, untyped]
11
+ def initialize: (schema: Hash[String | Symbol, untyped]) -> void
12
+ def parse: (String text) -> Hash[String, json_value]
13
+ end
9
14
  class Base
10
15
  def parse: (String text) -> untyped
11
16
  def invoke: (untyped input, ?config: Hash[untyped, untyped]) -> untyped
@@ -14,9 +19,10 @@ module Phronomy
14
19
 
15
20
  module Tracing
16
21
  class Base
22
+ def self.trace_with: [A] (untyped tracer, String name, ?record_output: bool, ?attributes: Hash[Symbol, untyped]) { (untyped span) -> [A, Hash[Symbol, Integer?]?] } -> A
17
23
  def start_span: (String name, **untyped attributes) -> untyped
18
- def finish_span: (untyped span, ?output: untyped, ?usage: untyped, ?error: Exception?) -> untyped
19
- def trace: [A] (String name, ?input: untyped, **untyped meta) { (untyped span) -> [A, untyped] } -> A
24
+ def finish_span: (untyped span, ?output: untyped, ?usage: Hash[Symbol, Integer?]?, ?error: Exception?) -> untyped
25
+ def trace: [A] (String name, ?input: untyped, **untyped meta) { (untyped span) -> [A, Hash[Symbol, Integer?]?] } -> A
20
26
  end
21
27
  end
22
28
 
@@ -0,0 +1,6 @@
1
+ module Phronomy
2
+ class FilterBlockError < Error
3
+ attr_reader filter: untyped
4
+ def initialize: (String message, ?filter: untyped, ?code: String?) -> void
5
+ end
6
+ end
@@ -0,0 +1,70 @@
1
+ module Phronomy
2
+ class GeneratorVerifier
3
+ DEFAULT_CONFIDENCE_THRESHOLD: Float
4
+ DEFAULT_MAX_ITERATIONS: Integer
5
+
6
+ interface _ApprovalListener
7
+ def call: (Approval approval) -> untyped
8
+ end
9
+
10
+ def self.open: [R] (**untyped options) { (GeneratorVerifier pipeline) -> (R | TaskResult[R]) } -> R
11
+ def initialize: (draft_agent: singleton(Agent::Base), review_agent: singleton(Agent::Base),
12
+ draft_prompt_builder: untyped, review_prompt_builder: untyped,
13
+ ?citation_schema: Hash[String | Symbol, untyped],
14
+ ?confidence_threshold: Numeric, ?max_iterations: Integer,
15
+ ?raise_if_unaccepted: bool, ?on_approval: _ApprovalListener?) -> void
16
+ def invoke: (untyped input, ?config: Hash[Symbol, untyped]) -> Result
17
+ def invoke_async: (untyped input, ?config: Hash[Symbol, untyped]) -> TaskResult[Result]
18
+ def approval_requests: () -> Array[Approval]
19
+ def cancel_async: () -> TaskResult[bool]
20
+ def release!: () -> bool
21
+
22
+ class Approval
23
+ attr_reader invocation_id: String
24
+ attr_reader phase: (:draft | :review)
25
+ attr_reader request: Agent::ToolApprovalRequest
26
+ def respond_async: (approved: bool) -> TaskResult[nil]
27
+ def to_h: () -> Hash[Symbol, untyped]
28
+ end
29
+
30
+ class Result
31
+ FIELDS: Array[Symbol]
32
+ attr_reader output: String?
33
+ attr_reader confidence: Float?
34
+ attr_reader citations: Array[Hash[String, untyped]]
35
+ attr_reader iterations: Integer
36
+ attr_reader review_notes: Array[String]
37
+ attr_reader confidence_threshold: Float
38
+ attr_reader review_approved: bool?
39
+ attr_reader termination_reason: String
40
+ attr_reader interrupted_phase: String?
41
+ attr_reader failure: Hash[String, untyped]?
42
+ def self.accepted?: (confidence: Numeric?, confidence_threshold: Numeric, review_approved: bool?) -> bool
43
+ def self.from_h: (Hash[untyped, untyped]) -> Result
44
+ def initialize: (output: String?, confidence: Numeric?,
45
+ citations: Array[Hash[untyped, untyped]], iterations: Integer, review_notes: Array[String],
46
+ confidence_threshold: Numeric, review_approved: bool?,
47
+ termination_reason: String | Symbol, ?interrupted_phase: String | Symbol | nil, ?failure: Hash[String | Symbol, untyped]?) -> void
48
+ def accepted?: () -> bool
49
+ def to_h: () -> Hash[Symbol, untyped]
50
+ def ==: (untyped other) -> bool
51
+ def eql?: (untyped other) -> bool
52
+ def hash: () -> Integer
53
+ end
54
+
55
+ class UnacceptedResultError < Phronomy::Error
56
+ attr_reader result: Result
57
+ def initialize: (Result result, ?code: String?) -> void
58
+ end
59
+
60
+ class CleanupError < Phronomy::Error
61
+ attr_reader pipeline: GeneratorVerifier
62
+ attr_reader failures: Array[{ phase: (:draft | :review | nil), error: Exception }]
63
+ attr_reader result: untyped
64
+ attr_reader primary_error: Exception?
65
+ def initialize: (pipeline: GeneratorVerifier,
66
+ failures: Array[{ phase: (:draft | :review | nil), error: Exception }],
67
+ ?result: untyped, ?primary_error: Exception?, ?code: String?) -> void
68
+ end
69
+ end
70
+ end
@@ -0,0 +1,14 @@
1
+ module Phronomy
2
+ module Integrations
3
+ class OrderedEventDelivery
4
+ class ClosedError < Phronomy::Error
5
+ end
6
+ class OverflowError < Phronomy::Error
7
+ end
8
+ def self.open: [T] (?capacity: Integer, ?batch_size: Integer, ?flush_timeout: Numeric?, deliver: ^(untyped) -> untyped, ?prepare_batch: (^(Array[untyped]) -> Array[untyped])?) { (OrderedEventDelivery) -> T } -> T
9
+ def initialize: (?capacity: Integer, ?batch_size: Integer, ?prepare_batch: (^(Array[untyped]) -> Array[untyped])?) { (untyped) -> untyped } -> void
10
+ def publish: (untyped) -> self
11
+ def close_and_wait: (?timeout: Numeric?) -> self
12
+ end
13
+ end
14
+ end
@@ -0,0 +1,8 @@
1
+ module Phronomy
2
+ module LLMAdapter
3
+ class LMStudio < RubyLLM
4
+ PARSE_FAILURE_CODE: String
5
+ def initialize: (context: untyped, ?max_parse_retries: Integer, ?on_attempt: (^(Hash[Symbol, untyped]) -> void)?) -> void
6
+ end
7
+ end
8
+ end
@@ -1,6 +1,7 @@
1
1
  module Phronomy
2
2
  module LLMAdapter
3
3
  class RubyLLM < Base
4
+ def initialize: (?context: untyped) -> void
4
5
  end
5
6
  end
6
7
  end
@@ -6,7 +6,8 @@ module Phronomy
6
6
  attr_reader messages: Array[Message]
7
7
  attr_reader tools: Array[Hash[String, untyped]]
8
8
  attr_reader message: String?
9
- def initialize: (?model_config: Hash[String | Symbol, untyped], ?system: String?, ?messages: Array[Message], ?tools: Array[Hash[String, untyped]], ?message: String?) -> void
9
+ attr_reader response_schema: Hash[String, untyped]?
10
+ 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
10
11
  end
11
12
  class Message
12
13
  attr_reader role: Symbol
@@ -21,7 +22,9 @@ module Phronomy
21
22
  end
22
23
  class Response < Message
23
24
  attr_reader usage: TokenUsage
24
- def initialize: (?content: json_value, ?tool_calls: Array[Tool::CallRequest], ?usage: TokenUsage, ?metadata: Hash[String, json_value], ?role: String | Symbol) -> void
25
+ attr_reader finish_reason: Symbol
26
+ attr_reader refusal: String?
27
+ 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
25
28
  def self.from_h: (Hash[String | Symbol, untyped] value) -> Response
26
29
  def to_h: () -> Hash[String, untyped]
27
30
  end
@@ -29,6 +32,9 @@ module Phronomy
29
32
  attr_reader content: String?
30
33
  def initialize: (content: String?) -> void
31
34
  end
35
+ class StructuredOutputUnsupportedError < Error
36
+ def initialize: (?String message) -> void
37
+ end
32
38
  class InvalidResultError < Error
33
39
  end
34
40
  class TransportError < Error
@@ -0,0 +1,8 @@
1
+ module Phronomy
2
+ module MultiAgent
3
+ class TeamBusyError < Phronomy::Error
4
+ attr_reader team_id: String
5
+ def initialize: (?String? message, team_id: untyped) -> void
6
+ end
7
+ end
8
+ end
@@ -0,0 +1,8 @@
1
+ module Phronomy
2
+ module MultiAgent
3
+ class TeamNotFoundError < Phronomy::Persistence::NotFoundError
4
+ attr_reader team_id: String
5
+ def initialize: (?String? message, team_id: untyped) -> void
6
+ end
7
+ end
8
+ end
@@ -16,11 +16,11 @@ module Phronomy
16
16
  class UniqueConstraintError < ConflictError
17
17
  attr_reader resource: String
18
18
  attr_reader constraint: Symbol
19
- def initialize: (resource: Resource, constraint: Symbol) -> void
19
+ def initialize: (resource: Resource, constraint: Symbol, ?code: String?) -> void
20
20
  end
21
21
  class ConditionFailedError < ConflictError
22
22
  attr_reader condition: condition
23
- def initialize: (condition) -> void
23
+ def initialize: (condition, ?code: String?) -> void
24
24
  end
25
25
  class BlobConflictError < ConflictError
26
26
  end
@@ -1,7 +1,7 @@
1
1
  module Phronomy
2
2
  module Tracing
3
3
  module Observation
4
- def self.trace: [A] (String name, ?input: untyped, **untyped meta) { (untyped span) -> [A, LLMAdapter::TokenUsage?] } -> A
4
+ def self.trace: [A] (String name, ?input: untyped, **untyped meta) { (untyped span) -> [A, Hash[Symbol, Integer?]?] } -> A
5
5
  end
6
6
  end
7
7
  end
@@ -10,5 +10,6 @@ module Phronomy
10
10
  def compile_transitions: (**untyped definition) -> untyped
11
11
  def build_session: (**untyped options) -> untyped
12
12
  def register_session: (untyped session, completion: TaskResult[untyped]) -> untyped
13
+ def subscribe_cancellation: (Concurrency::CancellationToken token) { () -> void } -> untyped
13
14
  end
14
15
  end
@@ -1,4 +1,7 @@
1
1
  module Phronomy
2
+ class WorkflowTaskResumeError < Error
3
+ def initialize: (?String message, ?code: String?) -> void
4
+ end
2
5
  module WorkflowContext
3
6
  def phase: () -> Symbol
4
7
  def halted?: () -> bool
@@ -20,6 +23,7 @@ module Phronomy
20
23
  class Builder
21
24
  def initial: (Symbol state_name) -> untyped
22
25
  def state: (Symbol name, ?action: untyped) -> untyped
26
+ def task_state: (Symbol name, start: ^(untyped) -> TaskResult[untyped], apply: ^(untyped, untyped) -> untyped) -> void
23
27
  def entry: (Symbol name, untyped callable) -> untyped
24
28
  def exit: (Symbol name, untyped callable) -> untyped
25
29
  def wait_state: (Symbol name) -> untyped
data/sig/phronomy.rbs CHANGED
@@ -2,9 +2,15 @@ module Phronomy
2
2
  VERSION: String
3
3
 
4
4
  class Error < StandardError
5
+ attr_reader code: String?
6
+ def initialize: (?untyped message, ?code: String?) -> void
7
+ def self.diagnostic: (Exception) -> Hash[String, untyped]
8
+ def self.from_diagnostic: (Hash[untyped, untyped], ?remaining: Integer) -> Error
5
9
  end
6
10
 
7
11
  class ParseError < Error
12
+ attr_reader details: Array[Hash[String, untyped]]
13
+ def initialize: (?untyped message, ?code: String?, ?details: Array[Hash[String, untyped]]) -> void
8
14
  end
9
15
 
10
16
  class ToolError < Error
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: phronomy
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.28.0
4
+ version: 0.30.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Raizo T.C.S
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2026-10-08 00:00:00.000000000 Z
11
+ date: 2026-10-23 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: ruby_llm
@@ -24,6 +24,46 @@ dependencies:
24
24
  - - "~>"
25
25
  - !ruby/object:Gem::Version
26
26
  version: 2.0.0
27
+ - !ruby/object:Gem::Dependency
28
+ name: faraday
29
+ requirement: !ruby/object:Gem::Requirement
30
+ requirements:
31
+ - - "~>"
32
+ - !ruby/object:Gem::Version
33
+ version: '2.14'
34
+ - - ">="
35
+ - !ruby/object:Gem::Version
36
+ version: 2.14.4
37
+ type: :runtime
38
+ prerelease: false
39
+ version_requirements: !ruby/object:Gem::Requirement
40
+ requirements:
41
+ - - "~>"
42
+ - !ruby/object:Gem::Version
43
+ version: '2.14'
44
+ - - ">="
45
+ - !ruby/object:Gem::Version
46
+ version: 2.14.4
47
+ - !ruby/object:Gem::Dependency
48
+ name: faraday-net_http
49
+ requirement: !ruby/object:Gem::Requirement
50
+ requirements:
51
+ - - "~>"
52
+ - !ruby/object:Gem::Version
53
+ version: '3.4'
54
+ - - ">="
55
+ - !ruby/object:Gem::Version
56
+ version: 3.4.4
57
+ type: :runtime
58
+ prerelease: false
59
+ version_requirements: !ruby/object:Gem::Requirement
60
+ requirements:
61
+ - - "~>"
62
+ - !ruby/object:Gem::Version
63
+ version: '3.4'
64
+ - - ">="
65
+ - !ruby/object:Gem::Version
66
+ version: 3.4.4
27
67
  - !ruby/object:Gem::Dependency
28
68
  name: schematist
29
69
  requirement: !ruby/object:Gem::Requirement
@@ -104,6 +144,9 @@ dependencies:
104
144
  name: json
105
145
  requirement: !ruby/object:Gem::Requirement
106
146
  requirements:
147
+ - - ">="
148
+ - !ruby/object:Gem::Version
149
+ version: 2.21.2
107
150
  - - "<"
108
151
  - !ruby/object:Gem::Version
109
152
  version: '3'
@@ -111,6 +154,9 @@ dependencies:
111
154
  prerelease: false
112
155
  version_requirements: !ruby/object:Gem::Requirement
113
156
  requirements:
157
+ - - ">="
158
+ - !ruby/object:Gem::Version
159
+ version: 2.21.2
114
160
  - - "<"
115
161
  - !ruby/object:Gem::Version
116
162
  version: '3'
@@ -141,21 +187,29 @@ files:
141
187
  - benchmark/bench_vector_store.rb
142
188
  - benchmark/bench_workflow.rb
143
189
  - benchmark/run_all.rb
190
+ - docs/application-recipes.md
144
191
  - docs/architecture.md
145
192
  - docs/architecture/agent-chat-and-state-ownership.md
146
193
  - docs/architecture/agent-configuration-and-tool-binding.md
147
194
  - docs/architecture/agent-context.md
195
+ - docs/architecture/agent-iteration-budget.md
148
196
  - docs/architecture/agent-transition-ownership.md
149
197
  - docs/architecture/backend-groups.md
150
198
  - docs/architecture/before-llm-input.md
151
199
  - docs/architecture/context-management.md
152
200
  - docs/architecture/context-preparation-steps.md
201
+ - docs/architecture/dx05-agent-scope.md
202
+ - docs/architecture/dx05-workflow-task-state.md
153
203
  - docs/architecture/entry-action-and-team-wording.md
204
+ - docs/architecture/error-api-review.md
154
205
  - docs/architecture/execution-abstraction-review.md
155
206
  - docs/architecture/execution-boundaries.md
156
207
  - docs/architecture/execution-metadata-and-values.md
208
+ - docs/architecture/generator-verifier-lifecycle-result.md
157
209
  - docs/architecture/generator-verifier-ownership.md
158
210
  - docs/architecture/knowledge-and-rag.md
211
+ - docs/architecture/llm-continuation-metadata.md
212
+ - docs/architecture/lm-studio-output-failures.md
159
213
  - docs/architecture/multi-agent-handoff.md
160
214
  - docs/architecture/persistence-refactoring-plan.md
161
215
  - docs/architecture/persistence.md
@@ -188,8 +242,11 @@ files:
188
242
  - docs/architecture/rubyllm-2-token-ownership.md
189
243
  - docs/architecture/security-boundaries.md
190
244
  - docs/architecture/storage-execution-boundaries.md
245
+ - docs/architecture/structured-output-and-scope.md
191
246
  - docs/architecture/tool-schema-recording-gap.md
192
247
  - docs/architecture/tracing.md
248
+ - docs/architecture/transport-error-boundaries.md
249
+ - docs/architecture/trust-acceptance-followup.md
193
250
  - docs/architecture/workflow-terminal-ownership-design.md
194
251
  - docs/archive/design/archived/04_api_design.md
195
252
  - docs/archive/design/archived/09_guardrails.md
@@ -276,6 +333,7 @@ files:
276
333
  - docs/design/durable-semantic-coordination/RECOVERY_CONTRACT_CLARIFICATIONS.md
277
334
  - docs/design/durable-semantic-coordination/RESPONSIBILITY_BOUNDARY_REVIEW.md
278
335
  - docs/execution-boundaries-preview.md
336
+ - docs/failure-reason-codes.md
279
337
  - docs/features.md
280
338
  - docs/getting-started.md
281
339
  - docs/mcp-client.md
@@ -313,15 +371,20 @@ files:
313
371
  - docs/migrations/storage-backend-composition.md
314
372
  - docs/migrations/storage-transaction-boundaries.md
315
373
  - docs/migrations/vector-async-clients.md
374
+ - docs/ordered-event-delivery.md
316
375
  - docs/persistence-backends.md
317
376
  - docs/runtime-and-concurrency.md
377
+ - docs/workflow-completion.md
318
378
  - examples/README.md
379
+ - gemfiles/http_minimum.gemfile
319
380
  - gemfiles/mcp_1_0.gemfile
320
381
  - lib/phronomy.rb
321
382
  - lib/phronomy/agent/admission.rb
322
383
  - lib/phronomy/agent/agent_already_exists_error.rb
323
384
  - lib/phronomy/agent/agent_busy_error.rb
385
+ - lib/phronomy/agent/agent_not_found_error.rb
324
386
  - lib/phronomy/agent/agent_purged_error.rb
387
+ - lib/phronomy/agent/agent_unloaded_error.rb
325
388
  - lib/phronomy/agent/api/agent.rb
326
389
  - lib/phronomy/agent/api/execution_rehydration_required_error.rb
327
390
  - lib/phronomy/agent/async_event_api.rb
@@ -347,6 +410,7 @@ files:
347
410
  - lib/phronomy/agent/execution/initial_preparation.rb
348
411
  - lib/phronomy/agent/execution/invocation_actions.rb
349
412
  - lib/phronomy/agent/execution/invocation_transitions.rb
413
+ - lib/phronomy/agent/execution/iteration_budget.rb
350
414
  - lib/phronomy/agent/execution/llm_operation_result.rb
351
415
  - lib/phronomy/agent/execution/runtime_record_encoder.rb
352
416
  - lib/phronomy/agent/execution_change.rb
@@ -363,7 +427,15 @@ files:
363
427
  - lib/phronomy/agent/knowledge_item.rb
364
428
  - lib/phronomy/agent/lifecycle/agent_root.rb
365
429
  - lib/phronomy/agent/lifecycle/default_persistence.rb
430
+ - lib/phronomy/agent/lifecycle/lifetime_api.rb
431
+ - lib/phronomy/agent/lifecycle/operation_lease.rb
432
+ - lib/phronomy/agent/lifecycle/operation_result.rb
366
433
  - lib/phronomy/agent/lifecycle/ownership_registry.rb
434
+ - lib/phronomy/agent/lifecycle/scope.rb
435
+ - lib/phronomy/agent/lifecycle/scope_cleanup_error.rb
436
+ - lib/phronomy/agent/lifecycle/unload_transition.rb
437
+ - lib/phronomy/agent/output_contract.rb
438
+ - lib/phronomy/agent/output_error.rb
367
439
  - lib/phronomy/agent/persistence/agent_repository.rb
368
440
  - lib/phronomy/agent/persistence/cancellation_repository.rb
369
441
  - lib/phronomy/agent/persistence/codec.rb
@@ -431,9 +503,11 @@ files:
431
503
  - lib/phronomy/documents/splitter/fixed_size_splitter.rb
432
504
  - lib/phronomy/documents/splitter/recursive_splitter.rb
433
505
  - lib/phronomy/embeddings/async/async_client.rb
506
+ - lib/phronomy/embeddings/authentication_error.rb
434
507
  - lib/phronomy/embeddings/backends/ruby_llm_embeddings.rb
435
508
  - lib/phronomy/embeddings/base.rb
436
509
  - lib/phronomy/embeddings/invalid_result_error.rb
510
+ - lib/phronomy/embeddings/rate_limit_error.rb
437
511
  - lib/phronomy/embeddings/transport_error.rb
438
512
  - lib/phronomy/engine/concurrency/async_queue.rb
439
513
  - lib/phronomy/engine/concurrency/offload_pool.rb
@@ -490,14 +564,21 @@ files:
490
564
  - lib/phronomy/generation/generator_verifier.rb
491
565
  - lib/phronomy/generation/generator_verifier/agent_operation.rb
492
566
  - lib/phronomy/generation/generator_verifier/agent_result_receiver.rb
493
- - lib/phronomy/generation/generator_verifier/default_parser.rb
567
+ - lib/phronomy/generation/generator_verifier/approval.rb
568
+ - lib/phronomy/generation/generator_verifier/cleanup_error.rb
569
+ - lib/phronomy/generation/generator_verifier/invocation.rb
494
570
  - lib/phronomy/generation/generator_verifier/pipeline_state.rb
571
+ - lib/phronomy/generation/generator_verifier/protocol.rb
572
+ - lib/phronomy/generation/generator_verifier/result.rb
573
+ - lib/phronomy/generation/generator_verifier/unaccepted_result_error.rb
495
574
  - lib/phronomy/generation/generator_verifier/workflow_builder.rb
496
- - lib/phronomy/generation/low_confidence_error.rb
575
+ - lib/phronomy/integrations/ordered_event_delivery.rb
497
576
  - lib/phronomy/llm_adapter.rb
498
577
  - lib/phronomy/llm_adapter/async/async_client.rb
499
578
  - lib/phronomy/llm_adapter/authentication_error.rb
579
+ - lib/phronomy/llm_adapter/backends/lm_studio.rb
500
580
  - lib/phronomy/llm_adapter/backends/ruby_llm.rb
581
+ - lib/phronomy/llm_adapter/backends/structured_response_capture.rb
501
582
  - lib/phronomy/llm_adapter/base.rb
502
583
  - lib/phronomy/llm_adapter/context_length_error.rb
503
584
  - lib/phronomy/llm_adapter/invalid_result_error.rb
@@ -506,6 +587,7 @@ files:
506
587
  - lib/phronomy/llm_adapter/request.rb
507
588
  - lib/phronomy/llm_adapter/response.rb
508
589
  - lib/phronomy/llm_adapter/stream_chunk.rb
590
+ - lib/phronomy/llm_adapter/structured_output_unsupported_error.rb
509
591
  - lib/phronomy/llm_adapter/token_usage.rb
510
592
  - lib/phronomy/llm_adapter/transport_error.rb
511
593
  - lib/phronomy/llm_context_window/token_budget.rb
@@ -530,13 +612,16 @@ files:
530
612
  - lib/phronomy/multi_agent/runtime_binding/engine_environment.rb
531
613
  - lib/phronomy/multi_agent/shared_state.rb
532
614
  - lib/phronomy/multi_agent/store.rb
615
+ - lib/phronomy/multi_agent/team_busy_error.rb
533
616
  - lib/phronomy/multi_agent/team_coordinator.rb
534
617
  - lib/phronomy/multi_agent/team_execution.rb
618
+ - lib/phronomy/multi_agent/team_not_found_error.rb
535
619
  - lib/phronomy/multi_agent/team_ownership_registry.rb
536
620
  - lib/phronomy/multi_agent/team_root.rb
537
621
  - lib/phronomy/output_parser.rb
538
622
  - lib/phronomy/output_parser/base.rb
539
623
  - lib/phronomy/output_parser/json_parser.rb
624
+ - lib/phronomy/output_parser/json_schema_parser.rb
540
625
  - lib/phronomy/output_parser/parse_error.rb
541
626
  - lib/phronomy/output_parser/structured_parser.rb
542
627
  - lib/phronomy/persistence/content_repository.rb
@@ -555,7 +640,6 @@ files:
555
640
  - lib/phronomy/runtime_composition/configuration_defaults.rb
556
641
  - lib/phronomy/runtime_composition/evaluation_defaults.rb
557
642
  - lib/phronomy/runtime_composition/execution_defaults.rb
558
- - lib/phronomy/runtime_composition/generation_defaults.rb
559
643
  - lib/phronomy/runtime_composition/global_configuration.rb
560
644
  - lib/phronomy/runtime_composition/global_runtime.rb
561
645
  - lib/phronomy/runtime_composition/multi_agent_defaults.rb
@@ -645,11 +729,15 @@ files:
645
729
  - lib/phronomy/workflow/execution/workflow_execution_registry.rb
646
730
  - lib/phronomy/workflow/execution/workflow_runner.rb
647
731
  - lib/phronomy/workflow/execution/workflow_settings.rb
732
+ - lib/phronomy/workflow/execution/workflow_task_execution.rb
733
+ - lib/phronomy/workflow/execution/workflow_task_reception.rb
734
+ - lib/phronomy/workflow/execution/workflow_task_resume_error.rb
648
735
  - lib/phronomy/workflow/persistence/codec.rb
649
736
  - lib/phronomy/workflow/persistence/state_repository.rb
650
737
  - lib/phronomy/workflow/persistence/storage_schema.rb
651
738
  - lib/phronomy/workflow/runtime_binding/workflow_engine_environment.rb
652
739
  - lib/phronomy/workflow/runtime_binding/workflow_phase_machine_builder.rb
740
+ - lib/phronomy/workflow/runtime_binding/workflow_task_session.rb
653
741
  - lib/phronomy/workflow/runtime_binding/workflow_terminal_policy.rb
654
742
  - scripts/add_to_h_to_token_doubles.rb
655
743
  - scripts/add_to_h_unnamed_doubles.rb
@@ -657,6 +745,7 @@ files:
657
745
  - scripts/check_api_annotations.rb
658
746
  - scripts/check_readme_ruby.rb
659
747
  - scripts/check_readme_runnable.rb
748
+ - scripts/migrate_generator_verifier_result.rb
660
749
  - scripts/migrate_spec_agent_definition.rb
661
750
  - scripts/migrate_spec_agent_definition_pass2.rb
662
751
  - scripts/migrate_spec_inline_pass3.rb
@@ -673,9 +762,12 @@ files:
673
762
  - sig/phronomy.rbs
674
763
  - sig/phronomy/agent.rbs
675
764
  - sig/phronomy/agent/admission.rbs
765
+ - sig/phronomy/agent/agent_not_found_error.rbs
766
+ - sig/phronomy/agent/agent_unloaded_error.rbs
676
767
  - sig/phronomy/agent/execution_contract.rbs
677
768
  - sig/phronomy/agent/execution_environment.rbs
678
769
  - sig/phronomy/agent/store.rbs
770
+ - sig/phronomy/agent/stream_callback_error.rbs
679
771
  - sig/phronomy/common.rbs
680
772
  - sig/phronomy/content_store/contracts.rbs
681
773
  - sig/phronomy/context.rbs
@@ -701,7 +793,11 @@ files:
701
793
  - sig/phronomy/execution/invocation_controls.rbs
702
794
  - sig/phronomy/execution/task_result.rbs
703
795
  - sig/phronomy/extensions.rbs
796
+ - sig/phronomy/filter/filter_block_error.rbs
797
+ - sig/phronomy/generation/generator_verifier.rbs
704
798
  - sig/phronomy/handoff.rbs
799
+ - sig/phronomy/integrations.rbs
800
+ - sig/phronomy/llm_adapter/backends/lm_studio.rbs
705
801
  - sig/phronomy/llm_adapter/backends/ruby_llm.rbs
706
802
  - sig/phronomy/llm_adapter/base.rbs
707
803
  - sig/phronomy/llm_adapter/usage.rbs
@@ -710,6 +806,8 @@ files:
710
806
  - sig/phronomy/multi_agent.rbs
711
807
  - sig/phronomy/multi_agent/reserved_child_admission.rbs
712
808
  - sig/phronomy/multi_agent/store.rbs
809
+ - sig/phronomy/multi_agent/team_busy_error.rbs
810
+ - sig/phronomy/multi_agent/team_not_found_error.rbs
713
811
  - sig/phronomy/persistence.rbs
714
812
  - sig/phronomy/persistence/errors.rbs
715
813
  - sig/phronomy/persistence/migration.rbs
@@ -1,27 +0,0 @@
1
- # frozen_string_literal: true
2
-
3
- module Phronomy
4
- class GeneratorVerifier
5
- # Boot supplies the default concrete parser. The generation algorithm owns
6
- # its output interpretation and fallback, not the concrete parser selection.
7
- # @api private
8
- module DefaultParser
9
- FACTORIES = {}
10
- private_constant :FACTORIES
11
-
12
- # Private one-time composition binding; not an application registry.
13
- # @api private
14
- def self.install_factory(factory)
15
- raise ArgumentError, "factory must respond to call" unless factory.respond_to?(:call)
16
-
17
- FACTORIES.replace(parser: factory).freeze
18
- nil
19
- end
20
-
21
- # @api private
22
- def self.build
23
- FACTORIES.fetch(:parser).call
24
- end
25
- end
26
- end
27
- end
@@ -1,14 +0,0 @@
1
- # frozen_string_literal: true
2
-
3
- require_relative "../common/error"
4
-
5
- module Phronomy
6
- class LowConfidenceError < Error
7
- attr_reader :result
8
-
9
- def initialize(result)
10
- @result = result
11
- super("Answer confidence #{result.confidence} is below the required threshold")
12
- end
13
- end
14
- end
@@ -1,6 +0,0 @@
1
- # frozen_string_literal: true
2
-
3
- # Select the existing default without constructing a parser during boot.
4
- Phronomy::GeneratorVerifier::DefaultParser.install_factory(
5
- -> { Phronomy::OutputParser::JsonParser.new }
6
- )