# MLVA

> MLVA (Machine Learning Virtual Assistant) is a 100% offline-capable, privacy-first developer assistant and local search engine. It combines local dense vector embeddings (all-MiniLM-L6-v2) with Okapi BM25 keyword matching in a local SQLite database, providing fast, natural-language search directly in the terminal (mlva-cli) and on the web.

## Documentation & Resources
- [MLVA Web Application](https://mlva.web.app/): Interactive web app, document viewer, and local search interface.
- [System Architecture](https://mlva.web.app/architecture): Technical whitepaper detailing BM25 + ONNX vector hybrid ranking pipeline.
- [Tool Comparisons](https://mlva.web.app/comparisons): Comparative benchmarks vs Ripgrep, FZF, and classic Grep.
- [Developer Tutorials](https://mlva.web.app/tutorials): Step-by-step guides for installation, custom folder indexing, and syntax viewing.
- [npm Package Registry](https://www.npmjs.com/package/mlva-cli): Official npm package distribution for the global command-line interface.
- [Full LLM Specification](https://mlva.web.app/llms-full.txt): Comprehensive unabridged technical reference for AI agents and language models.

## Core Capabilities
- **Natural Language Search**: Query code and notes conceptually using plain-English task descriptions.
- **Hybrid Retrieval**: Combines BM25 lexical scoring with dense 384-dimensional cosine vector similarity.
- **Language Intent Detection**: Re-weights rankings dynamically when queries request specific programming languages.
- **Terminal Code Viewer (`mlva show <n>`)**: View full syntax-highlighted code in terminal with line numbering and pagination.
- **External App Integration**: Launch files directly in Visual Studio Code (`mlva code <n>`), default OS application (`mlva open <n>`), or native file manager (`mlva reveal <n>`).
- **Clipboard Streaming (`mlva copy <n>`)**: Stream full source code directly into system clipboard without truncation.
- **100% Offline Privacy**: Zero telemetry, zero cloud LLM API calls. All embeddings and SQLite data remain strictly local (`~/.mlva`).

## Quick Installation & Usage
```bash
# Global installation from npm
npm install -g mlva-cli

# Initialize local SQLite database and cache ONNX model
mlva setup

# Run hybrid search
mlva "linear regression implementation"
```

## Essential CLI Commands
- `mlva "<query>"`: Run hybrid semantic and keyword search.
- `mlva "<query>" --lang <lang>`: Filter or boost by programming language (e.g., `python`, `java`, `cpp`).
- `mlva "<query>" --ext <ext>`: Filter strictly by file extension (e.g., `py`, `java`, `sql`).
- `mlva show <index>`: Inspect complete code in terminal with syntax highlighting and line numbers.
- `mlva show <index> --lines <start-end>`: Display specific line range.
- `mlva code <index>`: Open selected result in Visual Studio Code.
- `mlva open <index>`: Open result in operating system default application.
- `mlva reveal <index>`: Reveal file in native file manager (Finder / File Explorer).
- `mlva copy <index>`: Copy full file content to system clipboard.
- `mlva index <path>`: Recursively index custom local directory into SQLite.
- `mlva status`: View database statistics and model cache status.
- `mlva sync`: Re-synchronize local database from bundled content manifest.
- `mlva bridge`: Start background sync bridge on 127.0.0.1:28282 for web app integration.