streamctx 0.3.0__tar.gz

streamctx-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sneh R Joshi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

streamctx-0.3.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: streamctx
+Version: 0.3.0
+Summary: Context health monitoring for AI agents — detect poisoning, drift, loops
+Home-page: https://github.com/streamctx/streamctx
+Author: Sneh R Joshi
+Author-email: joshisneh51@gmail.com
+Keywords: llm,ai,agent,context,monitoring,observability,openai,anthropic,token,checkpoint,compression,self-healing
+Classifier: Development Status :: 4 - Beta
+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 :: Software Development :: Libraries
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.0.0
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.25.0; extra == "anthropic"
+Provides-Extra: all
+Requires-Dist: openai>=1.0.0; extra == "all"
+Requires-Dist: anthropic>=0.25.0; extra == "all"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+
+# StreamCtx 🧠
+
+**Your AI agent is silently corrupting its own context. StreamCtx detects it — and fixes it.**
+
+## Install
+
+pip install streamctx
+
+## 2-Line Setup
+
+import streamctx
+streamctx.start()  # patches OpenAI + Anthropic automatically
+
+---
+
+## The Problem Nobody Talks About
+
+You ship an AI agent. It works perfectly in demos.
+
+Then in production:
+- Agent gets stuck repeating the same failed action 58 times
+- Context from step 3 contradicts context from step 7
+- Agent hallucinates a tool call, writes it to memory, references it forever
+- Your $0.50 task costs $50 because nobody set a limit
+
+Every LLM observability tool tracks tokens. Nobody tracks context health.
+
+Until now.
+
+---
+
+## What StreamCtx Does
+
+### 1. Context Poison Detection
+
+result = streamctx.scan(messages)
+print(result["health_score"])    # 25/100
+print(result["warnings"])
+# ⚠️  Repeated errors: 'failed' 4x — agent stuck in loop
+# 🚨 Context severely poisoned — resume from checkpoint
+
+### 2. Context Diff — See Exactly What Changed
+
+diff = streamctx.context_diff(step3_msgs, step7_msgs, step_a=3, step_b=7)
+print(diff["summary"])
+# ⚠️  System prompt REMOVED — agent lost instructions
+# ⚠️  Contradiction: 'use gpt' added but 'use claude' removed
+# Drift Score: 50/100
+
+### 3. Auto-Checkpoint + Resume
+
+session_id = streamctx.get_session_id()
+messages = streamctx.resume(session_id)
+# Pick up exactly where agent left off
+
+### 4. 50% Token Compression
+
+result = streamctx.compress(messages, max_tokens=2000)
+# 140 tokens → 70 tokens (50% reduction)
+
+### 5. Self-Healing
+
+stats = streamctx.healing_stats()
+# failures: 1, recoveries: 1
+
+### 6. Full Session Report
+
+streamctx.report()
+streamctx.stop()
+
+---
+
+## Feature Comparison
+
+Feature              | StreamCtx | Langfuse | LangSmith | Mem0
+---------------------|-----------|----------|-----------|-----
+Token tracking       |     YES   |    YES   |    YES    |  NO
+Cost estimation      |     YES   |    YES   |    YES    |  NO
+Context Poison Det.  |     YES   |    NO    |    NO     |  NO
+Context Diff         |     YES   |    NO    |    NO     |  NO
+Auto-checkpoint      |     YES   |    NO    |    NO     |  NO
+50% Compression      |     YES   |    NO    |    NO     |  NO
+Self-healing         |     YES   |    NO    |    NO     |  NO
+Zero config          |     YES   |    NO    |    NO     |  NO
+Open source          |     YES   |    YES   |    NO     |  NO
+
+---
+
+## Quick Start
+
+import streamctx
+from openai import OpenAI
+
+streamctx.start()
+client = OpenAI()
+
+messages = [{"role": "user", "content": "Hello!"}]
+response = client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=messages,
+)
+
+result = streamctx.scan(messages)
+print(result["health_score"])
+print(result["recommendation"])
+
+streamctx.report()
+streamctx.stop()
+
+---
+
+## API Reference
+
+streamctx.start()                    # start tracking
+streamctx.stop()                     # stop tracking
+streamctx.report()                   # print full report
+streamctx.wrap(client)               # manually wrap client
+
+streamctx.scan(messages)             # context health score
+streamctx.context_diff(a, b)         # compare two steps
+
+streamctx.checkpoint()               # save checkpoint
+streamctx.resume(session_id)         # resume from checkpoint
+streamctx.get_session_id()           # current session ID
+
+streamctx.compress(messages)         # 50% token compression
+streamctx.healing_stats()            # self-healing stats
+
+---
+
+## Why StreamCtx?
+
+Most tools answer: "How many tokens did I use?"
+
+StreamCtx answers: "Why is my agent broken — and how do I fix it?"
+
+---
+
+## Roadmap
+
+DONE:
+- Token tracking + cost estimation
+- Context poison detection
+- Context diff + drift scoring
+- Auto-checkpoint + resume
+- 50% token compression
+- Self-healing engine
+
+COMING:
+- Context budget manager (v0.4.0)
+- Visual dashboard
+- Multi-agent support
+
+---
+
+## License
+
+MIT - Sneh R Joshi
+
+Built by a solo founder who got tired of AI agents silently going insane.
+
+

streamctx-0.3.0/README.md

@@ -0,0 +1,163 @@
+
+# StreamCtx 🧠
+
+**Your AI agent is silently corrupting its own context. StreamCtx detects it — and fixes it.**
+
+## Install
+
+pip install streamctx
+
+## 2-Line Setup
+
+import streamctx
+streamctx.start()  # patches OpenAI + Anthropic automatically
+
+---
+
+## The Problem Nobody Talks About
+
+You ship an AI agent. It works perfectly in demos.
+
+Then in production:
+- Agent gets stuck repeating the same failed action 58 times
+- Context from step 3 contradicts context from step 7
+- Agent hallucinates a tool call, writes it to memory, references it forever
+- Your $0.50 task costs $50 because nobody set a limit
+
+Every LLM observability tool tracks tokens. Nobody tracks context health.
+
+Until now.
+
+---
+
+## What StreamCtx Does
+
+### 1. Context Poison Detection
+
+result = streamctx.scan(messages)
+print(result["health_score"])    # 25/100
+print(result["warnings"])
+# ⚠️  Repeated errors: 'failed' 4x — agent stuck in loop
+# 🚨 Context severely poisoned — resume from checkpoint
+
+### 2. Context Diff — See Exactly What Changed
+
+diff = streamctx.context_diff(step3_msgs, step7_msgs, step_a=3, step_b=7)
+print(diff["summary"])
+# ⚠️  System prompt REMOVED — agent lost instructions
+# ⚠️  Contradiction: 'use gpt' added but 'use claude' removed
+# Drift Score: 50/100
+
+### 3. Auto-Checkpoint + Resume
+
+session_id = streamctx.get_session_id()
+messages = streamctx.resume(session_id)
+# Pick up exactly where agent left off
+
+### 4. 50% Token Compression
+
+result = streamctx.compress(messages, max_tokens=2000)
+# 140 tokens → 70 tokens (50% reduction)
+
+### 5. Self-Healing
+
+stats = streamctx.healing_stats()
+# failures: 1, recoveries: 1
+
+### 6. Full Session Report
+
+streamctx.report()
+streamctx.stop()
+
+---
+
+## Feature Comparison
+
+Feature              | StreamCtx | Langfuse | LangSmith | Mem0
+---------------------|-----------|----------|-----------|-----
+Token tracking       |     YES   |    YES   |    YES    |  NO
+Cost estimation      |     YES   |    YES   |    YES    |  NO
+Context Poison Det.  |     YES   |    NO    |    NO     |  NO
+Context Diff         |     YES   |    NO    |    NO     |  NO
+Auto-checkpoint      |     YES   |    NO    |    NO     |  NO
+50% Compression      |     YES   |    NO    |    NO     |  NO
+Self-healing         |     YES   |    NO    |    NO     |  NO
+Zero config          |     YES   |    NO    |    NO     |  NO
+Open source          |     YES   |    YES   |    NO     |  NO
+
+---
+
+## Quick Start
+
+import streamctx
+from openai import OpenAI
+
+streamctx.start()
+client = OpenAI()
+
+messages = [{"role": "user", "content": "Hello!"}]
+response = client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=messages,
+)
+
+result = streamctx.scan(messages)
+print(result["health_score"])
+print(result["recommendation"])
+
+streamctx.report()
+streamctx.stop()
+
+---
+
+## API Reference
+
+streamctx.start()                    # start tracking
+streamctx.stop()                     # stop tracking
+streamctx.report()                   # print full report
+streamctx.wrap(client)               # manually wrap client
+
+streamctx.scan(messages)             # context health score
+streamctx.context_diff(a, b)         # compare two steps
+
+streamctx.checkpoint()               # save checkpoint
+streamctx.resume(session_id)         # resume from checkpoint
+streamctx.get_session_id()           # current session ID
+
+streamctx.compress(messages)         # 50% token compression
+streamctx.healing_stats()            # self-healing stats
+
+---
+
+## Why StreamCtx?
+
+Most tools answer: "How many tokens did I use?"
+
+StreamCtx answers: "Why is my agent broken — and how do I fix it?"
+
+---
+
+## Roadmap
+
+DONE:
+- Token tracking + cost estimation
+- Context poison detection
+- Context diff + drift scoring
+- Auto-checkpoint + resume
+- 50% token compression
+- Self-healing engine
+
+COMING:
+- Context budget manager (v0.4.0)
+- Visual dashboard
+- Multi-agent support
+
+---
+
+## License
+
+MIT - Sneh R Joshi
+
+Built by a solo founder who got tired of AI agents silently going insane.
+
+

streamctx-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

streamctx-0.3.0/setup.py

@@ -0,0 +1,43 @@
+from setuptools import find_packages, setup
+
+with open("README.md", encoding="utf-8") as f:
+    long_description = f.read()
+
+setup(
+    name="streamctx",
+    version="0.3.0",
+    description="Context health monitoring for AI agents — detect poisoning, drift, loops",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    author="Sneh R Joshi",
+    author_email="joshisneh51@gmail.com",
+    url="https://github.com/streamctx/streamctx",
+    packages=find_packages(where="src"),
+    package_dir={"": "src"},
+    python_requires=">=3.9",
+    install_requires=[
+        "rich>=13.0.0",
+    ],
+    extras_require={
+        "openai": ["openai>=1.0.0"],
+        "anthropic": ["anthropic>=0.25.0"],
+        "all": ["openai>=1.0.0", "anthropic>=0.25.0"],
+    },
+    classifiers=[
+        "Development Status :: 4 - Beta",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Topic :: Software Development :: Libraries",
+        "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    ],
+    keywords=[
+        "llm", "ai", "agent", "context", "monitoring",
+        "observability", "openai", "anthropic", "token",
+        "checkpoint", "compression", "self-healing",
+    ],
+)

streamctx-0.3.0/src/streamctx.egg-info/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: streamctx
+Version: 0.3.0
+Summary: Context health monitoring for AI agents — detect poisoning, drift, loops
+Home-page: https://github.com/streamctx/streamctx
+Author: Sneh R Joshi
+Author-email: joshisneh51@gmail.com
+Keywords: llm,ai,agent,context,monitoring,observability,openai,anthropic,token,checkpoint,compression,self-healing
+Classifier: Development Status :: 4 - Beta
+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 :: Software Development :: Libraries
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.0.0
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.25.0; extra == "anthropic"
+Provides-Extra: all
+Requires-Dist: openai>=1.0.0; extra == "all"
+Requires-Dist: anthropic>=0.25.0; extra == "all"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+
+# StreamCtx 🧠
+
+**Your AI agent is silently corrupting its own context. StreamCtx detects it — and fixes it.**
+
+## Install
+
+pip install streamctx
+
+## 2-Line Setup
+
+import streamctx
+streamctx.start()  # patches OpenAI + Anthropic automatically
+
+---
+
+## The Problem Nobody Talks About
+
+You ship an AI agent. It works perfectly in demos.
+
+Then in production:
+- Agent gets stuck repeating the same failed action 58 times
+- Context from step 3 contradicts context from step 7
+- Agent hallucinates a tool call, writes it to memory, references it forever
+- Your $0.50 task costs $50 because nobody set a limit
+
+Every LLM observability tool tracks tokens. Nobody tracks context health.
+
+Until now.
+
+---
+
+## What StreamCtx Does
+
+### 1. Context Poison Detection
+
+result = streamctx.scan(messages)
+print(result["health_score"])    # 25/100
+print(result["warnings"])
+# ⚠️  Repeated errors: 'failed' 4x — agent stuck in loop
+# 🚨 Context severely poisoned — resume from checkpoint
+
+### 2. Context Diff — See Exactly What Changed
+
+diff = streamctx.context_diff(step3_msgs, step7_msgs, step_a=3, step_b=7)
+print(diff["summary"])
+# ⚠️  System prompt REMOVED — agent lost instructions
+# ⚠️  Contradiction: 'use gpt' added but 'use claude' removed
+# Drift Score: 50/100
+
+### 3. Auto-Checkpoint + Resume
+
+session_id = streamctx.get_session_id()
+messages = streamctx.resume(session_id)
+# Pick up exactly where agent left off
+
+### 4. 50% Token Compression
+
+result = streamctx.compress(messages, max_tokens=2000)
+# 140 tokens → 70 tokens (50% reduction)
+
+### 5. Self-Healing
+
+stats = streamctx.healing_stats()
+# failures: 1, recoveries: 1
+
+### 6. Full Session Report
+
+streamctx.report()
+streamctx.stop()
+
+---
+
+## Feature Comparison
+
+Feature              | StreamCtx | Langfuse | LangSmith | Mem0
+---------------------|-----------|----------|-----------|-----
+Token tracking       |     YES   |    YES   |    YES    |  NO
+Cost estimation      |     YES   |    YES   |    YES    |  NO
+Context Poison Det.  |     YES   |    NO    |    NO     |  NO
+Context Diff         |     YES   |    NO    |    NO     |  NO
+Auto-checkpoint      |     YES   |    NO    |    NO     |  NO
+50% Compression      |     YES   |    NO    |    NO     |  NO
+Self-healing         |     YES   |    NO    |    NO     |  NO
+Zero config          |     YES   |    NO    |    NO     |  NO
+Open source          |     YES   |    YES   |    NO     |  NO
+
+---
+
+## Quick Start
+
+import streamctx
+from openai import OpenAI
+
+streamctx.start()
+client = OpenAI()
+
+messages = [{"role": "user", "content": "Hello!"}]
+response = client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=messages,
+)
+
+result = streamctx.scan(messages)
+print(result["health_score"])
+print(result["recommendation"])
+
+streamctx.report()
+streamctx.stop()
+
+---
+
+## API Reference
+
+streamctx.start()                    # start tracking
+streamctx.stop()                     # stop tracking
+streamctx.report()                   # print full report
+streamctx.wrap(client)               # manually wrap client
+
+streamctx.scan(messages)             # context health score
+streamctx.context_diff(a, b)         # compare two steps
+
+streamctx.checkpoint()               # save checkpoint
+streamctx.resume(session_id)         # resume from checkpoint
+streamctx.get_session_id()           # current session ID
+
+streamctx.compress(messages)         # 50% token compression
+streamctx.healing_stats()            # self-healing stats
+
+---
+
+## Why StreamCtx?
+
+Most tools answer: "How many tokens did I use?"
+
+StreamCtx answers: "Why is my agent broken — and how do I fix it?"
+
+---
+
+## Roadmap
+
+DONE:
+- Token tracking + cost estimation
+- Context poison detection
+- Context diff + drift scoring
+- Auto-checkpoint + resume
+- 50% token compression
+- Self-healing engine
+
+COMING:
+- Context budget manager (v0.4.0)
+- Visual dashboard
+- Multi-agent support
+
+---
+
+## License
+
+MIT - Sneh R Joshi
+
+Built by a solo founder who got tired of AI agents silently going insane.
+
+

streamctx-0.3.0/src/streamctx.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+setup.py
+src/streamctx.egg-info/PKG-INFO
+src/streamctx.egg-info/SOURCES.txt
+src/streamctx.egg-info/dependency_links.txt
+src/streamctx.egg-info/requires.txt
+src/streamctx.egg-info/top_level.txt
+tests/test_checkpoint.py
+tests/test_compression.py
+tests/test_diff.py
+tests/test_healing.py
+tests/test_openai_integration.py
+tests/test_poison.py
+tests/test_streaming.py

streamctx-0.3.0/src/streamctx.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

streamctx-0.3.0/src/streamctx.egg-info/requires.txt

@@ -0,0 +1,11 @@
+rich>=13.0.0
+
+[all]
+openai>=1.0.0
+anthropic>=0.25.0
+
+[anthropic]
+anthropic>=0.25.0
+
+[openai]
+openai>=1.0.0

streamctx-0.3.0/src/streamctx.egg-info/top_level.txt

@@ -0,0 +1 @@
+

streamctx-0.3.0/tests/test_checkpoint.py

@@ -0,0 +1,49 @@
+
+"""Pytest version of StreamCtx checkpoint system test."""
+
+import streamctx
+from streamctx.tracker import get_tracker
+
+
+def test_checkpoint_and_resume():
+    """Checkpoint should save state, and resume should restore exact messages."""
+    streamctx.start()
+    session_id = streamctx.get_session_id()
+    assert session_id is not None
+
+    tracker = get_tracker()
+
+    tracker.state._last_messages = [
+        {"role": "system", "content": "You are a helpful assistant."},
+        {"role": "user", "content": "What is Python?"},
+    ]
+    tracker.state.step_counter = 1
+    streamctx.checkpoint()
+
+    tracker.state._last_messages = [
+        {"role": "system", "content": "You are a helpful assistant."},
+        {"role": "user", "content": "What is Python?"},
+        {"role": "assistant", "content": "Python is a programming language."},
+        {"role": "user", "content": "Tell me more."},
+    ]
+    tracker.state.step_counter = 2
+    streamctx.checkpoint()
+
+    messages = streamctx.resume(session_id)
+
+    assert len(messages) == 4
+    assert messages[0]["role"] == "system"
+    assert messages[1]["content"] == "What is Python?"
+    assert messages[2]["content"] == "Python is a programming language."
+    assert messages[3]["content"] == "Tell me more."
+
+    streamctx.stop()
+
+
+def test_resume_unknown_session_returns_empty_or_raises():
+    """Resuming a session that never checkpointed should not silently fabricate data."""
+    result = streamctx.resume(999999999)
+    assert result == [] or result is None
+
+
+

streamctx-0.3.0/tests/test_compression.py

@@ -0,0 +1,60 @@
+"""Pytest suite to verify Context Compression works."""
+
+import streamctx
+
+
+messages = [
+    {"role": "system", "content": "You are a helpful AI assistant for coding tasks."},
+    {"role": "user", "content": "What is Python? Tell me everything about it in detail."},
+    {
+        "role": "assistant",
+        "content": (
+            "Python is a high-level, interpreted programming language known for "
+            "its simplicity and readability. It was created by Guido van Rossum."
+        ),
+    },
+    {"role": "user", "content": "What are Python libraries? Give me a comprehensive list."},
+    {
+        "role": "assistant",
+        "content": (
+            "Python has thousands of libraries. NumPy, Pandas, Matplotlib, "
+            "Scikit-learn, TensorFlow, PyTorch, Django, Flask, Requests and many more."
+        ),
+    },
+    {"role": "user", "content": "Now tell me about neural networks."},
+    {
+        "role": "assistant",
+        "content": "Neural networks are computational models inspired by biological neural networks.",
+    },
+]
+
+
+def test_compress_returns_expected_keys():
+    """Compression result should include messages and a stats block."""
+    result = streamctx.compress(messages, max_tokens=100, keep_last_n=2)
+
+    assert "messages" in result
+    assert "stats" in result
+
+    stats = result["stats"]
+    assert "original_tokens" in stats
+    assert "compressed_tokens" in stats
+    assert "saved_tokens" in stats
+    assert "compression_pct" in stats
+
+
+def test_compress_reduces_token_count():
+    """Compressed token count should be less than or equal to the original."""
+    result = streamctx.compress(messages, max_tokens=100, keep_last_n=2)
+    stats = result["stats"]
+
+    assert stats["compressed_tokens"] <= stats["original_tokens"]
+    assert stats["saved_tokens"] >= 0
+
+
+def test_compress_keeps_last_n_messages():
+    """Compression should not drop more messages than keep_last_n allows from the end."""
+    result = streamctx.compress(messages, max_tokens=100, keep_last_n=2)
+
+    assert len(result["messages"]) >= 2
+    assert len(result["messages"]) <= len(messages)

streamctx-0.3.0/tests/test_diff.py

@@ -0,0 +1,65 @@
+"""Pytest suite to verify Context Diff works."""
+
+import streamctx
+
+
+# Step 3 messages (earlier)
+step3 = [
+    {"role": "system", "content": "You are a helpful assistant. Use Claude only."},
+    {"role": "user", "content": "What is Python?"},
+    {"role": "assistant", "content": "Python is a programming language."},
+]
+
+# Step 7 messages (later - things changed!)
+step7 = [
+    {"role": "system", "content": "You are a helpful assistant. Use GPT-4 only."},
+    {"role": "user", "content": "What is Python?"},
+    {"role": "assistant", "content": "Python is a programming language."},
+    {"role": "user", "content": "Now explain JavaScript too."},
+    {"role": "assistant", "content": "JavaScript runs in the browser."},
+]
+
+
+def test_diff_minor_change_has_low_drift():
+    """Comparing identical message sets should show minimal/no drift."""
+    diff = streamctx.context_diff(step3, step3, step_a=3, step_b=3)
+
+    assert "summary" in diff
+    assert "drift_score" in diff
+    assert diff["drift_score"] == 0
+
+
+def test_diff_significant_drift_detected():
+    """Comparing step3 vs step7 should detect drift, added messages, and removed messages."""
+    diff = streamctx.context_diff(step3, step7, step_a=3, step_b=7)
+
+    assert "summary" in diff
+    assert "drift_score" in diff
+    assert "added" in diff
+    assert "removed" in diff
+    assert "token_delta" in diff
+
+    # step7 has 2 more messages than step3
+    assert len(diff["added"]) >= 1
+    # drift score should be greater than the identical-message case
+    assert diff["drift_score"] > 0
+
+
+def test_diff_system_prompt_removed_triggers_warning():
+    """Removing the system prompt between steps should raise a warning."""
+    step_with_system = [
+        {"role": "system", "content": "Always respond in English only."},
+        {"role": "user", "content": "Hello"},
+    ]
+    step_without_system = [
+        {"role": "user", "content": "Hello"},
+        {"role": "user", "content": "Now respond in French please."},
+    ]
+
+    diff = streamctx.context_diff(
+        step_with_system, step_without_system, step_a=1, step_b=5
+    )
+
+    assert "summary" in diff
+    assert "warnings" in diff
+    assert len(diff["warnings"]) >= 1

streamctx-0.3.0/tests/test_healing.py

@@ -0,0 +1,74 @@
+"""Pytest suite to verify StreamCtx self-healing works."""
+
+import streamctx
+from streamctx.healer import SelfHealingEngine
+
+
+valid_messages = [
+    {"role": "system", "content": "You are a helpful assistant."},
+    {"role": "user", "content": "What is Python?"},
+    {"role": "assistant", "content": "Python is a programming language."},
+]
+
+failed_messages = [
+    {"role": "system", "content": "You are a helpful assistant."},
+    {"role": "user", "content": "What is Python?"},
+    {"role": "assistant", "content": "Python is a programming language."},
+    {"role": "user", "content": "Tell me more about Python."},
+]
+
+
+class FakeResponse:
+    content = "Python is a programming language."
+
+
+def test_healer_records_success_and_can_heal():
+    healer = SelfHealingEngine()
+    healer.record_success(valid_messages, FakeResponse())
+
+    assert healer.can_heal() is True
+
+
+def test_healer_records_failure():
+    healer = SelfHealingEngine()
+    healer.record_success(valid_messages, FakeResponse())
+    healer.record_failure()
+
+    stats = healer.get_stats()
+    assert stats["failure_count"] >= 1
+
+
+def test_healer_generates_recovery_messages():
+    healer = SelfHealingEngine()
+    healer.record_success(valid_messages, FakeResponse())
+    healer.record_failure()
+
+    recovery = healer.get_recovery_messages(failed_messages)
+
+    assert isinstance(recovery, list)
+    assert len(recovery) > 0
+    for msg in recovery:
+        assert "role" in msg
+        assert "content" in msg
+
+
+def test_healer_stats_structure():
+    healer = SelfHealingEngine()
+    healer.record_success(valid_messages, FakeResponse())
+    healer.record_failure()
+    stats = healer.get_stats()
+
+    assert "failure_count" in stats
+    assert "recovery_count" in stats
+    assert "has_valid_context" in stats
+
+
+def test_streamctx_healing_stats_integration():
+    """Full integration: streamctx.start()/stop() should expose healing_stats()."""
+    streamctx.start()
+    h_stats = streamctx.healing_stats()
+    streamctx.stop()
+
+    assert h_stats is not None
+
+

streamctx-0.3.0/tests/test_openai_integration.py

@@ -0,0 +1,138 @@
+"""Integration tests for streamctx with the OpenAI Python SDK."""
+
+from __future__ import annotations
+
+import os
+import unittest
+
+import httpx
+import streamctx
+from openai import OpenAI
+from streamctx.tracker import get_tracker
+
+
+def _mock_openai_handler(request: httpx.Request) -> httpx.Response:
+    return httpx.Response(
+        200,
+        json={
+            "id": "chatcmpl-test",
+            "object": "chat.completion",
+            "created": 0,
+            "model": "gpt-4o-mini",
+            "choices": [
+                {
+                    "index": 0,
+                    "message": {
+                        "role": "assistant",
+                        "content": "Hello from streamctx test!",
+                    },
+                    "finish_reason": "stop",
+                }
+            ],
+            "usage": {
+                "prompt_tokens": 18,
+                "completion_tokens": 6,
+                "total_tokens": 24,
+            },
+        },
+    )
+
+
+def _mock_client() -> OpenAI:
+    return OpenAI(
+        api_key="sk-test",
+        http_client=httpx.Client(transport=httpx.MockTransport(_mock_openai_handler)),
+    )
+
+
+class TestOpenAIIntegration(unittest.TestCase):
+    def tearDown(self) -> None:
+        streamctx.stop()
+        tracker = get_tracker()
+        tracker.state.auto_reported = False
+        tracker.state.call_count = 0
+        tracker.state.active = False
+        tracker.state.session_id = None
+        tracker.state._wrapped_clients.clear()
+        tracker.diff = tracker.diff.__class__()
+
+    def test_start_tracks_openai_calls(self) -> None:
+        streamctx.start()
+        client = _mock_client()
+        response = client.chat.completions.create(
+            model="gpt-4o-mini",
+            messages=[
+                {"role": "system", "content": "You are helpful."},
+                {"role": "user", "content": "Say hello"},
+            ],
+        )
+
+        self.assertEqual(response.choices[0].message.content, "Hello from streamctx test!")
+        stats = get_tracker().get_stats()
+        self.assertEqual(stats["call_count"], 1)
+        self.assertEqual(stats["total_tokens"], 24)
+        self.assertGreater(stats["total_cost"], 0)
+
+    def test_wrap_without_double_counting(self) -> None:
+        streamctx.start()
+        client = streamctx.wrap(_mock_client())
+        messages = [
+            {"role": "system", "content": "You are helpful."},
+            {"role": "user", "content": "Hi"},
+        ]
+        client.chat.completions.create(model="gpt-4o-mini", messages=messages)
+        client.chat.completions.create(model="gpt-4o-mini", messages=messages)
+
+        stats = get_tracker().get_stats()
+        self.assertEqual(stats["call_count"], 2)
+        self.assertEqual(stats["total_tokens"], 48)
+        self.assertGreater(stats["reused_tokens"], 0)
+
+    def test_wrap_only_tracks_client(self) -> None:
+        client = streamctx.wrap(_mock_client())
+        client.chat.completions.create(
+            model="gpt-4o-mini",
+            messages=[{"role": "user", "content": "Hello"}],
+        )
+
+        stats = get_tracker().get_stats()
+        self.assertEqual(stats["call_count"], 1)
+        self.assertEqual(stats["total_tokens"], 24)
+
+    def test_report_and_stop(self) -> None:
+        streamctx.start()
+        _mock_client().chat.completions.create(
+            model="gpt-4o-mini",
+            messages=[{"role": "user", "content": "Hello"}],
+        )
+        streamctx.report()
+        streamctx.stop()
+
+        self.assertFalse(get_tracker().state.active)
+
+
+@unittest.skipUnless(os.environ.get("OPENAI_API_KEY"), "OPENAI_API_KEY not set")
+class TestOpenAILive(unittest.TestCase):
+    def tearDown(self) -> None:
+        streamctx.stop()
+
+    def test_real_openai_call(self) -> None:
+        streamctx.start()
+        client = OpenAI()
+        response = client.chat.completions.create(
+            model="gpt-4o-mini",
+            messages=[{"role": "user", "content": "Reply with exactly: pong"}],
+            max_tokens=5,
+        )
+        content = response.choices[0].message.content or ""
+        self.assertIn("pong", content.lower())
+
+        stats = get_tracker().get_stats()
+        self.assertEqual(stats["call_count"], 1)
+        self.assertGreater(stats["total_tokens"], 0)
+        self.assertGreater(stats["total_cost"], 0)
+        streamctx.report()
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

streamctx-0.3.0/tests/test_poison.py

@@ -0,0 +1,59 @@
+"""Pytest suite to verify Context Poison Detector works."""
+
+import streamctx
+
+
+def test_healthy_context_has_high_health_score():
+    healthy_messages = [
+        {"role": "system", "content": "You are a helpful assistant."},
+        {"role": "user", "content": "What is Python?"},
+        {"role": "assistant", "content": "Python is a programming language."},
+        {"role": "user", "content": "Tell me more."},
+        {"role": "assistant", "content": "Python is used for web, data science, and AI."},
+    ]
+
+    result = streamctx.scan(healthy_messages)
+
+    assert "health_score" in result
+    assert "is_poisoned" in result
+    assert "recommendation" in result
+    assert result["is_poisoned"] is False
+
+
+def test_agent_stuck_in_loop_is_flagged_as_poisoned():
+    poisoned_messages = [
+        {"role": "system", "content": "You are an API assistant."},
+        {"role": "user", "content": "Call the payment API."},
+        {"role": "assistant", "content": "Error: endpoint not found. Failed to connect."},
+        {"role": "user", "content": "Try again."},
+        {"role": "assistant", "content": "Error: endpoint not found. Failed again."},
+        {"role": "user", "content": "Try once more."},
+        {"role": "assistant", "content": "Error: invalid request. Failed to process."},
+        {"role": "user", "content": "One more time."},
+        {"role": "assistant", "content": "Error: cannot connect. Failed."},
+    ]
+
+    result = streamctx.scan(poisoned_messages)
+
+    assert "health_score" in result
+    assert "is_poisoned" in result
+    assert "warnings" in result
+    assert result["is_poisoned"] is True
+    assert len(result["warnings"]) >= 1
+
+
+def test_contradictory_context_is_flagged():
+    contradiction_messages = [
+        {"role": "system", "content": "The payment feature is enabled and available."},
+        {"role": "user", "content": "Process my payment."},
+        {"role": "assistant", "content": "Payment processed successfully."},
+        {"role": "user", "content": "Check status."},
+        {"role": "assistant", "content": "Payment is unavailable. Feature is disabled."},
+    ]
+
+    result = streamctx.scan(contradiction_messages)
+
+    assert "health_score" in result
+    assert "is_poisoned" in result
+    assert "warnings" in result
+    assert "recommendation" in result

streamctx-0.3.0/tests/test_streaming.py

@@ -0,0 +1,160 @@
+"""Pytest suite to verify real-time step streaming (SessionStorage + LLMTracker)."""
+
+import pytest
+
+from streamctx.storage import SessionStorage
+from streamctx.tracker import get_tracker
+
+
+@pytest.fixture
+def storage(tmp_path):
+    """Fresh SessionStorage backed by a temp SQLite file for each test.
+
+    Uses pytest's built-in tmp_path fixture, which handles Windows-safe
+    cleanup automatically (avoids PermissionError on file handle release).
+    """
+    db_path = tmp_path / "test_sessions.db"
+    return SessionStorage(db_path=db_path)
+
+
+
+def test_start_and_end_session(storage):
+    session_id = storage.start_session()
+
+    assert isinstance(session_id, int)
+    assert session_id > 0
+
+    # Should not raise
+    storage.end_session(session_id)
+
+
+def test_record_call_streams_to_db(storage):
+    """Every LLM call should be written to the calls table immediately (real-time streaming)."""
+    session_id = storage.start_session()
+
+    storage.record_call(
+        session_id=session_id,
+        provider="openai",
+        model="gpt-4",
+        input_tokens=100,
+        output_tokens=50,
+        cost=0.01,
+        reused_tokens=10,
+        waste_category=None,
+        messages=[{"role": "user", "content": "Hello"}],
+    )
+
+    stats = storage.get_session_stats(session_id)
+
+    assert stats["call_count"] == 1
+    assert stats["input_tokens"] == 100
+    assert stats["output_tokens"] == 50
+    assert stats["total_tokens"] == 150
+    assert stats["reused_tokens"] == 10
+
+
+def test_record_call_accumulates_across_multiple_calls(storage):
+    session_id = storage.start_session()
+
+    for _ in range(3):
+        storage.record_call(
+            session_id=session_id,
+            provider="openai",
+            model="gpt-4",
+            input_tokens=100,
+            output_tokens=50,
+            cost=0.01,
+            reused_tokens=0,
+            waste_category=None,
+            messages=[{"role": "user", "content": "Hi"}],
+        )
+
+    stats = storage.get_session_stats(session_id)
+
+    assert stats["call_count"] == 3
+    assert stats["input_tokens"] == 300
+    assert stats["output_tokens"] == 150
+    assert abs(stats["total_cost"] - 0.03) < 1e-9
+
+
+def test_save_checkpoint_per_step(storage):
+    """Auto-checkpoint per step: every checkpoint write should be retrievable by step number."""
+    session_id = storage.start_session()
+    messages_step1 = [{"role": "user", "content": "step 1"}]
+    messages_step2 = [
+        {"role": "user", "content": "step 1"},
+        {"role": "assistant", "content": "response 1"},
+        {"role": "user", "content": "step 2"},
+    ]
+
+    storage.save_checkpoint(session_id, step_number=1, messages=messages_step1)
+    storage.save_checkpoint(session_id, step_number=2, messages=messages_step2)
+
+    latest = storage.get_latest_checkpoint(session_id)
+
+    assert latest is not None
+    assert latest["step_number"] == 2
+    assert latest["messages"] == messages_step2
+
+
+def test_resume_from_checkpoint_returns_latest_messages(storage):
+    session_id = storage.start_session()
+    messages = [{"role": "user", "content": "resume me"}]
+
+    storage.save_checkpoint(session_id, step_number=1, messages=messages)
+    resumed = storage.resume_from_checkpoint(session_id)
+
+    assert resumed == messages
+
+
+def test_resume_from_checkpoint_no_checkpoint_returns_empty(storage):
+    session_id = storage.start_session()
+
+    resumed = storage.resume_from_checkpoint(session_id)
+
+    assert resumed == []
+
+
+def test_get_session_stats_tracks_biggest_waste(storage):
+    session_id = storage.start_session()
+
+    storage.record_call(
+        session_id=session_id,
+        provider="openai",
+        model="gpt-4",
+        input_tokens=50,
+        output_tokens=20,
+        cost=0.005,
+        reused_tokens=5,
+        waste_category="repeated system prompt",
+        messages=[{"role": "system", "content": "You are helpful."}],
+    )
+    storage.record_call(
+        session_id=session_id,
+        provider="openai",
+        model="gpt-4",
+        input_tokens=50,
+        output_tokens=20,
+        cost=0.005,
+        reused_tokens=5,
+        waste_category="repeated system prompt",
+        messages=[{"role": "system", "content": "You are helpful."}],
+    )
+
+    stats = storage.get_session_stats(session_id)
+
+    assert stats["biggest_waste"] == "repeated system prompt"
+
+
+def test_tracker_start_stop_creates_and_ends_session():
+    """Full integration: LLMTracker.start()/stop() should create a real streamed session."""
+    tracker = get_tracker()
+
+    tracker.start()
+    session_id = tracker.get_session_id()
+
+    assert session_id is not None
+
+    tracker.stop()
+    # After stop, the active session should be cleared/ended without error
+    assert tracker.state.active is False