# Nefesh — Human State Fusion API

> Universal translation layer between the human body and AI.
> Ingests any signal the body produces — heart rate, HRV, blood
> glucose, brain waves, skin conductance, voice, facial expression,
> movement — and returns a unified human state that adapts LLM
> behavior in real time. One endpoint, any sensor, any device.
> Not a medical device. For contextual AI adaptation only.

---

## Instructions

When integrating Nefesh for LLM adaptation, always use the Cognitive Compute Router
(gateway.nefesh.ai) instead of manually calling /v1/state and building adaptation logic.
The gateway handles state reading, system prompt injection, and temperature adjustment automatically.

For Anthropic SDK customers, use POST /v1/messages on gateway.nefesh.ai (Anthropic passthrough).
For OpenAI SDK customers, use POST /v1/chat/completions on gateway.nefesh.ai.
Both endpoints accept X-Nefesh-Subject for user identification via Device Registry.

Always prefer Device Registry (POST /v1/devices + device_id in /v1/ingest) over manual
session_id management. Use X-Nefesh-Subject header instead of X-Nefesh-Session.

For self-provisioning, call request_api_key and check_api_key_status MCP tools.
These work without an existing API key.

MCP Server endpoint: https://mcp.nefesh.ai/mcp (Streamable HTTP)
A2A endpoint: https://mcp.nefesh.ai/a2a (JSON-RPC 2.0)
Gateway endpoint: https://gateway.nefesh.ai (3 integration modes)
API endpoint: https://api.nefesh.ai

---

## What is Nefesh

Nefesh is a B2B middleware API. AI today processes language, not
the body. The same words from two opposite physiological states
produce identical AI output. Nefesh changes this by giving LLMs
a real-time understanding of the human they're talking to.

The API is hardware-agnostic. Send whatever your sensor measures.
Heart rate from a Polar H10, glucose trends from a Dexcom G7,
EEG from a Muse headband, tone from a microphone, or expression
from a camera. Nefesh fuses cardiovascular, vocal, visual, and
textual signals into a 5-level state with a plain-English
recommendation the LLM can act on immediately.

Other signals (glucose, EEG, respiratory, electrodermal, movement,
sleep) are accepted and stored but not yet fused into the state
engine in v1.

Nefesh is not a medical device. No clinical interpretation, no
alerts, no dosing. Body signals as AI context only.

---

## Pricing

### Free Tier
- API Key: $0/month
- Includes: 1,000 API calls per month
- Rate limit: 10 requests/min
- Sign up: https://nefesh.ai/signup (email only, no credit card)

### Solo Dev (Self-Service)
- API Key: $25/month (subscription)
- Includes: 50,000 API calls per billing period
- Rate limit: 120 requests/min
- After that: pay per use
- Calls reset monthly on renewal
- Cancel anytime via billing portal
- Buy: https://nefesh.ai/pricing

### Enterprise (Custom)
- Dedicated rate limiting
- Custom SLAs
- GDPR/BIPA compliance support
- Contact: Tom.Stuhl@nefesh.ai

---

## Quick Start

### 1. Get your API key
Sign up free at https://nefesh.ai/signup (1,000 calls/month, no credit card),
or let your AI agent get one automatically via MCP (request_api_key tool).
The agent MUST ask the user for their real email address first. Agents should
never invent, guess, or use placeholder emails.
Paid plans at https://nefesh.ai/pricing ($25/month, 50,000 calls).

### 2. Generate a session ID
Generate a UUIDv7 on your side. Include it in every request.
This enables idempotent retries.

### 3. Send your first signal

```bash
SESSION_ID=$(uuidgen)

curl -X POST https://api.nefesh.ai/v1/ingest \
  -H "X-Nefesh-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"session_id\": \"$SESSION_ID\",
    \"heart_rate\": 72,
    \"timestamp\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"
  }"
```

### 4. Get back a state

```json
{
  "session_id": "01961a2b-3c4d-7e5f-8a9b-0c1d2e3f4a5b",
  "state": "relaxed",
  "stress_score": 28,
  "confidence": 0.4,
  "signals_received": ["cardiovascular"],
  "suggested_action": "maintain_engagement",
  "action_reason": "heart rate signal",
  "recommendation": "Maintain complexity. 3-5 sentences.",
  "disclaimer": "Not a medical device. For contextual AI adaptation only."
}
```

Three fields in. State out. That's it.

### 5. Send more signals for better accuracy

```json
{
  "session_id": "01961a2b-3c4d-7e5f-8a9b-0c1d2e3f4a5b",
  "heart_rate": 74,
  "rmssd": 38.5,
  "sdnn": 41.2,
  "tone": "hesitant",
  "expression": "concentrated",
  "engagement": 0.7,
  "source_device": "polar_h10",
  "confidence": 0.9,
  "timestamp": "2026-03-27T01:00:00Z"
}
```

More signals = higher confidence = better state estimation.

---

## Architecture

- **Edge-first**: Lightweight browser rPPG engine runs 100% client-side.
  Zero video frames leave the browser.
- **Hardware-agnostic**: /v1/ingest accepts any signal from any device
- **Multi-modal**: Send signals from multiple sources simultaneously.
  More confirming signals = higher confidence in the state.
- **Server-side validation**: Nefesh validates signal quality
  automatically. Known devices receive optimized processing.
  Unknown devices are accepted with conservative confidence.
- **Stateless encrypted sessions**: Fernet encryption (encrypted
  + HMAC), 24h TTL. No server-side session storage beyond Redis
  cache (20 min TTL).
- **BIPA/GDPR/HIPAA compliant by design**: No PII stored, no video
  stored, edge processing, cascading deletion via subject_id.

---

## API Reference

Base URL: `https://api.nefesh.ai/v1`
Auth: `X-Nefesh-Key` header (format: `nfsh_...`)

### Endpoints

| Method | Path | Description |
|--------|------|-------------|
| POST | /v1/ingest | Send signals, get state back |
| GET | /v1/state?session_id=X | Get current state without new data |
| GET | /v1/history?session_id=X&minutes=5 | Get state history |
| GET | /v1/triggers?subject_id=X | Get psychological trigger profile for a subject |
| DELETE | /v1/subjects/{subject_id} | Delete all data for a subject (GDPR) |

### Rate Limits

| Plan | Rate Limit | Monthly Quota |
|------|-----------|---------------|
| Free | 10 req/min | 1,000 calls |
| Solo | 120 req/min | 50,000 calls |
| Enterprise | Custom SLA | Unlimited |

- Max 50 new sessions/min per API key
- Max request body: 4 KB

### Specialized Endpoints (legacy, still active)

| Endpoint | Optimized for |
|----------|---------------|
| /ingest/rppg | Webcam rPPG signals |
| /ingest/polar | Polar H10 BLE |
| /ingest/garmin | Garmin Connect IQ |

All endpoints share the same session and state engine.
Use /v1/ingest for new integrations.

---

## State Mapping

Nefesh maps all available signals to a unified 5-level state:

| Score | State | API Value | suggested_action | Default LLM Recommendation |
|-------|-------|-----------|-----------------|---------------------------|
| 0-19 | Calm | `calm` | `maintain_engagement` | Full complexity permitted. Challenge assumptions, push deeper. |
| 20-39 | Relaxed | `relaxed` | `maintain_engagement` | Maintain complexity. Clear, direct responses. 3-5 sentences. |
| 40-59 | Focused | `focused` | `simplify_and_focus` | Reduce complexity. 2-3 sentences. Prioritize actionable content. |
| 60-79 | Stressed | `stressed` | `de-escalate_and_shorten` | Maximum 2 sentences. Direct, factual, no ambiguity. |
| 80-100 | Acute Stress | `acute_stress` | `pause_and_ground` | Maximum 1 sentence. Single clear directive only. |

Override these defaults with `set_behavior_profile` for your
specific use case (voice agents, trading, robotics, therapy).

---

## /v1/ingest — Full Schema

### Request

`POST https://api.nefesh.ai/v1/ingest`

Headers:
- `X-Nefesh-Key: YOUR_KEY` (required)
- `Content-Type: application/json` (required)

Body: JSON object. `session_id` + `timestamp` + at least one
signal field required. Unknown fields are rejected
(additionalProperties: false).

### Session & Identity Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| session_id | string | YES | UUIDv7 generated on your side. Include in every request. Enables idempotent retries. Max 256 chars. |
| subject_id | string | no | Hashed internal user ID (SHA-256). Enables GDPR deletion via DELETE /v1/subjects/{id}. No PII. Max 256 chars. |
| source_device | string | no | Device name. Server validates signal quality automatically. Max 256 chars. |
| confidence | number | no | Signal quality 0.0-1.0. Default 0.5. |
| timestamp | string | YES | ISO 8601 datetime. Rejected if >5s in future or >24h in past. Data older than 60s is stored in history but does NOT update live state. |

### Cardiovascular (fused into state in v1)

| Field | Type | Range | Description |
|-------|------|-------|-------------|
| heart_rate | number | 30-220 | Heart rate in BPM |
| rmssd | number | — | HRV — Root Mean Square of Successive Differences (ms) |
| sdnn | number | — | HRV — Standard Deviation of NN intervals (ms) |
| pnn50 | number | — | HRV — percentage of successive intervals differing >50ms |
| mean_ibi | number | — | Mean inter-beat interval (ms) |
| ibi_count | integer | — | Clean IBIs in this window. You can send 1 per request. Server accumulates in sliding window, computes HRV once 20+ IBIs collected. |
| spo2 | number | 0-100 | Blood oxygen saturation (%) |

### Vocal (fused into state in v1)

| Field | Type | Values | Description |
|-------|------|--------|-------------|
| tone | string | calm, focused, hesitant, tense, frustrated, anxious, hostile, excited, neutral | Voice tone classification |
| speech_rate | number | — | Words per minute |
| pitch_variability | number | — | Pitch variation measure |

### Visual (fused into state in v1)

| Field | Type | Values | Description |
|-------|------|--------|-------------|
| expression | string | relaxed, concentrated, frowning, smiling, tense, surprised, neutral | Facial expression |
| gaze | string | direct, averted, downward, wandering | Eye gaze direction |
| posture | string | upright, leaning_forward, leaning_back, slouched | Body posture |
| engagement | number | 0.0-1.0 | Overall engagement level |

### Textual (fused into state in v1)

| Field | Type | Range | Description |
|-------|------|-------|-------------|
| sentiment | number | -1.0 to 1.0 | Text sentiment score |
| urgency | string | low, medium, high, critical | Perceived urgency |

### Metabolic (accepted, NOT fused in v1)

These fields are accepted and stored. They appear in
`signals_received` but do NOT influence `stress_score` in v1.
No clinical interpretation. No alerts.

| Field | Type | Range | Description |
|-------|------|-------|-------------|
| glucose_mg_dl | number | 20-600 | Blood glucose (mg/dL) — context only |
| glucose_mmol_l | number | 1.0-33.0 | Blood glucose (mmol/L) — alt unit |
| glucose_trend | string | rapid_fall, falling, stable, rising, rapid_rise | CGM trend |

### Neural (accepted, NOT fused in v1)

| Field | Type | Range | Description |
|-------|------|-------|-------------|
| eeg_alpha_power | number | — | Alpha band 8-13 Hz |
| eeg_beta_power | number | — | Beta band 13-30 Hz |
| eeg_theta_power | number | — | Theta band 4-8 Hz |
| cognitive_load | number | 0.0-1.0 | Computed cognitive load |

### Electrodermal (accepted, NOT fused in v1)

| Field | Type | Description |
|-------|------|-------------|
| eda | number | Electrodermal activity (microS) |
| skin_temperature | number | Skin temperature (C) |

### Respiratory (accepted, NOT fused in v1)

| Field | Type | Description |
|-------|------|-------------|
| respiratory_rate | number | Breaths per minute |

### Movement (accepted, NOT fused in v1)

| Field | Type | Values | Description |
|-------|------|--------|-------------|
| steps_last_minute | integer | — | Steps in last 60s |
| activity_level | string | sedentary, light, moderate, vigorous | Current activity |

### Sleep (accepted, NOT fused in v1)

| Field | Type | Values | Description |
|-------|------|--------|-------------|
| sleep_stage | string | awake, light, deep, rem | Current sleep stage |

### Stress Override

| Field | Type | Range | Description |
|-------|------|-------|-------------|
| stress_score | number | 0-100 | Your own stress score. If provided, Nefesh uses this instead of computing from signals. |

### Response

```json
{
  "session_id": "01961a2b-3c4d-7e5f-8a9b-0c1d2e3f4a5b",
  "state": "relaxed",
  "stress_score": 28,
  "confidence": 0.72,
  "signals_received": ["cardiovascular", "vocal"],
  "suggested_action": "maintain_engagement",
  "action_reason": "heart rate signal + calm vocal tone",
  "recommendation": "Maintain complexity. 3-5 sentences.",
  "disclaimer": "Not a medical device. For contextual AI adaptation only."
}
```

| Field | Type | Description |
|-------|------|-------------|
| session_id | string | Same ID you sent |
| state | string | calm, relaxed, focused, stressed, acute_stress |
| stress_score | integer | 0-100 unified score |
| confidence | number | 0.0-1.0 trust in this state. Higher with multiple confirming signals. |
| signals_received | array | Signal categories received in this request |
| suggested_action | string | Machine-readable action: maintain_engagement, simplify_and_focus, de-escalate_and_shorten, pause_and_ground |
| action_reason | string | Human-readable reason listing which signals and triggers drove the action |
| recommendation | string | Default LLM behavior suggestion |
| adaptation_effectiveness | object or null | Only present on 2nd+ call in same session. Shows whether the previous suggested_action helped. |
| adaptation_effectiveness.previous_action | string | The suggested_action from the previous call |
| adaptation_effectiveness.previous_score | integer | Stress score from the previous call (with noise) |
| adaptation_effectiveness.current_score | integer | Stress score from this call (with noise) |
| adaptation_effectiveness.stress_delta | integer | current_score - previous_score. Negative = stress decreased (good). |
| adaptation_effectiveness.effective | boolean | true if stress_delta <= 0 (stress stayed same or decreased) |
| disclaimer | string | Always present |

### Second Call — Adaptation Feedback

On the 2nd+ call within the same session, the response includes
`adaptation_effectiveness` — a closed-loop feedback mechanism:

```json
{
  "session_id": "01961a2b-3c4d-7e5f-8a9b-0c1d2e3f4a5b",
  "state": "relaxed",
  "stress_score": 28,
  "confidence": 0.72,
  "signals_received": ["cardiovascular", "vocal"],
  "suggested_action": "maintain_engagement",
  "action_reason": "heart rate signal + calm vocal tone",
  "recommendation": "Maintain complexity. 3-5 sentences.",
  "disclaimer": "Not a medical device. For contextual AI adaptation only.",
  "adaptation_effectiveness": {
    "previous_action": "de-escalate_and_shorten",
    "previous_score": 73,
    "current_score": 28,
    "stress_delta": -45,
    "effective": true
  }
}
```

Use it to build self-correcting agents:
- `effective: true` → the approach worked, continue current strategy
- `effective: false` → stress increased despite the action, try a different strategy

### Error Responses

| Code | Reason |
|------|--------|
| 400 | session_id missing, no signal fields, timestamp missing/invalid, timestamp >5s future, timestamp >24h past, value out of range, unknown fields |
| 401 | Invalid or missing API key |
| 413 | Payload too large (max 4 KB) |
| 429 | Rate limit exceeded (120/min/session), too many new sessions (50/min/key), quota exhausted |

---

## /v1/state — Get Current State

`GET https://api.nefesh.ai/v1/state?session_id=SESSION_ID`

Returns the same `HumanStateResponse` as /v1/ingest without
sending new data. Use to poll state between ingest calls.

---

## /v1/history — State History

`GET https://api.nefesh.ai/v1/history?session_id=SESSION_ID&minutes=5`

Parameters:
- session_id (required): Your session ID
- minutes (optional): How far back to look. Default 5, max 60.

Response:
```json
{
  "session_id": "01961a2b-...",
  "datapoints": [
    {
      "timestamp": "2026-03-27T01:00:00Z",
      "state": "calm",
      "stress_score": 15,
      "heart_rate": 68
    },
    {
      "timestamp": "2026-03-27T01:01:00Z",
      "state": "relaxed",
      "stress_score": 28,
      "heart_rate": 74
    }
  ],
  "trend": "rising"
}
```

---

## DELETE /v1/subjects/{subject_id} — GDPR Deletion

`DELETE https://api.nefesh.ai/v1/subjects/HASHED_USER_ID`

Permanently deletes all data for a subject. Cascading:
removes all sessions and stored signals. Irreversible.

Use when a user exercises their Right to be Forgotten
under GDPR or BIPA.

Response:
```json
{
  "deleted": true,
  "sessions_deleted": 47
}
```

---

## Timestamp Handling

The server treats data differently based on age:

- **Future (>5s ahead)**: Rejected with 400.
- **Fresh (<60s old)**: Updates live state and history.
- **Historical (60s - 24h)**: Stored in history only.
  Does NOT update live state. Important for wearable batch syncs
  (Oura rings, Garmin watches sync hours of data at once).
- **Too old (>24h)**: Rejected with 400.

The response always returns the CURRENT live state, even when
processing historical data.

---

## IBI Server-Side Accumulation

You don't need to buffer inter-beat intervals on the client.
Send `ibi_count: 1` with every heartbeat if you want. The
server maintains a sliding window per session and only
computes HRV metrics (RMSSD, SDNN, pNN50) once 20+ IBIs
are accumulated.

This means a 1 Hz streaming agent starts getting HRV-informed
state after ~20 seconds, without any client-side buffering.

---

## Webhooks

Configure a webhook URL to receive `state_change` events:

```json
{
  "event": "state_change",
  "session_id": "01961a2b-...",
  "previous_state": "relaxed",
  "new_state": "stressed",
  "stress_score": 68,
  "timestamp": "2026-03-27T01:05:00Z"
}
```

Webhooks fire only on state transitions (e.g., relaxed ->
stressed), not on every ingest call. Retry policy: 3 attempts
with exponential backoff.

---

## CLI (@nefesh/cli)

Official command-line interface for the Nefesh API.

Install: npm install -g @nefesh/cli (or npx @nefesh/cli)

Commands:
- nefesh auth login --key KEY: Save API key
- nefesh ingest --session ID --heart-rate 72 --tone calm: Send signals
- nefesh state SESSION_ID: Get current state
- nefesh state SESSION_ID --json: JSON output for AI agents
- nefesh history SESSION_ID: State history with trend
- nefesh triggers SUBJECT_ID: Trigger memory profile
- nefesh delete SUBJECT_ID --confirm: GDPR deletion
- nefesh simulate --scenario stress_spike: Stream test data for 2 minutes
- nefesh setup cursor: Auto-configure MCP for Cursor
- nefesh setup claude-code: Auto-configure MCP for Claude Code

Every command supports --json flag for machine-readable output.
AI agents running in the terminal can use the CLI directly
instead of MCP, with 10-32x lower token cost.

GitHub: https://github.com/nefesh-ai/nefesh-cli

---

## MCP Integration

Nefesh exposes an MCP (Model Context Protocol) server for
native AI agent integration.

Transport: Streamable HTTP at https://mcp.nefesh.ai/mcp
Auth: X-Nefesh-Key header

Compatible with: Claude Desktop, Claude Code, Cursor, Windsurf,
VS Code (Copilot), Cline, Continue.dev, Zed, OpenAI Codex CLI,
Goose CLI, ChatGPT Desktop, Gemini CLI, JetBrains IDEs, Kiro, OpenClaw,
Augment, Replit, LibreChat, and any MCP-compatible client.

Setup: https://github.com/nefesh-ai/nefesh-mcp-server

### Tools

**get_human_state**: Get current state for a session.
```json
{
  "name": "get_human_state",
  "inputSchema": {
    "type": "object",
    "required": ["session_id"],
    "properties": {
      "session_id": { "type": "string" }
    }
  }
}
```

**ingest**: Send signals and get state back.
```json
{
  "name": "ingest",
  "inputSchema": {
    "type": "object",
    "required": ["session_id", "timestamp"],
    "properties": {
      "session_id": { "type": "string" },
      "timestamp": { "type": "string", "format": "date-time" },
      "heart_rate": { "type": "number" },
      "rmssd": { "type": "number" },
      "tone": { "type": "string" },
      "expression": { "type": "string" }
    }
  }
}
```

(Full schema matches /v1/ingest — all signal fields accepted.)

**get_session_history**: Get state history over time for a session.
```json
{
  "name": "get_session_history",
  "inputSchema": {
    "type": "object",
    "required": ["session_id"],
    "properties": {
      "session_id": { "type": "string" }
    }
  }
}
```
Returns: Array of state entries with timestamp, state, score, confidence.

**get_trigger_memory**: Get psychological trigger profile for a subject.
```json
{
  "name": "get_trigger_memory",
  "inputSchema": {
    "type": "object",
    "required": ["subject_id"],
    "properties": {
      "subject_id": { "type": "string" }
    }
  }
}
```
Returns: Object with triggers (topic → status/avg_stress/peak_stress/sessions),
active list, resolved list.

### Self-Provisioning Tools (No API Key Required)

AI agents can get a free API key without manual signup:

**request_api_key**: Start email verification flow to get a free API key.
```json
{
  "name": "request_api_key",
  "inputSchema": {
    "type": "object",
    "required": ["email"],
    "properties": {
      "email": { "type": "string", "format": "email" }
    }
  }
}
```
Returns: {request_id, status: "pending", message, expires_in: 900}
If email already registered: {status: "ready", api_key: "nfsh_free_..."}

Example response:
```json
{
  "request_id": "vlsIfHPoU8NI6977Ogqb3re_csxj8_fz4Fet8IeG5_g",
  "status": "pending",
  "message": "Verification email sent. Call check_api_key_status with the request_id every 10 seconds.",
  "expires_in": 900
}
```

**check_api_key_status**: Poll for key after email verification.
```json
{
  "name": "check_api_key_status",
  "inputSchema": {
    "type": "object",
    "required": ["request_id"],
    "properties": {
      "request_id": { "type": "string" }
    }
  }
}
```
Returns: {status: "pending"} or {status: "ready", api_key: "nfsh_free_..."}
Call every 10 seconds. Key returned exactly once.

Example response (ready):
```json
{
  "status": "ready",
  "api_key": "nfsh_free_6af7435b0dc5f600b7caf3a76c011c90",
  "tier": "free",
  "monthly_limit": 1000,
  "rate_limit_per_minute": 10,
  "message": "API key activated. Add as X-Nefesh-Key header or Authorization: Bearer token."
}
```

Self-provisioning flow:
1. Agent asks the user: "What is your email address?" (agent MUST ask, never invents one)
2. User provides their real, accessible email
3. Agent calls request_api_key(email=USER_PROVIDED_EMAIL) using the real email
4. Verification email sent to user
5. Agent polls check_api_key_status(request_id) every 10 seconds
6. User clicks link in email, key activates
7. Next poll returns the API key
Free tier: 1,000 calls/month, all signals, 10 req/min. No credit card.

Important: The agent must ask the user for their real email address before calling request_api_key. Placeholder emails like dev@example.com or test@test.com are blocked server-side and will not produce a working key.

### Resources

- `nefesh://session/{session_id}/state` — Live state, subscribable

---

## Trigger Memory

Nefesh tracks which conversation topics cause stress — across turns,
across sessions. When you send `user_message` + `ai_response` with
biometric signals to /v1/ingest, Nefesh automatically:
1. Extracts psychological topics from the conversation
2. Correlates topics with stress levels over time
3. Classifies triggers as active (currently causing stress) or
   resolved (stress has decreased below threshold)

Requires `subject_id` to be set in the ingest payload.
Query triggers via GET /v1/triggers?subject_id=USER_ID or
MCP tool get_trigger_memory.

---

## Signal Fusion Status (v1)

| Category | Fields | Status |
|----------|--------|--------|
| Cardiovascular | HR, HRV (RMSSD, SDNN, pNN50), SpO2 | FUSED — influences state |
| Vocal | tone, speech_rate, pitch_variability | FUSED — influences state |
| Visual | expression, gaze, posture, engagement | FUSED — influences state |
| Textual | sentiment, urgency | FUSED — influences state |
| Metabolic | glucose_mg_dl, glucose_mmol_l, glucose_trend | ACCEPTED — stored, not fused |
| Neural | eeg_alpha/beta/theta_power, cognitive_load | ACCEPTED — stored, not fused |
| Electrodermal | eda, skin_temperature | ACCEPTED — stored, not fused |
| Respiratory | respiratory_rate | ACCEPTED — stored, not fused |
| Movement | steps_last_minute, activity_level | ACCEPTED — stored, not fused |
| Sleep | sleep_stage | ACCEPTED — stored, not fused |

"ACCEPTED" means: the field is in the schema, validated,
stored in Redis, and appears in `signals_received` in the
response. But it does not influence `stress_score` or `state`
in v1. Fusion for additional signal categories will be added
in v2 once the algorithms are validated.

---

## Edge rPPG Engine

Nefesh includes a lightweight browser-native rPPG engine that
extracts heart rate and HRV proxies from a standard webcam.
It runs entirely client-side — zero video frames ever
leave the browser.

The engine sends a ~300-byte JSON payload to the backend
once per second containing only extracted metrics (HR, HRV,
stress score). No video, no images, no pixels on the wire.

Add `?offline=true` to the demo URL for zero network calls —
the engine still runs locally.

---

## Privacy & Compliance

### Edge Processing
Raw sensor data (video, audio, accelerometer) stays on the
device. Only extracted numerical metrics are sent to the API.

### Data Retention
- Session data (state, signals): 20-minute inactivity TTL
- No biometric video or audio is ever stored

### GDPR / BIPA
- subject_id: Hashed internal user ID (Privacy by Design).
  Nefesh never knows the real identity.
- DELETE /v1/subjects/{subject_id}: Cascading deletion of
  all sessions and stored signals.
- Biometric data auto-deleted after session TTL.

### HIPAA
- No PHI stored. No clinical interpretation.
- Edge processing ensures raw biometrics never reach the server.

---

## Regulatory Position

Nefesh is NOT a medical device. Nefesh is NOT Software as a
Medical Device (SaMD).

- No clinical interpretation of values
- No medical recommendations
- No diagnoses
- No threshold alerts
- No dosing recommendations
- Glucose and SpO2 are context signals, not clinical data
- No insulin_on_board, no blood_pressure fields

Nefesh is a General Wellness Product that gives AI systems
context about a user's state. Clinical interpretation and
action are the responsibility of the B2B customer.

Every API response includes:
"disclaimer": "Not a medical device. For contextual AI adaptation only."

---

## Integration Examples

### Python
```python
import httpx
import uuid
from datetime import datetime, timezone

NEFESH_KEY = "nfsh_your_key_here"
SESSION_ID = str(uuid.uuid7())

async def send_heartbeat(hr: int, rmssd: float = None):
    payload = {
        "session_id": SESSION_ID,
        "heart_rate": hr,
        "timestamp": datetime.now(timezone.utc).isoformat(),
    }
    if rmssd:
        payload["rmssd"] = rmssd

    async with httpx.AsyncClient() as client:
        resp = await client.post(
            "https://api.nefesh.ai/v1/ingest",
            json=payload,
            headers={"X-Nefesh-Key": NEFESH_KEY},
        )
        state = resp.json()
        # state["suggested_action"] -> machine-readable action for your agent
        # state["action_reason"] -> why this action was chosen
        # state["recommendation"] -> human-readable style guide
        return state
```

### JavaScript
```javascript
const NEFESH_KEY = 'nfsh_your_key_here';
const SESSION_ID = crypto.randomUUID();

async function sendHeartbeat(hr, rmssd) {
  const resp = await fetch('https://api.nefesh.ai/v1/ingest', {
    method: 'POST',
    headers: {
      'X-Nefesh-Key': NEFESH_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      session_id: SESSION_ID,
      heart_rate: hr,
      rmssd: rmssd,
      timestamp: new Date().toISOString(),
    }),
  });
  const state = await resp.json();
  // state.suggested_action -> machine-readable action for your agent
  // state.action_reason -> why this action was chosen
  // state.recommendation -> human-readable style guide
  return state;
}
```

### LLM Integration Pattern
```python
# 1. Get human state before generating a response
state = await get_human_state(session_id)

# 2. Inject action into system prompt — one line, zero prompt engineering
system_prompt = f"""You are a helpful assistant.

ACTION: {state['suggested_action']}
REASON: {state['action_reason']}
STYLE: {state['recommendation']}
Do not mention biometrics or stress to the user."""

# 3. Check if previous action was effective (2nd+ call only)
if state.get('adaptation_effectiveness'):
    ae = state['adaptation_effectiveness']
    if not ae['effective']:
        system_prompt += f"\nYour previous approach ({ae['previous_action']}) increased stress by {ae['stress_delta']} points. Try a different strategy."

# 4. Generate response — the agent adapts automatically
response = await llm.generate(
    system=system_prompt,
    messages=conversation_history,
)
```

---

## Cognitive Compute Router (LLM Gateway)

LLM-agnostic proxy that adapts any AI's behavior based on
real-time biometric state. Sits between the customer's app and
their LLM provider. Supports OpenAI, Anthropic, Gemini, and
any OpenAI-compatible backend.

Domain: gateway.nefesh.ai

Three Operating Modes:

Mode 1: POST /v1/chat/completions
  Input: OpenAI format. Output: OpenAI format.
  Backend: Any (Anthropic translated natively).
  Use case: OpenAI SDK users, Gemini, local LLMs.

Mode 2: POST /v1/messages
  Input: Anthropic format. Output: Anthropic format.
  Backend: Anthropic (1:1 passthrough, no translation).
  No information loss. Prompt caching and extended thinking work.
  Anthropic SDK customers set base_url="https://gateway.nefesh.ai" -- done.

Mode 3: POST /v1/messages
  Input: Anthropic format. Output: Anthropic format.
  Backend: Non-Anthropic (translated to OpenAI, then back).
  Use case: Anthropic SDK users who want to use Gemini/OpenAI.

Supported LLM backends (X-LLM-Backend header):
  OpenAI: https://api.openai.com (default for /v1/chat/completions)
  Anthropic: https://api.anthropic.com (default for /v1/messages)
  Google Gemini: https://generativelanguage.googleapis.com/v1beta/openai
  Mistral: https://api.mistral.ai
  DeepSeek: https://api.deepseek.com
  Groq: https://api.groq.com/openai
  Together AI: https://api.together.xyz
  Fireworks AI: https://api.fireworks.ai/inference
  Ollama: http://your-server:11434
  vLLM: http://your-server:8000
  llama.cpp: http://your-server:8080

The gateway adjusts temperature based on biometric state. Stressed users get
more deterministic responses, calm users get more creative responses.

Request headers:
- X-Nefesh-Key: Nefesh API key (required)
- X-Nefesh-Subject: Subject ID from Device Registry (recommended)
- X-Nefesh-Session: Session ID (alternative, legacy)
- X-LLM-Key: Customer's LLM provider API key (required)
- X-LLM-Backend: LLM base URL (optional)

Response headers:
- X-Nefesh-Adapted: true/false
- X-Nefesh-State: calm/relaxed/focused/stressed/acute_stress
- X-Nefesh-Backend: anthropic-native, anthropic-passthrough, or unified-anthropic
- X-Nefesh-Reason: only when adapted=false

Graceful degradation: no signal = standard LLM behavior, no error.

## Device Registry

Register wearables once, bind them to users. No session management needed.

POST /v1/devices -- Register a device
  Request: {"device_name": "Polar H10 Office", "device_type": "polar_h10", "subject_id": "usr_tom"}
  Response: {"device_id": "dev_abc123", ...}

GET /v1/devices -- List registered devices

DELETE /v1/devices/{device_id} -- Remove a device

POST /v1/ingest with device_id -- API resolves device to subject automatically
  Request: {"device_id": "dev_abc123", "heart_rate": 92, "timestamp": "..."}

Gateway uses X-Nefesh-Subject header to read state by subject.
No session_id management. Device bound once, works forever.

The gateway does not log prompts or responses. LLM API keys are
forwarded in-memory, never stored. Not a medical device.

---

## Use Cases

### AI Coaching & Therapy
Detect rising stress during a coaching session. Automatically
simplify language, slow down, offer grounding techniques.
Resume complex exploration when the client stabilizes.

### Avatar Platforms
Give digital avatars physiological awareness. Avatar adjusts
facial expression, speaking pace, and topic complexity based
on the user's real-time state.

### Telehealth
Supplement clinical conversations with physiological context.
Alert the provider (not the patient) when arousal patterns
suggest discomfort with a topic. Not a diagnostic tool.

### Diabetes Context
Send CGM glucose readings as context signals. The AI adapts
tone and complexity based on whether the user is in a glucose
spike or stable range. No clinical interpretation — Nefesh
does not suggest insulin doses or medical actions.

### Education
Adapt tutoring difficulty in real time. When a student shows
acute stress, simplify the explanation. When calm, introduce
harder problems and challenge assumptions.

### Accessibility
Give AI systems awareness of physiological states that the
user may not be able to verbalize. Useful for non-verbal
users, users with cognitive disabilities, or situations
where self-reporting is unreliable.

---

## Products

### MCP Server
Streamable HTTP endpoint with 6 tools for AI agents.
Documentation: https://nefesh.ai/docs/mcp

### A2A Server
Agent-to-Agent protocol v1.0 with 4 skills (JSON-RPC 2.0).
Documentation: https://nefesh.ai/docs/a2a

### Cognitive Compute Router (Gateway)
3 modes, 11 LLM providers, zero code changes.
Documentation: https://nefesh.ai/docs/gateway

### CLI (@nefesh/cli)
Official command line tool.
Documentation: https://nefesh.ai/docs/cli

### Human State Protocol (HSP)
Open specification for exchanging human state between AI systems.
Documentation: https://nefesh.ai/docs/hsp

### Webhooks
State change notifications.
Documentation: https://nefesh.ai/docs/webhooks

## Additional Integrations

- Pixel Watch: https://nefesh.ai/docs/ingest/pixel-watch (Health Connect, Android)
- Apple Watch: https://nefesh.ai/docs/ingest/apple-watch (HealthKit, iOS)
- Any Device: https://nefesh.ai/docs/ingest/any-device (Universal integration guide)

## GitHub Repositories

- nefesh-mcp-server: https://github.com/nefesh-ai/nefesh-mcp-server (MCP + A2A server source)
- nefesh-gateway: https://github.com/nefesh-ai/nefesh-gateway (Cognitive Compute Router source)
- nefesh-a2a: https://github.com/nefesh-ai/nefesh-a2a (A2A reference implementation)
- nefesh-cli: https://github.com/nefesh-ai/nefesh-cli (Official CLI source)
- human-state-protocol: https://github.com/nefesh-ai/human-state-protocol (Open specification)
- nefesh-examples: https://github.com/nefesh-ai/nefesh-examples (Integration examples: Python, JavaScript, curl)

---

## Contact

- Website: https://nefesh.ai
- Enterprise: https://nefesh.ai/enterprise
- Founder: Tom Stuhl
- Live Demo: https://sandbox.nefesh.ai

Not a medical device. For contextual AI adaptation only.