feat(models): add xAI (Grok) support

- Introduce `XaiDriver` for xAI Grok API, mirroring OpenAiDriver
- Register new `xai` vendor in `ModelRegistry`
- Extend `resources/models.yaml` with xAI endpoint, auth config, usage mapping (including reasoning tokens) and grok-* models
- Update `README.md` and CLI `Help` to list `xai:grok-*` models and require `XAI_API_KEY`
- Restructure README section order slightly to accommodate new vendor

Author: bionicman

README.md

@@ -27,6 +27,12 @@ APIs supported:
   - `yandex:gpt-lite` - YandexGPT Lite
   - `yandex:gpt-pro` - YandexGPT Pro
   - `yandex:gpt-32k` - YandexGPT Pro 32K
+- X.ai:
+  - `xai:grok-4` - Grok 4
+  - `xai:grok-3` - Grok 3
+  - `xai:grok-3-fast` - Grok 3 Fast
+  - `xai:grok-3-mini` - Grok 3 Mini
+  - `xai:grok-3-mini-fast` - Grok 3 Mini Fast
 
 ## Features
 
@@ -61,6 +67,7 @@ chmod +x vendor/bin/bblslug
   export GOOGLE_API_KEY=...
   export OPENAI_API_KEY=...
   export YANDEX_API_KEY=... && export YANDEX_FOLDER_ID=...
+  export XAI_API_KEY=...
   ```
 
   **NB!** Some vendors require additional parameters, e.g. `YANDEX_FOLDER_ID`.

resources/models.yaml

@@ -291,3 +291,66 @@ yandex:
       defaults:
         model: llama/latest
       notes: 'Full-scale Meta Llama 70 B, up to 8 k tokens sync or async.'
+
+
+# -------------------------------------------------------------------
+# xAI (Grok)
+# -------------------------------------------------------------------
+xai:
+  endpoint: 'https://api.x.ai/v1/chat/completions'
+  format: text
+  defaults:
+    temperature: 0.0
+    source_lang: auto
+    target_lang: EN
+  requirements:
+    auth:
+      type: header
+      key_name: Authorization
+      prefix: Bearer
+      env: XAI_API_KEY
+      help_url: 'https://console.x.ai/team/default/api-keys'
+    headers:
+      - 'Content-Type: application/json'
+  limits:
+    max_tokens: 262144
+    token_estimator: gpt
+    estimated_max_chars: 1048576
+  usage:
+    tokens:
+      total:       total_tokens
+      breakdown:
+        prompt:      prompt_tokens
+        completion:  completion_tokens
+        reasoning: completion_tokens_details.reasoning_tokens
+
+  models:
+    grok-4:
+      name: 'Grok 4'
+      defaults:
+        model: grok-4
+      notes: 'Scientist-grade reasoning, coding mode, and real-time internet understanding'
+
+    grok-3:
+      name: 'Grok 3'
+      defaults:
+        model: grok-3
+      notes: 'Optimized for logical reasoning, math problem-solving, and real-time data with DeepSearch'
+
+    grok-3-fast:
+      name: 'Grok 3 Fast'
+      defaults:
+        model: grok-3-fast
+      notes: 'Optimized for fastest Grok 3 inference'
+
+    grok-3-mini:
+      name: 'Grok 3 Mini'
+      defaults:
+        model: grok-3-mini
+      notes: 'Compact variant balancing Grok 3 performance and efficiency'
+
+    grok-3-mini-fast:
+      name: 'Grok 3 Mini Fast'
+      defaults:
+        model: grok-3-mini-fast
+      notes: 'Mini variant optimized for fastest inference with compact footprint'

src/Bblslug/Console/Help.php

@@ -64,6 +64,8 @@ public static function printHelp(?int $exitCode = 1): void
         echo "\t  export DEEPL_PRO_API_KEY=\"...\" # for DeepL Pro\n";
         echo "\t  export GOOGLE_API_KEY=\"...\" # for Google (Gemini)\n";
         echo "\t  export OPENAI_API_KEY=\"...\" # for OpenAI (GPT)\n";
+        echo "\t  export YANDEX_API_KEY=\"...\" && export YANDEX_FOLDER_ID=\"...\" # for Yandex (FM)\n";
+        echo "\t  export XAI_API_KEY=\"...\" # for X.AI (Grok)\n";
         echo "\t  (See each model's required variable with --list-models)\n";
         echo "\tSome models may not require API keys at all.\n";
         echo "\tModel-specific variables can be passed via --variables or read from env\n";

src/Bblslug/Models/Drivers/XaiDriver.php

@@ -0,0 +1,122 @@
+<?php
+
+namespace Bblslug\Models\Drivers;
+
+use Bblslug\Models\ModelDriverInterface;
+use Bblslug\Models\Prompts;
+
+/**
+ * xAI Grok driver using explicit markers and OpenAI‐style API.
+ */
+class XaiDriver implements ModelDriverInterface
+{
+    private const START = '‹‹TRANSLATION››';
+    private const END   = '‹‹END››';
+
+    /**
+     * Build HTTP request params for Grok.
+     *
+     * @param array<string,mixed> $config  Model config from registry
+     * @param string              $text    Input text
+     * @param array<string,mixed> $options Options: [
+     *     'dryRun'      => bool,
+     *     'format'      => 'text'|'html',
+     *     'verbose'     => bool,
+     *     'temperature' => float,
+     *     'context'     => string|null,
+     * ]
+     *
+     * @return array{
+     *     url:     string,
+     *     headers: string[],
+     *     body:    string
+     * }
+     */
+    public function buildRequest(array $config, string $text, array $options): array
+    {
+        $defaults    = $config['defaults'] ?? [];
+        $model       = $defaults['model'] ?? throw new \RuntimeException('Missing xAI model name');
+        $temperature = (float) ($options['temperature'] ?? $defaults['temperature'] ?? 0.0);
+        $context     = trim((string) ($options['context'] ?? $defaults['context'] ?? ''));
+        $format      = $options['format'] ?? 'text';
+
+        $systemPrompt = Prompts::render(
+            'translator',
+            $format,
+            [
+                'source'  => $defaults['source_lang'] ?? 'auto',
+                'target'  => $defaults['target_lang'] ?? 'EN',
+                'start'   => self::START,
+                'end'     => self::END,
+                'context' => $context !== '' ? "Context: {$context}" : '',
+            ]
+        );
+
+        $messages = [
+            ['role' => 'system', 'content' => $systemPrompt],
+            ['role' => 'user',   'content' => self::START . "\n{$text}\n" . self::END],
+        ];
+
+        $payload = [
+            'model'       => $model,
+            'messages'    => $messages,
+            'temperature' => $temperature,
+            'stream'      => false,
+        ];
+
+        return [
+            'url'     => $config['endpoint'],
+            'headers' => $config['requirements']['headers'] ?? [],
+            'body'    => json_encode($payload, JSON_UNESCAPED_UNICODE),
+        ];
+    }
+
+    /**
+     * Parse the translated text from Grok's response.
+     *
+     * @param array<string,mixed> $config       Model config (not used)
+     * @param string              $responseBody Raw HTTP body
+     *
+     * @return array{
+     *     text:  string,
+     *     usage: array<string,mixed>|null
+     * }
+     *
+     * @throws \RuntimeException If API returned an error or markers not found
+     */
+    public function parseResponse(array $config, string $responseBody): array
+    {
+        $data = json_decode($responseBody, true);
+
+        // xAI error payload (model not found, auth, etc.)
+        if (isset($data['error'])) {
+            $code = $data['code'] ?? 'unknown_error';
+            throw new \RuntimeException("Grok API error [{$code}]: {$data['error']}");
+        }
+
+        // Normal completion path
+        if (
+            empty($data['choices'][0]['message']['content'])
+            || !is_string($data['choices'][0]['message']['content'])
+        ) {
+            throw new \RuntimeException("Grok translation failed: {$responseBody}");
+        }
+
+        $content = $data['choices'][0]['message']['content'];
+
+        if (
+            !preg_match(
+                '/' . preg_quote(self::START, '/') . '(.*?)' . preg_quote(self::END, '/') . '/s',
+                $content,
+                $matches
+            )
+        ) {
+            throw new \RuntimeException("Markers not found in Grok response");
+        }
+
+        $text  = trim($matches[1]);
+        $usage = $data['usage'] ?? null;
+
+        return ['text' => $text, 'usage' => $usage];
+    }
+}

src/Bblslug/Models/ModelRegistry.php

@@ -7,6 +7,7 @@
 use Bblslug\Models\Drivers\GoogleDriver;
 use Bblslug\Models\Drivers\OpenAiDriver;
 use Bblslug\Models\Drivers\YandexDriver;
+use Bblslug\Models\Drivers\XaiDriver;
 use Bblslug\Models\ModelDriverInterface;
 use Symfony\Component\Yaml\Yaml;
 
@@ -196,6 +197,7 @@ public function getDriver(string $key): ModelDriverInterface
             'google' => new GoogleDriver(),
             'openai' => new OpenAiDriver(),
             'yandex' => new YandexDriver(),
+            'xai' => new XaiDriver(),
             default => throw new \InvalidArgumentException("Unknown vendor '{$vendor}' in registry."),
         };
     }