# ContextSlim Python SDK

> **High-performance M2M context middleware and x402 micropayment engine for Python AI Agents and MCP tools on Base.**

ContextSlim prunes massive JSON payloads by up to **75%+**, enforces strict token budgets, and handles autonomous HTTP 402 EIP-712 micropayments—keeping Python AI agents (LangChain, CrewAI, AutoGen, LlamaIndex) fast, cost-effective, and deterministically within LLM context limits.

---

## Proven E2E Benchmarks

Real-world test suite performance measured over live execution on Cloudflare KV + Base Sepolia:

| MCP Tool / Operation | Input Payload | Output Payload | Reduction / Impact | Performance Metric |
| --- | --- | --- | --- | --- |
| **`optimize_context`** | 542 Tokens | **136 Tokens** | **74.8% Token Saved** | 406 Tokens saved in initial pruning |
| **`fetch_result` (Targeted Path)** | 542 Tokens | **23 Tokens** | **95.7% Savings** | Surgical extraction via JSONPath |
| **Session Pass (2nd Query)** | On-chain Auth | Cache Auth | **70% Latency Drop** | **0.43s $\rightarrow$ 0.13s** execution speed |

---

## Architecture & Protocol Flow

ContextSlim seamlessly sits between your Python AI Agent framework, the Model Context Protocol (MCP), and the Base blockchain:

```
+-------------------+       1. MCP Tool Call       +------------------------+
|  AI Agent / LLM   | ---------------------------> |  contextslim           |
| (CrewAI/LangChain)| <--------------------------- |  (Python SDK Engine)   |
+-------------------+     4. Pruned Payload        +------------------------+
                                                               |        ^
                                             2. x402 Payment   |        | 3. Optimized Data
                                                Challenge/Pass |        |    & Reference ID
                                                               v        |
                                                   +--------------------------------+
                                                   | ContextSlim Worker Engine      |
                                                   | (Cloudflare KV + Pruner Engine)|
                                                   +--------------------------------+
                                                                   |
                                                                   v (On-Chain Settlement)
                                                   +--------------------------------+
                                                   | Base Network (USDC / ERC-3009) |
                                                   +--------------------------------+
```

---

## Installation

Install the lightweight native package from PyPI:

```bash
pip install contextslim eth-account python-dotenv
```

---

## MCP Client Configurations

### 1. Claude Desktop Integration

Add the following configuration to your `claude_desktop_config.json` file:

```json
{
  "mcpServers": {
    "contextslim": {
      "command": "uvx",
      "args": ["contextslim"],
      "env": {
        "ENDPOINT_URL": "https://contextslim.friczero.com",
        "PRIVATE_KEY": "0x_YOUR_AGENT_PRIVATE_KEY"
      }
    }
  }
}
```

### 2. Cursor IDE (`.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "contextslim": {
      "url": "https://contextslim.friczero.com/message"
    }
  }
}
```

### 3. Smithery CLI

One-click installation via Smithery:

```bash
npx -y @smithery/cli install contextslim --client claude
```

---

## 30-Second Quickstart

This script initializes the client with an active **Session Pass** ($0.005 USDC), prunes a massive JSON payload, and retrieves specific fields with ultra-low latency:

```python
import os
from dotenv import load_dotenv
from eth_account import Account
from contextslim import ContextSlimClient

load_dotenv()

def main():
    # 1. Initialize Local Signer (Private key isolated in memory)
    signer = Account.from_key(os.getenv("PRIVATE_KEY"))

    # 2. Instantiate ContextSlim Client
    client = ContextSlimClient(
        endpoint=os.getenv("ENDPOINT_URL", "https://contextslim.friczero.com"),
        signer=signer,
        allowance_budget=0.005,  # Optional: Enables Session Pass to avoid signing every query
        max_token_budget=1000,
    )

    # 3. Prune Massive Payload (optimize_context)
    heavy_payload = {
        "company": "Acme Corp International",
        "key_team": [
            {"name": "Alice Gomez", "role": "CTO"},
            {"name": "Carlos M.", "role": "CEO"},
        ],
        "historical_logs": [f"Log entry #{i + 1}: Activity sweep" for i in range(100)],
    }

    print("Optimizing massive context...")
    prep = client.call_tool("optimize_context", {
      "data": heavy_payload,
      "maxTokenBudget": 150
    })

    res = prep.get("result", {})
    ref_id = res.get("toolResultReference", {}).get("referenceId") or res.get("referenceId")
    
    print(f"Reference Cached in KV: {ref_id}")
    print(f"Saved Tokens: {prep.get('metrics', {}).get('savedTokens')}")
    print(f"Compression Ratio: {prep.get('metrics', {}).get('reductionPercentage')}")

    # 4. Targeted Path Extraction (fetch_result)
    print("Retrieving only 'key_team[0].name'...")
    extracted = client.call_tool("fetch_result", {
      "referenceId": ref_id,
      "paths": ["company", "key_team[0].name"]
    })

    print("Result:", extracted.get("result"))
    # Returns only 23 tokens: {"company": "Acme Corp International", "key_team": [{"name": "Alice Gomez"}]}

if __name__ == "__main__":
    main()
```

---

## Advanced Signer Setup (Production & Enterprise)

While passing a raw `eth_account.LocalAccount` initialized from an environment variable works for local testing, production AI agents should avoid storing plain-text private keys in `.env` files.

`ContextSlimClient` accepts any compatible signing interface (wrapping EIP-712 / ERC-3009 signatures), allowing seamless integration with Cloud Key Management Services (KMS), Hardware Security Modules (HSMs), and Vaults:

### 1. AWS KMS / HashiCorp Vault Integration

Keep keys non-exportable inside dedicated cloud HSMs using a custom signer wrapper:

```python
from contextslim import ContextSlimClient
from my_kms_signer import AWSKMSSigner  # Custom wrapper around boto3 KMS sign_digest

kms_signer = AWSKMSSigner(key_id="arn:aws:kms:us-east-1:123456789012:key/your-agent-key-id")

client = ContextSlimClient(
    endpoint="https://contextslim.friczero.com",
    signer=kms_signer,
)
```

### 2. Turnkey / Web3.py Signers

Isolate credentials for serverless agents or multi-tenant agent architectures:

```python
from contextslim import ContextSlimClient
from turnkey import TurnkeyAccount

turnkey_signer = TurnkeyAccount(
    organization_id=os.getenv("TURNKEY_ORGANIZATION_ID"),
    wallet_address=os.getenv("TURNKEY_WALLET_ADDRESS"),
)

client = ContextSlimClient(
    endpoint="https://contextslim.friczero.com",
    signer=turnkey_signer,
)
```

---

## API Reference

### `ContextSlimClient(endpoint, signer, allowance_budget, max_token_budget)`

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `endpoint` | `str` | **Required** | Base URL of the ContextSlim Worker (`https://contextslim.friczero.com`). |
| `signer` | `LocalAccount` | **Required** | `eth_account` LocalAccount or KMS Signer for ERC-3009/EIP-712 payment authorizations. |
| `allowance_budget` | `float` | `0.0` | USDC budget to pre-approve a Session Pass (base price: **$0.001 USDC/call**; on-chain settlement triggers at **$0.005 USDC**). |
| `max_token_budget` | `int` | `1000` | Default response token limit. |

---

### Client Methods

#### `client.call_tool(name, args)`

Unified tool invocation method compatible with MCP JSON-RPC.

##### 1. `optimize_context` Tool

Reduces complex JSON structures while preserving critical fields and inserting truncated reference markers (`_slim`).

* **Parameters (`args` dict):**
  * `data` (`dict`, required) - Full JSON payload to optimize.
  * `maxTokenBudget` (`int`, optional) - Hard token limit for the response payload.

* **Response:**

```python
{
    "status": "success",
    "result": {
        "toolResultReference": {"referenceId": "ref_ef17a253", "expiresIn": "3600s"},
        # ... pruned payload
    },
    "metrics": {
        "savedTokens": "406",
        "reductionPercentage": "74.8%",
        "strategy": "recursive:arrays(47_items)",
    },
}
```

##### 2. `fetch_result` Tool

Retrieves exact data subsets from a cached reference ID.

* **Parameters (`args` dict):**
  * `referenceId` (`str`, required) - ID returned by `optimize_context`.
  * `paths` (`list[str]`, optional) - Dot-notation field paths to extract (e.g., `["company", "key_team[0].name"]`).

* **Response:**

```python
{
    "status": "success",
    "referenceId": "ref_ef17a253",
    "retrievedTokens": 23,
    "result": {
        "company": "Acme Corp International",
        "key_team": [{"name": "Alice Gomez"}],
    },
}
```

---

## Security & Resilience

* **Cryptographic Isolation:** EIP-712 / ERC-3009 x402 payment challenge signing happens strictly in local process memory via `eth-account` or your cloud KMS. No private keys or seed phrases ever leave your client environment.
* **Anti-Replay Protection:** Every payment challenge issued by the HTTP 402 server includes time-bound single-use nonces. Reusing `X-PAYMENT` headers is strictly rejected.
* **Session Pass Mechanism:** Setting an `allowance_budget` issues an encrypted session pass, amortizing on-chain verification and speeding up subsequent KV fetches to an average execution speed of **0.13 seconds**.

---

## License

This project is licensed under the [MIT License](LICENSE).