Metadata-Version: 2.4
Name: token-guardian
Version: 0.1.2
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

## Preview

<p align="center">
  <img src="https://raw.githubusercontent.com/LeonardoCesca/token-guardian/master/docs/images/token-guardian-analyze.svg" alt="Token Guardian CLI analyze output" width="1100">
</p>

The current CLI interface is optimized for interactive terminal use and the guided experience is presented in pt-BR.

## 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
pip install token-guardian
token-guardian
```

### macOS / Linux

```bash
pip install token-guardian
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 is rendered as a terminal report with token estimate, cost, context usage, risk, and prompt guidance.

## 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
