docs(models): config-selectable backends (backend: <module>)#556
docs(models): config-selectable backends (backend: <module>)#556heskew wants to merge 4 commits into
Conversation
Covers the public custom-backend registration API added in HarperFast/harper#1405: a Custom backends section in backends.md, a registerBackend() entry in api.md, and an overview mention. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…tream return shape Addresses gemini-code-assist review on #554. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…-only generate #1405 (registerBackend/defineBackend) merged and ships in v5.1.15. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Companion to HarperFast/harper#1521 (#1471). Stacked on #554. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
heskew
added
the
content
![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 updates the documentation in reference/models/backends.md to introduce "Config-selectable backends," explaining how custom backends can be loaded via configuration module specifiers. The feedback suggests minor grammatical improvements to the introductory text and recommends clarifying how the factory registers the backend using the parameters provided in its signature.
| Beyond the four built-ins, a component or application can register its own backend — including an in-process one that runs inference locally instead of calling an HTTP service. A registered backend is selected by its logical name through the same `model` option as a configured backend. | ||
|
|
||
| Custom backends are registered programmatically; the `backend` field in the [`models` configuration](./overview#configuration) selects only the built-ins above. | ||
| Custom backends can be added two ways: **registered programmatically** (below), or **selected in config** by pointing the `backend` field at a module — see [Config-selectable backends](#config-selectable-backends). |
There was a problem hiding this comment.
For better grammatical flow and professionalism, consider changing 'added two ways' to 'added in two ways'.
| Custom backends can be added two ways: **registered programmatically** (below), or **selected in config** by pointing the `backend` field at a module — see [Config-selectable backends](#config-selectable-backends). | |
| Custom backends can be added in two ways: **registered programmatically** (below), or **selected in config** by pointing the `backend` field at a module — see [Config-selectable backends](#config-selectable-backends). |
| - an **instance-root-relative path** (`./backends/local.js`) — resolved against the Harper instance root. | ||
| - an **absolute path**. | ||
|
|
||
| The factory has the signature `({ logicalName, kind, config }) => void | Promise<void>` and registers via [`registerBackend`](#registerbackend); it receives the config entry with `${VAR}` placeholders already resolved. A `backend` that is neither a built-in nor an importable module is logged and skipped at startup, leaving other entries unaffected. |
There was a problem hiding this comment.
To make the integration clearer for developers implementing custom backends, explicitly state that the factory should register the backend by calling registerBackend with the provided kind and logicalName parameters.
| The factory has the signature `({ logicalName, kind, config }) => void | Promise<void>` and registers via [`registerBackend`](#registerbackend); it receives the config entry with `${VAR}` placeholders already resolved. A `backend` that is neither a built-in nor an importable module is logged and skipped at startup, leaving other entries unaffected. | |
| The factory has the signature `({ logicalName, kind, config }) => void | Promise<void>` and registers the backend by calling [`registerBackend`](#registerbackend) with the provided `kind` and `logicalName`. It receives the config entry with `${VAR}` placeholders already resolved. A `backend` that is neither a built-in nor an importable module is logged and skipped at startup, leaving other entries unaffected. |
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-556 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>
|
Superseded by #558. The config-selectable backends content ( 🤖 Posted by Claude (Opus 4.8) on Nathan's behalf |
🧹 Preview CleanupThe preview deployment for this PR has been removed. |
3 participants
Summary
Documents the config-selectable custom backends added in HarperFast/harper#1521 (#1471): an operator can point a
models:backendfield at a module — a bare package, an instance-root-relative path, or an absolute path — and Harper imports it and invokes its factory at startup.Updates the Custom backends section in
reference/models/backends.md: reframes the intro to "two ways" (programmatic registration vs config selection) and adds a Config-selectable backends subsection (resolution rules + the module factory contract + a YAML example).Stacking
docs/models-register-backend; retarget tomainonce docs(models): document registerBackend / defineBackend custom backends #554 merges.Version
<VersionBadge>is a v5.1.16 placeholder — harper#1521 isn't merged yet; set it to the actual release at merge time.Generated by an LLM (Claude Opus 4.8).
🤖 Generated with Claude Code