qkb — local knowledge-base CLI

A small CLI for ingesting and querying local knowledge files (markdown, plain text, JSON, YAML, CSV) using SQLite FTS5 BM25, with optional LLM-powered summarization on ingest and reranking on query.

Install

Requires Python 3.12+ and uv.

git clone <this-repo>
cd qkb_trial
uv sync
uv pip install -e .

After install, qkb is on your PATH. (Or run any command via uv run qkb ….)

Quick start

# Initialize the database (creates ~/.qkb/index.sqlite)
qkb init

# Ingest some files
qkb ingest examples/

# See what's there
qkb list
qkb status

# BM25 search — no LLM required
qkb search "user_id"
qkb search "Postgres"

# Show a single document's metadata + chunk layout
qkb show 1

# Drop a document
qkb delete 1

LLM features (optional)

With an LLM configured, ingest stores a generated summary and tags per document, and qkb query does BM25 → LLM rerank for higher-quality results.

Configure once via env vars or qkb config set:

# OpenAI
export QKB_LLM_PROVIDER=openai
export QKB_LLM_MODEL=gpt-4o-mini
export QKB_LLM_API_KEY=sk-...

# Or local Ollama
qkb config set llm_provider ollama
qkb config set llm_base_url http://localhost:11434/v1
qkb config set llm_model llama3.1:8b

# Then:
qkb ingest examples/
qkb query "how do we handle authentication?"

qkb config list prints the effective configuration. Env vars override ~/.qkb/config.toml.

Commands

Storage

Single SQLite file at ~/.qkb/index.sqlite (override with QKB_DATA_DIR or QKB_DB_PATH). Schema: documents (one row per file), chunks (header- or window-bounded fragments), chunks_fts (FTS5 BM25 index over chunk content + heading + summary).

Supported formats

Testing

pytest -q

The test suite uses an in-memory SQLite database and a mocked LLM client — no network required.