groq_ruby 0.1.0

data/lib/groq_ruby/resources/models.rb

@@ -0,0 +1,35 @@
+module GroqRuby
+  module Resources
+    # `client.models.list / retrieve / delete`.
+    #
+    # @example List
+    #   client.models.list.data.each { |m| puts m.id }
+    #
+    # @example Retrieve
+    #   client.models.retrieve("llama-3.3-70b-versatile")
+    class Models < Base
+      BASE_PATH = "/openai/v1/models".freeze
+
+      # @return [GroqRuby::Models::ModelList]
+      def list
+        payload = perform(Request.new(method: :get, path: BASE_PATH))
+        GroqRuby::Models::ModelList.from_hash(payload)
+      end
+
+      # @param model_id [String]
+      # @return [GroqRuby::Models::Model]
+      # @raise [NotFoundError] if no such model exists for this account
+      def retrieve(model_id)
+        payload = perform(Request.new(method: :get, path: "#{BASE_PATH}/#{model_id}"))
+        GroqRuby::Models::Model.from_hash(payload)
+      end
+
+      # @param model_id [String]
+      # @return [GroqRuby::Models::ModelDeleted]
+      def delete(model_id)
+        payload = perform(Request.new(method: :delete, path: "#{BASE_PATH}/#{model_id}"))
+        GroqRuby::Models::ModelDeleted.from_hash(payload)
+      end
+    end
+  end
+end

data/lib/groq_ruby/response.rb

@@ -0,0 +1,9 @@
+module GroqRuby
+  # Value object representing a parsed HTTP response. The body is either a
+  # decoded JSON object (Hash/Array) or a raw String for binary responses.
+  Response = Data.define(:status, :headers, :body) do
+    def success?
+      status.between?(200, 299)
+    end
+  end
+end

data/lib/groq_ruby/streaming/chunk_stream.rb

@@ -0,0 +1,58 @@
+require "json"
+
+module GroqRuby
+  module Streaming
+    # Lazy stream of parsed chat completion chunks. Wraps the transport's
+    # SSE delivery with the `[DONE]` sentinel handling that OpenAI-style
+    # APIs use, and the JSON decode → model wrap step.
+    #
+    # Yields {GroqRuby::Models::ChatCompletionChunk} instances. Honours the
+    # `[DONE]` terminator by stopping iteration cleanly.
+    #
+    # @example Iterate via Enumerable
+    #   stream = client.chat.completions.create(stream: true, ...)
+    #   stream.each { |chunk| print chunk.choices.first.delta.content }
+    #
+    # @example Pass a block directly
+    #   client.chat.completions.create(stream: true, ...) do |chunk|
+    #     ...
+    #   end
+    class ChunkStream
+      include Enumerable
+
+      DONE_SENTINEL = "[DONE]".freeze
+
+      # @param transport [Transport]
+      # @param request [Request]
+      # @param chunk_model [Class] class with a `.from_hash(Hash)` constructor
+      def initialize(transport:, request:, chunk_model:)
+        @transport = transport
+        @request = request
+        @chunk_model = chunk_model
+      end
+
+      # Iterate through each chunk. When called without a block, returns an
+      # Enumerator that lets callers compose with `Enumerable` methods.
+      #
+      # @yieldparam chunk [GroqRuby::Models::ChatCompletionChunk]
+      # @return [Enumerator] when called without a block
+      # @return [void] when called with a block
+      # @raise [APIError] subclass on non-2xx response or transport failure.
+      def each(&block)
+        return enum_for(:each) unless block_given?
+        parser = EventParser.new
+        result = @transport.stream(@request) do |raw_chunk|
+          parser.feed(raw_chunk) { |_event, data, _id, _retry| forward_event(data, &block) }
+        end
+        raise result.failure if result.failure?
+      end
+
+      private
+
+      def forward_event(data, &block)
+        return if data.nil? || data.empty? || data == DONE_SENTINEL
+        block.call(@chunk_model.from_hash(JSON.parse(data)))
+      end
+    end
+  end
+end

data/lib/groq_ruby/streaming/event_parser.rb

@@ -0,0 +1,23 @@
+require "event_stream_parser"
+
+module GroqRuby
+  module Streaming
+    # Thin adapter over the upstream `event_stream_parser` gem. Feeds raw
+    # response chunks in and yields parsed `(event, data, id, retry)`
+    # tuples. Single-purpose: it owns the SSE parser state and nothing else.
+    class EventParser
+      def initialize
+        @parser = ::EventStreamParser::Parser.new
+      end
+
+      # Feed a raw chunk from the HTTP response. Yields each parsed event.
+      # @yieldparam event [String, nil]
+      # @yieldparam data [String]
+      # @yieldparam id [String, nil]
+      # @yieldparam reconnect_time [Integer, nil]
+      def feed(chunk, &block)
+        @parser.feed(chunk, &block)
+      end
+    end
+  end
+end

data/lib/groq_ruby/transport.rb

@@ -0,0 +1,169 @@
+require "net/http"
+require "json"
+require "uri"
+require "dry/monads"
+
+module GroqRuby
+  # The single HTTP client used by every resource. Wraps Net::HTTP and
+  # exposes two operations: a buffered {#call} for ordinary requests and a
+  # streaming {#stream} for SSE (chat completions with `stream: true`).
+  #
+  # Both methods return a Result. Internal control flow uses Do notation
+  # so the happy path stays linear; transport-level failures are wrapped in
+  # the appropriate {APIError} subclass.
+  #
+  # Resources call `.value!` to surface the parsed response (raising on
+  # failure), preserving parity with the Python client's exception model.
+  class Transport
+    include Dry::Monads[:result, :do]
+
+    JSON_CONTENT_TYPE = "application/json"
+
+    # @param configuration [Configuration]
+    def initialize(configuration)
+      @config = configuration
+    end
+
+    # Execute a buffered request.
+    #
+    # @param request [Request]
+    # @param accept [Symbol] :json (decode body as JSON) or :binary (return raw String)
+    # @return [Dry::Monads::Result<Response, APIError>]
+    def call(request, accept: :json)
+      raw = yield execute(request)
+      response = yield decode(raw, accept)
+      yield validate(response)
+      Success(response)
+    end
+
+    # Execute a streaming request, yielding each raw chunk to the block.
+    # The HTTP response is opened in chunked mode; the body is never
+    # buffered in full. Validates the status before streaming begins;
+    # error responses are read in full so the body can be parsed and
+    # surfaced via the mapped exception.
+    #
+    # @yieldparam chunk [String]
+    # @return [Dry::Monads::Result<Response, APIError>]
+    def stream(request, &on_chunk)
+      uri = build_uri(request)
+      http = build_http(uri)
+      net_request = build_net_request(request, uri)
+
+      with_translated_errors do
+        outcome = nil
+        http.start do |conn|
+          conn.request(net_request) do |raw|
+            outcome = stream_response(raw, &on_chunk)
+          end
+        end
+        outcome
+      end
+    end
+
+    private
+
+    def execute(request)
+      uri = build_uri(request)
+      http = build_http(uri)
+      net_request = build_net_request(request, uri)
+
+      with_translated_errors do
+        Success(http.start { |conn| conn.request(net_request) })
+      end
+    end
+
+    def with_translated_errors
+      yield
+    rescue Net::OpenTimeout, Net::ReadTimeout => e
+      Failure(APITimeoutError.new(e.message))
+    rescue SocketError, Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH => e
+      Failure(APIConnectionError.new(e.message))
+    end
+
+    def decode(raw, accept)
+      headers = collect_headers(raw)
+      body = raw.body || ""
+      decoded = (accept == :json) ? decode_json(body) : body
+      Success(Response.new(status: raw.code.to_i, headers: headers, body: decoded))
+    rescue JSON::ParserError => e
+      Failure(APIResponseError.new("invalid JSON response: #{e.message}"))
+    end
+
+    def decode_json(body)
+      body.empty? ? nil : JSON.parse(body)
+    end
+
+    def validate(response)
+      response.success? ? Success(response) : Failure(map_error(response))
+    end
+
+    def stream_response(raw, &on_chunk)
+      status = raw.code.to_i
+      headers = collect_headers(raw)
+      if status.between?(200, 299)
+        raw.read_body(&on_chunk)
+        Success(Response.new(status: status, headers: headers, body: nil))
+      else
+        body = decode_json_safe(raw.read_body)
+        Failure(map_error(Response.new(status: status, headers: headers, body: body)))
+      end
+    end
+
+    def decode_json_safe(body)
+      decode_json(body)
+    rescue JSON::ParserError
+      body
+    end
+
+    def map_error(response)
+      ErrorMapper.call(status: response.status, headers: response.headers, body: response.body)
+    end
+
+    def collect_headers(raw)
+      raw.each_header.to_h
+    end
+
+    def build_uri(request)
+      uri = URI.parse("#{@config.base_url.chomp("/")}/#{request.path.delete_prefix("/")}")
+      uri.query = URI.encode_www_form(request.query) if request.query && !request.query.empty?
+      uri
+    end
+
+    def build_http(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.open_timeout = @config.open_timeout
+      http.read_timeout = @config.read_timeout
+      http
+    end
+
+    def build_net_request(request, uri)
+      klass = net_http_class(request.method)
+      net_request = klass.new(uri.request_uri)
+      apply_headers(net_request, request)
+      apply_body(net_request, request)
+      net_request
+    end
+
+    def net_http_class(method)
+      case method
+      when :get then Net::HTTP::Get
+      when :post then Net::HTTP::Post
+      when :delete then Net::HTTP::Delete
+      else raise ArgumentError, "unsupported HTTP method: #{method.inspect}"
+      end
+    end
+
+    def apply_headers(net_request, request)
+      @config.default_headers.each { |k, v| net_request[k] = v }
+      request.headers.each { |k, v| net_request[k] = v }
+      net_request["Content-Type"] = request.content_type if request.content_type
+    end
+
+    def apply_body(net_request, request)
+      return if request.body.nil?
+      net_request.body = request.body.is_a?(String) ? request.body : JSON.generate(request.body)
+      net_request["Content-Type"] ||= JSON_CONTENT_TYPE
+    end
+  end
+end

data/lib/groq_ruby/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module GroqRuby
+  VERSION = "0.1.0"
+end

data/lib/groq_ruby.rb

@@ -0,0 +1,36 @@
+require "zeitwerk"
+
+loader = Zeitwerk::Loader.for_gem
+# Acronyms that can't be derived from the default snake_case → CamelCase
+# inflection. Each maps a basename (without `.rb`) to its constant.
+loader.inflector.inflect(
+  "mcp" => "MCP",
+  "api_error" => "APIError",
+  "api_connection_error" => "APIConnectionError",
+  "api_timeout_error" => "APITimeoutError",
+  "api_status_error" => "APIStatusError",
+  "api_response_error" => "APIResponseError"
+)
+# Collapse organizational sub-directories so files inside them define
+# constants in the parent namespace. Public API stays flat — callers
+# write `GroqRuby::AuthenticationError`, not `GroqRuby::Errors::Auth…`.
+loader.collapse("#{__dir__}/groq_ruby/errors")
+loader.collapse("#{__dir__}/groq_ruby/mcp/errors")
+loader.collapse("#{__dir__}/groq_ruby/models/chat")
+loader.collapse("#{__dir__}/groq_ruby/models/audio")
+loader.collapse("#{__dir__}/groq_ruby/models/embeddings")
+loader.collapse("#{__dir__}/groq_ruby/models/files")
+loader.collapse("#{__dir__}/groq_ruby/models/batches")
+loader.setup
+
+# Idiomatic Ruby client for the Groq API. See {GroqRuby::Client} for the
+# main entry point and the `examples/` directory for end-to-end snippets.
+module GroqRuby
+  # Convenience constructor — `GroqRuby.client` reads configuration from
+  # the `GROQ_API_KEY` and `GROQ_BASE_URL` env vars by default.
+  #
+  # @return [Client]
+  def self.client(**opts)
+    Client.new(**opts)
+  end
+end

data/lib/tasks/gem.rake

@@ -0,0 +1,5 @@
+require "bundler/gem_helper"
+
+namespace :gem do
+  Bundler::GemHelper.install_tasks
+end

data/lib/tasks/lint/all.rake

@@ -0,0 +1,11 @@
+namespace :lint do
+  desc "Run all linter checks"
+  task all: %i[rubocop] do
+    puts "All lints completed successfully!"
+  end
+
+  namespace :all do
+    desc "Run all linter autocorrects"
+    task autocorrect: %i[rubocop:autocorrect]
+  end
+end

data/lib/tasks/lint/rubocop.rake

@@ -0,0 +1,15 @@
+require "rubocop/rake_task"
+
+namespace :lint do
+  desc "Run rubocop linter check"
+  task :rubocop do
+    exec "bundle exec rubocop"
+  end
+
+  namespace :rubocop do
+    desc "Run rubocop autocorrect"
+    task :autocorrect do
+      exec "bundle exec rubocop --autocorrect-all"
+    end
+  end
+end

data/lib/tasks/security.rake

@@ -0,0 +1,11 @@
+require "bundler/audit/task"
+
+Bundler::Audit::Task.new
+
+namespace :security do
+  desc "Update vulnerability database and run audit"
+  task :audit do
+    Rake::Task["bundle:audit:update"].invoke
+    Rake::Task["bundle:audit"].invoke
+  end
+end

data/lib/tasks/types.rake

@@ -0,0 +1,11 @@
+namespace :types do
+  desc "Validate RBS syntax in sig/ (catches sigs that reference nonexistent types)"
+  task :validate do
+    sh "bundle exec rbs " \
+       "-r uri -r ipaddr -r stringio -r tempfile -r net-http -r openssl -r resolv -r zlib " \
+       "-I sig validate"
+  end
+end
+
+desc "Validate RBS sigs"
+task types: ["types:validate"]

data/sig/groq_ruby.rbs

@@ -0,0 +1,191 @@
+module GroqRuby
+  VERSION: String
+
+  def self.client: (**untyped opts) -> Client
+
+  class Error < StandardError
+  end
+
+  class ConfigurationError < Error
+  end
+
+  class ParameterError < Error
+    attr_reader messages: Hash[untyped, untyped]
+    def initialize: (Hash[untyped, untyped] messages) -> void
+  end
+
+  class APIError < Error
+    attr_reader request: untyped
+    def initialize: (String message, ?request: untyped?) -> void
+  end
+
+  class APIConnectionError < APIError
+  end
+
+  class APITimeoutError < APIConnectionError
+  end
+
+  class APIStatusError < APIError
+    attr_reader status: Integer
+    attr_reader headers: Hash[String, String]
+    attr_reader body: untyped
+
+    def initialize: (
+      String message,
+      status: Integer,
+      ?headers: Hash[String, String],
+      ?body: untyped,
+      ?request: untyped?
+    ) -> void
+  end
+
+  class BadRequestError < APIStatusError
+  end
+
+  class AuthenticationError < APIStatusError
+  end
+
+  class PermissionDeniedError < APIStatusError
+  end
+
+  class NotFoundError < APIStatusError
+  end
+
+  class ConflictError < APIStatusError
+  end
+
+  class UnprocessableEntityError < APIStatusError
+  end
+
+  class RateLimitError < APIStatusError
+  end
+
+  class InternalServerError < APIStatusError
+  end
+
+  class APIResponseError < APIError
+  end
+
+  class Client
+    attr_reader configuration: untyped
+
+    def initialize: (
+      ?api_key: String?,
+      ?base_url: String?,
+      ?open_timeout: (Float | Integer)?,
+      ?read_timeout: (Float | Integer)?,
+      ?user_agent: String?
+    ) -> void
+
+    def chat: () -> untyped
+    def embeddings: () -> untyped
+    def audio: () -> untyped
+    def models: () -> untyped
+    def files: () -> untyped
+    def batches: () -> untyped
+  end
+
+  module MCP
+    PROTOCOL_VERSION: String
+
+    class Error < GroqRuby::Error
+    end
+
+    class TransportError < Error
+    end
+
+    class TimeoutError < Error
+    end
+
+    class ProtocolError < Error
+    end
+
+    class JsonRpcError < Error
+      attr_reader code: Integer
+      attr_reader data: untyped
+
+      def initialize: (code: Integer, message: String, ?data: untyped) -> void
+    end
+
+    class UnknownToolError < Error
+    end
+
+    class ServerConfig
+      attr_reader name: String
+      attr_reader command: String
+      attr_reader args: Array[String]
+      attr_reader env: Hash[String, String]
+
+      def initialize: (
+        name: String,
+        command: String,
+        ?args: Array[String],
+        ?env: Hash[String, String]
+      ) -> void
+    end
+
+    module ClaudeDesktopConfig
+      VAR_PATTERN: Regexp
+
+      def self.load: (String path) -> Array[ServerConfig]
+      def self.parse: ((Hash[untyped, untyped] | String) input) -> Array[ServerConfig]
+    end
+
+    class Tool
+      attr_reader name: String
+      attr_reader description: String?
+      attr_reader input_schema: Hash[String, untyped]
+      def self.from_hash: (Hash[untyped, untyped]?) -> Tool?
+    end
+
+    class Resource
+      attr_reader uri: String
+      attr_reader name: String?
+      attr_reader description: String?
+      attr_reader mime_type: String?
+      def self.from_hash: (Hash[untyped, untyped]?) -> Resource?
+    end
+
+    class Prompt
+      attr_reader name: String
+      attr_reader description: String?
+      attr_reader arguments: Array[untyped]
+      def self.from_hash: (Hash[untyped, untyped]?) -> Prompt?
+    end
+
+    class Client
+      DEFAULT_REQUEST_TIMEOUT: Float
+
+      attr_reader server_name: String?
+      attr_reader server_version: String?
+      attr_reader server_capabilities: Hash[String, untyped]
+
+      def self.connect: (ServerConfig, ?request_timeout: Numeric) -> Client
+      def initialize: (untyped transport, ?request_timeout: Numeric) -> void
+      def initialize_session: () -> Hash[String, untyped]
+      def tools_list: () -> Array[Tool]
+      def tools_call: (name: String, ?arguments: Hash[untyped, untyped]) -> Hash[String, untyped]
+      def resources_list: () -> Array[Resource]
+      def resources_read: (String uri) -> Hash[String, untyped]
+      def prompts_list: () -> Array[Prompt]
+      def prompts_get: (String name, ?Hash[untyped, untyped] arguments) -> Hash[String, untyped]
+      def supports?: (String capability) -> bool
+      def stop: () -> void
+    end
+
+    class Bridge
+      NAME_SEPARATOR: String
+      READ_RESOURCE_SUFFIX: String
+
+      def initialize: (Array[ServerConfig], ?request_timeout: Numeric) -> void
+      def tools: () -> Array[Hash[Symbol, untyped]]
+      def tool_names: () -> Array[String]
+      def resources: () -> Array[Hash[Symbol, untyped]]
+      def prompts: () -> Array[Hash[Symbol, untyped]]
+      def call: (String namespaced_name, (Hash[untyped, untyped] | String) arguments) -> Hash[String, untyped]
+      def read_resource: (String uri, ?server: String?) -> Hash[String, untyped]
+      def get_prompt: (String namespaced_name, ?Hash[untyped, untyped] arguments) -> Hash[String, untyped]
+      def stop: () -> void
+    end
+  end
+end

data/sig/zeitwerk.rbs

@@ -0,0 +1,13 @@
+# Minimal type stubs for Zeitwerk. We only use a tiny slice of its API in the
+# gem entry point — `Zeitwerk::Loader.for_gem` plus `#ignore` and `#setup` on
+# the returned loader. The community gem_rbs_collection has fuller sigs; this
+# stub avoids pulling that in for one bootstrap call.
+module Zeitwerk
+  class Loader
+    def self.for_gem: () -> Loader
+
+    def ignore: (*String paths) -> void
+
+    def setup: () -> void
+  end
+end