Engineering Whitepaper & System Design

Under the Hood of MLVA

How MLVA delivers instant, 100% offline natural-language code search combining dense vector embeddings, Okapi BM25 keyword indexing, and local SQLite storage.

System Architecture Diagram

Visual overview of how MLVA processes user queries, evaluates dual AI and lexical retrieval streams in parallel, and returns calibrated results in milliseconds.

Step 1 · User Query Input

mlva "Find Python code for linear regression"

User enters a plain-English, intent-driven search query in the terminal CLI or browser app.

Step 2 · Intent & Language Parser

Semantic Query Pre-Processor

Analyzes natural language to extract domain targets and filter stopwords:

Target Language: python (boosts .py files) Task Intent: regression (identifies mathematical objective)

Engine A · 60% Weight

Dense Vector Embedding Engine

Semantic & Conceptual Code Understanding

Model: Xenova/all-MiniLM-L6-v2 (384-dimensional dense vectors)
Execution: 100% offline CPU inference via ONNX Runtime (Zero GPU/Cloud)
Method: Cosine similarity between query vector and code chunk embeddings
Strength: Finds matching code conceptually even with zero overlapping keywords

Engine B · 40% Weight

Okapi BM25 Lexical Keyword Engine

Exact Identifier & Token Retrieval

Tokenization: Language-aware code lexer & inverted term frequency matrix
Execution: Local SQLite inverted index lookups
Method: Okapi BM25 with term saturation and match coordination factors
Strength: Pinpoints exact function names, class identifiers, and literal syntax

Step 4 · Calibrated Hybrid Ranker

Weighted Score Calibration & Verification

Final Score = (Semantic Score × 0.60) + (BM25 Score × 0.40) × Language Intent Multiplier

Task Match Verification Language Compatibility Bonus Deduplication & Top-N Sort

Step 5 · Storage & Terminal Delivery

Local SQLite Store (~/.mlva/mlva.db)

Sub-millisecond retrieval from local Write-Ahead Logging (WAL) SQLite database. Results immediately rendered in terminal with syntax highlighting, interactive code viewing (mlva show 1), and direct VS Code launcher (mlva code 1).

Core Pillars of the Architecture

1. Local ONNX Model Inference

MLVA bundles the Xenova/all-MiniLM-L6-v2 transformer model. Executed locally via ONNX Runtime on your host CPU, it transforms document chunks into dense 384-dimensional unit vectors. No GPU, CUDA, or Python runtime required.

2. Okapi BM25 Keyword Engine

Pure vector search can occasionally miss exact function names or variable tokens. MLVA integrates Okapi BM25 scoring with term coordination factors to guarantee that exact identifier matches are boosted alongside conceptual matches.

3. Optimized SQLite Storage

Document chunks, tokens, and vector blobs are persisted in ~/.mlva/mlva.db using better-sqlite3 with Write-Ahead Logging (WAL) mode enabled, supporting thousands of queries per second with zero network latency.

4. Task & Language Intent Calibrator

Raw cosine similarity can produce false positives if two unrelated programs share general text tokens. MLVA analyzes user query grammar, detects target languages (e.g. Python vs Java), and validates algorithmic verbs to eliminate false matches.

Privacy & Security Boundaries

Zero Telemetry & 100% Offline: MLVA executes all embedding generation, indexing, and search scoring strictly on the user's local CPU. No document content, search query, or embedding vector is ever transmitted across external networks.