TrackerConfig

TrackerConfig is a Pydantic BaseModel that controls every aspect of the belief tracking pipeline. It is passed to the BeliefTracker constructor at initialization time. All parameters have sensible defaults — you only need to override the ones relevant to your use case.

pythonfrom beliefstate import BeliefTracker, TrackerConfig

# Minimal config — all defaults
tracker = BeliefTracker(config=TrackerConfig())

# Custom config — override what you need
config = TrackerConfig(
    store_type="sqlite",
    store_kwargs={"db_path": "beliefs.db"},
    similarity_threshold=0.80,
    enable_background_tasks=True,
    max_beliefs=100,
)

Store Settings

These parameters determine where extracted beliefs are persisted. The store is the database backend that holds all subject-predicate-value triples for each user session. Choose a store based on your deployment model:

• "sqlite" — Best for single-process apps, local development, and prototyping. Data persists in a single file. Zero setup.
• "redis" — Best for multi-worker production deployments behind a load balancer. Shared state across processes with native TTL support.

Detection Settings

These three thresholds control the contradiction detection pipeline — the two-stage filter that determines whether a newly extracted belief conflicts with, duplicates, or is independent of existing beliefs in the store. Tuning these values directly impacts the precision and recall of contradiction detection.

How the Two-Stage Filter Works

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.

Resilience Settings

These parameters control how the tracker handles LLM API failures. Since belief extraction runs in the background, transient API errors should be retried automatically rather than silently dropping beliefs. The retry mechanism uses exponential backoff with jitter to prevent thundering herd problems when the provider recovers.

Task & Dispatcher Settings

These parameters control how belief tracking tasks are executed. By default, tracking runs as fire-and-forget asyncio background tasks in the same event loop as your application. For production deployments that require task durability (surviving process restarts), you can offload to Celery or RQ workers.

Internal Provider Override

By default, the tracker uses the same LLM adapter as your application for all internal operations (extraction, contradiction detection, embeddings). You can override this to use a separate, cheaper model for background tracking via the Dual-Adapter pattern.

Belief Storage & Injection

These parameters control how beliefs are selected and formatted when injecting context into your LLM prompts via get_context_prompt() or inject_context(). They determine which beliefs are surfaced, how many, and in what order.

Belief TTL (Time-to-Live)

These parameters enable automatic pruning of old beliefs based on age. Useful for applications where user preferences change frequently and stale beliefs should be automatically cleaned up rather than manually managed.

Staleness Scoring

When a user resumes an old session after days or weeks, some beliefs may no longer be relevant (e.g., "USER is working on a project X" from 10 days ago). Staleness scoring deprioritizes old beliefs during prompt injection without deleting them, keeping the context prompt focused on recent, high-confidence information.

Staleness Decay Formula

Each belief is scored using:

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

Examples:

• A belief with confidence 1.0, referenced today → Score = 1.0 / (0 + 1) = 1.0 ✅ (included)
• A belief with confidence 0.8, referenced 3 days ago → Score = 0.8 / (3 + 1) = 0.2 ✅ (included)
• A belief with confidence 0.5, referenced 10 days ago → Score = 0.5 / (10 + 1) = 0.045 ❌ (excluded, below 0.1)

Token-Aware Injection

For users with many accumulated beliefs, the formatted context prompt can grow very large, consuming a significant portion of the LLM's context window. Token-aware injection automatically selects the most relevant beliefs when the total would exceed a token budget, using cosine similarity with the current user message to rank relevance.

Token-Aware Filtering Cascade

When enable_token_aware_injection=True and a current_user_message is provided, the filtering works as follows:

1. Estimate — Format all candidate beliefs and count tokens using the 1 token ≈ 4 chars heuristic.
2. Check budget — If estimated tokens ≤ belief_budget_tokens, use all beliefs (no filtering needed).
3. Embed query — Generate a vector embedding of the current user message.
4. Rank beliefs — Compute cosine similarity between the user message embedding and each belief's stored embedding.
5. Select top-K — Fill beliefs from highest to lowest relevance until the token budget is reached.

Custom Prompts

BeliefState uses two LLM prompts internally for the tracking pipeline. The extraction prompt parses conversation text into structured beliefs. The judge prompt evaluates whether two beliefs contradict, entail, or are neutral to each other. You can override both via TrackerConfig to customize behavior for your domain.

Extraction Prompt

This prompt is sent to the internal adapter after each LLM conversation turn. It instructs the model to parse the response text and extract factual claims as structured JSON objects.

pythonconfig = TrackerConfig(
    extract_user_prompt_template="""Extract beliefs from user text: {response}""",
    extract_assistant_prompt_template="""Extract beliefs from assistant text: {response}""",
)

Expected Output Format

The extraction prompt must instruct the model to return a JSON array where each object has these fields:

Judge Prompt

This prompt is sent to the internal adapter during contradiction detection. It evaluates the logical relationship between two beliefs (a "premise" and a "hypothesis").

pythonconfig = TrackerConfig(
    judge_prompt_template="""Analyze these two claims.
Premise: {premise}
Hypothesis: {hypothesis}
Return {"relationship": "contradiction|entailment|neutral", "score": 0.0-1.0}"""
)

Tips for Writing Custom Prompts

• Be explicit about output format: The tracker parses the model's output as JSON. Include format examples in your prompt.
• Subject normalization matters: The default prompt normalizes first-person pronouns to "USER" and second-person to "ASSISTANT". If you override the extraction prompt, include similar normalization rules to ensure consistent subject keys in the store.
• Value normalization: The default prompt normalizes dates (ISO 8601), currencies (ISO 4217), and numbers (digits only). This prevents near-duplicate beliefs like "has $5,000" vs "has USD 5000".
• Test with enable_background_tasks=False: When iterating on prompt design, disable background tasks so you can synchronously inspect extraction results.