salescomp / AIRULES.md
stepolan
Refactor scenarios to plans with auto-projections
6795a21
|
Raw History Blame Contribute Delete
5.01 kB

A newer version of the Streamlit SDK is available: 1.67.0

Upgrade

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:

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:

git remote add hf https://huggingface.co/spaces/stepolan/salescomp

You will need a HuggingFace token with write access to push. Log in with:

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().

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.

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

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.