igniter 0.5.0 → 0.5.1

data/docs/PATTERNS.md

@@ -1,411 +0,0 @@
-# Igniter Patterns
-
-This document collects recommended orchestration shapes that already have runnable examples in the repository.
-
-The goal is not to introduce new primitives, but to show how the existing DSL composes into readable contracts.
-
-## 1. Linear Derivation
-
-Use this when the flow is a straight dependency chain with no routing or fan-out.
-
-Example:
-
-- [basic_pricing.rb](/Users/alex/dev/hotfix/igniter/examples/basic_pricing.rb)
-
-Use:
-
-- pricing
-- totals
-- normalization pipelines
-- simple business formulas
-
-Shape:
-
-```ruby
-input :order_total
-input :country
-
-compute :vat_rate, with: :country do |country:|
-  country == "UA" ? 0.2 : 0.0
-end
-
-compute :gross_total, with: %i[order_total vat_rate] do |order_total:, vat_rate:|
-  order_total * (1 + vat_rate)
-end
-
-output :gross_total
-```
-
-## 2. Stage Composition
-
-Use this when one contract should orchestrate several bounded subgraphs.
-
-Examples:
-
-- [composition.rb](/Users/alex/dev/hotfix/igniter/examples/composition.rb)
-- [ringcentral_routing.rb](/Users/alex/dev/hotfix/igniter/examples/ringcentral_routing.rb)
-
-Use:
-
-- reusable business stages
-- transport shell + domain pipeline
-- larger flows with clear internal boundaries
-
-Guideline:
-
-- keep the parent contract thin
-- export child outputs explicitly
-- read child diagnostics from the child execution, not from the parent by default
-
-## 3. Scoped Domain Flow
-
-Use this when the graph is still one contract, but a flat node list becomes hard to read.
-
-Example:
-
-- [marketing_ergonomics.rb](/Users/alex/dev/hotfix/igniter/examples/marketing_ergonomics.rb)
-
-Use:
-
-- routing
-- validation
-- pricing
-- response shaping
-
-Shape:
-
-```ruby
-scope :routing do
-  map :trade_name, from: :service do |service:|
-    ...
-  end
-end
-
-namespace :validation do
-  guard :zip_supported, with: :zip_code, in: %w[60601 10001], message: "Unsupported zip"
-end
-```
-
-Guideline:
-
-- use `scope` and `namespace` for readability first
-- do not treat them as runtime boundaries
-
-## 4. Declarative Routing
-
-Use this when control flow depends on a selector value and should stay visible in the graph.
-
-Examples:
-
-- [ringcentral_routing.rb](/Users/alex/dev/hotfix/igniter/examples/ringcentral_routing.rb)
-
-Use:
-
-- vendor routing
-- status routing
-- country-specific flows
-- mode-specific processing
-
-Shape:
-
-```ruby
-branch :status_route, with: :telephony_status, inputs: {
-  extension_id: :extension_id,
-  telephony_status: :telephony_status,
-  active_calls: :active_calls
-} do
-  on "CallConnected", contract: CallConnectedContract
-  on "NoCall", contract: NoCallContract
-  default contract: UnknownStatusContract
-end
-```
-
-Guideline:
-
-- keep branch contracts on a shared input interface
-- let compile-time validation force interface consistency
-- use explicit `export` from the branch node
-
-## 5. Fan-Out With Stable Identity
-
-Use this when a node should run the same child contract for many item inputs.
-
-Examples:
-
-- [collection.rb](/Users/alex/dev/hotfix/igniter/examples/collection.rb)
-- [collection_partial_failure.rb](/Users/alex/dev/hotfix/igniter/examples/collection_partial_failure.rb)
-- [ringcentral_routing.rb](/Users/alex/dev/hotfix/igniter/examples/ringcentral_routing.rb)
-
-Use:
-
-- technicians
-- calls
-- locations
-- vendors
-- external records
-
-Shape:
-
-```ruby
-collection :technicians,
-  with: :technician_inputs,
-  each: TechnicianContract,
-  key: :technician_id,
-  mode: :collect
-```
-
-Guideline:
-
-- feed `collection` an array of item input hashes
-- choose a stable `key:`
-- keep item logic in the child contract, not in a giant parent `compute`
-
-## 6. Partial Failure Without Failing The Whole Execution
-
-Use `mode: :collect` when you want item-level failures surfaced, but not promoted to parent execution failure.
-
-Example:
-
-- [collection_partial_failure.rb](/Users/alex/dev/hotfix/igniter/examples/collection_partial_failure.rb)
-
-What to read:
-
-- `result.summary`
-- `result.items_summary`
-- `result.failed_items`
-- `contract.diagnostics_text`
-- `contract.diagnostics_markdown`
-
-Guideline:
-
-- parent execution can still be `succeeded`
-- collection summary may be `:partial_failure`
-- diagnostics should be read at collection level, not only at execution status level
-
-## 7. Nested Branch + Collection
-
-Use this when routing chooses a stage, and that stage performs fan-out or per-item routing.
-
-Example:
-
-- [ringcentral_routing.rb](/Users/alex/dev/hotfix/igniter/examples/ringcentral_routing.rb)
-
-Observed semantics:
-
-- parent execution records top-level `branch_selected`
-- collection item events belong to the selected child execution
-- child diagnostics is usually the best place to inspect collection status
-
-Guideline:
-
-- inspect parent audit for high-level routing
-- inspect child audit for item-level fan-out behavior
-
-## 8. Async Resume Flow
-
-Use this when a node cannot complete immediately and should suspend the execution.
-
-Example:
-
-- [async_store.rb](/Users/alex/dev/hotfix/igniter/examples/async_store.rb)
-
-Use:
-
-- external jobs
-- long-running enrichment
-- async pricing or classification
-
-Guideline:
-
-- model the slow step as a deferred node
-- resume with store-backed execution restore
-- keep downstream graph pure and resumable
-
-## 9. Distributed Event-Driven Contract
-
-Use this when execution spans multiple external triggers (webhooks, background jobs, async callbacks) that arrive at different times.
-
-Examples:
-
-- [distributed_server.rb](../examples/distributed_server.rb)
-
-Use:
-
-- multi-step approval workflows
-- job application pipelines
-- order fulfilment with external vendor callbacks
-- KYC / onboarding flows requiring background checks
-
-Key DSL:
-
-```ruby
-class ApplicationReviewWorkflow < Igniter::Contract
-  correlate_by :application_id       # uniquely identifies an in-flight execution
-
-  define do
-    input :application_id
-    input :applicant_name
-
-    # Execution suspends here until the named event is delivered
-    await :screening_result, event: :screening_completed
-    await :manager_review,   event: :manager_reviewed
-
-    compute :decision, depends_on: %i[screening_result manager_review] do |screening_result:, manager_review:|
-      manager_review[:approved] && screening_result[:passed] ? :hired : :rejected
-    end
-
-    output :decision
-  end
-end
-
-store = Igniter::Runtime::Stores::MemoryStore.new
-
-# Launch — suspends at the first await
-exec = ApplicationReviewWorkflow.start({ application_id: "app-1", applicant_name: "Alice" }, store: store)
-
-# Deliver events as they arrive (order does not matter)
-ApplicationReviewWorkflow.deliver_event(:screening_completed,
-  correlation: { application_id: "app-1" },
-  payload: { passed: true, score: 92 },
-  store: store)
-
-final = ApplicationReviewWorkflow.deliver_event(:manager_reviewed,
-  correlation: { application_id: "app-1" },
-  payload: { approved: true, note: "Strong candidate" },
-  store: store)
-
-final.result.decision  # => :hired
-```
-
-Guideline:
-
-- choose correlation keys that uniquely identify the in-flight instance
-- deliver events from any process; the store is the coordination layer
-- keep `await` payloads as plain hashes — they become the node's resolved value
-- `on_success` / `on_exit` callbacks fire when the final event resolves the graph
-
-## 10. Remote Contract Composition
-
-Use this when logic lives on a different service node and should be called over HTTP inside a graph.
-
-Examples:
-
-- [examples/server/](../examples/server/)
-
-Key DSL:
-
-```ruby
-require "igniter/server"
-
-# ── Service node (runs on port 4568) ─────────────────────────────────────────
-
-class ScoringContract < Igniter::Contract
-  define do
-    input :value
-    compute :score, depends_on: :value do |value:|
-      value * 1.5
-    end
-    output :score
-  end
-end
-
-Igniter::Server.configure do |c|
-  c.port = 4568
-  c.register "ScoringContract", ScoringContract
-end
-Igniter::Server.start  # blocking
-
-# ── Orchestrator node (runs on port 4567) ─────────────────────────────────────
-
-class PipelineContract < Igniter::Contract
-  define do
-    input :data
-    remote :scored,
-           contract: "ScoringContract",
-           node:     "http://localhost:4568",
-           inputs:   { value: :data }
-    output :scored
-  end
-end
-```
-
-Guideline:
-
-- validate the `node:` URL at compile time — the graph will reject bad URLs before runtime
-- keep remote contracts on a shared input interface so they are easy to swap
-- igniter-server is stateless over HTTP; use a shared store for distributed state
-- start the service with `bin/igniter-server start --port 4568 --require ./contracts.rb`
-
-## 11. LLM Compute Node
-
-Use this when a step requires a language model — classification, summarisation, drafting, or multi-step agent chains.
-
-Examples:
-
-- [llm/tool_use.rb](../examples/llm/tool_use.rb)
-
-Key DSL:
-
-```ruby
-require "igniter/integrations/llm"
-
-Igniter::LLM.configure do |c|
-  c.default_provider = :anthropic
-  c.anthropic.api_key = ENV.fetch("ANTHROPIC_API_KEY")
-end
-
-class SummarizeExecutor < Igniter::LLM::Executor
-  provider :anthropic
-  model    "claude-haiku-4-5-20251001"
-  system_prompt "Return a single concise sentence summary."
-
-  def call(text:)
-    complete("Summarize: #{text}")
-  end
-end
-
-class ArticleContract < Igniter::Contract
-  define do
-    input :text
-    compute :summary, depends_on: :text, call: SummarizeExecutor
-    output :summary
-  end
-end
-
-ArticleContract.new(text: "Long article...").result.summary
-```
-
-For multi-turn conversations, use `Igniter::LLM::Context`:
-
-```ruby
-def call(feedback:, category:)
-  ctx = Igniter::LLM::Context
-    .empty(system: self.class.system_prompt)
-    .append_user("Feedback: #{feedback}")
-    .append_user("Category: #{category}")
-  chat(context: ctx)
-end
-```
-
-For tool use (Anthropic function calling), declare tools at the class level:
-
-```ruby
-class ClassifyExecutor < Igniter::LLM::Executor
-  tools({
-    name: "set_category",
-    description: "Record the detected category",
-    input_schema: { type: "object", properties: { category: { type: "string" } }, required: ["category"] }
-  })
-
-  def call(feedback:)
-    complete_with_tools("Classify: #{feedback}")
-  end
-end
-```
-
-Guideline:
-
-- keep prompts inside the executor class, not scattered in the graph
-- use `Context` when a step needs multi-turn history rather than a single prompt
-- chain LLM executors as normal `compute` nodes — the graph handles ordering and caching
-- mock the provider in tests and CI; real API calls belong in integration tests only

data/docs/PROACTIVE_AGENTS_V1.md

@@ -1,293 +0,0 @@
-# Proactive Agents — V1
-
-## Concept
-
-Standard Igniter agents are **reactive** — they wait for messages and respond.
-A **proactive** agent acts *without being asked*: it polls conditions on a
-schedule, evaluates rules, and fires actions when conditions are met.
-
-```
-Reactive:   external message  →  handler  →  new state
-Proactive:  timer tick        →  watchers  →  triggers  →  actions  →  new state
-```
-
-`ProactiveAgent` is an experimental base class that adds four DSL keywords and
-a built-in scan lifecycle on top of the standard `Igniter::Agent` API.
-
----
-
-## Architecture
-
-```
-ProactiveAgent < Igniter::Agent
-    │
-    ├── scan_interval  — register a recurring :_scan timer
-    ├── watch          — register a named poll callable
-    ├── trigger        — register condition + action pair
-    └── proactive_initial_state
-            │
-            └── :_scan handler (auto-injected into every subclass)
-                    1. Call each watcher → build context Hash
-                    2. Evaluate each trigger condition(ctx)
-                    3. Call action(state:, context:) for truthy conditions
-                    4. Append FiredTrigger records, increment scan_count
-```
-
-### Execution model
-
-Every `scan_interval` seconds the timer fires and posts a `:_scan` message.
-The same `:_scan` handler is also callable programmatically — useful in specs
-and for composing proactive agents with other agents.
-
-When `active: false` (via `:pause`) the scan cycle is a no-op; timer still
-fires but watchers are not called and triggers are not evaluated.
-
----
-
-## DSL Reference
-
-### `ProactiveAgent`
-
-| Keyword | Description |
-|---|---|
-| `intent "…"` | Human-readable mission string (metadata, shown in `:status`) |
-| `scan_interval N` | Register a recurring timer every N seconds |
-| `watch :name, poll: callable` | Named watcher; callable returns current reading |
-| `trigger :name, condition:, action:` | Register a conditional action |
-| `proactive_initial_state extra` | Set initial state (merges ProactiveAgent defaults) |
-
-### Built-in handlers (injected into every subclass)
-
-| Handler | Type | Description |
-|---|---|---|
-| `:_scan` | state-mutating | Run one scan cycle |
-| `:pause` | state-mutating | Suspend trigger evaluation (active: false) |
-| `:resume` | state-mutating | Resume trigger evaluation (active: true) |
-| `:status` | sync query → `Status` | Counts, intent, watcher/trigger names |
-| `:context` | sync query → Hash | Last context snapshot |
-| `:trigger_history` | sync query → Array | Up to 100 most recent `FiredTrigger` records |
-
----
-
-## Quick start
-
-```ruby
-require "igniter/agents/proactive_agent"
-
-class ServerTempMonitor < Igniter::Agents::ProactiveAgent
-  intent "Alert when server room temperature exceeds safe range"
-
-  scan_interval 10.0   # check every 10 seconds
-
-  watch :temp_c, poll: -> { SensorAPI.read_temp }
-
-  trigger :overheating,
-    condition: ->(ctx) { ctx[:temp_c].to_f > 30 },
-    action:    ->(state:, context:) {
-      Notifier.alert("Server room temp: #{context[:temp_c]}°C")
-      state.merge(last_alert_at: Time.now)
-    }
-
-  proactive_initial_state last_alert_at: nil
-end
-
-ref = ServerTempMonitor.start
-status = ref.call(:status)
-# => Status(active: true, scan_count: 0, intent: "Alert when …", …)
-```
-
----
-
-## Subclasses — AlertAgent and HealthCheckAgent
-
-Two production-ready proactive agents are included in the stdlib:
-
-```
-require "igniter/agents"
-```
-
-### `AlertAgent`
-
-Threshold-based numeric monitoring with a concise DSL:
-
-```ruby
-class ApiMonitor < Igniter::Agents::AlertAgent
-  intent "Watch error rate and latency"
-  scan_interval 15.0
-
-  monitor :error_rate, source: -> { Metrics.error_rate }
-  monitor :p99_ms,     source: -> { Metrics.p99_latency }
-
-  threshold :error_rate, above: 0.05   # >5% errors
-  threshold :p99_ms,     above: 800    # >800ms p99
-  threshold :p99_ms,     below: 1      # ghost: no traffic at all
-
-  proactive_initial_state alerts: [], silenced: false
-end
-
-ref    = ApiMonitor.start
-ref.send(:silence)             # suppress new alerts
-alerts = ref.call(:alerts)     # => Array<AlertRecord>
-ref.send(:clear_alerts)
-```
-
-**AlertRecord fields**: `metric`, `value`, `kind` (`:above`/`:below`),
-`threshold`, `fired_at`.
-
-### `HealthCheckAgent`
-
-Service liveness polling with automatic transition detection:
-
-```ruby
-class InfraHealth < Igniter::Agents::HealthCheckAgent
-  intent "Monitor database and cache"
-  scan_interval 30.0
-
-  # poll returns truthy = healthy, falsy / raises = unhealthy
-  check :database, poll: -> { DB.ping }
-  check :cache,    poll: -> { Redis.current.ping == "PONG" }
-
-  proactive_initial_state health: {}, transitions: []
-end
-
-ref         = InfraHealth.start
-health      = ref.call(:health)       # => { database: :healthy, cache: :unhealthy }
-all_ok      = ref.call(:all_healthy)  # => false
-transitions = ref.call(:transitions)  # => [Transition(cache: unknown→unhealthy)]
-```
-
-Transitions are only recorded when status **changes** — no duplicate events for
-persistently unhealthy services.
-
-**Transition fields**: `service`, `from`, `to`, `occurred_at`.
-
----
-
-## Building your own ProactiveAgent subclass
-
-### Pattern: layering reactive and proactive handlers
-
-```ruby
-class StockWatcher < Igniter::Agents::ProactiveAgent
-  intent "Monitor stock price and fire when it crosses buy/sell thresholds"
-
-  scan_interval 60.0
-
-  watch :price, poll: -> { FinanceAPI.last_price("AAPL") }
-
-  trigger :buy_signal,
-    condition: ->(ctx) { ctx[:price].to_f < 150 },
-    action:    ->(state:, context:) {
-      state.merge(signals: state[:signals] + [{ type: :buy, price: context[:price], at: Time.now }])
-    }
-
-  proactive_initial_state signals: []
-
-  # Reactive handler for manual context override (e.g. in tests)
-  on :inject_price do |state:, payload:|
-    state.merge(context: state[:context].merge(price: payload[:price]))
-  end
-
-  on :signals do |state:, **|
-    state[:signals].dup
-  end
-end
-```
-
-### Pattern: re-injecting handlers in a concrete subclass
-
-Because `Agent.inherited` resets `@handlers`, any handlers defined in a
-parent class (like `AlertAgent`) are NOT automatically present in
-`Class.new(AlertAgent)` (used in tests or further subclasses).
-
-Both `AlertAgent` and `HealthCheckAgent` override `inherited` and call
-`inject_*_handlers!(subclass)` to ensure their handlers are always present.
-Follow the same pattern when building your own concrete subclass:
-
-```ruby
-class MyAgent < Igniter::Agents::ProactiveAgent
-  def self.inherited(subclass)
-    super                          # ProactiveAgent.inherited injects :_scan etc.
-    inject_my_handlers!(subclass)
-  end
-
-  private_class_method def self.inject_my_handlers!(klass)
-    klass.on(:my_query) { |state:, **| state[:my_data].dup }
-  end
-
-  on :my_query do |state:, **|
-    state[:my_data].dup
-  end
-end
-```
-
-### Testing: drive scans without a real timer
-
-```ruby
-RSpec.describe MyAgent do
-  let(:h) { ->(type, state) { MyAgent.handlers[type].call(state: state, payload: {}) } }
-
-  def base_state(extra = {})
-    { active: true, context: {}, scan_count: 0,
-      last_scan_at: nil, trigger_history: [] }.merge(extra)
-  end
-
-  it "fires trigger when condition is met" do
-    # Call :_scan directly — no timer, no threads
-    result = h.call(:_scan, base_state)
-    expect(result[:trigger_history]).not_to be_empty
-  end
-end
-```
-
----
-
-## Companion example
-
-`examples/companion/proactive/` shows three proactive agents in the context of
-the voice assistant companion application:
-
-| File | Agent | Mission |
-|---|---|---|
-| `conversation_nudge_agent.rb` | `ConversationNudgeAgent` | Detect silence and topic stagnation; propose conversation nudges |
-| `system_watch_agent.rb` | `SystemAlertAgent` / `DependencyHealthAgent` | Monitor API metrics and service liveness |
-| `demo.rb` | All four agents | Self-contained, runnable demonstration |
-
-```bash
-ruby examples/companion/proactive/demo.rb
-```
-
----
-
-## API quick reference
-
-```ruby
-# Base class DSL
-class MyAgent < Igniter::Agents::ProactiveAgent
-  intent        "…"
-  scan_interval 5.0
-  watch         :metric, poll: -> { source }
-  trigger       :name, condition: ->(ctx) { … }, action: ->(state:, context:) { … }
-  proactive_initial_state key: default_value
-end
-
-# Runtime
-ref = MyAgent.start
-ref.send(:pause)                       # suspend reactions
-ref.send(:resume)                      # resume
-ref.call(:status)                      # => Status struct
-ref.call(:context)                     # => { metric: last_reading, … }
-ref.call(:trigger_history)             # => [FiredTrigger, …]
-
-# AlertAgent
-ref.send(:silence)                     # suppress new alerts
-ref.send(:unsilence)
-ref.call(:alerts)                      # => [AlertRecord, …]
-ref.send(:clear_alerts)
-
-# HealthCheckAgent
-ref.call(:health)                      # => { service: :healthy/:unhealthy }
-ref.call(:all_healthy)                 # => true | false
-ref.call(:transitions)                 # => [Transition, …]
-ref.send(:reset)
-```