# MLVA: Complete Technical & Command Reference (Unabridged)

## 1. Product Overview
- **Name**: MLVA (Machine Learning Virtual Assistant)
- **Tagline**: AI-Powered Local File Search and Command-Line Interface
- **Official Website**: [https://mlva.web.app/](https://mlva.web.app/)
- **Official npm Package**: [https://www.npmjs.com/package/mlva-cli](https://www.npmjs.com/package/mlva-cli)
- **System Architecture**: [https://mlva.web.app/architecture](https://mlva.web.app/architecture)
- **Tool Comparisons**: [https://mlva.web.app/comparisons](https://mlva.web.app/comparisons)
- **Developer Tutorials**: [https://mlva.web.app/tutorials](https://mlva.web.app/tutorials)
- **Version**: 2.0.3
- **License**: MIT
- **Architecture**: Hybrid BM25 Lexical + Dense 384-Dimensional Semantic Embeddings + SQLite Local Database

## 2. Problem Statement & Architecture
Traditional terminal tools like `grep` or `find` only perform exact literal string or regex matching. They fail when a user describes what code or notes do conceptually (e.g. "Find Python code for adding two numbers" or "Matrix multiplication in Java").

MLVA solves this by building a local vector and keyword index:
1. **Embedding Engine**: `@xenova/transformers` running the `all-MiniLM-L6-v2` ONNX model locally on CPU via ONNX Runtime. No external OpenAI, Anthropic, or cloud API calls are made.
2. **Lexical Engine**: BM25 algorithm with coordination matching and fuzzy fallback.
3. **Storage Engine**: SQLite database stored locally in `~/.mlva/mlva.db` (leveraging `better-sqlite3` on desktop/CLI and OPFS/Dexie on the web).
4. **Task & Language Intent**: Calibrated relevance scoring that recognizes language keywords (`python`, `java`, `cpp`, etc.) and task verbs (`adding`, `multiplication`, `clustering`) to suppress false positives.
5. **Privacy Assurance**: All file indexing, embeddings, and query searches are processed 100% locally on the user's computer. No user documents or search queries are ever uploaded.

## 3. Getting Started Workflow
1. Visit the official MLVA Web App: https://mlva.web.app/
2. Sign in to authorize and initiate the automatic seed index download to your local device.
3. Install the MLVA CLI in your terminal:
   ```bash
   npm install -g mlva-cli
   # On macOS/Linux with default Node.js pkg installer, use sudo if permissions error occurs:
   # sudo npm install -g mlva-cli
   ```
   Or run without installing:
   ```bash
   npx mlva-cli setup
   npx mlva-cli "search query"
   ```
4. Run first-time initialization:
   ```bash
   mlva setup
   ```
5. Search your files:
   ```bash
   mlva "Find Python code for linear regression"
   ```

## 4. Full CLI Command Specification

### `mlva "<query>" [flags]`
Performs a hybrid search across all indexed files.
- **Flags**:
  - `--lang <language>`: Filter or boost results by programming language (e.g., `python`, `java`, `javascript`, `cpp`).
  - `--ext <extension>`: Strict filter by file extension without dot (e.g., `py`, `java`, `sql`, `md`).
  - `-v, --version`: Print installed MLVA version.
  - `-h, --help`: Display command options and examples.

### `mlva show <index> [--lines <start-end>]`
Displays full source code of the numbered result from the most recent search.
- Preserves exact indentation, tabs, and Unicode characters.
- Highlights syntax according to file extension.
- Supports paging through terminal pager (`less` or fallback).
- `--lines 1-50`: View a specific line range.

### `mlva code <index>`
Opens the selected file directly in Visual Studio Code (`code <path>`).

### `mlva open <index>`
Opens the selected file in the operating system's default viewer (`open` on macOS, `start` on Windows, `xdg-open` on Linux).

### `mlva reveal <index>`
Reveals the selected file in the native file manager (macOS Finder, Windows File Explorer, or Linux desktop file manager).

### `mlva copy <index>`
Streams the full content of the selected file into the system clipboard (`pbcopy`, `clip.exe`, or `wl-copy`/`xclip`).

### `mlva index <path>`
Recursively walks and indexes a user-specified folder or single file into the SQLite database. Generates 384-dimensional dense vectors and keyword chunks.

### `mlva status`
Displays SQLite database statistics (document count, chunk count, file size), registered folder roots, and model cache status (`~/.cache/xenova`).

### `mlva sync` (or `-y`)
Re-synchronizes the database from the pre-bundled content manifest.

### `mlva bridge` (or `-b`)
Starts a lightweight local HTTP synchronization server on `127.0.0.1:28282` allowing the browser-based MLVA web application to communicate securely with the local desktop CLI.

### `mlva clear` (or `--clear`)
Removes the saved search state file (`~/.mlva/last_search.json`). Does not delete indexed documents or database records.

### `mlva uninstall`
Launches an interactive safe uninstaller:
- Option A: Unlinks global CLI symlinks while preserving local database and model weights.
- Option B: Full purge of `~/.mlva` data directory, model caches, and CLI symlinks. Never deletes user-indexed original files.

## 5. Troubleshooting & FAQ
- **EACCES Permission Denied on macOS/Linux**:
  Occurs because the default nodejs.org installer owns `/usr/local/lib/node_modules` with root permissions. Fix by using `sudo npm install -g mlva-cli`, switching to `npx mlva-cli`, or configuring a user prefix `npm config set prefix ~/.npm-global`.
- **Command Not Found**:
  Ensure npm's global bin directory is in your shell PATH (`export PATH=$(npm prefix -g)/bin:$PATH`).
- **Offline Execution**:
  MLVA requires an active internet connection only during initial `npm install` and the first `mlva setup` run (to download the 23MB ONNX model weights). All subsequent queries and indexing run 100% offline.