QUICKSTART

1-Line Setup & CLI Installation

Mi:RAG is a local document search and question answering tool. It indexes PDFs, Word documents, and images directly on your machine, extracts diagrams and figures, and answers questions using local Ollama models and ChromaDB vector search. Optional cloud API connections (OpenAI, Gemini, Claude, Groq) are also supported.

Windows 1-Line Installer

# Run in PowerShell (Windows 10 or 11)
irm https://mirag.me/install | iex

Linux & macOS 1-Line Installer

# Run in Terminal (Ubuntu, Debian, Fedora, Arch, macOS)
curl -fsSL https://mirag.me/install.sh | bash

Instant Launch: Global 'mirag' Command

After the first run, the installer registers the mirag command in your terminal's PATH. You can launch your studio anytime from any directory:

# Launch Mi:RAG Studio from any terminal (PowerShell, CMD, Bash, Zsh)
mirag

Manual Installation (Git / All Platforms)

# Clone and start the factory server
git clone https://github.com/AryanSingh64/Mi-RAG.git
cd Mi-RAG
pip install -r requirements.txt
python run_factory.py

Automatic Hardware Check

Detects available NVIDIA VRAM, Apple Silicon MPS, or CPU cores to configure quantization.

Local Weight Caching

Downloads lightweight on-device embedding weights (all-MiniLM-L6-v2, 80MB) once.

Instant Browser Launch

Launches the factory web studio on http://localhost:8000 automatically.

SYSTEM ARCHITECTURE

6-Level Pipeline Lifecycle

Mi:RAG uses a 6-level pipeline engineered to extract textual passages, mathematical formulas, and visual diagrams without external cloud dependencies:

1. INGESTION  : PDF / Word / Images -> PyMuPDF Vector & Raster Extraction (>80px) + RapidOCR
2. CHUNKING   : Recursive Chunker (~400 chars) + Proximity Window Regex Caption Binding
3. INDEXING   : SentenceTransformers (768-dim) in ChromaDB + Perceptual Hashes (pHash/dHash)
4. RETRIEVAL  : ChromaDB Dense Vector Search + BM25 Lexical Scoring + Reverse Image Matching
5. GUARDRAILS : Content Word Lexical Check + Anisotropy-Aware Cosine Similarity Refusal Gate
6. SYNTHESIS  : Local Ollama LLM (Llama 3.2 / Qwen 2.5) + Grounded Inline Citations & Diagrams

Production Optimization Blueprint

Comparison between current prototype heuristics and target production standards for enterprise deployments:

Level	Current Implementation	Production Blueprint	Primary Failure Mode Addressed
1. Ingestion	PyMuPDF coordinates + regex window	Docling (RT-DETR + TableFormer) / MinerU	Reading order inversions & fragmented vector plots
2. Chunking	Fixed 400-char recursive splitting	Parent-Child (128/1024) / Late Chunking (Jina 8k)	Mid-argument fragmentation & pronoun context loss
3. Visual Index	Perceptual hash (pHash/dHash)	Unified Latent Space (SigLIP / ColPali ViT)	Inability to perform text-to-image semantic queries
4. Retrieval	Ad-hoc linear scoring combination	Reciprocal Rank Fusion (RRF) + Cross-Encoder	Metric scale distortion & lack of full cross-attention
5. Guardrails	Literal word match + static cosine cutoff	Calibrated Z-Score + NLI Entailment (HHEM-2.1)	Anisotropy noise leaks & false paraphrase rejections
6. Synthesis	Local 3B models + heuristic self-eval	Qwen-2.5-14B/VL + Atomic Claim Attribution	Chart misreads & self-reinforcing evaluation bias

COMPUTE PROFILING

Hardware Auto-Tuning

Rather than failing on resource-constrained machines, the hardware engine automatically scales quantization and model parameters to fit your machine's exact specifications:

High VRAM (>= 12GB)

Runs Qwen2.5 (7B / 14B) with full context windows and high-resolution visual processing.

Mid-Range (6GB - 11GB)

Selects Llama3.2 (3B) with Q4_K_M quantization for rapid inference and low memory overhead.

CPU Only / Ultrabook

Employs CPU ONNX runtime, multi-threaded batching, and lightweight 1.5B/3B models.

EMBEDDINGS

Dense Embedding Models Guide

Select the optimal dense vector embedding model for your specific document corpus and hardware profile:

When to Use	Model ID	Vector Dim	Optimization Target
Best Overall	BAAI/bge-base-en-v1.5	768-dim	Default recommendation. SOTA MTEB retrieval accuracy for standard documents, technical manuals, and general corpora.
Fastest	all-MiniLM-L6-v2	384-dim	Ultra-fast CPU indexing with minimal memory footprint. Best for rapid prototyping or lower-spec hardware.
Multilingual	BAAI/bge-m3	1024-dim	Multi-lingual support across 100+ languages with extended 8192-token context window for long-document attention.
Deep Research	BAAI/bge-large-en-v1.5	1024-dim	Maximum semantic precision for dense academic research papers, legal contracts, and engineering specifications.
Long Documents	nomic-ai/nomic-embed-text-v1.5	768-dim	Full-chapter retrieval with 8192-token attention span and Matryoshka dimensionality support.

MULTIMODAL

High-Recall Multimodal Parser

Standard RAG solutions discard charts, flowcharts, and diagrams by stripping documents to raw text. Mi:RAG uses a high-recall multi-mode extractor supporting raster images, vector drawings, and embedded office graphics:

Vector Drawing Plots & Charts

Isolates and renders canvas drawing paths directly from research and technical PDFs (e.g. arXiv / IEEE papers).

Proximity Caption Alignment

Matches diagram bounding boxes to nearby figure captions (e.g. Figure 2: Architecture Overview).

Embedded Word (.docx) Media

Extracts and indexes embedded graphics and images packaged within Microsoft Word documents.

Reverse Visual Search

Allows users to paste or upload an image (Ctrl+V) to find matching diagrams and formulas across documents.

PRIVACY & GUARDRAILS

Anti-Hallucination & Local-First Privacy

Cloud models frequently reject sensitive or proprietary documents due to third-party data transmission policies. Mi:RAG provides a local-first pipeline where document chunking, visual layout detection, and vector indexing always remain private on your machine, with optional BYOK cloud models for synthesis.

Anti-Hallucination Verification

Every generated response is cross-checked against retrieved source chunks. Answers unsupported by source text are flagged with confidence metrics and grounded badges.

DEPLOYMENT

Standalone Package Export

Once your documents are indexed, you can export a self-contained ZIP bundle that can run on other local machines:

What's Inside the Exported Bundle:

vector_db/

Pre-indexed ChromaDB vector database with all document embeddings.

images/

Extracted high-resolution diagram crops and figures ready for visual search.

run.bat & run.sh

1-click launchers with system package cache detection for startup under 0.1s.

server.py & index.html

Standalone FastAPI microservice with persistent LocalStorage auto-save and Quit controls.

Running Your Standalone Package

# On Windows: Double-click or run from terminal
run.bat

# On Linux or macOS:
chmod +x run.sh
./run.sh

DEVELOPERS

REST API Reference

Integrate the Mi:RAG engine into your own frontends, Discord bots, or internal tools using the standard REST API:

Method	Endpoint	Description
POST	`/api/sessions/create`	Creates an isolated RAG session with private vector storage.
POST	`/api/sessions/{id}/upload`	Uploads and parses a PDF, Word document, or image.
POST	`/api/sessions/{id}/chat`	Submits a query with multi-turn memory and diagram matching.
GET	`/api/sessions/{id}/export`	Exports the standalone ZIP package.
POST	`/api/shutdown`	Gracefully stops and halts the local standalone server.