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

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

Response:

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

### GET `/kb/{job_id}/stream`

Server-Sent Events stream for lifecycle and progress events.

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

Example frontend:

```js
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.

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

### POST `/chat`

Hybrid retrieval + generation.

```bash
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:

```json
{
  "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.