Backend API

Startup

1. pip install -r backend/requirements.txt
2. Copy backend/.env.example to backend/.env and fill keys.
3. uvicorn backend.app:app --reload --port 8000

Endpoints

POST /kb/upload

Upload files or zip archives.

Example:

curl -X POST http://localhost:8000/kb/upload \
  -F "files=@C:/path/to/doc1.pdf" \
  -F "files=@C:/path/to/folder.zip"

Response:

{
  "job_id": "a1b2c3d4e5f6",
  "status": "running"
}

GET /kb/{job_id}/stream

Server-Sent Events stream for lifecycle and progress events.

curl -N http://localhost:8000/kb/a1b2c3d4e5f6/stream

Example frontend:

const source = new EventSource("http://localhost:8000/kb/a1b2c3d4e5f6/stream");
source.onmessage = (e) => console.log(e.data);
source.addEventListener("stage_started", (e) => console.log("started", e.data));
source.addEventListener("stage_completed", (e) => console.log("done", e.data));
source.addEventListener("pipeline_failed", (e) => console.log("failed", e.data));

GET /kb/{job_id}/status

Polling status endpoint.

curl http://localhost:8000/kb/a1b2c3d4e5f6/status

POST /chat

Hybrid retrieval + generation.

curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d "{\"query\":\"What are symptoms of diabetes?\",\"debug\":false,\"use_multihop\":true}"

Response shape:

{
  "answer": "....",
  "sources": [
    {
      "chunk_id": "doc_chunk_001",
      "doc_id": "doc_001",
      "score": 0.88,
      "page": 3,
      "section": "section_name"
    }
  ]
}

Notes:

• use_multihop is optional (false by default). If true, backend runs a multi-hop failsafe: second retrieval only when first-pass retrieval is judged insufficient.
• sources fields are only included when present in retriever metadata.
• No source fields are fabricated.