Skip to main content

FastAPI Server with caesura-io-openai

This example demonstrates a minimal FastAPI backend exposing standard OpenAI-compatible HTTP endpoints using the caesura-io-openai wrapper.

Source Code: caesura-io/examples-sdk-py/examples/fastapi-openai-server

What this shows​

A server-side integration wrapping the official OpenAI Python SDK, logging injected recommendations and credit usage to the console. It uses gpt-5.4-mini via the new Responses API and the older Chat Completions API.

When to use it: Use the caesura-io-openai package when you are building a headless service, backend worker, or an application that already uses the official openai package directly.

Prerequisites​

  • Python 3.10 or higher
  • uv — fast Python package manager
  • An OpenAI API key
  • A Caesura API key (see Authentication)

Setup​

  1. Clone the examples repository.
  2. Navigate to the example directory: 
    cd examples/fastapi-openai-server
  3. Copy the example environment file: 
    cp .env.example .env
  4. Fill in your OPENAI_API_KEY and CAESURA_API_KEY in .env. Ensure your Caesura environment base URL is correctly set if you are not using the default.
  5. Install dependencies: 
    uv sync

Run​

Start the server using uvicorn:

uv run uvicorn app.main:app --reload --port 8000

The server starts at http://localhost:8000.

What you'll see​

You can use the included requests.http file (or curl) to ping the server.

In your console, you will see FastAPI/uvicorn startup logs alongside detailed Caesura lifecycle events:

  • The requests sent to Caesura's backend for analysis
  • The resulting recommendations
  • When a recommendation is injected into your OpenAI request

Async vs Sync Observation Mode​

This example uses sync mode by default, meaning recommendations are injected immediately on the current turn (blocking the LLM request). To switch to the non-blocking mode, set CAESURA_MODE=async in your .env file.

Data Flow​

Because Caesura operates as a middleware/proxy, it is important to understand where your data goes:

  • Provider API Key (OpenAI): Sent only to OpenAI. It is never sent to the Caesura backend. This key remains securely on your server.
  • Conversation Content: Sent to the Caesura backend for analysis, and to the provider for language model generation.
  • Caesura API Key: Sent only to the Caesura backend.