feat(models): add Yandex Foundation Models support and model-specific variables

- Introduce `YandexDriver` for synchronous Yandex Foundation Models API
- Add `variables` section in `models.yaml` and `ModelRegistry#getVariables()`
- Extend `Bblslug::runFromCli()` and `translate()` to merge env- and CLI-provided variables
- Update CLI help (`--variables`) and README with example usage
- Add tests in `ModelRegistryTest` for `getVariables()` on Yandex and other models
- Populate all Yandex model entries (`gpt-lite`, `gpt-pro`, `gpt-32k`, `llama-lite`, `llama`) in `resources/models.yaml`

Author: bionicman

README.md

@@ -23,6 +23,10 @@ APIs supported:
  - `openai:gpt-4-turbo` - OpenAI GPT-4 Turbo
  - `openai:gpt-4o` - OpenAI GPT-4o
  - `openai:gpt-4o-mini` - OpenAI GPT-4o Mini
+- Yandex:
+  - `yandex:gpt-lite` - YandexGPT Lite
+  - `yandex:gpt-pro` - YandexGPT Pro
+  - `yandex:gpt-32k` - YandexGPT Pro 32K
 
 ## Features
 
@@ -53,8 +57,11 @@ chmod +x vendor/bin/bblslug
  export DEEPL_PRO_API_KEY=...
  export GOOGLE_API_KEY=...
  export OPENAI_API_KEY=...
+ export YANDEX_API_KEY=... && export YANDEX_FOLDER_ID=...
  ```
 
+**NB!** Some vendors require additional parameters for client authentication (like Yandex)
+
 3. **Input / output**:
 
  - If `--source` is omitted, Bblslug reads from **STDIN**.
@@ -162,6 +169,18 @@ vendor/bin/bblslug \
   --translated=out.html
 ```
 
+### Use additional model/vendor-specific options
+
+```bash
+vendor/bin/bblslug \
+  --model=vendor:name \
+  --variables=some=XXX,other=YYY \
+  --format=html \
+  --verbose \
+  --source=input.html \
+  --translated=out.html
+```
+
 ## PHP Library Usage
 
 You can embed Bblslug in your PHP project:
@@ -189,6 +208,7 @@ $result = Bblslug::translate(
     proxy:      getenv('BBLSLUG_PROXY'),         // Optional proxy URI (http://..., socks5h://...)
     sourceLang: null,                            // Source language code (optional; autodetect if null)
     targetLang: null,                            // Target language code (optional; default from driver settings)
+    variables:  TBD,                             // TBD
     verbose:    true,                            // If true, prints debug request/response to stderr
 );
 

resources/models.yaml

@@ -347,3 +347,138 @@
   defaults:
     model: gpt-4o-mini
     temperature: 0.0
+
+'yandex:gpt-lite':
+  vendor: yandex
+  name: 'Yandex GPT Lite'
+  endpoint: 'https://llm.api.cloud.yandex.net/foundationModels/v1/completion'
+  format: text
+  limits:
+    max_tokens: 8192
+    token_estimator: gpt
+    estimated_max_chars: 32768
+  requirements:
+    auth:
+      help_url: 'https://yandex.cloud/en/docs/foundation-models/api-ref/authentication'
+      type: header
+      key_name: Authorization
+      prefix: Bearer
+      env: YANDEX_API_KEY
+    variables:
+      folder_id: YANDEX_FOLDER_ID
+    headers:
+      - 'Content-Type: application/json'
+  defaults:
+    model: yandexgpt-lite/latest
+    temperature: 0.0
+    max_tokens: 8192
+  http_error_handling: true
+  notes: 'Low-latency model with up to 8 k tokens sync or 32 k async.'
+
+'yandex:gpt-pro':
+  vendor: yandex
+  name: 'Yandex GPT Pro'
+  endpoint: 'https://llm.api.cloud.yandex.net/foundationModels/v1/completion'
+  format: text
+  limits:
+    max_tokens: 8192
+    token_estimator: gpt
+    estimated_max_chars: 32768
+  requirements:
+    auth:
+      help_url: 'https://yandex.cloud/en/docs/foundation-models/api-ref/authentication'
+      type: header
+      key_name: Authorization
+      prefix: Bearer
+      env: YANDEX_API_KEY
+    variables:
+      folder_id: YANDEX_FOLDER_ID
+    headers:
+      - 'Content-Type: application/json'
+  defaults:
+    model: yandexgpt/latest
+    temperature: 0.0
+    max_tokens: 8192
+  http_error_handling: true
+  notes: 'High-capacity 5th-gen model, up to 8 k tokens sync or 32 k async.'
+
+'yandex:gpt-32k':
+  vendor: yandex
+  name: 'Yandex GPT Pro 32K'
+  endpoint: 'https://llm.api.cloud.yandex.net/foundationModels/v1/completion'
+  format: text
+  limits:
+    max_tokens: 32000
+    token_estimator: gpt
+    estimated_max_chars: 128000
+  requirements:
+    auth:
+      help_url: 'https://yandex.cloud/en/docs/foundation-models/api-ref/authentication'
+      type: header
+      key_name: Authorization
+      prefix: Bearer
+      env: YANDEX_API_KEY
+    variables:
+      folder_id: YANDEX_FOLDER_ID
+    headers:
+      - 'Content-Type: application/json'
+  defaults:
+    model: yandexgpt-32k/latest
+    temperature: 0.0
+    max_tokens: 32000
+  http_error_handling: true
+  notes: 'Extended-context model: up to 32 k tokens (sync only).'
+
+'yandex:llama-lite':
+  vendor: yandex
+  name: 'Llama 8B (Lite)'
+  endpoint: 'https://llm.api.cloud.yandex.net/foundationModels/v1/completion'
+  format: text
+  limits:
+    max_tokens: 8192
+    token_estimator: gpt
+    estimated_max_chars: 32768
+  requirements:
+    auth:
+      help_url: 'https://yandex.cloud/en/docs/foundation-models/api-ref/authentication'
+      type: header
+      key_name: Authorization
+      prefix: Bearer
+      env: YANDEX_API_KEY
+    variables:
+      folder_id: YANDEX_FOLDER_ID
+    headers:
+      - 'Content-Type: application/json'
+  defaults:
+    model: llama-lite/latest
+    temperature: 0.0
+    max_tokens: 8192
+  http_error_handling: true
+  notes: 'Meta Llama 8 B variant, up to 8 k tokens sync or async.'
+
+'yandex:llama':
+  vendor: yandex
+  name: 'Llama 70B'
+  endpoint: 'https://llm.api.cloud.yandex.net/foundationModels/v1/completion'
+  format: text
+  limits:
+    max_tokens: 8192
+    token_estimator: gpt
+    estimated_max_chars: 32768
+  requirements:
+    auth:
+      help_url: 'https://yandex.cloud/en/docs/foundation-models/api-ref/authentication'
+      type: header
+      key_name: Authorization
+      prefix: Bearer
+      env: YANDEX_API_KEY
+    variables:
+      folder_id: YANDEX_FOLDER_ID
+    headers:
+      - 'Content-Type: application/json'
+  defaults:
+    model: llama/latest
+    temperature: 0.0
+    max_tokens: 8192
+  http_error_handling: true
+  notes: 'Full-scale Meta Llama 70 B, up to 8 k tokens sync or async.'

src/Bblslug/Bblslug.php

@@ -22,6 +22,7 @@ class Bblslug
      * @param string|null $proxy      Optional proxy URL (from env or CLI).
      * @param string|null $sourceLang Optional source language code.
      * @param string|null $targetLang Optional target language code.
+     * @param array<string,string>     $variables  Model-specific vars (e.g. ['some'=>'...'])
      * @param bool        $verbose    If true: include request/response logs.
      *
      * @return array{
@@ -51,6 +52,7 @@ public static function translate(
         ?string $proxy = null,
         ?string $sourceLang = null,
         ?string $targetLang = null,
+        array $variables = [],
         bool $verbose = false
     ): array {
         // Validate model
@@ -84,11 +86,21 @@ public static function translate(
         $prepared = $filterManager->apply($text);
         $preparedLength = mb_strlen($prepared);
 
+        // Prepare options for driver, merging in any CLI-provided variables
+        $options = array_merge(
+            ['format' => $format, 'dryRun' => $dryRun, 'verbose' => $verbose],
+            $variables
+        );
+
+        if ($context !== null) {
+            $options['context'] = $context;
+        }
+
         // Build request
         $req = $driver->buildRequest(
             $model,
             $prepared,
-            ['format' => $format, 'dryRun' => $dryRun, 'verbose' => $verbose]
+            $options
         );
 
         // API auth key handling
@@ -209,6 +221,7 @@ public static function runFromCli()
             "source-lang:",  // override source language
             "target-lang:",  // override target language
             "translated:",   // output file (default = STDOUT)
+            "variables:",    // model-specific overrides
             "verbose",       // enable debug logs
         ]);
 
@@ -282,6 +295,19 @@ public static function runFromCli()
             );
         }
 
+        // Parse CLI --variables (takes precedence over env)
+        $cliVars = [];
+        if (!empty($options['variables'])) {
+            foreach (explode(',', $options['variables']) as $pair) {
+                [$k, $v] = array_map('trim', explode('=', $pair, 2)) + [null, null];
+                if ($k !== null && $v !== null) {
+                    $cliVars[$k] = $v;
+                } else {
+                    Help::error("Invalid --variables format: '{$pair}'");
+                }
+            }
+        }
+
         // in interactive mode without --source, warn user about STDIN and EOF
         if ($sourceFile === null && function_exists('stream_isatty') && stream_isatty(STDIN)) {
             Help::warning("Reading from STDIN; press Ctrl-D to finish input and continue.");
@@ -341,6 +367,18 @@ public static function runFromCli()
         // Read optional proxy setting (CLI flag has priority)
         $proxy = $options['proxy'] ?? getenv('BBLSLUG_PROXY') ?: null;
 
+        // Collect any model-specific variables
+        $variables = [];
+        foreach ($registry->getVariables($modelKey) as $name => $envVar) {
+            $val = getenv($envVar);
+            if ($val === false) {
+                Help::error("Missing required env var {$envVar} for model {$modelKey}");
+            }
+            $variables[$name] = $val;
+        }
+        // Override by CLI
+        $variables = array_merge($variables, $cliVars);
+
         // Perform translation
         $res = [];
         try {
@@ -355,6 +393,7 @@ public static function runFromCli()
                 proxy: $proxy,
                 sourceLang: $sourceLang,
                 targetLang: $targetLang,
+                variables: $variables,
                 verbose: $verbose,
             );
         } catch (\Throwable $e) {

src/Bblslug/Help.php

@@ -52,6 +52,8 @@ public static function printHelp(?int $exitCode = 1): void
         echo "\t{$bold}--source-lang=LANG{$reset}   Source language code (e.g. EN, DE) - default autodetect\n";
         echo "\t{$bold}--target-lang=LANG{$reset}   Target language (e.g. EN, DE) - default EN\n";
         echo "\t{$bold}--translated=FILE{$reset}    Output file for translated content (omit to write to STDOUT)\n";
+        echo "\t{$bold}--variables=K=V,...{$reset}  Comma-separated model-specific overrides\n";
+        echo "\t{$bold}--variables=k=v[,k2=v2,...]{$reset}  Comma-separated list of model-specific variables\n";
         echo "\t{$bold}--verbose{$reset}            Show extra debug info after processing\n";
 
         echo "\nEnvironment:\n";
@@ -63,6 +65,7 @@ public static function printHelp(?int $exitCode = 1): void
         echo "\t  export OPENAI_API_KEY=\"...\" # for OpenAI (GPT)\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";
         echo "\n\tYou may also set a proxy globally via the BBLSLUG_PROXY environment variable:\n";
         echo "\t  export BBLSLUG_PROXY=\"http://localhost:3128\" # HTTP proxy\n";
         echo "\t  export BBLSLUG_PROXY=\"socks5h://127.0.0.1:9050\" # SOCKS5 proxy\n";
@@ -90,6 +93,11 @@ public static function printHelp(?int $exitCode = 1): void
         echo "\tphp bblslug.php --model=deepl:pro --format=html \\\n";
         echo "\t    --source=doc.html --translated=out.html --filters=url,html_code,html_pre\n";
 
+        echo "\n\tUsing model-specific variables (comma-separated):\n";
+        echo "\tphp bblslug.php --model=yandex:gpt-lite --format=text \\\n";
+        echo "\t    --variables=folder_id=...,foo=bar \\\n";
+        echo "\t    --source=in.txt --translated=out.txt\n";
+
         echo "\n\tUse HTTP proxy\n";
         echo "\tphp bblslug.php --model=openai:gpt-4o --format=text \\\n";
         echo "\t    --source=in.txt --translated=out.txt \\\n";