lutflow 0.1.0__py3-none-any.whl

lutflow/__init__.py

@@ -0,0 +1,44 @@
+"""
+Lutflow — GPU Financial Firewall for AI inference.
+
+Track costs, enforce budgets, and kill runaway GPU spending in real time.
+
+Example:
+    >>> from lutflow import Client
+    >>> client = Client(tenant_id="acme", budget_usd=10.00)
+    >>> wrapped = client.wrap(openai.OpenAI())
+    >>> response = wrapped.chat.completions.create(model="gpt-4o", messages=[...])
+
+Example with budget_session context manager:
+    >>> from lutflow import budget_session
+    >>> with budget_session(budget_usd=0.50, tenant_id="acme") as session:
+    ...     wrapped = session.wrap(openai.OpenAI())
+    ...     response = wrapped.chat.completions.create(...)
+"""
+
+from lutflow.client import Client, budget_session
+from lutflow.budget import BudgetStrategy, BudgetExceededError
+from lutflow.pricing import PricingMode
+from lutflow.pcpo import (
+    CostPredictor,
+    CostPrediction,
+    PredictiveBudgetGuard,
+    UsageEstimate,
+    UseCase,
+    MessageLength,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "Client",
+    "budget_session",
+    "BudgetStrategy",
+    "BudgetExceededError",
+    "PricingMode",
+    "CostPredictor",
+    "CostPrediction",
+    "PredictiveBudgetGuard",
+    "UsageEstimate",
+    "UseCase",
+    "MessageLength",
+]

lutflow/budget.py

@@ -0,0 +1,161 @@
+"""Budget management and enforcement strategies."""
+
+from enum import Enum
+from typing import Callable, Optional
+import logging
+
+logger = logging.getLogger("lutflow")
+
+
+class BudgetStrategy(Enum):
+    """Strategy for handling budget exceeded events."""
+    
+    SELF_KILL = "self_kill"
+    """Terminate the process immediately when budget is exceeded."""
+    
+    RAISE_ERROR = "raise_error"
+    """Raise BudgetExceededError when budget is exceeded."""
+    
+    WARN_ONLY = "warn_only"
+    """Log a warning but continue execution."""
+    
+    CALLBACK = "callback"
+    """Call a custom callback function."""
+
+
+class BudgetExceededError(Exception):
+    """Raised when the budget limit has been exceeded."""
+    
+    def __init__(
+        self,
+        budget_usd: float,
+        spent_usd: float,
+        tenant_id: str,
+        deployment_id: Optional[str] = None,
+    ):
+        self.budget_usd = budget_usd
+        self.spent_usd = spent_usd
+        self.tenant_id = tenant_id
+        self.deployment_id = deployment_id
+        super().__init__(
+            f"Budget exceeded: spent ${spent_usd:.4f} of ${budget_usd:.4f} "
+            f"(tenant={tenant_id}, deployment={deployment_id})"
+        )
+
+
+class BudgetGuard:
+    """
+    Local budget guard that enforces spending limits.
+    
+    This is the SDK-side implementation of the budget guard.
+    It tracks accumulated costs and triggers the configured strategy
+    when the budget is exceeded.
+    """
+    
+    def __init__(
+        self,
+        budget_usd: float,
+        tenant_id: str,
+        deployment_id: Optional[str] = None,
+        strategy: BudgetStrategy = BudgetStrategy.SELF_KILL,
+        on_exceeded_callback: Optional[Callable[[float, float], None]] = None,
+    ):
+        self.budget_usd = budget_usd
+        self.tenant_id = tenant_id
+        self.deployment_id = deployment_id
+        self.strategy = strategy
+        self.on_exceeded_callback = on_exceeded_callback
+        self._accumulated_cost_usd = 0.0
+        self._triggered = False
+    
+    @property
+    def accumulated_cost_usd(self) -> float:
+        """Total cost accumulated so far."""
+        return self._accumulated_cost_usd
+    
+    @property
+    def remaining_budget_usd(self) -> float:
+        """Remaining budget available."""
+        return max(0.0, self.budget_usd - self._accumulated_cost_usd)
+    
+    @property
+    def budget_utilization_percent(self) -> float:
+        """Percentage of budget used (0-100+)."""
+        if self.budget_usd <= 0:
+            return 100.0
+        return (self._accumulated_cost_usd / self.budget_usd) * 100
+    
+    def add_cost(self, cost_usd: float) -> bool:
+        """
+        Add cost to the accumulated total and check budget.
+        
+        Args:
+            cost_usd: Cost to add in USD.
+            
+        Returns:
+            True if budget is still available, False if exceeded.
+        """
+        self._accumulated_cost_usd += cost_usd
+        
+        if self._accumulated_cost_usd >= self.budget_usd and not self._triggered:
+            self._triggered = True
+            self._handle_budget_exceeded()
+            return False
+        
+        return True
+    
+    def check_budget(self) -> bool:
+        """
+        Check if budget is still available.
+        
+        Returns:
+            True if budget is available, False if exceeded.
+        """
+        return self._accumulated_cost_usd < self.budget_usd
+    
+    def _handle_budget_exceeded(self) -> None:
+        """Handle budget exceeded based on configured strategy."""
+        logger.warning(
+            "LUTFLOW: Budget exceeded - spent=$%.4f budget=$%.4f tenant=%s",
+            self._accumulated_cost_usd,
+            self.budget_usd,
+            self.tenant_id,
+        )
+        
+        if self.strategy == BudgetStrategy.SELF_KILL:
+            self._execute_self_kill()
+        elif self.strategy == BudgetStrategy.RAISE_ERROR:
+            raise BudgetExceededError(
+                budget_usd=self.budget_usd,
+                spent_usd=self._accumulated_cost_usd,
+                tenant_id=self.tenant_id,
+                deployment_id=self.deployment_id,
+            )
+        elif self.strategy == BudgetStrategy.WARN_ONLY:
+            logger.warning(
+                "LUTFLOW: Continuing despite budget exceeded (WARN_ONLY strategy)"
+            )
+        elif self.strategy == BudgetStrategy.CALLBACK:
+            if self.on_exceeded_callback:
+                self.on_exceeded_callback(
+                    self._accumulated_cost_usd,
+                    self.budget_usd,
+                )
+    
+    def _execute_self_kill(self) -> None:
+        """Terminate the current process."""
+        import os
+        import signal
+        
+        logger.critical(
+            "LUTFLOW: Self-terminating process (budget exceeded). "
+            "Spent=$%.4f Budget=$%.4f",
+            self._accumulated_cost_usd,
+            self.budget_usd,
+        )
+        
+        # Flush logs before killing
+        logging.shutdown()
+        
+        # Send SIGKILL to self
+        os.kill(os.getpid(), signal.SIGKILL)