Metadata-Version: 2.4
Name: tokenshield
Version: 0.1.0
Summary: LLMコスト最適化SDKラッパー - 1行追加でキャッシュ・ルーティング・コスト追跡
Author-email: "TSUNAGU Inc." <dev@tsunagu.co.jp>
License: MIT
Project-URL: Homepage, https://github.com/ShoyoAoki/tokenshield
Project-URL: Repository, https://github.com/ShoyoAoki/tokenshield
Keywords: llm,cost-optimization,anthropic,openai,deepseek
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20.0; extra == "anthropic"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: all
Requires-Dist: anthropic>=0.20.0; extra == "all"
Requires-Dist: openai>=1.0.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: anthropic>=0.20.0; extra == "dev"
Requires-Dist: openai>=1.0.0; extra == "dev"

# TokenShield

**Cut your LLM API costs by up to 93%. One line of code. Zero quality loss.**

TokenShield is a Python SDK wrapper that sits between your code and LLM providers (Anthropic, OpenAI, etc.), automatically optimizing every API call through intelligent caching and routing.

---

## Quick Start

```bash
pip install tokenshield
```

```python
import anthropic
from tokenshield import shield

# Wrap your client — that's it
client = shield(anthropic.Anthropic())

# Use it exactly as before
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, world!"}],
)
```

**Your existing code stays the same.** TokenShield optimizes behind the scenes.

---

## How It Works

```
Your Code
  │
  ▼
┌─────────────────────────┐
│      TokenShield        │
│                         │
│  1. Cache Check         │  ← Same query? Return instantly ($0)
│  2. Smart Routing       │  ← Simple task? Route to DeepSeek (10x cheaper)
│  3. Cost Tracking       │  ← Dashboard shows exactly how much you saved
│                         │
└─────────────────────────┘
  │
  ▼
Claude / GPT / DeepSeek
```

### What gets optimized:

| Optimization | How | Savings |
|---|---|---|
| **Cache** | Identical queries return cached responses | 100% per hit |
| **Smart Routing** | Simple tasks (translation, summarization) → DeepSeek V3 | ~93% |
| **Cost Tracking** | See exactly where your money goes | Awareness |

### What stays the same:

- Your code (1 line change only)
- API response format (100% compatible)
- Quality for complex tasks (routed to original model)

---

## Works With Every Provider

```python
# Anthropic (Claude)
from tokenshield import shield
client = shield(anthropic.Anthropic())

# OpenAI (GPT-4o)
client = shield(openai.OpenAI())

# Groq
client = shield(openai.OpenAI(base_url="https://api.groq.com/openai/v1", api_key="..."))

# Any OpenAI-compatible API
client = shield(openai.OpenAI(base_url="https://...", api_key="..."))
```

---

## Configuration

```python
from tokenshield import shield, ShieldConfig

client = shield(anthropic.Anthropic(), config=ShieldConfig(
    # Routing
    enable_routing=True,
    deepseek_api_key="sk-xxx",      # Enable DeepSeek routing (optional)
    routing_threshold=0.5,           # 0 = route everything, 1 = route nothing

    # Cache
    enable_cache=True,
    cache_ttl=300,                   # Cache lifetime in seconds

    # Tracking
    enable_tracking=True,
    tracking_dir="~/.tokenshield",   # Where to store usage data
))
```

### Without DeepSeek key

TokenShield works without a DeepSeek API key — you still get caching benefits. Add a DeepSeek key to unlock routing savings.

---

## Dashboard

```bash
# CLI dashboard
python -m tokenshield.dashboard

# Web dashboard (Streamlit)
python -m tokenshield.dashboard --web
```

```
╔══════════════════════════════════════════════╗
║         TokenShield  Savings Report          ║
╚══════════════════════════════════════════════╝

  Total Savings:    $127.50 (85.6%)
  Requests:         12,340
  Cache Hit Rate:   23.4%
  DeepSeek Routed:  52.1%
```

---

## Benchmarks

Tested on 10 real business tasks (translation, code generation, analysis, strategy):

| Metric | Without Shield | With Shield |
|---|---|---|
| Cost | $0.098 | $0.054 |
| Quality | 8.3/10 | 8.0/10 |
| Savings | — | **45%** |

DeepSeek V3 vs Claude Sonnet quality test (9 tasks):

| Metric | Result |
|---|---|
| Success Rate | 9/9 (100%) |
| Cost Reduction | **93%** |
| Quality | Equivalent |

---

## Routing Logic

TokenShield routes based on task complexity:

| Complexity | Signals | Routed to |
|---|---|---|
| **Simple** | Translation, summarization, templates | DeepSeek V3 |
| **Medium** | Analysis, code generation | DeepSeek V3 |
| **Complex** | Strategy, multi-step reasoning, tool use | Original model |

Tool use (`tools=` parameter) always stays on the original model for reliability.

---

## How Routing Decides

The router uses lightweight heuristics (no API call needed):

- **Keywords**: "translate" / "summarize" → simple
- **Tool use**: Any tools defined → keep original
- **System prompt length**: Long system prompts → keep original
- **Message complexity**: Short, single-turn → simple

No LLM is called to make routing decisions. Zero overhead.

---

## Privacy & Security

- **No data leaves your environment** — TokenShield runs locally in your Python process
- **No external servers** — Cache is in-memory or local Redis
- **No telemetry** — Usage data stays in `~/.tokenshield/`
- **DeepSeek routing is optional** — Disable with `enable_routing=False`

---

## Requirements

- Python 3.9+
- `anthropic` and/or `openai` SDK
- No other dependencies

---

## License

MIT

---

## Links

- [GitHub](https://github.com/tsunagu-inc/tokenshield)
- [PyPI](https://pypi.org/project/tokenshield/)
- [Dashboard Demo](https://tokenshield.dev)

---

Built by [TSUNAGU Inc.](https://tsunagu.co.jp) — Battle-tested on 80 AI agents running 24/7.
