feat: MiniMax image OCR + registry-driven multimodal provider support (#423)

Adds MiniMax as an AI provider (text enhancement + vision OCR, global_en/cn_zh
regions, openai/anthropic wire protocols) and generalizes AgentClient
multimodal support while landing it:

- API_PROVIDERS registry now declares each provider's wire protocol,
  supports_images capability, and optional regional endpoint map;
  _call_api branches on protocol, not provider names.
- AgentClient.call_with_image() serves all image-capable providers
  (Anthropic, OpenAI, Gemini, MiniMax); video_visual frame OCR routes
  through it via a table-driven provider dispatch with registry-based
  auto-detection (SKILL_SEEKER_VISION_PROVIDER).
- MiniMax adaptor resolves MINIMAX_API_REGION for enhancement requests
  (China-issued keys no longer 401 against the global endpoint).
- Closes the UNIFICATION_PLAN "AgentClient multimodal support" deferred
  item; CLAUDE.md updated accordingly.

Author: octo-patch

.env.example

@@ -16,6 +16,14 @@ GOOGLE_API_KEY=
 # Get your key from: https://platform.openai.com/api-keys
 OPENAI_API_KEY=
 
+# MiniMax API (Optional)
+# Required for MiniMax enhancement and vision OCR
+MINIMAX_API_KEY=
+MINIMAX_API_REGION=global_en
+MINIMAX_API_PROTOCOL=openai
+MINIMAX_VISION_MODEL=MiniMax-M3
+# SKILL_SEEKER_VISION_PROVIDER=minimax
+
 # GitHub Token (Optional, but recommended)
 # Increases rate limits from 60/hour to 5000/hour
 # Create token at: https://github.com/settings/tokens

CLAUDE.md

@@ -184,9 +184,9 @@ Local codebase analysis features, all opt-out (`--skip-*` flags):
 
 ### Enhancement (AgentClient is the single AI transport)
 
-Every text-based AI call goes through `AgentClient` (`src/skill_seekers/cli/agent_client.py`): central truncation gate, timeout policy, error classification. `API_PROVIDERS` (provider registry) and `AGENT_PRESETS` (local-agent command templates) live ONLY there. Adaptors declare provider/endpoint/model/prompt and route through `SkillAdaptor._enhance_skill_md_via_client` (atomic save with backup). `video_visual` frame classification is the documented multimodal exception (AgentClient is text-only).
+Every AI call goes through `AgentClient` (`src/skill_seekers/cli/agent_client.py`): central truncation gate, timeout policy, error classification. `API_PROVIDERS` (provider registry) and `AGENT_PRESETS` (local-agent command templates) live ONLY there. Each `API_PROVIDERS` entry declares its wire `protocol` (`anthropic`/`openai`/`google`) and `supports_images` capability — `_call_api` branches on the resolved protocol, NOT the provider name, so an OpenAI/Anthropic-compatible provider needs no new branch. Adaptors declare provider/endpoint/model/prompt and route through `SkillAdaptor._enhance_skill_md_via_client` (atomic save with backup). Multimodal image input goes through `AgentClient.call_with_image()` (used by `video_visual` frame OCR across all image-capable providers); it no longer bypasses AgentClient with a direct SDK call.
 
-- **API mode** (if API key set): Anthropic, Google Gemini, OpenAI, Moonshot/Kimi — detected in registry order; `SKILL_SEEKER_PROVIDER` forces one. Models: `SKILL_SEEKER_MODEL` (global) or `ANTHROPIC_MODEL`/`GOOGLE_MODEL`/`OPENAI_MODEL`/`MOONSHOT_MODEL`; `ANTHROPIC_BASE_URL` for compatible endpoints.
+- **API mode** (if API key set): Anthropic, Google Gemini, OpenAI, Moonshot/Kimi, MiniMax — detected in registry order; `SKILL_SEEKER_PROVIDER` forces one. Models: `SKILL_SEEKER_MODEL` (global) or `ANTHROPIC_MODEL`/`GOOGLE_MODEL`/`OPENAI_MODEL`/`MOONSHOT_MODEL`/`MINIMAX_MODEL`; `ANTHROPIC_BASE_URL` for compatible endpoints. MiniMax adds `MINIMAX_API_REGION` (`global_en`/`cn_zh`) and `MINIMAX_API_PROTOCOL` (`openai`/`anthropic`). Vision OCR provider: `SKILL_SEEKER_VISION_PROVIDER` (`auto` picks the first image-capable provider with a key).
 - **LOCAL mode** (fallback): Claude Code, Kimi Code, Codex, Copilot, OpenCode, custom agents — command built by `build_local_agent_command()`.
 - Control: `--enhance-level 0` (off) / `1` (SKILL.md only) / `2` (default, balanced) / `3` (full)
 - Agent selection: `--agent claude|codex|copilot|opencode|kimi|custom`

docs/UNIFICATION_PLAN.md

@@ -106,8 +106,9 @@ AgentClient is now the single AI transport for every text-based call:
   sys.exit removed); unified_scraper Phase-6 API save is atomic;
   doc_scraper's path already routed via adaptors.
 - video_scraper's reference cleaner goes through AgentClient.
-  video_visual's frame classification is the DOCUMENTED EXCEPTION
-  (multimodal; AgentClient is text-only today).
+  video_visual's frame OCR goes through AgentClient.call_with_image()
+  (multimodal support landed with the MiniMax image work; the former
+  text-only exception is gone).
 - `build_local_agent_command()` in agent_client is the single
   preset-template/permissions-flag handler; LocalSkillEnhancer delegates.
 
@@ -119,7 +120,9 @@ contracts — blind merges would silently change AI quality):
 - LocalSkillEnhancer terminal/background/daemon orchestration is kept; the
   remaining overlap with AgentClient._call_local is the prompt-file +
   subprocess loop (small).
-- AgentClient multimodal support (would absorb video_visual).
+- ~~AgentClient multimodal support (would absorb video_visual).~~ DONE —
+  `AgentClient.call_with_image()` serves all image-capable providers;
+  `_call_api` branches on a registry `protocol`/`supports_images`.
 
 ## Phase 3 — Enhancement consolidation (medium-large)
 
@@ -277,7 +280,7 @@ quality.
 - Per-request ExecutionContext initialization at the MCP boundary —
   lower urgency since the converters' raw-config fallback (fixed earlier)
   plus the contextvars override (5b) cover the known divergences.
-- AgentClient multimodal support (absorbs video_visual).
+- ~~AgentClient multimodal support (absorbs video_visual).~~ DONE (see Phase 3).
 
 ## Phase 5 — Platform unification: config, dispatch, MCP (medium)
 

docs/integrations/MINIMAX_INTEGRATION.md

@@ -40,11 +40,23 @@ pip install skill-seekers[all-llms]
 ### 3. Configure Environment
 
 ```bash
-export MINIMAX_API_KEY=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
+export MINIMAX_API_KEY=your-api-key
+export MINIMAX_API_REGION=global_en
+export MINIMAX_API_PROTOCOL=openai
 ```
 
 Add to your `~/.bashrc`, `~/.zshrc`, or `.env` file for persistence.
 
+Choose the region and protocol that match your account:
+
+| Region | OpenAI-compatible base URL | Anthropic-compatible base URL |
+|--------|----------------------------|-------------------------------|
+| `global_en` | `https://api.minimax.io/v1` | `https://api.minimax.io/anthropic` |
+| `cn_zh` | `https://api.minimaxi.com/v1` | `https://api.minimaxi.com/anthropic` |
+
+Set `MINIMAX_API_PROTOCOL` to `openai` or `anthropic`. Anthropic-compatible base
+URLs already end in `/anthropic`; do not append `/v1` to the configured base URL.
+
 ---
 
 ## Complete Workflow
@@ -182,6 +194,24 @@ response = client.chat.completions.create(
 )
 ```
 
+### Vision OCR for Video Frames
+
+MiniMax-M3 accepts image input and can power the existing low-confidence OCR
+fallback used during visual video extraction. Select MiniMax as the vision
+provider, then run the normal video workflow:
+
+```bash
+export SKILL_SEEKER_VISION_PROVIDER=minimax
+export MINIMAX_API_REGION=global_en
+export MINIMAX_API_PROTOCOL=openai
+
+skill-seekers create --video-file demo.mp4 --visual --vision-ocr
+```
+
+Use `MINIMAX_API_REGION=cn_zh` for the China endpoint. Both `openai` and
+`anthropic` protocols support the same tool path. `MINIMAX_VISION_MODEL`
+defaults to `MiniMax-M3`; MiniMax-M2.7 remains available for text workflows.
+
 ---
 
 ## API Reference
@@ -213,6 +243,11 @@ success = adaptor.enhance(skill_dir, api_key)
 | Variable | Description | Required |
 |----------|-------------|----------|
 | `MINIMAX_API_KEY` | Your MiniMax API key (JWT format) | Yes |
+| `MINIMAX_API_REGION` | API region: `global_en` or `cn_zh` | No; defaults to `global_en` |
+| `MINIMAX_API_PROTOCOL` | API protocol: `openai` or `anthropic` | No; defaults to `openai` |
+| `MINIMAX_MODEL` | Model override for text enhancement | No |
+| `MINIMAX_VISION_MODEL` | Model override for image OCR | No; defaults to `MiniMax-M3` |
+| `SKILL_SEEKER_VISION_PROVIDER` | Set to `minimax` to use MiniMax for vision OCR | No |
 
 ---
 

src/skill_seekers/cli/adaptors/minimax.py

@@ -8,14 +8,26 @@
 """
 
 from .openai_compatible import OpenAICompatibleAdaptor
+from skill_seekers.cli.minimax_config import (
+    MINIMAX_DEFAULT_MODEL,
+    MINIMAX_ENDPOINTS,
+    resolve_minimax_endpoint,
+)
 
 
 class MiniMaxAdaptor(OpenAICompatibleAdaptor):
     """MiniMax AI platform adaptor."""
 
     PLATFORM = "minimax"
     PLATFORM_NAME = "MiniMax AI"
-    DEFAULT_API_ENDPOINT = "https://api.minimax.io/v1"
-    DEFAULT_MODEL = "MiniMax-M3"
+    # Static fallback (global). Actual requests resolve region from
+    # MINIMAX_API_REGION via _api_base_url() so China-issued keys reach
+    # api.minimaxi.com instead of 401-ing against the global endpoint.
+    DEFAULT_API_ENDPOINT = MINIMAX_ENDPOINTS["global_en"]["openai"]
+    DEFAULT_MODEL = MINIMAX_DEFAULT_MODEL
     ENV_VAR_NAME = "MINIMAX_API_KEY"
     PLATFORM_URL = "https://platform.minimaxi.com/"
+
+    def _api_base_url(self) -> str:
+        """Resolve the OpenAI-compatible endpoint for the configured region."""
+        return resolve_minimax_endpoint(protocol="openai")

src/skill_seekers/cli/adaptors/openai_compatible.py

@@ -40,6 +40,14 @@ def _resolve_model(self) -> str:
         """Model to use: ``config['custom_model']`` if set, else DEFAULT_MODEL."""
         return self.config.get("custom_model") or self.DEFAULT_MODEL
 
+    def _api_base_url(self) -> str:
+        """API base URL for requests and packaged metadata.
+
+        Defaults to the static ``DEFAULT_API_ENDPOINT``; subclasses override for
+        region-aware routing (e.g. MiniMax global vs. China endpoints).
+        """
+        return self.DEFAULT_API_ENDPOINT
+
     def format_skill_md(self, skill_dir: Path, metadata: SkillMetadata) -> str:
         """
         Format SKILL.md as system instructions (no YAML frontmatter).
@@ -153,7 +161,7 @@ def package(
                 "version": "1.0.0",
                 "created_with": "skill-seekers",
                 "model": self._resolve_model(),
-                "api_base": self.DEFAULT_API_ENDPOINT,
+                "api_base": self._api_base_url(),
             }
 
             zf.writestr(f"{self.PLATFORM}_metadata.json", json.dumps(metadata, indent=2))
@@ -226,7 +234,7 @@ def upload(self, package_path: Path, api_key: str, **kwargs) -> dict[str, Any]:
 
                 client = OpenAI(
                     api_key=api_key,
-                    base_url=self.DEFAULT_API_ENDPOINT,
+                    base_url=self._api_base_url(),
                 )
 
                 client.chat.completions.create(
@@ -294,7 +302,7 @@ def enhance(self, skill_dir: Path, api_key: str) -> bool:
             skill_dir,
             api_key,
             provider="openai",
-            base_url=self.DEFAULT_API_ENDPOINT,
+            base_url=self._api_base_url(),
             model=self._resolve_model(),
             system=(
                 "You are an expert technical writer creating system "