Skip to main content

FastAPI Server

A FastAPI backend using caesura-io-openai for Responses, Chat Completions, and streaming.

Source and setup · Repository setup

Use Python 3.10+ and uv. In the example directory, copy .env.example to .env, set OPENAI_API_KEY and CAESURA_API_KEY, run uv sync --locked, then uv run uvicorn app.main:app --reload --port 8000. The lockfile installs the published packages from PyPI.

What it demonstrates​

  1. Call POST /caesura/conversations with an optional name and greeting, and retain the returned id. The greeting is saved without triggering analysis.
  2. Pass it as conversationId to both Responses and Chat Completions routes, including streaming.
  3. Send growing dialogue history containing actual replies and new customer messages.
  4. Fetch GET /caesura/conversations/{id} to inspect saved messages and analyses.

The example uses AsyncOpenAI and defaults to CAESURA_MODE=sync, so analysis finishes before generation. Background mode makes completed guidance available to a later call. Logs show analysis events and reported credit usage. The example uses strict failure handling: analysis or customer-message storage failures prevent generation; failures to save a completed reply are reported after generation.

The minimal HTTP server uses history-based customer detection. Applications with retries, truncated histories, or user-role retrieval content should pass explicit CustomerTurn identity and trusted background through caesura_context; see the Python SDK guide.

Saving is enabled by default and stores customer messages, their analyses, and completed agent replies. It excludes tools, retrieval content, and interrupted partial replies. Both APIs require a backend conversation ID even with CAESURA_PERSIST=false. See Conversations & Persistence for dashboard visibility.

The repository includes mocked tests and an optional live check that creates conversations and consumes API credits. Add caller authentication and ownership checks before exposing this local example publicly.