feat(jobs): add background job support for benchmarks and processing

Why:
- Long benchmark and process runs block HTTP clients; task #20 required async execution.

Changes:
- SQLite jobs table + GET /jobs and GET /jobs/{id}
- POST /benchmarks?background=true and POST /documents/{id}/process?background=true return 202 + job_id
- FastAPI BackgroundTasks execute work in-process; sync paths unchanged

Impact:
- Jobs are lost on server restart (Option A, no external queue)

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
2026-08-22 15:32:33 +03:30
parent 47e4846270
commit 3f9677f6aa
11 changed files with 473 additions and 40 deletions

View File

@@ -82,6 +82,9 @@ Delete a document and its vectors.
Run chunking strategies on a document.
**Query parameters:**
- `background` (bool, default `false`) — when `true`, enqueue processing and return **202** with a `job_id`; poll `GET /jobs/{job_id}`.
**Request:**
```json
{
@@ -199,6 +202,9 @@ Retrieve a past query.
Run a benchmark comparing multiple strategies.
**Query parameters:**
- `background` (bool, default `false`) — when `true`, enqueue the run and return **202** with a `job_id`; poll `GET /jobs/{job_id}` for status and result.
**Request:**
```json
{
@@ -278,6 +284,32 @@ List all experiments.
---
### Jobs
Background execution for long-running benchmarks and document processing (FastAPI `BackgroundTasks` + SQLite job records).
#### `GET /jobs`
List jobs (newest first).
**Query parameters:** `job_type`, `status`, `offset`, `limit`
#### `GET /jobs/{job_id}`
Poll job status. When `status` is `completed`, `result` contains the same payload as the synchronous endpoint would return; when `failed`, `error` is set.
**Response (202 enqueue body from POST with `background=true`):**
```json
{
"job_id": "abc123",
"job_type": "benchmark",
"status": "pending",
"poll_url": "/jobs/abc123"
}
```
---
## Error Responses
All errors return:

View File

@@ -43,7 +43,7 @@ Status legend: `DONE` `IN_PROGRESS` `TODO`
| 17 | Create question-answer evaluation dataset from insurance regulation document | DONE | 12 |
| 18 | Implement HTML benchmark report generation system | DONE | 14 |
| 19 | Design HTML report structure for experiment comparison and visualization | DONE | 14 |
| 20 | Create background processing jobs for document ingestion and benchmarking | TODO | 12 |
| 20 | Create background processing jobs for document ingestion and benchmarking | DONE | 12 |
## Phase 5 — Wiring + Verification