salman/igny8
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8cd036d8ce5158ea6928b3e4cae31d11f65b2dcd
igny8/docs/ActiveDocs/AI-ELEMENTS-EXTRACTED.md
alorig 8cd036d8ce new docs
2025-11-09 19:07:06 +05:00

17 KiB
Raw Blame History

IGNY8 AI Elements Reference Table

Generated by extract_ai_elements.py analysis

🧠 AI Core Functions

Function Name Category Type File Line Uses AIProcessor Celery Progress Steps Prompt Source Model Source
_auto_cluster_keywords_core cluster core_function backend/igny8_core/modules/planner/tasks.py 26 ✅ ❌ ✅ ✅ Database (get_prompt_value) AIProcessor.default_model
_generate_single_idea_core ideas core_function backend/igny8_core/modules/planner/tasks.py 1047 ✅ ❌ ✅ ✅ Database (get_prompt_value) AIProcessor.default_model
auto_generate_content_task content celery_task backend/igny8_core/modules/writer/tasks.py 27 ✅ ✅ ✅ ❌ Database (get_prompt_value) AIProcessor.default_model
auto_generate_images_task image celery_task backend/igny8_core/modules/writer/tasks.py 741 ✅ ✅ ✅ ❌ Database (get_prompt_value) AIProcessor.default_model
AutoClusterFunction cluster class backend/igny8_core/ai/functions/auto_cluster.py 14 ✅ ❌ ✅ ✅ Database (get_prompt_value) Function.get_model()
cluster_keywords cluster method backend/igny8_core/utils/ai_processor.py 1080 ✅ ❌ ✅ ✅ Inline/Hardcoded AIProcessor.default_model
generate_ideas ideas method backend/igny8_core/utils/ai_processor.py 1280 ✅ ❌ ✅ ✅ Inline/Hardcoded AIProcessor.default_model
generate_content content method backend/igny8_core/utils/ai_processor.py 446 ✅ ❌ ❌ ❌ Inline/Hardcoded AIProcessor.default_model
generate_image image method backend/igny8_core/utils/ai_processor.py 656 ✅ ❌ ❌ ❌ Inline/Hardcoded Parameter or default
run_ai_task unified celery_task backend/igny8_core/ai/tasks.py 13 ❌ ✅ ✅ ✅ Via function Via function
execute unified method backend/igny8_core/ai/engine.py 26 ✅ ❌ ✅ ✅ Via function Via function

🧱 Prompt Sources

Prompt Type Source File Retrieval Method
clustering Hardcoded in get_default_prompt() backend/igny8_core/modules/system/utils.py get_prompt_value() -> AIPrompt model or default
ideas Hardcoded in get_default_prompt() backend/igny8_core/modules/system/utils.py get_prompt_value() -> AIPrompt model or default
content_generation Hardcoded in get_default_prompt() backend/igny8_core/modules/system/utils.py get_prompt_value() -> AIPrompt model or default
image_prompt_extraction Hardcoded in get_default_prompt() backend/igny8_core/modules/system/utils.py get_prompt_value() -> AIPrompt model or default
image_prompt_template Hardcoded in get_default_prompt() backend/igny8_core/modules/system/utils.py get_prompt_value() -> AIPrompt model or default
negative_prompt Hardcoded in get_default_prompt() backend/igny8_core/modules/system/utils.py get_prompt_value() -> AIPrompt model or default

Prompt Storage:

  • Database Model: AIPrompt in backend/igny8_core/modules/system/models.py
  • Table: igny8_ai_prompts
  • Fields: prompt_type, prompt_value, default_prompt, account (FK)
  • Unique Constraint: (account, prompt_type)

Prompt Retrieval Flow:

  1. get_prompt_value(account, prompt_type) in modules/system/utils.py:108
  2. Tries: AIPrompt.objects.get(account=account, prompt_type=prompt_type, is_active=True)
  3. Falls back to: get_default_prompt(prompt_type) if not found

🧾 Model Configuration

Model Name Source File Selection Method
gpt-4.1 MODEL_RATES constant backend/igny8_core/utils/ai_processor.py AIProcessor._get_model() -> IntegrationSettings or Django settings
gpt-4o-mini MODEL_RATES constant backend/igny8_core/utils/ai_processor.py AIProcessor._get_model() -> IntegrationSettings or Django settings
gpt-4o MODEL_RATES constant backend/igny8_core/utils/ai_processor.py AIProcessor._get_model() -> IntegrationSettings or Django settings
dall-e-3 IMAGE_MODEL_RATES constant backend/igny8_core/utils/ai_processor.py Parameter or default in generate_image()
dall-e-2 IMAGE_MODEL_RATES constant backend/igny8_core/utils/ai_processor.py Parameter or default in generate_image()

Model Selection Flow:

  1. AIProcessor.__init__(account) in utils/ai_processor.py:54
  2. Calls _get_model('openai', account) in utils/ai_processor.py:98
  3. Tries: IntegrationSettings.objects.filter(integration_type='openai', account=account, is_active=True).first().config.get('model')
  4. Validates model is in MODEL_RATES dict
  5. Falls back to: settings.DEFAULT_AI_MODEL (default: 'gpt-4.1')

Model Storage:

  • Database Model: IntegrationSettings in backend/igny8_core/modules/system/models.py
  • Table: igny8_integration_settings
  • Fields: integration_type, config (JSONField), account (FK)
  • Config Structure: {"apiKey": "...", "model": "gpt-4.1", "enabled": true}

⚠️ Validation & Limits

Function Validation Checks Limit Checks
_auto_cluster_keywords_core Has validate() call, Keywords exist check Credit check, Plan limits (daily_cluster_limit, max_clusters)
AutoClusterFunction.validate() Base validation (ids array, max_items), Keywords exist Plan limits (daily_cluster_limit, max_clusters)
auto_generate_content_task Task existence, Account validation Credit check (via CreditService)
auto_generate_images_task Task existence, Account validation Credit check (via CreditService)
generate_image Model validation (VALID_OPENAI_IMAGE_MODELS), Size validation (VALID_SIZES_BY_MODEL) None
AIProcessor._get_model() Model in MODEL_RATES validation None

Validation Details:

  1. Plan Limits (in AutoClusterFunction.validate()):

    • plan.daily_cluster_limit - Max clusters per day
    • plan.max_clusters - Total max clusters
    • Checked in backend/igny8_core/ai/functions/auto_cluster.py:59-79

  2. Credit Checks:

    • CreditService.check_credits(account, required_credits) in modules/billing/services.py:16
    • Used before AI operations

  3. Model Validation:

    • OpenAI images: Only dall-e-3 and dall-e-2 valid (line 704-708 in ai_processor.py)
    • Size validation per model (line 719-724 in ai_processor.py)

  4. Input Validation:

    • Base validation in BaseAIFunction.validate() checks for 'ids' array and max_items limit
    • AutoClusterFunction.get_max_items() returns 20 (max keywords per cluster)

🔁 Retry & Error Handling

Component Retry Logic Error Handling Fallback
run_ai_task max_retries=3 (Celery decorator) Exception caught, task state updated to FAILURE None
auto_generate_content_task max_retries=3 (Celery decorator) Try/except blocks, error logging None
_call_openai None (single attempt) HTTP error handling, JSON parse errors, timeout (60s) Returns error dict
_get_api_key None Exception caught, logs warning Falls back to Django settings (OPENAI_API_KEY, RUNWARE_API_KEY)
_get_model None Exception caught, logs warning Falls back to Django settings (DEFAULT_AI_MODEL)

🪵 AI Debug Steps

Function Request Steps Response Steps Step Tracking Method
_auto_cluster_keywords_core ✅ (manual list) ✅ (manual list) Manual request_steps.append() and response_steps.append()
AutoClusterFunction ✅ (via StepTracker) ✅ (via StepTracker) StepTracker.add_request_step() and add_response_step()
run_ai_task ✅ (via engine) ✅ (via engine) Extracted from engine.execute() result
AIEngine.execute ✅ (via StepTracker) ✅ (via StepTracker) StepTracker instance tracks all steps
auto_generate_content_task ❌ ❌ No step tracking (legacy)
auto_generate_images_task ❌ ❌ No step tracking (legacy)

Step Tracking Implementation:

  1. New Framework (AIEngine):

    • Uses StepTracker class in backend/igny8_core/ai/tracker.py
    • Steps added at each phase: INIT, PREP, AI_CALL, PARSE, SAVE, DONE
    • Steps stored in request_steps and response_steps lists
    • Returned in result dict and logged to AITaskLog model

  2. Legacy Functions:

    • Manual step tracking with lists
    • Steps added to meta dict for Celery task progress
    • Extracted in integration_views.py:task_progress() for frontend

  3. Step Structure:

    {
    'stepNumber': int,
    'stepName': str,  # INIT, PREP, AI_CALL, PARSE, SAVE, DONE
    'functionName': str,
    'status': 'success' | 'error' | 'pending',
    'message': str,
    'error': str (optional),
    'duration': int (milliseconds, optional)
}

📦 Request/Response Structuring

Function Request Format Response Format JSON Mode Parsing Method
_call_openai OpenAI API format: {'model': str, 'messages': [...], 'temperature': float, 'max_tokens': int, 'response_format': dict} {'content': str, 'input_tokens': int, 'output_tokens': int, 'total_tokens': int, 'model': str, 'cost': float, 'error': str, 'api_id': str} ✅ (if response_format={'type': 'json_object'}) _extract_json_from_response()
cluster_keywords Prompt string with keywords JSON with 'clusters' array ✅ (auto-enabled for json_models) _extract_json_from_response() then extract 'clusters'
generate_ideas Prompt string with clusters JSON with 'ideas' array ✅ (auto-enabled for json_models) _extract_json_from_response() then extract 'ideas'
generate_image (OpenAI) {'prompt': str, 'model': str, 'n': int, 'size': str} {'url': str, 'revised_prompt': str, 'cost': float} N/A Direct JSON response
generate_image (Runware) Array format with imageInference tasks {'url': str, 'cost': float} N/A Extract from nested response structure

JSON Mode Auto-Enable:

  • Models: ['gpt-4o', 'gpt-4o-mini', 'gpt-4-turbo-preview']
  • Auto-enabled in AIProcessor.call() if response_format not specified
  • Location: backend/igny8_core/ai/processor.py:40-42

JSON Extraction:

  • Primary: Direct json.loads() on response
  • Fallback: _extract_json_from_response() handles:
    • Markdown code blocks (json ... )
    • Multiline JSON
    • Partial JSON extraction
  • Location: backend/igny8_core/utils/ai_processor.py:334-440

📍 Paths & Constants

Constant Value File Usage
OPENAI_API_KEY Django setting backend/igny8_core/utils/ai_processor.py:93 Fallback API key
RUNWARE_API_KEY Django setting backend/igny8_core/utils/ai_processor.py:95 Fallback API key
DEFAULT_AI_MODEL Django setting (default: 'gpt-4.1') backend/igny8_core/utils/ai_processor.py:121 Fallback model
OpenAI API URL 'https://api.openai.com/v1/chat/completions' backend/igny8_core/utils/ai_processor.py:163 Text generation endpoint
OpenAI Images URL 'https://api.openai.com/v1/images/generations' backend/igny8_core/utils/ai_processor.py:735 Image generation endpoint
Runware API URL 'https://api.runware.ai/v1' backend/igny8_core/utils/ai_processor.py:844 Runware image generation
MODEL_RATES Dict with pricing per 1M tokens backend/igny8_core/utils/ai_processor.py:19 Cost calculation
IMAGE_MODEL_RATES Dict with pricing per image backend/igny8_core/utils/ai_processor.py:26 Image cost calculation
VALID_OPENAI_IMAGE_MODELS {'dall-e-3', 'dall-e-2'} backend/igny8_core/utils/ai_processor.py:34 Model validation
VALID_SIZES_BY_MODEL Dict mapping models to valid sizes backend/igny8_core/utils/ai_processor.py:41 Size validation

💰 Cost Tracking

Component Cost Calculation Token Tracking Storage
_call_openai Calculated from MODEL_RATES based on input/output tokens ✅ (input_tokens, output_tokens, total_tokens) Returned in result dict
generate_image (OpenAI) IMAGE_MODEL_RATES[model] * n N/A Returned in result dict
generate_image (Runware) 0.036 * n (hardcoded) N/A Returned in result dict
CostTracker Aggregates costs from multiple operations ✅ (total_tokens) In-memory during execution
AITaskLog Stored in cost field (DecimalField) ✅ (stored in tokens field) Database table igny8_ai_task_logs
CreditUsageLog Stored in cost_usd field ✅ (tokens_input, tokens_output) Database table (billing module)

Cost Calculation Formula:

# Text generation
input_cost = (input_tokens / 1_000_000) * MODEL_RATES[model]['input']
output_cost = (output_tokens / 1_000_000) * MODEL_RATES[model]['output']
total_cost = input_cost + output_cost

# Image generation
cost = IMAGE_MODEL_RATES[model] * n_images

📊 Progress Tracking

Function Progress Method Phase Tracking Percentage Mapping
_auto_cluster_keywords_core progress_callback() function Manual phase strings Manual percentage
auto_generate_content_task self.update_state() (Celery) Manual phase strings Manual percentage
AIEngine.execute ProgressTracker.update() Automatic (INIT, PREP, AI_CALL, PARSE, SAVE, DONE) Automatic: INIT (0-10%), PREP (10-25%), AI_CALL (25-70%), PARSE (70-85%), SAVE (85-98%), DONE (98-100%)
run_ai_task Via AIEngine Via AIEngine Via AIEngine

Progress Tracker:

  • Class: ProgressTracker in backend/igny8_core/ai/tracker.py:77
  • Updates Celery task state via task.update_state()
  • Tracks: phase, percentage, message, current, total, meta

🗄️ Database Logging

Component Log Table Fields Logged When Logged
AIEngine.execute AITaskLog task_id, function_name, phase, message, status, duration, cost, tokens, request_steps, response_steps, error, payload, result After execution (success or error)
Credit usage CreditUsageLog account, operation_type, credits_used, cost_usd, model_used, tokens_input, tokens_output After successful save operation

AITaskLog Model:

  • Table: igny8_ai_task_logs
  • Location: backend/igny8_core/ai/models.py:8
  • Fields: All execution details including steps, costs, tokens, errors

🔄 Celery Integration

Task Entrypoint Task ID State Updates Error Handling
run_ai_task backend/igny8_core/ai/tasks.py:13 self.request.id Via ProgressTracker Updates state to FAILURE, raises exception
auto_generate_content_task backend/igny8_core/modules/writer/tasks.py:27 self.request.id Manual self.update_state() Try/except, logs error
auto_generate_images_task backend/igny8_core/modules/writer/tasks.py:741 self.request.id Manual self.update_state() Try/except, logs error

Task Progress Endpoint:

  • Route: /api/v1/system/settings/task_progress/{task_id}/
  • Handler: IntegrationSettingsViewSet.task_progress() in modules/system/integration_views.py:936
  • Extracts: request_steps and response_steps from task meta
  • Returns: Progress data to frontend for debug panel

Summary

Key Findings:

  1. Two AI Systems Coexist:

    • Legacy: Direct functions in modules/planner/tasks.py and modules/writer/tasks.py
    • New Framework: AIEngine + BaseAIFunction classes in ai/ directory

  2. Unified Entrypoint:

    • run_ai_task() in ai/tasks.py is the unified Celery entrypoint
    • Uses AIEngine to execute any registered AI function

  3. Prompt Management:

    • All prompts stored in AIPrompt model (database)
    • Fallback to hardcoded defaults in get_default_prompt()
    • Retrieved via get_prompt_value(account, prompt_type)

  4. Model Selection:

    • Per-account via IntegrationSettings.config['model']
    • Falls back to Django DEFAULT_AI_MODEL setting
    • Validated against MODEL_RATES dict

  5. Step Tracking:

    • New framework uses StepTracker class
    • Legacy functions use manual lists
    • Both stored in Celery task meta and AITaskLog model

  6. Cost Tracking:

    • Calculated from MODEL_RATES and IMAGE_MODEL_RATES
    • Logged to AITaskLog and CreditUsageLog
    • Tracked via CostTracker during execution
Reference in New Issue View Git Blame Copy Permalink