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
Refactor: extract data models to headroom/proxy/models.py (Step 1/9)
chopratejasa4ddaa32ce3e
diff --git a/headroom/proxy/models.py b/headroom/proxy/models.pynew file mode 100644index 000000000..a140fc0f9--- /dev/null+++ b/headroom/proxy/models.py@@ -0,0 +1,199 @@+"""Data models for the Headroom proxy.++Contains configuration and data classes used across the proxy modules.+Extracted from server.py to keep the codebase maintainable.+"""++from __future__ import annotations++from dataclasses import dataclass, field+from datetime import datetime+from typing import Any, Literal++# =============================================================================+# Data Models+# =============================================================================+++@dataclass+class RequestLog:+ """Complete log of a single request."""++ request_id: str+ timestamp: str+ provider: str+ model: str++ # Tokens+ input_tokens_original: int+ input_tokens_optimized: int+ output_tokens: int | None+ tokens_saved: int+ savings_percent: float++ # Performance+ optimization_latency_ms: float+ total_latency_ms: float | None++ # Metadata+ tags: dict[str, str]+ cache_hit: bool+ transforms_applied: list[str]++ # Waste signals detected in original messages+ waste_signals: dict[str, int] | None = None++ # Request/Response (optional, for debugging)+ request_messages: list[dict] | None = None+ response_content: str | None = None+ error: str | None = None+++@dataclass+class CacheEntry:+ """Cached response entry."""++ response_body: bytes+ response_headers: dict[str, str]+ created_at: datetime+ ttl_seconds: int+ hit_count: int = 0+ tokens_saved_per_hit: int = 0+++@dataclass+class RateLimitState:+ """Token bucket rate limiter state."""++ tokens: float+ last_update: float+++@dataclass+class ProxyConfig:+ """Proxy configuration."""++ # Server+ host: str = "127.0.0.1"+ port: int = 8787+ anthropic_api_url: str | None = None # Custom Anthropic API URL override+ openai_api_url: str | None = None # Custom OpenAI API URL override+ gemini_api_url: str | None = None # Custom Gemini API URL override++ # Backend: "anthropic" (direct API), "litellm-*" (via LiteLLM), or "anyllm" (via any-llm)+ backend: str = "anthropic"+ bedrock_region: str = "us-west-2"+ bedrock_profile: str | None = None+ anyllm_provider: str = "openai"++ # Optimization mode+ mode: str = "token_headroom"++ # Optimization+ optimize: bool = True+ image_optimize: bool = True+ min_tokens_to_crush: int = 500+ max_items_after_crush: int = 50+ keep_last_turns: int = 4++ # CCR Tool Injection+ ccr_inject_tool: bool = True+ ccr_inject_system_instructions: bool = False++ # CCR Response Handling+ ccr_handle_responses: bool = True+ ccr_max_retrieval_rounds: int = 3++ # CCR Context Tracking+ ccr_context_tracking: bool = True+ ccr_proactive_expansion: bool = True+ ccr_max_proactive_expansions: int = 2++ # Code-aware compression+ code_aware_enabled: bool = True++ # Per-tool compression profiles+ tool_profiles: dict[str, Any] | None = None++ # Read lifecycle management+ read_lifecycle: bool = True++ # Smart content routing+ smart_routing: bool = True++ # Intelligent context management+ intelligent_context: bool = True+ intelligent_context_scoring: bool = True+ intelligent_context_compress_first: bool = True++ # Caching+ cache_enabled: bool = True+ cache_ttl_seconds: int = 3600+ cache_max_entries: int = 1000++ # Rate limiting+ rate_limit_enabled: bool = True+ rate_limit_requests_per_minute: int = 60+ rate_limit_tokens_per_minute: int = 100000++ # Retry+ retry_enabled: bool = True+ retry_max_attempts: int = 3+ retry_base_delay_ms: int = 1000+ retry_max_delay_ms: int = 30000++ # Prefix freeze+ prefix_freeze_enabled: bool = True+ prefix_freeze_session_ttl: int = 600++ # Cost tracking+ cost_tracking_enabled: bool = True+ budget_limit_usd: float | None = None+ budget_period: Literal["hourly", "daily", "monthly"] = "daily"++ # Logging+ log_requests: bool = True+ log_file: str | None = None+ log_full_messages: bool = False++ # Fallback+ fallback_enabled: bool = False+ fallback_provider: str | None = None++ # Timeouts+ request_timeout_seconds: int = 300+ connect_timeout_seconds: int = 10++ # Connection pool+ max_connections: int = 500+ max_keepalive_connections: int = 100+ http2: bool = True++ # Memory System+ memory_enabled: bool = False+ memory_backend: Literal["local", "qdrant-neo4j"] = "local"+ memory_db_path: str = "headroom_memory.db"+ memory_inject_tools: bool = True+ traffic_learning_enabled: bool = False+ memory_use_native_tool: bool = False+ memory_inject_context: bool = True+ memory_top_k: int = 10+ memory_min_similarity: float = 0.3+ memory_qdrant_host: str = "localhost"+ memory_qdrant_port: int = 6333+ memory_neo4j_uri: str = "neo4j://localhost:7687"+ memory_neo4j_user: str = "neo4j"+ memory_neo4j_password: str = "password"+ memory_bridge_enabled: bool = False+ memory_bridge_md_paths: list[str] = field(default_factory=list)+ memory_bridge_md_format: str = "auto"+ memory_bridge_auto_import: bool = False+ memory_bridge_export_path: str = ""++ # License / Usage Reporting+ license_key: str | None = None+ license_cloud_url: str = "https://app.headroomlabs.ai"+ license_report_interval: int = 300++ # Compression Hooks+ hooks: Any = Nonediff --git a/headroom/proxy/server.py b/headroom/proxy/server.pyindex 0ede904d2..a168579c9 100644--- a/headroom/proxy/server.py+++ b/headroom/proxy/server.py@@ -33,7 +33,7 @@ import randomimport sysimport timefrom collections import OrderedDict, defaultdict, deque-from dataclasses import asdict, dataclass, field+from dataclasses import asdictfrom datetime import datetime, timedeltafrom pathlib import Pathfrom typing import TYPE_CHECKING, Any, Literal@@ -89,6 +89,9 @@ from headroom.config import (from headroom.dashboard import get_dashboard_htmlfrom headroom.providers import AnthropicProvider, OpenAIProviderfrom headroom.proxy.memory_handler import MemoryConfig, MemoryHandler++# Data models (extracted to headroom/proxy/models.py for maintainability)+from headroom.proxy.models import CacheEntry, ProxyConfig, RateLimitState, RequestLog # noqa: F401from headroom.proxy.savings_tracker import SavingsTrackerfrom headroom.telemetry import get_telemetry_collectorfrom headroom.telemetry.toin import get_toin@@ -604,201 +607,6 @@ MAX_RATE_LIMITER_BUCKETS = 1000COMPRESSION_TIMEOUT_SECONDS = 30-# =============================================================================-# Data Models-# =============================================================================---@dataclass-class RequestLog:- """Complete log of a single request."""-- request_id: str- timestamp: str- provider: str- model: str-- # Tokens- input_tokens_original: int- input_tokens_optimized: int- output_tokens: int | None- tokens_saved: int- savings_percent: float-- # Performance- optimization_latency_ms: float- total_latency_ms: float | None-- # Metadata- tags: dict[str, str]- cache_hit: bool- transforms_applied: list[str]-- # Waste signals detected in original messages- waste_signals: dict[str, int] | None = None-- # Request/Response (optional, for debugging)- request_messages: list[dict] | None = None- response_content: str | None = None- error: str | None = None---@dataclass-class CacheEntry:- """Cached response entry."""-- response_body: bytes- response_headers: dict[str, str]- created_at: datetime- ttl_seconds: int- hit_count: int = 0- tokens_saved_per_hit: int = 0---@dataclass-class RateLimitState:- """Token bucket rate limiter state."""-- tokens: float- last_update: float---@dataclass-class ProxyConfig:- """Proxy configuration."""-- # Server- host: str = "127.0.0.1"- port: int = 8787- anthropic_api_url: str | None = None # Custom Anthropic API URL override- openai_api_url: str | None = None # Custom OpenAI API URL override- gemini_api_url: str | None = None # Custom Gemini API URL override-- # Backend: "anthropic" (direct API), "litellm-*" (via LiteLLM), or "anyllm" (via any-llm)- # LiteLLM backends: "litellm-bedrock", "litellm-vertex", "litellm-azure", etc.- # any-llm backends: "anyllm" with --anyllm-provider (openai, mistral, groq, etc.)- backend: str = "anthropic"- bedrock_region: str = "us-west-2" # AWS region for Bedrock/LiteLLM- bedrock_profile: str | None = None # AWS profile (optional)- anyllm_provider: str = "openai" # any-llm provider (openai, mistral, groq, etc.)-- # Optimization mode: "token_headroom" (default) or "cost_savings"- # token_headroom: compress older messages for session extension- # cost_savings: preserve prefix cache for cost reduction- mode: str = "token_headroom"-- # Optimization- optimize: bool = True- image_optimize: bool = True # Compress images using trained ML router- min_tokens_to_crush: int = 500- max_items_after_crush: int = 50- keep_last_turns: int = 4-- # CCR Tool Injection- ccr_inject_tool: bool = True # Inject headroom_retrieve tool when compression occurs- ccr_inject_system_instructions: bool = False # Add instructions to system message-- # CCR Response Handling (intercept and handle CCR tool calls automatically)- ccr_handle_responses: bool = True # Handle headroom_retrieve calls in responses- ccr_max_retrieval_rounds: int = 3 # Max rounds of retrieval before returning-- # CCR Context Tracking (track compressed content across turns)- ccr_context_tracking: bool = True # Track compressed contexts for proactive expansion- ccr_proactive_expansion: bool = True # Proactively expand based on query relevance- ccr_max_proactive_expansions: int = 2 # Max contexts to proactively expand per turn-- # Code-aware compression (ON by default if installed)- code_aware_enabled: bool = True # Enable AST-based code compression-- # Per-tool compression profiles (parsed from CLI/env)- tool_profiles: dict[str, Any] | None = None-- # Read lifecycle management (compress stale/superseded Read outputs)- read_lifecycle: bool = True # ON by default: stale/superseded are provably safe-- # Smart content routing (routes each message to optimal compressor)- smart_routing: bool = True # Use ContentRouter for intelligent compression-- # Intelligent context management (score-based dropping instead of age-based)- intelligent_context: bool = True # Use IntelligentContextManager instead of RollingWindow- intelligent_context_scoring: bool = True # Use multi-factor importance scoring- intelligent_context_compress_first: bool = True # Try deeper compression before dropping-- # Caching- cache_enabled: bool = True- cache_ttl_seconds: int = 3600 # 1 hour- cache_max_entries: int = 1000-- # Rate limiting- rate_limit_enabled: bool = True- rate_limit_requests_per_minute: int = 60- rate_limit_tokens_per_minute: int = 100000-- # Retry- retry_enabled: bool = True- retry_max_attempts: int = 3- retry_base_delay_ms: int = 1000- retry_max_delay_ms: int = 30000-- # Prefix freeze: skip compression on already-cached messages- prefix_freeze_enabled: bool = True # Respect provider's prefix cache- prefix_freeze_session_ttl: int = 600 # Session tracker TTL (seconds)-- # Cost tracking- cost_tracking_enabled: bool = True- budget_limit_usd: float | None = None # None = unlimited- budget_period: Literal["hourly", "daily", "monthly"] = "daily"-- # Logging- log_requests: bool = True- log_file: str | None = None- log_full_messages: bool = False # Privacy: don't log content by default-- # Fallback- fallback_enabled: bool = False- fallback_provider: str | None = None # "openai" or "anthropic"-- # Timeouts- request_timeout_seconds: int = 300- connect_timeout_seconds: int = 10-- # Connection pool (for high concurrency with multiple agents)- max_connections: int = 500 # Max total connections to upstream APIs- max_keepalive_connections: int = 100 # Max idle connections to keep alive- http2: bool = True # Enable HTTP/2 multiplexing for better throughput-- # Memory System- memory_enabled: bool = False # Enable memory integration- memory_backend: Literal["local", "qdrant-neo4j"] = "local" # Backend type- memory_db_path: str = "headroom_memory.db" # Path for local backend- memory_inject_tools: bool = True # Auto-inject memory tools- traffic_learning_enabled: bool = False # Live traffic pattern learning (--learn)- memory_use_native_tool: bool = False # Use Anthropic's native memory_20250818 tool- memory_inject_context: bool = True # Inject searched memories into context- memory_top_k: int = 10 # Number of memories to inject- memory_min_similarity: float = 0.3 # Minimum similarity threshold- # Qdrant+Neo4j config (only used when memory_backend="qdrant-neo4j")- memory_qdrant_host: str = "localhost"- memory_qdrant_port: int = 6333- memory_neo4j_uri: str = "neo4j://localhost:7687"- memory_neo4j_user: str = "neo4j"- memory_neo4j_password: str = "password"- # Memory Bridge (bidirectional markdown <-> Headroom sync)- memory_bridge_enabled: bool = False- memory_bridge_md_paths: list[str] = field(default_factory=list)- memory_bridge_md_format: str = "auto"- memory_bridge_auto_import: bool = False- memory_bridge_export_path: str = ""-- # License / Usage Reporting (managed/enterprise deployments)- license_key: str | None = None # HEADROOM_LICENSE_KEY env var- license_cloud_url: str = "https://app.headroomlabs.ai"- license_report_interval: int = 300 # seconds (5 min)-- # Compression Hooks (for SaaS and advanced customization)- hooks: Any = None # CompressionHooks instance, or None for default behavior--# =============================================================================# Caching# =============================================================================