feat(provider): add Groq provider (#33)

*add groq provider

Author: agpituk

CLAUDE.md

@@ -83,21 +83,28 @@ Providers implement `ErrorConverter` using `errors.As` with SDK typed errors (no
 ### Key Patterns
 
 - **Configuration**: Functional options with validation
-- **Constants**: Extract ALL magic strings to named constants (including response format types like `json_object`)
+- **Constants**: Extract ALL magic strings to named constants (including response format types like `json_object`). Constants belong in production code files, not test files
 - **Streaming**: Break monolithic handlers into focused methods (see `anthropic/anthropic.go`)
 - **Streaming Safety**: Always use `select` with `ctx.Done()` when sending to channels in goroutines to prevent blocking forever if consumer abandons
 - **ID Generation**: Use `crypto/rand`, not package-level mutable state
 - **Error Conversion**: Use `errors.As` with SDK typed errors; avoid string matching when possible
 - **Input Validation**: Validate required fields (Model non-empty, Messages has entries) before API calls
 - **Unknown Values**: Never silently convert unknown enum values (e.g., unknown role → user); error or log warning instead
 - **Struct Field Order**: Order struct fields A-Z (don't optimize for padding)
+- **Slice Cloning**: Prefer `slices.Clone` over manual `make` + `copy`
+- **Slice Capacity**: Use `make([]T, 0, len(source))` when building slices from known-size sources
+- **ContentString()**: Use `msg.ContentString()` instead of `msg.Content.(string)` type assertions
+- **Switch Completeness**: Switch statements should have a `default` case (error or explicit fallback)
+- **Variable Naming**: Don't shadow imported package names (e.g., use `imgURL` not `url` when `net/url` is imported)
+- **Error Messages**: Don't double-print provider name when the base error already includes it
 
 ### OpenAI-Compatible Providers
 
 For providers that expose OpenAI-compatible APIs but don't have their own Go SDK (Llamafile, vLLM, LM Studio, etc.):
 - Use the compatible provider in `providers/openai/compatible.go`
 - Import: `"github.com/mozilla-ai/any-llm-go/providers/openai"`
 - Create thin wrapper that calls `openai.NewCompatible()` with provider-specific `CompatibleConfig`
+- Set ALL `CompatibleConfig` fields explicitly, including empty values (e.g., `BaseURLEnvVar: ""`, `DefaultAPIKey: ""`)
 - Add interface assertions in the wrapper package
 
 ### Testing
@@ -110,6 +117,8 @@ For providers that expose OpenAI-compatible APIs but don't have their own Go SDK
 - Skip integration tests gracefully when provider unavailable
 - Use constants (e.g., `objectChatCompletion`) instead of string literals in test assertions
 - Base packages need their own test suites, not just wrapper tests
+- No redundant assertions (e.g., `require.NotEmpty` already checks len > 0, don't follow with `require.Greater`)
+- Add a comment when intentionally discarding return values (e.g., `_, _ = fn()`)
 
 ## Adding a New Provider
 

README.md

@@ -281,6 +281,7 @@ for _, model := range models.Data {
 | Anthropic  |      ✅      |      ✅      |      ✅ |      ✅      |      ❌       |
 |  DeepSeek  |      ✅      |      ✅      |      ✅ |      ✅      |      ❌       |
 |   Gemini   |      ✅      |      ✅      |      ✅ |      ✅      |      ✅       |
+|    Groq    |      ✅      |      ✅      |      ✅ |      ❌      |      ❌       |
 | Llamafile  |      ✅      |      ✅      |      ✅ |      ❌      |      ✅       |
 |  Mistral   |      ✅      |      ✅      |      ✅ |      ✅      |      ✅       |
 |   Ollama   |      ✅      |      ✅      |      ✅ |      ✅      |      ✅       |

docs/providers.md

@@ -9,6 +9,7 @@ any-llm-go supports multiple LLM providers through a unified interface. Each pro
 | [Anthropic](#anthropic) | `anthropic` |     ✅      |     ✅     |   ✅   |     ✅     |     ❌      |      ❌      |
 | [DeepSeek](#deepseek)   | `deepseek`  |     ✅      |     ✅     |   ✅   |     ✅     |     ❌      |      ✅      |
 | [Gemini](#gemini)       | `gemini`    |     ✅      |     ✅     |   ✅   |     ✅     |     ✅      |      ✅      |
+| [Groq](#groq)           | `groq`      |     ✅      |     ✅     |   ✅   |     ❌     |     ❌      |      ✅      |
 | [Llamafile](#llamafile) | `llamafile` |     ✅      |     ✅     |   ✅   |     ❌     |     ✅      |      ✅      |
 | [Mistral](#mistral)     | `mistral`   |     ✅      |     ✅     |   ✅   |     ✅     |     ✅      |      ✅      |
 | [Ollama](#ollama)       | `ollama`    |     ✅      |     ✅     |   ✅   |     ✅     |     ✅      |      ✅      |
@@ -148,6 +149,42 @@ if response.Choices[0].Message.Reasoning != nil {
 }
 ```
 
+### Groq
+
+Groq provides fast inference through their cloud API. It exposes an OpenAI-compatible API.
+
+```go
+import (
+    anyllm "github.com/mozilla-ai/any-llm-go"
+    "github.com/mozilla-ai/any-llm-go/providers/groq"
+)
+
+// Using environment variable (GROQ_API_KEY).
+provider, err := groq.New()
+
+// Or with explicit API key.
+provider, err := groq.New(anyllm.WithAPIKey("gsk_..."))
+```
+
+**Environment Variable:** `GROQ_API_KEY`
+
+**Popular Models:**
+- `llama-3.1-8b-instant` - Fast and cost-effective
+- `llama-3.3-70b-versatile` - More capable model
+- `mixtral-8x7b-32768` - Mixtral with 32k context
+
+**Completion:**
+
+```go
+provider, _ := groq.New()
+resp, err := provider.Completion(ctx, anyllm.CompletionParams{
+    Model: "llama-3.1-8b-instant",
+    Messages: []anyllm.Message{
+        {Role: anyllm.RoleUser, Content: "Hello!"},
+    },
+})
+```
+
 ### Mistral
 
 ```go
@@ -369,7 +406,6 @@ The following providers are planned for future releases:
 
 | Provider     | Status                                            |
 |--------------|---------------------------------------------------|
-| Groq         | Planned                                           |
 | Cohere       | Planned                                           |
 | Together AI  | Planned                                           |
 | AWS Bedrock  | Planned                                           |

internal/testutil/fixtures.go

@@ -18,7 +18,7 @@ var ProviderModelMap = map[string]string{
 	"mistral":    "mistral-small-latest",
 	"gemini":     "gemini-2.5-flash",
 	"cohere":     "command-r",
-	"groq":       "llama-3.1-8b-instant",
+	"groq":       "llama-3.3-70b-versatile",
 	"ollama":     "llama3.2",
 	"llamafile":  "LLaMA_CPP",
 	"together":   "meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo",

providers/groq/groq.go

@@ -0,0 +1,68 @@
+// Package groq provides a Groq provider implementation for any-llm.
+// Groq exposes an OpenAI-compatible API optimized for fast inference.
+package groq
+
+import (
+	"github.com/mozilla-ai/any-llm-go/config"
+	"github.com/mozilla-ai/any-llm-go/providers"
+	"github.com/mozilla-ai/any-llm-go/providers/openai"
+)
+
+// Provider configuration constants.
+const (
+	defaultBaseURL = "https://api.groq.com/openai/v1"
+	envAPIKey      = "GROQ_API_KEY"
+	providerName   = "groq"
+)
+
+// Object type constants for API responses.
+const (
+	objectChatCompletion      = "chat.completion"
+	objectChatCompletionChunk = "chat.completion.chunk"
+	objectList                = "list"
+)
+
+// Ensure Provider implements the required interfaces.
+var (
+	_ providers.CapabilityProvider = (*Provider)(nil)
+	_ providers.ErrorConverter     = (*Provider)(nil)
+	_ providers.ModelLister        = (*Provider)(nil)
+	_ providers.Provider           = (*Provider)(nil)
+)
+
+// Provider implements the providers.Provider interface for Groq.
+// It embeds openai.CompatibleProvider since Groq exposes an OpenAI-compatible API.
+type Provider struct {
+	*openai.CompatibleProvider
+}
+
+// New creates a new Groq provider.
+func New(opts ...config.Option) (*Provider, error) {
+	base, err := openai.NewCompatible(openai.CompatibleConfig{
+		APIKeyEnvVar:   envAPIKey,
+		BaseURLEnvVar:  "",
+		Capabilities:   groqCapabilities(),
+		DefaultAPIKey:  "",
+		DefaultBaseURL: defaultBaseURL,
+		Name:           providerName,
+		RequireAPIKey:  true,
+	}, opts...)
+	if err != nil {
+		return nil, err
+	}
+
+	return &Provider{CompatibleProvider: base}, nil
+}
+
+// groqCapabilities returns the capabilities for the Groq provider.
+func groqCapabilities() providers.Capabilities {
+	return providers.Capabilities{
+		Completion:          true,
+		CompletionImage:     false, // Groq doesn't support image inputs.
+		CompletionPDF:       false,
+		CompletionReasoning: false, // Groq doesn't support reasoning parameters.
+		CompletionStreaming: true,
+		Embedding:           false, // Groq doesn't host embedding models.
+		ListModels:          true,
+	}
+}