groq_ruby 0.1.0

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "minitest/test_task"
+
+Dir.glob("lib/tasks/**/*.rake").each { |r| load r }
+
+Minitest::TestTask.create
+
+task default: %i[test lint types]
+desc "Run linter"
+task lint: "lint:all"

data/examples/README.md

@@ -0,0 +1,39 @@
+# groq_ruby examples
+
+Each script is self-contained and reads `GROQ_API_KEY` from the environment.
+
+```sh
+export GROQ_API_KEY=gsk_...
+
+bundle exec examples/chat_completion.rb
+bundle exec examples/chat_completion_streaming.rb
+bundle exec examples/chat_completion_stop.rb
+bundle exec examples/embedding.rb
+bundle exec examples/transcription.rb path/to/audio.mp3
+bundle exec examples/translation.rb path/to/audio.mp3
+bundle exec examples/speech.rb "Hello, Groq."
+bundle exec examples/models_list.rb
+bundle exec examples/file_upload.rb path/to/requests.jsonl
+bundle exec examples/batch.rb file_abc123
+bundle exec examples/error_handling.rb
+bundle exec examples/mcp_agent.rb /path/to/sandbox             # needs npx
+bundle exec examples/mcp_chat_with_tools.rb /path/to/sandbox   # needs npx
+bundle exec examples/mcp_resources_and_prompts.rb /path/to/sandbox  # needs npx
+```
+
+| Script                         | Endpoint                                     | What it shows                                    |
+|--------------------------------|----------------------------------------------|--------------------------------------------------|
+| `chat_completion.rb`           | `POST /openai/v1/chat/completions`           | Buffered chat completion with usage info         |
+| `chat_completion_streaming.rb` | same, `stream: true`                         | Token-by-token Server-Sent-Events streaming      |
+| `chat_completion_stop.rb`      | same                                         | Custom `stop` sequence + reading `finish_reason` |
+| `embedding.rb`                 | `POST /openai/v1/embeddings`                 | Generating an embedding vector                   |
+| `transcription.rb`             | `POST /openai/v1/audio/transcriptions`       | Whisper STT from a local file                    |
+| `translation.rb`               | `POST /openai/v1/audio/translations`         | Whisper STT translated into English              |
+| `speech.rb`                    | `POST /openai/v1/audio/speech`               | TTS — saves a WAV to disk                        |
+| `models_list.rb`               | `GET /openai/v1/models`                      | Listing available models                         |
+| `file_upload.rb`               | `POST /openai/v1/files` (+ list/info/delete) | Multipart file upload lifecycle                  |
+| `batch.rb`                     | `POST /openai/v1/batches` (+ retrieve poll)  | Async batch submission and status polling        |
+| `error_handling.rb`            | any                                          | Catching the typed error hierarchy               |
+| `mcp_agent.rb`                 | chat.completions + MCP                       | Minimal agent loop — bridge tools, dispatch tool_calls back |
+| `mcp_chat_with_tools.rb`       | chat.completions + MCP                       | Heavily annotated walkthrough of the same loop, step by step |
+| `mcp_resources_and_prompts.rb` | chat.completions + MCP                       | Full coverage: tools + resources (synthetic read_resource) + prompts |

data/examples/batch.rb

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# Submit a batch job referencing a previously uploaded JSONL file, then poll
+# until it terminates.
+#
+# Usage:
+#   GROQ_API_KEY=gsk_... bundle exec examples/batch.rb <input_file_id>
+
+require "bundler/setup"
+require "groq_ruby"
+
+input_file_id = ARGV.first || abort("usage: batch.rb <input_file_id>")
+
+client = GroqRuby::Client.new
+
+batch = client.batches.create(
+  input_file_id: input_file_id,
+  endpoint: "/v1/chat/completions",
+  completion_window: "24h"
+)
+puts "submitted batch id=#{batch.id} status=#{batch.status}"
+
+terminal = %w[completed failed cancelled expired].freeze
+
+loop do
+  current = client.batches.retrieve(batch.id)
+  puts "status=#{current.status}"
+  break if terminal.include?(current.status)
+  sleep 5
+end

data/examples/chat_completion.rb

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+# Buffered chat completion. Reads GROQ_API_KEY from the environment.
+#
+# Usage:
+#   GROQ_API_KEY=gsk_... bundle exec examples/chat_completion.rb
+
+require "bundler/setup"
+require "groq_ruby"
+
+client = GroqRuby::Client.new
+
+response = client.chat.completions.create(
+  model: "llama-3.3-70b-versatile",
+  messages: [
+    {role: "system", content: "You are a helpful assistant."},
+    {role: "user", content: "Explain the importance of low-latency LLMs in two sentences."}
+  ],
+  temperature: 0.5,
+  max_completion_tokens: 256
+)
+
+puts response.choices.first.message.content
+puts
+puts "tokens: prompt=#{response.usage.prompt_tokens} completion=#{response.usage.completion_tokens} total=#{response.usage.total_tokens}"

data/examples/chat_completion_stop.rb

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+# Chat completion that halts when the model emits a custom stop sequence.
+#
+# Usage:
+#   GROQ_API_KEY=gsk_... bundle exec examples/chat_completion_stop.rb
+
+require "bundler/setup"
+require "groq_ruby"
+
+client = GroqRuby::Client.new
+
+response = client.chat.completions.create(
+  model: "llama-3.3-70b-versatile",
+  messages: [{role: "user", content: "Count from 1 to 10."}],
+  stop: ", 6"
+)
+
+puts response.choices.first.message.content
+puts "finish_reason: #{response.choices.first.finish_reason}"

data/examples/chat_completion_streaming.rb

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+# Streaming chat completion. Each chunk is yielded as it arrives.
+#
+# Usage:
+#   GROQ_API_KEY=gsk_... bundle exec examples/chat_completion_streaming.rb
+
+require "bundler/setup"
+require "groq_ruby"
+
+client = GroqRuby::Client.new
+
+client.chat.completions.create(
+  model: "llama-3.3-70b-versatile",
+  messages: [
+    {role: "user", content: "Write a short poem about latency."}
+  ],
+  stream: true
+) do |chunk|
+  delta = chunk.choices.first.delta.content
+  print delta if delta
+end
+
+puts

data/examples/embedding.rb

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+# Generate an embedding vector for a piece of text.
+#
+# Usage:
+#   GROQ_API_KEY=gsk_... bundle exec examples/embedding.rb
+
+require "bundler/setup"
+require "groq_ruby"
+
+client = GroqRuby::Client.new
+
+response = client.embeddings.create(
+  model: "nomic-embed-text-v1_5",
+  input: "Groq makes inference very fast."
+)
+
+vector = response.data.first.embedding
+puts "vector length: #{vector.is_a?(Array) ? vector.size : "(base64)"}"
+puts "first 5 dims: #{vector.first(5).inspect}" if vector.is_a?(Array)
+puts "tokens: #{response.usage.prompt_tokens}"

data/examples/error_handling.rb

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# Demonstrates the error hierarchy. Every API failure raises a subclass of
+# GroqRuby::APIError so callers can rescue the base class and degrade
+# gracefully — or pattern-match on a specific status code.
+#
+# Usage:
+#   GROQ_API_KEY=invalid bundle exec examples/error_handling.rb
+
+require "bundler/setup"
+require "groq_ruby"
+
+client = GroqRuby::Client.new
+
+begin
+  client.chat.completions.create(
+    model: "llama-3.3-70b-versatile",
+    messages: [{role: "user", content: "Hi"}]
+  )
+rescue GroqRuby::AuthenticationError => e
+  warn "auth failed (status #{e.status}): #{e.message}"
+rescue GroqRuby::RateLimitError => e
+  warn "rate limited: #{e.message}"
+rescue GroqRuby::APIStatusError => e
+  warn "status #{e.status}: #{e.message}"
+rescue GroqRuby::APIConnectionError => e
+  warn "network: #{e.message}"
+end

data/examples/file_upload.rb

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+# Upload a JSONL file for use with the batch API, then list, info, and delete.
+#
+# Usage:
+#   GROQ_API_KEY=gsk_... bundle exec examples/file_upload.rb path/to/requests.jsonl
+
+require "bundler/setup"
+require "groq_ruby"
+
+path = ARGV.first || abort("usage: file_upload.rb <jsonl-file>")
+
+client = GroqRuby::Client.new
+
+uploaded = File.open(path, "rb") do |file|
+  client.files.create(file: file, filename: File.basename(path), purpose: "batch")
+end
+puts "uploaded id=#{uploaded.id} bytes=#{uploaded.bytes}"
+
+info = client.files.info(uploaded.id)
+puts "info: filename=#{info.filename} purpose=#{info.purpose}"
+
+deleted = client.files.delete(uploaded.id)
+puts "deleted=#{deleted.deleted}"

data/examples/mcp_agent.rb

@@ -0,0 +1,63 @@
+#!/usr/bin/env ruby
+# Minimal MCP-powered agent loop:
+#   1. Connect to one or more MCP servers via stdio
+#   2. Expose their tools through chat.completions(tools:)
+#   3. If the model wants to call a tool, dispatch through the bridge
+#      and feed the result back as a follow-up message.
+#
+# Usage:
+#   GROQ_API_KEY=gsk_... bundle exec examples/mcp_agent.rb
+#
+# This example uses the official @modelcontextprotocol/server-filesystem
+# MCP server. Install once with:  npm install -g @modelcontextprotocol/server-filesystem
+
+require "bundler/setup"
+require "groq_ruby"
+require "json"
+
+ROOT = ARGV[0] || Dir.pwd
+
+filesystem = GroqRuby::MCP::ServerConfig.new(
+  name: "fs",
+  command: "npx",
+  args: ["-y", "@modelcontextprotocol/server-filesystem", ROOT]
+)
+
+bridge = GroqRuby::MCP::Bridge.new([filesystem])
+groq = GroqRuby::Client.new
+
+messages = [
+  {role: "system", content: "You can read files in #{ROOT}. Use tools to answer."},
+  {role: "user", content: "List the files in the directory and tell me what's there."}
+]
+
+begin
+  loop do
+    response = groq.chat.completions.create(
+      model: "llama-3.3-70b-versatile",
+      messages: messages,
+      tools: bridge.tools
+    )
+
+    message = response.choices.first.message
+    tool_calls = message.tool_calls
+
+    if tool_calls.nil? || tool_calls.empty?
+      puts message.content
+      break
+    end
+
+    messages << {role: "assistant", content: message.content, tool_calls: tool_calls}
+    tool_calls.each do |call|
+      function = call["function"]
+      result = bridge.call(function["name"], function["arguments"])
+      messages << {
+        role: "tool",
+        tool_call_id: call["id"],
+        content: JSON.generate(result)
+      }
+    end
+  end
+ensure
+  bridge.stop
+end

data/examples/mcp_chat_with_tools.rb

@@ -0,0 +1,103 @@
+#!/usr/bin/env ruby
+# Annotated walkthrough: how an MCP server's tools become a Groq
+# `tools:` argument and how a returned `tool_calls` flows back to the
+# right MCP server.
+#
+# Usage:
+#   GROQ_API_KEY=gsk_... bundle exec examples/mcp_chat_with_tools.rb [DIR]
+#
+# Requires the official filesystem MCP server. One-time install:
+#   npm install -g @modelcontextprotocol/server-filesystem
+
+require "bundler/setup"
+require "groq_ruby"
+require "json"
+
+ROOT = ARGV[0] || Dir.pwd
+
+# 1. Describe each MCP server you want to expose. ServerConfig is purely
+#    declarative — nothing is spawned yet. `name` is the prefix the bridge
+#    uses to namespace this server's tools (so `read_file` from server
+#    `fs` becomes `fs__read_file` to the model).
+filesystem = GroqRuby::MCP::ServerConfig.new(
+  name: "fs",
+  command: "npx",
+  args: ["-y", "@modelcontextprotocol/server-filesystem", ROOT]
+)
+
+# 2. Build the Bridge. This synchronously: spawns each server's stdio
+#    process, runs the MCP `initialize` handshake, asks each server for
+#    its tool list, and indexes those tools by namespaced name.
+#
+#    From this point on, `bridge.tools` returns OpenAI/Groq-shaped tool
+#    definitions ready to drop into chat.completions.
+bridge = GroqRuby::MCP::Bridge.new([filesystem])
+groq = GroqRuby::Client.new
+
+# Inspect what the bridge advertises:
+puts "tools advertised to the model:"
+bridge.tools.each { |t| puts "  - #{t[:function][:name]}: #{t[:function][:description]}" }
+puts
+
+# 3. The conversation. The system prompt nudges the model to use the
+#    tools we just enumerated.
+messages = [
+  {role: "system", content: "You can use filesystem tools to inspect files in #{ROOT}. Prefer tools over speculation."},
+  {role: "user", content: "Look at the README in #{ROOT} and summarise it in two sentences."}
+]
+
+# 4. Agent loop. Each iteration:
+#      a. ask Groq for the next assistant turn, passing bridge.tools
+#      b. if Groq returned plain content, print it and stop
+#      c. otherwise dispatch every tool_call through the bridge and feed
+#         the result back as a `role: tool` message
+begin
+  loop do
+    response = groq.chat.completions.create(
+      model: "llama-3.3-70b-versatile",
+      messages: messages,
+      tools: bridge.tools,
+      # `tool_choice: "auto"` is the default — Groq decides whether to
+      # answer directly or call a tool. Use "required" to force a tool
+      # call, or {type: "function", function: {name: "fs__read_file"}}
+      # to demand a specific one.
+      tool_choice: "auto"
+    )
+
+    message = response.choices.first.message
+    tool_calls = message.tool_calls
+
+    if tool_calls.nil? || tool_calls.empty?
+      puts "\nassistant: #{message.content}"
+      break
+    end
+
+    # 5. Add the assistant turn (with its tool_calls) to the history,
+    #    then resolve each tool_call against the bridge.
+    messages << {role: "assistant", content: message.content, tool_calls: tool_calls}
+
+    tool_calls.each do |call|
+      fn = call["function"]
+      puts "tool call: #{fn["name"]}(#{fn["arguments"]})"
+
+      # bridge.call accepts either a Hash or the raw JSON string Groq
+      # returns in `function.arguments`. It looks up the namespaced name,
+      # forwards the call to the owning MCP server, and returns the
+      # server's tool_call result (typically `{"content" => [...]}`).
+      result = bridge.call(fn["name"], fn["arguments"])
+
+      messages << {
+        role: "tool",
+        tool_call_id: call["id"],
+        # The chat-completions endpoint expects tool results as strings.
+        # Most MCP results are wrapped Hashes — encode them so the model
+        # sees structured data on the next turn.
+        content: JSON.generate(result)
+      }
+    end
+  end
+ensure
+  # 6. Always stop the bridge. This kills each MCP server's child
+  #    process and closes the stdio pipes.
+  bridge.stop
+end

data/examples/mcp_resources_and_prompts.rb

@@ -0,0 +1,89 @@
+#!/usr/bin/env ruby
+# Demonstrates the full MCP coverage of Bridge:
+#   * tools     — surfaced as Groq function tools
+#   * resources — surfaced via a synthetic <server>__read_resource tool
+#                 (and inventoried in the system prompt so the LLM knows
+#                 which URIs exist)
+#   * prompts   — surfaced to YOU (the application), not the LLM
+#
+# Usage:
+#   GROQ_API_KEY=gsk_... bundle exec examples/mcp_resources_and_prompts.rb [DIR]
+#
+# Requires the official filesystem MCP server. One-time install:
+#   npm install -g @modelcontextprotocol/server-filesystem
+
+require "bundler/setup"
+require "groq_ruby"
+require "json"
+
+ROOT = ARGV[0] || Dir.pwd
+
+filesystem = GroqRuby::MCP::ServerConfig.new(
+  name: "fs",
+  command: "npx",
+  args: ["-y", "@modelcontextprotocol/server-filesystem", ROOT]
+)
+
+bridge = GroqRuby::MCP::Bridge.new([filesystem])
+groq = GroqRuby::Client.new
+
+# 1. Inspect what each MCP capability gave us.
+puts "tools (#{bridge.tools.size}):"
+bridge.tools.each { |t| puts "  - #{t[:function][:name]}" }
+puts
+puts "resources (#{bridge.resources.size}):"
+bridge.resources.each { |r| puts "  - #{r[:resource].uri} (#{r[:resource].name})" }
+puts
+puts "prompts (#{bridge.prompts.size}):"
+bridge.prompts.each { |p| puts "  - #{p[:namespaced_name]}: #{p[:prompt].description}" }
+puts
+
+# 2. Build a system prompt that catalogues the available resources so
+#    the LLM knows which URIs are valid arguments to the synthetic
+#    `<server>__read_resource` tool that Bridge injects into bridge.tools.
+resource_catalogue = bridge.resources.map { |r|
+  "  - #{r[:resource].uri} — #{r[:resource].name || r[:resource].description}"
+}.join("\n")
+
+system_prompt = <<~PROMPT
+  You can use these tools to inspect files in #{ROOT}.
+
+  In addition to the named tools, you can call `fs__read_resource(uri)` to
+  fetch any of these resources:
+  #{resource_catalogue}
+PROMPT
+
+messages = [
+  {role: "system", content: system_prompt},
+  {role: "user", content: "What's in the README?"}
+]
+
+# 3. Run the loop. Bridge.call transparently routes both real tool calls
+#    and the synthetic `fs__read_resource` calls.
+begin
+  loop do
+    response = groq.chat.completions.create(
+      model: "llama-3.3-70b-versatile",
+      messages: messages,
+      tools: bridge.tools
+    )
+
+    message = response.choices.first.message
+    tool_calls = message.tool_calls
+
+    if tool_calls.nil? || tool_calls.empty?
+      puts "\nassistant: #{message.content}"
+      break
+    end
+
+    messages << {role: "assistant", content: message.content, tool_calls: tool_calls}
+    tool_calls.each do |call|
+      fn = call["function"]
+      puts "  -> #{fn["name"]}(#{fn["arguments"]})"
+      result = bridge.call(fn["name"], fn["arguments"])
+      messages << {role: "tool", tool_call_id: call["id"], content: JSON.generate(result)}
+    end
+  end
+ensure
+  bridge.stop
+end

data/examples/models_list.rb

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+# List the models available on the Groq account.
+#
+# Usage:
+#   GROQ_API_KEY=gsk_... bundle exec examples/models_list.rb
+
+require "bundler/setup"
+require "groq_ruby"
+
+client = GroqRuby::Client.new
+
+response = client.models.list
+
+response.data.each do |model|
+  puts "%-50s owned_by=%-15s context=%s" % [model.id, model.owned_by, model.context_window]
+end

data/examples/speech.rb

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+# Synthesise speech from text (TTS) and write it to a file.
+#
+# Usage:
+#   GROQ_API_KEY=gsk_... bundle exec examples/speech.rb "Hello, Groq."
+
+require "bundler/setup"
+require "groq_ruby"
+
+text = ARGV.first || "Hello from Groq."
+
+client = GroqRuby::Client.new
+
+audio_bytes = client.audio.speech.create(
+  input: text,
+  model: "playai-tts",
+  voice: "Aaliyah-PlayAI",
+  response_format: "wav"
+)
+
+out = "speech.wav"
+File.binwrite(out, audio_bytes)
+puts "wrote #{out} (#{audio_bytes.bytesize} bytes)"

data/examples/transcription.rb

@@ -0,0 +1,23 @@
+#!/usr/bin/env ruby
+# Transcribe a local audio file with Whisper.
+#
+# Usage:
+#   GROQ_API_KEY=gsk_... bundle exec examples/transcription.rb path/to/audio.mp3
+
+require "bundler/setup"
+require "groq_ruby"
+
+audio_path = ARGV.first || abort("usage: transcription.rb <audio-file>")
+
+client = GroqRuby::Client.new
+
+response = File.open(audio_path, "rb") do |file|
+  client.audio.transcriptions.create(
+    file: file,
+    filename: File.basename(audio_path),
+    model: "whisper-large-v3-turbo",
+    response_format: "json"
+  )
+end
+
+puts response.text

data/examples/translation.rb

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+# Translate non-English speech to English text.
+#
+# Usage:
+#   GROQ_API_KEY=gsk_... bundle exec examples/translation.rb path/to/audio.mp3
+
+require "bundler/setup"
+require "groq_ruby"
+
+audio_path = ARGV.first || abort("usage: translation.rb <audio-file>")
+
+client = GroqRuby::Client.new
+
+response = File.open(audio_path, "rb") do |file|
+  client.audio.translations.create(
+    file: file,
+    filename: File.basename(audio_path),
+    model: "whisper-large-v3"
+  )
+end
+
+puts response.text

data/lib/groq_ruby/client.rb

@@ -0,0 +1,69 @@
+module GroqRuby
+  # User-facing entry point. Holds the immutable {Configuration} and a
+  # single {Transport} instance, and lazily constructs each resource on
+  # demand. Mirrors the layout of the python SDK's `Groq` class:
+  #
+  #   client.chat.completions.create(...)
+  #   client.embeddings.create(...)
+  #   client.audio.transcriptions.create(...)
+  #   client.models.list
+  #   client.files.create(...)
+  #   client.batches.create(...)
+  #
+  # @example Build from environment
+  #   client = GroqRuby::Client.new
+  #
+  # @example Explicit configuration
+  #   client = GroqRuby::Client.new(api_key: "gsk_…", base_url: "https://api.groq.com")
+  class Client
+    # @return [Configuration] the immutable configuration this client was built with
+    attr_reader :configuration
+
+    # @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
+    # @raise [ConfigurationError] if no api_key is found
+    def initialize(api_key: nil, base_url: nil, open_timeout: nil, read_timeout: nil, user_agent: nil)
+      @configuration = Configuration.from_env(
+        api_key: api_key,
+        base_url: base_url,
+        open_timeout: open_timeout,
+        read_timeout: read_timeout,
+        user_agent: user_agent
+      )
+      @transport = Transport.new(@configuration)
+    end
+
+    # @return [Resources::Chat] entry point for `client.chat.completions.create(...)`
+    def chat
+      @chat ||= Resources::Chat.new(@transport)
+    end
+
+    # @return [Resources::Embeddings] entry point for `client.embeddings.create(...)`
+    def embeddings
+      @embeddings ||= Resources::Embeddings.new(@transport)
+    end
+
+    # @return [Resources::Audio] entry point for `.speech`, `.transcriptions`, `.translations`
+    def audio
+      @audio ||= Resources::Audio.new(@transport)
+    end
+
+    # @return [Resources::Models] entry point for `.list`, `.retrieve`, `.delete`
+    def models
+      @models ||= Resources::Models.new(@transport)
+    end
+
+    # @return [Resources::Files] entry point for `.create`, `.list`, `.info`, `.content`, `.delete`
+    def files
+      @files ||= Resources::Files.new(@transport)
+    end
+
+    # @return [Resources::Batches] entry point for `.create`, `.retrieve`, `.list`, `.cancel`
+    def batches
+      @batches ||= Resources::Batches.new(@transport)
+    end
+  end
+end