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
