phronomy 0.20.0 → 0.22.0

data/lib/phronomy/vector_store/embeddings/base.rb

@@ -3,15 +3,18 @@
 module Phronomy
   module VectorStore
     module Embeddings
-      # Abstract interface for embedding adapters.
+      # Public extension SPI for embedding adapters.
       #
-      # Concrete implementations must override {#embed} and return a vector
-      # as an +Array<Float>+.
+      # Concrete implementations override {#embed}. Phronomy owns the async
+      # bridge: {#embed_async} routes the synchronous implementation through the
+      # bounded OffloadPool and returns a {Phronomy::Task}.
+      #
+      # @api public
       class Base
         # Embed the given text and return a vector representation.
         #
-        # @param text               [String]                         the text to embed
-        # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; raises CancellationError when cancelled
+        # @param text               [String] the text to embed
+        # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
         # @return [Array<Float>] the embedding vector
         # @api public
         def embed(text, cancellation_token = nil)
@@ -19,13 +22,12 @@ module Phronomy
           raise NotImplementedError, "#{self.class}#embed is not implemented"
         end
 
-        # Submits an {#embed} call to {OffloadPool} and returns an
-        # {OffloadPool::PendingOperation}.
+        # Submits an {#embed} call to {OffloadPool}.
         #
         # @param text               [String]
         # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
-        # @param timeout            [Numeric, nil] seconds before the operation is abandoned
-        # @return [OffloadPool::PendingOperation]
+        # @param timeout            [Numeric, nil] operation-wide submit timeout
+        # @return [Phronomy::Task]
         # @api public
         def embed_async(text, cancellation_token = nil, timeout: nil)
           Phronomy::Runtime.instance.offload.submit(

data/lib/phronomy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phronomy
-  VERSION = "0.20.0"
+  VERSION = "0.22.0"
 end

data/scripts/run_mutation.sh

@@ -13,7 +13,8 @@
 # Target: mutation score >= 80% for each listed subject.
 # Baseline scores (as of initial run):
 #   Phronomy::WorkflowContext  84.85%
-#   Phronomy::Tool::Base       55.74%
+#   Phronomy::Agent::Context::Capability::Base  55.74%
+#     (public facade alias: Phronomy::Tool::Base; same Class object)
 #
 # Note: mutation testing is slow (~1-5 min per subject). Run locally or via
 # the nightly-mutation GitHub Actions workflow.

data/sig/phronomy/agent.rbs

@@ -0,0 +1,36 @@
+module Phronomy
+  module Agent
+    class Base
+      def self.model: (?String name) -> String?
+      def self.instructions: (?untyped text) { (untyped) -> untyped } -> untyped
+                           | (?untyped text) -> untyped
+      def self.tools: (?Hash[Class, String?] definitions) -> untyped
+      def self.tool_aliases: () -> Hash[Class, String]
+      def self.provider: (?Symbol name) -> Symbol?
+      def self.temperature: (?Float value) -> Float?
+      def self.max_iterations: (?Integer value) -> Integer
+      def self.cache_instructions: (?bool enabled) -> bool?
+      def self.max_output_tokens: (?Integer value) -> Integer?
+      def self.context_window: (?Integer value) -> Integer?
+      def self.agent_definition: (?id: String?, ?version: Integer?) -> Hash[Symbol, untyped]
+      def self.create: (?agent_id: String, ?context: untyped, ?knowledge: Array[untyped], ?persistence: Persistence?, ?metadata: Hash[untyped, untyped]) -> instance
+      def self.load: (String agent_id, persistence: Persistence) -> instance
+      def self.live_for_execution: (String execution_id) -> instance
+
+      attr_reader agent_id: String
+      attr_reader persistence: Persistence
+
+      def invoke: (untyped input, **untyped) -> Hash[Symbol, untyped]
+      def invoke_async: (untyped input, **untyped) -> Task[Hash[Symbol, untyped]]
+      def stream: (untyped input, **untyped) { (untyped event) -> void } -> Hash[Symbol, untyped]
+      def stream_async: (untyped input, **untyped) -> Task[Hash[Symbol, untyped]]
+      def transcript: () -> Array[untyped]
+      def add_knowledge: (untyped content, ?metadata: Hash[untyped, untyped]) -> self
+      def clear_transcript!: () -> untyped
+      def clear_knowledge!: () -> untyped
+      def reset_context!: () -> untyped
+      def close!: () -> untyped
+      def purge!: () -> bool
+    end
+  end
+end

data/sig/phronomy/extensions.rbs

@@ -0,0 +1,50 @@
+module Phronomy
+  module Filter
+    class Base
+      def call: (untyped value, **untyped context) -> untyped
+    end
+  end
+
+  module OutputParser
+    class Base
+      def parse: (String text) -> untyped
+      def invoke: (untyped input, ?config: Hash[untyped, untyped]) -> untyped
+    end
+  end
+
+  module Tracing
+    class Base
+      def start_span: (String name, **untyped attributes) -> untyped
+      def finish_span: (untyped span, ?output: untyped, ?usage: untyped, ?error: Exception?) -> untyped
+      def trace: [A] (String name, ?input: untyped, **untyped meta) { (untyped span) -> [A, untyped] } -> A
+    end
+  end
+
+  module VectorStore
+    class Base
+      def add: (id: String, embedding: Array[Float], ?metadata: Hash[untyped, untyped], ?cancellation_token: Concurrency::CancellationToken?) -> untyped
+      def search: (query_embedding: Array[Float], ?k: Integer, ?cancellation_token: Concurrency::CancellationToken?) -> Array[Hash[Symbol, untyped]]
+      def remove: (id: String) -> untyped
+      def clear: () -> untyped
+      def size: () -> Integer
+
+      def add_async: (id: String, embedding: Array[Float], ?metadata: Hash[untyped, untyped], ?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> Task[untyped]
+      def search_async: (query_embedding: Array[Float], ?k: Integer, ?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> Task[Array[Hash[Symbol, untyped]]]
+      def remove_async: (id: String, ?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> Task[untyped]
+      def clear_async: (?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> Task[untyped]
+    end
+
+    module Embeddings
+      class Base
+        def embed: (String text, ?Concurrency::CancellationToken? cancellation_token) -> Array[Float]
+        def embed_async: (String text, ?Concurrency::CancellationToken? cancellation_token, ?timeout: Numeric?) -> Task[Array[Float]]
+      end
+    end
+  end
+  module Testing
+    module PersistenceContract
+      SHARED_EXAMPLES: Array[String]
+    end
+  end
+
+end

data/sig/phronomy/llm_adapter.rbs

@@ -0,0 +1,11 @@
+module Phronomy
+  module LLMAdapter
+    class Base
+      def complete: (untyped chat, String? message, ?config: Hash[untyped, untyped]) -> untyped
+      def stream: (untyped chat, String? message, ?config: Hash[untyped, untyped]) { (untyped chunk) -> void } -> untyped
+    end
+
+    class RubyLLM < Base
+    end
+  end
+end

data/sig/phronomy/persistence.rbs

@@ -0,0 +1,70 @@
+module Phronomy
+  interface _ContentRepository
+    def put: (String bytes, canonicalization_version: untyped) -> String
+    def fetch: (String content_id) -> String
+    def exist?: (String content_id) -> bool
+  end
+
+  interface _AgentRepository
+    def create: (untyped root) -> untyped
+    def load: (String agent_id) -> untyped
+    def save: (String agent_id, expected_revision: Integer, root: untyped) -> untyped
+    def delete: (String agent_id) -> untyped
+  end
+
+  interface _JournalRepository
+    def append: (String agent_id, expected_position: Integer, records: Array[untyped]) -> Array[untyped]
+    def read: (String agent_id, ?after: Integer?, ?limit: Integer?) -> Array[untyped]
+    def head: (String agent_id) -> Integer
+    def delete: (String agent_id) -> untyped
+  end
+
+  interface _ExecutionRepository
+    def create_active: (untyped execution) -> untyped
+    def load: (String execution_id) -> untyped
+    def save: (String execution_id, expected_revision: Integer, execution: untyped) -> untyped
+    def list_active: (String agent_id) -> Array[untyped]
+    def delete: (String execution_id) -> untyped
+    def delete_for_agent: (String agent_id) -> untyped
+    def assert_idle!: (String agent_id) -> untyped
+  end
+
+  interface _WorkflowStateRepository
+    def load: (String thread_id) -> Hash[untyped, untyped]?
+    def save: (String thread_id, expected_revision: Integer?, snapshot: Hash[untyped, untyped]) -> untyped
+    def delete: (String thread_id, expected_revision: Integer) -> untyped
+  end
+
+  interface _PersistenceTransactionView
+    def contents: () -> _ContentRepository
+    def agents: () -> _AgentRepository
+    def journals: () -> _JournalRepository
+    def executions: () -> _ExecutionRepository
+    def workflow_states: () -> _WorkflowStateRepository
+    def assert_agent_watermark!: (agent_id: String, agent_revision: Integer, journal_position: Integer) -> true
+  end
+
+  class Persistence
+    class ConflictError < Phronomy::Error
+    end
+    class NotFoundError < Phronomy::Error
+    end
+    class UnsupportedBackendError < Phronomy::Error
+    end
+    class SerializationError < Phronomy::Error
+    end
+
+    REQUIRED_CAPABILITIES: Hash[Symbol, bool]
+
+    attr_reader contents: _ContentRepository
+    attr_reader agents: _AgentRepository
+    attr_reader journals: _JournalRepository
+    attr_reader executions: _ExecutionRepository
+    attr_reader workflow_states: _WorkflowStateRepository
+
+    def initialize: (contents: _ContentRepository, agents: _AgentRepository, journals: _JournalRepository, executions: _ExecutionRepository, workflow_states: _WorkflowStateRepository) -> void
+    def capabilities: () -> Hash[Symbol, bool]
+    def transaction: () { (_PersistenceTransactionView) -> untyped } -> untyped
+    def assert_agent_watermark!: (agent_id: String, agent_revision: Integer, journal_position: Integer) -> true
+  end
+end

data/sig/phronomy/runtime.rbs

@@ -0,0 +1,43 @@
+module Phronomy
+  class Task[A]
+    attr_reader name: String?
+    attr_reader parent: Task[untyped]?
+
+    def status: () -> (:pending | :completed | :failed | :cancelled)
+    def done?: () -> bool
+    def alive?: () -> bool
+    def wait_result: (?timeout: Numeric?) -> A
+    def on_complete: () { (A?, Exception?) -> void } -> self
+    def map: [B] () { (A) -> B } -> Task[B]
+  end
+
+  module Concurrency
+    class CancellationToken
+      def self.timeout_after: (Numeric seconds) -> CancellationToken
+      def initialize: (?monotonic_deadline: Float?) -> void
+      def remaining_monotonic_seconds: () -> Float?
+      def on_cancel: () { () -> void } -> self
+      def cancel!: () -> self
+      def cancelled?: () -> bool
+      def raise_if_cancelled!: (?String message) -> nil
+    end
+  end
+end
+
+module Phronomy
+  class InvocationContext
+    attr_reader thread_id: String?
+    attr_reader session_id: String?
+    attr_reader user_id: String?
+    attr_reader cancellation_token: Concurrency::CancellationToken?
+    attr_reader deadline: untyped
+    attr_reader tracer_span: untyped
+    attr_reader token_budget: Integer?
+    attr_reader approval_policy: untyped
+    attr_reader redaction_policy: untyped
+    attr_reader task_id: String?
+    attr_reader parent_task_id: String?
+
+    def initialize: (?thread_id: String?, ?session_id: String?, ?user_id: String?, ?cancellation_token: Concurrency::CancellationToken?, ?deadline: untyped, ?tracer_span: untyped, ?token_budget: Integer?, ?approval_policy: untyped, ?redaction_policy: untyped, ?task_id: String?, ?parent_task_id: String?) -> void
+  end
+end

data/sig/phronomy/tool.rbs

@@ -0,0 +1,39 @@
+module Phronomy
+  module Tool
+    class Base
+      def self.tool_name: (?untyped value) -> String?
+      def self.description: (?String text) -> String?
+      def self.desc: (?String text) -> String?
+      def self.parameters: () -> Hash[untyped, untyped]
+      def self.params_schema_definition: () -> untyped
+      def self.provider_params: () -> Hash[untyped, untyped]
+      def self.param: (untyped name, ?enum: untyped, ?properties: untyped, **untyped options) -> untyped
+      def self.execution_mode: (?(:cooperative | :offloaded) value) -> (:cooperative | :offloaded)
+      def self.on_error: (?(:raise | :suppress) behavior) -> (:raise | :suppress)
+      def self.on_schema_error: (?untyped behavior) -> untyped
+      def self.requires_approval: (?untyped value) { () -> untyped } -> untyped
+                               | (?untyped value) -> untyped
+      def self.approval_facts: () { (untyped, untyped) -> untyped } -> untyped
+                             | () -> untyped
+      def self.redact_params: (*untyped names) -> Array[Symbol]
+      def self.max_result_size: (?untyped value) -> untyped
+
+      def name: () -> String
+      def params_schema: () -> untyped
+      def call: (Hash[untyped, untyped] args, ?cancellation_token: Concurrency::CancellationToken?) -> untyped
+      def call_async: (Hash[untyped, untyped] args, ?cancellation_token: Concurrency::CancellationToken?, ?config: Hash[untyped, untyped]) -> Task[untyped]
+      def requires_approval?: () -> untyped
+      def tool_origin: () -> Symbol
+      def approval_metadata: () -> Hash[untyped, untyped]
+      def execute: (**untyped args) -> untyped
+    end
+  end
+
+  module Agent
+    module Context
+      module Capability
+        class Base = ::Phronomy::Tool::Base
+      end
+    end
+  end
+end

data/sig/phronomy/workflow.rbs

@@ -0,0 +1,30 @@
+module Phronomy
+  module WorkflowContext
+    def phase: () -> Symbol
+    def halted?: () -> bool
+    def thread_id: () -> String?
+    def merge: (Hash[Symbol, untyped] updates) -> self
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+
+  class Workflow
+    def self.define: (Class context_class, ?persistence: Persistence?) { () -> void } -> Workflow
+
+    def invoke: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) -> untyped
+    def invoke_async: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) -> Task[untyped]
+    def stream: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) { (untyped) -> void } -> untyped
+    def resume: (state: untyped, ?input: untyped) -> untyped
+    def send_event: (state: untyped, event: Symbol, ?input: untyped) -> untyped
+    def signal: (thread_id: String, event: Symbol, ?payload: untyped) -> bool
+
+    class Builder
+      def initial: (Symbol state_name) -> untyped
+      def state: (Symbol name, ?action: untyped) -> untyped
+      def entry: (Symbol name, untyped callable) -> untyped
+      def exit: (Symbol name, untyped callable) -> untyped
+      def wait_state: (Symbol name) -> untyped
+      def transition: (from: Symbol, to: Symbol, ?guard: untyped, ?on: Symbol?, ?action: untyped) -> untyped
+      def build: () -> Workflow
+    end
+  end
+end

data/sig/phronomy.rbs

@@ -1,4 +1,52 @@
 module Phronomy
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+  class Error < StandardError
+  end
+
+  class ParseError < Error
+  end
+
+  class RecursionLimitError < Error
+  end
+
+  class ToolError < Error
+  end
+
+  class TimeoutError < Error
+  end
+
+  class ConfigurationError < Error
+  end
+
+  class TransportError < Error
+  end
+
+  class RateLimitError < TransportError
+  end
+
+  class AuthenticationError < TransportError
+  end
+
+  class ContextLengthError < Error
+  end
+
+  class CancellationError < Error
+  end
+
+  class EventLoopReentrancyError < Error
+  end
+
+  class PoolShutdownError < Error
+  end
+
+  class BackpressureError < Error
+  end
+
+  class Configuration
+    attr_accessor llm_adapter: LLMAdapter::Base
+  end
+
+  def self.configuration: () -> Configuration
+  def self.configure: () { (Configuration) -> void } -> void
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.20.0
+  version: 0.22.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-16 00:00:00.000000000 Z
+date: 2026-08-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -120,6 +120,7 @@ files:
 - docs/decisions/012-canonical-execution-log-and-context-policy.md
 - docs/decisions/013-journal-backed-knowledge-as-context-candidates.md
 - docs/decisions/014-unified-persistence-durable-state.md
+- docs/decisions/015-tool-public-facade-and-rbs-boundary.md
 - docs/features.md
 - docs/getting-started.md
 - docs/mcp-client.md
@@ -259,6 +260,8 @@ files:
 - lib/phronomy/testing/persistence_contract/an_agent_repository.rb
 - lib/phronomy/testing/persistence_contract/an_execution_repository.rb
 - lib/phronomy/token_usage.rb
+- lib/phronomy/tool.rb
+- lib/phronomy/tool/base.rb
 - lib/phronomy/tools/agent.rb
 - lib/phronomy/tools/mcp.rb
 - lib/phronomy/tools/vector_search.rb
@@ -298,6 +301,13 @@ files:
 - scripts/migrate_spec_inline_pass3.rb
 - scripts/run_mutation.sh
 - sig/phronomy.rbs
+- sig/phronomy/agent.rbs
+- sig/phronomy/extensions.rbs
+- sig/phronomy/llm_adapter.rbs
+- sig/phronomy/persistence.rbs
+- sig/phronomy/runtime.rbs
+- sig/phronomy/tool.rbs
+- sig/phronomy/workflow.rbs
 homepage: https://github.com/Raizo-TCS/phronomy
 licenses:
 - MIT