igniter 0.4.3 → 0.5.0

data/lib/igniter/integrations/llm/providers/anthropic.rb

@@ -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
 

data/lib/igniter/integrations/llm/providers/openai.rb

@@ -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
 

data/lib/igniter/integrations/llm/transcription/providers/assemblyai.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module Igniter
+  module LLM
+    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::LLM::ProviderError, "AssemblyAI: no upload_url in response")
+          rescue Errno::ECONNREFUSED, SocketError, Net::OpenTimeout => e
+            raise Igniter::LLM::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::LLM::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::LLM::ProviderError,
+                      "AssemblyAI transcription failed: #{result["error"]}"
+              end
+
+              if Time.now > deadline
+                raise Igniter::LLM::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::LLM::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::LLM::ConfigurationError,
+                  "AssemblyAI API key not configured. Set ASSEMBLYAI_API_KEY or pass api_key: to the provider."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/igniter/integrations/llm/transcription/providers/base.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Igniter
+  module LLM
+    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::LLM::ProviderError, "#{provider_name} error #{response.code}: #{msg}"
+            end
+            JSON.parse(response.body)
+          rescue JSON::ParserError => e
+            raise Igniter::LLM::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/lib/igniter/integrations/llm/transcription/providers/deepgram.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Igniter
+  module LLM
+    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::LLM::ProviderError, "Cannot connect to Deepgram API: #{e.message}"
+          end
+
+          def validate_api_key!
+            return if @api_key && !@api_key.empty?
+
+            raise Igniter::LLM::ConfigurationError,
+                  "Deepgram API key not configured. Set DEEPGRAM_API_KEY or pass api_key: to the provider."
+          end
+        end
+      end
+    end
+  end
+end