streamctx 0.3.0__tar.gz → 0.3.1__tar.gz

{streamctx-0.3.0/src/streamctx.egg-info → streamctx-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: streamctx
-Version: 0.3.0
+Version: 0.3.1
 Summary: Context health monitoring for AI agents — detect poisoning, drift, loops
 Home-page: https://github.com/streamctx/streamctx
 Author: Sneh R Joshi

{streamctx-0.3.0 → streamctx-0.3.1}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", encoding="utf-8") as f:
 
 setup(
     name="streamctx",
-    version="0.3.0",
+    version="0.3.1",
     description="Context health monitoring for AI agents — detect poisoning, drift, loops",
     long_description=long_description,
     long_description_content_type="text/markdown",

streamctx-0.3.1/src/streamctx/__init__.py

@@ -0,0 +1,156 @@
+
+"""
+streamctx — zero-config LLM call tracing with context reuse insights.
+
+Usage::
+
+    import streamctx
+    streamctx.start()
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .reporter import print_auto_summary, print_report
+from .tracker import get_tracker
+from .compressor import compress_messages, get_compression_stats
+from .poison_detector import PoisonDetector
+from .differ import ContextDiffer
+
+__version__ = "0.3.0"
+__all__ = [
+    "start", "wrap", "report", "stop",
+    "checkpoint", "resume", "get_session_id",
+    "compress", "compression_stats",
+    "healing_stats",
+    "scan",
+    "context_diff",
+    "__version__",
+]
+
+_detector = PoisonDetector()
+_differ = ContextDiffer()
+
+
+def start() -> None:
+    """Enable tracing, monkeypatch OpenAI/Anthropic SDKs, and start token tracking."""
+    get_tracker().start()
+
+
+def wrap(client: Any) -> Any:
+    """Manually wrap an OpenAI or Anthropic client for token tracking."""
+    return get_tracker().wrap(client)
+
+
+def report() -> None:
+    """Print a terminal summary with token counts, cost, and context reuse."""
+    print_report(get_tracker())
+
+
+def stop() -> None:
+    """Stop tracking, restore SDK patches, and close the session."""
+    get_tracker().stop()
+
+
+def checkpoint() -> None:
+    """Manually save a checkpoint of the current conversation state."""
+    get_tracker().checkpoint()
+
+
+def resume(session_id: int) -> list:
+    """Resume from the latest checkpoint of a given session."""
+    return get_tracker().resume(session_id)
+
+
+def get_session_id() -> int | None:
+    """Get the current active session ID."""
+    return get_tracker().get_session_id()
+
+
+def compress(
+    messages: list,
+    max_tokens: int = 2000,
+    keep_last_n: int = 4,
+) -> dict:
+    """
+    Compress messages to reduce token usage by 40-70%.
+
+    Usage::
+
+        result = streamctx.compress(messages, max_tokens=2000)
+        compressed = result["messages"]
+        print(result["stats"])
+    """
+    compressed, original, after = compress_messages(
+        messages,
+        max_tokens=max_tokens,
+        keep_last_n=keep_last_n,
+    )
+    stats = get_compression_stats(original, after)
+    return {
+        "messages": compressed,
+        "stats": stats,
+    }
+
+
+def compression_stats(original_tokens: int, compressed_tokens: int) -> dict:
+    """Get compression statistics."""
+    return get_compression_stats(original_tokens, compressed_tokens)
+
+
+def healing_stats() -> dict:
+    """Get self-healing statistics."""
+    return get_tracker().healing_stats()
+
+
+def scan(messages: list) -> dict:
+    """
+    Scan messages for context poisoning.
+
+    Usage::
+
+        result = streamctx.scan(messages)
+        print(result["health_score"])
+        print(result["warnings"])
+    """
+    return _detector.scan(messages)
+
+
+def context_diff(
+    messages_a: list,
+    messages_b: list,
+    step_a: int = 0,
+    step_b: int = 0,
+) -> dict:
+    """
+    Compare two sets of messages to see exactly what changed.
+
+    Shows added, removed, unchanged messages and drift score.
+
+    Usage::
+
+        diff = streamctx.context_diff(
+            messages_a=step3_messages,
+            messages_b=step7_messages,
+            step_a=3,
+            step_b=7,
+        )
+        print(diff["summary"])
+        print(diff["warnings"])
+        print(diff["drift_score"])
+
+    Returns:
+        {
+            "added": list,
+            "removed": list,
+            "unchanged": list,
+            "drift_score": int 0-100,
+            "summary": str,
+            "warnings": list,
+            "token_delta": int,
+        }
+    """
+    return _differ.diff(messages_a, messages_b, step_a, step_b)
+
+

streamctx-0.3.1/src/streamctx/compressor.py

@@ -0,0 +1,100 @@
+"""Context compression engine for StreamCtx."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def _estimate_tokens(text: str) -> int:
+    if not text:
+        return 0
+    return max(1, len(text) // 4)
+
+
+def _total_tokens(messages: list[dict[str, Any]]) -> int:
+    return sum(_estimate_tokens(m.get("content", "")) for m in messages)
+
+
+def compress_messages(
+    messages: list[dict[str, Any]],
+    max_tokens: int = 2000,
+    keep_system: bool = True,
+    keep_last_n: int = 4,
+) -> tuple[list[dict[str, Any]], int, int]:
+    if not messages:
+        return messages, 0, 0
+
+    original_tokens = _total_tokens(messages)
+
+    if original_tokens <= max_tokens:
+        return messages, original_tokens, original_tokens
+
+    # Separate system, middle, recent
+    system_msgs = [m for m in messages if m.get("role") == "system"]
+    non_system = [m for m in messages if m.get("role") != "system"]
+
+    if len(non_system) <= keep_last_n:
+        recent = non_system
+        middle = []
+    else:
+        recent = non_system[-keep_last_n:]
+        middle = non_system[:-keep_last_n]
+
+    # Compress middle into one short summary
+    compressed_middle = _compress_middle(middle)
+
+    result = system_msgs + compressed_middle + recent
+    compressed_tokens = _total_tokens(result)
+
+    return result, original_tokens, compressed_tokens
+
+
+def _compress_middle(
+    messages: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    if not messages:
+        return []
+
+    # Extract key points only — very aggressive compression
+    topics = []
+    for msg in messages:
+        role = msg.get("role", "user")
+        content = msg.get("content", "")
+        if not content:
+            continue
+        # Take only first 15 chars per message
+        short = content[:15].replace("\n", " ").strip()
+        topics.append(f"{role}: {short}")
+
+    if not topics:
+        return []
+
+    # Single compressed summary message
+    summary = "Earlier context: " + " | ".join(topics)
+
+    return [{"role": "system", "content": summary}]
+
+
+def get_compression_stats(
+    original_tokens: int,
+    compressed_tokens: int,
+) -> dict[str, Any]:
+    if original_tokens == 0:
+        return {
+            "original_tokens": 0,
+            "compressed_tokens": 0,
+            "saved_tokens": 0,
+            "compression_pct": 0,
+        }
+
+    saved = original_tokens - compressed_tokens
+    pct = int(round(100 * saved / original_tokens))
+
+    return {
+        "original_tokens": original_tokens,
+        "compressed_tokens": compressed_tokens,
+        "saved_tokens": saved,
+        "compression_pct": pct,
+    }
+
+

streamctx-0.3.1/src/streamctx/differ.py

@@ -0,0 +1,199 @@
+"""Context Diff Engine for StreamCtx.
+
+Compare context between any two steps to see exactly:
+- What was added
+- What was removed 
+- What changed
+- Context drift score 0-100
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+def _estimate_tokens(text: str) -> int:
+    if not text:
+        return 0
+    return max(1, len(text) // 4)
+
+
+class ContextDiffer:
+    """
+    Compare context between two steps in a session.
+
+    Shows exactly when and how context changed —
+    helping developers pinpoint where agent went wrong.
+    """
+
+    def diff(
+        self,
+        messages_a: list[dict[str, Any]],
+        messages_b: list[dict[str, Any]],
+        step_a: int = 0,
+        step_b: int = 0,
+    ) -> dict[str, Any]:
+        """
+        Compare two sets of messages and return diff.
+
+        Returns:
+            {
+                "added": list of new messages in B,
+                "removed": list of messages only in A,
+                "unchanged": list of common messages,
+                "drift_score": int 0-100,
+                "summary": str,
+                "warnings": list[str],
+                "token_delta": int,
+            }
+        """
+        # Convert to comparable format
+        set_a = {self._msg_key(m): m for m in messages_a}
+        set_b = {self._msg_key(m): m for m in messages_b}
+
+        keys_a = set(set_a.keys())
+        keys_b = set(set_b.keys())
+
+        added = [set_b[k] for k in keys_b - keys_a]
+        removed = [set_a[k] for k in keys_a - keys_b]
+        unchanged = [set_a[k] for k in keys_a & keys_b]
+
+        # Token delta
+        tokens_a = sum(_estimate_tokens(m.get("content", "")) for m in messages_a)
+        tokens_b = sum(_estimate_tokens(m.get("content", "")) for m in messages_b)
+        token_delta = tokens_b - tokens_a
+
+        # Drift score
+        drift_score = self._calc_drift(
+            added, removed, unchanged, messages_a, messages_b
+        )
+
+        # Warnings
+        warnings = self._get_warnings(added, removed, drift_score)
+
+        # Summary
+        summary = self._build_summary(
+            added, removed, unchanged, step_a, step_b, drift_score
+        )
+
+        return {
+            "step_a": step_a,
+            "step_b": step_b,
+            "added": added,
+            "removed": removed,
+            "unchanged": unchanged,
+            "drift_score": drift_score,
+            "summary": summary,
+            "warnings": warnings,
+            "token_delta": token_delta,
+            "tokens_a": tokens_a,
+            "tokens_b": tokens_b,
+        }
+
+    def _msg_key(self, msg: dict[str, Any]) -> str:
+        """Unique key for a message."""
+        role = msg.get("role", "")
+        content = msg.get("content", "")
+        return f"{role}:{content}"
+
+    def _calc_drift(
+        self,
+        added: list,
+        removed: list,
+        unchanged: list,
+        messages_a: list,
+        messages_b: list,
+    ) -> int:
+        """
+        Calculate drift score 0-100.
+        0 = identical, 100 = completely different.
+        """
+        total = len(messages_a) + len(messages_b)
+        if total == 0:
+            return 0
+
+        changed = len(added) + len(removed)
+        drift = int(round(100 * changed / total))
+        return min(100, drift)
+
+    def _get_warnings(
+        self,
+        added: list,
+        removed: list,
+        drift_score: int,
+    ) -> list[str]:
+        warnings = []
+
+        # System prompt removed
+        removed_roles = [m.get("role") for m in removed]
+        added_roles = [m.get("role") for m in added]
+
+        if "system" in removed_roles:
+            warnings.append(
+                "⚠️  System prompt was REMOVED — agent may have lost instructions"
+            )
+
+        if "system" in added_roles:
+            warnings.append(
+                "⚠️  New system prompt ADDED — context instructions changed"
+            )
+
+        if drift_score >= 70:
+            warnings.append(
+                f"🚨 High drift ({drift_score}/100) — context changed significantly"
+            )
+        elif drift_score >= 40:
+            warnings.append(
+                f"⚡ Medium drift ({drift_score}/100) — monitor context closely"
+            )
+
+        # Check for contradictions
+        added_content = " ".join(m.get("content", "").lower() for m in added)
+        removed_content = " ".join(m.get("content", "").lower() for m in removed)
+
+        contradiction_pairs = [
+            ("use gpt", "use claude"),
+            ("enabled", "disabled"),
+            ("yes", "no"),
+            ("true", "false"),
+        ]
+        for w1, w2 in contradiction_pairs:
+            if w1 in added_content and w2 in removed_content:
+                warnings.append(
+                    f"⚠️  Contradiction: '{w1}' added but '{w2}' removed"
+                )
+            elif w2 in added_content and w1 in removed_content:
+                warnings.append(
+                    f"⚠️  Contradiction: '{w2}' added but '{w1}' removed"
+                )
+
+        return warnings
+
+    def _build_summary(
+        self,
+        added: list,
+        removed: list,
+        unchanged: list,
+        step_a: int,
+        step_b: int,
+        drift_score: int,
+    ) -> str:
+        if drift_score == 0:
+            return f"✅ Step {step_a} → {step_b}: No context change"
+        elif drift_score < 40:
+            return (
+                f"✅ Step {step_a} → {step_b}: Minor changes "
+                f"(+{len(added)} -{len(removed)} messages, drift: {drift_score}/100)"
+            )
+        elif drift_score < 70:
+            return (
+                f"⚡ Step {step_a} → {step_b}: Moderate drift "
+                f"(+{len(added)} -{len(removed)} messages, drift: {drift_score}/100)"
+            )
+        else:
+            return (
+                f"🚨 Step {step_a} → {step_b}: HIGH DRIFT "
+                f"(+{len(added)} -{len(removed)} messages, drift: {drift_score}/100)"
+            )
+
+

streamctx-0.3.1/src/streamctx/healer.py

@@ -0,0 +1,124 @@
+"""Self-healing engine for StreamCtx."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class SelfHealingEngine:
+    """
+    Detects failed LLM calls and recovers using last valid checkpoint.
+
+    When a call fails:
+    1. Catches the exception
+    2. Loads last valid checkpoint messages
+    3. Injects recovery context
+    4. Retries the call automatically
+    """
+
+    def __init__(self) -> None:
+        self._last_valid_messages: list[dict[str, Any]] = []
+        self._last_valid_response: Any = None
+        self._failure_count: int = 0
+        self._recovery_count: int = 0
+
+    def record_success(
+        self,
+        messages: list[dict[str, Any]],
+        response: Any,
+    ) -> None:
+        """Save last successful call for recovery."""
+        self._last_valid_messages = list(messages)
+        self._last_valid_response = response
+
+    def record_failure(self) -> None:
+        """Track failure count."""
+        self._failure_count += 1
+
+    def can_heal(self) -> bool:
+        """Check if we have valid context to recover from."""
+        return len(self._last_valid_messages) > 0
+
+    def get_recovery_messages(
+        self,
+        failed_messages: list[dict[str, Any]],
+    ) -> list[dict[str, Any]]:
+        """
+        Build recovery message list by injecting last valid context.
+
+        Strategy:
+        - Take last valid messages as base
+        - Add recovery notice
+        - Append the last user message from failed call
+        """
+        if not self._last_valid_messages:
+            return failed_messages
+
+        # Get last user message from failed call
+        last_user_msg = None
+        for msg in reversed(failed_messages):
+            if msg.get("role") == "user":
+                last_user_msg = msg
+                break
+
+        # Build recovery context
+        recovery = list(self._last_valid_messages)
+
+        # Add recovery notice as system message
+        recovery_notice = {
+            "role": "system",
+            "content": (
+                "Note: Previous response was interrupted. "
+                "Continuing from last valid context."
+            ),
+        }
+        recovery.append(recovery_notice)
+
+        # Re-add the last user message
+        if last_user_msg:
+            recovery.append(last_user_msg)
+
+        self._recovery_count += 1
+        return recovery
+
+    def attempt_heal(
+        self,
+        fn: Any,
+        failed_messages: list[dict[str, Any]],
+        kwargs: dict[str, Any],
+        max_retries: int = 2,
+    ) -> Any:
+        """
+        Attempt to recover from a failed LLM call.
+
+        Retries with last valid context injected.
+        """
+        if not self.can_heal():
+            raise RuntimeError("Self-healing failed: no valid checkpoint available.")
+
+        recovery_messages = self.get_recovery_messages(failed_messages)
+
+        for attempt in range(max_retries):
+            try:
+                # Update messages with recovery context
+                kwargs_copy = dict(kwargs)
+                kwargs_copy["messages"] = recovery_messages
+                response = fn(**kwargs_copy)
+                self.record_success(recovery_messages, response)
+                return response
+            except Exception:
+                if attempt == max_retries - 1:
+                    raise
+                continue
+
+        raise RuntimeError("Self-healing exhausted all retries.")
+
+    def get_stats(self) -> dict[str, Any]:
+        """Return healing statistics."""
+        return {
+            "failure_count": self._failure_count,
+            "recovery_count": self._recovery_count,
+            "has_valid_context": self.can_heal(),
+        }
+
+