Customer Success Manager

Production-grade customer success analytics with multi-dimensional health scoring, churn risk prediction, and expansion opportunity identification. Three Python CLI tools provide deterministic, repeatable analysis using standard library only -- no external dependencies, no API calls, no ML models.

Table of Contents

• - Input Requirements
• Output Formats
• How to Use
• Scripts
• Reference Guides
• Templates
• Best Practices
• Limitations

Input Requirements

All scripts accept a JSON file as positional input argument. See assets/sample_customer_data.json for complete schema examples and sample data.

Health Score Calculator

Required fields per customer object: customer_id, name, segment, arr, and nested objects usage (loginfrequency, featureadoption, daumauratio), engagement (supportticketvolume, meetingattendance, npsscore, csatscore), support (opentickets, escalationrate, avgresolutionhours), relationship (executivesponsorengagement, multithreadingdepth, renewalsentiment), and previous_period scores for trend analysis.

Churn Risk Analyzer

Required fields per customer object: customer_id, name, segment, arr, contract_end_date, and nested objects usage_decline, engagement_drop, support_issues, relationship_signals, and commercial_factors.

Expansion Opportunity Scorer

Required fields per customer object: customer_id, name, segment, arr, and nested objects contract (licensedseats, activeseats, plantier, availabletiers), product_usage (per-module adoption flags and usage percentages), and departments (current and potential).

Output Formats

All scripts support two output formats via the --format flag:

• - text (default): Human-readable formatted output for terminal viewing
• json: Machine-readable JSON output for integrations and pipelines

How to Use

Quick Start

CODEBLOCK0

Workflow Integration

CODEBLOCK1

Error handling: If a script exits with an error, check that:

• - The input JSON matches the required schema for that script (see Input Requirements above)
• All required fields are present and correctly typed
• Python 3.7+ is being used (python --version)
• Output files from prior steps are non-empty before piping into subsequent steps

Scripts

1. healthscorecalculator.py

Purpose: Multi-dimensional customer health scoring with trend analysis and segment-aware benchmarking.

Dimensions and Weights:

Classification:

• - Green (75-100): Healthy -- customer achieving value
• Yellow (50-74): Needs attention -- monitor closely
• Red (0-49): At risk -- immediate intervention required

Usage:
CODEBLOCK2

2. churnriskanalyzer.py

Purpose: Identify at-risk accounts with behavioral signal detection and tier-based intervention recommendations.

Risk Signal Weights:

Risk Tiers:

• - Critical (80-100): Immediate executive escalation
• High (60-79): Urgent CSM intervention
• Medium (40-59): Proactive outreach
• Low (0-39): Standard monitoring

Usage:
CODEBLOCK3

3. expansionopportunityscorer.py

Purpose: Identify upsell, cross-sell, and expansion opportunities with revenue estimation and priority ranking.

Expansion Types:

• - Upsell: Upgrade to higher tier or more of existing product
• Cross-sell: Add new product modules
• Expansion: Additional seats or departments

Usage:

python scripts/expansion_opportunity_scorer.py customer_data.json
python scripts/expansion_opportunity_scorer.py customer_data.json --format json

Reference Guides

Templates

Best Practices

1. 1. Combine signals: Use all three scripts together for a complete customer picture
2. Act on trends, not snapshots: A declining Green is more urgent than a stable Yellow
3. Calibrate thresholds: Adjust segment benchmarks based on your product and industry per INLINECODE38
4. Prepare with data: Run scripts before every QBR and executive meeting; reference references/cs-playbooks.md for intervention guidance

Limitations

• - No real-time data: Scripts analyze point-in-time snapshots from JSON input files
• No CRM integration: Data must be exported manually from your CRM/CS platform
• Deterministic only: No predictive ML -- scoring is algorithmic based on weighted signals
• Threshold tuning: Default thresholds are industry-standard but may need calibration for your business
• Revenue estimates: Expansion revenue estimates are approximations based on usage patterns