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.

Refactor: extract data models to headroom/proxy/models.py (Step 1/9)

chopratejasa4ddaa32ce3e
diff --git a/headroom/proxy/models.py b/headroom/proxy/models.py
new file mode 100644
index 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 = None
diff --git a/headroom/proxy/server.py b/headroom/proxy/server.py
index 0ede904d2..a168579c9 100644
--- a/headroom/proxy/server.py
+++ b/headroom/proxy/server.py
@@ -33,7 +33,7 @@ import random
import sys
import time
from collections import OrderedDict, defaultdict, deque
-from dataclasses import asdict, dataclass, field
+from dataclasses import asdict
from datetime import datetime, timedelta
from pathlib import Path
from typing import TYPE_CHECKING, Any, Literal
@@ -89,6 +89,9 @@ from headroom.config import (
from headroom.dashboard import get_dashboard_html
from headroom.providers import AnthropicProvider, OpenAIProvider
from 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: F401
from headroom.proxy.savings_tracker import SavingsTracker
from headroom.telemetry import get_telemetry_collector
from headroom.telemetry.toin import get_toin
@@ -604,201 +607,6 @@ MAX_RATE_LIMITER_BUCKETS = 1000
COMPRESSION_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
# =============================================================================