LLMCostGuard

#!/usr/bin/env python3
"""
LLMCostGuard - Zero-config budget enforcement and proxy engine for LLM APIs.

LLMCostGuard acts as a lightweight reverse proxy sitting between your apps and
providers like OpenAI, Anthropic, and Groq. It provides real-time token tracking,
strict cost ceilings, prompt caching, and intelligent failover routing to prevent
unexpected cloud billing spikes.

Features:
- Multi-provider support (OpenAI, Anthropic, Groq)
- Real-time token budget enforcement and hard billing caps
- In-memory exact and semantic prompt caching
- Automatic provider failover cascades on rate-limit or outage
- Built-in Prometheus metrics exporter for Grafana monitoring

Usage:
  $ python main.py --config config.json --port 8080
  $ docker run -p 8080:8080 -v $(pwd)/config.json:/app/config.json llmcostguard
"""

from dataclasses import dataclass, field
from enum import Enum, auto
import logging
import time
from typing import Any, Dict, List, Optional, Tuple

# Configure logging baseline
logger = logging.getLogger("llmcostguard")


class ProviderType(Enum):
    """Supported upstream LLM API providers."""
    OPENAI = "openai"
    ANTHROPIC = "anthropic"
    GROQ = "groq"


@dataclass
class BudgetConfig:
    """Defines rate limits, token quotas, and financial caps for a tenant."""
    tenant_id: str
    daily_cost_limit_usd: float
    monthly_cost_limit_usd: float
    max_tokens_per_minute: int = 100000
    hard_stop_on_exceed: bool = True


class CostGuardEngine:
    """Core proxy engine managing token budgets and failover routing."""
    def __init__(self, budgets: Optional[List[BudgetConfig]] = None) -> None:
        self._budgets: Dict[str, BudgetConfig] = {b.tenant_id: b for b in (budgets or [])}
        self._usage_tracker: Dict[str, float] = {}

# ... the full file ships with your download