Document the 5.1 AI & Models feature set by heskew · Pull Request #523 · HarperFast/documentation

heskew · 2026-06-10T00:43:09Z

Summary

First documentation for the models/AI surface shipping in 5.1 — the docs currently have zero coverage of it. Everything is tagged <VersionBadge version="v5.1.0" /> (all feature commits are first contained in core's v5.1.0-beta.1).

New reference/models/ section (sidebar: "AI & Models"): overview + models configuration block, embed()/generate()/generateStream() API, tool calling incl. the toolMode: 'auto' agent loop (budgets, parallelism, error modes, trace, conversation hook), the four bundled backends (Ollama, OpenAI incl. OpenAI-compatible endpoints via baseUrl, Anthropic, Bedrock), and hdb_model_calls / aggregate analytics.
Schema reference: new @embed directive section (write semantics, validation, auto-HNSW); vector-indexing additions — int8 quantization with full-precision rerank, per-query ef, auto-scaled search ef (type="changed"), dotProduct distance.
Correction: the HNSW parameter table documented efSearchConstruction; the option Harper reads is efConstructionSearch. Fixed with a note.
Release notes: deliberately not included — the 5.1 release notes are authored separately (the earlier draft was removed in 44bfe49).

Deliberately not documented

openaiStream() SSE formatter — unmerged (branch pinned).
The built-in agent component (agent: config, agent_* operations) — merged as scaffold, operations-API-only, maxCostUsd advertised but unenforced; holding docs until #839 lands.
Reserved GenerateOpts (toolArgValidation strict/lenient, maxCostUsd, conversationId) — called out in a short "Reserved options" note as non-functional in 5.1 so TypeScript autocomplete doesn't mislead.

Where to look

Facts were verified against the implementation (signatures from resources/models/types.ts, defaults from agentLoop.ts/analyticsTable.ts/backend components, HNSW behavior from resources/indexes/HierarchicalNavigableSmallWorld.ts). A follow-up docs-accuracy audit is planned; flagging two spots reviewers should sanity-check: the per-query ef example (plumbed through the sort descriptor; no existing unit test exercises it end-to-end) and the Azure/Gemini OpenAI-compatibility claims (bearer-auth-only constraint stated).
npm run build passes (links/MDX verified); format:write applied.

Generated by Claude (Fable 5).

🤖 Generated with Claude Code

@embed

New reference section (models/): overview + configuration, embed/generate/ generateStream API, tool calling and the toolMode 'auto' agent loop, the four bundled backends (ollama, openai, anthropic, bedrock), and model-call analytics. Adds the @embed directive and 5.1 vector-indexing additions (int8 quantization, per-query ef, auto-scaled search ef, dotProduct distance) to the schema reference, corrects the HNSW search parameter name (efConstructionSearch, previously documented as efSearchConstruction), and starts the 5.1 release notes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

gemini-code-assist · 2026-06-10T00:43:13Z

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

error_code can also be pending_unsupported (Models.ts pending-status path is reachable); Bedrock family dispatch also handles mistral., and unknown prefixes are rejected. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Config-file (Joi) validation of the models block is boot-blocking for structurally invalid entries; only registration-time errors are warn-and-skip. Also note ${VAR} indirection is string-fields-only. Surfaced by the models-subsystem deep review. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Only credential fields reject unresolved ${VAR} placeholders at startup; host/model/region carry them into requests literally. Surfaced by the models-subsystem deep review. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Current reference docs are served at /reference/v5/ (versions config maps current -> path 'v5'); the PR preview's broken-link check caught the unversioned /reference/ links. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

github-actions · 2026-06-10T03:34:31Z

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-523

This preview will update automatically when you push new commits.

VersionBadge tagging for minor-version availability (new vs changed), version derivation from the core release, release-notes-per-minor placement, versioned /reference/v5/ link paths from other content trees, and feature/docs PR cross-linking. Gives the engineering guidelines a single place to point at for docs mechanics. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

github-actions · 2026-06-10T03:53:17Z

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-523

This preview will update automatically when you push new commits.

gemini-code-assist · 2026-06-10T20:13:07Z

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

dawsontoth · 2026-06-11T15:37:57Z

+type Document @table {
+	id: Long @primaryKey
+	text: String
+	embedding: [Float] @embed(source: "text", model: "default")


Is there an equivalent to automatically embed on the search side of the equation? When we Document.search({. I'm not seeing an equivalent in the docs, but maybe I missed it.

Sorry Dawson. Missed this before merging. No, there's not but the need is now tracked at HarperFast/harper#1277. Great callout.

Release notes will be authored separately (Kris owns them); this PR stays scoped to the reference documentation. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

github-actions · 2026-06-11T21:39:25Z

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-523

This preview will update automatically when you push new commits.

github-actions · 2026-06-11T22:36:55Z

🧹 Preview Cleanup

The preview deployment for this PR has been removed.

@embed

* docs(v5.1): release notes, deployment tracking ops, deploy_component updates - Add 5.1.md release notes covering: models/AI, @embed directive, MCP server, deployment tracking, HNSW int8 quantization, and replication improvements - Update deploy_component docs: urlPath, install_allow_scripts params, deployment_id response - Document new deployment operations: list_deployments, get_deployment, get_deployment_payload, delete_deployment_payload - Document hdb_deployment record schema (fields, phases, peer_results) Note: models/AI detail, MCP reference, and HNSW quantization have separate PRs (#523, #507/#516, #508) — this PR adds the release notes overview and the deployment tracking operations which had no coverage. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * style: run prettier on changed files Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix: remove cross-plugin MCP link that breaks Docusaurus build The release-notes and reference doc plugins are separate; relative .md links between them resolve incorrectly. Removing until PR #507 (MCP reference section) merges and can be linked with an absolute path. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs(5.1): expand release notes — middleware/routing, caching, LOCAL_ONLY, HARPER_CONFIG, RocksDB, migrateOnStart, upgrade improvements --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

heskew and others added 4 commits June 9, 2026 17:48

Docs-accuracy fixes from implementation audit

802254c

error_code can also be pending_unsupported (Models.ts pending-status path is reachable); Bedrock family dispatch also handles mistral., and unknown prefixes are rejected. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Fix release-notes links to versioned reference path

803530d

Current reference docs are served at /reference/v5/ (versions config maps current -> path 'v5'); the PR preview's broken-link check caught the unversioned /reference/ links. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

github-actions Bot temporarily deployed to pr-523 June 10, 2026 03:34 Inactive

github-actions Bot temporarily deployed to pr-523 June 10, 2026 03:53 Inactive

kriszyp mentioned this pull request Jun 10, 2026

docs(v5.1): release notes, deployment tracking operations #524

Merged

4 tasks

heskew requested review from Ethan-Arrowood and kriszyp June 10, 2026 20:12

heskew marked this pull request as ready for review June 10, 2026 20:12

heskew requested a review from a team as a code owner June 10, 2026 20:12

dawsontoth reviewed Jun 11, 2026

View reviewed changes

dawsontoth approved these changes Jun 11, 2026

View reviewed changes

Ethan-Arrowood approved these changes Jun 11, 2026

View reviewed changes

Drop the 5.1 release-notes draft from this PR

44bfe49

Release notes will be authored separately (Kris owns them); this PR stays scoped to the reference documentation. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Ethan-Arrowood approved these changes Jun 11, 2026

View reviewed changes

github-actions Bot temporarily deployed to pr-523 June 11, 2026 21:39 Inactive

heskew merged commit dcd5dc2 into main Jun 11, 2026
7 checks passed

heskew deleted the docs/models-5.1 branch June 11, 2026 22:36

This was referenced Jun 12, 2026

Search-side automatic embedding for vector search (@embed counterpart) HarperFast/harper#1277

Open

5.1 GA readiness: models/vector subsystem audit findings HarperFast/harper#1235

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document the 5.1 AI & Models feature set#523

Document the 5.1 AI & Models feature set#523
heskew merged 7 commits into
mainfrom
docs/models-5.1

heskew commented Jun 10, 2026 •

edited

Loading

Uh oh!

gemini-code-assist Bot commented Jun 10, 2026

Uh oh!

github-actions Bot commented Jun 10, 2026

Uh oh!

github-actions Bot commented Jun 10, 2026

Uh oh!

gemini-code-assist Bot commented Jun 10, 2026

Uh oh!

dawsontoth Jun 11, 2026

Uh oh!

heskew Jun 12, 2026

Uh oh!

github-actions Bot commented Jun 11, 2026

Uh oh!

Uh oh!

github-actions Bot commented Jun 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

heskew commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Deliberately not documented

Where to look

Uh oh!

gemini-code-assist Bot commented Jun 10, 2026

Uh oh!

github-actions Bot commented Jun 10, 2026

🚀 Preview Deployment

Uh oh!

github-actions Bot commented Jun 10, 2026

🚀 Preview Deployment

Uh oh!

gemini-code-assist Bot commented Jun 10, 2026

Uh oh!

dawsontoth Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

heskew Jun 12, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jun 11, 2026

🚀 Preview Deployment

Uh oh!

Uh oh!

github-actions Bot commented Jun 11, 2026

🧹 Preview Cleanup

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

heskew commented Jun 10, 2026 •

edited

Loading