promptmeter 0.1.0__tar.gz

promptmeter-0.1.0/.github/ISSUE_TEMPLATE/bug.md

@@ -0,0 +1,30 @@
+---
+name: Bug report
+about: Something doesn't work as expected
+title: "[BUG] "
+labels: bug
+---
+
+## What happened
+
+<!-- A clear description of what went wrong. -->
+
+## What you expected
+
+<!-- What did you expect to happen instead? -->
+
+## Reproduction
+
+```python
+# minimal code that reproduces the issue
+```
+
+If a specific prompt triggered it:
+- Prompt: `<paste here>`
+- Rule that fired (if any): `<RULE_ID>`
+
+## Environment
+
+- promptmeter version: <!-- `pip show promptmeter` -->
+- Python version: <!-- `python --version` -->
+- OS:

promptmeter-0.1.0/.github/ISSUE_TEMPLATE/feature.md

@@ -0,0 +1,18 @@
+---
+name: Feature request
+about: Suggest a new feature or enhancement
+title: "[FEATURE] "
+labels: enhancement
+---
+
+## Problem
+
+<!-- What problem are you trying to solve? -->
+
+## Proposed solution
+
+<!-- What would you like to see? -->
+
+## Alternatives considered
+
+<!-- Any other approaches you've thought about? -->

promptmeter-0.1.0/.github/ISSUE_TEMPLATE/suggest_rule.md

@@ -0,0 +1,32 @@
+---
+name: Suggest a new rule
+about: Propose a new pre-flight rule for the analyzer
+title: "[RULE] "
+labels: new-rule
+---
+
+## Pattern this rule should catch
+
+<!-- One sentence: what wasteful pattern does this detect? -->
+
+## Example prompts that should trigger it
+
+```
+<paste 1-3 example prompts>
+```
+
+## Example prompts that should NOT trigger it (false-positive guards)
+
+```
+<paste 1-3 prompts that look similar but are fine>
+```
+
+## Suggested severity
+
+- [ ] high   (clear waste, real cost)
+- [ ] medium (suboptimal, costs more output)
+- [ ] low    (cosmetic, costs a few tokens)
+
+## Suggested fix message
+
+<!-- What would you tell the user? -->

promptmeter-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,19 @@
+## Summary
+
+<!-- 1–3 bullets on what changed and why. -->
+
+## Type of change
+
+- [ ] New rule (added to `analyzer/rules.py`)
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Documentation
+- [ ] Refactor / internal cleanup
+
+## Checklist
+
+- [ ] `pytest` passes locally
+- [ ] `ruff check .` passes locally
+- [ ] Added / updated tests
+- [ ] Updated README rule table (if a new rule was added)
+- [ ] Added an entry under `## [Unreleased]` in CHANGELOG.md

promptmeter-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package + dev dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Test
+        run: pytest -v

promptmeter-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write   # required for PyPI trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

promptmeter-0.1.0/.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Editor / IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# Local Token Tracker data (never commit your usage DB)
+*.db
+.token_tracker/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Environment
+.env
+.env.local
+
+# Smoke / scratch test scripts (these were one-off dev verifications)
+test_phase*.py

promptmeter-0.1.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-10
+
+Initial release.
+
+### Added
+
+- `TrackedClient` — drop-in wrapper around `anthropic.Anthropic`
+- SQLite logging at `~/.token_tracker/usage.db` (sessions + usage records)
+- Pre-flight analyzer with 8 rules:
+  `VAGUE_INTENT`, `OPEN_ENDED_TASK`, `WALL_OF_TEXT`, `MISSING_FORMAT`,
+  `MISSING_SCOPE`, `REDUNDANT_CONTEXT`, `FILLER_WORDS`, `AMBIGUOUS_PRONOUN`
+- 0–100 efficiency scoring with severity-based penalties
+- Rule-based prompt optimizer with side-by-side rewrite diff
+- Interactive `[s]end / [o]ptimize+send / [c]ancel` flow
+- CLI: `tt report`, `tt sessions`, `tt analyze`, `tt top-waste`, `tt cost-model`, `tt demo`
+- Cost calculation for `claude-opus-4-7`, `claude-sonnet-4-6`, `claude-haiku-4-5`

promptmeter-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,96 @@
+# Contributing to Token Tracker
+
+Thanks for considering a contribution. The lowest-friction way to help is **adding a new rule to the pre-flight analyzer** — see below.
+
+---
+
+## Setting up
+
+```bash
+git clone https://github.com/emam07/Token-tracker.git
+cd Token-tracker
+python -m venv .venv
+.venv/Scripts/activate          # Windows
+source .venv/bin/activate       # macOS / Linux
+pip install -e ".[dev]"
+```
+
+Run the test suite:
+```bash
+pytest
+ruff check .
+```
+
+---
+
+## Adding a new rule (great first PR)
+
+A "rule" detects one wasteful prompt pattern. Adding one takes ~10 lines.
+
+**1.** Open `token_tracker/analyzer/rules.py`.
+
+**2.** Write your rule as a function returning `Warning | None`:
+
+```python
+def check_my_pattern(prompt: str) -> Warning | None:
+    if re.search(r"\bsome bad pattern\b", prompt, re.IGNORECASE):
+        return Warning(
+            rule="MY_RULE_ID",
+            severity="medium",          # "low" | "medium" | "high"
+            message="Short explanation of what's wrong.",
+            suggestion="Concrete advice on how to fix it.",
+        )
+    return None
+```
+
+**3.** Add the function to the `RULES` list at the bottom of the file.
+
+**4.** Add a unit test in `tests/test_rules.py`:
+
+```python
+def test_my_rule_triggers_on_bad_prompt():
+    result = check_my_pattern("contains some bad pattern here")
+    assert result is not None
+    assert result.rule == "MY_RULE_ID"
+
+def test_my_rule_skips_clean_prompt():
+    assert check_my_pattern("a perfectly fine prompt") is None
+```
+
+**5.** Add the rule to the table in `README.md`.
+
+That's it. Open the PR.
+
+---
+
+## Reporting a false positive
+
+Open an issue with the **"Bug"** template and include:
+- The exact prompt that triggered the warning
+- Which rule fired
+- Why you think it's wrong
+
+---
+
+## Pull request checklist
+
+- [ ] New rule has a unit test (positive + negative case)
+- [ ] `pytest` passes locally
+- [ ] `ruff check .` passes locally
+- [ ] README rule table updated (if a new rule was added)
+- [ ] CHANGELOG entry added under `## [Unreleased]`
+
+---
+
+## Code style
+
+- 100-char lines max
+- Type hints on public functions
+- No comments explaining *what* the code does — only *why*, when non-obvious
+- Prefer stdlib over new dependencies
+
+---
+
+## Questions
+
+Open a [discussion](https://github.com/emam07/Token-tracker/discussions) before a big change.

promptmeter-0.1.0/LICENSE

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

promptmeter-0.1.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: promptmeter
+Version: 0.1.0
+Summary: Pre-flight token analyzer and usage tracker for Claude — gas optimization for LLM prompts
+Project-URL: Homepage, https://github.com/emam07/Token-tracker
+Project-URL: Repository, https://github.com/emam07/Token-tracker
+Project-URL: Issues, https://github.com/emam07/Token-tracker/issues
+Project-URL: Documentation, https://github.com/emam07/Token-tracker#readme
+Author: Token Tracker contributors
+License: MIT
+License-File: LICENSE
+Keywords: ai,anthropic,claude,cost,llm,prompt-optimization,token
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=0.40.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tiktoken>=0.6.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Token Tracker
+
+> **Gas optimization for LLM prompts.** A pre-flight analyzer + usage tracker for the Claude API. Catches vague, wasteful, or open-ended prompts *before* they hit the wire — and suggests a leaner rewrite.
+
+[![PyPI version](https://img.shields.io/pypi/v/promptmeter.svg)](https://pypi.org/project/promptmeter/)
+[![Python](https://img.shields.io/pypi/pyversions/promptmeter.svg)](https://pypi.org/project/promptmeter/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![CI](https://github.com/emam07/Token-tracker/actions/workflows/ci.yml/badge.svg)](https://github.com/emam07/Token-tracker/actions)
+
+---
+
+## The idea
+
+Solidity devs use a gas estimator before deploying. LLM devs send blind prompts and wait for the bill.
+
+Token Tracker fixes that. It wraps the Anthropic SDK and adds three layers:
+
+| Layer | What it does | Analogy |
+|---|---|---|
+| **Token Tracker** | Logs every API call — tokens in/out, cost, session | Gas meter |
+| **Pre-flight Analyzer** | Scores your prompt before sending — flags 8 patterns of waste | Gas estimator + linter |
+| **Prompt Optimizer** | Rewrites bad prompts into leaner versions, side-by-side | Compiler optimizer |
+
+All analysis is **offline** — zero extra API calls. Storage is local SQLite.
+
+---
+
+## Demo
+
+![Token Tracker demo](docs/demo.gif)
+
+*Run `tt demo` yourself to see all features without using any API credits.*
+
+---
+
+## Quickstart
+
+```bash
+pip install promptmeter
+export ANTHROPIC_API_KEY="sk-ant-..."
+```
+
+### As a drop-in for the Anthropic SDK
+
+```python
+from token_tracker import TrackedClient
+
+client = TrackedClient(session_name="my-app")
+
+response = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=512,
+    messages=[{"role": "user", "content": "List 3 Python web frameworks."}],
+)
+```
+
+That's it. Every call is now analyzed, logged, and reportable.
+
+### As a standalone CLI
+
+```bash
+tt analyze "Please could you kindly tell me something about Python"
+tt report                # today's usage summary
+tt report --week         # last 7 days
+tt cost-model            # cost breakdown by model
+tt top-waste             # most expensive flagged prompts
+tt sessions              # list named sessions
+tt demo                  # guided walkthrough — zero API calls
+```
+
+---
+
+## What the pre-flight catches
+
+8 rules, each with severity and a suggested fix:
+
+| Rule | Severity | Detects |
+|---|---|---|
+| `VAGUE_INTENT` | high | `"tell me something about X"` — no clear task |
+| `OPEN_ENDED_TASK` | high | `"explain everything about X"` — unbounded scope |
+| `WALL_OF_TEXT` | high | unstructured 500+ token dumps |
+| `MISSING_FORMAT` | medium | asks for a list without specifying format |
+| `MISSING_SCOPE` | medium | `"explain X"` with no length/depth limit |
+| `REDUNDANT_CONTEXT` | medium | the same sentence twice |
+| `FILLER_WORDS` | low | "please", "could you kindly", "thank you in advance" |
+| `AMBIGUOUS_PRONOUN` | low | "fix it" — fix what? |
+
+Each rule contributes to a **0–100 efficiency score**. Below 60 triggers a warning. Below 40 hard-blocks (in interactive mode).
+
+---
+
+## Try the walkthrough
+
+```bash
+tt demo
+```
+
+Runs through every feature with three example prompts (good, bad, terrible) and renders the live dashboard. No API calls, safe to run anytime.
+
+---
+
+## How it actually saves tokens
+
+| Without Token Tracker | With Token Tracker |
+|---|---|
+| Vague prompt → Claude asks clarifying questions → 2-3 round trips | Pre-flight catches vagueness → fix once → one round trip |
+| `"explain X"` → Claude writes 800 words when you needed 100 | `MISSING_SCOPE` flags it → add `"in 3 sentences"` → 6× cheaper output |
+| Same context pasted in every message | `REDUNDANT_CONTEXT` warns → use prompt caching → 90% cheaper input |
+| No visibility into spend → no behavior change | Daily report shows cost per session → habits adjust |
+
+Conservative real-world reduction: **30–50% of token spend** for a developer who acts on warnings.
+
+---
+
+## Configuration
+
+```python
+TrackedClient(
+    api_key="sk-ant-...",
+    session_name="my-app",      # tag this session in the DB
+    analyze=True,               # run pre-flight before every call
+    interactive=True,           # prompt user on flagged prompts (s/o/c menu)
+    warn_threshold=60,          # show warning when score drops below this
+)
+```
+
+---
+
+## Where data lives
+
+A single SQLite file at `~/.token_tracker/usage.db`. Two tables: `sessions`, `usage_records`. Open it with [DB Browser for SQLite](https://sqlitebrowser.org/) to poke around.
+
+Token Tracker stores a hash of each prompt — never the full text. Your prompts stay in your process.
+
+---
+
+## Contributing
+
+The lowest-friction first contribution is **adding a new rule** in `token_tracker/analyzer/rules.py` — about 10 lines of Python. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+Found a false positive? Open an issue with the prompt and the rule that misfired.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

promptmeter-0.1.0/README.md

@@ -0,0 +1,147 @@
+# Token Tracker
+
+> **Gas optimization for LLM prompts.** A pre-flight analyzer + usage tracker for the Claude API. Catches vague, wasteful, or open-ended prompts *before* they hit the wire — and suggests a leaner rewrite.
+
+[![PyPI version](https://img.shields.io/pypi/v/promptmeter.svg)](https://pypi.org/project/promptmeter/)
+[![Python](https://img.shields.io/pypi/pyversions/promptmeter.svg)](https://pypi.org/project/promptmeter/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![CI](https://github.com/emam07/Token-tracker/actions/workflows/ci.yml/badge.svg)](https://github.com/emam07/Token-tracker/actions)
+
+---
+
+## The idea
+
+Solidity devs use a gas estimator before deploying. LLM devs send blind prompts and wait for the bill.
+
+Token Tracker fixes that. It wraps the Anthropic SDK and adds three layers:
+
+| Layer | What it does | Analogy |
+|---|---|---|
+| **Token Tracker** | Logs every API call — tokens in/out, cost, session | Gas meter |
+| **Pre-flight Analyzer** | Scores your prompt before sending — flags 8 patterns of waste | Gas estimator + linter |
+| **Prompt Optimizer** | Rewrites bad prompts into leaner versions, side-by-side | Compiler optimizer |
+
+All analysis is **offline** — zero extra API calls. Storage is local SQLite.
+
+---
+
+## Demo
+
+![Token Tracker demo](docs/demo.gif)
+
+*Run `tt demo` yourself to see all features without using any API credits.*
+
+---
+
+## Quickstart
+
+```bash
+pip install promptmeter
+export ANTHROPIC_API_KEY="sk-ant-..."
+```
+
+### As a drop-in for the Anthropic SDK
+
+```python
+from token_tracker import TrackedClient
+
+client = TrackedClient(session_name="my-app")
+
+response = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=512,
+    messages=[{"role": "user", "content": "List 3 Python web frameworks."}],
+)
+```
+
+That's it. Every call is now analyzed, logged, and reportable.
+
+### As a standalone CLI
+
+```bash
+tt analyze "Please could you kindly tell me something about Python"
+tt report                # today's usage summary
+tt report --week         # last 7 days
+tt cost-model            # cost breakdown by model
+tt top-waste             # most expensive flagged prompts
+tt sessions              # list named sessions
+tt demo                  # guided walkthrough — zero API calls
+```
+
+---
+
+## What the pre-flight catches
+
+8 rules, each with severity and a suggested fix:
+
+| Rule | Severity | Detects |
+|---|---|---|
+| `VAGUE_INTENT` | high | `"tell me something about X"` — no clear task |
+| `OPEN_ENDED_TASK` | high | `"explain everything about X"` — unbounded scope |
+| `WALL_OF_TEXT` | high | unstructured 500+ token dumps |
+| `MISSING_FORMAT` | medium | asks for a list without specifying format |
+| `MISSING_SCOPE` | medium | `"explain X"` with no length/depth limit |
+| `REDUNDANT_CONTEXT` | medium | the same sentence twice |
+| `FILLER_WORDS` | low | "please", "could you kindly", "thank you in advance" |
+| `AMBIGUOUS_PRONOUN` | low | "fix it" — fix what? |
+
+Each rule contributes to a **0–100 efficiency score**. Below 60 triggers a warning. Below 40 hard-blocks (in interactive mode).
+
+---
+
+## Try the walkthrough
+
+```bash
+tt demo
+```
+
+Runs through every feature with three example prompts (good, bad, terrible) and renders the live dashboard. No API calls, safe to run anytime.
+
+---
+
+## How it actually saves tokens
+
+| Without Token Tracker | With Token Tracker |
+|---|---|
+| Vague prompt → Claude asks clarifying questions → 2-3 round trips | Pre-flight catches vagueness → fix once → one round trip |
+| `"explain X"` → Claude writes 800 words when you needed 100 | `MISSING_SCOPE` flags it → add `"in 3 sentences"` → 6× cheaper output |
+| Same context pasted in every message | `REDUNDANT_CONTEXT` warns → use prompt caching → 90% cheaper input |
+| No visibility into spend → no behavior change | Daily report shows cost per session → habits adjust |
+
+Conservative real-world reduction: **30–50% of token spend** for a developer who acts on warnings.
+
+---
+
+## Configuration
+
+```python
+TrackedClient(
+    api_key="sk-ant-...",
+    session_name="my-app",      # tag this session in the DB
+    analyze=True,               # run pre-flight before every call
+    interactive=True,           # prompt user on flagged prompts (s/o/c menu)
+    warn_threshold=60,          # show warning when score drops below this
+)
+```
+
+---
+
+## Where data lives
+
+A single SQLite file at `~/.token_tracker/usage.db`. Two tables: `sessions`, `usage_records`. Open it with [DB Browser for SQLite](https://sqlitebrowser.org/) to poke around.
+
+Token Tracker stores a hash of each prompt — never the full text. Your prompts stay in your process.
+
+---
+
+## Contributing
+
+The lowest-friction first contribution is **adding a new rule** in `token_tracker/analyzer/rules.py` — about 10 lines of Python. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+Found a false positive? Open an issue with the prompt and the rule that misfired.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).