docs(models): namespace registration API + document routing & fallback#558
Conversation
The merged registration docs describe the free-global `registerBackend` / `defineBackend` form that 5.2 removed; correct them to the `models.`-namespaced methods, and add a Routing & Fallback page for the pluggable routing shipped in harper #1326 / #1537. - reference/models/backends.md, api.md: registerBackend/defineBackend are methods on `models` (not standalone `harper` exports/globals) — fix signatures + example. - reference/models/routing.md (new): fallback groups (`fallback:` config), capability routing (`opts.requires`, tools auto-require), fallback-on-error (primary error surfaced, abort short-circuits), custom routers (`models.registerRouter`). - api.md: `requires` option on embed/generate; overview + sidebar cross-links. - release-notes/v5-lincoln/5.2.md (new): breaking namespacing note + routing. Refs harper #1326, #1534, #1537. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces documentation and release notes for Harper v5.2.0, focusing on the new pluggable routing and fallback capabilities for AI models, as well as the breaking change that namespaces backend registration under the models object. The feedback suggests clarifying some potentially confusing phrasing in the routing documentation regarding error fallbacks and custom router candidate resolution. Additionally, it recommends replacing absolute URL paths with relative markdown file paths in the release notes to ensure proper link validation and resolution by Docusaurus.
…ment) The absolute links to the reference docs were missing the version segment (/reference/models/... → /reference/v5/models/...), which failed the Docusaurus broken-links build check. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-558 This preview will update automatically when you push new commits. |
…e note Our model changes (routing #1326, namespaced registration #1534, fallback #1537) all landed in v5.1.15 — not a future 5.2 — and the free-global registration form was never in a released version (added by #1405 and removed by #1534 within the same release), so there is no user-facing breaking change to note. - routing.md: version badge v5.2.0 -> v5.1.15 (+ source comment) - remove release-notes/v5-lincoln/5.2.md (wrong version + moot breaking framing) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-558 This preview will update automatically when you push new commits. |
dawsontoth
left a comment
dawsontoth
left a comment
There was a problem hiding this comment.
I like the namespacing, makes it a lot easier to understand, nice!
Address gemini-code-assist clarity notes on routing.md: the facade default IS to fall back on any error (filtering which errors skip the fallback is the custom policy), and the no-candidates case reads more clearly as a backend that satisfies the requirement. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-558 This preview will update automatically when you push new commits. |
Fold the config-selectable backend docs from #556 into this PR (superseding it): a `backend` value that is not a built-in is resolved as a module specifier (bare package / instance-root-relative / absolute) and imported at startup. Shipped in v5.1.15 (registerFromModule), so it sits under the existing v5.1.15 Custom backends heading; corrected #556 stray v5.1.16 badge and namespaced the registerBackend reference. Refs harper #1471. Supersedes documentation #556. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-558 This preview will update automatically when you push new commits. |
🧹 Preview CleanupThe preview deployment for this PR has been removed. |
2 participants
Summary
Corrects the model-extension docs to match what shipped in v5.1.15, and documents routing.
registerBackend/defineBackendas standaloneharperexports/globals, but v5.1.15 ships them as methods onmodels(the free-global form was added and removed within the same release and was never in a tagged version). Corrected inreference/models/backends.md+api.md(signatures, example, and the "exported fromharper" claim →models.registerBackend(...)/models.defineBackend(...)).reference/models/routing.md, v5.1.15) —fallback:config groups, capability routing (opts.requires+ tools auto-require), fallback-on-error (primary error surfaced, abort short-circuits, no mid-stream fallback), and custom routers (models.registerRouter). Adds arequiresoption row to the embed/generate tables, overview + sidebar cross-links.Notes
globals.jshas noregisterBackendin any v5.1.x tag) — so there is nothing to break for users.reference/docs are touched; nothing versioned/released.Refs harper #1326, #1534, #1537. Companion to #554 (registration) / #556 (config backends).
🤖 Generated with Claude Code