{"id":49187713,"url":"https://github.com/mukundakatta/tokenwise","last_synced_at":"2026-04-23T05:03:04.600Z","repository":{"id":347637674,"uuid":"1191405996","full_name":"MukundaKatta/TokenWise","owner":"MukundaKatta","description":"Token usage optimization toolkit — count, estimate costs, optimize prompts, track budgets across LLM providers","archived":false,"fork":false,"pushed_at":"2026-04-19T21:14:43.000Z","size":20,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-19T23:24:47.718Z","etag":null,"topics":["ai","llm","machine-learning","officethree","open-source","python","token-optimization","tokens"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MukundaKatta.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-25T07:59:29.000Z","updated_at":"2026-04-19T21:14:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/MukundaKatta/TokenWise","commit_stats":null,"previous_names":["mukundakatta/tokenwise"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/MukundaKatta/TokenWise","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MukundaKatta%2FTokenWise","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MukundaKatta%2FTokenWise/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MukundaKatta%2FTokenWise/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MukundaKatta%2FTokenWise/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MukundaKatta","download_url":"https://codeload.github.com/MukundaKatta/TokenWise/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MukundaKatta%2FTokenWise/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32166661,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-23T02:19:40.750Z","status":"ssl_error","status_checked_at":"2026-04-23T02:17:55.737Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","llm","machine-learning","officethree","open-source","python","token-optimization","tokens"],"created_at":"2026-04-23T05:02:58.413Z","updated_at":"2026-04-23T05:03:04.590Z","avatar_url":"https://github.com/MukundaKatta.png","language":"Python","readme":"# TokenWise\n\n[![CI](https://github.com/MukundaKatta/TokenWise/actions/workflows/ci.yml/badge.svg)](https://github.com/MukundaKatta/TokenWise/actions/workflows/ci.yml)\n[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\n**Token usage optimization toolkit** — count tokens, compress prompts, estimate API costs, and track LLM token budgets. Works with GPT-4, Claude, Llama, Gemini, Mistral, and more.\n\n---\n\n## Why TokenWise\n\nToken cost and context-window limits show up everywhere in modern AI systems, but most teams still handle them with scattered scripts, rough estimates, and provider-specific logic.\n\nTokenWise is designed to make those concerns easier to manage in one place:\n\n- estimate token usage before a request goes out\n- compare cost across model families\n- compress prompts when budgets are tight\n- track spend over time instead of treating cost as an afterthought\n\n## What It Covers\n\n- token counting heuristics across major model families\n- prompt optimization and budget-aware trimming\n- cost estimation for input and output tokens\n- usage tracking with alerts and reporting\n- batch prompt cleanup workflows\n\n## Architecture\n\n```mermaid\ngraph LR\n    A[Your Code] --\u003e B[TokenWise]\n    B --\u003e C[TokenCounter]\n    B --\u003e D[TokenOptimizer]\n    B --\u003e E[CostEstimator]\n    B --\u003e F[UsageTracker]\n    B --\u003e G[BatchOptimizer]\n    C --\u003e C1[count]\n    C --\u003e C2[count_messages]\n    C --\u003e C3[fits_context]\n    D --\u003e D1[optimize]\n    D --\u003e D2[optimize_to_budget]\n    D --\u003e D3[savings_report]\n    E --\u003e E1[estimate]\n    E --\u003e E2[compare_models]\n    F --\u003e F1[track]\n    F --\u003e F2[check_budget]\n    F --\u003e F3[get_report]\n    G --\u003e G1[optimize_batch]\n    G --\u003e G2[deduplicate_prompts]\n    B --\u003e H[Config]\n    H --\u003e H1[Model Pricing]\n    H --\u003e H2[Budget Settings]\n```\n\n## Quickstart\n\n### Installation\n\n```bash\npip install tokenwise\n```\n\nOr install from source:\n\n```bash\ngit clone https://github.com/MukundaKatta/TokenWise.git\ncd TokenWise\npip install -e .\n```\n\n### Basic Usage\n\n```python\nfrom tokenwise import TokenCounter, TokenOptimizer, CostEstimator, UsageTracker\n\n# Count tokens\ncounter = TokenCounter()\ntokens = counter.count(\"Hello, how can I help you today?\", model=\"gpt-4\")\nprint(f\"Token count: {tokens}\")\n\n# Estimate cost\nestimator = CostEstimator()\ncost = estimator.estimate(tokens, model=\"gpt-4\")\nprint(f\"Estimated cost: ${cost:.6f}\")\n\n# Optimize a prompt\noptimizer = TokenOptimizer()\nreport = optimizer.savings_report(\n    \"Please kindly just basically explain what AI actually is in my opinion.\"\n)\nprint(f\"Saved {report['tokens_saved']} tokens ({report['savings_pct']}%)\")\n\n# Track usage with budget alerts\ntracker = UsageTracker()\ntracker.track(\n    request=\"Explain quantum computing in simple terms.\",\n    response=\"Quantum computing uses qubits instead of classical bits...\"\n)\nprint(f\"Total spend: ${tracker.total_cost():.6f}\")\n```\n\n### Multi-step Budget Breakdown\n\n```python\nfrom tokenwise import BudgetTracker\n\ntracker = BudgetTracker()\ntracker.add_step(\"draft\", request=\"Write a landing page headline\", response=\"Fast AI workflows for teams.\")\ntracker.add_step(\"review\", request=\"Critique the headline\", response=\"Shorten the second clause.\")\n\nreport = tracker.get_report(warning_threshold_usd=0.01)\nprint(report.total_cost)\nprint(report.pricing_version)\nfor step in report.steps:\n    print(step.name, step.total_tokens, step.total_cost)\n```\n\n### CLI\n\n```bash\n# Count tokens\ntokenwise count \"Hello, how can I help you today?\"\n\n# Estimate cost\ntokenwise cost \"Hello, how can I help you today?\" --model gpt-4\n\n# Compare costs across all models\ntokenwise cost \"Hello, how can I help you today?\" --compare\n\n# Optimize a prompt\ntokenwise optimize \"Please kindly just basically explain what AI is.\"\n```\n\n### Batch Optimization\n\n```python\nfrom tokenwise import BatchOptimizer\n\nbatch = BatchOptimizer()\nprompts = [\n    \"Please kindly explain AI.\",\n    \"In order to understand, basically describe ML.\",\n    \"Please kindly explain AI.\",  # duplicate\n]\n\n# Deduplicate\nunique = batch.deduplicate_prompts(prompts)\n\n# Optimize and get summary\nsummary = batch.batch_summary(unique)\nprint(f\"Saved {summary['total_tokens_saved']} tokens across {summary['prompt_count']} prompts\")\n```\n\n## Pricing Data\n\nModel pricing now lives in a versioned package data file at `src/tokenwise/data/model_pricing.v1.json`.\n\nThat gives TokenWise a safer update workflow:\n\n- pricing changes are separated from estimator logic\n- the catalog carries an explicit version\n- historical reports can point back to the pricing version used at the time\n\nTo update pricing, edit the JSON catalog, keep the schema consistent, and run the test suite before publishing.\n\n## Pricing Table\n\n| Model | Input (per 1K tokens) | Output (per 1K tokens) |\n|-------|----------------------|------------------------|\n| GPT-4 | $0.0300 | $0.0600 |\n| GPT-4 Turbo | $0.0100 | $0.0300 |\n| GPT-4o | $0.0050 | $0.0150 |\n| GPT-3.5 Turbo | $0.0005 | $0.0015 |\n| Claude 3 Opus | $0.0150 | $0.0750 |\n| Claude 3.5 Sonnet | $0.0030 | $0.0150 |\n| Claude 3 Haiku | $0.00025 | $0.00125 |\n| Claude 4 Opus | $0.0150 | $0.0750 |\n| Claude 4 Sonnet | $0.0030 | $0.0150 |\n| Gemini 1.5 Pro | $0.00125 | $0.0050 |\n| Gemini 1.5 Flash | $0.000075 | $0.0003 |\n| Llama 3 70B | $0.00059 | $0.00079 |\n| Llama 3 8B | $0.00005 | $0.00008 |\n| Mistral Large | $0.0040 | $0.0120 |\n| Mistral Small | $0.0010 | $0.0030 |\n\n## Features\n\n- **Token Counting** — Heuristic-based token estimation for all major LLM models\n- **Prompt Optimization** — Compress prompts by removing filler words and shortening verbose phrases\n- **Cost Estimation** — Up-to-date pricing for GPT-4, Claude, Gemini, Llama, Mistral, and more\n- **Usage Tracking** — Track token usage with daily/monthly budgets and threshold alerts\n- **Batch Optimization** — Optimize and deduplicate lists of prompts in bulk\n- **CLI** — Built-in command-line interface powered by Typer and Rich\n- **Model Comparison** — Compare token counts and costs across models side-by-side\n\n## Who This Is For\n\n- developers building AI products with real token budgets\n- teams comparing providers and model cost tradeoffs\n- prompt engineers trying to reduce waste without losing clarity\n- anyone who wants lightweight token tooling without a larger framework\n\n## Configuration\n\nSet defaults via environment variables or `.env` file:\n\n```bash\nTOKENWISE_DEFAULT_MODEL=gpt-4\nTOKENWISE_LOG_LEVEL=INFO\nTOKENWISE_COST_MULTIPLIER=1.0\n```\n\nSee [.env.example](.env.example) for all available options.\n\n## Development\n\n```bash\nmake dev       # Install with dev dependencies\nmake test      # Run tests\nmake lint      # Lint with ruff\nmake format    # Auto-format code\nmake run       # Show CLI help\n```\n\n## Project Direction\n\nTokenWise is best when it stays practical: easy to script, easy to embed in existing apps, and focused on the real questions developers ask when shipping LLM-powered systems.\n\nFuture improvements can build on that foundation with:\n\n- better model-pricing refresh workflows\n- more benchmark-style prompt comparisons\n- richer reporting and budget policy options\n- stronger integration patterns for production AI pipelines\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for details.\n\n---\n\n*Inspired by LLM cost optimization trends and the need for better token management*\n\n---\n\nBuilt by Officethree Technologies | Made with ❤️ and AI\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmukundakatta%2Ftokenwise","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmukundakatta%2Ftokenwise","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmukundakatta%2Ftokenwise/lists"}