# CognitiveRAG

QMIND CognitiveRAG — a multi-stage Retrieval-Augmented Generation pipeline for multimodal knowledge bases.

## Data Flow

```
00_Data/  (raw files: PDFs, images, audio, video, CSV, ...)
   │
   ▼
01_data_ingestion   →  cleaned_documents.jsonl   (extraction + normalization)
   │
   ▼
02_chunking         →  chunked output             (text segmentation)
   │
   ▼
03_embedding        →  vector embeddings           (dense representations)
   │
   ▼
04_vectordb         →  indexed store               (similarity search)
   │
   ▼
05_generation       →  final answers               (LLM-powered retrieval + response)
```

The backend server (`server.py`) exposes both the `/query` endpoint for the full pipeline and the `/ingestion/*` endpoints for data ingestion with real-time progress.

## Setup

### System Dependencies

```bash
# macOS
brew install tesseract poppler ffmpeg

# Windows (Chocolatey)
choco install tesseract poppler ffmpeg
```

### Python Environment

```bash
# macOS / Linux (Python 3.11 required for audio/video on macOS)
python3.11 -m venv Final_venv
source Final_venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
```

```powershell
# Windows
py -3.11 -m venv Final_venv
.\Final_venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt
```

If you only need a specific stage:

```bash
pip install -r 01_data_ingestion/requirements.txt
pip install -r 04_vectoredb/requirements.txt
pip install -r 05_generation/requirements.txt
```

## Running the Backend

```bash
source Final_venv/bin/activate          # macOS / Linux
uvicorn server:app --reload --port 8000
```

```powershell
.\Final_venv\Scripts\activate           # Windows
uvicorn server:app --reload --port 8000
```

The server exposes:
- `GET /health` — health check
- `POST /query` — run the full RAG pipeline
- `POST /ingestion/start` — start ingestion from a server-side folder
- `POST /ingestion/upload` — upload files (or `.zip`) and start ingestion
- `GET /ingestion/{job_id}/stream` — SSE real-time progress stream
- `GET /ingestion/{job_id}/status` — polling fallback for job progress
- `POST /ingestion/{job_id}/cancel` — cancel a running job

## Data Ingestion

The ingestion pipeline converts files (PDFs, images, audio, video, CSV, etc.) into structured JSONL for the downstream RAG pipeline. It supports multi-threaded parallel processing, real-time SSE progress streaming, file upload (including ZIP), and cooperative job cancellation.

For full architecture details, frontend JavaScript examples, and response schemas, see [`01_data_ingestion/OVERVIEW.md`](01_data_ingestion/OVERVIEW.md).

### CLI Usage

```bash
# Default parallel mode (4 worker threads)
python 01_data_ingestion/ingest_multimodal.py \
  --input 00_Data \
  --output-dir 01_data_ingestion/output

# Custom worker count
python 01_data_ingestion/ingest_multimodal.py \
  --input 00_Data \
  --output-dir 01_data_ingestion/output \
  --workers 8

# Sequential legacy mode (for debugging)
python 01_data_ingestion/ingest_multimodal.py \
  --input 00_Data \
  --output-dir 01_data_ingestion/output \
  --workers 0
```

### HTTP API (with the server running)

```bash
# Start ingestion from a server-side folder
curl -X POST http://localhost:8000/ingestion/start \
  -H "Content-Type: application/json" \
  -d '{"input_dir": "00_Data", "workers": 4}'

# Upload files (including .zip)
curl -X POST http://localhost:8000/ingestion/upload \
  -F "files=@documents.zip"

# Stream real-time progress (SSE)
curl -N http://localhost:8000/ingestion/{job_id}/stream

# Check job status (polling fallback)
curl http://localhost:8000/ingestion/{job_id}/status

# Cancel a running job
curl -X POST http://localhost:8000/ingestion/{job_id}/cancel
```

### Running Tests

```bash
cd 01_data_ingestion
python -m pytest tests/ -v    # 59 tests
```

## Frontend (React / Vite)

The frontend is in a separate `oracle-insights` repository and communicates with the backend via the `/query` and `/ingestion/*` endpoints.

```bash
cd oracle-insights
npm run dev
```

For frontend integration examples (JavaScript `EventSource`, `fetch()`, response schemas), see the [Frontend Integration Guide](01_data_ingestion/OVERVIEW.md#2-frontend-integration-guide) in `01_data_ingestion/OVERVIEW.md`.