Metadata-Version: 2.4
Name: contextdecay
Version: 0.2.0
Summary: Persistent, cross-session context decay detection for LLM apps. Track how much your Claude session has drifted from its original context.
License: MIT
Project-URL: Homepage, https://github.com/yourusername/contextdecay
Project-URL: Repository, https://github.com/yourusername/contextdecay
Project-URL: Issues, https://github.com/yourusername/contextdecay/issues
Keywords: llm,anthropic,claude,context,drift,decay,evaluation,agents
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anthropic>=0.25.0
Requires-Dist: sentence-transformers>=2.7.0
Requires-Dist: numpy>=1.24.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Dynamic: license-file

# contextdecay

**Persistent, cross-session context decay detection for LLM apps.**

`contextdecay` tracks how much your Claude session has drifted from its original context — across multiple sessions — and surfaces it on demand via `decaycheck()` or the `contextdecay check` CLI command.

---

## Install

```bash
pip install contextdecay
```

---

## Quick start

```python
from anthropic import Anthropic
from contextdecay import ContextDecayDetector

client = Anthropic()
detector = ContextDecayDetector(client, persist="./myapp.decay")

# Normal calls — zero overhead
response = detector.messages.create(
    model="claude-haiku-4-5-20251001",
    system="You are a customer support assistant for RetailCo.",
    messages=[{"role": "user", "content": "What is your return policy?"}],
    max_tokens=200,
)

# Check drift on demand
report = detector.decaycheck()
print(report)
```

Output:
```
DecayReport (sessions=3, turns=18)
  cumulative : score=0.721 | on_track | OK
  recent     : score=0.812 | on_track | OK
```

---

## How it works

```
Session 1, msgs 1–5  →  original context fingerprint captured + saved to .decay file
Session N, any turn  →  response embedded locally (~20ms) — zero API cost
decaycheck()         →  cumulative score (vs original) + recent score (vs last check)
                     →  if triggered: Haiku explains what drifted
                     →  checkpoint updated
```

**Original context** = system prompt + first 5 user+assistant messages.
**Fingerprint** = persisted to a local `.decay` JSON file — survives across sessions.

---

## CLI

```bash
# Check drift now (requires ANTHROPIC_API_KEY)
contextdecay check
contextdecay check --file ./myapp.decay

# Inspect fingerprint metadata (no API call)
contextdecay status
contextdecay status --file ./myapp.decay

# Reset — wipe fingerprint and start fresh
contextdecay reset
contextdecay reset --file ./myapp.decay
```

---

## DecayReport

```python
report = detector.decaycheck()

# Cumulative: vs original context (session 1)
report.cumulative.score        # 0.38
report.cumulative.level        # DecayLevel.SIGNIFICANT
report.cumulative.triggered    # True
report.cumulative.explanation  # "Responses shifted from retail support to..."

# Recent: vs last decaycheck() call
report.recent.score            # 0.71
report.recent.level            # DecayLevel.ON_TRACK
report.recent.triggered        # False

# Session metadata
report.session_count           # 4
report.total_turns             # 23
```

---

## Decay levels

| Score | Level | Meaning |
|---|---|---|
| ≥ 0.55 | `on_track` | Aligned with original context |
| 0.40 – 0.54 | `mild` | Some drift |
| 0.25 – 0.39 | `significant` | Noticeable drift |
| < 0.25 | `severe` | Serious misalignment |

---

## Configuration

```python
detector = ContextDecayDetector(
    client,
    persist="./myapp.decay",       # where to store the fingerprint
    threshold=0.40,                 # trigger sensitivity
    explain=True,                   # Haiku explains drift on trigger
    embedding_model="all-MiniLM-L6-v2",
    explainer_model="claude-haiku-4-5-20251001",
)
```

---

## Session management

```python
# Check if original context has been captured yet
detector.is_fingerprinted   # True after 5 messages

# Current session and turn counts
detector.session            # 3
detector.turn               # 18

# Wipe everything and start fresh
detector.reset()
```

---

## Cost and latency

| Operation | Extra tokens | Cost | Latency |
|---|---|---|---|
| Normal API call | 0 | $0 | ~20ms (local embed) |
| `decaycheck()` — no trigger | 0 | $0 | <5ms |
| `decaycheck()` — triggered | ~300 | ~$0.0003 | +500ms |
| First run (model download) | 0 | $0 | ~3s one-time |

---

## Run the example

```bash
ANTHROPIC_API_KEY=your_key python3 examples/quickstart.py
```

---

## Run tests

```bash
pip install -e ".[dev]"
pytest tests/ -v
```

---

## Roadmap

- [ ] Multi-anchor support
- [ ] Decay history timeline
- [ ] Streaming support
- [ ] OpenAI / Gemini adapters
- [ ] Web dashboard

---

## License

MIT
