Pages
Integrations Sections
FastAPI Flask ASGI LangChain LlamaIndex OpenAI Assistants Error Handling

Reference

Integrations

Connect beliefstate to your active web applications, orchestration flows, and agent run cycles using native framework wrappers.

FastAPI Integration

The FastAPI middleware extracts session IDs from request headers and sets session context automatically — your endpoint handlers need no changes.

fastapi_server.py
from fastapi import FastAPI, Depends from beliefstate import FastAPIBeliefTrackerMiddleware, get_session_id app = FastAPI() # 1. Register middleware globally app.add_middleware( FastAPIBeliefTrackerMiddleware, header_name="X-Session-ID" ) # 2. Endpoint executes automatically with context @app.post("/chat") async def chat(message: str): response = await run_chat_model(message) return {"response": response} # 3. Alternative: Explicit dependency injection @app.post("/chat-explicit") async def chat_explicit( message: str, session_id: str = Depends(get_session_id) ): response = await run_chat_model(message) return {"response": response, "session_id": session_id}
Parameter Type Default Description
app ASGIApp required The target FastAPI application instance.
header_name str "X-Session-ID" The HTTP header key utilized to look up session identifiers.

Context Propagation Mechanics

The middleware manages concurrent request execution states using context variables:

  1. Lookup — Middleware intercepts incoming headers and extracts the session identifier value, executing session_context.set(session_id).
  2. Propagation — The context propagates through the async call chain, enabling trackers to retrieve state without explicit parameters.
  3. Cleanup — A finally execution block executes session_context.reset() to restore initial empty contexts.

Testing Locally

Trigger requests with target headers to verify session propagation:

curl_test.sh
curl -X POST http://localhost:8000/chat \ -H "X-Session-ID: user_123" \ -H "Content-Type: application/json" \ -d '{"message": "I reside in London"}'
💡 Tip

If X-Session-ID header is missing, the session defaults to 'default' — all requests without a header share one belief store. Always send a session header in production.

Flask Integration

For Flask WSGI backends, beliefstate supports request context extraction via WSGI middleware or lifecycle hooks.

flask_server.py
from flask import Flask from beliefstate import FlaskBeliefTrackerMiddleware, register_flask_hooks app = Flask(__name__) # Option A: WSGI Middleware wrapper (Recommended) app.wsgi_app = FlaskBeliefTrackerMiddleware( app.wsgi_app, header_name="X-Session-ID" ) # Option B: Lifecycle Hooks registration register_flask_hooks(app, header_name="X-Session-ID")

Middleware Parameters

Parameter Type Default Description
app WSGIApp required The underlying WSGI application instance.
header_name str "X-Session-ID" HTTP header key holding session identifiers.

Hook Parameters

Parameter Type Default Description
app Flask required The Flask application instance.
header_name str "X-Session-ID" HTTP header key holding session identifiers.
Note

Middleware vs Hooks — either works. Middleware recommended for consistency with other frameworks.

Generic ASGI Middleware

Works with Starlette, Litestar, Quart, or any ASGI-compatible framework.

starlette_server.py
from starlette.applications import Starlette from beliefstate import BeliefTrackerASGIMiddleware app = Starlette() app.add_middleware( BeliefTrackerASGIMiddleware, header_name="X-Session-ID" )
Parameter Type Default Description
app ASGIApp required The target ASGI application instance.
header_name str "X-Session-ID" Case-insensitive header key indicating session ID.
Note

HTTP header keys are processed case-insensitively, complying with the RFC 7230 specification guidelines.

LangChain Callback

Hooks into LangChain's on_llm_end lifecycle event.

langchain_callback.py
from beliefstate import session_context, BeliefTrackerLangchainCallback # 1. Establish session variable scope beforehand session_context.set("user_123") # 2. Instantiate callback hook handler = BeliefTrackerLangchainCallback(tracker=tracker) # 3. Provide handler during chain execution await chain.ainvoke( {"input": "I prefer Python"}, config={"callbacks": [handler]} )
Parameter Type Default Description
tracker BeliefTracker required The active BeliefTracker tracking instance.
Important

You must set session_context before invoking the chain. LangChain callbacks don't have access to HTTP request headers.

Callback Lifecycle

The callback coordinates execution during the run cycle:

  1. Callback intercepts output text and input prompt.
  2. Grabs session_id from ContextVar.
  3. Dispatches background tracking task.

LlamaIndex Callback

Registers a callback handler with LlamaIndex's callback manager to track llama-index execution queries automatically.

llamaindex_setup.py
from llama_index.core import Settings from llama_index.core.callbacks import CallbackManager from beliefstate import LlamaIndexBeliefTrackerCallback # Initialize callback handler callback = LlamaIndexBeliefTrackerCallback(tracker=tracker) # Assign globally to settings manager Settings.callback_manager = CallbackManager([callback])
Parameter Type Default Description
tracker BeliefTracker required The active BeliefTracker tracking instance.
Note

Registers globally via Settings — all LLM calls in the process are tracked automatically.

OpenAI Assistants Observer

Polls a run to completion, then extracts beliefs from the full thread conversation in bulk.

assistants_observer.py
import asyncio from beliefstate import observe_run # Run observer task concurrently asyncio.create_task( observe_run( tracker=tracker, client=openai_client, thread_id=thread_id, run_id=run.id, session_id="user_123" ) )
Parameter Type Default Description
tracker BeliefTracker required The active BeliefTracker tracking instance.
client AsyncOpenAI required OpenAI client connection client.
thread_id str required OpenAI assistant thread key.
run_id str required Assistant run session ID.
session_id str required Belief state session context key.
Note

Difference from @tracker.wrap — the observer processes the full thread after the run completes, not turn-by-turn.

Error Handling in Integrations

BeliefState is built to operate as a non-blocking tracking layer. Under-the-hood, all integrations wrap execution segments to isolate exception contexts and safeguard your primary application flow.

What always happens

  • User receives LLM response
  • Error is logged as warning
  • Session context is cleaned up

What never happens

  • Exception propagates to your app
  • User request fails due to tracking error
  • Belief store left in inconsistent state