active_harness 0.2.40 → 0.2.41

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4246d31550942e31c26ec9a708f49aae5b2e0f385a32aeaa06d6d6a75f2849ee
-  data.tar.gz: d7f12a75e7f72e3d004bfd3b64a094e99a082992fd0077e69253bddf97b919f0
+  metadata.gz: e575886969a297ab3688f08a326e0290b1f7c433322c7a05aab8f183178e441e
+  data.tar.gz: 8b73cfb142335117fd7bde7c6da6ebca88f7218906450a1897b2cd42ea9b37d5
 SHA512:
-  metadata.gz: 81cf0f7cb7f5f54c2a996097e34461f724bd66da920db0cee57cc84f558f8430bc83ad1e914c62a56f3493e890c993c9f2dd9408c161563ae8c161f5ac03e4d5
-  data.tar.gz: e144ed04675d274af6d66157a2f733e1cb65342adc7312b10428e9afc3c135b64af616218d6bb9ddbfb36948efd0e83b817f36654523f910c51d4797e07674e6
+  metadata.gz: 51060b54a300332514f5993d83b5666416da70dc51493d06259106909c17a96262d28991290cbcc51b4018f324e82d06f274cd292d81ad65ad9b99a33a82060d
+  data.tar.gz: f4041988b036d9b252c0081e3e664febabaf72cbc69995629f21b6b6711c7a4283a1d9e30fb388f0bbde0a127c940e54cd3a4b325978798a4d090e93ecf639dc

data/lib/active_harness/agent/providers.rb

@@ -43,11 +43,16 @@ module ActiveHarness
       openrouter:  -> { Providers::Images::OpenRouter.new }
     }.freeze
 
+    TRANSCRIPTION_PROVIDERS = {
+      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 +83,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/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,7 @@ 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/openrouter"
 require "active_harness_pricing"
 require_relative "active_harness/memory"
 require_relative "active_harness/agent"
@@ -32,7 +33,7 @@ require_relative "active_harness/pipeline"
 require_relative "active_harness/railtie" if defined?(Rails::Railtie)
 
 module ActiveHarness
-  VERSION = "0.2.40"
+  VERSION = "0.2.41"
 
   class << self
     # Configure ActiveHarness.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_harness
 version: !ruby/object:Gem::Version
-  version: 0.2.40
+  version: 0.2.41
 platform: ruby
 authors:
 - the-teacher
@@ -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,7 @@ 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/openrouter.rb
 - lib/active_harness/providers/azure.rb
 - lib/active_harness/providers/base.rb
 - lib/active_harness/providers/bedrock.rb