token-guardian 0.1.0b1__tar.gz

token_guardian-0.1.0b1/.gitignore

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

token_guardian-0.1.0b1/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: token-guardian
+Version: 0.1.0b1
+Summary: CLI-first guardrail for prompt token, cost, and context observability.
+Author: Token Guardian Contributors
+License: MIT
+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'
+Provides-Extra: gateway
+Requires-Dist: litellm<2.0.0,>=1.51.0; extra == 'gateway'
+Description-Content-Type: text/markdown
+
+# Token Guardian
+
+Token Guardian is a CLI-first preflight guardrail for LLM prompts.
+
+```text
+   _______    _                 _____                     _ _
+  |__   __|  | |               / ____|                   | (_)
+     | | ___ | | _____ _ __   | |  __ _   _  __ _ _ __ __| |_  __ _ _ __
+     | |/ _ \| |/ / _ \ '_ \  | | |_ | | | |/ _` | '__/ _` | |/ _` | '_ \
+     | | (_) |   <  __/ | | | | |__| | |_| | (_| | | | (_| | | (_| | | | |
+     |_|\___/|_|\_\___|_| |_|  \_____|\__,_|\__,_|_|  \__,_|_|\__,_|_| |_|
+
+                            [ shielded prompt preflight ]
+```
+
+Before any real model call, it shows:
+
+- estimated tokens
+- estimated cost
+- context usage
+- context risk
+- prompt reduction hints
+
+Then it shows the analysis before the execution flow continues.
+
+## Preview
+
+Token Guardian opens with an interactive terminal flow that lets developers choose a host profile, select a model, submit a prompt, and inspect the preflight analysis before any real LLM call.
+
+## Release Status
+
+Current release: `0.1.0-beta.1`
+
+This project is ready for early adopters who want to test a prompt guardrail in real workflows. It is not yet positioned as a fully hardened enterprise product.
+
+## What It Is
+
+Token Guardian helps developers inspect a prompt before it reaches an LLM.
+
+It is designed to answer three questions quickly:
+
+- how many tokens this prompt is likely to use
+- how much this prompt may cost
+- whether this prompt is too large, noisy, or risky for the selected model context
+
+## Who It Is For
+
+- developers using LLMs in daily coding workflows
+- teams that want a simple prompt review step before execution
+- open-source users who want a local, cross-platform CLI
+
+## What It Does Not Do
+
+- it does not intercept every editor chat automatically
+- it does not enforce organization-wide policy remotely
+- it does not replace provider-side safety systems
+- it does not depend on MCP or VS Code integration as a product requirement
+
+## Why CLI First
+
+This is the most reliable way to enforce a real preflight gate:
+
+- it works on Windows, macOS, and Linux
+- it does not depend on editor-specific chat hooks
+- it always shows the analysis before any real LLM call
+- it is easy to share with other developers
+
+## Install
+
+### Windows
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts\install.ps1
+```
+
+### macOS / Linux
+
+```bash
+bash scripts/install.sh
+```
+
+## Run
+
+### Windows
+
+```powershell
+powershell -File scripts\run-cli.ps1
+```
+
+### macOS / Linux
+
+```bash
+bash scripts/run-cli.sh
+```
+
+You can also run the command directly:
+
+```bash
+token-guardian
+```
+
+## What the menu does
+
+When the CLI opens, you get a simple menu:
+
+1. revisar prompt
+2. revisar prompt e enviar para LLM
+3. ver metricas
+4. listar modelos suportados
+5. sair
+
+The intended flow is:
+
+1. choose the host profile such as `Claude Code`, `Codex`, or `GitHub Copilot`
+2. choose a suggested model for that profile
+3. paste the prompt and press `Enter`
+4. inspect the markdown analysis
+5. if you are in execution mode, Token Guardian continues to the LLM automatically
+
+In the interactive terminal flow, selections use `espaco` to mark and `Enter` to confirm.
+
+Prompt UX in the current menu:
+
+- the prompt is entered in a single step
+- `Enter` sends the prompt
+- output token estimation is automatic in the interactive flow
+
+## Main commands
+
+The interactive menu is the default, but advanced commands are still available:
+
+```bash
+token-guardian
+token-guardian menu
+token-guardian models
+token-guardian metrics
+token-guardian review --provider anthropic --model claude-sonnet-4 --prompt "Revise esta arquitetura."
+token-guardian run --provider anthropic --model claude-sonnet-4 --prompt "Revise esta arquitetura."
+```
+
+## Real LLM invocation
+
+If you want Token Guardian to call the provider after the analysis step, install the gateway extra:
+
+```bash
+pip install -e .[gateway]
+```
+
+Then use:
+
+```bash
+token-guardian run --provider anthropic --model claude-sonnet-4 --prompt "Revise esta arquitetura."
+```
+
+The `run` flow analyzes first and then calls the LLM directly.
+
+## Metrics and observability
+
+Token Guardian stores local usage data in SQLite.
+
+Tracked data includes:
+
+- total requests
+- total tokens
+- estimated cumulative cost
+- most used models
+- most used providers
+
+Database file:
+
+- `token_guardian.db`
+
+To inspect metrics:
+
+```bash
+token-guardian metrics
+```
+
+## Supported models
+
+See the live list from the CLI:
+
+```bash
+token-guardian models
+```
+
+## Developer commands
+
+Run the full test suite:
+
+```bash
+pytest
+```
+
+## License
+
+MIT

token_guardian-0.1.0b1/README.md

@@ -0,0 +1,197 @@
+# Token Guardian
+
+Token Guardian is a CLI-first preflight guardrail for LLM prompts.
+
+```text
+   _______    _                 _____                     _ _
+  |__   __|  | |               / ____|                   | (_)
+     | | ___ | | _____ _ __   | |  __ _   _  __ _ _ __ __| |_  __ _ _ __
+     | |/ _ \| |/ / _ \ '_ \  | | |_ | | | |/ _` | '__/ _` | |/ _` | '_ \
+     | | (_) |   <  __/ | | | | |__| | |_| | (_| | | | (_| | | (_| | | | |
+     |_|\___/|_|\_\___|_| |_|  \_____|\__,_|\__,_|_|  \__,_|_|\__,_|_| |_|
+
+                            [ shielded prompt preflight ]
+```
+
+Before any real model call, it shows:
+
+- estimated tokens
+- estimated cost
+- context usage
+- context risk
+- prompt reduction hints
+
+Then it shows the analysis before the execution flow continues.
+
+## Preview
+
+Token Guardian opens with an interactive terminal flow that lets developers choose a host profile, select a model, submit a prompt, and inspect the preflight analysis before any real LLM call.
+
+## Release Status
+
+Current release: `0.1.0-beta.1`
+
+This project is ready for early adopters who want to test a prompt guardrail in real workflows. It is not yet positioned as a fully hardened enterprise product.
+
+## What It Is
+
+Token Guardian helps developers inspect a prompt before it reaches an LLM.
+
+It is designed to answer three questions quickly:
+
+- how many tokens this prompt is likely to use
+- how much this prompt may cost
+- whether this prompt is too large, noisy, or risky for the selected model context
+
+## Who It Is For
+
+- developers using LLMs in daily coding workflows
+- teams that want a simple prompt review step before execution
+- open-source users who want a local, cross-platform CLI
+
+## What It Does Not Do
+
+- it does not intercept every editor chat automatically
+- it does not enforce organization-wide policy remotely
+- it does not replace provider-side safety systems
+- it does not depend on MCP or VS Code integration as a product requirement
+
+## Why CLI First
+
+This is the most reliable way to enforce a real preflight gate:
+
+- it works on Windows, macOS, and Linux
+- it does not depend on editor-specific chat hooks
+- it always shows the analysis before any real LLM call
+- it is easy to share with other developers
+
+## Install
+
+### Windows
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts\install.ps1
+```
+
+### macOS / Linux
+
+```bash
+bash scripts/install.sh
+```
+
+## Run
+
+### Windows
+
+```powershell
+powershell -File scripts\run-cli.ps1
+```
+
+### macOS / Linux
+
+```bash
+bash scripts/run-cli.sh
+```
+
+You can also run the command directly:
+
+```bash
+token-guardian
+```
+
+## What the menu does
+
+When the CLI opens, you get a simple menu:
+
+1. revisar prompt
+2. revisar prompt e enviar para LLM
+3. ver metricas
+4. listar modelos suportados
+5. sair
+
+The intended flow is:
+
+1. choose the host profile such as `Claude Code`, `Codex`, or `GitHub Copilot`
+2. choose a suggested model for that profile
+3. paste the prompt and press `Enter`
+4. inspect the markdown analysis
+5. if you are in execution mode, Token Guardian continues to the LLM automatically
+
+In the interactive terminal flow, selections use `espaco` to mark and `Enter` to confirm.
+
+Prompt UX in the current menu:
+
+- the prompt is entered in a single step
+- `Enter` sends the prompt
+- output token estimation is automatic in the interactive flow
+
+## Main commands
+
+The interactive menu is the default, but advanced commands are still available:
+
+```bash
+token-guardian
+token-guardian menu
+token-guardian models
+token-guardian metrics
+token-guardian review --provider anthropic --model claude-sonnet-4 --prompt "Revise esta arquitetura."
+token-guardian run --provider anthropic --model claude-sonnet-4 --prompt "Revise esta arquitetura."
+```
+
+## Real LLM invocation
+
+If you want Token Guardian to call the provider after the analysis step, install the gateway extra:
+
+```bash
+pip install -e .[gateway]
+```
+
+Then use:
+
+```bash
+token-guardian run --provider anthropic --model claude-sonnet-4 --prompt "Revise esta arquitetura."
+```
+
+The `run` flow analyzes first and then calls the LLM directly.
+
+## Metrics and observability
+
+Token Guardian stores local usage data in SQLite.
+
+Tracked data includes:
+
+- total requests
+- total tokens
+- estimated cumulative cost
+- most used models
+- most used providers
+
+Database file:
+
+- `token_guardian.db`
+
+To inspect metrics:
+
+```bash
+token-guardian metrics
+```
+
+## Supported models
+
+See the live list from the CLI:
+
+```bash
+token-guardian models
+```
+
+## Developer commands
+
+Run the full test suite:
+
+```bash
+pytest
+```
+
+## License
+
+MIT

token_guardian-0.1.0b1/app/__init__.py

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