Metadata-Version: 2.4
Name: tokenstretcher
Version: 1.3.3
Summary: Get better results for far less cost. TokenStretcher decomposes complex work, routes tasks intelligently, and enforces hard prepaid budgets so you never blow past limits.
Author: TokenStretcher Contributors
License: Business Source License 1.1
Project-URL: Homepage, https://github.com/ResponsiveDesignLLC/TokenStretcher
Project-URL: Documentation, https://github.com/ResponsiveDesignLLC/TokenStretcher#readme
Project-URL: Repository, https://github.com/ResponsiveDesignLLC/TokenStretcher
Project-URL: Issues, https://github.com/ResponsiveDesignLLC/TokenStretcher/issues
Keywords: ai,llm,agents,token-optimization,cost-saving,orchestration,grok,litellm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Internet :: Proxy Servers
Classifier: Topic :: Office/Business :: Financial :: Point-Of-Sale
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: litellm>=1.40.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: aiofiles>=23.0.0
Requires-Dist: tomli>=2.0.0; python_version < "3.11"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Provides-Extra: proxy
Requires-Dist: fastapi>=0.110.0; extra == "proxy"
Requires-Dist: uvicorn[standard]>=0.29.0; extra == "proxy"
Requires-Dist: python-multipart>=0.0.9; extra == "proxy"
Requires-Dist: resend>=0.8.0; extra == "proxy"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# TokenStretcher

**Higher quality results for far less cost.**

Most people throw entire complex tasks at a powerful model in one giant prompt. This wastes massive context on irrelevant details, produces unfocused output, and makes it easy to blow past budgets.

**TokenStretcher works differently.**

It breaks complex work into focused subtasks, routes each piece to the right model, executes in parallel where it makes sense, and synthesizes a superior final result — while using dramatically fewer tokens overall.

Typical real-world outcome on hard tasks: **30–60% lower cost** with **better, more reliable results** than a single massive prompt.

**Using with a virtual key (tsai_...)?**  
Just run:

```bash
tokenstretcher --key "tsai_YourKeyHere" "your complex task"
```

That's it — the official hosted proxy is used automatically. No extra environment variables or config needed.

---

## Why Giant Prompts Are Wasteful

- 70%+ of the tokens often go to context that doesn't matter for the current part of the work.
- One model is forced to be a jack-of-all-trades.
- Output quality suffers from lack of focus.
- Costs are unpredictable and easy to overrun.

## With TokenStretcher

- **Prepaid only, hard caps** — You preload funds. The system enforces your budget in real time. No surprise bills, ever.
- **Focused work** — Each part of the task gets only the context and expertise it needs.
- **Better results** — Specialists handle what they're good at. You get sharper, more production-grade output.
- **Full visibility** — Every run gives you a clear report so you can see exactly what you got for the cost.

You stay in control. The system stays efficient.

---

## Real Results on Complex Tasks

Here are outcomes from recent production-grade tasks (measured against strong single-prompt baselines using the same underlying models):

**EvalForge** — Complete LLM Evaluation & Prompt Optimization Platform  
- Requirements: evaluation engine with multiple dimensions + caching/routing, prompt optimizer with Pareto analysis, analytics (kappa, cost curves, exports), background jobs, auth/billing integration, FastAPI + HTMX UI, SDK + CLI, Docker, full tests, demo.  
- Result: **52% token reduction**, "excellent" quality rating, clean modular production code delivered across specialized components.

**Personal Finance Dashboard** — Full end-to-end system  
- Requirements: CoinGecko price data, 30/90-day metrics (volatility, Sharpe, correlations, trends), FastAPI + JWT auth, Redis-backed background jobs, interactive HTMX frontend, CSV/PDF export, pytest suite with golden data, Docker Compose, comprehensive README.  
- Result: **9%+ token savings** (significant improvement vs earlier versions), fully working runnable system with real calculations, auth, jobs, and frontend.

On the right tasks (new features, large refactors, multi-domain systems with research + code + tests + infra), teams routinely see **30–60%+ effective cost reduction** while getting more focused, higher-quality deliverables.

---

## Quick Start

### If you have a virtual key (recommended for most users)

```bash
pip install tokenstretcher

# Just use your key — the hosted proxy is used automatically
tokenstretcher --key "tsai_YourKeyHere" "Build a production FastAPI service with JWT auth, user CRUD, and rate limiting"

# Or with JSON (great when called from other AI tools)
tokenstretcher --key "tsai_YourKeyHere" --json "your complex task"
```

No extra environment variables or config needed. The hosted proxy is used automatically for `tsai_` keys.

### Advanced / self-hosted use

```bash
pip install tokenstretcher

tokenstretcher "Build a production FastAPI service with JWT auth, user CRUD, and rate limiting"

tokenstretcher --plan-only "your task here"

tokenstretcher --json "your task here"
```

(Use `--key` + `--base-url` or environment variables if you are connecting to a different proxy.)

If you are operating the proxy server itself for virtual keys, see DEPLOYMENT.md (and the /admin/export-keys endpoint) for Redis + persistent volume recommendations so keys survive restarts.

### Python API

```python
from tokenstretcher import run

result = await run(
    "Create a complete, secure FastAPI authentication system with refresh tokens and roles"
)

print(result.final_output)
print(result.savings.summary())
```

---

## Built for Agentic Tools

TokenStretcher is designed to be called as a tool by other AI coding environments (Grok Build, OpenCode, Cursor, Aider, Continue.dev, etc.).

Every run returns structured results and clear savings data so the calling agent can decide intelligently when decomposition is worth it.

---

## Prepay Model — Zero Surprise Bills

1. Add funds to your wallet.
2. Run tasks.
3. Every call is tracked against your prepaid balance in real time.
4. If balance is too low, it simply stops — no overages.

This is the safest possible way to use powerful models at scale, whether you're a human or an autonomous agent.

---

## Installation

```bash
pip install tokenstretcher
```

---

## Why It Matters

Most AI usage today is extremely wasteful.

TokenStretcher gives you a practical way to get **better work** while using **far fewer tokens** and staying within hard budget limits.

Prepaid. Hard-capped. Focused. Effective.

That’s the entire point.

---

## License

TokenStretcher is released under the Business Source License (BSL 1.1).

Free for individuals and internal use. Commercial resale or hosting as a paid service requires a separate license after the change date.

See the LICENSE file for details.
