igniter 0.4.5 → 0.5.1

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "set"
+
+require "igniter/core/errors"
+require "igniter/core/tool"
+require_relative "skill"
+
+module Igniter
+  module AI
+    module ToolRegistry
+      SCOPES = %i[bundled managed workspace].freeze
+
+      @tools = {}
+
+      class << self
+        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::AI::Skill subclass"
+            end
+
+            @tools[klass.tool_name] = { klass: klass, scope: scope }
+          end
+          self
+        end
+
+        def find(name)
+          @tools[name.to_s]&.fetch(:klass)
+        end
+
+        def all(scope: nil)
+          entries_for(scope).map { |e| e[:klass] }
+        end
+
+        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
+
+        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
+
+        def size = @tools.size
+        def empty? = @tools.empty?
+
+        def clear!
+          @tools = {}
+          self
+        end
+
+        private
+
+        def entries_for(scope)
+          scope ? @tools.values.select { |e| e[:scope] == scope } : @tools.values
+        end
+
+        def discoverable?(klass)
+          klass.is_a?(Class) &&
+            (klass < Igniter::Tool || klass < Igniter::AI::Skill)
+        end
+      end
+    end
+  end
+end

data/packages/igniter-ai/lib/igniter/ai/transcription/providers/assemblyai.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module Igniter
+  module AI
+    module Transcription
+      module Providers
+        # AssemblyAI transcription provider.
+        #
+        # Uses a 3-step async workflow:
+        #   1. Upload audio file to AssemblyAI CDN → upload_url
+        #   2. Submit transcription job             → job_id
+        #   3. Poll until completed / error         → result
+        #
+        # Docs: https://www.assemblyai.com/docs/api-reference
+        #
+        # Strengths:
+        #   - Speaker diarization (diarize: true → speaker_labels: true)
+        #   - Rich intelligence features via options
+        #   - Free tier (333 hr/month)
+        #
+        # Extra options:
+        #   sentiment_analysis: Boolean — per-sentence sentiment
+        #   auto_chapters:      Boolean — topic-based chapters
+        #   entity_detection:   Boolean — named entity recognition
+        #   pii_redact:         Array   — entity types to redact (e.g. [:name, :phone_number])
+        #   auto_highlights:    Boolean — key phrases extraction
+        #   summarization:      Boolean — extractive summary
+        #   custom_vocabulary:  Array   — boost accuracy for specific words
+        class AssemblyAI < Base # rubocop:disable Metrics/ClassLength
+          API_BASE       = "https://api.assemblyai.com"
+          MIN_INTERVAL   = 1   # seconds
+          MAX_INTERVAL   = 30  # seconds — exponential backoff cap
+
+          def initialize(api_key: ENV["ASSEMBLYAI_API_KEY"], base_url: API_BASE,
+                         timeout: 60, poll_interval: 2, poll_timeout: 300)
+            super()
+            @api_key       = api_key
+            @base_url      = base_url.to_s.chomp("/")
+            @timeout       = timeout
+            @poll_interval = poll_interval
+            @poll_timeout  = poll_timeout
+          end
+
+          def transcribe(audio_source, model:, language: nil, diarize: false, # rubocop:disable Metrics/ParameterLists
+                         _word_timestamps: true, poll_interval: nil, poll_timeout: nil, **options)
+            validate_api_key!
+
+            interval = poll_interval || @poll_interval
+            deadline = poll_timeout  || @poll_timeout
+
+            audio      = read_audio(audio_source)
+            fname      = filename_from(audio_source)
+            upload_url = upload_file(audio, fname)
+            job_id     = submit_job(upload_url, model: model, language: language,
+                                                diarize: diarize, options: options)
+            raw        = poll_until_complete(job_id, interval: interval, timeout: deadline)
+            build_result(raw, model: model, diarize: diarize)
+          end
+
+          private
+
+          # ── Step 1: Upload ─────────────────────────────────────────────────
+
+          def upload_file(audio_data, filename)
+            ctype    = audio_content_type(filename)
+            uri      = URI.parse("#{@base_url}/v2/upload")
+            http     = http_for(uri)
+            request  = Net::HTTP::Post.new(uri.path, auth_headers)
+            request["Content-Type"] = ctype
+            request.body            = audio_data
+
+            response = handle_response(http.request(request))
+            response["upload_url"] || raise(Igniter::AI::ProviderError, "AssemblyAI: no upload_url in response")
+          rescue Errno::ECONNREFUSED, SocketError, Net::OpenTimeout => e
+            raise Igniter::AI::ProviderError, "Cannot connect to AssemblyAI API: #{e.message}"
+          end
+
+          # ── Step 2: Submit job ─────────────────────────────────────────────
+
+          def submit_job(upload_url, model:, language:, diarize:, options:) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+            body = { audio_url: upload_url }
+            body[:speech_model]        = model if model && model != "default"
+            body[:language_code]       = language if language
+            body[:speaker_labels]      = true if diarize
+            body[:word_boost]          = options[:custom_vocabulary] if options[:custom_vocabulary]
+            body[:sentiment_analysis]  = true if options[:sentiment_analysis]
+            body[:auto_chapters]       = true if options[:auto_chapters]
+            body[:entity_detection]    = true if options[:entity_detection]
+            body[:auto_highlights]     = true if options[:auto_highlights]
+            body[:summarization]       = true if options[:summarization]
+            body[:summary_model]       = "informative" if options[:summarization]
+            body[:summary_type]        = "bullets" if options[:summarization]
+            body[:redact_pii]          = true if options[:pii_redact]
+            body[:redact_pii_policies] = options[:pii_redact].map(&:to_s) if options[:pii_redact]
+
+            uri      = URI.parse("#{@base_url}/v2/transcripts")
+            http     = http_for(uri)
+            request  = Net::HTTP::Post.new(uri.path, json_headers)
+            request.body = JSON.generate(body)
+
+            response = handle_response(http.request(request))
+            response["id"] || raise(Igniter::AI::ProviderError, "AssemblyAI: no transcript id in response")
+          end
+
+          # ── Step 3: Poll ───────────────────────────────────────────────────
+
+          def poll_until_complete(job_id, interval:, timeout:) # rubocop:disable Metrics/MethodLength
+            deadline = Time.now + timeout
+            wait     = [interval.to_f, MIN_INTERVAL].max
+
+            loop do
+              result = fetch_transcript(job_id)
+
+              case result["status"]
+              when "completed" then return result
+              when "error"
+                raise Igniter::AI::ProviderError,
+                      "AssemblyAI transcription failed: #{result["error"]}"
+              end
+
+              if Time.now > deadline
+                raise Igniter::AI::ProviderError,
+                      "AssemblyAI transcription timed out after #{timeout}s (job_id: #{job_id})"
+              end
+
+              sleep(wait)
+              wait = [wait * 1.5, MAX_INTERVAL].min
+            end
+          end
+
+          def fetch_transcript(job_id)
+            uri      = URI.parse("#{@base_url}/v2/transcripts/#{job_id}")
+            http     = http_for(uri)
+            request  = Net::HTTP::Get.new(uri.path, auth_headers)
+            handle_response(http.request(request))
+          rescue Errno::ECONNREFUSED, SocketError, Net::OpenTimeout => e
+            raise Igniter::AI::ProviderError, "Cannot connect to AssemblyAI API: #{e.message}"
+          end
+
+          # ── Result building ────────────────────────────────────────────────
+
+          def build_result(raw, model:, diarize:) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+            words = (raw["words"] || []).map do |w|
+              TranscriptWord.new(
+                word: w["text"].to_s,
+                start_time: w["start"].to_f / 1000.0, # AssemblyAI uses milliseconds
+                end_time: w["end"].to_f / 1000.0,
+                confidence: w["confidence"]&.to_f,
+                speaker: w["speaker"] # "A", "B", ... or nil
+              )
+            end
+
+            speakers = diarize ? build_speakers(raw["utterances"], words) : nil
+
+            TranscriptResult.new(
+              text: raw["text"].to_s,
+              words: words,
+              speakers: speakers,
+              language: raw["language_code"],
+              duration: raw["audio_duration"]&.to_f,
+              provider: :assemblyai,
+              model: model,
+              raw: raw
+            )
+          end
+
+          def build_speakers(utterances, _words)
+            return [] unless utterances&.any?
+
+            utterances.map do |u|
+              SpeakerSegment.new(
+                speaker: u["speaker"], # "A", "B", ...
+                start_time: u["start"].to_f / 1000.0,
+                end_time: u["end"].to_f / 1000.0,
+                text: u["text"].to_s
+              )
+            end
+          end
+
+          # ── Helpers ────────────────────────────────────────────────────────
+
+          def auth_headers
+            { "Authorization" => @api_key }
+          end
+
+          def json_headers
+            auth_headers.merge("Content-Type" => "application/json")
+          end
+
+          def validate_api_key!
+            return if @api_key && !@api_key.empty?
+
+            raise Igniter::AI::ConfigurationError,
+                  "AssemblyAI API key not configured. Set ASSEMBLYAI_API_KEY or pass api_key: to the provider."
+          end
+        end
+      end
+    end
+  end
+end

data/packages/igniter-ai/lib/igniter/ai/transcription/providers/base.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Igniter
+  module AI
+    module Transcription
+      module Providers
+        # Abstract base for all transcription providers.
+        #
+        # Subclasses must implement #transcribe and may override the protected helpers.
+        # All helpers use only stdlib (Net::HTTP, JSON) — zero production dependencies.
+        class Base
+          # @param audio_source [String, Pathname, IO] File path or IO object.
+          # @param model        [String]
+          # @param language     [String, nil]  BCP-47 code, or nil for auto-detection.
+          # @param diarize      [Boolean]      Request speaker labels.
+          # @param word_timestamps [Boolean]   Request per-word timing.
+          # @param options      [Hash]         Provider-specific extras.
+          # @return [TranscriptResult]
+          def transcribe(audio_source, model:, language: nil, diarize: false, # rubocop:disable Metrics/ParameterLists
+                         word_timestamps: true, **options)
+            raise NotImplementedError, "#{self.class}#transcribe must be implemented"
+          end
+
+          private
+
+          # ── Audio helpers ──────────────────────────────────────────────────
+
+          def read_audio(source)
+            case source
+            when String then File.binread(source)
+            when Pathname then File.binread(source.to_s)
+            when StringIO then source.string.b
+            when IO then source.read.b
+            else
+              raise ArgumentError, "audio_source must be a file path or IO object, got #{source.class}"
+            end
+          end
+
+          def filename_from(source)
+            case source
+            when String then File.basename(source)
+            when Pathname then source.basename.to_s
+            else "audio.wav"
+            end
+          end
+
+          # Best-effort MIME type from file extension.
+          def audio_content_type(filename)
+            ext = File.extname(filename.to_s).downcase
+            {
+              ".mp3" => "audio/mpeg", ".mp4" => "video/mp4", ".m4a" => "audio/mp4",
+              ".wav" => "audio/wav",  ".webm" => "audio/webm", ".ogg" => "audio/ogg",
+              ".flac" => "audio/flac", ".mpeg" => "audio/mpeg", ".mpga" => "audio/mpeg"
+            }.fetch(ext, "application/octet-stream")
+          end
+
+          # ── Multipart form-data builder ────────────────────────────────────
+          #
+          # Returns [body (binary String), boundary (String)].
+          # Hash values that contain :data are treated as file parts.
+          def build_multipart(fields) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+            boundary = "IgniterBdy#{Time.now.to_i}"
+            crlf     = "\r\n"
+            body     = String.new("", encoding: "BINARY")
+
+            fields.each do |name, value|
+              body << "--#{boundary}#{crlf}"
+              if value.is_a?(Hash) && value.key?(:data)
+                body << "Content-Disposition: form-data; name=\"#{name}\"; filename=\"#{value[:filename]}\"#{crlf}"
+                body << "Content-Type: #{value[:content_type]}#{crlf}#{crlf}"
+                data = value[:data]
+                data = data.b if data.respond_to?(:b)
+                body << data
+              else
+                body << "Content-Disposition: form-data; name=\"#{name}\"#{crlf}#{crlf}"
+                body << value.to_s
+              end
+              body << crlf
+            end
+
+            body << "--#{boundary}--#{crlf}"
+            [body, boundary]
+          end
+
+          # ── HTTP helpers ───────────────────────────────────────────────────
+
+          def http_for(uri)
+            http             = Net::HTTP.new(uri.host, uri.port)
+            http.use_ssl     = uri.scheme == "https"
+            http.read_timeout = @timeout || 300
+            http.open_timeout = 15
+            http
+          end
+
+          def handle_response(response) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+            unless response.is_a?(Net::HTTPSuccess)
+              body = begin
+                JSON.parse(response.body)
+              rescue StandardError
+                {}
+              end
+              msg = body["error"].is_a?(Hash) ? body.dig("error", "message") : body["error"]
+              msg ||= response.body.to_s.slice(0, 200)
+              raise Igniter::AI::ProviderError, "#{provider_name} error #{response.code}: #{msg}"
+            end
+            JSON.parse(response.body)
+          rescue JSON::ParserError => e
+            raise Igniter::AI::ProviderError, "#{provider_name} returned invalid JSON: #{e.message}"
+          end
+
+          def provider_name
+            self.class.name.to_s.split("::").last
+          end
+        end
+      end
+    end
+  end
+end

data/packages/igniter-ai/lib/igniter/ai/transcription/providers/deepgram.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Igniter
+  module AI
+    module Transcription
+      module Providers
+        # Deepgram transcription provider (Nova-3 and others).
+        #
+        # API: POST /v1/listen (raw binary body, model/options as query params)
+        # Docs: https://developers.deepgram.com/docs/getting-started-with-pre-recorded-audio
+        #
+        # Strengths:
+        #   - Speaker diarization (diarize: true)
+        #   - Per-second billing (cheapest for variable-length calls)
+        #   - Synchronous response (no polling)
+        #   - Intelligence features via options: :sentiment, :topics, :intents, :summarize
+        #
+        # Extra options:
+        #   sentiment:    Boolean — per-sentence sentiment analysis
+        #   topics:       Boolean — topic detection
+        #   intents:      Boolean — intent recognition
+        #   summarize:    Boolean — extractive summary
+        #   smart_format: Boolean — punctuation + capitalization (default: true)
+        #   punctuate:    Boolean — add punctuation (default: true)
+        class Deepgram < Base # rubocop:disable Metrics/ClassLength
+          API_BASE = "https://api.deepgram.com"
+
+          def initialize(api_key: ENV["DEEPGRAM_API_KEY"], base_url: API_BASE, timeout: 300)
+            super()
+            @api_key  = api_key
+            @base_url = base_url.to_s.chomp("/")
+            @timeout  = timeout
+          end
+
+          def transcribe(audio_source, model:, language: nil, diarize: false, # rubocop:disable Metrics/ParameterLists
+                         _word_timestamps: true, **options)
+            validate_api_key!
+
+            audio = read_audio(audio_source)
+            fname = filename_from(audio_source)
+            ctype = audio_content_type(fname)
+
+            params = build_params(model: model, language: language, diarize: diarize, options: options)
+            raw = post_binary("/v1/listen", audio, ctype, params)
+            build_result(raw, model: model, diarize: diarize)
+          end
+
+          private
+
+          def build_params(model:, language:, diarize:, options:) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+            p = { model: model }
+            p[:language]     = language if language
+            p[:diarize]      = "true" if diarize
+            p[:utterances]   = "true" if diarize  # structured speaker segments
+            p[:punctuate]    = options.fetch(:punctuate, true) ? "true" : "false"
+            p[:smart_format] = options.fetch(:smart_format, true) ? "true" : "false"
+            p[:sentiment]    = "true" if options[:sentiment]
+            p[:topics]       = "true" if options[:topics]
+            p[:intents]      = "true" if options[:intents]
+            p[:summarize]    = "v2" if options[:summarize]
+            p
+          end
+
+          def build_result(raw, model:, diarize:) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+            alternative = raw.dig("results", "channels", 0, "alternatives", 0) || {}
+
+            words = (alternative["words"] || []).map do |w|
+              TranscriptWord.new(
+                word: (w["punctuated_word"] || w["word"]).to_s,
+                start_time: w["start"].to_f,
+                end_time: w["end"].to_f,
+                confidence: w["confidence"]&.to_f,
+                speaker: w["speaker"] # Integer (0-based) when diarize: true, else nil
+              )
+            end
+
+            speakers = diarize ? build_speakers(raw.dig("results", "utterances"), words) : nil
+            lang     = raw.dig("results", "channels", 0, "detected_language") ||
+                       raw.dig("metadata", "detected_language")
+
+            TranscriptResult.new(
+              text: alternative["transcript"].to_s,
+              words: words,
+              speakers: speakers,
+              language: lang,
+              duration: raw.dig("metadata", "duration")&.to_f,
+              provider: :deepgram,
+              model: model,
+              raw: raw
+            )
+          end
+
+          # Build SpeakerSegment list from Deepgram utterances (preferred) or word grouping.
+          def build_speakers(utterances, words) # rubocop:disable Metrics/MethodLength
+            if utterances&.any?
+              utterances.map do |u|
+                SpeakerSegment.new(
+                  speaker: u["speaker"],
+                  start_time: u["start"].to_f,
+                  end_time: u["end"].to_f,
+                  text: u["transcript"].to_s
+                )
+              end
+            else
+              # Fall back: group consecutive words by speaker
+              group_words_by_speaker(words)
+            end
+          end
+
+          def group_words_by_speaker(words) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+            return [] if words.empty?
+
+            segments = []
+            current  = nil
+
+            words.each do |w|
+              if current.nil? || w.speaker != current[:speaker]
+                segments << current if current
+                current = { speaker: w.speaker, start_time: w.start_time, end_time: w.end_time, words: [w.word] }
+              else
+                current[:end_time] = w.end_time
+                current[:words] << w.word
+              end
+            end
+            segments << current if current
+
+            segments.map do |seg|
+              SpeakerSegment.new(
+                speaker: seg[:speaker],
+                start_time: seg[:start_time],
+                end_time: seg[:end_time],
+                text: seg[:words].join(" ")
+              )
+            end
+          end
+
+          def post_binary(path, audio_data, content_type, params)
+            query = URI.encode_www_form(params)
+            uri   = URI.parse("#{@base_url}#{path}?#{query}")
+            http  = http_for(uri)
+
+            request = Net::HTTP::Post.new("#{uri.path}?#{uri.query}")
+            request["Authorization"] = "Token #{@api_key}"
+            request["Content-Type"]  = content_type
+            request.body             = audio_data
+
+            handle_response(http.request(request))
+          rescue Errno::ECONNREFUSED, SocketError, Net::OpenTimeout => e
+            raise Igniter::AI::ProviderError, "Cannot connect to Deepgram API: #{e.message}"
+          end
+
+          def validate_api_key!
+            return if @api_key && !@api_key.empty?
+
+            raise Igniter::AI::ConfigurationError,
+                  "Deepgram API key not configured. Set DEEPGRAM_API_KEY or pass api_key: to the provider."
+          end
+        end
+      end
+    end
+  end
+end

data/packages/igniter-ai/lib/igniter/ai/transcription/providers/openai.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Igniter
+  module AI
+    module Transcription
+      module Providers
+        # OpenAI Whisper transcription provider.
+        #
+        # API: POST /v1/audio/transcriptions (multipart/form-data)
+        # Docs: https://platform.openai.com/docs/api-reference/audio
+        #
+        # Limitations vs other providers:
+        #   - No speaker diarization (speakers will be nil in result)
+        #   - 20 MB file size limit
+        #   - Only word-level granularity (no sentence-level)
+        #
+        # Extra options passed through:
+        #   prompt:          String  — context hint to guide spelling/vocabulary
+        #   response_format: Symbol  — :srt or :vtt stores raw subtitles in result.raw[:subtitle_text]
+        class OpenAI < Base
+          API_BASE = "https://api.openai.com"
+
+          def initialize(api_key: ENV["OPENAI_API_KEY"], base_url: API_BASE, timeout: 120)
+            super()
+            @api_key  = api_key
+            @base_url = base_url.to_s.chomp("/")
+            @timeout  = timeout
+          end
+
+          def transcribe(audio_source, model:, language: nil, _diarize: false, # rubocop:disable Metrics/MethodLength,Metrics/ParameterLists
+                         word_timestamps: true, **options)
+            validate_api_key!
+
+            audio = read_audio(audio_source)
+            fname = filename_from(audio_source)
+            ctype = audio_content_type(fname)
+
+            fields = {
+              "file" => { data: audio, filename: fname, content_type: ctype },
+              "model" => model,
+              "response_format" => "verbose_json"
+            }
+            fields["language"] = language if language
+            fields["prompt"]   = options[:prompt] if options[:prompt]
+            # Request word-level timestamps
+            fields["timestamp_granularities[]"] = "word" if word_timestamps
+
+            body, boundary = build_multipart(fields)
+            raw = post_multipart("/v1/audio/transcriptions", body, boundary)
+            build_result(raw, model: model)
+          end
+
+          private
+
+          def build_result(raw, model:) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+            words = (raw["words"] || []).map do |w|
+              TranscriptWord.new(
+                word: w["word"].to_s.strip,
+                start_time: w["start"].to_f,
+                end_time: w["end"].to_f,
+                confidence: w["confidence"]&.to_f,
+                speaker: nil # Whisper has no diarization
+              )
+            end
+
+            TranscriptResult.new(
+              text: raw["text"].to_s,
+              words: words,
+              speakers: nil,
+              language: raw["language"],
+              duration: raw["duration"]&.to_f,
+              provider: :openai,
+              model: model,
+              raw: raw
+            )
+          end
+
+          def post_multipart(path, body, boundary)
+            uri  = URI.parse("#{@base_url}#{path}")
+            http = http_for(uri)
+
+            request = Net::HTTP::Post.new(uri.path)
+            request["Authorization"] = "Bearer #{@api_key}"
+            request["Content-Type"]  = "multipart/form-data; boundary=#{boundary}"
+            request.body             = body
+
+            handle_response(http.request(request))
+          rescue Errno::ECONNREFUSED, SocketError, Net::OpenTimeout => e
+            raise Igniter::AI::ProviderError, "Cannot connect to OpenAI API: #{e.message}"
+          end
+
+          def validate_api_key!
+            return if @api_key && !@api_key.empty?
+
+            raise Igniter::AI::ConfigurationError,
+                  "OpenAI API key not configured. Set OPENAI_API_KEY or pass api_key: to the provider."
+          end
+        end
+      end
+    end
+  end
+end