API Reference
BeliefTracker
The main orchestrator class.
| Method | Returns | Description |
|---|
| wrap(fn) | Callable | Decorator that intercepts LLM calls for belief extraction |
| set_session(id) | None | Set the active session ID for tracking |
| set_conversation(id) | None | Set the active conversation thread within a session |
| get_context_prompt() | str | Get formatted belief summary for injection into prompts |
| get_beliefs(session_id) | list[Belief] | Retrieve all beliefs for a session |
| delete_session(id) | DeletionReceipt | Delete all session data (GDPR) |
| prune_expired_beliefs() | int | Remove beliefs older than max_age_seconds |
| update_belief_reference() | None | Touch a belief's last_referenced_at timestamp |
ProviderAdapter (Protocol)
Interface that all adapters implement.
| Method | Returns | Description |
|---|
| to_llm_call(*args, **kwargs) | LLMCall | Convert native SDK args to universal LLMCall |
| to_llm_response(response) | LLMResponse | Convert native SDK response to universal LLMResponse |
| generate(call, response_format) | LLMResponse | Execute generation with retry and timeout |
| get_embedding(text) | list[float] | Generate embedding for a single text |
| get_embeddings(texts) | list[list[float]] | Generate embeddings for multiple texts (batched) |
| health_check() | bool | Verify provider connectivity |
Store (Protocol)
Interface for belief storage backends.
| Method | Returns | Description |
|---|
| add_belief(session_id, belief) | None | Add or overwrite a belief |
| get_beliefs(session_id, conversation_id) | list[Belief] | Retrieve all beliefs for a session |
| search_beliefs(session_id, embedding, ...) | list[Belief] | Semantic similarity search |
| remove_belief(session_id, subject, predicate) | None | Remove a specific belief |
| update_belief(session_id, belief) | None | Update an existing belief |
| clear(session_id) | None | Clear all beliefs for a session |
Key Models
| Class | Module | Description |
|---|
| Belief | beliefstate.models | Subject-predicate-value triple with confidence and metadata |
| LLMCall | beliefstate.call | Universal representation of an LLM chat completion request |
| LLMResponse | beliefstate.call | Universal representation of an LLM chat completion response |
| TrackerConfig | beliefstate.config | Pydantic configuration model for the tracker |
| DeletionReceipt | beliefstate.models | Audit receipt returned by session deletion |
| RetryConfig | beliefstate.adapters.common | Per-adapter retry strategy configuration |
Changelog
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