Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.synheart.ai/llms.txt

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

HSI is at version 1.3. This page is a high-level orientation. The canonical schemas, RFCs, and validator live in the hsi repository:
  • Payload structure.
  • Canonicalization, content hashing, signatures (HSI-VALIDATE-INTEGRITY).
  • Canonical 5-axis domain set (physiological / kinematic / digital / cognitive / affective).
  • Multimodal attribution (modalities_used, confidence_breakdown).
Earlier 1.0 / 1.1 / 1.2 schemas are retained for historical payloads. Producers and consumers dispatch on hsi_version and validate against the schema for the declared version.
Human State Interface (HSI) is a language-agnostic, contract-only specification for exchanging human-state signals between independent systems (producers and consumers). HSI defines a canonical JSON payload, explicit time windows, normalized scores + confidence, an authoritative JSON Schema, and versioning rules so teams can interoperate without sharing implementation details.
HSI is a data contract. It does not specify models, sensor pipelines, SDKs, or device assumptions.

​
What HSI is (and is not)

  • HSI is: a stable, versioned payload contract; a schema you can validate against; and a compatibility policy for evolution.
  • HSI is not: an SDK, an inference model, a sensor pipeline, or a device specification.

​
Top-level structure (HSI 1.3)

An HSI 1.3 payload is a single JSON object. Required top-level fields:
  • hsi_version — "1.3".
  • observed_at_utc — RFC 3339 timestamp (event-time; typically aligns with the latest window’s end_utc).
  • computed_at_utc — RFC 3339 timestamp (processing-time; must be ≥ observed_at_utc).
  • producer — identity of the producing system (non-PII).
  • windows — map of window IDs to window descriptors (each requires start_utc and end_utc).
  • privacy — privacy assertions; contains_pii MUST be false, plus required raw_biosignals_allowed and derived_metrics_allowed.
Optional top-level fields:
  • axes — human-state axis readings grouped by domain (see canonical 5-axis set below).
  • embeddings — window-scoped latent vectors (sensitive; vector or vector_hash).
  • integrity — canonicalization + content hash + signature block.
  • meta — non-normative metadata, including meta.provenance (sources, providers, engine identifiers, equation IDs, SRM snapshot IDs).
Earlier-version drift. HSI 1.0/1.1 used top-level source_ids / sources and window_ids arrays, axis readings keyed by axis / window_id (singular), and a domain set of affect / engagement / behavior. None of those apply to 1.3. If you’re integrating against 1.3, follow the canonical schemas.

​
Canonical 5-axis domain set

In HSI 1.3, the axes object is closed (additionalProperties: false) and permits exactly these five domains:
DomainWhat it carries
physiologicalCardiovascular, autonomic, sleep, recovery, and similar bio-signals.
kinematicMotion, posture, activity-state classification.
digitalInteraction-derived signals (taps, scrolls, typing rhythm, app context).
cognitiveFocus, attention, capacity, fatigue.
affectiveValence, arousal, emotional state.
Consumers MUST tolerate unknown axis names (name values) within a known domain, but MUST reject unknown domains under strict validation.

​
Axis readings (HSI 1.3)

Each axis reading is an object with these required fields:
  • name — lower_snake_case (e.g. arousal, task_persistence, hr_rmssd).
  • score — number in [0, 1] (or label, see direction: categorical).
  • confidence — number in [0, 1].
  • direction — one of higher_is_more, lower_is_more, bidirectional, categorical.
  • window_ids — array of window IDs this reading covers.
  • evidence_source_ids — array of source IDs declared under meta.provenance.sources.
  • inference_mode — describes how the score was produced (e.g. model, heuristic, pass_through).
  • model_id — identifier of the model or rulepack used.
Optional fields include unit, notes (no PII), modalities_used, confidence_breakdown (per-channel attribution), and for direction: categorical, label and categories.

​
Privacy block

Every payload MUST include privacy with at minimum:
  • contains_pii: false
  • raw_biosignals_allowed: <bool>
  • derived_metrics_allowed: <bool>
If a producer cannot guarantee contains_pii=false, it MUST NOT emit HSI payloads.

​
Validation tiers

HSI defines three validator levels:
  • HSI-VALIDATE-BASIC — Draft 2020-12 schema validation (structure + ranges).
  • HSI-VALIDATE-STRICT — basic plus cross-field integrity (timestamp ordering, declared-window references, source-id references, embedding dimension equals vector length when present).
  • HSI-VALIDATE-INTEGRITY — strict plus canonicalization + content_hash + signature verification on the optional integrity block.

​
Versioning policy

HSI uses Semantic Versioning as MAJOR.MINOR (patch is unused for payload compatibility).
  • Major: breaking changes. Consumers supporting 1.x MUST reject 2.0+ unless explicitly updated.
  • Minor: backward-compatible additions/clarifications within the same major.
  • Unknown top-level fields MUST be rejected under strict validation (additionalProperties: false).
  • Unknown axes (new name values) MUST be tolerated.

​
Synheart Core implementation

If you’re using Synheart’s SDK, the HSI contract is implemented by the Synheart runtime and surfaced through Synheart Core:
Canonical HSI version: 1.3. See the hsi repo for schemas and RFCs HSI-0008 / HSI-0009 / HSI-0010 / HSI-0011.