intellicrack.providers.grok

X.AI Grok API provider implementation.

This module provides integration with X.AI’s Grok models for chat completion and tool/function calling. Grok uses an OpenAI-compatible API, so this implementation leverages the OpenAI SDK with a custom base URL.

class GrokMessageContent[source]

Bases: TypedDict

Grok message content structure.

type: str
text: str
class GrokMessage[source]

Bases: TypedDict

Grok message structure.

role: str
content: str | list[GrokMessageContent] | None
tool_calls: list[dict[str, object]]
tool_call_id: str
name: str
class GrokProvider[source]

Bases: LLMProviderBase

X.AI Grok API provider implementation.

Provides integration with X.AI’s Grok models including support for tool/function calling and streaming responses. Uses the OpenAI SDK with a custom base URL for API compatibility.

Variables:

  • BASE_URL (str) – The X.AI API base URL.

  • TOOL_COUNT_CAP (int | None) – Maximum number of flattened tool functions Grok accepts in a single function-calling request.

BASE_URL: str = 'https://api.x.ai/v1'
TOOL_COUNT_CAP: int | None = 250
__init__()[source]

Initialize the GrokProvider instance.

Return type:

None

client: openai.AsyncOpenAI | None
property name: str

The provider instance id.

Returns:

The grok built-in provider id.

Return type:

str

property dialect: ApiDialect

The wire format this provider speaks.

Returns:

Always ApiDialect.CHAT_COMPLETIONS.

Return type:

ApiDialect

async connect(credentials)[source]

Connect to X.AI Grok API.

Parameters:

credentials (ProviderCredentials) – Must contain api_key. Optionally api_base for custom URL, and timeout to replace the SDK’s default request timeout.

Raises:
Return type:

None

async disconnect()[source]

Disconnect from Grok API.

Return type:

None

async list_models()[source]

Dynamically fetch available models from Grok.

Returns:

List of available Grok models.

Return type:

list[ModelInfo]

Raises:

ProviderError – If not connected.

async chat(messages, model, tools=None, temperature=0.7, max_tokens=4096, tool_choice=None, thinking=None, *, enable_cache=False)[source]

Send a chat completion request to Grok.

thinking is honoured on Grok models that expose it through the OpenAI-compatible reasoning_effort parameter (grok-4-multi-agent). Grok-4 / Grok-4-fast reason automatically, so the parameter is intentionally omitted there.

Parameters:

  • messages (list[Message]) – Conversation history.

  • model (str) – Model ID to use.

  • tools (list[ToolDefinition] | None) – Available tools for function calling.

  • temperature (float) – Sampling temperature.

  • max_tokens (int) – Maximum tokens in response.

  • tool_choice (ToolChoice | None) – How the model should select tools.

  • thinking (ThinkingConfig | None) – Extended thinking configuration. Forwarded as reasoning_effort for grok-*-multi-agent models.

  • enable_cache (bool) – Whether to enable prompt caching. Grok caches automatically when the same prompt prefix is reused; the parameter is logged for symmetry.

Returns:

Tuple of (assistant message, tool calls if any).

Return type:

tuple[Message, list[ToolCall] | None]

Raises:

ProviderError – If not connected or request fails.

async chat_stream(messages, model, tools=None, temperature=0.7, max_tokens=4096, tool_choice=None, thinking=None, *, enable_cache=False)[source]

Stream a chat completion response from Grok.

Parameters:

  • messages (list[Message]) – Conversation history.

  • model (str) – Model ID to use.

  • tools (list[ToolDefinition] | None) – Available tools for function calling.

  • temperature (float) – Sampling temperature.

  • max_tokens (int) – Maximum tokens in response.

  • tool_choice (ToolChoice | None) – How the model should select tools.

  • thinking (ThinkingConfig | None) – Extended thinking configuration. Forwarded as reasoning_effort for grok-*-multi-agent models; ignored on grok-4 / grok-4-fast (auto-reasoning).

  • enable_cache (bool) – Whether to enable prompt caching. Grok caches automatically; the parameter is logged for symmetry.

Yields:

str – Text chunks as they arrive.

Raises:

ProviderError – If not connected or the request fails. An invalid key raises the AuthenticationError subclass and a transient rate limit the RateLimitError subclass.

Return type:

AsyncIterator[str]

async cancel_request()[source]

Cancel any in-flight request.

Return type:

None