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

Move ProxyConfig, RequestLog, CacheEntry, RateLimitState to
headroom/proxy/models.py. Re-exported from server.py for backward
compatibility — all existing imports continue to work.

server.py: 8835 → 8643 lines (-192)
models.py: 199 lines (new)

Part of the server.py split effort to improve maintainability.

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

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
 # =============================================================================