Metadata-Version: 2.4
Name: tokenleaf
Version: 0.6.3
Summary: FinOps + GreenOps MCP server — compress LLM prompts losslessly, save money and CO₂.
Author-email: TokenLeaf <hello@tokenleaf.app>
License: TokenLeaf Software License Agreement
        =====================================
        
        Copyright (c) 2026 TokenLeaf. All rights reserved.
        
        This software and its associated documentation (the "Software") are
        proprietary to TokenLeaf. Use of the Software is permitted only under an
        active TokenLeaf subscription and is governed by the Terms of Service at
        https://tokenleaf.app/terms.
        
        GRANT OF LICENSE
        ----------------
        
        Subject to the terms below, TokenLeaf grants you a non-exclusive,
        non-transferable, revocable license to install and use the Software on
        machines under your control, solely for your own internal use, for the
        duration of an active subscription tied to a valid TokenLeaf activation
        key.
        
        RESTRICTIONS
        ------------
        
        You may NOT, except as expressly permitted in writing by TokenLeaf:
        
          1. Distribute, sublicense, sell, rent, lease, or transfer the Software
             to any third party.
          2. Modify, reverse engineer, decompile, or disassemble the Software,
             except to the extent that applicable law expressly permits such
             activity despite this restriction.
          3. Remove or alter any copyright, trademark, or attribution notices.
          4. Use the Software to develop a competing product or service.
          5. Bypass, disable, or interfere with any license-validation mechanism.
        
        NO WARRANTY
        -----------
        
        THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. IN NO EVENT SHALL
        THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR
        OTHER LIABILITY ARISING FROM USE OF THE SOFTWARE.
        
        TERMINATION
        -----------
        
        This license terminates automatically upon expiry, cancellation, or
        revocation of your TokenLeaf subscription, or upon any breach of these
        terms. Upon termination you must stop using the Software and remove it
        from all systems under your control.
        
        CONTACT
        -------
        
        Questions about this license: legal@tokenleaf.app
        
Project-URL: Homepage, https://tokenleaf.app
Project-URL: Documentation, https://tokenleaf.app/docs
Project-URL: Issues, https://github.com/tokenleaf/tokenleaf/issues
Project-URL: Source, https://github.com/tokenleaf/tokenleaf
Keywords: mcp,model-context-protocol,llm,finops,greenops,claude,cursor,prompt-compression,tiktoken,sustainability
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: tiktoken>=0.8.0
Requires-Dist: pydantic>=2.9.0
Requires-Dist: pydantic-settings>=2.6.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: cryptography>=43.0.0
Requires-Dist: sqlalchemy>=2.0.30
Requires-Dist: platformdirs>=4.3.0
Requires-Dist: markitdown[all]>=0.0.1a3
Requires-Dist: pypdf>=4.0.0
Requires-Dist: starlette>=0.40.0
Requires-Dist: uvicorn>=0.30.0
Provides-Extra: dev
Requires-Dist: pytest>=8.3.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: twine>=5.1.0; extra == "dev"
Dynamic: license-file

# TokenLeaf

**FinOps + GreenOps for LLM users.** Compress your prompts losslessly before
they hit the LLM, save money and reduce CO₂ emissions — without changing the
meaning of what you ask.

Typical savings on debugging prompts with duplicated code, JSON dumps, or
repetitive logs: **25–45 %**. Savings on short conversational messages: ~0 %.
What you save depends entirely on what you paste.

---

## The four pillars

TokenLeaf is more than a single MCP tool. It's four cooperating pieces:

1. **`analyze_and_compress_prompt`** — seven lossless strategies (stack-trace
   collapse, code-block dedup, JSON minify, HTML/XML, Markdown tables, log
   collapse, whitespace) applied in a safe order.
2. **`preprocess_document` / `preprocess_directory`** — turn PDFs, DOCX,
   PPTX, XLSX, EPUB, HTML, RTF into compressed markdown before they're
   uploaded into a prompt. PDF savings are routinely 70–90 % vs. multimodal
   page-tokenization.
3. **Output governor** — `calculate_esg_impact` + a policy injector that
   nudges the LLM toward terser responses on simple questions.
4. **Transparent proxy** — `tokenleaf proxy` runs an Anthropic-API-compatible
   server on localhost that compresses every outgoing `role=user` message
   before forwarding to `api.anthropic.com`. Works with Cursor and any SDK
   that respects `ANTHROPIC_BASE_URL`.

Code blocks (` ``` ` and inline backticks) are **never** modified beyond
whitespace cleanup. The compressed prompt is always semantically equivalent
to the original for the LLM.

---

## Install

```bash
pip install tokenleaf
tokenleaf init
```

`tokenleaf init` walks you through:

1. Saving your activation key (purchased at https://tokenleaf.app)
2. Validating it against the TokenLeaf backend
3. Detecting installed MCP hosts (Claude Desktop, Cursor)
4. Wiring TokenLeaf into each host's config (with backup + diff confirmation)

Restart your MCP host and you're done.

---

## How it integrates with each host

TokenLeaf intercepts in two complementary ways. Different hosts get different
paths:

| Host / Tool | How TokenLeaf intercepts | Reliability |
|---|---|---|
| **Claude Desktop** | MCP tool invocation via `LEAF_INSTRUCTIONS.md` in your Claude profile | ~95 % on long prompts |
| **Cursor** | MCP tools **and** transparent proxy via `ANTHROPIC_BASE_URL` | 100 % via proxy |
| **Anthropic SDK / scripts** | Transparent proxy via `ANTHROPIC_BASE_URL` | 100 % |
| **Claude Code** | MCP tools (proxy planned for v0.7) | ~95 % |

### Soft transparency on Claude Desktop

Paste the contents of [`LEAF_INSTRUCTIONS.md`](./LEAF_INSTRUCTIONS.md) into
your Claude **Personal preferences** or a project's **Custom instructions**.
Claude will then invoke `analyze_and_compress_prompt` and `preprocess_document`
on its own whenever the routine matches. No manual `"compress this first"`
needed.

### True transparency on Cursor / SDK

```bash
tokenleaf proxy --port 8788
# Then in another terminal:
export ANTHROPIC_BASE_URL=http://localhost:8788
cursor .
```

Every outgoing user message is compressed before it reaches Anthropic. System
prompts and assistant turns are passed through unchanged.

---

## Usage

In Claude Desktop or Cursor, just paste a long debugging prompt or upload a
document. With `LEAF_INSTRUCTIONS.md` installed, you'll see a one-line note
at the bottom of Claude's reply:

> *LEAF saved 8,432 → 4,891 tokens (42.0 % · $0.0106 · 1.42 g CO₂). Deduplicé
> 2 bloques de código idénticos; minimicé 1 bloque HTML/XML.*

Inspect your cumulative savings any time:

```bash
tokenleaf summary
tokenleaf dashboard      # opens leaf-dashboard.html in your browser
```

---

## CLI

```
tokenleaf init          # interactive first-time setup
tokenleaf doctor        # diagnose license, hosts, ledger
tokenleaf serve         # run the MCP server (stdio)
tokenleaf install       # add TokenLeaf to all detected hosts
tokenleaf uninstall     # remove TokenLeaf from a host's config
tokenleaf summary       # cumulative savings ledger as JSON
tokenleaf dashboard     # open the local savings dashboard
tokenleaf proxy         # run the transparent Anthropic-API proxy
tokenleaf convert       # convert a document/folder to compressed markdown
tokenleaf handshake     # force a fresh license handshake
tokenleaf config        # print resolved settings (secrets masked)
```

---

## Privacy

- **Prompt content never leaves your machine.** All compression and document
  conversion happen locally.
- **The local ledger stores only sizes, costs, and SHA-256 hashes** — never
  prompt text.
- **The license-validation handshake sends only your activation key and a
  stable machine fingerprint.** No prompt data is transmitted.
- **The optional heartbeat** (fired once per UTC day per machine, only when
  `TOKENLEAF_LICENSE_KEY` is set) carries only your `license_id`, machine
  fingerprint, timestamp, and lifetime aggregate totals. **No per-event
  detail, no domain breakdown, no prompt content.** The exact request body
  is built by `src/tokenleaf/telemetry/heartbeat.py` and a privacy-canary
  test in `tests/test_telemetry.py` fails CI if any prompt-content-shaped
  field name appears.
- **Personal-use mode** (no license key + `TOKENLEAF_ALLOW_OFFLINE=true`,
  the default) makes zero network calls. You can use the full feature set
  offline; only paid tier requires a key.

---

## Requirements

- Python ≥ 3.11
- An MCP-compatible host (Claude Desktop, Cursor, Claude Code, or any client
  supporting MCP)
- A TokenLeaf subscription — start at https://tokenleaf.app

---

## License

Proprietary. See the `LICENSE` file. Use requires an active subscription.
