Spaces:
Running
Running
File size: 25,769 Bytes
5c429d4 6d71ef9 5c429d4 6d71ef9 5c429d4 6d71ef9 5c429d4 6d71ef9 5c429d4 6d71ef9 5c429d4 6d71ef9 5c429d4 6d71ef9 7dd26e8 b644d36 6d71ef9 7dd26e8 b644d36 7dd26e8 b644d36 6d71ef9 7dd26e8 6d71ef9 7dd26e8 6d71ef9 7dd26e8 6d71ef9 7dd26e8 5c429d4 6d71ef9 5c429d4 6d71ef9 5c429d4 6d71ef9 5c429d4 6d71ef9 5c429d4 6d71ef9 5c429d4 6d71ef9 5c429d4 6d71ef9 5c429d4 6d71ef9 5c429d4 6d71ef9 5c429d4 6d71ef9 04dc01d 6d71ef9 04dc01d 6d71ef9 04dc01d 6d71ef9 04dc01d 6d71ef9 5c429d4 6d71ef9 7dd26e8 6d71ef9 5c429d4 6d71ef9 5c429d4 6d71ef9 5c429d4 6d71ef9 7dd26e8 6d71ef9 5c429d4 6d71ef9 5c429d4 7dd26e8 6d71ef9 5c429d4 6d71ef9 5c429d4 6d71ef9 5c429d4 6d71ef9 5c429d4 6d71ef9 5c429d4 6d71ef9 5c429d4 6d71ef9 5c429d4 6d71ef9 5c429d4 6d71ef9 5c429d4 6d71ef9 5c429d4 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 | """AI Content Engine โ ู
ุญุฑู ุงูู
ุญุชูู ุจุงูุฐูุงุก ุงูุงุตุทูุงุนู
Supports: Groq (fast/free), OpenAI, Claude, Ollama.
2026 Standards: Grounded content, Entity graphs, Multi-schema, GEO local, Proof sections.
"""
import os
import json
import re
import requests
# โโ LLM backends โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
def _call_groq(prompt: str, api_key: str = None) -> str:
key = api_key or os.getenv('GROQ_API_KEY')
if not key:
raise RuntimeError('GROQ_API_KEY not set')
from groq import Groq
client = Groq(api_key=key)
resp = client.chat.completions.create(
model=os.getenv('GROQ_MODEL', 'llama-3.3-70b-versatile'),
messages=[{'role': 'user', 'content': prompt}],
temperature=0.2,
max_tokens=3000
)
return resp.choices[0].message.content
def _call_openai(prompt: str, api_key: str = None) -> str:
from openai import OpenAI
key = api_key or os.getenv('OPENAI_API_KEY')
if not key:
raise RuntimeError('OPENAI_API_KEY not set')
client = OpenAI(api_key=key)
resp = client.chat.completions.create(
model=os.getenv('OPENAI_MODEL', 'gpt-4o-mini'),
messages=[{'role': 'user', 'content': prompt}],
temperature=0.2,
max_tokens=3000
)
return resp.choices[0].message.content
def _call_claude(prompt: str, api_key: str = None) -> str:
key = api_key or os.getenv('CLAUDE_API_KEY') or os.getenv('ANTHROPIC_API_KEY')
if not key:
raise RuntimeError('CLAUDE_API_KEY not set')
resp = requests.post(
'https://api.anthropic.com/v1/messages',
headers={'x-api-key': key, 'anthropic-version': '2023-06-01', 'content-type': 'application/json'},
json={'model': os.getenv('CLAUDE_MODEL', 'claude-3-5-sonnet-20241022'),
'max_tokens': 3000, 'messages': [{'role': 'user', 'content': prompt}]},
timeout=60
)
resp.raise_for_status()
return resp.json()['content'][0]['text']
def _call_ollama(prompt: str, model: str = None) -> str:
host = os.getenv('OLLAMA_HOST', 'http://localhost:11434')
model = model or os.getenv('OLLAMA_MODEL', 'llama3')
resp = requests.post(f"{host}/api/chat", json={
'model': model,
'messages': [{'role': 'user', 'content': prompt}],
'stream': False
}, timeout=120)
resp.raise_for_status()
return resp.json()['message']['content']
def _call_demo(prompt: str) -> str:
"""Honest demo โ shows the STRUCTURE of what real output looks like, clearly marked as demo."""
prompt_lower = prompt.lower()
is_arabic = 'arabic' in prompt_lower or bool(re.search(r'[\u0600-\u06FF]', prompt))
# Extract keyword
kw_match = re.search(r'(?:TARGET KEYWORD|keyword)[:\s]+([^\n]+)', prompt, re.IGNORECASE)
keyword = kw_match.group(1).strip() if kw_match else 'your keyword'
# Extract brand โ try multiple patterns
brand = 'YourBrand'
for pattern in [
r'Brand[:\s]+([^\n,]+)',
r'BRAND[:\s]+([^\n,]+)',
r'BRAND/SITE[:\s]+([^\n,]+)',
r'target site[:\s]+([^\n,]+)',
]:
m = re.search(pattern, prompt, re.IGNORECASE)
if m:
candidate = m.group(1).strip()
# Clean URL from brand
if ',' in candidate:
parts = [p.strip() for p in candidate.split(',')]
candidate = next((p for p in parts if not p.startswith('http')), parts[-1])
if candidate.startswith('http'):
candidate = candidate.split('//')[-1].split('/')[0].replace('www.', '')
if candidate and candidate != 'YourBrand':
brand = candidate
break
# Extract real page content if passed
content_match = re.search(r'Page Content[:\s]+(.*?)(?:\n\n|\Z)', prompt, re.DOTALL | re.IGNORECASE)
real_snippet = content_match.group(1).strip()[:300] if content_match else ''
if 'faq' in prompt_lower:
if is_arabic:
return json.dumps({"faqs": [
{"question": f"ู
ุง ูู ุฎุฏู
ุงุช {brand}ุ",
"answer": f"[DEMO] {brand} ุชูุฏู
ุฎุฏู
ุงุช ู
ุชุฎุตุตุฉ ูู ู
ุฌุงู {keyword}. ูุชูููุฏ ุฅุฌุงุจุงุช ุญููููุฉ ู
ุจููุฉ ุนูู ุจูุงูุงุช ู
ููุนูุ ุฃุถู ู
ูุชุงุญ Groq API ูู ุงูุฅุนุฏุงุฏุงุช."},
{"question": f"ููู ูุณุงุนุฏ {brand} ูู ุชุญุณูู ุงูุธููุฑุ",
"answer": f"[DEMO] ู
ู ุฎูุงู ุงุณุชุฑุงุชูุฌูุงุช {keyword} ุงูู
ุฏุนูู
ุฉ ุจุงูุฐูุงุก ุงูุงุตุทูุงุนู. ุฃุถู Groq API ููุญุตูู ุนูู ุฅุฌุงุจุงุช ู
ุจููุฉ ุนูู ุจูุงูุงุช ุฒุญู ู
ููุนู ุงููุนููุฉ."}
]}, ensure_ascii=False)
return json.dumps({"faqs": [
{"question": f"What does {brand} offer for {keyword}?",
"answer": f"[DEMO] {brand} provides specialized {keyword} services. Add a Groq API key in Settings to generate answers grounded in your actual crawled data."},
{"question": f"How does {brand} improve {keyword} rankings?",
"answer": "[DEMO] Through AI-powered strategies. Connect your API key to generate evidence-based answers from your site's real content."}
]})
if 'optimize' in prompt_lower or 'analyze' in prompt_lower:
if is_arabic:
return json.dumps({
"score": 0,
"issues": [
"โ ๏ธ ูุถุน ุชุฌุฑูุจู โ ูุง ููุฌุฏ ู
ูุชุงุญ API",
"ูุง ูู
ูู ุชุญููู ุงูู
ุญุชูู ุจุฏูู Groq ุฃู OpenAI",
"ุฃุถู ู
ูุชุงุญ API ูู ุงูุฅุนุฏุงุฏุงุช ููุญุตูู ุนูู ุชุญููู ุญูููู"
],
"suggestions": [
"ุฃุถู ู
ูุชุงุญ Groq API (ู
ุฌุงูู) ููุญุตูู ุนูู ุชุญููู ููุฑู",
"ุชุฃูุฏ ู
ู ุฑุจุท ุจูุงูุงุช ุงูุฒุญู ุฃููุงู ู
ู ู
ุณุชูุฏุน ุงูุฃุจุญุงุซ"
],
"optimized_content": f"[DEMO MODE] ุฃุถู ู
ูุชุงุญ Groq API ููุญุตูู ุนูู ู
ุญุชูู ู
ุญุณูู ุญูููู ู
ุจูู ุนูู ุจูุงูุงุช {brand}.",
"schema": ""
}, ensure_ascii=False)
return json.dumps({
"score": 0,
"issues": ["โ ๏ธ Demo mode โ no API key connected", "Real analysis requires Groq or OpenAI key"],
"suggestions": ["Add a free Groq API key in Settings", "Connect crawled data from Research Repository first"],
"optimized_content": f"[DEMO MODE] Add Groq API key to get real optimized content grounded in {brand}'s actual data.",
"schema": ""
})
# Article generation demo
if is_arabic:
return json.dumps({
"title": f"[DEMO] {brand}: ุฏููู {keyword} โ ุฃุถู Groq API ููู
ุญุชูู ุงูุญูููู",
"meta_description": f"[DEMO] ูุตู ุชุนุฑููู ูู {brand} ูู ู
ุฌุงู {keyword}. ุฃุถู ู
ูุชุงุญ API ููุญุตูู ุนูู ูุตู ุญูููู.",
"content": f"""# [ูุถุน ุชุฌุฑูุจู โ ุฃุถู Groq API ููู
ุญุชูู ุงูุญูููู]
## ู
ุง ุงูุฐู ุณุชุญุตู ุนููู ุจุนุฏ ุฅุถุงูุฉ ู
ูุชุงุญ APIุ
### 1. ุงูุฅุฌุงุจุฉ ุงูู
ุจุงุดุฑุฉ (Direct Answer)
ู
ุญุชูู ู
ุญุฏุฏ ููุงุจู ููุงูุชุจุงุณ ู
ู ู
ุญุฑูุงุช ุงูุฐูุงุก ุงูุงุตุทูุงุนูุ ู
ุจูู ุนูู ุจูุงูุงุช ู
ููุน {brand} ุงููุนููุฉ.
{f'ุจูุงูุงุช ู
ู ู
ููุนู: {real_snippet}' if real_snippet else ''}
### 2. ุฎุฑูุทุฉ ุงูููุงูุงุช (Entity Graph)
```
{brand} โ (Organization/LocalBusiness)
โโโ provides โ [{keyword}]
โโโ operates_in โ [ุงูู
ุฏููุฉ/ุงูุฏููุฉ]
โโโ competes_with โ [ุงูู
ูุงูุณูู]
โโโ recognized_by โ [Google, Bing, Perplexity]
```
### 3. ุทุจูุฉ GEO ุงูู
ุญููุฉ
- ููู
ุงุช ู
ูุชุงุญูุฉ ู
ุญููุฉ: "{keyword} ูู ุงูุฑูุงุถ"ุ "{keyword} ุงูุณุนูุฏูุฉ"
- Google Maps integration
- LocalBusiness Schema
### 4. ูุณู
ุงูุฅุซุจุงุช (Proof Section)
- ุฃุฑูุงู
ูุฅุญุตุงุฆูุงุช ุญููููุฉ ู
ู ู
ููุนู
- Case studies
- ูุชุงุฆุฌ ูุงุจูุฉ ููููุงุณ
### 5. Schema ู
ุชูุงู
ู
Organization + LocalBusiness + Service + FAQ
---
โ๏ธ ูุชูุนูู ุงูู
ุญุชูู ุงูุญูููู: ุฃุถู ู
ูุชุงุญ Groq API ูู ุงูุฅุนุฏุงุฏุงุช (ู
ุฌุงูู ุนูู groq.com)""",
"faqs": [
{"question": f"[DEMO] ู
ุง ูู ุฎุฏู
ุงุช {brand}ุ",
"answer": "ุฃุถู Groq API ููุญุตูู ุนูู ุฅุฌุงุจุงุช ู
ุจููุฉ ุนูู ุจูุงูุงุช ู
ููุนู ุงููุนููุฉ."}
],
"schema": "",
"implemented_fixes": ["DEMO MODE โ add API key for real implementation"],
"backend": "demo"
}, ensure_ascii=False)
return json.dumps({
"title": f"[DEMO] {brand}: {keyword} Guide โ Add Groq API for Real Content",
"meta_description": f"[DEMO] Add a Groq API key to generate content grounded in {brand}'s actual crawled data.",
"content": f"""# [DEMO MODE โ Add Groq API for Real Content]
## What you'll get with a real API key:
### 1. Direct Answer (AI-Citable)
A specific, evidence-based 50-word answer about {brand} and {keyword}, built from your crawled pages.
{f'Your site data: {real_snippet}' if real_snippet else ''}
### 2. Entity Graph
```
{brand} โ (Organization)
โโโ provides โ [{keyword}]
โโโ operates_in โ [City/Country]
โโโ competes_with โ [Real competitors]
โโโ cited_by โ [ChatGPT, Perplexity, Google SGE]
```
### 3. GEO Local Layer
- Local keywords: "{keyword} in [City]", "best {keyword} [Country]"
- Google Maps signals
- LocalBusiness Schema
### 4. Proof Section
- Real metrics from your site
- Case studies
- Measurable outcomes
### 5. Full Schema Stack
Organization + LocalBusiness + Service + FAQ
---
โ๏ธ To activate: Add free Groq API key in Settings (groq.com)""",
"faqs": [
{"question": f"[DEMO] What does {brand} offer for {keyword}?",
"answer": "Add Groq API key to generate answers grounded in your actual site data."}
],
"schema": "",
"implemented_fixes": ["DEMO MODE โ add API key for real implementation"],
"backend": "demo"
})
def _llm_call(prompt: str, prefer: str = 'groq', api_keys: dict = None) -> dict:
"""Try backends in order. Returns {text, backend}."""
api_keys = api_keys or {}
order = [prefer] + [b for b in ['groq', 'openai', 'claude', 'ollama', 'demo'] if b != prefer]
errors = {}
for backend in order:
try:
if backend == 'groq':
return {'text': _call_groq(prompt, api_keys.get('groq')), 'backend': 'groq'}
elif backend == 'openai':
return {'text': _call_openai(prompt, api_keys.get('openai')), 'backend': 'openai'}
elif backend == 'claude':
return {'text': _call_claude(prompt, api_keys.get('claude')), 'backend': 'claude'}
elif backend == 'ollama':
return {'text': _call_ollama(prompt), 'backend': 'ollama'}
elif backend == 'demo':
return {'text': _call_demo(prompt), 'backend': 'demo'}
except Exception as e:
errors[backend] = str(e)
continue
return {'text': _call_demo(prompt), 'backend': 'demo'}
def _parse_json_from_text(text: str) -> dict:
"""Extract first JSON object from LLM response."""
json_match = re.search(r'```json\s*(\{.*?\})\s*```', text, re.DOTALL | re.IGNORECASE)
if not json_match:
json_match = re.search(r'(\{.*\})', text, re.DOTALL)
block = json_match.group(1).strip() if json_match else text.strip()
def repair(match):
inner = match.group(0)[1:-1]
inner = inner.replace('\n', '\\n').replace('\r', '\\r').replace('\t', '\\t')
return f'"{inner}"'
repaired = re.sub(r'"(?:\\.|[^"\\])*"', repair, block, flags=re.DOTALL)
try:
return json.loads(repaired, strict=False)
except Exception:
try:
return json.loads(block, strict=False)
except Exception:
raise ValueError('No JSON found in LLM response')
def _build_context_block(crawl_data: dict) -> str:
"""Build a grounded context block from real crawled data."""
if not crawl_data:
return ''
lines = ['=== GROUNDED DATA FROM CRAWLED SITE ===']
if crawl_data.get('org_name'):
lines.append(f'Brand: {crawl_data["org_name"]}')
if crawl_data.get('url'):
lines.append(f'Site: {crawl_data["url"]}')
if crawl_data.get('keywords'):
kws = [k.get('kw', k) if isinstance(k, dict) else k for k in crawl_data['keywords'][:15]]
lines.append(f'Top Keywords: {", ".join(kws)}')
if crawl_data.get('headings'):
lines.append(f'Site Structure: {" | ".join(crawl_data["headings"][:8])}')
if crawl_data.get('page_content'):
lines.append(f'Page Content Sample:\n{crawl_data["page_content"][:1000]}')
if crawl_data.get('competitors'):
lines.append(f'Detected Competitors: {", ".join(crawl_data["competitors"][:5])}')
if crawl_data.get('geo_score'):
gs = crawl_data['geo_score']
lines.append(f'Current GEO Score: {gs.get("score", 0)}% โ {gs.get("status", "")}')
if crawl_data.get('issues'):
lines.append(f'Critical Issues: {"; ".join(crawl_data["issues"][:5])}')
if crawl_data.get('local_regions'):
lines.append(f'Detected Regions: {", ".join(crawl_data["local_regions"])}')
lines.append('=== END GROUNDED DATA ===')
return '\n'.join(lines)
def _build_schema(brand: str, keyword: str, url: str, lang: str,
faqs: list = None, local_regions: list = None) -> str:
"""Build a complete multi-type Schema.org JSON-LD block."""
# Clean brand: if it contains a URL, extract just the org name
if ',' in brand:
parts = [p.strip() for p in brand.split(',')]
# pick the non-URL part
brand = next((p for p in parts if not p.startswith('http')), parts[-1])
if brand.startswith('http'):
# extract domain as brand fallback
brand = brand.split('//')[-1].split('/')[0].replace('www.', '')
schemas = []
# Organization / LocalBusiness
org = {
"@context": "https://schema.org",
"@type": "LocalBusiness" if local_regions else "Organization",
"name": brand,
"url": url or f"https://{brand.lower().replace(' ', '')}.com",
"description": f"{brand} provides {keyword} services",
"knowsAbout": [keyword],
}
if local_regions:
org["areaServed"] = local_regions
schemas.append(org)
# Service
schemas.append({
"@context": "https://schema.org",
"@type": "Service",
"name": keyword,
"provider": {"@type": "Organization", "name": brand},
"areaServed": local_regions or ["Global"],
"description": f"Professional {keyword} services by {brand}"
})
# FAQPage
if faqs:
schemas.append({
"@context": "https://schema.org",
"@type": "FAQPage",
"mainEntity": [
{"@type": "Question", "name": f["question"],
"acceptedAnswer": {"@type": "Answer", "text": f["answer"]}}
for f in faqs[:5]
]
})
return '\n'.join(
f'<script type="application/ld+json">\n{json.dumps(s, ensure_ascii=False, indent=2)}\n</script>'
for s in schemas
)
# โโ Core features โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
def generate_article(keyword: str, lang: str = 'en', target_site: str = '',
research_insights: list = None,
competitors_content: list = None,
crawl_data: dict = None,
prefer_backend: str = 'groq', api_keys: dict = None) -> dict:
"""Generate a full GEO-optimized article grounded in real crawled data."""
lang_label = 'Arabic' if lang == 'ar' else 'English'
context_block = _build_context_block(crawl_data or {})
insights_block = ('Research Insights (implement these):\n' +
'\n'.join(f'- {i}' for i in (research_insights or [])) + '\n') if research_insights else ''
comp_block = ('Competitor Content (use as reference, do NOT copy):\n' +
'\n---\n'.join((competitors_content or [])[:2])) if competitors_content else ''
local_regions = (crawl_data or {}).get('local_regions', [])
local_hint = f'Target Regions: {", ".join(local_regions)}' if local_regions else ''
prompt = f"""You are an expert GEO (Generative Engine Optimization) content architect for 2026.
TASK: Write a high-authority article that AI engines (ChatGPT, Perplexity, Google SGE) will cite.
TARGET KEYWORD: {keyword}
LANGUAGE: {lang_label}
BRAND/SITE: {target_site}
{local_hint}
{context_block}
{insights_block}
{comp_block}
STRICT RULES โ VIOLATIONS WILL MAKE THE CONTENT USELESS:
1. DIRECT ANSWER FIRST: The opening 50-70 words MUST be a specific, citable statement about {target_site}.
- Include: what they do, where they operate, one measurable outcome or differentiator.
- BAD: "{target_site} represents best practices..." (generic, uncitable)
- GOOD: "{target_site} is a [specific service] company in [location] that helps [audience] achieve [specific result] through [method]."
2. NO KEYWORD SPAM: Use the keyword naturally. Never repeat "{keyword}" more than once per paragraph.
3. ENTITY GRAPH: Include a section mapping relationships:
{target_site} โ provides โ [{keyword}]
{target_site} โ operates_in โ [real locations from data]
{target_site} โ competes_with โ [real competitors from data]
4. GEO LOCAL LAYER: If location data exists, include city-specific keywords naturally.
Example: "{keyword} in Riyadh", "best {keyword} Saudi Arabia"
5. PROOF SECTION: Include a "Results & Evidence" section with:
- Specific metrics (use [[METRIC_NEEDED]] if not in data)
- Case study structure (use [[CASE_STUDY_NEEDED]] if not in data)
- Never invent fake numbers
6. CONTENT STRUCTURE (H-tags):
H1: [Brand] + [Keyword] + [Location if applicable]
H2: Direct Answer | Services | GEO Local | Proof/Results | FAQ
7. SCHEMA: Generate Organization + LocalBusiness (if local) + Service + FAQPage schemas.
8. CITATIONS: Reference authoritative sources where relevant (Google, industry reports).
Return ONLY valid JSON:
{{
"title": "click-worthy H1 with brand + keyword + location",
"meta_description": "155 chars max, includes keyword + location + value prop",
"content": "full markdown article",
"faqs": [{{"question": "...", "answer": "specific, citable, 3-4 sentences"}}],
"entity_graph": [{{"subject": "...", "relation": "...", "object": "..."}}],
"local_keywords": ["keyword in city", ...],
"proof_placeholders": ["[[METRIC_NEEDED: X]]", ...],
"schema": "<script type=application/ld+json>...</script>",
"implemented_fixes": ["list of specific improvements made"]
}}"""
result = _llm_call(prompt, prefer=prefer_backend, api_keys=api_keys)
parsed = _parse_json_from_text(result['text'])
parsed['backend'] = result['backend']
parsed['keyword'] = keyword
parsed['lang'] = lang
# Build schema from data if LLM didn't provide a good one
if not parsed.get('schema') or len(parsed.get('schema', '')) < 100:
parsed['schema'] = _build_schema(
brand=target_site or keyword,
keyword=keyword,
url=(crawl_data or {}).get('url', ''),
lang=lang,
faqs=parsed.get('faqs', []),
local_regions=local_regions
)
return parsed
def optimize_content(content: str, keyword: str, lang: str = 'en', target_site: str = '',
research_insights: list = None,
crawl_data: dict = None,
prefer_backend: str = 'groq', api_keys: dict = None) -> dict:
"""Analyze and optimize existing content for GEO. Returns grounded improvements."""
lang_label = 'Arabic' if lang == 'ar' else 'English'
context_block = _build_context_block(crawl_data or {})
insights_block = ('Research Insights:\n' +
'\n'.join(f'- {i}' for i in (research_insights or [])) + '\n') if research_insights else ''
prompt = f"""You are an Elite GEO Content Auditor for 2026.
TASK: Audit and rewrite this content to maximize AI engine citation probability.
KEYWORD: {keyword}
LANGUAGE: {lang_label}
BRAND: {target_site}
{context_block}
{insights_block}
AUDIT CRITERIA (score each 0-20):
1. Direct Answer Quality: Does it open with a specific, citable statement? (not generic marketing)
2. Entity Coverage: Are brand, location, service, audience entities clearly defined?
3. Keyword Intent Match: Does content match what users actually search for?
4. Proof & Evidence: Are there specific numbers, results, case studies?
5. Schema Readiness: Is content structured for JSON-LD extraction?
REWRITE RULES:
- Fix the Direct Answer to be specific and citable
- Remove keyword spam (natural usage only)
- Add entity relationships explicitly
- Add [[PROOF_NEEDED: metric type]] where evidence is missing
- Add GEO local keywords if location data available
- Improve H-tag hierarchy
Return ONLY valid JSON:
{{
"score": 0-100,
"score_breakdown": {{"direct_answer": 0-20, "entities": 0-20, "intent": 0-20, "proof": 0-20, "schema": 0-20}},
"issues": ["specific issue with line/section reference"],
"suggestions": ["specific actionable fix"],
"optimized_content": "full rewritten content in markdown",
"schema": "<script type=application/ld+json>...</script>",
"implemented_fixes": ["what was changed and why"]
}}
CONTENT TO AUDIT:
{content[:3000]}"""
result = _llm_call(prompt, prefer=prefer_backend, api_keys=api_keys)
parsed = _parse_json_from_text(result['text'])
parsed['backend'] = result['backend']
return parsed
def generate_faqs(topic: str, page_content: str = None, lang: str = 'en', count: int = 5,
prefer_backend: str = 'groq', api_keys: dict = None,
target_site: str = '', research_insights: list = None,
crawl_data: dict = None) -> dict:
"""Generate FAQ pairs grounded in real crawled data."""
lang_label = 'Arabic' if lang == 'ar' else 'English'
context_block = _build_context_block(crawl_data or {})
insights_block = ('Research Insights:\n' +
'\n'.join(f'- {i}' for i in (research_insights or [])) + '\n') if research_insights else ''
context = f'\nPage Content:\n{page_content[:1500]}' if page_content else ''
prompt = f"""Generate {count} high-performance GEO FAQ pairs for AI engine citation.
TOPIC: {topic}
LANGUAGE: {lang_label}
BRAND: {target_site}
{context_block}
{insights_block}{context}
FAQ QUALITY RULES:
1. Questions must be REAL user queries (long-tail, conversational, as asked on Perplexity/ChatGPT)
- BAD: "What is {topic}?" (too generic)
- GOOD: "How does {target_site} help businesses improve {topic} in [location]?"
2. Answers must be SPECIFIC and CITABLE:
- Lead with a direct fact from the crawled data
- Include brand name, service, location where relevant
- 3-4 sentences max
- Never use generic phrases like "in today's digital landscape"
3. Cover these intent types: Informational, Commercial, Local/GEO
Return ONLY JSON: {{"faqs": [{{"question": "...", "answer": "..."}}]}}"""
result = _llm_call(prompt, prefer=prefer_backend, api_keys=api_keys)
parsed = _parse_json_from_text(result['text'])
parsed['backend'] = result['backend']
parsed['topic'] = topic
parsed['lang'] = lang
return parsed
def semantic_optimize(content: str, lang: str = 'en',
prefer_backend: str = 'groq', api_keys: dict = None) -> dict:
"""Extract semantic entities, build entity graph, suggest LSI keywords."""
lang_label = 'Arabic' if lang == 'ar' else 'English'
entities_extracted = []
if lang == 'ar':
try:
from src import arabic_tools
ner_res = arabic_tools.extract_entities_arabic(content)
for e in ner_res.get('entities', []):
entities_extracted.append({'text': e['text'], 'type': e['label']})
except Exception:
pass
prompt = f"""Perform deep semantic analysis on this {lang_label} content for GEO optimization.
Return ONLY valid JSON:
{{
"entities": [{{"text": "...", "type": "ORG|PERSON|PRODUCT|PLACE|CONCEPT|SERVICE"}}],
"entity_graph": [{{"subject": "...", "relation": "provides|operates_in|competes_with|serves|part_of", "object": "..."}}],
"topics": ["main topics covered"],
"lsi_keywords": ["semantically related keywords to add"],
"missing_entities": ["important entities not mentioned"],
"local_signals": ["any location/GEO signals found"],
"semantic_score": 0-100,
"missing_concepts": ["important concepts not covered"]
}}
Content:
{content[:3000]}"""
result = _llm_call(prompt, prefer=prefer_backend, api_keys=api_keys)
parsed = _parse_json_from_text(result['text'])
if lang == 'ar' and entities_extracted:
existing = {e['text'].lower() for e in parsed.get('entities', [])}
for e in entities_extracted:
if e['text'].lower() not in existing:
parsed.setdefault('entities', []).append(e)
parsed['backend'] = result['backend']
return parsed
|