🧠 RAGGuide_ (Mini RAG App)

RAGGuide_ is a powerful Retrieval-Augmented Generation (RAG) system designed for:

• Question Answering (Q&A) — providing accurate, context-aware responses to user queries.
• Rule Compliance Evaluation (Judge Mode) — analyzing reports or documents against specified rules and offering structured feedback.

It combines FastAPI, PostgreSQL/pgvector, and Streamlit to create a smart, document-aware conversational system that bridges reasoning and data-driven understanding.

✨ Key Features

• 💬 Q&A Mode – Ask natural-language questions and get accurate, polite, and concise answers.

• ⚖️ Judge Mode – Verify if uploaded reports or ideas comply with specific rules or policies and receive improvement suggestions.

• 🧩 RAG Architecture – Combines vector retrieval with generative reasoning.

• 🚀 FastAPI Backend – High-performance and modular REST API.

• 🎨 Streamlit Frontend – User-friendly web interface for uploading, processing, and querying documents.

• 🐳 Docker Ready – Fully containerized for easy deployment.

• 📊 Monitoring – Integrated Prometheus and Grafana dashboards for performance insights.

Requirements

• Python 3.9+
• PostgreSQL (with pgvector extension) or Qdrant
• Docker
• Conda (recommended for local development)
• VS Code (for editing and debugging)

🧩 Installation Steps

Install Dependencies

sudo apt update
sudo apt install libpq-dev gcc python3-dev

Install Python Using Miniconda

1. Download Miniconda from here

2. Create New Environment using :

   $ conda create -n mini-rag-app-2 python=3.9

3. Activate New Environment using :

   $ conda activate mini-rag-app-2

4. Install packages in requirements.txt:

   $ pip install -r requirements.txt

Setup Your Environment Variables

$ cp .env.example .env

• Then open docker/env/.env.app and configure your keys:

  COHERE_API_KEY="your_cohere_key"
  OPEN_API_KEY="your_openai_key"
  POSTGRES_USERNAME="postgres"
  POSTGRES_PASSWORD="postgres_password"

Run Docker Compose Services

$ cd docker
$ sudo docker compose up

• update .env with your credentials.

Run the FastAPI Backend (Locally)

  $ uvicorn main:app --reload --host 0.0.0.0 --port 5000

Access the API documentation here: http://localhost:8000/docs

💻 Run the Streamlit Interface

  $ streamlit run app.py

🌐 Open in your browser: http://localhost:8501

📊 Grafana Performance Dashboard

• You can monitor application metrics, performance, and API usage using the integrated Grafana dashboard.

(Example view of RAGGuide’s system performance using Grafana and Prometheus integration.)

🧱 Project Structure

RAGGuide_/
├── app.py                          # Streamlit frontend entrypoint
│
├── src/                            # Backend (FastAPI + RAG core logic)
│   ├── main.py                     # FastAPI app entrypoint
│   ├── .env                        # Environment variables for backend
│   ├── .env.example                # Example environment file
│   ├── requirements.txt            # Backend dependencies
│   ├── .gitignore                  # Ignore rules specific to backend development
│   │
│   ├── assets/                     # Static assets or processed data
│   │
│   ├── controllers/                # Core application controllers (business logic)
│   │   ├── __pycache__/
│   │   ├── __init__.py
│   │   ├── BaseController.py       # Common controller base class
│   │   ├── DataController.py       # Handles document ingestion and management
│   │   ├── NLPController.py        # Handles text processing, embeddings, and NLP tasks
│   │   ├── ProcessController.py    # Document preprocessing and cleaning
│   │   └── ProjectController.py    # Manages project-level configurations and workflows
│   │
│   ├── helpers/                    # General-purpose helpers and configurations
│   │   ├── __pycache__/
│   │   ├── __init__.py
│   │   └── config.py               # Global configuration and environment loader
│   │
│   ├── models/                     # Database and Pydantic models
│   │   ├── __pycache__/
│   │   ├── db_schemes/             # Alembic schemas and DB structure
│   │   ├── enum/                   # Enum definitions for model constants
│   │   ├── __init__.py
│   │   ├── AssetModel.py
│   │   ├── BaseDataModel.py
│   │   ├── ChunkModel.py
│   │   └── ProjectModel.py
│   │
│   ├── routes/                     # FastAPI routes (API endpoints)
│   │   ├── __pycache__/
│   │   ├── schemes/                # Request/response schemas for routes
│   │   │   ├── __init__.py
│   │   │   ├── base.py
│   │   │   ├── data.py
│   │   │   └── nlp.py
│   │
│   ├── stores/                     # Data and model storage layer
│   │   ├── llm/                    # Large Language Model integration layer
│   │   │   ├── __pycache__/
│   │   │   ├── providers/          # Specific LLM providers (OpenAI, Cohere, etc.)
│   │   │   │   ├── __pycache__/
│   │   │   │   ├── __init__.py
│   │   │   │   ├── ColHereProvider.py
│   │   │   │   └── OpenAllProvider.py
│   │   │   ├── templates/          # Prompt templates and LLM configuration files
│   │   │   ├── __init__.py
│   │   │   ├── LLMinums.py         # Enum for LLM provider types
│   │   │   ├── LLMInterface.py     # Abstract interface for all LLMs
│   │   │   └── LLMProviderFactory.py # Factory pattern for dynamic provider selection
│   │   │
│   │   └── vectordb/               # Vector database layer (for retrieval)
│   │       ├── __pycache__/
│   │       ├── providers/          # Specific vector DB providers
│   │       │   ├── __pycache__/
│   │       │   ├── __init__.py
│   │       │   ├── PGVectorProvider.py
│   │       │   └── OdrantDBProvider.py
│   │       ├── __init__.py
│   │       ├── VectorDBEnumspy      # Enum definitions for vector DB backends
│   │       ├── VectorDBInterface.py # Interface for all vector DB integrations
│   │       └── VectorDBProviderFactory.py # Factory for vector DB providers
│   │
│   ├── utils/                      # Utility functions and performance metrics
│   │   ├── __pycache__/
│   │   ├── __init__.py
│   │   └── metrics.py              # App-level metrics and monitoring logic
│
├── docker/                         # Docker deployment and orchestration
│   ├── env/                        # Environment configuration files
│   │   ├── .env.app
│   │   ├── .env.example.app
│   │   ├── .env.example.grafana
│   │   ├── .env.example.postgres
│   │   ├── .env.example.postgres-exporter
│   │   ├── .env.grafana
│   │   ├── .env.postgres
│   │   └── .env.postgres-exporter
│   │
│   ├── minirag/                    # FastAPI build context and Alembic migrations
│   │   ├── alembic.ini
│   │   ├── alembic.ini.example
│   │   ├── Dockerfile
│   │   └── entrypoint.sh
│   │
│   ├── nginx/                      # Reverse proxy configuration
│   │   └── default.conf
│   │
│   ├── prometheus/                 # Prometheus configuration for metrics
│   │   └── prometheus.yml
│   │
│   ├── docker-compose.yml          # Multi-container setup (FastAPI, Streamlit, Postgres, Grafana)
│   ├── .gitignore
│   └── README.md
│
├── assets/                         # Data assets or sample files
│
├── Images/                         # Screenshots and monitoring visuals
│   ├── fastapi-grafana.jpg         # Grafana dashboard showing API metrics
│   └── streamlit_interface.jpg     # Streamlit user interface screenshot
│
├── .gitignore                      # Root-level ignore configuration
├── LICENSE                         # MIT License
└── README.md                       # Project documentation

📬 Postman Collection

• You can test all API endpoints using the included Postman collection: Download the Postman collection from ./assets/mini-rag-app.postman_collection.json

🤝 Contributing

Contributions are always welcome..

To contribute to RAGGuide_:

1. Fork the repository.
2. Create a new branch for your feature or fix:

   git checkout -b feature/your-feature-name

3. Commit your changes:

   git commit -m "Add new feature or fix issue"

4. Push to your branch:

   git push origin feature/your-feature-name

5. Open a Pull Request with a clear description of your changes.

📜 License

This project is licensed under the MIT License.
See the LICENSE file for details.

🌟 Note

RAGGuide_ was created to serve as both an educational and deployable Retrieval-Augmented Generation (RAG) system.
It provides a flexible foundation for building intelligent, retrieval-augmented applications that combine reasoning, context awareness, and document understanding.

📧 Contact

For questions, collaborations, or contribution opportunities, feel free to reach out:

• Email: ahmdeltoky4@gmail.com
• LinkedIn: www.linkedin.com/in/ahmed-eltokhy-7a7901383