# Copyright (C) 2026 Mattia Zatelli # # This program is free software: you can redistribute it and/or modify # it under the terms of the GNU Affero General Public License as published by # the Free Software Foundation, either version 3 of the License, or # (at your option) any later version. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU Affero General Public License for more details. # # You should have received a copy of the GNU Affero General Public License # along with this program. If not, see . """ Usage event model for tracking API usage and billing """ from typing import Dict, Any, Optional from sqlalchemy import Column, Integer, String, JSON, DateTime, ForeignKey, Float, Index from sqlalchemy.orm import relationship from sqlalchemy.sql import func import uuid from app.core.database import Base class UsageEvent(Base): """ Usage event model for tracking API calls and resource usage """ __tablename__ = "usage_events" # Primary key id = Column(Integer, primary_key=True, index=True) # External identifiers tenant_id = Column(String(50), nullable=False, index=True) api_key_hash = Column(String(100), nullable=True, index=True) request_id = Column(String(100), nullable=False, index=True) # Project and query references (optional) project_id = Column(Integer, ForeignKey("projects.id", ondelete="SET NULL"), nullable=True, index=True) query_id = Column(Integer, ForeignKey("queries.id", ondelete="SET NULL"), nullable=True, index=True) # Request information endpoint = Column(String(200), nullable=False, index=True) http_method = Column(String(10), nullable=False) status_code = Column(Integer, nullable=False) user_agent = Column(String(500), nullable=True) client_ip = Column(String(45), nullable=True, index=True) # IPv6 support # Resource usage metrics units = Column(JSON, nullable=False) # {queries: 1, tokens: 532, compute_ms: 187, bytes: 1024} # Performance metrics processing_time_ms = Column(Integer, nullable=True) database_time_ms = Column(Integer, nullable=True) llm_time_ms = Column(Integer, nullable=True) cache_hit = Column(String(20), nullable=True) # "L1", "L2", "miss" # File operations (for upload/download endpoints) file_size_bytes = Column(Integer, nullable=True) file_type = Column(String(50), nullable=True) s3_operations = Column(JSON, nullable=True) # {uploads: 1, downloads: 0} # Error information (if status_code >= 400) error_type = Column(String(50), nullable=True) error_code = Column(String(50), nullable=True) error_message = Column(String(500), nullable=True) # Request/response metadata request_size_bytes = Column(Integer, nullable=True) response_size_bytes = Column(Integer, nullable=True) content_type = Column(String(100), nullable=True) # Feature usage flags features_used = Column(JSON, nullable=True) # ["nl_query", "vector_search", "export"] experimental_features = Column(JSON, nullable=True) # Track beta feature usage # Billing and quota tracking billable_units = Column(Float, nullable=False, default=1.0) # Calculated billing units quota_consumed = Column(JSON, nullable=True) # {monthly_queries: 1, api_calls: 1} # Geographic and context info region = Column(String(20), nullable=True) timezone = Column(String(50), nullable=True) # Timestamps timestamp = Column(DateTime(timezone=True), nullable=False, server_default=func.now()) created_at = Column(DateTime(timezone=True), server_default=func.now()) # Relationships project = relationship("Project", back_populates="usage_events") query = relationship("Query", back_populates="usage_events") # Indexes for performance and analytics __table_args__ = ( Index('idx_usage_tenant_timestamp', 'tenant_id', 'timestamp'), Index('idx_usage_endpoint_timestamp', 'endpoint', 'timestamp'), Index('idx_usage_status_timestamp', 'status_code', 'timestamp'), Index('idx_usage_billing', 'tenant_id', 'timestamp', 'billable_units'), Index('idx_usage_project', 'project_id', 'timestamp'), Index('idx_usage_performance', 'processing_time_ms', 'timestamp'), ) def __repr__(self): return f"" def to_dict(self) -> Dict[str, Any]: """Convert to dictionary for API responses""" return { "id": self.id, "tenant_id": self.tenant_id, "request_id": self.request_id, "endpoint": self.endpoint, "http_method": self.http_method, "status_code": self.status_code, "units": self.units, "processing_time_ms": self.processing_time_ms, "cache_hit": self.cache_hit, "file_size_bytes": self.file_size_bytes, "billable_units": self.billable_units, "features_used": self.features_used or [], "timestamp": self.timestamp.isoformat() if self.timestamp else None, } @classmethod def create_from_request( cls, tenant_id: str, endpoint: str, http_method: str, status_code: int, units: Dict[str, Any], request_id: str, api_key_hash: str = None, project_id: int = None, query_id: int = None, **kwargs ) -> "UsageEvent": """Create usage event from request data""" return cls( tenant_id=tenant_id, api_key_hash=api_key_hash, request_id=request_id, project_id=project_id, query_id=query_id, endpoint=endpoint, http_method=http_method, status_code=status_code, units=units, **kwargs ) def calculate_billable_units(self) -> float: """Calculate billable units based on usage metrics""" if not self.units: return 1.0 # Base billing unit base_units = 0.0 # Query-based billing if "queries" in self.units: base_units += self.units["queries"] * 1.0 # Token-based billing (for AI features) if "tokens" in self.units: base_units += self.units["tokens"] * 0.0001 # 1 unit per 10k tokens # Compute-based billing if "compute_ms" in self.units: base_units += self.units["compute_ms"] * 0.00001 # 1 unit per 100s compute # File operation billing if "bytes" in self.units: base_units += self.units["bytes"] * 0.000001 # 1 unit per MB # Storage operations if "s3_operations" in self.units: s3_ops = self.units["s3_operations"] if isinstance(s3_ops, dict): base_units += s3_ops.get("uploads", 0) * 0.1 base_units += s3_ops.get("downloads", 0) * 0.01 return max(base_units, 0.1) # Minimum billing unit def update_performance_metrics( self, processing_time_ms: int = None, database_time_ms: int = None, llm_time_ms: int = None, cache_hit: str = None ): """Update performance metrics""" if processing_time_ms is not None: self.processing_time_ms = processing_time_ms if database_time_ms is not None: self.database_time_ms = database_time_ms if llm_time_ms is not None: self.llm_time_ms = llm_time_ms if cache_hit is not None: self.cache_hit = cache_hit def add_feature_usage(self, feature: str): """Add feature to features_used list""" if not self.features_used: self.features_used = [] if feature not in self.features_used: self.features_used.append(feature) def set_error_info(self, error_type: str, error_code: str, error_message: str = None): """Set error information for failed requests""" self.error_type = error_type self.error_code = error_code self.error_message = error_message[:500] if error_message else None def is_billable(self) -> bool: """Check if event should be billed""" # Don't bill health checks and documentation non_billable_endpoints = ["/health", "/docs", "/redoc", "/openapi.json"] if any(self.endpoint.endswith(ep) for ep in non_billable_endpoints): return False # Don't bill failed authentication if self.status_code == 401: return False # Don't bill server errors (our fault) if 500 <= self.status_code < 600: return False return True def get_analytics_data(self) -> Dict[str, Any]: """Get data formatted for analytics""" return { "tenant_id": self.tenant_id, "endpoint": self.endpoint, "status_code": self.status_code, "processing_time_ms": self.processing_time_ms, "cache_hit": self.cache_hit, "features_used": self.features_used or [], "billable_units": self.billable_units, "timestamp": self.timestamp.isoformat() if self.timestamp else None, "region": self.region, } @classmethod def get_usage_summary( cls, tenant_id: str, start_date: str, end_date: str ) -> Dict[str, Any]: """Get usage summary for a tenant in date range""" # This would be implemented with SQL aggregation queries # Placeholder structure return { "tenant_id": tenant_id, "period": {"start": start_date, "end": end_date}, "total_requests": 0, "total_billable_units": 0.0, "by_endpoint": {}, "by_status": {}, "by_feature": {}, "performance_metrics": { "avg_processing_time_ms": 0, "cache_hit_rate": 0.0, } }