tokencast 0.1.0__py3-none-any.whl

tokencast/__init__.py

@@ -0,0 +1,3 @@
+"""tokencast — Pre-execution cost estimation for LLM agent workflows."""
+
+__version__ = "0.1.0"

tokencast-0.1.0.dist-info/METADATA

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: tokencast
+Version: 0.1.0
+Summary: Pre-execution cost estimation for LLM agent workflows with calibration learning
+Project-URL: Homepage, https://github.com/krulewis/tokencast
+Project-URL: Documentation, https://github.com/krulewis/tokencast/wiki
+Project-URL: Repository, https://github.com/krulewis/tokencast
+Project-URL: Issues, https://github.com/krulewis/tokencast/issues
+Author-email: Kelly Lewis <krulewis@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,calibration,cost-estimation,llm,mcp,token-cost
+Classifier: Development Status :: 2 - Pre-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 :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/tokencast-logo.svg" alt="tokencast logo" width="150">
+</p>
+
+# tokencast
+
+A Claude Code skill that estimates Anthropic API cost for planned agent tasks, then **learns from actual usage** to improve estimates over time.
+
+Install once per project. It auto-estimates after plans are created and auto-learns at session end. Zero ongoing friction.
+
+## Setup (one time per project)
+
+```bash
+# Clone the repo (anywhere — it doesn't need to live inside your project)
+git clone https://github.com/krulewis/tokencast.git
+
+# Install into your project (quote paths with spaces)
+bash tokencast/scripts/install-hooks.sh "/path/to/your-project"
+```
+
+> **Paths with spaces:** Always wrap the project path in quotes. Without them the install script will fail on paths like `/Volumes/Macintosh HD2/...`.
+
+This does three things:
+1. Symlinks the skill into `<project>/.claude/skills/tokencast/`
+2. Adds a `Stop` hook for auto-learning at session end
+3. Adds a `PostToolUse` hook to nudge estimation after planning agents
+
+Every Claude Code session in that project now has tokencast active.
+
+## What Happens Automatically
+
+### After a plan is created
+tokencast detects the plan in conversation context, infers size, files, complexity, project type, and language, then outputs a cost table:
+
+```
+## tokencast estimate
+
+Change: size=M, files=5, complexity=medium
+Calibration: 1.12x from 8 prior runs
+
+| Step                  | Model  | Optimistic | Expected | Pessimistic |
+|-----------------------|--------|------------|----------|-------------|
+| Research Agent        | Sonnet | $0.60      | $1.17    | $4.47       |
+| Architect Agent       | Opus   | $0.67      | $1.18    | $3.97       |
+| ...                   | ...    | ...        | ...      | ...         |
+| TOTAL                 |        | $3.37      | $6.26    | $22.64      |
+```
+
+### At session end
+The learning hook silently:
+1. Reads the session's JSONL log
+2. Computes actual token cost (including cache write tokens)
+3. Compares to the estimate
+4. Updates calibration factors
+
+### Next session
+Future estimates use learned correction factors. More sessions = better accuracy.
+
+## Manual Invocation
+
+You can also invoke explicitly with overrides:
+
+```
+/tokencast size=L files=12 complexity=high
+/tokencast steps=implement,test,qa
+/tokencast review_cycles=3
+/tokencast review_cycles=0
+```
+
+Use `review_cycles=N` to set the number of expected PR review cycles. Use `review_cycles=0` to suppress the PR Review Loop row.
+
+## How It Works
+
+1. Infers size, file count, complexity from the plan in conversation
+2. Reads reference files for pricing and token heuristics
+3. Loads learned calibration factors (if any exist)
+4. Computes per-step token estimates using activity decomposition
+5. Applies complexity multiplier, context accumulation `(K+1)/2`, and cache rates
+6. Splits into Optimistic / Expected / Pessimistic bands
+7. If PR Review Loop is in scope, computes loop cost using geometric decay across N review cycles (Optimistic=1, Expected=N, Pessimistic=N×2)
+8. Applies calibration correction to Expected band (individual steps re-anchor; PR Review Loop scales each band independently)
+9. Records the estimate for later comparison with actuals
+
+## Overrides
+
+| Override | Effect |
+|----------|--------|
+| `size=M` | Set size class explicitly |
+| `files=5` | Set file count explicitly |
+| `complexity=high` | Set complexity explicitly |
+| `steps=implement,test,qa` | Estimate only those pipeline steps |
+| `project_type=migration` | Set project type explicitly |
+| `language=go` | Set primary language explicitly |
+| `review_cycles=3` | Set PR review cycle count (0 = disable) |
+
+## Confidence Bands
+
+| Band        | Cache Hit | Multiplier | Meaning                                |
+|-------------|-----------|------------|----------------------------------------|
+| Optimistic  | 60%       | 0.6x       | Best case — focused agent work         |
+| Expected    | 50%       | 1.0x       | Typical run                            |
+| Pessimistic | 30%       | 3.0x       | With rework loops, debugging, retries  |
+
+## Calibration
+
+Calibration is fully automatic:
+- **0-2 sessions:** No correction applied. "Collecting data" status.
+- **3-10 sessions:** Global correction factor via trimmed mean of actual/expected ratios (trim_fraction=0.1).
+- **10+ sessions:** EWMA with recency weighting. Per-size-class factors activate when a class has 3+ samples.
+- **Outlier filtering:** Sessions with actual/expected ratio >3.0x or <0.2x are excluded from calibration and logged for inspection.
+
+Calibration data lives in `calibration/` (gitignored, local to each user).
+
+## Disabling
+
+```bash
+bash /path/to/tokencast/scripts/disable.sh /path/to/your-project
+```
+
+Removes the skill and hooks. Preserves calibration data for reuse.
+
+## Files
+
+```
+SKILL.md                        — Skill definition (auto-trigger, algorithm)
+references/pricing.md           — Model prices, cache rates, step→model map
+references/heuristics.md        — Token budgets, pipeline decompositions, multipliers
+references/examples.md          — Worked examples with arithmetic
+references/calibration-algorithm.md — Detailed calibration algorithm reference
+commands/
+  tokencast-version.md     — /tokencast-version slash command
+scripts/
+  install-hooks.sh              — One-time project setup
+  disable.sh                    — Remove from project
+  tokencast-learn.sh       — Stop hook: auto-captures actuals
+  tokencast-track.sh       — PostToolUse hook: nudges estimation after plans
+  sum-session-tokens.py         — Parses session JSONL for actual costs
+  update-factors.py             — Computes calibration factors from history
+calibration/                    — Per-user local data (gitignored)
+  history.jsonl                 — Estimate vs actual records
+  factors.json                  — Learned correction factors
+  active-estimate.json          — Transient marker for current estimate
+```
+
+## v1.1 Changes
+
+- **Trimmed mean** replaces median for faster convergence with small samples
+- **Outlier flagging** — extreme ratios (>3.0x or <0.2x) excluded from calibration, logged for inspection
+- **Richer data** — project type, language, pipeline signature, and step count captured per session
+- **Baseline subtraction** — tokens spent before the estimate are excluded from actuals
+- **Security hardening** — path injection fixes, consolidated parsing, safe handling of paths with spaces
+- **Version markers** — `version: 1.1.0` in SKILL.md, `--version` flag on learn script
+
+## v1.2 Changes
+
+- **PR Review Loop modeling** — geometric-decay cost model for review-fix-re-review cycles
+- **New override** — `review_cycles=N` to set expected cycle count (0 = disable)
+- **Per-band calibration** — PR Review Loop applies calibration independently per band (not re-anchored)
+- **New schema fields** — `review_cycles_estimated` and `review_cycles_actual` in active-estimate.json
+
+## Limitations
+
+- Pipeline step names reflect a default workflow — map your own steps to the closest defaults. Formulas are pipeline-agnostic (see `references/heuristics.md`)
+- Heuristics assume typical 150-300 line source files
+- Does not model parallel agent execution
+- Calibration requires 3+ completed sessions before corrections activate
+- Pricing data embedded; check `last_updated` in references/pricing.md
+- Multi-session tasks only capture the session containing the estimate
+
+## License
+
+MIT

tokencast-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+tokencast/__init__.py,sha256=0jzkVDSSFzmt5udYTWuCZLQeZXOQsQcw1yt0_uD9_SU,98
+tokencast-0.1.0.dist-info/METADATA,sha256=ZCa8CMyYuzQYbdFe5IsaPcFyKkk7optq-Ssn8lb7-3Y,8637
+tokencast-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+tokencast-0.1.0.dist-info/licenses/LICENSE,sha256=BRpVorPXnNn_0agY7SJJNESzSLfUm3Ul7d0KKMc6sic,1068
+tokencast-0.1.0.dist-info/RECORD,,

tokencast-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

tokencast-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kelly Lewis
+
+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.