refactor(ai): single provider registry as the backend source of truth

[lfnovo]

Summary

Adding an AI provider today means hand-syncing ~6 independent dicts. This PR makes open_notebook/ai/provider_registry.py the backend's single source of truth and derives everything else from it, without changing the shape of any existing surface — every import and call site keeps working.

Before: adding a provider touched 6 places

1. api/models.py — SupportedProvider Literal
2. api/credentials_service.py — PROVIDER_ENV_CONFIG
3. api/credentials_service.py — PROVIDER_MODALITIES (+ the discovery url_map)
4. open_notebook/ai/connection_tester.py — TEST_MODELS
5. open_notebook/ai/model_discovery.py — OPENAI_COMPAT_PROVIDERS / discovery wiring
6. frontend/src/lib/providers.tsx — ALL_PROVIDERS, PROVIDER_MODALITIES, PROVIDER_DOCS

After: registry + 2 manual copies (both test-enforced)

1. Add a ProviderSpec to PROVIDERS in open_notebook/ai/provider_registry.py — env vars, modalities, test model, discovery URL, display name, docs link, all in one place. PROVIDER_ENV_CONFIG, PROVIDER_MODALITIES, TEST_MODELS, the discovery url_map and OPENAI_COMPAT_PROVIDERS are now thin derivations in their current homes.
2. Add the name to the SupportedProvider Literal (typing — can't be built at runtime).
3. Add it to the frontend tables in frontend/src/lib/providers.tsx.

tests/test_credential_provider_validation.py enforces registry keys == Literal == frontend list, checks each spec's internal consistency (env config present, compat-discovery providers have exactly one required env var), and asserts the discovery function table covers the registry.

New endpoint

GET /api/providers exposes the registry: name, display_name, modalities, docs_url, env_configured. The frontend still uses its own tables — migrating it to consume this endpoint (and killing the regex-based .tsx cross-check test) is a deliberate follow-up, not part of this PR.

Docs

open_notebook/AGENTS.md and docs/7-DEVELOPMENT/credentials.md updated from the "keep four locations in sync" rule to the registry + 2 copies rule.

Verification

• uv run pytest tests/ — 434 passed
• ruff check . — clean
• mypy on the touched modules — 36 errors, identical set to the origin/main baseline (all pre-existing, none in the new/changed code)
• No registry value drifted: all env vars, modalities, test models, URLs and docs links carry the exact values previously hardcoded in each location

[cubic-dev-ai]

1 issue found across 11 files

Confidence score: 4/5

• In api/credentials_service.py, deriving provider metadata dynamically from the registry can hide which providers are OpenAI-compatible and which discovery URLs are expected, so a registry mismatch could slip through and cause runtime credential/discovery failures; before merging, add explicit tests/assertions for provider compatibility and exact discovery URLs (or keep a clear in-file allowlist) to preserve review-time visibility.

_{You’re at about 99% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.}

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="api/credentials_service.py">

<violation number="1" location="api/credentials_service.py:388">
P2: Replacing the explicit `url_map` with a dynamic derivation from the registry removes in-file visibility of which providers are OpenAI-compatible and what their discovery URLs are. The existing tests verify structural constraints (e.g., exactly one required env var) and that every provider has a discovery function, but they do not assert the exact set of providers with `openai_compat_discovery_url` or pin their URL values. Without that guard, a future registry edit could silently omit, alter, or misassign a discovery URL—causing `discover_models` to return nothing or misparse a non-OpenAI response as `data[]`. Consider adding a test that asserts the exact expected mapping.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Replacing the explicit url_map with a dynamic derivation from the registry removes in-file visibility of which providers are OpenAI-compatible and what their discovery URLs are. The existing tests verify structural constraints (e.g., exactly one required env var) and that every provider has a discovery function, but they do not assert the exact set of providers with openai_compat_discovery_url or pin their URL values. Without that guard, a future registry edit could silently omit, alter, or misassign a discovery URL—causing discover_models to return nothing or misparse a non-OpenAI response as data[]. Consider adding a test that asserts the exact expected mapping.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At api/credentials_service.py, line 388:

<comment>Replacing the explicit `url_map` with a dynamic derivation from the registry removes in-file visibility of which providers are OpenAI-compatible and what their discovery URLs are. The existing tests verify structural constraints (e.g., exactly one required env var) and that every provider has a discovery function, but they do not assert the exact set of providers with `openai_compat_discovery_url` or pin their URL values. Without that guard, a future registry edit could silently omit, alter, or misassign a discovery URL—causing `discover_models` to return nothing or misparse a non-OpenAI response as `data[]`. Consider adding a test that asserts the exact expected mapping.</comment>

<file context>
@@ -426,16 +383,11 @@ def models_endpoint(url: str) -> str:
-        "openrouter": "https://openrouter.ai/api/v1/models",
-        "dashscope": "https://dashscope.aliyuncs.com/compatible-mode/v1/models",
-        "minimax": "https://api.minimax.io/v1/models",
+        name: spec.openai_compat_discovery_url
+        for name, spec in PROVIDERS.items()
+        if spec.openai_compat_discovery_url
</file context>

[lfnovo]

Addressed the review findings in 1a66680:

• Duplicate-name safety: PROVIDERS is now built by _build_registry(), which raises ValueError at import time on a duplicate provider name instead of silently dropping the earlier spec; regression test added.
• Pinned discovery URLs: new test asserts the exact expected provider → OpenAI-compatible discovery URL mapping (both on the registry specs and on the derived OPENAI_COMPAT_PROVIDERS table), so a registry edit can't silently drop or misassign a URL.
• Typing: TEST_MODELS is now annotated Dict[str, Tuple[Optional[str], str]] instead of bare dict.

Rebased on latest main; 436 tests pass, ruff clean, mypy unchanged vs the main baseline.

[lfnovo]

The re-review finding was already addressed in 1a66680: test_openai_compat_discovery_urls_are_exactly_as_expected pins the exact 8-entry provider → discovery-URL mapping against both the registry specs and the derived OPENAI_COMPAT_PROVIDERS table — a registry edit that drops/misassigns a URL now fails CI. (The incremental review appears not to have picked up the new test.)