/ revenue-intelligence / README.md
README.md
1 # 📊 AI Revenue Intelligence 2 3 > **Prove content ROI, extract call intelligence, and generate client reports — automatically.** 4 5 An AI-powered revenue intelligence suite that connects the dots between sales calls, content performance, and closed deals. These tools pull from Gong, GA4, HubSpot, and Ahrefs to answer the questions every marketing team hates: "What content actually drove revenue?" and "What are prospects really saying on calls?" 6 7 Built in production at [Single Grain](https://www.singlegrain.com/?utm_source=github&utm_medium=skill_repo&utm_campaign=ai_marketing_skills). Now open-sourced for any revenue-focused marketing team. 8 9 --- 10 11 ## Architecture 12 13 ``` 14 ┌─────────────────────────────────────────────────────────────────────┐ 15 │ DATA SOURCES │ 16 │ │ 17 │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │ 18 │ │ Gong │ │ GA4 │ │ HubSpot │ │ Ahrefs │ │ 19 │ │ (calls) │ │(traffic) │ │ (deals) │ │ (SEO) │ │ 20 │ └─────┬────┘ └─────┬────┘ └─────┬────┘ └────────┬─────────┘ │ 21 └────────┼──────────────┼─────────────┼────────────────┼─────────────┘ 22 │ │ │ │ 23 ▼ │ │ │ 24 ┌──────────────────┐ │ │ │ 25 │ Gong-to-Insight │ │ │ │ 26 │ Pipeline │ │ │ │ 27 │ │ │ │ │ 28 │ • Objections │ │ │ │ 29 │ • Buying signals │ │ │ │ 30 │ • Competitors │ │ │ │ 31 │ • Content topics │ │ │ │ 32 │ • Follow-ups │ │ │ │ 33 └──────┬───────────┘ │ │ │ 34 │ ▼ ▼ │ 35 │ ┌───────────────────────────┐ │ 36 │ │ Revenue Attribution │ │ 37 │ │ Mapper │ │ 38 │ │ │ │ 39 │ │ • First-touch / linear / │ │ 40 │ │ time-decay attribution │ │ 41 │ │ • Content ROI by type │ │ 42 │ │ • CPA calculations │ │ 43 │ │ • Content gap analysis │ │ 44 │ └───────────┬───────────────┘ │ 45 │ │ │ 46 ▼ ▼ ▼ 47 ┌──────────────────────────────────────────────────────────────┐ 48 │ Client Report Generator │ 49 │ │ 50 │ Executive Summary + Traffic + Pipeline + SEO + Call Quality │ 51 │ Anomaly Detection + Period-over-Period Comparison │ 52 │ → Markdown or JSON output │ 53 └──────────────────────────────────────────────────────────────┘ 54 ``` 55 56 --- 57 58 ## Tools 59 60 ### 1. 🎙️ Gong-to-Insight Pipeline (`gong_insight_pipeline.py`) 61 62 Turns sales call transcripts into structured intelligence. Works with the Gong API or plain `.txt` transcript files. 63 64 **What it extracts:** 65 - **Objections** — categorized as pricing, timing, competition, authority, or need 66 - **Buying signals** — budget confirmed, timeline mentioned, decision maker engaged, champion identified 67 - **Competitive mentions** — which competitors were named and in what sentiment (positive/negative/neutral) 68 - **Pricing discussions** — dollar amounts, pricing model questions, ROI concerns 69 - **Content topics** — recurring objection patterns that should become blog posts, case studies, or battle cards 70 - **Follow-up drafts** — personalized outbound suggestions based on what happened on the call 71 72 ```bash 73 # Analyze a transcript file 74 python gong_insight_pipeline.py --file transcript.txt 75 76 # Analyze a directory of transcripts 77 python gong_insight_pipeline.py --dir ./transcripts/ --content-topics 78 79 # Pull from Gong API (last 7 days) 80 python gong_insight_pipeline.py --gong --days 7 81 82 # Full output with follow-ups 83 python gong_insight_pipeline.py --file call.txt --follow-ups --output insights.json 84 85 # Example output: 86 # ============================================================ 87 # Call: discovery-call-acme 88 # Temperature: WARM 89 # ============================================================ 90 # 91 # 🚫 Objections (3): 92 # pricing: 2 93 # timing: 1 94 # → [pricing] "That's a bit more than we budgeted for this quarter" 95 # → [pricing] "Can you do a smaller pilot first?" 96 # → [timing] "We're in the middle of a platform migration" 97 # 98 # ✅ Buying Signals (2): 99 # budget_confirmed: 1 100 # champion_identified: 1 101 # 102 # ⚔️ Competitors: HubSpot, Drift 103 # 104 # 💰 Pricing discussed: Yes (3 mentions) 105 ``` 106 107 ### 2. 💰 Revenue Attribution Mapper (`revenue_attribution.py`) 108 109 The "prove content ROI" tool. Maps blog posts, videos, podcasts, and webinars to actual closed deals using first-touch, linear, or time-decay attribution models. 110 111 **What it produces:** 112 - Content-to-revenue mapping showing exactly which pieces drove pipeline 113 - Attribution across three models (pick the one that fits your sales motion) 114 - Cost-per-acquisition by content type (blog vs. video vs. webinar vs. podcast) 115 - Content gap analysis (which funnel stages have no content working?) 116 - Top performers ranked by attributed revenue 117 118 ```bash 119 # Full attribution report (linear model) 120 python revenue_attribution.py --report 121 122 # Time-decay model (more credit to recent touchpoints) 123 python revenue_attribution.py --report --model time-decay 124 125 # Content gaps (which funnel stages are uncovered?) 126 python revenue_attribution.py --gaps 127 128 # CPA by content type 129 python revenue_attribution.py --cpa --costs content_costs.json 130 131 # Example output: 132 # ====================================================================== 133 # CONTENT REVENUE ATTRIBUTION REPORT 134 # Model: linear 135 # ====================================================================== 136 # 137 # 📊 Summary 138 # Total Revenue: $984,000 139 # Total Deals: 5 140 # Avg Deal Size: $196,800 141 # Content w/ Attribution: 13 142 # Avg Touchpoints/Deal: 4.4 143 # 144 # 📈 Revenue by Content Type 145 # Type Revenue Sessions Pieces Avg/Piece 146 # -------------------------------------------------------- 147 # landing_page $211,200 1,800 1 $211,200 148 # blog $298,560 17,000 6 $49,760 149 # case_study $156,000 2,090 2 $78,000 150 # ... 151 ``` 152 153 ### 3. 📋 Multi-Source Client Report Generator (`client_report_generator.py`) 154 155 Pulls from all four data sources (GA4, HubSpot, Ahrefs, Gong) and generates a unified, client-ready BI report with an auto-generated executive summary and optional anomaly detection. 156 157 **What it includes:** 158 - **Executive summary** — auto-generated highlights, concerns, and recommendations 159 - **Traffic** — sessions, users, conversions, channel breakdown, top pages (GA4) 160 - **Pipeline** — deals created/won/lost, revenue, win rate, avg cycle (HubSpot) 161 - **SEO** — domain rating, rankings, backlinks, organic traffic (Ahrefs) 162 - **Call quality** — talk ratio, call duration, next-steps rate, top topics (Gong) 163 - **Anomaly detection** — flags unusual changes with severity levels 164 - **Period comparison** — month-over-month, quarter-over-quarter, or year-over-year 165 166 ```bash 167 # Console summary 168 python client_report_generator.py --client "Acme Corp" 169 170 # Full markdown report 171 python client_report_generator.py --client "Acme Corp" --format markdown --output report.md 172 173 # JSON for dashboards/slides 174 python client_report_generator.py --client "Acme Corp" --format json --anomalies 175 176 # Skip sources you don't use 177 python client_report_generator.py --client "Acme Corp" --skip gong,ahrefs 178 179 # Example output: 180 # ====================================================================== 181 # Acme Corp - Performance Report 182 # 2025-03-01 to 2025-03-31 183 # ====================================================================== 184 # 185 # 🟢 Overall: Strong 186 # 187 # ✅ Highlights: 188 # • Traffic up 8.1% (45,200 sessions) 189 # • Conversions up 14.8% (342 total) 190 # • Win rate at 60.0% (12 won) 191 # • $1,440,000 revenue closed 192 # 193 # ⚠️ Concerns: 194 # • Reps talking too much (54.2% talk ratio) 195 ``` 196 197 --- 198 199 ## Quick Start 200 201 ### 1. Install dependencies 202 203 ```bash 204 pip install -r requirements.txt 205 ``` 206 207 ### 2. Configure environment 208 209 ```bash 210 cp .env.example .env 211 # Edit .env with your API keys 212 ``` 213 214 ### 3. Test with sample data 215 216 All tools ship with built-in sample data and fall back gracefully when API keys aren't configured. Try them out of the box: 217 218 ```bash 219 # Analyze a transcript 220 echo "Prospect: That's more than we budgeted for this quarter. 221 Rep: I understand. What range were you expecting? 222 Prospect: We were looking at HubSpot too, they quoted us around 50k. 223 Rep: Makes sense. Our ROI calculator shows 3x return in year one." > sample.txt 224 225 python gong_insight_pipeline.py --file sample.txt --follow-ups 226 227 # Run attribution report (uses sample data without API keys) 228 python revenue_attribution.py --report --gaps 229 230 # Generate client report (uses sample data without API keys) 231 python client_report_generator.py --client "Demo Corp" --anomalies 232 ``` 233 234 ### 4. Connect real APIs 235 236 Set these environment variables to connect live data: 237 238 ```bash 239 # Gong 240 export GONG_API_KEY="your-gong-api-key" 241 242 # GA4 243 export GA4_PROPERTY_ID="123456789" 244 export GA4_CREDENTIALS_JSON="/path/to/service-account.json" 245 246 # HubSpot 247 export HUBSPOT_API_KEY="your-hubspot-private-app-token" 248 249 # Ahrefs 250 export AHREFS_TOKEN="your-ahrefs-api-token" 251 ``` 252 253 --- 254 255 ## Configuration 256 257 | Variable | Required By | Description | 258 |----------|-------------|-------------| 259 | `GONG_API_KEY` | Gong Pipeline, Client Report | Gong API access key | 260 | `GONG_API_BASE_URL` | Gong Pipeline, Client Report | Gong API URL (default: `https://api.gong.io/v2`) | 261 | `GA4_PROPERTY_ID` | Attribution, Client Report | GA4 property ID | 262 | `GA4_CREDENTIALS_JSON` | Attribution, Client Report | Path to GA4 service account JSON | 263 | `HUBSPOT_API_KEY` | Attribution, Client Report | HubSpot private app token | 264 | `AHREFS_TOKEN` | Client Report | Ahrefs API token | 265 | `YOUR_DOMAIN` | Client Report | Your root domain for Ahrefs data | 266 | `OUTPUT_DIR` | All | Output directory (default: `./output`) | 267 268 --- 269 270 ## Customization 271 272 ### Objection Patterns 273 Edit `OBJECTION_PATTERNS` in `gong_insight_pipeline.py` to match your industry's objection language. 274 275 ### Competitor List 276 Edit `KNOWN_COMPETITORS` in `gong_insight_pipeline.py` with your actual competitive landscape. 277 278 ### Content Type Classification 279 Edit `CONTENT_TYPE_PATTERNS` in `revenue_attribution.py` to match your site's URL structure. 280 281 ### Anomaly Thresholds 282 Pass custom thresholds to `detect_anomalies()` in `client_report_generator.py`: 283 ```python 284 thresholds = {"warning": 0.15, "critical": 0.30} # 15% = warning, 30% = critical 285 ``` 286 287 --- 288 289 ## How They Work Together 290 291 1. **Weekly**: Run `gong_insight_pipeline.py` on recent calls → extract objections and buying signals 292 2. **Monthly**: Run `revenue_attribution.py` → see which content drove deals 293 3. **Monthly**: Run `client_report_generator.py` → deliver unified report to clients or leadership 294 4. **Quarterly**: Use Gong content topics + attribution gaps to plan next quarter's content 295 296 The insight loop: 297 - Gong reveals what prospects ask about → creates content topics 298 - Content gets published → drives traffic (GA4) 299 - Traffic converts to pipeline → deals close (HubSpot) 300 - Attribution mapper proves which content worked → invest more in winners 301 - Repeat 302 303 --- 304 305 ## File Structure 306 307 ``` 308 revenue-intelligence/ 309 ├── README.md # This file 310 ├── SKILL.md # Claude Code agent skill definition 311 ├── requirements.txt # Python dependencies 312 ├── gong_insight_pipeline.py # Call transcript → structured insights 313 ├── revenue_attribution.py # Content → revenue mapping 314 └── client_report_generator.py # Multi-source client BI reports 315 ``` 316 317 --- 318 319 <div align="center"> 320 321 **🧠 [Want these built and managed for you? →](https://singlebrain.com/?utm_source=github&utm_medium=skill_repo&utm_campaign=ai_marketing_skills)** 322 323 *This is how we build agents at [Single Brain](https://singlebrain.com/?utm_source=github&utm_medium=skill_repo&utm_campaign=ai_marketing_skills) for our clients.* 324 325 [Single Grain](https://www.singlegrain.com/?utm_source=github&utm_medium=skill_repo&utm_campaign=ai_marketing_skills) · our marketing agency 326 327 📬 **[Level up your marketing with 14,000+ marketers and founders →](https://levelingup.beehiiv.com/subscribe)** *(free)* 328 329 </div>