headroom-ai 0.2.13__py3-none-any.whl

headroom/__init__.py

@@ -0,0 +1,212 @@
+"""
+Headroom - The Context Optimization Layer for LLM Applications.
+
+Cut your LLM costs by 50-90% without losing accuracy.
+
+Headroom wraps LLM clients to provide:
+- Smart compression of tool outputs (keeps errors, anomalies, relevant items)
+- Cache-aligned prefix optimization for better provider cache hits
+- Rolling window token management for long conversations
+- Full streaming support with zero accuracy loss
+
+Quick Start:
+
+    from headroom import HeadroomClient, OpenAIProvider
+    from openai import OpenAI
+
+    # Wrap your existing client
+    client = HeadroomClient(
+        original_client=OpenAI(),
+        provider=OpenAIProvider(),
+        default_mode="optimize",
+    )
+
+    # Use exactly like the original client
+    response = client.chat.completions.create(
+        model="gpt-4o",
+        messages=[
+            {"role": "user", "content": "Hello!"},
+        ],
+    )
+
+    # Check savings
+    stats = client.get_stats()
+    print(f"Tokens saved: {stats['session']['tokens_saved_total']}")
+
+Verify It's Working:
+
+    # Validate configuration
+    result = client.validate_setup()
+    if not result["valid"]:
+        print("Issues:", result)
+
+    # Enable logging to see what's happening
+    import logging
+    logging.basicConfig(level=logging.INFO)
+    # INFO:headroom.transforms.pipeline:Pipeline complete: 45000 -> 4500 tokens
+
+Simulate Before Sending:
+
+    plan = client.chat.completions.simulate(
+        model="gpt-4o",
+        messages=large_messages,
+    )
+    print(f"Would save {plan.tokens_saved} tokens")
+    print(f"Transforms: {plan.transforms}")
+
+Error Handling:
+
+    from headroom import HeadroomError, ConfigurationError, ProviderError
+
+    try:
+        response = client.chat.completions.create(...)
+    except ConfigurationError as e:
+        print(f"Config issue: {e.details}")
+    except HeadroomError as e:
+        print(f"Headroom error: {e}")
+
+For more examples, see https://github.com/headroom-sdk/headroom/tree/main/examples
+"""
+
+from .cache import (
+    AnthropicCacheOptimizer,
+    BaseCacheOptimizer,
+    CacheConfig,
+    CacheMetrics,
+    CacheOptimizerRegistry,
+    CacheResult,
+    CacheStrategy,
+    GoogleCacheOptimizer,
+    OpenAICacheOptimizer,
+    OptimizationContext,
+    SemanticCache,
+    SemanticCacheLayer,
+)
+from .client import HeadroomClient
+from .config import (
+    Block,
+    CacheAlignerConfig,
+    CacheOptimizerConfig,
+    CachePrefixMetrics,
+    DiffArtifact,
+    HeadroomConfig,
+    HeadroomMode,
+    RelevanceScorerConfig,
+    RequestMetrics,
+    RollingWindowConfig,
+    SimulationResult,
+    SmartCrusherConfig,
+    ToolCrusherConfig,
+    TransformDiff,
+    TransformResult,
+    WasteSignals,
+)
+from .exceptions import (
+    CacheError,
+    CompressionError,
+    ConfigurationError,
+    HeadroomError,
+    ProviderError,
+    StorageError,
+    TokenizationError,
+    TransformError,
+    ValidationError,
+)
+
+# Memory module - simple, LLM-driven memory
+from .memory import Memory, SQLiteMemoryStore, with_memory
+from .providers import AnthropicProvider, OpenAIProvider, Provider, TokenCounter
+from .relevance import (
+    BM25Scorer,
+    EmbeddingScorer,
+    HybridScorer,
+    RelevanceScore,
+    RelevanceScorer,
+    create_scorer,
+    embedding_available,
+)
+from .reporting import generate_report
+from .tokenizer import Tokenizer, count_tokens_messages, count_tokens_text
+from .transforms import (
+    CacheAligner,
+    RollingWindow,
+    SmartCrusher,
+    ToolCrusher,
+    TransformPipeline,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    # Main client
+    "HeadroomClient",
+    # Providers
+    "Provider",
+    "TokenCounter",
+    "OpenAIProvider",
+    "AnthropicProvider",
+    # Exceptions
+    "HeadroomError",
+    "ConfigurationError",
+    "ProviderError",
+    "StorageError",
+    "CompressionError",
+    "TokenizationError",
+    "CacheError",
+    "ValidationError",
+    "TransformError",
+    # Config
+    "HeadroomConfig",
+    "HeadroomMode",
+    "ToolCrusherConfig",
+    "SmartCrusherConfig",
+    "CacheAlignerConfig",
+    "CacheOptimizerConfig",
+    "RollingWindowConfig",
+    "RelevanceScorerConfig",
+    # Data models
+    "Block",
+    "CachePrefixMetrics",
+    "DiffArtifact",
+    "RequestMetrics",
+    "SimulationResult",
+    "TransformDiff",
+    "TransformResult",
+    "WasteSignals",
+    # Transforms
+    "ToolCrusher",
+    "SmartCrusher",
+    "CacheAligner",
+    "RollingWindow",
+    "TransformPipeline",
+    # Cache optimizers
+    "BaseCacheOptimizer",
+    "CacheConfig",
+    "CacheMetrics",
+    "CacheResult",
+    "CacheStrategy",
+    "OptimizationContext",
+    "CacheOptimizerRegistry",
+    "AnthropicCacheOptimizer",
+    "OpenAICacheOptimizer",
+    "GoogleCacheOptimizer",
+    "SemanticCache",
+    "SemanticCacheLayer",
+    # Relevance scoring
+    "RelevanceScore",
+    "RelevanceScorer",
+    "BM25Scorer",
+    "EmbeddingScorer",
+    "HybridScorer",
+    "create_scorer",
+    "embedding_available",
+    # Utilities
+    "Tokenizer",
+    "count_tokens_text",
+    "count_tokens_messages",
+    "generate_report",
+    # Memory - simple, LLM-driven memory
+    "with_memory",
+    "Memory",
+    "SQLiteMemoryStore",
+]

headroom/cache/__init__.py

@@ -0,0 +1,76 @@
+"""
+Headroom Cache Optimization Module.
+
+This module provides a plugin-based architecture for cache optimization
+across different LLM providers. Each provider has different caching
+mechanisms and this module abstracts those differences.
+
+Provider Caching Differences:
+- Anthropic: Explicit cache_control blocks, 90% savings, 5-min TTL
+- OpenAI: Automatic prefix caching, 50% savings, no user control
+- Google: Separate CachedContent API, 75% savings + storage costs
+
+Usage:
+    from headroom.cache import CacheOptimizerRegistry, SemanticCacheLayer
+
+    # Get provider-specific optimizer
+    optimizer = CacheOptimizerRegistry.get("anthropic")
+    result = optimizer.optimize(messages, context)
+
+    # With semantic caching layer
+    semantic = SemanticCacheLayer(optimizer, similarity_threshold=0.95)
+    result = semantic.process(messages, context)
+
+    # Register custom optimizer
+    CacheOptimizerRegistry.register("my-provider", MyOptimizer)
+"""
+
+from .anthropic import AnthropicCacheOptimizer
+from .base import (
+    BaseCacheOptimizer,
+    CacheBreakpoint,
+    CacheConfig,
+    CacheMetrics,
+    CacheOptimizer,
+    CacheResult,
+    CacheStrategy,
+    OptimizationContext,
+)
+from .dynamic_detector import (
+    DetectorConfig,
+    DynamicCategory,
+    DynamicContentDetector,
+    DynamicSpan,
+    detect_dynamic_content,
+)
+from .google import GoogleCacheOptimizer
+from .openai import OpenAICacheOptimizer
+from .registry import CacheOptimizerRegistry
+from .semantic import SemanticCache, SemanticCacheLayer
+
+__all__ = [
+    # Base types
+    "BaseCacheOptimizer",
+    "CacheBreakpoint",
+    "CacheConfig",
+    "CacheMetrics",
+    "CacheOptimizer",
+    "CacheResult",
+    "CacheStrategy",
+    "OptimizationContext",
+    # Dynamic content detection
+    "DetectorConfig",
+    "DynamicCategory",
+    "DynamicContentDetector",
+    "DynamicSpan",
+    "detect_dynamic_content",
+    # Registry
+    "CacheOptimizerRegistry",
+    # Provider implementations
+    "AnthropicCacheOptimizer",
+    "OpenAICacheOptimizer",
+    "GoogleCacheOptimizer",
+    # Semantic caching
+    "SemanticCacheLayer",
+    "SemanticCache",
+]