# Sales Comp Plan Builder — AI Rules ## Project Overview This is a Streamlit-based sales compensation plan builder hosted on HuggingFace Spaces. Users define comp plans (base salary, quota, commission tiers, ramp, draw, etc.) and the app auto-generates projections at multiple attainment levels (default: 75%, 100%, 150%, 200%). - **App:** `app.py` (single-file Streamlit app) - **Backend:** Google Sheets via public CSV reads + Google Apps Script (`apps_script.js`) for writes - **Hosting:** HuggingFace Spaces (unlisted) at `stepolan/salescomp` - **Repo:** `github.com/DBDoyen/salescomp` ## Deploying Changes After modifying `app.py`, push to both remotes: ```bash git push origin main git push hf main ``` The HuggingFace Space rebuilds automatically on push. If the `hf` remote is not configured (e.g. fresh clone), add it: ```bash git remote add hf https://huggingface.co/spaces/stepolan/salescomp ``` You will need a HuggingFace token with write access to push. Log in with: ```bash huggingface-cli login ``` ## Data Model: Plans (v2) Plans are saved as JSON to Google Sheets. A plan stores **config only** — results are computed on-the-fly via `compute_projection()`. ```python plan_data = { "version": 2, "author": "Founder", # Generic label, no real names "timestamp": "2026-03-25T...", "commission_mode": "Attainment-based rates", # or "Deal-size rates + accelerators" "retroactive": False, # True = retroactive rates (top rate applies to ALL revenue) "months_employed": 12, "attainment_levels": [75, 100, 150, 200], # Configurable projection levels "params": { "base_salary": 150000, "annual_quota": 1250000, "draw_amount": 0, "draw_months": 0, "draw_recoverable": True, "ramp_pcts": [25, 50, 75], "cogs_pct": 20.0, "other_cost_per_rep": 20000, "commission_tiers": [[100, 8.0], [150, 14.0], [200, 26.0], [null, 50.0]], "deal_rate_tiers": null, "accel_tiers": null, # Optional rich fields for agreement text: "equity": {"pct": "0.5", "vesting": "4-year vest with 1-year cliff"}, "policies": {...}, "illustrative_scenarios": [...], }, } ``` ### Backward Compatibility Legacy scenarios (version 1, no version field) are auto-normalized by `normalize_plan()`. They had `inputs` and `results` baked in — these are ignored and projections are computed fresh from `params`. ## Saving / Updating Plans Programmatically ### Apps Script URL ``` https://script.google.com/macros/s/AKfycbxJTi4RhN-CevolOEsk4egxoTKQ0qgn2eLlmzu5Yv903MVWR-tVBcg02Hr5bBjtX4vj/exec ``` ### Save / Update a Plan POST JSON with `action: "save"`. If a plan with the same `name` exists, it updates in place. ```python import requests, json, datetime SCRIPT_URL = "https://script.google.com/macros/s/AKfycbxJTi4RhN-CevolOEsk4egxoTKQ0qgn2eLlmzu5Yv903MVWR-tVBcg02Hr5bBjtX4vj/exec" payload = { "action": "save", "name": "Plan A", "author": plan_data["author"], "timestamp": plan_data["timestamp"], "data_json": json.dumps(plan_data), } resp = requests.post(SCRIPT_URL, json=payload, timeout=60) ``` ### Delete a Plan ```python payload = {"action": "delete", "name": "Plan A"} requests.post(SCRIPT_URL, json=payload, timeout=60) ``` ## Key Functions ### `compute_projection(params, commission_mode, retroactive, attainment_pct, months_employed=12)` The core function. Takes plan params and an attainment %, returns a full results dict (commission, total_comp, net_after_rep, etc.). Used for: - Auto-generating projections in the Compare tab - Agreement text illustrative earnings - Can be called programmatically for batch scenario generation ### Commission Calculation - **Attainment-based (marginal):** Each tier rate applies only to revenue in that band - **Attainment-based (retroactive):** Highest tier reached applies to ALL revenue from dollar one - **Deal-size + accelerators:** Flat rate per deal ACV × attainment multiplier - Commission tiers are calculated against the **full annual quota** (not ramp-adjusted) ### Key Formulas - **Attainment %** = actual_revenue / effective_quota × 100 - **Revenue at X% attainment** = annual_quota × X / 100 - **Draw paid** = draw_amount × (months_employed / draw_months) - **Total variable** (non-recoverable draw) = commission + draw_paid - **Total variable** (recoverable draw) = max(commission, draw_paid) - **Total comp** = prorated_base + total_variable - **Gross profit** = revenue × (1 - cogs_pct / 100) - **Net after rep** = gross_profit - total_cost_of_rep ## Privacy Do NOT use real names, company names, or identifying information in plan names or author fields. The Google Sheet is accessible to anyone with the link. ## Google Sheet https://docs.google.com/spreadsheets/d/1SM9_8IRuoKwwtK_pQuF0wwb3DW-CQJgglB3XCBgH11M/edit Use timeout=60 when POSTing to the Apps Script — it can be slow on first invocation.