igny8/4th-jan-refactor/REFACTOR-OVERVIEW.md

AI Configuration Refactor - Master Overview

Created: January 4, 2026
Goal: Clean, unified AI configuration with single source of truth

---

Documentation Files

File	Purpose
REFACTOR-OVERVIEW.md	This file - master overview
implementation-plan-for-ai-models-and-cost.md	Detailed implementation plan with schema changes
safe-migration-and-testing-plan.md	Testing strategy and verification steps

---

What We're Fixing

Current Problems

1. Duplicate configuration sources

   • AIModelConfig (database) has model definitions
   • GlobalIntegrationSettings (database) has hardcoded CHOICES duplicating the same info
   • constants.py has MODEL_RATES and IMAGE_MODEL_RATES hardcoded
   • Frontend Settings.tsx has hardcoded model choices

2. Broken/inconsistent data

   • GlobalIntegrationSettings.runware_model = "bria:10@1" but this model doesn't exist
   • GlobalIntegrationSettings.openai_model = "gpt-4o-mini" but default should be gpt-5.1

3. API keys mixed with model config

   • GlobalIntegrationSettings stores both API keys and model preferences
   • No separation of concerns
   • Can't easily extend to other integrations (email, payment, etc.)

4. Credit calculation scattered

   • CreditCostConfig for token-based operations
   • ModelRegistry.calculate_cost() for image costs
   • No clear per-model credit rate

---

Target State

Single Source of Truth

IntegrationProvider (NEW)
├── openai (api_key, active)
├── runware (api_key, active)
├── resend (api_key, active) ← future
├── stripe (api_key, webhook_secret, active) ← future
└── ...

AIModelConfig (ENHANCED)
├── Text Models
│   ├── gpt-5.1 (is_default=true, tokens_per_credit=1000)
│   ├── gpt-4o (tokens_per_credit=1000)
│   └── gpt-4o-mini (tokens_per_credit=10000)
└── Image Models
    ├── runware:97@1 (credits_per_image=1, quality_tier=basic)
    ├── dall-e-3 (is_default=true, credits_per_image=5, quality_tier=quality)
    └── google:4@2 (credits_per_image=15, quality_tier=premium)

No More Hardcoding

• Backend: Remove MODEL_RATES, IMAGE_MODEL_RATES from constants.py
• Backend: Remove hardcoded CHOICES from GlobalIntegrationSettings
• Backend: ModelRegistry always uses database, no fallbacks
• Frontend: Load model choices from API endpoint

Clear Credit Calculation

Model Type	How Credits Calculated
Text	ceil(total_tokens / tokens_per_credit) from AIModelConfig
Image	credits_per_image * num_images from AIModelConfig

---

Migration Phases Summary

Phase	What Changes	Risk	Rollback
1	Add new models/fields	None - additive only	Drop new tables
2	Add parallel code paths	Low - old code untouched	Remove new methods
3	IntegrationProvider for keys	Medium - API key loading	Revert key loading
4	Switch to new credit calc	Medium - financial impact	Revert credit service
5	Create API endpoint	None - new endpoint	Remove endpoint
6	Update frontend	Low - UI only	Revert frontend
7	Cleanup legacy code	High if bugs found	Restore from backup

Rule: Run full test suite after EACH phase before proceeding.

---

Files Being Modified

Backend Files

File	Changes
billing/models.py	Add IntegrationProvider, add fields to AIModelConfig
ai/model_registry.py	Add get_default_model(), remove constants fallback
ai/ai_core.py	Use IntegrationProvider for API keys
ai/constants.py	Remove MODEL_RATES, IMAGE_MODEL_RATES
billing/services/credit_service.py	Model-based credit calculation
modules/system/global_settings_models.py	Remove API keys, hardcoded choices
api/views/system.py	Add /api/v1/system/ai-models/ endpoint

Frontend Files

File	Changes
src/pages/Sites/Settings.tsx	Load models from API, remove hardcodes

New Files

File	Purpose
tests/test_ai_system_integration.py	Integration tests for migration

---

Credit Values (Final)

Text Models (per 1 credit)

Model	Tokens per Credit	Example: 5000 tokens
gpt-5.1	1,000	5 credits
gpt-4o	1,000	5 credits
gpt-4o-mini	10,000	1 credit

Image Models (per image)

Model	Credits per Image	UI Display
runware:97@1	1	"Basic (1 credit/image)"
dall-e-3	5	"Quality (5 credits/image)"
google:4@2	15	"Premium (15 credits/image)"

---

Execution Paths That Must Keep Working

All these paths use the same AI functions and must work identically after migration:

1. Manual Buttons (Planner/Writer pages)

   • Cluster Keywords → auto_cluster
   • Generate Ideas → generate_ideas
   • Generate Content → generate_content
   • Extract Prompts → generate_image_prompts
   • Generate Images → generate_images

2. Automation Manual Run (Automation page → Run Now)

   • Same AI functions called via AutomationService

3. Scheduled Automation (Celery Beat scheduler)

   • Same AI functions called via scheduled tasks

4. Direct Services (Linker, Optimizer modules)

   • Use CreditService directly for credit deduction

---

Success Criteria

Migration is COMPLETE when:

• All integration tests pass
• All manual test checklist items pass
• No errors in production logs for 1 week
• Credit calculations match expected values
• All execution paths work (manual, automation, scheduled)
• Frontend loads models dynamically from API
• No legacy code remains:
  • No MODEL_RATES / IMAGE_MODEL_RATES in constants.py
  • No API keys in GlobalIntegrationSettings
  • No hardcoded models in frontend
  • No fallback to constants in ModelRegistry
  • No unused fields in GlobalIntegrationSettings

---

Quick Reference Commands

# Run integration tests
docker exec igny8_backend python manage.py test igny8_core.tests.test_ai_system_integration -v 2

# Check AIModelConfig
docker exec igny8_backend python manage.py shell -c "
from igny8_core.business.billing.models import AIModelConfig
for m in AIModelConfig.objects.all().order_by('model_type'):
    print(f'{m.model_name}: {m.model_type}, default={m.is_default}')
"

# Check recent credit usage
docker exec igny8_backend python manage.py shell -c "
from igny8_core.business.billing.models import CreditUsageLog
for log in CreditUsageLog.objects.order_by('-created_at')[:10]:
    print(f'{log.operation_type}: {log.credits_used} credits')
"

# Check account credits
docker exec igny8_backend python manage.py shell -c "
from igny8_core.auth.models import Account
for acc in Account.objects.all():
    print(f'{acc.name}: {acc.credits} credits')
"