phronomy 0.5.4 → 0.7.0

data/docs/decisions/002-workflow-context-immutability.md

@@ -0,0 +1,42 @@
+# ADR-002: WorkflowContext#merge Returns a New Instance (Immutability Contract)
+
+## Status
+
+Accepted
+
+## Context
+
+`WorkflowContext` carries the shared state that flows through workflow nodes.
+Two design options existed:
+
+1. **Mutable**: nodes modify state in-place; the same object is passed through
+   the entire graph.
+2. **Immutable**: `merge` always returns a new instance; nodes return the new
+   state rather than mutating the old one.
+
+Mutable state is simpler to implement but creates hazards: parallel node
+execution (current or future) would require locking to prevent races. It also
+makes debugging harder — it is difficult to track where a field was last changed
+without snapshotting state at each step.
+
+## Decision
+
+`WorkflowContext#merge` (and all field writers) return a new `WorkflowContext`
+instance. Nodes receive a state object and must return (or yield) a new state
+object. The framework replaces the current state with the returned value.
+
+## Consequences
+
+**Positive:**
+- Future parallel node execution (fork/join) can safely hand each branch a
+  separate copy of the state without defensive copying at the call site.
+- Checkpoint/replay for `interrupt_before`/`interrupt_after` is straightforward
+  — a checkpoint is just a serialized state value.
+- Accidental mutation by a node does not silently corrupt shared state.
+
+**Negative / Tradeoffs:**
+- A small allocation overhead per `merge` call. Acceptable at typical workflow
+  depth (tens of nodes, not millions).
+- Node authors must remember to return the new state; forgetting to do so
+  discards the update silently. (Future work: frozen state objects or
+  a strict return type could catch this at dev time.)

data/docs/decisions/003-event-loop-singleton.md

@@ -0,0 +1,48 @@
+# ADR-003: EventLoop Is a Process-Wide Singleton
+
+## Status
+
+Accepted
+
+## Context
+
+The `EventLoop` routes asynchronous events (tool results, child completions,
+timeouts) between concurrent agent invocations. The design choices were:
+
+1. **Per-agent event loop**: each `Agent::Base#invoke` owns its own event loop
+   thread.
+2. **Per-`Orchestrator` event loop**: one loop per orchestrator instance.
+3. **Process-wide singleton**: one `EventLoop` serves all concurrent
+   invocations in the process.
+
+Per-agent loops would require creating and tearing down threads on every
+`invoke` call. In Rails / Puma environments where multiple requests invoke
+agents concurrently, this creates significant thread churn. Per-orchestrator
+loops are better, but `Orchestrator` instances are often short-lived, and
+coordinating parent-child event delivery across loop boundaries is complex.
+
+Ruby's GVL means true parallelism is limited to I/O-bound work, so the
+throughput gain from per-agent loops would be minimal. A singleton loop with a
+thread-safe queue is simpler and avoids inter-loop coordination.
+
+## Decision
+
+`Phronomy::EventLoop` is implemented as a process-wide singleton that runs on a
+dedicated background thread. Agents post events to a shared `Queue`; the loop
+dispatches them to registered handlers (identified by `target_id`).
+
+## Consequences
+
+**Positive:**
+- Single background thread; no thread churn per invocation.
+- Cross-agent event delivery (e.g., child-to-parent completion) is natural
+  because all agents share the same loop.
+- Startup/shutdown logic is simple (one thread to manage).
+
+**Negative / Tradeoffs:**
+- The singleton is global mutable state; tests must call
+  `Phronomy.reset_runtime!` between examples.
+- A bug in the event loop (or a blocking handler) affects all concurrent
+  invocations, not just one agent.
+- In multi-process environments (e.g., Sidekiq workers), each process has its
+  own singleton — cross-process event delivery is not supported.

data/docs/decisions/004-invoke-timeout-is-not-cancellation.md

@@ -0,0 +1,51 @@
+# ADR-004: invoke_timeout Is a Wait Timeout, Not a Cancellation Signal
+
+## Status
+
+Accepted
+
+## Context
+
+`Agent::Base` exposes `invoke_timeout N` as a class-level DSL. When an invocation
+exceeds the timeout, `Phronomy::TimeoutError` is raised to the caller.
+
+The question is: should the timeout also stop the agent's background work?
+
+Ruby's `Timeout.timeout` / `Thread#kill` can interrupt a running thread, but
+doing so is unsafe: it can leave mutexes locked, database connections in a broken
+state, and external API calls mid-flight without cleanup. `Thread#raise` has the
+same hazards because it can interrupt anywhere inside a `rescue`/`ensure` block.
+
+Cooperative cancellation (checking a shared flag periodically) is safe but
+requires every tool, every LLM call, and every framework-internal loop to
+participate — a significant API surface change.
+
+## Decision
+
+`invoke_timeout` is a **wait timeout only**. When the deadline is reached:
+
+- `TimeoutError` is raised in the calling thread.
+- The agent's background thread continues running until it either completes
+  normally or is garbage-collected when the process ends.
+- No cancellation signal is sent to the agent.
+
+This is explicitly documented in the README and in the DSL source.
+
+A proper cooperative cancellation mechanism is tracked in Issue #216
+(`CancellationToken`), which is a separate feature requiring agent, tool, and
+transport layer participation.
+
+## Consequences
+
+**Positive:**
+- No risk of leaving shared resources (DB connections, mutexes, sockets) in a
+  broken state due to forced thread interruption.
+- Implementation is simple: `Timeout.timeout` on the calling side only.
+- The contract is explicit and predictable.
+
+**Negative / Tradeoffs:**
+- Background threads may continue consuming resources (LLM API quota, etc.)
+  after the caller has given up.
+- Users who expect "cancel" semantics from a timeout will be surprised.
+- Proper cancellation requires the `CancellationToken` feature (#216), which
+  has not yet been implemented.

data/docs/decisions/005-static-knowledge-class-level-cache.md

@@ -0,0 +1,45 @@
+# ADR-005: static_knowledge Chunks Are Cached at the Class Level
+
+## Status
+
+Accepted
+
+## Context
+
+`Agent::Base` supports `static_knowledge` — a list of `KnowledgeSource` objects
+whose content is prepended to the system prompt on every invocation. Sources
+declared as `static?` (e.g., `StaticKnowledge`) return content that never
+changes at runtime.
+
+Two caching strategies were considered:
+
+1. **Instance-level cache**: each agent instance fetches and caches static chunks
+   after first `invoke`.
+2. **Class-level cache**: static chunks are fetched once per class and shared
+   across all instances.
+
+If agents are short-lived (created per-request), instance-level caching
+provides no benefit — the cache is thrown away with the instance. A class-level
+cache persists across request boundaries and is shared by all instances of the
+same agent class, giving the same hit rate with less overhead.
+
+## Decision
+
+`static_knowledge` chunks from sources that return `static? == true` are
+memoized in a class-level instance variable (`@_static_knowledge_cache`).
+Non-static sources (e.g., `EntityKnowledge`, `RAGKnowledge`) are always
+re-fetched on each invocation because their content depends on runtime state.
+
+## Consequences
+
+**Positive:**
+- Eliminates redundant fetches for read-only knowledge bases in request-per-
+  agent patterns.
+- Memory is shared: all instances of a class point to the same chunk array.
+
+**Negative / Tradeoffs:**
+- If the underlying file or data changes while the process is running, the cache
+  serves stale content. Applications that need live refresh must use a
+  non-static knowledge source.
+- In tests, the cache must be cleared between examples. `Phronomy.reset_runtime!`
+  handles this.

data/docs/decisions/006-no-built-in-guardrails.md

@@ -0,0 +1,48 @@
+# ADR-006: Built-in Guardrail Implementations Are Not Shipped
+
+## Status
+
+Accepted
+
+## Context
+
+Phronomy provides `Guardrail::InputGuardrail` and `Guardrail::OutputGuardrail`
+as base classes. The question is whether to ship a library of built-in
+implementations (e.g., prompt injection detector, PII scanner, toxic content
+filter, word-count limit).
+
+Arguments for built-ins:
+- Lower barrier to entry; users get safety out of the box.
+- Consistent quality baseline across applications.
+
+Arguments against:
+- Guardrail correctness is highly domain-specific. A PII pattern for US Social
+  Security Numbers is irrelevant to a Japanese-language application.
+- Prompt injection patterns evolve rapidly; a built-in detector would require
+  frequent updates and could give false confidence.
+- Shipping third-party detection libraries (NLP, regex banks) as hard
+  dependencies increases gem weight and potential supply-chain risk.
+- The guardrail interface is intentionally minimal (`check(input)` / `fail!`).
+  Custom implementations are one-class affairs.
+
+## Decision
+
+Phronomy ships no built-in guardrail implementations. The framework provides:
+
+1. `Guardrail::InputGuardrail` and `Guardrail::OutputGuardrail` base classes
+   with `check` and `fail!` hooks.
+2. Documentation and examples showing how to implement custom guardrails.
+
+Users are responsible for implementing domain-specific guardrail logic.
+
+## Consequences
+
+**Positive:**
+- No false sense of security from a generic built-in that does not match the
+  application's actual threat model.
+- Gem remains dependency-light.
+- The interface is stable regardless of how the threat landscape evolves.
+
+**Negative / Tradeoffs:**
+- Users must implement their own guardrails from scratch. Providing a cookbook
+  of example patterns in the README partially mitigates this.

data/docs/decisions/007-mcp-is-beta-stability.md

@@ -0,0 +1,51 @@
+# ADR-007: MCP Tool Support Is Classified as Beta Stability
+
+## Status
+
+Accepted
+
+## Context
+
+Phronomy's `McpTool` integrates with the Model Context Protocol (MCP), allowing
+agents to call tools exposed by external MCP servers over stdio or HTTP. The
+protocol specification is still evolving (as of 2025), and the surface area of
+the integration is large:
+
+- Two transports: `StdioTransport` and `HttpTransport`
+- JSON-RPC 2.0 framing, capability negotiation, tool listing, tool invocation
+- Custom authentication headers, environment forwarding, startup timeouts
+
+The phronomy README stability table uses three tiers: **Stable**, **Beta**, and
+**Experimental**. The distinction matters because:
+
+- **Stable** APIs are covered by the public API compatibility snapshot (#210)
+  and breaking changes require a major version bump.
+- **Beta** APIs can change between minor versions with a CHANGELOG entry.
+- **Experimental** APIs can change between patch versions without notice.
+
+Classifying MCP as Stable would lock in the current API before the protocol and
+integration have been exercised in production at scale. Classifying it as
+Experimental would be too conservative — the API is intentionally designed and
+documented.
+
+## Decision
+
+`McpTool` and its transport classes (`StdioTransport`, `HttpTransport`) are
+classified as **Beta** in the README stability table and in YARD documentation.
+
+This signals:
+- The interface is intentional and useful but may change as MCP specification
+  and real-world usage reveal gaps.
+- Users should pin minor versions when using MCP in production.
+
+## Consequences
+
+**Positive:**
+- Honest representation of the API maturity.
+- Allows breaking changes (e.g., richer error types, capability negotiation
+  changes) between minor versions without a major bump.
+
+**Negative / Tradeoffs:**
+- Some users may avoid a Beta-labeled feature in production. Documentation
+  should clarify that "Beta" reflects protocol evolution risk, not
+  implementation quality.

data/docs/decisions/008-orchestrator-uses-os-threads.md

@@ -0,0 +1,52 @@
+# ADR-008: Orchestrator Uses OS Threads for Parallel Dispatch
+
+## Status
+
+Accepted
+
+## Context
+
+`Agent::Orchestrator#dispatch_parallel` runs multiple sub-agent invocations
+concurrently. The Ruby concurrency primitives available are:
+
+1. **OS threads** (`Thread`): true OS-level threads, subject to Ruby's GVL for
+   CPU-bound work, but I/O-bound work (LLM API calls, tool HTTP requests)
+   releases the GVL and runs in parallel.
+2. **Ractors**: actor-model isolation, no shared mutable state between Ractors.
+   True parallel for CPU-bound work but requires strict object isolation.
+3. **Fibers / async**: cooperative concurrency via Fiber scheduler (e.g.,
+   `async` gem). Non-blocking I/O without multiple threads.
+4. **`concurrent-ruby` thread pool**: managed pool of OS threads.
+
+LLM calls and tool invocations are overwhelmingly I/O-bound (HTTP requests).
+Under the GVL, OS threads are sufficient to achieve meaningful parallelism for
+these workloads. Ractors require that all objects passed between them are
+shareable, which is incompatible with RubyLLM's mutable chat objects and
+`WorkflowContext` instances without significant refactoring.
+
+Fibers require an async-compatible HTTP library stack throughout (RubyLLM,
+Faraday, etc.), which is not guaranteed today.
+
+## Decision
+
+`dispatch_parallel` spawns one OS thread per task using Ruby's `Thread.new`.
+A `max_concurrency:` cap (default: unlimited) uses a `Mutex`-guarded counter to
+limit the number of simultaneously active threads when specified.
+
+## Consequences
+
+**Positive:**
+- Transparent parallelism for I/O-bound LLM/tool calls with no dependency
+  changes.
+- Compatible with all Ruby versions in the support matrix (3.2, 3.3, 3.4, head).
+- Simple to reason about: each task is an independent thread; results are
+  collected in input order.
+
+**Negative / Tradeoffs:**
+- CPU-bound work inside agents does not benefit from true parallelism due to
+  the GVL. (In practice, agents are almost always I/O-bound.)
+- Spawning many threads simultaneously (no `max_concurrency:`) can exhaust
+  system thread limits under high load. Users should set `max_concurrency:` for
+  large fan-outs.
+- Ractor-based isolation (if ever needed for security sandboxing) would require
+  significant API changes to `WorkflowContext` and RubyLLM integration.

data/docs/decisions/009-state-store-abstraction.md

@@ -0,0 +1,141 @@
+# ADR 009: StateStore Abstraction for Workflow Persistence
+
+**Status**: Accepted  
+**Date**: 2025-01  
+**Issue**: [#250](https://github.com/Raizo-TCS/phronomy/issues/250)
+
+---
+
+## Context
+
+`Phronomy::WorkflowContext` stores execution state in a plain Ruby object that lives only
+in the process heap for the duration of a single `invoke` call. This is intentional for
+simple, stateless pipelines but creates three gaps:
+
+1. **Process restart** destroys all in-flight workflow state. Long-running workflows (approval
+   pipelines, human-in-the-loop, async batch jobs) cannot survive a deploy or crash.
+2. **Multi-process fan-out** is impossible when all state is local. Horizontally-scaled
+   workers cannot hand off an in-progress workflow to a sibling process.
+3. **Debugging & auditability** — there is no canonical, queryable record of what a workflow
+   produced at each turn.
+
+The only persistence mechanism that existed before this ADR was the caller manually
+persisting the `WorkflowContext` object returned by `invoke` and passing it back to
+`send_event`. This is fragile and couples the caller to Phronomy internals.
+
+---
+
+## Decision
+
+Introduce a `StateStore` abstraction — a single, narrow interface that `WorkflowRunner`
+uses for all state reads and writes. Callers opt in by passing a `state_store:` argument
+to `Workflow.define` or by setting `Phronomy.configure { |c| c.state_store = … }`.
+
+### Interface
+
+```ruby
+# lib/phronomy/state_store/base.rb
+module Phronomy
+  module StateStore
+    class Base
+      def load(thread_id)          = raise NotImplementedError  # → Hash | nil
+      def save(thread_id, snapshot) = raise NotImplementedError  # → void
+      def delete(thread_id)        = raise NotImplementedError  # → void
+    end
+  end
+end
+```
+
+A **snapshot** is a plain `Hash` with two keys:
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `:fields` | `Hash` | Output of `context.to_h` — user-defined field values |
+| `:phase`  | `String` | `context.phase.to_s` — last recorded execution phase |
+
+### Built-in backends
+
+| Class | Dependency | Use case |
+|-------|-----------|---------|
+| `StateStore::InMemory` | none | Testing, single-process, default |
+| `StateStore::SQLite` | `sqlite3` gem | Simple production durability (not in scope) |
+| `StateStore::Redis` | `redis` gem | Multi-process, TTL support (not in scope) |
+
+This ADR covers only the interface contract and `InMemory`. SQLite and Redis backends
+are deferred to separate issues.
+
+### Integration with WorkflowRunner
+
+`WorkflowRunner` resolves the store in the following priority order:
+
+1. `config[:state_store]` passed per-invocation
+2. `state_store:` kwarg passed to `WorkflowRunner#initialize`
+3. `Phronomy.configuration.state_store`
+4. `nil` → no persistence (current default behaviour)
+
+On each `invoke` call that provides an explicit `thread_id`:
+
+```
+invoke(input, config: { thread_id: "t1" })
+  → load snapshot for "t1" (if store present)
+  → merge stored fields with input (input overrides stored values)
+  → run workflow from entry_point
+  → save final context snapshot for "t1"
+```
+
+On subsequent calls with the same `thread_id`, the stored fields are loaded as the
+initial context. The `phase` field in the snapshot is recorded but `invoke` always
+restarts from the entry point — the stored phase is informational. To resume a halted
+workflow at a specific named event, callers use `send_event`.
+
+---
+
+## Consequences
+
+### Positive
+
+- Pluggable backends: tests use `InMemory`; production uses `SQLite` or `Redis`.
+- Zero-change opt-out: when no store is configured, `WorkflowRunner` behaviour is
+  identical to the pre-ADR implementation (no reads, no writes).
+- `InMemory` replaces the implicit in-memory hash that previously lived only for the
+  duration of a single call: callers can now persist state across multiple `invoke`
+  calls in the same process without glue code.
+- Shared RSpec examples (`"a state store"`) enforce the contract for all backends.
+
+### Negative / Trade-offs
+
+- Snapshot serialization is the caller's responsibility for complex field types. Fields
+  that contain non-JSON-safe objects (e.g. `Proc`, `Symbol` keys) must serialize cleanly
+  via `to_h`. `InMemory` stores Ruby objects directly (no serialisation), so it does
+  not expose this issue during tests.
+- `invoke` always re-runs the workflow from the entry point — loading stored state does
+  NOT automatically resume a halted wait_state. Callers who want resume-from-halt
+  semantics must call `send_event` explicitly (as before).
+- The `:phase` field in the snapshot is currently informational (not used by `invoke`
+  to auto-resume). A future ADR may introduce auto-resume semantics.
+
+---
+
+## Alternatives Considered
+
+### A. Make InMemory the global default
+
+Set `Phronomy.configure { c.state_store = InMemory.new }` automatically on boot.
+Rejected: this would change the memory lifecycle of all workflows silently; existing
+tests relying on ephemeral state would accumulate in the default store indefinitely,
+and the store would become a slow memory leak in long-running processes.
+
+### B. Serialize snapshots to JSON at the InMemory layer
+
+Round-trip through JSON in `InMemory#save` to catch serialisation issues early.
+Rejected for this ADR: `InMemory` is intended as a zero-friction default for tests and
+local development. JSON round-tripping would penalise symbol keys (a common pattern in
+Ruby apps). The SQLite/Redis backends will enforce JSON round-tripping at their layer.
+
+### C. Auto-resume halted workflows in `invoke`
+
+When `invoke` finds a stored snapshot with `phase != "__end__"`, automatically call
+`send_event` with a synthetic `:resume` event.
+Rejected: the correct event to fire depends on the wait_state's declared external events,
+which may require named events (e.g. `:approve`, `:reject`). Inferring the right event
+automatically is ambiguous and would hide programmer errors.