# 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

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