igny8/docs/05-AI-FRAMEWORK-IMPLEMENTATION.md

IGNY8 AI Framework Implementation Reference

Last Updated: 2025-01-XX
Purpose: Complete AI framework implementation reference covering architecture, code structure, all 5 AI functions, execution flow, progress tracking, cost tracking, prompt management, and model configuration.

---

Table of Contents

1. AI Framework Overview
2. Common Architecture
3. AI Function Execution Flow
4. AI Functions
5. Progress Tracking
6. Cost Tracking
7. Prompt Management
8. Model Configuration

---

AI Framework Overview

The IGNY8 AI framework provides a unified interface for all AI operations. All AI functions inherit from BaseAIFunction and are orchestrated by AIEngine, ensuring consistent execution, progress tracking, error handling, and cost tracking.

Key Components

• BaseAIFunction: Abstract base class for all AI functions
• AIEngine: Central orchestrator managing lifecycle, progress, logging, cost tracking
• AICore: Centralized AI request handler for all AI operations
• PromptRegistry: Centralized prompt management with hierarchical resolution
• Function Registry: Lazy-loaded function registry
• Progress Tracking: Real-time progress updates via Celery
• Cost Tracking: Automatic cost and token tracking

AI Functions

1. Auto Cluster Keywords: Group related keywords into semantic clusters
2. Generate Ideas: Generate content ideas from keyword clusters
3. Generate Content: Generate blog post and article content
4. Generate Image Prompts: Extract image prompts from content
5. Generate Images: Generate images using OpenAI DALL-E or Runware

---

Common Architecture

Core Framework Files

Entry Point

File: backend/igny8_core/ai/tasks.py Function: run_ai_task Purpose: Unified Celery task entrypoint for all AI functions Parameters: function_name (str), payload (dict), account_id (int) Flow: Loads function from registry → Creates AIEngine → Executes function

Engine Orchestrator

File: backend/igny8_core/ai/engine.py Class: AIEngine Purpose: Central orchestrator managing lifecycle, progress, logging, cost tracking Methods:

• execute - Main execution pipeline (6 phases: INIT, PREP, AI_CALL, PARSE, SAVE, DONE)
• _handle_error - Centralized error handling
• _log_to_database - Logs to AITaskLog model

Base Function Class

File: backend/igny8_core/ai/base.py Class: BaseAIFunction Purpose: Abstract base class defining interface for all AI functions Abstract Methods:

• get_name - Returns function name (e.g., 'auto_cluster')
• prepare - Loads and prepares data
• build_prompt - Builds AI prompt
• parse_response - Parses AI response
• save_output - Saves results to database Optional Methods:
• get_metadata - Returns display name, description, phases
• get_max_items - Returns max items limit (or None)
• validate - Validates input payload (default: checks for 'ids')
• get_model - Returns model override (default: None, uses account default)

Function Registry

File: backend/igny8_core/ai/registry.py Functions:

• register_function - Registers function class
• register_lazy_function - Registers lazy loader
• get_function - Gets function class by name (lazy loads if needed)
• get_function_instance - Gets function instance by name
• list_functions - Lists all registered functions

AI Core Handler

File: backend/igny8_core/ai/ai_core.py Class: AICore Purpose: Centralized AI request handler for all AI operations (text and image generation) Methods:

• run_ai_request - Makes API call to OpenAI/Runware for text generation
• generate_image - Makes API call to OpenAI DALL-E or Runware for image generation
• extract_json - Extracts JSON from response (handles markdown code blocks)

Prompt Registry

File: backend/igny8_core/ai/prompts.py Class: PromptRegistry Purpose: Centralized prompt management with hierarchical resolution Method: get_prompt - Gets prompt with resolution order:

1. Task-level prompt_override (if exists)
2. DB prompt for (account, function)
3. Default fallback from DEFAULT_PROMPTS registry Prompt Types:

• clustering - For auto_cluster function
• ideas - For generate_ideas function
• content_generation - For generate_content function
• image_prompt_extraction - For extract_image_prompts function
• image_prompt_template - Template for formatting image prompts
• negative_prompt - Negative prompt for Runware image generation

Model Settings

File: backend/igny8_core/ai/settings.py Constants: FUNCTION_ALIASES - Function name aliases for backward compatibility Functions:

• get_model_config(function_name, account) - Gets model config from IntegrationSettings (account required, no fallbacks)
  • Raises ValueError if IntegrationSettings not configured
  • Returns dict with model, max_tokens, temperature, response_format

---

AI Function Execution Flow

Complete Execution Pipeline

1. API Endpoint (views.py)
   ↓
2. run_ai_task (tasks.py)
   - Gets account from account_id
   - Gets function instance from registry
   - Creates AIEngine
   ↓
3. AIEngine.execute (engine.py)
   Phase 1: INIT (0-10%)
   - Calls function.validate()
   - Updates progress tracker
   ↓
   Phase 2: PREP (10-25%)
   - Calls function.prepare()
   - Calls function.build_prompt()
   - Updates progress tracker
   ↓
   Phase 3: AI_CALL (25-70%)
   - Gets model config from settings
   - Calls AICore.run_ai_request() or AICore.generate_image()
   - Tracks cost and tokens
   - Updates progress tracker
   ↓
   Phase 4: PARSE (70-85%)
   - Calls function.parse_response()
   - Updates progress tracker
   ↓
   Phase 5: SAVE (85-98%)
   - Calls function.save_output()
   - Logs credit usage
   - Updates progress tracker
   ↓
   Phase 6: DONE (98-100%)
   - Logs to AITaskLog
   - Returns result

Progress Updates

Progress Endpoint: /api/v1/system/settings/task_progress/{task_id}/

Response Format:

• state: Task state (PENDING, PROGRESS, SUCCESS, FAILURE)
• meta: Progress metadata
  • phase: Current phase (INIT, PREP, AI_CALL, PARSE, SAVE, DONE)
  • percentage: Progress percentage (0-100)
  • message: User-friendly message
  • request_steps: Array of request steps
  • response_steps: Array of response steps
  • cost: API cost in USD
  • tokens: Token count

---

AI Functions

1. Auto Cluster Keywords

Purpose: Group related keywords into semantic clusters using AI

Function Class: AutoClusterFunction File: backend/igny8_core/ai/functions/auto_cluster.py

API Endpoint:

• ViewSet: KeywordViewSet
• Action: auto_cluster
• Method: POST
• URL Path: /v1/planner/keywords/auto_cluster/
• Payload: ids (list[int]) - Keyword IDs

Function Methods:

• get_name(): Returns 'auto_cluster'
• validate(payload, account): Validates keyword IDs exist
• prepare(payload, account): Loads keywords from database
• build_prompt(data, account): Builds clustering prompt with keyword data
• parse_response(response, step_tracker): Parses cluster JSON response
• save_output(parsed, original_data, account, progress_tracker, step_tracker): Creates Cluster records and links keywords

Input: List of keyword IDs Output: Cluster records created, keywords linked to clusters

Progress Messages:

• INIT: "Validating keywords"
• PREP: "Preparing keyword clustering"
• AI_CALL: "Analyzing keyword relationships"
• PARSE: "Processing cluster data"
• SAVE: "Creating clusters"

2. Generate Ideas

Purpose: Generate content ideas from keyword clusters

Function Class: GenerateIdeasFunction File: backend/igny8_core/ai/functions/generate_ideas.py

API Endpoint:

• ViewSet: ClusterViewSet
• Action: auto_generate_ideas
• Method: POST
• URL Path: /v1/planner/clusters/auto_generate_ideas/
• Payload: ids (list[int]) - Cluster IDs

Function Methods:

• get_name(): Returns 'generate_ideas'
• validate(payload, account): Validates cluster IDs exist
• prepare(payload, account): Loads clusters and keywords
• build_prompt(data, account): Builds idea generation prompt with cluster data
• parse_response(response, step_tracker): Parses ideas JSON response
• save_output(parsed, original_data, account, progress_tracker, step_tracker): Creates ContentIdeas records

Input: List of cluster IDs Output: ContentIdeas records created

Progress Messages:

• INIT: "Verifying cluster integrity"
• PREP: "Loading cluster keywords"
• AI_CALL: "Generating ideas with Igny8 Semantic AI"
• PARSE: "{count} high-opportunity idea(s) generated"
• SAVE: "Content Outline for Ideas generated"

3. Generate Content

Purpose: Generate blog post and article content from tasks

Function Class: GenerateContentFunction File: backend/igny8_core/ai/functions/generate_content.py

API Endpoint:

• ViewSet: TasksViewSet
• Action: auto_generate_content
• Method: POST
• URL Path: /v1/writer/tasks/auto_generate_content/
• Payload: ids (list[int]) - Task IDs (max 50)

Function Methods:

• get_name(): Returns 'generate_content'
• get_max_items(): Returns 50 (max tasks per batch)
• validate(payload, account): Validates task IDs exist
• prepare(payload, account): Loads tasks with related data
• build_prompt(data, account): Builds content generation prompt with task data
• parse_response(response, step_tracker): Parses content (JSON or plain text)
• save_output(parsed, original_data, account, progress_tracker, step_tracker): Creates/updates Content records

Input: List of task IDs Output: Content records created/updated with HTML content

Progress Messages:

• INIT: "Initializing content generation"
• PREP: "Loading tasks and building prompts"
• AI_CALL: "Generating content with AI"
• PARSE: "Processing content"
• SAVE: "Saving content"

4. Generate Image Prompts

Purpose: Extract image prompts from content for generating images

Function Class: GenerateImagePromptsFunction File: backend/igny8_core/ai/functions/generate_image_prompts.py

API Endpoint:

• ViewSet: TasksViewSet (via content)
• Action: generate_image_prompts
• Method: POST
• URL Path: /v1/writer/content/generate_image_prompts/
• Payload: ids (list[int]) - Content IDs

Function Methods:

• get_name(): Returns 'generate_image_prompts'
• validate(payload, account): Validates content IDs exist
• prepare(payload, account): Loads content records
• build_prompt(data, account): Builds prompt extraction prompt with content HTML
• parse_response(response, step_tracker): Parses image prompts JSON
• save_output(parsed, original_data, account, progress_tracker, step_tracker): Updates Images records with prompts

Input: List of content IDs Output: Images records updated with prompts (featured, in-article)

Progress Messages:

• INIT: "Validating content"
• PREP: "Preparing image prompt extraction"
• AI_CALL: "Extracting image prompts"
• PARSE: "Processing image prompts"
• SAVE: "Saving image prompts"

5. Generate Images

Purpose: Generate images using AI (OpenAI DALL-E or Runware) based on prompts

Function Class: GenerateImagesFunction File: backend/igny8_core/ai/functions/generate_images.py

API Endpoint:

• ViewSet: ImagesViewSet
• Action: generate_images
• Method: POST
• URL Path: /v1/writer/images/generate_images/
• Payload: ids (list[int]) - Image IDs

Function Methods:

• get_name(): Returns 'generate_images'
• validate(payload, account): Validates image IDs exist and have prompts
• prepare(payload, account): Loads images with prompts
• build_prompt(data, account): Formats image prompt with context
• parse_response(response, step_tracker): Parses image URL from API response
• save_output(parsed, original_data, account, progress_tracker, step_tracker): Updates Images records with image URLs

Input: List of image IDs (with prompts) Output: Images records updated with image URLs

Image Generation Settings:

• Provider: 'openai' or 'runware'
• Model: Model name (e.g., 'dall-e-3', 'runware:97@1')
• Image Type: 'realistic', 'artistic', 'cartoon'
• Max In-Article Images: Max images per content
• Image Format: 'webp', 'jpg', 'png'
• Desktop/Mobile: Boolean flags

Progress Messages:

• INIT: "Validating image prompts"
• PREP: "Preparing image generation"
• AI_CALL: "Creating image(s) with AI"
• PARSE: "Processing image response"
• SAVE: "Saving generated image(s)"

---

Progress Tracking

Progress Phases

All AI functions follow the same 6-phase execution:

1. INIT (0-10%): Validation phase
2. PREP (10-25%): Data preparation phase
3. AI_CALL (25-70%): AI API call phase
4. PARSE (70-85%): Response parsing phase
5. SAVE (85-98%): Database save phase
6. DONE (98-100%): Completion phase

Progress Updates

Frontend Polling: Frontend polls /api/v1/system/settings/task_progress/{task_id}/ every 1-2 seconds

Progress Response:

• state: Task state
• meta: Progress metadata
  • phase: Current phase
  • percentage: Progress percentage
  • message: User-friendly message
  • request_steps: Request steps array
  • response_steps: Response steps array
  • cost: API cost
  • tokens: Token count

Step Tracking

Request Steps: Tracked during prompt building and AI call Response Steps: Tracked during response parsing

Purpose: Provides detailed logging for debugging and transparency

---

Cost Tracking

Cost Calculation

Text Generation:

• Cost calculated based on model pricing (input tokens + output tokens)
• Tracked per request
• Stored in CostTracker

Image Generation:

• Cost calculated based on provider pricing
• OpenAI DALL-E: Fixed cost per image
• Runware: Variable cost per image
• Tracked per image

Cost Storage

AITaskLog Model:

• cost: Total cost for task
• tokens: Total tokens used

CreditUsageLog Model:

• cost_usd: Cost in USD
• credits_used: Credits deducted

---

Prompt Management

Prompt Resolution Order

1. Task-Level Override: If task has prompt_override, use it
2. Database Prompt: If account has custom prompt in database, use it
3. Default Prompt: Use default prompt from DEFAULT_PROMPTS registry

Prompt Customization

Per Account: Custom prompts stored in AIPrompt model Per Function: Different prompts for each function type Context Variables: Prompts support context placeholders:

• [IGNY8_KEYWORDS] - Keyword list
• [IGNY8_CLUSTERS] - Cluster list
• [IGNY8_CLUSTER_KEYWORDS] - Cluster keywords
• [IGNY8_IDEA] - Idea data
• [IGNY8_CLUSTER] - Cluster data

---

Model Configuration

IntegrationSettings - Single Source of Truth

IMPORTANT: As of the refactoring completed in 2025-01-XX, the AI framework uses IntegrationSettings only for model configuration. There are no hardcoded defaults or fallbacks.

IntegrationSettings Model:

• integration_type: 'openai' or 'runware' (required)
• account: Account instance (required) - each account must configure their own models
• is_active: Boolean (must be True for configuration to be used)
• config: JSONField with model configuration (required)
  • model: Model name (required) - e.g., 'gpt-4o-mini', 'gpt-4o', 'dall-e-3'
  • max_tokens: Max tokens (optional, defaults to 4000)
  • temperature: Temperature (optional, defaults to 0.7)
  • response_format: Response format (optional, automatically set for JSON mode models)

Model Configuration Function

File: backend/igny8_core/ai/settings.py

Function: get_model_config(function_name: str, account) -> Dict[str, Any]

Behavior:

• Requires account parameter (no longer optional)
• Requires IntegrationSettings to be configured for the account
• Raises ValueError with clear error messages if:
  • Account not provided
  • IntegrationSettings not found for account
  • Model not configured in IntegrationSettings
  • IntegrationSettings is inactive

Error Messages:

• Missing account: "Account is required for model configuration"
• Missing IntegrationSettings: "OpenAI IntegrationSettings not configured for account {id}. Please configure OpenAI settings in the integration page."
• Missing model: "Model not configured in IntegrationSettings for account {id}. Please set 'model' in OpenAI integration settings."

Returns:

{
    'model': str,              # Model name from IntegrationSettings
    'max_tokens': int,         # From config or default 4000
    'temperature': float,       # From config or default 0.7
    'response_format': dict,   # JSON mode for supported models, or None
}

Account-Specific Configuration

Key Principle: Each account must configure their own AI models. There are no global defaults.

Configuration Steps:

1. Navigate to Settings → Integrations
2. Configure OpenAI integration settings
3. Set model in the configuration (required)
4. Optionally set max_tokens and temperature
5. Ensure integration is active

Supported Models:

• Text generation: gpt-4o-mini, gpt-4o, gpt-4-turbo, etc.
• Image generation: dall-e-3 (OpenAI) or runware:97@1 (Runware)
• JSON mode: Automatically enabled for supported models (gpt-4o, gpt-4-turbo, etc.)

Function Aliases

File: backend/igny8_core/ai/settings.py

FUNCTION_ALIASES: Dictionary mapping legacy function names to current names

• cluster_keywords → auto_cluster
• auto_cluster_keywords → auto_cluster
• auto_generate_ideas → generate_ideas
• auto_generate_content → generate_content
• auto_generate_images → generate_images

Purpose: Maintains backward compatibility with legacy function names.

Removed Functions

The following helper functions were removed as part of the refactoring (they were never used):

• get_model() - Removed (use get_model_config()['model'] instead)
• get_max_tokens() - Removed (use get_model_config()['max_tokens'] instead)
• get_temperature() - Removed (use get_model_config()['temperature'] instead)

Rationale: These functions were redundant - get_model_config() already returns all needed values.

---

Summary

The IGNY8 AI framework provides:

1. Unified Interface: All AI functions use the same execution pipeline
2. Consistent Execution: All functions follow the same 6-phase flow
3. Progress Tracking: Real-time progress updates via Celery
4. Cost Tracking: Automatic cost and token tracking
5. Error Handling: Centralized error handling in AIEngine
6. Prompt Management: Hierarchical prompt resolution
7. Model Configuration: Per-account model overrides
8. Database Logging: Automatic logging to AITaskLog
9. Extensibility: Easy to add new AI functions
10. Reliability: Retry logic and error recovery

This architecture ensures consistency, maintainability, and extensibility while providing a robust foundation for all AI operations in the IGNY8 platform.