active_harness 0.2.39 → 0.2.41

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 656a10b468592b8e0c53c2c93a8fbf7b8536420f94bd0cb7a61255d432ee78ed
-  data.tar.gz: 29de2c821b23ba363ef1596fb545035fbd1191ca6487161f6b9f30b39fe960db
+  metadata.gz: e575886969a297ab3688f08a326e0290b1f7c433322c7a05aab8f183178e441e
+  data.tar.gz: 8b73cfb142335117fd7bde7c6da6ebca88f7218906450a1897b2cd42ea9b37d5
 SHA512:
-  metadata.gz: 9d0d4c4114ed028a603a783841c5205163f1f02203e7c010d5c806a8e673644b391cbfb636bbb1c4d77eb40a807907e63380213b087ab3c5515491c1c2c64fcf
-  data.tar.gz: 84b154cb18717e6183337d728a6eb3ec9d34753856d6acc8fbf96c90e06a6e0db799b961b3f8d5bd7dc3984797bed401429a3110573243379eb471fcd84f160b
+  metadata.gz: 51060b54a300332514f5993d83b5666416da70dc51493d06259106909c17a96262d28991290cbcc51b4018f324e82d06f274cd292d81ad65ad9b99a33a82060d
+  data.tar.gz: f4041988b036d9b252c0081e3e664febabaf72cbc69995629f21b6b6711c7a4283a1d9e30fb388f0bbde0a127c940e54cd3a4b325978798a4d090e93ecf639dc

data/lib/active_harness/agent/image.rb

@@ -7,6 +7,10 @@ module ActiveHarness
       #     image true
       #     size  "1024x1024"
       #
+      #     # Optional: base style/formatting guidance, prepended to @input
+      #     # to form the final image prompt (see Agent#build_image_prompt).
+      #     system_prompt "Watercolor style, soft pastel colors, no text overlays."
+      #
       #     model do
       #       use      provider: :openrouter, model: "openai/gpt-5-image-mini"
       #       fallback provider: :openai,     model: "gpt-image-1"

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)                   if @config[:image]
+      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)
@@ -58,17 +63,44 @@ module ActiveHarness
       provider.call(**opts)
     end
 
-    def attempt_image_model(entry)
+    def attempt_image_model(entry, system_prompt)
       factory = IMAGE_PROVIDERS[entry[:provider].to_sym]
       raise ArgumentError, "Provider #{entry[:provider].inspect} does not support image generation. " \
                            "Supported image providers: #{IMAGE_PROVIDERS.keys.join(', ')}" unless factory
 
       size = entry[:size] || @config[:image_size] || "1024x1024"
-      opts = { model: entry[:model], prompt: @input.to_s, size: size }
+      opts = { model: entry[:model], prompt: build_image_prompt(system_prompt, @input.to_s), size: size }
       opts[:quality] = entry[:quality] if entry[:quality]
       factory.call.call(**opts)
     end
 
+    # Image APIs take a single prompt string (no system/user role split), so the
+    # system prompt — e.g. base style/formatting guidance — is prepended to the
+    # user's input rather than sent as a separate message.
+    def build_image_prompt(system_prompt, input)
+      return input if system_prompt.nil? || system_prompt.to_s.strip.empty?
+
+      "#{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/memory.rb

@@ -10,14 +10,21 @@ module ActiveHarness
   # It does NOT automatically inject history into LLM messages.
   # Injection is always manual — you control when and how context is used.
   #
-  # --- Recording (automatic) ---
+  # --- Recording ---
   #
-  # When a Memory object is passed to an agent, the agent automatically
-  # saves each successful turn (request + response) after the call.
+  # Passing a Memory object to Agent.call(memory:) does NOT by itself save
+  # anything — Agent never calls #load or #record on it. Loading and
+  # recording turns for a bare agent call is entirely manual (e.g. via
+  # before_call/after_call hooks calling @memory.load / @memory.record).
+  #
+  # Pipeline is the one place recording is automatic: when a Memory is
+  # passed to Pipeline#call, the pipeline itself calls #load before running
+  # steps and #record after a successful run — independent of any hooks the
+  # individual agents define.
   #
   #   memory = ActiveHarness::Memory.new(session_id: "u42", depth: 8)
   #   SupportAgent.call(input: "Hello", memory: memory)
-  #   # => turn is saved to storage/ai/memory/u42.json
+  #   # => nothing is saved unless SupportAgent's own hooks record it
   #
   # --- Manual injection patterns ---
   #

data/lib/active_harness/pipeline/README.md

@@ -25,7 +25,7 @@ pipeline.call
 
 pipeline.output       # => final payload string (nil if stopped)
 pipeline.stopped?     # => false
-pipeline.step_results # => { translate: <Result>, injection_guard: <Result>, ... }
+pipeline.steps.to_a   # => [[:translate, <TranslationAgent>, <Result>], [:injection_guard, <InjectionGuardAgent>, <Result>], ...]
 ```
 
 ## Step types

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.39"
+  VERSION = "0.2.41"
 
   class << self
     # Configure ActiveHarness.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_harness
 version: !ruby/object:Gem::Version
-  version: 0.2.39
+  version: 0.2.41
 platform: ruby
 authors:
 - the-teacher
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-06-15 00:00:00.000000000 Z
+date: 2026-07-19 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,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