Skip to main content

FastAPI Server with caesura-io-openai

A FastAPI backend using the CaesuraO Python wrapper for OpenAI Responses and Chat Completions, including streaming. It demonstrates explicit conversation creation, saved analyses, and SDK events.

Source and full walkthrough: fastapi-openai-server.

Run​

Requires Python 3.10+, uv, an OpenAI API key, and a CaesuraO API key. Clone the examples repository, then:

cd examples/fastapi-openai-server
cp .env.example .env
# Set OPENAI_API_KEY and CAESURA_API_KEY in .env.
uv sync --locked
uv run uvicorn app.main:app --reload --port 8000

The server runs at http://localhost:8000. The SDK uses https://api.caesurao.com by default.

Follow a conversation​

  1. Call POST /caesura/conversations once with an optional name and save the returned id.
  2. Pass that backend ID as conversationId for Responses requests, or as user for this example's Chat Completions route.
  3. Send growing dialogue history with actual provider replies and subsequent user messages. Fetch /caesura/conversations/{id} to inspect saved analyses.

The HTTP field names above are conventions of this example server. Both routes pass the ID to the SDK as caesura_conversation_id. Persistence requires a backend ID; local labels or generated UUIDs alone are insufficient. See Conversations & Persistence.

The repository's requests.http contains complete Responses, Chat, and mixed-API flows. A conversation ID associates saved analyses but does not supply the model's dialogue history.

Behavior to observe​

CAESURA_MODE=sync is this example's default, including with AsyncOpenAI. It awaits analysis before generation. async supplies completed guidance to a later call. Logs show full analysis values and lifecycle events; a successful OpenAI response alone does not verify analysis succeeded.

Saving is enabled by default. Set CAESURA_PERSIST=false for unsaved analysis. Reuse a stable local label to keep guidance across unsaved turns; omitted IDs receive separate temporary sessions in this example.

The example includes mocked tests and an optional live conversation check; see its README for commands. The live check creates conversations and consumes API credits.

API keys stay on the server and go only to their respective services. Dialogue is sent to both CaesuraO and OpenAI. Keep prior analysis separate from ordinary dialogue; the SDK handles analysis context.