RubyGems - igniter - Versions diffs - 0.5.0 → 0.5.2 - Mend

igniter 0.5.0 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (840) hide show

data/docs/PATTERNS.md DELETED Viewed

@@ -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 DELETED Viewed

@@ -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)
-```