FastAPI Integration

ASGI middleware that automatically extracts session IDs from request headers and sets them in the tracker context.

pythonfrom fastapi import FastAPI, Depends
from beliefstate import FastAPIBeliefTrackerMiddleware, get_session_id

app = FastAPI()


app.add_middleware(
    FastAPIBeliefTrackerMiddleware,
    header_name="X-Session-ID"
)


@app.post("/chat")
async def chat(message: str, session_id: str = Depends(get_session_id)):
    
    
    response = await chat_with_llm(message)
    return {"response": response}

ℹ️ Context Propagation Mechanics: Web frameworks process multiple requests concurrently on different asynchronous task contexts. BeliefState uses Python's standard contextvars.ContextVar (session_context) to store and isolate session identifiers. When a request comes in:

  1. The ASGI middleware intercepts the request headers and extracts the session key.
  2. It sets the value via token = session_context.set(session_id), propagating the variable down the active execution flow.
  3. When the request handler finishes, the middleware executes a finally block to call session_context.reset(token), ensuring zero context leakage across different requests.

Flask Integration

pythonfrom flask import Flask
from beliefstate import FlaskBeliefTrackerMiddleware, register_flask_hooks

app = Flask(__name__)


app.wsgi_app = FlaskBeliefTrackerMiddleware(app.wsgi_app, header_name="X-Session-ID")


register_flask_hooks(app, header_name="X-Session-ID")

Generic ASGI Middleware

pythonfrom starlette.applications import Starlette
from beliefstate import BeliefTrackerASGIMiddleware

app = Starlette()
app.add_middleware(BeliefTrackerASGIMiddleware, header_name="X-Session-ID")

LangChain Callback

pythonfrom beliefstate import session_context, BeliefTrackerLangchainCallback


session_context.set("user_123")


handler = BeliefTrackerLangchainCallback(tracker=tracker)
await llm.ainvoke("Hello!", config={"callbacks": [handler]})

LlamaIndex Callback

pythonfrom llama_index.core import Settings
from llama_index.core.callbacks import CallbackManager
from beliefstate import LlamaIndexBeliefTrackerCallback

callback = LlamaIndexBeliefTrackerCallback(tracker=tracker)
Settings.callback_manager = CallbackManager([callback])

OpenAI Assistants Observer

pythonimport asyncio
from beliefstate import observe_run


asyncio.create_task(
    observe_run(
        tracker=tracker,
        client=openai_client,
        thread_id=thread_id,
        run_id=run.id,
        session_id="session_123"
    )
)

ℹ️ Callback Hook Lifecycles: The LangChain and LlamaIndex callback handlers inherit from their respective framework lifecycle hooks (e.g. on_llm_end or on_event_end). When the model finishes generating a response:

  1. The callback intercepts the output response text and input prompt history.
  2. It grabs the active session_id and conversation_id from thread context variables.
  3. It packages this payload and schedules a background belief tracking task asynchronously via the tracker dispatcher, keeping the application response pipeline completely non-blocking.