phronomy 0.17.0 → 0.18.0

data/docs/getting-started.md

@@ -0,0 +1,351 @@
+# Getting started
+
+This guide contains the setup and introductory examples that were previously
+embedded in the repository README. The README remains the project entry point;
+this document carries the longer operational examples.
+
+## Install
+
+Add Phronomy to your Gemfile:
+
+```ruby
+gem "phronomy"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Phronomy uses RubyLLM for Large Language Model (LLM) access. Configure provider credentials and the
+transport retry/timeout policy on RubyLLM itself:
+
+```ruby
+RubyLLM.configure do |c|
+  c.openai_api_key = ENV["OPENAI_API_KEY"]
+  # c.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
+
+  c.request_timeout = 120
+  c.max_retries = 3
+  c.retry_interval = 0.1
+  c.retry_backoff_factor = 2
+  c.retry_interval_randomness = 0.5
+end
+```
+
+Phronomy does not add a second LLM transport timeout/retry layer on top of the
+configured adapter.
+
+## Optional dependencies
+
+Install only the backend gems required by your application:
+
+| Gem | Required for |
+|---|---|
+| `pgvector` | `Phronomy::VectorStore::Pgvector` |
+| `redis` | `Phronomy::VectorStore::RedisSearch` |
+| `opentelemetry-api` | `Phronomy::Tracing::OpenTelemetryTracer` |
+
+## Define a Tool and Agent
+
+```ruby
+class WebSearch < Phronomy::Agent::Context::Capability::Base
+  description "Search the web"
+  param :query, type: :string, desc: "Search query"
+
+  def execute(query:)
+    "Mock search result for: #{query}"
+  end
+end
+
+class ResearchAgent < Phronomy::Agent::Base
+  agent_definition id: "research-agent", version: 1
+  model "gpt-4o"
+  instructions "You are a research assistant. Use tools to answer questions."
+  tools(WebSearch => nil)
+  max_iterations 5
+end
+
+result = ResearchAgent.new.invoke("Research Ruby AI frameworks")
+puts result[:output]
+```
+
+Every concrete stateful Agent definition declares a stable definition ID and
+version. The definition identity is checked when persisted Agent state is loaded.
+
+## Stateful Agent persistence
+
+Phronomy Agents own their conversation history and persistent Knowledge. The
+application does not need to pass the previous `messages` array back into every
+invocation.
+
+```ruby
+persistence = Phronomy::Persistence::InMemory.new
+
+agent = ResearchAgent.create(
+  agent_id: "research-session-42",
+  knowledge: ["Customer tier: enterprise"],
+  persistence: persistence
+)
+
+agent.invoke("My name is Alice.")
+agent.add_knowledge("Customer locale: ja-JP")
+result = agent.invoke("What is my name?")
+
+puts result[:output]
+```
+
+Load the same Agent again when the same Persistence backend is available:
+
+```ruby
+agent = ResearchAgent.load(
+  "research-session-42",
+  persistence: persistence
+)
+
+agent.invoke("Continue our previous discussion.")
+```
+
+The active transcript and Knowledge views can be advanced independently without
+deleting the append-only canonical Journal:
+
+```ruby
+agent.clear_transcript!
+agent.clear_knowledge!
+agent.reset_context!
+```
+
+`purge!` is different: it permanently removes the Agent and persisted execution
+history from the configured Persistence backend.
+
+## Sync and async Agent APIs
+
+Use synchronous APIs at an external/top-level application boundary and async
+APIs when the caller must remain non-blocking.
+
+```ruby
+result = agent.invoke("Hello")
+
+task = agent.invoke_async("Hello")
+result = task.wait_result
+```
+
+`Task#wait_result` is for an external caller. Do not block EventLoop waiting for
+a Task that can only complete through that same EventLoop.
+
+Streaming follows the same split:
+
+```ruby
+agent.stream("Explain the design") do |event|
+  puts event.payload if event.type == :token
+end
+```
+
+```ruby
+task = agent.stream_async(
+  "Explain the design",
+  on_event: ->(event) { puts event.payload if event.type == :token }
+)
+```
+
+Streaming callbacks execute on EventLoop and therefore should return quickly.
+
+## Human-in-the-loop approval
+
+A Tool requiring approval can suspend an Agent invocation. Resume it with the
+approval request identifier returned by the suspension result.
+
+At a top-level synchronous boundary:
+
+```ruby
+result = agent.invoke("Perform the requested protected action")
+
+if result[:suspended]
+  request = result[:approval_request]
+  result = agent.approve(
+    result[:execution_id],
+    approval_request_id: request.id,
+    approved: true
+  )
+end
+```
+
+From an EventLoop callback, use `approve_async` rather than blocking EventLoop.
+
+## Workflow basics
+
+A Workflow is state-machine-driven and can halt at an explicit wait state:
+
+```ruby
+class ReviewContext
+  include Phronomy::WorkflowContext
+  field :draft,    type: :replace
+  field :feedback, type: :replace
+  field :approved, type: :replace, default: false
+end
+
+write_draft  = ->(state) { state.merge(draft: "Draft content") }
+review_draft = ->(state) { state.merge(feedback: "Feedback on: #{state.draft}") }
+
+workflow = Phronomy::Workflow.define(ReviewContext) do
+  initial :write
+  state :write, action: write_draft
+  state :review, action: review_draft
+  wait_state :awaiting_approval
+  state :finalize, action: ->(s) { s.merge(approved: true) }
+
+  transition from: :write, to: :review
+  transition from: :review, to: :awaiting_approval
+  transition from: :awaiting_approval, on: :approve, to: :finalize
+  transition from: :awaiting_approval, on: :reject, to: :write
+  transition from: :finalize, to: :__finish__
+end
+
+state = workflow.invoke({draft: ""}, config: {thread_id: "doc-1"})
+final = workflow.send_event(state: state, event: :approve)
+puts final.approved
+```
+
+Workflow entry and transition actions are synchronous Run-to-Completion
+callbacks. If a Workflow needs an Agent or another asynchronous lifecycle, start
+it asynchronously, return the Workflow context immediately, and deliver its
+completion later with `Workflow#signal`.
+
+```ruby
+class AnswerContext
+  include Phronomy::WorkflowContext
+
+  field :question, type: :replace, default: ""
+  field :answer,   type: :replace, default: nil
+  field :thread_id, type: :replace, default: nil
+end
+
+class ResearchAgent < Phronomy::Agent::Base
+  agent_definition id: "research-agent", version: 1
+  model "gpt-4o-mini"
+  instructions "Research the question and return a concise answer."
+end
+
+my_agent = ResearchAgent.new
+workflow = nil
+
+workflow = Phronomy::Workflow.define(AnswerContext) do
+  initial :asking
+  state :asking
+  state :done
+
+  entry :asking, ->(ctx) {
+    thread_id = ctx.thread_id
+
+    my_agent.invoke_async(
+      ctx.question,
+      on_event: ->(event) {
+        next unless event.type == :done
+
+        workflow.signal(
+          thread_id: thread_id,
+          event: :answer_ready,
+          payload: {answer: event.payload[:output]}
+        )
+      }
+    )
+
+    ctx
+  }
+
+  transition(
+    from: :asking,
+    on: :answer_ready,
+    to: :done,
+    action: ->(ctx, event) { ctx.merge(answer: event.payload[:answer]) }
+  )
+end
+```
+
+Returning a `Phronomy::Task` from a Workflow entry/transition action is not an
+implicit await mechanism and is rejected.
+
+## Agent as Tool
+
+Expose a child Agent using `Phronomy::Tools::Agent.from_agent` rather than calling
+a synchronous child Agent from a Tool worker:
+
+```ruby
+ResearchTool = Phronomy::Tools::Agent.from_agent(
+  ResearchAgent,
+  tool_name: "research",
+  description: "Delegate research to the research Agent"
+)
+
+class OrchestratorAgent < Phronomy::Agent::Base
+  agent_definition id: "orchestrator-agent", version: 1
+  model "gpt-4o"
+  instructions "Use the research Tool when research is required."
+  tools(ResearchTool => nil)
+end
+```
+
+Agent-backed Tools return control to EventLoop while the child lifecycle is
+waiting. They do not occupy an OffloadPool worker merely to wait for a child
+Agent result.
+
+## Filters
+
+Filters can transform or reject values at Agent boundaries:
+
+```ruby
+class NoCreditCardFilter < Phronomy::Filter::Base
+  def call(value, **_context)
+    block!("Credit card numbers are not allowed") if value.match?(/\d{4}-\d{4}-\d{4}-\d{4}/)
+    value
+  end
+end
+
+agent.add_input_filter(NoCreditCardFilter.new)
+```
+
+Phronomy includes `PromptInjectionFilter` as a baseline pattern filter. It is not
+a complete security policy for untrusted input.
+
+## Persistent Knowledge and per-call context
+
+Register durable Knowledge on the Agent:
+
+```ruby
+agent.add_knowledge(
+  "Customer locale: ja-JP",
+  metadata: {"origin" => "customer_profile"}
+)
+```
+
+Request-scoped context can instead be supplied through `before_llm_input` using
+`LLMInputPatch#segment_candidates`; those candidates enter Context Policy for the
+specific call and are not persisted to the Journal.
+
+## Model Context Protocol (MCP)
+
+Phronomy targets MCP 1.x through the official `mcp` gem:
+
+```ruby
+search_tool = Phronomy::Tools::Mcp.from_server(
+  "stdio://./mcp-server",
+  tool_name: "web_search"
+)
+
+begin
+  # use search_tool
+ensure
+  search_tool.close
+end
+```
+
+See [MCP client](mcp-client.md) for schema, error, cancellation, and lifecycle
+contracts.
+
+## Next steps
+
+- [Features and API stability](features.md)
+- [Runtime and concurrency](runtime-and-concurrency.md)
+- [Architecture decisions](decisions/)
+- [Migration guides](migrations/)

data/docs/migrations/0.15.md

@@ -0,0 +1,35 @@
+# Migration from 0.15-era execution-policy APIs
+
+This guide preserves the execution-policy migration information that previously
+lived in the top-level README. It is historical upgrade guidance; new code should
+follow the current contracts documented in
+[Runtime and concurrency](../runtime-and-concurrency.md).
+
+| Removed Phronomy setting/API | Replacement |
+|---|---|
+| `retry_policy` | RubyLLM transport retry, or explicit application orchestration |
+| `invoke_timeout` | `InvocationContext#deadline` or `cancellation_token` when the caller needs a root deadline |
+| `config[:llm_timeout]` | `RubyLLM.configure { |c| c.request_timeout = ... }` |
+| Tool `retry_on` | Tool/client-specific retry with explicit idempotency guarantees |
+| `config[:tool_timeout]` | Tool/client-native timeout |
+| `max_parallel_tools` | No replacement; `parallel_tool_execution` remains an on/off mode |
+| `InvocationContext#provider_limits` | Configure the provider client directly |
+| `stream_queue_max_size` | No replacement; the shared EventLoop queue is unbounded by design. Monitor `Metrics.snapshot[:event_loop_queue_depth]` instead |
+
+## Timeout ownership
+
+Phronomy owns logical lifecycle deadlines and cooperative cancellation. Provider,
+HTTP, database, MCP, and other transport-level timeouts belong to the relevant
+client library.
+
+A caller-defined root deadline can be represented through `InvocationContext` or
+a cancellation token, but that does not replace operation-native socket/request/
+statement timeouts for a synchronous call already in progress.
+
+## Retry ownership
+
+Automatic replay of an entire Agent invocation is not a generic framework retry
+policy. Configure transport retry on RubyLLM or another adapter, and implement
+application orchestration explicitly when replay is semantically safe.
+
+See [`CHANGELOG.md`](../../CHANGELOG.md) for the release-by-release history.

data/docs/migrations/0.16.md

@@ -0,0 +1,43 @@
+# 0.16 cleanup migration
+
+This guide preserves the compatibility cleanup information that previously lived
+in the top-level README. It is intended for applications upgrading older Phronomy
+code; new applications should use the current documentation directly.
+
+| Removed API | Current contract |
+|---|---|
+| `context_overhead` | Manifest-first assembly budgets actual mandatory + selected content |
+| Tool `on_error :return_empty` | Use `:raise` or `:suppress` |
+| `dispatch_parallel(..., force_kill:)` / `fan_out(..., force_kill:)` | Cooperative cancellation; no force-kill switch |
+| `runtime_backend` | Removed. Phronomy has one control model: EventLoop/FSMSession for lifecycle coordination and OffloadPool for synchronous work that must stay off EventLoop |
+| `Runtime.instance = ...` | Runtime replacement is test/internal infrastructure, not a public setter |
+| `Runtime#spawn` / `TaskGroup` | Removed. Start framework async work through domain async APIs (`invoke_async`, Workflow events, ToolInvocation, FanOut) |
+| `tools ToolA, ToolB` | Use `tools(ToolA => nil, ToolB => nil)` |
+| `CancellationToken.new(deadline: Time...)` | Use `CancellationToken.timeout_after(seconds)` for a lazy token deadline, or a Runtime-backed cancellation scope when callback delivery on deadline is required |
+| `StaticKnowledge` / `EntityKnowledge` / `Knowledge::Base` / `Phronomy::KnowledgeSource` | Register plain persistent Knowledge with `knowledge:` or `add_knowledge` |
+| `static_knowledge*` class APIs | Persistent Knowledge belongs to Agent instances and is Journal-backed |
+| `clear_memory!` | Use `clear_knowledge!`; conversation history is controlled independently with `clear_transcript!` |
+
+The legacy `build_context` / `LlmContextWindow::Assembler` extension path is no
+longer an active API. Stateful Agent input is assembled through the canonical:
+
+```text
+Journal
+  → Context candidates
+  → Context Policy
+  → Large Language Model (LLM) Input Manifest
+  → runtime projection
+```
+
+## Concurrency model
+
+The active concurrency model is EventLoop/FSMSession for logical lifecycle
+coordination plus OffloadPool for synchronous work that cannot run on EventLoop.
+There is no configurable runtime backend and no generic framework task-spawn
+backend.
+
+For the current design, see
+[Runtime and concurrency](../runtime-and-concurrency.md) and
+[ADR-010](../decisions/010-cooperative-first-concurrency.md).
+
+See [`CHANGELOG.md`](../../CHANGELOG.md) for release details.

data/docs/runtime-and-concurrency.md

@@ -0,0 +1,258 @@
+# Runtime and concurrency
+
+Phronomy uses an **EventLoop / FSMSession first** architecture for framework
+lifecycle coordination. `FSMSession` is the framework finite-state-machine session
+used to represent explicit lifecycle state and events. A `Task` is a completion
+handle, not an execution backend. Synchronous work that must stay off EventLoop is isolated in the bounded
+`OffloadPool`.
+
+For the design rationale, see Architecture Decision Record (ADR)
+[ADR-010: EventLoop / FSMSession First Concurrency](decisions/010-cooperative-first-concurrency.md).
+
+## Runtime model
+
+```text
+Runtime
+├─ EventLoop (one control-plane operating-system Thread)
+│  └─ FSMSession
+│     ├─ Agent
+│     ├─ Workflow
+│     ├─ ToolInvocation
+│     └─ MultiAgent fan-out
+├─ OffloadPool (bounded operating-system Threads)
+│  ├─ blocking input/output (I/O)
+│  ├─ central-processing-unit (CPU)-bound synchronous work
+│  └─ other long synchronous work
+├─ named OffloadPools
+└─ EventLoop-driven timers
+
+Task = completion handle
+```
+
+The framework does not allocate one operating-system Thread per logical Agent/Workflow/Tool
+lifecycle. Logical waits remain explicit states plus later EventLoop events.
+
+## Tool execution modes
+
+Phronomy exposes two execution modes for capabilities:
+
+- `:cooperative` — short EventLoop-safe work, or a specialized asynchronous Tool
+  that starts another Phronomy lifecycle and returns immediately.
+- `:offloaded` — synchronous work that must not run to completion on EventLoop.
+
+Phronomy does not classify application work into framework-level I/O/CPU/process
+execution modes. That workload classification and capacity planning belong to the
+application.
+
+A CPU-heavy operation may therefore use `:offloaded`, but thread offload does not
+remove CRuby Global VM Lock contention or physical CPU contention.
+
+## Logical waiting versus offload
+
+Do not offload a logical wait merely to make it asynchronous.
+
+Prohibited shape:
+
+```text
+OffloadPool worker
+  → child_agent.invoke_async
+  → wait_result
+```
+
+Correct shape:
+
+```text
+parent FSMSession
+  → start child lifecycle
+  → return immediately
+  → child settles
+  → post parent EventLoop event
+```
+
+This distinction prevents worker-slot starvation when many logical lifecycles are
+waiting at the same time.
+
+## Sync versus async application APIs
+
+| Calling context | Recommended approach |
+|---|---|
+| Top-level application code | `agent.invoke(...)` when blocking the caller is acceptable |
+| Top-level explicit async | `task = agent.invoke_async(...)`; optionally `task.wait_result` outside EventLoop |
+| Workflow entry/transition action | Start async work and continue through `Workflow#signal` |
+| EventLoop callback | Never block waiting for a Task that requires EventLoop progress |
+| Top-level streaming | `agent.stream(...)` |
+| Non-blocking streaming | `agent.stream_async(...)` |
+| Approval from EventLoop callback | `approve_async` |
+
+Blocking synchronous APIs reject EventLoop re-entry with
+`Phronomy::EventLoopReentrancyError` when waiting would stall the same EventLoop
+needed for progress.
+
+## Task
+
+`Phronomy::Task` is thread-free. It represents one terminal result:
+
+- completed value,
+- failure,
+- cancellation.
+
+`Task#wait_result(timeout:)` is a bridge for external synchronous callers. It is
+not the framework continuation mechanism.
+
+`Task#map` is application-level composition. A transformation exception settles
+the mapped Task as failed. This is different from independent notification
+callbacks, described below.
+
+## OffloadPool
+
+`OffloadPool` is a bounded worker pool for synchronous work that must not execute
+on EventLoop.
+
+Its guarantees include:
+
+- bounded worker count,
+- bounded queue depth,
+- queue backpressure,
+- operation-wide submit timeout/cancellation settlement,
+- abandoned-worker accounting,
+- runtime metrics,
+- shutdown/drain behavior.
+
+It does not guarantee CPU/I/O fairness or CPU isolation. Applications that need
+resource isolation can create named Runtime pools.
+
+### EventLoop queue admission
+
+Framework-owned EventLoop-origin submissions must not wait for a free worker
+queue slot. They use non-blocking admission (`on_full: :raise`) and route
+`BackpressureError` through the ordinary FSM/completion path.
+
+External management threads may choose a blocking admission policy when blocking
+the caller is acceptable.
+
+## PendingOperation and blocking_wait
+
+`OffloadPool#submit` returns a private `PendingOperation` immediately after queue
+admission.
+
+`PendingOperation#blocking_wait(timeout:)` is intentionally a **low-level
+synchronous bridge** for non-EventLoop callers such as tests and diagnostics.
+The timeout belongs only to that waiter:
+
+- it raises `TimeoutError` to that calling thread,
+- it does not settle the PendingOperation,
+- it does not cancel the submitted operation,
+- it does not mark the operation abandoned.
+
+There is no waiter-local `cancellation_token:` argument. Operation-wide
+cancellation belongs exclusively to `OffloadPool#submit(cancellation_token:)`.
+
+## Submit timeout and cancellation
+
+Submit-time timeout and submit cancellation settle the caller-facing operation.
+They do **not** asynchronously interrupt an already-running synchronous worker.
+
+### Before worker start
+
+If timeout/cancellation wins before execution starts:
+
+- the PendingOperation settles,
+- the submitted block does not run,
+- the operation is not counted as abandoned.
+
+### After worker start
+
+If timeout/cancellation wins after execution starts:
+
+- the PendingOperation settles immediately,
+- the operation is marked abandoned,
+- the worker is allowed to continue until its synchronous call returns,
+- the eventual worker result is discarded.
+
+Phronomy does not use `Thread#raise` to inject an exception into the worker.
+Application/library code that needs hard or transport-level deadlines should use
+its native timeout or, in the future, an appropriate process-isolation mechanism.
+
+### CancellationToken deadlines
+
+`CancellationToken.timeout_after(seconds)` uses a monotonic deadline.
+`cancelled?` becomes true after that deadline, but the token itself does not own a
+Thread.
+
+Components requiring callback delivery for a monotonic deadline must promote the
+deadline to explicit `cancel!` through the Runtime timer queue. OffloadPool does
+this for its submit cancellation token.
+
+`CancellationScope#deadline_in` is appropriate when the application needs a
+Runtime-timer-backed cancellation scope whose `on_cancel` subscribers are fired
+on expiry.
+
+## Independent notification callbacks
+
+Independent notification fan-out is fault-isolated.
+
+The rule applies to:
+
+- `CancellationToken#on_cancel`,
+- `Task#on_complete`,
+- `PendingOperation#on_complete`,
+- EventLoop timer callbacks.
+
+A `StandardError` from one independent subscriber is logged and does not suppress
+later subscribers.
+
+This is deliberately different from a continuation/transform such as
+`Task#map`: a transform exception is the outcome of the derived operation and is
+therefore propagated into that derived Task.
+
+Callback execution thread is not guaranteed for low-level completion handles.
+Callbacks must therefore be thread-safe and should complete quickly. Framework
+lifecycle code normally turns completion into an explicit EventLoop event rather
+than mutating unrelated logical state from a worker thread.
+
+## Abandoned-worker metrics
+
+Two metrics answer different operational questions:
+
+- `offload_pool_abandoned_total` — cumulative count of operations that became
+  abandoned after worker execution had started.
+- `offload_pool_abandoned_active` — current number of abandoned operations whose
+  synchronous workers still occupy pool capacity.
+
+Example:
+
+```text
+offload_pool_size             = 10
+offload_pool_active           = 10
+offload_pool_abandoned_active = 8
+offload_pool_abandoned_total  = 523
+offload_pool_queue_length     = 40
+```
+
+This means 10 workers are currently executing, 8 of them are doing work whose
+caller-facing result has already been abandoned, 523 abandonment events have
+occurred since process start, and 40 operations are queued.
+
+`Phronomy::Diagnostics.dump` exposes the same distinction for point-in-time
+troubleshooting.
+
+## EventLoop metrics
+
+`Phronomy::Metrics.snapshot` also reports EventLoop queue depth and lag values.
+Use these to distinguish worker saturation from EventLoop backlog/latency.
+
+## Shutdown
+
+`Runtime#shutdown` is terminal for that Runtime. It drains/terminates the
+Runtime-owned EventLoop, then closes pools and timers according to the Runtime
+shutdown contract.
+
+`Phronomy.reset_runtime!` exists primarily for test isolation and performs a real
+Runtime shutdown before resetting configuration.
+
+## Further design records
+
+The `docs/decisions/` directory contains the historical and current Architecture
+Decision Records (ADRs). When an older ADR is superseded, use the superseding
+section/current ADR as the active design contract and keep the earlier document
+as historical rationale.