thanos-ctx 0.1.0__tar.gz

thanos_ctx-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: thanos-ctx
+Version: 0.1.0
+Summary: Lightweight context-window limits, pricing-tier awareness, and compression for LLM conversations
+Author: Karthikeya Surabhi
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/freakomonk/thanos
+Keywords: llm,context,tokens,pricing,prompt-caching,anthropic,openai
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+
+# thanos (Python)
+
+Keep an LLM conversation inside its context window and pricing tier, track
+spend, and compress history automatically when a limit is hit.
+
+```bash
+pip install thanos-ctx
+```
+
+(Published as `thanos-ctx` — the bare `thanos` name on PyPI belongs to an
+unrelated project. The import stays `from thanos import ...`.)
+
+```python
+from thanos import ContextGuard
+
+guard = ContextGuard(model="claude-sonnet-4-5")
+
+messages = [
+    {"role": "system", "content": "You are a helpful assistant."},
+    {"role": "user", "content": "..."},
+    # ... growing conversation history
+]
+
+result = guard.prepare(messages)
+
+# Send result.messages to the API instead of the original list.
+response = client.messages.create(model="claude-sonnet-4-5", messages=result.messages, ...)
+
+print(result.tokens, result.estimated_cost_usd, result.compressed)
+```
+
+## Budgets
+
+```python
+from thanos import Budget, ContextGuard
+
+budget = Budget(max_cost_usd=5.00)
+guard = ContextGuard(model="claude-sonnet-4-5", budget=budget)
+
+for turn in conversation:
+    result = guard.prepare(turn.messages)  # auto-compresses once max_cost_usd is projected to be exceeded
+```
+
+## Custom compression
+
+```python
+from thanos import ContextGuard
+
+def summarize_and_truncate(messages, target_tokens, pinned_prefix_len, tokenizer):
+    # Your own strategy — e.g. call an LLM to summarize the dropped turns
+    # into one system note, then fall back to truncation.
+    ...
+
+guard = ContextGuard(model="claude-sonnet-4-5", compressor=summarize_and_truncate)
+```
+
+## Reacting to limits
+
+```python
+def alert(info: dict) -> None:
+    print(f"compressed={info['compressed']} tokens={info['tokens']} cost=${info['estimated_cost_usd']:.4f}")
+
+guard = ContextGuard(model="claude-sonnet-4-5", on_limit=alert)
+```
+
+Pass `raise_on_limit=True` to raise `thanos.LimitExceeded` instead of just
+notifying `on_limit`.
+
+## Adding or overriding a model
+
+```python
+guard = ContextGuard(
+    model="my-self-hosted-model",
+    models={
+        "my-self-hosted-model": {
+            "contextWindow": 128_000,
+            "tiers": [{"maxTokens": 128_000, "inputPerMTok": 0.0, "outputPerMTok": 0.0}],
+        }
+    },
+)
+```
+
+See the [top-level README](../README.md) for the full design rationale.

thanos_ctx-0.1.0/README.md

@@ -0,0 +1,83 @@
+# thanos (Python)
+
+Keep an LLM conversation inside its context window and pricing tier, track
+spend, and compress history automatically when a limit is hit.
+
+```bash
+pip install thanos-ctx
+```
+
+(Published as `thanos-ctx` — the bare `thanos` name on PyPI belongs to an
+unrelated project. The import stays `from thanos import ...`.)
+
+```python
+from thanos import ContextGuard
+
+guard = ContextGuard(model="claude-sonnet-4-5")
+
+messages = [
+    {"role": "system", "content": "You are a helpful assistant."},
+    {"role": "user", "content": "..."},
+    # ... growing conversation history
+]
+
+result = guard.prepare(messages)
+
+# Send result.messages to the API instead of the original list.
+response = client.messages.create(model="claude-sonnet-4-5", messages=result.messages, ...)
+
+print(result.tokens, result.estimated_cost_usd, result.compressed)
+```
+
+## Budgets
+
+```python
+from thanos import Budget, ContextGuard
+
+budget = Budget(max_cost_usd=5.00)
+guard = ContextGuard(model="claude-sonnet-4-5", budget=budget)
+
+for turn in conversation:
+    result = guard.prepare(turn.messages)  # auto-compresses once max_cost_usd is projected to be exceeded
+```
+
+## Custom compression
+
+```python
+from thanos import ContextGuard
+
+def summarize_and_truncate(messages, target_tokens, pinned_prefix_len, tokenizer):
+    # Your own strategy — e.g. call an LLM to summarize the dropped turns
+    # into one system note, then fall back to truncation.
+    ...
+
+guard = ContextGuard(model="claude-sonnet-4-5", compressor=summarize_and_truncate)
+```
+
+## Reacting to limits
+
+```python
+def alert(info: dict) -> None:
+    print(f"compressed={info['compressed']} tokens={info['tokens']} cost=${info['estimated_cost_usd']:.4f}")
+
+guard = ContextGuard(model="claude-sonnet-4-5", on_limit=alert)
+```
+
+Pass `raise_on_limit=True` to raise `thanos.LimitExceeded` instead of just
+notifying `on_limit`.
+
+## Adding or overriding a model
+
+```python
+guard = ContextGuard(
+    model="my-self-hosted-model",
+    models={
+        "my-self-hosted-model": {
+            "contextWindow": 128_000,
+            "tiers": [{"maxTokens": 128_000, "inputPerMTok": 0.0, "outputPerMTok": 0.0}],
+        }
+    },
+)
+```
+
+See the [top-level README](../README.md) for the full design rationale.

thanos_ctx-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "thanos-ctx"
+version = "0.1.0"
+description = "Lightweight context-window limits, pricing-tier awareness, and compression for LLM conversations"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Karthikeya Surabhi" }]
+keywords = ["llm", "context", "tokens", "pricing", "prompt-caching", "anthropic", "openai"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest", "ruff"]
+
+[project.urls]
+Homepage = "https://github.com/freakomonk/thanos"
+
+[project.scripts]
+thanos = "thanos.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["thanos*"]
+
+[tool.setuptools.package-data]
+thanos = ["data/models.json"]
+
+[tool.ruff]
+target-version = "py39"

thanos_ctx-0.1.0/setup.cfg

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

thanos_ctx-0.1.0/tests/test_cli.py

@@ -0,0 +1,71 @@
+import json
+
+from thanos.cli import main
+
+
+def _write_messages(tmp_path, messages):
+    path = tmp_path / "conversation.json"
+    path.write_text(json.dumps(messages))
+    return str(path)
+
+
+def test_check_prints_report_and_returns_zero_when_under_limit(tmp_path, capsys):
+    path = _write_messages(tmp_path, [{"role": "user", "content": "hello"}])
+
+    code = main(["check", path, "--model", "claude-haiku-4-5"])
+
+    out = capsys.readouterr().out
+    assert code == 0
+    assert "model:" in out
+    assert "claude-haiku-4-5" in out
+    assert "limit exceeded:  False" in out
+
+
+def test_check_json_output_is_valid_json(tmp_path, capsys):
+    path = _write_messages(tmp_path, [{"role": "user", "content": "hello"}])
+
+    code = main(["check", path, "--model", "claude-haiku-4-5", "--json"])
+
+    out = capsys.readouterr().out
+    report = json.loads(out)
+    assert code == 0
+    assert report["model"] == "claude-haiku-4-5"
+    assert report["limit_exceeded"] is False
+
+
+def test_check_returns_nonzero_when_budget_exceeded(tmp_path, capsys):
+    path = _write_messages(tmp_path, [{"role": "user", "content": "x" * 4000}])
+
+    code = main(
+        ["check", path, "--model", "claude-haiku-4-5", "--max-tokens", "10", "--json"]
+    )
+
+    report = json.loads(capsys.readouterr().out)
+    assert code == 1
+    assert report["limit_exceeded"] is True
+
+
+def test_check_accepts_object_with_messages_key(tmp_path, capsys):
+    path = tmp_path / "conversation.json"
+    path.write_text(json.dumps({"messages": [{"role": "user", "content": "hi"}]}))
+
+    code = main(["check", str(path), "--model", "claude-haiku-4-5"])
+
+    assert code == 0
+
+
+def test_models_lists_bundled_registry(capsys):
+    code = main(["models"])
+
+    out = capsys.readouterr().out
+    assert code == 0
+    assert "claude-sonnet-4-5" in out
+    assert "gpt-5" in out
+
+
+def test_models_json_output(capsys):
+    code = main(["models", "--json"])
+
+    registry = json.loads(capsys.readouterr().out)
+    assert code == 0
+    assert registry["claude-sonnet-4-5"]["provider"] == "anthropic"

thanos_ctx-0.1.0/tests/test_compressor.py

@@ -0,0 +1,56 @@
+from thanos import TruncateCompressor, estimate_tokens
+
+
+def _msg(role: str, text: str) -> dict:
+    return {"role": role, "content": text}
+
+
+def test_truncate_keeps_pinned_prefix_untouched():
+    messages = [
+        _msg("system", "You are a helpful assistant. " * 5),
+        _msg("user", "turn 1 " * 50),
+        _msg("assistant", "turn 1 reply " * 50),
+        _msg("user", "turn 2 " * 50),
+        _msg("assistant", "turn 2 reply " * 50),
+        _msg("user", "most recent turn " * 5),
+    ]
+    compressor = TruncateCompressor()
+    target = estimate_tokens([messages[0], messages[-1]]) + 5
+
+    result = compressor(
+        messages, target, pinned_prefix_len=1, tokenizer=estimate_tokens
+    )
+
+    assert result[0] == messages[0]
+    assert estimate_tokens(result) <= target or len(result) == 1
+
+
+def test_truncate_drops_oldest_turns_first():
+    messages = [
+        _msg("system", "sys"),
+        _msg("user", "oldest"),
+        _msg("assistant", "oldest reply"),
+        _msg("user", "newest"),
+    ]
+    compressor = TruncateCompressor()
+    # Target fits system + only the very last message.
+    target = estimate_tokens([messages[0], messages[-1]])
+
+    result = compressor(
+        messages, target, pinned_prefix_len=1, tokenizer=estimate_tokens
+    )
+
+    assert result[0]["role"] == "system"
+    assert result[-1] == messages[-1]
+    assert messages[1] not in result
+
+
+def test_truncate_never_touches_pinned_prefix_even_if_oversized():
+    messages = [_msg("system", "x" * 10_000), _msg("user", "hi")]
+    compressor = TruncateCompressor()
+
+    result = compressor(
+        messages, target_tokens=1, pinned_prefix_len=1, tokenizer=estimate_tokens
+    )
+
+    assert result == [messages[0]]

thanos_ctx-0.1.0/tests/test_guard.py

@@ -0,0 +1,93 @@
+from thanos import Budget, ContextGuard
+
+
+def _msg(role: str, text: str) -> dict:
+    return {"role": role, "content": text}
+
+
+def test_prepare_returns_stats_without_compression_when_under_limit():
+    guard = ContextGuard(model="claude-haiku-4-5")
+    messages = [_msg("user", "hello there")]
+
+    result = guard.prepare(messages)
+
+    assert result.compressed is False
+    assert result.limit_exceeded is False
+    assert result.tokens > 0
+    assert result.messages == messages
+
+
+def test_prepare_compresses_when_over_tier_ceiling():
+    guard = ContextGuard(model="claude-haiku-4-5", stay_in_tier=0)
+    big_history = [_msg("system", "sys")] + [
+        _msg("user", "x" * 4000) for _ in range(300)
+    ]
+
+    result = guard.prepare(big_history)
+
+    assert result.compressed is True
+    assert len(result.messages) < len(big_history)
+    assert result.messages[0]["role"] == "system"
+
+
+def test_on_limit_callback_fires_and_does_not_raise_by_default():
+    calls = []
+    guard = ContextGuard(
+        model="claude-haiku-4-5",
+        stay_in_tier=0,
+        on_limit=lambda info: calls.append(info),
+    )
+    big_history = [_msg("system", "sys")] + [
+        _msg("user", "x" * 4000) for _ in range(300)
+    ]
+
+    guard.prepare(big_history)
+
+    assert len(calls) == 1
+    assert calls[0]["compressed"] is True
+
+
+def test_budget_ceiling_triggers_limit_and_raise_on_limit_raises():
+    from thanos import LimitExceeded
+
+    budget = Budget(max_tokens=50)
+    guard = ContextGuard(model="claude-haiku-4-5", budget=budget, raise_on_limit=True)
+    messages = [_msg("user", "x" * 4000)]  # far more than 50 tokens
+
+    try:
+        guard.prepare(messages)
+        assert False, "expected LimitExceeded"
+    except LimitExceeded:
+        pass
+
+
+def test_custom_tokenizer_and_compressor_are_used():
+    from thanos.pricing import ModelProfile, PriceTier
+
+    calls = {"tokenizer": 0, "compressor": 0}
+
+    def fixed_tokenizer(messages):
+        calls["tokenizer"] += 1
+        return 10
+
+    def noop_compressor(messages, target_tokens, pinned_prefix_len, tokenizer):
+        calls["compressor"] += 1
+        return messages
+
+    tiny_model = ModelProfile(
+        model_id="tiny",
+        context_window=5,
+        tiers=[PriceTier(max_tokens=5, input_per_m_tok=1.0, output_per_m_tok=1.0)],
+    )
+    guard = ContextGuard(
+        model=tiny_model,
+        tokenizer=fixed_tokenizer,
+        compressor=noop_compressor,
+        stay_in_tier=None,
+    )
+
+    result = guard.prepare([_msg("user", "hi")])
+
+    assert calls["tokenizer"] >= 1
+    assert calls["compressor"] == 1
+    assert result.tokens == 10

thanos_ctx-0.1.0/tests/test_pricing.py

@@ -0,0 +1,41 @@
+from thanos import load_models
+
+
+def test_loads_bundled_models():
+    models = load_models()
+    assert "claude-sonnet-4-5" in models
+    sonnet = models["claude-sonnet-4-5"]
+    assert sonnet.context_window == 1_000_000
+    assert len(sonnet.tiers) == 2
+
+
+def test_tier_for_selects_cheaper_tier_below_threshold():
+    models = load_models()
+    sonnet = models["claude-sonnet-4-5"]
+    cheap_tier = sonnet.tier_for(100_000)
+    expensive_tier = sonnet.tier_for(500_000)
+    assert cheap_tier.input_per_m_tok < expensive_tier.input_per_m_tok
+
+
+def test_estimate_cost_usd_bills_cache_tokens_at_cache_rate():
+    models = load_models()
+    haiku = models["claude-haiku-4-5"]
+    # 1,000 total tokens, all served from cache read.
+    cost = haiku.estimate_cost_usd(total_input_tokens=1000, cache_read_tokens=1000)
+    expected = (1000 / 1_000_000) * haiku.cache.read_per_m_tok
+    assert cost == expected
+
+
+def test_extra_models_override_and_extend_registry():
+    models = load_models(
+        extra={
+            "my-custom-model": {
+                "contextWindow": 32000,
+                "tiers": [
+                    {"maxTokens": 32000, "inputPerMTok": 0.5, "outputPerMTok": 1.5}
+                ],
+            }
+        }
+    )
+    assert "my-custom-model" in models
+    assert models["my-custom-model"].context_window == 32000

thanos_ctx-0.1.0/thanos/__init__.py

@@ -0,0 +1,20 @@
+from .budget import Budget
+from .compressor import Compressor, TruncateCompressor
+from .guard import ContextGuard, GuardResult, LimitExceeded
+from .pricing import ModelProfile, load_models
+from .tokenizer import Tokenizer, estimate_tokens
+
+__all__ = [
+    "Budget",
+    "Compressor",
+    "ContextGuard",
+    "GuardResult",
+    "LimitExceeded",
+    "ModelProfile",
+    "Tokenizer",
+    "TruncateCompressor",
+    "estimate_tokens",
+    "load_models",
+]
+
+__version__ = "0.1.0"

thanos_ctx-0.1.0/thanos/budget.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Budget:
+    """Cumulative ceiling for a conversation/session.
+
+    Either limit is optional; set only the one(s) you care about.
+    `used_tokens`/`used_cost_usd` are running totals that `ContextGuard`
+    updates after each `prepare()` call when you pass `record=True`.
+    """
+
+    max_tokens: int | None = None
+    max_cost_usd: float | None = None
+    used_tokens: int = 0
+    used_cost_usd: float = 0.0
+
+    def record(self, tokens: int, cost_usd: float) -> None:
+        self.used_tokens += tokens
+        self.used_cost_usd += cost_usd
+
+    def exceeded(self) -> bool:
+        if self.max_tokens is not None and self.used_tokens > self.max_tokens:
+            return True
+        return bool(
+            self.max_cost_usd is not None and self.used_cost_usd > self.max_cost_usd
+        )
+
+    def remaining_tokens(self, fallback: int) -> int:
+        if self.max_tokens is None:
+            return fallback
+        return max(0, self.max_tokens - self.used_tokens)