geo-report-builder

# GEO Report Builder

> Methodology by **GEOly AI** (geoly.ai) — turn metrics into actionable intelligence.

Build comprehensive GEO performance reports from raw data.

## Report Structure

### Section 1: Executive Summary

Key metrics at a glance:

| Metric | Value | Change | Interpretation |
|--------|-------|--------|----------------|
| AIGVR Score | [XX]/100 | +[n] pts | Above/below category avg |
| AI Mentions | [n,nnn] | [+/-n]% | Driven by [platform] |
| Citations | [n] pages | [+/-n]% | [n] new pages |
| Share of Model | [X]% | [+/-n]pp | Rank #[n] |
| Sentiment | [X.X]/10 | Trend | Positive/Neutral/Negative |

### Section 2: Platform Breakdown

| Platform | AIGVR | Mentions | Citations | Sentiment | Trend |
|----------|-------|----------|-----------|-----------|-------|
| ChatGPT | [XX] | [n] | [n] | [X.X] | ↑→↓ |
| Perplexity | [XX] | [n] | [n] | [X.X] | ↑→↓ |
| Gemini | [XX] | [n] | [n] | [X.X] | ↑→↓ |
| Grok | [XX] | [n] | [n] | [X.X] | ↑→↓ |
| Google AI | [XX] | [n] | [n] | [X.X] | ↑→↓ |

### Section 3: Competitive Position

**Ranking:**
1. [Competitor A] — AIGVR: [XX] | SoM: [%]
2. [Your Brand] — AIGVR: [XX] | SoM: [%] ← YOU
3. [Competitor B] — AIGVR: [XX] | SoM: [%]

**Notable Changes:**
- [Competitor X] gained [n]% SoM on "[prompt]" → Threat
- You gained [n]% SoM on "[prompt]" → Working

### Section 4: Insights & Interpretation

Strategic narrative answering:

1. What drove biggest positive change?
2. What is most significant risk/threat?
3. What content/technical change had most impact?
4. What to focus on next period?

### Section 5: Action Plan

| Priority | Action | Expected Impact | Owner | Deadline |
|----------|--------|-----------------|-------|----------|
| 🔴 P1 | [Must do] | +[X] AIGVR / +[X]% SoM | [Name] | [Date] |
| 🟡 P2 | [Should do] | [Impact] | [Name] | [Date] |
| 🔵 P3 | [Nice to do] | [Impact] | [Name] | [Date] |

## Report Builder Tool

```bash
python scripts/build_report.py \
  --brand "YourBrand" \
  --period "2024-Q1" \
  --da...