igniter 0.4.5 → 0.5.1

data/{lib/igniter/integrations/llm → packages/igniter-ai/lib/igniter/ai}/providers/anthropic.rb

@@ -5,7 +5,7 @@ require "json"
 require "uri"
 
 module Igniter
-  module LLM
+  module AI
     module Providers
       # Anthropic Claude provider.
       # Requires ANTHROPIC_API_KEY environment variable or explicit api_key:.
@@ -68,7 +68,11 @@ module Igniter
           tool_calls = content_blocks
                        .select { |b| b["type"] == "tool_use" }
                        .map do |b|
-            { name: b["name"].to_s, arguments: (b["input"] || {}).transform_keys(&:to_sym) }
+            {
+              id:        b["id"].to_s,
+              name:      b["name"].to_s,
+              arguments: (b["input"] || {}).transform_keys(&:to_sym),
+            }
           end
 
           usage = response.fetch("usage", {})
@@ -80,9 +84,38 @@ module Igniter
           { role: :assistant, content: text_content, tool_calls: tool_calls }
         end
 
-        def normalize_messages(messages)
-          messages.map do |m|
-            { "role" => (m[:role] || m["role"]).to_s, "content" => (m[:content] || m["content"]).to_s }
+        def normalize_messages(messages) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+          messages.flat_map do |m|
+            role = (m[:role] || m["role"]).to_sym
+
+            case role
+            when :assistant
+              calls = Array(m[:tool_calls])
+              if calls.any?
+                # Anthropic requires tool_use blocks inside the content array
+                blocks = []
+                blocks << { "type" => "text", "text" => m[:content].to_s } unless m[:content].to_s.empty?
+                calls.each do |tc|
+                  blocks << {
+                    "type"  => "tool_use",
+                    "id"    => tc[:id].to_s,
+                    "name"  => tc[:name].to_s,
+                    "input" => (tc[:arguments] || {}).transform_keys(&:to_s),
+                  }
+                end
+                [{ "role" => "assistant", "content" => blocks }]
+              else
+                [{ "role" => "assistant", "content" => m[:content].to_s }]
+              end
+            when :tool_results
+              # All results for one LLM turn → single user message with tool_result blocks
+              blocks = Array(m[:results]).map do |r|
+                { "type" => "tool_result", "tool_use_id" => r[:id].to_s, "content" => r[:content].to_s }
+              end
+              [{ "role" => "user", "content" => blocks }]
+            else
+              [{ "role" => role.to_s, "content" => (m[:content] || m["content"]).to_s }]
+            end
           end
         end
 
@@ -109,7 +142,7 @@ module Igniter
           response = http.request(request)
           handle_response(response)
         rescue Errno::ECONNREFUSED, Errno::EADDRNOTAVAIL, SocketError, Net::OpenTimeout => e
-          raise Igniter::LLM::ProviderError, "Cannot connect to Anthropic API: #{e.message}"
+          raise Igniter::AI::ProviderError, "Cannot connect to Anthropic API: #{e.message}"
         end
 
         def headers
@@ -128,18 +161,18 @@ module Igniter
               {}
             end
             error_msg = body.dig("error", "message") || response.body.to_s.slice(0, 200)
-            raise Igniter::LLM::ProviderError, "Anthropic API error #{response.code}: #{error_msg}"
+            raise Igniter::AI::ProviderError, "Anthropic API error #{response.code}: #{error_msg}"
           end
 
           JSON.parse(response.body)
         rescue JSON::ParserError => e
-          raise Igniter::LLM::ProviderError, "Anthropic returned invalid JSON: #{e.message}"
+          raise Igniter::AI::ProviderError, "Anthropic returned invalid JSON: #{e.message}"
         end
 
         def validate_api_key!
           return if @api_key && !@api_key.empty?
 
-          raise Igniter::LLM::ConfigurationError,
+          raise Igniter::AI::ConfigurationError,
                 "Anthropic API key not configured. Set ANTHROPIC_API_KEY or pass api_key: to the provider."
         end
       end

data/{lib/igniter/integrations/llm → packages/igniter-ai/lib/igniter/ai}/providers/base.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Igniter
-  module LLM
+  module AI
     module Providers
       class Base
         attr_reader :last_usage

data/{lib/igniter/integrations/llm → packages/igniter-ai/lib/igniter/ai}/providers/ollama.rb

@@ -5,7 +5,7 @@ require "json"
 require "uri"
 
 module Igniter
-  module LLM
+  module AI
     module Providers
       # Ollama provider — calls the local Ollama REST API.
       # Requires Ollama to be running: https://ollama.com
@@ -63,7 +63,7 @@ module Igniter
           response = http.request(request)
           handle_response(response)
         rescue Errno::ECONNREFUSED, Errno::EADDRNOTAVAIL, SocketError, Net::OpenTimeout => e
-          raise Igniter::LLM::ProviderError, "Cannot connect to Ollama at #{@base_url}: #{e.message}"
+          raise Igniter::AI::ProviderError, "Cannot connect to Ollama at #{@base_url}: #{e.message}"
         end
 
         def get(path)
@@ -76,13 +76,13 @@ module Igniter
 
         def handle_response(response)
           unless response.is_a?(Net::HTTPSuccess)
-            raise Igniter::LLM::ProviderError,
+            raise Igniter::AI::ProviderError,
                   "Ollama API error #{response.code}: #{response.body.to_s.slice(0, 200)}"
           end
 
           JSON.parse(response.body)
         rescue JSON::ParserError => e
-          raise Igniter::LLM::ProviderError, "Ollama returned invalid JSON: #{e.message}"
+          raise Igniter::AI::ProviderError, "Ollama returned invalid JSON: #{e.message}"
         end
 
         def normalize_messages(messages)

data/{lib/igniter/integrations/llm → packages/igniter-ai/lib/igniter/ai}/providers/openai.rb

@@ -5,7 +5,7 @@ require "json"
 require "uri"
 
 module Igniter
-  module LLM
+  module AI
     module Providers
       # OpenAI provider (also compatible with Azure OpenAI and any OpenAI-compatible API).
       # Requires OPENAI_API_KEY environment variable or explicit api_key:.
@@ -67,8 +67,9 @@ module Igniter
           raw.map do |tc|
             fn = tc["function"] || {}
             {
-              name: fn["name"].to_s,
-              arguments: parse_arguments(fn["arguments"])
+              id:        tc["id"].to_s,
+              name:      fn["name"].to_s,
+              arguments: parse_arguments(fn["arguments"]),
             }
           end
         end
@@ -83,9 +84,37 @@ module Igniter
           {}
         end
 
-        def normalize_messages(messages)
-          messages.map do |m|
-            { "role" => (m[:role] || m["role"]).to_s, "content" => (m[:content] || m["content"]).to_s }
+        def normalize_messages(messages) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+          messages.flat_map do |m|
+            role = (m[:role] || m["role"]).to_sym
+
+            case role
+            when :assistant
+              calls = Array(m[:tool_calls])
+              if calls.any?
+                # OpenAI assistant message with tool_calls field
+                formatted = calls.map do |tc|
+                  {
+                    "id"       => tc[:id].to_s,
+                    "type"     => "function",
+                    "function" => {
+                      "name"      => tc[:name].to_s,
+                      "arguments" => JSON.generate(tc[:arguments] || {}),
+                    },
+                  }
+                end
+                [{ "role" => "assistant", "content" => m[:content].to_s, "tool_calls" => formatted }]
+              else
+                [{ "role" => "assistant", "content" => m[:content].to_s }]
+              end
+            when :tool_results
+              # OpenAI expects one :tool message per result
+              Array(m[:results]).map do |r|
+                { "role" => "tool", "tool_call_id" => r[:id].to_s, "name" => r[:name].to_s, "content" => r[:content].to_s }
+              end
+            else
+              [{ "role" => role.to_s, "content" => (m[:content] || m["content"]).to_s }]
+            end
           end
         end
 
@@ -115,7 +144,7 @@ module Igniter
           response = http.request(request)
           handle_response(response)
         rescue Errno::ECONNREFUSED, Errno::EADDRNOTAVAIL, SocketError, Net::OpenTimeout => e
-          raise Igniter::LLM::ProviderError, "Cannot connect to OpenAI API at #{@base_url}: #{e.message}"
+          raise Igniter::AI::ProviderError, "Cannot connect to OpenAI API at #{@base_url}: #{e.message}"
         end
 
         def headers
@@ -133,18 +162,18 @@ module Igniter
               {}
             end
             error_msg = body.dig("error", "message") || response.body.to_s.slice(0, 200)
-            raise Igniter::LLM::ProviderError, "OpenAI API error #{response.code}: #{error_msg}"
+            raise Igniter::AI::ProviderError, "OpenAI API error #{response.code}: #{error_msg}"
           end
 
           JSON.parse(response.body)
         rescue JSON::ParserError => e
-          raise Igniter::LLM::ProviderError, "OpenAI returned invalid JSON: #{e.message}"
+          raise Igniter::AI::ProviderError, "OpenAI returned invalid JSON: #{e.message}"
         end
 
         def validate_api_key!
           return if @api_key && !@api_key.empty?
 
-          raise Igniter::LLM::ConfigurationError,
+          raise Igniter::AI::ConfigurationError,
                 "OpenAI API key not configured. Set OPENAI_API_KEY or pass api_key: to the provider."
         end
       end

data/packages/igniter-ai/lib/igniter/ai/skill/feedback.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Igniter
+  module AI
+    # Immutable record of one rated invocation of a Skill.
+    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 Skill::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 Skill::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/packages/igniter-ai/lib/igniter/ai/skill/output_schema.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Igniter
+  module AI
+    # 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::AI::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 Skill::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)
+        Skill::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 Skill::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::AI::Skill::StructuredResult #{to_h}>"
+      end
+    end
+  end
+end

data/packages/igniter-ai/lib/igniter/ai/skill/runtime_contract.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Igniter
+  module AI
+    class Skill < Executor
+      # Canonical runtime-facing contract for AI skills.
+      #
+      # This gathers the skill semantics that previously lived across separate
+      # class-level methods into one immutable object:
+      # - structured output contract
+      # - feedback/refinement behavior
+      # - capability requirements
+      # - nested tool/skill affordances
+      class RuntimeContract
+        attr_reader :output_schema, :feedback_enabled, :feedback_store,
+                    :required_capabilities, :tools
+
+        def initialize(output_schema:, feedback_enabled:, feedback_store:, required_capabilities:, tools:)
+          @output_schema = output_schema
+          @feedback_enabled = !!feedback_enabled
+          @feedback_store = feedback_store
+          @required_capabilities = Array(required_capabilities).map(&:to_sym).freeze
+          @tools = Array(tools).freeze
+          @tool_classes = @tools.select do |tool|
+            tool.is_a?(Class) && tool.respond_to?(:tool_name) && tool.respond_to?(:to_schema)
+          end.freeze
+          @tool_names = @tool_classes.map(&:tool_name).freeze
+          freeze
+        end
+
+        def structured_output?
+          output_schema.is_a?(Skill::OutputSchema)
+        end
+
+        def feedback?
+          feedback_enabled
+        end
+
+        def tool_classes
+          @tool_classes
+        end
+
+        def tool_names
+          @tool_names
+        end
+
+        def tool_schemas(provider = nil)
+          tool_classes.map { |tool| tool.to_schema(provider) }
+        end
+
+        def to_h
+          {
+            structured_output: structured_output?,
+            output_schema: serialize_output_schema,
+            feedback_enabled: feedback_enabled,
+            feedback_store: serialize_feedback_store,
+            required_capabilities: required_capabilities,
+            tool_names: tool_names,
+            tool_count: tool_classes.size,
+          }.freeze
+        end
+
+        private
+
+        def serialize_output_schema
+          if structured_output?
+            {
+              type: "structured",
+              fields: output_schema.fields.map { |field| { name: field.name, type: field.type.name } },
+            }
+          else
+            output_schema
+          end
+        end
+
+        def serialize_feedback_store
+          return nil unless feedback_store
+
+          {
+            class_name: feedback_store.class.name,
+            size: feedback_store.respond_to?(:size) ? feedback_store.size : nil,
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/packages/igniter-ai/lib/igniter/ai/skill.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "igniter/core/errors"
+require "igniter/core/tool"
+require_relative "executor"
+
+module Igniter
+  module AI
+    # Base class for AI-callable skills — composable units of agent capability.
+    class Skill < Executor
+      CapabilityError = Igniter::Tool::CapabilityError
+
+      include Igniter::Tool::Discoverable
+
+      class << self
+        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
+
+        def output_schema(value = nil, &block)
+          if block
+            @output_schema = Skill::OutputSchema.new(&block)
+          elsif value
+            super(value)
+          else
+            @output_schema || super
+          end
+        end
+
+        def feedback_enabled(val = nil)
+          val.nil? ? (@feedback_enabled || false) : (@feedback_enabled = val)
+        end
+
+        def feedback_store(val = nil)
+          return @feedback_store if val.nil?
+
+          @feedback_store = val == :memory ? Skill::FeedbackStore::Memory.new : val
+        end
+
+        def runtime_contract
+          Skill::RuntimeContract.new(
+            output_schema: output_schema,
+            feedback_enabled: feedback_enabled,
+            feedback_store: feedback_store,
+            required_capabilities: required_capabilities,
+            tools: tools
+          )
+        end
+      end
+
+      protected
+
+      def complete(prompt, context: nil)
+        contract = self.class.runtime_contract
+        schema = contract.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
+
+      def feedback(output, rating:, notes: nil) # rubocop:disable Metrics/MethodLength
+        contract = self.class.runtime_contract
+        return self unless contract.feedback?
+
+        store = contract.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
+
+      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
+end
+
+require_relative "skill/output_schema"
+require_relative "skill/feedback"
+require_relative "skill/runtime_contract"