Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
Slim core dependencies: 2.5GB → 195MB install size
chopratejas18118af5cec9
diff --git a/headroom/__init__.py b/headroom/__init__.pyindex 6ff530353..2d1b8c264 100644--- a/headroom/__init__.py+++ b/headroom/__init__.py@@ -113,16 +113,27 @@ from .exceptions import (ValidationError,)-# Memory module - hierarchical memory system-from .memory import (- EmbedderBackend,- HierarchicalMemory,- Memory,- MemoryConfig,- ScopeLevel,- with_memory,-)+# Memory module - optional (requires numpy, hnswlib, etc.)+try:+ from .memory import (+ EmbedderBackend,+ HierarchicalMemory,+ Memory,+ MemoryConfig,+ ScopeLevel,+ with_memory,+ )+except ImportError:+ EmbedderBackend = None # type: ignore[assignment,misc]+ HierarchicalMemory = None # type: ignore[assignment,misc]+ Memory = None # type: ignore[assignment,misc]+ MemoryConfig = None # type: ignore[assignment,misc]+ ScopeLevel = None # type: ignore[assignment,misc]+ with_memory = None # type: ignore[assignment]+from .providers import AnthropicProvider, OpenAIProvider, Provider, TokenCounter++# Relevance scoring - BM25 always available, embedding requires sentence-transformersfrom .relevance import (BM25Scorer,EmbeddingScorer,diff --git a/headroom/cli/main.py b/headroom/cli/main.pyindex 753c6bf13..acc84ca97 100644--- a/headroom/cli/main.py+++ b/headroom/cli/main.py@@ -37,12 +37,17 @@ def _register_commands() -> None:evals, # noqa: F401learn, # noqa: F401mcp, # noqa: F401- memory, # noqa: F401perf, # noqa: F401proxy, # noqa: F401wrap, # noqa: F401)+ # Memory CLI requires numpy/hnswlib — optional+ try:+ from . import memory # noqa: F401+ except ImportError:+ pass+_register_commands()diff --git a/headroom/image/trained_router.py b/headroom/image/trained_router.pyindex 8d068cfa6..c91f1dc81 100644--- a/headroom/image/trained_router.py+++ b/headroom/image/trained_router.py@@ -16,9 +16,14 @@ from enum import Enumfrom pathlib import Pathfrom typing import Any-import torch-from PIL import Image-from transformers.modeling_outputs import BaseModelOutputWithPooling+try:+ import torch+ from PIL import Image+ from transformers.modeling_outputs import BaseModelOutputWithPooling++ _IMAGE_ML_AVAILABLE = True+except ImportError:+ _IMAGE_ML_AVAILABLE = Falsefrom headroom.models.config import ML_MODEL_DEFAULTSdiff --git a/headroom/memory/models.py b/headroom/memory/models.pyindex 163b2ef54..6e1293c34 100644--- a/headroom/memory/models.py+++ b/headroom/memory/models.py@@ -8,7 +8,10 @@ from datetime import datetimefrom enum import Enumfrom typing import Any-import numpy as np+try:+ import numpy as np+except ImportError:+ np = None # type: ignore[assignment]class ScopeLevel(Enum):@@ -56,7 +59,7 @@ class Memory:entity_refs: list[str] = field(default_factory=list)# Embedding (for vector search)- embedding: np.ndarray | None = None+ embedding: Any = None # np.ndarray when numpy is available# Metadatametadata: dict[str, Any] = field(default_factory=dict)@@ -105,7 +108,7 @@ class Memory:def from_dict(cls, data: dict[str, Any]) -> Memory:"""Create from dictionary."""embedding = None- if data.get("embedding"):+ if data.get("embedding") and np is not None:embedding = np.array(data["embedding"], dtype=np.float32)return cls(diff --git a/headroom/pricing/litellm_pricing.py b/headroom/pricing/litellm_pricing.pyindex 3314a9a0e..764adec6a 100644--- a/headroom/pricing/litellm_pricing.py+++ b/headroom/pricing/litellm_pricing.py@@ -11,7 +11,13 @@ from __future__ import annotationsfrom dataclasses import dataclassfrom typing import Any-import litellm+try:+ import litellm++ LITELLM_AVAILABLE = True+except ImportError:+ litellm = None # type: ignore[assignment]+ LITELLM_AVAILABLE = False# Aliases for models removed from LiteLLM's cost database (retired/renamed).# Maps old model name -> current LiteLLM key that has equivalent pricing.@@ -46,7 +52,10 @@ def get_litellm_model_cost() -> dict[str, Any]:Returns:Dictionary mapping model names to their pricing/capability info.+ Empty dict if litellm is not installed."""+ if not LITELLM_AVAILABLE:+ return {}return litellm.model_cost # type: ignore[no-any-return]@@ -57,8 +66,10 @@ def get_model_pricing(model: str) -> LiteLLMModelPricing | None:model: Model name (e.g., 'gpt-4o', 'claude-3-5-sonnet-20241022').Returns:- LiteLLMModelPricing if found, None otherwise.+ LiteLLMModelPricing if found, None if not found or litellm not installed."""+ if not LITELLM_AVAILABLE:+ return Nonecost_data = litellm.model_cost# Try exact match first@@ -124,6 +135,8 @@ def list_available_models() -> list[str]:"""List all models with pricing info in LiteLLM's database.Returns:- List of model names.+ List of model names. Empty list if litellm not installed."""+ if not LITELLM_AVAILABLE:+ return []return list(litellm.model_cost.keys())diff --git a/pyproject.toml b/pyproject.tomlindex 0b9023db5..20695fe61 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -44,52 +44,65 @@ classifiers = ["Typing :: Typed",]dependencies = [- "tiktoken>=0.5.0",- "pydantic>=2.0.0",- "openai>=2.14.0",- "sentence-transformers>=5.2.0",- "litellm>=1.0.0",- "accelerate>=1.12.0",- "sentencepiece>=0.2.1",- "protobuf>=6.33.4",- "semantic-router>=0.1.12",- "pillow>=10.0.0", # Image processing for compression- "datasets>=4.5.0",- "hnswlib>=0.8.0", # HNSW vector index for memory system+ # Core: lightweight compression (SmartCrusher, ContentRouter, CCR, TOIN)+ "tiktoken>=0.5.0", # Tokenizer for all compressors+ "pydantic>=2.0.0", # Config and data models+ "litellm>=1.0.0", # Model registry, pricing, and provider support"click>=8.1.0", # CLI framework"rich>=13.0.0", # Rich terminal output][project.optional-dependencies]-# Semantic relevance scoring with embeddings-relevance = [- "sentence-transformers>=2.2.0",- "numpy>=1.24.0",-]-# Proxy server+# Proxy server (most common install: pip install headroom-ai[proxy])proxy = ["fastapi>=0.100.0","uvicorn>=0.23.0",- "httpx[http2]>=0.24.0", # http2 extra enables h2 for HTTP/2 support+ "httpx[http2]>=0.24.0",+ "openai>=2.14.0", # OpenAI API format support]-# Report generation-reports = [- "jinja2>=3.0.0",+# AST-based code compression (tree-sitter)+code = [+ "tree-sitter-language-pack>=0.10.0",]-# ML-based compression (LLMLingua-2 — fallback if Kompress fails)+# ML-based compression with Kompress (ModernBERT)+ml = [+ "torch>=2.0.0",+ "transformers>=4.30.0",+]+# Legacy ML compression (LLMLingua-2 — use [ml] instead for Kompress)llmlingua = ["llmlingua>=0.2.0","torch>=2.0.0","transformers>=4.30.0",]-# AST-based code compression (tree-sitter)-code = [- "tree-sitter-language-pack>=0.10.0",+# Memory system (hierarchical memory with vector search)+memory = [+ "hnswlib>=0.8.0",+ "sqlite-vec>=0.1.6",+ "sentence-transformers>=2.2.0",+]+# Semantic relevance scoring with embeddings+relevance = [+ "sentence-transformers>=2.2.0",+ "numpy>=1.24.0",+]+# Image compression (ML-based routing)+image = [+ "pillow>=10.0.0",+]+# Report generation+reports = [+ "jinja2>=3.0.0",]# any-llm multi-provider backend (requires Python 3.11+)anyllm = ["any-llm-sdk>=1.0.0",]+# LangChain integration+langchain = [+ "langchain-core>=0.2.0",+ "langchain-openai>=0.1.0",+]# Agno agent framework integrationagno = ["agno>=1.0.0",@@ -98,46 +111,41 @@ agno = [strands = ["strands-agents>=0.1.0",]-# MCP server for Claude Code integration (CCR without API access)+# MCP server for Claude Code integrationmcp = ["mcp>=1.0.0","httpx>=0.24.0",]-# Voice filler detection (training and inference)+# Voice filler detectionvoice = [- "onnxruntime>=1.16.0", # Fast CPU inference- "transformers>=4.30.0", # Model loading and tokenization- "torch>=2.0.0", # Training+ "onnxruntime>=1.16.0",+ "transformers>=4.30.0",+ "torch>=2.0.0",]-# Voice training only (includes voice deps + training extras)+# Voice training (includes voice deps + training extras)voice-train = ["headroom-ai[voice]",- "datasets>=2.14.0", # Data loading- "accelerate>=0.20.0", # Training acceleration+ "datasets>=2.14.0",+ "accelerate>=0.20.0",]-# Evaluation framework for testing compression accuracy+# Evaluation frameworkevals = [- "datasets>=2.14.0", # HuggingFace datasets- "sentence-transformers>=2.2.0", # Semantic similarity- "numpy>=1.24.0", # Numerical operations- "scikit-learn>=1.3.0", # ML metrics- "anthropic>=0.18.0", # Anthropic API for evals- "openai>=1.0.0", # OpenAI API for evals-]-# Memory system extras (hierarchical memory with vector search)-memory = [- "hnswlib>=0.8.0", # HNSW vector index for semantic search- "sqlite-vec>=0.1.6",+ "datasets>=2.14.0",+ "sentence-transformers>=2.2.0",+ "numpy>=1.24.0",+ "scikit-learn>=1.3.0",+ "anthropic>=0.18.0",+ "openai>=1.0.0",]# AWS Bedrock backendbedrock = ["boto3>=1.28.0",]-# HTML content extraction (web scraping results)+# HTML content extractionhtml = ["trafilatura>=1.6.0",]-# Comprehensive LLM benchmarks (EleutherAI lm-evaluation-harness)+# Comprehensive LLM benchmarksbenchmark = ["lm-eval>=0.4.0","openai>=1.0.0",@@ -153,14 +161,20 @@ dev = ["pre-commit>=3.0.0","openai>=1.0.0","anthropic>=0.18.0",- "ollama>=0.4.0", # For Ollama integration tests (local LLM, no API key needed)- "langchain-ollama>=0.2.0", # For LangChain+Ollama integration tests- "hnswlib>=0.8.0", # For memory system tests- "sqlite-vec>=0.1.6", # Fallback vector backend for CI runners without AVX support+ "litellm>=1.0.0",+ "fastapi>=0.100.0",+ "uvicorn>=0.23.0",+ "httpx[http2]>=0.24.0",+ "ollama>=0.4.0",+ "langchain-ollama>=0.2.0",+ "hnswlib>=0.8.0",+ "sqlite-vec>=0.1.6",+ "sentence-transformers>=2.2.0",+ "numpy>=1.24.0",]-# All optional dependencies+# All optional dependencies (everything you need)all = [- "headroom-ai[relevance,proxy,reports,llmlingua,code,evals,memory,voice,html,benchmark,mcp]",+ "headroom-ai[proxy,code,ml,memory,relevance,image,reports,evals,voice,html,benchmark,mcp]",][project.scripts]diff --git a/tests/test_image_compressor.py b/tests/test_image_compressor.pyindex 7eeee1136..676583325 100644--- a/tests/test_image_compressor.py+++ b/tests/test_image_compressor.py@@ -27,19 +27,21 @@ try:except ImportError:HAS_PIL = False-from headroom.image.compressor import (+torch = pytest.importorskip("torch")++from headroom.image.compressor import ( # noqa: E402CompressionResult,ImageCompressor,Technique,compress_images,get_compressor,)-from headroom.image.trained_router import (+from headroom.image.trained_router import ( # noqa: E402ImageSignals,RouteDecision,TrainedRouter,)-from headroom.image.trained_router import (+from headroom.image.trained_router import ( # noqa: E402Technique as RouterTechnique,)