> ## 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.

# Human State Interface (HSI)

> A contract-only, language-agnostic JSON payload for exchanging human-state signals (HSI 1.3)

<Note>
  HSI is at version **1.3**. This page is a high-level orientation. The canonical schemas, RFCs, and validator live in the [hsi repository](https://github.com/synheart-ai/hsi):

  * **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`).

  Producers and consumers dispatch on `hsi_version` and validate against the schema for the declared version.
</Note>

**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).

## Canonical 5-axis domain set

In HSI 1.3, the `axes` object is closed (`additionalProperties: false`) and permits exactly these five domains:

| Domain              | What it carries                                                          |
| ------------------- | ------------------------------------------------------------------------ |
| **`physiological`** | Cardiovascular, autonomic, sleep, recovery, and similar biosignals.      |
| **`kinematic`**     | Motion, posture, activity-state classification.                          |
| **`digital`**       | Interaction-derived signals (taps, scrolls, typing rhythm, app context). |
| **`cognitive`**     | Focus, attention, capacity, fatigue.                                     |
| **`affective`**     | Valence, 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`.

## Example payload

A minimal but complete HSI 1.3 envelope with one window and one axis reading:

```json theme={null}
{
  "hsi_version": "1.3",
  "observed_at_utc": "2026-01-15T10:30:00Z",
  "computed_at_utc": "2026-01-15T10:30:00.420Z",
  "producer": {
    "name": "synheart-runtime",
    "version": "5.4.0",
    "instance_id": "device_3f1c8b"
  },
  "windows": {
    "w_micro_30s": {
      "start_utc": "2026-01-15T10:29:30Z",
      "end_utc": "2026-01-15T10:30:00Z",
      "duration_seconds": 30
    }
  },
  "axes": {
    "cognitive": [
      {
        "name": "focus",
        "score": 0.72,
        "confidence": 0.81,
        "direction": "higher_is_more",
        "window_ids": ["w_micro_30s"],
        "evidence_source_ids": ["wear_hrv", "behavior_taps"],
        "inference_mode": "model",
        "model_id": "focus.v1",
        "modalities_used": ["physiological", "digital"]
      }
    ]
  },
  "privacy": {
    "contains_pii": false,
    "raw_biosignals_allowed": false,
    "derived_metrics_allowed": true
  },
  "meta": {
    "provenance": {
      "sources": [
        { "id": "wear_hrv", "kind": "wearable", "vendor": "apple_watch" },
        { "id": "behavior_taps", "kind": "behavior", "vendor": "synheart_behavior" }
      ]
    }
  }
}
```

The same envelope shape carries any combination of axes across the five canonical domains; consumers MUST validate against the schema for the declared `hsi_version`.

## 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:

* [HSI in Synheart Core](/synheart-core/hsi-specification)
* [HSV Specification](/synheart-core/hsv-specification) — typed intermediate representation that flux packs into HSI payloads.

***

**Canonical HSI version:** 1.3. See the [hsi repo](https://github.com/synheart-ai/hsi) for schemas and RFCs HSI-0008 / HSI-0009 / HSI-0010 / HSI-0011.