npm package: @pytt0n/moodle-rag
Description: RAG (Retrieval-Augmented Generation) system for Moodle development with Claude Code CLI
Author: pytt0n
Latest version: 1.0.0

# @pytt0n/moodle-rag

🚀 **RAG (Retrieval-Augmented Generation) system for Moodle development with Claude Code CLI**

Enhance your Moodle development workflow with semantic code search, intelligent context retrieval, and AI-powered assistance.

[![npm version](https://img.shields.io/npm/v/@pytt0n/moodle-rag.svg)](https://www.npmjs.com/package/@pytt0n/moodle-rag)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub](https://img.shields.io/badge/GitHub-SuperPiTT-blue.svg)](https://github.com/SuperPiTT/moodle-rag)

---

## ✨ Features

- 🔍 **Semantic Code Search** - Find code by meaning, not just text
- 🤖 **7 AI Agents** - Specialized assistants for Moodle development
- ⚡ **9 Slash Commands** - Powerful development tools
- 📊 **Analytics Dashboard** - Monitor usage and performance
- 🎯 **Smart Commits** - Auto-generate conventional commit messages
- 📝 **Auto Changelog** - Generate changelogs from git history
- 🔄 **Semantic Diff** - Understand code changes by intent
- 💾 **Local & Private** - All processing happens on your machine

---

## 📦 Installation

### Quick Install (Recommended)

```bash
# Navigate to your Moodle project
cd /path/to/your/moodle-project

# Install with one command (that's it!)
npx @pytt0n/moodle-rag install
```

**That's literally it!** No global installations, no complex setup. Just one command.

The installer automatically:
- ✅ Check system requirements (Python 3.8+, disk space)
- ✅ Download and setup the RAG system
- ✅ Create isolated Python virtual environment
- ✅ Install Python dependencies
- ✅ Download embeddings model (~80MB)
- ✅ Index your project (code, docs, tests)
- ✅ Start the RAG service

**Time:** ~10-15 minutes (first time, includes downloads)

### Installation Options

```bash
# Custom port (default: 8000)
npx @pytt0n/moodle-rag install --port 8001

# Skip initial indexing (index later)
npx @pytt0n/moodle-rag install --skip-index

# Force reinstall (skip confirmation)
npx @pytt0n/moodle-rag install --force

# Specify project path
npx @pytt0n/moodle-rag install /path/to/project
```

---

## 🏗️ Architecture - Per-Project Installation

**Each project gets its own independent RAG system.** There is NO shared database between projects.

### How It Works

When you run `npx @pytt0n/moodle-rag install` in a project:

```
/your/project/
  ├── .rag/                        ← Complete RAG system (per-project)
  │   ├── venv/                    ← Isolated Python environment
  │   ├── chromadb_data/           ← Project's vector database
  │   ├── services/                ← RAG service code
  │   ├── config.json              ← Project configuration
  │   └── logs/                    ← Service logs
  └── [your project files]
```

### Multiple Projects Example

```bash
# Project 1: aula-virtual-infra
cd /home/user/aula-virtual-infra
npx @pytt0n/moodle-rag install --port 8000
# → Creates .rag/ with database indexing ONLY aula-virtual-infra code

# Project 2: otro-moodle
cd /home/user/otro-moodle
npx @pytt0n/moodle-rag install --port 8001
# → Creates .rag/ with database indexing ONLY otro-moodle code
```

**Result**: Two completely independent RAG systems, each with its own database and index.

### Command Behavior

Commands like `health`, `query`, and `stats` work on the **current directory's project**:

```bash
# Check health of current project
cd /your/project
npx @pytt0n/moodle-rag health
# → Shows info for /your/project/.rag/

# Query current project
npx @pytt0n/moodle-rag query "How to validate CSV?"
# → Searches only current project's database
```

**The system auto-detects the project from your current working directory.**

---

## 🚀 Quick Start

### 1. Check Health

```bash
npx moodle-rag health
```

### 2. Query the System

```bash
npx moodle-rag query "How to validate CSV files in Moodle?"
```

### 3. View Statistics

```bash
npx moodle-rag stats
```

### 4. Open Dashboard

```bash
# Open in browser
open http://localhost:8000/docs
```

---

## 📚 Usage

### Available Commands

```bash
# Install RAG system
npx moodle-rag install [project-path]

# Check service health
npx moodle-rag health

# Query the system
npx moodle-rag query "your question"

# View statistics
npx moodle-rag stats

# Reindex project
npx moodle-rag reindex

# Uninstall
npx moodle-rag uninstall
```

### Command Options

**Install**
```bash
npx moodle-rag install \
  --port 8000 \
  --layers code,docs,tests \
  --skip-index
```

**Query**
```bash
npx moodle-rag query "your question" \
  -k 10 \
  -t 0.7 \
  -p 8000
```

Options:
- `-k, --top-k` - Number of results (default: 5)
- `-t, --threshold` - Similarity threshold 0-1 (default: 0.7)
- `-p, --port` - Service port (default: 8000)

---

## 🎯 Slash Commands (Claude Code CLI)

Once installed, use these commands in Claude Code:

### `/vuela-impact-analysis <file>`
Analyze the impact of changes to a file
```bash
/vuela-impact-analysis local/sand_bulk_enrollment/validator.php
```

### `/vuela-rag-dashboard`
Show complete RAG system dashboard
```bash
/vuela-rag-dashboard
```

### `/vuela-rag-similar <file>`
Find similar code
```bash
/vuela-rag-similar validator.php
```

### `/vuela-rag-explain <module>`
Explain a Moodle module
```bash
/vuela-rag-explain sand_bulk_enrollment --depth 2
```

### `/vuela-smart-commit`
Generate commit message from staged changes
```bash
git add .
/vuela-smart-commit
```

### `/vuela-changelog <branch>`
Generate changelog from branch
```bash
/vuela-changelog feature/OT-123 --ticket OT-123 --append
```

### `/vuela-rag-diff <branch>`
Semantic diff between branches
```bash
/vuela-rag-diff feature/my-feature main
```

### `/vuela-rag-explore`
Interactive codebase explorer
```bash
/vuela-rag-explore
```

### `/vuela-analytics`
View analytics dashboard
```bash
/vuela-analytics
```

---

## 🤖 AI Agents

The system includes 7 specialized AI agents:

1. **Moodle Development Expert** - Validates Moodle best practices
2. **Playwright Test Specialist** - Suggests automated tests
3. **UI/UX Design Validator** - Validates Bootstrap/WCAG compliance
4. **Architecture Decision Recorder** - Captures technical decisions
5. **Error Pattern Analyzer** - Detects error patterns
6. **Context Recovery** - Recovers session context
7. **Performance Optimizer** - Finds performance issues

---

## 📊 REST API

The RAG service exposes a REST API:

```bash
# Health check
curl http://localhost:8000/health

# Query
curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{"query": "How to validate CSV?", "top_k": 5}'

# Status
curl http://localhost:8000/status

# Reindex
curl -X POST http://localhost:8000/reindex

# Interactive docs
open http://localhost:8000/docs
```

---

## ⚙️ Configuration

Edit `.rag/config.json` to customize:

```json
{
  "project_root": "/path/to/moodle",
  "rag_port": 8000,
  "rag_host": "127.0.0.1",

  "embeddings": {
    "model": "sentence-transformers/all-MiniLM-L6-v2",
    "batch_size": 32
  },

  "chunking": {
    "chunk_size": 1500,
    "chunk_overlap": 200
  },

  "indexing": {
    "excluded_dirs": ["node_modules", "vendor", "backup"],
    "max_file_size_mb": 1
  },

  "rag": {
    "top_k_results": 5,
    "similarity_threshold": 0.7
  }
}
```

After changes, restart the service:
```bash
cd .rag
pkill -f rag_service.py
venv/bin/python3 services/rag_service.py &
```

---

## 🔧 Requirements

- **Python** 3.8+
- **Node.js** 14+ (for npm)
- **Disk Space** 2GB minimum
- **OS** Linux, macOS, or Windows (WSL2)

---

## 📈 Performance

- **Query latency**: 150-250ms average
- **Cache hit rate**: 70-90% after warm-up
- **Indexing speed**: ~11 files/second
- **Memory usage**: 200-400MB (service)
- **Disk usage**: ~100-500MB (index)

---

## 🆘 Troubleshooting

### Service won't start

```bash
# Check logs
tail -f .rag/logs/rag_service.log

# Verify Python
python3 --version  # Should be 3.8+

# Reinstall
npx moodle-rag uninstall --force
npx moodle-rag install
```

### No query results

```bash
# Check index
npx moodle-rag stats

# Lower threshold
npx moodle-rag query "test" -t 0.3

# Reindex
npx moodle-rag reindex
```

### Port already in use

```bash
# Use different port
npx moodle-rag install --port 8001

# Or kill existing process
lsof -i :8000
kill -9 <PID>
```

---

## 📚 Documentation

- **[Installation Guide](./docs/INSTALLATION_GUIDE.md)** - Detailed installation
- **[API Reference](./docs/API_REFERENCE.md)** - REST API documentation
- **[Command Reference](./docs/COMMANDS.md)** - All slash commands
- **[Configuration](./docs/CONFIGURATION.md)** - Configuration options
- **[Architecture](./docs/ARCHITECTURE.md)** - System architecture

---

## 🤝 Contributing

Contributions welcome! Please read our [Contributing Guide](CONTRIBUTING.md) first.

```bash
# Fork the repo
git clone https://github.com/SuperPiTT/moodle-rag.git
cd moodle-rag

# Install dependencies
npm install

# Run tests
npm test

# Submit PR
```

---

## 📝 License

MIT License - see [LICENSE](LICENSE) file for details.

---

## 🙏 Acknowledgments

- Built with [ChromaDB](https://www.trychroma.com/) for vector storage
- Uses [sentence-transformers](https://www.sbert.net/) for embeddings
- Powered by [Claude Code CLI](https://www.anthropic.com/)

---

## 📞 Support

- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/SuperPiTT/moodle-rag/issues)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/SuperPiTT/moodle-rag/discussions)
- 📧 **Email**: Create an issue on GitHub

---

## 🌟 Star Us!

If you find this tool useful, please ⭐ star the repo!

---

**Made with ❤️ by [@pytt0n](https://github.com/SuperPiTT)**