Skip to content

Commit f98f077

Browse files
SourasishBasuSourasishBasu
committed
docs: added setup and usage info
1 parent eb5a7fe commit f98f077

File tree

4 files changed

+148
-13
lines changed

4 files changed

+148
-13
lines changed

‎README.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# RAGnarok
2+
> RAG powered research and documentation assistant for professionals
3+
4+
---
5+
6+
### Tech Stack
7+
![NextJs](https://img.shields.io/badge/Nextjs-black?style=for-the-badge&logo=nextdotjs&logoColor=white)
8+
![Python](https://img.shields.io/badge/Python-blue?style=for-the-badge&logo=python&logoColor=white)
9+
![FastAPI](https://img.shields.io/badge/FastAPI-009688.svg?style=for-the-badge&logo=FastAPI&logoColor=white)
10+
![AstraDB](https://img.shields.io/badge/astradb-3b0764?style=for-the-badge&logo=expo&logoColor=b85930)
11+
![Docker](https://img.shields.io/badge/docker-%230db7ed.svg?style=for-the-badge&logo=docker&logoColor=white)
12+
![Gemini](https://img.shields.io/badge/gemini-8E75B2?style=for-the-badge&logo=google%20gemini&logoColor=white)
13+
![Bun](https://img.shields.io/badge/Bun-000000.svg?style=for-the-badge&logo=Bun&logoColor=white)
14+
![GitHub Actions](https://img.shields.io/badge/github%20actions-%232671E5.svg?style=for-the-badge&logo=githubactions&logoColor=white)
15+
![Ollama](https://img.shields.io/badge/Ollama-FFF.svg?style=for-the-badge&logo=Ollama&logoColor=black)
16+
![Caddy](https://img.shields.io/badge/Caddy-1F88C0.svg?style=for-the-badge&logo=Caddy&logoColor=white)
17+
![UV](https://img.shields.io/badge/uv-DE5FE9.svg?style=for-the-badge&logo=uv&logoColor=white)
18+
![DigitalOcean](https://img.shields.io/badge/DigitalOcean-0080FF.svg?style=for-the-badge&logo=DigitalOcean&logoColor=white)
19+
20+
## Overview
21+
22+
RAGnarok is a full-stack, retrieval-augmented generation (RAG) system that lets you:
23+
24+
1. **Ingest** arbitrary documents pertaining to diverse professions into a vector store
25+
2. **Serve** a REST API that retrieves relevant passages and generates answers via
26+
3. **Interact** through a modern NextJS based chat UI
27+
4. **Deploy** the entire stack using Docker Compose onto the cloud or self host locally
28+
29+
The project consists of four main components:
30+
31+
- **Ingestion Pipeline**
32+
Reads documents (PDFs, text, markdown), splits and vectorizes them, and stores embeddings in a vector database (e.g. Pinecone, Weaviate).
33+
34+
- **Backend API**
35+
A FastAPI service exposing endpoints for querying the vector store, invoking SoTa LLMs such as Deepseek, and streaming chat responses.
36+
37+
- **Frontend UI**
38+
A NextJS + Typescript chat interface that calls the Backend API for conversational RAG.
39+
40+
- **Deployment Manifests**
41+
Dockerfiles and Docker Compose manifests to deploy entire project locally or in the cloud.
42+
43+
![System Architecture](assets/arch.jpeg)
44+
45+
## Prerequisites
46+
47+
- **Docker & Docker Compose**
48+
- **Node.js** (v20+) and **Bun**
49+
- **Python** (v3.11+)
50+
- **LLM API key** (Groq, Gemini, etc.)
51+
- **[AstraDB](https://www.datastax.com/lp/vector-database) Vector database credentials**
52+
53+
## Project Structure
54+
```
55+
.
56+
├───.github
57+
│ └───workflows
58+
├───assets
59+
├───backend
60+
│ └───app
61+
│ ├───models
62+
│ ├───routes
63+
│ ├───services
64+
│ └───utils
65+
├───deployment
66+
├───frontend
67+
│ ├───public
68+
│ └───src
69+
│ ├───app
70+
│ │ └───test
71+
│ ├───components
72+
│ │ └───ui
73+
│ ├───context
74+
│ └───lib
75+
└───ingestion-pipeline
76+
77+
20 directories, 65 files
78+
```
79+
80+
81+
## Setup
82+
83+
1. **Clone the repo**
84+
```bash
85+
git clone https://github.com/3xCaffeine/rag.git
86+
cd rag
87+
```
88+
2. Configure environment variables
89+
90+
Copy the example `.env.example` into each service folder and add the API keys, URLs and AstraDB database credentials.
91+
92+
3. Build & run with Docker Compose
93+
94+
```
95+
docker-compose up -d
96+
```
97+
> [!NOTE]
98+
> In case GPU support is unavailable on the machine, utilize a hosted text embedding model (OpenAI Ada, Jina AI, Cohere etc.) and remove the Ollama section from the Compose config.
99+
100+
4. (Optional) For remote deployment with custom domains, configure the `deployment/Caddyfile` otherwise remove the Caddy section from Compose configuration.
101+
102+
### Expected Result
103+
104+
```bash
105+
$ docker compose ps
106+
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
107+
backend-api-1 ragbackend:latest "fastapi run app/mai…" api 3 minutes ago Up 3 minutes (healthy) 0.0.0.0:8000->8000/tcp
108+
ollama ollama/ollama:latest "/bin/sh ./run_model…" ollama 9 seconds ago Up 9 seconds 0.0.0.0:11434->11434/tcp
109+
```
110+
111+
## Usage
112+
113+
Visit Ragnarok chat at http://localhost:3000.
114+
115+
116+
#### Demo
117+
118+
119+
120+
## Authors
121+
This project was built for the AISoC Chronos Hackathon 2025 by the 3xCaffeine team.
122+
123+
- Sourasish Basu ([@SourasishBasu](https://github.com/SourasishBasu))
124+
- Swapnil Dutta ([@rycerzes])(https://github.com/rycerzes)
125+
- Vaibhav Singh ([@monkeplication])(https://github.com/monkeplication)
126+
127+
## Version
128+
| Version | Date | Comments |
129+
| ------- | ------------------- | --------------- |
130+
| 1.0 | May 14th, 2025 | Revised release |

‎deployment/docker-compose.yml‎

Lines changed: 14 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,17 @@
11
---
22
services:
3+
api:
4+
image: ghcr.io/3xCaffeine/rag-backend:latest
5+
container_name: api
6+
restart: unless-stopped
7+
env_file:
8+
- .env
9+
expose:
10+
- "8000"
11+
ports:
12+
- "8000:8000"
13+
14+
# Add below section to use Caddy as a reverse proxy with custom domains
315
caddy:
416
image: caddy:latest
517
restart: unless-stopped
@@ -11,15 +23,8 @@ services:
1123
- ./Caddyfile:/etc/caddy/Caddyfile
1224
- caddy_data:/data
1325

14-
api:
15-
image: ghcr.io/3xCaffeine/rag-backend:latest
16-
container_name: api
17-
restart: unless-stopped
18-
env_file:
19-
- .env
20-
expose:
21-
- "8000"
22-
26+
27+
# Add the service below to run Nomic text embedding model via Ollama if machine has GPU support
2328
ollama:
2429
container_name: ollama
2530
tty: true

backend/env.example renamed to deployment/env.example

File renamed without changes.

ingestion-pipeline/test_medical.ipynb renamed to ingestion-pipeline/test_pipeline.ipynb

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@
4242
},
4343
{
4444
"cell_type": "code",
45-
"execution_count": 3,
45+
"execution_count": null,
4646
"metadata": {},
4747
"outputs": [
4848
{
@@ -62,7 +62,7 @@
6262
],
6363
"source": [
6464
"# load documents\n",
65-
"documents = SimpleDirectoryReader(\"./data/medical/\").load_data(num_workers=10)\n",
65+
"documents = SimpleDirectoryReader(\"./data/paul_graham/\").load_data(num_workers=10)\n",
6666
"print(f\"Total documents: {len(documents)}\")\n",
6767
"print(f\"First document, id: {documents[0].doc_id}\")\n",
6868
"print(f\"First document, hash: {documents[0].hash}\")\n",
@@ -103,7 +103,7 @@
103103
},
104104
{
105105
"cell_type": "code",
106-
"execution_count": 7,
106+
"execution_count": null,
107107
"metadata": {},
108108
"outputs": [
109109
{
@@ -128,7 +128,7 @@
128128
"llm = Groq(model=\"deepseek-r1-distill-llama-70b\", api_key=groq_api_token)\n",
129129
"\n",
130130
"query_engine = index.as_query_engine(llm=llm)\n",
131-
"response = query_engine.query(\"A BRIEF REVIEW OF THE FATTY LIVER DISEASE\")\n",
131+
"response = query_engine.query(\"A BRIEF REVIEW OF THE ESSAY\")\n",
132132
"\n",
133133
"print(response.response)"
134134
]

0 commit comments

Comments
 (0)