ruby_llm-providers-groq 2.0.0.pre.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dc8fd696d7d3ef887cd311067e41bc36ac0c202c735a7a1b6eb674e395588bc1
+  data.tar.gz: 5be0aa59c8a2d164ec35b374947a8108440cbe37cd762987bb41d2af187cf040
+SHA512:
+  metadata.gz: 257873259aabd817b71f2d2f49f1c44c5fe0f10196c4e04c8a5f4ff13a0030d8388b8d38fb263c6a1bdedf1d1511956559b04096ccae548387d197f14e3cffda
+  data.tar.gz: 7428bbeeb1302be35d569074f6751971fa048038576d35ab8e80e94e7713bc3d53de4544dc076caa3076790df1b28bd60e9986bdf54c5fe96c4ffd777590476e

data/.flayignore

@@ -0,0 +1 @@
+spec/support/streaming_error_helpers.rb

data/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  pull_request:
+    branches: ["main"]
+  push:
+    branches: ["main", "wip"]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Ruby ${{ matrix.ruby-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ["3.3", "3.4", "4.0"]
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true
+
+      - run: bundle exec rake
+
+      - run: bundle exec rake rubocop flay spec

data/.github/workflows/gitleaks.yml

@@ -0,0 +1,22 @@
+name: Gitleaks
+
+on:
+  pull_request:
+    branches: ["main"]
+  push:
+    branches: ["main", "wip"]
+
+permissions:
+  contents: read
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

data/.github/workflows/release.yml

@@ -0,0 +1,36 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+
+      - run: bundle exec rake
+
+      - name: Build gem
+        run: gem build ruby_llm-providers-groq.gemspec
+
+      - name: Publish to RubyGems
+        run: |
+          mkdir -p "$HOME/.gem"
+          touch "$HOME/.gem/credentials"
+          chmod 0600 "$HOME/.gem/credentials"
+          printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > "$HOME/.gem/credentials"
+          gem push ruby_llm-providers-groq-*.gem
+        env:
+          GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_AUTH_TOKEN }}

data/.overcommit.yml

@@ -0,0 +1,31 @@
+PreCommit:
+  RuboCop:
+    enabled: true
+    auto_correct: true
+    on_warn: fail
+
+  Flay:
+    enabled: true
+    include:
+      - lib/**/*.rb
+      - spec/**/*.rb
+    mass_threshold: 70
+
+  ArchSpec:
+    enabled: true
+    command: ['bundle', 'exec', 'archspec', 'check']
+    on_warn: fail
+
+  RSpec:
+    enabled: true
+    command: ['bundle', 'exec', 'rspec']
+    on_warn: fail
+
+  TrailingWhitespace:
+    enabled: true
+    auto_correct: true
+
+  Gitleaks:
+    enabled: true
+    required_executable: gitleaks
+    command: ['gitleaks', 'protect', '--staged', '--redact', '--verbose']

data/.rspec

@@ -0,0 +1,2 @@
+--require spec_helper
+--format progress

data/.rubocop.yml

@@ -0,0 +1,29 @@
+plugins:
+  - rubocop-performance
+  - rubocop-rake
+  - rubocop-rspec
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.3
+  Exclude:
+    - Archspec.rb
+    - vendor/**/*
+    - gemfiles/**/*
+  SuggestExtensions: false
+
+Metrics/AbcSize:
+  Max: 80
+Metrics/MethodLength:
+  Max: 40
+  CountAsOne:
+    - array
+    - hash
+    - heredoc
+Metrics/BlockLength:
+  Exclude:
+    - spec/**/*.rb
+RSpec/ExampleLength:
+  Enabled: false
+RSpec/MultipleExpectations:
+  Enabled: false

data/Archspec.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+source 'lib/**/*.rb'
+
+component :provider,
+          in: %w[
+            lib/ruby_llm/providers/groq.rb
+            lib/ruby_llm/providers/groq/**/*.rb
+          ],
+          namespace: 'RubyLLM::Providers::Groq'
+
+provider.cannot_reference_constants 'RSpec', 'WebMock', 'VCR'
+
+preset :ruby_conventions

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 your-github-org
+
+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,57 @@
+# ruby_llm-providers-groq
+
+RubyLLM provider gem for [Groq](https://groq.com) support.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ruby_llm-providers-groq', require: 'ruby_llm/providers/groq'
+```
+
+Then configure the provider:
+
+```ruby
+require 'ruby_llm/providers/groq'
+
+RubyLLM.configure do |config|
+  config.groq_api_key = ENV['GROQ_API_KEY']
+end
+```
+
+## Usage
+
+An example of automatically picking the first chat-capable model:
+
+```ruby
+model = RubyLLM.models.by_provider(:groq).chat_models.first
+chat = RubyLLM.chat(provider: :groq, model: model.id)
+response = chat.ask('Hello')
+puts "The selected chat model '#{model.name}' replied:"
+puts response.content
+```
+
+When using Enterprise models, add an extra `assume_model_exists: true` argument (as they are for some reason not listed in the models registry):
+
+```ruby
+chat = RubyLLM.chat(provider: :groq, model: 'llama-3.3-70b-versatile',
+                    assume_model_exists: true)
+```
+
+## Development
+
+The generator installs the bundle and creates an ignored `.env`. Edit the generated `op read` reference so it points to your 1Password credential. If you do not use the 1Password CLI, replace the expression with the provider key.
+
+```sh
+bundle exec rake models
+bundle exec rake
+```
+
+`rake models` calls only Groq's model-listing endpoint and writes `models.json` at the gem root. RubyLLM loads that catalog as a fallback when this provider is registered, so applications do not need to combine registry files. The main RubyLLM registry always wins when both catalogs carry the same model. If the API uses a different path, change `models_url` in `lib/ruby_llm/providers/groq.rb`.
+
+Run `rake models` from this provider gem when you want to update its packaged catalog. `RubyLLM.models.refresh` updates the application's main registry and does not refresh provider gem catalogs.
+
+The suite always runs the provider integration specs. The first local run calls the API and records VCR cassettes; CI only replays committed cassettes. A failing example deletes its cassette so the next local run tests the live API again.
+
+After refreshing the catalog, add real model IDs to `spec/support/models.rb`. Keep only the operation matrices the provider supports. The portable contract specs are adapted from [RubyLLM's live specs](https://github.com/crmne/ruby_llm/tree/main/spec/ruby_llm); use those as the reference when your provider needs coverage for another feature or dialect.

data/lib/ruby_llm/providers/groq.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'ruby_llm'
+
+module RubyLLM
+  module Providers
+    # Groq API integration.
+    class Groq < Provider
+      # Groq's Responses protocol.
+      class Responses < Protocols::Responses
+        def models_url
+          'models'
+        end
+
+        # rubocop:disable-next Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity,Style/MultipleComparison
+        # replace 'output_text' with 'input_text'
+        def sanitize_input_types!(node)
+          case node
+          when Hash
+            node.each do |key, value|
+              if (key == :type || key == 'type') && (value == :output_text || value == 'output_text')
+                node[key] = value.is_a?(Symbol) ? :input_text : 'input_text'
+              else
+                sanitize_input_types!(value)
+              end
+            end
+          when Array
+            node.each { |element| sanitize_input_types!(element) }
+          end
+        end
+
+        # Groq does not support the 'include' field
+        def render_payload(...)
+          payload = super
+          sanitize_input_types!(payload[:input]) if payload[:input]
+          payload.delete(:include)
+          payload
+        end
+      end
+
+      protocol :responses, Responses
+
+      def api_base
+        @config.groq_api_base || 'https://api.groq.com/openai/v1'
+      end
+
+      def headers
+        { 'Authorization' => "Bearer #{@config.groq_api_key}" }
+      end
+
+      class << self
+        def configuration_options
+          %i[groq_api_key groq_api_base]
+        end
+
+        def configuration_requirements
+          %i[groq_api_key]
+        end
+
+        # Use this only when the provider has no model-listing endpoint.
+        # def assume_models_exist?
+        #   true
+        # end
+      end
+    end
+  end
+end
+
+RubyLLM::Provider.register :groq, RubyLLM::Providers::Groq,
+                           models: File.expand_path('../../../models.json', __dir__)

data/models.json

@@ -0,0 +1,218 @@
+[
+  {
+    "id": "meta-llama/llama-prompt-guard-2-22m",
+    "name": "meta-llama/llama-prompt-guard-2-22m",
+    "provider": "groq",
+    "family": null,
+    "created_at": "2025-05-30 19:08:21 UTC",
+    "context_window": 512,
+    "max_output_tokens": 512,
+    "knowledge_cutoff": null,
+    "modalities": {
+      "input": ["text"],
+      "output": ["moderation"]
+    },
+    "capabilities": [],
+    "pricing": {},
+    "metadata": {
+      "object": "model",
+      "owned_by": "Meta"
+    }
+  },
+  {
+    "id": "openai/gpt-oss-safeguard-20b",
+    "name": "openai/gpt-oss-safeguard-20b",
+    "provider": "groq",
+    "family": null,
+    "created_at": "2025-10-29 03:33:09 UTC",
+    "context_window": 131072,
+    "max_output_tokens": 65536,
+    "knowledge_cutoff": null,
+    "modalities": {
+      "input": ["text"],
+      "output": ["text"]
+    },
+    "capabilities": [
+      "reasoning"
+    ],
+    "pricing": {},
+    "metadata": {
+      "object": "model",
+      "owned_by": "OpenAI"
+    }
+  },
+  {
+    "id": "meta-llama/llama-prompt-guard-2-86m",
+    "name": "meta-llama/llama-prompt-guard-2-86m",
+    "provider": "groq",
+    "family": null,
+    "created_at": "2025-05-30 19:09:25 UTC",
+    "context_window": 512,
+    "max_output_tokens": 512,
+    "knowledge_cutoff": null,
+    "modalities": {
+      "input": ["text"],
+      "output": ["moderation"]
+    },
+    "capabilities": [],
+    "pricing": {},
+    "metadata": {
+      "object": "model",
+      "owned_by": "Meta"
+    }
+  },
+  {
+    "id": "canopylabs/orpheus-v1-english",
+    "name": "canopylabs/orpheus-v1-english",
+    "provider": "groq",
+    "family": null,
+    "created_at": "2025-12-19 23:18:36 UTC",
+    "context_window": 4000,
+    "max_output_tokens": 50000,
+    "knowledge_cutoff": null,
+    "modalities": {
+      "input": ["text"],
+      "output": ["audio"]
+    },
+    "capabilities": [
+      "speech_generation"
+    ],
+    "pricing": {},
+    "metadata": {
+      "object": "model",
+      "owned_by": "Canopy Labs"
+    }
+  },
+  {
+    "id": "whisper-large-v3",
+    "name": "whisper-large-v3",
+    "provider": "groq",
+    "family": null,
+    "created_at": "2023-09-03 06:14:58 UTC",
+    "context_window": null,
+    "max_output_tokens": null,
+    "knowledge_cutoff": null,
+    "modalities": {
+      "input": ["audio"],
+      "output": ["text"]
+    },
+    "capabilities": [],
+    "pricing": {},
+    "metadata": {
+      "object": "model",
+      "owned_by": "OpenAI"
+    }
+  },
+  {
+    "id": "qwen/qwen3.8-27b",
+    "name": "qwen/qwen3.8-27b",
+    "provider": "groq",
+    "family": null,
+    "created_at": "2026-08-17 16:40:46 UTC",
+    "context_window": 131072,
+    "max_output_tokens": 16384,
+    "knowledge_cutoff": null,
+    "modalities": {
+      "input": ["text", "image"],
+      "output": ["text"]
+    },
+    "capabilities": [
+      "reasoning",
+      "structured_output",
+      "vision"
+    ],
+    "pricing": {},
+    "metadata": {
+      "object": "model",
+      "owned_by": "Alibaba Cloud"
+    }
+  },
+  {
+    "id": "openai/gpt-oss-120b",
+    "name": "openai/gpt-oss-120b",
+    "provider": "groq",
+    "family": null,
+    "created_at": "2025-08-05 15:37:04 UTC",
+    "context_window": 131072,
+    "max_output_tokens": 65536,
+    "knowledge_cutoff": "2024-06-30",
+    "modalities": {
+      "input": ["text"],
+      "output": ["text"]
+    },
+    "capabilities": [
+      "reasoning",
+      "structured_output"
+    ],
+    "pricing": {},
+    "metadata": {
+      "object": "model",
+      "owned_by": "OpenAI"
+    }
+  },
+  {
+    "id": "openai/gpt-oss-20b",
+    "name": "openai/gpt-oss-20b",
+    "provider": "groq",
+    "family": null,
+    "created_at": "2025-08-05 15:32:37 UTC",
+    "context_window": 131072,
+    "max_output_tokens": 65536,
+    "knowledge_cutoff": "2024-06-30",
+    "modalities": {
+      "input": ["text"],
+      "output": ["text"]
+    },
+    "capabilities": [
+      "reasoning",
+      "structured_output"
+    ],
+    "pricing": {},
+    "metadata": {
+      "object": "model",
+      "owned_by": "OpenAI"
+    }
+  },
+  {
+    "id": "whisper-large-v3-turbo",
+    "name": "whisper-large-v3-turbo",
+    "provider": "groq",
+    "family": null,
+    "created_at": "2024-10-08 18:44:48 UTC",
+    "context_window": null,
+    "max_output_tokens": null,
+    "knowledge_cutoff": null,
+    "modalities": {
+      "input": ["audio"],
+      "output": ["text"]
+    },
+    "capabilities": [],
+    "pricing": {},
+    "metadata": {
+      "object": "model",
+      "owned_by": "OpenAI"
+    }
+  },
+  {
+    "id": "canopylabs/orpheus-arabic-saudi",
+    "name": "canopylabs/orpheus-arabic-saudi",
+    "provider": "groq",
+    "family": null,
+    "created_at": "2025-12-16 23:07:19 UTC",
+    "context_window": 4000,
+    "max_output_tokens": 50000,
+    "knowledge_cutoff": null,
+    "modalities": {
+      "input": ["text"],
+      "output": ["audio"]
+    },
+    "capabilities": [
+      "speech_generation"
+    ],
+    "pricing": {},
+    "metadata": {
+      "object": "model",
+      "owned_by": "Canopy Labs"
+    }
+  }
+]