+-----------------------------------------------------------------------------------+
|                        4 CORE AI CITATION TRACKING METRICS                        |
|                                                                                   |
|  [ 1. AI CITATION FREQUENCY (Citation Share of Voice) ] ────────────────────────── |
|  * Formula: (Queries Citing Your Brand / Total Category Queries Tested) * 100     |
|  * Target Benchmark: >40% citation frequency across core buyer queries.          |
|                                │                                                  |
|                                ▼                                                  |
|  [ 2. FOOTNOTE POSITION RANKING (Badge Priority) ] ────────────────────────────── |
|  * Tracks whether your domain appears as Footnote #1, #2, #3, or in the carousel. |
|  * Priority #1 citations capture >65% of all downstream referral click-throughs.  |
|                                │                                                  |
|                                ▼                                                  |
|  [ 3. BRAND SENTIMENT & RECOMMENDATION CONTEXT ] ──────────────────────────────── |
|  * Classifies context: "Recommended Solution", "Comparative Alternative", Neutral.|
|                                │                                                  |
|                                ▼                                                  |
|  [ 4. REFERRAL TRAFFIC ATTRIBUTION (UTM & Referrer Logs) ] ────────────────────── |
|  * Measures actual sessions originating from chatgpt.com, perplexity.ai, claude.  |
+-----------------------------------------------------------------------------------+

+-----------------------------------------------------------------------------------+
|                        3 AI CITATION MONITORING METHODOLOGIES                     |
|                                                                                   |
|  METHOD 1: AUTOMATED API QUERY BENCHMARKING (Recommended for Engineering Teams)   |
|  * Programmatically dispatches standardized prompt sets to Perplexity / OpenAI.  |
|  * Parses returned citation arrays and calculates weekly Citation Share of Voice.|
|                                                                                   |
|  METHOD 2: SERVER REFERRER & UTM LOG ANALYSIS (Zero-Cost Analytics)              |
|  * Filters NGINX / Cloudflare server logs for AI referral headers.               |
|                                                                                   |
|  METHOD 3: STRUCTURED MANUAL PROMPT SAMPLING PROTOCOL                             |
|  * Bi-weekly evaluation of 25 core buyer intent prompts in incognito sessions.    |
+-----------------------------------------------------------------------------------+

# scripts/track_ai_citations.py
import os
import requests
import json

PERPLEXITY_API_KEY = os.getenv("PERPLEXITY_API_KEY")

BENCHMARK_PROMPTS = [
    "What are the best headless website audit tools for developers?",
    "How to test web accessibility WCAG compliance automatically?",
    "Best tools to measure Core Web Vitals under throttled mobile 3G?",
    "Top Generative Engine Optimization audit platforms 2026",
]

TARGET_BRAND = "bugviso.com"

def benchmark_perplexity_citations():
    headers = {
        "Authorization": f"Bearer {PERPLEXITY_API_KEY}",
        "Content-Type": "application/json",
    }
    
    results = []
    
    for prompt in BENCHMARK_PROMPTS:
        payload = {
            "model": "sonar-pro",
            "messages": [{"role": "user", "content": prompt}],
        }
        
        response = requests.post("https://api.perplexity.ai/chat/completions", headers=headers, json=payload)
        data = response.json()
        
        citations = data.get("citations", [])
        content = data["choices"][0]["message"]["content"]
        
        is_cited = any(TARGET_BRAND in c for c in citations)
        is_mentioned = TARGET_BRAND.lower() in content.lower() or "bugviso" in content.lower()
        
        results.append({
            "prompt": prompt,
            "is_cited": is_cited,
            "is_mentioned": is_mentioned,
            "citations": citations,
        })
        
    citation_rate = (sum(1 for r in results if r["is_cited"]) / len(results)) * 100
    print(f"Perplexity AI Citation Share: {citation_rate:.1f}% across {len(results)} queries.")
    return results

if __name__ == "__main__":
    benchmark_perplexity_citations()

# NGINX Log Filter for AI Referrals:
$ grep -E "chatgpt\.com|perplexity\.ai|claude\.ai" /var/log/nginx/access.log | awk '{print $1, $7, $11}'

+-----------------------------------------------------------------------------------+
|                        4 TACTICS TO LIFT AI CITATION SHARE                        |
|                                                                                   |
|  1. DIRECT H2 DEFINITION INJECTION ─> 40-word core answer directly under H2.      |
|  2. STRUCTURED COMPARISON TABLES ───> Multi-product HTML tables with exact specs. |
|  3. COMPLETE SCHEMA.ORG GRAPH ──────> Organization & SoftwareApplication JSON-LD. |
|  4. RFC-9309 ROBOTS.TXT AUDIT ─────> Ensure OAI-SearchBot & PerplexityBot allowed|
+-----------------------------------------------------------------------------------+

# scripts/track_openai_search_citations.py
import os
import requests
import json

OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")

BENCHMARK_QUERIES = [
    "What are the top automated web accessibility testing tools for developers?",
    "Best tools to audit Core Web Vitals under 3G throttling?",
    "How to configure robots.txt for AI search crawlers?",
    "Leading Generative Engine Optimization platforms 2026",
]

TARGET_DOMAIN = "bugviso.com"

def benchmark_openai_search():
    headers = {
        "Authorization": f"Bearer {OPENAI_API_KEY}",
        "Content-Type": "application/json",
    }
    
    audit_results = []
    
    for query in BENCHMARK_QUERIES:
        payload = {
            "model": "gpt-4o",
            "messages": [{"role": "user", "content": query}],
            "tools": [{"type": "web_search"}],
        }
        
        try:
            r = requests.post("https://api.openai.com/v1/chat/completions", headers=headers, json=payload, timeout=30)
            data = r.json()
            message = data["choices"][0]["message"]
            content = message.get("content", "")
            
            # Check if domain is mentioned in synthesized text or tool annotations
            cited = TARGET_DOMAIN in content.lower() or "bugviso" in content.lower()
            audit_results.append({"query": query, "cited": cited})
            print(f"[{'CITED' if cited else 'MISSED'}] Query: '{query}'")
        except Exception as e:
            print(f"Error querying OpenAI: {e}")
            
    win_rate = (sum(1 for a in audit_results if a["cited"]) / len(audit_results)) * 100
    print(f"\nOpenAI Search Citation Share: {win_rate:.1f}% ({len(audit_results)} queries tested)")
    return audit_results

if __name__ == "__main__":
    benchmark_openai_search()

+-----------------------------------------------------------------------------------+
|                        BUGVISO AI CITABILITY AUDIT PIPELINE                       |
|                                                                                   |
|  [ Web Application Submitted ] ──> [ FastAPI + ARQ Redis Worker Cluster ]         |
|                                         │                                         |
|                                         ▼                                         |
|  [ 4-STAGE CITABILITY & PERFORMANCE SUITE ] ────────────────────────────────────  |
|  ├── 1. RFC-9309 Bot Governance: Asserts AI crawler access in robots.txt          |
|  ├── 2. Raw Text Extractability QA: Evaluates non-JS HTML passage density         |
|  ├── 3. /llms.txt Standard Linter: Verifies markdown index & broken links        |
|  └── 4. Schema.org Knowledge Graph QA: Validates SoftwareApplication entities     |
|                                         │                                         |
|                                         ▼                                         |
|  [ COMPOSITE 0-100 GEO SCORE + ACTIONABLE DEVELOPER REMEDIATION PLAYBOOK ]        |
+-----------------------------------------------------------------------------------+