docs & ux improvmeents
This commit is contained in:
IGNY8 VPS (Salman)
462
docs/90-REFERENCE/AI-FUNCTIONS.md
Normal file
462
docs/90-REFERENCE/AI-FUNCTIONS.md
Normal file
@@ -0,0 +1,462 @@
|
||||
# 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.
|
||||
|
||||
```python
|
||||
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:**
|
||||
```python
|
||||
{
|
||||
"keywords": [
|
||||
{"id": "...", "keyword": "python tutorial"},
|
||||
{"id": "...", "keyword": "learn python"},
|
||||
{"id": "...", "keyword": "python basics"},
|
||||
...
|
||||
],
|
||||
"site_context": {
|
||||
"name": "Tech Blog",
|
||||
"industry": "Technology"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```python
|
||||
{
|
||||
"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:**
|
||||
```python
|
||||
{
|
||||
"cluster": {
|
||||
"name": "Python Learning Resources",
|
||||
"description": "...",
|
||||
"keywords": [...]
|
||||
},
|
||||
"site_context": {
|
||||
"name": "Tech Blog",
|
||||
"industry": "Technology"
|
||||
},
|
||||
"count": 5 # Number of ideas to generate
|
||||
}
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```python
|
||||
{
|
||||
"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:**
|
||||
```python
|
||||
{
|
||||
"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:**
|
||||
```python
|
||||
{
|
||||
"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:**
|
||||
```python
|
||||
{
|
||||
"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:**
|
||||
```python
|
||||
{
|
||||
"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:**
|
||||
```python
|
||||
{
|
||||
"content": {
|
||||
"title": "...",
|
||||
"body": "...",
|
||||
"target_keyword": "..."
|
||||
},
|
||||
"optimization_type": "seo" | "readability" | "both"
|
||||
}
|
||||
```
|
||||
|
||||
**Planned Output:**
|
||||
```python
|
||||
{
|
||||
"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
|
||||
|
||||
```python
|
||||
{
|
||||
"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:
|
||||
|
||||
```python
|
||||
# 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
|
||||
|
||||
```python
|
||||
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
|
||||
|
||||
```python
|
||||
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.
|
||||
|
||||
```python
|
||||
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
|
||||
|
||||
```python
|
||||
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
|
||||
|
||||
```python
|
||||
# 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
|
||||
Reference in New Issue
Block a user