kb/DEVELOPER.md

Developer Guide

Instructions for building from source, releasing, and contributing to kb.

Building from source

Engine

cd engine

# NVIDIA GPU
KB_DATA_PATH=~/kb-data docker compose -f compose.nvidia.yaml up -d

# AMD GPU (ROCm)
KB_DATA_PATH=~/kb-data docker compose -f compose.rocm.yaml up -d

Client

cd client
make build    # produces ./kb binary
make all      # or cross-compile: dist/kb-{os}-{arch}

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

./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

./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 ROCm Docker images, creates a Gitea/GitHub release, and pushes images to the registry.

Checking versions

# Client
kb --version

# Engine
curl http://localhost:8000/api/v1/status | jq .version

Docker images

Images are pushed to docker.dcglab.co.uk/dcg/kb/engine with tags:

• engine-v2.0.6-nvidia / engine-v2.0.6-rocm — versioned
• latest-nvidia / latest-rocm — latest release

Override the registry and org via environment variables:

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
GET	/status	Engine status, GPU info, DB stats
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

Future: ROCm runtime migration

The onnxruntime-rocm execution provider was removed from onnxruntime as of v1.23. AMD is pushing toward the MIGraphX execution provider as the replacement for ROCm GPU inference. When upgrading onnxruntime beyond v1.22, the ROCm Dockerfile will need to switch from onnxruntime-rocm to onnxruntime with the MIGraphX EP and install the migraphx runtime libraries instead.