Version 1.4.0

2026-01-05 01:48:23 +00:00
parent dc7a459ebb
commit 6947819742
4 changed files with 551 additions and 85 deletions
--- a/docs/10-MODULES/BILLING.md
+++ b/docs/10-MODULES/BILLING.md
@@ -1,6 +1,6 @@
 # Billing Module

-**Last Verified:** December 25, 2025  
+**Last Verified:** January 5, 2026  
 **Status:** ✅ Active  
 **Backend Path:** `backend/igny8_core/modules/billing/` + `backend/igny8_core/business/billing/`  
 **Frontend Path:** `frontend/src/pages/Billing/` + `frontend/src/pages/Account/`
@@ -11,7 +11,7 @@

 | What | File | Key Items |
 |------|------|-----------|
-| Models | `business/billing/models.py` | `CreditTransaction`, `CreditUsageLog`, `CreditCostConfig` |
+| Models | `business/billing/models.py` | `CreditTransaction`, `CreditUsageLog`, `CreditCostConfig`, `AIModelConfig` |
 | Service | `business/billing/services/credit_service.py` | `CreditService` |
 | Views | `modules/billing/views.py` | `CreditBalanceViewSet`, `CreditUsageViewSet` |
 | Frontend | `pages/Account/PlansAndBillingPage.tsx` | Plans, credits, billing history |
@@ -23,6 +23,7 @@

 The Billing module manages:
 - Credit balance and transactions
+- AI model pricing and credit configuration (v1.4.0)
 - Usage tracking and limits
 - Plan enforcement
 - Payment processing
@@ -31,6 +32,37 @@ The Billing module manages:

 ## Data Models

+### AIModelConfig (NEW v1.4.0)
+
+Single Source of Truth for all AI models with pricing.
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| model_name | CharField(100) | Model identifier (gpt-4o-mini, dall-e-3) |
+| model_type | CharField(20) | text / image |
+| provider | CharField(50) | openai, anthropic, runware |
+| display_name | CharField(200) | Human-readable name |
+| is_default | BooleanField | One default per type |
+| is_active | BooleanField | Enable/disable |
+| cost_per_1k_input | DecimalField | USD cost per 1K input tokens (text) |
+| cost_per_1k_output | DecimalField | USD cost per 1K output tokens (text) |
+| tokens_per_credit | IntegerField | Text: tokens per 1 credit (e.g., 1000) |
+| credits_per_image | IntegerField | Image: credits per image (1, 5, 15) |
+| quality_tier | CharField(20) | basic / quality / premium |
+| max_tokens | IntegerField | Model token limit |
+| context_window | IntegerField | Model context size |
+| capabilities | JSONField | vision, function_calling, etc. |
+
+**Credit Examples:**
+
+| Model | tokens_per_credit | credits_per_image | quality_tier |
+|-------|-------------------|-------------------|--------------|
+| gpt-4o | 1000 | - | - |
+| gpt-4o-mini | 10000 | - | - |
+| runware:97@1 | - | 1 | basic |
+| dall-e-3 | - | 5 | quality |
+| google:4@2 | - | 15 | premium |
+
 ### CreditTransaction (Ledger)

 | Field | Type | Purpose |
@@ -41,7 +73,8 @@ The Billing module manages:
 | balance_after | Decimal | Balance after transaction |
 | description | CharField | Transaction description |
 | metadata | JSON | Additional data |
-| reference_id | CharField | External reference |
+| payment | FK(Payment) | Payment that triggered this (v1.4.0) |
+| reference_id | CharField | DEPRECATED: Use payment FK |
 | created_at | DateTime | Transaction time |

 ### CreditUsageLog (Analytics)
@@ -60,24 +93,23 @@ The Billing module manages:
 | metadata | JSON | Additional data |
 | created_at | DateTime | Usage time |

-### CreditCostConfig
+### CreditCostConfig (Updated v1.4.0)

 | Field | Type | Purpose |
 |-------|------|---------|
-| operation_type | CharField | Operation name |
-| credits_cost | Decimal | Credits per unit |
-| unit | CharField | per_request/per_100_words/per_200_words/per_item/per_image |
-| display_name | CharField | UI display name |
-| description | TextField | Description |
-| is_active | Boolean | Enable/disable |
-| previous_cost | Decimal | Previous cost (audit) |
-| updated_by | FK | Last updater |
+| operation_type | CharField(50) PK | Unique operation ID |
+| display_name | CharField(100) | Human-readable name |
+| base_credits | IntegerField | Fixed credits per operation |
+| is_active | BooleanField | Enable/disable |
+| description | TextField | Admin notes |
+
+**Note:** `tokens_per_credit` moved to AIModelConfig in v1.4.0.

 ---

 ## Credit Calculation Methods

-### Method 1: Token-Based (Text Models)
+### Method 1: Token-Based (Text Models) - Updated v1.4.0

 Used for: Clustering, Ideas, Content Generation, Optimization

@@ -85,19 +117,30 @@ Used for: Clustering, Ideas, Content Generation, Optimization
 1. AI call completes
 2. OpenAI returns actual token usage
 3. Calculate: `total_tokens = input_tokens + output_tokens`
-4. Look up `CreditCostConfig` for operation
-5. Apply formula based on unit:
-   - `per_100_words`: `credits = ceil(words / 100) * cost`
-   - `per_item`: `credits = items * cost`
-6. Apply minimum credits
-7. Deduct from balance
+4. Look up `AIModelConfig.tokens_per_credit` for the model used
+5. Calculate: `credits = ceil(total_tokens / tokens_per_credit)`
+6. Deduct from balance

-### Method 2: Fixed Cost (Image Models)
+**Example:**
+- Model: `gpt-4o-mini` (tokens_per_credit = 10000)
+- Tokens used: 15000
+- Credits: `ceil(15000 / 10000)` = 2 credits
+
+### Method 2: Fixed Cost (Image Models) - Updated v1.4.0

 Used for: Image Generation

 **Flow:**
-1. Before AI call
+1. User selects quality tier (basic/quality/premium)
+2. Look up `AIModelConfig.credits_per_image` for selected tier
+3. Check balance sufficient: `balance >= num_images * credits_per_image`
+4. Deduct credits
+5. Make AI call
+
+**Example:**
+- Quality Tier: "quality" (dall-e-3, credits_per_image = 5)
+- Images: 3
+- Credits: 3 × 5 = 15 credits
 2. Calculate: `credits = num_images * cost_per_image`
 3. Check balance sufficient
 4. Deduct credits
@@ -188,18 +231,31 @@ Displays:

 ---

-## Credit Costs Reference
+## Credit Costs Reference (Updated v1.4.0)

-Current costs (from `CreditCostConfig`):
+**Text Model Credits** (from `AIModelConfig.tokens_per_credit`):

-| Operation | Unit | Default Cost |
-|-----------|------|--------------|
-| Clustering | per_request | 10 credits |
-| Idea Generation | per_item | 2 credits |
-| Content Generation | per_100_words | 5 credits |
-| Image Generation (Basic) | per_image | 3 credits |
-| Image Generation (Premium) | per_image | 5 credits |
-| Content Optimization | per_200_words | 3 credits |
+| Model | tokens_per_credit | Cost/Credit | Notes |
+|-------|-------------------|-------------|-------|
+| gpt-4o | 1000 | ~$0.015 | High quality, lower throughput |
+| gpt-4o-mini | 10000 | ~$0.001 | Fast, cost-effective |
+| gpt-4.5-preview | 500 | ~$0.05 | Highest quality |
+
+**Image Model Credits** (from `AIModelConfig.credits_per_image`):
+
+| Quality Tier | credits_per_image | Model Example | Notes |
+|--------------|-------------------|---------------|-------|
+| Basic | 1 | runware:97@1 | Fast generation |
+| Quality | 5 | dall-e-3 | Balanced |
+| Premium | 15 | google:4@2 | Best quality |
+
+**Operation Base Costs** (from `CreditCostConfig.base_credits`):
+
+| Operation | Base Credits | Notes |
+|-----------|--------------|-------|
+| Clustering | 10 | Per clustering request |
+| Idea Generation | 2 | Per idea generated |
+| Content Optimization | 5 | Per optimization run |

 ---

@@ -248,7 +304,4 @@ Current costs (from `CreditCostConfig`):

 | Feature | Status | Description |
 |---------|--------|-------------|
-| AI Model Config database | 🔜 Planned | Move model pricing to database |
-| Budget alerts | 🔜 Planned | Email when approaching limits |
-| Usage forecasting | 🔜 Planned | Predict credit usage |
-| Overage billing | 🔜 Planned | Charge for overages instead of blocking |
+| ~~AI Model Config database~~ | ✅ v1.4.0 | Model pricing moved to AIModelConfig |