feat(customer-analytics): add explainable account health scores

.capy-cache/dependencies.sha256

@@ -0,0 +1 @@
+8620910f03b78c62ebc5462fc6ef8351843f0a2525ee8213a01b0cfc28ba250b

.capy-cache/docker-compose.capy.yml

@@ -0,0 +1,19 @@
+services:
+  clickhouse:
+    mem_limit: !reset null
+    cpus: !reset null
+  proxy:
+    extra_hosts: !override
+      - 'plugins:host-gateway'
+      - 'capture:host-gateway'
+      - 'capture-ai:host-gateway'
+      - 'capture-logs:host-gateway'
+      - 'replay-capture:host-gateway'
+      - 'feature-flags:host-gateway'
+      - 'hypercache-server:host-gateway'
+  web:
+    image: caddy:latest
+    entrypoint: socat
+    command: ['TCP-LISTEN:8000,fork,reuseaddr', 'TCP:host.docker.internal:8011']
+    extra_hosts:
+      - 'host.docker.internal:host-gateway'

frontend/src/queries/schema/schema-general.ts

@@ -2306,6 +2306,36 @@ export interface GroupsQuery extends DataNode<GroupsQueryResponse> {
     offset?: integer
 }
 
+/** Health bucket an account falls into. `no_data` means we could not score it (no
+ * external id, no usage-metric config, no defined metrics, or no usable signal). */
+export type AccountHealthStatus = 'healthy' | 'needs_attention' | 'at_risk' | 'no_data'
+
+/** One usage metric's contribution to an account's health score. */
+export interface AccountHealthFactor {
+    /** The GroupUsageMetric id this factor was derived from. */
+    metric_id: string
+    metric_name: string
+    /** Lookback window in days for both the current and the immediately preceding period. */
+    interval: integer
+    /** Total in the current period. */
+    current: number
+    /** Total in the immediately preceding equal-length period. */
+    previous: number
+    /** 0–100 retained-usage score, or null when there is no signal (both periods zero). */
+    factor_score: number | null
+    /** Percentage change current vs previous, or null when previous is zero. */
+    change_pct: number | null
+}
+
+/** Explainable account health score derived from the team's usage-metric definitions. */
+export interface AccountHealthScore {
+    /** 0–100 overall score (rounded mean of non-null factor scores), or null when no_data. */
+    score: number | null
+    status: AccountHealthStatus
+    /** Per-metric breakdown that explains the overall score. */
+    factors: AccountHealthFactor[]
+}
+
 export type CachedAccountsQueryResponse = CachedQueryResponse<AccountsQueryResponse>
 
 export interface AccountsQueryResponse extends AnalyticsQueryResponseBase {
@@ -2323,6 +2353,10 @@ export interface AccountsQueryResponse extends AnalyticsQueryResponseBase {
 
 export interface AccountsQuery extends DataNode<AccountsQueryResponse> {
     kind: NodeKind.AccountsQuery
+    /** Columns to return. Most are HogQL expressions resolved against `system.accounts`, but the
+     * synthetic `health_score` column is computed by the runner from the team's usage-metric
+     * definitions and returned as an `AccountHealthScore` object per row. Callers that omit it do
+     * zero health work. */
     select?: HogQLExpression[]
     /** Aggregation expressions evaluated against the filtered account set; one value per metric is returned in `metricsResults`. When `metrics` is set without a `select`, the runner skips the regular row fetch and returns only the aggregated values. */
     metrics?: HogQLExpression[]

posthog/schema_enums.py

@@ -21,6 +21,13 @@ class AIEventType(StrEnum):
     FIELD_AI_GENERATION_CLUSTERS = "$ai_generation_clusters"
 
 
+class AccountHealthStatus(StrEnum):
+    HEALTHY = "healthy"
+    NEEDS_ATTENTION = "needs_attention"
+    AT_RISK = "at_risk"
+    NO_DATA = "no_data"
+
+
 class MathGroupTypeIndex(float, Enum):
     NUMBER_0 = 0
     NUMBER_1 = 1