Skip to content

docs(fallback): document the actual config shape (top-level fallback_providers) (#19691)#20516

Closed
0xsir0000 wants to merge 1 commit into
NousResearch:mainfrom
0xsir0000:docs/fallback-providers-correct-config-paths
Closed

docs(fallback): document the actual config shape (top-level fallback_providers) (#19691)#20516
0xsir0000 wants to merge 1 commit into
NousResearch:mainfrom
0xsir0000:docs/fallback-providers-correct-config-paths

Conversation

@0xsir0000
Copy link
Copy Markdown
Contributor

Summary

The fallback-providers user-guide page was leading with the legacy `fallback_model:` (singular dict) shape across nine YAML examples, the intro paragraph, the custom-endpoint section, the auxiliary cross-reference, and the summary table. The CLI-reference page already showed the correct top-level `fallback_providers:` list shape, and `hermes_cli/fallback_cmd.py` + `cli.py` only persist to that key — so users hand-editing config from the docs ended up with a key the writer never updates and the reader treats as legacy back-compat only.

The intro line under `hermes fallback` also wrongly said the chain persists under `model.fallback_providers` — the writer has never put it nested under `model:`; the deep-merge config loader silently ignored the misplaced key, producing the confusing failover behaviour the issue describes.

Fix

Rewrite the page to:

  • lead with `fallback_providers:` (top-level list) as the primary shape,
  • add a worked "multiple fallbacks tried in order" example so the list format's value is obvious,
  • update the custom-endpoint, auxiliary, and summary-table snippets to use the same shape,
  • correct the `hermes fallback` intro to "top-level `fallback_providers:` list ... not nested under `model:`",
  • keep the `fallback_providers` vs `fallback_model` admonition (now flipped — current shape first, legacy shape second), and refresh the env-var tip and "main provider only valid in ..." prose to mention both keys.

Also touch `configuration.md` (the auxiliary-section cross-reference and two `"main"`-only-valid-in-X notes) so it stops pointing readers back at the legacy key.

Verification

  • ✅ `hermes_cli/fallback_cmd.py` lines 36–54 confirm: write to `fallback_providers`, read both `fallback_providers` (preferred) + legacy `fallback_model`.
  • ✅ `cli.py` line 2224 confirms the same precedence.
  • ✅ The CLI reference (`reference/cli-commands.md:1110`) and env-vars reference (`reference/environment-variables.md:523-531`) were already correct; this PR aligns the user-guide page with them.

Fixes #19691

…providers) (NousResearch#19691)

The fallback-providers user-guide page was leading with the legacy
``fallback_model:`` (singular dict) shape across nine YAML examples, the
intro paragraph, the custom-endpoint section, the auxiliary cross-reference,
and the summary table. The CLI-reference page already showed the correct
top-level ``fallback_providers:`` list shape, and ``hermes_cli/fallback_cmd.py``
+ ``cli.py`` only persist to that key — so users hand-editing config from
the docs ended up with a key the writer never updates and the reader treats
as legacy back-compat only.

The intro line under ``hermes fallback`` also wrongly said the chain
persists under ``model.fallback_providers`` — the writer has never put it
nested under ``model:``; the deep-merge config loader silently ignored the
misplaced key, producing the confusing failover behaviour the issue
describes.

Rewrite the page to:

- lead with ``fallback_providers:`` (top-level list) as the primary shape,
- add a worked "multiple fallbacks tried in order" example so the list
  format's value is obvious,
- update the custom-endpoint, auxiliary, and summary-table snippets to use
  the same shape,
- correct the ``hermes fallback`` intro to "top-level ``fallback_providers:``
  list ... not nested under ``model:``",
- keep the ``fallback_providers`` vs ``fallback_model`` admonition (now
  flipped — current shape first, legacy shape second), and refresh the env-
  var tip and "main provider only valid in ..." prose to mention both keys.

Also touch ``configuration.md`` (the auxiliary-section cross-reference and
two ``"main"``-only-valid-in-X notes) so it stops pointing readers back at
the legacy key.

Fixes NousResearch#19691
@alt-glitch alt-glitch added type/docs Documentation improvements P3 Low — cosmetic, nice to have area/config Config system, migrations, profiles labels May 6, 2026
@alt-glitch
Copy link
Copy Markdown
Collaborator

Duplicate of #19790 — both fix #19691 by correcting the fallback provider config shape in the same doc files (configuration.md, fallback-providers.md). Note that #20382 (merged) already fixed the CLI reference docs portion.

@0xsir0000 0xsir0000 closed this May 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/config Config system, migrations, profiles P3 Low — cosmetic, nice to have type/docs Documentation improvements

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Fallback provider docs show stale/incorrect config paths for fallback_providers

2 participants