groq_ruby 0.1.0

data/lib/groq_ruby/configuration.rb

@@ -0,0 +1,62 @@
+require "uri"
+
+module GroqRuby
+  # Immutable per-client configuration. Built once when the {Client} is
+  # constructed; never mutated afterwards. No global state — each client
+  # carries its own configuration, so multi-tenant code can hold multiple
+  # clients without leakage.
+  #
+  # @example Build from environment
+  #   config = GroqRuby::Configuration.from_env
+  #
+  # @example Explicit construction
+  #   config = GroqRuby::Configuration.from_env(api_key: "...", base_url: "https://api.groq.com")
+  class Configuration < Data.define(:api_key, :base_url, :open_timeout, :read_timeout, :user_agent)
+    DEFAULT_BASE_URL = "https://api.groq.com".freeze
+    DEFAULT_OPEN_TIMEOUT = 10.0
+    DEFAULT_READ_TIMEOUT = 60.0
+    DEFAULT_USER_AGENT = "groq_ruby/#{GroqRuby::VERSION} (ruby; net-http)".freeze
+
+    # Build a configuration from environment variables, with overrides.
+    # Reads `GROQ_API_KEY` and `GROQ_BASE_URL`.
+    #
+    # @param api_key [String, nil] explicit key (falls back to `GROQ_API_KEY`)
+    # @param base_url [String, nil] explicit base URL (falls back to `GROQ_BASE_URL`)
+    # @param open_timeout [Numeric, nil] connect-phase timeout in seconds
+    # @param read_timeout [Numeric, nil] socket-read timeout in seconds
+    # @param user_agent [String, nil] override the default User-Agent header
+    # @return [Configuration]
+    # @raise [ConfigurationError] if no api_key is provided or in env.
+    def self.from_env(api_key: nil, base_url: nil, open_timeout: nil, read_timeout: nil, user_agent: nil)
+      new(
+        api_key: api_key || ENV["GROQ_API_KEY"],
+        base_url: base_url || ENV["GROQ_BASE_URL"] || DEFAULT_BASE_URL,
+        open_timeout: open_timeout || DEFAULT_OPEN_TIMEOUT,
+        read_timeout: read_timeout || DEFAULT_READ_TIMEOUT,
+        user_agent: user_agent || DEFAULT_USER_AGENT
+      )
+    end
+
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, open_timeout: DEFAULT_OPEN_TIMEOUT,
+      read_timeout: DEFAULT_READ_TIMEOUT, user_agent: DEFAULT_USER_AGENT)
+      raise ConfigurationError, "api_key is required (or set GROQ_API_KEY)" if api_key.nil? || api_key.empty?
+      super
+    end
+
+    # The parsed base URI used to build per-request URIs.
+    # @return [URI::Generic]
+    def base_uri
+      @base_uri ||= URI.parse(base_url)
+    end
+
+    # Default headers attached to every request.
+    # @return [Hash{String => String}]
+    def default_headers
+      {
+        "Authorization" => "Bearer #{api_key}",
+        "User-Agent" => user_agent,
+        "Accept" => "application/json"
+      }
+    end
+  end
+end

data/lib/groq_ruby/error_mapper.rb

@@ -0,0 +1,37 @@
+module GroqRuby
+  # Maps an HTTP status code + parsed body to the matching {APIStatusError}
+  # subclass. Single-purpose: status in, exception instance out.
+  class ErrorMapper
+    STATUS_CLASSES = {
+      400 => BadRequestError,
+      401 => AuthenticationError,
+      403 => PermissionDeniedError,
+      404 => NotFoundError,
+      409 => ConflictError,
+      422 => UnprocessableEntityError,
+      429 => RateLimitError
+    }.freeze
+
+    # @param status [Integer] HTTP status code
+    # @param headers [Hash] response headers
+    # @param body [Object, nil] decoded JSON body (Hash) or raw String
+    # @return [APIStatusError]
+    def self.call(status:, headers:, body:)
+      klass = resolve_class(status)
+      message = extract_message(body) || "Groq API returned status #{status}"
+      klass.new(message, status: status, headers: headers, body: body)
+    end
+
+    def self.resolve_class(status)
+      STATUS_CLASSES[status] || ((status >= 500) ? InternalServerError : APIStatusError)
+    end
+
+    def self.extract_message(body)
+      return nil unless body.is_a?(Hash)
+      err = body["error"] || body[:error]
+      err.is_a?(Hash) ? (err["message"] || err[:message]) : err
+    end
+
+    private_class_method :resolve_class, :extract_message
+  end
+end

data/lib/groq_ruby/errors/api_connection_error.rb

@@ -0,0 +1,8 @@
+module GroqRuby
+  # Network failed before a response was received (DNS, refused, reset...).
+  class APIConnectionError < APIError
+    def initialize(message = "Connection error.", request: nil)
+      super
+    end
+  end
+end

data/lib/groq_ruby/errors/api_error.rb

@@ -0,0 +1,14 @@
+module GroqRuby
+  # Parent for everything that happens while talking to the Groq API.
+  class APIError < Error
+    # @return [Object, nil] the originating request when available
+    attr_reader :request
+
+    # @param message [String]
+    # @param request [Object, nil]
+    def initialize(message, request: nil)
+      @request = request
+      super(message)
+    end
+  end
+end

data/lib/groq_ruby/errors/api_response_error.rb

@@ -0,0 +1,5 @@
+module GroqRuby
+  # Raised when the API returned an unexpected payload (e.g. non-JSON body
+  # for a JSON endpoint) and we cannot map it onto a response model.
+  class APIResponseError < APIError; end
+end

data/lib/groq_ruby/errors/api_status_error.rb

@@ -0,0 +1,23 @@
+module GroqRuby
+  # 4xx/5xx response. Carries status, headers, and the parsed body.
+  class APIStatusError < APIError
+    # @return [Integer] HTTP status code
+    attr_reader :status
+    # @return [Hash{String => String}] response headers
+    attr_reader :headers
+    # @return [Hash, String, nil] decoded JSON body or raw String
+    attr_reader :body
+
+    # @param message [String]
+    # @param status [Integer]
+    # @param headers [Hash{String => String}]
+    # @param body [Hash, String, nil]
+    # @param request [Object, nil]
+    def initialize(message, status:, headers: {}, body: nil, request: nil)
+      @status = status
+      @headers = headers
+      @body = body
+      super(message, request: request)
+    end
+  end
+end

data/lib/groq_ruby/errors/api_timeout_error.rb

@@ -0,0 +1,8 @@
+module GroqRuby
+  # Connection or read timed out.
+  class APITimeoutError < APIConnectionError
+    def initialize(message = "Request timed out.", request: nil)
+      super
+    end
+  end
+end

data/lib/groq_ruby/errors/authentication_error.rb

@@ -0,0 +1,4 @@
+module GroqRuby
+  # HTTP 401 — invalid or missing API key.
+  class AuthenticationError < APIStatusError; end
+end

data/lib/groq_ruby/errors/bad_request_error.rb

@@ -0,0 +1,4 @@
+module GroqRuby
+  # HTTP 400 — the request was malformed or rejected by the API.
+  class BadRequestError < APIStatusError; end
+end

data/lib/groq_ruby/errors/configuration_error.rb

@@ -0,0 +1,4 @@
+module GroqRuby
+  # Raised when client configuration is missing or invalid (e.g. no api_key).
+  class ConfigurationError < Error; end
+end

data/lib/groq_ruby/errors/conflict_error.rb

@@ -0,0 +1,4 @@
+module GroqRuby
+  # HTTP 409 — request conflicts with the current resource state.
+  class ConflictError < APIStatusError; end
+end

data/lib/groq_ruby/errors/error.rb

@@ -0,0 +1,5 @@
+module GroqRuby
+  # Base for every error raised by this gem. Callers can rescue this single
+  # class and degrade gracefully without enumerating subclasses.
+  class Error < StandardError; end
+end

data/lib/groq_ruby/errors/internal_server_error.rb

@@ -0,0 +1,4 @@
+module GroqRuby
+  # HTTP 5xx — Groq is unhappy or unreachable from its side.
+  class InternalServerError < APIStatusError; end
+end

data/lib/groq_ruby/errors/not_found_error.rb

@@ -0,0 +1,4 @@
+module GroqRuby
+  # HTTP 404 — referenced resource (model, file, batch) does not exist.
+  class NotFoundError < APIStatusError; end
+end

data/lib/groq_ruby/errors/parameter_error.rb

@@ -0,0 +1,13 @@
+module GroqRuby
+  # Raised when a request fails dry-schema validation before being sent.
+  class ParameterError < Error
+    # @return [Hash] dry-schema error messages, keyed by parameter name
+    attr_reader :messages
+
+    # @param messages [Hash]
+    def initialize(messages)
+      @messages = messages
+      super("invalid parameters: #{messages.inspect}")
+    end
+  end
+end

data/lib/groq_ruby/errors/permission_denied_error.rb

@@ -0,0 +1,4 @@
+module GroqRuby
+  # HTTP 403 — the API key cannot perform this action.
+  class PermissionDeniedError < APIStatusError; end
+end

data/lib/groq_ruby/errors/rate_limit_error.rb

@@ -0,0 +1,4 @@
+module GroqRuby
+  # HTTP 429 — too many requests; back off and retry.
+  class RateLimitError < APIStatusError; end
+end

data/lib/groq_ruby/errors/unprocessable_entity_error.rb

@@ -0,0 +1,4 @@
+module GroqRuby
+  # HTTP 422 — well-formed request but semantically invalid.
+  class UnprocessableEntityError < APIStatusError; end
+end

data/lib/groq_ruby/mcp/bridge.rb

@@ -0,0 +1,239 @@
+require "json"
+
+module GroqRuby
+  module MCP
+    # Glues one or more MCP servers into a Groq chat completion. Connects
+    # to each server, builds the OpenAI-style `tools:` array the model
+    # expects, and routes each `tool_calls[*]` from the model back to the
+    # owning MCP server.
+    #
+    # Bridge surfaces three MCP capabilities:
+    #
+    # - **Tools** — every server-advertised tool becomes a Groq function
+    #   tool, namespaced as `<server>__<tool>`. The LLM calls these
+    #   exactly like any other function tool; {#call} routes the call to
+    #   the owning server.
+    # - **Resources** — for every server that advertises resources,
+    #   Bridge injects a synthetic `<server>__read_resource(uri)` tool
+    #   into {#tools} so the LLM can fetch resource content on demand.
+    #   {#resources} returns the full inventory if you want to surface
+    #   it (e.g. in a system-prompt catalogue).
+    # - **Prompts** — {#prompts} returns the list of prompt templates
+    #   advertised by each server. Prompts are typically surfaced to a
+    #   user (a picker in your UI), not the LLM directly. {#get_prompt}
+    #   renders one with arguments.
+    #
+    # Optional capabilities are probed gracefully — a server that
+    # responds with `-32601 method not found` to `resources/list` simply
+    # contributes no resources.
+    #
+    # @example Wire a filesystem MCP server into chat.completions
+    #   fs = GroqRuby::MCP::ServerConfig.new(name: "fs", command: "...")
+    #   bridge = GroqRuby::MCP::Bridge.new([fs])
+    #   begin
+    #     response = groq.chat.completions.create(
+    #       model: "llama-3.3-70b-versatile",
+    #       messages: messages,
+    #       tools: bridge.tools
+    #     )
+    #     tool_call = response.choices.first.message.tool_calls&.first
+    #     result = bridge.call(tool_call["function"]["name"], tool_call["function"]["arguments"]) if tool_call
+    #   ensure
+    #     bridge.stop
+    #   end
+    class Bridge
+      NAME_SEPARATOR = "__".freeze
+      READ_RESOURCE_SUFFIX = "read_resource".freeze
+
+      # @param configs [Array<ServerConfig>]
+      # @param request_timeout [Numeric] forwarded to each {Client}
+      def initialize(configs, request_timeout: Client::DEFAULT_REQUEST_TIMEOUT)
+        @clients = configs.map { |c| Client.connect(c, request_timeout: request_timeout) }
+        @tool_index = build_tool_index
+        @resource_index = build_resource_index
+        @prompt_index = build_prompt_index
+      end
+
+      # Tool definitions for `chat.completions.create(tools:)`. Includes
+      # every advertised MCP tool plus, for each server with resources,
+      # a synthetic `<server>__read_resource(uri)` tool so the LLM can
+      # fetch resource content on demand.
+      #
+      # @return [Array<Hash>]
+      def tools
+        @tool_index.values.map { |entry| as_groq_tool(entry) } + synthetic_resource_tools
+      end
+
+      # @return [Array<String>] every namespaced tool name {#tools} surfaces
+      def tool_names
+        tools.map { |t| t[:function][:name] }
+      end
+
+      # Flat inventory of every resource discovered across all servers.
+      #
+      # @return [Array<Hash>] each entry has keys `:server`, `:resource` (a {Resource})
+      def resources
+        @resource_index.values.map { |entry| {server: entry[:server_name], resource: entry[:resource]} }
+      end
+
+      # Flat inventory of every prompt template discovered across all servers.
+      #
+      # @return [Array<Hash>] each entry has keys `:server`, `:namespaced_name`, `:prompt`
+      def prompts
+        @prompt_index.map do |namespaced, entry|
+          {server: entry[:server_name], namespaced_name: namespaced, prompt: entry[:prompt]}
+        end
+      end
+
+      # Dispatch a tool call from a Groq response to the owning MCP server.
+      # Recognises the synthetic `<server>__read_resource` tool and routes
+      # to {#read_resource} instead.
+      #
+      # @param namespaced_name [String]
+      # @param arguments [Hash, String] parsed Hash or the JSON string Groq returns
+      # @return [Hash] the MCP server's tool-call result
+      # @raise [UnknownToolError] if no connected server advertises this tool
+      def call(namespaced_name, arguments)
+        parsed_args = parse_args(arguments)
+        if (server_name = match_synthetic_resource_tool(namespaced_name))
+          uri = parsed_args["uri"] || parsed_args[:uri]
+          read_resource(uri, server: server_name)
+        else
+          dispatch_tool_call(namespaced_name, parsed_args)
+        end
+      end
+
+      # Read a resource by URI. When more than one server advertises the
+      # same URI, pass `server:` to disambiguate.
+      #
+      # @param uri [String]
+      # @param server [String, nil] explicit server name
+      # @return [Hash] the server's `resources/read` result
+      # @raise [UnknownToolError] if no server owns the URI
+      def read_resource(uri, server: nil)
+        candidates = @resource_index.values.select { |e| e[:resource].uri == uri }
+        candidates = candidates.select { |e| e[:server_name] == server } if server
+        entry = candidates.first or raise UnknownToolError, "no MCP resource for uri #{uri.inspect}"
+        entry[:client].resources_read(uri)
+      end
+
+      # Render a prompt template. The name is the namespaced
+      # `<server>__<prompt>` form returned by {#prompts}.
+      #
+      # @param namespaced_name [String]
+      # @param arguments [Hash]
+      # @return [Hash] the server's `prompts/get` result (`messages` array)
+      # @raise [UnknownToolError] if the prompt isn't known
+      def get_prompt(namespaced_name, arguments = {})
+        entry = @prompt_index[namespaced_name] or raise UnknownToolError, "no MCP prompt named #{namespaced_name.inspect}"
+        entry[:client].prompts_get(entry[:prompt].name, arguments)
+      end
+
+      # Stop every underlying MCP server. Idempotent.
+      def stop
+        @clients.each(&:stop)
+      end
+
+      private
+
+      def build_tool_index
+        @clients.each_with_object({}) do |client, acc|
+          server_name = name_for(client)
+          tools_for(client).each do |tool|
+            acc["#{server_name}#{NAME_SEPARATOR}#{tool.name}"] = {client: client, tool: tool, server_name: server_name}
+          end
+        end
+      end
+
+      def build_resource_index
+        @clients.each_with_object({}) do |client, acc|
+          server_name = name_for(client)
+          resources_for(client).each do |resource|
+            key = "#{server_name}#{NAME_SEPARATOR}#{resource.uri}"
+            acc[key] = {client: client, resource: resource, server_name: server_name}
+          end
+        end
+      end
+
+      def build_prompt_index
+        @clients.each_with_object({}) do |client, acc|
+          server_name = name_for(client)
+          prompts_for(client).each do |prompt|
+            acc["#{server_name}#{NAME_SEPARATOR}#{prompt.name}"] = {client: client, prompt: prompt, server_name: server_name}
+          end
+        end
+      end
+
+      def tools_for(client)
+        client.tools_list
+      rescue JsonRpcError
+        []
+      end
+
+      def resources_for(client)
+        client.resources_list
+      rescue JsonRpcError
+        []
+      end
+
+      def prompts_for(client)
+        client.prompts_list
+      rescue JsonRpcError
+        []
+      end
+
+      def synthetic_resource_tools
+        servers_with_resources.map do |server_name|
+          {
+            type: "function",
+            function: {
+              name: "#{server_name}#{NAME_SEPARATOR}#{READ_RESOURCE_SUFFIX}",
+              description: "Read the contents of a resource hosted by the '#{server_name}' MCP server. The 'uri' argument must be one of the URIs from bridge.resources.",
+              parameters: {
+                "type" => "object",
+                "properties" => {"uri" => {"type" => "string", "description" => "Resource URI to read"}},
+                "required" => ["uri"]
+              }
+            }
+          }
+        end
+      end
+
+      def servers_with_resources
+        @resource_index.values.map { |e| e[:server_name] }.uniq
+      end
+
+      def match_synthetic_resource_tool(name)
+        suffix = "#{NAME_SEPARATOR}#{READ_RESOURCE_SUFFIX}"
+        return nil unless name.end_with?(suffix)
+        server_name = name.delete_suffix(suffix)
+        servers_with_resources.include?(server_name) ? server_name : nil
+      end
+
+      def dispatch_tool_call(namespaced_name, parsed_args)
+        entry = @tool_index[namespaced_name] or raise UnknownToolError, "no MCP tool named #{namespaced_name.inspect}"
+        entry[:client].tools_call(name: entry[:tool].name, arguments: parsed_args)
+      end
+
+      def parse_args(arguments)
+        return {} if arguments.nil?
+        arguments.is_a?(String) ? JSON.parse(arguments) : arguments
+      end
+
+      def as_groq_tool(entry)
+        {
+          type: "function",
+          function: {
+            name: "#{entry[:server_name]}#{NAME_SEPARATOR}#{entry[:tool].name}",
+            description: entry[:tool].description,
+            parameters: entry[:tool].input_schema
+          }
+        }
+      end
+
+      def name_for(client)
+        client.server_name || "server#{client.object_id}"
+      end
+    end
+  end
+end

data/lib/groq_ruby/mcp/claude_desktop_config.rb

@@ -0,0 +1,79 @@
+require "json"
+
+module GroqRuby
+  module MCP
+    # Loads MCP server configurations from the same JSON shape Claude
+    # Desktop uses (`claude_desktop_config.json`'s `mcpServers` block) and
+    # returns a list of {ServerConfig} ready for {Bridge.new}.
+    #
+    # Supports `${VAR}` interpolation in `args` and `env` values. Lookup
+    # order: the server's own `env` block first, then the process's
+    # `ENV`. Unresolved references raise so silent misconfigurations
+    # don't ship.
+    #
+    # @example Load from disk
+    #   configs = GroqRuby::MCP::ClaudeDesktopConfig.load("~/Library/Application Support/Claude/claude_desktop_config.json")
+    #   bridge = GroqRuby::MCP::Bridge.new(configs)
+    #
+    # @example Parse an in-memory Hash
+    #   configs = GroqRuby::MCP::ClaudeDesktopConfig.parse({
+    #     "mcpServers" => {
+    #       "spectrum-ferret-staging" => {
+    #         "command" => "npx",
+    #         "args" => ["-y", "mcp-remote@latest", "https://...", "--header", "Authorization: Bearer ${SF_PAT}"],
+    #         "env" => {"SF_PAT" => ENV.fetch("SF_PAT")}
+    #       }
+    #     }
+    #   })
+    module ClaudeDesktopConfig
+      VAR_PATTERN = /\$\{([A-Z_][A-Z0-9_]*)\}/
+
+      # Load configurations from a JSON file path.
+      #
+      # @param path [String] file path
+      # @return [Array<ServerConfig>]
+      # @raise [Errno::ENOENT] if the file is missing
+      # @raise [JSON::ParserError] if the file is not valid JSON
+      # @raise [ConfigurationError] if the structure is wrong or `${VAR}` references are unresolvable
+      def self.load(path)
+        parse(JSON.parse(File.read(File.expand_path(path))))
+      end
+
+      # Parse configurations from an already-decoded Hash (or a JSON
+      # string).
+      #
+      # @param input [Hash, String]
+      # @return [Array<ServerConfig>]
+      # @raise [ConfigurationError] on structural errors or unresolved variables
+      def self.parse(input)
+        hash = input.is_a?(String) ? JSON.parse(input) : input
+        servers = hash["mcpServers"] || hash[:mcpServers] || {}
+        servers.map { |name, entry| build_server_config(name.to_s, entry) }
+      end
+
+      def self.build_server_config(name, entry)
+        command = entry["command"] || entry[:command] or
+          raise ConfigurationError, "MCP server #{name.inspect}: missing 'command'"
+        raw_args = Array(entry["args"] || entry[:args])
+        raw_env = (entry["env"] || entry[:env] || {}).transform_keys(&:to_s)
+
+        ServerConfig.new(
+          name: name,
+          command: command,
+          args: raw_args.map { |arg| expand_vars(arg, raw_env, server: name) },
+          env: raw_env.transform_values { |v| expand_vars(v, raw_env, server: name) }
+        )
+      end
+
+      def self.expand_vars(value, server_env, server:)
+        value.to_s.gsub(VAR_PATTERN) do
+          var = Regexp.last_match(1)
+          server_env[var] || ENV[var] ||
+            raise(ConfigurationError, "MCP server #{server.inspect}: unresolved ${#{var}} (not in env block or process ENV)")
+        end
+      end
+
+      private_class_method :build_server_config, :expand_vars
+    end
+  end
+end