igniter 0.4.5 → 0.5.1

data/docs/STORE_ADAPTERS.md

@@ -1,126 +0,0 @@
-# Store Adapters
-
-Igniter ships with reference execution stores for:
-
-- memory
-- file
-- ActiveRecord-style persistence
-- Redis-style persistence
-
-All stores implement the same minimal protocol:
-
-- `save(snapshot)`
-- `fetch(execution_id)`
-- `delete(execution_id)`
-- `exist?(execution_id)`
-
-## Memory Store
-
-Useful for tests and single-process flows.
-
-```ruby
-Igniter.execution_store = Igniter::Runtime::Stores::MemoryStore.new
-```
-
-## File Store
-
-Useful for local development and smoke-testing worker flows.
-
-```ruby
-Igniter.execution_store = Igniter::Runtime::Stores::FileStore.new(
-  root: Rails.root.join("tmp/igniter_executions")
-)
-```
-
-## ActiveRecord Store
-
-Expected record shape:
-
-- one unique `execution_id` column
-- one text/json column for serialized snapshot payload
-
-Example model:
-
-```ruby
-class IgniterExecutionSnapshot < ApplicationRecord
-  validates :execution_id, presence: true, uniqueness: true
-end
-```
-
-Example migration:
-
-```ruby
-class CreateIgniterExecutionSnapshots < ActiveRecord::Migration[7.1]
-  def change
-    create_table :igniter_execution_snapshots do |t|
-      t.string :execution_id, null: false
-      t.jsonb :snapshot_json, null: false, default: {}
-      t.timestamps
-    end
-
-    add_index :igniter_execution_snapshots, :execution_id, unique: true
-  end
-end
-```
-
-Store configuration:
-
-```ruby
-Igniter.execution_store = Igniter::Runtime::Stores::ActiveRecordStore.new(
-  record_class: IgniterExecutionSnapshot,
-  execution_id_column: :execution_id,
-  snapshot_column: :snapshot_json
-)
-```
-
-## Redis Store
-
-Expected client protocol:
-
-- `set(key, value)`
-- `get(key)`
-- `del(key)`
-- `exists?(key)`
-
-Example configuration:
-
-```ruby
-redis = Redis.new(url: ENV.fetch("REDIS_URL"))
-
-Igniter.execution_store = Igniter::Runtime::Stores::RedisStore.new(
-  redis: redis,
-  namespace: "igniter:executions"
-)
-```
-
-## Worker Flow
-
-Store-backed contracts should declare:
-
-```ruby
-class AsyncPricingContract < Igniter::Contract
-  run_with runner: :store
-end
-```
-
-Producer side:
-
-```ruby
-contract = AsyncPricingContract.new(order_total: 100)
-deferred = contract.result.gross_total
-
-execution_id = contract.execution.events.execution_id
-token = deferred.token
-```
-
-Worker side:
-
-```ruby
-AsyncPricingContract.resume_from_store(
-  execution_id,
-  token: token,
-  value: 150
-)
-```
-
-If the resumed execution finishes successfully, the current `StoreRunner` deletes the persisted snapshot automatically.

data/lib/igniter/diagnostics.rb

@@ -1,8 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "diagnostics/report"
-
-module Igniter
-  module Diagnostics
-  end
-end

data/lib/igniter/executor.rb

@@ -1,74 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  class Executor
-    class << self
-      def inherited(subclass)
-        super
-        subclass.instance_variable_set(:@executor_inputs, executor_inputs.transform_values(&:dup))
-        subclass.instance_variable_set(:@executor_metadata, executor_metadata.dup)
-      end
-
-      def input(name, required: true, type: nil, **metadata)
-        executor_inputs[name.to_sym] = metadata.merge(required: required, type: type).compact
-      end
-
-      def executor_inputs
-        @executor_inputs ||= {}
-      end
-
-      def executor_metadata
-        @executor_metadata ||= {}
-      end
-
-      def executor_key(value = nil)
-        metadata_value(:key, value)
-      end
-
-      def label(value = nil)
-        metadata_value(:label, value)
-      end
-
-      def category(value = nil)
-        metadata_value(:category, value)
-      end
-
-      def summary(value = nil)
-        metadata_value(:summary, value)
-      end
-
-      def tags(*values)
-        return Array(executor_metadata[:tags]).freeze if values.empty?
-
-        executor_metadata[:tags] = values.flatten.compact.map(&:to_sym).freeze
-      end
-
-      def output_schema(value = nil)
-        metadata_value(:output_schema, value)
-      end
-
-      def call(**dependencies)
-        new.call(**dependencies)
-      end
-
-      private
-
-      def metadata_value(key, value)
-        return executor_metadata[key] if value.nil?
-
-        executor_metadata[key] = value
-      end
-    end
-
-    attr_reader :execution, :contract
-
-    def initialize(execution: nil, contract: nil)
-      @execution = execution
-      @contract = contract
-    end
-
-    def defer(token: nil, payload: {})
-      Runtime::DeferredResult.build(token: token, payload: payload)
-    end
-  end
-end

data/lib/igniter/extensions/introspection/plan_formatter.rb

@@ -1,55 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Extensions
-    module Introspection
-      class PlanFormatter
-        def self.to_text(execution, output_names = nil)
-          new(execution, output_names).to_text
-        end
-
-        def initialize(execution, output_names = nil)
-          @execution = execution
-          @plan = execution.plan(output_names)
-        end
-
-        def to_text
-          lines = []
-          lines << "Plan #{@execution.compiled_graph.name}"
-          lines << "Targets: #{format_list(@plan[:targets])}"
-          lines << "Ready: #{format_list(@plan[:ready])}"
-          lines << "Blocked: #{format_list(@plan[:blocked])}"
-          lines << "Nodes:"
-
-          @plan[:nodes].each_value do |entry|
-            lines << format_node(entry)
-          end
-
-          lines.join("\n")
-        end
-
-        private
-
-        def format_node(entry)
-          line = "- #{entry[:kind]} #{entry[:path]} status=#{entry[:status]}"
-          line += " ready=true" if entry[:ready]
-          line += " blocked=true" if entry[:blocked]
-          line += " waiting_on=#{format_list(entry[:waiting_on])}" if entry[:waiting_on].any?
-
-          dependency_summary = entry[:dependencies].map do |dependency|
-            "#{dependency[:name]}(#{dependency[:status]})"
-          end
-          line += " deps=#{dependency_summary.join(',')}" if dependency_summary.any?
-          line
-        end
-
-        def format_list(values)
-          array = Array(values)
-          return "none" if array.empty?
-
-          array.join(",")
-        end
-      end
-    end
-  end
-end

data/lib/igniter/extensions/invariants.rb

@@ -1,116 +0,0 @@
-# frozen_string_literal: true
-
-require "igniter"
-require "igniter/invariant"
-
-module Igniter
-  module Extensions
-    # Patches Igniter::Contract with:
-    #   - Class method: invariant(name) { |output:, **| condition }
-    #   - Instance method: check_invariants → Array<InvariantViolation>
-    #   - Automatic post-execution check in resolve_all (raises InvariantError)
-    #
-    # Invariant blocks receive ONLY the contract's declared output values as
-    # keyword args — the stable public interface, independent of internal nodes.
-    # Use ** to absorb outputs you don't need.
-    #
-    # @example
-    #   class PricingContract < Igniter::Contract
-    #     define do
-    #       input  :price
-    #       input  :quantity
-    #       compute :total, depends_on: %i[price quantity] do |price:, quantity:|
-    #         price * quantity
-    #       end
-    #       output :total
-    #     end
-    #
-    #     invariant(:total_non_negative) { |total:, **| total >= 0 }
-    #   end
-    #
-    # This module is applied globally via:
-    #   Igniter::Contract.include(Igniter::Extensions::Invariants)
-    #
-    module Invariants
-      def self.included(base)
-        base.extend(ClassMethods)
-        base.prepend(InstanceMethods)
-      end
-
-      # ── Class-level DSL ──────────────────────────────────────────────────────
-
-      module ClassMethods
-        # Declare a condition that must always hold after successful execution.
-        #
-        # The block receives the contract's declared output values as keyword
-        # arguments; use ** to absorb outputs you don't care about. Return a
-        # truthy value to indicate the invariant holds, falsy to indicate
-        # a violation.
-        #
-        # @example
-        #   invariant(:positive_total) { |total:, **| total >= 0 }
-        #
-        # @param name [Symbol]
-        def invariant(name, &block)
-          @_invariants ||= {}
-          @_invariants[name.to_sym] = Igniter::Invariant.new(name, &block)
-        end
-
-        # @return [Hash{Symbol => Igniter::Invariant}]
-        def invariants
-          @_invariants || {}
-        end
-      end
-
-      # ── Instance override + new public method ───────────────────────────────
-
-      module InstanceMethods
-        # Intercepts resolve_all to run invariant checks after execution.
-        # Uses a thread-local flag so that property testing can disable the
-        # automatic raise and collect violations as data instead.
-        def resolve_all(...)
-          result = super
-          validate_invariants! unless Thread.current[:igniter_skip_invariants]
-          result
-        end
-
-        # Run all invariants without raising. Returns violations as data.
-        # Safe to call at any time after execution.
-        #
-        # @return [Array<Igniter::InvariantViolation>]
-        def check_invariants
-          return [] if self.class.invariants.empty?
-
-          resolved = collect_output_values
-          self.class.invariants.values.filter_map { |inv| inv.check(resolved) }
-        end
-
-        private
-
-        def validate_invariants!
-          violations = check_invariants
-          return if violations.empty?
-
-          names = violations.map { |v| ":#{v.name}" }.join(", ")
-          raise Igniter::InvariantError.new(
-            "#{violations.size} invariant(s) violated: #{names}",
-            violations: violations,
-            context: { contract: self.class.name }
-          )
-        end
-
-        # Collect all declared output values from the resolved cache.
-        # Keyed by output name (not source node name).
-        def collect_output_values
-          cache = execution.cache
-          execution.compiled_graph.outputs.each_with_object({}) do |output_node, acc|
-            state = cache.fetch(output_node.source_root)
-            acc[output_node.name] = state.value if state&.succeeded?
-          end
-        end
-      end
-    end
-  end
-end
-
-Igniter::Contract.include(Igniter::Extensions::Invariants)

data/lib/igniter/integrations/agents.rb

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-# Actor system for Igniter — stateful message-driven agents with supervision.
-#
-# Usage:
-#   require "igniter/integrations/agents"
-#
-# Provides:
-#   Igniter::Agent      — base class for stateful actors
-#   Igniter::Supervisor — supervises and restarts child agents
-#   Igniter::Registry   — thread-safe name → Ref lookup
-#   Igniter::StreamLoop — continuous contract-in-a-tick-loop
-#
-
-require_relative "../agent"
-require_relative "../supervisor"
-require_relative "../registry"
-require_relative "../stream_loop"

data/lib/igniter/integrations/llm/config.rb

@@ -1,69 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module LLM
-    class Config
-      class OllamaConfig
-        attr_accessor :base_url, :default_model, :timeout
-
-        def initialize
-          @base_url = "http://localhost:11434"
-          @default_model = "llama3.2"
-          @timeout = 120
-        end
-      end
-
-      class AnthropicConfig
-        attr_accessor :api_key, :base_url, :default_model, :timeout
-
-        def initialize
-          @api_key = ENV["ANTHROPIC_API_KEY"]
-          @base_url = "https://api.anthropic.com"
-          @default_model = "claude-sonnet-4-6"
-          @timeout = 120
-        end
-      end
-
-      class OpenAIConfig
-        attr_accessor :api_key, :base_url, :default_model, :timeout
-
-        def initialize
-          @api_key = ENV["OPENAI_API_KEY"]
-          @base_url = "https://api.openai.com"
-          @default_model = "gpt-4o"
-          @timeout = 120
-        end
-      end
-
-      PROVIDERS = %i[ollama anthropic openai].freeze
-
-      attr_accessor :default_provider
-      attr_reader :providers
-
-      def initialize
-        @default_provider = :ollama
-        @providers = {
-          ollama: OllamaConfig.new,
-          anthropic: AnthropicConfig.new,
-          openai: OpenAIConfig.new
-        }
-      end
-
-      def ollama
-        @providers[:ollama]
-      end
-
-      def anthropic
-        @providers[:anthropic]
-      end
-
-      def openai
-        @providers[:openai]
-      end
-
-      def provider_config(name)
-        @providers.fetch(name.to_sym) { raise ArgumentError, "Unknown LLM provider: #{name}. Available: #{PROVIDERS.inspect}" }
-      end
-    end
-  end
-end

data/lib/igniter/integrations/llm/executor.rb

@@ -1,159 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module LLM
-    # Base class for LLM-powered compute nodes.
-    #
-    # Subclass and override #call(**inputs) to build prompts and get completions.
-    # Use the #complete and #chat helper methods inside #call.
-    #
-    # Example:
-    #   class DocumentSummarizer < Igniter::LLM::Executor
-    #     provider :ollama
-    #     model "llama3.2"
-    #     system_prompt "You are a concise technical writer."
-    #
-    #     def call(document:)
-    #       complete("Summarize this in 3 bullet points:\n\n#{document}")
-    #     end
-    #   end
-    #
-    #   class OrderContract < Igniter::Contract
-    #     define do
-    #       input :document
-    #       compute :summary, depends_on: :document, with: DocumentSummarizer
-    #       output :summary
-    #     end
-    #   end
-    class Executor < Igniter::Executor
-      class << self
-        def provider(name = nil)
-          return @provider || Igniter::LLM.config.default_provider if name.nil?
-
-          @provider = name.to_sym
-        end
-
-        def model(name = nil)
-          return @model || provider_config.default_model if name.nil?
-
-          @model = name
-        end
-
-        def system_prompt(text = nil)
-          return @system_prompt if text.nil?
-
-          @system_prompt = text
-        end
-
-        def temperature(val = nil)
-          return @temperature if val.nil?
-
-          @temperature = val
-        end
-
-        def tools(*tool_definitions)
-          return @tools || [] if tool_definitions.empty?
-
-          @tools = tool_definitions.flatten
-        end
-
-        def inherited(subclass)
-          super
-          subclass.instance_variable_set(:@provider, @provider)
-          subclass.instance_variable_set(:@model, @model)
-          subclass.instance_variable_set(:@system_prompt, @system_prompt)
-          subclass.instance_variable_set(:@temperature, @temperature)
-          subclass.instance_variable_set(:@tools, @tools&.dup)
-        end
-
-        private
-
-        def provider_config
-          Igniter::LLM.provider_instance(provider).instance_of?(Class) ? nil : Igniter::LLM.config.provider_config(provider)
-        rescue StandardError
-          Igniter::LLM.config.ollama
-        end
-      end
-
-      attr_reader :last_usage, :last_context
-
-      # Subclasses override this method. Use #complete or #chat inside.
-      def call(**_inputs)
-        raise NotImplementedError, "#{self.class.name}#call must be implemented"
-      end
-
-      protected
-
-      # Single-turn completion. Builds a simple user message from prompt.
-      def complete(prompt, context: nil)
-        messages = build_messages(prompt: prompt, context: context)
-        response = provider_instance.chat(
-          messages: messages,
-          model: self.class.model,
-          **completion_options
-        )
-        @last_usage = provider_instance.last_usage
-        @last_context = track_context(context, prompt, response[:content])
-        response[:content]
-      end
-
-      # Multi-turn chat with a Context object or raw messages array.
-      def chat(context:)
-        messages = context.is_a?(Context) ? context.to_a : Array(context)
-        response = provider_instance.chat(
-          messages: messages,
-          model: self.class.model,
-          **completion_options
-        )
-        @last_usage = provider_instance.last_usage
-        response[:content]
-      end
-
-      # Tool-use call. Returns DeferredResult if the LLM wants to call a tool.
-      def complete_with_tools(prompt, context: nil) # rubocop:disable Metrics/MethodLength
-        messages = build_messages(prompt: prompt, context: context)
-        response = provider_instance.chat(
-          messages: messages,
-          model: self.class.model,
-          tools: self.class.tools,
-          **completion_options
-        )
-        @last_usage = provider_instance.last_usage
-
-        if response[:tool_calls].any?
-          defer(payload: { tool_calls: response[:tool_calls], messages: messages })
-        else
-          response[:content]
-        end
-      end
-
-      private
-
-      def provider_instance
-        @provider_instance ||= Igniter::LLM.provider_instance(self.class.provider)
-      end
-
-      def build_messages(prompt:, context: nil)
-        base = []
-        base << { role: "system", content: self.class.system_prompt } if self.class.system_prompt
-
-        if context.is_a?(Context)
-          base + context.to_a + [{ role: "user", content: prompt }]
-        else
-          base + [{ role: "user", content: prompt }]
-        end
-      end
-
-      def completion_options
-        opts = {}
-        opts[:temperature] = self.class.temperature if self.class.temperature
-        opts
-      end
-
-      def track_context(existing, user_prompt, assistant_reply)
-        ctx = existing.is_a?(Context) ? existing : Context.empty(system: self.class.system_prompt)
-        ctx.append_user(user_prompt).append_assistant(assistant_reply)
-      end
-    end
-  end
-end

data/lib/igniter/integrations/llm.rb

@@ -1,59 +0,0 @@
-# frozen_string_literal: true
-
-require "igniter"
-require_relative "llm/config"
-require_relative "llm/context"
-require_relative "llm/providers/base"
-require_relative "llm/providers/ollama"
-require_relative "llm/providers/anthropic"
-require_relative "llm/providers/openai"
-require_relative "llm/executor"
-
-module Igniter
-  module LLM
-    class Error < Igniter::Error; end
-    class ProviderError < Error; end
-    class ConfigurationError < Error; end
-
-    AVAILABLE_PROVIDERS = Config::PROVIDERS
-
-    class << self
-      def config
-        @config ||= Config.new
-      end
-
-      def configure
-        yield config
-      end
-
-      # Returns a memoized provider instance for the given provider name.
-      def provider_instance(name)
-        @provider_instances ||= {}
-        @provider_instances[name.to_sym] ||= build_provider(name.to_sym)
-      end
-
-      # Reset cached provider instances (useful after reconfiguration).
-      def reset_providers!
-        @provider_instances = nil
-      end
-
-      private
-
-      def build_provider(name)
-        case name
-        when :ollama
-          cfg = config.ollama
-          Providers::Ollama.new(base_url: cfg.base_url, timeout: cfg.timeout)
-        when :anthropic
-          cfg = config.anthropic
-          Providers::Anthropic.new(api_key: cfg.api_key, base_url: cfg.base_url, timeout: cfg.timeout)
-        when :openai
-          cfg = config.openai
-          Providers::OpenAI.new(api_key: cfg.api_key, base_url: cfg.base_url, timeout: cfg.timeout)
-        else
-          raise ConfigurationError, "Unknown LLM provider: #{name}. Available: #{AVAILABLE_PROVIDERS.inspect}"
-        end
-      end
-    end
-  end
-end