Skip to content

Subscription System Setup

Complete guide for installing and configuring the ALwrity usage-based subscription system.

Prerequisites

  • Python 3.8+
  • PostgreSQL database (or SQLite for development)
  • FastAPI backend environment
  • Required Python packages: sqlalchemy, loguru, fastapi

Installation

1. Database Migration

Run the database setup script to create all subscription tables:

cd backend
python scripts/create_subscription_tables.py

This script will: - Create all subscription-related database tables - Initialize default subscription plans (Free, Basic, Pro, Enterprise) - Configure API pricing for all providers - Verify the setup

2. Verify Installation

Test the subscription system:

python test_subscription_system.py

This will verify: - Database table creation - Pricing calculations - Usage tracking - Limit enforcement - Error handling - API endpoints

3. Start the Server

python start_alwrity_backend.py

Configuration

Environment Variables

Create or update your .env file with the following:

# Database Configuration
DATABASE_URL=postgresql://user:password@localhost/alwrity
# For development, you can use SQLite:
# DATABASE_URL=sqlite:///./alwrity.db

# API Keys (required for usage tracking)
GEMINI_API_KEY=your_gemini_key
OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
# ... other API keys as needed

# HuggingFace Pricing (optional, for GPT-OSS-120B via Groq)
HUGGINGFACE_INPUT_TOKEN_COST=0.000001
HUGGINGFACE_OUTPUT_TOKEN_COST=0.000003

HuggingFace Pricing Configuration

HuggingFace API calls (specifically for GPT-OSS-120B model via Groq) are tracked and billed using configurable pricing.

Environment Variables

  • HUGGINGFACE_INPUT_TOKEN_COST: Cost per input token (default: 0.000001 = $1 per 1M tokens)
  • HUGGINGFACE_OUTPUT_TOKEN_COST: Cost per output token (default: 0.000003 = $3 per 1M tokens)

Updating Pricing

The pricing is automatically initialized when the database is set up. To update pricing after changing environment variables:

  1. Option 1: Restart the backend server (pricing will be updated on next initialization)
  2. Option 2: Run the database setup script again: 
    python backend/scripts/create_subscription_tables.py

Verify Pricing

Check that pricing is correctly configured by: 1. Checking the database api_provider_pricing table 2. Making a test API call and checking the cost in usage logs 3. Viewing the billing dashboard to see cost calculations

Production Setup

1. Database

Use PostgreSQL for production:

DATABASE_URL=postgresql://user:password@host:5432/alwrity_prod

2. Caching

Set up Redis for caching (optional but recommended):

REDIS_URL=redis://localhost:6379/0

3. Email Notifications

Configure email service for usage alerts:

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=alerts@alwrity.com
SMTP_PASSWORD=your_password

4. Monitoring and Alerting

Set up monitoring and alerting systems: - Configure log aggregation - Set up performance monitoring - Configure alert thresholds

5. Payment Processing

Implement payment processing integration: - Stripe integration - Payment gateway setup - Billing cycle management

Middleware Integration

The subscription system automatically tracks API usage through enhanced middleware. The middleware:

  • Detects API provider from request patterns
  • Estimates token usage from request/response content
  • Validates usage limits before processing
  • Calculates costs in real-time
  • Logs all API calls for tracking

No additional configuration is required - the middleware is automatically active once the subscription system is installed.

Usage Limit Enforcement

The system enforces usage limits automatically:

# Usage limits are checked before processing requests
can_proceed, message, usage_info = await usage_service.enforce_usage_limits(
    user_id=user_id,
    provider=APIProvider.GEMINI,
    tokens_requested=1000
)

if not can_proceed:
    return JSONResponse(
        status_code=429,
        content={"error": "Usage limit exceeded", "message": message}
    )

Testing

Run Tests

python test_subscription_system.py

Test Coverage

The test suite covers: - Database table creation - Pricing calculations - Usage tracking - Limit enforcement - Error handling - API endpoints

Troubleshooting

Common Issues

  1. Database Connection Errors
  2. Check DATABASE_URL configuration
  3. Verify database is running

  4. Check network connectivity

  5. Missing API Keys

  6. Verify all required keys are set in .env

  7. Check environment variable names match exactly

  8. Usage Not Tracking

  9. Verify middleware is integrated
  10. Check database connection

  11. Review logs for errors

  12. Pricing Errors

  13. Verify provider pricing configuration in database
  14. Check api_provider_pricing table
  15. Review pricing initialization logs

Debug Mode

Enable debug logging:

import logging
logging.basicConfig(level=logging.DEBUG)

Support

For issues and questions: 1. Check the logs in logs/subscription_errors.log 2. Run the test suite to identify problems 3. Review the error handling documentation 4. Contact the development team

Next Steps

Last Updated: January 2025