Base code

2026-01-08 22:39:53 +07:00
parent 697115c61a
commit c35fa52117
2169 changed files with 626670 additions and 0 deletions
--- a/docs-site/docs/features/subscription/overview.md
+++ b/docs-site/docs/features/subscription/overview.md
@@ -0,0 +1,157 @@
+# Subscription System Overview
+
+ALwrity's usage-based subscription system provides comprehensive API cost tracking, usage limits, and real-time monitoring for all external API providers.
+
+## Features
+
+### Core Functionality
+- **Usage-Based Billing**: Track API calls, tokens, and costs across all providers
+- **Subscription Tiers**: Free, Basic, Pro, and Enterprise plans with different limits
+- **Real-Time Monitoring**: Live usage tracking and limit enforcement
+- **Cost Calculation**: Accurate pricing for Gemini, OpenAI, Anthropic, and other APIs
+- **Usage Alerts**: Automatic notifications at 80%, 90%, and 100% usage thresholds
+- **Robust Error Handling**: Comprehensive logging and exception management
+
+### Supported API Providers
+- **Gemini API**: Google's AI models with latest pricing
+- **OpenAI**: GPT models and embeddings
+- **Anthropic**: Claude models
+- **Mistral AI**: Mistral models
+- **Tavily**: AI-powered search
+- **Serper**: Google search API
+- **Metaphor/Exa**: Advanced search
+- **Firecrawl**: Web content extraction
+- **Stability AI**: Image generation
+- **Hugging Face**: GPT-OSS-120B via Groq
+
+## Architecture
+
+### Database Schema
+
+The system uses the following core tables:
+
+- `subscription_plans`: Available subscription tiers and limits
+- `user_subscriptions`: User subscription information
+- `api_usage_logs`: Detailed log of every API call
+- `usage_summaries`: Aggregated usage per user per billing period
+- `api_provider_pricing`: Pricing configuration for all providers
+- `usage_alerts`: Usage notifications and warnings
+- `billing_history`: Historical billing records
+
+### Service Structure
+
+```
+backend/services/subscription/
+├── __init__.py              # Package exports
+├── pricing_service.py       # API pricing and cost calculations
+├── usage_tracking_service.py # Usage tracking and limits
+├── exception_handler.py      # Exception handling
+└── monitoring_middleware.py # API monitoring middleware
+```
+
+### Core Services
+
+#### Pricing Service
+- Real-time cost calculation for all API providers
+- Subscription limit management
+- Usage validation and enforcement
+- Support for Gemini, OpenAI, Anthropic, Mistral, and search APIs
+
+#### Usage Tracking Service
+- Comprehensive API usage tracking
+- Real-time usage statistics
+- Trend analysis and projections
+- Automatic alert generation at 80%, 90%, and 100% thresholds
+
+#### Exception Handler
+- Robust error handling with detailed logging
+- Structured exception types for different scenarios
+- Automatic alert creation for critical errors
+- User-friendly error messages
+
+### Enhanced Middleware
+
+The system automatically tracks API usage through enhanced middleware:
+
+- **Automatic API Provider Detection**: Identifies Gemini, OpenAI, Anthropic, etc.
+- **Token Estimation**: Estimates usage from request/response content
+- **Pre-Request Validation**: Enforces usage limits before processing
+- **Cost Tracking**: Real-time cost calculation and logging
+- **Usage Limit Enforcement**: Returns 429 errors when limits exceeded
+
+## Key Capabilities
+
+### Usage-Based Billing
+- ✅ **Real-time cost tracking** for all API providers
+- ✅ **Token-level precision** for LLM APIs (Gemini, OpenAI, Anthropic)
+- ✅ **Request-based pricing** for search APIs (Tavily, Serper, Metaphor)
+- ✅ **Automatic cost calculation** with configurable pricing
+
+### Subscription Management
+- ✅ **4 Subscription Tiers**: Free, Basic ($29/mo), Pro ($79/mo), Enterprise ($199/mo)
+- ✅ **Flexible limits**: API calls, tokens, and monthly cost caps
+- ✅ **Usage enforcement**: Pre-request validation and blocking
+- ✅ **Billing cycle support**: Monthly and yearly options
+
+### Monitoring & Analytics
+- ✅ **Real-time dashboard** with usage statistics
+- ✅ **Usage trends** and projections
+- ✅ **Provider-specific breakdowns** (Gemini, OpenAI, etc.)
+- ✅ **Performance metrics** (response times, error rates)
+
+### Alert System
+- ✅ **Automatic notifications** at 80%, 90%, and 100% usage
+- ✅ **Multi-channel alerts** (database, logs, future email integration)
+- ✅ **Alert management** (mark as read, severity levels)
+- ✅ **Usage recommendations** and upgrade prompts
+
+## Security & Privacy
+
+### Data Protection
+- User usage data is encrypted at rest
+- API keys are never logged in usage tracking
+- Sensitive information is excluded from error logs
+- GDPR-compliant data handling
+
+### Rate Limiting
+- Pre-request usage validation
+- Automatic limit enforcement
+- Graceful degradation when limits are reached
+- User-friendly error messages
+
+## Exception Types
+
+The system uses structured exception types:
+
+- `UsageLimitExceededException`: When usage limits are reached
+- `PricingException`: Pricing calculation errors
+- `TrackingException`: Usage tracking failures
+- `SubscriptionException`: General subscription errors
+
+## Customization
+
+### Adding New API Providers
+1. Add provider to `APIProvider` enum
+2. Configure pricing in `api_provider_pricing` table
+3. Update detection patterns in middleware
+4. Add usage tracking logic
+
+### Modifying Subscription Plans
+1. Update plans in database or via API
+2. Modify limits and pricing
+3. Add/remove features
+4. Update billing integration
+
+## Next Steps
+
+- [Setup Guide](setup.md) - Installation and configuration
+- [API Reference](api-reference.md) - Endpoint documentation
+- [Pricing](pricing.md) - Subscription plans and API pricing
+- [Frontend Integration](frontend-integration.md) - Technical specifications
+- [Implementation Status](implementation-status.md) - Current features and metrics
+
+---
+
+**Version**: 1.0.0  
+**Last Updated**: January 2025
+