Replace implicit note shorthand with explicit addnote command and split README
Two changes: 1. structured-add-commands: The implicit note shorthand (kb "text") caused accidental note creation from mistyped commands. Replaced with explicit kb addnote <text> command. Root command reverts to standard Cobra behaviour. Updated examples, tests, SKILL.md, and specs. 2. split-readme-developer-docs: Moved build-from-source instructions, release process, API reference, and ROCm migration notes from README.md into a new DEVELOPER.md. README now links to DEVELOPER.md for dev workflows. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -83,17 +83,7 @@ services:
|
||||
KB_DATA_PATH=~/kb-data docker compose up -d
|
||||
```
|
||||
|
||||
**From source** (for development):
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
See [DEVELOPER.md](DEVELOPER.md) to run the engine from source.
|
||||
|
||||
The engine will download the embedding model on first start (~90MB) and load it onto the GPU. Check readiness:
|
||||
|
||||
@@ -129,13 +119,7 @@ chmod +x kb
|
||||
sudo mv kb /usr/local/bin/
|
||||
```
|
||||
|
||||
**From source** (for development):
|
||||
|
||||
```bash
|
||||
cd client
|
||||
make build # produces ./kb binary
|
||||
make all # or cross-compile: dist/kb-{os}-{arch}
|
||||
```
|
||||
See [DEVELOPER.md](DEVELOPER.md) to build the client from source.
|
||||
|
||||
### 3. Configure the client
|
||||
|
||||
@@ -152,9 +136,9 @@ Override via environment variables (`KB_ENGINE_URL`, `KB_API_KEY`) or CLI flags
|
||||
### 4. Use it
|
||||
|
||||
```bash
|
||||
# Quick notes (shorthand — no subcommand needed)
|
||||
kb "Always restart nginx after config changes"
|
||||
kb "Server room is building 3, floor 2" --tags ops
|
||||
# Add notes
|
||||
kb addnote "Always restart nginx after config changes"
|
||||
kb addnote "Server room is building 3, floor 2" --tags ops
|
||||
|
||||
# Add files (async — uploads and exits immediately)
|
||||
kb addfile ~/docs/manual.pdf --tags admin
|
||||
@@ -214,81 +198,6 @@ KB_DATA_PATH=~/kb-data docker compose -f compose.nvidia.yaml up -d
|
||||
|
||||
Data is GPU-vendor-agnostic — you can ingest on NVIDIA and serve from AMD (or vice versa) with the same data directory.
|
||||
|
||||
## 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 |
|
||||
|
||||
## 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 ROCm 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 `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:
|
||||
|
||||
```bash
|
||||
REGISTRY=ghcr.io IMAGE_ORG=myorg ./release-engine.sh --github
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
## Claude Code skill
|
||||
|
||||
This tool is designed to be wrapped as a Claude Code skill. See `SKILL.md` for the skill definition.
|
||||
|
||||
Reference in New Issue
Block a user