Full-stack AI assistant with Retrieval-Augmented Generation, local LLM inference via llama-cpp, and a NiceGUI web UI — designed to run entirely offline.

• Local LLM inference — llama-cpp server with auto-model discovery and GPU/CPU selection
• RAG pipeline — BGE embeddings, semantic chunking, Qdrant vector search, layout-aware PDF parsing
• Enhanced RAG Pipeline — 22+ SOTA modules with adaptive query routing (see Core Modules)
• Multi-format ingestion — PDF, DOCX, XLSX, web pages, code files (30+ types)
• NiceGUI UI — dark mode, RAG badges, chat interface, settings sidebar, pipeline selector
• Pre-flight validation — auto-checks binary, models, and dependencies on startup
• Multi-model support — auto-discovers GGUF models, switch models live
• Zena AI personality — customizable AI assistant with enhanced capabilities
• RAG Test Bench — lightweight Flask app for A/B testing RAG pipelines side-by-side

# Install dependencies
pip install -r requirements.txt

# Launch (auto-validates and starts llama-cpp server + NiceGUI UI)
python start_llm.py

Or use the batch/shell scripts:

# Windows
Run_Me.bat

# Linux/macOS
./Run_Me.sh

start_llm.py                     # Entry point — delegates to zena_mode/server.py
zena.py                          # NiceGUI chat application (main UI)
zena_mode/
├── server.py                    # Orchestrator: model engines, health checks, HTTP endpoints
├── rag_manager.py               # Thread-safe RAG state proxy (uses RLock)
config.py                        # Configuration management (ports, model paths, dirs)
model_manager.py                 # Model discovery and hot-swap

The enhanced RAG pipeline consists of 22+ industry-best modules orchestrated by EnhancedRAGService:

Query → QueryRewriter → QueryRouter → [Strategy Selection]
                                         │
                    ┌────────────────────┤
                    ▼                    ▼
              Simple Path          Analytical Path
              (fast)               (full SOTA)
                    │                    │
                    ▼                    ▼
              Retrieve            HyDE + Retrieve
                    │                    │
                    └────────┬───────────┘
                             ▼
                    Parent Document Expand
                             ▼
                    Smart Deduplicator
                             ▼
                    Advanced Reranker
                             ▼
                    Conflict Detector
                             ▼
                    Contextual Compressor
                             ▼
                    Corrective RAG (CRAG)
                             ▼
                    FLARE (if uncertain)
                             ▼
                    LLM Generate Answer
                             ▼
                    Post-Processing:
                    ├── Hallucination Detection
                    ├── Confidence Scoring
                    ├── Follow-Up Generation
                    └── Metrics Recording

• Pipeline selector: Choose between Standard RAG and Enhanced (SOTA) pipeline
• Live metadata display: Routing intent, pipeline stages, latency, confidence score, hallucination probability
• CRAG feedback: Retrieval grade and corrections applied
• FLARE status: Iteration count and sub-queries generated
• Conflict alerts: Cross-source contradictions detected
• Follow-up suggestions: Context-aware next questions

# All tests (uses the test runner with server lifecycle management)
python run_tests.py

# Core module tests only (94 tests, fast)
python -m pytest tests/test_core_modules.py -v

# Enhanced RAG integration tests (38 tests)
python -m pytest tests/test_enhanced_rag.py -v

# Deep audit tests — KnowledgeGraph, Pydantic models, pipeline integration (67 tests)
python -m pytest tests/test_deep_audit.py -v

# All three test suites (199 tests)
python -m pytest tests/test_core_modules.py tests/test_enhanced_rag.py tests/test_deep_audit.py -v

# With coverage
python run_tests.py --coverage

• llama-cpp-python — local GGUF model inference
• nicegui — web UI
• sentence-transformers — BGE embeddings + cross-encoder reranking
• qdrant-client — vector database
• beautifulsoup4, PyMuPDF — document parsing
• pydantic — data validation for RAG models
• psutil — process/memory monitoring for inference guard

• config.py / config.json — Ports (default engine: 8001), model paths, directories
• settings.json — User preferences (theme, voice, RAG settings)
• data/custom_prompts.json — User-created prompt templates

Run locally: python -m xray . --dry-run

MIT