fix(models): map openai-api provider slug to openai picker group

[rodboev]

Fixes #3443.

Thinking Path

• hermes-agent's PROVIDER_REGISTRY uses the slug openai-api for its built-in OpenAI provider (the one activated by OPENAI_API_KEY / OPENAI_BASE_URL env vars, distinct from openai-codex which reads ~/.codex/auth.json).
• The WebUI model picker groups models by canonical provider slug via _resolve_provider_alias, but _PROVIDER_ALIASES has no entry for openai-api. The slug passes through unchanged, doesn't match the openai key in _PROVIDER_MODELS, and falls into the else branch of the group builder.
• GPT models from the openai-api provider are either silently dropped from the picker or misattributed to OpenRouter (if OR also lists them).
• This is the same shape as BYOK custom provider models not shown in WebUI model dropdown (TUI shows them) #815 (z.ai → zai) and bug(local-model): 'Provider local set but no API key' fires after a few turns — auxiliary client (compression/vision) has no 'local' branch #1384 (local → custom): a provider slug mismatch resolved by a one-line alias table entry.

What Changed

• api/config.py — Added "openai-api": "openai" to _PROVIDER_ALIASES with a comment explaining the provenance of the slug and referencing BYOK custom provider models not shown in WebUI model dropdown (TUI shows them) #815 and bug(local-model): 'Provider local set but no API key' fires after a few turns — auxiliary client (compression/vision) has no 'local' branch #1384 as precedent.
• tests/test_openai_api_provider_alias.py — New test file (4 tests) following the pattern of test_issue1384_local_provider.py:
  • test_openai_api_resolves_to_openai — the alias resolves correctly
  • test_openai_api_case_insensitive — uppercase and mixed-case variants also resolve
  • test_alias_table_contains_entry — the raw dict entry exists (guards against accidental removal)
  • test_openai_canonical_unchanged — the canonical slug openai passes through unchanged

Why It Matters

Users who configure hermes-agent with OPENAI_API_KEY + OPENAI_BASE_URL (the openai-api provider path) see their GPT models missing from the WebUI model picker. The models are available to the agent but invisible in the UI.

Verification

pytest tests/test_openai_api_provider_alias.py -v --timeout=60
pytest tests/test_byok_model_dropdown.py -v --timeout=60
pytest tests/test_issue1384_local_provider.py -v --timeout=60

All 33 tests pass (4 new + 20 existing BYOK + 9 existing #1384).

Manual: configure OPENAI_API_KEY and OPENAI_BASE_URL in .env, open the model picker, confirm GPT models appear under the OpenAI group.

Risks / Follow-ups

• Low risk. One data entry in an alias table with clear precedent. No logic changes.
• The adjacent slug openai-codex (auto-discovered from ~/.codex/auth.json) is already handled by hermes-agent's own provider registry and doesn't need a WebUI alias, but could be added defensively in a future PR.

Model Used

Claude Opus 4.6 via Claude Code CLI

[nesquena-hermes]

Reviewed the diff at HEAD (264f66be) against origin/master — api/config.py (+6) and the new tests/test_openai_api_provider_alias.py (+33). The one-line alias entry is the right fix, and the cross-repo contract checks out. Walking through the verification:

What the fix does

# api/config.py  (inside _PROVIDER_ALIASES, ~line 792)
"openai-api": "openai",

_resolve_provider_alias (config.py:792) consults the agent's hermes_cli.models._PROVIDER_ALIASES first, then falls back to the WebUI's local table. I checked the agent table directly — it has no openai-api entry, because openai-api is a real registry slug, not an alias:

# hermes_cli/auth.py:183
"openai-api": ProviderConfig(
    id="openai-api",

So the slug passes through the agent-first lookup unchanged and lands in the WebUI's local table — exactly where this entry belongs. Good call keeping it local rather than expecting the agent to alias its own canonical slug.

Cross-repo grouping is consistent

On the agent side, openai-api and openai-codex both feed a single "OpenAI" display group:

# hermes_cli/models.py:987
"openai": ("OpenAI", "Codex CLI or direct OpenAI API", ["openai-codex", "openai-api"]),

The WebUI's _PROVIDER_MODELS has an openai key (config.py:1058) and _PROVIDER_DISPLAY has "openai": "OpenAI" (config.py:706), so aliasing openai-api → openai folds those GPT models into the same picker group the agent intends. Matches the #815 / #1384 precedent precisely.

Bonus: it also fixes _canonicalise_provider_id

Worth noting in the PR description — this entry fixes a second code path. Before the change, _canonicalise_provider_id("openai-api") (config.py:911) returned the slug unchanged, since openai-api isn't in _PROVIDER_DISPLAY/_PROVIDER_MODELS and the alias resolved to itself. After the change it resolves to openai, which is in _PROVIDER_DISPLAY, so the guarded branch:

resolved = _resolve_provider_alias(raw)
if resolved and resolved.lower() in _PROVIDER_DISPLAY:
    return resolved.lower()

now correctly canonicalizes it. So this also prevents a duplicate "openai-api" provider group from appearing alongside "OpenAI" anywhere _canonicalise_provider_id is the entry point.

Tests

The four assertions in test_openai_api_provider_alias.py cover the resolve path, case-insensitivity, raw-table presence, and canonical pass-through — same structure as test_issue1384_local_provider.py. Per cron policy I don't execute PR-authored test files, but the assertions match the behavior verified above by reading the code.

Verdict

LGTM. One data entry with clear precedent, no logic change, low risk. The only optional follow-up would be adding an openai-api key to the WebUI's static _PROVIDER_MODELS table, but that table is fallback-only (the live list comes from the agent), so the alias-to-openai approach is correct and sufficient.

[nesquena-hermes]

Thanks @rodboev — the diagnosis is exactly right (hermes-agent reports its built-in OpenAI provider as the openai-api slug, and the WebUI picker group builder doesn't recognize it, so GPT models vanish from the picker — #3443 is a real bug). Holding with changes-requested because the chosen fix has a send-path regression we caught in the release gate.

The problem with aliasing openai-api → openai in _PROVIDER_ALIASES

_PROVIDER_ALIASES collapses the slug everywhere it's resolved, not just for picker display. The gate traced the full path and it bricks the send:

1. With the alias, /api/models exposes active_provider: "openai" and the optgroup provider_id="openai" for a model.provider: openai-api config.
2. The browser then sends model_provider: "openai".
3. _session_model_state_from_request() preserves that, model_with_provider_context() emits @openai:gpt-..., and resolve_model_provider() returns provider "openai".
4. But the installed hermes-agent registry (hermes_cli.auth.PROVIDER_REGISTRY) has openai-api and openai-codex — no openai — so resolve_provider("openai") raises Unknown provider 'openai' on the send path.

So the models would become visible but unsendable. CI/full suite stays green because no test exercises the end-to-end send path for this provider config (a static-test blind spot).

Suggested direction

Keep the runtime provider identity as openai-api; only fix the display grouping. Concretely:

• Do not add "openai-api": "openai" to _PROVIDER_ALIASES.
• Instead register openai-api as a first-class picker provider — add it to _PROVIDER_DISPLAY (a friendly group label) and to _PROVIDER_MODELS / the generic live-lookup path so its GPT models render in the picker — while the option value and session model_provider stay openai-api.

That way the group renders AND the send path resolves openai-api against the agent registry correctly.

Test to add

Replace the alias-only assertions with an end-to-end regression: a model.provider=openai-api config + a selected gpt-* from the picker must resolve through model_with_provider_context(...) / resolve_model_provider(...) to provider openai-api (not openai), proving the models are both visible and sendable.

Happy to review as soon as you push the reworked version — the underlying bug is real and worth fixing, it just needs the display/runtime split. (Verified against current master; the alias-table pattern you cited from #815/#1384 works for those because those providers' canonical slugs DO exist in the agent registry, whereas openai does not.)

[rodboev]

Verified the send-path regression: _resolve_provider_alias fires in _resolve_configured_provider_id, the picker emits provider_id="openai", the browser sends it back, and resolve_provider("openai") raises because the agent registry has openai-api but not openai.

Reworked in 19f7f70: dropped the alias, registered openai-api as a first-class entry in _PROVIDER_DISPLAY ("OpenAI API") and _PROVIDER_MODELS (same GPT model list). _canonicalise_provider_id now returns "openai-api" unchanged, the picker emits provider_id="openai-api", and the send path resolves it directly from PROVIDER_REGISTRY.

Tests rewritten: 6 picker assertions (display registered, models registered, not aliased, canonicalise preserves slug, openai/openai-codex unchanged) plus 2 send-path assertions (resolve_model_provider and model_with_provider_context both preserve "openai-api").

Separately filed NousResearch/hermes-agent#37714 to add "openai": "openai-api" to the agent's own alias table as a general robustness fix, but the webui no longer depends on it.

[nesquena-hermes]

Shipped in v0.51.223 ✅ — cherry-picked onto release stage-p5 (the reworked first-class-provider version, not the original alias approach that broke the send path). I also added the env-detection fix a review caught: OPENAI_API_KEY detection now surfaces openai-api instead of a bare openai the agent registry can't resolve, so env-only OpenAI-API setups get working picker entries end to end. Thanks @rodboev! Closing as merged-via-release. (Closes #3443.)