# Credit System

**Last Verified:** January 10, 2026
**Status:** ✅ Complete (v1.7.1 - Image Generation Credits)

---

## Overview

IGNY8 uses a unified credit system where all AI operations consume credits from a single balance. Plan limits are simplified to 4 hard/monthly limits only.

---

## Credit Flow (Verified Architecture)

```
┌─────────────────────────────────────────────────────────────────┐
│                    CREDIT FLOW                                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Plan.included_credits = Monthly allocation (e.g., 10,000)      │
│         ↓ (Added on subscription renewal/approval)               │
│  Account.credits = Current balance (real-time, decremented)     │
│         ↓ (Decremented on each AI operation)                    │
│  CreditTransaction = Log of all credit changes                  │
│  CreditUsageLog = Detailed operation tracking                   │
│                                                                  │
│  THESE ARE NOT PARALLEL - They serve different purposes:        │
│  • Plan.included_credits = "How many credits per month"         │
│  • Account.credits = "How many credits you have RIGHT NOW"      │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

**Where credits are added to Account.credits:**
1. `billing/views.py` - When manual payment is approved
2. `payment_service.py` - When credit package purchased
3. `credit_service.py` - Generic `add_credits()` method

---

## Simplified Limits (v1.5.0)

### Hard Limits (Never Reset)

| Limit | Plan Field | Account Field | Description |
|-------|------------|---------------|-------------|
| Sites | `max_sites` | (count of Site objects) | Maximum sites per account |
| Users | `max_users` | (count of User objects) | Maximum team members |
| Keywords | `max_keywords` | (count of Keyword objects) | Total keywords allowed |

### Monthly Limits (Reset on Billing Cycle)

| Limit | Plan Field | Account Field | Description |
|-------|------------|---------------|-------------|
| Ahrefs Queries | `max_ahrefs_queries` | `usage_ahrefs_queries` | Live Ahrefs API queries per month |

### Removed Limits (Now Credit-Based)

The following limits were removed in v1.5.0 - credits handle these:
- ~~max_clusters~~ → Credits
- ~~max_content_ideas~~ → Credits
- ~~max_content_words~~ → Credits
- ~~max_images_basic~~ → Credits
- ~~max_images_premium~~ → Credits
- ~~max_image_prompts~~ → Credits

---

## Plan Tiers

| Plan | Credits/Month | Sites | Users | Keywords | Ahrefs Queries |
|------|---------------|-------|-------|----------|----------------|
| Free | 500 | 1 | 1 | 100 | 0 |
| Starter | 5,000 | 3 | 2 | 500 | 50 |
| Growth | 15,000 | 10 | 5 | 2,000 | 200 |
| Scale | 50,000 | Unlimited | 10 | 10,000 | 500 |

---

## Credit Operations

### Token-Based Operations (Text AI)

Credits calculated from actual token usage:
- `credits = ceil(total_tokens / tokens_per_credit)`
- `tokens_per_credit` defined per model in `AIModelConfig`

| Operation | Model Example | tokens_per_credit |
|-----------|---------------|-------------------|
| Keyword Clustering | gpt-4o-mini | 10,000 |
| Idea Generation | gpt-4o-mini | 10,000 |
| Content Generation | gpt-4o | 1,000 |
| Content Optimization | gpt-4o-mini | 10,000 |

### Fixed-Cost Operations (Image AI) - v1.7.1 Complete

Credits per image based on quality tier:

| Quality Tier | Model Example | Credits/Image |
|--------------|---------------|---------------|
| Basic | runware:97@1 | 1 |
| Quality | dall-e-3 | 5 |
| Premium | google:4@2 | 15 |

**Image Generation Credit Flow (v1.7.1):**
1. Pre-check: `CreditService.check_credits_for_image()` verifies sufficient credits
2. Generation: Images generated via `process_image_generation_queue` Celery task
3. Post-deduct: `CreditService.deduct_credits_for_image()` called per successful image
4. Logging: `CreditUsageLog` + `CreditTransaction` + `AITaskLog` entries created
5. Notifications: `NotificationService.notify_images_complete/failed()` called

### Free Operations

| Operation | Cost |
|-----------|------|
| Add keyword (manual) | 0 |
| Create content task | 0 |
| Edit content | 0 |
| Publish to WordPress | 0 |
| Sync from WordPress | 0 |

---

## Database Models

### Account (Credit Balance)

```python
class Account(models.Model):
    credits = models.IntegerField(default=0)  # Current balance
    usage_ahrefs_queries = models.IntegerField(default=0)  # Monthly Ahrefs usage
```

### Plan (Allocations)

```python
class Plan(models.Model):
    included_credits = models.IntegerField(default=0)  # Monthly allocation
    max_sites = models.IntegerField(default=1)
    max_users = models.IntegerField(default=1)
    max_keywords = models.IntegerField(default=100)
    max_ahrefs_queries = models.IntegerField(default=0)  # Monthly Ahrefs limit
```

### CreditTransaction (Ledger)

```python
class CreditTransaction(models.Model):
    account = models.ForeignKey(Account)
    transaction_type = models.CharField()  # purchase/subscription/refund/deduction
    amount = models.DecimalField()  # Positive (add) or negative (deduct)
    balance_after = models.DecimalField()
    description = models.CharField()
    created_at = models.DateTimeField()
```

### CreditUsageLog (Analytics)

```python
class CreditUsageLog(models.Model):
    account = models.ForeignKey(Account)
    operation_type = models.CharField()  # clustering/content_generation/image_generation
    credits_used = models.DecimalField()
    model_used = models.CharField()
    tokens_input = models.IntegerField()
    tokens_output = models.IntegerField()
    created_at = models.DateTimeField()
```

---

## Business Logic

### CreditService

Location: `backend/igny8_core/business/billing/services/credit_service.py`

**Key Methods:**

```python
class CreditService:
    @staticmethod
    def check_credits(account, required_credits):
        """Check if sufficient credits available, raises InsufficientCreditsError if not"""
        
    @staticmethod
    def deduct_credits_for_operation(account, operation_type, model, tokens_in, tokens_out, metadata=None):
        """Deduct credits and log usage after AI operation"""
        
    @staticmethod
    def add_credits(account, amount, transaction_type, description):
        """Add credits (admin/purchase/subscription)"""
        
    @staticmethod
    def calculate_credits_from_tokens(operation_type, tokens_in, tokens_out, model=None):
        """Calculate credits based on token usage and model"""
```

### LimitService

Location: `backend/igny8_core/business/billing/services/limit_service.py`

**Key Methods:**

```python
class LimitService:
    HARD_LIMIT_MAPPINGS = {
        'sites': {...},
        'users': {...},
        'keywords': {...},
    }
    
    MONTHLY_LIMIT_MAPPINGS = {
        'ahrefs_queries': {...},
    }
    
    @classmethod
    def check_hard_limit(cls, account, limit_name, additional_count=1):
        """Check if adding items would exceed hard limit"""
        
    @classmethod
    def check_monthly_limit(cls, account, limit_name, additional_count=1):
        """Check if operation would exceed monthly limit"""
        
    @classmethod
    def increment_monthly_usage(cls, account, limit_name, count=1):
        """Increment monthly usage counter"""
```

### Usage in AI Operations

```python
# In content generation service
def generate_content(task, user):
    account = task.site.account
    
    # 1. Pre-check credits (estimated)
    estimated_credits = 50  # Estimate for content generation
    CreditService.check_credits(account, estimated_credits)
    
    # 2. Execute AI function
    content, usage = ai_engine.generate_content(task)
    
    # 3. Deduct actual credits based on token usage
    CreditService.deduct_credits_for_operation(
        account=account,
        operation_type='content_generation',
        model=usage.model,
        tokens_in=usage.input_tokens,
        tokens_out=usage.output_tokens,
        metadata={'content_id': content.id}
    )
    
    return content
```

---

## API Responses

### Successful Operation

```json
{
  "success": true,
  "data": { ... },
  "credits_used": 15,
  "balance": 9985
}
```

### Insufficient Credits

```json
HTTP 402 Payment Required

{
  "success": false,
  "error": "Insufficient credits",
  "code": "INSUFFICIENT_CREDITS",
  "required": 50,
  "available": 25
}
```

### Limit Exceeded

```json
HTTP 402 Payment Required

{
  "success": false,
  "error": "Keyword limit reached",
  "code": "HARD_LIMIT_EXCEEDED",
  "limit": "keywords",
  "current": 500,
  "max": 500
}
```

---

## Frontend Handling

### Credit Balance Display

- Header shows current credit balance
- Updates after each operation
- Warning at low balance (< 10%)

### Pre-Operation Check

```typescript
import { checkCreditsBeforeOperation } from '@/utils/creditCheck';
import { useInsufficientCreditsModal } from '@/components/billing/InsufficientCreditsModal';

function ContentGenerator() {
  const { showModal } = useInsufficientCreditsModal();
  
  const handleGenerate = async () => {
    // Check credits before operation
    const check = await checkCreditsBeforeOperation(50); // estimated cost
    
    if (!check.hasEnoughCredits) {
      showModal({
        requiredCredits: check.requiredCredits,
        availableCredits: check.availableCredits,
      });
      return;
    }
    
    // Proceed with generation
    await generateContent();
  };
}
```

---

## API Endpoints

### Credit Balance

```
GET /api/v1/billing/balance/
```

Response:
```json
{
  "credits": 9500,
  "plan_credits_per_month": 10000,
  "credits_used_this_month": 500,
  "credits_remaining": 9500
}
```

### Usage Limits

```
GET /api/v1/billing/usage/limits/
```

Response:
```json
{
  "limits": {
    "sites": { "current": 2, "limit": 5, "type": "hard" },
    "users": { "current": 2, "limit": 3, "type": "hard" },
    "keywords": { "current": 847, "limit": 1000, "type": "hard" },
    "ahrefs_queries": { "current": 23, "limit": 50, "type": "monthly" }
  },
  "days_until_reset": 18
}
```

### Usage Analytics

```
GET /api/v1/account/usage/analytics/?days=30
```

Response:
```json
{
  "period_days": 30,
  "start_date": "2025-12-06",
  "end_date": "2026-01-05",
  "current_balance": 9500,
  "total_usage": 500,
  "total_purchases": 0,
  "usage_by_type": [
    { "transaction_type": "content_generation", "total": -350, "count": 15 },
    { "transaction_type": "image_generation", "total": -100, "count": 20 },
    { "transaction_type": "clustering", "total": -50, "count": 10 }
  ],
  "daily_usage": [
    { "date": "2026-01-05", "usage": 25, "purchases": 0, "net": -25 }
  ]
}
```

---

## Credit Allocation

Credits are added to `Account.credits` when:

1. **Subscription Renewal** - `Plan.included_credits` added monthly
2. **Payment Approval** - Manual payments approved by admin
3. **Credit Purchase** - Credit packages bought by user
4. **Admin Adjustment** - Manual credit grants/adjustments

### Monthly Reset

Monthly limits (Ahrefs queries) reset on billing cycle:

```python
# In Account model
def reset_monthly_usage(self):
    """Reset monthly usage counters (called on billing cycle renewal)"""
    self.usage_ahrefs_queries = 0
    self.save(update_fields=['usage_ahrefs_queries'])
```

---

## Admin Operations

### Manual Credit Adjustment

Via Django Admin or API:

```python
from igny8_core.business.billing.services.credit_service import CreditService

# Add credits
CreditService.add_credits(
    account=account,
    amount=1000,
    transaction_type='adjustment',
    description='Customer support adjustment'
)
```

### Usage Audit

All credit changes logged in `CreditTransaction` with:
- Timestamp
- Transaction type
- Amount (positive or negative)
- Balance after transaction
- Description

All AI operations logged in `CreditUsageLog` with:
- Operation type
- Credits used
- Model used
- Token counts
- Related object metadata

---

## Image Generation Credit System (v1.7.1)

### Implementation Details

**Files:**
- `CreditService.check_credits_for_image()` - [credit_service.py:307-335](../backend/igny8_core/business/billing/services/credit_service.py#L307-L335)
- `process_image_generation_queue` credit check - [tasks.py:290-319](../backend/igny8_core/ai/tasks.py#L290-L319)
- `deduct_credits_for_image()` - [tasks.py:745-770](../backend/igny8_core/ai/tasks.py#L745-L770)
- AITaskLog logging - [tasks.py:838-875](../backend/igny8_core/ai/tasks.py#L838-L875)
- Notifications - [tasks.py:877-895](../backend/igny8_core/ai/tasks.py#L877-L895)

### Credit Flow for Image Generation

```
1. User triggers image generation
   ↓
2. CreditService.check_credits_for_image(account, model, num_images)
   - Calculates: credits_per_image × num_images
   - Raises InsufficientCreditsError if balance < required
   ↓
3. process_image_generation_queue() processes each image
   ↓
4. For each successful image:
   CreditService.deduct_credits_for_image()
   - Creates CreditUsageLog entry
   - Creates CreditTransaction entry
   - Updates account.credits balance
   ↓
5. After all images processed:
   - AITaskLog entry created
   - Notification created (success or failure)
```

### Logging Locations

| Table | What's Logged | When |
|-------|---------------|------|
| CreditTransaction | Credit deduction (financial ledger) | Per image |
| CreditUsageLog | Usage details (model, cost, credits) | Per image |
| AITaskLog | Task execution summary | After batch |
| Notification | User notification | After batch |

### Automation Compatibility

Image generation credits work identically for:
- Manual image generation (from UI)
- Automation Stage 6 (scheduled/manual automation runs)

Both call `process_image_generation_queue` which handles:
- Credit checking before generation
- Credit deduction after each successful image
- Proper logging to all tables
