active_harness 0.2.6 → 0.2.8

data/lib/active_harness/providers/custom.rb

@@ -0,0 +1,96 @@
+require "uri"
+
+module ActiveHarness
+  module Providers
+    # Custom — generic OpenAI-compatible provider for any named endpoint.
+    #
+    # Configured via ActiveHarness.configure:
+    #
+    #   ActiveHarness.configure do |config|
+    #     config.custom["MyLocal"]["url"]     = "http://localhost:8080/v1/chat/completions"
+    #     config.custom["MyLocal"]["api_key"] = ENV["MYLOCAL_API_KEY"]   # omit if no auth needed
+    #
+    #     config.custom["SecondProvider"]["url"]     = "https://second.example.com/v1/chat/completions"
+    #     config.custom["SecondProvider"]["api_key"] = ENV["SECOND_API_KEY"]
+    #   end
+    #
+    # Use in an agent:
+    #
+    #   model do
+    #     use      provider: :custom, name: "MyLocal",        model: "llama3.2"
+    #     fallback provider: :custom, name: "SecondProvider", model: "mixtral"
+    #   end
+    #
+    class Custom < Base
+      def call(model:, messages:, temperature: 0.7, name: nil)
+        raise Errors::InvalidRequestError,
+          "provider: :custom requires a `name:` key — e.g. `use provider: :custom, name: \"MyLocal\", model: \"...\"`" \
+          if name.nil? || name.to_s.empty?
+
+        settings = config.custom[name.to_s]
+
+        url = settings["url"].to_s
+        raise Errors::InvalidRequestError,
+          "Custom provider \"#{name}\" has no url configured. " \
+          "Set it with: config.custom[\"#{name}\"][\"url\"] = \"https://...\"" \
+          if url.empty?
+
+        headers = { "Content-Type" => "application/json" }
+        key = settings["api_key"].to_s
+        headers["Authorization"] = "Bearer #{key}" unless key.empty?
+
+        raw  = post_json(URI(url),
+          headers: headers,
+          body:    { model: model, messages: messages, temperature: temperature }
+        )
+        data = parse!(raw)
+        handle_error!(data, name: name)
+
+        {
+          content:  data.dig("choices", 0, "message", "content").to_s.strip,
+          provider: :custom,
+          model:    data["model"] || model,
+          usage:    extract_usage_openai(data)
+        }
+      end
+
+      private
+
+      def handle_error!(data, name:)
+        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", "401"
+          raise Errors::InvalidApiKeyError.new(
+            "[Custom:#{name}] #{msg}", error_code: code, metadata: metadata
+          )
+        when "429", "rate_limit_exceeded"
+          raise Errors::RateLimitError.new(
+            "[Custom:#{name}] #{msg}", error_code: code, metadata: metadata
+          )
+        when "500", "502", "503", "504"
+          raise Errors::ProviderUnavailableError.new(
+            "[Custom:#{name}] #{msg}", error_code: code, metadata: metadata
+          )
+        else
+          case type
+          when "server_error"
+            raise Errors::ServerError.new(
+              "[Custom:#{name}] #{msg}", error_code: code, metadata: metadata
+            )
+          else
+            raise Errors::InvalidRequestError.new(
+              "[Custom:#{name}] #{msg}", error_code: code, metadata: metadata
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_harness/providers/deepseek.rb

@@ -0,0 +1,62 @@
+require "uri"
+
+module ActiveHarness
+  module Providers
+    # DeepSeek — OpenAI-compatible API.
+    # https://platform.deepseek.com/api-docs
+    class DeepSeek < Base
+      def call(model:, messages:, temperature: 0.7)
+        raw  = post_json(URI(config.deepseek_api_url),
+          headers: {
+            "Content-Type"  => "application/json",
+            "Authorization" => "Bearer #{api_key}"
+          },
+          body: { model: model, messages: messages, temperature: temperature }
+        )
+        data = parse!(raw)
+        handle_error!(data)
+
+        {
+          content:  data.dig("choices", 0, "message", "content").to_s.strip,
+          provider: :deepseek,
+          model:    data["model"] || model,
+          usage:    extract_usage_openai(data)
+        }
+      end
+
+      private
+
+      def api_key
+        key = config.deepseek_api_key.to_s
+        raise Errors::InvalidApiKeyError, "deepseek_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 "500", "502", "503", "504"
+          raise Errors::ProviderUnavailableError.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

data/lib/active_harness/providers/gemini.rb

@@ -5,10 +5,8 @@ module ActiveHarness
     # Google Gemini — OpenAI-compatible endpoint (beta).
     # https://ai.google.dev/gemini-api/docs/openai
     class Gemini < Base
-      API_URL = URI("https://generativelanguage.googleapis.com/v1beta/openai/chat/completions")
-
       def call(model:, messages:, temperature: 0.7)
-        raw  = post_json(API_URL,
+        raw  = post_json(URI(config.gemini_api_url),
           headers: {
             "Content-Type"  => "application/json",
             "Authorization" => "Bearer #{api_key}"
@@ -29,8 +27,8 @@ module ActiveHarness
       private
 
       def api_key
-        key = ENV["GEMINI_API_KEY"].to_s
-        raise Errors::InvalidApiKeyError, "GEMINI_API_KEY is not set" if key.empty?
+        key = config.gemini_api_key.to_s
+        raise Errors::InvalidApiKeyError, "gemini_api_key is not configured" if key.empty?
         key
       end
 

data/lib/active_harness/providers/gpustack.rb

@@ -0,0 +1,78 @@
+require "uri"
+
+module ActiveHarness
+  module Providers
+    # GPUStack — self-hosted GPU inference server, OpenAI-compatible API.
+    # https://docs.gpustack.ai/latest/user-guide/inference-openai-compatible-apis/
+    #
+    # GPUSTACK_API_BASE is required (e.g. "http://my-gpustack-server:80").
+    # GPUSTACK_API_KEY is optional (needed only if the server has auth enabled).
+    #
+    # Example:
+    #   model do
+    #     use provider: :gpustack, model: "Qwen/Qwen2.5-7B-Instruct-GGUF"
+    #   end
+    class GPUStack < Base
+      def call(model:, messages:, temperature: 0.7)
+        url = URI("#{api_base}/v1/chat/completions")
+
+        headers = { "Content-Type" => "application/json" }
+        key     = api_key
+        headers["Authorization"] = "Bearer #{key}" if key
+
+        raw  = post_json(url,
+          headers: headers,
+          body:    { model: model, messages: messages, temperature: temperature }
+        )
+        data = parse!(raw)
+        handle_error!(data)
+
+        {
+          content:  data.dig("choices", 0, "message", "content").to_s.strip,
+          provider: :gpustack,
+          model:    data["model"] || model,
+          usage:    extract_usage_openai(data)
+        }
+      end
+
+      private
+
+      def api_base
+        base = config.gpustack_api_base.to_s
+        raise Errors::InvalidRequestError, "gpustack_api_base is not configured" if base.empty?
+        base.chomp("/")
+      end
+
+      def api_key
+        key = config.gpustack_api_key.to_s
+        key.empty? ? nil : 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", "401"
+          raise Errors::InvalidApiKeyError.new(msg,       error_code: code, metadata: metadata)
+        when "429"
+          raise Errors::RateLimitError.new(msg,           error_code: code, metadata: metadata)
+        when "500", "502", "503", "504"
+          raise Errors::ProviderUnavailableError.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

data/lib/active_harness/providers/groq.rb

@@ -5,10 +5,8 @@ module ActiveHarness
     # Groq — OpenAI-compatible API with fast inference.
     # https://console.groq.com/docs/openai
     class Groq < Base
-      API_URL = URI("https://api.groq.com/openai/v1/chat/completions")
-
       def call(model:, messages:, temperature: 0.7)
-        raw  = post_json(API_URL,
+        raw  = post_json(URI(config.groq_api_url),
           headers: {
             "Content-Type"  => "application/json",
             "Authorization" => "Bearer #{api_key}"
@@ -29,8 +27,8 @@ module ActiveHarness
       private
 
       def api_key
-        key = ENV["GROQ_API_KEY"].to_s
-        raise Errors::InvalidApiKeyError, "GROQ_API_KEY is not set" if key.empty?
+        key = config.groq_api_key.to_s
+        raise Errors::InvalidApiKeyError, "groq_api_key is not configured" if key.empty?
         key
       end
 

data/lib/active_harness/providers/mistral.rb

@@ -0,0 +1,63 @@
+require "uri"
+
+module ActiveHarness
+  module Providers
+    # Mistral AI — OpenAI-compatible API.
+    # https://docs.mistral.ai/api
+    class Mistral < Base
+      def call(model:, messages:, temperature: 0.7)
+        raw  = post_json(URI(config.mistral_api_url),
+          headers: {
+            "Content-Type"  => "application/json",
+            "Authorization" => "Bearer #{api_key}"
+          },
+          body: { model: model, messages: messages, temperature: temperature }
+        )
+        data = parse!(raw)
+        handle_error!(data)
+
+        {
+          content:  data.dig("choices", 0, "message", "content").to_s.strip,
+          provider: :mistral,
+          model:    data["model"] || model,
+          usage:    extract_usage_openai(data)
+        }
+      end
+
+      private
+
+      def api_key
+        key = config.mistral_api_key.to_s
+        raise Errors::InvalidApiKeyError, "mistral_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 "1901"              # unauthorized
+          raise Errors::InvalidApiKeyError.new(msg,       error_code: code, metadata: metadata)
+        when "1902"              # rate limit
+          raise Errors::RateLimitError.new(msg,           error_code: code, metadata: metadata)
+        when "500", "502",
+             "503", "504"
+          raise Errors::ProviderUnavailableError.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

data/lib/active_harness/providers/ollama.rb

@@ -0,0 +1,67 @@
+require "uri"
+
+module ActiveHarness
+  module Providers
+    # Ollama — local model inference server, OpenAI-compatible API.
+    # https://ollama.com/blog/openai-compatibility
+    #
+    # Set OLLAMA_API_BASE to override the default local address.
+    # OLLAMA_API_KEY is optional (needed only if Ollama is behind a proxy with auth).
+    #
+    # Example:
+    #   model do
+    #     use provider: :ollama, model: "llama3.2"
+    #   end
+    class Ollama < Base
+      def call(model:, messages:, temperature: 0.7)
+        url = URI("#{api_base}/v1/chat/completions")
+
+        headers = { "Content-Type" => "application/json" }
+        key     = api_key
+        headers["Authorization"] = "Bearer #{key}" if key
+
+        raw  = post_json(url,
+          headers: headers,
+          body:    { model: model, messages: messages, temperature: temperature }
+        )
+        data = parse!(raw)
+        handle_error!(data)
+
+        {
+          content:  data.dig("choices", 0, "message", "content").to_s.strip,
+          provider: :ollama,
+          model:    data["model"] || model,
+          usage:    extract_usage_openai(data)
+        }
+      end
+
+      private
+
+      def api_base
+        config.ollama_api_base.to_s.chomp("/")
+      end
+
+      # Ollama does not require an API key by default.
+      def api_key
+        key = config.ollama_api_key.to_s
+        key.empty? ? nil : 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["error"].reject { |k, _| %w[message code].include?(k) }
+        metadata = nil if metadata.empty?
+
+        case code
+        when "500", "502", "503", "504"
+          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

data/lib/active_harness/providers/openai.rb

@@ -3,14 +3,12 @@ require "uri"
 module ActiveHarness
   module Providers
     class OpenAI < Base
-      API_URL = URI("https://api.openai.com/v1/chat/completions")
-
       # @param model    [String]
       # @param messages [Array<Hash>]  [{role:, content:}, ...]
       # @param temperature [Float]
       # @return [Hash]  { content:, provider:, model: }
       def call(model:, messages:, temperature: 0.7)
-        raw  = post_json(API_URL,
+        raw  = post_json(URI(config.openai_api_url),
           headers: {
             "Content-Type"  => "application/json",
             "Authorization" => "Bearer #{api_key}"
@@ -31,8 +29,8 @@ module ActiveHarness
       private
 
       def api_key
-        key = ENV["OPENAI_API_KEY"].to_s
-        raise Errors::InvalidApiKeyError, "OPENAI_API_KEY is not set" if key.empty?
+        key = config.openai_api_key.to_s
+        raise Errors::InvalidApiKeyError, "openai_api_key is not configured" if key.empty?
         key
       end
 

data/lib/active_harness/providers/openrouter.rb

@@ -4,8 +4,6 @@ module ActiveHarness
   module Providers
     # OpenRouter — OpenAI-compatible API that proxies many models.
     class OpenRouter < Base
-      API_URL = URI("https://openrouter.ai/api/v1/chat/completions")
-
       # @param model    [String]
       # @param messages [Array<Hash>]  [{role:, content:}, ...]
       # @param temperature [Float]
@@ -15,17 +13,17 @@ module ActiveHarness
         headers = {
           "Content-Type"  => "application/json",
           "Authorization" => "Bearer #{api_key}",
-          "HTTP-Referer"  => "https://github.com/the-teacher/ActiveHarness"
+          "HTTP-Referer"  => config.openrouter_http_referer
         }
         body = { model: model, messages: messages, temperature: temperature }
 
         if stream
           body[:stream] = true
-          content = post_json_stream(API_URL, headers: headers, body: body, on_token: stream)
+          content = post_json_stream(URI(config.openrouter_api_url), headers: headers, body: body, on_token: stream)
           return { content: content, provider: :openrouter, model: model }
         end
 
-        raw  = post_json(API_URL, headers: headers, body: body)
+        raw  = post_json(URI(config.openrouter_api_url), headers: headers, body: body)
         data = parse!(raw)
         handle_error!(data)
 
@@ -40,8 +38,8 @@ module ActiveHarness
       private
 
       def api_key
-        key = ENV["OPENROUTER_API_KEY"].to_s
-        raise Errors::InvalidApiKeyError, "OPENROUTER_API_KEY is not set" if key.empty?
+        key = config.openrouter_api_key.to_s
+        raise Errors::InvalidApiKeyError, "openrouter_api_key is not configured" if key.empty?
         key
       end
 

data/lib/active_harness/providers/perplexity.rb

@@ -0,0 +1,62 @@
+require "uri"
+
+module ActiveHarness
+  module Providers
+    # Perplexity — OpenAI-compatible API with web-search-augmented models.
+    # https://docs.perplexity.ai/api-reference/chat-completions
+    class Perplexity < Base
+      def call(model:, messages:, temperature: 0.7)
+        raw  = post_json(URI(config.perplexity_api_url),
+          headers: {
+            "Content-Type"  => "application/json",
+            "Authorization" => "Bearer #{api_key}"
+          },
+          body: { model: model, messages: messages, temperature: temperature }
+        )
+        data = parse!(raw)
+        handle_error!(data)
+
+        {
+          content:  data.dig("choices", 0, "message", "content").to_s.strip,
+          provider: :perplexity,
+          model:    data["model"] || model,
+          usage:    extract_usage_openai(data)
+        }
+      end
+
+      private
+
+      def api_key
+        key = config.perplexity_api_key.to_s
+        raise Errors::InvalidApiKeyError, "perplexity_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 "401"
+          raise Errors::InvalidApiKeyError.new(msg,       error_code: code, metadata: metadata)
+        when "429"
+          raise Errors::RateLimitError.new(msg,           error_code: code, metadata: metadata)
+        when "500", "502", "503", "504"
+          raise Errors::ProviderUnavailableError.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

data/lib/active_harness/providers/vertexai.rb

@@ -0,0 +1,34 @@
+module ActiveHarness
+  module Providers
+    # Google Vertex AI — stub provider.
+    #
+    # 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
+    # next model in its fallback chain.
+    #
+    # To use Vertex AI in production, please look for a dedicated gem, for example:
+    #   gem "active_harness-vertexai"  (not yet released — contributions welcome)
+    #
+    # 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):
+    #   model do
+    #     use      provider: :vertexai, model: "gemini-2.0-flash"
+    #     fallback provider: :gemini,   model: "gemini-2.0-flash"
+    #   end
+    class VertexAI < Base
+      STUB_MESSAGE = <<~MSG.strip
+        ActiveHarness: Google Vertex AI provider is not built-in.
+        Vertex AI requires Google Cloud OAuth2 credentials (googleauth gem) — please use a dedicated gem.
+        Consider using the built-in :gemini provider instead (simple API key, same models).
+        Falling through to the next model in the fallback chain.
+      MSG
+
+      def call(model:, messages:, temperature: 0.7) # rubocop:disable Lint/UnusedMethodArgument
+        raise Errors::ProviderUnavailableError, STUB_MESSAGE
+      end
+    end
+  end
+end

data/lib/active_harness/providers/xai.rb

@@ -0,0 +1,62 @@
+require "uri"
+
+module ActiveHarness
+  module Providers
+    # xAI (Grok) — OpenAI-compatible API.
+    # https://docs.x.ai/api
+    class XAI < Base
+      def call(model:, messages:, temperature: 0.7)
+        raw  = post_json(URI(config.xai_api_url),
+          headers: {
+            "Content-Type"  => "application/json",
+            "Authorization" => "Bearer #{api_key}"
+          },
+          body: { model: model, messages: messages, temperature: temperature }
+        )
+        data = parse!(raw)
+        handle_error!(data)
+
+        {
+          content:  data.dig("choices", 0, "message", "content").to_s.strip,
+          provider: :xai,
+          model:    data["model"] || model,
+          usage:    extract_usage_openai(data)
+        }
+      end
+
+      private
+
+      def api_key
+        key = config.xai_api_key.to_s
+        raise Errors::InvalidApiKeyError, "xai_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 "500", "502", "503", "504"
+          raise Errors::ProviderUnavailableError.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