Future Modules planning docs
This commit is contained in:
IGNY8 VPS (Salman)
314
docs/90-REFERENCE/final-model-schemas.md
Normal file
314
docs/90-REFERENCE/final-model-schemas.md
Normal file
@@ -0,0 +1,314 @@
|
||||
# Final Model Schemas - Clean State
|
||||
|
||||
## Overview
|
||||
|
||||
This document defines the simplified, clean architecture for AI configuration and billing models.
|
||||
|
||||
**Total Models**: 5 (down from 7)
|
||||
- IntegrationProvider (API keys)
|
||||
- AIModelConfig (model definitions + pricing)
|
||||
- AISettings (system defaults + account overrides) - *renamed from GlobalIntegrationSettings*
|
||||
- AccountSettings (generic key-value store)
|
||||
- CreditCostConfig (operation-level pricing)
|
||||
|
||||
**Models Removed**:
|
||||
- IntegrationSettings (merged into AISettings/AccountSettings)
|
||||
- CreditCostConfig.tokens_per_credit (moved to AIModelConfig)
|
||||
|
||||
---
|
||||
|
||||
## 1. IntegrationProvider (API Keys Only)
|
||||
|
||||
Centralized storage for ALL external service API keys.
|
||||
|
||||
| Field | Type | Required | Notes |
|
||||
|-------|------|----------|-------|
|
||||
| `provider_id` | CharField(50) PK | Yes | openai, runware, stripe, paypal, resend |
|
||||
| `display_name` | CharField(100) | Yes | Human-readable name |
|
||||
| `provider_type` | CharField(20) | Yes | ai / payment / email / storage |
|
||||
| `api_key` | CharField(500) | No | Primary API key |
|
||||
| `api_secret` | CharField(500) | No | Secondary secret (Stripe, PayPal) |
|
||||
| `webhook_secret` | CharField(500) | No | Webhook signing secret |
|
||||
| `api_endpoint` | URLField | No | Custom endpoint (optional) |
|
||||
| `config` | JSONField | No | Provider-specific config |
|
||||
| `is_active` | BooleanField | Yes | Enable/disable provider |
|
||||
| `is_sandbox` | BooleanField | Yes | Test mode flag |
|
||||
| `updated_by` | FK(User) | No | Audit trail |
|
||||
| `created_at` | DateTime | Auto | |
|
||||
| `updated_at` | DateTime | Auto | |
|
||||
|
||||
**Seeded Providers**:
|
||||
- `openai` - AI (text + DALL-E)
|
||||
- `runware` - AI (images)
|
||||
- `anthropic` - AI (future)
|
||||
- `stripe` - Payment
|
||||
- `paypal` - Payment
|
||||
- `resend` - Email
|
||||
|
||||
---
|
||||
|
||||
## 2. AIModelConfig (Single Source of Truth for Models)
|
||||
|
||||
All AI models (text + image) with pricing and credit configuration.
|
||||
|
||||
| Field | Type | Required | Notes |
|
||||
|-------|------|----------|-------|
|
||||
| `id` | AutoField PK | Auto | |
|
||||
| `model_name` | CharField(100) | Yes | gpt-5.1, dall-e-3, runware:97@1 |
|
||||
| `model_type` | CharField(20) | Yes | text / image |
|
||||
| `provider` | CharField(50) | Yes | Links to IntegrationProvider |
|
||||
| `display_name` | CharField(200) | Yes | Human-readable |
|
||||
| `is_default` | BooleanField | Yes | One default per type |
|
||||
| `is_active` | BooleanField | Yes | Enable/disable |
|
||||
| `cost_per_1k_input` | DecimalField | No | Provider cost (USD) - text models |
|
||||
| `cost_per_1k_output` | DecimalField | No | Provider cost (USD) - text models |
|
||||
| `tokens_per_credit` | IntegerField | No | Text: tokens per 1 credit (e.g., 1000) |
|
||||
| `credits_per_image` | IntegerField | No | Image: credits per image (e.g., 1, 5, 15) |
|
||||
| `quality_tier` | CharField(20) | No | basic / quality / premium |
|
||||
| `max_tokens` | IntegerField | No | Model token limit |
|
||||
| `context_window` | IntegerField | No | Model context size |
|
||||
| `capabilities` | JSONField | No | vision, function_calling, etc. |
|
||||
| `created_at` | DateTime | Auto | |
|
||||
| `updated_at` | DateTime | Auto | |
|
||||
|
||||
**Credit Configuration Examples**:
|
||||
|
||||
| Model | Type | tokens_per_credit | credits_per_image | quality_tier |
|
||||
|-------|------|-------------------|-------------------|--------------|
|
||||
| gpt-5.1 | text | 1000 | - | - |
|
||||
| gpt-4o-mini | text | 10000 | - | - |
|
||||
| runware:97@1 | image | - | 1 | basic |
|
||||
| dall-e-3 | image | - | 5 | quality |
|
||||
| google:4@2 | image | - | 15 | premium |
|
||||
|
||||
---
|
||||
|
||||
## 3. AISettings (Renamed from GlobalIntegrationSettings)
|
||||
|
||||
System-wide AI defaults. Singleton (pk=1).
|
||||
|
||||
| Field | Type | Required | Default | Notes |
|
||||
|-------|------|----------|---------|-------|
|
||||
| `id` | AutoField PK | Auto | 1 | Singleton |
|
||||
| `temperature` | FloatField | Yes | 0.7 | AI temperature (0.0-2.0) |
|
||||
| `max_tokens` | IntegerField | Yes | 8192 | Max response tokens |
|
||||
| `image_style` | CharField(30) | Yes | photorealistic | Default image style |
|
||||
| `image_quality` | CharField(20) | Yes | standard | standard / hd |
|
||||
| `max_images_per_article` | IntegerField | Yes | 4 | Max in-article images |
|
||||
| `image_size` | CharField(20) | Yes | 1024x1024 | Default image dimensions |
|
||||
| `updated_by` | FK(User) | No | | Audit trail |
|
||||
| `updated_at` | DateTime | Auto | | |
|
||||
|
||||
**Removed Fields** (now elsewhere):
|
||||
- All `*_api_key` fields → IntegrationProvider
|
||||
- All `*_model` fields → AIModelConfig.is_default
|
||||
- `default_text_provider` → AIModelConfig.is_default where model_type='text'
|
||||
- `default_image_service` → AIModelConfig.is_default where model_type='image'
|
||||
|
||||
**Image Style Choices**:
|
||||
- `photorealistic` - Ultra realistic photography
|
||||
- `illustration` - Digital illustration
|
||||
- `3d_render` - Computer generated 3D
|
||||
- `minimal_flat` - Minimal / Flat Design
|
||||
- `artistic` - Artistic / Painterly
|
||||
- `cartoon` - Cartoon / Stylized
|
||||
|
||||
---
|
||||
|
||||
## 4. AccountSettings (Per-Account Overrides)
|
||||
|
||||
Generic key-value store for account-specific settings.
|
||||
|
||||
| Field | Type | Required | Notes |
|
||||
|-------|------|----------|-------|
|
||||
| `id` | AutoField PK | Auto | |
|
||||
| `account` | FK(Account) | Yes | |
|
||||
| `key` | CharField(100) | Yes | Setting key |
|
||||
| `value` | JSONField | Yes | Setting value |
|
||||
| `created_at` | DateTime | Auto | |
|
||||
| `updated_at` | DateTime | Auto | |
|
||||
|
||||
**Unique Constraint**: `(account, key)`
|
||||
|
||||
**AI-Related Keys** (override AISettings defaults):
|
||||
|
||||
| Key | Type | Example | Notes |
|
||||
|-----|------|---------|-------|
|
||||
| `ai.temperature` | float | 0.7 | Override system default |
|
||||
| `ai.max_tokens` | int | 8192 | Override system default |
|
||||
| `ai.image_style` | string | "photorealistic" | Override system default |
|
||||
| `ai.image_quality` | string | "hd" | Override system default |
|
||||
| `ai.max_images` | int | 6 | Override system default |
|
||||
| `ai.image_quality_tier` | string | "quality" | User's preferred tier |
|
||||
|
||||
---
|
||||
|
||||
## 5. CreditCostConfig (Operation-Level Pricing)
|
||||
|
||||
Fixed credit costs per operation type.
|
||||
|
||||
| Field | Type | Required | Notes |
|
||||
|-------|------|----------|-------|
|
||||
| `operation_type` | CharField(50) PK | Yes | Unique operation ID |
|
||||
| `display_name` | CharField(100) | Yes | Human-readable |
|
||||
| `base_credits` | IntegerField | Yes | Fixed credits per operation |
|
||||
| `is_active` | BooleanField | Yes | Enable/disable |
|
||||
| `description` | TextField | No | Admin notes |
|
||||
|
||||
**Removed**: `tokens_per_credit` (now in AIModelConfig)
|
||||
|
||||
---
|
||||
|
||||
## Frontend Settings Structure
|
||||
|
||||
### Content Generation Settings Tab
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Content Generation Settings │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ AI Parameters │
|
||||
│ ┌─────────────────────────────────────────────────────┐ │
|
||||
│ │ Temperature [=====○====] 0.7 │ │
|
||||
│ │ More focused ←→ More creative │ │
|
||||
│ │ │ │
|
||||
│ │ Max Tokens [8192 ▼] │ │
|
||||
│ │ Response length limit │ │
|
||||
│ └─────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ Image Generation │
|
||||
│ ┌─────────────────────────────────────────────────────┐ │
|
||||
│ │ Image Quality │ │
|
||||
│ │ ○ Basic (1 credit/image) - Fast, simple │ │
|
||||
│ │ ● Quality (5 credits/image) - Balanced │ │
|
||||
│ │ ○ Premium (15 credits/image) - Best quality │ │
|
||||
│ │ │ │
|
||||
│ │ Image Style [Photorealistic ▼] │ │
|
||||
│ │ │ │
|
||||
│ │ Images per Article [4 ▼] (max 8) │ │
|
||||
│ └─────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ [Save Settings] │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Frontend API Response
|
||||
|
||||
```
|
||||
GET /api/v1/accounts/settings/ai/
|
||||
|
||||
Response:
|
||||
{
|
||||
"content_generation": {
|
||||
"temperature": 0.7,
|
||||
"max_tokens": 8192
|
||||
},
|
||||
"image_generation": {
|
||||
"quality_tiers": [
|
||||
{"tier": "basic", "credits": 1, "label": "Basic", "description": "Fast, simple images"},
|
||||
{"tier": "quality", "credits": 5, "label": "Quality", "description": "Balanced quality"},
|
||||
{"tier": "premium", "credits": 15, "label": "Premium", "description": "Best quality"}
|
||||
],
|
||||
"selected_tier": "quality",
|
||||
"styles": [
|
||||
{"value": "photorealistic", "label": "Photorealistic"},
|
||||
{"value": "illustration", "label": "Illustration"},
|
||||
{"value": "3d_render", "label": "3D Render"},
|
||||
{"value": "minimal_flat", "label": "Minimal / Flat"},
|
||||
{"value": "artistic", "label": "Artistic"},
|
||||
{"value": "cartoon", "label": "Cartoon"}
|
||||
],
|
||||
"selected_style": "photorealistic",
|
||||
"max_images": 4,
|
||||
"max_allowed": 8
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Save Settings Request
|
||||
|
||||
```
|
||||
PUT /api/v1/accounts/settings/ai/
|
||||
|
||||
Request:
|
||||
{
|
||||
"temperature": 0.8,
|
||||
"max_tokens": 4096,
|
||||
"image_quality_tier": "premium",
|
||||
"image_style": "illustration",
|
||||
"max_images": 6
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Flow
|
||||
|
||||
```
|
||||
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
|
||||
│ IntegrationProv. │ │ AIModelConfig │ │ AISettings │
|
||||
│ │ │ │ │ (Singleton) │
|
||||
│ - API keys │◄────│ - Model list │ │ │
|
||||
│ - Provider info │ │ - Pricing │ │ - Defaults │
|
||||
└──────────────────┘ │ - Credits config │ │ - temperature │
|
||||
│ - quality_tier │ │ - max_tokens │
|
||||
└────────┬─────────┘ │ - image_style │
|
||||
│ └────────┬─────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌──────────────────────────────────────────┐
|
||||
│ AccountSettings │
|
||||
│ │
|
||||
│ Account-specific overrides: │
|
||||
│ - ai.temperature = 0.8 │
|
||||
│ - ai.image_quality_tier = "premium" │
|
||||
│ - ai.image_style = "illustration" │
|
||||
└──────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────────┐
|
||||
│ Frontend Settings UI │
|
||||
│ │
|
||||
│ GET /api/v1/accounts/settings/ai/ │
|
||||
│ - Merges AISettings + AccountSettings │
|
||||
│ - Returns effective values for account │
|
||||
└──────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migration Summary
|
||||
|
||||
| From | To | Action |
|
||||
|------|----|--------|
|
||||
| GlobalIntegrationSettings.*_api_key | IntegrationProvider | Already done |
|
||||
| GlobalIntegrationSettings.*_model | AIModelConfig.is_default | Already done |
|
||||
| GlobalIntegrationSettings (remaining) | AISettings (rename) | Phase 3 |
|
||||
| IntegrationSettings | AccountSettings | Phase 3 - delete model |
|
||||
| CreditCostConfig.tokens_per_credit | AIModelConfig.tokens_per_credit | Already done |
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 Implementation Steps
|
||||
|
||||
1. **Rename Model**: GlobalIntegrationSettings → AISettings
|
||||
2. **Remove Fields**: All `*_api_key`, `*_model` fields from AISettings
|
||||
3. **Create API Endpoint**: `/api/v1/accounts/settings/ai/`
|
||||
4. **Update Frontend**: Load from new endpoint, use quality_tier picker
|
||||
5. **Delete Model**: IntegrationSettings (after migrating any data)
|
||||
6. **Cleanup**: Remove deprecated choices/constants
|
||||
|
||||
---
|
||||
|
||||
## Files to Modify (Phase 3)
|
||||
|
||||
| File | Change |
|
||||
|------|--------|
|
||||
| `modules/system/global_settings_models.py` | Rename class, remove deprecated fields |
|
||||
| `modules/system/admin.py` | Update admin for AISettings |
|
||||
| `modules/system/views.py` | New AI settings API endpoint |
|
||||
| `modules/system/serializers.py` | AISettingsSerializer |
|
||||
| `settings.py` | Update admin sidebar |
|
||||
| `ai/ai_core.py` | Use AISettings instead of GlobalIntegrationSettings |
|
||||
| Frontend | New settings component with quality tier picker |
|
||||
Reference in New Issue
Block a user