igniter 0.5.0 → 0.5.2

data/examples/invariants.rb

@@ -1,179 +0,0 @@
-# frozen_string_literal: true
-
-# examples/invariants.rb
-#
-# Demonstrates Igniter Invariants and Property Testing — declare conditions
-# that must always hold for a contract's outputs, then verify them against
-# hundreds of randomly generated inputs.
-#
-# Run with: bundle exec ruby examples/invariants.rb
-
-require_relative "../lib/igniter"
-require_relative "../lib/igniter/extensions/invariants"
-require_relative "../lib/igniter/property_testing"
-
-# ── 1. Define a contract with invariants ──────────────────────────────────────
-
-class PricingContract < Igniter::Contract
-  define do
-    input :price
-    input :quantity
-
-    compute :subtotal, depends_on: %i[price quantity] do |price:, quantity:|
-      price * quantity
-    end
-
-    compute :discount, depends_on: :subtotal do |subtotal:|
-      subtotal > 100 ? subtotal * 0.1 : 0.0
-    end
-
-    compute :total, depends_on: %i[subtotal discount] do |subtotal:, discount:|
-      subtotal - discount
-    end
-
-    output :total
-    output :subtotal
-    output :discount
-  end
-
-  # Block receives only declared output values as keyword args.
-  # Use ** to absorb outputs you don't need to check.
-  invariant(:total_non_negative)    { |total:, **|             total >= 0 }
-  invariant(:discount_non_negative) { |discount:, **|          discount >= 0 }
-  invariant(:total_le_subtotal)     { |total:, subtotal:, **|  total <= subtotal }
-end
-
-# ── 2. Happy path — invariants pass ───────────────────────────────────────────
-
-puts "=" * 60
-puts "HAPPY PATH — invariants pass"
-puts "=" * 60
-puts
-
-contract = PricingContract.new(price: 20.0, quantity: 10)
-contract.resolve_all
-
-puts "  total:    #{contract.result.total}"
-puts "  subtotal: #{contract.result.subtotal}"
-puts "  discount: #{contract.result.discount}"
-puts
-puts "  check_invariants: #{contract.check_invariants.inspect}"
-puts
-
-# ── 3. Manual violation check — does not raise ───────────────────────────────
-
-puts "=" * 60
-puts "MANUAL CHECK — does not raise, returns violations"
-puts "=" * 60
-puts
-
-class NegativePriceContract < Igniter::Contract
-  define do
-    input :price
-    input :quantity
-    compute :total, depends_on: %i[price quantity] do |price:, quantity:|
-      price * quantity # can be negative if price < 0
-    end
-    output :total
-  end
-
-  invariant(:total_non_negative) { |total:, **| total >= 0 }
-end
-
-c = NegativePriceContract.new(price: -5.0, quantity: 3)
-
-# Disable auto-raise to inspect violations manually
-Thread.current[:igniter_skip_invariants] = true
-c.resolve_all
-Thread.current[:igniter_skip_invariants] = false
-
-violations = c.check_invariants
-puts "  violations: #{violations.map(&:name).inspect}"
-puts "  total: #{c.result.total}"
-puts
-
-# ── 4. Automatic raise on violation ───────────────────────────────────────────
-
-puts "=" * 60
-puts "AUTO-RAISE — resolve_all raises InvariantError"
-puts "=" * 60
-puts
-
-begin
-  NegativePriceContract.new(price: -5.0, quantity: 3).resolve_all
-rescue Igniter::InvariantError => e
-  puts "  Caught InvariantError: #{e.message}"
-  puts "  violations: #{e.violations.map(&:name).inspect}"
-end
-puts
-
-# ── 5. Property testing — all inputs valid ────────────────────────────────────
-
-puts "=" * 60
-puts "PROPERTY TEST — PricingContract with valid inputs"
-puts "=" * 60
-puts
-
-G = Igniter::PropertyTesting::Generators
-
-result = PricingContract.property_test(
-  generators: {
-    price: G.float(0.0..500.0),
-    quantity: G.positive_integer(max: 100)
-  },
-  runs: 200,
-  seed: 42
-)
-
-puts result.explain
-puts
-
-# ── 6. Property testing — finds a counterexample ─────────────────────────────
-
-puts "=" * 60
-puts "PROPERTY TEST — NegativePriceContract with unconstrained inputs"
-puts "=" * 60
-puts
-
-failing_result = NegativePriceContract.property_test(
-  generators: {
-    price: G.float(-100.0..100.0), # can be negative!
-    quantity: G.positive_integer(max: 10)
-  },
-  runs: 100,
-  seed: 1
-)
-
-puts failing_result.explain
-puts
-puts "  First counterexample inputs: #{failing_result.counterexample&.inputs.inspect}"
-puts
-
-# ── 7. Property testing — execution errors captured ──────────────────────────
-
-puts "=" * 60
-puts "PROPERTY TEST — execution errors captured as failed runs"
-puts "=" * 60
-puts
-
-class FragileContract < Igniter::Contract
-  define do
-    input :value
-    compute :result, depends_on: :value do |value:|
-      raise ArgumentError, "value must be positive" if value <= 0
-
-      Math.sqrt(value)
-    end
-    output :result
-  end
-
-  invariant(:result_non_negative) { |result:, **| result >= 0 }
-end
-
-fragile_result = FragileContract.property_test(
-  generators: { value: G.integer(min: -10, max: 10) },
-  runs: 50,
-  seed: 7
-)
-
-puts fragile_result.explain

data/examples/llm_tools.rb

@@ -1,237 +0,0 @@
-# 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."

data/examples/marketing_ergonomics.rb

@@ -1,57 +0,0 @@
-# frozen_string_literal: true
-
-$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
-require "igniter"
-
-OUTBOX = []
-
-class MarketingQuoteContract < Igniter::Contract
-  define do
-    input :service, type: :string
-    input :zip_code, type: :string
-
-    const :vendor_id, "eLocal"
-
-    scope :routing do
-      map :trade_name, from: :service do |service:|
-        %w[heating cooling ventilation air_conditioning].include?(service.downcase) ? "HVAC" : service
-      end
-    end
-
-    scope :pricing do
-      lookup :trade, with: :trade_name do |trade_name:|
-        { name: trade_name, base_bid: trade_name == "HVAC" ? 45.0 : 25.0 }
-      end
-    end
-
-    namespace :validation do
-      guard :zip_supported, with: :zip_code, in: %w[60601 10001], message: "Unsupported zip"
-    end
-
-    compute :quote, with: %i[vendor_id trade zip_supported zip_code] do |vendor_id:, trade:, zip_supported:, zip_code:|
-      zip_supported
-      {
-        vendor_id: vendor_id,
-        trade: trade[:name],
-        zip_code: zip_code,
-        bid: trade[:base_bid]
-      }
-    end
-
-    expose :quote, as: :response
-  end
-
-  on_success :response do |value:, **|
-    OUTBOX << {
-      vendor_id: value[:vendor_id],
-      zip_code: value[:zip_code]
-    }
-  end
-end
-
-contract = MarketingQuoteContract.new(service: "heating", zip_code: "60601")
-
-puts contract.explain_plan
-puts "---"
-puts "response=#{contract.result.response.inspect}"
-puts "outbox=#{OUTBOX.inspect}"