CognitiveRAG Backend

Requirements

Python 3.12

Check your Python version: python --version

---

Setup

1. Go to the backend folder cd backend

2. Create a virtual environment python -m venv .venv

3. Activate the virtual environment

Windows: ..venv\Scripts\Activate.ps1

Mac/Linux: source .venv/bin/activate

1. Install dependencies pip install -r requirements.win.txt

---

Environment Variables

Create a .env file inside the backend folder and add your API keys and configuration. ⚠️ Never commit your .env file to Git. Add the following:

PINECONE_API_KEY=XXXXXXXXXXXXXXXXXXXXXX PINECONE_INDEX_NAME=rag-hybrid-index-v2 SPARSE_INDEX_NAME=rag-sparse-index-v1 PINECONE_CLOUD=aws PINECONE_REGION=us-east-1

AWS_ACCESS_KEY_ID=XXXXXXXXXXXXXXXXXXX AWS_SECRET_ACCESS_KEY=XXXXXXXXXXXXXXX AWS_DEFAULT_REGION=ca-central-1

NVIDIA_API_KEY=XXXXXXXXXXXXXXXXXX EMBEDDING_MODEL=XXXXXXXXXXXXXXXXX

OPENAI_API_KEY=XXXXXXXXXXXXXXXXXXXXXXXX

TOP_K=30 RRF_K=60 RERANKER_ENABLED=true RERANKER_MODEL=cross-encoder/ms-marco-MiniLM-L6-v2 RERANKER_TOP_N=10 MEMORY_BOOST=0.5 MEMORY_MIN_SCORE=0.2 DOC_NAMESPACE= MEMORY_TOP_K=3

Optional

LANGCHAIN_TRACING_V2=true LANGCHAIN_API_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXX LANGCHAIN_PROJECT=CognitiveRAG

---

Run the Backend

uvicorn backend.app:app --reload --port 8000

---

Quick Test

Health check: curl http://localhost:8000/health

Upload a file: curl -X POST http://localhost:8000/kb/upload -F "files=@path/to/file.pdf"

Stream: curl -N http://localhost:8000/kb/<job_id>/stream

Chat request: $r = Invoke-RestMethod -Uri "http://127.0.0.1:8000/chat" -Method POST -ContentType "application/json" ` -Body '{"query":"What is StreamCore?","debug":false,"use_multihop":false}'

$r.answer

Run with curl:

curl -X POST http://localhost:8000/chat
-H "Content-Type: application/json"
-d "{"query":"What is the document about?","debug":false}"

Streaming lets you watch the document processing job in real time. After uploading a file, the backend returns a job_id. Use this job_id with the stream endpoint to see each processing step complete. Once the job finishes, you can ask questions using the /chat endpoint.

Pipeline:

Upload file ↓ Create JOB ↓ Ingest document ↓ Split document into chunks ↓ Generate embeddings for chunks ↓ Upsert embeddings into vector database (dense + sparse) ↓ JOB finished

Then later…

User asks question ↓ Embed the question ↓ Hybrid retrieval from vector database ↓ Select most relevant chunks ↓ Generate answer using retrieved context ↓ Return answer + sources ↓ Store question + answer in conversation memory