active_harness 0.2.40 → 0.2.42

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4246d31550942e31c26ec9a708f49aae5b2e0f385a32aeaa06d6d6a75f2849ee
-  data.tar.gz: d7f12a75e7f72e3d004bfd3b64a094e99a082992fd0077e69253bddf97b919f0
+  metadata.gz: 64ee242555ae4c7c33965a04607e3f72c76eb83046f62aaadebf98585866b1a8
+  data.tar.gz: 0ec32b43d65efce4ed82c3a6ab997eb42f03720cd219baf63375fd9d4abb4316
 SHA512:
-  metadata.gz: 81cf0f7cb7f5f54c2a996097e34461f724bd66da920db0cee57cc84f558f8430bc83ad1e914c62a56f3493e890c993c9f2dd9408c161563ae8c161f5ac03e4d5
-  data.tar.gz: e144ed04675d274af6d66157a2f733e1cb65342adc7312b10428e9afc3c135b64af616218d6bb9ddbfb36948efd0e83b817f36654523f910c51d4797e07674e6
+  metadata.gz: 0cb81649fd8e9a5c8ee2f2836dbda95cf94e0ce2ad5a9f60ed5325bb5666baf0c11009578b449c0b8ba45551dd670d71b78329be71a196423d08137f660d86b3
+  data.tar.gz: 2b1c6257ca5e3fd16337e57a7ab5c018de1534aa98616d6cee1be19b6a767cbd7a0ec03f1bbe578400d183a1d61ae566c6eccc91587cbe276954874633a0d5e3

data/lib/active_harness/agent/providers.rb

@@ -43,11 +43,17 @@ module ActiveHarness
       openrouter:  -> { Providers::Images::OpenRouter.new }
     }.freeze
 
+    TRANSCRIPTION_PROVIDERS = {
+      openai:      -> { Providers::Audio::OpenAI.new },
+      openrouter:  -> { Providers::Audio::OpenRouter.new }
+    }.freeze
+
     private
 
     def attempt_model(entry, system_prompt)
       return attempt_via_custom_llm(entry, system_prompt) if @config[:custom_llm_backend]
       return attempt_image_model(entry, system_prompt)     if @config[:image]
+      return attempt_transcription_model(entry)            if @config[:transcribe]
 
       provider = resolve_provider(entry[:provider])
       messages = build_messages(system_prompt, @input)
@@ -78,6 +84,24 @@ module ActiveHarness
       "#{system_prompt}\n\n#{input}"
     end
 
+    def attempt_transcription_model(entry)
+      factory = TRANSCRIPTION_PROVIDERS[entry[:provider].to_sym]
+      raise ArgumentError, "Provider #{entry[:provider].inspect} does not support audio transcription. " \
+                           "Supported transcription providers: #{TRANSCRIPTION_PROVIDERS.keys.join(', ')}" unless factory
+
+      path = @input.to_s
+      raise ArgumentError, "#{self.class.name}: audio file not found: #{path.inspect}" unless File.exist?(path)
+
+      format = File.extname(path).delete_prefix(".").downcase
+      raise ArgumentError, "#{self.class.name}: cannot determine audio format from #{path.inspect} " \
+                           "— expected a file extension like .mp3/.wav/.flac/.m4a/.ogg/.webm/.aac" if format.empty?
+
+      opts = { model: entry[:model], audio_data: File.binread(path), audio_format: format }
+      language = entry[:language] || @config[:transcribe_language]
+      opts[:language] = language if language
+      factory.call.call(**opts)
+    end
+
     def resolve_provider(name)
       factory = PROVIDERS[name.to_sym]
       raise ArgumentError, "Unknown provider: #{name.inspect}. Supported: #{PROVIDERS.keys.join(', ')}" unless factory

data/lib/active_harness/agent/transcription.rb

@@ -0,0 +1,65 @@
+module ActiveHarness
+  class Agent
+    class << self
+      # Mark this agent as an audio transcription agent.
+      #
+      #   class TranscriptionAgent < ActiveHarness::Agent
+      #     transcribe true
+      #
+      #     model do
+      #       use      provider: :openrouter, model: "openai/whisper-1"
+      #       fallback provider: :openrouter, model: "deepgram/nova-3"
+      #     end
+      #   end
+      #
+      # @input           — path to a local audio file (String), not free text
+      # result.output    — transcribed text (String)
+      # result.processed — same as output (format :text default)
+      def transcribe(value = true)
+        agent_config[:transcribe] = value
+      end
+
+      # Default ISO-639-1 language hint for all models in this agent's chain.
+      # Can be overridden per-model via:  use provider: :openrouter, model: "...", language: "ja"
+      def language(default_language)
+        agent_config[:transcribe_language] = default_language
+      end
+    end
+
+    alias_method :_model_list_before_transcribe, :model_list
+
+    def model_list
+      list = _model_list_before_transcribe
+      validate_transcription_models!(list) if @config[:transcribe]
+      list
+    end
+
+    private
+
+    alias_method :_normalize_input_before_transcribe, :normalize_input!
+
+    # @input is a file path for transcription agents, not free text —
+    # stripping/collapsing whitespace could corrupt a path. Skip it.
+    def normalize_input!
+      return if @config[:transcribe]
+      _normalize_input_before_transcribe
+    end
+
+    # Models absent from the Pricing registry are silently skipped — unknown
+    # models are assumed valid to avoid false negatives on new/private models.
+    def validate_transcription_models!(list)
+      list.each do |entry|
+        info = Pricing.find(entry[:model].to_s)
+        next unless info
+
+        unless info.categories.include?("transcription")
+          raise ArgumentError,
+            "#{self.class.name}: model #{entry[:model].inspect} (provider: #{entry[:provider]}) " \
+            "does not support audio transcription " \
+            "(output_modalities: #{info.output_modalities.inspect}). " \
+            "Use a model that has 'transcription' in output_modalities."
+        end
+      end
+    end
+  end
+end

data/lib/active_harness/agent.rb

@@ -213,4 +213,5 @@ require_relative "agent/output_parser"
 require_relative "agent/custom_llm_backend"
 require_relative "agent/cost"
 require_relative "agent/image"
+require_relative "agent/transcription"
 

data/lib/active_harness/providers/audio/openai.rb

@@ -0,0 +1,127 @@
+require "uri"
+require "securerandom"
+
+module ActiveHarness
+  module Providers
+    module Audio
+      class OpenAI < Base
+        ENDPOINT = "https://api.openai.com/v1/audio/transcriptions"
+
+        # OpenAI's transcription endpoint only accepts these formats — notably
+        # no flac/ogg/aac, unlike OpenRouter's version of this endpoint.
+        CONTENT_TYPES = {
+          "mp3"  => "audio/mpeg",
+          "mp4"  => "audio/mp4",
+          "mpeg" => "audio/mpeg",
+          "mpga" => "audio/mpeg",
+          "m4a"  => "audio/mp4",
+          "wav"  => "audio/wav",
+          "webm" => "audio/webm"
+        }.freeze
+
+        # @param model        [String]  e.g. "whisper-1", "gpt-4o-transcribe", "gpt-4o-mini-transcribe"
+        # @param audio_data   [String]  raw binary audio bytes
+        # @param audio_format [String]  one of CONTENT_TYPES.keys
+        # @param language     [String]  ISO-639-1 code, e.g. "en" (optional — auto-detected if omitted)
+        #
+        # Synchronous — this endpoint has no job/polling API. Unlike OpenRouter's
+        # transcription endpoint, OpenAI's is multipart/form-data only (no
+        # base64/JSON request mode).
+        def call(model:, audio_data:, audio_format:, language: nil, **_)
+          content_type = CONTENT_TYPES[audio_format]
+          unless content_type
+            raise Errors::InvalidRequestError,
+              "openai transcription does not support .#{audio_format} — use one of: #{CONTENT_TYPES.keys.join(', ')}"
+          end
+
+          boundary = SecureRandom.hex(16)
+          fields   = { "model" => model }
+          fields["language"] = language if language
+
+          body = build_multipart_body(boundary, fields, audio_data, "audio.#{audio_format}", content_type)
+          headers = {
+            "Content-Type"  => "multipart/form-data; boundary=#{boundary}",
+            "Authorization" => "Bearer #{api_key}"
+          }
+
+          raw  = HTTP.post(URI(ENDPOINT), headers: headers, body: body, timeout: 90)
+          data = parse!(raw)
+          handle_error!(data)
+
+          text = data["text"]
+          raise Errors::ProviderError, "No transcription text in response: #{data.keys}" if text.nil?
+
+          { content: text, provider: :openai, model: model, usage: extract_transcription_usage(data) }
+        end
+
+        private
+
+        def build_multipart_body(boundary, fields, file_data, filename, content_type)
+          body = +""
+          fields.each do |name, value|
+            body << "--#{boundary}\r\n"
+            body << "Content-Disposition: form-data; name=\"#{name}\"\r\n\r\n"
+            body << "#{value}\r\n"
+          end
+
+          body << "--#{boundary}\r\n"
+          body << "Content-Disposition: form-data; name=\"file\"; filename=\"#{filename}\"\r\n"
+          body << "Content-Type: #{content_type}\r\n\r\n"
+          body << file_data
+          body << "\r\n--#{boundary}--\r\n"
+          body
+        end
+
+        # whisper-1 reports usage as { type: "duration", seconds: N } — no token
+        # counts, so there's nothing to map to input_tokens/output_tokens. Newer
+        # models (gpt-4o-transcribe, gpt-4o-mini-transcribe) report
+        # { type: "tokens", input_tokens:, output_tokens:, total_tokens:, ... }.
+        # Neither reports a direct dollar cost like OpenRouter does — cost is left
+        # to the normal per-token Pricing lookup, which returns nil for
+        # duration-billed models since it has no token counts to work with.
+        def extract_transcription_usage(data)
+          u = data["usage"]
+          return nil unless u && u["type"] == "tokens"
+
+          {
+            input_tokens:  u["input_tokens"].to_i,
+            output_tokens: u["output_tokens"].to_i,
+            total_tokens:  u["total_tokens"].to_i
+          }
+        end
+
+        def api_key
+          key = config.openai_api_key.to_s
+          raise Errors::InvalidApiKeyError, "openai_api_key is not configured" if key.empty?
+          key
+        end
+
+        def handle_error!(data)
+          return unless data["error"]
+
+          msg      = data.dig("error", "message").to_s
+          code     = data.dig("error", "code").to_s
+          type     = data.dig("error", "type").to_s
+          metadata = data["error"].reject { |k, _| %w[message code type].include?(k) }
+          metadata = nil if metadata.empty?
+
+          case code
+          when "invalid_api_key", "unauthorized"
+            raise Errors::InvalidApiKeyError.new(msg,  error_code: code, metadata: metadata)
+          when "rate_limit_exceeded"
+            raise Errors::RateLimitError.new(msg,      error_code: code, metadata: metadata)
+          when "content_filter"
+            raise Errors::SafetyBlockedError.new(msg,  error_code: code, metadata: metadata)
+          else
+            case type
+            when "server_error"
+              raise Errors::ServerError.new(msg,       error_code: code, metadata: metadata)
+            else
+              raise Errors::InvalidRequestError.new(msg, error_code: code, metadata: metadata)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_harness/providers/audio/openrouter.rb

@@ -0,0 +1,85 @@
+require "uri"
+require "base64"
+
+module ActiveHarness
+  module Providers
+    module Audio
+      class OpenRouter < Base
+        # Dedicated transcription endpoint — distinct from the chat completions
+        # endpoint used by text/image generation on OpenRouter.
+        ENDPOINT = "https://openrouter.ai/api/v1/audio/transcriptions"
+
+        # @param model        [String]  e.g. "openai/whisper-1", "deepgram/nova-3"
+        # @param audio_data   [String]  raw binary audio bytes
+        # @param audio_format [String]  "wav", "mp3", "flac", "m4a", "ogg", "webm", "aac"
+        # @param language     [String]  ISO-639-1 code, e.g. "en" (optional — auto-detected if omitted)
+        #
+        # Synchronous call — OpenRouter's transcription endpoint has no job/polling
+        # API. Upstream providers time out after ~60s per request, so long audio
+        # should be split into shorter chunks by the caller before transcribing.
+        def call(model:, audio_data:, audio_format:, language: nil, **_)
+          headers = {
+            "Content-Type"  => "application/json",
+            "Authorization" => "Bearer #{api_key}"
+          }
+          referer = config.openrouter_http_referer.to_s
+          headers["HTTP-Referer"] = referer unless referer.empty?
+
+          body = {
+            model: model,
+            input_audio: { data: Base64.strict_encode64(audio_data), format: audio_format }
+          }
+          body[:language] = language if language
+
+          raw  = post_json(URI(ENDPOINT), headers: headers, body: body, timeout: 90)
+          data = parse!(raw)
+          handle_error!(data)
+
+          text = data["text"]
+          raise Errors::ProviderError, "No transcription text in response: #{data.keys}" if text.nil?
+
+          { content: text, provider: :openrouter, model: model, usage: extract_transcription_usage(data) }
+        end
+
+        private
+
+        # OpenRouter's transcription usage shape differs from its chat/image usage
+        # shape (input_tokens/output_tokens directly, not prompt_tokens/completion_tokens).
+        def extract_transcription_usage(data)
+          u = data["usage"]
+          return nil unless u
+
+          result = {
+            input_tokens:  u["input_tokens"].to_i,
+            output_tokens: u["output_tokens"].to_i,
+            total_tokens:  u["total_tokens"].to_i
+          }
+          result[:provider_cost] = u["cost"].to_f if u.key?("cost")
+          result
+        end
+
+        def api_key
+          key = config.openrouter_api_key.to_s
+          raise Errors::InvalidApiKeyError, "openrouter_api_key is not configured" if key.empty?
+          key
+        end
+
+        def handle_error!(data)
+          return unless data["error"]
+
+          msg      = data.dig("error", "message").to_s
+          code     = data.dig("error", "code").to_s
+          metadata = data.dig("error", "metadata")
+
+          case code
+          when "401"             then raise Errors::InvalidApiKeyError.new(msg,       error_code: code, metadata: metadata)
+          when "402", "429"      then raise Errors::RateLimitError.new(msg,           error_code: code, metadata: metadata)
+          when "500", "502",
+               "503", "504"      then raise Errors::ProviderUnavailableError.new(msg, error_code: code, metadata: metadata)
+          else                        raise Errors::InvalidRequestError.new(msg,      error_code: code, metadata: metadata)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_harness.rb

@@ -23,6 +23,8 @@ require_relative "active_harness/providers/vertexai"
 require_relative "active_harness/providers/custom"
 require_relative "active_harness/providers/images/openai"
 require_relative "active_harness/providers/images/openrouter"
+require_relative "active_harness/providers/audio/openai"
+require_relative "active_harness/providers/audio/openrouter"
 require "active_harness_pricing"
 require_relative "active_harness/memory"
 require_relative "active_harness/agent"
@@ -32,7 +34,7 @@ require_relative "active_harness/pipeline"
 require_relative "active_harness/railtie" if defined?(Rails::Railtie)
 
 module ActiveHarness
-  VERSION = "0.2.40"
+  VERSION = "0.2.42"
 
   class << self
     # Configure ActiveHarness.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_harness
 version: !ruby/object:Gem::Version
-  version: 0.2.40
+  version: 0.2.42
 platform: ruby
 authors:
 - the-teacher
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-07-19 00:00:00.000000000 Z
+date: 2026-07-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -55,6 +55,7 @@ files:
 - lib/active_harness/agent/output_parser.rb
 - lib/active_harness/agent/prompt.rb
 - lib/active_harness/agent/providers.rb
+- lib/active_harness/agent/transcription.rb
 - lib/active_harness/configuration.rb
 - lib/active_harness/core/errors.rb
 - lib/active_harness/core/hooks.rb
@@ -72,6 +73,8 @@ files:
 - lib/active_harness/pipeline/step.rb
 - lib/active_harness/providers/PROVIDER_CONTRACT.md
 - lib/active_harness/providers/anthropic.rb
+- lib/active_harness/providers/audio/openai.rb
+- lib/active_harness/providers/audio/openrouter.rb
 - lib/active_harness/providers/azure.rb
 - lib/active_harness/providers/base.rb
 - lib/active_harness/providers/bedrock.rb