phronomy 0.17.0 → 0.19.0

data/docs/getting-started.md

@@ -0,0 +1,387 @@
+# 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.")
+```
+
+`load` is the hydration boundary. While that Agent instance is live, the
+instance and its active `AgentExecutionActivation` own the current logical state.
+Phronomy persists snapshots at defined durability boundaries but does not reload
+mutable Agent/Execution/Journal state before every LLM or Tool step. A conflicting
+external durable write is surfaced as `Persistence::ConflictError` rather than
+silently merged into the live instance.
+
+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.
+Approval resume continues the same live Agent instance, Activation, and
+AgentInvocation; it is not an Agent reload boundary.
+
+## 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}") }
+
+persistence = Phronomy::Persistence::InMemory.new
+
+workflow = Phronomy::Workflow.define(
+  ReviewContext,
+  persistence: persistence
+) 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
+```
+
+`Persistence#workflow_states` is the durable Workflow repository. `thread_id`
+identifies the durable Workflow state and remains stable across resume. Each
+concrete Runtime execution receives a separate internal `fsm_session_id`; the
+application-level `session_id` remains ordinary caller/tracing metadata. Phronomy
+holds owner-aware admission for `thread_id` from durable load through terminal
+save so another local invocation cannot start from a stale snapshot while the
+current owner is still committing.
+
+A global Persistence backend can be configured when Agents and Workflows should
+share one durable backend:
+
+```ruby
+Phronomy.configure do |config|
+  config.persistence = persistence
+end
+```
+
+Agent `new`/`create` and Workflow definitions use the global backend when they do
+not inject an explicit `persistence:`. Workflow durability is fixed at the
+application/Workflow-definition boundary; there is no per-invocation backend
+switch.
+
+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/migrations/0.19.md

@@ -0,0 +1,148 @@
+# Migrating to 0.19: Unified Persistence
+
+This release removes the separate Workflow `StateStore` abstraction and uses
+`Phronomy::Persistence` for both Agent and Workflow durable state.
+
+## Workflow persistence
+
+Before:
+
+```ruby
+store = Phronomy::StateStore::InMemory.new
+
+workflow = Phronomy::Workflow.define(
+  MyContext,
+  state_store: store
+) do
+  # ...
+end
+```
+
+After:
+
+```ruby
+persistence = Phronomy::Persistence::InMemory.new
+
+workflow = Phronomy::Workflow.define(
+  MyContext,
+  persistence: persistence
+) do
+  # ...
+end
+```
+
+Global configuration changes from:
+
+```ruby
+Phronomy.configure do |config|
+  config.state_store = store
+end
+```
+
+to:
+
+```ruby
+Phronomy.configure do |config|
+  config.persistence = persistence
+end
+```
+
+The global backend is also used by Agent `new`/`create` calls that do not pass an
+explicit `persistence:`. An explicitly injected Agent or Workflow backend still
+takes precedence over the global setting.
+
+Per-invocation `config[:state_store]` is removed. Persistence is selected at the
+Workflow definition/application boundary rather than switched on individual
+invocations.
+
+`Phronomy::StateStore`, `StateStore::InMemory`, and the `state_store:` Workflow
+parameter are removed without compatibility aliases.
+
+## workflow_states repository
+
+Custom Persistence backends must provide `workflow_states` with revision-aware
+load/save/delete semantics:
+
+```ruby
+record = persistence.workflow_states.load("order-123")
+
+persistence.workflow_states.save(
+  "order-123",
+  expected_revision: record&.fetch(:revision),
+  snapshot: {
+    fields: workflow_context.to_h,
+    phase: workflow_context.phase.to_s
+  }
+)
+```
+
+A stale revision must raise `Phronomy::Persistence::ConflictError` rather than
+silently overwriting newer durable state.
+
+Custom durable backends must also implement the internal
+`Persistence#assert_agent_watermark!` precondition used before next-LLM durable
+barriers. It verifies the caller's Agent revision and Journal position without
+returning replacement mutable state; mismatches raise `ConflictError`. SQL
+backends should implement this check inside the same database transaction as the
+subsequent durable write.
+
+## Agent ownership and approval resume
+
+A live Agent instance now remains the logical owner of its mutable state after
+hydration. Phronomy no longer re-loads mutable AgentRoot/AgentExecution/Journal
+state at each LLM boundary just to obtain freshness.
+
+Approval resume continues the same live Agent/Activation and is performed through
+the Agent instance APIs:
+
+```ruby
+agent.approve(...)
+agent.approve_async(...)
+```
+
+The former class-level `MyAgent.approve(...)` / `MyAgent.approve_async(...)`
+routing APIs are removed. Applications that only have an `execution_id` should
+first resolve the current process's live owner:
+
+```ruby
+agent = MyAgent.live_for_execution(execution_id)
+
+agent.approve_async(
+  execution_id,
+  approval_request_id: request_id
+)
+```
+
+If the concrete Agent class is not known, use:
+
+```ruby
+agent = Phronomy::Agent::Base.live_for_execution(execution_id)
+```
+
+`live_for_execution` resolves the Runtime-local Activation and returns its
+existing Agent instance. It does not accept `persistence:` and does not load a new
+Agent or Execution from Persistence. If the live Activation has been lost (for
+example after process restart), it raises `ExecutionRehydrationRequiredError`
+until durable execution rehydration is implemented.
+
+`execution_id` is not an authorization token. HTTP/API applications must still
+verify that the caller is allowed to act on the resolved Agent and approval
+request.
+
+## Workflow identity
+
+Do not treat the following as the same identifier:
+
+- `session_id`: application/tracing session metadata;
+- `thread_id`: durable Workflow state identity;
+- `fsm_session_id`: private Runtime identity for one FSMSession execution.
+
+The last value is internal and is regenerated for each invoke/resume. Applications
+continue to use `thread_id` when calling `Workflow#signal`.
+
+Workflow admission for a durable `thread_id` is Runtime/process-local. Separate
+Ruby processes or service replicas can execute the same `thread_id` concurrently
+unless the application adds distributed coordination. `workflow_states` optimistic
+revisions can reject a stale terminal commit, but they do not prevent duplicate
+execution from starting or undo external side effects already performed before a
+conflict is detected.