feat(nl2sql): add GLM, Doubao, and Sakana Fugu providers (19 → 22) (#252)

* feat(nl2sql): add GLM, Doubao, and Sakana Fugu providers (19 -> 22)

Three more built-in OpenAI-compatible NL->SQL providers, each a one-line
_PROVIDERS registry entry (all derived lookup tables update automatically):

- glm     -> https://api.z.ai/api/paas/v4        ZAI_API_KEY (fallback ZHIPUAI_API_KEY)  glm-4.5-flash
- doubao  -> https://ark.cn-beijing.volces.com/api/v3  ARK_API_KEY  doubao-seed-1-6-251015
- sakana  -> https://api.sakana.ai/v1            SAKANA_API_KEY  fugu

Base URLs, key env vars, and default models verified against each
vendor's official docs. Extended the key-discovery test with the new
deviating env vars (ZAI_API_KEY, ARK_API_KEY). Bumped the built-in count
to 22 in README/tools.md/tour.md and added the three rows to the
user-guide provider table. release-notes-0.6.9 left at 19 (historical).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0122yLZLJ8t4W43sdN6BmTZc

* test(nl2sql): cover GLM legacy ZHIPUAI_API_KEY fallback

Addresses Sourcery review on #252 — the GLM spec accepts both ZAI_API_KEY
and the legacy ZHIPUAI_API_KEY; parametrize the key-discovery test for the
fallback too.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0122yLZLJ8t4W43sdN6BmTZc

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: devopam

CHANGELOG.md

@@ -8,6 +8,13 @@ adheres to [Semantic Versioning](https://semver.org/).
 
 ### Added
 
+- **Three more built-in NL→SQL providers (19 → 22).** `translate_nl_to_sql`
+  now ships **GLM** (Zhipu AI / Z.ai — `ZAI_API_KEY`, default
+  `glm-4.5-flash`), **Doubao** (ByteDance / Volcengine Ark — `ARK_API_KEY`,
+  default `doubao-seed-1-6-251015`; the model must be activated in the Ark
+  console), and **Sakana Fugu** (`SAKANA_API_KEY`, default `fugu`). Each is
+  a one-line entry in the `nl2sql._PROVIDERS` registry; base URLs and key
+  env vars were verified against each vendor's own docs.
 - **Doc-table drift guard.** `tools/generate_doc_tables.py` regenerates
   the `docs/tools.md` tool index and the `docs/architecture.md` module
   map from the single sources of truth (the registered tool surface and

README.md

@@ -221,7 +221,7 @@ are one-shot commands, not configuration). The only required one is
 | HTTP transport with bearer auth | `MCPG_TRANSPORT=streamable-http` + `MCPG_HTTP_AUTH_TOKEN=…` |
 | Multi-tenant SaaS | `MCPG_DEFAULT_ROLE=tenant_a` + `MCPG_ALLOWED_ROLES=tenant_a,tenant_b,…` |
 | Read-replica fan-out | `MCPG_REPLICA_URLS=postgresql://…?sslmode=require,postgresql://…?sslmode=require` |
-| NL→SQL — single provider | Set any one vendor key (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `XAI_API_KEY`, `GROQ_API_KEY`, `HF_TOKEN`, … — 19 built-in providers). MCPg auto-picks the default. |
+| NL→SQL — single provider | Set any one vendor key (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `XAI_API_KEY`, `GROQ_API_KEY`, `HF_TOKEN`, … — 22 built-in providers). MCPg auto-picks the default. |
 | NL→SQL — multiple providers, caller picks | Set all vendor keys you want active. Each call to `translate_nl_to_sql` can pass `provider="…"` (any configured built-in or custom). |
 
 ### Full reference
@@ -492,7 +492,7 @@ Compact category list. For the full, current tool reference see
 - **Search** — `fuzzy_search` (trigram), `full_text_search`,
   `vector_search`, `hybrid_search` (pgvector + FTS via RRF),
   `geo_search` (PostGIS k-NN).
-- **Natural language → SQL** — `translate_nl_to_sql` (19 built-in
+- **Natural language → SQL** — `translate_nl_to_sql` (22 built-in
   providers — Anthropic, OpenAI, Gemini, xAI, Groq, Mistral, Hugging
   Face, … — plus any custom OpenAI-compatible endpoint; output passes
   through the same safe-SQL kernel as hand-written queries).

docs/tools.md

@@ -34,7 +34,7 @@ plumbing:
 | `MCPG_SECRETS_BACKEND` | `env` (default), `vault`, `aws`, or `gcp`. Resolves credential settings through HashiCorp Vault, AWS Secrets Manager, or GCP Secret Manager instead of plain env vars. Per-provider config: `MCPG_VAULT_*`, `MCPG_AWS_*`, `MCPG_GCP_*`. |
 | `MCPG_OTEL_ENABLED` / `MCPG_OTEL_SERVICE_NAME` | Emit one OpenTelemetry span per `call_tool` (tool name, argument count, status — never argument values). Requires the `mcpg[otel]` extra. |
 | `MCPG_SLOW_CALL_THRESHOLD_MS` / `MCPG_LOG_FORMAT` | Log a structured "slow call" record when a tool exceeds the threshold; switch the logger between `text` and `json` formats. |
-| `MCPG_NL2SQL_PROVIDER` / `MCPG_NL2SQL_API_KEY` / `MCPG_NL2SQL_MODEL` / `MCPG_NL2SQL_BASE_URL` / `MCPG_NL2SQL_MAX_TOKENS` | `translate_nl_to_sql` provider config — 19 built-in providers + custom (`MCPG_NL2SQL_CUSTOM_PROVIDERS`). |
+| `MCPG_NL2SQL_PROVIDER` / `MCPG_NL2SQL_API_KEY` / `MCPG_NL2SQL_MODEL` / `MCPG_NL2SQL_BASE_URL` / `MCPG_NL2SQL_MAX_TOKENS` | `translate_nl_to_sql` provider config — 22 built-in providers + custom (`MCPG_NL2SQL_CUSTOM_PROVIDERS`). |
 
 <!-- BEGIN generated: tool-index (python tools/generate_doc_tables.py --tools) -->
 ## Tool index (252 tools)

docs/tour.md

@@ -83,7 +83,7 @@ run_select_parallel(statements, parallel_limit=8)    # concurrent fan-out; one b
 explain_query(sql, format="json")
 analyze_query_plan(sql)                              # walks the EXPLAIN tree
 translate_nl_to_sql(question, schema, provider=null, execute=false)
-                                                     # NL → SQL; routes per call across 19 built-in providers (+ custom)
+                                                     # NL → SQL; routes per call across 22 built-in providers (+ custom)
 ```
 
 ## "Stream a huge result set" (server-side cursors)

docs/user-guide.md

@@ -313,6 +313,9 @@ callable through the tool:
 | `github` | `GITHUB_TOKEN` (GitHub Models) | `openai/gpt-4o-mini` |
 | `sambanova` | `SAMBANOVA_API_KEY` | `Meta-Llama-3.1-8B-Instruct` |
 | `moonshot` | `MOONSHOT_API_KEY` (Kimi) | `kimi-k2.5` |
+| `glm` | `ZAI_API_KEY` (falls back to `ZHIPUAI_API_KEY`) | `glm-4.5-flash` |
+| `doubao` | `ARK_API_KEY` (Volcengine Ark; model must be activated in the console) | `doubao-seed-1-6-251015` |
+| `sakana` | `SAKANA_API_KEY` (Fugu) | `fugu` |
 
 All but the first three (`anthropic` / `openai` / `gemini`) are
 OpenAI-compatible vendors: MCPg drives them through one chat-completions

src/mcpg/nl2sql.py

@@ -164,6 +164,20 @@ class ProviderSpec:
         "sambanova", "openai", "https://api.sambanova.ai/v1", "Meta-Llama-3.1-8B-Instruct", ("SAMBANOVA_API_KEY",)
     ),
     ProviderSpec("moonshot", "openai", "https://api.moonshot.ai/v1", "kimi-k2.5", ("MOONSHOT_API_KEY",)),
+    # GLM (Zhipu AI / Z.ai). International Z.ai endpoint + the modern
+    # /paas/v4 OpenAI-compatible path (raw key as Bearer, no JWT). The
+    # newer international SDK reads ZAI_API_KEY; the legacy MetaGLM SDK
+    # used ZHIPUAI_API_KEY, kept as a fallback.
+    ProviderSpec("glm", "openai", "https://api.z.ai/api/paas/v4", "glm-4.5-flash", ("ZAI_API_KEY", "ZHIPUAI_API_KEY")),
+    # Doubao (ByteDance / Volcengine Ark). Plain model id works in the
+    # `model` field (endpoint ids are only for custom deployments); the
+    # model must be activated in the Ark console first.
+    ProviderSpec(
+        "doubao", "openai", "https://ark.cn-beijing.volces.com/api/v3", "doubao-seed-1-6-251015", ("ARK_API_KEY",)
+    ),
+    # Sakana Fugu — Sakana AI's multi-agent system, exposed as a single
+    # OpenAI-compatible chat model.
+    ProviderSpec("sakana", "openai", "https://api.sakana.ai/v1", "fugu", ("SAKANA_API_KEY",)),
 )
 
 _PROVIDERS_BY_KEY: dict[str, ProviderSpec] = {p.key: p for p in _PROVIDERS}

tests/unit/test_config.py

@@ -417,6 +417,10 @@ def test_custom_provider_declarations_fail_fast_on_malformed_entries(entry: str,
         ("GITHUB_TOKEN", "github"),  # deviates
         ("DEEPINFRA_TOKEN", "deepinfra"),  # deviates
         ("SAMBANOVA_API_KEY", "sambanova"),
+        ("ZAI_API_KEY", "glm"),  # deviates
+        ("ZHIPUAI_API_KEY", "glm"),  # GLM legacy fallback env var
+        ("ARK_API_KEY", "doubao"),  # deviates
+        ("SAKANA_API_KEY", "sakana"),
     ],
 )
 def test_expanded_fleet_provider_discovered_from_its_vendor_env_var(env_var: str, provider: str) -> None: