igny8/docs/90-REFERENCE/AI-FUNCTIONS.md

AI Functions Reference

Last Verified: December 25, 2025

---

Overview

IGNY8's AI engine provides functions for content planning and generation. Located in backend/igny8_core/ai/.

Providers:

• OpenAI - GPT-4 for text, DALL-E 3 for images
• Runware - Alternative image generation

---

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        AI ENGINE                                 │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐      │
│  │   AIEngine   │───►│   Function   │───►│   Provider   │      │
│  │   (router)   │    │   (logic)    │    │   (API)      │      │
│  └──────────────┘    └──────────────┘    └──────────────┘      │
│                                                                  │
│  Functions:                                                      │
│  • AutoClusterKeywords                                          │
│  • GenerateContentIdeas                                         │
│  • GenerateContent                                              │
│  • GenerateImages                                               │
│  • OptimizeContent (pending)                                    │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

---

AIEngine

Location: backend/igny8_core/ai/engine.py

Main orchestrator for AI operations.

class AIEngine:
    def __init__(self, account: Account):
        self.account = account
        self.settings = self._load_settings()
        self.text_provider = self._init_text_provider()
        self.image_provider = self._init_image_provider()
    
    def auto_cluster(self, keywords: List[Keyword]) -> List[Cluster]:
        """Cluster keywords by topic"""
        
    def generate_ideas(self, cluster: Cluster) -> List[ContentIdea]:
        """Generate content ideas for cluster"""
        
    def generate_content(self, task: Task) -> Content:
        """Generate full article content"""
        
    def generate_images(self, content: Content, count: int = 1) -> List[ContentImage]:
        """Generate images for content"""

---

Function: AutoClusterKeywords

Purpose: Group semantically related keywords into clusters

Input:

{
    "keywords": [
        {"id": "...", "keyword": "python tutorial"},
        {"id": "...", "keyword": "learn python"},
        {"id": "...", "keyword": "python basics"},
        ...
    ],
    "site_context": {
        "name": "Tech Blog",
        "industry": "Technology"
    }
}

Output:

{
    "clusters": [
        {
            "name": "Python Learning Resources",
            "description": "Tutorials and guides for learning Python",
            "keywords": ["python tutorial", "learn python", "python basics"]
        },
        ...
    ]
}

Prompt Template: auto_cluster

Model: GPT-4

Credit Cost: 1 idea credit per operation

---

Function: GenerateContentIdeas

Purpose: Create content ideas from a keyword cluster

Input:

{
    "cluster": {
        "name": "Python Learning Resources",
        "description": "...",
        "keywords": [...]
    },
    "site_context": {
        "name": "Tech Blog",
        "industry": "Technology"
    },
    "count": 5  # Number of ideas to generate
}

Output:

{
    "ideas": [
        {
            "title": "10 Essential Python Tips for Beginners",
            "description": "A comprehensive guide covering...",
            "primary_keyword": "python tutorial",
            "secondary_keywords": ["learn python", "python basics"]
        },
        ...
    ]
}

Prompt Template: generate_ideas

Model: GPT-4

Credit Cost: 1 idea credit per idea generated

---

Function: GenerateContent

Purpose: Create full article from task brief

Input:

{
    "task": {
        "title": "10 Essential Python Tips for Beginners",
        "brief": "Write a comprehensive guide...",
        "primary_keyword": "python tutorial",
        "secondary_keywords": ["learn python", "python basics"]
    },
    "site_context": {
        "name": "Tech Blog",
        "industry": "Technology",
        "tone": "Professional but approachable"
    },
    "options": {
        "target_word_count": 2000,
        "include_headings": True,
        "include_lists": True,
        "include_code_blocks": True
    }
}

Output:

{
    "title": "10 Essential Python Tips for Beginners",
    "body": "<h2>Introduction</h2><p>...</p>...",  # Full HTML
    "excerpt": "Learn the essential Python tips...",
    "meta_title": "10 Python Tips for Beginners | Tech Blog",
    "meta_description": "Master Python with these 10 essential tips...",
    "word_count": 2150
}

Prompt Template: generate_content

Model: GPT-4

Credit Cost: 1 content credit per generation

---

Function: GenerateImages

Purpose: Create images for article content

Input:

{
    "content": {
        "title": "10 Essential Python Tips for Beginners",
        "body": "<html>...</html>",
        "primary_keyword": "python tutorial"
    },
    "options": {
        "count": 3,
        "style": "photorealistic",  # photorealistic, illustration, diagram
        "size": "1024x1024"
    }
}

Process:

1. Analyze content to identify image opportunities
2. Generate prompts for each image
3. Call image provider API
4. Store images and generate thumbnails

Output:

{
    "images": [
        {
            "url": "https://storage.../image1.png",
            "thumbnail_url": "https://storage.../image1_thumb.png",
            "alt_text": "Python code example showing...",
            "caption": "Example of Python list comprehension",
            "prompt": "A clean code editor showing Python syntax...",
            "is_featured": True
        },
        ...
    ]
}

Prompt Template: generate_image_prompts

Model: DALL-E 3 or Runware

Credit Cost: 1 image credit per image

---

Function: OptimizeContent (Pending)

Status: ⏸️ Not yet implemented

Purpose: SEO optimize existing content

Planned Input:

{
    "content": {
        "title": "...",
        "body": "...",
        "target_keyword": "..."
    },
    "optimization_type": "seo" | "readability" | "both"
}

Planned Output:

{
    "optimized_title": "...",
    "optimized_body": "...",
    "changes": [
        {"type": "keyword_density", "description": "..."},
        {"type": "heading_structure", "description": "..."},
        ...
    ],
    "score_before": 65,
    "score_after": 85
}

---

Prompt Templates

System Prompts

Stored in PromptTemplate model or defaults in code.

Template	Purpose
auto_cluster	Keywords → Clusters
generate_ideas	Cluster → Ideas
generate_content	Task → Article
generate_image_prompts	Content → Image prompts
optimize_content	Content → Optimized (pending)

Template Variables

{
    "site_name": "Tech Blog",
    "site_industry": "Technology",
    "site_tone": "Professional",
    "keyword": "python tutorial",
    "keywords": ["python", "tutorial", "learn"],
    "cluster_name": "Python Learning",
    "task_title": "10 Python Tips",
    "task_brief": "Write a guide...",
    "target_word_count": 2000
}

Custom Prompts

Users can customize prompts via Settings → Prompts:

# API
GET /api/v1/system/prompts/{type}/
PUT /api/v1/system/prompts/{type}/
POST /api/v1/system/prompts/{type}/reset/

---

Provider: OpenAI

Location: backend/igny8_core/ai/providers/openai_provider.py

Text Generation

class OpenAITextProvider:
    def complete(self, prompt: str, options: dict) -> str:
        response = openai.ChatCompletion.create(
            model=options.get('model', 'gpt-4'),
            messages=[
                {"role": "system", "content": self.system_prompt},
                {"role": "user", "content": prompt}
            ],
            temperature=options.get('temperature', 0.7),
            max_tokens=options.get('max_tokens', 4000)
        )
        return response.choices[0].message.content

Image Generation

class OpenAIImageProvider:
    def generate(self, prompt: str, options: dict) -> str:
        response = openai.Image.create(
            model="dall-e-3",
            prompt=prompt,
            size=options.get('size', '1024x1024'),
            quality=options.get('quality', 'standard'),
            n=1
        )
        return response.data[0].url

---

Provider: Runware

Location: backend/igny8_core/ai/providers/runware_provider.py

Alternative image generation via Runware API.

class RunwareImageProvider:
    def generate(self, prompt: str, options: dict) -> str:
        response = self.client.generate(
            prompt=prompt,
            width=options.get('width', 1024),
            height=options.get('height', 1024),
            model=options.get('model', 'default')
        )
        return response.image_url

---

Error Handling

Common Errors

Error	Code	Handling
Rate limit	rate_limit_exceeded	Retry with backoff
Context too long	context_length_exceeded	Truncate input
Content filter	content_policy_violation	Return error to user
API unavailable	api_error	Retry or fail

Retry Strategy

class AIEngine:
    MAX_RETRIES = 3
    BASE_DELAY = 1  # seconds
    
    def _call_with_retry(self, func, *args, **kwargs):
        for attempt in range(self.MAX_RETRIES):
            try:
                return func(*args, **kwargs)
            except RateLimitError:
                delay = self.BASE_DELAY * (2 ** attempt)
                time.sleep(delay)
            except ContentPolicyError:
                raise  # Don't retry policy violations
        raise MaxRetriesExceeded()

---

Configuration

Per-Account Settings

# In AIIntegrationSettings
openai_api_key = "sk-..."
openai_model = "gpt-4"  # or gpt-4-turbo
image_provider = "dalle"  # or "runware"
dalle_api_key = "sk-..."
runware_api_key = "..."

Model Options

Model	Use Case	Token Limit
gpt-4	High quality content	8,192
gpt-4-turbo	Faster, larger context	128,000
gpt-3.5-turbo	Budget option	4,096

---

Monitoring

Logging

All AI operations logged with:

• Input parameters (sanitized)
• Output summary
• Token usage
• Latency
• Error details

Metrics

Tracked via internal logging:

• Operations per day
• Average latency
• Error rate
• Token consumption
• Credit usage