igniter 0.4.5 → 0.5.0

data/examples/dataflow.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+# examples/dataflow.rb
+#
+# Demonstrates Igniter's incremental dataflow:
+#
+# Part 1 — Incremental Collection (mode: :incremental)
+#   Only added/changed items have their child contract re-run.
+#   Removed items are retracted automatically.
+#   window: { last: N } keeps a bounded sliding window in memory.
+#
+# Part 2 — Maintained Aggregates
+#   Aggregate nodes (count, sum, avg, min, max, group_count, custom) update
+#   in O(change) time — only the diff contributes, not the full collection.
+#
+# Typical use-cases:
+#   • IoT sensor streams   — thousands of sensors, updates arrive as diffs
+#   • Live analytics       — sliding-window aggregates with O(change) compute
+#   • Event-driven systems — process only the delta, not the full dataset
+#
+# Run with: bundle exec ruby examples/dataflow.rb
+
+require_relative "../lib/igniter"
+require_relative "../lib/igniter/extensions/dataflow"
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# PART 1 — Incremental Collection + Sliding Window
+# ═══════════════════════════════════════════════════════════════════════════════
+
+# ─── Child contract: process a single sensor reading ──────────────────────────
+class SensorAnalysis < Igniter::Contract
+  define do
+    input :sensor_id
+    input :value, type: :numeric
+    input :unit
+
+    compute :status, depends_on: :value do |value:|
+      case value
+      when (..0)    then :error
+      when (0..25)  then :normal
+      when (26..75) then :warning
+      else               :critical
+      end
+    end
+
+    compute :label, depends_on: %i[sensor_id status] do |sensor_id:, status:|
+      "[#{sensor_id}] #{status.upcase}"
+    end
+
+    output :status
+    output :label
+  end
+end
+
+# ─── Pipeline with sliding window ─────────────────────────────────────────────
+class SensorPipeline < Igniter::Contract
+  define do
+    input :readings, type: :array
+
+    collection :processed,
+               with: :readings,
+               each: SensorAnalysis,
+               key: :sensor_id,
+               mode: :incremental,
+               window: { last: 5 }
+
+    output :processed
+  end
+end
+
+# ─── Helpers ──────────────────────────────────────────────────────────────────
+
+def print_diff(label, diff)
+  puts "\n#{label}"
+  puts "  added:     #{diff.added.inspect}"
+  puts "  changed:   #{diff.changed.inspect}"
+  puts "  removed:   #{diff.removed.inspect}"
+  puts "  unchanged: #{diff.unchanged.inspect}"
+  puts "  processed: #{diff.processed_count} child contract(s) re-run"
+end
+
+def print_results(processed)
+  processed.successes.each_value do |item|
+    puts "  #{item.result.label}"
+  end
+end
+
+puts "═" * 60
+puts "PART 1 — Incremental Collection + Sliding Window"
+puts "═" * 60
+
+# ── Round 1: initial batch — 4 sensors, all treated as :added ─────────────────
+
+initial_readings = [
+  { sensor_id: "tmp-1",  value: 20, unit: "°C" },
+  { sensor_id: "tmp-2",  value: 45, unit: "°C" },
+  { sensor_id: "hum-1",  value: 80, unit: "%" },
+  { sensor_id: "pres-1", value: 5,  unit: "kPa" }
+]
+
+pipeline = SensorPipeline.new(readings: initial_readings)
+pipeline.resolve_all
+
+diff = pipeline.collection_diff(:processed)
+print_diff("── Round 1: initial batch ──────────────────────────", diff)
+print_results(pipeline.result.processed)
+
+# ── Round 2: one sensor crosses critical threshold ────────────────────────────
+
+pipeline.feed_diff(:readings, update: [{ sensor_id: "tmp-2", value: 90, unit: "°C" }])
+pipeline.resolve_all
+
+diff = pipeline.collection_diff(:processed)
+print_diff("── Round 2: tmp-2 value 45 → 90 ───────────────────", diff)
+print_results(pipeline.result.processed)
+
+# ── Round 3: new sensor arrives ───────────────────────────────────────────────
+
+pipeline.feed_diff(:readings, add: [{ sensor_id: "wind-1", value: 15, unit: "m/s" }])
+pipeline.resolve_all
+
+diff = pipeline.collection_diff(:processed)
+print_diff("── Round 3: wind-1 joins the stream ────────────────", diff)
+print_results(pipeline.result.processed)
+
+# ── Round 4: sensor goes offline ──────────────────────────────────────────────
+
+pipeline.feed_diff(:readings, remove: ["hum-1"])
+pipeline.resolve_all
+
+diff = pipeline.collection_diff(:processed)
+print_diff("── Round 4: hum-1 removed ──────────────────────────", diff)
+print_results(pipeline.result.processed)
+
+# ── Round 5: identical update — zero re-runs ──────────────────────────────────
+
+pipeline.update_inputs(readings: pipeline.execution.inputs[:readings].dup)
+pipeline.resolve_all
+
+diff = pipeline.collection_diff(:processed)
+print_diff("── Round 5: no data changed (zero re-runs) ─────────", diff)
+
+# ── Round 6: sliding window — adding 6th sensor evicts oldest ─────────────────
+
+pipeline.feed_diff(:readings, add: [{ sensor_id: "co2-1", value: 60, unit: "ppm" }])
+pipeline.resolve_all
+
+diff = pipeline.collection_diff(:processed)
+print_diff("── Round 6: co2-1 added (window: last 5) ───────────", diff)
+puts "\n  Active sensors in window: #{pipeline.result.processed.keys.inspect}"
+
+# ─── Summary ──────────────────────────────────────────────────────────────────
+
+puts "\n── Summary ─────────────────────────────────────────────"
+puts "  Final window: #{pipeline.result.processed.keys.inspect}"
+puts "  Diff explain: #{pipeline.collection_diff(:processed).explain}"
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# PART 2 — Maintained Aggregates
+#
+# Aggregates update in O(change) time — only the diff items are processed.
+# The AggregateState stores per-key contributions so that removed/changed items
+# can be retracted without rescanning the full collection.
+# ═══════════════════════════════════════════════════════════════════════════════
+
+puts "\n"
+puts "═" * 60
+puts "PART 2 — Maintained Aggregates"
+puts "═" * 60
+
+# ─── Child contract: classify sensor with zone info ───────────────────────────
+
+class SensorMetrics < Igniter::Contract
+  define do
+    input :sensor_id
+    input :value, type: :numeric
+    input :zone
+
+    compute :status, depends_on: :value do |value:|
+      value > 75 ? :critical : :normal
+    end
+
+    output :status
+    output :value   # exposed for sum/avg/min/max projections
+    output :zone    # exposed for group_count
+  end
+end
+
+# ─── Analytics pipeline with all built-in aggregate operators ─────────────────
+
+class AnalyticsPipeline < Igniter::Contract
+  define do # rubocop:disable Metrics/BlockLength
+    input :sensors, type: :array
+
+    collection :processed,
+               with: :sensors,
+               each: SensorMetrics,
+               key: :sensor_id,
+               mode: :incremental
+
+    # ── Built-in operators ──────────────────────────────────────────────────
+    aggregate :total, from: :processed # count all
+    aggregate :high_count,
+              from: :processed,
+              count: ->(item) { item.result.status == :critical }
+    aggregate :total_value,
+              from: :processed,
+              sum: ->(item) { item.result.value.to_f }
+    aggregate :avg_value,
+              from: :processed,
+              avg: ->(item) { item.result.value.to_f }
+    aggregate :peak,
+              from: :processed,
+              max: ->(item) { item.result.value.to_f }
+    aggregate :by_zone,
+              from: :processed,
+              group_count: ->(item) { item.result.zone }
+
+    # ── Custom retractable aggregate ────────────────────────────────────────
+    # Maintains a sorted list of unique critical sensor IDs
+    critical_add = lambda do |acc, item|
+      item.result.status == :critical ? (acc + [item.key]).sort.uniq : acc
+    end
+    aggregate :critical_ids,
+              from: :processed,
+              initial: [],
+              add: critical_add,
+              remove: ->(acc, item) { acc - [item.key] }
+
+    output :processed
+    output :total
+    output :high_count
+    output :total_value
+    output :avg_value
+    output :peak
+    output :by_zone
+    output :critical_ids
+  end
+end
+
+# ─── Helper ───────────────────────────────────────────────────────────────────
+
+def print_aggregates(result) # rubocop:disable Metrics/AbcSize
+  r = result
+  puts "  total       = #{r.total}"
+  puts "  high_count  = #{r.high_count}  (critical sensors)"
+  puts "  total_value = #{r.total_value.round(1)}"
+  puts "  avg_value   = #{r.avg_value.round(2)}"
+  puts "  peak        = #{r.peak.inspect}"
+  puts "  by_zone     = #{r.by_zone.inspect}"
+  puts "  critical_ids= #{r.critical_ids.inspect}"
+end
+
+sensor = ->(id, value, zone) { { sensor_id: id, value: value, zone: zone } }
+
+# ── Round A: initial batch ─────────────────────────────────────────────────────
+
+sensors_a = [
+  sensor.call("s1", 20, "north"), # normal
+  sensor.call("s2", 80, "north"), # critical
+  sensor.call("s3", 90, "south"), # critical
+  sensor.call("s4", 30, "south")  # normal
+]
+
+ap = AnalyticsPipeline.new(sensors: sensors_a)
+ap.resolve_all
+
+puts "\n── Round A: initial batch (4 sensors) ──────────────────"
+puts "  diff: #{ap.collection_diff(:processed).processed_count} child contract(s) run"
+print_aggregates(ap.result)
+
+# ── Round B: s2 value drops (critical → normal) ───────────────────────────────
+
+ap.feed_diff(:sensors, update: [sensor.call("s2", 40, "north")])
+ap.resolve_all
+
+puts "\n── Round B: s2 value 80 → 40  (critical → normal) ──────"
+puts "  diff: #{ap.collection_diff(:processed).processed_count} child contract(s) run"
+print_aggregates(ap.result)
+
+# ── Round C: new sensor added in a new zone ────────────────────────────────────
+
+ap.feed_diff(:sensors, add: [sensor.call("s5", 95, "east")])
+ap.resolve_all
+
+puts "\n── Round C: s5 added in zone 'east' (critical) ─────────"
+puts "  diff: #{ap.collection_diff(:processed).processed_count} child contract(s) run"
+print_aggregates(ap.result)
+
+# ── Round D: peak sensor removed ──────────────────────────────────────────────
+
+ap.feed_diff(:sensors, remove: ["s5"])
+ap.resolve_all
+
+puts "\n── Round D: s5 removed (peak was 95) ───────────────────"
+puts "  diff: #{ap.collection_diff(:processed).processed_count} child contract(s) run"
+print_aggregates(ap.result)
+
+# ── Round E: no change — zero re-runs, aggregates stable ──────────────────────
+
+ap.update_inputs(sensors: ap.execution.inputs[:sensors].dup)
+ap.resolve_all
+
+puts "\n── Round E: no change (zero re-runs, aggregates stable) "
+puts "  diff: #{ap.collection_diff(:processed).processed_count} child contract(s) run"
+print_aggregates(ap.result)
+
+puts "\nDone."

data/examples/elocal_webhook.rb

@@ -0,0 +1 @@
+# frozen_string_literal: true

data/examples/llm_tools.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+# examples/llm_tools.rb
+#
+# Demonstrates Igniter::Tool — AI-callable tools with:
+#   - Declarative metadata (description, param schema, required capabilities)
+#   - JSON schema generation for Anthropic / OpenAI APIs
+#   - Capability-based access guards (enforced before tool.call)
+#   - Automatic tool-use loop inside LLM::Executor#complete
+#   - ToolRegistry for global discovery and schema export
+#   - Tool reuse as regular Igniter::Contract compute nodes
+#
+# Requires: ANTHROPIC_API_KEY (skips live calls if absent)
+#
+# Run: bundle exec ruby examples/llm_tools.rb
+
+require "igniter"
+require "igniter/tool"
+require "igniter/tool_registry"
+require "igniter/integrations/llm"
+
+puts "=" * 62
+puts "  Igniter::Tool Demo"
+puts "=" * 62
+
+# ─────────────────────────────────────────────────────────────────────────────
+# [1] Define tools
+# ─────────────────────────────────────────────────────────────────────────────
+puts "\n[1] Defining tools"
+
+class Calculator < Igniter::Tool
+  description "Evaluate a mathematical expression and return the result"
+  param :expression, type: :string, required: true, desc: "A Ruby-evaluable math expression"
+
+  def call(expression:)
+    result = eval(expression) # rubocop:disable Security/Eval
+    { expression: expression, result: result }
+  end
+end
+
+class TimeNow < Igniter::Tool
+  description "Return the current UTC time"
+  # no params, no required capabilities
+
+  def call
+    { utc: Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ") }
+  end
+end
+
+class DatabaseLookup < Igniter::Tool
+  description "Look up a record in the (simulated) product database by SKU"
+  param :sku, type: :string, required: true, desc: "Product SKU identifier"
+
+  requires_capability :database_read   # agent must declare this capability
+
+  PRODUCTS = {
+    "SKU-001" => { name: "Widget Pro", price: 29.99, stock: 150 },
+    "SKU-002" => { name: "Gadget Plus", price: 49.99, stock: 42 },
+    "SKU-003" => { name: "Doohickey Max", price: 99.00, stock: 7 },
+  }.freeze
+
+  def call(sku:)
+    product = PRODUCTS[sku.upcase]
+    product ? product.merge(sku: sku.upcase) : { error: "SKU #{sku} not found" }
+  end
+end
+
+puts "  Defined: Calculator, TimeNow, DatabaseLookup"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# [2] Schema generation
+# ─────────────────────────────────────────────────────────────────────────────
+puts "\n[2] Schema generation"
+
+puts "  Calculator.tool_name:     #{Calculator.tool_name}"
+puts "  DatabaseLookup.tool_name: #{DatabaseLookup.tool_name}"
+puts "  DatabaseLookup.required_capabilities: #{DatabaseLookup.required_capabilities.inspect}"
+
+schema = Calculator.to_schema
+puts "\n  Intermediate schema (normalized by provider):"
+puts "    name:       #{schema[:name]}"
+puts "    parameters: #{schema[:parameters].inspect}"
+
+puts "\n  Anthropic schema:"
+require "json"
+puts JSON.pretty_generate(Calculator.to_schema(:anthropic)).split("\n").map { |l| "    #{l}" }.join("\n")
+
+# ─────────────────────────────────────────────────────────────────────────────
+# [3] ToolRegistry
+# ─────────────────────────────────────────────────────────────────────────────
+puts "\n[3] ToolRegistry"
+
+Igniter::ToolRegistry.register(Calculator, TimeNow, DatabaseLookup)
+puts "  Registered #{Igniter::ToolRegistry.size} tools: #{Igniter::ToolRegistry.all.map(&:tool_name).join(", ")}"
+
+# Capability filtering
+public_tools = Igniter::ToolRegistry.tools_for(capabilities: [])
+puts "  Tools with no caps required: #{public_tools.map(&:tool_name).join(", ")}"
+
+db_tools = Igniter::ToolRegistry.tools_for(capabilities: %i[database_read])
+puts "  Tools available with :database_read: #{db_tools.map(&:tool_name).join(", ")}"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# [4] Capability guard
+# ─────────────────────────────────────────────────────────────────────────────
+puts "\n[4] Capability guard"
+
+puts "  Calling Calculator (no caps required)..."
+result = Calculator.new.call_with_capability_check!(allowed_capabilities: [], expression: "6 * 7")
+puts "    6 * 7 = #{result[:result]}"
+
+puts "  Calling DatabaseLookup without :database_read capability..."
+begin
+  DatabaseLookup.new.call_with_capability_check!(allowed_capabilities: [], sku: "SKU-001")
+  puts "    BUG: should have raised"
+rescue Igniter::Tool::CapabilityError => e
+  puts "    CapabilityError: #{e.message}"
+end
+
+puts "  Calling DatabaseLookup WITH :database_read capability..."
+product = DatabaseLookup.new.call_with_capability_check!(
+  allowed_capabilities: [:database_read], sku: "SKU-001"
+)
+puts "    Found: #{product[:name]} — $#{product[:price]}"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# [5] Tool as a regular Igniter::Contract compute node
+#     Tool IS an Executor — full Contract compatibility
+# ─────────────────────────────────────────────────────────────────────────────
+puts "\n[5] Tool as Contract compute node"
+
+class PriceChecker < Igniter::Contract
+  define do
+    input :sku
+
+    compute :product, with: :sku, call: DatabaseLookup
+    compute :discount, with: :product, call: Class.new(Igniter::Executor) {
+      def call(product:)
+        return { rate: 0.2, reason: "low stock" } if product[:stock] < 10
+        { rate: 0.05, reason: "standard" }
+      end
+    }
+
+    output :product
+    output :discount
+  end
+end
+
+checker = PriceChecker.new(sku: "SKU-003")
+checker.resolve_all
+puts "  SKU-003: #{checker.result.product[:name]}"
+puts "  Stock:   #{checker.result.product[:stock]}  →  discount: #{(checker.result.discount[:rate] * 100).to_i}% (#{checker.result.discount[:reason]})"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# [6] LLM::Executor with automatic tool-use loop
+#     (live call requires ANTHROPIC_API_KEY)
+# ─────────────────────────────────────────────────────────────────────────────
+puts "\n[6] LLM::Executor with automatic tool-use loop"
+
+if ENV["ANTHROPIC_API_KEY"].to_s.empty?
+  puts "  ANTHROPIC_API_KEY not set — skipping live call"
+  puts "  (showing executor definition only)"
+
+  class ProductAgent < Igniter::LLM::Executor
+    provider :anthropic
+    model "claude-haiku-4-5-20251001"
+    system_prompt "You are a helpful product assistant. Use tools to answer questions."
+
+    tools Calculator, TimeNow, DatabaseLookup
+
+    # This agent may use the database — declare the capability
+    capabilities :database_read
+
+    max_tool_iterations 5
+
+    def call(question:)
+      complete(question)
+      # complete() detects Tool classes in tools DSL and auto-loops:
+      #   1. Sends tool schemas to Anthropic API
+      #   2. LLM responds with tool_use blocks
+      #   3. Capability guard checks agent.declared_capabilities
+      #   4. Tool#call executes, result appended to conversation
+      #   5. Loop until LLM returns plain text
+    end
+  end
+
+  puts "  ProductAgent defined with:"
+  puts "    tools:        #{ProductAgent.tools.map(&:tool_name).join(", ")}"
+  puts "    capabilities: #{ProductAgent.declared_capabilities.inspect}"
+  puts "    max_iters:    #{ProductAgent.max_tool_iterations}"
+else
+  class ProductAgent < Igniter::LLM::Executor
+    provider :anthropic
+    model "claude-haiku-4-5-20251001"
+    system_prompt "You are a helpful product assistant. Use tools to answer questions."
+
+    tools Calculator, TimeNow, DatabaseLookup
+    capabilities :database_read
+    max_tool_iterations 5
+
+    def call(question:)
+      complete(question)
+    end
+  end
+
+  puts "  Asking: 'What is the price of SKU-001 and what is 15% of that price?'"
+  begin
+    answer = ProductAgent.new.call(question: "What is the price of SKU-001 and what is 15% of that price?")
+    puts "  Agent: #{answer}"
+  rescue Igniter::LLM::Error => e
+    puts "  LLM error: #{e.message}"
+  end
+end
+
+# ─────────────────────────────────────────────────────────────────────────────
+# [7] Agent without database_read — CapabilityError before tool executes
+# ─────────────────────────────────────────────────────────────────────────────
+puts "\n[7] Agent with restricted capabilities"
+
+class RestrictedAgent < Igniter::LLM::Executor
+  provider :anthropic
+  model "claude-haiku-4-5-20251001"
+  system_prompt "You are a limited assistant."
+
+  tools Calculator, TimeNow, DatabaseLookup
+  # no capabilities declared — cannot call DatabaseLookup
+  max_tool_iterations 3
+
+  def call(question:)
+    complete(question)
+  end
+end
+
+puts "  RestrictedAgent.declared_capabilities: #{RestrictedAgent.declared_capabilities.inspect}"
+puts "  Tools it may safely call: #{Igniter::ToolRegistry.tools_for(capabilities: RestrictedAgent.declared_capabilities).map(&:tool_name).join(", ")}"
+
+puts "\nDone."