token-guardian 0.1.0__tar.gz

token_guardian-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+token_guardian.db
+.venv/

token_guardian-0.1.0/LICENSE

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

token_guardian-0.1.0/PKG-INFO

@@ -0,0 +1,293 @@
+Metadata-Version: 2.4
+Name: token-guardian
+Version: 0.1.0
+Summary: CLI-first prompt guardrail for token, cost, and context observability.
+Project-URL: Homepage, https://pypi.org/project/token-guardian/
+Project-URL: Repository, https://github.com/LeonardoCesca/token-guardian
+Project-URL: Issues, https://github.com/LeonardoCesca/token-guardian/issues
+Author: Token Guardian Contributors
+License: MIT
+License-File: LICENSE
+Keywords: cli,cost,guardrail,llm,prompt,tokens
+Classifier: Development Status :: 4 - Beta
+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.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: inquirerpy<1.0.0,>=0.3.4
+Requires-Dist: pydantic<3.0.0,>=2.8.0
+Requires-Dist: rich<14.0.0,>=13.9.0
+Provides-Extra: dev
+Requires-Dist: black<25.0.0,>=24.8.0; extra == 'dev'
+Requires-Dist: mypy<2.0.0,>=1.11.0; extra == 'dev'
+Requires-Dist: pytest-cov<6.0.0,>=5.0.0; extra == 'dev'
+Requires-Dist: pytest<9.0.0,>=8.3.0; extra == 'dev'
+Requires-Dist: ruff<1.0.0,>=0.6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Token Guardian
+
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-2F81F7)](https://www.python.org/)
+[![CLI](https://img.shields.io/badge/interface-CLI-00C2FF)](#usage)
+[![License: MIT](https://img.shields.io/badge/license-MIT-8CE99A)](#license)
+[![Tests](https://img.shields.io/badge/tests-pytest-6EA8FE)](#development)
+
+Token Guardian is a CLI-first guardrail for checking prompt size, context pressure, and estimated cost before you call an LLM.
+
+It helps developers answer three questions quickly:
+
+- how many tokens this prompt will probably use
+- how much this request may cost
+- whether this prompt is risky for the selected context window
+
+## Why Use Token Guardian?
+
+- catch oversized prompts before they hit the model
+- estimate cost before expensive runs
+- compare supported models using the same prompt
+- clean duplicated or bloated prompt text
+- keep simple local observability with SQLite metrics
+- start from an interactive terminal menu instead of memorizing commands
+
+## Copy-Paste Install
+
+### Windows PowerShell
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+pip install -e .[dev]
+token-guardian
+```
+
+### macOS / Linux
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .[dev]
+token-guardian
+```
+
+Running `token-guardian` without arguments opens an interactive menu when your terminal supports it.
+
+## What the CLI Can Do
+
+- analyze one prompt for one provider/model pair
+- compare one prompt across the default supported models
+- optimize prompt text by removing duplicates and excess whitespace
+- list supported models
+- sync the local model catalog snapshot
+- inspect local usage metrics
+- guide the full flow through an interactive menu
+
+## Usage
+
+### Start here
+
+```bash
+token-guardian
+```
+
+Running without arguments shows the available flow and the most useful commands to start with.
+
+In interactive terminals, Token Guardian opens a guided menu with:
+
+- provider selection
+- model selection
+- prompt entry with Enter to send
+- sync selection by provider
+- quick access to models and metrics
+
+### Analyze a prompt
+
+```bash
+token-guardian analyze \
+  --provider anthropic \
+  --model claude-sonnet-4 \
+  --prompt "Review this architecture proposal and identify risks."
+```
+
+### Compare models
+
+```bash
+token-guardian compare \
+  --prompt "Summarize this technical RFC and list migration risks."
+```
+
+### Optimize a prompt
+
+```bash
+token-guardian optimize \
+  --prompt "Goal: summarize
+Goal: summarize
+
+
+Return bullets only."
+```
+
+### List supported models
+
+```bash
+token-guardian models
+```
+
+### Sync model catalog
+
+```bash
+token-guardian sync-models
+token-guardian sync-models --provider openai
+```
+
+### View local metrics
+
+```bash
+token-guardian metrics
+```
+
+## Example Output
+
+Typical `analyze` output:
+
+```json
+{
+  "provider": "anthropic",
+  "model": "claude-sonnet-4",
+  "input_tokens": 20,
+  "estimated_output_tokens": 128,
+  "estimated_total_tokens": 148,
+  "context_limit": 200000,
+  "context_usage_percent": 0.07,
+  "estimated_cost_usd": 0.00198,
+  "risk_level": "low",
+  "context_health_score": 99,
+  "cost_score": "$",
+  "complexity_score": "Simple",
+  "suggestions": [
+    "Prompt enxuto e com bom sinal; mantenha foco em objetivo, restricoes e saida."
+  ]
+}
+```
+
+## Supported Providers
+
+Current built-in catalog:
+
+- OpenAI: `gpt-4.1`
+- Anthropic: `claude-sonnet-4`, `claude-opus-4`
+- Google: `gemini-2.5-pro`, `gemini-2.5-flash`
+- OpenRouter: `openai/gpt-4.1`
+
+Each model stores:
+
+- context limit
+- input price per 1K tokens
+- output price per 1K tokens
+- speed estimate
+- source URL
+
+The CLI also shows catalog metadata such as:
+
+- `Catalogo atualizado em 2026-06-13`
+- the current JSON snapshot path
+
+## Scoring
+
+### Risk level
+
+Based on estimated context usage:
+
+- `low`
+- `medium`
+- `high`
+- `critical`
+
+### Context health score
+
+Range: `0` to `100`
+
+Factors include:
+
+- prompt size
+- repeated lines
+- repeated vocabulary
+- redundant sections
+
+### Cost score
+
+- `$`: very low
+- `$$`: low
+- `$$$`: medium
+- `$$$$`: high
+
+### Complexity score
+
+- `Simple`
+- `Medium`
+- `Complex`
+- `Very Complex`
+
+## Metrics
+
+Token Guardian stores local metrics in SQLite.
+
+Database file:
+
+- `token_guardian.db`
+
+Tracked fields include:
+
+- total requests
+- total tokens
+- estimated cumulative cost
+- top models
+- top providers
+
+## Project Structure
+
+```text
+token-guardian/
+|-- app/
+|   |-- cli.py
+|   |-- models/
+|   |-- providers/
+|   |-- services/
+|   `-- utils/
+|-- docs/
+|-- tests/
+|-- LICENSE
+|-- pyproject.toml
+`-- README.md
+```
+
+## Development
+
+Run tests:
+
+```bash
+pytest
+```
+
+Run quality checks:
+
+```bash
+ruff check .
+black --check .
+mypy app
+```
+
+## Roadmap
+
+- add richer interactive CLI flows
+- expand supported model catalog
+- improve prompt optimization heuristics
+- add exportable reports
+- add model catalog sync support
+
+## License
+
+MIT

token_guardian-0.1.0/README.md

@@ -0,0 +1,262 @@
+# Token Guardian
+
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-2F81F7)](https://www.python.org/)
+[![CLI](https://img.shields.io/badge/interface-CLI-00C2FF)](#usage)
+[![License: MIT](https://img.shields.io/badge/license-MIT-8CE99A)](#license)
+[![Tests](https://img.shields.io/badge/tests-pytest-6EA8FE)](#development)
+
+Token Guardian is a CLI-first guardrail for checking prompt size, context pressure, and estimated cost before you call an LLM.
+
+It helps developers answer three questions quickly:
+
+- how many tokens this prompt will probably use
+- how much this request may cost
+- whether this prompt is risky for the selected context window
+
+## Why Use Token Guardian?
+
+- catch oversized prompts before they hit the model
+- estimate cost before expensive runs
+- compare supported models using the same prompt
+- clean duplicated or bloated prompt text
+- keep simple local observability with SQLite metrics
+- start from an interactive terminal menu instead of memorizing commands
+
+## Copy-Paste Install
+
+### Windows PowerShell
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+pip install -e .[dev]
+token-guardian
+```
+
+### macOS / Linux
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .[dev]
+token-guardian
+```
+
+Running `token-guardian` without arguments opens an interactive menu when your terminal supports it.
+
+## What the CLI Can Do
+
+- analyze one prompt for one provider/model pair
+- compare one prompt across the default supported models
+- optimize prompt text by removing duplicates and excess whitespace
+- list supported models
+- sync the local model catalog snapshot
+- inspect local usage metrics
+- guide the full flow through an interactive menu
+
+## Usage
+
+### Start here
+
+```bash
+token-guardian
+```
+
+Running without arguments shows the available flow and the most useful commands to start with.
+
+In interactive terminals, Token Guardian opens a guided menu with:
+
+- provider selection
+- model selection
+- prompt entry with Enter to send
+- sync selection by provider
+- quick access to models and metrics
+
+### Analyze a prompt
+
+```bash
+token-guardian analyze \
+  --provider anthropic \
+  --model claude-sonnet-4 \
+  --prompt "Review this architecture proposal and identify risks."
+```
+
+### Compare models
+
+```bash
+token-guardian compare \
+  --prompt "Summarize this technical RFC and list migration risks."
+```
+
+### Optimize a prompt
+
+```bash
+token-guardian optimize \
+  --prompt "Goal: summarize
+Goal: summarize
+
+
+Return bullets only."
+```
+
+### List supported models
+
+```bash
+token-guardian models
+```
+
+### Sync model catalog
+
+```bash
+token-guardian sync-models
+token-guardian sync-models --provider openai
+```
+
+### View local metrics
+
+```bash
+token-guardian metrics
+```
+
+## Example Output
+
+Typical `analyze` output:
+
+```json
+{
+  "provider": "anthropic",
+  "model": "claude-sonnet-4",
+  "input_tokens": 20,
+  "estimated_output_tokens": 128,
+  "estimated_total_tokens": 148,
+  "context_limit": 200000,
+  "context_usage_percent": 0.07,
+  "estimated_cost_usd": 0.00198,
+  "risk_level": "low",
+  "context_health_score": 99,
+  "cost_score": "$",
+  "complexity_score": "Simple",
+  "suggestions": [
+    "Prompt enxuto e com bom sinal; mantenha foco em objetivo, restricoes e saida."
+  ]
+}
+```
+
+## Supported Providers
+
+Current built-in catalog:
+
+- OpenAI: `gpt-4.1`
+- Anthropic: `claude-sonnet-4`, `claude-opus-4`
+- Google: `gemini-2.5-pro`, `gemini-2.5-flash`
+- OpenRouter: `openai/gpt-4.1`
+
+Each model stores:
+
+- context limit
+- input price per 1K tokens
+- output price per 1K tokens
+- speed estimate
+- source URL
+
+The CLI also shows catalog metadata such as:
+
+- `Catalogo atualizado em 2026-06-13`
+- the current JSON snapshot path
+
+## Scoring
+
+### Risk level
+
+Based on estimated context usage:
+
+- `low`
+- `medium`
+- `high`
+- `critical`
+
+### Context health score
+
+Range: `0` to `100`
+
+Factors include:
+
+- prompt size
+- repeated lines
+- repeated vocabulary
+- redundant sections
+
+### Cost score
+
+- `$`: very low
+- `$$`: low
+- `$$$`: medium
+- `$$$$`: high
+
+### Complexity score
+
+- `Simple`
+- `Medium`
+- `Complex`
+- `Very Complex`
+
+## Metrics
+
+Token Guardian stores local metrics in SQLite.
+
+Database file:
+
+- `token_guardian.db`
+
+Tracked fields include:
+
+- total requests
+- total tokens
+- estimated cumulative cost
+- top models
+- top providers
+
+## Project Structure
+
+```text
+token-guardian/
+|-- app/
+|   |-- cli.py
+|   |-- models/
+|   |-- providers/
+|   |-- services/
+|   `-- utils/
+|-- docs/
+|-- tests/
+|-- LICENSE
+|-- pyproject.toml
+`-- README.md
+```
+
+## Development
+
+Run tests:
+
+```bash
+pytest
+```
+
+Run quality checks:
+
+```bash
+ruff check .
+black --check .
+mypy app
+```
+
+## Roadmap
+
+- add richer interactive CLI flows
+- expand supported model catalog
+- improve prompt optimization heuristics
+- add exportable reports
+- add model catalog sync support
+
+## License
+
+MIT

token_guardian-0.1.0/app/__init__.py

@@ -0,0 +1,2 @@
+"""Token Guardian MCP application package."""
+