beliefstate 1.0.0__tar.gz

beliefstate-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,79 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  # ── Core-only import test ────────────────────────────────────────────
+  core-import:
+    runs-on: ubuntu-latest
+    name: Verify core import (no optional deps)
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+    - name: Install core only
+      run: python -m pip install -e .
+    - name: Verify import succeeds
+      run: |
+        python -c "from beliefstate import BeliefTracker, TrackerConfig, Belief; print('Core import OK')"
+        python -c "from beliefstate import OpenAIAdapter; assert OpenAIAdapter is None or callable(OpenAIAdapter); print('Lazy import OK')"
+
+  # ── Test matrix ──────────────────────────────────────────────────────
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+        cache: 'pip'
+
+    - name: Install base dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install -e .
+
+    - name: Install dev dependencies
+      run: |
+        python -m pip install -e ".[dev]"
+
+    - name: Install optional dependencies (non-blocking)
+      run: |
+        python -m pip install -e ".[openai,anthropic,ollama,litellm,redis,langchain,llamaindex,fastapi,flask]" || true
+
+    - name: Skip Gemini on Python 3.12+ (compatibility issue)
+      if: matrix.python-version == '3.10' || matrix.python-version == '3.11'
+      run: |
+        python -m pip install -e ".[gemini]" || true
+
+    - name: Run Ruff Linter
+      run: ruff check .
+
+    - name: Run Ruff Formatter Check
+      run: ruff format --check .
+
+    - name: Run Mypy Type Checker
+      run: |
+        mypy beliefstate
+
+    - name: Run Pytest
+      run: |
+        pytest -v --tb=short
+
+    - name: Run Pytest with Coverage
+      if: matrix.python-version == '3.12'
+      run: |
+        pytest --cov=beliefstate --cov-report=xml --cov-fail-under=55

beliefstate-1.0.0/.github/workflows/lint.yml

@@ -0,0 +1,36 @@
+name: Lint & Type Check
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    name: Lint and Type Check
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+        cache: 'pip'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install -e ".[dev]"
+        python -m pip install -e ".[openai,anthropic,ollama,litellm,redis,langchain,llamaindex,fastapi,flask]" || true
+
+    - name: Run Ruff Linter
+      run: ruff check .
+
+    - name: Run Ruff Formatter Check
+      run: ruff format --check .
+
+    - name: Run Mypy Type Checker
+      run: mypy beliefstate

beliefstate-1.0.0/.github/workflows/pages.yml

@@ -0,0 +1,41 @@
+name: Deploy GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - '.github/workflows/pages.yml'
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          # Upload entire docs repository
+          path: './docs'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

beliefstate-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,53 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build-n-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+
+    permissions:
+      id-token: write  # Mandatory for PyPI Trusted Publishing OIDC
+      contents: read
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.11"
+        cache: 'pip'
+
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install build
+
+    - name: Build binary wheel and source tarball
+      run: |
+        python -m build
+
+    - name: Check build artifacts
+      run: |
+        ls -lh dist/
+        tar -tzf dist/*.tar.gz | head -20
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        skip-existing: true
+
+    - name: Create GitHub Release
+      uses: softprops/action-gh-release@v1
+      if: startsWith(github.ref, 'refs/tags/')
+      with:
+        files: dist/*
+        draft: false
+        prerelease: false
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

beliefstate-1.0.0/.gitignore

@@ -0,0 +1,68 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Type hints
+.mypy_cache/
+
+# Linting
+.ruff_cache/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Project specific
+*.db
+*.sqlite3
+beliefstate.db
+demo_beliefs.db
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo

beliefstate-1.0.0/ADAPTER_AUDIT_REPORT.md

@@ -0,0 +1,132 @@
+# Adapter & Integration Production Readiness Audit
+
+## Date: June 18, 2026
+## Status: Audit Complete - Production Enhancements Required
+
+---
+
+## FINDINGS
+
+### CRITICAL ISSUES
+
+#### 1. **OpenAI Adapter - Missing Error Handling**
+- ❌ No retry logic for transient API errors (rate limits, timeouts)
+- ❌ No graceful handling of partial responses
+- ❌ No validation of API keys at initialization
+- ❌ No request timeout configuration
+- ✅ Response format parsing is robust
+
+#### 2. **Anthropic Adapter - Embedding Not Implemented**
+- ❌ `get_embedding()` and `get_embeddings()` raise NotImplementedError
+- ❌ No fallback mechanism to suggest alternatives
+- ❌ Requires manual setup with external embedding provider
+- ⚠️ Prompt-based JSON formatting is fragile, could fail with long schemas
+
+#### 3. **Gemini Adapter - API Incompatibility Risk**
+- ❌ Using experimental `google-genai` library (not stable)
+- ❌ Message format conversion may lose information
+- ❌ No handling of Gemini-specific response formats (safety ratings, etc.)
+- ❌ Missing configuration defaults for safety settings
+
+#### 4. **Ollama Adapter - No Validation**
+- ❌ No check for Ollama server availability
+- ❌ No model availability verification
+- ❌ No handling of malformed local responses
+- ⚠️ Assumes localhost:11434 without configuration
+
+#### 5. **LiteLLM Adapter - Incomplete**
+- ❌ Minimal implementation, missing error handling
+- ❌ No support for response schema validation
+- ❌ No provider-specific optimizations
+
+#### 6. **Integration Issues**
+- ❌ FastAPI middleware doesn't handle missing X-Session-ID gracefully
+- ❌ Flask integration may have threading issues with ContextVar
+- ❌ No rate limiting or circuit breaker at integration layer
+- ❌ Missing request/response logging for debugging
+- ❌ No support for distributed tracing (OpenTelemetry)
+
+### HIGH PRIORITY ISSUES
+
+#### 7. **Shared Concerns Across All Adapters**
+- ❌ No structured logging
+- ❌ No metrics/observability (request latency, errors, etc.)
+- ❌ No explicit timeout handling
+- ❌ No request deduplication (idempotency)
+- ❌ Missing documentation on required environment variables
+- ❌ No health check mechanism
+
+#### 8. **Response Parsing Fragility**
+- ❌ All adapters assume specific response structures
+- ❌ No fallback if response format changes
+- ❌ Minimal validation of extracted text
+
+#### 9. **Embedding Consistency**
+- ❌ Different embedding models have different dimensions
+- ❌ No automatic model dimension discovery
+- ❌ No validation that embedding dimensions match stored dimensions
+
+---
+
+## RECOMMENDATIONS
+
+### IMMEDIATE (Must Fix for Production)
+1. Add retry logic with exponential backoff to all adapters
+2. Implement proper embedding support or validation for Anthropic
+3. Add structured logging throughout
+4. Implement health checks for all providers
+5. Add request timeout configuration
+
+### SHORT-TERM (Should Fix)
+1. Add request deduplication / idempotency
+2. Implement proper error categorization (transient vs permanent)
+3. Add metrics collection (latency, errors, model drift)
+4. Add OpenTelemetry support for distributed tracing
+5. Validate embedding dimensions match cached values
+
+### LONG-TERM (Nice to Have)
+1. Provider-specific optimizations and features
+2. Advanced caching strategies
+3. A/B testing framework for models
+4. Cost tracking per request
+5. Provider health dashboards
+
+---
+
+## FILES AFFECTED
+
+### Adapters (Need Updates)
+- `beliefstate/adapters/base.py` - Add health check protocol
+- `beliefstate/adapters/openai.py` - Add retry, timeout, validation
+- `beliefstate/adapters/anthropic.py` - Add embedding fallback
+- `beliefstate/adapters/gemini.py` - Add safety handling, validation
+- `beliefstate/adapters/ollama.py` - Add server validation
+- `beliefstate/adapters/litellm.py` - Expand implementation
+- `beliefstate/adapters/common.py` - NEW: Shared utilities (retry, logging, etc.)
+
+### Integrations (Need Updates)
+- `beliefstate/integrations/fastapi.py` - Add error handling, logging
+- `beliefstate/integrations/flask.py` - Add thread safety, logging
+- `beliefstate/integrations/asgi.py` - Add middleware chain support
+- `beliefstate/integrations/common.py` - NEW: Shared integration utilities
+
+### New Files
+- `beliefstate/observability.py` - Logging, metrics, tracing
+- `beliefstate/resilience.py` - Already exists, enhance with more patterns
+- `beliefstate/health.py` - NEW: Health check utilities
+
+---
+
+## SUCCESS CRITERIA
+
+- ✅ All adapters have retry logic with exponential backoff
+- ✅ All adapters have timeout configuration
+- ✅ All adapters validate initialization (API keys, model availability)
+- ✅ All adapters have structured logging
+- ✅ All adapters have health check methods
+- ✅ All adapters handle embedding requirements explicitly
+- ✅ All integrations have error handling middleware
+- ✅ All integrations have request logging
+- ✅ All 37 existing tests still pass
+- ✅ No breaking API changes
+

beliefstate-1.0.0/CRITICAL_BLOCKERS_ANALYSIS.md

@@ -0,0 +1,216 @@
+# BeliefState: Critical Blockers - Verified Status
+
+## Status Summary
+This document audits the 4 "CRITICAL" blockers identified in the requirements against the actual codebase.
+
+---
+
+## BLOCKER #1: Belief @dataclass vs Pydantic BaseModel
+
+**STATUS**: ✅ **ALREADY FIXED**
+
+**Finding**: `models.py` already uses Pydantic BaseModel with field validation:
+```python
+class Belief(BaseModel):
+    subject: str
+    predicate: str
+    value: str
+    confidence: float = Field(ge=0.0, le=1.0)  # ← Validation present
+    turn: int
+    source: str
+    embedding: List[float] = Field(default_factory=list)
+```
+
+**Verification**:
+- RedisStore calls `belief.model_dump_json()` → works ✅
+- SQLiteStore calls `Belief()` constructor → works ✅
+- Field validation `ge=0.0, le=1.0` → present ✅
+
+**Action**: No fix needed for this task. Can mark #1 as complete, but add architecture enhancements:
+- Add `embedding_model: str` field (Task #7)
+- Add `created_at: datetime` field for TTL tracking
+- Add session context if needed
+
+---
+
+## BLOCKER #2: LocalNLIJudge Event Loop Blocking
+
+**STATUS**: ✅ **ALREADY FIXED**
+
+**Finding**: `judge.py` LocalNLIJudge.check() already uses `run_in_executor()`:
+
+```python
+async def check(self, old: Belief, new: Belief) -> Tuple[bool, float, str]:
+    # ...
+    loop = asyncio.get_running_loop()
+    pipeline_fn = self._pipeline
+    
+    # ✅ Runs in thread pool, doesn't block event loop
+    res = await loop.run_in_executor(
+        None, 
+        lambda: pipeline_fn({"text": premise, "text_pair": hypothesis})
+    )
+```
+
+**Verification**:
+- CPU-bound NLI inference wrapped in executor ✅
+- Event loop not blocked ✅
+
+**Action**: No fix needed for this task. Mark #2 as complete.
+
+---
+
+## BLOCKER #3: SQLiteBeliefStore Persistent Connection
+
+**STATUS**: ✅ **PARTIALLY FIXED** (reuses connection, but no lifecycle mgmt)
+
+**Finding**: SQLiteStore uses `_get_connection()` for connection reuse:
+
+```python
+async def _get_connection(self) -> Any:
+    if self._conn is None:
+        # ...
+        self._conn = await aiosqlite.connect(self.db_path)
+        # ...
+    return self._conn  # ← Reused across all calls
+```
+
+**What works**:
+- Connection is reused (not reopened per call) ✅
+- `:memory:` database works because same connection is reused ✅
+- File-based DB avoids connection pool exhaustion ✅
+
+**What's missing**:
+- No explicit `open()` / `close()` / context manager interface
+- Connection never cleaned up (no `__del__` or `await close()`)
+- Tests can't do `async with store: ...` cleanup
+
+**Action**: Add lifecycle management:
+```python
+async def open(self) -> None:
+    """Explicitly open and initialize the database."""
+    await self._get_connection()
+
+async def close(self) -> None:
+    """Explicitly close the database connection."""
+    if self._conn:
+        await self._conn.close()
+        self._conn = None
+
+async def __aenter__(self):
+    await self.open()
+    return self
+
+async def __aexit__(self, *args):
+    await self.close()
+```
+
+This is an **enhancement**, not a critical blocker. The current code works but lacks hygiene.
+
+---
+
+## BLOCKER #4: Demo Mock Mode Bypasses Pipeline
+
+**STATUS**: ⚠️ **PARTIALLY VERIFIED**
+
+**Finding**: Current `demo.py` uses real Ollama, not mocks:
+
+```python
+@tracker.wrap
+async def chat_with_ollama(messages):
+    client = ollama.AsyncClient()
+    response = await client.chat(model="qwen2.5:7b", messages=messages)
+    return response
+```
+
+**Analysis**:
+- ✅ Uses real Ollama (not hardcoded mock)
+- ✅ Real extractor runs (not replaced with mock)
+- ✅ Real adapter normalization happens
+- ✅ Real pipeline executes
+- ⚠️ Problem: Requires Ollama running locally to execute
+
+**Why previous note said "mock mode"**:
+- The requirement snippet mentioned: "When OPENAI_API_KEY is absent, demo.py replaces the entire extractor with hardcoded mock"
+- This doesn't exist in current code
+- The current demo just calls real Ollama
+
+**Improvement Opportunity**:
+Use `respx` to mock HTTP calls so demo works without external services:
+```python
+with respx.mock:
+    respx.post("https://api.ollama.ai/chat").mock(
+        return_value=httpx.Response(200, json=MOCK_RESPONSE)
+    )
+    await chat_with_ollama(messages)
+```
+
+This is an **enhancement for reliability**, not a critical blocker.
+
+---
+
+## SUMMARY: Which Blockers Are Real?
+
+| # | Blocker | Status | Impact | Action |
+|---|---------|--------|--------|--------|
+| 1 | Belief dataclass | ✅ Fixed | None | Mark complete |
+| 2 | Event loop blocking | ✅ Fixed | None | Mark complete |
+| 3 | SQLite connection | ⚠️ Works but inelegant | Low | Add lifecycle mgmt (enhancement) |
+| 4 | Demo mocking | ✅ Uses real Ollama | Low | Add respx mocking (improvement) |
+
+---
+
+## Actual Blockers to Address
+
+The real issues are in the **ARCH** category (tasks #5-10):
+
+1. **Dual-adapter pattern**: ✅ **ALREADY IMPLEMENTED**
+   - `internal_adapter` parameter exists in `BeliefTracker.__init__`
+   - Used for background tasks (extraction, detection)
+   - Working as designed
+
+2. **No max_beliefs enforcement**: ⚠️ **REAL ISSUE**
+   - Current: `get_context_prompt()` iterates all beliefs
+   - Needed: Cap at `config.max_beliefs` (default 50)
+
+3. **No embedding_model versioning**: Dimension mismatch crashes silently
+   - Current: Embeddings lack source info
+   - Needed: Store `embedding_model` field per belief
+
+4. **No ASK escalation**: Same conflict loops forever
+   - Current: ASK conflict notes stack infinitely
+   - Needed: Track conflicts, escalate to BLOCK if unresolved
+
+5. **Distributed dispatcher session leak**: Celery/RQ lose session context
+   - Current: ContextVar doesn't cross process boundary
+   - Needed: Serialize session_id in task payload
+
+6. **No entailment deduplication**: Duplicate beliefs clutter store
+   - Current: "likes Python" and "enjoys Python" both stored
+   - Needed: Use entailment score to deduplicate
+
+---
+
+## Revised Task Priority
+
+**Mark complete (already done)**:
+- #1 Belief Pydantic ✅
+- #2 Event loop ✅
+- #5 Dual-adapter ✅ (already in tracker.py)
+
+**Real fixes needed (ARCH + missing features)**:
+1. Add `max_beliefs` cap to `get_context_prompt()` (Task #6)
+2. Add embedding_model field to prevent dimension mismatch (Task #7)
+3. Implement ASK escalation logic (Task #8)
+4. Fix Celery/RQ session_id propagation (Task #9)
+5. Add entailment deduplication (Task #10)
+6. Add public query API (Task #11)
+7. Implement adapter auto-detection (Task #12)
+8. Add streaming support (Task #13)
+9. Store-level TTL (Task #14)
+10. OpenTelemetry integration (Task #15)
+
+**Nice-to-have enhancements**:
+- #3 SQLite lifecycle management (open/close context mgr)
+- #4 Demo respx mocking for reliability
+