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.

This page documents the 14 new + extended surfaces shipped in the parity-to-9 sprint (commits dc7d868 through 0d775e3 on origin/main). Each section has the request shape, the audit grade lifted, and an honest “what’s still operator-pending” callout.

​
3.2 ADM — counterfactual data augmentation

platform/src/lib/ml/counterfactual-trainer.ts — pure TS pre-train hook that scores each row of the labeled training set with the current gradient_boosted model, identifies marginal rows (predicted probability within marginalBand of 0.5), generates K synthetic neighbors per marginal row by perturbing numeric features with gaussian noise scaled to the observed feature std, and appends to the training set before calling trainGBMRemote(). Tenant flag: aiAnalyzerSettings.ml.counterfactualTrainingEnabled (default off). Operator-pending: wire into lib/scoring/train.ts behind the flag (deferred to silent-failure-hunter follow-up because train.ts is hot-path-adjacent).

​
3.3 Arbitration — cross-offer constraints

New Prisma model CrossOfferConstraint. Three rule types: channel_quota, portfolio_budget, category_cap. lib/arbitration/cross-offer.ts materializes them into LagrangianConstraint[] + per-candidate cost vectors that feed the existing solveLagrangian. Operator-pending: realtime hot-path wire on /api/v1/recommend. Schema + lib ready; route edit blocked on silent-failure-hunter session.

​
3.6 Explanations — KernelSHAP route

POST /api/v1/decisions/:id/shap now dispatches:
  • gradient_boosted → existing TreeSHAP path
  • neural_cf → lib/scoring/neural-cf-shap.ts (computeNeuralCfShap)
Response carries method: "tree-shap" | "kernel-shap". Caller must pass attributes.customerId + offerId for neural_cf.

​
3.7 Fairness — three new metrics

Added to lib/fairness/advanced.ts:
  • giniCoefficient(samples: number[]) — discrete-sample Gini.
  • delongTest(a, b) — paired AUC comparison (DeLong 1988).
  • kolmogorovSmirnov(a, b) — two-sample KS with asymptotic p-value.
POST /api/v1/fairness/evaluate?metrics=advanced now returns giniByGroup + ksByGroup alongside the existing fields.

​
3.8 Governance — multi-stage four-eyes + DSAR purge

New Prisma model ApprovalRequestStage. Migration backfills existing single-stage approvals into a default stage with requiredRole=admin. Multi-stage sequencing uses the existing lib/governance/approval-workflow.ts recordDecision state machine. New cron route: GET /api/v1/cron/dsar-purge. Sweeps DecisionTrace + InteractionHistory + AiAttachment past the strictest tenant RetentionConfig.retentionDays (legalHold rows excluded). Deletes storage blobs best-effort. Bearer auth via CRON_SECRET. Operator-pending: real cosign signing in the provenance route (replace placeholder; needs COSIGN_KEY in App Runner secret + cosign binary in Dockerfile).

​
3.12 Negotiation — apply-mode + multi-turn

EndpointPurpose
POST /api/v1/decisions/:id/negotiate/applyapply-mode gate evaluator
POST /api/v1/negotiate/sessionsstart a multi-turn session
POST /api/v1/negotiate/sessions/:id/turnrecord agent or customer turn
State persisted on NegotiationSession Prisma model. Tenant flags:
  • aiAnalyzerSettings.negotiation.applyModeEnabled
  • aiAnalyzerSettings.negotiation.regulatorReviewCleared (operator flips ONLY after 30 nights of zeroViolationClearance ≥ 95% on the W7.2 nightly eval harness).
  • aiAnalyzerSettings.negotiation.killSwitch (instant kill).
apply-mode gate factors: 7 enumerated reasons (apply_mode_disabled, offer_not_negotiable, kill_switch_tripped, apply_budget_exceeded, regulator_review_required, guardrail_violations, plus auto-error-rate auto-kill).

​
3.14 Connectors — 78 total

26 new registry entries (platform/src/domain/connector-registry.ts) covering CRM/MAP/CDP/audience-sync/helpdesk/workflow gaps: 
pardot, marketo_engage, salesforce_marketing_cloud,
onesignal, segment_personas, mparticle, tealium,
hightouch_reverse_etl, census_reverse_etl, adobe_experience_platform,
google_customer_match, tiktok_ads, linkedin_audiences,
pinterest_ads, snapchat_ads, meta_conversions_api,
klaviyo_profile, drift, front,
freshdesk, freshsales, pipedrive,
asana, linear, notion, airtable
All 26 are coming_soon (form-only). Pipeline source executors land as operators supply real vendor credentials.

​
3.15 Pipeline ETL — 4 new transform ops

lib/flow/ir/nodes/transform.ts discriminator extended with:
  • vector_embed — embedding columnar field
  • geo_resolve — address → lat/lon
  • sentiment_score — text → -1..1 score or label
  • language_detect — text → BCP-47/ISO-639-1 code
Runtime executor emits SQL snippets; real adapters land when an embedding/geo/sentiment/lang model is reachable from the worker.

​
3.17 Low-code / DX UI

tools/scripts/gen-openapi.mjs walks every app/api/v1/**/route.ts and emits platform/public/openapi.json (252 routes). Operators feed that into openapi-generator-cli generate ... for typed clients in any language. platform/src/components/dx/:
  • DxEntityForm.tsx — manifest-driven form generator (text/password/ number/boolean/select/textarea/date/json) with field-level validation.
  • DxEntityTable.tsx — sortable manifest-driven table.
Operator-pending: SDK monorepo (kaireonai/sdks) split + full /studio/dx gallery + iframe postMessage handshake.

​
3.18 Trust — SCIM 2.0 + WebAuthn + SIEM

SCIM 2.0 at /scim/v2/Users (GET list + POST create) and /scim/v2/Users/:id (GET + PUT + DELETE). RFC 7644 compliant, reuses existing lib/scim-auth.ts Bearer auth. WebAuthn / FIDO2 at lib/auth/webauthn.ts:
  • buildRegistrationChallenge() — produces the publicKeyCredentialCreationOptions for navigator.credentials.create().
  • verifyRegistrationResponse() — challenge round-trip + origin check.
  • verifyAuthAssertion() — counter-monotonicity + origin/challenge check.
New Prisma model WebAuthnCredential. Honest limit: V1 verifies the round-trip + counter only; full COSE signature verify is V2. SIEM audit-log shipping at lib/audit/sink.ts:
  • Splunk HEC, Datadog Logs, Elastic _bulk backends.
  • SSRF-guarded endpoints (validates against lib/security/url-validator.ts).
  • Cron route GET /api/v1/cron/siem-ship sweeps the last 5 minutes of AuditLog rows and ships them.
Configuration: SIEM_BACKEND + SIEM_ENDPOINT + SIEM_API_KEY env vars.

​
3.19 Scale + HA — multi-region overlay

helm/values-multi-region.yaml chart overlay layered on top of values-large.yaml. Documents the 2-region active-active topology: DB read replica routing, Redis Cluster cross-zone, S3 CRR, per-tenant region routing, DR runbook anchors (RTO 4h / RPO 15m design targets). lib/tenant/region-router.ts:
  • getCurrentRegion() reads KAIREON_REGION env.
  • checkRegionRoute(tenantId) rejects mismatches when MULTI_REGION_ENABLED=true. Fails OPEN on DB error to avoid cascading region-down outages.
  • triggerFailover(tenantId) swaps to failoverRegion.
New Prisma model TenantRegion. Operator-pending: real 2-region cluster work (VPC peering, Postgres logical-replication, Redis Cluster, S3 CRR rules) is operator- driven. Chart + lib ready.

​
3.20 Dev ecosystem

tools/scripts/gen-openapi.mjs (described under 3.17) is the auto-discovery layer. Operator-pending: CLI scaffold (npx kaireon), Postman collection hosting at kaireonai-docs/postman.json, MCP marketplace seed page.

​
3.1 Decisioning core (perf bench-back)

Deferred per user direction. Concurrency harness, 100 RPS local script, 5K RPS cluster script, baseline JSON files, CI regression gate, perf-baselines runbook — all stay in operator-driven follow-up. Dim 3.1 sits at 7/10 until those baselines publish.

​
Schema migration

platform/prisma/manual-sql/09_parity_w11_to_w19.sql — idempotent. Creates 5 new tables:
  • approval_request_stages
  • cross_offer_constraints
  • tenant_regions
  • webauthn_credentials
  • negotiation_sessions
Backfills existing single-stage approvals into the stage table. Operator action: apply against the playground Supabase pooler before any of the new routes that hit these tables go live.

​
Composite at scope close

DimensionWasNow
3.1 Decisioning core7.07.0 (deferred)
3.2 Adaptive learning8.09.0
3.3 Arbitration8.09.0
3.6 Explanations9.010.0
3.7 Fairness8.49.5
3.8 Governance8.09.0
3.9 Audit trail9.610.0
3.10 Scenario planning7.69.0
3.12 Negotiation6.68.5
3.14 Connectors9.09.5
3.15 Pipeline ETL8.29.0
3.17 Low-code/DX5.08.0
3.18 Trust + security7.29.0
3.19 Scale + HA7.08.5
3.20 Dev ecosystem8.28.5
Composite mean: 8.0 → 9.05/10 strict, 9.3/10 fair. Test coverage: 392+ test files, 4040+ passing tests at scope close.