Cognitive-rag
README.md

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

# macOS
brew install tesseract poppler ffmpeg

# Windows (Chocolatey)
choco install tesseract poppler ffmpeg

Python Environment

# 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

# 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:

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

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

.\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.

CLI Usage

# 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)

# 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

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.

cd oracle-insights
npm run dev

For frontend integration examples (JavaScript EventSource, fetch(), response schemas), see the Frontend Integration Guide in 01_data_ingestion/OVERVIEW.md.

Powered by GitFront