igniter 0.4.5 → 0.5.1

data/{lib/igniter → packages/igniter-core/lib/igniter/core}/runtime/result.rb

@@ -90,6 +90,8 @@ module Igniter
 
       def serialize_output_value(value)
         case value
+        when StreamResult
+          value.as_json
         when DeferredResult
           value.as_json
         when Result

data/packages/igniter-core/lib/igniter/core/runtime/stores/redis_store.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Igniter
+  module Runtime
+    module Stores
+      class RedisStore
+        def initialize(redis:, namespace: "igniter:executions")
+          @redis = redis
+          @namespace = namespace
+        end
+
+        # Save a snapshot. Maintains secondary indexes:
+        #   {namespace}:all               — set of all execution_ids
+        #   {namespace}:graph:{name}      — set of execution_ids for a given graph
+        #   {namespace}:corr:{graph}      — hash of JSON(sorted_correlation) → execution_id
+        def save(snapshot, correlation: nil, graph: nil) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+          execution_id = snapshot[:execution_id] || snapshot["execution_id"]
+          @redis.set(redis_key(execution_id), JSON.generate(snapshot))
+          @redis.sadd(all_key, execution_id)
+
+          if graph
+            @redis.sadd(graph_key(graph), execution_id)
+            if correlation && !correlation.empty?
+              corr_json = JSON.generate(correlation.transform_keys(&:to_s).sort.to_h)
+              @redis.hset(correlation_key(graph), corr_json, execution_id)
+            end
+          end
+
+          execution_id
+        end
+
+        def find_by_correlation(graph:, correlation:)
+          normalized = correlation.transform_keys(&:to_s).sort.to_h
+          @redis.hget(correlation_key(graph), JSON.generate(normalized))
+        end
+
+        def list_all(graph: nil)
+          @redis.smembers(graph ? graph_key(graph) : all_key)
+        end
+
+        def list_pending(graph: nil)
+          list_all(graph: graph).select do |id|
+            payload = @redis.get(redis_key(id))
+            next false unless payload
+
+            snapshot = JSON.parse(payload)
+            states   = snapshot["states"] || {}
+            states.any? { |_name, state| state["status"].to_s == "pending" }
+          rescue StandardError
+            false
+          end
+        end
+
+        def fetch(execution_id)
+          payload = @redis.get(redis_key(execution_id))
+          raise Igniter::ResolutionError, "No execution snapshot found for '#{execution_id}'" unless payload
+
+          JSON.parse(payload)
+        end
+
+        def delete(execution_id)
+          @redis.del(redis_key(execution_id))
+          @redis.srem(all_key, execution_id)
+        end
+
+        def exist?(execution_id)
+          result = @redis.exists?(redis_key(execution_id))
+          result == true || result.to_i.positive?
+        end
+
+        private
+
+        def redis_key(execution_id)
+          "#{@namespace}:#{execution_id}"
+        end
+
+        def all_key
+          "#{@namespace}:all"
+        end
+
+        def graph_key(graph)
+          "#{@namespace}:graph:#{graph}"
+        end
+
+        def correlation_key(graph)
+          "#{@namespace}:corr:#{graph}"
+        end
+      end
+    end
+  end
+end

data/packages/igniter-core/lib/igniter/core/runtime/stores/sqlite_store.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module Igniter
+  module Runtime
+    module Stores
+      class SQLiteStore
+        def initialize(path:)
+          require "sqlite3"
+        rescue LoadError
+          raise Igniter::Runtime::ConfigurationError,
+                "`igniter` now ships with a required `sqlite3` dependency. " \
+                "If it is missing in this environment, run bundle install or reinstall the gem."
+        else
+          prepare_path!(path)
+          @mutex = Mutex.new
+          @db = ::SQLite3::Database.new(path)
+          @db.results_as_hash = true
+          create_schema!
+        end
+
+        def save(snapshot, correlation: nil, graph: nil)
+          execution_id = snapshot[:execution_id] || snapshot["execution_id"]
+          resolved_graph = graph || snapshot[:graph] || snapshot["graph"]
+          correlation_json = normalized_correlation_json(correlation)
+          pending = pending_snapshot?(snapshot) ? 1 : 0
+
+          @mutex.synchronize do
+            @db.execute(
+              <<~SQL,
+                INSERT OR REPLACE INTO execution_snapshots
+                  (execution_id, graph, correlation_json, pending, snapshot_json, updated_at)
+                VALUES (?, ?, ?, ?, ?, ?)
+              SQL
+              [execution_id, resolved_graph, correlation_json, pending, JSON.generate(snapshot), Time.now.to_i]
+            )
+          end
+
+          execution_id
+        end
+
+        def find_by_correlation(graph:, correlation:)
+          @mutex.synchronize do
+            row = @db.get_first_row(
+              "SELECT execution_id FROM execution_snapshots WHERE graph = ? AND correlation_json = ?",
+              [graph, normalized_correlation_json(correlation)]
+            )
+            row && row["execution_id"]
+          end
+        end
+
+        def list_all(graph: nil)
+          @mutex.synchronize do
+            rows =
+              if graph
+                @db.execute(
+                  "SELECT execution_id FROM execution_snapshots WHERE graph = ? ORDER BY updated_at ASC",
+                  [graph]
+                )
+              else
+                @db.execute("SELECT execution_id FROM execution_snapshots ORDER BY updated_at ASC")
+              end
+            rows.map { |row| row["execution_id"] }
+          end
+        end
+
+        def list_pending(graph: nil)
+          @mutex.synchronize do
+            rows =
+              if graph
+                @db.execute(
+                  "SELECT execution_id FROM execution_snapshots WHERE graph = ? AND pending = 1 ORDER BY updated_at ASC",
+                  [graph]
+                )
+              else
+                @db.execute("SELECT execution_id FROM execution_snapshots WHERE pending = 1 ORDER BY updated_at ASC")
+              end
+            rows.map { |row| row["execution_id"] }
+          end
+        end
+
+        def fetch(execution_id)
+          @mutex.synchronize do
+            row = @db.get_first_row(
+              "SELECT snapshot_json FROM execution_snapshots WHERE execution_id = ?",
+              [execution_id]
+            )
+            raise Igniter::ResolutionError, "No execution snapshot found for '#{execution_id}'" unless row
+
+            JSON.parse(row["snapshot_json"])
+          end
+        end
+
+        def delete(execution_id)
+          @mutex.synchronize do
+            @db.execute("DELETE FROM execution_snapshots WHERE execution_id = ?", [execution_id])
+          end
+        end
+
+        def exist?(execution_id)
+          @mutex.synchronize do
+            row = @db.get_first_row(
+              "SELECT 1 FROM execution_snapshots WHERE execution_id = ? LIMIT 1",
+              [execution_id]
+            )
+            !row.nil?
+          end
+        end
+
+        private
+
+        def create_schema!
+          @db.execute_batch(<<~SQL)
+            CREATE TABLE IF NOT EXISTS execution_snapshots (
+              execution_id TEXT PRIMARY KEY,
+              graph TEXT,
+              correlation_json TEXT,
+              pending INTEGER NOT NULL DEFAULT 0,
+              snapshot_json TEXT NOT NULL,
+              updated_at INTEGER NOT NULL
+            );
+            CREATE INDEX IF NOT EXISTS idx_execution_snapshots_graph
+              ON execution_snapshots(graph);
+            CREATE INDEX IF NOT EXISTS idx_execution_snapshots_pending
+              ON execution_snapshots(pending, updated_at);
+            CREATE INDEX IF NOT EXISTS idx_execution_snapshots_graph_correlation
+              ON execution_snapshots(graph, correlation_json);
+          SQL
+        end
+
+        def normalized_correlation_json(correlation)
+          return nil if correlation.nil? || correlation.empty?
+
+          JSON.generate(correlation.transform_keys(&:to_s).sort.to_h)
+        end
+
+        def pending_snapshot?(snapshot)
+          states = snapshot[:states] || snapshot["states"] || {}
+          states.any? do |_name, state|
+            status = state[:status] || state["status"]
+            status.to_s == "pending"
+          end
+        end
+
+        def prepare_path!(path)
+          return if path.to_s.empty? || path == ":memory:"
+
+          FileUtils.mkdir_p(::File.dirname(path))
+        end
+      end
+    end
+  end
+end

data/packages/igniter-core/lib/igniter/core/runtime/stream_result.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Runtime
+    class StreamResult < DeferredResult
+      def self.build(token: nil, payload: {}, source_node: nil, waiting_on: nil)
+        new(
+          token: token || SecureRandom.uuid,
+          payload: payload,
+          source_node: source_node,
+          waiting_on: waiting_on
+        )
+      end
+
+      def session
+        data = agent_session_data
+        return nil unless data
+
+        Runtime::AgentSession.from_h(data)
+      end
+
+      def agent_result_contract
+        Runtime::AgentResultContract.from_result(self, kind: :stream)
+      end
+
+      def phase
+        session&.phase || :streaming
+      end
+
+      def chunks
+        session&.chunks || []
+      end
+
+      def events
+        session&.events || []
+      end
+
+      def last_event
+        events.last
+      end
+
+      def status_events
+        events.select { |event| event[:type] == :status }
+      end
+
+      def statuses
+        status_events.filter_map { |event| event[:status] }
+      end
+
+      def tool_calls
+        events.select { |event| event[:type] == :tool_call }
+      end
+
+      def tool_results
+        events.select { |event| event[:type] == :tool_result }
+      end
+
+      def artifacts
+        events.select { |event| event[:type] == :artifact }
+      end
+
+      def final_event
+        events.reverse.find { |event| event[:type] == :final }
+      end
+
+      def tool_interactions
+        session&.tool_interactions || []
+      end
+
+      def pending_tool_interactions
+        session&.pending_tool_interactions || []
+      end
+
+      def completed_tool_interactions
+        session&.completed_tool_interactions || []
+      end
+
+      def orphan_tool_interactions
+        session&.orphan_tool_interactions || []
+      end
+
+      def all_tool_calls_resolved?
+        session ? session.all_tool_calls_resolved? : true
+      end
+
+      def tool_loop_consistent?
+        session ? session.tool_loop_consistent? : true
+      end
+
+      def tool_loop_complete?
+        session ? session.tool_loop_complete? : true
+      end
+
+      def tool_loop_status
+        session&.tool_loop_status || :idle
+      end
+
+      def tool_loop_summary
+        session&.tool_loop_summary || {
+          status: :idle,
+          total: 0,
+          pending: 0,
+          completed: 0,
+          orphaned: 0,
+          resolved: true,
+          consistent: true,
+          complete: true,
+          open_keys: [],
+          orphan_keys: []
+        }
+      end
+
+      def tool_runtime
+        session&.tool_runtime || {
+          status: :idle,
+          policy: nil,
+          finalizer: nil,
+          waiting_on: waiting_on,
+          interaction_count: 0,
+          pending_count: 0,
+          completed_count: 0,
+          orphaned_count: 0,
+          resolved: true,
+          consistent: true,
+          complete: true,
+          open_keys: [],
+          orphan_keys: [],
+          open_tools: [],
+          completed_tools: [],
+          orphan_tools: []
+        }.freeze
+      end
+
+      def last_chunk
+        chunks.last
+      end
+
+      def complete?
+        phase == :completed
+      end
+
+      def streaming?
+        !complete?
+      end
+
+      def to_h
+        super.merge(
+          type: :stream,
+          agent_result_contract: agent_result_contract&.to_h,
+          phase: phase,
+          events: events,
+          event_count: events.size,
+          status_count: status_events.size,
+          tool_call_count: tool_calls.size,
+          tool_result_count: tool_results.size,
+          tool_interaction_count: tool_interactions.size,
+          pending_tool_interaction_count: pending_tool_interactions.size,
+          completed_tool_interaction_count: completed_tool_interactions.size,
+          orphan_tool_interaction_count: orphan_tool_interactions.size,
+          tool_loop_status: tool_loop_status,
+          tool_loop_complete: tool_loop_complete?,
+          tool_loop_summary: tool_loop_summary,
+          tool_runtime: tool_runtime,
+          artifact_count: artifacts.size,
+          chunks: chunks,
+          chunk_count: chunks.size
+        )
+      end
+    end
+  end
+end

data/{lib/igniter → packages/igniter-core/lib/igniter/core}/runtime.rb

@@ -3,6 +3,13 @@
 require_relative "runtime/node_state"
 require_relative "runtime/cache"
 require_relative "runtime/deferred_result"
+require_relative "runtime/stream_result"
+require_relative "runtime/agent_session"
+require_relative "runtime/agent_result_contract"
+require_relative "runtime/agent_session_query"
+require_relative "runtime/orchestration_runtime_state"
+require_relative "runtime/orchestration_transition_query"
+require_relative "runtime/orchestration_overview"
 require_relative "runtime/collection_result"
 require_relative "runtime/input_validator"
 require_relative "runtime/planner"
@@ -14,7 +21,14 @@ require_relative "runtime/stores/active_record_store"
 require_relative "runtime/stores/file_store"
 require_relative "runtime/stores/memory_store"
 require_relative "runtime/stores/redis_store"
+require_relative "runtime/stores/sqlite_store"
 require_relative "runtime/runner_factory"
+require_relative "runtime/remote_adapter"
+require_relative "runtime/agent_adapter"
+require_relative "runtime/agent_route"
+require_relative "runtime/agent_route_resolver"
+require_relative "runtime/agent_transport"
+require_relative "runtime/proxy_agent_adapter"
 require_relative "runtime/resolver"
 require_relative "runtime/invalidator"
 require_relative "runtime/result"
@@ -22,5 +36,6 @@ require_relative "runtime/execution"
 
 module Igniter
   module Runtime
+    ConfigurationError = Class.new(Igniter::Error)
   end
 end

data/packages/igniter-core/lib/igniter/core/temporal.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Igniter
+  # Mixin for time-aware contracts.
+  #
+  # Including Igniter::Temporal in a Contract automatically injects an `as_of`
+  # input (default: Time.now) and provides the `temporal_compute` DSL helper,
+  # which adds `:as_of` to a node's dependencies automatically.
+  #
+  # The key property of a temporal contract: if ALL time-varying nodes depend on
+  # `as_of`, any historical execution is fully reproducible — just supply the
+  # original timestamp as the `as_of` input.
+  #
+  # == Usage
+  #
+  #   require "igniter/core/temporal"
+  #
+  #   class TaxRateContract < Igniter::Contract
+  #     include Igniter::Temporal
+  #
+  #     define do
+  #       input :country
+  #       # `as_of` is injected automatically (default: Time.now)
+  #
+  #       temporal_compute :tax_rate, depends_on: :country do |country:, as_of:|
+  #         HistoricalTaxRates.lookup(country: country, date: as_of.to_date)
+  #       end
+  #
+  #       output :tax_rate
+  #     end
+  #   end
+  #
+  #   # Current rates:
+  #   TaxRateContract.new(country: "UA").result.tax_rate
+  #
+  #   # Reproduce a historical result:
+  #   TaxRateContract.new(country: "UA", as_of: Time.new(2024, 1, 1)).result.tax_rate
+  #
+  # == TemporalExecutor
+  #
+  # For class-based executors in temporal contracts, inherit from
+  # Igniter::Temporal::Executor. It ensures `as_of:` is always passed as
+  # a keyword argument by the resolver.
+  #
+  #   class TaxRateExecutor < Igniter::Temporal::Executor
+  #     def call(country:, as_of:)
+  #       HistoricalTaxRates.lookup(country: country, date: as_of.to_date)
+  #     end
+  #   end
+  module Temporal
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # Returns true for contracts that include Temporal.
+      def temporal? = true
+
+      # Override define to inject `as_of` and the `temporal_compute` builder helper
+      # before the user's block runs.
+      def define(&user_block)
+        super do
+          # Inject temporal input first so it can be used as a dependency.
+          input :as_of, default: -> { Time.now }
+
+          # Add `temporal_compute` as a convenience method on this builder instance.
+          # It behaves like `compute` but automatically adds `:as_of` to depends_on.
+          define_singleton_method(:temporal_compute) do |name, depends_on: [], **opts, &blk|
+            deps = (Array(depends_on) | [:as_of])
+            compute(name, depends_on: deps, **opts, &blk)
+          end
+
+          instance_eval(&user_block)
+        end
+      end
+    end
+
+    # Base executor for temporal compute nodes.
+    # Inheriting from this signals that the executor expects `as_of:` among its kwargs.
+    class Executor < Igniter::Executor
+      # Subclasses must implement: def call(**deps_including_as_of)
+    end
+  end
+end

data/packages/igniter-core/lib/igniter/core/tool/discoverable.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Igniter
+  class Tool
+    # Shared discovery DSL included by both +Igniter::Tool+ and +Igniter::AI::Skill+.
+    #
+    # Provides: +description+, +param+, +requires_capability+, +tool_name+,
+    # +to_schema+, and the instance-side +call_with_capability_check!+.
+    #
+    # Classes that include this module must call +copy_discoverable_state_to(subclass)+
+    # inside their own +inherited+ hook so the metadata propagates to subclasses.
+    module Discoverable
+      # Ruby type → JSON Schema type string
+      JSON_TYPES = {
+        string: "string", str: "string",
+        integer: "integer", int: "integer",
+        float: "number", number: "number",
+        boolean: "boolean", bool: "boolean",
+        array: "array",
+        object: "object",
+      }.freeze
+
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.instance_variable_set(:@tool_params, [])
+        base.instance_variable_set(:@required_capabilities, [].freeze)
+      end
+
+      # ── Class-level DSL ────────────────────────────────────────────────────
+      module ClassMethods
+        # Describe what the tool/skill does. Sent to the LLM as part of its schema.
+        def description(text = nil)
+          text ? (@tool_description = text.freeze) : @tool_description
+        end
+
+        # Declare an LLM-visible input parameter.
+        #
+        # @param name     [Symbol]  parameter name (keyword arg in #call)
+        # @param type     [Symbol]  :string, :integer, :float, :boolean, :array, :object
+        # @param required [Boolean] whether the LLM must supply this value
+        # @param default  [Object]  informational default (not enforced at call-time)
+        # @param desc     [String]  short description for the LLM
+        def param(name, type:, required: false, default: nil, desc: nil)
+          tool_params << {
+            name:     name.to_sym,
+            type:     type.to_sym,
+            required: required,
+            default:  default,
+            desc:     desc.to_s,
+          }.freeze
+        end
+
+        # Declare capabilities the calling agent must have before this tool/skill
+        # is allowed to run. +CapabilityError+ is raised before +#call+ if any
+        # required capability is missing from the agent's +declared_capabilities+.
+        def requires_capability(*caps)
+          @required_capabilities = caps.flatten.map(&:to_sym).freeze
+        end
+
+        # ── Read-only accessors ──────────────────────────────────────────────
+
+        def tool_params
+          @tool_params ||= []
+        end
+
+        def required_capabilities
+          @required_capabilities || [].freeze
+        end
+
+        # Snake-case name derived from the class name (last namespace component).
+        #
+        #   class SearchWebTool < Igniter::Tool  →  "search_web_tool"
+        #   class ResearchSkill < Igniter::AI::Skill →  "research_skill"
+        def tool_name
+          n = name.to_s.split("::").last
+          return "anonymous" if n.nil? || n.empty?
+
+          n.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+           .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+           .downcase
+        end
+
+        # Generate a tool schema for the given provider.
+        # With no argument returns the provider-agnostic intermediate format
+        # (used internally and processed by each provider's +normalize_tools+).
+        #
+        # @param provider [Symbol, nil] :anthropic, :openai, or nil for intermediate
+        # @return [Hash]
+        def to_schema(provider = nil)
+          case provider&.to_sym
+          when :anthropic
+            { name: tool_name, description: description.to_s, input_schema: json_schema }
+          when :openai
+            {
+              type: "function",
+              function: { name: tool_name, description: description.to_s, parameters: json_schema },
+            }
+          else
+            { name: tool_name, description: description.to_s, parameters: json_schema }
+          end
+        end
+
+        # Call this in +inherited+ to propagate discoverable metadata to subclasses.
+        # Each class using this module is responsible for calling this in its own
+        # +inherited+ hook (alongside any chain-specific super calls).
+        def copy_discoverable_state_to(subclass)
+          subclass.instance_variable_set(:@tool_params, @tool_params&.dup || [])
+          subclass.instance_variable_set(:@required_capabilities, @required_capabilities&.dup || [].freeze)
+          subclass.instance_variable_set(:@tool_description, @tool_description)
+        end
+
+        private
+
+        def json_schema
+          required_names = tool_params.select { |p| p[:required] }.map { |p| p[:name].to_s }
+          properties = tool_params.each_with_object({}) do |p, h|
+            prop = { "type" => JSON_TYPES.fetch(p[:type], "string") }
+            prop["description"] = p[:desc] unless p[:desc].empty?
+            prop["default"] = p[:default] unless p[:default].nil?
+            h[p[:name].to_s] = prop
+          end
+
+          schema = { "type" => "object", "properties" => properties }
+          schema["required"] = required_names unless required_names.empty?
+          schema
+        end
+      end
+
+      # ── Instance — capability-guarded call ──────────────────────────────────
+
+      # Verify the agent has all required capabilities, then invoke +#call+.
+      # Called by +AI::Executor+ during the tool-use loop for every tool/skill invocation.
+      #
+      # @param allowed_capabilities [Array<Symbol>] capabilities the calling agent has
+      # @raise [Igniter::Tool::CapabilityError] if a required capability is missing
+      def call_with_capability_check!(allowed_capabilities:, **kwargs)
+        required = self.class.required_capabilities
+        unless required.empty?
+          allowed = allowed_capabilities.map(&:to_sym)
+          missing = required.reject { |c| allowed.include?(c) }
+          unless missing.empty?
+            raise Igniter::Tool::CapabilityError,
+                  "Tool #{self.class.tool_name.inspect} requires capabilities " \
+                  "#{missing.inspect} but agent only has #{allowed.inspect}"
+          end
+        end
+        call(**kwargs)
+      end
+    end
+  end
+end