igniter 0.5.0 → 0.5.2

data/lib/igniter/supervisor.rb

@@ -1,167 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  # Supervises a group of agents and restarts them when they crash.
-  #
-  # Subclass Supervisor and declare children with the class-level DSL:
-  #
-  #   class AppSupervisor < Igniter::Supervisor
-  #     strategy     :one_for_one   # default
-  #     max_restarts 5, within: 60  # default
-  #
-  #     children do |c|
-  #       c.worker :counter, CounterAgent
-  #       c.worker :logger,  LoggerAgent, initial_state: { level: :info }
-  #     end
-  #   end
-  #
-  #   sup = AppSupervisor.start
-  #   sup.child(:counter).send(:increment, by: 1)
-  #   sup.stop
-  #
-  # Restart strategies:
-  #   :one_for_one  — restart only the crashed agent (default)
-  #   :one_for_all  — stop all agents and restart them all when any one crashes
-  #
-  # Restart budget: if more than +max_restarts+ crashes happen within +within+
-  # seconds, the supervisor logs the failure and stops trying to restart.
-  #
-  class Supervisor
-    class RestartBudgetExceeded < Igniter::Error; end
-
-    # ── ChildSpec ────────────────────────────────────────────────────────────
-
-    ChildSpec = Struct.new(:name, :agent_class, :init_opts, keyword_init: true)
-
-    class ChildSpecBuilder
-      attr_reader :specs
-
-      def initialize
-        @specs = []
-      end
-
-      def worker(name, agent_class, **opts)
-        @specs << ChildSpec.new(name: name.to_sym, agent_class: agent_class, init_opts: opts)
-      end
-    end
-
-    # ── Class-level defaults ─────────────────────────────────────────────────
-
-    @strategy        = :one_for_one
-    @max_restarts    = 5
-    @restart_window  = 60
-    @spec_builder    = ChildSpecBuilder.new
-
-    class << self
-      def inherited(subclass)
-        super
-        subclass.instance_variable_set(:@strategy,       :one_for_one)
-        subclass.instance_variable_set(:@max_restarts,   5)
-        subclass.instance_variable_set(:@restart_window, 60)
-        subclass.instance_variable_set(:@spec_builder,   ChildSpecBuilder.new)
-      end
-
-      def strategy(sym)
-        @strategy = sym
-      end
-
-      def max_restarts(count, within:)
-        @max_restarts   = count
-        @restart_window = within
-      end
-
-      def children(&block)
-        block.call(@spec_builder)
-      end
-
-      def child_specs
-        @spec_builder.specs
-      end
-
-      def start
-        new.tap(&:start_all)
-      end
-    end
-
-    # ── Instance ─────────────────────────────────────────────────────────────
-
-    def initialize
-      @refs          = {}
-      @specs_by_name = {}
-      @restart_log   = []
-      @mutex         = Mutex.new
-    end
-
-    def start_all
-      self.class.child_specs.each do |spec|
-        @specs_by_name[spec.name] = spec
-        start_child(spec)
-      end
-    end
-
-    # Return the Ref for a named child. Returns nil if not found.
-    def child(name)
-      @mutex.synchronize { @refs[name.to_sym] }
-    end
-
-    # Stop all children gracefully.
-    def stop
-      refs = @mutex.synchronize { @refs.values.dup }
-      refs.each do |ref|
-        ref.stop
-      rescue StandardError
-        nil
-      end
-      self
-    end
-
-    private
-
-    def start_child(spec)
-      opts = spec.init_opts.dup
-      opts[:on_crash] = ->(error) { handle_crash(spec, error) }
-      ref = spec.agent_class.start(**opts)
-      @mutex.synchronize { @refs[spec.name] = ref }
-      ref
-    end
-
-    def handle_crash(spec, _error)
-      check_restart_budget!
-
-      case self.class.instance_variable_get(:@strategy)
-      when :one_for_one
-        start_child(spec)
-      when :one_for_all
-        stop_all_children
-        self.class.child_specs.each { |s| start_child(s) }
-      end
-    rescue RestartBudgetExceeded => e
-      warn "Igniter::Supervisor #{self.class.name}: #{e.message}"
-    end
-
-    def check_restart_budget! # rubocop:disable Metrics/MethodLength
-      now    = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      window = self.class.instance_variable_get(:@restart_window).to_f
-      max    = self.class.instance_variable_get(:@max_restarts)
-
-      @mutex.synchronize do
-        @restart_log.reject! { |t| now - t > window }
-        @restart_log << now
-
-        if @restart_log.size > max
-          raise RestartBudgetExceeded,
-                "#{@restart_log.size} crashes in #{window}s (max=#{max})"
-        end
-      end
-    end
-
-    def stop_all_children
-      refs = @mutex.synchronize { @refs.values.dup }
-      refs.each do |ref|
-        ref.stop(timeout: 2)
-      rescue StandardError
-        nil
-      end
-    end
-  end
-end

data/lib/igniter/temporal.rb

@@ -1,84 +0,0 @@
-# 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/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/lib/igniter/tool/discoverable.rb

@@ -1,151 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  class Tool
-    # Shared discovery DSL included by both +Igniter::Tool+ and +Igniter::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::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 +LLM::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

data/lib/igniter/tool.rb

@@ -1,52 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  # Base class for AI-callable tools.
-  #
-  # Extends +Igniter::Executor+ with declarative metadata for LLM function-calling
-  # (Anthropic, OpenAI) and capability-based access guards.
-  # Shares the discovery DSL with +Igniter::Skill+ via +Tool::Discoverable+.
-  #
-  # == Defining a tool
-  #
-  #   class SearchWeb < Igniter::Tool
-  #     description "Search the internet for current information"
-  #
-  #     param :query,       type: :string,  required: true,  desc: "The search query"
-  #     param :max_results, type: :integer, default: 5,      desc: "Max results to return"
-  #
-  #     requires_capability :web_access
-  #
-  #     def call(query:, max_results: 5)
-  #       [{ title: "...", url: "...", snippet: "..." }]
-  #     end
-  #   end
-  #
-  # == Schema generation
-  #
-  #   SearchWeb.tool_name             # => "search_web"
-  #   SearchWeb.to_schema             # => { name:, description:, parameters: { ... } }
-  #   SearchWeb.to_schema(:anthropic) # => { name:, description:, input_schema: { ... } }
-  #   SearchWeb.to_schema(:openai)    # => { type: "function", function: { ... } }
-  #
-  # == Compatibility
-  #
-  # Tool inherits +Igniter::Executor+ — usable as a compute node in any Contract graph.
-  class Tool < Executor
-    # Raised when a tool or skill requires a capability the calling agent does not have.
-    # Also aliased as +Igniter::Skill::CapabilityError+.
-    class CapabilityError < Igniter::Error; end
-
-    require_relative "tool/discoverable"
-    include Discoverable
-
-    def self.inherited(subclass)
-      super
-      # Tool subclasses always start with empty params and capabilities —
-      # each concrete tool declares its own. Only the description carries forward.
-      subclass.instance_variable_set(:@tool_params, [])
-      subclass.instance_variable_set(:@required_capabilities, [].freeze)
-      subclass.instance_variable_set(:@tool_description, @tool_description)
-    end
-  end
-end

data/lib/igniter/tool_registry.rb

@@ -1,144 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "tool"
-require_relative "skill"
-
-module Igniter
-  # Global registry for Igniter::Tool and Igniter::Skill classes.
-  #
-  # Both Tools (atomic operations) and Skills (agentic sub-processes) share the
-  # same discovery interface and are registered the same way. The registry does
-  # not distinguish between them — from a caller's perspective both are callable
-  # units described by name, description, and a parameter schema.
-  #
-  # == Scopes
-  #
-  # Every entry belongs to one of three scopes:
-  #   :bundled   — shipped with the core library
-  #   :managed   — installed from an external registry or package manager
-  #   :workspace — local, app-specific (default)
-  #
-  # Scope does not affect capability filtering or schema generation unless you
-  # pass +scope:+ explicitly. All existing calls without +scope:+ continue to
-  # work exactly as before.
-  #
-  # == Registration
-  #
-  #   Igniter::ToolRegistry.register(SearchWeb, WriteFile, ResearchSkill)
-  #   Igniter::ToolRegistry.register(WeatherTool, scope: :bundled)
-  #
-  # == Discovery
-  #
-  #   Igniter::ToolRegistry.all
-  #   # => [SearchWeb, WriteFile, ResearchSkill, WeatherTool]
-  #
-  #   Igniter::ToolRegistry.all(scope: :bundled)
-  #   # => [WeatherTool]
-  #
-  #   Igniter::ToolRegistry.tools_for(capabilities: [:web_access])
-  #   Igniter::ToolRegistry.tools_for(capabilities: [:web_access], scope: :workspace)
-  #
-  # == Schema generation
-  #
-  #   Igniter::ToolRegistry.schemas(:anthropic)
-  #   Igniter::ToolRegistry.schemas(:openai, capabilities: [:web_access], scope: :managed)
-  module ToolRegistry
-    # Valid scope identifiers, ordered from least to most specific.
-    SCOPES = %i[bundled managed workspace].freeze
-
-    # Internal store: { tool_name_string => { klass: Class, scope: Symbol } }
-    @tools = {}
-
-    class << self
-      # Register one or more Tool or Skill subclasses.
-      #
-      # @param tool_classes [Array<Class>] Tool or Skill subclasses
-      # @param scope        [Symbol]       :bundled, :managed, or :workspace (default)
-      # @raise [ArgumentError] if a class is not discoverable or scope is invalid
-      def register(*tool_classes, scope: :workspace) # rubocop:disable Metrics/MethodLength
-        unless SCOPES.include?(scope)
-          raise ArgumentError, "Invalid scope #{scope.inspect}. Must be one of #{SCOPES.inspect}"
-        end
-
-        tool_classes.flatten.each do |klass|
-          unless discoverable?(klass)
-            raise ArgumentError,
-                  "#{klass.inspect} must be an Igniter::Tool or Igniter::Skill subclass"
-          end
-
-          @tools[klass.tool_name] = { klass: klass, scope: scope }
-        end
-        self
-      end
-
-      # Look up a tool or skill by its snake_case name.
-      # @param name [String, Symbol]
-      # @return [Class, nil]
-      def find(name)
-        @tools[name.to_s]&.fetch(:klass)
-      end
-
-      # All registered classes, optionally filtered by scope.
-      #
-      # @param scope [Symbol, nil] :bundled, :managed, :workspace, or nil for all
-      # @return [Array<Class>]
-      def all(scope: nil)
-        entries_for(scope).map { |e| e[:klass] }
-      end
-
-      # Classes whose required capabilities are fully covered by +capabilities+.
-      # Tools/skills with no required capabilities are always included.
-      #
-      # @param capabilities [Array<Symbol>]
-      # @param scope        [Symbol, nil]
-      # @return [Array<Class>]
-      def tools_for(capabilities: [], scope: nil)
-        allowed  = capabilities.map(&:to_sym).to_set
-        matching = entries_for(scope).select do |e|
-          e[:klass].required_capabilities.all? { |c| allowed.include?(c) }
-        end
-        matching.map { |e| e[:klass] }
-      end
-
-      # Generate schemas for the given provider.
-      # Optionally filter by capabilities and/or scope.
-      #
-      # @param provider      [Symbol]        :anthropic, :openai, or nil for intermediate
-      # @param capabilities  [Array<Symbol>] optional capability filter
-      # @param scope         [Symbol, nil]   optional scope filter
-      # @return [Array<Hash>]
-      def schemas(provider = nil, capabilities: nil, scope: nil)
-        list = if capabilities
-                 tools_for(capabilities: capabilities, scope: scope)
-               else
-                 all(scope: scope)
-               end
-        list.map { |klass| klass.to_schema(provider) }
-      end
-
-      # Number of registered classes (across all scopes).
-      def size = @tools.size
-
-      # True if nothing is registered.
-      def empty? = @tools.empty?
-
-      # Remove all registrations (primarily for tests).
-      def clear!
-        @tools = {}
-        self
-      end
-
-      private
-
-      def entries_for(scope)
-        scope ? @tools.values.select { |e| e[:scope] == scope } : @tools.values
-      end
-
-      # A class is discoverable if it is a Tool or Skill (includes Tool::Discoverable).
-      def discoverable?(klass)
-        klass.is_a?(Class) &&
-          (klass < Igniter::Tool || klass < Igniter::Skill)
-      end
-    end
-  end
-end

data/lib/igniter/type_system.rb

@@ -1,44 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module TypeSystem
-    SUPPORTED_TYPES = {
-      integer: Integer,
-      float: Float,
-      numeric: Numeric,
-      string: String,
-      boolean: :boolean,
-      array: Array,
-      hash: Hash,
-      symbol: Symbol,
-      result: :result
-    }.freeze
-
-    module_function
-
-    def supported?(type)
-      return false unless type
-
-      SUPPORTED_TYPES.key?(type.to_sym)
-    end
-
-    def compatible?(source_type, target_type)
-      return true if source_type.nil? || target_type.nil?
-
-      source = source_type.to_sym
-      target = target_type.to_sym
-      return true if source == target
-      return true if %i[integer float].include?(source) && target == :numeric
-
-      false
-    end
-
-    def match?(type, value)
-      matcher = SUPPORTED_TYPES.fetch(type.to_sym)
-      return false if matcher == :result
-      return value == true || value == false if matcher == :boolean
-
-      value.is_a?(matcher)
-    end
-  end
-end