groq_ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e37b875bee74a1cd5660dd886ae8aa670b964cd6f75822abf9d66c81060e6b81
+  data.tar.gz: a68e3933724ff8972efef22ab22ea3e5ceb1a657e29451008770c2f63f479068
+SHA512:
+  metadata.gz: a97a4e32dae7e9d313da6d6f4dd75e570218f55296e2daf06c071c11230e90e75832ec646f5e6e3f4cdb92e8eaa687235bd9541d20b2e96c7d3a10b6bf9bdea1
+  data.tar.gz: a83b33d635b1b06ff1e157a21d3c9c317ca4bbb0d0793eb575277f1cf1b6750f0fdb8e28540d8d961e123995a223e99d380d15020f3d33967ecdfa372cac9cfe

data/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. The
+format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0]
+
+Initial release. Idiomatic Ruby client for the Groq API, mirroring the
+surface of the [`groq-python`](https://github.com/groq/groq-python) SDK.
+
+### Added — Groq API
+
+- `GroqRuby::Client` exposes `chat`, `embeddings`, `audio`, `models`,
+  `files`, and `batches` resources.
+- Chat completions: buffered responses and Server-Sent-Events streaming
+  (block form or `Enumerable`-returning `ChunkStream`).
+- Function (tool) calling: pass `tools:` / `tool_choice:` directly to
+  `chat.completions.create`.
+- Embeddings: `client.embeddings.create(model:, input:)`.
+- Audio: `speech` (TTS, returns raw bytes), `transcriptions`, and
+  `translations` (multipart upload + Whisper).
+- Models: `list`, `retrieve`, `delete`.
+- Files lifecycle: `create`, `list`, `info`, `content` (binary), `delete`.
+- Batches: `create`, `retrieve`, `list`, `cancel`.
+
+### Added — MCP (Model Context Protocol)
+
+- `GroqRuby::MCP::Client` — stdio MCP client with `initialize`
+  handshake, `tools/list`, `tools/call`, `resources/list`,
+  `resources/read`, `prompts/list`, `prompts/get`, `supports?`.
+- `GroqRuby::MCP::Bridge` — wires one or more MCP servers into Groq's
+  `chat.completions(tools:)` parameter. Surfaces tools (namespaced
+  `<server>__<tool>`), resources (via a synthetic
+  `<server>__read_resource(uri)` tool), and prompts (`bridge.prompts`,
+  `bridge.get_prompt`). Optional capabilities are probed gracefully.
+- `GroqRuby::MCP::ClaudeDesktopConfig` — loads the same
+  `claude_desktop_config.json` shape (with `${VAR}` expansion against
+  per-server `env` block first, then process `ENV`) and returns
+  `Array<ServerConfig>`.
+
+### Added — infrastructure
+
+- Typed response models (`Data` definitions, frozen) with recursive
+  `from_hash` coercion for nested choices/messages/usage/etc.
+- Per-call parameter validation via `dry-schema` raising
+  `ParameterError` before any HTTP request fires.
+- Internal transport pipeline uses `dry-monads` `Result` + Do notation
+  for short-circuiting on transport failures, mapped to a typed
+  exception hierarchy at the public boundary
+  (`AuthenticationError`, `RateLimitError`, `BadRequestError`, etc.).
+- RBS signatures for the public API (`sig/groq_ruby.rbs`).
+- `examples/` directory with one runnable script per major endpoint
+  plus three MCP variants (minimal, annotated walkthrough, full
+  resources+prompts coverage).

data/CLAUDE.md

@@ -0,0 +1,103 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this gem is
+
+`groq_ruby` is an idiomatic Ruby client for the [Groq](https://groq.com)
+API. It mirrors the surface of the official `groq-python` SDK and is
+**not** an official Groq product — its wire protocol and resource
+layout come from the publicly available python SDK at
+<https://github.com/groq/groq-python>.
+
+The `README.md` is the user-facing documentation. This file documents
+the *internal* conventions and constraints — read it before changing
+architecture, dependencies, or naming.
+
+> Note: the parent directory `/Users/pablo/code/posiczko/CLAUDE.md`
+> documents a different project (Ougai). It does not apply here.
+
+## Architectural constraints
+
+These are deliberate, non-negotiable choices. Don't change them without
+explicit discussion:
+
+- **No global state, no `GroqRuby.configure`.** Configuration is
+  per-`Client` instance. Multi-tenant code holds multiple clients.
+  Constructor reads `GROQ_API_KEY` / `GROQ_BASE_URL` from env as a
+  default — that's it.
+- **`Net::HTTP` only.** No Faraday/HTTParty/http.rb dependency. Single
+  shared `GroqRuby::Transport` instance per client. Resources never
+  open their own sockets.
+- **Internal control flow uses `dry-monads` `Result` + Do notation**
+  inside `Transport`. The *public* API raises typed exceptions
+  (`AuthenticationError`, `RateLimitError`, ...) — `Resources::Base`
+  unwraps the `Failure` and re-raises so callers don't see Result.
+- **Per-call parameter validation via `dry-schema`** raises
+  `ParameterError` *before* any HTTP request fires. Schemas live next
+  to each resource (e.g. `Resources::Chat::Completions::SCHEMA`).
+- **Response models are frozen `Data` classes** under
+  `GroqRuby::Models::*`, each with a `from_hash` factory via the
+  `ModelFactory` mixin. Coerce nested types via `coerce :field, with:`.
+- **Single class per file** so Zeitwerk autoloads cleanly. The two
+  exceptions to "one constant per file" (the error families and the
+  per-domain model groups) live in collapsed sub-directories
+  (`lib/groq_ruby/errors/`, `lib/groq_ruby/models/<domain>/`); see the
+  `loader.collapse` calls in `lib/groq_ruby.rb`.
+- **No `require_relative` in `lib/`.** Zeitwerk autoloads everything.
+  The gemspec's `require_relative "lib/groq_ruby/version"` is the only
+  exception (gemspec runs before zeitwerk; zeitwerk's `for_gem`
+  ignores `version.rb` automatically).
+- **MCP integration is client-side orchestration**, not a Groq API
+  feature. The bridge speaks JSON-RPC 2.0 to MCP servers and converts
+  their tools to OpenAI-shaped function tools. Don't suggest adding a
+  request-side `mcp_servers:` parameter — Groq's API doesn't accept one.
+
+## Layout
+
+- `lib/groq_ruby.rb` — entry point: zeitwerk setup with inflections
+  (acronyms: `MCP`, `APIError` family) and collapsed sub-dirs.
+- `lib/groq_ruby/{client,configuration,transport,request,response,multipart,error_mapper,version}.rb` — top-level plumbing.
+- `lib/groq_ruby/errors/*.rb` — error classes (collapsed → `GroqRuby::*`).
+- `lib/groq_ruby/resources/{chat,audio}/*.rb` and `lib/groq_ruby/resources/*.rb` — one class per API surface.
+- `lib/groq_ruby/models/{chat,audio,embeddings,files,batches}/*.rb` — collapsed → `GroqRuby::Models::*`.
+- `lib/groq_ruby/streaming/*.rb` — SSE adapter (`event_stream_parser`) + `ChunkStream` enumerable.
+- `lib/groq_ruby/mcp/*.rb` — MCP client, bridge, transports, error families (collapsed). `MCP::PROTOCOL_VERSION` lives in `mcp.rb`.
+- `sig/groq_ruby.rbs` — public-API RBS sigs. Keep in sync when adding public API.
+- `test/**/test_*.rb` — Minitest. Real network calls are forbidden — every HTTP test stubs via WebMock; every MCP test uses `test/support/fake_mcp_transport.rb`.
+- `examples/*.rb` — runnable scripts. Each starts with `require "bundler/setup"; require "groq_ruby"`.
+
+## Commands
+
+- `bin/setup` — `bundle install` wrapper.
+- `bin/console` — IRB with the gem preloaded.
+- `bundle exec rake` — default: `test` + `lint` (rubocop+standard) + `types:validate` (RBS validate). All three must pass.
+- `bundle exec rake test` — Minitest suite.
+- `bundle exec rake test TESTOPTS="--name=/pattern/"` — subset.
+- `bundle exec rake lint` / `lint:all:autocorrect` — rubocop check / autofix.
+- `bundle exec rake types:validate` — `rbs validate` against `sig/`.
+- `bundle exec rake gem:build` / `install` / `release` — gem packaging (release is maintainer-only).
+
+## Conventions
+
+- Ruby 3.2+ (`.rubocop.yml` inherits from Standard; the gemspec pins `>= 3.2.0`).
+- Style is Standard via Rubocop. Run autocorrect before committing.
+- Prefer `git mv` when reorganising files so history is preserved.
+- Bump `GroqRuby::VERSION` in `lib/groq_ruby/version.rb` for releases; the gemspec reads it via `require_relative`.
+- Steep is intentionally **not** part of the default rake. Steep 2.0 crashes on `Data.define do ... end` blocks (upstream). RBS validate is enough for v1.
+- CI (`.github/workflows/main.yml`) currently has a placeholder branch (`.invalid`) and a non-existent Ruby version (`'4.0.3'`) in the matrix — pre-existing scaffolding issue, fix when wiring CI for real.
+
+## When extending the gem
+
+- New API endpoint → new `Resources::...` class (sub-class of
+  `Resources::Base`) + a `Models::...` Data class for the response.
+  Mirror the python SDK's parameter names verbatim.
+- New error condition → add a class under `lib/groq_ruby/errors/`
+  matching the file naming (one class per file). Update the README's
+  error-hierarchy table.
+- New MCP capability → add a `Client` method first, then expose via
+  `Bridge` if the LLM should be able to use it through chat
+  completions. Probe optional capabilities gracefully (catch
+  `JsonRpcError` / `-32601`).
+- New public method → add a YARD `@param`/`@return`/`@raise` and
+  update `sig/groq_ruby.rbs`.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pawel Osiczko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,495 @@
+# groq_ruby
+
+Idiomatic Ruby client for the [Groq](https://groq.com) API.
+
+`groq_ruby` mirrors the surface of the official
+[`groq-python`](https://github.com/groq/groq-python) SDK in a Ruby-native
+shape: typed response objects, single-purpose resource classes, internal
+`dry-monads` `Result` pipelines, and request validation via
+`dry-schema`. Streaming chat completions are supported via Server-Sent
+Events. A built-in [MCP](https://modelcontextprotocol.io) client lets you
+wire one or more MCP servers into a Groq chat completion as tools.
+
+This gem is **not** an official Groq product. The wire protocol it
+implements and the API surface it mirrors come from the publicly
+available `groq-python` SDK.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "groq_ruby"
+```
+
+```sh
+bundle install
+```
+
+## Quick start
+
+```ruby
+require "groq_ruby"
+
+client = GroqRuby::Client.new # reads GROQ_API_KEY from the environment
+
+response = client.chat.completions.create(
+  model: "llama-3.3-70b-versatile",
+  messages: [
+    {role: "system", content: "You are a helpful assistant."},
+    {role: "user", content: "Explain low-latency LLMs in one sentence."}
+  ]
+)
+
+puts response.choices.first.message.content
+puts "tokens: #{response.usage.total_tokens}"
+```
+
+## Configuration
+
+Configuration is per-client and immutable — no global state, no
+`GroqRuby.configure`. Build one client per tenant or set of credentials.
+
+```ruby
+client = GroqRuby::Client.new(
+  api_key: ENV["GROQ_API_KEY"],         # default: ENV["GROQ_API_KEY"]
+  base_url: "https://api.groq.com",     # default: ENV["GROQ_BASE_URL"] || "https://api.groq.com"
+  open_timeout: 10,                     # connect-phase timeout, seconds
+  read_timeout: 60,                     # socket-read timeout, seconds
+  user_agent: "myapp/1.0"               # default: "groq_ruby/<version> (ruby; net-http)"
+)
+```
+
+A `ConfigurationError` is raised at construction time if no API key can
+be found.
+
+## Chat completions
+
+### Buffered
+
+```ruby
+response = client.chat.completions.create(
+  model: "llama-3.3-70b-versatile",
+  messages: [{role: "user", content: "Hello"}],
+  temperature: 0.5,
+  max_completion_tokens: 256
+)
+response.choices.first.message.content
+response.usage.prompt_tokens
+```
+
+### Streaming
+
+Pass `stream: true`. With a block, each chunk is yielded as it arrives.
+Without a block, you get a lazy `Enumerable` you can iterate later.
+
+```ruby
+client.chat.completions.create(
+  model: "llama-3.3-70b-versatile",
+  messages: [{role: "user", content: "Write a poem about latency."}],
+  stream: true
+) do |chunk|
+  print chunk.choices.first.delta.content
+end
+
+# Or:
+stream = client.chat.completions.create(model: "...", messages: [...], stream: true)
+stream.each { |chunk| ... }
+```
+
+Validation rejects out-of-range values before any HTTP request fires:
+
+```ruby
+client.chat.completions.create(
+  model: "...", messages: [{role: "user", content: "x"}], temperature: 5.0
+)
+# => GroqRuby::ParameterError: invalid parameters: {:temperature=>["must be less than or equal to 2.0"]}
+```
+
+### Function (tool) calling
+
+Pass `tools:` (and optionally `tool_choice:`) just like the OpenAI/Groq
+schema — `groq_ruby` doesn't transform them. When the model decides to
+call a tool, it comes back in `response.choices.first.message.tool_calls`.
+
+```ruby
+tools = [
+  {
+    type: "function",
+    function: {
+      name: "get_weather",
+      description: "Look up the current weather for a city",
+      parameters: {
+        type: "object",
+        properties: {city: {type: "string"}},
+        required: ["city"]
+      }
+    }
+  }
+]
+
+response = client.chat.completions.create(
+  model: "llama-3.3-70b-versatile",
+  messages: [{role: "user", content: "What's the weather in Berlin?"}],
+  tools: tools,
+  tool_choice: "auto"   # "auto" | "required" | "none" | {type: "function", function: {name: "get_weather"}}
+)
+
+call = response.choices.first.message.tool_calls&.first
+if call
+  args = JSON.parse(call["function"]["arguments"])
+  result = get_weather(args["city"])
+
+  # Feed the result back as a follow-up turn:
+  followup = client.chat.completions.create(
+    model: "llama-3.3-70b-versatile",
+    messages: [
+      *original_messages,
+      {role: "assistant", content: nil, tool_calls: response.choices.first.message.tool_calls},
+      {role: "tool", tool_call_id: call["id"], content: JSON.generate(result)}
+    ]
+  )
+end
+```
+
+For an MCP-driven version of this loop (where the tools come from an
+MCP server instead of being hand-defined), see the [MCP section below](#mcp--model-context-protocol).
+
+## Embeddings
+
+```ruby
+response = client.embeddings.create(
+  model: "nomic-embed-text-v1_5",
+  input: "Groq makes inference very fast."
+)
+vector = response.data.first.embedding
+```
+
+## Audio
+
+### Text → speech
+
+```ruby
+audio_bytes = client.audio.speech.create(
+  input: "Hello from Groq.",
+  model: "playai-tts",
+  voice: "Aaliyah-PlayAI",
+  response_format: "wav"
+)
+File.binwrite("speech.wav", audio_bytes)
+```
+
+### Speech → text (transcription)
+
+```ruby
+response = File.open("audio.mp3", "rb") do |file|
+  client.audio.transcriptions.create(
+    file: file,
+    filename: "audio.mp3",
+    model: "whisper-large-v3-turbo"
+  )
+end
+puts response.text
+```
+
+### Speech → English text (translation)
+
+```ruby
+response = File.open("audio.mp3", "rb") do |file|
+  client.audio.translations.create(
+    file: file,
+    filename: "audio.mp3",
+    model: "whisper-large-v3"
+  )
+end
+```
+
+## Models
+
+```ruby
+client.models.list.data.each { |m| puts m.id }
+client.models.retrieve("llama-3.3-70b-versatile")
+client.models.delete("custom-model-id")
+```
+
+## Files
+
+```ruby
+uploaded = File.open("requests.jsonl", "rb") do |file|
+  client.files.create(file: file, filename: "requests.jsonl", purpose: "batch")
+end
+
+client.files.list.data
+client.files.info(uploaded.id)
+client.files.content(uploaded.id) # raw bytes
+client.files.delete(uploaded.id)
+```
+
+## Batches
+
+```ruby
+batch = client.batches.create(
+  input_file_id: uploaded.id,
+  endpoint: "/v1/chat/completions",
+  completion_window: "24h"
+)
+
+client.batches.retrieve(batch.id)
+client.batches.list
+client.batches.cancel(batch.id)
+```
+
+## MCP — Model Context Protocol
+
+`groq_ruby` ships with a stdio MCP client, so a Groq agent can use tools
+exposed by any MCP-compatible server (filesystem, web, custom tooling).
+Coverage matches what host applications like Claude Desktop surface:
+
+| MCP capability          | Coverage                                                                                                                                                                             |
+|-------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **Tools**               | Surfaced as Groq function tools, namespaced `<server>__<tool>`                                                                                                                       |
+| **Resources**           | Surfaced via a synthetic `<server>__read_resource(uri)` tool the LLM can call. `bridge.resources` returns the inventory if you want to advertise specific URIs in your system prompt |
+| **Prompts**             | Listed via `bridge.prompts` for *your application* to surface (e.g. as a picker in your UI) and rendered via `bridge.get_prompt(name, args)`                                         |
+| Sampling, notifications | Not supported in v1                                                                                                                                                                  |
+
+Optional capabilities are probed gracefully — if a server doesn't
+implement `resources/list` or `prompts/list`, those entries are simply
+empty for that server.
+
+### Configuring servers
+
+Build `ServerConfig` directly, or load from the same JSON shape Claude
+Desktop uses (`mcpServers` block). The Claude Desktop adapter expands
+`${VAR}` references against each server's `env` block first, then the
+process's `ENV`, and raises on unresolved references.
+
+```ruby
+# (a) direct
+config = GroqRuby::MCP::ServerConfig.new(
+  name: "fs",
+  command: "npx",
+  args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/docs"]
+)
+
+# (b) load Claude Desktop JSON
+configs = GroqRuby::MCP::ClaudeDesktopConfig.load(
+  "~/Library/Application Support/Claude/claude_desktop_config.json"
+)
+bridge = GroqRuby::MCP::Bridge.new(configs)
+
+# (c) parse an in-memory hash (e.g. for a private server with a PAT)
+configs = GroqRuby::MCP::ClaudeDesktopConfig.parse({
+  "mcpServers" => {
+    "spectrum-ferret-staging" => {
+      "command" => "npx",
+      "args" => [
+        "-y", "mcp-remote@latest", "https://mcp-staging.spectrumferret.com",
+        "--header", "Authorization: Bearer ${SF_PAT}"
+      ],
+      "env" => {"SF_PAT" => ENV.fetch("SF_PAT")}
+    }
+  }
+})
+```
+
+### Direct usage
+
+```ruby
+config = GroqRuby::MCP::ServerConfig.new(
+  name: "fs",
+  command: "npx",
+  args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/docs"]
+)
+
+mcp = GroqRuby::MCP::Client.connect(config)
+mcp.tools_list                                # [Tool(name: "read_file", ...), ...]
+mcp.tools_call(name: "read_file", arguments: {path: "/Users/me/docs/foo.txt"})
+mcp.resources_list                            # [Resource(uri: "fs://...", ...)]
+mcp.resources_read("fs://docs/foo.md")
+mcp.prompts_list                              # [Prompt(name: "summarize", ...)]
+mcp.prompts_get("summarize", {path: "foo.md"})
+mcp.stop
+```
+
+### Bridge into chat.completions
+
+> **Important:** Groq's chat-completions API does not have a request
+> parameter for "MCP server URL." MCP integration here is **client-side
+> orchestration**: this gem talks to the MCP servers, exposes their tools
+> as ordinary OpenAI/Groq function tools through the standard `tools:`
+> parameter, then routes the model's `tool_calls` back to the right
+> server. From Groq's perspective there is no MCP — just function tools.
+
+`Bridge` does three things at construction:
+
+1. spawns each `ServerConfig`'s child process via stdio,
+2. runs the MCP `initialize` handshake and asks each server for its tool list,
+3. indexes those tools by namespaced name `<server>__<tool>` so collisions across servers are impossible.
+
+`bridge.tools` then returns an array shaped exactly like Groq's
+`tools:` parameter:
+
+```ruby
+bridge.tools
+# => [
+#   {
+#     type: "function",
+#     function: {
+#       name: "fs__read_file",
+#       description: "Read the contents of a file at the given path",
+#       parameters: {           # JSON Schema, straight from the MCP server
+#         "type" => "object",
+#         "properties" => { "path" => { "type" => "string" } },
+#         "required" => ["path"]
+#       }
+#     }
+#   },
+#   ...
+# ]
+```
+
+A complete agent loop using a real MCP server (`@modelcontextprotocol/server-filesystem`):
+
+```ruby
+require "groq_ruby"
+require "json"
+
+filesystem = GroqRuby::MCP::ServerConfig.new(
+  name: "fs",
+  command: "npx",
+  args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/docs"]
+)
+
+bridge = GroqRuby::MCP::Bridge.new([filesystem])
+groq = GroqRuby::Client.new
+
+messages = [
+  {role: "system", content: "You can use filesystem tools. Prefer tools over speculation."},
+  {role: "user", content: "Summarise README.md."}
+]
+
+begin
+  loop do
+    response = groq.chat.completions.create(
+      model: "llama-3.3-70b-versatile",
+      messages: messages,
+      tools: bridge.tools          # <-- MCP tools surfaced as Groq function 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|
+      fn = call["function"]
+      # bridge.call accepts either a Hash or the raw JSON string Groq
+      # returns in `function.arguments` — it routes to the owning server.
+      result = bridge.call(fn["name"], fn["arguments"])
+      messages << {role: "tool", tool_call_id: call["id"], content: JSON.generate(result)}
+    end
+  end
+ensure
+  bridge.stop                       # kills child processes, closes stdio
+end
+```
+
+Runnable variants in `examples/`:
+- [`examples/mcp_agent.rb`](examples/mcp_agent.rb) — minimal version of the loop above.
+- [`examples/mcp_chat_with_tools.rb`](examples/mcp_chat_with_tools.rb) — same loop, heavily annotated step by step.
+- [`examples/mcp_resources_and_prompts.rb`](examples/mcp_resources_and_prompts.rb) — adds resources (catalogued in the system prompt + fetched via the synthetic `read_resource` tool) and prompts.
+
+## Error handling
+
+Every API failure raises a subclass of `GroqRuby::APIError`. Rescue the
+base class to handle anything; rescue specific subclasses to react to
+particular conditions.
+
+```ruby
+begin
+  client.chat.completions.create(...)
+rescue GroqRuby::AuthenticationError => e
+  warn "auth failed: #{e.message}"
+rescue GroqRuby::RateLimitError => e
+  warn "rate limited; retry after backoff"
+rescue GroqRuby::APIStatusError => e
+  warn "status #{e.status}: #{e.message}"
+rescue GroqRuby::APIConnectionError => e
+  warn "network: #{e.message}"
+end
+```
+
+Hierarchy:
+
+| Class                                | When                                                   |
+|--------------------------------------|--------------------------------------------------------|
+| `GroqRuby::Error`                    | Base for everything in the gem                         |
+| `GroqRuby::ConfigurationError`       | Missing or invalid configuration                       |
+| `GroqRuby::ParameterError`           | Request params failed validation                       |
+| `GroqRuby::APIError`                 | Base for any failure talking to the API                |
+| `GroqRuby::APIConnectionError`       | Network failure before a response                      |
+| `GroqRuby::APITimeoutError`          | Connection or read timeout                             |
+| `GroqRuby::APIStatusError`           | 4xx/5xx response (carries `status`, `headers`, `body`) |
+| `GroqRuby::BadRequestError`          | 400                                                    |
+| `GroqRuby::AuthenticationError`      | 401                                                    |
+| `GroqRuby::PermissionDeniedError`    | 403                                                    |
+| `GroqRuby::NotFoundError`            | 404                                                    |
+| `GroqRuby::ConflictError`            | 409                                                    |
+| `GroqRuby::UnprocessableEntityError` | 422                                                    |
+| `GroqRuby::RateLimitError`           | 429                                                    |
+| `GroqRuby::InternalServerError`      | 5xx                                                    |
+| `GroqRuby::APIResponseError`         | API returned an unexpected payload                     |
+| `GroqRuby::MCP::Error`               | Base for any MCP-layer failure                         |
+| `GroqRuby::MCP::TransportError`      | Stdio pipe broke or process exited                     |
+| `GroqRuby::MCP::TimeoutError`        | MCP request timed out                                  |
+| `GroqRuby::MCP::ProtocolError`       | Server sent malformed JSON-RPC                         |
+| `GroqRuby::MCP::JsonRpcError`        | Server returned a JSON-RPC `error`                     |
+| `GroqRuby::MCP::UnknownToolError`    | `Bridge#call` couldn't find the tool                   |
+
+## Examples
+
+The [`examples/`](examples) directory has one runnable script per major
+endpoint, plus the MCP agent loop. Each reads `GROQ_API_KEY` from the
+environment. See [`examples/README.md`](examples/README.md) for the full
+list.
+
+## Compatibility
+
+- Ruby 3.2+
+- Net::HTTP (no Faraday/HTTParty dependency)
+
+### Not yet supported
+
+The python SDK has a few features that aren't in `groq_ruby` v1:
+
+- Async client (everything here is synchronous; use threads/fibers if you need concurrency).
+- `with_raw_response` / `with_streaming_response` accessors (responses are always parsed into typed models).
+- Built-in retries / backoff (handle in your own caller).
+- MCP sampling and `notifications/list_changed` (resource and prompt inventories are snapshotted at `Bridge` construction).
+
+## Development
+
+```sh
+bin/setup                              # install deps
+bundle exec rake                       # tests + lint + RBS validate
+bundle exec rake test                  # tests only
+bundle exec rake test TESTOPTS="--name=/pattern/"   # subset
+bin/console                            # IRB with the gem preloaded
+```
+
+Tests use Minitest + WebMock; no test makes real network calls.
+
+## Attribution
+
+The API surface, parameter names, and resource layout follow the
+official Groq Python SDK at
+<https://github.com/groq/groq-python>, distributed under the Apache 2.0
+licence. This gem is an independent Ruby implementation and is not
+affiliated with or endorsed by Groq.
+
+## License
+
+MIT — see [`LICENSE.txt`](LICENSE.txt).