active_harness 0.2.41 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e575886969a297ab3688f08a326e0290b1f7c433322c7a05aab8f183178e441e
-  data.tar.gz: 8b73cfb142335117fd7bde7c6da6ebca88f7218906450a1897b2cd42ea9b37d5
+  metadata.gz: 779258acc7a5947e923ac8f5ad262f653e96ad0509585f8a309e362bc0ee3703
+  data.tar.gz: 1364d064abfe80ccdd5fdadd7bfb6d55396ec2ceaf7680d0bdd1373011cd9923
 SHA512:
-  metadata.gz: 51060b54a300332514f5993d83b5666416da70dc51493d06259106909c17a96262d28991290cbcc51b4018f324e82d06f274cd292d81ad65ad9b99a33a82060d
-  data.tar.gz: f4041988b036d9b252c0081e3e664febabaf72cbc69995629f21b6b6711c7a4283a1d9e30fb388f0bbde0a127c940e54cd3a4b325978798a4d090e93ecf639dc
+  metadata.gz: 94bf07f8a86b78da1f5507e02644c1a6bb2310074ea3b02eca476164480a546c286d12c699ee97743a4e8b9e1c52fd74f1fc1f33e90f1302c4235b0009e2bbd6
+  data.tar.gz: 3355b0cb47da66faa4164f4712ba7f5e9e0e23d405a00177599ce26d34255ea3e80b29effa8f9fa7d5bfc34e6dfb45005e0a6281df70dfa847db965e7039e54e

data/lib/active_harness/configuration.rb

@@ -52,6 +52,7 @@ module ActiveHarness
     # -------------------------------------------------------------------------
     attr_accessor :openrouter_api_key
     attr_accessor :openrouter_api_url
+    attr_accessor :openrouter_images_api_url
     attr_accessor :openrouter_http_referer
 
     # -------------------------------------------------------------------------
@@ -111,7 +112,7 @@ module ActiveHarness
     #     config.custom["SecondProvider"]["api_key"] = ENV["SECOND_API_KEY"]
     #   end
     #
-    # Use in an agent:
+    # Use in a request:
     #   model do
     #     use      provider: :custom, name: "MyLocal",       model: "llama3.2"
     #     fallback provider: :custom, name: "SecondProvider", model: "mixtral"
@@ -144,6 +145,7 @@ module ActiveHarness
 
       @openrouter_api_key      = ENV["OPENROUTER_API_KEY"]
       @openrouter_api_url      = "https://openrouter.ai/api/v1/chat/completions"
+      @openrouter_images_api_url = ENV.fetch("OPENROUTER_IMAGES_API_URL", "https://openrouter.ai/api/v1/images")
       @openrouter_http_referer = "https://github.com/the-teacher/ActiveHarness"
 
       @xai_api_key = ENV["XAI_API_KEY"]

data/lib/active_harness/core/errors.rb

@@ -5,8 +5,8 @@ module ActiveHarness
     # Raised when all models in the chain fail
     AllModelsFailed = Class.new(Error)
 
-    # Raised by Tribunal when every agent fails or times out
-    AllAgentsFailed = Class.new(Error)
+    # Raised by Tribunal when every request fails or times out
+    AllRequestsFailed = Class.new(Error)
 
     # Base for all provider-level failures — carries an optional error_code and metadata
     class ProviderError < Error

data/lib/active_harness/core/hooks.rb

@@ -1,13 +1,13 @@
 module ActiveHarness
   module Core
-    # Shared hook execution logic included by Agent, Tribunal, and Pipeline.
+    # Shared hook execution logic included by Request, Tribunal, and Pipeline.
     #
     # Hooks are stored in arrays so multiple +on+/+before+/+after+/+callback+
     # calls with the same event name accumulate — later registrations append
     # rather than overwrite. This lets modules register default hooks without
     # blocking user-defined hooks on the same event.
     #
-    #   class MyAgent < ActiveHarness::Agent
+    #   class MyRequest < ActiveHarness::Request
     #     include SomeTracingConcern   # registers before(:call) internally
     #     before(:call) { ... }        # appends — both hooks run in order
     #   end

data/lib/active_harness/memory.rb

@@ -4,7 +4,7 @@ require_relative "memory/adapter/postgresql"
 require_relative "memory/adapter/sqlite"
 
 module ActiveHarness
-  # Conversational memory for agents.
+  # Conversational memory for requests.
   #
   # Memory only records the history of request/response turns.
   # It does NOT automatically inject history into LLM messages.
@@ -12,19 +12,19 @@ module ActiveHarness
   #
   # --- Recording ---
   #
-  # 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
+  # Passing a Memory object to Request.call(memory:) does NOT by itself save
+  # anything — Request never calls #load or #record on it. Loading and
+  # recording turns for a bare request 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.
+  # individual requests define.
   #
   #   memory = ActiveHarness::Memory.new(session_id: "u42", depth: 8)
-  #   SupportAgent.call(input: "Hello", memory: memory)
-  #   # => nothing is saved unless SupportAgent's own hooks record it
+  #   SupportRequest.call(input: "Hello", memory: memory)
+  #   # => nothing is saved unless SupportRequest's own hooks record it
   #
   # --- Manual injection patterns ---
   #
@@ -76,7 +76,7 @@ module ActiveHarness
     #   adapter          — :json_file (default), or an adapter instance
     #   enabled          — false disables all reads and writes (no-op mode)
     #   read_only        — true: load history but never write new turns
-    #   namespace        — isolates history per-agent within a session
+    #   namespace        — isolates history per-request within a session
     #   on_trim          — Proc called with trimmed turns on storage trim
     #   async            — write to adapter in a background thread
     #   **adapter_opts   — forwarded to the adapter (path, storage_size, etc.)
@@ -117,7 +117,7 @@ module ActiveHarness
     # -------------------------------------------------------------------------
 
     # Load history from storage into RAM.
-    # Called automatically by the agent at the start of #call.
+    # Called automatically by the request at the start of #call.
     # After loading, history is available via #turns and #to_messages
     # for manual injection in hooks or prompt classes.
     def load
@@ -129,7 +129,7 @@ module ActiveHarness
       @loaded = true
     end
 
-    # Record a turn after a successful agent call.
+    # Record a turn after a successful request call.
     def record(request:, response:, **meta)
       return unless @enabled
       return if @read_only
@@ -151,7 +151,7 @@ module ActiveHarness
 
     # Returns messages array for LLM consumption, respecting depth.
     # Optional filters:
-    #   filter:       ->(turn) { turn[:agent] == "SupportAgent" }
+    #   filter:       ->(turn) { turn[:request_class] == "SupportRequest" }
     #   since:        Time.now - 3600
     #   token_budget: 4000  # rough limit (chars / 4 estimate); trims oldest turns first
     def to_messages(filter: nil, since: nil, token_budget: nil)

data/lib/active_harness/pipeline/README.md

@@ -1,16 +1,16 @@
 # Pipeline
 
-A pipeline chains multiple agents and tribunals into a sequential workflow.
+A pipeline chains multiple requests and tribunals into a sequential workflow.
 Each step receives the current payload, can transform it, and can stop the pipeline early.
 
 ## Basic usage
 
 ```ruby
 class SupportPipeline < ActiveHarness::Pipeline
-  step :translate, TranslationAgent
+  step :translate, TranslationRequest
 
   step :injection_guard do
-    use InjectionGuardAgent
+    use InjectionGuardRequest
     stop_if ->(result) { result.processed["detected"] == true }
   end
 
@@ -25,17 +25,17 @@ pipeline.call
 
 pipeline.output       # => final payload string (nil if stopped)
 pipeline.stopped?     # => false
-pipeline.steps.to_a   # => [[:translate, <TranslationAgent>, <Result>], [:injection_guard, <InjectionGuardAgent>, <Result>], ...]
+pipeline.steps.to_a   # => [[:translate, <TranslationRequest>, <Result>], [:injection_guard, <InjectionGuardRequest>, <Result>], ...]
 ```
 
 ## Step types
 
 There are two kinds of classes a step can use.
 
-**Agent step** — runs the agent, takes `result.output` as the new payload:
+**Request step** — runs the request, takes `result.output` as the new payload:
 
 ```ruby
-step :translate, TranslationAgent
+step :translate, TranslationRequest
 ```
 
 **Tribunal step** — runs the tribunal, returns a `Result` with `processed["verdict"]`.
@@ -54,8 +54,8 @@ The payload starts as the value passed to `input:` and flows through the steps:
 
 | Condition | Payload after step |
 |-----------|--------------------|
-| Agent step, no `stop_if` | Updated to `result.output` |
-| Agent step with `stop_if` | Unchanged (guard step) |
+| Request step, no `stop_if` | Updated to `result.output` |
+| Request step with `stop_if` | Unchanged (guard step) |
 | Tribunal step | Unchanged |
 
 After each step the result is also stored in `context[step_name]`,
@@ -67,7 +67,7 @@ Any step can stop the pipeline by defining `stop_if`:
 
 ```ruby
 step :injection_guard do
-  use InjectionGuardAgent
+  use InjectionGuardRequest
   stop_if ->(result) { result.processed["detected"] == true }
 end
 ```
@@ -82,7 +82,7 @@ When the condition is true:
 
 ```ruby
 class SupportPipeline < ActiveHarness::Pipeline
-  on_agent_event    do |event, result|  ... end  # fires for every agent inside
+  on_request_event  do |event, result|  ... end  # fires for every request inside
   on_tribunal_event do |event, verdict| ... end  # fires for every tribunal inside
   on_pipeline_event do |event, *args|   ... end  # :before_step, :after_step, :stopped, :complete
 end
@@ -93,7 +93,7 @@ Runtime streams can be passed at construction time:
 ```ruby
 SupportPipeline.new(
   input:   "...",
-  streams: { token: token_lambda, agent: agent_lambda }
+  streams: { token: token_lambda, request: request_lambda }
 )
 ```
 
@@ -112,7 +112,7 @@ SupportPipeline.new(input: "...", memory: mem).call
 
 ## Proposal: universal step interface
 
-Currently `Pipeline::Step` special-cases two concrete classes: `Agent` and `Tribunal`.
+Currently `Pipeline::Step` special-cases two concrete classes: `Request` and `Tribunal`.
 This section explores making the pipeline open to any entity — a plain Ruby object,
 a lambda, a nested pipeline, an HTTP call, a cache lookup — with no inheritance required.
 
@@ -149,7 +149,7 @@ Pipeline::StepResult = Struct.new(:output, :stop, keyword_init: true) do
 end
 ```
 
-**Pros:** almost no change to existing code; agents and tribunals get thin adapters.  
+**Pros:** almost no change to existing code; requests and tribunals get thin adapters.  
 **Cons:** every custom step must construct `StepResult`; slightly more boilerplate.
 
 ---
@@ -208,7 +208,7 @@ step :length_guard, LengthGuard.new
 
 **Pros:** stateless, composable, easy to test (`call(env)` in one line); nested
 pipelines become trivial — a pipeline is just another object with `call(env)`.  
-**Cons:** largest departure from the current API; requires migrating Agent/Tribunal wrappers.
+**Cons:** largest departure from the current API; requires migrating Request/Tribunal wrappers.
 
 ---
 
@@ -229,7 +229,7 @@ class EnrichStep
 end
 ```
 
-Agents and Tribunals include `Callable` automatically, so they work as before.
+Requests and Tribunals include `Callable` automatically, so they work as before.
 Any plain class can opt in with one `include`.
 
 **Pros:** clear opt-in contract; helpers reduce boilerplate; IDE-friendly.  

data/lib/active_harness/pipeline/step.rb

@@ -10,7 +10,7 @@ module ActiveHarness
         instance_eval(&block) if block_given?
       end
 
-      # DSL: use TranslationAgent / SafetyTribunal / NestedPipeline
+      # DSL: use TranslationRequest / SafetyTribunal / NestedPipeline
       def use(klass)
         @executor = klass
       end

data/lib/active_harness/pipeline.rb

@@ -1,16 +1,16 @@
 module ActiveHarness
-  # Sequential pipeline that chains agents and tribunals.
+  # Sequential pipeline that chains requests and tribunals.
   # Each step receives the current payload and can transform it or stop the pipeline.
   #
   # Usage (subclass with DSL):
   #
   #   class SupportPipeline < ActiveHarness::Pipeline
   #     step :injection_guard do
-  #       use InjectionGuardAgent
+  #       use InjectionGuardRequest
   #       stop_if ->(result) { result.processed["detected"] == true }
   #     end
   #
-  #     step :translate, TranslationAgent   # shorthand — no stop_if
+  #     step :translate, TranslationRequest   # shorthand — no stop_if
   #
   #     step :safety_tribunal do
   #       use SafetyTribunal
@@ -38,12 +38,12 @@ module ActiveHarness
     class << self
       # Define a step in the pipeline.
       #
-      # Shorthand (agent only, no stop_if):
-      #   step :translate, TranslationAgent
+      # Shorthand (request only, no stop_if):
+      #   step :translate, TranslationRequest
       #
       # Full block form:
       #   step :injection_guard do
-      #     use InjectionGuardAgent
+      #     use InjectionGuardRequest
       #     stop_if ->(result) { result.processed["detected"] == true }
       #   end
       def step(name, executor = nil, &block)
@@ -63,13 +63,13 @@ module ActiveHarness
       end
 
       # Class-level event stream handlers — fired for every matching event from
-      # any agent or tribunal executed within this pipeline (including agents
+      # any request or tribunal executed within this pipeline (including requests
       # running inside tribunals). Multiple blocks can be registered; all fire.
       #
       # The handler receives (event, *args) — already scoped to the source.
       #
-      #   on_agent_event do |event, result|
-      #     Rails.logger.info "[Agent #{event}] #{result.model}" if event == :after_call
+      #   on_request_event do |event, result|
+      #     Rails.logger.info "[Request #{event}] #{result.model}" if event == :after_call
       #   end
       #
       #   on_tribunal_event do |event, verdict|
@@ -79,8 +79,8 @@ module ActiveHarness
       #   on_pipeline_event do |event, step_name, _data|
       #     Rails.logger.info "[Pipeline #{event}] step=#{step_name}"
       #   end
-      def on_agent_event(&block)
-        (pipeline_config[:streams][:agent] ||= []) << block
+      def on_request_event(&block)
+        (pipeline_config[:streams][:request] ||= []) << block
       end
 
       def on_tribunal_event(&block)
@@ -157,7 +157,7 @@ module ActiveHarness
     #   pipeline.steps { |name, executor, result| }
     #
     #   name     — step name symbol          (:translate, :guard, …)
-    #   executor — the instance that ran     (TranslationAgent instance, …)
+    #   executor — the instance that ran     (TranslationRequest instance, …)
     #   result   — Result struct             (output, processed, usage, model, …)
     #
     #   pipeline.steps.map { |name, executor, result| [name, result.output] }
@@ -173,7 +173,7 @@ module ActiveHarness
     end
 
     # Wraps pipeline outcome into a Result so a pipeline can be used as a step
-    # inside another pipeline, matching the same interface as Agent and Tribunal.
+    # inside another pipeline, matching the same interface as Request and Tribunal.
     #
     # output    — final payload (nil when stopped)
     # processed — { "stopped" => bool, "stopped_at" => step_name_string_or_nil }
@@ -187,7 +187,7 @@ module ActiveHarness
     end
 
     # Execute all steps sequentially. Returns self for chaining.
-    # Accepts optional input, token, stream to match the Agent/Tribunal call interface.
+    # Accepts optional input, token, stream to match the Request/Tribunal call interface.
     def call(input = nil, token: nil, stream: nil)
       if input
         @original_input = input
@@ -245,24 +245,24 @@ module ActiveHarness
     private
 
     # Combines a runtime-passed stream lambda with class-level handler blocks
-    # registered via on_agent_event / on_tribunal_event / on_pipeline_event.
+    # registered via on_request_event / on_tribunal_event / on_pipeline_event.
     # Returns nil when there are no handlers at all.
     #
     # Class-level handlers receive (event, *args) — already scoped to source.
     # Runtime lambda receives (source, event, *args).
     # instance_exec lets class-level blocks access pipeline instance variables.
     def merge_stream(passed_in, class_handlers)
-      agent_handlers    = Array(class_handlers[:agent]).compact
+      request_handlers  = Array(class_handlers[:request]).compact
       tribunal_handlers = Array(class_handlers[:tribunal]).compact
       pipeline_handlers = Array(class_handlers[:pipeline]).compact
 
-      has_class_handlers = agent_handlers.any? || tribunal_handlers.any? || pipeline_handlers.any?
+      has_class_handlers = request_handlers.any? || tribunal_handlers.any? || pipeline_handlers.any?
       return passed_in unless has_class_handlers
 
       pipeline_instance = self
       ->(source, event, *args) {
         handlers = case source
-                   when :agent    then agent_handlers
+                   when :request  then request_handlers
                    when :tribunal then tribunal_handlers
                    when :pipeline then pipeline_handlers
                    else                []

data/lib/active_harness/providers/PROVIDER_CONTRACT.md

@@ -50,5 +50,5 @@ raise Errors::RateLimitError.new(msg, error_code: code, metadata: metadata)
 | `InvalidApiKeyError`       | no        | Missing or invalid API key       |
 | `SafetyBlockedError`       | no        | Content policy violation         |
 
-Retryable errors cause the agent to move to the next model in the chain.
+Retryable errors cause the request to move to the next model in the chain.
 Non-retryable errors abort the chain immediately and are re-raised.

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/azure.rb

@@ -20,7 +20,7 @@ module ActiveHarness
     #   POST {azure_api_base}/openai/deployments/{deployment}/chat/completions
     #        ?api-version={azure_api_version}
     #
-    # Example agent config:
+    # Example request config:
     #   model do
     #     use provider: :azure, model: "my-gpt4o-deployment", temperature: 0.7
     #   end

data/lib/active_harness/providers/bedrock.rb

@@ -4,12 +4,12 @@ module ActiveHarness
     #
     # Bedrock requires AWS Signature V4 request signing, which is non-trivial
     # to implement and carries AWS SDK dependencies. This stub raises a clear
-    # error so that the agent falls through to the next model in its fallback chain.
+    # error so that the request falls through to the next model in its fallback chain.
     #
     # To use Bedrock in production, please look for a dedicated gem, for example:
     #   gem "active_harness-bedrock"  (not yet released — contributions welcome)
     #
-    # Example agent config (will fall through to the next fallback):
+    # Example request config (will fall through to the next fallback):
     #   model do
     #     use      provider: :bedrock, model: "anthropic.claude-3-5-sonnet-20241022-v2:0"
     #     fallback provider: :anthropic, model: "claude-3-5-sonnet-20241022"

data/lib/active_harness/providers/custom.rb

@@ -14,7 +14,7 @@ module ActiveHarness
     #     config.custom["SecondProvider"]["api_key"] = ENV["SECOND_API_KEY"]
     #   end
     #
-    # Use in an agent:
+    # Use in a request:
     #
     #   model do
     #     use      provider: :custom, name: "MyLocal",        model: "llama3.2"

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

@@ -6,6 +6,8 @@ module ActiveHarness
       class OpenRouter < Base
         # @param model  [String]  e.g. "openai/gpt-5-image-mini", "google/gemini-2.5-flash-image"
         # @param prompt [String]  image description
+        # Image-only models use OpenRouter's dedicated Images API. Models that
+        # also output text retain the legacy chat-completions request path.
         # @param size   [String]  ignored by OpenRouter (passed through for future support)
         def call(model:, prompt:, size: nil, quality: nil, **_)
           headers = {
@@ -15,6 +17,22 @@ module ActiveHarness
           referer = config.openrouter_http_referer.to_s
           headers["HTTP-Referer"] = referer unless referer.empty?
 
+          return call_images_api(model, prompt, size, quality, headers) if image_only_model?(model)
+
+          call_chat_api_with_fallback(model, prompt, size, quality, headers)
+        end
+
+        private
+
+        def call_chat_api_with_fallback(model, prompt, size, quality, headers)
+          call_chat_api(model, prompt, size, quality, headers)
+        rescue Errors::InvalidRequestError => error
+          raise unless unsupported_output_modalities?(error)
+
+          call_images_api(model, prompt, size, quality, headers)
+        end
+
+        def call_chat_api(model, prompt, size, quality, headers)
           messages = [{ role: "user", content: prompt }]
           body = { model: model, messages: messages, modalities: ["image", "text"] }
           body[:size]    = size    if size
@@ -30,7 +48,25 @@ module ActiveHarness
           { content: content, provider: :openrouter, model: model, usage: extract_usage_openai(data) }
         end
 
-        private
+        def call_images_api(model, prompt, size, quality, headers)
+          body = { model: model, prompt: prompt }
+          body[:size] = size if size
+          body[:quality] = quality if quality
+          body[:output_format] = "png"
+
+          raw = post_json(URI(config.openrouter_images_api_url), headers: headers, body: body, timeout: 120)
+          data = parse!(raw)
+          handle_error!(data)
+
+          content = extract_images_api_image(data)
+          raise Errors::ProviderError, "No image data in response: #{data.keys}" unless content
+
+          { content: content, provider: :openrouter, model: model, usage: extract_usage_openai(data) }
+        end
+
+        def extract_images_api_image(data)
+          data.dig("data", 0, "b64_json")
+        end
 
         def extract_image(data)
           images = data.dig("choices", 0, "message", "images")
@@ -39,6 +75,18 @@ module ActiveHarness
           images.first&.dig("image_url", "url")
         end
 
+        def image_only_model?(model)
+          info = Pricing::OpenRouter.find(model)
+          modalities = Array(info&.output_modalities).map(&:to_s)
+          modalities.include?("image") && !modalities.include?("text")
+        rescue StandardError
+          false
+        end
+
+        def unsupported_output_modalities?(error)
+          error.message.include?("requested output modalities")
+        end
+
         def api_key
           key = config.openrouter_api_key.to_s
           raise Errors::InvalidApiKeyError, "openrouter_api_key is not configured" if key.empty?

data/lib/active_harness/providers/vertexai.rb

@@ -4,7 +4,7 @@ module ActiveHarness
     #
     # Vertex AI requires Google Cloud OAuth2 authentication via Service Account
     # credentials (googleauth gem) or Application Default Credentials.
-    # This stub raises a clear error so that the agent falls through to the
+    # This stub raises a clear error so that the request falls through to the
     # next model in its fallback chain.
     #
     # To use Vertex AI in production, please look for a dedicated gem, for example:
@@ -13,7 +13,7 @@ module ActiveHarness
     # For most use cases, consider using the built-in :gemini provider instead:
     # it accesses Google's Gemini models via a simple API key (no OAuth needed).
     #
-    # Example agent config (will fall through to the next fallback):
+    # Example request config (will fall through to the next fallback):
     #   model do
     #     use      provider: :vertexai, model: "gemini-2.0-flash"
     #     fallback provider: :gemini,   model: "gemini-2.0-flash"

data/lib/active_harness/railtie.rb

@@ -1,6 +1,6 @@
 module ActiveHarness
   class Railtie < Rails::Railtie
-    APP_AI_DIRS = %w[agents prompts tribunals pipelines memory].freeze
+    APP_AI_DIRS = %w[requests prompts tribunals pipelines memory].freeze
 
     initializer "active_harness.autoload_paths", before: :set_autoload_paths do |app|
       APP_AI_DIRS.each do |dir|

data/lib/active_harness/{agent → request}/cost.rb

@@ -1,5 +1,5 @@
 module ActiveHarness
-  class Agent
+  class Request
     # Providers that have a dedicated pricing source beyond ModelsDev.
     # Consulted in tier-2 before the general ModelsDev fallback.
     # Add entries here when a new provider-specific source is available.