igniter 0.4.3 → 0.5.0

data/lib/igniter/skill/feedback.rb

@@ -0,0 +1,116 @@
+# 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

@@ -0,0 +1,110 @@
+# 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

@@ -0,0 +1,218 @@
+# 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/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/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

@@ -0,0 +1,151 @@
+# 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