API Reference & Changelog — BeliefState Documentation

API Reference

BeliefTracker

The main orchestrator class. Manages the full belief tracking pipeline: interception, extraction, contradiction detection, resolution, and storage.

Constructor

Parameter	Type	Default	Description
`config`	`TrackerConfig`	(required)	Configuration object controlling all tracker behavior. See TrackerConfig.
`adapter`	`Optional[ProviderAdapter]`	`None`	The main application adapter for payload normalization. If `None`, auto-detected from the first wrapped LLM call's response type.
`store`	`Optional[Store]`	`None`	Belief storage backend. If `None`, created from `config.store_type` and `config.store_kwargs`.
`internal_adapter`	`Optional[ProviderAdapter]`	`None`	Adapter for background tracking operations (extraction, judge, embeddings). If `None`, uses `adapter`. Set to a cheaper/local model for cost optimization.
`dispatcher`	`Optional[Dispatcher]`	`None`	Task dispatcher for background execution. If `None`, created from `config.task_dispatcher_type`.

Methods

Method	Signature	Returns	Description
`wrap`	`(fn: Callable)`	`Callable`	Decorator that intercepts an async LLM function. Captures the input messages and output response, then dispatches a background tracking task. The original function's return value is passed through unchanged.
`set_session`	`(session_id: str)`	`None`	Set the active session ID in the context variable. All subsequent `@wrap` calls and `get_context_prompt()` calls will use this session.
`set_conversation`	`(conversation_id: str)`	`None`	Set the active conversation thread within a session. Enables multi-thread belief scoping.
`get_session_turn`	`(session_id: Optional[str])`	`int`	Get the current turn number for a specific session. Returns `0` if no turns have been processed. Uses per-session counters (thread-safe).
`get_context_prompt`	`(session_id, conversation_id, format_template, current_user_message)`	`str`	Get formatted belief summary for injection into system prompts. Applies staleness filtering, sort strategy, and token-aware relevance selection. All parameters are optional.
`inject_context`	`(messages, session_id, conversation_id, format_template, current_user_message)`	`list[dict]`	Inject belief context into a list of message dicts. If a system message exists, appends context to it; otherwise prepends a new system message. Returns a new list (does not mutate the original).
`get_beliefs`	`(session_id: Optional[str])`	`list[Belief]`	Retrieve all beliefs for a session from the store. Delegates to `store.get_beliefs()`.
`export_beliefs`	`(session_id: Optional[str])`	`list[dict]`	Export all beliefs for a session as JSON-serializable dicts (via `Belief.model_dump()`). Useful for backups, debugging, and store migration.
`import_beliefs`	`(session_id: Optional[str], beliefs_data: list[dict])`	`int`	Import beliefs from a list of dicts into the store. Validates each entry via `Belief.model_validate()`. Skips invalid entries with a warning. Returns the count of successfully imported beliefs.
`clear_session`	`(session_id: str)`	`DeletionReceipt`	Delete all session data (GDPR right to erasure). Drains in-flight tasks, deletes all beliefs, cleans up session locks, and returns an auditable receipt.
`health_check`	`()`	`dict[str, bool]`	Check health of all tracker components. Returns `{"store": bool, "adapter": bool}`. Use at startup or in readiness probes.
`prune_expired_beliefs`	`(session_id: Optional[str], max_age_seconds: Optional[int])`	`int`	Remove beliefs older than `max_age_seconds` (defaults to `config.belief_max_age_seconds`). Returns the count of pruned beliefs.
`update_belief_reference`	`(session_id: Optional[str], subject: str, predicate: str)`	`None`	Touch a belief's `last_referenced_at` timestamp. Helps with staleness scoring — called internally when beliefs are injected into prompts.
`__aenter__`	`()`	`BeliefTracker`	Async context manager entry. Opens the store connection (if the store has an `open()` method). Enables `async with tracker:` pattern.
`__aexit__`	`(exc_type, exc_val, exc_tb)`	`None`	Async context manager exit. Closes the store connection (if the store has a `close()` method). Ensures proper resource cleanup.

Context Manager Usage

pythonasync with BeliefTracker(config=config, adapter=adapter) as tracker:
    tracker.set_session("user_123")
    await chat([{"role": "user", "content": "Hello!"}])
# Store connection is automatically closed here

ProviderAdapter (Protocol)

Interface that all adapters implement. Defines the contract for payload normalization, LLM generation, embedding creation, and health checking.

Method	Signature	Returns	Description
`to_llm_call`	`(args, *kwargs)`	`LLMCall`	Convert native SDK arguments into a universal `LLMCall` model. Extracts message history, system prompt, and model parameters.
`to_llm_response`	`(response: Any)`	`LLMResponse`	Convert native SDK response into a universal `LLMResponse` model. Extracts response text, model name, and token usage.
`generate`	`(call: LLMCall, response_format: Optional[type])`	`LLMResponse`	Execute an LLM chat completion with retry and timeout. Used internally for extraction and judge prompts.
`get_embedding`	`(text: str)`	`list[float]`	Generate a vector embedding for a single text string.
`get_embeddings`	`(texts: list[str])`	`list[list[float]]`	Generate embeddings for multiple texts in a single batched API call.
`health_check`	`()`	`bool`	Verify provider connectivity. Returns `True` if the provider is reachable and responding.

Store (Protocol)

Interface for belief storage backends. See Stores for full method signatures and implementation details.

Method	Returns	Description
`add_belief(session_id, belief)`	`None`	Add or upsert a belief (keyed by session + subject + predicate).
`get_beliefs(session_id, conversation_id)`	`list[Belief]`	Retrieve all beliefs for a session, optionally filtered by conversation.
`search_beliefs(session_id, embedding, ...)`	`list[Belief]`	Semantic similarity search using cosine distance on embedding vectors.
`remove_belief(session_id, subject, predicate)`	`None`	Remove a specific belief by its composite key.
`update_belief(session_id, belief)`	`None`	Update an existing belief's fields (confidence, value, timestamps).
`clear(session_id)`	`None`	Delete all beliefs for a session.
`belief_count(session_id)`	`int`	Count beliefs without loading them into memory.
`health_check()`	`bool`	Verify store backend health and connectivity.

Belief Model

The core data model representing a single extracted fact. Stored as a Pydantic BaseModel in beliefstate.models.

Field	Type	Default	Description
`subject`	`str`	(required)	Who or what the belief is about. Normalized: first-person → `"USER"`, second-person → `"ASSISTANT"`.
`predicate`	`str`	(required)	The relationship or attribute (e.g., `"lives in"`, `"likes"`, `"works at"`).
`value`	`str`	(required)	The value of the claim. Normalized: dates → ISO 8601, currency → ISO 4217, numbers → digits.
`confidence`	`float`	`1.0`	Extraction confidence from 0.0 (uncertain) to 1.0 (definitive). Reported by the extraction model.
`turn`	`int`	`0`	The conversation turn number when this belief was extracted.
`source`	`str`	`"user"`	Who made the claim: `"user"` (from user messages) or `"assistant"` (from LLM responses).
`belief_type`	`str`	`"assertion"`	`"assertion"` — a normal factual claim. `"update"` — an explicit correction of a prior belief (triggers immediate override).
`is_hypothetical`	`bool`	`False`	Whether the belief is conditional or speculative (e.g., "If I were…"). Hypothetical beliefs are excluded from prompt injection but kept in the store.
`embedding`	`Optional[list[float]]`	`None`	Vector embedding of the belief text (`"{subject} {predicate} {value}"`). Used for semantic similarity search in contradiction detection.
`created_at`	`datetime`	(auto)	UTC timestamp when the belief was first extracted and stored.
`last_referenced_at`	`Optional[datetime]`	`None`	UTC timestamp of the last time this belief was actively used (injected into a prompt). Used by the staleness scoring algorithm.
`conversation_id`	`Optional[str]`	`None`	The conversation thread ID this belief belongs to. Enables multi-thread filtering in `get_context_prompt()`.

Other Key Models

Class	Module	Description
`LLMCall`	`beliefstate.call`	Universal representation of an LLM chat completion request. Contains normalized message history, system prompt, model name, and parameters.
`LLMResponse`	`beliefstate.call`	Universal representation of an LLM chat completion response. Contains response text, model name, and token usage metadata.
`TrackerConfig`	`beliefstate.config`	Pydantic configuration model with 25+ parameters controlling the full tracker pipeline. See Configuration.
`DeletionReceipt`	`beliefstate.models`	Audit receipt returned by `clear_session()`. Contains `session_id`, `beliefs_deleted`, `in_flight_tasks_drained`, `deleted_at`.
`RetryConfig`	`beliefstate.adapters.common`	Per-adapter retry strategy. Controls `max_retries`, `initial_delay`, `max_delay`, `exponential_base`, `jitter`. See RetryConfig.
`TrackerEvent`	`beliefstate.logging_utils`	Structured log event dataclass. Contains `session_id`, `operation`, `turn`, `latency_ms`, `detail`. See Observability.
`CircuitBreaker`	`beliefstate.resilience`	Circuit breaker implementation with CLOSED / OPEN / HALF-OPEN states. See Resilience.
`CircuitBreakerOpenException`	`beliefstate.resilience`	Exception raised when the circuit breaker is in OPEN state. Signals that the provider is currently unavailable.

Context Variables

BeliefState uses Python contextvars.ContextVar for thread/task-safe session management:

Variable	Type	Default	Description
`session_context`	`ContextVar[str]`	`"default"`	The active session ID. Set via `tracker.set_session()`, middleware, or directly via `session_context.set()`. Read by all tracker methods to determine which session to operate on.
`conversation_context`	`ContextVar[Optional[str]]`	`None`	The active conversation thread ID within a session. Set via `tracker.set_conversation()` or directly.

Changelog

v1.0.2 — Advanced Enhancements

Feature release introducing cloud-ready storage, low-latency streaming wrappers, and decoupled configuration.

PostgreSQL Store Backend (PostgreSQLStore): Added a new database store backend supporting PostgreSQL with database-side PL/pgSQL vector similarity.
Non-Blocking Streaming Wrapper (AsyncStreamWrapper): Upgraded the LLM function wrapper to natively support async streaming generators, yielding tokens to clients with zero added latency while extracting beliefs in the background.
Decoupled Embeddings: Added embed_provider and embed_model fields to TrackerConfig to separate chat LLM and embedding LLM providers.
Fail-Fast Configuration Validation: The tracker now immediately raises a descriptive ValueError at runtime if the auto-detected response type resolves to a non-functional GenericAdapter fallback.

v1.0.1 — Pronoun Mapping Fix

Bug fix release targeting pronoun mapping bias during extraction.

Fixed Pronoun Mapping Bias: Split the extraction prompt into separate user and assistant templates (extract_user_prompt_template and extract_assistant_prompt_template) to prevent first-person pronoun mapping failures in assistant responses.

v1.0.0 — Production Release

Production hardening release with critical bug fixes, new features, and improved reliability.

🐛 Bug Fixes

Fixed global turn counter race condition: Replaced shared int counter with per-session Dict[str, int] counters. Prevents cross-session turn collision in multi-user servers (FastAPI, multi-worker).
Fixed inject_context() silent bug: The method was passing format_template as conversation_id to get_context_prompt() due to positional argument mismatch. Now uses explicit keyword arguments.
Fixed session lock memory leak: _session_locks dict grew unboundedly — every new session created a lock that was never removed. clear_session() now cleans up locks, turn counters, and provider tracking entries.

✨ New Features

async with context manager: BeliefTracker now supports async with tracker: pattern for automatic store open/close lifecycle management.
belief_count(): New Store protocol method to count beliefs without deserializing them all into memory. Uses SELECT COUNT(*) (SQLite), HLEN (Redis), len() (Memory).
export_beliefs() / import_beliefs(): New tracker methods for belief portability. Export to JSON-serializable dicts, import with Pydantic validation. Enables store migration (SQLite → Redis), backups, and debugging.
health_check(): New tracker method that checks store and adapter health. Returns {"store": bool, "adapter": bool}. Use at startup or in Kubernetes readiness probes.
Structured logging (TrackerEvent): All pipeline operations emit structured JSON log events with consistent fields (session_id, operation, turn, latency_ms, detail). Compatible with Datadog, CloudWatch, Loki.
get_session_turn(): New method to query the turn counter for a specific session (replaces the deprecated global turn_counter attribute).

📦 Infrastructure

Published to PyPI via GitHub Actions (Trusted Publisher)
Added ruff formatting checks to CI
Test coverage above 60% across all modules

v0.1.0 — Initial Release

Core belief extraction pipeline (extract → detect → resolve)
5 provider adapters: OpenAI, Anthropic, Gemini, Ollama, LiteLLM
3 storage backends: SQLite, Redis, In-Memory
7 framework integrations: FastAPI, Flask, ASGI, WSGI, LangChain, LlamaIndex, OpenAI Assistants
Dual-Adapter architecture for cost optimization
Pluggable dispatchers: asyncio, sync, Celery, RQ
Production resilience: retry, circuit breaker, health checks
OpenTelemetry observability
GDPR session deletion with audit receipts
Token-aware belief injection
Staleness scoring for session resumption
Full mypy type safety (0 errors)
205 unit tests