# Kuan Yin — Model Documentation

> Technical doc 32.16.1.7. Model families in `@kuanyin/ai-ml-models`; gating in
> `@kuanyin/evaluation`.

Kuan Yin specifies six model families. Each is documented with a model card
(intended use, training data shape, fairness constraints, known limits) and is
**gated through `@kuanyin/evaluation` before it touches a person**.

## The six families

| Family                    | Output                                                            |
| ------------------------- | ----------------------------------------------------------------- |
| Intent classification     | 25+ intent classes, multi-intent head, calibrated confidence      |
| Emotional state detection | Arousal-valence + discrete emotions, trajectory, crisis module    |
| Harm potential scoring    | Multi-label severity + reversibility + cascade risk               |
| Cognitive reframing       | CBT distortion detection + intent/tone-preserving reframe         |
| Behavioural pattern       | Sequence model for escalation/recidivism/intervention selection   |
| Community health          | Graph-neural relationship model + conflict/raid/health trajectory |

Each family supports continuous learning, A/B testing, bias detection +
mitigation, confidence calibration, attention-based explainability, and
versioning with rollback.

## Evaluation gate (`@kuanyin/evaluation`)

`model-evaluation.ts` computes, against hand-verified known values:

- **Classification** — confusion matrix, precision/recall/F1/MCC, Cohen's kappa,
  ROC-AUC and PR-AUC, calibration (ECE/Brier).
- **Regression** — MAE/RMSE/R².
- **Fairness** — demographic parity, equalized odds, EEOC four-fifths rule,
  cross-cultural disparity.
- **Robustness** — adversarial-perturbation suites, edge-case runner.
- **Operations** — latency percentiles (p50/p90/p95/p99 + SLA), regression vs
  baseline, two-proportion A/B testing, human inter-rater agreement, and
  PSI/KL/JS drift detection.

A model release is blocked if any fairness constraint regresses, drift exceeds
threshold, or the latency SLA is missed.

## Privacy & federation

Models train under the privacy regime in `13-privacy-implementation.md`:
on-device feature reduction for typing dynamics, ephemeral content analysis, and
federated learning (`dharma-analytics/federated-learning.ts`) with FedAvg,
gradient clipping, (ε,δ)-Gaussian differential privacy, and secure aggregation —
so cross-community learning never requires sharing raw user data.

## Serving

Real-time families target sub-100ms inference (intent) and sub-50ms fast paths
(toxicity), with model quantization (fp32→int4) and edge deployment for
latency-critical analysis. See `dharma-analytics/performance-sla.ts` and
`11-performance-tuning.md`.
