Configuration Reference

TrackerConfig

TrackerConfig is a Pydantic BaseModel passed to the BeliefTracker constructor. All fields have defaults — only override what you need.

from beliefstate import BeliefTracker, TrackerConfig tracker = BeliefTracker(config=TrackerConfig())

from beliefstate import TrackerConfig config = TrackerConfig( store_type="sqlite", store_kwargs={"db_path": "beliefs.db"}, similarity_threshold=0.82, contradiction_threshold=0.70, entailment_threshold=0.85, retry_max_attempts=5, enable_circuit_breaker=True, enable_background_tasks=True, task_dispatcher_type="asyncio", max_beliefs=50, belief_sort_strategy="confidence_recency", enable_belief_ttl=False, enable_staleness_scoring=True, enable_token_aware_injection=True, belief_budget_tokens=500 )

Store Settings

Configure how and where user conversation facts are written to database storage.

Parameter	Type	Default	Description
`store_type`	str	"sqlite"	The type of storage database instance. Supported options: `"sqlite"`, `"redis"`, or `"memory"`.
`store_kwargs`	dict	{}	Additional keyword arguments forwarded directly to the backend storage constructor.

💡 Tip

Use "sqlite" for local prototyping and single-process applications. Use "redis" for multi-worker environments to share session states across horizontal deployments.

Detection Settings

These settings control the evaluation sensitivity of the conflict and duplicate checking pipeline.

Parameter	Type	Default	Description
`similarity_threshold`	float	0.82	Cosine similarity limit for Stage 1 vector checking. Filters out unrelated facts before NLI.
`contradiction_threshold`	float	0.70	NLI contradiction score limit. Scores above this value flag logical conflicts.
`entailment_threshold`	float	0.85	NLI entailment limit. Scores above this value identify and discard duplicate facts.

💡 Tip

Raise the contradiction_threshold to 0.80 to restrict false positives. Lower the similarity_threshold to 0.75 to let more candidate pairs reach the NLI judge and catch more subtle contradictions.

Resilience Settings

Configures error handling, retries, and local circuit breakers for backend LLM operations.

Parameter	Type	Default	Description
`retry_max_attempts`	int	5	Max retries for failed extraction or checking operations before dropping tasks.
`retry_min_wait`	float	2.0	Initial wait duration in seconds before the first retry attempt.
`retry_max_wait`	float	30.0	Maximum backoff wait duration in seconds. Caps long intervals.
`retry_multiplier`	float	2.0	Base multiplier scale used to compute consecutive exponential retry delays.
`enable_circuit_breaker`	bool	True	Enables local circuit breaker monitoring to block calls during external API down times.
`circuit_breaker_failure_threshold`	int	5	Consecutive errors required to trip the circuit breaker from CLOSED to OPEN.
`circuit_breaker_recovery_timeout`	float	30.0	Cooldown time in seconds before trying a probe request in the HALF-OPEN state.

The retry backoff schedule resolves to the following sequence:

Attempt 1: 2.0s delay Attempt 2: 4.0s delay Attempt 3: 8.0s delay Attempt 4: 16.0s delay Attempt 5: 30.0s delay (capped at retry_max_wait)

Task and Dispatcher Settings

Configures how asynchronous operations are queued and processed by the system.

Parameter	Type	Default	Description
`enable_background_tasks`	bool	True	Fires background tracking tasks asynchronously. Set to False only for synchronous tests.
`task_dispatcher_type`	str	"asyncio"	Selects task dispatcher backend: `"asyncio"`, `"sync"`, `"celery"`, or `"rq"`.
`dispatcher_kwargs`	dict	{}	Keyword configurations forwarded directly to the selected queue client instance.

⚠ Warning

The default asyncio task dispatcher is not durable in multi-worker production deployments. Tasks in memory disappear if worker processes terminate. Use Celery or RQ dispatchers for task persistence.

Internal Provider Override

Specifies separate LLM clients for background parsing and embedding computations.

Parameter	Type	Default	Description
`internal_provider`	Optional[Any]	None	Overrides the adapter client used for extractions and NLI. If None, reuses the primary client.
`embed_provider`	Optional[Any]	None	Specifies a separate client for generating vectors (e.g. for chat models lacking embed endpoints).
`embed_model`	Optional[str]	None	Model name override passed to the selected embedding provider.

Note

Configuring separate internal and embedding providers optimizes processing costs. Read the Dual-Adapter guide to set up separate tracking models.

Belief Storage and Injection

Manages belief caps and injection parameters used when formatting system prompts.

Parameter	Type	Default	Description
`max_beliefs`	int	50	Limits the count of formatted belief claims injected to prevent token window overflow.
`belief_sort_strategy`	str	"confidence_recency"	Determines injection priorities: `"confidence_recency"`, `"recency"`, or `"confidence"`.

Belief TTL

Configures absolute database retention cleanup intervals for older belief rows.

Parameter	Type	Default	Description
`enable_belief_ttl`	bool	False	Enables automatic pruning of older records. Defaults to False.
`belief_max_age_seconds`	int	86400	Age limit in seconds before a stored fact becomes eligible for deletion. Default is 24 hours.
`belief_ttl_check_interval`	int	3600	Cooldown interval in seconds between consecutive database cleanup sweeps.

💡 Tip

TTL pruning permanently deletes expired facts from database tables. In contrast, staleness scoring filters stale facts out of the active prompt context while leaving database records untouched.

Staleness Scoring

Grades facts based on confidence and age to filter out stale context during prompt injection.

Parameter	Type	Default	Description
`enable_staleness_scoring`	bool	True	Enables decay calculations. Filters out facts scoring below the threshold.
`staleness_threshold`	float	0.1	Minimum score required to inject a belief. Safety fallbacks inject the top 5 records if all are stale.

Staleness Decay Formula

Relevance decays over time according to this formula:

Staleness Score = Confidence / (Days Since Last Referenced + 1)

Decay examples:

Confidence	Days Since Reference	Formula	Score	Action
1.0	0	`1.0 / (0 + 1)`	1.00	Included
0.8	3	`0.8 / (3 + 1)`	0.20	Included
0.5	10	`0.5 / (10 + 1)`	0.045	Excluded

Token-Aware Injection

Filters and prioritizes beliefs dynamically when summary text exceeds a token limit.

Parameter	Type	Default	Description
`enable_token_aware_injection`	bool	True	Enables budget checks. Uses vector similarity to select the most relevant beliefs first.
`belief_budget_tokens`	int	500	Max tokens allocated to belief context in prompts. Estimated using 1 token ≈ 4 characters.

Token-Aware Filtering Cascade

When formatted belief text exceeds the token budget, the system executes these steps:

Estimate — Computes the character lengths of candidate beliefs and estimates token counts.
Verify — If the total count falls below the token budget, it injects all facts.
Embed — Generates a vector representation of the current user message.
Rank — Computes cosine similarity between the query vector and candidate belief vectors.
Select — Appends the highest-ranked beliefs into the system message until the budget is full.

Confidence Caps & Judge Timeout

Control per-source confidence ceilings and LLM judge timeouts to fine-tune extraction behavior.

Parameter	Type	Default	Description
`user_confidence_cap`	float	0.99	Maximum confidence for beliefs extracted from user messages. User claims are treated as near-ground-truth.
`assistant_confidence_cap`	float	0.85	Maximum confidence for beliefs extracted from assistant responses. LLM outputs are capped lower to account for potential hallucination.
`judge_timeout`	float	60.0	Timeout in seconds for LLM judge contradiction checks. If the judge does not respond within this window, the check is skipped.

Tip

The confidence caps are applied after extraction and after hedging calibration. If a hedging pattern lowers confidence below the cap, the cap has no additional effect.

config = TrackerConfig( # Cap user-extracted beliefs at 0.95 (not 0.99) user_confidence_cap=0.95, # Cap assistant-extracted beliefs at 0.70 (stricter hallucination guard) assistant_confidence_cap=0.70, # Judge timeout: 30 seconds (fail fast on slow judge) judge_timeout=30.0, )

Custom Prompts

Both internal LLM prompts are overridable. Useful when tuning extraction for a specific domain.

Extraction Prompt

Sent to the internal LLM adapter after each turn to structure facts into JSON lists.

Parameter	Type	Default	Description
`extract_prompt_template`	str	DEFAULT_EXTRACT_PROMPT	Universal extraction prompt used to extract beliefs from both user and assistant messages.
`extract_user_prompt_template`	str	Built-in	Template used for user messages. Instructs the model to resolve personal pronouns to `"USER"`.
`extract_assistant_prompt_template`	str	Built-in	Template used for assistant replies. Instructs the model to map first-person references to `"ASSISTANT"`.

from beliefstate import TrackerConfig config = TrackerConfig( extract_user_prompt_template="Extract user assertions: {response}. Format: JSON.", extract_assistant_prompt_template="Extract assistant assertions: {response}. Format: JSON." )

Expected Output Format

Custom extraction templates must output a JSON list of objects containing the following fields:

Field	Type	Required	Description
`subject`	str	required	Target of the claim, normalized to `"USER"`, `"ASSISTANT"`, or a proper noun.
`predicate`	str	required	The relationship or attribute connecting the subject and value (e.g. `"likes"`).
`value`	str	required	Factual claim value, normalized to standard formats (e.g. ISO currency or numbers).
`confidence`	float	required	Extraction certainty score assigned by the model, bounded between 0.0 and 1.0.
`belief_type`	str	None	Either `"assertion"` (default fact) or `"update"` (explicit correction of a stored belief).
`source`	str	None	Identifier recording which agent generated the response (e.g. `"user"` or `"assistant"`).
`is_hypothetical`	bool	None	Set to `True` if the claim is hypothetical, which excludes it from prompt injections.

Judge Prompt

Evaluates logic relationships between stored premise beliefs and new hypothesis facts.

Parameter	Type	Default	Description
`judge_prompt_template`	str	Built-in	Logical inference check template. Must contain the `{premise}` and `{hypothesis}` placeholders.

from beliefstate import TrackerConfig config = TrackerConfig( judge_prompt_template="""Analyze logical relation. Premise: {premise} Hypothesis: {hypothesis} Output JSON: {"relationship": "contradiction|entailment|neutral", "score": float}""" )

Tips for Writing Custom Prompts

Explicit JSON Format — Models occasionally wrap outputs in markdown formatting. Instruct the model to return raw JSON only.
Subject Normalisation — Norm values to "USER" or "ASSISTANT" to prevent duplicate keys in the data store.
Value Normalisation — Standardize digits (e.g. 5000 rather than five thousand) to ensure consistent lookups.
Testing Asynchronously — Set enable_background_tasks=False during prompt engineering to inspect extractions synchronously.