thanos-ctx 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
thanos/__init__.py ADDED
@@ -0,0 +1,20 @@
1
+ from .budget import Budget
2
+ from .compressor import Compressor, TruncateCompressor
3
+ from .guard import ContextGuard, GuardResult, LimitExceeded
4
+ from .pricing import ModelProfile, load_models
5
+ from .tokenizer import Tokenizer, estimate_tokens
6
+
7
+ __all__ = [
8
+ "Budget",
9
+ "Compressor",
10
+ "ContextGuard",
11
+ "GuardResult",
12
+ "LimitExceeded",
13
+ "ModelProfile",
14
+ "Tokenizer",
15
+ "TruncateCompressor",
16
+ "estimate_tokens",
17
+ "load_models",
18
+ ]
19
+
20
+ __version__ = "0.1.0"
thanos/budget.py ADDED
@@ -0,0 +1,34 @@
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import dataclass
4
+
5
+
6
+ @dataclass
7
+ class Budget:
8
+ """Cumulative ceiling for a conversation/session.
9
+
10
+ Either limit is optional; set only the one(s) you care about.
11
+ `used_tokens`/`used_cost_usd` are running totals that `ContextGuard`
12
+ updates after each `prepare()` call when you pass `record=True`.
13
+ """
14
+
15
+ max_tokens: int | None = None
16
+ max_cost_usd: float | None = None
17
+ used_tokens: int = 0
18
+ used_cost_usd: float = 0.0
19
+
20
+ def record(self, tokens: int, cost_usd: float) -> None:
21
+ self.used_tokens += tokens
22
+ self.used_cost_usd += cost_usd
23
+
24
+ def exceeded(self) -> bool:
25
+ if self.max_tokens is not None and self.used_tokens > self.max_tokens:
26
+ return True
27
+ return bool(
28
+ self.max_cost_usd is not None and self.used_cost_usd > self.max_cost_usd
29
+ )
30
+
31
+ def remaining_tokens(self, fallback: int) -> int:
32
+ if self.max_tokens is None:
33
+ return fallback
34
+ return max(0, self.max_tokens - self.used_tokens)
thanos/cli.py ADDED
@@ -0,0 +1,167 @@
1
+ from __future__ import annotations
2
+
3
+ import argparse
4
+ import json
5
+ import sys
6
+ from typing import Any
7
+
8
+ from .budget import Budget
9
+ from .guard import ContextGuard
10
+ from .pricing import load_models
11
+
12
+ Message = dict[str, Any]
13
+
14
+
15
+ def _read_messages(path: str) -> list[Message]:
16
+ if path == "-":
17
+ text = sys.stdin.read()
18
+ else:
19
+ with open(path) as f:
20
+ text = f.read()
21
+ payload = json.loads(text)
22
+ if isinstance(payload, dict) and "messages" in payload:
23
+ payload = payload["messages"]
24
+ if not isinstance(payload, list):
25
+ raise SystemExit(
26
+ 'Input must be a JSON array of messages, or an object with a "messages" array.'
27
+ )
28
+ return payload
29
+
30
+
31
+ def _stay_in_tier(value: str) -> int | None:
32
+ return None if value.lower() == "none" else int(value)
33
+
34
+
35
+ def _build_parser() -> argparse.ArgumentParser:
36
+ parser = argparse.ArgumentParser(
37
+ prog="thanos",
38
+ description="Context-window limits, pricing tiers, and compression for LLM conversations.",
39
+ )
40
+ sub = parser.add_subparsers(dest="command", required=True)
41
+
42
+ check = sub.add_parser(
43
+ "check",
44
+ help="Report tokens, pricing tier, and estimated cost for a conversation, "
45
+ "and what prepare() would do to it.",
46
+ )
47
+ check.add_argument(
48
+ "file", help="Path to a JSON file with a messages array (or '-' for stdin)."
49
+ )
50
+ check.add_argument(
51
+ "--model",
52
+ required=True,
53
+ help="Model id, e.g. claude-sonnet-4-5. See `thanos models`.",
54
+ )
55
+ check.add_argument("--pinned-prefix-len", type=int, default=1)
56
+ check.add_argument(
57
+ "--stay-in-tier",
58
+ default="0",
59
+ help="Tier index to cap at (default 0, the cheapest tier), or 'none' to only cap at the context window.",
60
+ )
61
+ check.add_argument(
62
+ "--output-tokens",
63
+ type=int,
64
+ default=0,
65
+ help="Estimated output tokens, for cost estimation.",
66
+ )
67
+ check.add_argument("--cache-write-tokens", type=int, default=0)
68
+ check.add_argument("--cache-read-tokens", type=int, default=0)
69
+ check.add_argument(
70
+ "--max-tokens",
71
+ type=int,
72
+ default=None,
73
+ help="Optional budget ceiling in tokens.",
74
+ )
75
+ check.add_argument(
76
+ "--max-cost-usd",
77
+ type=float,
78
+ default=None,
79
+ help="Optional budget ceiling in dollars.",
80
+ )
81
+ check.add_argument(
82
+ "--json", action="store_true", help="Print a machine-readable JSON report."
83
+ )
84
+
85
+ models = sub.add_parser("models", help="List models in the bundled registry.")
86
+ models.add_argument("--json", action="store_true")
87
+
88
+ return parser
89
+
90
+
91
+ def _cmd_check(args: argparse.Namespace) -> int:
92
+ messages = _read_messages(args.file)
93
+ budget = None
94
+ if args.max_tokens is not None or args.max_cost_usd is not None:
95
+ budget = Budget(max_tokens=args.max_tokens, max_cost_usd=args.max_cost_usd)
96
+
97
+ guard = ContextGuard(
98
+ model=args.model,
99
+ budget=budget,
100
+ pinned_prefix_len=args.pinned_prefix_len,
101
+ stay_in_tier=_stay_in_tier(args.stay_in_tier),
102
+ )
103
+ result = guard.prepare(
104
+ messages,
105
+ estimated_output_tokens=args.output_tokens,
106
+ cache_write_tokens=args.cache_write_tokens,
107
+ cache_read_tokens=args.cache_read_tokens,
108
+ record=False,
109
+ )
110
+
111
+ report = {
112
+ "model": args.model,
113
+ "input_messages": len(messages),
114
+ "output_messages": len(result.messages),
115
+ "tokens": result.tokens,
116
+ "tier_max_tokens": result.tier_max_tokens,
117
+ "estimated_cost_usd": round(result.estimated_cost_usd, 6),
118
+ "compressed": result.compressed,
119
+ "limit_exceeded": result.limit_exceeded,
120
+ }
121
+
122
+ if args.json:
123
+ print(json.dumps(report, indent=2))
124
+ else:
125
+ suffix = " (compressed)" if report["compressed"] else ""
126
+ print(f"model: {report['model']}")
127
+ print(
128
+ f"messages: {report['input_messages']} -> {report['output_messages']}{suffix}"
129
+ )
130
+ print(
131
+ f"tokens: {report['tokens']} (tier ceiling {report['tier_max_tokens']})"
132
+ )
133
+ print(f"estimated cost: ${report['estimated_cost_usd']:.6f}")
134
+ print(f"limit exceeded: {report['limit_exceeded']}")
135
+
136
+ return 1 if report["limit_exceeded"] else 0
137
+
138
+
139
+ def _cmd_models(args: argparse.Namespace) -> int:
140
+ models = load_models()
141
+ if args.json:
142
+ out = {
143
+ mid: {"provider": m.provider, "contextWindow": m.context_window}
144
+ for mid, m in sorted(models.items())
145
+ }
146
+ print(json.dumps(out, indent=2))
147
+ else:
148
+ for mid, m in sorted(models.items()):
149
+ print(
150
+ f"{mid:<22} provider={m.provider or '-':<10} contextWindow={m.context_window}"
151
+ )
152
+ return 0
153
+
154
+
155
+ def main(argv: list[str] | None = None) -> int:
156
+ parser = _build_parser()
157
+ args = parser.parse_args(argv)
158
+ if args.command == "check":
159
+ return _cmd_check(args)
160
+ if args.command == "models":
161
+ return _cmd_models(args)
162
+ parser.print_help()
163
+ return 1
164
+
165
+
166
+ if __name__ == "__main__":
167
+ sys.exit(main())
thanos/compressor.py ADDED
@@ -0,0 +1,50 @@
1
+ from __future__ import annotations
2
+
3
+ from typing import Any, Protocol
4
+
5
+ from .tokenizer import Tokenizer, estimate_tokens
6
+
7
+ Message = dict[str, Any]
8
+
9
+
10
+ class Compressor(Protocol):
11
+ def __call__(
12
+ self,
13
+ messages: list[Message],
14
+ target_tokens: int,
15
+ pinned_prefix_len: int,
16
+ tokenizer: Tokenizer,
17
+ ) -> list[Message]: ...
18
+
19
+
20
+ class TruncateCompressor:
21
+ """Default, zero-dependency compressor.
22
+
23
+ Keeps `messages[:pinned_prefix_len]` (the system message and anything
24
+ before the provider's cache breakpoint) untouched, then drops the
25
+ oldest remaining messages until the result fits `target_tokens`.
26
+ Never reorders or edits a message, so it never busts a cache
27
+ breakpoint that falls inside the pinned prefix.
28
+ """
29
+
30
+ def __call__(
31
+ self,
32
+ messages: list[Message],
33
+ target_tokens: int,
34
+ pinned_prefix_len: int,
35
+ tokenizer: Tokenizer = estimate_tokens,
36
+ ) -> list[Message]:
37
+ pinned = messages[:pinned_prefix_len]
38
+ rest = messages[pinned_prefix_len:]
39
+
40
+ if tokenizer(pinned) >= target_tokens:
41
+ # Even the pinned prefix alone doesn't fit; nothing safe to drop.
42
+ return pinned
43
+
44
+ kept: list[Message] = []
45
+ for message in reversed(rest):
46
+ candidate = [message] + kept
47
+ if tokenizer(pinned + candidate) > target_tokens:
48
+ break
49
+ kept = candidate
50
+ return pinned + kept