# Python FastAPI PostgreSQL AI research queue

A research queue turns a question into saved evidence notes and a finished brief while the browser watches each step. Tokay runs the FastAPI page and Background Worker together, and PostgreSQL lets interrupted jobs resume from their latest checkpoint.

You can prove the queue and recovery path without paying for a model. Three bundled documents drive the default demo, and an optional Anthropic key upgrades the same workflow to model generated notes and synthesis.

## Facts

- Runtime: Python
- Framework: FastAPI
- Service types: Web Service, Background Worker
- Resources: PostgreSQL
- Required secrets: None

## What it does

The page starts with a completed heat pump brief so you can see the shape of a finished result.

Enter a research question and press **Start research**. The job moves through reading documents, building evidence notes, drafting the synthesis, and saving the result while the page updates live.

Check **Restart the worker once during this job** to watch recovery happen on purpose. The replacement process continues after the saved second step instead of repeating the job from the beginning.

## Deploy it

Bring this folder to Tokay any way you like. Paste or upload it in the dashboard, push it with git, or hand it to your AI agent along with [our agent instructions](https://app.tokay.io/llms.txt). Tokay figures out the rest.

Working in Claude, ChatGPT, VS Code, or another MCP client? Connect the [Tokay MCP server](https://tokay.io/docs/platform-mcp) and ask your agent to deploy this example. It signs in through your browser, so there is no token to paste.

New to Tokay? The [getting started guide](https://tokay.io/getting-started) walks you through your first deploy.

## Try it

1. Submit the provided heat pump question and wait for its four steps to finish.
2. Run it again with **Restart the worker once during this job** checked. Confirm that a later attempt resumes after step two.
3. Deploy both Services again. The completed briefs and recovery evidence remain in PostgreSQL.

## Add real model synthesis

Open the Background Worker's **Environment** page and find `ANTHROPIC_API_KEY` under **From your code**. Choose **Set shared value**, paste your key, and save it. Deploy the Background Worker again.

New jobs now call Anthropic once for each bundled document and once for the final synthesis. The result badge changes to **Anthropic**. The page keeps showing saved progress while those model calls run.

## How it works

You avoid competing schema changes because the Web Service owns the Alembic migration for both processes. The Background Worker connects to those tables without trying to apply it again.

Each claimed job has a short lease that the worker renews while saving progress. If the process disappears, the lease expires and another worker continues from the checkpoint. `FOR UPDATE SKIP LOCKED` prevents two live workers from claiming the same job.

The queue retries a temporary failure up to three times. SSE updates the page without a refresh, while PostgreSQL remains the source of truth if that browser connection closes.

## Secrets

| Name | Required | Purpose |
| --- | --- | --- |
| `ANTHROPIC_API_KEY` | No | Turns the bundled document demo into model synthesis with several calls. Keep the key in encrypted Project storage. |

## Grow from here

Try the [PostgreSQL task tracker](/examples/node-express-postgres-task-tracker) when you want a smaller starting point for migrations and saved CRUD data.

## Source files

- [web/alembic.ini](https://tokay.io/examples/src/python-fastapi-postgres-ai-research-queue/web/alembic.ini)
- [web/main.py](https://tokay.io/examples/src/python-fastapi-postgres-ai-research-queue/web/main.py)
- [web/migrations/env.py](https://tokay.io/examples/src/python-fastapi-postgres-ai-research-queue/web/migrations/env.py)
- [web/migrations/versions/0001\_research\_jobs.py](https://tokay.io/examples/src/python-fastapi-postgres-ai-research-queue/web/migrations/versions/0001_research_jobs.py)
- [web/requirements.txt](https://tokay.io/examples/src/python-fastapi-postgres-ai-research-queue/web/requirements.txt)
- [worker/documents/climate-and-efficiency.md](https://tokay.io/examples/src/python-fastapi-postgres-ai-research-queue/worker/documents/climate-and-efficiency.md)
- [worker/documents/cold-weather-and-resilience.md](https://tokay.io/examples/src/python-fastapi-postgres-ai-research-queue/worker/documents/cold-weather-and-resilience.md)
- [worker/documents/costs-and-retrofit.md](https://tokay.io/examples/src/python-fastapi-postgres-ai-research-queue/worker/documents/costs-and-retrofit.md)
- [worker/main.py](https://tokay.io/examples/src/python-fastapi-postgres-ai-research-queue/worker/main.py)
- [worker/requirements.txt](https://tokay.io/examples/src/python-fastapi-postgres-ai-research-queue/worker/requirements.txt)

## Download and source

- [Download the complete project](https://tokay.io/examples/downloads/python-fastapi-postgres-ai-research-queue.zip)
- Last updated: 2026-07-31
- Example revision: `52c7b7f`
- [View this revision on GitHub](https://github.com/tokayio/tokay-examples/tree/52c7b7ffd52e157375b08f1f11ff4fbe6c498642/python-fastapi-postgres-ai-research-queue)
- [Deploy a queue worker](https://tokay.io/use-cases/deploy-queue-worker)