Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Fairness hard-gate (publish-time enforcement)

POST /api/v1/decision-flows/publish runs the fairness hard-gate as a pre-publish check when the tenant has opted in. If configured thresholds breach, the publish is blocked with HTTP 422 and a structured violation report — the new flow version is not written.

​
Configuration

Set on tenant.settings.fairnessPolicy: 
{
  "fairnessPolicy": {
    "enabled": true,
    "sensitiveAttribute": "ethnicity",
    "thresholds": {
      "disparateImpactRatio": 0.8,
      "demographicParityGap": 0.2,
      "equalOpportunityGap": 0.2
    },
    "minSampleSize": 100,
    "override": {
      "approvedBy": "compliance@example.com",
      "expiresAt": "2026-06-01T00:00:00Z"
    }
  }
}
FieldDefaultPurpose
enabledfalseMaster switch. When unset/false the gate is a no-op.
sensitiveAttribute—The protected-attribute key the gate looks up in decision_trace.qualificationResults[*].context.attributes.
thresholds.disparateImpactRatio0.8Four-fifths rule (29 CFR § 1607.4D). Below this → block.
thresholds.demographicParityGap0.2Max allowed maxRate − minRate across groups. Above this → block.
thresholds.equalOpportunityGap0.2Max allowed TPR gap when ground-truth labels are present.
minSampleSize100Skip the gate (not block) when fewer than this many traces in the last 7 days carry the sensitive attribute.
override—Four-eyes bypass: { approvedBy, expiresAt }. Active overrides skip the gate (audit-logged).

​
Behavior

  • Not configured / disabled — gate is a no-op, publish proceeds.
  • Active override (not expired) — gate is skipped, publish proceeds, audit log records the bypass.
  • Insufficient samples — gate is skipped (enforced: false, reason explains samples < minSampleSize).
  • Thresholds breached — publish blocked with 422: 
    {
  "title": "Fairness gate blocked publish",
  "violations": [
    "disparate impact ratio 0.612 < threshold 0.8",
    "demographic parity gap 0.351 > threshold 0.2"
  ],
  "metrics": { "sampleSize": 1840, "disparateImpactRatio": 0.612, ... },
  "override": "To bypass, an admin can set tenant.settings.fairnessPolicy.override = { approvedBy, expiresAt } via four-eyes governance."
}
  • Infrastructure error — fail-open (publish proceeds, warning logged) so a transient DB blip doesn’t block legitimate compliance work.

​
Sample-source caveats

The MVP derives the protected group from decision_trace.qualificationResults[*].context.attributes[sensitiveAttribute]. If your traces don’t yet include the sensitive attribute in qualification context, the gate skips with a “no usable samples” reason. Upcoming work extends sample sourcing to InteractionHistory and to a tenant-supplied custom attribute resolver. Backed by the platform’s fairness hard-gate enforcement helper.

​
Tiered fairness evaluation

POST /api/v1/fairness/evaluate?metrics=basic|advanced runs the full fairness pipeline. The query string controls which metrics tier is returned.

​
Basic tier (default)

Existing demographic-parity, four-fifths-rule, equal-opportunity, and equalized-odds gap calculations from lib/fairness/metrics.ts. Unchanged behavior — every existing caller is bit-identical.

​
Advanced tier

Adds intersectional analysis + mitigation recommendations from lib/fairness/advanced.ts:
  • Intersectional cells require per-sample intersectionalGroups: { axisName: groupValue }. The route runs the intersectional evaluator with a default minimum cell size of 10 samples and surfaces the cells plus the worst disparate-impact ratio.
  • Mitigation recommendations are derived from the report shape (DI ratio, four-fifths violation, equal-opportunity gap) — no extra inputs needed.
When the caller asks for advanced but doesn’t supply intersectionalGroups, the response includes advancedAwaitingConfig: ["intersectional: no per-sample intersectionalGroups supplied"] so operators know why the analysis is empty. No silent fallback.

​
Counterfactual + Lipschitz

These primitives also live in lib/fairness/advanced.ts but are NOT auto-run from this route — they need a real scorer + paired counterfactual samples that the evaluate route does not have. Pipeline callers invoke them directly.

​
EU AI Act report

POST /api/v1/fairness/report runs the same fairness pipeline and returns a formatted report:
formatContent typeNotes
csvtext/csvPer-group + summary metrics, suitable for compliance archive ingestion.
htmltext/htmlMarkup-only; pipe through headless Chromium / wkhtmltopdf for PDF.
Body shape mirrors /evaluate. Optional title + subtitle override the defaults (“Fairness Assessment Report” / “EU AI Act Article 10 § 2(f)”).

​
Audit trail

Every call to /evaluate and /report writes one audit-log row (action: fairness_evaluate or fairness_report) so DSAR exports can cite the exact report contents.