feat(provider): add Llamafile provider and OpenAI-compatible base package (#20)

* test: add Llamafile model mappings to test fixtures

* feat: add OpenAI-compatible base provider package

Adds a reusable base provider for services that expose OpenAI-compatible
APIs but don't have their own Go SDK. This reduces code duplication for
providers like Llamafile, vLLM, LM Studio, etc.

* feat: add Llamafile provider implementation

Llamafile is a single-file executable that bundles a model with llama.cpp,
exposing an OpenAI-compatible API. This provider uses the openaicompat
base package since Llamafile doesn't have its own Go SDK.

* test: add Llamafile provider tests

* docs: add Llamafile to supported providers documentation

* docs: update CLAUDE.md with PR feedback patterns

Author: agpituk

CLAUDE.md

@@ -83,10 +83,22 @@ 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
+- **Constants**: Extract ALL magic strings to named constants (including response format types like `json_object`)
 - **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
+- **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)
+
+### 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`
+- Add interface assertions in the wrapper package
 
 ### Testing
 
@@ -96,6 +108,8 @@ Providers implement `ErrorConverter` using `errors.As` with SDK typed errors (no
 - Name test case variable `tc`, not `tt`
 - Name helpers/mocks with `test`, `mock`, `fake` to distinguish from production code
 - 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
 
 ## Adding a New Provider
 

config/config.go

@@ -169,3 +169,41 @@ func (c *Config) ResolveAPIKey(envVar string) string {
 
 	return os.Getenv(envVar)
 }
+
+// ResolveEnv returns the value of the specified environment variable,
+// trimming whitespace. Returns empty string if the variable is not set or empty.
+func (c *Config) ResolveEnv(envVar string) string {
+	if envVar == "" {
+		return ""
+	}
+	return strings.TrimSpace(os.Getenv(envVar))
+}
+
+// ResolveBaseURL resolves the base URL from config, environment variable, or default value.
+// It validates that the resolved URL has a scheme and host.
+func (c *Config) ResolveBaseURL(envVar, defaultVal string) (string, error) {
+	baseURL := c.BaseURL
+	if baseURL == "" {
+		baseURL = c.ResolveEnv(envVar)
+	}
+	if baseURL == "" {
+		baseURL = defaultVal
+	}
+
+	if baseURL == "" {
+		return "", nil
+	}
+
+	baseURL = strings.TrimSpace(baseURL)
+
+	parsed, err := url.Parse(baseURL)
+	if err != nil {
+		return "", fmt.Errorf("invalid base URL %q: %w", baseURL, err)
+	}
+
+	if parsed.Scheme == "" || parsed.Host == "" {
+		return "", fmt.Errorf("base URL %q must have scheme and host", baseURL)
+	}
+
+	return baseURL, nil
+}

config/config_test.go

@@ -479,6 +479,87 @@ func TestResolveAPIKey(t *testing.T) {
 	}
 }
 
+func TestResolveEnv(t *testing.T) {
+	// Note: Cannot use t.Parallel() with t.Setenv().
+
+	t.Run("returns trimmed env value", func(t *testing.T) {
+		t.Setenv("TEST_RESOLVE_ENV", "  some-value  ")
+
+		cfg := &Config{}
+		result := cfg.ResolveEnv("TEST_RESOLVE_ENV")
+		require.Equal(t, "some-value", result)
+	})
+
+	t.Run("returns empty for unset variable", func(t *testing.T) {
+		cfg := &Config{}
+		result := cfg.ResolveEnv("TEST_RESOLVE_ENV_UNSET")
+		require.Empty(t, result)
+	})
+
+	t.Run("returns empty for empty env var name", func(t *testing.T) {
+		cfg := &Config{}
+		result := cfg.ResolveEnv("")
+		require.Empty(t, result)
+	})
+}
+
+func TestResolveBaseURL(t *testing.T) {
+	// Note: Cannot use t.Parallel() with t.Setenv().
+
+	t.Run("uses config BaseURL first", func(t *testing.T) {
+		cfg := &Config{BaseURL: "https://config.example.com/v1"}
+		result, err := cfg.ResolveBaseURL("", "https://default.example.com/v1")
+		require.NoError(t, err)
+		require.Equal(t, "https://config.example.com/v1", result)
+	})
+
+	t.Run("falls back to env var", func(t *testing.T) {
+		t.Setenv("TEST_BASE_URL_RESOLVE", "https://env.example.com/v1")
+
+		cfg := &Config{}
+		result, err := cfg.ResolveBaseURL("TEST_BASE_URL_RESOLVE", "https://default.example.com/v1")
+		require.NoError(t, err)
+		require.Equal(t, "https://env.example.com/v1", result)
+	})
+
+	t.Run("falls back to default", func(t *testing.T) {
+		cfg := &Config{}
+		result, err := cfg.ResolveBaseURL("", "https://default.example.com/v1")
+		require.NoError(t, err)
+		require.Equal(t, "https://default.example.com/v1", result)
+	})
+
+	t.Run("returns empty when all empty", func(t *testing.T) {
+		cfg := &Config{}
+		result, err := cfg.ResolveBaseURL("", "")
+		require.NoError(t, err)
+		require.Empty(t, result)
+	})
+
+	t.Run("returns error for invalid URL", func(t *testing.T) {
+		cfg := &Config{BaseURL: "://bad-url"}
+		_, err := cfg.ResolveBaseURL("", "")
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "invalid base URL")
+	})
+
+	t.Run("returns error for URL without scheme", func(t *testing.T) {
+		cfg := &Config{BaseURL: "example.com/v1"}
+		_, err := cfg.ResolveBaseURL("", "")
+		require.Error(t, err)
+		require.Contains(t, err.Error(), "must have scheme and host")
+	})
+
+	t.Run("trims whitespace from resolved URL", func(t *testing.T) {
+		t.Setenv("TEST_BASE_URL_WS", "  https://env.example.com/v1  ")
+
+		cfg := &Config{}
+		result, err := cfg.ResolveBaseURL("TEST_BASE_URL_WS", "")
+		require.NoError(t, err)
+		require.Equal(t, "https://env.example.com/v1", result)
+	})
+}
+
 func TestHTTPClientCaching(t *testing.T) {
 	t.Parallel()
 

docs/providers.md

@@ -9,6 +9,7 @@ any-llm-go supports multiple LLM providers through a unified interface. Each pro
 | [OpenAI](#openai) | `openai` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | [Anthropic](#anthropic) | `anthropic` | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
 | [Ollama](#ollama) | `ollama` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| [Llamafile](#llamafile) | `llamafile` | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ |
 
 ### Legend
 
@@ -156,6 +157,75 @@ for _, model := range models.Data {
 }
 ```
 
+### Llamafile
+
+Llamafile is a single-file executable that bundles a model with llama.cpp for easy local deployment. It exposes an OpenAI-compatible API. No API key is required.
+
+```go
+import (
+    anyllm "github.com/mozilla-ai/any-llm-go"
+    "github.com/mozilla-ai/any-llm-go/providers/llamafile"
+)
+
+// Using default settings (localhost:8080/v1).
+provider, err := llamafile.New()
+
+// Or with custom base URL.
+provider, err := llamafile.New(anyllm.WithBaseURL("http://localhost:8081/v1"))
+```
+
+**Environment Variable:** `LLAMAFILE_BASE_URL` (optional, defaults to `http://localhost:8080/v1`)
+
+**Running Llamafile:**
+
+Download a llamafile from [Mozilla-Ocho/llamafile](https://github.com/Mozilla-Ocho/llamafile) and run it:
+
+```bash
+# Download a llamafile (example: LLaVA)
+curl -LO https://huggingface.co/Mozilla/llava-v1.5-7b-llamafile/resolve/main/llava-v1.5-7b-q4.llamafile
+chmod +x llava-v1.5-7b-q4.llamafile
+./llava-v1.5-7b-q4.llamafile --server
+```
+
+**Completion:**
+
+```go
+provider, _ := llamafile.New()
+resp, err := provider.Completion(ctx, anyllm.CompletionParams{
+    Model: "LLaMA_CPP", // Llamafile uses "LLaMA_CPP" as the model name.
+    Messages: []anyllm.Message{
+        {Role: anyllm.RoleUser, Content: "Hello!"},
+    },
+})
+```
+
+**Streaming:**
+
+```go
+provider, _ := llamafile.New()
+chunks, errs := provider.CompletionStream(ctx, anyllm.CompletionParams{
+    Model: "LLaMA_CPP",
+    Messages: messages,
+})
+
+for chunk := range chunks {
+    fmt.Print(chunk.Choices[0].Delta.Content)
+}
+if err := <-errs; err != nil {
+    log.Fatal(err)
+}
+```
+
+**List Models:**
+
+```go
+provider, _ := llamafile.New()
+models, err := provider.ListModels(ctx)
+for _, model := range models.Data {
+    fmt.Println(model.ID) // Typically "LLaMA_CPP"
+}
+```
+
 ## Coming Soon
 
 The following providers are planned for future releases:
@@ -168,7 +238,6 @@ The following providers are planned for future releases:
 | Cohere | Planned |
 | Together AI | Planned |
 | AWS Bedrock | Planned |
-| Llamafile | Planned |
 | Azure OpenAI | Planned (use OpenAI with custom base URL for now) |
 
 ## Adding a New Provider

internal/testutil/fixtures.go

@@ -18,6 +18,7 @@ var ProviderModelMap = map[string]string{
 	"cohere":     "command-r",
 	"groq":       "llama-3.1-8b-instant",
 	"ollama":     "llama3.2",
+	"llamafile":  "LLaMA_CPP",
 	"together":   "meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo",
 	"perplexity": "llama-3.1-sonar-small-128k-online",
 	"deepseek":   "deepseek-chat",
@@ -46,11 +47,12 @@ var ProviderImageModelMap = map[string]string{
 
 // EmbeddingProviderModelMap maps providers to embedding models.
 var EmbeddingProviderModelMap = map[string]string{
-	"openai":   "text-embedding-3-small",
-	"cohere":   "embed-english-v3.0",
-	"mistral":  "mistral-embed",
-	"together": "togethercomputer/m2-bert-80M-8k-retrieval",
-	"ollama":   "nomic-embed-text",
+	"openai":    "text-embedding-3-small",
+	"cohere":    "embed-english-v3.0",
+	"mistral":   "mistral-embed",
+	"together":  "togethercomputer/m2-bert-80M-8k-retrieval",
+	"ollama":    "nomic-embed-text",
+	"llamafile": "LLaMA_CPP",
 }
 
 // ProviderClientConfig holds provider-specific configuration for tests.

providers/llamafile/llamafile.go

@@ -0,0 +1,64 @@
+// Package llamafile provides a Llamafile provider implementation for any-llm.
+// Llamafile is a single-file executable that bundles a model with llama.cpp,
+// exposing an OpenAI-compatible API.
+package llamafile
+
+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 (
+	defaultAPIKey  = "llamafile" // Dummy key; Llamafile doesn't require auth.
+	defaultBaseURL = "http://localhost:8080/v1"
+	envBaseURL     = "LLAMAFILE_BASE_URL"
+	providerName   = "llamafile"
+)
+
+// Ensure Provider implements the required interfaces.
+var (
+	_ providers.CapabilityProvider = (*Provider)(nil)
+	_ providers.EmbeddingProvider  = (*Provider)(nil)
+	_ providers.ErrorConverter     = (*Provider)(nil)
+	_ providers.ModelLister        = (*Provider)(nil)
+	_ providers.Provider           = (*Provider)(nil)
+)
+
+// Provider implements the providers.Provider interface for Llamafile.
+// It embeds openai.CompatibleProvider since Llamafile exposes an OpenAI-compatible API.
+type Provider struct {
+	*openai.CompatibleProvider
+}
+
+// New creates a new Llamafile provider.
+func New(opts ...config.Option) (*Provider, error) {
+	base, err := openai.NewCompatible(openai.CompatibleConfig{
+		APIKeyEnvVar:   "", // Llamafile doesn't use an API key env var.
+		BaseURLEnvVar:  envBaseURL,
+		Capabilities:   llamafileCapabilities(),
+		DefaultAPIKey:  defaultAPIKey,
+		DefaultBaseURL: defaultBaseURL,
+		Name:           providerName,
+		RequireAPIKey:  false,
+	}, opts...)
+	if err != nil {
+		return nil, err
+	}
+
+	return &Provider{CompatibleProvider: base}, nil
+}
+
+// llamafileCapabilities returns the capabilities for the Llamafile provider.
+func llamafileCapabilities() providers.Capabilities {
+	return providers.Capabilities{
+		Completion:          true,
+		CompletionImage:     true, // Depends on the model loaded.
+		CompletionPDF:       false,
+		CompletionReasoning: false, // Llamafile doesn't support reasoning natively.
+		CompletionStreaming: true,
+		Embedding:           true,
+		ListModels:          true,
+	}
+}