Metadata-Version: 2.4
Name: alethex
Version: 0.1.0
Summary: Temporal Belief Consistency Engine — catch AI self-contradictions in real time
Author-email: Yugendhar S <jeevithamproject@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/codewithyug/alethex
Project-URL: Repository, https://github.com/codewithyug/alethex
Project-URL: Bug Tracker, https://github.com/codewithyug/alethex/issues
Project-URL: Model Card, https://huggingface.co/codewithyug/alethex-nli-deberta-v3-large
Keywords: nli,contradiction-detection,temporal-reasoning,belief-graph,rag,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: spacy>=3.0
Requires-Dist: sentence-transformers>=2.0
Requires-Dist: transformers>=4.30
Requires-Dist: torch>=2.0
Requires-Dist: networkx>=3.0
Requires-Dist: streamlit>=1.20
Requires-Dist: plotly>=5.0
Requires-Dist: pydantic>=2.0
Requires-Dist: dateparser>=1.1
Requires-Dist: openai>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: python-dateutil>=2.8
Requires-Dist: datasets>=2.0
Requires-Dist: scikit-learn>=1.0
Requires-Dist: onnxruntime>=1.16
Requires-Dist: loguru>=0.7
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Provides-Extra: langchain
Requires-Dist: langchain>=0.1; extra == "langchain"
Provides-Extra: llamaindex
Requires-Dist: llama-index>=0.10; extra == "llamaindex"
Dynamic: license-file

﻿# ALETHEX — Temporal Belief Consistency Engine

[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/pypi/v/alethex.svg)](https://pypi.org/project/alethex/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
[![CI](https://github.com/codewithyug/alethex/actions/workflows/ci.yml/badge.svg)](https://github.com/codewithyug/alethex/actions/workflows/ci.yml)
[![Model: DeBERTa-v3-Large](https://img.shields.io/badge/model-DeBERTa--v3--Large-orange.svg)](https://huggingface.co/codewithyug/alethex-nli-deberta-v3-large)
[![Accuracy: 92.8%](https://img.shields.io/badge/NLI%20accuracy-92.8%25-brightgreen.svg)](https://huggingface.co/codewithyug/alethex-nli-deberta-v3-large)

> Catch AI self-contradictions in real time — Chrome extension + Python engine that watches AI chat sessions and flags when the AI says something that contradicts what it said before.

---

## What Is ALETHEX?

ALETHEX is two things:

**1. Chrome Extension** — loads silently alongside your AI chats (ChatGPT, Claude, Gemini, Grok, Copilot) and shows a live **Consistency Index** badge. When the AI contradicts itself, ALETHEX flags it immediately.

**2. Python Library** — a full Temporal Belief Graph engine for researchers and developers building contradiction-aware RAG pipelines, LangChain memory, or LlamaIndex filters.

---

## Chrome Extension

### Install

1. Download `dist/alethex-extension-v1.0.0.zip` and unzip it
2. Open `chrome://extensions/` and enable **Developer mode** (top right)
3. Click **Load unpacked** and select the unzipped `extension/` folder
4. Visit ChatGPT, Claude, or Gemini — the ALETHEX badge appears automatically

### How It Works

```
Every AI reply
      |
  [Fast regex pass — ~0ms]
  Extract explicit facts (name, location, job, diet, age, etc.)
      |
  [NLI semantic pass — ~2-5s]
  Build all sentence pairs across the full conversation
  Run DeBERTa-v3-Large ONNX contradiction detection in-browser
      |
  [Consistency Index]
  CI = 1.0 - (conflicts + superseded x 0.5) / totalClaims
  ─────────────────────────────────────────────────────────
  1.0      = Fully consistent       (green)
  0.5-0.99 = Facts updated          (amber)
  < 0.5    = Active contradictions  (red)
```

The NLI model runs **100% in-browser** via Transformers.js — no server, no API calls. Downloaded once (~641MB), cached permanently.

### Example Detections

| Earlier statement | Later statement | Detected |
|---|---|---|
| "I live in New York." | "I moved to London last year." | contradiction (0.97) |
| "I am vegetarian." | "I had steak for dinner." | contradiction (0.94) |
| "I work at Google." | "My job at Microsoft keeps me busy." | contradiction (0.91) |
| "I am 25 years old." | "I turn 30 next week." | contradiction (0.88) |

---

## NLI Models on HuggingFace

Both models trained for 3 epochs on a unified 1M+ pair corpus (MultiNLI + SNLI + Temporal-NLI), no synthetic data.

| Model | Parameters | ONNX size | Accuracy | Link |
|-------|-----------|-----------|----------|------|
| **alethex-nli-deberta-v3-large** (default) | 400M | 641 MB | **92.8%** | [HuggingFace](https://huggingface.co/codewithyug/alethex-nli-deberta-v3-large) |
| alethex-nli-deberta-v3-small (lightweight) | 22M | 172 MB | 92.8% | [HuggingFace](https://huggingface.co/codewithyug/alethex-nli-deberta-v3-small) |

### Training Progression

| Epoch | Accuracy | Macro F1 | MCC |
|-------|----------|----------|-----|
| 1 | 91.94% | 91.94% | 0.879 |
| 2 | 92.51% | 92.52% | 0.887 |
| **3** | **92.80%** | **92.81%** | **0.892** |

Large model trained on 8x NVIDIA H100 80GB (BF16, effective batch size 2048). Small model trained on RTX 4050 Laptop GPU.

---

## Python Library

### Install

```bash
pip install alethex
```

Or from source:

```bash
git clone https://github.com/codewithyug/alethex.git
cd alethex
pip install -e .
```

Optional extras:

```bash
pip install "alethex[langchain]"    # LangChain integration
pip install "alethex[llamaindex]"   # LlamaIndex integration
pip install "alethex[dev]"          # dev tools (pytest, ruff, mypy)
```

### Quickstart

```python
import alethex

memories = [
    {"id": "m1", "timestamp": "2024-01-10", "text": "Alice works at Google in London."},
    {"id": "m2", "timestamp": "2024-06-15", "text": "Alice relocated to Tokyo and joined Anthropic."}
]
filtered = alethex.filter_context(memories)
# -> returns only m2 (m1 is superseded)
```

### Online Session Tracking

```python
from datetime import datetime
from alethex.streaming.online_session import OnlineBeliefTracker

tracker = OnlineBeliefTracker()
tracker.process_turn("user", "I live in London and work at Google.", datetime(2024, 1, 15))
tracker.process_turn("user", "I moved to Tokyo last week.", datetime(2024, 7, 1))

print(tracker.get_active_beliefs("user"))
print(tracker.get_current_ci())  # 0.75 — superseded fact detected
```

### LangChain / LlamaIndex

```python
# LangChain — drop-in reconciled memory
from alethex.integrations.langchain_memory import AlethexReconciledMemory

# LlamaIndex — post-processor that drops or annotates contradicted context
from alethex.integrations.llamaindex_filter import AlethexConsistencyFilter
```

### CLI

```bash
python -m alethex.cli run-pipeline --corpus dataset/corpus.jsonl --output-dir results/
python -m alethex.evaluation.eval_pipeline --samples 150
```

---

## Repository Structure

```
alethex/
|
+-- alethex/                    # Python package
|   +-- ingestion/              # Document loaders and schema
|   +-- extraction/             # Claim extraction (OpenIE + LLM)
|   +-- coreference/            # Cross-document entity linking
|   +-- temporal/               # TIMEX parsing and interval algebra
|   +-- relation/               # NLI classifier and LLM judge
|   +-- graph/                  # Temporal belief graph (MultiDiGraph)
|   +-- scoring/                # Consistency Index calculation
|   +-- optim/                  # ONNX export and INT8 runtime
|   +-- training/               # NLI fine-tuning trainer
|   +-- streaming/              # Incremental OnlineBeliefTracker
|   +-- integrations/           # LangChain, LlamaIndex, MCP, OpenAI proxy
|   \-- evaluation/             # Benchmarking suite
|
+-- extension/                  # Chrome extension (MV3 source)
|   +-- manifest.json
|   +-- background.js           # Service worker
|   +-- content.js              # Chat page observer
|   +-- nli_worker.js           # NLI Web Worker (Transformers.js)
|   +-- popup.html / popup.js   # Extension popup UI
|   \-- vendor/                 # Bundled transformers.min.js (no CDN)
|
+-- configs/                    # Training and inference YAML configs
+-- dataset/                    # Preprocessed NLI data (gitignored — large files)
+-- docs/                       # Documentation and training reference
+-- experiments/                # Evaluation scripts and experiments
+-- models/                     # Model checkpoints and ONNX (gitignored — large files)
|   +-- alethex-nli/            # Small model checkpoints
|   +-- alethex-nli-large/      # Large model (H100 trained, 1.7GB)
|   +-- alethex-nli-onnx/       # Small ONNX (172MB quantized)
|   \-- alethex-nli-large-onnx/ # Large ONNX (641MB quantized)
+-- paper/                      # Draft paper and figures
+-- results/                    # Training logs and benchmark reports
+-- scripts/                    # Utility scripts
|   +-- export_onnx.py          # Export checkpoint to ONNX + INT8
|   +-- analyze_training_results.py
|   +-- start_all.py
|   \-- alethex_desktop.py      # Desktop companion (MCP auto-attach)
+-- tests/                      # Test suite
+-- dist/                       # Packaged extension zip for download
+-- pyproject.toml
+-- requirements.txt
\-- LICENSE
```

---

## Export a Model to ONNX

```bash
python scripts/export_onnx.py \
  --checkpoint models/alethex-nli-large \
  --out-dir models/alethex-nli-large-onnx
```

---

## Testing

```bash
python -m pytest tests/ -v
```

---

## Citation

```bibtex
@misc{alethex2026,
  title  = {ALETHEX: Temporal Belief Consistency Engine for AI Chat Contradiction Detection},
  author = {codewithyug},
  year   = {2026},
  url    = {https://github.com/codewithyug/alethex}
}
```

---

## License

[Apache 2.0](LICENSE) — free for commercial and research use.
