igniter 0.5.0 → 0.5.2

data/lib/igniter/server.rb

@@ -1,73 +0,0 @@
-# frozen_string_literal: true
-
-require "igniter"
-require "json"
-
-# Define the top-level Server module and Error class first,
-# so subfiles can inherit from Igniter::Server::Error.
-module Igniter
-  module Server
-    class Error < Igniter::Error; end
-  end
-end
-
-require_relative "server/registry"
-require_relative "server/server_logger"
-require_relative "server/config"
-require_relative "server/router"
-require_relative "server/http_server"
-require_relative "server/rack_app"
-require_relative "server/client"
-require_relative "server/handlers/base"
-require_relative "server/handlers/health_handler"
-require_relative "server/handlers/contracts_handler"
-require_relative "server/handlers/execute_handler"
-require_relative "server/handlers/event_handler"
-require_relative "server/handlers/status_handler"
-require_relative "server/handlers/liveness_handler"
-require_relative "server/handlers/readiness_handler"
-require_relative "server/handlers/metrics_handler"
-require_relative "server/handlers/manifest_handler"
-require_relative "server/handlers/peers_handler"
-
-module Igniter
-  module Server
-    class << self
-      def config
-        @config ||= Config.new
-      end
-
-      def configure
-        yield config
-        self
-      end
-
-      # Start the built-in HTTP server (blocking).
-      def start(**options)
-        apply_options!(options)
-        HttpServer.new(config).start
-      end
-
-      # Return a Rack-compatible application for use with Puma/Unicorn/etc.
-      def rack_app
-        RackApp.new(config)
-      end
-
-      # Reset configuration (useful in tests).
-      def reset!
-        @config = nil
-      end
-
-      private
-
-      def apply_options!(options) # rubocop:disable Metrics/AbcSize
-        config.port  = options[:port]  if options[:port]
-        config.host  = options[:host]  if options[:host]
-        config.store = options[:store] if options[:store]
-        return unless options[:contracts].is_a?(Hash)
-
-        options[:contracts].each { |name, klass| config.register(name.to_s, klass) }
-      end
-    end
-  end
-end

data/lib/igniter/skill/feedback.rb

@@ -1,116 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  class Skill
-    # Immutable record of one rated invocation of a Skill.
-    FeedbackEntry = Struct.new(
-      :input,      # String — the prompt that was sent to the LLM
-      :output,     # String — the response that was returned
-      :rating,     # Symbol — :good, :bad, or :neutral
-      :notes,      # String, nil — optional human comment
-      :timestamp,  # Time
-      keyword_init: true
-    ) do
-      def initialize(**)
-        super
-        freeze
-      end
-    end
-
-    # Thread-safe in-memory store for feedback entries.
-    module FeedbackStore
-      class Memory
-        MAX_SIZE = 500
-
-        def initialize
-          @entries = []
-          @mutex   = Mutex.new
-        end
-
-        def store(entry)
-          @mutex.synchronize do
-            @entries << entry
-            @entries.shift if @entries.size > MAX_SIZE
-          end
-          self
-        end
-
-        def all
-          @mutex.synchronize { @entries.dup }
-        end
-
-        def size
-          @mutex.synchronize { @entries.size }
-        end
-
-        def empty?
-          size.zero?
-        end
-
-        def by_rating(rating)
-          all.select { |e| e.rating == rating.to_sym }
-        end
-
-        def clear
-          @mutex.synchronize { @entries.clear }
-          self
-        end
-      end
-    end
-
-    # Generates an improved system prompt from accumulated feedback.
-    #
-    # Uses the skill's own LLM provider to propose changes. Returns a plain
-    # String — it does NOT mutate any class-level state. The caller decides
-    # whether to adopt the refined prompt.
-    #
-    # == Usage
-    #
-    #   improved = skill.refine_system_prompt
-    #   # Inspect it, then use it:
-    #   MySkill.system_prompt improved
-    class FeedbackRefiner
-      TEMPLATE = <<~PROMPT
-        You are improving a system prompt for an AI skill based on user feedback.
-        Return ONLY the improved system prompt text, with no explanation or preamble.
-
-        Current system prompt:
-        %<current>s
-
-        %<feedback>s
-      PROMPT
-
-      def initialize(provider_instance, model)
-        @provider = provider_instance
-        @model    = model
-      end
-
-      # @param current_prompt [String]
-      # @param entries        [Array<FeedbackEntry>]
-      # @return [String] the refined system prompt
-      def refine(current_prompt, entries) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
-        return current_prompt if entries.empty?
-
-        good = entries.select { |e| e.rating == :good }
-                      .filter_map { |e| e.notes && "✓ #{e.notes}" }
-                      .join("\n")
-
-        bad = entries.select { |e| e.rating == :bad }
-                     .filter_map { |e| e.notes && "✗ #{e.notes}" }
-                     .join("\n")
-
-        parts = []
-        parts << "Positive feedback (preserve these qualities):\n#{good}" unless good.empty?
-        parts << "Negative feedback (address these issues):\n#{bad}"      unless bad.empty?
-
-        return current_prompt if parts.empty?
-
-        prompt = format(TEMPLATE, current: current_prompt, feedback: parts.join("\n\n"))
-        @provider.chat(
-          messages: [{ role: "user", content: prompt }],
-          model: @model
-        )[:content]
-      end
-    end
-  end
-end

data/lib/igniter/skill/output_schema.rb

@@ -1,110 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-
-module Igniter
-  class Skill
-    # DSL for declaring a typed JSON output contract on a Skill.
-    #
-    # When an +output_schema+ block is given, the Skill automatically:
-    #   1. Appends a JSON instruction to every prompt sent to the LLM.
-    #   2. Parses the LLM response as JSON on return.
-    #   3. Wraps the parsed data in a +StructuredResult+ with field readers.
-    #
-    # == Definition
-    #
-    #   class AnalysisSkill < Igniter::Skill
-    #     output_schema do
-    #       field :summary,    String
-    #       field :confidence, Float
-    #       field :sources,    Array
-    #     end
-    #   end
-    #
-    # == Usage
-    #
-    #   result = AnalysisSkill.call(document: "...")
-    #   result.summary     # => "This document covers..."
-    #   result.confidence  # => 0.91
-    #   result.to_h        # => { summary: "...", confidence: 0.91, sources: [...] }
-    class OutputSchema
-      # Raised when the LLM response cannot be parsed into the declared schema.
-      class ParseError < Igniter::Error; end
-
-      # Maps Ruby constant types to JSON Schema type strings.
-      TYPE_MAP = {
-        String => "string",
-        Integer => "number",
-        Float => "number",
-        Array => "array",
-        Hash => "object"
-      }.freeze
-
-      Field = Struct.new(:name, :type, keyword_init: true)
-
-      def initialize(&block)
-        @fields = []
-        instance_eval(&block) if block
-      end
-
-      # Declare a field in the output schema.
-      # @param name [Symbol, String] field name
-      # @param type [Class]          expected Ruby type (String, Integer, Float, Array, Hash)
-      def field(name, type)
-        @fields << Field.new(name: name.to_sym, type: type)
-        self
-      end
-
-      # Frozen array of declared fields.
-      def fields
-        @fields.dup
-      end
-
-      # Human-readable JSON description injected into the prompt.
-      # Example: { "summary": string, "confidence": number }
-      def to_json_description
-        pairs = @fields.map { |f| "\"#{f.name}\": #{TYPE_MAP.fetch(f.type, "string")}" }
-        "{ #{pairs.join(", ")} }"
-      end
-
-      # Parse LLM response text into a +StructuredResult+.
-      # Extracts the first JSON object found in +text+.
-      #
-      # @param text [String] raw LLM response
-      # @return [StructuredResult]
-      # @raise [ParseError] if no JSON object is found or JSON is invalid
-      def parse(text)
-        json_str = text.match(/\{.*\}/m)&.to_s
-        raise ParseError, "No JSON object found in LLM response" unless json_str
-
-        data = JSON.parse(json_str)
-        StructuredResult.new(@fields, data)
-      rescue JSON::ParserError => e
-        raise ParseError, "Invalid JSON in LLM response: #{e.message}"
-      end
-    end
-
-    # A typed result object returned by skills with an +output_schema+.
-    # Provides reader methods for each declared field plus +to_h+ / +to_json+.
-    class StructuredResult
-      def initialize(fields, data)
-        @fields = fields
-        @data   = data.transform_keys(&:to_sym)
-        fields.each { |f| define_singleton_method(f.name) { @data[f.name] } }
-      end
-
-      # Returns a plain Hash keyed by field names (symbols).
-      def to_h
-        @fields.each_with_object({}) { |f, h| h[f.name] = @data[f.name] }
-      end
-
-      def to_json(*args)
-        to_h.to_json(*args)
-      end
-
-      def inspect
-        "#<Igniter::Skill::StructuredResult #{to_h}>"
-      end
-    end
-  end
-end

data/lib/igniter/skill.rb

@@ -1,218 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "tool"
-require_relative "integrations/llm/executor"
-
-module Igniter
-  # Base class for AI-callable skills — composable units of agent capability.
-  #
-  # A +Skill+ is both discoverable (LLM can call it like a Tool) and agentic
-  # (it runs its own LLM reasoning loop with its own set of tools).
-  # Use Skills when a single tool call is not enough: the task requires planning,
-  # multi-step tool use, or internal LLM reasoning.
-  #
-  # == Tool vs Skill
-  #
-  # +Tool+  — atomic operation, single call, stateless, fast.
-  # +Skill+ — multi-step process, own LLM loop, own tools, may take seconds.
-  #
-  # From the parent agent's perspective both look identical: they share the same
-  # discovery interface (+description+, +param+, +to_schema+, +requires_capability+)
-  # and are registered in +ToolRegistry+ the same way.
-  #
-  # == Defining a skill
-  #
-  #   class ResearchSkill < Igniter::Skill
-  #     description "Research a topic by searching and synthesizing multiple sources"
-  #
-  #     param :topic, type: :string, required: true,
-  #                   desc: "Subject to research"
-  #
-  #     requires_capability :network
-  #
-  #     provider :anthropic
-  #     model "claude-sonnet-4-6"
-  #     tools SearchWebTool, ReadUrlTool   # skill's own sub-tools
-  #     max_tool_iterations 8
-  #
-  #     def call(topic:)
-  #       complete("Research this thoroughly: #{topic}")
-  #       # ↑ runs sub-tool loop internally; returns plain-text summary
-  #     end
-  #   end
-  #
-  # == Structured output
-  #
-  #   class AnalysisSkill < Igniter::Skill
-  #     output_schema do
-  #       field :summary,    String
-  #       field :confidence, Float
-  #     end
-  #
-  #     def call(document:)
-  #       complete("Analyse: #{document}")
-  #       # Returns StructuredResult, not a plain String
-  #     end
-  #   end
-  #
-  # == Feedback loop
-  #
-  #   class MySkill < Igniter::Skill
-  #     feedback_enabled true
-  #     feedback_store   :memory
-  #
-  #     def call(prompt:) = complete(prompt)
-  #   end
-  #
-  #   result = MySkill.call(prompt: "...")
-  #   MySkill.new.feedback(result, rating: :good, notes: "Very helpful")
-  #   improved = MySkill.new.refine_system_prompt
-  #
-  # == Hierarchical agents
-  #
-  #   class ChatExecutor < Igniter::LLM::Executor
-  #     tools TimeTool, WeatherTool,
-  #           ResearchSkill,   # ← parent sees this as a Tool
-  #           WriteCodeSkill   # ← parent sees this as a Tool
-  #   end
-  #
-  # == Schema + registry
-  #
-  #   ResearchSkill.tool_name          # => "research_skill"
-  #   ResearchSkill.to_schema          # => { name:, description:, parameters: { ... } }
-  #   Igniter::ToolRegistry.register(ResearchSkill)
-  class Skill < LLM::Executor
-    # CapabilityError is the same class as Tool::CapabilityError.
-    # Defined here as an alias for convenience and symmetry.
-    CapabilityError = Tool::CapabilityError
-
-    include Tool::Discoverable
-
-    class << self
-      # Propagate BOTH the LLM executor config (via super → LLM::Executor.inherited)
-      # AND the Discoverable metadata to every subclass.
-      # Note: @feedback_store is intentionally NOT copied — each class owns its store.
-      def inherited(subclass)
-        super
-        subclass.instance_variable_set(:@output_schema, @output_schema)
-        subclass.instance_variable_set(:@feedback_enabled, @feedback_enabled)
-        copy_discoverable_state_to(subclass)
-      end
-
-      # Declare a typed JSON output schema for this skill.
-      #
-      # When a block is given, creates an +OutputSchema+ and stores it.
-      # Calling +complete+ inside +call+ will then inject a JSON instruction
-      # into the prompt and return a +StructuredResult+ instead of a String.
-      #
-      # Without a block, falls back to the inherited +Executor#output_schema+
-      # metadata getter/setter for backward compatibility.
-      #
-      # @example
-      #   output_schema do
-      #     field :summary,    String
-      #     field :confidence, Float
-      #     field :sources,    Array
-      #   end
-      def output_schema(value = nil, &block)
-        if block
-          @output_schema = Skill::OutputSchema.new(&block)
-        elsif value
-          super(value)             # Executor metadata setter (backward compat)
-        else
-          @output_schema || super  # new DSL ivar or executor_metadata fallback
-        end
-      end
-
-      # Enable or query feedback collection for this skill.
-      # When enabled, +#feedback+ stores entries in the configured store.
-      #
-      # @param val [Boolean, nil] pass true/false to set; nil to get
-      def feedback_enabled(val = nil)
-        val.nil? ? (@feedback_enabled || false) : (@feedback_enabled = val)
-      end
-
-      # Set or get the feedback store for this skill.
-      #
-      # Pass +:memory+ to create a new in-memory store (one per class).
-      # Pass any object responding to +#store+, +#all+, and +#clear+ to use a custom store.
-      #
-      # Note: the store is NOT inherited by subclasses — each class has its own.
-      #
-      # @param val [:memory, #store, nil]
-      def feedback_store(val = nil)
-        return @feedback_store if val.nil?
-
-        @feedback_store = val == :memory ? Skill::FeedbackStore::Memory.new : val
-      end
-    end
-
-    protected
-
-    # Override LLM::Executor#complete to inject a JSON instruction when an
-    # +OutputSchema+ is declared, and parse the response into a +StructuredResult+.
-    def complete(prompt, context: nil)
-      schema = self.class.output_schema
-
-      adjusted = if schema.is_a?(Skill::OutputSchema)
-                   "#{prompt}\n\nRespond ONLY with valid JSON matching this schema: #{schema.to_json_description}"
-                 else
-                   prompt
-                 end
-
-      result = super(adjusted, context: context)
-      schema.is_a?(Skill::OutputSchema) ? schema.parse(result) : result
-    end
-
-    public
-
-    # Record feedback for a previous output.
-    #
-    # Matches +output+ against +call_history+ to capture the input context.
-    # No-op when +feedback_enabled+ is false or no store is configured.
-    #
-    # @param output [String, StructuredResult] the response to rate
-    # @param rating [:good, :bad, :neutral]
-    # @param notes  [String, nil]
-    # @return [self]
-    def feedback(output, rating:, notes: nil) # rubocop:disable Metrics/MethodLength
-      return self unless self.class.feedback_enabled
-
-      store = self.class.feedback_store
-      return self unless store
-
-      output_str = output.to_s
-      matched    = (call_history || []).reverse.find { |h| h[:output] == output_str }
-
-      store.store(FeedbackEntry.new(
-                    input: matched&.dig(:input),
-                    output: output_str,
-                    rating: rating.to_sym,
-                    notes: notes,
-                    timestamp: Time.now
-                  ))
-      self
-    end
-
-    # Generate an improved system prompt based on accumulated feedback.
-    #
-    # Uses the skill's own LLM provider + model. Returns a new String — does NOT
-    # mutate class-level state. The caller decides whether to adopt the result.
-    #
-    # @return [String] the refined system prompt
-    # @raise [Igniter::Error] if no feedback_store is configured
-    def refine_system_prompt
-      store = self.class.feedback_store
-      raise Igniter::Error, "No feedback_store configured on #{self.class.name}" unless store
-
-      FeedbackRefiner.new(provider_instance, current_model).refine(
-        self.class.system_prompt.to_s,
-        store.all
-      )
-    end
-  end
-end
-
-# Load sub-files that reopen Skill after it is fully defined above.
-require_relative "skill/output_schema"
-require_relative "skill/feedback"

data/lib/igniter/stream_loop.rb

@@ -1,80 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  # Runs an Igniter contract in a continuous tick-loop.
-  #
-  # Each tick resolves the contract with the current inputs and delivers the
-  # result to the on_result callback. Useful for sensor polling, feed
-  # processing, or any recurring computation.
-  #
-  #   stream = Igniter::StreamLoop.new(
-  #     contract:      SensorContract,
-  #     tick_interval: 0.1,
-  #     inputs:        { sensor_id: "temp-1", threshold: 25.0 },
-  #     on_result:     ->(result) { puts result.status },
-  #     on_error:      ->(err)    { warn err.message }
-  #   )
-  #
-  #   stream.start
-  #   stream.update_inputs(threshold: 30.0)  # hot-swap inputs between ticks
-  #   stream.stop
-  #
-  class StreamLoop
-    def initialize(contract:, tick_interval: 1.0, inputs: {}, on_result: nil, on_error: nil)
-      @contract_class = contract
-      @tick_interval  = tick_interval.to_f
-      @on_result      = on_result
-      @on_error       = on_error
-      @mutex          = Mutex.new
-      @current_inputs = inputs.dup
-      @running        = false
-      @thread         = nil
-    end
-
-    # Start the loop in a background thread. Returns self.
-    def start
-      @running = true
-      @thread  = Thread.new { loop_body }
-      @thread.abort_on_exception = false
-      self
-    end
-
-    # Stop the loop and wait for the current tick to finish.
-    def stop(timeout: 5)
-      @running = false
-      @thread&.join(timeout)
-      self
-    end
-
-    # Merge +new_inputs+ into the current input set. Takes effect on the next tick.
-    def update_inputs(new_inputs)
-      @mutex.synchronize { @current_inputs.merge!(new_inputs) }
-      self
-    end
-
-    def alive?
-      @thread&.alive? || false
-    end
-
-    private
-
-    def loop_body
-      while @running
-        tick_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-        run_tick
-        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - tick_start
-        sleep_for = [@tick_interval - elapsed, 0].max
-        sleep(sleep_for) if sleep_for.positive? && @running
-      end
-    end
-
-    def run_tick
-      inputs   = @mutex.synchronize { @current_inputs.dup }
-      contract = @contract_class.new(**inputs)
-      contract.resolve_all
-      @on_result&.call(contract.result)
-    rescue StandardError => e
-      @on_error&.call(e)
-    end
-  end
-end