igny8/05_GLOBAL-SETTINGS-CORRECT-IMPLEMENTATION.md

GLOBAL SETTINGS - CORRECT IMPLEMENTATION

Date: December 20, 2025
Status: ✅ FIXED AND WORKING

---

WHAT WAS WRONG

The initial implementation had:

• AccountIntegrationOverride model allowing users to use their own API keys
• Enterprise plan that doesn't exist
• Confusing override logic where accounts could bring their own API keys

WHAT IS NOW CORRECT

Architecture

1. Plans (Only 4 Valid):

• Free Plan - Cannot override anything, uses global defaults
• Starter Plan - Can override model/settings
• Growth Plan - Can override model/settings
• Scale Plan - Can override model/settings

2. API Keys (Platform-Wide):

• Stored in GlobalIntegrationSettings (singleton, pk=1)
• ALL accounts use platform API keys
• NO user can bring their own API keys
• NO exceptions for any plan level

3. Model & Parameter Overrides (Per-Account):

• Stored in IntegrationSettings model (per-account)
• Free plan: CANNOT create overrides
• Starter/Growth/Scale: CAN override model, temperature, max_tokens, image settings
• NULL values in config = use global default
• API keys NEVER stored here

4. Prompts (Global + Override):

• GlobalAIPrompt: Platform-wide default prompts
• AIPrompt: Per-account with default_prompt field
• When user customizes: prompt_value changes, default_prompt stays same
• Reset to default: Copies default_prompt back to prompt_value
• is_customized flag tracks if using custom or default

---

WHERE TO FIND SETTINGS IN DJANGO ADMIN

1. Global Integration Settings

URL: /admin/system/globalintegrationsettings/

What It Stores:

• Platform OpenAI API key (used by ALL accounts)
• Platform DALL-E API key (used by ALL accounts)
• Platform Anthropic API key (used by ALL accounts)
• Platform Runware API key (used by ALL accounts)
• Default model selections for each service
• Default parameters (temperature, max_tokens, image quality, etc.)

Important:

• Singleton model (only 1 record, pk=1)
• Changes affect ALL accounts using global defaults
• Free plan accounts MUST use these (cannot override)
• Other plans can override model/params but NOT API keys

2. Integration Settings (Per-Account Overrides)

URL: /admin/system/integrationsettings/

What It Stores:

• Per-account model selection overrides
• Per-account parameter overrides (temperature, max_tokens, etc.)
• Per-account image setting overrides (size, quality, style)

What It DOES NOT Store:

• API keys (those come from global)

Who Can Create:

• Starter/Growth/Scale plans only
• Free plan users cannot create these

How It Works:

• If account has IntegrationSettings record with config values → uses those
• If config field is NULL or missing → uses global default
• API key ALWAYS from GlobalIntegrationSettings

Example Config:

{
  "model": "gpt-4",
  "temperature": 0.8,
  "max_tokens": 4000
}

3. Global AI Prompts

URL: /admin/system/globalaiprompt/

What It Stores:

• Platform-wide default prompt templates
• Used for: clustering, ideas, content_generation, etc.

How Accounts Use Them:

• All accounts start with global prompts
• When user wants to customize, system creates AIPrompt record
• AIPrompt.default_prompt = GlobalAIPrompt.prompt_value (for reset)
• AIPrompt.prompt_value = user's custom text
• AIPrompt.is_customized = True

4. AI Prompts (Per-Account)

URL: /admin/system/aiprompt/

What It Stores:

• Account-specific prompt customizations
• default_prompt field = global default (for reset)
• prompt_value = current prompt (custom or default)
• is_customized = True if user modified it

Actions Available:

• "Reset selected prompts to global default" - Copies default_prompt → prompt_value, sets is_customized=False

---

HOW IT WORKS (Complete Flow)

Text Generation Request

1. Code calls: get_model_config(function_name='generate_content', account=some_account)

2. System gets API key from GlobalIntegrationSettings:

   • global_settings = GlobalIntegrationSettings.get_instance()
   • api_key = global_settings.openai_api_key # ALWAYS from global

3. System checks for account overrides:

   • Try to find IntegrationSettings for this account + integration_type='openai'
   • If found: Use config['model'], config['temperature'], config['max_tokens']
   • If not found OR config field is NULL: Use global defaults

4. Result returned:

   {
       'api_key': 'sk-xxx',  # Always from global
       'model': 'gpt-4',  # From account override OR global
       'temperature': 0.8,  # From account override OR global  
       'max_tokens': 4000  # From account override OR global
   }
   

Prompt Retrieval

1. Code calls: AIPrompt.get_effective_prompt(account=some_account, prompt_type='clustering')

2. System checks for account-specific prompt:

   • Try to find AIPrompt for this account + prompt_type
   • If found and is_customized=True: Return prompt_value
   • If found and is_customized=False: Return default_prompt

3. If no account prompt found:

   • Get GlobalAIPrompt for prompt_type
   • Return global prompt_value

User Customizes a Prompt

1. User edits prompt in frontend
2. Frontend saves to AIPrompt model:
   • If AIPrompt doesn't exist: Create new record
   • Set default_prompt = GlobalAIPrompt.prompt_value (for future reset)
   • Set prompt_value = user's custom text
   • Set is_customized = True

User Resets Prompt

1. User clicks "Reset to Default"
2. System calls: AIPrompt.reset_to_default()
3. Method does:
   • prompt_value = default_prompt
   • is_customized = False
   • save()

---

MIGRATION APPLIED

File: 0004_fix_global_settings_remove_override.py

Changes:

• Added default_prompt field to AIPrompt model
• Updated help text on IntegrationSettings.config field
• Updated integration_type choices (removed GSC, image_generation)
• Updated GlobalIntegrationSettings help text
• Removed AccountIntegrationOverride model

---

ADMIN INTERFACE CHANGES

GlobalIntegrationSettings Admin:

• Shows all platform API keys and default settings
• One record only (singleton)
• Help text clarifies these are used by ALL accounts

IntegrationSettings Admin:

• Help text emphasizes: "NEVER store API keys here"
• Config field description explains it's for overrides only
• Removed bulk_test_connection action
• Free plan check should be added to prevent creation

AIPrompt Admin:

• Added default_prompt to readonly_fields
• Added "Reset selected prompts to global default" bulk action
• Fieldsets show both prompt_value and default_prompt

Removed:

• AccountIntegrationOverride model
• AccountIntegrationOverrideAdmin class
• All references to per-account API keys

---

SIDEBAR NAVIGATION (TODO)

Need to add links in app sidebar to access global settings:

For Superusers/Admin:

• Global Settings
  • Platform API Keys (/admin/system/globalintegrationsettings/)
  • Global Prompts (/admin/system/globalaiprompt/)
  • Global Author Profiles (/admin/system/globalauthorprofile/)
  • Global Strategies (/admin/system/globalstrategy/)

For All Users (Starter+ plans):

• Account Settings
  • AI Model Selection (/settings/ai) - Configure IntegrationSettings
  • Custom Prompts (/settings/prompts) - Manage AIPrompts
  • Author Profiles (/settings/profiles) - Manage AuthorProfiles
  • Content Strategies (/settings/strategies) - Manage Strategies

---

VERIFICATION

Run these commands to verify:

# Check migration applied
docker exec igny8_backend python manage.py showmigrations system

# Verify global settings exist
docker exec igny8_backend python manage.py shell -c "
from igny8_core.modules.system.global_settings_models import GlobalIntegrationSettings
obj = GlobalIntegrationSettings.get_instance()
print(f'OpenAI Model: {obj.openai_model}')
print(f'Max Tokens: {obj.openai_max_tokens}')
"

# Check AIPrompt has default_prompt field
docker exec igny8_backend python manage.py shell -c "
from igny8_core.modules.system.models import AIPrompt
fields = [f.name for f in AIPrompt._meta.get_fields()]
print('default_prompt' in fields)
"

# Verify AccountIntegrationOverride removed
docker exec igny8_backend python manage.py shell -c "
try:
    from igny8_core.modules.system.global_settings_models import AccountIntegrationOverride
    print('ERROR: Model still exists!')
except ImportError:
    print('✓ Model correctly removed')
"

---

QUICK START

1. Configure Platform API Keys:

   • Login to Django Admin
   • Go to: System → Global integration settings
   • Fill in OpenAI, DALL-E API keys
   • Set default models
   • Save

2. Create Global Prompts:

   • Go to: System → Global ai prompts
   • Add prompts for: clustering, ideas, content_generation
   • These become defaults for all accounts

3. Test with Account:

   • Create test account on Starter plan
   • Account automatically uses global API keys
   • Account can create IntegrationSettings to override model selection
   • Account CANNOT override API keys

4. Verify Free Plan Restriction:

   • Create test account on Free plan
   • Verify they CANNOT create IntegrationSettings records
   • Verify they use global defaults only

---

SUMMARY

✅ Correct: Platform API keys used by all accounts
✅ Correct: No user can bring their own API keys
✅ Correct: Only 4 plans (Free, Starter, Growth, Scale)
✅ Correct: Free plan cannot override, must use global
✅ Correct: Other plans can override model/params only
✅ Correct: Prompts have default_prompt for reset
✅ Correct: Global settings NOT associated with any account

❌ Removed: AccountIntegrationOverride model
❌ Removed: Enterprise plan references
❌ Removed: "Bring your own API key" functionality

🔧 TODO: Add sidebar navigation links to global settings
🔧 TODO: Add plan check to IntegrationSettings creation

---

For complete implementation details, see COMPLETE-IMPLEMENTATION-GUIDE.md