Reliable Reasoning Components

# research-assistant/ ├── main.py # FastAPI app ├── requirements.txt # Dependencies ├── Dockerfile # Container build ├── .env # API keys (never commit) └── README.md

# requirements.txt fastapi openai pydantic python-dotenv uvicorn

// GET /ask response { "answer": "Prompt engineering is...", "sources": ["source1", "source2"], "confidence": 0.92, "model": "gpt-5.4-mini", "tokens_used": 150 }

stream = client.chat.completions.create( model="gpt-5.4-mini", messages=[{"role": "user", "content": question}], stream=True, ) for chunk in stream: delta = chunk.choices[0].delta.content if delta: print(delta, end="", flush=True)

from fastapi.responses import StreamingResponse @app.post("/ask/stream") async def ask_stream(question: str): def token_generator(): stream = client.chat.completions.create( model="gpt-5.4-mini", messages=[{"role": "user", "content": question}], stream=True, ) for chunk in stream: delta = chunk.choices[0].delta.content if delta: yield delta return StreamingResponse( token_generator(), media_type="text/plain" )

# The harness checklist # ✓ validated output shape # ✓ timeout set # ✓ retries on transient failures # ✓ safe fallback on the bad path # ✓ errors logged not swallowed # # Optional upgrade: # fall back to a different model # if the primary fails

from pydantic import BaseModel class Answer(BaseModel): answer: str sources: list[str] confidence: float # 0.0 to 1.0

response = client.chat.completions.parse( model="gpt-5.4-mini", messages=[ {"role": "system", "content": "You are a careful research assistant."}, {"role": "user", "content": question}, ], response_format=Answer, ) result = response.choices[0].message.parsed # result.answer, result.sources, result.confidence # parsed and validated — every field guaranteed

@app.post("/ask") async def ask_question(question: str): try: response = client.chat.completions.parse( model="gpt-5.4-mini", messages=[{ "role": "user", "content": question, }], response_format=Answer, ) return response.choices[0].message.parsed except Exception: # Log the real error. Still return HTTP 200 + valid Answer. return Answer( answer="Sorry, I couldn't answer that right now.", sources=[], confidence=0.0, )

client = OpenAI( api_key=os.getenv("OPENAI_API_KEY"), timeout=20.0, # give up after 20s max_retries=3, # retry with backoff )

FROM python:3.12-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . CMD ["fastapi", "run", "main.py", "--host", "0.0.0.0", "--port", "8000"]

# build the image docker build -t research-assistant . # run it with your env vars docker run -p 8000:8000 \ --env-file .env \ research-assistant