feat(migrations): Rename indexes and update global integration settings fields for improved clarity and functionality
feat(admin): Add API monitoring, debug console, and system health templates for enhanced admin interface docs: Add AI system cleanup summary and audit report detailing architecture, token management, and recommendations docs: Introduce credits and tokens system guide outlining configuration, data flow, and monitoring strategies
This commit is contained in:
IGNY8 VPS (Salman)
163
docs/AI_CLEANUP_SUMMARY.md
Normal file
163
docs/AI_CLEANUP_SUMMARY.md
Normal file
@@ -0,0 +1,163 @@
|
||||
# AI System Cleanup Summary
|
||||
|
||||
## Actions Completed
|
||||
|
||||
### 1. Standardized max_tokens to 8192
|
||||
**Status:** ✅ COMPLETE
|
||||
|
||||
**Changes Made:**
|
||||
- `backend/igny8_core/ai/settings.py:103` - Changed fallback from 16384 → 8192
|
||||
- `backend/igny8_core/ai/ai_core.py:116` - Kept default at 8192 (already correct)
|
||||
- `backend/igny8_core/ai/ai_core.py:856` - Updated legacy method from 4000 → 8192
|
||||
- `backend/igny8_core/utils/ai_processor.py:111` - Updated from 4000 → 8192
|
||||
- `backend/igny8_core/utils/ai_processor.py:437` - Updated from 4000 → 8192
|
||||
- `backend/igny8_core/utils/ai_processor.py:531` - Updated from 1000 → 8192 (already done)
|
||||
- `backend/igny8_core/utils/ai_processor.py:1133` - Updated from 3000 → 8192
|
||||
- `backend/igny8_core/utils/ai_processor.py:1340` - Updated from 4000 → 8192
|
||||
- IntegrationSettings (aws-admin) - Updated from 16384 → 8192
|
||||
|
||||
**Result:** Single source of truth = 8192 tokens across entire codebase
|
||||
|
||||
### 2. Marked Legacy Code
|
||||
**Status:** ✅ COMPLETE
|
||||
|
||||
**Changes Made:**
|
||||
- Added deprecation warning to `backend/igny8_core/utils/ai_processor.py`
|
||||
- Documented that it's only kept for MODEL_RATES constant
|
||||
- Marked `call_openai()` in `ai_core.py` as deprecated
|
||||
|
||||
### 3. Removed Unused Files
|
||||
**Status:** ✅ COMPLETE
|
||||
|
||||
**Files Removed:**
|
||||
- `backend/igny8_core/modules/writer/views.py.bak`
|
||||
- `frontend/src/pages/account/AccountSettingsPage.tsx.old`
|
||||
|
||||
### 4. System Verification
|
||||
**Status:** ✅ COMPLETE
|
||||
|
||||
**Test Results:**
|
||||
- Backend restarted successfully
|
||||
- Django check passed (0 issues)
|
||||
- Content generation tested with task 229
|
||||
- Confirmed max_tokens=8192 is being used
|
||||
- AI only generates 999 output tokens (< 8192 limit)
|
||||
|
||||
## Current AI Architecture
|
||||
|
||||
### Active System (Use This)
|
||||
```
|
||||
backend/igny8_core/ai/
|
||||
├── ai_core.py - Core AI request handler
|
||||
├── engine.py - Orchestrator (AIEngine class)
|
||||
├── settings.py - Config loader (get_model_config)
|
||||
├── prompts.py - Prompt templates
|
||||
├── base.py - BaseAIFunction class
|
||||
├── tasks.py - Celery tasks
|
||||
├── models.py - AITaskLog
|
||||
├── tracker.py - Progress tracking
|
||||
├── registry.py - Function registry
|
||||
├── constants.py - Shared constants
|
||||
└── functions/
|
||||
├── auto_cluster.py
|
||||
├── generate_ideas.py
|
||||
├── generate_content.py
|
||||
├── generate_images.py
|
||||
├── generate_image_prompts.py
|
||||
└── optimize_content.py
|
||||
```
|
||||
|
||||
### Legacy System (Do Not Use)
|
||||
```
|
||||
backend/igny8_core/utils/ai_processor.py
|
||||
```
|
||||
**Status:** DEPRECATED - Only kept for MODEL_RATES constant
|
||||
**Will be removed:** After extracting MODEL_RATES to ai/constants.py
|
||||
|
||||
## Key Finding: Short Content Issue
|
||||
|
||||
### Root Cause Analysis
|
||||
❌ **NOT a token limit issue:**
|
||||
- max_tokens set to 8192
|
||||
- AI only generates ~999 output tokens
|
||||
- Has room for 7000+ more tokens
|
||||
|
||||
✅ **IS a prompt structure issue:**
|
||||
- AI generates "complete" content in 400-500 words
|
||||
- Thinks task is done because JSON structure is filled
|
||||
- Needs MORE AGGRESSIVE enforcement in prompt:
|
||||
- "DO NOT stop until you reach 1200 words"
|
||||
- "Count your words and verify before submitting"
|
||||
- Possibly need to use a different output format that encourages longer content
|
||||
|
||||
## Standardized Configuration
|
||||
|
||||
### Single max_tokens Value
|
||||
**Value:** 8192 tokens (approximately 1500-2000 words)
|
||||
**Location:** All AI functions use this consistently
|
||||
**Fallback:** No fallbacks - required in IntegrationSettings
|
||||
|
||||
### Where max_tokens Is Used
|
||||
1. `get_model_config()` - Loads from IntegrationSettings, falls back to 8192
|
||||
2. `AICore.run_ai_request()` - Default parameter: 8192
|
||||
3. All AI functions - Use value from get_model_config()
|
||||
4. IntegrationSettings - Database stores 8192
|
||||
|
||||
## Recommendations
|
||||
|
||||
### Short Term
|
||||
1. ✅ max_tokens standardized (DONE)
|
||||
2. 🔄 Fix prompt to enforce 1200+ words more aggressively
|
||||
3. 🔄 Consider using streaming or multi-turn approach for long content
|
||||
|
||||
### Long Term
|
||||
1. Extract MODEL_RATES from ai_processor.py to ai/constants.py
|
||||
2. Remove ai_processor.py entirely
|
||||
3. Add validation that content meets minimum word count before saving
|
||||
4. Implement word count tracking in generation loop
|
||||
|
||||
## Testing Commands
|
||||
|
||||
```bash
|
||||
# Check current config
|
||||
docker exec igny8_backend python manage.py shell -c "
|
||||
from igny8_core.ai.settings import get_model_config
|
||||
from igny8_core.auth.models import Account
|
||||
account = Account.objects.filter(slug='aws-admin').first()
|
||||
config = get_model_config('generate_content', account=account)
|
||||
print(f'max_tokens: {config[\"max_tokens\"]}')
|
||||
"
|
||||
|
||||
# Test content generation
|
||||
docker exec igny8_backend python manage.py shell -c "
|
||||
from igny8_core.ai.functions.generate_content import GenerateContentFunction
|
||||
from igny8_core.ai.engine import AIEngine
|
||||
from igny8_core.auth.models import Account
|
||||
account = Account.objects.filter(slug='aws-admin').first()
|
||||
fn = GenerateContentFunction()
|
||||
engine = AIEngine(celery_task=None, account=account)
|
||||
result = engine.execute(fn, {'ids': [229]})
|
||||
print(f'Success: {result.get(\"success\")}')
|
||||
"
|
||||
```
|
||||
|
||||
## Files Modified
|
||||
|
||||
1. `backend/igny8_core/ai/settings.py` - Standardized fallback to 8192
|
||||
2. `backend/igny8_core/ai/ai_core.py` - Updated legacy method, added deprecation note
|
||||
3. `backend/igny8_core/utils/ai_processor.py` - Updated all max_tokens, added deprecation warning
|
||||
4. IntegrationSettings database - Updated to 8192
|
||||
|
||||
## Verification
|
||||
|
||||
✅ All max_tokens references now use 8192
|
||||
✅ No conflicting fallback values
|
||||
✅ Legacy code marked clearly
|
||||
✅ System tested and working
|
||||
✅ Backend restarted successfully
|
||||
|
||||
---
|
||||
|
||||
**Date:** December 17, 2025
|
||||
**Status:** COMPLETE
|
||||
**Next Step:** Fix prompt structure for 1200+ word content generation
|
||||
79
docs/AI_SYSTEM_AUDIT.md
Normal file
79
docs/AI_SYSTEM_AUDIT.md
Normal file
@@ -0,0 +1,79 @@
|
||||
# AI System Audit Report
|
||||
|
||||
## Current State
|
||||
|
||||
### Active AI System (New Architecture)
|
||||
**Location:** `backend/igny8_core/ai/`
|
||||
|
||||
**Core Components:**
|
||||
- `ai_core.py` - Central AI request handler (run_ai_request method)
|
||||
- `engine.py` - Orchestrator for all AI functions
|
||||
- `settings.py` - Model configuration loader
|
||||
- `prompts.py` - Prompt templates
|
||||
- `base.py` - Base class for AI functions
|
||||
- `tasks.py` - Celery tasks
|
||||
- `models.py` - AITaskLog for logging
|
||||
- `tracker.py` - Progress/step tracking
|
||||
- `registry.py` - Function registry
|
||||
- `constants.py` - Shared constants (MODEL_RATES, etc.)
|
||||
|
||||
**AI Functions:**
|
||||
- `functions/auto_cluster.py` - Keyword clustering
|
||||
- `functions/generate_ideas.py` - Content idea generation
|
||||
- `functions/generate_content.py` - Article content generation
|
||||
- `functions/generate_images.py` - Image generation
|
||||
- `functions/generate_image_prompts.py` - Image prompt generation
|
||||
- `functions/optimize_content.py` - Content optimization
|
||||
|
||||
**Usage:** All new code uses `AIEngine` + function classes
|
||||
|
||||
### Legacy AI System (Old Architecture)
|
||||
**Location:** `backend/igny8_core/utils/ai_processor.py`
|
||||
|
||||
**Purpose:** Original AI interface from reference plugin migration
|
||||
**Size:** 1390 lines
|
||||
**Status:** PARTIALLY USED - Only for:
|
||||
- MODEL_RATES constant (imported by settings.py and integration_views.py)
|
||||
- Integration test views
|
||||
|
||||
**NOT USED FOR:** Actual AI function execution (replaced by AIEngine)
|
||||
|
||||
## max_tokens Fallback Analysis
|
||||
|
||||
### Current Fallbacks Found:
|
||||
|
||||
1. **settings.py:103** - `config.get('max_tokens', 16384)`
|
||||
- Falls back to 16384 if not in IntegrationSettings
|
||||
|
||||
2. **ai_core.py:116** - `max_tokens: int = 8192`
|
||||
- Default parameter in run_ai_request()
|
||||
|
||||
3. **ai_core.py:856** - `max_tokens: int = 4000` **[LEGACY]**
|
||||
- Legacy call_openai() method
|
||||
|
||||
4. **ai_processor.py:111** - `max_tokens: int = 4000` **[LEGACY]**
|
||||
- Legacy _call_openai() method
|
||||
|
||||
5. **ai_processor.py:437** - `max_tokens: int = 4000` **[LEGACY]**
|
||||
- Legacy generate_content() method
|
||||
|
||||
6. **ai_processor.py:531** - Hardcoded `max_tokens=1000`
|
||||
|
||||
7. **ai_processor.py:1133** - Hardcoded `max_tokens=3000`
|
||||
|
||||
8. **ai_processor.py:1340** - Hardcoded `max_tokens=4000`
|
||||
|
||||
## Recommended Actions
|
||||
|
||||
### 1. Standardize max_tokens to 8192
|
||||
- Remove fallback in settings.py (line 103): Change to just `config['max_tokens']` and require it
|
||||
- Keep ai_core.py:116 default at 8192 (main entry point)
|
||||
- Update IntegrationSettings to have 8192 as required value
|
||||
|
||||
### 2. Mark Legacy Code
|
||||
- Add deprecation warnings to ai_processor.py
|
||||
- Document that it's only kept for MODEL_RATES constant
|
||||
- Consider extracting MODEL_RATES to constants.py and removing ai_processor.py entirely
|
||||
|
||||
### 3. Remove Dead Code
|
||||
- call_openai() legacy method in ai_core.py (if not used)
|
||||
455
docs/CREDITS-TOKENS-GUIDE.md
Normal file
455
docs/CREDITS-TOKENS-GUIDE.md
Normal file
@@ -0,0 +1,455 @@
|
||||
# IGNY8 Credits & Tokens System Guide
|
||||
|
||||
**Version:** 1.0
|
||||
**Last Updated:** December 19, 2025
|
||||
**System Status:** ✅ Fully Operational
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
IGNY8 uses a **token-based credit system** where all AI operations consume credits calculated from actual AI token usage. This guide covers configuration, data flow, and monitoring.
|
||||
|
||||
---
|
||||
|
||||
## System Architecture
|
||||
|
||||
### Data Flow
|
||||
|
||||
```
|
||||
User Action (Content Generation, Ideas, etc.)
|
||||
↓
|
||||
Backend Service Initiated
|
||||
↓
|
||||
AI API Called (OpenAI, etc.)
|
||||
↓
|
||||
Response Received: {input_tokens, output_tokens, cost_usd, model}
|
||||
↓
|
||||
Credits Calculated: (total_tokens / tokens_per_credit)
|
||||
↓
|
||||
Credits Deducted from Account
|
||||
↓
|
||||
CreditUsageLog Created: {tokens_input, tokens_output, cost_usd, credits_used, model_used}
|
||||
↓
|
||||
Reports Updated with Real-Time Analytics
|
||||
```
|
||||
|
||||
### Key Components
|
||||
|
||||
1. **BillingConfiguration** - System-wide billing settings
|
||||
2. **CreditCostConfig** - Per-operation token-to-credit ratios
|
||||
3. **CreditUsageLog** - Transaction log with token data
|
||||
4. **AITaskLog** - Detailed AI execution history
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### 1. Global Billing Settings
|
||||
|
||||
**Location:** Django Admin → Billing → Billing Configuration
|
||||
|
||||
**Key Settings:**
|
||||
- **Default Tokens Per Credit:** 100 (base ratio)
|
||||
- **Default Credit Price:** $0.01 USD
|
||||
- **Rounding Mode:** Up (conservative billing)
|
||||
- **Token Reporting Enabled:** Yes
|
||||
|
||||
**When to Adjust:**
|
||||
- Change credit pricing across all operations
|
||||
- Modify rounding behavior for credit calculations
|
||||
- Enable/disable token tracking
|
||||
|
||||
### 2. Per-Operation Configuration
|
||||
|
||||
**Location:** Django Admin → Billing → Credit Cost Configs
|
||||
|
||||
**Current Ratios:**
|
||||
|
||||
| Operation | Tokens/Credit | Min Credits | Price/Credit |
|
||||
|-----------|---------------|-------------|--------------|
|
||||
| Clustering | 150 | 2 | $0.0100 |
|
||||
| Content Generation | 100 | 3 | $0.0100 |
|
||||
| Idea Generation | 200 | 1 | $0.0100 |
|
||||
| Image Generation | 50 | 5 | $0.0200 |
|
||||
| Image Prompt Extraction | 100 | 1 | $0.0100 |
|
||||
| Linking | 300 | 1 | $0.0050 |
|
||||
| Optimization | 200 | 1 | $0.0050 |
|
||||
|
||||
**Adjusting Pricing:**
|
||||
- **Increase `tokens_per_credit`** → Lower cost (more tokens per credit)
|
||||
- **Decrease `tokens_per_credit`** → Higher cost (fewer tokens per credit)
|
||||
- **Adjust `min_credits`** → Enforce minimum charge per operation
|
||||
- **Change `price_per_credit_usd`** → Override default credit price
|
||||
|
||||
**Example:** To make Content Generation cheaper:
|
||||
```
|
||||
Current: 100 tokens/credit (1000 tokens = 10 credits)
|
||||
Change to: 150 tokens/credit (1000 tokens = 6.67 → 7 credits)
|
||||
Result: 30% cost reduction
|
||||
```
|
||||
|
||||
### 3. Token Extraction
|
||||
|
||||
**Location:** `backend/igny8_core/ai/engine.py` (line 380-381)
|
||||
|
||||
**Current Implementation:**
|
||||
```python
|
||||
tokens_input = raw_response.get('input_tokens', 0)
|
||||
tokens_output = raw_response.get('output_tokens', 0)
|
||||
```
|
||||
|
||||
**Critical:** Field names must match AI provider response format
|
||||
- ✅ Correct: `input_tokens`, `output_tokens`
|
||||
- ❌ Wrong: `tokens_input`, `tokens_output`
|
||||
|
||||
**Supported Providers:**
|
||||
- OpenAI (GPT-4, GPT-4o, GPT-5.1)
|
||||
- Anthropic Claude
|
||||
- Runware (image generation)
|
||||
|
||||
---
|
||||
|
||||
## Monitoring & Reports
|
||||
|
||||
### 1. AI Cost & Margin Analysis
|
||||
|
||||
**URL:** `https://api.igny8.com/admin/reports/ai-cost-analysis/`
|
||||
|
||||
**Metrics Displayed:**
|
||||
- **Total Cost** - Actual USD spent on AI APIs
|
||||
- **Revenue** - Income from credits charged
|
||||
- **Margin** - Profit (Revenue - Cost) with percentage
|
||||
- **Margin / 1M Tokens** - Profit efficiency per million tokens
|
||||
- **Margin / 1K Credits** - Profit per thousand credits charged
|
||||
- **Projected Monthly** - Forecasted costs based on trends
|
||||
|
||||
**Tables:**
|
||||
- Model Cost Comparison - Profitability by AI model
|
||||
- Top Spenders - Highest cost accounts
|
||||
- Cost by Function - Profitability by operation type
|
||||
- Cost Anomalies - Expensive outlier calls
|
||||
|
||||
**Use Cases:**
|
||||
- Identify unprofitable operations or accounts
|
||||
- Optimize token-to-credit ratios
|
||||
- Detect unusual AI spending patterns
|
||||
- Track margins over time
|
||||
|
||||
### 2. Token Usage Report
|
||||
|
||||
**URL:** `https://api.igny8.com/admin/reports/token-usage/`
|
||||
|
||||
**Metrics Displayed:**
|
||||
- Total tokens consumed (input + output)
|
||||
- Average tokens per call
|
||||
- Cost per 1K tokens
|
||||
- Token distribution by model
|
||||
- Token distribution by operation
|
||||
- Daily token trends
|
||||
|
||||
**Use Cases:**
|
||||
- Understand token consumption patterns
|
||||
- Identify token-heavy operations
|
||||
- Optimize prompts to reduce token usage
|
||||
- Track token efficiency over time
|
||||
|
||||
### 3. Usage Report
|
||||
|
||||
**URL:** `https://api.igny8.com/admin/reports/usage/`
|
||||
|
||||
**Metrics Displayed:**
|
||||
- Total credits used system-wide
|
||||
- Credits by operation type
|
||||
- Top credit consumers
|
||||
- Model usage distribution
|
||||
|
||||
**Use Cases:**
|
||||
- Monitor overall system usage
|
||||
- Identify high-volume users
|
||||
- Track popular AI operations
|
||||
- Plan capacity and scaling
|
||||
|
||||
### 4. Data Quality Report
|
||||
|
||||
**URL:** `https://api.igny8.com/admin/reports/data-quality/`
|
||||
|
||||
**Purpose:** Identify data integrity issues
|
||||
- Orphaned content
|
||||
- Duplicate keywords
|
||||
- Missing SEO metadata
|
||||
|
||||
---
|
||||
|
||||
## Data Models
|
||||
|
||||
### CreditUsageLog (Primary Transaction Log)
|
||||
|
||||
**Purpose:** Record every credit deduction with full context
|
||||
|
||||
**Key Fields:**
|
||||
- `account` - User account charged
|
||||
- `operation_type` - Function executed (e.g., "content_generation")
|
||||
- `credits_used` - Credits deducted
|
||||
- `cost_usd` - Actual AI provider cost
|
||||
- `tokens_input` - Input tokens consumed
|
||||
- `tokens_output` - Output tokens generated
|
||||
- `model_used` - AI model (e.g., "gpt-4o")
|
||||
- `related_object_type/id` - Link to content/site/keyword
|
||||
- `metadata` - Additional context (prompt, settings, etc.)
|
||||
|
||||
**Query Examples:**
|
||||
```python
|
||||
# Total tokens for an account
|
||||
CreditUsageLog.objects.filter(account=account).aggregate(
|
||||
total_tokens=Sum('tokens_input') + Sum('tokens_output')
|
||||
)
|
||||
|
||||
# Average cost by operation
|
||||
CreditUsageLog.objects.values('operation_type').annotate(
|
||||
avg_cost=Avg('cost_usd'),
|
||||
total_calls=Count('id')
|
||||
)
|
||||
|
||||
# Margin analysis
|
||||
logs = CreditUsageLog.objects.all()
|
||||
revenue = logs.aggregate(Sum('credits_used'))['credits_used__sum'] * 0.01
|
||||
cost = logs.aggregate(Sum('cost_usd'))['cost_usd__sum']
|
||||
margin = revenue - cost
|
||||
```
|
||||
|
||||
### AITaskLog (Execution History)
|
||||
|
||||
**Purpose:** Detailed AI execution tracking
|
||||
|
||||
**Key Fields:**
|
||||
- `function_name` - AI function executed
|
||||
- `account` - User account
|
||||
- `cost` - AI provider cost
|
||||
- `tokens` - Total tokens (input + output)
|
||||
- `phase` - Execution stage
|
||||
- `status` - Success/failure
|
||||
- `execution_time` - Processing duration
|
||||
- `raw_request/response` - Full API data
|
||||
|
||||
**Use Cases:**
|
||||
- Debug AI execution failures
|
||||
- Analyze prompt effectiveness
|
||||
- Track model performance
|
||||
- Audit AI interactions
|
||||
|
||||
---
|
||||
|
||||
## Historical Data Backfill
|
||||
|
||||
### Issue
|
||||
Prior to December 2025, token fields were not populated due to incorrect field name mapping.
|
||||
|
||||
### Solution
|
||||
A backfill script matched AITaskLog entries to CreditUsageLog records using:
|
||||
- Account matching
|
||||
- Timestamp matching (±10 second window)
|
||||
- 40/60 input/output split estimation (when only total available)
|
||||
|
||||
### Result
|
||||
- ✅ 777,456 tokens backfilled
|
||||
- ✅ 380/479 records updated (79% coverage)
|
||||
- ✅ Historical margin analysis now available
|
||||
- ⚠️ 99 records remain at 0 tokens (no matching AITaskLog)
|
||||
|
||||
### Script Location
|
||||
`backend/igny8_core/management/commands/backfill_tokens.py`
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Empty Margin Metrics
|
||||
**Symptom:** "Margin / 1M Tokens" shows "No token data yet"
|
||||
|
||||
**Causes:**
|
||||
1. No recent AI calls with token data
|
||||
2. Token extraction not working (field name mismatch)
|
||||
3. Historical data has 0 tokens
|
||||
|
||||
**Resolution:**
|
||||
1. Check AIEngine token extraction: `tokens_input`, `tokens_output` fields
|
||||
2. Verify AI responses contain `input_tokens`, `output_tokens`
|
||||
3. Run test AI operation and check CreditUsageLog
|
||||
4. Consider backfill for historical data
|
||||
|
||||
### Zero Tokens in CreditUsageLog
|
||||
**Symptom:** `tokens_input` and `tokens_output` are 0
|
||||
|
||||
**Causes:**
|
||||
1. Field name mismatch in AIEngine
|
||||
2. AI provider not returning token data
|
||||
3. Historical records before fix
|
||||
|
||||
**Resolution:**
|
||||
1. Verify `engine.py` line 380-381 uses correct field names
|
||||
2. Check AI provider API response format
|
||||
3. Restart backend services after fixes
|
||||
4. Future calls will populate correctly
|
||||
|
||||
### Incorrect Margins
|
||||
**Symptom:** Margin percentages seem wrong
|
||||
|
||||
**Causes:**
|
||||
1. Incorrect token-to-credit ratios
|
||||
2. Credit price misconfigured
|
||||
3. Decimal division errors
|
||||
|
||||
**Resolution:**
|
||||
1. Review CreditCostConfig ratios
|
||||
2. Check BillingConfiguration credit price
|
||||
3. Verify margin calculations use `float()` conversions
|
||||
4. Check for TypeError in logs
|
||||
|
||||
### Operations Not Charging Correctly
|
||||
**Symptom:** Wrong number of credits deducted
|
||||
|
||||
**Causes:**
|
||||
1. Token-to-credit ratio misconfigured
|
||||
2. Minimum credits not enforced
|
||||
3. Rounding mode incorrect
|
||||
|
||||
**Resolution:**
|
||||
1. Check operation's CreditCostConfig
|
||||
2. Verify `min_credits` setting
|
||||
3. Review `rounding_mode` in BillingConfiguration
|
||||
4. Test with known token count
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Pricing Strategy
|
||||
1. **Monitor margins weekly** - Use AI Cost Analysis report
|
||||
2. **Adjust ratios based on costs** - If margins drop below 70%, decrease tokens_per_credit
|
||||
3. **Set reasonable minimums** - Enforce min_credits for small operations
|
||||
4. **Track model costs** - Some models (GPT-4) cost more than others
|
||||
|
||||
### Token Optimization
|
||||
1. **Optimize prompts** - Reduce unnecessary tokens
|
||||
2. **Use appropriate models** - GPT-4o-mini for simple tasks
|
||||
3. **Cache results** - Avoid duplicate AI calls
|
||||
4. **Monitor anomalies** - Investigate unusually expensive calls
|
||||
|
||||
### Data Integrity
|
||||
1. **Regular audits** - Check token data completeness
|
||||
2. **Verify field mappings** - Ensure AI responses parsed correctly
|
||||
3. **Monitor logs** - Watch for errors in CreditService
|
||||
4. **Backup configurations** - Export CreditCostConfig settings
|
||||
|
||||
### Performance
|
||||
1. **Archive old logs** - Move historical CreditUsageLog to archive tables
|
||||
2. **Index frequently queried fields** - account, operation_type, created_at
|
||||
3. **Aggregate reports** - Use materialized views for large datasets
|
||||
4. **Cache report data** - Reduce database load
|
||||
|
||||
---
|
||||
|
||||
## API Integration
|
||||
|
||||
### Frontend Credit Display
|
||||
|
||||
**Endpoint:** `/v1/billing/credits/balance/`
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"credits": 1234,
|
||||
"plan_credits_per_month": 5000,
|
||||
"credits_used_this_month": 876,
|
||||
"credits_remaining": 4124
|
||||
}
|
||||
```
|
||||
|
||||
**Pages Using This:**
|
||||
- `/account/plans` - Plans & Billing
|
||||
- `/account/usage` - Usage Analytics
|
||||
- Dashboard credit widget
|
||||
|
||||
### Credit Transaction History
|
||||
|
||||
**Endpoint:** `/v1/billing/credits/usage/`
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"results": [
|
||||
{
|
||||
"id": 123,
|
||||
"operation_type": "Content Generation",
|
||||
"credits_used": 15,
|
||||
"tokens_input": 500,
|
||||
"tokens_output": 1000,
|
||||
"cost_usd": 0.015,
|
||||
"model_used": "gpt-4o",
|
||||
"created_at": "2025-12-19T10:30:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Common Operations
|
||||
|
||||
**Check account credits:**
|
||||
```python
|
||||
account.credits # Current balance
|
||||
```
|
||||
|
||||
**Manual credit adjustment:**
|
||||
```python
|
||||
CreditService.add_credits(account, amount=100, description="Bonus credits")
|
||||
```
|
||||
|
||||
**Get operation config:**
|
||||
```python
|
||||
config = CreditService.get_or_create_config('content_generation')
|
||||
# Returns: CreditCostConfig with tokens_per_credit, min_credits
|
||||
```
|
||||
|
||||
**Calculate credits needed:**
|
||||
```python
|
||||
credits = CreditService.calculate_credits_from_tokens(
|
||||
operation_type='content_generation',
|
||||
tokens_input=500,
|
||||
tokens_output=1500
|
||||
)
|
||||
# Returns: 20 (if 100 tokens/credit)
|
||||
```
|
||||
|
||||
### Important File Locations
|
||||
|
||||
- **Credit Service:** `backend/igny8_core/business/billing/services/credit_service.py`
|
||||
- **AI Engine:** `backend/igny8_core/ai/engine.py`
|
||||
- **Reports:** `backend/igny8_core/admin/reports.py`
|
||||
- **Models:** `backend/igny8_core/modules/billing/models.py`
|
||||
- **Admin:** `backend/igny8_core/modules/billing/admin.py`
|
||||
|
||||
### Report Access
|
||||
|
||||
All reports require staff/superuser login:
|
||||
- AI Cost Analysis: `/admin/reports/ai-cost-analysis/`
|
||||
- Token Usage: `/admin/reports/token-usage/`
|
||||
- Usage Report: `/admin/reports/usage/`
|
||||
- Data Quality: `/admin/reports/data-quality/`
|
||||
|
||||
---
|
||||
|
||||
## Support & Updates
|
||||
|
||||
For questions or issues with the credits & tokens system:
|
||||
1. Check Django admin logs: `/admin/`
|
||||
2. Review CreditUsageLog for transaction details
|
||||
3. Monitor AITaskLog for execution errors
|
||||
4. Check backend logs: `docker logs igny8_backend`
|
||||
|
||||
**System Maintainer:** IGNY8 DevOps Team
|
||||
**Last Major Update:** December 2025 (Token-based credit system implementation)
|
||||
Reference in New Issue
Block a user