ContextShrink

Zero-dependency, AST-aware LLM prompt context compression engine for code, text, and RAG payloads.

contextshrink is an open-source Python engine designed to compress LLM prompt contexts (Code + Text + RAG) by 20%–60% using Abstract Syntax Tree (AST) parsing, deterministic lexical pruning, and sliding-window deduplication.

Built for air-gapped corporate environments with zero external network egress requirements and strict enterprise security constraints.

---

Key Features

• Zero External Egress: 100% in-memory processing. No network calls, socket connections, or external telemetry logging.
• AST-Aware Code Compression: Strips function/method body implementations while preserving class hierarchies, signatures, type annotations, and docstrings.
• Entity & PII Preservation: Automatic protection of API keys (AWS, OpenAI, GitHub), JWTs, IP addresses, private keys, and high-entropy strings during lexical pruning.
• Sliding-Window RAG Deduplication: Removes line-level and near-duplicate text blocks across retrieval chunks using deterministic rolling string hashes.
• Zero External Runtime Dependencies: Standard Python library (ast, re, dataclasses, hashlib, math, typing).

---

Installation

pip install contextshrink

Or install with dev dependencies for running tests:

pip install -e ".[dev]"

---

Quick Start

from contextshrink import ContextCompressor, ShrinkConfig

# Initialize compressor with default configuration
compressor = ContextCompressor()

# Compress Python source code
code_sample = """
def calculate_metrics(data: list[float]) -> dict[str, float]:
    '''Calculate descriptive statistics for input data.'''
    if not data:
        return {"mean": 0.0, "sum": 0.0}
    total = sum(data)
    mean = total / len(data)
    return {"mean": mean, "sum": total}
"""

result = compressor.compress_code(code_sample)
print(result.compressed)
print(f"Tokens saved: {result.metrics.tokens_saved} ({result.metrics.compression_ratio:.1f}%)")

---

🎨 Interactive Live Web UI Demo

An interactive, zero-egress Web UI dashboard is included inside web/ to demonstrate AST code compression, lexical text pruning, RAG deduplication, and PII/secret locking in real-time.

To launch the live interactive UI demo:

# Launch local zero-egress web server
python -m http.server 8080 --directory web

Then open your web browser at: http://localhost:8080

---

📊 Benchmark & Financial ROI Performance

contextshrink includes an in-memory benchmark runner to measure compression ratios, sub-millisecond execution latency, and dollar savings across leading LLM providers.

To run the benchmark suite on your machine:

python -m contextshrink.cli benchmark

Benchmark Summary Results

• Overall Token Reduction: 46.98%
• Average Processing Latency: 0.511 ms per request (In-memory CPU)

Scenario Breakdown

Scenario Name	Mode	Original Tokens	Compressed Tokens	Tokens Saved	Reduction %	Processing Latency
Enterprise Payment API Class	code	292	143	149	51.03%	1.11 ms
Corporate System Prompt	text	82	49	33	40.24%	0.32 ms
RAG Document Vector Retrieval	rag	56	36	20	35.71%	0.09 ms

Financial Cost Savings (per 1 Million API Calls)

LLM Model Provider	Input Pricing (per 1M tokens)	Estimated Cost Saved / 1M Calls
Claude 3.5 Sonnet (Anthropic)	$3.00	$606.00
GPT-4o (OpenAI)	$2.50	$505.00
Gemini 1.5 Pro (Google)	$1.25	$252.50
DeepSeek-V3	$0.27	$54.54

---

Architecture Overview

contextshrink/
├── core/             # Immutable configuration, exceptions, security scanner & metrics
├── modules/
│   ├── ast_code/     # Python AST transformer & body stripper
│   ├── text_lexical/ # Rule-based lexical pruner & entity preservation
│   └── rag_dedup/    # Sliding-window hash deduplicator
└── integrations/     # LiteLLM & LangChain middleware adapters

---

Security & Compliance

1. Air-gapped & In-Memory: No network sockets, HTTP requests, or external service calls.
2. Safe Code Parsing: Standard static analysis (ast module) exclusively. No eval(), exec(), or dynamic code evaluation primitives.
3. Resource Bounded: Max input payload limit (10MB) and maximum AST depth limit (100 levels) to prevent DoS attacks.
4. Secret Protection: Automated regex pattern matching for secrets and high-entropy strings ensures PII/PHI is never stripped or mutated.

---

License

MIT License. See LICENSE for details.