HarperFast / HarperFast/harper
Document local-embedding dev story (examples/local-embedding/ recipe)
- Dominant language
- JavaScript
- Stars
- 89
- Forks
- 10
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 200
Description
## Problem
`scope.models.embed()` is a great API but the local-dev path isn't documented anywhere a developer would naturally find it. \"How do I run embeddings locally?\" should be a one-page README with copy-pasteable commands, not a treasure hunt across issues + the Fabric runbook.
## Proposal
Add `examples/local-embedding/` to harper-pro (or to `HarperFast/documentation`) containing:
### `README.md`
- 5-step quickstart: install ollama, start it, pull `nomic-embed-text`, drop in `harperdb-config.yaml`, run `harper`
- A small worked example: `Documents` table with a `vector` column + an HNSW index, `MatchDocuments` resource that embeds the query and runs a vector search
- Notes on vector dimensions: pick one embedding model and stick with it; switching changes vector dimensions and invalidates the index
### `harperdb-config.yaml`
The minimal config needed.
### `resources/Documents.js`
The minimal resource showing the embed-then-search pattern.
### `docker-compose.yml`
Bundles harper + ollama + a volume for `~/.ollama` so models survive container restarts. `docker compose up` and you have a working stack.
### `package.json`
`npm run dev` script that orchestrates the above.
## Stretch: TestBackend documentation
Brief note on how to use `TestBackend.ts` in unit tests so CI doesn't need a real model:
```js
import { setEmbedding } from 'harper-pro/resources/models/backendRegistry.ts';
import { TestBackend } from 'harper-pro/resources/models/TestBackend.ts';
beforeEach(() => {
setEmbedding('default', new TestBackend());
});
```
## Related
- PR #779 (Phase 1 model analytics emission)
- `harper-celebrity-match` (a working multi-modal example to point at for the harder case)
Contributor guide
Assessment
This issue has not been assessed yet.