Metadata-Version: 2.4
Name: beliefstate
Version: 1.2.0
Summary: A sidecar belief state tracker for LLM agents to detect contradictions and maintain persistent facts.
Project-URL: Homepage, https://github.com/abhay-2108/beliefstate
Project-URL: Repository, https://github.com/abhay-2108/beliefstate
Project-URL: Documentation, https://abhay-2108.github.io/beliefstate/
Project-URL: Issues, https://github.com/abhay-2108/beliefstate/issues
Project-URL: Changelog, https://github.com/abhay-2108/beliefstate/blob/main/CHANGELOG.md
Author: Abhay Tiwari
License: Apache-2.0
License-File: LICENSE
Keywords: agent,belief-state,contradiction-detection,langchain,llm,memory,openai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: aiosqlite>=0.18.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0
Requires-Dist: tenacity>=8.0.0
Provides-Extra: all
Requires-Dist: anthropic>=0.25.0; extra == 'all'
Requires-Dist: asyncpg>=0.28.0; extra == 'all'
Requires-Dist: fastapi>=0.95.0; extra == 'all'
Requires-Dist: flask>=2.2.0; extra == 'all'
Requires-Dist: google-generativeai>=0.5.0; extra == 'all'
Requires-Dist: langchain-core>=0.2.0; extra == 'all'
Requires-Dist: litellm>=1.40.0; extra == 'all'
Requires-Dist: llama-index-core>=0.10.0; extra == 'all'
Requires-Dist: numpy>=1.20; extra == 'all'
Requires-Dist: ollama>=0.2.0; extra == 'all'
Requires-Dist: openai>=1.0.0; extra == 'all'
Requires-Dist: redis>=5.0.0; extra == 'all'
Requires-Dist: sentence-transformers>=2.7; extra == 'all'
Requires-Dist: sse-starlette>=1.6.0; extra == 'all'
Requires-Dist: torch>=2.0; extra == 'all'
Requires-Dist: uvicorn>=0.22.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.25.0; extra == 'anthropic'
Provides-Extra: dashboard
Requires-Dist: fastapi>=0.95.0; extra == 'dashboard'
Requires-Dist: sse-starlette>=1.6.0; extra == 'dashboard'
Requires-Dist: uvicorn>=0.22.0; extra == 'dashboard'
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: respx>=0.20.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.95.0; extra == 'fastapi'
Provides-Extra: flask
Requires-Dist: flask>=2.2.0; extra == 'flask'
Provides-Extra: gemini
Requires-Dist: google-generativeai>=0.5.0; extra == 'gemini'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.2.0; extra == 'langchain'
Provides-Extra: litellm
Requires-Dist: litellm>=1.40.0; extra == 'litellm'
Provides-Extra: llamaindex
Requires-Dist: llama-index-core>=0.10.0; extra == 'llamaindex'
Provides-Extra: local
Requires-Dist: numpy>=1.20; extra == 'local'
Requires-Dist: sentence-transformers>=2.7; extra == 'local'
Requires-Dist: torch>=2.0; extra == 'local'
Provides-Extra: ollama
Requires-Dist: ollama>=0.2.0; extra == 'ollama'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.28.0; extra == 'postgres'
Provides-Extra: redis
Requires-Dist: redis>=5.0.0; extra == 'redis'
Description-Content-Type: text/markdown

<h1 align="center">BeliefState</h1>

<p align="center">
  Persistent memory for LLM applications.<br>
  Extract facts, resolve contradictions, and recall knowledge — automatically.
</p>

<p align="center">
  <a href="https://pypi.org/project/beliefstate/"><img src="https://img.shields.io/pypi/v/beliefstate?color=blue" alt="PyPI"></a>
  <a href="https://github.com/abhay-2108/beliefstate/blob/main/LICENSE"><img src="https://img.shields.io/github/license/abhay-2108/beliefstate" alt="License"></a>
  <a href="https://pypi.org/project/beliefstate/"><img src="https://img.shields.io/pypi/pyversions/beliefstate" alt="Python"></a>
  <a href="https://github.com/abhay-2108/beliefstate/actions/workflows/ci.yml"><img src="https://github.com/abhay-2108/beliefstate/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://github.com/abhay-2108/beliefstate/actions/workflows/lint.yml"><img src="https://github.com/abhay-2108/beliefstate/actions/workflows/lint.yml/badge.svg" alt="Lint"></a>
  <a href="https://abhay-2108.github.io/beliefstate/"><img src="https://img.shields.io/badge/docs-online-brightgreen" alt="Docs"></a>
</p>

---

## The Problem

Every time a user starts a new conversation, your LLM starts from zero. It doesn't remember that the user is a Rust developer in Berlin, prefers dark mode, or already explained their project architecture three messages ago.

You can dump the full chat history into the system prompt, but that burns tokens fast — and most of it is noise. RAG helps with documents, but **user facts** (preferences, identity, context) fall through the cracks. There's no clean way to say "remember this about the user" without manual bookkeeping.

## How BeliefState Works

BeliefState sits between your LLM and your application. Every time the LLM responds, it silently:

1. **Extracts facts** — "user prefers Rust", "project uses PostgreSQL", "works at Google"
2. **Detects contradictions** — if the user says "I live in Tokyo" after saying "I live in Berlin", it flags the conflict
3. **Stores beliefs** — persisted in SQLite, PostgreSQL, or Redis with full history
4. **Injects context** — on the next call, relevant beliefs are added to the system prompt automatically

All of this happens in the background. Zero added latency to your request path.

```python
from beliefstate import BeliefTracker
from beliefstate.adapters import OpenAIAdapter

tracker = BeliefTracker(
    adapter=OpenAIAdapter(model="gpt-4o"),
    config=TrackerConfig(store_type="sqlite", store_kwargs={"db_path": "beliefs.db"})
)

@tracker.wrap
async def chat(messages):
    return await openai_client.chat.completions.create(model="gpt-4o", messages=messages)

tracker.set_session("user_123")
await chat([{"role": "user", "content": "I live in Tokyo and work at Google."}])
# BeliefState extracts: {subject: "user", predicate: "lives_in", value: "Tokyo"}
```

---

## Features

| Feature | Description |
|---------|-------------|
| **Zero-latency tracking** | Background extraction pipeline — no added latency to your request path |
| **Dual-source extraction** | Extracts beliefs from both user messages and assistant responses every turn |
| **5+ LLM providers** | OpenAI, Anthropic, Gemini, Ollama, LiteLLM (100+ models via LiteLLM) |
| **Dual-adapter architecture** | Expensive model for your app, cheap/local model for background tracking |
| **NLI contradiction detection** | 3-stage pipeline: rule-based → embedding similarity → LLM judge, with negation awareness and exact-match dedup |
| **3 resolution strategies** | `overwrite`, `keep_old`, or `raise` — with escalation logic (ASK → BLOCK) and per-belief resolution notes |
| **Confidence calibration** | Automatic hedging detection, per-source confidence caps (user/assistant), hypothetical flagging |
| **Belief categorization** | Extracted beliefs grouped into 5 categories: identity, technical, planning, constraint, state |
| **Persistent stores** | SQLite, PostgreSQL, Redis — with full audit trails, binary embedding storage, and automatic schema migration |
| **Streaming support** | `@tracker.wrap(stream=True)` intercepts async generators, accumulates text, and dispatches tracking on completion |
| **Automatic context injection** | Relevant beliefs injected into the system prompt on every call — with category-grouped summarization |
| **Token-aware injection** | Relevance-based belief selection within a configurable token budget using vector similarity |
| **Framework integrations** | LangChain, LlamaIndex, FastAPI, Flask, ASGI, WSGI, OpenAI Assistants |
| **Production resilience** | Retry with exponential backoff, circuit breakers (per operation), health checks, graceful shutdown with task draining |
| **Pluggable dispatchers** | Asyncio (in-process), Sync, Celery, Redis Queue — survives server restarts |
| **GDPR-compliant** | `clear_session()` with auditable deletion receipts and in-flight task draining |
| **Staleness scoring & TTL** | Automatic belief decay (`confidence / days_since_reference`) and configurable time-based pruning |
| **Belief export/import** | JSON round-trip for portable belief data; CSV export via dashboard |
| **Developer Dashboard** | Live browser UI with charts, session compare, contradiction heatmaps, global search, alert rules, keyboard shortcuts, and real-time SSE pipeline events |
| **Observability** | OpenTelemetry traces and metrics, structured `TrackerEvent` logging with JSON output |

---

## Installation

```bash
pip install beliefstate
```

With optional extras:

```bash
pip install "beliefstate[openai]"         # OpenAI adapter
pip install "beliefstate[anthropic]"      # Anthropic adapter
pip install "beliefstate[gemini]"         # Gemini adapter
pip install "beliefstate[ollama]"         # Ollama adapter (local)
pip install "beliefstate[litellm]"        # LiteLLM (100+ providers)
pip install "beliefstate[local]"          # Local embeddings (sentence-transformers)
pip install "beliefstate[redis]"          # Redis store
pip install "beliefstate[postgres]"       # PostgreSQL store
pip install "beliefstate[langchain]"      # LangChain integration
pip install "beliefstate[llamaindex]"     # LlamaIndex integration
pip install "beliefstate[fastapi]"        # FastAPI middleware
pip install "beliefstate[flask]"          # Flask middleware
pip install "beliefstate[dashboard]"      # Developer dashboard (fastapi, uvicorn)
pip install "beliefstate[all]"            # Everything
```

---

## Documentation

For provider setup, store configuration, framework integrations, advanced usage, and API reference:

**[https://abhay-2108.github.io/beliefstate/](https://abhay-2108.github.io/beliefstate/)**

---

## Quick Example: Dual-Adapter Setup

Use Claude for your app, Llama 3 for background tracking — zero API costs for belief extraction:

```python
from beliefstate import BeliefTracker
from beliefstate.adapters import AnthropicAdapter, OllamaAdapter

tracker = BeliefTracker(
    adapter=AnthropicAdapter(model="claude-3-5-sonnet-latest"),
    internal_adapter=OllamaAdapter(model="llama3", embed_model="nomic-embed-text"),
)
```

---

## Development

```bash
git clone https://github.com/abhay-2108/beliefstate.git
cd beliefstate
pip install -e ".[dev]"
pytest
ruff check beliefstate/
```

---

## Contributing

Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on the development setup, coding standards, and pull request process.

This project follows a [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you agree to uphold it.

For security vulnerabilities, please see our [Security Policy](SECURITY.md).

For version history, see the [Changelog](CHANGELOG.md).

---

## License

Apache License 2.0. See [LICENSE](LICENSE) for details.
