Determinism and Local Only

Determinism & Local-Only

Two design choices define how Columbus behaves: it is deterministic and it is local-only.

Deterministic

There is no LLM in Columbus. Search embeds the query with a fixed, bundled on-device model and ranks by vector similarity re-scored with deterministic heuristics — the "why relevant" text and risk hints are heuristic too. The same query against the same tree (and the same model) produces the same result, in the same order, every time.

$ columbus search "parse config" --json | sha256sum
$ columbus search "parse config" --json | sha256sum   # identical

Why this is valuable:

• Reproducible — a result you can reproduce is a result you can debug.
• Auditable — the why field explains every hit (exact name match, signature match, …).
• Cache-friendly — agents and tools can rely on stable output.
• No surprise drift — output changes only when your code or query changes.

What the ranking considers

Vector (semantic) similarity blended with deterministic heuristics: exact / prefix / signature name matches, symbol role (impl weighted over test/doc), and content density. Scores and the why string are emitted with every hit so the ranking is never a black box.

Local-only

Columbus runs entirely on your machine.

• No network calls. It works offline. Nothing about your code leaves the host.
• On-device embeddings. The vector model (bge-small-en-v1.5, via ONNX) runs locally; code is never shipped to a cloud to be vectorized.
• No API keys, no per-query cost. There is nothing to bill.
• Private by default. The database lives in your OS data dir; config is git-excluded.

The only hard runtime dependency is git. The onnxruntime shared library enables semantic search (bundled in release archives; search falls back to keyword without it). ripgrep is a recommended fast-path (pure-Go fallback otherwise) and ast-grep is optional.

The payoff for AI workflows

Deterministic + local-only means an agent gets context that is fast, free, private, and reproducible — the opposite of fuzzy, cloud-dependent, pay-per-query similarity search.

Related

How Columbus Works · Never Stale: Live Reconstruction · Scope Boundary