Cohort Analysis

curl https://api.promptster.ai/v1/assessments/$ASSESSMENT_ID/cohort-stats \
  -H "Authorization: Bearer $PROMPTSTER_API_KEY"

{
  "cohortStats": {
    "sessionCount": 8,
    "metrics": {
      "avgDurationMs": 5400000,
      "avgPromptCount": 42.3,
      "avgCommandFailRate": 0.15,
      "avgVerifyIntensity": 0.28,
      "avgManualEditRatio": 0.12,
      "avgFirstChangeLatencyMs": 240000,
      "testPassRate": 75
    }
  }
}

curl "https://api.promptster.ai/v1/assessments/$ASSESSMENT_ID/cohort-stats?sessionId=$SESSION_ID" \
  -H "Authorization: Bearer $PROMPTSTER_API_KEY"

{
  "cohortStats": {
    "sessionCount": 8,
    "metrics": { ... },
    "percentiles": {
      "durationMs": 0.714,
      "promptCount": 0.571,
      "commandFailRate": 0.857,
      "verifyIntensity": 0.429,
      "manualEditRatio": 0.286,
      "firstChangeLatencyMs": 0.571
    }
  }
}

curl https://api.promptster.ai/v1/sessions/$SESSION_ID/cohort-stats \
  -H "Authorization: Bearer $PROMPTSTER_API_KEY"

import requests
import os

API_KEY = os.environ["PROMPTSTER_API_KEY"]
BASE = "https://api.promptster.ai"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def rank_candidates(assessment_id):
    # Get all candidate keys for this assessment
    res = requests.get(
        f"{BASE}/v1/assessments/{assessment_id}/keys",
        headers=HEADERS,
    )
    keys = res.json()["keys"]

    candidates = []
    for key in keys:
        if key["status"] != "completed" or not key["sessionId"]:
            continue

        # Get cohort stats with percentiles for this session
        res = requests.get(
            f"{BASE}/v1/assessments/{assessment_id}/cohort-stats",
            headers=HEADERS,
            params={"sessionId": key["sessionId"]},
        )
        stats = res.json().get("cohortStats")
        if not stats or "percentiles" not in stats:
            continue

        pctl = stats["percentiles"]
        # Weighted composite score
        composite = (
            pctl.get("commandFailRate", 0) * 0.3
            + pctl.get("verifyIntensity", 0) * 0.25
            + pctl.get("durationMs", 0) * 0.2
            + pctl.get("promptCount", 0) * 0.15
            + pctl.get("firstChangeLatencyMs", 0) * 0.1
        )

        candidates.append({
            "name": key.get("candidateName", key["key"]),
            "sessionId": key["sessionId"],
            "composite": round(composite, 3),
            "percentiles": pctl,
        })

    # Sort by composite score
    candidates.sort(key=lambda c: c["composite"], reverse=True)
    return candidates