steve
6dfc13be1d
Implements five of the six enhancements from docs/kb-enhancements-proposal.htm, closing the retrieval-quality gap identified in the qmd review. - Cross-encoder reranking: new kb/reranker.py loads an optional reranking model at startup (KB_RERANK_ENABLED, KB_RERANKER_MODEL, KB_RERANK_CANDIDATES). Search degrades gracefully to plain hybrid retrieval when the model is absent. Exposed via a "rerank" block in /status, a rerank flag on search, and --no-rerank in the CLI. - RRF rank fusion: FTS and vector lists now merge by reciprocal rank fusion with a top-rank bonus, replacing the old score blend. Scores are comparable across queries. - Bench harness and explain traces: kb bench runs a query fixture against each backend and reports precision@k, recall and MRR. --explain returns a per-result score breakdown. - Tag context descriptions: tags carry an optional one-line description (kb tag-describe), returned as tag_contexts with search results. Adds a tags.description column migration. - Structured data ingestion: .json/.yaml/.toml files ingest as text via the new "data" doc type, pretty-printing minified JSON before chunking. Query expansion (proposal item 5) is deliberately left out pending bench results. Requires engine v3.3.0. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
127 lines
4.0 KiB
Markdown
127 lines
4.0 KiB
Markdown
# Developer Guide
|
|
|
|
Instructions for building from source, releasing, and contributing to kb.
|
|
|
|
## Building from source
|
|
|
|
### Engine
|
|
|
|
```bash
|
|
cd engine
|
|
|
|
# NVIDIA GPU
|
|
KB_DATA_PATH=~/kb-data docker compose -f compose.nvidia.yaml up -d
|
|
```
|
|
|
|
### Client
|
|
|
|
```bash
|
|
cd client
|
|
make build # produces ./kb binary
|
|
make all # or cross-compile: dist/kb-{os}-{arch}
|
|
```
|
|
|
|
## Running tests
|
|
|
|
### Engine
|
|
|
|
Engine tests run against SQLite (with sqlite-vec) and stub out the embedding
|
|
model, so they only need lightweight dependencies — no torch/docling install:
|
|
|
|
```bash
|
|
uv venv /tmp/kb-test-venv
|
|
uv pip install --python /tmp/kb-test-venv/bin/python pytest pytest-asyncio fastapi httpx sqlite-vec
|
|
cd engine && /tmp/kb-test-venv/bin/python -m pytest
|
|
```
|
|
|
|
### Client
|
|
|
|
```bash
|
|
cd client && go test ./...
|
|
```
|
|
|
|
## Search-quality benchmarking
|
|
|
|
`kb bench fixture.json` runs a fixture of queries with known-relevant documents
|
|
against each backend (fts, vec, hybrid, hybrid+rerank) and reports precision@k,
|
|
recall, and MRR. See `docs/bench-example.json` for the fixture format.
|
|
|
|
Run a bench before and after any ranking change (RRF weights, reranker, model
|
|
swap) and compare — keep a 20-30 query fixture against your real corpus outside
|
|
the repo.
|
|
|
|
## Building and releasing
|
|
|
|
Client and engine are versioned independently via `client/VERSION` and `engine/VERSION`. Each has its own release script and git tag prefix.
|
|
|
|
### Release client
|
|
|
|
```bash
|
|
./release-client.sh --gitea # patch bump, release via Gitea
|
|
./release-client.sh --github --minor # minor bump, release via GitHub
|
|
./release-client.sh --gitea --no-increment # release current version as-is
|
|
./release-client.sh --gitea --dry-run # preview without doing anything
|
|
```
|
|
|
|
Creates tag `client-vX.Y.Z`, builds Go binaries for all platforms, and creates a Gitea/GitHub release with binaries attached.
|
|
|
|
The client embeds a `MinEngineVersion` (from `client/MIN_ENGINE_VERSION`) and will hard-fail if the connected engine is too old.
|
|
|
|
### Release engine
|
|
|
|
```bash
|
|
./release-engine.sh --gitea # patch bump, release via Gitea
|
|
./release-engine.sh --github --minor # minor bump, release via GitHub
|
|
./release-engine.sh --gitea --no-increment # release current version as-is
|
|
./release-engine.sh --gitea --dry-run # preview without doing anything
|
|
```
|
|
|
|
Creates tag `engine-vX.Y.Z`, builds NVIDIA and CPU Docker images, creates a Gitea/GitHub release, and pushes images to the registry.
|
|
|
|
### Checking versions
|
|
|
|
```bash
|
|
# Client
|
|
kb --version
|
|
|
|
# Engine
|
|
curl http://localhost:8000/api/v1/status | jq .version
|
|
```
|
|
|
|
### Docker images
|
|
|
|
Images are pushed to `gitea.dcglab.co.uk/steve/kb/engine` with tags:
|
|
|
|
- `engine-v2.0.6-nvidia` / `engine-v2.0.6-cpu` — versioned
|
|
- `latest-nvidia` / `latest-cpu` — latest release
|
|
|
|
Override the registry and org via environment variables:
|
|
|
|
```bash
|
|
REGISTRY=ghcr.io IMAGE_ORG=myorg ./release-engine.sh --github
|
|
```
|
|
|
|
## API reference
|
|
|
|
All endpoints are under `/api/v1/`. Requires `Authorization: Bearer <key>` header when `KB_API_KEY` is set.
|
|
|
|
| Method | Endpoint | Description |
|
|
|---|---|---|
|
|
| `GET` | `/health` | Health check (bypasses auth) |
|
|
| `POST` | `/search` | Hybrid search (JSON body) |
|
|
| `POST` | `/jobs` | Upload file/note for ingestion (multipart, returns 202 or 409 if duplicate) |
|
|
| `GET` | `/jobs` | List ingestion jobs |
|
|
| `GET` | `/jobs/{id}` | Job details |
|
|
| `GET` | `/documents` | List documents |
|
|
| `GET` | `/documents/{id}` | Document details with chunks |
|
|
| `GET` | `/documents/{id}/file` | Download original file |
|
|
| `DELETE` | `/documents/{id}` | Remove a document (and stored file) |
|
|
| `PUT` | `/documents/{id}/tags` | Add/remove tags |
|
|
| `GET` | `/tags` | List all tags (with descriptions) |
|
|
| `PUT` | `/tags/{name}/description` | Set/clear a tag context description |
|
|
| `GET` | `/status` | Engine status, GPU info, DB stats, rerank state |
|
|
| `POST` | `/reindex` | Re-embed all chunks |
|
|
| `POST` | `/bulk/delete` | Bulk delete documents by filter |
|
|
| `POST` | `/bulk/tags` | Bulk add/remove tags by filter |
|
|
| `POST` | `/bulk/set-tags` | Bulk replace tags by filter |
|