BobAi 4166d0a362 Initial release: FSS-Mini-RAG - Lightweight semantic code search system

🎯 Complete transformation from 5.9GB bloated system to 70MB optimized solution

✨ Key Features:
- Hybrid embedding system (Ollama + ML fallback + hash backup)
- Intelligent chunking with language-aware parsing
- Semantic + BM25 hybrid search with rich context
- Zero-config portable design with graceful degradation
- Beautiful TUI for beginners + powerful CLI for experts
- Comprehensive documentation with 8+ Mermaid diagrams
- Professional animated demo (183KB optimized GIF)

🏗️ Architecture Highlights:
- LanceDB vector storage with streaming indexing
- Smart file tracking (size/mtime) to avoid expensive rehashing
- Progressive chunking: Markdown headers → Python functions → fixed-size
- Quality filtering: 200+ chars, 20+ words, 30% alphanumeric content
- Concurrent batch processing with error recovery

📦 Package Contents:
- Core engine: claude_rag/ (11 modules, 2,847 lines)
- Entry points: rag-mini (unified), rag-tui (beginner interface)
- Documentation: README + 6 guides with visual diagrams
- Assets: 3D icon, optimized demo GIF, recording tools
- Tests: 8 comprehensive integration and validation tests
- Examples: Usage patterns, config templates, dependency analysis

🎥 Demo System:
- Scripted demonstration showing 12 files → 58 chunks indexing
- Semantic search with multi-line result previews
- Complete workflow from TUI startup to CLI mastery
- Professional recording pipeline with asciinema + GIF conversion

🛡️ Security & Quality:
- Complete .gitignore with personal data protection
- Dependency optimization (removed python-dotenv)
- Code quality validation and educational test suite
- Agent-reviewed architecture and documentation

Ready for production use - copy folder, run ./rag-mini, start searching\!

2025-08-12 16:38:28 +10:00

2.2 KiB

Raw Blame History

🚀 FSS-Mini-RAG: Get Started in 2 Minutes

Step 1: Install Everything

./install_mini_rag.sh

That's it! The installer handles everything automatically:

Checks Python installation
Sets up virtual environment
Guides you through Ollama setup
Installs dependencies
Tests everything works

Step 2: Use It

TUI - Interactive Interface (Easiest)

./rag-tui

Perfect for beginners! Menu-driven interface that:

Shows you CLI commands as you use it
Guides you through setup and configuration
No need to memorize commands

Quick Commands (Beginner-Friendly)

# Index any project
./run_mini_rag.sh index ~/my-project

# Search your code  
./run_mini_rag.sh search ~/my-project "authentication logic"

# Check what's indexed
./run_mini_rag.sh status ~/my-project

Full Commands (More Options)

# Basic indexing and search
./rag-mini index /path/to/project
./rag-mini search /path/to/project "database connection"

# Enhanced search with smart features
./rag-mini-enhanced search /path/to/project "UserManager"
./rag-mini-enhanced similar /path/to/project "def validate_input"

What You Get

Semantic Search: Instead of exact text matching, finds code by meaning:

Search "user login" → finds authentication functions, session management, password validation
Search "database queries" → finds SQL, ORM code, connection handling
Search "error handling" → finds try/catch blocks, error classes, logging

Installation Options

The installer offers two choices:

Light Installation (Recommended):

Uses Ollama for high-quality embeddings
Requires Ollama installed (installer guides you)
Small download (~50MB)

Full Installation:

Includes ML fallback models
Works without Ollama
Large download (~2-3GB)

Troubleshooting

"Python not found": Install Python 3.8+ from python.org "Ollama not found": Visit https://ollama.ai/download "Import errors": Re-run ./install_mini_rag.sh

Next Steps

Technical Details: Read README.md
Step-by-Step Guide: Read docs/GETTING_STARTED.md
Examples: Check examples/ directory
Test It: Run on this project: ./run_mini_rag.sh index .

Questions? Everything is documented in the README.md file.

2.2 KiB Raw Blame History