Skip to content

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.

Slim core dependencies: 2.5GB → 195MB install size

chopratejas18118af5cec9
diff --git a/headroom/__init__.py b/headroom/__init__.py
index 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-transformers
from .relevance import (
BM25Scorer,
EmbeddingScorer,
diff --git a/headroom/cli/main.py b/headroom/cli/main.py
index 753c6bf13..acc84ca97 100644
--- a/headroom/cli/main.py
+++ b/headroom/cli/main.py
@@ -37,12 +37,17 @@ def _register_commands() -> None:
evals, # noqa: F401
learn, # noqa: F401
mcp, # noqa: F401
- memory, # noqa: F401
perf, # noqa: F401
proxy, # noqa: F401
wrap, # 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.py
index 8d068cfa6..c91f1dc81 100644
--- a/headroom/image/trained_router.py
+++ b/headroom/image/trained_router.py
@@ -16,9 +16,14 @@ from enum import Enum
from pathlib import Path
from 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 = False
from headroom.models.config import ML_MODEL_DEFAULTS
diff --git a/headroom/memory/models.py b/headroom/memory/models.py
index 163b2ef54..6e1293c34 100644
--- a/headroom/memory/models.py
+++ b/headroom/memory/models.py
@@ -8,7 +8,10 @@ from datetime import datetime
from enum import Enum
from 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
# Metadata
metadata: 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.py
index 3314a9a0e..764adec6a 100644
--- a/headroom/pricing/litellm_pricing.py
+++ b/headroom/pricing/litellm_pricing.py
@@ -11,7 +11,13 @@ from __future__ import annotations
from dataclasses import dataclass
from 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 None
cost_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.toml
index 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 integration
agno = [
"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 integration
mcp = [
"mcp>=1.0.0",
"httpx>=0.24.0",
]
-# Voice filler detection (training and inference)
+# Voice filler detection
voice = [
- "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 framework
evals = [
- "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 backend
bedrock = [
"boto3>=1.28.0",
]
-# HTML content extraction (web scraping results)
+# HTML content extraction
html = [
"trafilatura>=1.6.0",
]
-# Comprehensive LLM benchmarks (EleutherAI lm-evaluation-harness)
+# Comprehensive LLM benchmarks
benchmark = [
"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.py
index 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: E402
CompressionResult,
ImageCompressor,
Technique,
compress_images,
get_compressor,
)
-from headroom.image.trained_router import (
+from headroom.image.trained_router import ( # noqa: E402
ImageSignals,
RouteDecision,
TrainedRouter,
)
-from headroom.image.trained_router import (
+from headroom.image.trained_router import ( # noqa: E402
Technique as RouterTechnique,
)