Raggy

Mathis1993
1

Raggy - RAG System with Svelte, Django and Milvus

Raggy - Learning RAG System with LlamaIndex and Milvus

Raggy is a learning-focused Retrieval-Augmented Generation (RAG) system built to understand the fundamentals of modern AI applications. This side project was created to practice and explore:

RAG Architecture: How retrieval-augmented generation works in practice
Vector Databases: Using Milvus for efficient similarity search and storage
Embeddings: Understanding how documents are chunked, embedded, and retrieved
Frontend Development: Learning Svelte as a modern frontend framework
Source Attribution: Implementing proper quote extraction and source linking

Note: This is a learning project, not production-ready software. The focus is on understanding RAG concepts, embeddings, and vector search rather than building a polished application.

🎯 Project Goals

Educational: Deep dive into RAG systems, vector databases, and embeddings
Hands-on Learning: Practical experience with LlamaIndex, Milvus, and Svelte
Concept Understanding: Learn how source attribution and quote extraction work
Modern Stack: Explore contemporary AI development tools and practices

✨ Features

Core RAG Functionality

Document Processing: Upload and process various document types (PDF, Word, text, websites)
Intelligent Chunking: Smart document splitting with configurable chunk sizes and overlap
Embedding Generation: Create vector embeddings using sentence-transformers
Vector Search: Efficient similarity search using Milvus vector database
Context Retrieval: Retrieve relevant document chunks for question answering

Conversation & Chat

Conversation Memory: Maintain chat history and context across sessions
Source Attribution: Show which documents were used to answer questions
Quote Extraction: Display relevant quotes from source documents
Multi-turn Conversations: Support for follow-up questions and clarifications

User Experience

Modern UI: Clean, responsive interface built with Svelte and Tailwind CSS
Real-time Chat: Interactive chat interface with typing indicators
Document Management: Upload, view, and manage your knowledge base
Source Visualization: See which documents contributed to each answer

🏗️ Project Structure

raggy/
├── backend/                    # Django backend application
│   ├── manage.py              # Django management script
│   ├── backend/               # Django project configuration
│   ├── conversations/         # Chat and conversation handling
│   │   ├── engine.py         # LlamaIndex chat engine
│   │   └── models.py         # Conversation and message models
│   ├── knowledge_base/        # Document processing and vector storage
│   │   ├── extractors/       # Document content extractors
│   │   ├── ingestion/        # Document ingestion pipeline
│   │   └── vector_store.py   # Milvus vector store integration
│   ├── users/                # User authentication and management
│   └── core/                 # Core utilities and Celery tasks
├── frontend/                  # Svelte frontend application
│   ├── src/
│   │   ├── components/       # Reusable UI components
│   │   ├── routes/           # SvelteKit routes and pages
│   │   ├── stores/           # State management
│   │   └── types/            # TypeScript type definitions
│   └── package.json          # Frontend dependencies
├── compose.yml         # Docker services configuration
├── pyproject.toml            # Python dependencies
└── README.md                 # This file

🛠️ Technology Stack

Backend

Django 5.1: Web framework and API
Django REST Framework: RESTful API development
LlamaIndex: RAG framework for document processing and retrieval
Milvus: Vector database for similarity search
Celery: Asynchronous task processing
PostgreSQL: Primary database
Redis: Caching and message broker

Frontend

SvelteKit: Modern frontend framework
TypeScript: Type-safe JavaScript
Tailwind CSS: Utility-first CSS framework
Flowbite: UI component library
Vite: Build tool and dev server

Infrastructure

Docker: Containerization
Milvus: Vector database (standalone mode)
MinIO: Object storage for Milvus
Etcd: Metadata storage for Milvus

🚀 Setup Instructions

Prerequisites

Docker and Docker Compose
Python 3.12+
Node.js 18+
uv (Python package installer)

1. Clone and Setup

git clone <repository-url>
cd raggy

2. Install uv (Python Package Manager)

# Using curl (Linux/macOS)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or using Homebrew (macOS)
brew install uv

3. Configure Environment

Copy the .env-sample as .env and enter your secrets (particularly an OpenAI API key, a Sendgrid API key for email communication is optional) inside the backend directory.

4. Setup Python Environment

# Create virtual environment and install dependencies
uv venv
uv sync

# Activate virtual environment (optional)
source .venv/bin/activate  # On Unix/macOS
# or
.venv\Scripts\activate     # On Windows

5. Start Infrastructure Services

# Start all required services
docker compose up -d

# Verify services are running
docker compose ps

This starts:

PostgreSQL (port 5432)
Redis (port 6379)
Milvus (port 19530)
Milvus Attu UI (port 3000) - Vector database management
MinIO (ports 9000, 9001) - Object storage
Etcd - Metadata storage

6. Initialize Database

cd backend

# Run migrations
uv run python manage.py migrate

# Create superuser
uv run python manage.py createsuperuser

7. Start Backend Services

# Terminal 1: Start Django server
cd backend
uv run python manage.py runserver

# Terminal 2: Start Celery worker
cd backend
uv run celery --app core worker --loglevel=info --concurrency=1 --pool=solo --queues=celery

8. Start Frontend

# Terminal 3: Install dependencies and start dev server
cd frontend
npm install
npm run dev

🌐 Access Points

Frontend Application: http://127.0.0.1:5173 (Svelte dev server)
Django Admin: http://127.0.0.1:8000/admin
Django API: http://127.0.0.1:8000/api
Milvus Attu UI: http://127.0.0.1:3000 (Username: root, Password: milvus)

🔧 Development Workflow

Adding New Dependencies

# Python dependencies
uv add <package-name>

# Frontend dependencies
cd frontend
npm install <package-name>

📚 Learning Resources

RAG and Vector Databases

Frontend Development

🐛 Troubleshooting

Common Issues

Port Conflicts: If you get port conflicts, check if services are already running:
```
docker compose down
docker compose up -d
```
Milvus Connection Issues: Ensure Milvus is fully started:
```
docker compose logs standalone
```
Python Path Issues: Always use the correct PYTHONPATH:
```
uv run python manage.py <command>
```

Stopping Services

# Stop frontend and backend servers (Ctrl+C)
# Stop Docker services
docker compose down

Top categories