groq_ruby 0.1.0

data/lib/groq_ruby/mcp/client.rb

@@ -0,0 +1,171 @@
+require "json"
+
+module GroqRuby
+  module MCP
+    # High-level MCP client. Wraps a {Transport} and exposes the
+    # operations a Groq agent typically needs: handshake, list tools,
+    # invoke tools, list/read resources.
+    #
+    # Synchronous on the outside (every public method blocks until the
+    # server responds or times out), thread-safe on the inside (the
+    # transport's reader thread fulfils a per-id Queue).
+    #
+    # @example
+    #   client = GroqRuby::MCP::Client.connect(server_config)
+    #   tools = client.tools_list
+    #   result = client.tools_call(name: "read_file", arguments: {path: "/tmp/x"})
+    #   client.stop
+    class Client
+      DEFAULT_REQUEST_TIMEOUT = 30.0
+
+      # Connect to a server via the default stdio transport and complete
+      # the initialize handshake. Caller must call {#stop} when done.
+      #
+      # @param config [ServerConfig]
+      # @param request_timeout [Numeric] seconds to wait for any single response
+      # @return [Client]
+      def self.connect(config, request_timeout: DEFAULT_REQUEST_TIMEOUT)
+        transport = Transports::Stdio.spawn(config)
+        new(transport, request_timeout: request_timeout).tap(&:initialize_session)
+      end
+
+      # @return [String, nil] the server-reported name, populated after handshake
+      attr_reader :server_name
+      # @return [String, nil] the server-reported version, populated after handshake
+      attr_reader :server_version
+      # @return [Hash] the server's advertised capabilities
+      attr_reader :server_capabilities
+
+      # @param transport [Transport]
+      # @param request_timeout [Numeric]
+      def initialize(transport, request_timeout: DEFAULT_REQUEST_TIMEOUT)
+        @transport = transport
+        @request_timeout = request_timeout
+        @next_id = 0
+        @id_mutex = Mutex.new
+        @pending = {}
+        @pending_mutex = Mutex.new
+        @transport.on_message { |msg| handle_message(msg) }
+      end
+
+      # Run the JSON-RPC `initialize` handshake. Called automatically by
+      # {.connect}; safe to call again to re-handshake.
+      # @return [Hash] the server's response payload
+      def initialize_session
+        result = request("initialize", {
+          protocolVersion: PROTOCOL_VERSION,
+          capabilities: {},
+          clientInfo: {name: "groq_ruby", version: GroqRuby::VERSION}
+        })
+        info = result["serverInfo"] || {}
+        @server_name = info["name"]
+        @server_version = info["version"]
+        @server_capabilities = result["capabilities"] || {}
+        notify("notifications/initialized")
+        result
+      end
+
+      # @return [Array<Tool>] every tool advertised by the server
+      def tools_list
+        result = request("tools/list", {})
+        Array(result["tools"]).map { |h| Tool.from_hash(h) }
+      end
+
+      # Invoke a tool on the server.
+      # @param name [String]
+      # @param arguments [Hash]
+      # @return [Hash] the server's tool-call result (may include `isError`)
+      def tools_call(name:, arguments: {})
+        request("tools/call", {name: name, arguments: arguments})
+      end
+
+      # @return [Array<Resource>] every resource advertised by the server
+      def resources_list
+        result = request("resources/list", {})
+        Array(result["resources"]).map { |h| Resource.from_hash(h) }
+      end
+
+      # Read a resource by URI.
+      # @param uri [String]
+      # @return [Hash] `contents` array as returned by the server
+      def resources_read(uri)
+        request("resources/read", {uri: uri})
+      end
+
+      # @return [Array<Prompt>] every prompt template advertised by the server
+      def prompts_list
+        result = request("prompts/list", {})
+        Array(result["prompts"]).map { |h| Prompt.from_hash(h) }
+      end
+
+      # Render a prompt template by name with the given arguments.
+      # @param name [String]
+      # @param arguments [Hash]
+      # @return [Hash] `messages` array as returned by the server
+      def prompts_get(name, arguments = {})
+        request("prompts/get", {name: name, arguments: arguments})
+      end
+
+      # Returns true when the handshake reported that the server
+      # advertises the given capability (`"tools"`, `"resources"`,
+      # `"prompts"`). Useful for probing which Bridge features to enable.
+      # @param capability [String]
+      # @return [Boolean]
+      def supports?(capability)
+        @server_capabilities&.key?(capability) || false
+      end
+
+      # Close the underlying transport. Idempotent.
+      def stop
+        @transport.stop
+      end
+
+      private
+
+      def request(method, params)
+        id = next_id
+        queue = Queue.new
+        @pending_mutex.synchronize { @pending[id] = queue }
+        @transport.send_message(JsonRpc.request(id: id, method: method, params: params))
+        await_response(id, queue)
+      ensure
+        @pending_mutex.synchronize { @pending.delete(id) }
+      end
+
+      def await_response(id, queue)
+        message = queue.pop(timeout: @request_timeout)
+        raise TimeoutError, "MCP request #{id} (#{@server_name || "server"}) timed out" if message.nil?
+        if (err = message["error"])
+          raise JsonRpcError.new(code: err["code"], message: err["message"], data: err["data"])
+        end
+        message["result"] || {}
+      end
+
+      def notify(method, params = {})
+        @transport.send_message(JsonRpc.notification(method: method, params: params))
+      end
+
+      def handle_message(message)
+        case JsonRpc.classify(message)
+        when :response then deliver_response(message)
+        when :notification then handle_notification(message)
+          # Server-initiated requests and invalid frames are ignored in v1.
+        end
+      end
+
+      def deliver_response(message)
+        queue = @pending_mutex.synchronize { @pending[message["id"]] }
+        queue&.push(message)
+      end
+
+      def handle_notification(_message)
+        # v1: no client-side notification handlers. Future: dispatch to
+        # registered callbacks for `notifications/tools/list_changed` etc.
+      end
+
+      def next_id
+        @id_mutex.synchronize { @next_id += 1 }
+      end
+    end
+  end
+end

data/lib/groq_ruby/mcp/errors/error.rb

@@ -0,0 +1,7 @@
+module GroqRuby
+  module MCP
+    # Base for every MCP-layer failure. Inherits from {GroqRuby::Error} so
+    # callers can rescue the whole gem with a single class.
+    class Error < GroqRuby::Error; end
+  end
+end

data/lib/groq_ruby/mcp/errors/json_rpc_error.rb

@@ -0,0 +1,21 @@
+module GroqRuby
+  module MCP
+    # Server returned a JSON-RPC error response. Carries the protocol code,
+    # message, and any extra `data` payload.
+    class JsonRpcError < Error
+      # @return [Integer] JSON-RPC error code (-32700..-32000 range)
+      attr_reader :code
+      # @return [Object, nil] optional error data payload
+      attr_reader :data
+
+      # @param code [Integer]
+      # @param message [String]
+      # @param data [Object, nil]
+      def initialize(code:, message:, data: nil)
+        @code = code
+        @data = data
+        super("MCP server error #{code}: #{message}")
+      end
+    end
+  end
+end

data/lib/groq_ruby/mcp/errors/protocol_error.rb

@@ -0,0 +1,7 @@
+module GroqRuby
+  module MCP
+    # Server sent us bytes that don't parse as JSON-RPC, or are missing a
+    # required field.
+    class ProtocolError < Error; end
+  end
+end

data/lib/groq_ruby/mcp/errors/timeout_error.rb

@@ -0,0 +1,7 @@
+module GroqRuby
+  module MCP
+    # Server died, response never arrived, or shutdown could not be reached
+    # in the configured budget.
+    class TimeoutError < Error; end
+  end
+end

data/lib/groq_ruby/mcp/errors/transport_error.rb

@@ -0,0 +1,6 @@
+module GroqRuby
+  module MCP
+    # Underlying transport (stdio pipe, HTTP socket) failed.
+    class TransportError < Error; end
+  end
+end

data/lib/groq_ruby/mcp/errors/unknown_tool_error.rb

@@ -0,0 +1,7 @@
+module GroqRuby
+  module MCP
+    # Raised by {Bridge} when a tool call references a tool that no
+    # connected server advertised.
+    class UnknownToolError < Error; end
+  end
+end

data/lib/groq_ruby/mcp/json_rpc.rb

@@ -0,0 +1,51 @@
+module GroqRuby
+  module MCP
+    # Pure builders for JSON-RPC 2.0 messages. No IO, no state — call
+    # these to produce the Hash you'll hand to a transport.
+    module JsonRpc
+      VERSION = "2.0".freeze
+
+      # Build a request envelope. Pair `id` with the Hash returned from a
+      # subsequent inbound response to correlate.
+      #
+      # @param id [Integer, String]
+      # @param method [String]
+      # @param params [Hash, nil]
+      # @return [Hash]
+      def self.request(id:, method:, params: nil)
+        payload = {jsonrpc: VERSION, id: id, method: method}
+        payload[:params] = params unless params.nil?
+        payload
+      end
+
+      # Build a notification envelope (request without id — no response).
+      #
+      # @param method [String]
+      # @param params [Hash, nil]
+      # @return [Hash]
+      def self.notification(method:, params: nil)
+        payload = {jsonrpc: VERSION, method: method}
+        payload[:params] = params unless params.nil?
+        payload
+      end
+
+      # Categorise a parsed inbound message. Returns one of:
+      # `:response`, `:notification`, `:request`, `:invalid`.
+      #
+      # @param message [Hash]
+      # @return [Symbol]
+      def self.classify(message)
+        return :invalid unless message.is_a?(Hash) && message["jsonrpc"] == VERSION
+        if message.key?("id") && (message.key?("result") || message.key?("error"))
+          :response
+        elsif message.key?("method") && !message.key?("id")
+          :notification
+        elsif message.key?("method") && message.key?("id")
+          :request
+        else
+          :invalid
+        end
+      end
+    end
+  end
+end

data/lib/groq_ruby/mcp/prompt.rb

@@ -0,0 +1,21 @@
+module GroqRuby
+  module MCP
+    # An MCP prompt template advertised by a server's `prompts/list`
+    # response. Prompts are typically surfaced to *users* as a picker
+    # rather than handed to the LLM directly — the user fills in the
+    # arguments and the server returns ready-to-send messages via
+    # `prompts/get`.
+    class Prompt < Data.define(:name, :description, :arguments)
+      # @param hash [Hash, nil]
+      # @return [Prompt, nil]
+      def self.from_hash(hash)
+        return nil if hash.nil?
+        new(
+          name: hash["name"] || hash[:name],
+          description: hash["description"] || hash[:description],
+          arguments: Array(hash["arguments"] || hash[:arguments])
+        )
+      end
+    end
+  end
+end

data/lib/groq_ruby/mcp/resource.rb

@@ -0,0 +1,17 @@
+module GroqRuby
+  module MCP
+    # An MCP resource advertised by a server's `resources/list` response.
+    class Resource < Data.define(:uri, :name, :description, :mime_type)
+      # MCP uses `mimeType` (camelCase); we expose `mime_type`.
+      def self.from_hash(hash)
+        return nil if hash.nil?
+        new(
+          uri: hash["uri"] || hash[:uri],
+          name: hash["name"] || hash[:name],
+          description: hash["description"] || hash[:description],
+          mime_type: hash["mimeType"] || hash[:mimeType] || hash["mime_type"] || hash[:mime_type]
+        )
+      end
+    end
+  end
+end

data/lib/groq_ruby/mcp/server_config.rb

@@ -0,0 +1,22 @@
+module GroqRuby
+  module MCP
+    # Description of an MCP server to connect to via stdio. Immutable —
+    # build one per server, then pass to {Client.connect} or {Bridge.new}.
+    #
+    # @example Filesystem server
+    #   ServerConfig.new(
+    #     name: "fs",
+    #     command: "npx",
+    #     args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/docs"]
+    #   )
+    class ServerConfig < Data.define(:name, :command, :args, :env)
+      # @param name [String] short identifier used to namespace tools in {Bridge}
+      # @param command [String] executable to spawn (looked up in PATH)
+      # @param args [Array<String>] arguments passed to the executable
+      # @param env [Hash{String => String}] extra environment variables for the child process
+      def initialize(name:, command:, args: [], env: {})
+        super
+      end
+    end
+  end
+end

data/lib/groq_ruby/mcp/tool.rb

@@ -0,0 +1,22 @@
+module GroqRuby
+  module MCP
+    # An MCP tool advertised by a server's `tools/list` response.
+    # The `input_schema` is a JSON Schema describing the tool's arguments.
+    class Tool < Data.define(:name, :description, :input_schema)
+      extend Models::ModelFactory
+
+      coerce :input_schema, with: ->(v) { v || {} }
+
+      # Override the factory to map MCP's camelCase `inputSchema` field to
+      # our snake_case attribute.
+      def self.from_hash(hash)
+        return nil if hash.nil?
+        new(
+          name: hash["name"] || hash[:name],
+          description: hash["description"] || hash[:description],
+          input_schema: hash["inputSchema"] || hash[:inputSchema] || hash["input_schema"] || hash[:input_schema] || {}
+        )
+      end
+    end
+  end
+end

data/lib/groq_ruby/mcp/transport.rb

@@ -0,0 +1,32 @@
+module GroqRuby
+  module MCP
+    # Interface every MCP transport must satisfy. Synchronous send,
+    # asynchronous receive via a single registered callback. Implementations
+    # own their own background reader thread/loop.
+    #
+    # @abstract
+    module Transport
+      # @param message [Hash] JSON-RPC envelope to deliver to the server
+      # @return [void]
+      def send_message(message)
+        raise NotImplementedError
+      end
+
+      # Register the callback invoked for every inbound message.
+      # Replaces any previous callback. Called from the transport's
+      # reader thread, so callbacks must be thread-safe.
+      #
+      # @yieldparam message [Hash] decoded JSON-RPC envelope
+      # @return [void]
+      def on_message(&block)
+        raise NotImplementedError
+      end
+
+      # Tear down the connection. Idempotent.
+      # @return [void]
+      def stop
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/groq_ruby/mcp/transports/stdio.rb

@@ -0,0 +1,100 @@
+require "open3"
+require "json"
+
+module GroqRuby
+  module MCP
+    module Transports
+      # Stdio transport — spawns the configured executable, talks
+      # newline-delimited JSON over its stdin/stdout, drains stderr to
+      # /dev/null. A background reader thread fans inbound messages out
+      # to the callback registered via {#on_message}.
+      #
+      # @example
+      #   transport = Stdio.spawn(ServerConfig.new(name: "fs", command: "..."))
+      #   transport.on_message { |msg| puts msg.inspect }
+      #   transport.send_message({jsonrpc: "2.0", id: 1, method: "ping"})
+      #   ...
+      #   transport.stop
+      class Stdio
+        include Transport
+
+        # Build and start a Stdio transport for the given server config.
+        # @param config [ServerConfig]
+        # @return [Stdio] a started transport ready to {#send_message}
+        # @raise [TransportError] if the child process cannot be spawned
+        def self.spawn(config)
+          new(config).tap(&:start)
+        end
+
+        # @param config [ServerConfig]
+        def initialize(config)
+          @config = config
+          @on_message = nil
+          @write_mutex = Mutex.new
+          @stopped = false
+        end
+
+        # Spawn the child process and start the reader thread.
+        # @return [self]
+        def start
+          @stdin, @stdout, @stderr, @wait_thr = Open3.popen3(@config.env, @config.command, *@config.args)
+          @stderr_thread = Thread.new { drain(@stderr) }
+          @reader_thread = Thread.new { read_loop }
+          self
+        rescue SystemCallError => e
+          raise TransportError, "could not spawn MCP server #{@config.name.inspect}: #{e.message}"
+        end
+
+        def send_message(message)
+          line = JSON.generate(message)
+          @write_mutex.synchronize do
+            @stdin.puts(line)
+            @stdin.flush
+          end
+        rescue IOError, Errno::EPIPE => e
+          raise TransportError, "stdin closed for MCP server #{@config.name.inspect}: #{e.message}"
+        end
+
+        def on_message(&block)
+          @on_message = block
+        end
+
+        def stop
+          return if @stopped
+          @stopped = true
+          @reader_thread&.kill
+          @stderr_thread&.kill
+          [@stdin, @stdout, @stderr].each { |io| io&.close }
+          @wait_thr&.kill if @wait_thr&.alive?
+        end
+
+        private
+
+        def read_loop
+          while (line = @stdout.gets)
+            stripped = line.strip
+            next if stripped.empty?
+            dispatch(stripped)
+          end
+        rescue IOError
+          # Pipe closed — normal during shutdown.
+        end
+
+        def dispatch(line)
+          message = JSON.parse(line)
+          @on_message&.call(message)
+        rescue JSON::ParserError
+          # Malformed line from server; surface as a synthetic protocol
+          # error so the Client can decide what to do.
+          @on_message&.call({"jsonrpc" => "2.0", "_invalid" => line})
+        end
+
+        def drain(io)
+          io.each_line { |_| }
+        rescue IOError
+          # Closed during shutdown — fine.
+        end
+      end
+    end
+  end
+end

data/lib/groq_ruby/mcp.rb

@@ -0,0 +1,25 @@
+module GroqRuby
+  # Model Context Protocol (MCP) client. Lets a Groq agent talk to MCP
+  # servers — local processes (stdio transport) that expose tools and
+  # resources via JSON-RPC 2.0.
+  #
+  # Two ways in:
+  #
+  # 1. Direct {Client} — connect to one server, call tools yourself:
+  #
+  #        config = GroqRuby::MCP::ServerConfig.new(name: "fs", command: "...", args: [...])
+  #        client = GroqRuby::MCP::Client.connect(config)
+  #        tools  = client.tools_list
+  #        result = client.tools_call(name: "read_file", arguments: {path: "/foo"})
+  #        client.stop
+  #
+  # 2. {Bridge} — wire many servers into Groq's `chat.completions(tools:)`
+  #    automatically and route tool_calls back to the owning server.
+  #
+  #        bridge = GroqRuby::MCP::Bridge.new([fs_config, weather_config])
+  #        groq.chat.completions.create(..., tools: bridge.tools)
+  #        # then bridge.call(tool_call.function.name, JSON.parse(tool_call.function.arguments))
+  module MCP
+    PROTOCOL_VERSION = "2024-11-05".freeze
+  end
+end

data/lib/groq_ruby/models/audio/transcription.rb

@@ -0,0 +1,10 @@
+module GroqRuby
+  module Models
+    # Result of `client.audio.transcriptions.create`. The shape varies with
+    # `response_format` (`json`, `verbose_json`, etc.); we expose both the
+    # primary `text` field and the full payload for richer formats.
+    class Transcription < Data.define(:text, :language, :duration, :segments, :words, :x_groq)
+      extend ModelFactory
+    end
+  end
+end

data/lib/groq_ruby/models/audio/translation.rb

@@ -0,0 +1,8 @@
+module GroqRuby
+  module Models
+    # Result of `client.audio.translations.create`.
+    class Translation < Data.define(:text, :language, :duration, :segments, :x_groq)
+      extend ModelFactory
+    end
+  end
+end

data/lib/groq_ruby/models/batches/batch.rb

@@ -0,0 +1,16 @@
+module GroqRuby
+  module Models
+    # A single batch job descriptor returned by the batches endpoints.
+    class Batch < Data.define(
+      :id, :object, :endpoint, :errors, :input_file_id, :completion_window,
+      :status, :output_file_id, :error_file_id,
+      :created_at, :in_progress_at, :expires_at, :finalizing_at,
+      :completed_at, :failed_at, :expired_at, :cancelling_at, :cancelled_at,
+      :request_counts, :metadata
+    )
+      extend ModelFactory
+
+      coerce :request_counts, with: ->(h) { h && BatchRequestCounts.from_hash(h) }
+    end
+  end
+end

data/lib/groq_ruby/models/batches/batch_list.rb

@@ -0,0 +1,10 @@
+module GroqRuby
+  module Models
+    # Wrapper for a `batches.list` response.
+    class BatchList < Data.define(:data, :object, :first_id, :last_id, :has_more)
+      extend ModelFactory
+
+      coerce :data, with: ->(arr) { Array(arr).map { |h| Batch.from_hash(h) } }
+    end
+  end
+end

data/lib/groq_ruby/models/batches/batch_request_counts.rb

@@ -0,0 +1,8 @@
+module GroqRuby
+  module Models
+    # Per-batch request count summary.
+    class BatchRequestCounts < Data.define(:total, :completed, :failed)
+      extend ModelFactory
+    end
+  end
+end

data/lib/groq_ruby/models/chat/chat_completion.rb

@@ -0,0 +1,14 @@
+module GroqRuby
+  module Models
+    # Full response from `client.chat.completions.create` (non-streaming).
+    class ChatCompletion < Data.define(
+      :id, :object, :created, :model, :choices, :usage,
+      :system_fingerprint, :x_groq
+    )
+      extend ModelFactory
+
+      coerce :choices, with: ->(arr) { Array(arr).map { |h| ChatCompletionChoice.from_hash(h) } }
+      coerce :usage, with: ->(h) { Usage.from_hash(h) }
+    end
+  end
+end

data/lib/groq_ruby/models/chat/chat_completion_choice.rb

@@ -0,0 +1,10 @@
+module GroqRuby
+  module Models
+    # A single completion choice in a {ChatCompletion} response.
+    class ChatCompletionChoice < Data.define(:index, :message, :finish_reason, :logprobs)
+      extend ModelFactory
+
+      coerce :message, with: ->(h) { ChatCompletionMessage.from_hash(h) }
+    end
+  end
+end

data/lib/groq_ruby/models/chat/chat_completion_chunk.rb

@@ -0,0 +1,13 @@
+module GroqRuby
+  module Models
+    # A single Server-Sent Event yielded while streaming a chat completion.
+    class ChatCompletionChunk < Data.define(
+      :id, :object, :created, :model, :choices, :usage, :system_fingerprint, :x_groq
+    )
+      extend ModelFactory
+
+      coerce :choices, with: ->(arr) { Array(arr).map { |h| ChatCompletionChunkChoice.from_hash(h) } }
+      coerce :usage, with: ->(h) { h && Usage.from_hash(h) }
+    end
+  end
+end

data/lib/groq_ruby/models/chat/chat_completion_chunk_choice.rb

@@ -0,0 +1,10 @@
+module GroqRuby
+  module Models
+    # One choice inside a streaming chunk.
+    class ChatCompletionChunkChoice < Data.define(:index, :delta, :finish_reason, :logprobs)
+      extend ModelFactory
+
+      coerce :delta, with: ->(h) { ChatCompletionDelta.from_hash(h) }
+    end
+  end
+end

data/lib/groq_ruby/models/chat/chat_completion_delta.rb

@@ -0,0 +1,8 @@
+module GroqRuby
+  module Models
+    # Delta payload yielded inside a streaming chat completion chunk.
+    class ChatCompletionDelta < Data.define(:role, :content, :tool_calls, :function_call, :refusal, :reasoning)
+      extend ModelFactory
+    end
+  end
+end

data/lib/groq_ruby/models/chat/chat_completion_message.rb

@@ -0,0 +1,10 @@
+module GroqRuby
+  module Models
+    # An assistant message inside a {ChatCompletion} choice.
+    class ChatCompletionMessage < Data.define(
+      :role, :content, :tool_calls, :function_call, :refusal, :reasoning
+    )
+      extend ModelFactory
+    end
+  end
+end