TrackerConfig
TrackerConfig is a Pydantic model that controls all aspects of the tracker. All parameters have sensible defaults.
Store Settings
| Parameter | Type | Default | Description |
|---|---|---|---|
| store_type | str | "sqlite" | Storage backend: "sqlite" or "redis" |
| store_kwargs | dict | {} | Extra arguments passed to the store constructor (e.g. {"db_path": "beliefs.db"}) |
Detection Settings
| Parameter | Type | Default | Description |
|---|---|---|---|
| similarity_threshold | float | 0.82 | Minimum cosine similarity to consider beliefs related |
| contradiction_threshold | float | 0.70 | Minimum NLI score to flag as contradiction |
| entailment_threshold | float | 0.85 | Minimum NLI score to detect semantic duplicates |
Resilience Settings
| Parameter | Type | Default | Description |
|---|---|---|---|
| retry_max_attempts | int | 5 | Maximum retry attempts for LLM API calls |
| retry_min_wait | float | 2.0 | Minimum wait time between retries (seconds) |
| retry_max_wait | float | 30.0 | Maximum wait time between retries (seconds) |
| retry_multiplier | float | 2.0 | Exponential backoff multiplier |
| enable_circuit_breaker | bool | True | Enable circuit breaker protection |
| circuit_breaker_failure_threshold | int | 5 | Failures before tripping the circuit breaker |
| circuit_breaker_recovery_timeout | float | 30.0 | Cooldown before recovery attempt (seconds) |
Task & Dispatcher Settings
| Parameter | Type | Default | Description |
|---|---|---|---|
| enable_background_tasks | bool | True | Run tracking in fire-and-forget background tasks |
| task_dispatcher_type | str | "asyncio" | Dispatcher: "asyncio", "sync", "celery", or "rq" |
| dispatcher_kwargs | dict | {} | Arguments for dispatcher initialization |
Belief Storage & Injection
| Parameter | Type | Default | Description |
|---|---|---|---|
| max_beliefs | int | 50 | Maximum beliefs injected into prompts |
| belief_sort_strategy | str | "confidence_recency" | Selection strategy: "confidence_recency", "recency", or "confidence" |
| enable_belief_ttl | bool | False | Enable automatic belief pruning by age |
| belief_max_age_seconds | int | 86400 | Max age before pruning (default: 24 hours) |
| enable_staleness_scoring | bool | True | Deprioritize old beliefs during session resumption |
| staleness_threshold | float | 0.1 | Minimum staleness score to inject a belief |
| enable_token_aware_injection | bool | True | Use relevance filtering when beliefs exceed token budget |
| belief_budget_tokens | int | 500 | Maximum tokens reserved for belief injection |
Technical Mechanics & Calculations
1. Threshold Calibration
To avoid querying the expensive NLI judge on every single stored fact, BeliefState uses a two-tiered check:
-
Similarity Threshold (
similarity_threshold): Checks the cosine similarity between the vector embeddings of the new fact and existing stored facts. If the similarity is below this value (default 0.82), the facts are deemed conceptually unrelated, and the NLI check is skipped. -
Contradiction & Entailment Thresholds: The Natural Language Inference (NLI) model scores logical relation on a 0.0 to 1.0 scale:
- If
contradiction_score >= contradiction_threshold, the facts are treated as contradicting (e.g. "lives in London" vs. "lives in Paris"). - If
entailment_score >= entailment_threshold, the facts are duplicates (e.g. "likes Python" vs. "enjoys Python programming") and the new record is ignored or merged.
- If
2. Staleness Decay Formula
When resuming an old conversation session, stale beliefs (e.g., intermediate tasks the user finished days ago) should not clutter the prompt context. If enable_staleness_scoring is active, each belief is rated using:
Staleness Score = Confidence / (Days Since Referenced + 1)If the calculated score falls below the staleness_threshold (default 0.1), the belief is excluded from prompt context injection. If all beliefs are too stale, the tracker falls back to injecting the top 5 most confident, recent facts as a safety measure.
3. Token-Aware Relevance Filtering
To keep LLM API token consumption low, the tracker estimates the size of the formatted prompt using a fast character-based heuristic: 1 token ≈ 4 characters. If this estimated size exceeds belief_budget_tokens, relevance filtering is triggered:
- The current user query is embedded into a vector.
- All candidate beliefs for the session are ranked by the cosine similarity between their stored embedding and the query embedding.
- Beliefs are filled into the prompt from highest to lowest similarity, stopping as soon as the token budget is reached.
Custom Prompts
Override the built-in extraction or judge prompts via TrackerConfig:
pythonconfig = TrackerConfig(
extract_prompt_template="""Extract beliefs from this text as JSON.
Return [{"subject": "...", "predicate": "...", "value": "...", "confidence": 0.0-1.0}]
Text: {response}""",
judge_prompt_template="""Analyze these two claims.
Premise: {premise}
Hypothesis: {hypothesis}
Return {"relationship": "contradiction|entailment|neutral", "score": 0.0-1.0}"""
)ℹ️ Note: The extraction prompt must include the {response} placeholder. The judge prompt must include {premise} and {hypothesis} placeholders.