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=300 )

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 backend. Supported options: `"sqlite"`, `"redis"`, or `"postgres"`.
`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.

Resolution Strategy

Controls how contradictions between new and existing beliefs are handled when a conflict is detected.

Parameter	Type	Default	Description
`resolution_strategy`	str	"overwrite"	How contradictions are resolved: `"overwrite"` replaces old belief, `"keep_old"` discards new belief, `"raise"` surfaces an error.

Strategy behaviors:

overwrite (default) — The new belief replaces the old one. No conflict note is generated.
keep_old — The new belief is discarded. A [BELIEF CONFLICT — kept old] note is appended to the response.
raise — A ValueError is raised. In background tasks, the error is buffered and accessible via get_pending_conflicts().

Note

Beliefs with belief_type="update" always overwrite existing beliefs regardless of the resolution strategy. The strategy only applies to belief_type="assertion" conflicts.

Context Injection Controls

Controls which beliefs are included when injecting context into system prompts.

Parameter	Type	Default	Description
`exclude_sources`	list[str]	["assistant"]	Sources to exclude from context injection. Default excludes assistant-generated beliefs.
`min_injection_confidence`	float	0.80	Minimum confidence required for a belief to be included in injected context.
`include_hypothetical_in_context`	bool	False	When True, hypothetical beliefs (`is_hypothetical=True`) are included in injected context.

Tip

By default, only user-sourced beliefs with confidence ≥ 0.80 are injected. This prevents low-confidence or assistant-generated beliefs from polluting the system prompt.

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	300	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.

Developer Dashboard

Enable the built-in web dashboard to inspect beliefs, track contradictions, compare sessions, and monitor pipeline activity in real time.

Parameter	Type	Default	Description
`enable_dashboard`	bool	False	Starts a FastAPI server with a browser UI at `http://127.0.0.1:8000`. Requires `fastapi`, `uvicorn`, and `sse-starlette`.

from beliefstate import BeliefTracker, TrackerConfig tracker = BeliefTracker( adapter=OpenAIAdapter(model="gpt-4o"), config=TrackerConfig( enable_dashboard=True, ), )

Tip

Once enabled, the dashboard URL appears in the terminal. Open it in your browser to access live charts, session comparison, contradiction heatmaps, global search, alert rules, keyboard shortcuts, and real-time SSE pipeline events. Install deps: pip install "beliefstate[dashboard]".

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.