tokenshield 0.1.0

LLMコスト最適化SDKラッパー - 1行追加でキャッシュ・ルーティング・コスト追跡

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

pip install tokenshield

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

# 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

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

# 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
• PyPI
• Dashboard Demo

---

Built by TSUNAGU Inc. — Battle-tested on 80 AI agents running 24/7.