Grok LLM provider

xAI Grok provider for Piko's LLM service. Chat completions, streaming, and tool/function calling against the xAI API at api.x.ai.

Overview

This provider implements llm.ProviderPort against the xAI Grok API. The wire shape is OpenAI-compatible. Grok exposes the same /v1/chat/completions endpoint structure, so the adapter delegates the wire protocol to Piko's OpenAI provider and overlays Grok-specific concerns. It overrides the model list, re-tags errors to grok, and records its own OpenTelemetry metrics. Streaming, tool calling, and structured output come straight from the OpenAI adapter.

The provider supports chat completions only. ListModels returns a static set: grok-3, grok-3-mini, grok-4-0709, grok-4-fast-reasoning, grok-4-fast-non-reasoning, grok-4-1-fast-reasoning, grok-4-1-fast-non-reasoning, and grok-code-fast-1. None of these report vision capability.

The package is pure Go with no build tags and no CGO. It runs identically in a compiled build and in interpreted dev (dev-i) mode.

The provider exposes no embeddings. Grok ships no embedding models. Register a separate embedding provider (OpenAI, Voyage, Mistral) when you need them.

Requirements

  • An xAI API key. The provider reads it from Config.APIKey. The caller populates that field, for example from an environment variable.
  • Network egress to api.x.ai (or your BaseURL override).

Configuration

import (
    "os"

    "piko.sh/piko/wdk/llm/llm_provider_grok"
)

provider, err := llm_provider_grok.NewGrokProvider(llm_provider_grok.Config{
    APIKey:       os.Getenv("XAI_API_KEY"), // required
    BaseURL:      "",                       // empty for https://api.x.ai/v1
    DefaultModel: "grok-3",                 // optional; package default if empty
})
if err != nil {
    return err
}

Config.Validate() rejects missing API keys at construction time. Config.WithDefaults() populates DefaultModel to "grok-3" and BaseURL to https://api.x.ai/v1 when those fields are empty.

Bootstrap

ssr := piko.New(
    piko.WithLLMProvider("grok", provider),
    piko.WithDefaultLLMProvider("grok"),
)

NewGrokProvider returns an llm.ProviderPort, the exact type WithLLMProvider accepts. A compile-time assertion in the package guarantees the fit. One constructor call plus one option registers a fully observable provider that slots into the LLM service.

Errors surface as Piko's own ProviderError re-tagged to provider grok. The status code, message, and upstream Retry-After hint pass through unchanged, so retry and backoff behave the same way as the other providers.

For embeddings, register a separate provider:

ssr := piko.New(
    piko.WithLLMProvider("grok", grokProvider),
    piko.WithDefaultLLMProvider("grok"),
    piko.WithEmbeddingProvider("voyage", voyageProvider),
    piko.WithDefaultEmbeddingProvider("voyage"),
)

See also

Other LLM providers:

  • Anthropic Claude, long-context, strong tool use.
  • OpenAI, widest model selection, native structured-output API.
  • Gemini, cheapest competent option, multimodal-native.
  • Mistral, open-weight European provider.
  • Ollama, local inference for offline or privacy-sensitive workloads.
  • Voyage, embeddings-only specialist.

Framework docs:

External: