rc-insights 0.1.0

AI-powered subscription analytics agent for RevenueCat's Charts API

📊 RC Insights — AI-Powered Subscription Analytics for RevenueCat

Your subscription metrics, analyzed by AI. RC Insights connects to RevenueCat's Charts API, pulls your data, and generates actionable health reports — so you can stop guessing and start growing.

---

What Is This?

RC Insights is an open-source tool that turns your RevenueCat Charts API data into intelligence. It comes in three flavors:

Mode	Best For
🖥️ CLI	Quick terminal reports, CI/CD pipelines, cron jobs
🌐 Web Dashboard	Interactive exploration with charts and export
📦 Python Library	Building your own analytics on top of the Charts API

Key Features

• 🔌 Charts API v2 Coverage — 9 confirmed-working chart types (revenue, MRR, churn, actives, customers, refund rate)
• 🧠 AI Analysis — GPT-4o-mini generates insights, anomaly detection, and recommendations
• 📊 Health Score — Single 0-100 number summarizing your subscription business health
• 📈 Trend Detection — Automatic week-over-week comparison across all metrics
• 📄 Export — Markdown and HTML reports you can share with your team
• 🔧 Heuristic Fallback — Works without any LLM key using rule-based analysis
• 🤖 100+ LLM Providers — OpenAI, Anthropic Claude, Ollama (local/free), Groq, Mistral, and more via litellm
• 🚨 Threshold Alerts — Define custom alert rules in YAML (if churn > 8%, alert)
• 📅 Cohort Retention — Weekly cohort analysis derived from subscriber data
• 💬 Slack/Discord — Send reports directly to your team channel via webhooks
• 📧 Email Reports — Deliver styled HTML reports via Resend
• 🔗 RevenueCat Webhooks — Real-time event processing for purchases, cancellations, billing issues
• ⚡ GitHub Action — Automated weekly health checks in CI

---

Quick Start

1. Install

pip install git+https://github.com/arimetabot/rc-insights.git

Or clone and install locally:

git clone https://github.com/arimetabot/rc-insights.git
cd rc-insights
pip install -e ".[web]"  # Include Streamlit dashboard

2. Configure

export RC_API_KEY=sk_your_revenuecat_key
export RC_PROJECT_ID=proj1ab2c3d4
export OPENAI_API_KEY=sk-your-openai-key  # Optional, for AI insights

Or create a .env file:

cp .env.example .env
# Edit .env with your keys

3. Generate a Report

# Full health report with AI insights
rc-insights report

# Just the overview metrics
rc-insights overview

# A specific chart
rc-insights chart mrr --days 90 --resolution week

4. Launch the Web Dashboard

streamlit run app.py

---

Live Demo — Dark Noise App

Real output from running RC Insights against the Dark Noise app (proj058a6330), March 11, 2026:

$ rc-insights overview --project-id proj058a6330

           📋 Overview Metrics
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━┳━━━━━━━━┓
┃ Metric                                     ┃     Value ┃ Unit ┃ Period ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━╇━━━━━━━━┩
│ Active Trials                              │     57.00 │ #    │ P0D    │
│ Active Subscriptions                       │  2,519.00 │ #    │ P0D    │
│ MRR                                        │  4,537.00 │ $    │ P28D   │
│ Revenue                                    │  4,795.00 │ $    │ P28D   │
│ New Customers                              │  1,615.00 │ #    │ P28D   │
│ Active Users                               │ 14,098.00 │ #    │ P28D   │
│ Number of transactions in the last 28 days │    600.00 │ #    │ P28D   │
└────────────────────────────────────────────┴───────────┴──────┴────────┘

$ rc-insights report --project-id proj058a6330 --no-ai

╭───────────────── 📊 Subscription Health Report ──────────────────╮
│ 42/100 — Mixed ⚠️                                                │
│                                                                   │
│ Your subscription metrics show mixed signals.                     │
│ Bright spots: Churn Improving.                                    │
╰───────────────────────────────────────────────────────────────────╯

                     🧠 Insights
┏━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┓
┃    ┃ Issue                        ┃ Metric    ┃ Recommendation       ┃
┡━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━┩
│ 🔵 │ MRR Stable                   │ $4,534.00 │ Focus on acquisition │
│ 🟡 │ MRR Growth Rate Slowing      │ -56.0%    │ Consider pricing...  │
│ 🟢 │ Churn Improving              │ -33.9%    │ Reinforce retention  │
│ 🟡 │ Elevated Refund Rate         │ 12.2%     │ Review refund reasons│
│ 🟡 │ New Customer Acquisition     │ -24.1%    │ Check app store...   │
│    │ Slowing                      │           │                      │
└────┴──────────────────────────────┴───────────┴──────────────────────┘

✓ Saved: reports/report_20260311_1501.md
✓ Saved: reports/report_20260311_1501.html

Markdown report (generated in under 30 seconds):

## Health Score: 42/100 — Mixed ⚠️
[████████░░░░░░░░░░░░] 42%

### Executive Summary
Your subscription metrics show mixed signals. Bright spots: Churn Improving.

## 📋 Key Metrics
| Metric                | Value     | Period |
|-----------------------|-----------|--------|
| Active Subscriptions  | 2,519     |  P0D   |
| MRR                   | $4,537    |  P28D  |
| Revenue               | $4,795    |  P28D  |
| New Customers         | 1,615     |  P28D  |
| Active Users          | 14,098    |  P28D  |

## 📈 Charts Summary
| Chart             | Latest    | Min       | Max       | Trend        |
|-------------------|-----------|-----------|-----------|--------------|
| Revenue           | $8.00     | $5.00     | $334.81   | 📉 -9.9%    |
| MRR               | $4,534.00 | $4,510.19 | $4,568.95 | ➡️ -0.8%   |
| MRR Movement      | $0.24     | -$24.18   | $29.42    | 📉 -56.0%   |
| Churn             | 0.20      | 0.08      | 2,545.00  | 📉 -33.9%   |
| Active Subs       | 2,519     | 2,512     | 2,545     | ➡️ -0.9%   |
| New Customers     | 48        | 46        | 94        | 📉 -24.1%   |

---

Architecture

┌──────────────────────────────────────────────────────┐
│                    RC Insights                        │
│                                                       │
│  ┌──────────┐  ┌──────────────┐  ┌────────────────┐ │
│  │   CLI    │  │ Web Dashboard│  │ Python Library │ │
│  │  (Typer) │  │ (Streamlit)  │  │   (importable) │ │
│  └────┬─────┘  └──────┬───────┘  └───────┬────────┘ │
│       │               │                   │          │
│  ┌────┴───────────────┴───────────────────┴────────┐ │
│  │           SubscriptionAnalyzer                   │ │
│  │   • Orchestrates data fetch + analysis           │ │
│  │   • AI mode (OpenAI) or Heuristic fallback       │ │
│  └──────────────────┬──────────────────────────────┘ │
│                     │                                 │
│  ┌──────────────────┴──────────────────────────────┐ │
│  │              ChartsClient                        │ │
│  │   • Auth, retries, rate limiting                 │ │
│  │   • 9 verified chart endpoints                   │ │
│  │   • Typed responses (Pydantic)                   │ │
│  └──────────────────┬──────────────────────────────┘ │
│                     │                                 │
└─────────────────────┼─────────────────────────────────┘
                      │
              ┌───────┴───────┐
              │ RevenueCat    │
              │ Charts API v2 │
              └───────────────┘

---

Usage Examples

As a Python Library

from rc_insights import ChartsClient, SubscriptionAnalyzer

# Low-level: Direct API access
with ChartsClient(api_key="sk_...", project_id="proj...") as client:
    overview = client.get_overview()
    print(f"MRR: ${overview.mrr:,.2f}")
    
    revenue = client.get_chart("revenue", start_date="2025-01-01", end_date="2025-12-31")
    for timestamp, value in revenue.data_points:
        print(f"  {timestamp.date()}: ${value:,.2f}")

# High-level: Full analysis with AI
with SubscriptionAnalyzer(
    rc_api_key="sk_...",
    rc_project_id="proj...",
    openai_api_key="sk-...",  # Optional
) as analyzer:
    report = analyzer.generate_report(days=30)
    
    print(f"Health Score: {report.overall_health_score}/100")
    print(f"Summary: {report.summary}")
    
    for insight in report.insights:
        print(f"  [{insight.severity}] {insight.title}: {insight.recommendation}")

CLI Commands

# Generate a 90-day report with weekly resolution
rc-insights report --days 90 --resolution week

# Save only markdown (skip HTML)
rc-insights report --format md --output ./my-reports

# Skip AI, use heuristic analysis
rc-insights report --no-ai

# Check your connection
rc-insights check

# List all available charts
rc-insights charts

# Pull a specific chart
rc-insights chart churn --days 60
rc-insights chart mrr --resolution month

---

Available Charts

All chart slugs below are verified working against the live RevenueCat Charts API v2.

Category	Charts
💰 Revenue	revenue, mrr, mrr_movement
👥 Subscribers	actives, actives_new, customers_new, customers_active
📉 Health	churn, refund_rate

Note: Some chart slugs documented in the RevenueCat dashboard return HTTP 400 errors via the API (e.g., annual_recurring_revenue, active_trials, trial_conversion). RC Insights only uses confirmed-working endpoints.

---

Supported LLMs

RC Insights uses litellm as an abstraction layer, giving you access to 100+ LLM providers with a single interface.

Provider	Model String	Setup
OpenAI (default)	gpt-4o-mini, gpt-4o	export OPENAI_API_KEY=sk-...
Anthropic	claude-sonnet-4-5, claude-opus-4-5	export ANTHROPIC_API_KEY=sk-ant-...
Ollama (local, free)	ollama/llama3, ollama/mistral, ollama/phi3	ollama serve (no key needed)
Groq	groq/llama-3.1-70b-versatile	export GROQ_API_KEY=gsk_...
Mistral	mistral/mistral-medium	export MISTRAL_API_KEY=...
Azure OpenAI	azure/gpt-4o	export AZURE_API_KEY=... + AZURE_API_BASE=...
Google Gemini	gemini/gemini-1.5-flash	export GEMINI_API_KEY=...

Quick Provider Examples

# OpenAI (default)
export OPENAI_API_KEY=sk-...
rc-insights report

# Anthropic Claude
export ANTHROPIC_API_KEY=sk-ant-...
rc-insights report --model claude-sonnet-4-5

# Ollama — completely local, no API key, runs on your machine
ollama serve &
rc-insights report --model ollama/llama3

# Groq — very fast inference, generous free tier
export GROQ_API_KEY=gsk_...
rc-insights report --model groq/llama-3.1-70b-versatile

# Universal key override
export LLM_API_KEY=your-key-here
rc-insights report --model gpt-4o

As a Python Library

# Any litellm model string works
analyzer = SubscriptionAnalyzer(
    rc_api_key="sk_...",
    rc_project_id="proj...",
    llm_model="claude-sonnet-4-5",   # or ollama/llama3, groq/llama-3.1-70b, etc.
    llm_api_key="sk-ant-...",        # optional: also reads from env vars
)

No key? No problem. Without any LLM key configured, RC Insights automatically falls back to heuristic analysis. All the trend detection and scoring still works — you just don't get the AI narrative summary.

List all supported models: rc-insights models

---

How the AI Analysis Works

When an LLM is configured, RC Insights:

1. Fetches all core charts from the Charts API (9 confirmed-working endpoints)
2. Formats the data into a concise summary with trends and statistics
3. Prompts GPT-4o-mini with a subscription analytics expert persona
4. Parses the structured JSON response into typed Insight objects
5. Scores overall health on a 0-100 scale

Without OpenAI, the heuristic engine applies rule-based analysis:

• MRR/revenue trend detection (week-over-week comparison)
• Churn rate thresholds (>10% critical, >5% warning)
• Trial conversion benchmarks (industry average: 10-15%)
• Refund rate monitoring

Both modes produce the same HealthReport output format.

---

Report Output

Reports are generated in both Markdown and HTML formats:

• Markdown — Perfect for GitHub READMEs, Notion, Slack
• HTML — Styled dark-mode dashboard, shareable as a static file

Each report includes:

• 📊 Health Score (0-100)
• 📋 Key Metrics table
• 🧠 Prioritized insights with recommendations
• 📈 Charts summary with trend indicators

---

Development

# Clone and install dev dependencies
git clone https://github.com/arimetabot/rc-insights.git
cd rc-insights
pip install -e ".[dev,web]"

# Run linter
ruff check .

# Run tests
pytest

---

Contributing

Contributions welcome! Some ideas:

• More chart visualizations — Plotly/matplotlib renderers for CLI output
• Multi-project dashboards — Compare health across multiple RC projects
• Historical trend reports — Week-over-week health score tracking
• Custom insight prompts — Let users define their own AI analysis templates
• Zapier/n8n integration — Webhook-based workflow triggers

---

License

MIT — See LICENSE for details.

---

Built with ❤️ using RevenueCat Charts API v2 · RevenueCat OpenClaw Skill

---

📋 Take-Home Submission

This tool was built as a take-home project for RevenueCat's Agentic AI Developer & Growth Advocate role.

• Full Submission — deliverables overview, live demo output, architecture
• Content Package — blog post, social media posts
• Growth Campaign — community strategy, budget allocation, measurement plan
• Process Log — how this was built using a multi-agent AI workflow
• Video Demo — 2-minute walkthrough with real data