# Clinical Intake Agent
Source: https://docs.hana.health/agents/clinical-intake-agent
Structured clinical data collection for pre-visit intake, assessment administration, and CMS-billable documentation.
## Overview
The Clinical Intake Agent handles structured clinical data collection — the forms, screenings, and assessments that traditionally require paper, portals, or staff phone calls. It converts unstructured patient dialogue into structured clinical data flowing directly into the EHR.
## Use Cases
### Pre-Visit Intake
* Demographics and insurance verification
* Chief complaint and symptom collection
* Medical history update
* Current medication list reconciliation
* Allergy review
* Social history (smoking, alcohol, exercise)
* Family history updates
### Clinical Screening
* Validated assessment instruments (PHQ-9, GAD-7, AUDIT-C, CAGE-AID, ASQ-3, Edinburgh, KCCQ)
* Natural conversation administration rather than robotic question-reading
* Automatic clinical scoring with threshold-based alerts
* Results written directly to EHR as structured observations
### BHI/CCM Documentation
* Structured interactions designed to support CMS documentation requirements for billing codes
* Automated documentation for billing compliance review by clinical staff
* Time tracking for CMS time-based codes
CMS billing eligibility for AI-conducted conversations depends on your organization's billing compliance framework and evolving CMS guidance. HANA generates the structured documentation and time tracking required for BHI/CCM billing submissions, but clinical teams should validate billing eligibility with their compliance department. We recommend consulting your billing compliance team during onboarding.
### Post-Procedure Follow-Up
* Structured symptom collection after procedures
* Pain assessment and medication effectiveness
* Complication screening with escalation
* Recovery milestone tracking
## Structured Data Extraction
The agent converts unstructured patient dialogue into structured clinical data with entity extraction, verification against EHR data, and automatic follow-up question generation for ambiguous or incomplete information.
## Assessment Administration
HANA administers validated clinical assessments through natural conversation, mapping patient responses to scoring categories, calculating total scores, triggering clinical alerts, and documenting structured scores in the EHR.
## EHR Write-Back
| Data Type | EHR Destination | Format |
| ---------------- | --------------- | ------------------------ |
| Demographics | Patient record | FHIR Patient |
| Medications | Medication list | FHIR MedicationStatement |
| Conditions | Problem list | FHIR Condition (ICD-10) |
| Screening scores | Clinical notes | FHIR Observation |
| Allergies | Allergy list | FHIR AllergyIntolerance |
| Appointments | Schedule | FHIR Appointment |
| Clinical notes | Encounter notes | FHIR DocumentReference |
## Note Generation
* **Configurable Templates**: Note styles per organization, specialty, and provider
* **Structured JSON**: All clinical data captured as structured JSON before note generation
* **SOAP Support**: Subjective, Objective, Assessment, Plan sections from conversation content
* **ICD-10/CPT Suggestions**: Relevant billing codes suggested based on conversation content
# Decision Support Agent
Source: https://docs.hana.health/agents/decision-support-agent
Deliberation Framework-powered agent for clinical conversation planning and real-time decision-making.
## Overview
The Decision Support Agent leverages the Deliberation Framework to enhance clinical conversation quality by providing comprehensive planning. It integrates contextual data from EHR, conversation history, and clinical protocols to deliver relevant questions, appropriate branching, and escalation decisions tailored to each patient interaction.
## Contextual Data Providers
* **EHR Gateway**: Patient historical information from electronic health records
* **Conversation Memory**: Details from prior patient interactions
* **Protocol Knowledge Base**: Clinical protocol rules, branching logic, and evidence-based guidelines
* **Real-Time Monitoring**: Live conversation quality signals
## Specialty Configuration
* **Specialty Protocols (1-N)**: Domain-specific conversation flows
* **Assessment Instruments**: Validated screening tools per specialty
* **Escalation Rules**: Specialty-appropriate thresholds for human handoff
## Deliberation Framework Integration
The Decision Support Agent dynamically utilizes consensus-based reasoning:
* Contextual information from EHR, conversation history, and protocol rules aggregated
* Deliberation Engine determines most clinically relevant questions, branching decisions, and escalation triggers
## Workflow
1. **Input Processing**: Patient EHR data and conversation context undergo entity extraction
2. **Parallel Processing**: Clinical queries routed to expert models; queries enhanced by protocol knowledge base
3. **Consensus Building**: Results synthesized using weighted probabilities and expert agreement
4. **Output Processing**: Plans validated with confidence scores, enabling revision and recalibration
5. **Feedback Loop**: Conversation outcomes provide feedback; agent adjusts future planning
## Clinical Outputs
* **Prioritized Question Sets**: Dynamically ordered by clinical importance and patient context
* **Protocol Branching Decisions**: Optimal path based on patient responses and guidelines
* **Escalation Triggers**: When to hand off to human staff with full context
* **Data Extraction Plans**: What structured data to capture from conversation
## Future Enhancements
* Graph-based patient modeling with dynamic knowledge graphs
* Enhanced specialty coverage with expanded expert models
* Predictive analytics for enhanced clinical responsiveness
# Voice Engagement Agent
Source: https://docs.hana.health/agents/voice-engagement-agent
Multi-channel patient communication agent for inbound and outbound voice interactions.
## Overview
The Voice Engagement Agent provides multi-channel communication, fostering an agentic relationship between patients and healthcare organizations. It facilitates efficient, personalized interactions via voice calls and SMS, ensuring a seamless patient experience.
## Top-Level Use Cases
### Inbound Call Handling
Healthcare organizations can handle greater call volume with better outcomes and reduced operational costs.
Features:
* **Low Latency NLP-based Skill Activation**: Loads contextually-specific protocols such as scheduling, insurance, triage, registration, medications, labs, forms, records, and billing. Includes warm transfers to appropriate staff when necessary.
* **Low Latency Responses**: Simultaneous response planning using partial transcripts within speech loops. Sub-second response times from optimized conversation engine.
* **Per-Patient Memory**: Tracks care goals, language preferences, identity verification, preferred contact methods, and self-scheduled callbacks across all channels.
### Outbound Retention & Engagement
```mermaid theme={null}
graph LR
subgraph Outreach["Outreach Flow"]
EHR["EHR Query\nCare gaps · Follow-ups"] --> ID["Identify\nPatients"]
ID --> SMS["SMS First\nContact"]
SMS --> SCHED["Patient\nSchedules Call"]
SCHED --> CALL["Voice\nConversation"]
end
subgraph Memory["Longitudinal Memory"]
CM["Clinical Context\n(from EHR)"]
IM["Interaction Context\n(built by HANA)"]
EI["Engagement Intelligence\n(learned over time)"]
end
CALL --> CM
CALL --> IM
CALL --> EI
CM --> NEXT["Next\nConversation"]
IM --> NEXT
EI --> NEXT
NEXT --> CALL
```
* **SMS-First Outreach**: Outbound engagement always begins with a text message — never an unsolicited cold call. The patient receives context about why HANA is reaching out and schedules a call at their preferred time. This approach consistently produces higher answer rates and patient satisfaction compared to cold outbound calls.
* **Automated Detection**: Identifies patients requiring outreach by querying EHR data, waitlists, and scheduling systems
* **Goal Persistence**: Remembers outreach objectives and brings them up dynamically regardless of when the conversation occurs
* **Multi-channel Coordination**: Outreach spans voice and SMS with consistent context across channels
## Capabilities
### Appointment Management
* Schedule, reschedule, and confirm appointments
* Waitlist management and backfill
* No-show follow-up and rebooking
* Pre-visit preparation reminders
### Care Gap Closure
* Preventive screening outreach (mammography, colonoscopy, annual wellness)
* Vaccination follow-up and scheduling
* Lab work reminders
* Referral completion tracking
### Chronic Care Management
* Monthly CCM check-in calls with documentation structured for CMS billing review
* Medication adherence monitoring
* Symptom tracking and trend detection
* Care plan review and updates
### Behavioral Health Integration
* BHI conversations with documentation structured for CMS billing review
* PHQ-9, GAD-7 administration through natural conversation
* Crisis screening with appropriate escalation
* Treatment adherence follow-up
### Patient Retention & Health Coaching
The biggest challenge in longitudinal patient programs (chronic care, behavioral health, post-procedure follow-up) is dropout. Patients stop answering calls after the first few weeks because they don't see personal value in the interaction.
HANA addresses this with an engagement architecture that gives patients reasons to stay in the program:
* **Accountability Companion**: Between clinical monitoring calls, the agent supports patients in working toward personal health goals (exercise targets, dietary changes, medication routines). These goals are set collaboratively during conversations and tracked across interactions.
* **Patient Diary**: Patients can access a summary of their own conversation history, health goals, and progress. This transparency gives patients ownership of their data and a reason to continue engaging.
* **Adaptive Engagement Timing**: The system learns when each patient is most likely to engage (morning vs. evening, weekday vs. weekend) and adjusts outreach timing accordingly.
* **Channel Switching**: If a patient stops responding to calls, the system can switch to SMS check-ins or adjust frequency — adapting to the patient's engagement pattern rather than forcing a rigid schedule.
***
## Longitudinal Patient Memory
HANA's engagement model is built on the principle that every conversation should be better than the last. The system maintains a longitudinal patient profile that grows richer with each interaction:
**Clinical Context (from EHR):**
* Diagnoses, medications, care plans, appointment history
* Pulled fresh before each conversation to ensure current data
**Interaction Context (built by HANA):**
* Communication preferences: voice vs. SMS, preferred time, language, pacing
* Conversation history: what was discussed, what goals were set, what was flagged
* Behavioral patterns: how the patient responds to different question styles, when they disengage
* Vocal baseline: prosodic profile for deviation detection (see Vocal Intelligence)
**Engagement Intelligence:**
* Which outreach strategies work for this patient (SMS first? Direct call? Morning vs. evening?)
* Dropout risk scoring based on engagement patterns
* Personalized conversation pacing and complexity level
Patient memory is not a parallel data store competing with the organization's EHR or CRM. Clinical data always comes from the organization's systems. HANA's memory layer captures *interaction intelligence* — how to communicate with each patient most effectively — and feeds clinical data back to the EHR via write-back.
***
## Technical Specifications
### Voice Quality
* Natural conversational speech synthesis with dynamic prosody
* Multiple voice personas configurable per organization
* Multi-language support: clinically validated for English, Spanish, Italian, French, and German; additional languages available with varying levels of clinical coverage through our voice synthesis and recognition providers
* Automatic language detection and switching
### Latency
* Target response time: \< 800ms p95
* Parallel response planning during patient speech
* Pre-computed segments for standard protocol language
* Streaming synthesis begins before full response is composed
# Autonomous Trained Agents
Source: https://docs.hana.health/decision-making/autonomous-agents
Agents designed to automate complex, multi-step healthcare workflows through role-based activation, contextual memory, and pattern-aware behavior.
## Overview
HANA is actively developing autonomous trained agents designed to streamline healthcare workflows by automating complex, multi-step tasks traditionally handled by clinical staff. Our current architecture includes foundational components such as real-time patient conversation management, task triage, and clinical data extraction — each contributing to agent specialization over time. These agents are built to adapt to role-specific workflows (e.g., intake coordinator, care navigator, outreach specialist) and are architected to incorporate behavioral patterns and institutional routines into their task execution logic.
## Importance
Autonomous trained agents combine structured learning, contextual memory, and task-specific reasoning to simulate human decision-making in healthcare workflows. These agents ingest unstructured input — such as patient voice conversations or incoming EHR data — and convert it into structured actions by referencing known medical ontologies, prior patient interactions, and observed organizational preferences. Over time, agents refine their behavior by learning from task feedback, repeat interactions, and localized workflow patterns.
## Current Capabilities
### Real-time Patient Conversations
* Conduct voice-based clinical conversations with > 95% information extraction accuracy
* Extract structured clinical elements (medications, conditions, screenings) in real-time to support downstream task automation
### AI Triage & Task Dispatch
* Classifies incoming patient needs by intent and clinical urgency, routing conversations to appropriate protocols or staff
* Supports modular agent chaining based on observed workflows and organizational preferences
### Clinical Decision Support
* Provides protocol-guided conversation branching based on patient responses and known clinical guidelines
* Operates within scoped environments with configurable guardrails and auditing for transparency
### Pattern-Aware Behavior Modeling
* Agents continuously observe conversation patterns across patient populations and use structured feedback to adjust responses
* Over time, agents apply known organizational routines (e.g., scheduling preferences, referral patterns, common protocols) to new patient contexts to reduce friction and increase relevance
### Structured Output Generation
* Agents produce standardized outputs such as clinical notes, appointment bookings, referral triggers, and care gap alerts
* These outputs are tied to intent signals derived from conversation data and historical patterns
## Implementation Workflow
1. **Role-Based Activation**: Agents enabled based on clinical workflow role (intake, follow-up, care coordination, scheduling)
2. **Context Setup**: Agents configured with access to patient EHR data, conversation history, and organizational preferences. Optional scheduling and referral system integrations enhance context
3. **Task Detection & Triggering**: Agents monitor real-time conversation content and trigger actions based on clinical patterns, keywords, or protocol rules
4. **Reasoning & Output**: Agents generate structured outputs — clinical notes, screening scores, appointment bookings — tailored to context and role
5. **Feedback Integration**: Clinical team feedback logged and used to refine agent behavior over time
6. **Memory & Personalization**: Agents adapt to individual patient communication patterns while maintaining strict data isolation between organizations
7. **Audit & Oversight**: All agent actions logged and reviewable for transparency and compliance
## Future Integration
Autonomous trained agents are a natural evolution of HANA's current infrastructure. With role-based orchestration, protocol-driven conversation management, and secure patient memory, we are positioned to support agents that learn from organizational behavior while remaining compliant and auditable. These agents will unlock scalable, safe task delegation across the care journey — beginning with high-trust domains and extending into more dynamic, multi-agent collaborations.
# Deliberation Framework
Source: https://docs.hana.health/decision-making/deliberation-framework
Multi-model deliberation architecture integrating specialized expert models for clinical conversation planning through collaborative reasoning.
## Overview
HANA's Deliberation Framework integrates multiple specialized clinical "expert" models to produce high-quality conversation plans through collaborative reasoning. Rather than relying on a single model to make clinical decisions, the framework orchestrates inputs from distinct, configurable specialty models — each evaluating the conversation plan from its domain perspective — to synthesize a unified, well-supported clinical approach.
The deliberation framework is the reasoning engine behind HANA's pre-call planning. It determines what questions to ask, in what order, with what branching logic, and when to escalate — before the conversation begins. This planning step is what enables the real-time conversation engine to operate within tight latency constraints while maintaining clinical accuracy.
## Core Architecture
### System Design
The Deliberation Framework comprises:
* **Triage Model**: Identifies the clinical task type and selects appropriate specialty models for the conversation context
* **Expert Model Block**: Consists of independent expert agents that evaluate tasks from specialized perspectives, each generating probability distributions over potential actions
* **Deliberation Aggregation Model**: Synthesizes expert inputs into a final decision, leveraging nuanced evaluation and probabilistic weighting
```mermaid theme={null}
graph TB
Q["Clinical Query\n+ Patient Context"] --> TM["Triage Model"]
TM -->|"Task Type + Specialties"| E1["Expert Model 1"]
TM -->|"Task Type + Specialties"| E2["Expert Model 2"]
TM -->|"Task Type + Specialties"| EN["Expert Model N"]
E1 -->|"Response + P(X)"| AGG["Deliberation\nAggregation"]
E2 -->|"Response + P(X)"| AGG
EN -->|"Response + P(X)"| AGG
AGG --> WLOP["WLOP Probability\nWeighting"]
WLOP --> CB["Cascade\nBoosting"]
CB --> DM["Deliberation\nModel"]
DM --> PLAN["Final Conversation Plan\nQuestions · Branching · Escalation"]
```
### Expert-Based Decomposition
The Triage Model evaluates clinical queries (Q) and assigns domain-specific models based on identified requirements:
```
LLM_triage(Q) → (Task Type, Specialties)
Specialties = {s₁, s₂, ..., sₙ}
```
Each specialist model (LLM\_sᵢ) generates an independent response and a probability distribution:
```
R_expert^(i) = LLM_sᵢ(Q, Task Type)
```
The final aggregated output is determined through:
```
O_final = f(R_expert^(1), ..., R_expert^(n))
A_final = LLM_consensus(O_final)
```
### Probability Weighting
To reflect clinical uncertainty, the Deliberation Framework aggregates expert probabilities using a Weighted Log Opinion Pool (WLOP):
```
P_combined(X) = Σ wᵢ · log pᵢ(X)
P_normalized(X) = exp(P_combined(X)) / Σⱼ exp(P_combined(Xⱼ))
```
This approach moderates expert biases, rewarding consensus while accommodating individual expert uncertainties.
### Cascade Boosting for Probabilities
To further refine probability assessments, Cascade Boosting amplifies the likelihood of answers based on frequency and rank across experts:
* Establish frequency f\_x,r for answer X at rank r
* Apply cascade weighting (θ) progressively decreasing for lower ranks
Boosted scores calculated:
```
BoostedScore(X) = P_normalized(X) + λ_boost · Σ(f_x,r × θ_r)
```
The final boosted probability:
```
P_final(X) = exp(BoostedScore(X)) / Σⱼ exp(BoostedScore(Xⱼ))
```
### Reaching Consensus
The final decision integrates each expert's analysis through structured deliberation, examining not only aggregated probabilities but also expert reasoning and justification.
The Deliberation Model explicitly factors nuanced clinical reasoning, allowing a sophisticated, clinically coherent final recommendation beyond numerical probability alone.
## Application to HANA Voice Conversations
### Pre-Call Planning
The deliberation framework determines the conversation plan:
1. Triage model analyzes patient profile and identifies clinical task type
2. Expert ensemble evaluates proposed question set, ordering, and branching logic
3. Consensus aggregation produces final conversation plan with confidence-weighted questions
### Real-Time Branching
During conversation, branching decisions use a simplified version of the deliberation framework optimized for voice latency constraints:
1. Patient response parsed and entities extracted
2. Pre-computed branching rules (generated during pre-call planning) handle the majority of decisions with sub-second latency
3. For unanticipated responses that fall outside pre-computed plans, a lightweight evaluation determines the optimal branch within the latency budget
4. If no action achieves sufficient confidence, the system falls back to a safe default or escalates to staff
The full multi-model deliberation framework runs during pre-call planning (where the 3-second latency budget allows it). Real-time branching primarily relies on the pre-computed conversation plan, with lightweight fallback evaluation for edge cases.
### Escalation Decisions
Deliberation governs escalation from AI to human:
* Clinical escalation: patient reports symptoms requiring immediate attention
* Emotional escalation: patient distress exceeds safe handling capacity
* Complexity escalation: conversation diverged beyond protocol coverage
* Quality escalation: system confidence dropped below acceptable threshold
## Evaluation Methodologies
### Accuracy Assessment
* **Raw accuracy**: Overall accuracy measured with detailed breakdown by clinical specialty and conversation type
* **Top-K performance**: Evaluates how frequently correct clinical actions appear within top-ranked probability outputs
* **Reliability analysis**: Calibration assessments ensure confidence intervals reliably correlate with observed accuracy
### Future Enhancements
* Enhanced specialization: Expand domain-specific expert models for nuanced evaluation across diverse clinical domains
* Predictive quality assessment: Implement proactive predictions about conversation quality to allow preemptive corrections
* Cross-modal evaluation: Assess consistency across different clinical data modalities
## Modular Framework
The Deliberation Framework is modular and adaptable:
* **Expert Model Blocks**: Independently configurable expert models specialized in distinct clinical domains — allows targeted updates without disrupting overall system
* **Flexible Triage System**: Dynamically routes clinical queries to appropriate expert models based on case specifics
* **Dynamic Deliberation Aggregation**: Aggregates expert outputs using weighted consensus, customizable for accuracy, efficiency, or latency optimization
* **Real-Time Integration**: Modular structure facilitates real-time adjustments based on clinician feedback and evolving clinical guidelines
# API Reference
Source: https://docs.hana.health/developers/api-reference
Complete API documentation for HANA's patient engagement infrastructure.
## Base URL
```
Production: https://api.hana.health/v1
Sandbox: https://sandbox.api.hana.health/v1
```
## Authentication
All requests require a Bearer token in the `Authorization` header:
```bash theme={null}
Authorization: Bearer hana_sk_live_...
```
API keys are scoped to an organization and environment (production or sandbox). Keys can be rotated without downtime.
## Rate Limits
| Endpoint | Rate Limit |
| ------------------- | ---------- |
| Engagement creation | 100/minute |
| Patient management | 200/minute |
| Read operations | 500/minute |
| Webhook management | 50/minute |
Rate limit headers are included in every response:
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1707300000
```
***
## Engagements
Engagements are the core resource. An engagement represents a single patient interaction — a call, an SMS sequence, or a multi-channel workflow.
### Create Engagement
Patient information for this engagement.
Your internal patient identifier.
Patient phone number (E.164 format).
`voice`, `sms`, or `whatsapp`.
ISO 639-1 language code. Supported: `en`, `it`, `es`, `de`, `fr`.
Protocol identifier. Use a pre-configured protocol ID or `custom` with inline protocol definition.
`scheduled`, `immediate`, or `event`.
ISO 8601 datetime. Required when `trigger_type` is `scheduled`.
Additional context from your system to enrich the reasoning engine.
Structured EHR data (diagnoses, medications, vitals).
Recent clinical events (lab results, alerts, appointment changes).
Free-text clinical notes for reasoning context.
Webhook URL for engagement events.
Branding configuration for white-label deployments.
**Request:**
```bash theme={null}
POST /v1/engagements
```
```json theme={null}
{
"patient": {
"id": "P-12345",
"phone": "+15550123456",
"preferred_channel": "voice",
"language": "en"
},
"protocol": "medication-adherence-diabetes",
"trigger_type": "scheduled",
"scheduled_at": "2026-02-08T10:00:00Z",
"context": {
"ehr_data": {
"diagnoses": [{"code": "E11.9", "description": "Type 2 diabetes"}],
"medications": [{"name": "Metformin", "dose": "500mg", "frequency": "2x daily"}]
}
},
"callback_url": "https://your-app.com/webhooks/hana"
}
```
**Response:**
```json theme={null}
{
"id": "eng_abc123",
"status": "scheduled",
"patient_id": "P-12345",
"protocol": "medication-adherence-diabetes",
"scheduled_at": "2026-02-08T10:00:00Z",
"created_at": "2026-02-07T14:30:00Z"
}
```
### Get Engagement
```bash theme={null}
GET /v1/engagements/{engagement_id}
```
**Response:**
```json theme={null}
{
"id": "eng_abc123",
"status": "completed",
"patient_id": "P-12345",
"protocol": "medication-adherence-diabetes",
"started_at": "2026-02-08T10:02:00Z",
"completed_at": "2026-02-08T10:08:30Z",
"outcome": {
"clinical_note": "...",
"tasks": [...],
"risk_flags": [],
"risk_level": "low",
"metrics": {
"engagement_score": 0.92,
"completion_rate": 1.0,
"interaction_count": 8,
"duration_seconds": 390
}
}
}
```
### List Engagements
```bash theme={null}
GET /v1/engagements?patient_id=P-12345&status=completed&limit=20
```
**Query Parameters:**
| Parameter | Type | Description |
| ------------ | -------- | -------------------------------------------------------------- |
| `patient_id` | string | Filter by patient |
| `protocol` | string | Filter by protocol |
| `status` | string | `scheduled`, `in_progress`, `completed`, `failed`, `cancelled` |
| `from` | datetime | Start of date range |
| `to` | datetime | End of date range |
| `limit` | integer | Max results (default 20, max 100) |
| `cursor` | string | Pagination cursor |
### Cancel Engagement
```bash theme={null}
DELETE /v1/engagements/{engagement_id}
```
***
## Patients
### Create or Update Patient
```bash theme={null}
PUT /v1/patients/{patient_id}
```
```json theme={null}
{
"first_name": "Maria",
"last_name": "Garcia",
"phone": "+15550123456",
"email": "maria@example.com",
"preferred_channel": "voice",
"preferred_language": "en",
"timezone": "America/New_York",
"clinical_data": {
"diagnoses": [{"code": "E11.9", "description": "Type 2 diabetes"}],
"medications": [{"name": "Metformin", "dose": "500mg", "frequency": "2x daily"}]
},
"tags": ["chronic_care", "medication_monitoring"]
}
```
### Get Patient
```bash theme={null}
GET /v1/patients/{patient_id}
```
### List Patient Engagements
```bash theme={null}
GET /v1/patients/{patient_id}/engagements
```
### Get Patient Memory
Retrieve the longitudinal context HANA has built for a patient:
```bash theme={null}
GET /v1/patients/{patient_id}/memory
```
**Response:**
```json theme={null}
{
"patient_id": "P-12345",
"interaction_count": 12,
"first_interaction": "2025-11-15T10:00:00Z",
"last_interaction": "2026-02-07T10:00:00Z",
"preferences": {
"best_contact_time": "morning",
"preferred_channel": "voice",
"communication_style": "warm_conversational",
"language_complexity": "simple"
},
"longitudinal_trends": {
"medication_adherence": [0.4, 0.5, 0.6, 0.6, 0.7],
"mood_trend": "stable",
"engagement_quality": "high"
},
"active_barriers": [
{"type": "cost", "detail": "Insurance change increasing copay", "first_reported": "2026-01-20"}
]
}
```
***
## Protocols
### List Protocols
```bash theme={null}
GET /v1/protocols
```
Returns all configured protocols for your organization.
### Create Protocol
```bash theme={null}
POST /v1/protocols
```
```json theme={null}
{
"name": "Post-Surgery Day 3 Check-In",
"description": "Verify patient recovery status 3 days post-surgery",
"objective": "Assess pain levels, medication compliance, wound status, and mobility",
"frequency": "one_time",
"channels": ["voice", "sms"],
"questions": [
{
"id": "pain_level",
"topic": "pain_assessment",
"prompt": "How would you rate your pain on a scale of 1 to 10?",
"response_type": "numeric",
"escalation_threshold": 8
},
{
"id": "medication",
"topic": "medication_adherence",
"prompt": "Have you been able to take your pain medication as prescribed?",
"response_type": "boolean",
"follow_up_if_false": "What's been preventing you from taking it?"
},
{
"id": "wound",
"topic": "wound_status",
"prompt": "How does the incision site look? Any redness, swelling, or drainage?",
"response_type": "text",
"escalation_keywords": ["infected", "pus", "fever", "red", "swollen"]
}
],
"escalation_policy": "clinic-xyz-post-surgical"
}
```
### Upload Protocol Document
Upload a PDF or document for HANA to parse into a structured protocol:
```bash theme={null}
POST /v1/protocols/upload
Content-Type: multipart/form-data
```
***
## Webhooks
### Webhook Events
| Event | Description |
| ---------------------- | ------------------------------------------ |
| `engagement.scheduled` | Engagement has been scheduled |
| `engagement.started` | Patient interaction has begun |
| `engagement.completed` | Interaction completed successfully |
| `engagement.failed` | Interaction could not be completed |
| `engagement.escalated` | Risk signal detected, escalation triggered |
| `patient.updated` | Patient memory or profile updated |
### Webhook Payload
All webhook payloads include:
```json theme={null}
{
"event": "engagement.completed",
"timestamp": "2026-02-08T10:08:30Z",
"engagement_id": "eng_abc123",
"data": {
// Event-specific data
},
"signature": "sha256=..."
}
```
### Webhook Security
All webhooks are signed with HMAC-SHA256. Verify the signature using your webhook secret:
```javascript theme={null}
const crypto = require('crypto');
function verifyWebhook(payload, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return `sha256=${expected}` === signature;
}
```
***
## Error Handling
All errors follow a consistent format:
```json theme={null}
{
"error": {
"code": "invalid_patient_phone",
"message": "Phone number must be in E.164 format",
"status": 400,
"details": {
"field": "patient.phone",
"provided": "555-0123",
"expected": "+15550123456"
}
}
}
```
| Status Code | Meaning |
| ----------- | ------------------------ |
| 400 | Invalid request |
| 401 | Authentication failed |
| 403 | Insufficient permissions |
| 404 | Resource not found |
| 429 | Rate limit exceeded |
| 500 | Internal server error |
Detailed SDK documentation for Node.js and Python.
# Authentication
Source: https://docs.hana.health/developers/authentication
Secure your integration with HANA using API keys, scoped tokens, and webhook verification.
## API Keys
Every HANA integration uses API keys scoped to your organization and environment. Keys follow a predictable format so you can identify them quickly in logs:
```
hana_sk_live_... → Production key
hana_sk_test_... → Sandbox key
```
Never embed API keys in client-side code, mobile apps, or version control. Use environment variables or a secrets manager.
### Key Permissions
Keys are scoped to one of three permission levels:
| Scope | Can Do | Use Case |
| ------------------ | ----------------------------------------- | ----------------------------- |
| `full_access` | All operations | Server-to-server integrations |
| `engagements_only` | Create/read engagements, receive webhooks | Limited integrations |
| `read_only` | Read engagements, patients, metrics | Dashboards, reporting |
### Creating Keys
Keys are provisioned during partner onboarding. To manage keys:
```bash theme={null}
# List active keys
GET /v1/auth/keys
# Rotate a key (old key remains valid for 24 hours)
POST /v1/auth/keys/{key_id}/rotate
```
**Response:**
```json theme={null}
{
"id": "key_xyz789",
"prefix": "hana_sk_live_",
"scope": "full_access",
"created_at": "2026-02-07T14:30:00Z",
"expires_at": null,
"last_used_at": "2026-02-07T14:28:00Z"
}
```
### Key Rotation
HANA supports zero-downtime key rotation. When you rotate a key:
1. A new key is issued immediately
2. The old key continues working for 24 hours
3. After 24 hours, the old key is automatically revoked
This gives your team time to update all services without disruption.
***
## Request Authentication
Include your API key in the `Authorization` header on every request:
```bash theme={null}
curl -X POST https://api.hana.health/v1/engagements \
-H "Authorization: Bearer hana_sk_live_abc123..." \
-H "Content-Type: application/json" \
-d '{ ... }'
```
```javascript Node.js theme={null}
import { HanaClient } from '@hana-health/sdk';
const hana = new HanaClient({
apiKey: process.env.HANA_API_KEY,
environment: 'production',
region: 'eu'
});
// SDK handles authentication automatically
const engagement = await hana.engagements.create({ ... });
```
```python Python theme={null}
from hana_health import HanaClient
hana = HanaClient(
api_key=os.environ["HANA_API_KEY"],
environment="production",
region="eu"
)
# SDK handles authentication automatically
engagement = hana.engagements.create(...)
```
***
## Webhook Verification
All outbound webhooks from HANA are signed with HMAC-SHA256 using your webhook secret. Always verify the signature before processing events.
### Verification Flow
1. HANA computes `HMAC-SHA256(webhook_secret, raw_request_body)`
2. The signature is sent in the `X-Hana-Signature` header
3. Your server recomputes the HMAC and compares
```javascript Node.js theme={null}
const crypto = require('crypto');
function verifyHanaWebhook(rawBody, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(rawBody)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(`sha256=${expected}`),
Buffer.from(signature)
);
}
// Express middleware
app.post('/webhooks/hana', express.raw({ type: 'application/json' }), (req, res) => {
const sig = req.headers['x-hana-signature'];
if (!verifyHanaWebhook(req.body, sig, process.env.HANA_WEBHOOK_SECRET)) {
return res.status(401).send('Invalid signature');
}
const event = JSON.parse(req.body);
// Process event...
res.status(200).send('ok');
});
```
```python Python theme={null}
import hmac
import hashlib
def verify_hana_webhook(raw_body: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(
secret.encode(),
raw_body,
hashlib.sha256
).hexdigest()
return hmac.compare_digest(f"sha256={expected}", signature)
# Flask example
@app.route('/webhooks/hana', methods=['POST'])
def hana_webhook():
sig = request.headers.get('X-Hana-Signature')
if not verify_hana_webhook(request.data, sig, WEBHOOK_SECRET):
abort(401)
event = request.json
# Process event...
return 'ok', 200
```
Always use timing-safe comparison functions to prevent timing attacks. Never use `==` for signature comparison.
***
## Organization & Environment Isolation
Each organization gets fully isolated environments:
```
Organization: "Acme Health"
├── Production
│ ├── API Key: hana_sk_live_...
│ ├── Webhook Secret: whsec_live_...
│ └── Data: Production patients & engagements
└── Sandbox
├── API Key: hana_sk_test_...
├── Webhook Secret: whsec_test_...
└── Data: Test patients only (no real calls)
```
Data never crosses environment boundaries. Sandbox keys cannot access production data.
***
## IP Allowlisting (Optional)
For organizations with strict network policies, restrict API access to specific IP ranges:
```bash theme={null}
POST /v1/auth/ip-allowlist
```
```json theme={null}
{
"allowed_cidrs": [
"203.0.113.0/24",
"198.51.100.0/24"
]
}
```
When enabled, requests from non-allowlisted IPs receive `403 Forbidden`.
Detailed guide to receiving and processing HANA events.
# EHR Integration
Source: https://docs.hana.health/developers/ehr-integration
Connect HANA to Electronic Health Record systems via direct API or middleware partners. Bidirectional data flow — read patient context, write clinical notes back.
## How EHR Integration Works
HANA's clinical value depends on being part of the care record, not separate from it. The integration model is bidirectional:
1. **Read** → HANA pulls patient context (demographics, diagnoses, medications, care plans) to inform the reasoning engine before each interaction
2. **Write-back** → After engagement, HANA pushes structured clinical notes, tasks, and flags directly into the patient chart
This closed loop is what makes HANA infrastructure rather than another disconnected tool.
```
┌─────────────┐ Read ┌─────────────┐ Engage ┌─────────────┐
│ EHR │ ────────────→ │ HANA │ ────────────→ │ Patient │
│ │ ←──────────── │ Reasoning │ ←──────────── │ │
└─────────────┘ Write-back └─────────────┘ Respond └─────────────┘
```
***
## Integration Paths
HANA supports three integration approaches, depending on your EHR and technical requirements:
### 1. Direct API Integration
For EHR systems with open APIs. Lowest latency, most control.
| EHR | Integration Status | Setup Time | Notes |
| ----------------- | ------------------ | ---------- | ------------------------- |
| PracticeQ | ✅ Live | 1-2 weeks | Direct API, bidirectional |
| Charma | ✅ Live | 1-2 weeks | Direct API, bidirectional |
| Custom / In-House | ✅ Supported | 2-4 weeks | Via HANA REST API |
**How it works:**
```
Your EHR API ←→ HANA Connector ←→ HANA Reasoning Engine
```
HANA maintains pre-built connectors for supported EHRs. For systems with standard REST/FHIR APIs, we build custom connectors during onboarding.
### 2. Integration Middleware (Redox, Keragon)
For EHR systems without open APIs, or when you need a standard interoperability layer. The breadth of EHR connectivity here comes from our middleware partners — Redox and Keragon maintain pre-built connections to hundreds of EHR systems, and HANA integrates through their platforms.
| Middleware | EHRs Supported | Setup Time | Notes |
| ---------- | -------------------------------------------- | ---------- | -------------------------------------------------- |
| Redox | Athena, Epic, Cerner, 200+ via Redox network | 2-4 weeks | HL7 FHIR, production-ready |
| Keragon | Multiple EU/US EHRs via Keragon platform | 2-4 weeks | Healthcare automation platform with EHR connectors |
**How it works:**
```
Your EHR ←→ Redox/Keragon ←→ HANA Connector ←→ HANA Reasoning Engine
```
Middleware platforms carry their own licensing costs. Redox typically charges a platform fee + per-connector fees. Keragon has its own pricing model. HANA works with your existing middleware subscription if you have one, or we can help you get set up.
### 3. HANA Dashboard (No EHR Required)
For organizations without an EHR, or with legacy systems that don't support integration.
HANA provides a lightweight clinical dashboard where care teams can:
* View patient engagement status and history
* Review clinical notes and tasks
* Manage agent configurations
* Export data as CSV or via API
```
HANA Dashboard (web) ←→ HANA Reasoning Engine ←→ Patient
```
This is the fastest path to deployment (typically 1 week) and is commonly used by:
* Small practices without modern EHR systems
* Pilot deployments before full EHR integration
* Platform partners building their own UI
***
## Data Flow Specification
### Inbound Data (EHR → HANA)
Data HANA reads from your system to inform the reasoning engine:
```json theme={null}
{
"patient": {
"id": "P-12345",
"demographics": {
"name": "Maria Garcia",
"age": 58,
"language": "en",
"timezone": "America/New_York"
},
"clinical": {
"diagnoses": [
{"code": "E11.9", "description": "Type 2 diabetes", "onset": "2020-03-15"}
],
"medications": [
{"name": "Metformin", "dose": "500mg", "frequency": "2x daily", "start": "2020-04-01"}
],
"allergies": ["penicillin"],
"vitals": {
"last_bp": "138/88",
"last_glucose": 142,
"recorded_at": "2026-01-28T09:00:00Z"
}
},
"care_plan": {
"active_goals": ["improve_medication_adherence", "reduce_hba1c"],
"upcoming_appointments": [
{"date": "2026-02-15", "provider": "Dr. Chen", "type": "follow_up"}
]
},
"engagement_history": {
"last_contact": "2026-02-01",
"preferred_channel": "voice",
"preferred_time": "morning"
}
}
}
```
### Outbound Data (HANA → EHR)
After each engagement, HANA writes back:
```json theme={null}
{
"engagement_id": "eng_abc123",
"patient_id": "P-12345",
"timestamp": "2026-02-08T10:08:30Z",
"clinical_note": {
"format": "fhir_document_reference",
"narrative": "Patient reports taking metformin approximately 4 of 7 days this week. Primary barrier identified as cost — recent insurance change increased copay. Mild nausea reported but considered tolerable by patient. No additional side effects. Mood and sleep stable. Recommended: review copay assistance programs.",
"structured": {
"medication_adherence": {
"metformin": {"reported_days": 4, "prescribed_days": 7, "rate": 0.57}
},
"barriers": [{"type": "cost", "detail": "Insurance copay increase"}],
"side_effects": [{"medication": "metformin", "effect": "mild_nausea", "severity": "low"}],
"mood": "stable",
"sdoh_flags": ["insurance_change"]
}
},
"tasks": [
{
"type": "review_medication_assistance",
"priority": "medium",
"assigned_to_role": "care_manager",
"reason": "Cost barrier to medication adherence"
}
],
"risk_level": "low",
"next_engagement": "2026-02-15T10:00:00Z"
}
```
***
## FHIR Support
HANA supports HL7 FHIR R4 for structured data exchange. Clinical notes are formatted as FHIR `DocumentReference` resources:
```json theme={null}
{
"resourceType": "DocumentReference",
"status": "current",
"type": {
"coding": [{
"system": "http://loinc.org",
"code": "11488-4",
"display": "Consult note"
}]
},
"subject": {
"reference": "Patient/P-12345"
},
"date": "2026-02-08T10:08:30Z",
"content": [{
"attachment": {
"contentType": "text/plain",
"data": "base64-encoded-clinical-note"
}
}]
}
```
FHIR resources supported for read/write:
* `Patient` — demographics, contact
* `Condition` — active diagnoses
* `MedicationStatement` — current medications
* `DocumentReference` — clinical notes (write-back)
* `Task` — clinical follow-up tasks
* `Flag` — risk alerts
***
## Integration Checklist
Use this checklist when planning your EHR integration:
What EHR does the organization use? Does it have an open API? Is Redox/Keragon already in use?
Which patient data fields should HANA read? What should HANA write back? Map the specific fields.
Set up API keys or OAuth credentials for the EHR connection. Define user/service account permissions.
Use HANA's sandbox environment with synthetic patient data. Verify read/write operations end-to-end.
Have clinical staff review sample write-back notes. Confirm escalation pathways trigger correctly.
Deploy to pilot cohort. Monitor data flow, note quality, and any integration errors for the first 2 weeks.
***
## Troubleshooting
| Issue | Likely Cause | Resolution |
| ------------------------------------- | ------------------------------- | ----------------------------------------------------------------- |
| Write-back notes not appearing in EHR | Incorrect document type mapping | Verify FHIR resource type matches your EHR's expected format |
| Patient data stale | Sync frequency too low | Configure real-time or near-real-time data polling |
| Connection timeout | EHR rate limits | Implement backoff; contact EHR vendor for rate limit increase |
| Missing medications in context | API permissions | Ensure HANA service account has read access to medication records |
Deploy HANA under your own brand with HANA Connect.
# EHR Proxy API
Source: https://docs.hana.health/developers/ehr-proxy-api
Complete API reference for HANA's EHR Proxy — a unified interface for patient, appointment, encounter, and clinical data operations across EHR systems.
## Overview
HANA's EHR Proxy provides a standardized REST API that abstracts the differences between EHR systems. Write once against HANA's API, and the Proxy handles translation to Epic, Cerner, Athena, AllScripts, or any FHIR-enabled system.
**Base URL:** `https://api.hana.health/v1`
**Authentication:** All requests require an `X-API-KEY` header and `X-ORG-ID` header.
```bash theme={null}
curl https://api.hana.health/v1/patients \
--header 'X-API-KEY: ' \
--header 'X-ORG-ID: '
```
***
## Patients
### List Patients
Retrieves a list of patients for a practitioner.
```
GET /v1/patients
```
**Parameters:**
| Name | In | Type | Required | Description |
| ------------------- | ------ | ------- | -------- | ------------------------------- |
| X-API-KEY | header | string | Yes | API key |
| X-ORG-ID | header | string | Yes | Organization ID |
| practitioner\_id | query | string | No | Filter by practitioner |
| practitioner\_email | query | string | No | Alternative practitioner lookup |
| count | query | integer | No | Results to return (default: 20) |
| include\_fhir | query | boolean | No | Include raw FHIR in response |
**Response (200):**
```json theme={null}
{
"status": "ok",
"data": [
{
"id": "pat_abc123",
"first_name": "Maria",
"last_name": "Garcia",
"date_of_birth": "1985-03-14",
"gender": "female",
"phone": "+1-555-0142",
"email": "maria.garcia@email.com",
"primary_provider_id": "prov_xyz789"
}
],
"count": 1,
"total": 1
}
```
### Create Patient
```
POST /v1/patients
```
**Request Body:**
```json theme={null}
{
"first_name": "string",
"last_name": "string",
"date_of_birth": "YYYY-MM-DD",
"gender": "male | female | other | unknown",
"email": "string",
"phone_numbers": ["string"],
"address": {
"street": "string",
"city": "string",
"state": "string",
"postal_code": "string",
"country": "string"
},
"practitioner_id": "string"
}
```
**Response (201):** Created patient object.
### Confirm Patient Identity
Validates if a patient exists. Requires either (first\_name + last\_name + date\_of\_birth) OR (phone\_number).
```
GET /v1/patients/exists
```
**Response (200):** Patient found with matching record.
**Response (404):** Patient not found.
***
## Patient Records
### Get Patient Record
Retrieves a comprehensive patient record.
```
GET /v1/patients/record
```
**Parameters:** Patient identified by (first\_name + last\_name + date\_of\_birth) OR (phone\_number).
**Response (200):**
```json theme={null}
{
"status": "ok",
"data": {
"demographics": { },
"conditions": [
{
"code": "I10",
"display": "Essential hypertension",
"status": "active",
"onset_date": "2020-06-15"
}
],
"medications": [
{
"name": "Lisinopril",
"dosage": "10mg",
"frequency": "daily",
"status": "active",
"prescriber": "Dr. Smith"
}
],
"allergies": [
{
"substance": "Penicillin",
"reaction": "rash",
"severity": "moderate"
}
],
"vital_signs": [ ],
"lab_results": [ ],
"encounter_notes": [ ],
"insurance": { }
}
}
```
### Get Vital Signs
```
GET /v1/patients/record/vital-signs
```
### Update Vital Signs
```
PUT /v1/patients/record/vital-signs
```
### Get Lab Results
```
GET /v1/patients/record/lab-results
```
### Get Medications
```
GET /v1/patients/record/medications
```
### Get Insurance
```
GET /v1/patients/record/insurance
```
### Update Insurance
```
PUT /v1/patients/record/insurance
```
***
## Practitioners
### List Practitioners
```
GET /v1/practitioners
```
**Parameters:**
| Name | In | Type | Required | Description |
| ------------- | ----- | ------- | -------- | ------------------------------- |
| count | query | integer | No | Results to return (default: 20) |
| include\_fhir | query | boolean | No | Include FHIR format |
**Response (200):**
```json theme={null}
{
"status": "ok",
"data": [
{
"id": "prov_xyz789",
"first_name": "Sarah",
"last_name": "Johnson",
"email": "sjohnson@clinic.com",
"specialty": "Family Medicine",
"npi": "1234567890",
"locations": ["loc_main", "loc_satellite"]
}
]
}
```
***
## Appointments
### List Appointments
```
GET /v1/appointments
```
**Parameters:**
| Name | In | Type | Required | Description |
| ------------------- | ----- | ------- | -------- | ------------------------- |
| start\_date\_time | query | string | Yes | Start of range (ISO 8601) |
| end\_date\_time | query | string | Yes | End of range (ISO 8601) |
| practitioner\_id | query | string | No | Filter by practitioner |
| patient identifiers | query | various | No | Filter by patient |
| count | query | integer | No | Results to return |
**Response (200):**
```json theme={null}
{
"status": "ok",
"data": [
{
"id": "appt_001",
"patient_id": "pat_abc123",
"practitioner_id": "prov_xyz789",
"start": "2026-02-10T09:00:00Z",
"end": "2026-02-10T09:30:00Z",
"status": "confirmed",
"type": "follow-up",
"reason": "Hypertension management"
}
]
}
```
### Book Appointment
```
POST /v1/appointments
```
**Request Body:**
```json theme={null}
{
"patient_id": "string",
"practitioner_id": "string",
"start_date_time": "ISO 8601",
"end_date_time": "ISO 8601",
"reason": "string",
"notes": "string"
}
```
### Reschedule Appointment
```
PUT /v1/appointments
```
**Request Body:**
```json theme={null}
{
"patient_id": "string",
"appointment_start_date_time": "ISO 8601 (original)",
"new_start_date_time": "ISO 8601",
"new_end_date_time": "ISO 8601",
"reason": "string"
}
```
### Cancel Appointment
```
DELETE /v1/appointments
```
### Get Open Slots
```
GET /v1/appointments/open-slots
```
**Parameters:**
| Name | In | Type | Required | Description |
| ----------------- | ----- | ------ | -------- | ---------------------- |
| start\_date\_time | query | string | Yes | Start of search window |
| end\_date\_time | query | string | No | End of search window |
| practitioner\_id | query | string | No | Filter by practitioner |
### Pre-Visit Notes
```
GET /v1/appointments/pre-visit/notes
PUT /v1/appointments/pre-visit/notes
```
***
## Encounters & Clinical Notes
### Get Encounter Notes
```
GET /v1/appointments/encounters/notes
```
Retrieves clinical notes for a given encounter or patient.
### Create Encounter Note
```
POST /v1/appointments/encounters/notes
```
**Request Body:**
```json theme={null}
{
"text_content": "string (markdown or plain text)",
"json_content": {
"subjective": "string",
"objective": "string",
"assessment": "string",
"plan": "string"
}
}
```
### Update Encounter Note
```
PUT /v1/appointments/encounters/notes
```
### Delete Encounter Note
```
DELETE /v1/appointments/encounters/notes
```
### SOAP Note Sections
Get or update individual SOAP sections:
```
GET /v1/appointments/encounters/notes/soap/sections/{section_id}
PUT /v1/appointments/encounters/notes/soap/sections/{section_id}
```
### Add Chief Complaints
```
POST /v1/appointments/encounters/notes/chief-complaints
```
**Request Body:** `["string"]`
### Add Intake Questionnaire
```
POST /v1/appointments/encounters/notes/intake-questionnaire
```
***
## Clinical Codes
### Add ICD-10 Codes
```
POST /v1/appointments/encounters/notes/codes/icd10
```
**Request Body:** `["I10", "E11.9", "F32.1"]`
### Add CPT Codes
```
POST /v1/appointments/encounters/notes/codes/cpt
```
**Request Body:** `["99213", "99490", "96127"]`
***
## Medications & Patient Instructions
### Add Medications
```
POST /v1/appointments/encounters/notes/medications
```
**Request Body:** `["Lisinopril 10mg daily", "Metformin 500mg BID"]`
### Add Patient Instructions
```
POST /v1/appointments/encounters/notes/patient-instructions
```
**Request Body:** `["Schedule follow-up in 2 weeks", "Monitor blood pressure daily"]`
***
## Conversations
### Create Conversation
Initiate an AI-driven patient conversation.
```
POST /v1/conversations
```
**Request Body:**
```json theme={null}
{
"patient_id": "string",
"protocol": "intake | follow_up | ccm_checkin | bhi_screen | care_gap | custom",
"protocol_config": {
"custom_protocol_id": "string (if protocol=custom)"
},
"channel": "voice_outbound | voice_inbound | sms",
"scheduled_at": "ISO 8601 (optional, for scheduled outbound)",
"priority": "normal | high | urgent",
"metadata": {}
}
```
**Response (201):**
```json theme={null}
{
"status": "ok",
"data": {
"conversation_id": "conv_abc123",
"status": "scheduled",
"scheduled_at": "2026-02-10T14:00:00Z",
"patient_id": "pat_abc123",
"protocol": "ccm_checkin"
}
}
```
### Get Conversation
```
GET /v1/conversations/{conversationId}
```
**Response (200):**
```json theme={null}
{
"status": "ok",
"data": {
"id": "conv_abc123",
"status": "completed",
"patient_id": "pat_abc123",
"protocol": "ccm_checkin",
"started_at": "2026-02-10T14:00:12Z",
"completed_at": "2026-02-10T14:07:45Z",
"duration_seconds": 453,
"outcome": {
"goals_completed": 4,
"goals_total": 5,
"escalated": false,
"quality_score": 4.5,
"extracted_data": { }
},
"transcript_url": "https://api.hana.health/v1/conversations/conv_abc123/transcript"
}
}
```
### List Conversations
```
GET /v1/conversations
```
**Parameters:** Filter by patient, protocol, status, date range.
### Get Transcript
```
GET /v1/conversations/{conversationId}/transcript
```
***
## Metadata
### List Protocols
```
GET /v1/protocols
```
### List Note Templates
```
GET /v1/appointments/encounters/notes/templates
```
### List Note Fields
```
GET /v1/appointments/encounters/notes/fields
```
***
## Monitoring
### Health Check
```
GET /v1/health
```
### EHR Connection Health
```
GET /v1/ehr/health
```
**Response (200):**
```json theme={null}
{
"status": "connected",
"ehr_system": "Epic",
"last_sync": "2026-02-07T13:45:00Z",
"latency_ms": 145
}
```
***
## Error Handling
All errors follow a consistent format:
```json theme={null}
{
"status": "error",
"error": {
"code": "PATIENT_NOT_FOUND",
"message": "No patient found matching the provided identifiers.",
"details": {}
}
}
```
**Common Error Codes:**
| Code | HTTP Status | Description |
| ----------------------- | ----------- | ---------------------------------- |
| UNAUTHORIZED | 401 | Invalid or missing API key |
| FORBIDDEN | 403 | Insufficient permissions |
| PATIENT\_NOT\_FOUND | 404 | No matching patient |
| APPOINTMENT\_NOT\_FOUND | 404 | No matching appointment |
| INVALID\_INPUT | 400 | Malformed request |
| EHR\_UNAVAILABLE | 503 | EHR system temporarily unreachable |
| RATE\_LIMITED | 429 | Too many requests |
## Rate Limits
| Tier | Requests/minute | Burst |
| ---------- | --------------- | ----- |
| Standard | 60 | 100 |
| Scale | 300 | 500 |
| Enterprise | 1,000 | 2,000 |
# SDK Reference
Source: https://docs.hana.health/developers/sdk
Full reference for the HANA Node.js and Python SDKs. Typed, async, and built for healthcare workflows.
## Installation
```bash npm theme={null}
npm install @hana-health/sdk
```
```bash yarn theme={null}
yarn add @hana-health/sdk
```
```bash pip theme={null}
pip install hana-health
```
***
## Client Initialization
```javascript Node.js theme={null}
import { HanaClient } from '@hana-health/sdk';
const hana = new HanaClient({
apiKey: process.env.HANA_API_KEY, // Required
environment: 'production', // 'production' | 'sandbox'
region: 'eu', // 'us' | 'eu' | 'uk'
mode: 'direct', // 'direct' | 'connect'
timeout: 30000, // Request timeout (ms)
retries: 3 // Auto-retry on transient failures
});
```
```python Python theme={null}
from hana_health import HanaClient
hana = HanaClient(
api_key=os.environ["HANA_API_KEY"],
environment="production",
region="eu",
mode="direct",
timeout=30,
retries=3
)
```
| Parameter | Type | Default | Description |
| ------------- | ------ | -------------- | --------------------------------------------------------- |
| `apiKey` | string | — | Your API key (required) |
| `environment` | string | `'production'` | `'production'` or `'sandbox'` |
| `region` | string | `'us'` | `'us'`, `'eu'`, `'uk'` |
| `mode` | string | `'direct'` | `'direct'` for clinics, `'connect'` for platform partners |
| `timeout` | number | 30000 | Request timeout in ms (Node) or seconds (Python) |
| `retries` | number | 3 | Auto-retry count on 5xx/timeout |
***
## Engagements
### `hana.engagements.create(params)`
Create a new patient engagement.
```javascript Node.js theme={null}
const engagement = await hana.engagements.create({
patient: {
id: 'P-12345',
phone: '+15550123456',
preferredChannel: 'voice',
language: 'en'
},
protocol: 'medication-adherence-diabetes',
triggerType: 'scheduled',
scheduledAt: '2026-02-08T10:00:00Z',
context: {
ehrData: {
diagnoses: [{ code: 'E11.9', description: 'Type 2 diabetes' }],
medications: [{ name: 'Metformin', dose: '500mg', frequency: '2x daily' }]
}
},
callbackUrl: 'https://your-app.com/webhooks/hana',
whiteLabel: { // Optional (Connect mode)
callerName: 'Your Health Platform',
callerId: '+18005551234'
}
});
// engagement.id → "eng_abc123"
// engagement.status → "scheduled"
```
```python Python theme={null}
engagement = hana.engagements.create(
patient={
"id": "P-12345",
"phone": "+15550123456",
"preferred_channel": "voice",
"language": "en"
},
protocol="medication-adherence-diabetes",
trigger_type="scheduled",
scheduled_at="2026-02-08T10:00:00Z",
context={
"ehr_data": {
"diagnoses": [{"code": "E11.9", "description": "Type 2 diabetes"}],
"medications": [{"name": "Metformin", "dose": "500mg", "frequency": "2x daily"}]
}
},
callback_url="https://your-app.com/webhooks/hana"
)
```
**Returns:** `Engagement` object with `id`, `status`, `patient_id`, `scheduled_at`, `created_at`.
### `hana.engagements.get(id)`
Retrieve an engagement by ID, including outcomes if completed.
```javascript Node.js theme={null}
const result = await hana.engagements.get('eng_abc123');
console.log(result.status); // "completed"
console.log(result.outcome.clinical_note); // Structured clinical note
console.log(result.outcome.tasks); // Array of clinical tasks
console.log(result.outcome.risk_level); // "low" | "medium" | "high" | "critical"
console.log(result.outcome.metrics); // engagement_score, completion_rate, etc.
```
```python Python theme={null}
result = hana.engagements.get("eng_abc123")
print(result.status)
print(result.outcome.clinical_note)
print(result.outcome.tasks)
print(result.outcome.risk_level)
```
### `hana.engagements.list(filters)`
List engagements with filtering and pagination.
```javascript Node.js theme={null}
const page = await hana.engagements.list({
patientId: 'P-12345',
status: 'completed',
from: '2026-01-01',
to: '2026-02-07',
limit: 20
});
for (const eng of page.data) {
console.log(eng.id, eng.status, eng.completed_at);
}
// Paginate
if (page.hasMore) {
const nextPage = await hana.engagements.list({
...filters,
cursor: page.cursor
});
}
```
```python Python theme={null}
page = hana.engagements.list(
patient_id="P-12345",
status="completed",
from_date="2026-01-01",
to_date="2026-02-07",
limit=20
)
for eng in page.data:
print(eng.id, eng.status, eng.completed_at)
```
### `hana.engagements.cancel(id)`
Cancel a scheduled engagement before it starts.
```javascript theme={null}
await hana.engagements.cancel('eng_abc123');
```
***
## Patients
### `hana.patients.upsert(id, data)`
Create or update a patient record. Upsert by your internal patient ID.
```javascript Node.js theme={null}
await hana.patients.upsert('P-12345', {
firstName: 'Maria',
lastName: 'Garcia',
phone: '+15550123456',
preferredChannel: 'voice',
preferredLanguage: 'en',
timezone: 'America/New_York',
clinicalData: {
diagnoses: [{ code: 'E11.9', description: 'Type 2 diabetes' }],
medications: [{ name: 'Metformin', dose: '500mg', frequency: '2x daily' }]
},
tags: ['chronic_care', 'medication_monitoring']
});
```
```python Python theme={null}
hana.patients.upsert("P-12345", {
"first_name": "Maria",
"last_name": "Garcia",
"phone": "+15550123456",
"preferred_channel": "voice",
"preferred_language": "en",
"timezone": "America/New_York",
"clinical_data": {
"diagnoses": [{"code": "E11.9", "description": "Type 2 diabetes"}],
"medications": [{"name": "Metformin", "dose": "500mg", "frequency": "2x daily"}]
},
"tags": ["chronic_care", "medication_monitoring"]
})
```
### `hana.patients.get(id)`
Retrieve a patient record.
### `hana.patients.getMemory(id)`
Retrieve the longitudinal engagement memory for a patient — preferences, trends, barriers, interaction patterns.
```javascript theme={null}
const memory = await hana.patients.getMemory('P-12345');
console.log(memory.preferences.bestContactTime); // "morning"
console.log(memory.preferences.communicationStyle); // "warm_conversational"
console.log(memory.longitudinalTrends.medicationAdherence); // [0.4, 0.5, 0.6, 0.7]
console.log(memory.activeBarriers); // [{ type: "cost", ... }]
```
### `hana.patients.delete(id, options)`
Delete a patient and optionally erase all data (GDPR right to erasure):
```javascript theme={null}
await hana.patients.delete('P-12345', { erase: true });
```
***
## Protocols
### `hana.protocols.create(config)`
Create a custom clinical protocol:
```javascript theme={null}
const protocol = await hana.protocols.create({
name: 'post-surgery-day3',
description: 'Day 3 post-surgery recovery check',
objective: 'Assess pain, medication compliance, wound status, mobility',
frequency: 'one_time',
channels: ['voice', 'sms'],
questions: [
{
id: 'pain',
topic: 'pain_assessment',
prompt: 'How would you rate your pain on a scale of 1 to 10?',
responseType: 'numeric',
escalationThreshold: 8
},
{
id: 'medication',
topic: 'medication_adherence',
prompt: 'Have you been able to take your pain medication as prescribed?',
responseType: 'boolean',
followUpIfFalse: "What's been preventing you from taking it?"
}
],
escalationPolicy: 'clinic-post-surgical'
});
```
### `hana.protocols.list()`
List all protocols for your organization.
### `hana.protocols.upload(file)`
Upload a clinical guideline (PDF, DOCX) for HANA to parse into a structured protocol:
```javascript theme={null}
const protocol = await hana.protocols.upload({
file: fs.readFileSync('./guidelines/palliative-care-protocol.pdf'),
fileName: 'palliative-care-protocol.pdf',
parseInstructions: 'Extract assessment questions, escalation criteria, and frequency guidelines'
});
```
***
## Webhooks
### `hana.webhooks.create(config)`
Register a webhook endpoint:
```javascript theme={null}
const webhook = await hana.webhooks.create({
url: 'https://your-app.com/webhooks/hana',
events: ['engagement.completed', 'engagement.escalated', 'clinical_note.ready'],
secret: process.env.HANA_WEBHOOK_SECRET
});
```
### `hana.webhooks.list()`
List registered webhooks.
### `hana.webhooks.test(id)`
Send a test event to verify connectivity.
### `hana.webhooks.replay(id, eventIds)`
Replay failed webhook deliveries.
***
## Organizations (Connect Mode)
Available when `mode: 'connect'`.
### `hana.organizations.create(config)`
Create a sub-organization (for multi-tenant deployments):
```javascript theme={null}
const org = await hana.organizations.create({
name: 'Sunrise Family Practice',
config: {
protocols: ['medication-adherence', 'post-visit-followup'],
timezone: 'America/Chicago',
language: 'en'
},
whiteLabel: {
callerName: 'Sunrise Family Practice',
callerId: '+18005552222'
}
});
```
### `hana.organizations.list()`
List all sub-organizations under your platform.
***
## Error Handling
All SDK methods throw typed errors:
```javascript Node.js theme={null}
import { HanaError, RateLimitError, ValidationError } from '@hana-health/sdk';
try {
await hana.engagements.create({ ... });
} catch (err) {
if (err instanceof RateLimitError) {
console.log(`Rate limited. Retry after ${err.retryAfter}s`);
} else if (err instanceof ValidationError) {
console.log(`Invalid field: ${err.field} — ${err.message}`);
} else if (err instanceof HanaError) {
console.log(`API error: ${err.code} — ${err.message}`);
}
}
```
```python Python theme={null}
from hana_health.errors import HanaError, RateLimitError, ValidationError
try:
hana.engagements.create(...)
except RateLimitError as e:
print(f"Rate limited. Retry after {e.retry_after}s")
except ValidationError as e:
print(f"Invalid field: {e.field} — {e.message}")
except HanaError as e:
print(f"API error: {e.code} — {e.message}")
```
***
## TypeScript Support
The Node.js SDK is fully typed. All request params and response objects have TypeScript definitions:
```typescript theme={null}
import { HanaClient, Engagement, Patient, Protocol } from '@hana-health/sdk';
const engagement: Engagement = await hana.engagements.get('eng_abc123');
const note: string = engagement.outcome.clinical_note.summary;
const tasks: Task[] = engagement.outcome.tasks;
```
Full REST API documentation for direct HTTP integration.
# Webhooks
Source: https://docs.hana.health/developers/webhooks
Receive real-time events from HANA — engagement outcomes, escalations, patient updates, and system status.
## Overview
Webhooks are how HANA pushes data to your system in real time. When a patient interaction completes, a risk flag is detected, or a clinical note is generated, HANA sends an HTTP POST to your configured endpoint.
This is the primary mechanism for the "closed loop" — HANA engages the patient, then sends structured results back to your EHR, care platform, or internal system.
***
## Event Types
### Engagement Events
| Event | Fired When | Typical Use |
| ---------------------- | ------------------------------------------- | -------------------------------- |
| `engagement.scheduled` | Engagement queued for future delivery | Update your scheduling UI |
| `engagement.started` | Patient answered (voice) or responded (SMS) | Log interaction start |
| `engagement.completed` | Full interaction finished | Ingest clinical note, update EHR |
| `engagement.failed` | Could not reach patient after retries | Trigger manual follow-up |
| `engagement.cancelled` | Engagement cancelled via API | Clean up internal records |
### Clinical Events
| Event | Fired When | Typical Use |
| ------------------------- | ---------------------------------------- | --------------------------- |
| `engagement.escalated` | Risk signal detected during conversation | Alert care team immediately |
| `engagement.task_created` | Clinical task generated from interaction | Route to task queue |
| `clinical_note.ready` | Structured clinical note finalized | Write to EHR |
### Patient Events
| Event | Fired When | Typical Use |
| -------------------------- | --------------------------------------- | ------------------------- |
| `patient.memory_updated` | Patient preferences or patterns learned | Sync longitudinal profile |
| `patient.barrier_detected` | New adherence barrier identified | Update care plan |
| `patient.trend_change` | Significant change in tracked metric | Notify provider |
### System Events
| Event | Fired When | Typical Use |
| ----------------- | ----------------------------- | --------------------- |
| `system.health` | Periodic health check | Monitoring dashboards |
| `batch.completed` | Batch engagement job finished | Process bulk results |
***
## Payload Structure
Every webhook payload follows a consistent envelope:
```json theme={null}
{
"id": "evt_abc123",
"event": "engagement.completed",
"timestamp": "2026-02-08T10:08:30Z",
"api_version": "2026-01-01",
"data": {
// Event-specific payload
}
}
```
### `engagement.completed` Payload
The most common event. Contains the full output of a patient interaction:
```json theme={null}
{
"id": "evt_abc123",
"event": "engagement.completed",
"timestamp": "2026-02-08T10:08:30Z",
"api_version": "2026-01-01",
"data": {
"engagement_id": "eng_abc123",
"patient_id": "P-12345",
"protocol": "medication-adherence-diabetes",
"channel": "voice",
"duration_seconds": 390,
"clinical_note": {
"summary": "Patient reports taking metformin ~4/7 days this week. Primary barrier is cost — insurance changed and copay increased. Reports mild nausea but considers it tolerable. No other side effects. Mood stable, sleep adequate.",
"structured_data": {
"medication_adherence": 0.57,
"barriers": ["cost"],
"side_effects": ["mild_nausea"],
"mood": "stable",
"sdoh_flags": ["insurance_change"]
}
},
"tasks": [
{
"id": "task_xyz",
"type": "review_medication_assistance",
"priority": "medium",
"reason": "Patient reports cost barrier to adherence due to insurance change",
"suggested_action": "Review copay assistance programs or generic alternatives"
}
],
"risk_flags": [],
"risk_level": "low",
"metrics": {
"engagement_score": 0.92,
"completion_rate": 1.0,
"interaction_count": 8,
"sentiment": "neutral_positive"
},
"transcript_url": "https://api.hana.health/v1/engagements/eng_abc123/transcript"
}
}
```
### `engagement.escalated` Payload
Sent immediately when a risk signal is detected. This is the highest-priority event:
```json theme={null}
{
"id": "evt_esc456",
"event": "engagement.escalated",
"timestamp": "2026-02-08T10:05:12Z",
"api_version": "2026-01-01",
"data": {
"engagement_id": "eng_abc123",
"patient_id": "P-12345",
"escalation_type": "clinical_risk",
"severity": "high",
"reason": "Patient expressed passive suicidal ideation during medication discussion",
"action_taken": "AI conversation paused. Patient informed of crisis resources.",
"requires_human_review": true,
"contact_info": {
"phone": "+15550123456",
"last_channel": "voice"
}
}
}
```
**Escalation events should trigger immediate action in your system.** Configure alerts, page on-call staff, or route to a human operator. HANA pauses the AI conversation and follows the clinic's defined escalation protocol, but your system must acknowledge and act.
***
## Configuring Webhooks
### Via API
```bash theme={null}
POST /v1/webhooks
```
```json theme={null}
{
"url": "https://your-app.com/webhooks/hana",
"events": [
"engagement.completed",
"engagement.escalated",
"clinical_note.ready"
],
"secret": "whsec_your_secret_here"
}
```
### Via SDK
```javascript Node.js theme={null}
await hana.webhooks.create({
url: 'https://your-app.com/webhooks/hana',
events: ['engagement.completed', 'engagement.escalated'],
secret: process.env.HANA_WEBHOOK_SECRET
});
```
```python Python theme={null}
hana.webhooks.create(
url="https://your-app.com/webhooks/hana",
events=["engagement.completed", "engagement.escalated"],
secret=os.environ["HANA_WEBHOOK_SECRET"]
)
```
### Filtering Events
Subscribe only to the events you need. Less noise, fewer wasted requests:
```json theme={null}
{
"url": "https://your-ehr.com/hana-notes",
"events": ["clinical_note.ready"],
"filters": {
"protocol": ["medication-adherence-*", "intake-*"],
"risk_level": ["medium", "high", "critical"]
}
}
```
***
## Delivery & Retry
HANA guarantees at-least-once delivery for all webhook events.
### Retry Schedule
If your endpoint returns a non-2xx status code or times out (30 seconds), HANA retries with exponential backoff:
| Attempt | Delay |
| --------- | ---------- |
| 1st retry | 30 seconds |
| 2nd retry | 2 minutes |
| 3rd retry | 10 minutes |
| 4th retry | 1 hour |
| 5th retry | 4 hours |
After 5 failed attempts, the event is moved to the dead letter queue. You can replay failed events via the API:
```bash theme={null}
POST /v1/webhooks/{webhook_id}/replay
```
```json theme={null}
{
"event_ids": ["evt_abc123", "evt_def456"]
}
```
### Idempotency
Every event has a unique `id`. Your system should deduplicate based on this ID, since retries may deliver the same event more than once.
```javascript theme={null}
// Example: Check if event was already processed
const processed = await db.webhookEvents.findOne({ eventId: event.id });
if (processed) return res.status(200).send('already processed');
```
***
## Testing Webhooks
### Sandbox Events
In sandbox mode, all engagements produce simulated webhook events. Test your integration end-to-end without real patient calls:
```javascript theme={null}
const hana = new HanaClient({
apiKey: process.env.HANA_API_KEY,
environment: 'sandbox'
});
// This triggers a simulated engagement + webhook delivery
const engagement = await hana.engagements.create({
patient: { id: 'TEST-001', phone: '+15550000000' },
protocol: 'medication-adherence-diabetes',
triggerType: 'immediate'
});
```
### Manual Event Trigger
Send a test event to your endpoint:
```bash theme={null}
POST /v1/webhooks/{webhook_id}/test
```
```json theme={null}
{
"event": "engagement.completed"
}
```
This sends a synthetic payload to your URL so you can verify connectivity, parsing, and signature verification.
Connect HANA to your Electronic Health Record system.
# Enterprise Guide
Source: https://docs.hana.health/enterprise/enterprise-guide
Platform overview, core features, and getting started guide for enterprise healthcare organizations.
## Platform Overview
HANA is an enterprise voice AI platform for healthcare patient engagement. The platform provides:
* **Voice-Based Patient Agents**: Autonomous AI agents that conduct clinical conversations with patients via phone and SMS
* **EHR Integration**: Bi-directional data exchange with Epic, Cerner, Athena, and other major EHR systems via FHIR R4
* **Clinical Protocol Engine**: Configurable conversation workflows for intake, screening, follow-up, and care coordination
* **Quality Assurance**: Automated conversation evaluation with LLM-as-judge and clinical team review
* **Analytics & Reporting**: Real-time dashboards for conversation outcomes, quality metrics, and ROI tracking
## Core Features
### For Clinical Teams
* Pre-configured protocols for 20+ specialties
* Validated assessment instrument administration (PHQ-9, GAD-7, AUDIT-C, etc.)
* Automated clinical note generation and EHR write-back
* Escalation queue with full conversation context for flagged interactions
### For Operations
* Automated patient outreach at scale (scheduling, reminders, follow-up, care gaps)
* CMS billing code capture for BHI/CCM qualifying conversations
* Staff time reduction through automated engagement workflows
* Real-time visibility into patient engagement metrics
### For IT & Security
* SOC 2 Type II, HIPAA, GDPR compliance
* SSO integration (SAML/OIDC) with enterprise identity providers
* Multi-tenant architecture with data isolation
* On-premises deployment option for data residency requirements
## Getting Started
1. **Discovery Call**: 30-minute call to understand your workflows, EHR system, and priority use cases
2. **Pilot Scope**: Select 1-2 protocols for initial deployment
3. **Integration**: Connect HANA to your EHR (3-5 days for standard EHR systems)
4. **Configuration**: Customize protocols, voice persona, and escalation rules
5. **Validation**: Test conversations with clinical team review
6. **Go-Live**: Phased rollout starting with 10-20% of eligible patients
7. **Optimization**: Continuous quality improvement based on production data
Total time to first live conversation: typically 18-25 days.
## Support
| Level | Response Time | Channels |
| ---------- | --------------------- | ------------------------------- |
| Standard | 4 business hours | Email, portal |
| Priority | 1 business hour | Email, portal, phone |
| Enterprise | 30 minutes (critical) | Dedicated Slack, phone, on-call |
# Clinical Safety Architecture
Source: https://docs.hana.health/getting-started/clinical-safety-architecture
Ensuring patient safety through calibrated confidence, hallucination reduction, and rigorous training data controls in voice-based clinical AI.
## Ensuring Safety
Ensuring patient safety is paramount in deploying voice-based clinical AI. Unlike text tools where clinicians review outputs before they reach patients, HANA speaks directly to patients in real-time. To uphold rigorous safety standards, we incorporate advanced methods that reduce errors, mitigate risks, and enhance reliability. Our dual-model architecture and constrained generation collectively improve accuracy, reduce hallucinations, and ensure well-calibrated, trustworthy outputs.
## Improved Calibration
Calibrated confidence refers to the alignment between the system's predicted confidence scores and its actual observed accuracy. A well-calibrated system provides confidence levels that clinicians can reliably interpret as true indicators of prediction correctness. Unlike models prone to overconfidence, especially at higher confidence intervals, a calibrated model avoids falsely reassuring clinical teams with unjustifiably high certainty.
Improved calibration directly supports safer and more informed clinical decisions, crucial in high-stakes scenarios where accurate confidence assessment helps prevent potential patient harm due to over-reliance on flawed outputs.
### How HANA Achieves Calibration
**Pre-Call Reasoning Engine:**
* Generates clinical question sets with associated confidence weights per question
* Each question tagged with expected information yield score
* Protocol branching decisions carry explicit confidence thresholds
* If confidence falls below threshold, system escalates to human review rather than guessing
**Real-Time Conversation Engine:**
* Monitors response quality against pre-computed expectations
* Tracks semantic alignment between patient responses and expected clinical patterns
* Flags unexpected responses for post-call clinical review
* Never improvises clinical guidance — falls back to approved protocol language
### Confidence Scoring
Scoring Dimensions:
* **Semantic Match (0.0–1.0)**: Does the patient response match the expected clinical entity?
* **Completeness (0.0–1.0)**: Did the patient provide all required information?
* **Consistency (0.0–1.0)**: Does the response contradict prior answers?
Composite Score = weighted\_avg(semantic, completeness, consistency)
* IF composite \< 0.7 → Re-ask with clarification
* IF composite \< 0.4 → Flag for human follow-up
* IF composite \< 0.2 → Graceful handoff to staff
### Calibration Validation
HANA validates calibration through continuous production monitoring:
* **Binned accuracy analysis**: Group predictions by confidence level and measure actual accuracy per bin
* **Expected Calibration Error (ECE)**: Track weighted average gap between predicted confidence and observed accuracy
* **Per-protocol calibration**: Each clinical protocol maintains its own calibration curve, updated with every completed conversation
* **Drift detection**: Automated alerts when calibration degrades beyond acceptable thresholds
## Reducing Hallucinations
By constraining the conversation engine to pre-approved response templates and grounding all entity references in verified data sources, HANA minimizes individual model biases and substantially reduces hallucinations.
### Anti-Hallucination Architecture
```mermaid theme={null}
graph TB
INPUT["Patient Conversation"] --> L1
subgraph Stack["Safety Stack"]
direction TB
L1["Layer 1: Protocol Constraints\nApproved questions only · No freeform advice"]
L2["Layer 2: Entity Grounding\nEHR validation · Drug DB · SNOMED/ICD-10"]
L3["Layer 3: Output Validation\nSemantic check · Post-utterance verification"]
L4["Layer 4: Human Oversight\nFull logging · 24h flagged review"]
L1 --> L2 --> L3 --> L4
end
subgraph Agents["Observational Safety Agents (Rule-Based)"]
DS["Direct Signals\nSelf-harm · Crisis · Medication misuse"]
AS["Associative Signals\nCompound risk patterns"]
VCF["Vocal + Content Fusion\nText-prosody discrepancy"]
end
DS --> ESC["Escalation Protocol"]
AS --> ESC
VCF --> ESC
Agents -.->|Parallel Monitoring| Stack
```
**Layer 1: Protocol Constraints**
* Only approved questions can be asked
* Only protocol-defined branches can be taken
* No freeform clinical advice generation
**Layer 2: Entity Grounding**
* All patient references grounded in EHR data
* Medication names validated against drug database
* Clinical terms mapped to SNOMED CT / ICD-10 ontologies
**Layer 3: Output Validation**
* Real-time semantic check against protocol
* Post-utterance verification before voice delivery
* Automated flagging of ungrounded statements
**Layer 4: Human Oversight**
* All conversations logged and auditable
* Flagged conversations reviewed within 24 hours
* Protocol updates triggered by error patterns
### Hallucination Monitoring
Metrics below are measured continuously across production conversations and updated as conversation volume grows. Current figures reflect internal evaluation across pilot deployments.
| Metric | Target | Observed |
| ------------------------------- | ------- | -------- |
| Ungrounded clinical entity rate | \< 0.1% | 0.03% |
| Protocol deviation rate | \< 0.5% | 0.2% |
| Patient-reported misinformation | 0 | 0 |
| Automated safety flag rate | \< 2% | 1.1% |
These metrics are derived from automated evaluation pipelines (LLM-as-judge + rule-based validation) and clinical team review of flagged conversations. Methodology and sample details available upon request.
## Observational Safety Agents
Beyond the conversation engine's built-in safety constraints, HANA deploys independent observational agents that monitor every conversation in parallel. These agents are architecturally separate from the conversation engine — they observe but do not generate responses — providing an independent safety layer.
### Why Rule-Based, Not LLM-Based
A critical design decision: HANA's observational safety agents are **rule-based, not LLM-powered**. This is intentional:
* **Full traceability**: Every risk flag traces back to the exact words, phrases, or patterns that triggered it. No black-box reasoning in safety-critical decisions.
* **Deterministic behavior**: Given the same input, the safety agent always produces the same output. No stochastic variation in risk detection.
* **Auditability**: Clinicians and compliance teams can inspect exactly why a conversation was flagged, what threshold was triggered, and what protocol was activated.
* **Regulatory defensibility**: In clinical safety, you need to explain *why* a decision was made. Rule-based systems provide this by construction.
### Risk Detection Architecture
**Direct Signal Detection:**
* Explicit self-harm language, suicidal ideation expressions, and crisis indicators
* Medication misuse signals (e.g., "I took too many pills")
* Acute distress indicators requiring immediate clinical intervention
**Associative Signal Detection:**
* Compound signals that individually seem benign but together indicate risk — for example, expressions of hopelessness combined with questions about methods or locations that suggest harmful intent
* Context-dependent risk patterns developed from clinical literature and clinical team collaboration
* These associative rules were developed over months of work with behavioral health clinicians across diverse patient populations
**Vocal + Content Fusion:**
* When vocal intelligence detects prosodic stress markers and the rule-based agent detects risk-adjacent language, the combined signal is escalated even if neither alone would trigger
* Text-prosody discrepancy (patient says "I'm fine" with flat affect and vocal tremor) generates a clinical review flag
### Escalation Protocols
Each healthcare organization configures escalation protocols during onboarding:
* **24/7 clinical coverage**: If the organization has round-the-clock staff, the agent can initiate a warm transfer to a clinician
* **Emergency services**: For organizations without 24/7 coverage, the agent follows a defined protocol — acknowledges its limitations, provides emergency contact information, and notifies the clinical team
* **Clinical team notification**: All risk flags generate structured notifications with the triggering signals, conversation context, and patient information
HANA's safety agents are guardrails, not clinical tools. They detect risk signals and activate clinic-defined protocols. They do not provide clinical assessment, diagnosis, or therapeutic intervention. The clinical response is always the responsibility of the healthcare organization's care team.
***
## Training Data Safety
To further ensure the safety and compliance of our clinical AI systems, we apply rigorous controls to the data used in training and evaluation.
### Data De-identification
* All real-world clinical data undergoes thorough de-identification, removing or obfuscating PII and PHI in accordance with HIPAA Safe Harbor and Expert Determination standards
* Re-identification risk assessment performed on each de-identified dataset
* Every de-identification operation logged with timestamp, method, and verification status
### Synthetic Data Generation
* Expert-designed clinical conversation templates covering common and edge-case scenarios
* Demographic diversity across age, gender, language, and cultural backgrounds to reduce model bias
* Complexity gradients from simple appointment confirmations to complex multi-condition medication reviews
* Adversarial examples with deliberately ambiguous patient responses for robust edge-case handling
### Scenario Coverage Without Risk
* By blending de-identified data with synthetic examples, we ensure high scenario diversity while eliminating risks of privacy breaches or data leakage
* Training data distributions monitored for demographic, geographic, and clinical condition balance
* All training data practices audited against HIPAA, GDPR, and SOC 2 Type II requirements
# HANA Overview
Source: https://docs.hana.health/getting-started/overview
A concise overview of HANA's agentic system design and infrastructure, providing a high-level understanding of the system architecture and technology underlying HANA's healthcare voice agents.
## Welcome
HANA is a platform that empowers healthcare organizations to deploy voice-based patient engagement agents. These agents automate outbound and inbound patient conversations, streamline clinical data collection, and improve care coordination — all while maintaining the highest standards of clinical safety, security, and reliability.
Built from clinical voice research in behavioral health populations and refined across nearly one million patient interactions, HANA's architecture is designed for the specific challenges of healthcare: safety-critical conversations, longitudinal patient relationships, and integration with clinical workflows.
### Clinical Domains
HANA has been deployed and validated across diverse clinical settings:
* **Behavioral Health**: Bipolar disorder, PTSD, depression, ADHD — including longitudinal monitoring and crisis detection
* **Primary Care**: Chronic care management, medication adherence, preventive screening outreach
* **Surgical / Specialty Care**: Pre-operative preparation, post-operative follow-up, recovery milestone tracking
* **Palliative Care**: End-of-life care coordination, symptom monitoring, caregiver support
* **Multi-Specialty Clinics**: Dermatology, orthopedics, physical rehabilitation, psychotherapy
### ROI-First Approach
1. Provide an alternative to manual patient outreach at a fraction of the staff cost per engagement
2. Success metrics include: patient completion rates, recovered appointments, accurate clinical data extraction, and CMS-billable conversation documentation
3. Validated across pilot deployments; organizations can measure ROI against their own baseline during pilot phase
### Safe, Reliable, and Certain
1. Our team includes experienced healthcare operators who have managed clinical workflows across behavioral health, primary care, and multi-specialty organizations
2. Our technology provides seamless integration with existing EHR systems, enabling smooth adaptation to clinical workflows
3. Unlike text-based engagement tools, HANA offers voice-first patient interaction with high completion rates and minimal staff burden
4. Rule-based safety guardrails with full traceability — not black-box LLM safety — ensure deterministic risk detection and auditable escalation
### Highly Modular & Customizable
1. Tailor solutions to fit the unique needs of your organization with our highly modular agent system
2. Customize protocols, voice personas, and clinical workflows to match existing processes
3. Easily scale and modify agents to adapt to changing requirements and growth
***
## System Card
**Scalable Architecture for Voice-Based Healthcare Agents**
### Design Principles
* **Isolated**: Each agent operates independently with its own protocol configuration and data context
* **Self-contained**: Agents include all necessary components for end-to-end conversation execution
* **Composable**: Agents can be combined for complex workflows (e.g., intake → screening → scheduling)
* **Customizable**: Every aspect of agent behavior is configurable per organization, specialty, and patient
### High-Level Architecture
```mermaid theme={null}
graph TB
subgraph Shared["Shared Services"]
AUTH["Authentication (SAML/OIDC)"]
TEL["Telephony (SIP Trunking)"]
EHRG["EHR Gateway (FHIR R4)"]
QUEUE["Queue System"]
EVALPIPE["Evaluation Pipeline"]
OBSRV["Observability"]
end
subgraph Agent["Agent Package"]
PROTO["Protocol Configuration"]
RE["Reasoning Engine\n(GPU · Pre-Call Planning)"]
CE["Conversation Engine\n(CPU · Real-Time)"]
EHRC["EHR Connector"]
QE["Quality Evaluation"]
end
subgraph Safety["Safety Layer"]
OSA["Observational Safety Agents\n(Rule-Based · Deterministic)"]
VI["Vocal Intelligence\n(Prosodic Analysis)"]
end
PROTO --> RE
RE -->|Conversation Plan| CE
EHRC --> RE
EHRC --> CE
TEL <--> CE
EHRG <--> EHRC
EVALPIPE --> QE
AUTH --> CE
CE --> QE
OSA -->|Parallel Monitoring| CE
VI -->|Audio Features| OSA
VI -->|Engagement Signals| CE
QUEUE --> RE
QUEUE --> CE
```
#### System Architecture Characteristics
1. **Dual-Model Design**: Each conversation is powered by two distinct AI systems — a pre-call Reasoning Engine for planning and a real-time Conversation Engine for execution
2. **Consistent Stack**: Standard technology stack across all agents: Python/Node.js services, PostgreSQL, Redis, cloud object storage, and FHIR-based EHR integration
3. **Multi-Modal Support**: System supports voice (outbound/inbound calls), SMS, and messaging channels
4. **Headless Agents**: Some agents operate without a patient-facing interface — processing EHR data, generating care gap lists, or coordinating between other agents via APIs
### Horizontal Components/Services
1. **Authentication**: Unified authentication mechanism across all agent services using SAML/OIDC with enterprise IdP integration
2. **Telephony**: Centralized SIP trunking and voice synthesis infrastructure shared across all voice agents
3. **EHR Gateway**: Standardized FHIR R4 interface providing consistent EHR read/write across Epic, Cerner, Athena, and other systems
4. **Queue System**: Enables agents to send and receive messages, trigger actions, and share results across the conversation pipeline
5. **Evaluation Pipeline**: Shared quality assessment infrastructure using LLM-as-judge and rule-based validation
6. **Observability**: Centralized logging, metrics, and tracing across all agent services
### Agent Package Components
Each agent package includes:
1. **Protocol Configuration**: Clinical workflow definition including questions, branching logic, escalation triggers, and data extraction rules
2. **Reasoning Engine Integration**: Pre-call planning that generates conversation plans from patient EHR data and protocol rules
3. **Conversation Engine**: Real-time dialogue management with constrained response generation
4. **EHR Connector**: Bi-directional data exchange with the patient's health record
5. **Quality Evaluation**: Automated post-conversation quality scoring and error detection
6. **Analytics**: Conversation outcome tracking, completion metrics, and clinical data extraction reporting
### Sample Agent Design
**Design Exercise — Voice Engagement Agent**
**Agent Package Components:**
* Authentication: Enabled by default for secure EHR access
* Telephony: SIP integration for outbound/inbound voice
* Protocol Engine: Configurable clinical conversation workflows
**Infrastructure:**
* Database: Patient context cache, conversation state, and extracted data
* REST APIs: Conversation initiation, status, outcomes, and transcript retrieval
* WebSocket: Real-time streaming for voice synthesis and recognition
**Implementation:**
1. API Endpoints: Conversation CRUD, protocol management, EHR sync
2. Reasoning Service: Pre-call planning using patient data and protocol rules
3. Conversation Service: Real-time dialogue with constrained generation
4. Containerization: Kubernetes deployment with auto-scaling based on concurrent call volume
# Designed for Fast-Adoption
Source: https://docs.hana.health/implementation/fast-adoption
Scalable EHR integration framework built to minimize implementation friction and accelerate time-to-value for healthcare organizations.
## Overview
Our scalable EHR integration framework is built to minimize implementation friction and accelerate time-to-value for healthcare organizations. By standardizing the onboarding process and providing clear documentation, we enable rapid deployment and seamless integration with existing clinical workflows.
## Key Fast-Adoption Features
### Streamlined Implementation Process
**5-Phase Implementation Methodology** ensures consistent, successful deployments:
1. **Discovery & Planning (Days 1-5)**: Requirements gathering, EHR system assessment, implementation roadmap
2. **Configuration & Integration (Days 6-15)**: API connection setup, data mapping validation, security verification
3. **Testing & Validation (Days 16-25)**: Functional testing, performance validation, user acceptance testing
4. **Training & Deployment (Days 26-30)**: Staff training, phased rollout, go-live support
5. **Optimization & Expansion (Ongoing)**: Performance monitoring, feature enhancement, protocol expansion
### Pre-Built Connectors
* **Major EHR System Support**: Ready-made integrations for Epic, Cerner, Athena, AllScripts, and other popular EHR systems
* **Standardized API Interfaces**: Common FHIR R4 connection patterns reduce custom development requirements
* **Automated Compliance**: Built-in HIPAA, GDPR, and SOC 2 compliance frameworks reduce regulatory overhead
### Implementation Accelerators
* **Protocol Templates**: Pre-configured clinical conversation templates allow quick validation of expected conversation flows
* **Field Mapping Tools**: Specialized forms streamline the connection between HANA's AI and EHR fields
* **Documentation-Driven Setup**: Step-by-step guides for all integration patterns
## Implementation Success Metrics
| Metric | Target | Typical Achievement |
| ---------------------------- | ---------- | ------------------- |
| Initial Setup Time | \< 1 Week | 3-5 Business Days |
| Staff Training Required | \< 2 Hours | 90 Minutes |
| Time to First Production Use | \< 30 Days | 12-18 Days |
| Integration Test Coverage | 100% | 98.5% |
| Data Validation Accuracy | 99.9% | 99.95% |
## What We Handle vs. What You Handle
| HANA Handles | Organization Handles |
| ------------------------------------------ | ----------------------------------------- |
| All infrastructure setup and management | EHR API credentials and access |
| Clinical protocol design and configuration | Clinical review and approval of protocols |
| EHR integration development | IT point of contact for integration |
| Voice and language configuration | Preferred voice and communication style |
| Quality monitoring and improvement | Escalation queue management |
| Compliance and security | BAA execution |
| Ongoing model updates | Feedback on conversation quality |
| 24/7 system monitoring | Staff training attendance |
# User-level Personalization
Source: https://docs.hana.health/implementation/personalization
Extensive customization capabilities adapting to the specific needs of healthcare organizations, departments, and individual patients.
## Overview
HANA's voice engagement framework provides extensive customization capabilities to adapt to the specific needs of healthcare organizations, clinical specialties, and individual patients.
## Personalization Dimensions
### Organization-level Settings
* **Brand Alignment**: Customizable voice persona and greeting language to match healthcare organization's identity
* **Terminology Adaptation**: Support for organization-specific medical terminology and abbreviations
* **Workflow Integration**: Tailored insertion points within existing clinical processes (scheduling, intake, follow-up)
* **Security Controls**: Granular access management aligned with organizational policies
* **Operating Hours**: Configurable call scheduling, after-hours behavior, and retry policies
### Specialty-specific Customization
* **Specialty Protocols**: Pre-configured conversation templates for 20+ medical specialties
* **Condition-specific Content**: Tailored conversation flows for common conditions within each specialty
* **Assessment Instruments**: Specialty-appropriate screening tools (PHQ-9, GAD-7, AUDIT-C, CAGE-AID, etc.)
* **Regulatory Compliance**: Specialty-specific documentation requirements built into protocols
* **Billing Integration**: CPT/HCPCS code suggestions relevant to each specialty and conversation type
### Individual Patient Preferences
* **Language**: Primary language detection and preference storage; clinically validated for English, Spanish, Italian, French, and German with additional languages available at varying coverage levels
* **Communication Style**: Adjustable pacing, detail level, and formality based on patient profile
* **Contact Preferences**: Best time to call, preferred channel (voice, SMS), callback scheduling
* **Personal Templates**: Patient-specific conversation adjustments that persist across interactions
* **Learning Adaptation**: System adapts to individual communication patterns over time
## Personalization Infrastructure
### Longitudinal Memory Architecture
HANA builds a patient interaction profile that grows richer with every conversation. This is distinct from EHR data — the organization's clinical systems remain the source of truth for medical information. HANA's memory layer captures *interaction intelligence*: how to communicate with each patient most effectively.
**Memory Layers:**
| Layer | Source | Purpose |
| ------------------------- | ----------------------------------- | -------------------------------------------------------------- |
| Clinical context | EHR (pulled fresh before each call) | Diagnoses, medications, care plans, appointments |
| Communication preferences | Learned from interactions | Channel preference, best time to call, pacing, formality level |
| Conversation history | Built by HANA | Prior topics discussed, goals set, issues flagged |
| Behavioral patterns | Observed over time | Response style, engagement triggers, dropout risk signals |
| Vocal baseline | Vocal intelligence engine | Prosodic profile for longitudinal deviation detection |
**How Memory Improves Conversations:**
* A patient who prefers texts over calls gets SMS outreach first
* A patient with lower health literacy gets simpler language and more confirmation checks
* A chronic care patient's third monthly check-in references what was discussed in the first two
* A patient who expressed frustration about insurance in a prior call gets a more empathetic tone when the topic comes up again
### Patient Profile Management
* **Preference Persistence**: Secure storage of patient settings across conversations and channels
* **Role-based Defaults**: Initial settings based on clinical protocol and patient demographics
* **Preference Portability**: Settings follow patients across departments, locations, and provider changes
* **Version Compatibility**: Patient preferences maintained through system updates
### Personalization Workflow
* **Guided Setup**: Interactive onboarding for initial organization and protocol personalization
* **Continuous Refinement**: Ongoing opportunities to adjust preferences based on conversation outcomes
* **Clinician Input Integration**: Clinical staff can annotate patient profiles with notes about communication preferences, sensitivities, or context that enriches future conversations — similar to how care teams pass notes between shifts
* **Preference Analytics**: Insights into which personalization options improve engagement and completion rates
* **Protocol Sharing**: Ability to share effective protocol configurations within organizations
### Technical Implementation
* **Efficient Caching**: Local caching of personalization settings for fast conversation initialization
* **Synced Preferences**: Real-time synchronization across channels (voice, SMS) and sessions
* **Fallback Handling**: Graceful defaults when personalization data is unavailable
* **Performance Optimization**: Minimal impact on conversation response latency regardless of personalization level
* **Privacy Compliance**: All preference data encrypted, auditable, and deletable per patient request
* **Data Ownership**: Patient interaction data belongs to the healthcare organization. HANA processes and stores it per the organization's retention policies and provides full export capability.
# Eval Based System
Source: https://docs.hana.health/reasoning-models/eval-based-system
HANA's adaptive reasoning models: multi-tiered processing, candidate generation and verification, infrastructure cost analysis, and model performance optimization.
## Overview
HANA's Adaptive Reasoning Models represent a breakthrough in large-scale inference optimization and real-time clinical decision support. Built on our service architecture, these models dynamically adjust their reasoning processes based on clinical context, computational constraints, and performance requirements.
The system leverages multi-tiered processing, candidate generation and verification, and self-calibration to deliver high performance while maintaining accuracy and reliability in production voice conversations.
## Core Architecture
### Multi-Tiered Processing System
HANA's adaptive reasoning system employs a sophisticated multi-tiered architecture designed for real-time clinical analysis and decision support:
**Processing Intervals:**
* **Immediate checks (\< 500ms)**: Response validation, entity grounding, safety filter — runs during every conversation turn
* **Turn-level checks (1-3 seconds)**: Context coherence, goal tracking, sentiment analysis — runs between conversation turns
* **Post-call analysis (async)**: Full transcript review, clinical accuracy audit, protocol compliance, quality scoring
**Concurrent Processing Capabilities:**
* Support for thousands of concurrent streaming voice sessions
* CPU-optimized conversation engine for low-latency response generation
* GPU-accelerated reasoning engine for pre-call planning and complex clinical analysis
* Memory-efficient design with minimal RAM per active conversation session
### Candidate Generation and Verification
```mermaid theme={null}
graph LR
subgraph Generate["Generation"]
CS["Conversation\nState"] --> FM["Fast Model"]
FM --> C1["Candidate 1"]
FM --> C2["Candidate 2"]
FM --> CN["Candidate N"]
end
subgraph Verify["Verification"]
C1 --> VE["Reasoning\nEngine"]
C2 --> VE
CN --> VE
VE --> PC["Protocol\nCheck"]
VE --> EG["Entity\nGrounding"]
VE --> SF["Safety\nFilter"]
end
subgraph Select["Selection"]
PC --> SC["Score &\nRank"]
EG --> SC
SF --> SC
SC --> OPT["Optimal\nResponse"]
OPT --> VS["Voice\nSynthesis"]
end
SC -.->|Calibration Feedback| FM
```
HANA's conversation engine uses a generate-and-verify architecture for response selection:
* A fast, lightweight model generates candidate responses for the next conversation turn
* The reasoning engine evaluates and ranks candidates against clinical protocol constraints, entity grounding, and safety rules
* The highest-scoring candidate is selected and delivered via streaming voice synthesis
* Self-calibration adjusts selection weights during runtime based on conversation context
**Generation and Verification Pipeline:**
* Fast model generates multiple candidate responses based on current conversation state
* Each candidate is verified against: protocol constraints, entity grounding, safety rules, and clinical appropriateness
* Optimal candidate selected and delivered via streaming voice synthesis
* Verification results feed back into calibration for future selections
## Infrastructure & Cost Analysis
### Current Usage & Projections
**Baseline Costs:**
* Current LLM API usage for reasoning engine: variable based on conversation volume
* Voice synthesis and recognition: per-minute telephony and processing costs
* Infrastructure: cloud compute, storage, and networking
**Projected Infrastructure Savings:**
* Optimized model routing reduces inference costs by 40-60% compared to single-model approaches
* Cached reasoning plans for common patient profiles reduce redundant computation
* Auto-scaling to zero during low-volume periods eliminates idle compute waste
### Hardware Configuration
**Production Setup:**
* Kubernetes clusters with auto-scaling node pools
* GPU nodes for reasoning engine inference (pre-call planning, post-call analysis)
* CPU-optimized nodes for real-time conversation engine (latency-critical path)
* Dedicated telephony infrastructure with geographic redundancy
***
## Model Performance & Optimization
### Overview
In the field of compute optimization, model routing, caching strategies, and batch processing optimization are crucial for enhancing performance. For cost optimization, intelligent complexity-based routing, reasoning plan reuse, and resource sharing across concurrent sessions are essential to efficiently manage resources and reduce expenses.
### Technical Implementation
**Memory Management:**
* Conversation state maintained per active session with minimal memory footprint
* EHR data cached with configurable TTL to reduce redundant API calls
* Reasoning plans stored and reused for similar patient profiles
* Efficient embedding storage and retrieval for patient context
**Processing Optimization:**
* Dynamic model routing based on conversation complexity (simple → fast model, complex → full reasoning pipeline)
* Protocol-specific optimization: pre-computed conversation plans for common clinical workflows
* Streaming voice synthesis begins before full response is composed (parallel processing)
### Performance Metrics
**Conversation Engine:**
* Response latency: \< 800ms p95 (time from patient speech end to HANA speech start)
* Concurrent sessions: scales horizontally based on demand
* Voice synthesis quality: natural conversational pacing with dynamic prosody
**Reasoning Engine:**
* Pre-call plan generation: \< 3 seconds per patient
* Post-call analysis: \< 30 seconds per conversation
* Clinical entity extraction accuracy: > 97% (measured across internal evaluation datasets; validated per protocol during onboarding)
* Protocol compliance rate: > 97% (measured via automated post-call evaluation pipeline)
### Performance Optimization Strategies
**Adaptive Processing:**
Dynamic Resource Allocation:
* Automatic scaling based on call volume and time-of-day patterns
* Context-aware compute allocation (complex protocols get more reasoning resources)
* Priority-based processing queues for urgent clinical conversations
Model Selection:
* Lightweight models for simple conversation turns (confirmations, acknowledgments)
* Full reasoning pipeline for clinical branching decisions and entity extraction
* Specialized models for assessment instrument scoring (PHQ-9, GAD-7, etc.)
**Efficiency Optimizations:**
Compute Optimization:
* Optimized inference for specific clinical conversation patterns
* Pre-computed response segments for standard protocol language
* Batch processing for post-call analysis across multiple conversations
Cost Optimization:
* Intelligent model routing based on complexity requirements
* Caching strategies for repeated reasoning patterns (same protocol + similar patient profile)
* Resource sharing across concurrent sessions with priority queuing
***
## Data Evaluation & Quality Assurance
### Evaluation Framework
**Dataset Management:**
* Comprehensive evaluation dataset of scored production conversations, growing continuously
* Data cleaning removes invalid or incomplete entries before evaluation
* Continuous evaluation with systematic processing for quality stability
**Evaluation Tools:**
* LLM-as-judge integration for automated quality assessment
* Reference-free evaluations without requiring golden standard transcripts
* Separate evaluation tracks for high-quality examples and failure mode identification
**Quality Metrics:**
* Auto-optimization system to improve quality scores over time
* Continuous feedback loop for model and protocol improvement
* Performance tracking across different clinical protocols and patient demographics
# LRMs as a Judge
Source: https://docs.hana.health/reasoning-models/lrms-as-judge
Advanced framework for autonomous quality assessment and conversation evaluation using large reasoning models as judges.
## Overview
Large Reasoning Models (LRMs) as a Judge represents HANA's advanced framework for autonomous quality assessment, conversation evaluation, and clinical accuracy validation. This system leverages capable evaluation models to assess outputs from the conversation engine, creating a hierarchical evaluation architecture that ensures quality, consistency, and reliability across all patient interactions.
Built on our service architecture, the LRM judging system provides reference-free evaluation, multi-dimensional scoring, and continuous quality assurance without requiring expensive golden datasets or extensive human annotation.
### Evaluation Metrics and KPIs
**Quality Assessment Metrics:**
Primary Quality Indicators:
* Overall quality score (1-5 star rating system)
* Dimension-specific scores (clinical accuracy, communication quality, protocol compliance, completeness)
* Confidence intervals for score reliability assessment
* Comparative rankings across model versions and protocol configurations
Performance Metrics:
* Evaluation throughput (conversations evaluated per minute)
* Response latency for real-time evaluation requests
* Judge model accuracy against human clinical reviewer ground truth
* Resource efficiency (cost per evaluation)
**Business Impact Measurements:**
Quality Improvement Tracking:
* Conversation quality trends over time and across clinical protocols
* Patient satisfaction correlation with judge model scores
* Error reduction rates attributable to judge-based quality control
* Cost savings from automated quality assurance vs. manual review
System Reliability Metrics:
* Judge model availability and uptime
* Evaluation consistency across different judge model instances
* False positive/negative rates for quality threshold decisions
* Escalation rates for human review requirements
**Cost-Benefit Analysis:**
Infrastructure Costs:
* Judge model hosting: integrated with existing inference infrastructure
* Evaluation framework: LLM-as-judge integration and custom evaluation tooling
* Monitoring systems: extension of existing observability infrastructure
Operational Efficiency Gains:
* Automated quality assurance: significant reduction in manual conversation review
* Consistent evaluation standards: elimination of subjective quality assessment variability
* 24/7 quality monitoring: continuous evaluation without human intervention
* Scalable assessment: linear scaling with conversation volume without proportional cost increase
***
## Core Architecture
### Core Judging Architecture
**Hierarchical Model Evaluation:**
Primary Judge Models:
* Large reasoning model: primary evaluation for complex clinical accuracy assessment and multi-turn conversation coherence
* Specialized clinical model: domain-specific evaluation for medical terminology, assessment instrument scoring, and protocol compliance
* Ensemble judging: multiple evaluation models provide consensus-based quality scores
Specialized Judge Models:
* Lightweight models: fast evaluation for simple quality checks (response formatting, basic safety)
* Domain-specific judges: fine-tuned evaluators for clinical conversation patterns
* Protocol-specific judges: evaluators trained on specific clinical workflow requirements
### Reference-Free Evaluation System
**Evaluation Tracking Infrastructure:**
* Growing evaluation dataset of scored production conversations
* Real-time quality scoring without requiring golden standard conversation transcripts
* Systematic evaluation collection with automated processing pipelines
* Automated data cleaning removing invalid or incomplete entries during processing
**Quality Assessment Dimensions:**
* High-quality evaluation datasets for identifying characteristics of excellent conversations
* Low-quality evaluation datasets for failure mode identification and error pattern analysis
* Comparative scoring between different model versions and protocol configurations
* Auto-optimization algorithms for continuous score improvement
**Judge Model Capabilities:**
Content Quality Assessment:
* Clinical accuracy evaluation using medical knowledge validation
* Logical consistency checking for conversation flow and branching decisions
* Completeness assessment for information collection goals
* Relevance scoring for clinical appropriateness of questions and responses
Communication Quality Evaluation:
* Clarity and readability assessment for patient comprehension
* Empathy and tone evaluation for sensitive clinical topics
* Pacing appropriateness for patient communication style
* Patient intent alignment for goal achievement assessment
***
## Evaluation Methodologies
### Consensus-Based Judging
**Multi-Judge Ensemble:**
* Independent evaluation by multiple judge models from different perspectives
* Consensus scoring using weighted voting mechanisms
* Disagreement analysis for identifying edge cases requiring human review
* Confidence-weighted aggregation for reliable final quality scores
**Judge Model Specialization:**
* Domain experts: clinical accuracy, medication safety, assessment instrument judges
* Task specialists: conversation flow, data extraction, escalation decision judges
* Quality dimensions: accuracy, clarity, completeness, relevance judges
* Patient perspective: communication quality, empathy, satisfaction judges
### Comparative Evaluation Framework
**Model-vs-Model Assessment:**
* Head-to-head comparisons between different model versions for A/B testing
* Ranking systems for multiple candidate conversation approaches
* Preference learning from comparative judgments
* Quality difference quantification for deployment decisions
**Human-vs-AI Alignment:**
* Human clinical reviewer correlation studies for judge model validation
* Bias detection in judge assessments across patient demographics
* Cultural sensitivity evaluation for diverse patient populations
* Ethical guideline compliance checking for clinical conversation content
***
## Applications
### Domain-Specific Applications
**Clinical Accuracy Assessment:**
* Medication name and dosage validation using pharmaceutical databases
* Assessment instrument scoring verification (PHQ-9, GAD-7, AUDIT-C administration rules)
* Clinical data extraction accuracy evaluation against source EHR data
* Medical terminology appropriateness for patient-facing communication
**Protocol Compliance Evaluation:**
* HIPAA compliance checking for PHI handling during conversations
* Clinical protocol adherence verification for each conversation
* Consent language delivery confirmation
* Escalation trigger compliance for safety-critical scenarios
**Patient Experience Assessment:**
* Communication quality scoring for empathy, clarity, and pacing
* Patient goal completion assessment (scheduling, information collection, screening)
* Conversation efficiency evaluation (duration vs. complexity)
* Satisfaction prediction based on conversation quality signals
***
## Quality and Performance
### Judge Model Efficiency
**Computational Optimization:**
* Model selection algorithms choosing appropriate judge size for evaluation complexity
* Caching strategies for repeated evaluation patterns (same protocol, similar conversations)
* Batch processing optimization for post-call evaluation of multiple conversations
* Resource scheduling to minimize impact on primary conversation inference workloads
**Cost-Effective Judging:**
* Tiered evaluation strategy using progressively more sophisticated judges
* Early termination for obviously high or low quality conversations
* Confidence-based routing to minimize expensive judge model usage
* Quality threshold optimization balancing evaluation cost and accuracy
### Quality Assurance Framework
**Judge Reliability Assessment:**
* Inter-judge agreement measurement for consistency validation
* Test-retest reliability for judge model stability across time
* Ground truth correlation where human clinical review scores exist
* Expert clinical validation for judge model calibration
**Bias and Fairness Monitoring:**
* Demographic bias detection in judge assessments across patient populations
* Language and dialect sensitivity analysis for multilingual conversations
* Protocol bias identification and mitigation strategies
* Temporal consistency monitoring for judge model drift
***
## Service Integration
### Judge Service Components
**Evaluation Orchestrator Service:**
* Request routing to appropriate judge models based on conversation type and protocol
* Load balancing across multiple judge model instances
* Priority queuing for time-sensitive evaluations (flagged conversations)
* Result aggregation from multiple judge models into composite quality score
**Judge Model Registry:**
* Model capability metadata for optimal judge selection per evaluation task
* Performance benchmarks for each judge model type
* Availability monitoring and automatic failover
* Version management for judge model updates
**Quality Scoring Service:**
* Multi-dimensional scoring across clinical accuracy, communication quality, protocol compliance, and completeness
* Confidence interval calculation for score reliability
* Historical trend analysis for quality improvements per protocol and organization
* Threshold-based alerting for quality degradation
### Application Integration Patterns
**Real-Time Judging APIs:**
* Synchronous evaluation for immediate quality feedback on flagged conversations
* Asynchronous batch evaluation for large-scale post-call quality assessment
* Streaming evaluation for continuous quality monitoring during active conversations
* Webhook integration for event-driven quality assessment (escalation triggers, safety flags)
**Quality Gate Integration:**
* Pre-deployment quality checks before new model or protocol versions go live
* Runtime quality monitoring for live conversation quality tracking
* Post-processing evaluation for historical conversation improvement analysis
* A/B testing support for comparing different model versions and conversation approaches
# Self-correcting Models
Source: https://docs.hana.health/reasoning-models/self-correcting-models
Advanced framework for autonomous error detection, correction, and continuous improvement in HANA's voice-based clinical conversations.
## Overview
HANA's Self-correcting Models represent an advanced framework for autonomous error detection, correction, and continuous improvement in clinical voice AI. Built on our service architecture, these models employ multi-layered validation, real-time feedback loops, and adaptive learning mechanisms to achieve high reliability and accuracy in production environments.
The system combines constrained generation, reference-free evaluation, and continuous optimization to create conversations that not only detect errors but actively improve performance over time.
## Core Self-Correction Architecture
```mermaid theme={null}
graph TB
INPUT["Patient Response"] --> RT
subgraph RTLayer["Real-Time Validation (per utterance)"]
RT["Template Compliance\nEntity Grounding\nConfidence Scoring\nSafety Filter"]
end
subgraph TLLayer["Turn-Level Validation (between turns)"]
TL["Semantic Consistency\nCross-Reference Validation\nContext Coherence\nDomain Rule Check"]
end
subgraph PCLayer["Post-Call Validation (async)"]
PC["LLM-as-Judge Evaluation\nProtocol Compliance\nHistory Validation\nQuality Scoring"]
end
RT -->|Pass| DELIVER["Deliver Response"]
RT -->|Fail| REGEN["Block & Regenerate"]
RT --> TL
TL -->|Issue Detected| REDIRECT["Soft Redirect\nor Clarify"]
TL -->|OK| NEXT["Continue\nConversation"]
NEXT --> PC
PC -->|Flag| REVIEW["Clinical Team\nReview"]
PC -->|Error Patterns| IMPROVE["Protocol &\nModel Updates"]
IMPROVE -.->|Feedback Loop| RT
```
### Multi-Layered Validation System
**Immediate Validation (per-utterance):**
* Template compliance checking for response format and content
* Entity grounding verification against patient EHR data
* Confidence scoring based on model internal states
* Real-time safety filtering for clinically inappropriate content
**Turn-Level Validation (between turns):**
* Semantic consistency analysis across conversation turns
* Cross-reference validation against known patient data and protocol constraints
* Context coherence checking for multi-turn clinical dialogues
* Domain-specific rule validation (e.g., medication names, ICD codes, assessment scoring)
**Post-Call Validation (async):**
* Comprehensive clinical accuracy verification using LLM-as-judge evaluation
* Full transcript analysis for protocol compliance
* Long-term context validation across patient's conversation history
* Quality assurance against evaluation datasets and clinical standards
### Candidate Verification Framework
**Generation and Verification Pipeline:**
* Conversation engine generates candidate responses for each turn
* Reasoning engine evaluates and ranks candidates against protocol constraints, selecting the optimal response
* Verification is optimized for minimal latency impact on the conversation flow
* Self-calibration adjusts correction thresholds based on conversation context and historical accuracy
**Correction Strategies:**
* Immediate corrections for detected errors during response generation (block and regenerate)
* Mid-conversation corrections through clarification and re-asking (soft redirect)
* Post-conversation corrections flagged for clinical team review
* Predictive corrections based on known error patterns in similar conversations
### Continuous Learning Mechanisms
**Feedback Loop Architecture:**
* Real-time correction logging for pattern identification across production conversations
* Error taxonomy classification for systematic improvement
* Performance regression detection and automatic rollback for model updates
* A/B testing framework for correction strategy optimization
**Data-Driven Optimization:**
* Error pattern mining from production conversations
* Correction effectiveness analysis across different clinical protocols
* Model weight adjustments based on correction success rates
* Dynamic threshold tuning for optimal precision-recall balance
***
## Self-Correction Implementation
### Implementation Architecture
**Real-Time Correction Pipeline:**
Stream Processing:
* Immediate error detection during response generation
* Context-aware correction maintaining natural conversation flow
* Memory-efficient correction processing per active session
* Concurrent correction across all active conversation sessions
Correction Decision Engine:
* Multi-factor scoring combining confidence, context, and historical data
* Threshold-based correction triggering with adaptive boundaries
* Cost-benefit analysis for correction implementation (is re-asking worth the disruption?)
* Patient experience optimization minimizing correction-related conversation friction
### Batch Correction Framework
**Historical Data Processing:**
* Retroactive quality analysis for completed conversations
* Large-scale pattern identification across conversation corpus
* Data migration support during model updates
* Quality metric recalculation after protocol changes
**Performance Optimization:**
* Parallel analysis processing across multiple compute nodes
* Checkpoint-based recovery for long-running analysis jobs
* Resource scheduling to minimize impact on live conversation services
* Progress tracking and reporting for operational visibility
### Error Detection Mechanisms
**Statistical Anomaly Detection:**
Confidence Score Analysis:
* Low confidence detection using model uncertainty quantification
* Confidence calibration ensuring scores reflect actual accuracy
* Ensemble disagreement as indicator of potential errors
* Temporal consistency checking across related outputs
Pattern Recognition:
* Known error pattern matching using curated clinical error databases
* Linguistic anomaly detection for unnatural conversation patterns
* Factual inconsistency detection using patient data validation
* Reasoning chain verification for multi-step clinical logic
**Domain-Specific Validation:**
Clinical Domain:
* Medication name validation against pharmaceutical databases
* Drug interaction checking when multiple medications discussed
* Medical terminology verification against authoritative sources (SNOMED CT, RxNorm)
* Clinical guideline compliance checking for protocol-defined recommendations
Assessment Instruments:
* PHQ-9, GAD-7, AUDIT-C scoring validation against administration rules
* Threshold-based alert verification for screening instrument results
* Response mapping validation (patient language → assessment score category)
### Correction Strategies
**Immediate Correction Approaches:**
Response-Level Correction:
* Real-time response replacement during generation when safety or grounding check fails
* Alternative phrasing generation for unclear or ambiguous utterances
* Template fallback for responses that fail multiple validation checks
* Graceful acknowledgment when system cannot generate a valid response
Conversation-Level Correction:
* Soft redirect: naturally steer conversation back on track without calling attention to the correction
* Explicit clarification: directly address ambiguity or inconsistency with the patient
* Graceful deferral: hand off to human staff when system cannot resolve the issue
**Retrospective Correction Methods:**
Post-Call Analysis:
* Targeted error identification for specific clinical data extraction issues
* Comprehensive quality assessment for entire conversation transcripts
* Pattern identification across conversations for systematic protocol improvements
* Clinical team notification for conversations requiring human review
Learning Integration:
* Protocol updates based on recurring error patterns
* Template expansion incorporating correction insights
* Training data augmentation with corrected conversation examples
* Evaluation metric refinement based on correction effectiveness
***
## Performance Monitoring
### Quality Metrics
**Correction Effectiveness:**
* Error detection rate (sensitivity) across different error types
* False positive rate (specificity) for correction triggers
* Correction accuracy measuring improvement quality
* Patient experience impact of corrections vs. uncorrected conversations
**System Performance:**
* Correction latency impact on conversation response time
* Throughput impact of correction processing on overall system
* Resource utilization for correction infrastructure
* Cost per correction for operational efficiency analysis
### Operational Dashboards
**Real-Time Monitoring:**
* Live error detection rates across all active conversation sessions
* Correction queue status and processing latency
* Quality score distributions for current conversations
* System health indicators for correction services
**Historical Analysis:**
* Error trend analysis over time and across different clinical protocols
* Correction success patterns for strategy optimization
* Model performance evolution showing improvement trajectory
* Cost-benefit analysis of correction infrastructure investment
### Quality Assurance Framework
**Validation Protocols:**
Multi-Stage Verification:
* Automated validation using evaluation models
* Human clinical review for flagged conversations
* Peer review processes for edge cases and complex corrections
* Patient feedback integration for real-world quality assessment
Quality Gates:
* Pre-deployment validation for model and protocol updates
* A/B testing protocols for new correction strategies
* Rollback procedures for correction strategy failures
* Performance regression testing ensuring corrections don't degrade quality
**Compliance and Auditing:**
Audit Trail Management:
* Complete correction history with timestamps and rationale
* Decision audit logs for correction trigger events
* Performance audit reports for regulatory compliance
* Patient consent tracking for conversation recording and analysis
Regulatory Compliance:
* Healthcare compliance (HIPAA) for all correction operations involving PHI
* Privacy compliance (GDPR) for personal information handling
* AI safety compliance ensuring fair and unbiased corrections
* SOC 2 Type II audit coverage for correction infrastructure
***
## Integration Guidelines
### For Application Teams
**Implementation Steps:**
1. Enable correction APIs in agent configuration
2. Set quality thresholds appropriate for clinical protocol requirements
3. Implement feedback collection for clinician-reported issues
4. Monitor correction impact on patient experience metrics
**Best Practices:**
* Graceful correction handling maintaining natural conversation flow
* Patient transparency about AI nature without over-explaining corrections
* Performance monitoring for correction-related latency
* Fallback strategies for correction system unavailability
### For Platform Teams
**Infrastructure Management:**
1. Deploy correction services across all environments (staging, production)
2. Configure monitoring for correction system health
3. Establish SLAs for correction response times
4. Implement scaling policies for correction infrastructure
**Operational Considerations:**
* Resource allocation for correction processing workloads
* Data pipeline management for correction training and evaluation
* Security protocols for correction system access (PHI handling)
* Disaster recovery for correction service failures
# Self-hosted Architecture
Source: https://docs.hana.health/reasoning-models/self-hosted-architecture
Enterprise-grade infrastructure for HANA's voice AI platform: service architecture, tenant management, security, and observability.
## Overview
HANA's architecture is designed to provide enterprise-grade security, scalability, and reliability for voice-based clinical AI agents. The architecture is built around a service-oriented model that supports multi-tenancy, cross-team collaboration, and comprehensive lifecycle management.
## Architecture Components
### 1. Cross-team Workflow
Supports collaboration across engineering teams with clear coordination and structure:
* **Standardized Interfaces**: Shared APIs and messaging protocols streamline communication between conversation engine, reasoning engine, EHR gateway, and telephony services
* **Managed Dependencies**: Teams align on service contracts and reuse common infrastructure through defined collaboration patterns
### 2. Tenant Management
Maintains performance, security, and organizational clarity through isolation and governance:
**Tenant Onboarding:**
* Automated provisioning of isolated environments per healthcare organization
* EHR credential management and connection validation
* Protocol configuration and clinical workflow setup
* Voice persona and language configuration
**Tenant Boundaries:**
* Data isolation: Patient data never crosses tenant boundaries
* Configuration isolation: Independent protocols, escalation rules, and voice settings
* Network isolation: Tenant-specific encryption keys and access controls
* Audit isolation: Complete audit trail per tenant for compliance
### 3. Engineering Lifecycle
Covers the full pipeline from development to production monitoring:
* **CI/CD Pipeline**: Automated build, test, and deployment for all services
* **Staging Environments**: Full production replica for pre-deployment validation
* **Blue-Green Deployments**: Zero-downtime deployments with instant rollback capability
* **Canary Releases**: Gradual traffic shifting for new model versions
### 4. Reliability
Optimized for productivity, reliability, and resilience:
* **Auto-scaling**: Horizontal scaling based on concurrent call volume
* **Circuit Breakers**: Automatic failure detection and isolation
* **Health Checks**: Continuous health monitoring with automatic remediation
* **Multi-Zone Deployment**: Services deployed across multiple availability zones
## Infrastructure Details
### Cloud Infrastructure
HANA runs on cloud infrastructure with healthcare-grade security and compliance:
**Production Environment:**
* Primary cloud: GCP/AWS with healthcare BAA
* Kubernetes orchestration (GKE/EKS) for container management
* GPU-accelerated inference nodes for reasoning engine
* CPU-optimized nodes for real-time conversation engine (latency-critical)
**Development:**
* Isolated non-production environment for testing and staging
* Synthetic patient data for development — no real PHI in non-prod
**Service Routing:**
Services are accessed through a standardized routing pattern:
* API Gateway with rate limiting and authentication
* Internal service mesh with mutual TLS
* Load balancing across service replicas
***
## Service Fabric Architecture
### Service Fabric Overview
HANA's Service Fabric provides the foundational platform for all agent services and infrastructure components. It manages service discovery, communication, scaling, and health monitoring.
**Core Components:**
| Component | Technology | Purpose |
| ----------------------- | -------------- | ----------------------------------------------------- |
| Container Orchestration | Kubernetes | Service deployment, scaling, health management |
| Service Mesh | Istio/Linkerd | Service-to-service communication, mTLS, observability |
| API Gateway | Kong/Envoy | External traffic management, rate limiting, auth |
| Message Queue | Redis/RabbitMQ | Async communication between services |
| Database | PostgreSQL | Conversation state, patient context, configuration |
| Cache | Redis | Session state, EHR data cache, conversation plans |
| Object Storage | Cloud Storage | Conversation recordings, transcripts, model artifacts |
**Service Communication:**
* Synchronous: gRPC for latency-critical inter-service calls (conversation engine ↔ voice synthesis)
* Asynchronous: Message queue for non-blocking operations (post-call analysis, EHR write-back)
* Streaming: WebSocket for real-time voice data transport
***
## Security and Compliance
### Network Security
* **Zero Trust Architecture**: No implicit trust, continuous verification for every request
* **Network Segmentation**: Micro-segmentation with software-defined perimeters
* **Encryption in Transit**: TLS 1.3 for all communications
* **Encryption at Rest**: AES-256 encryption for all stored data
### Access Management
* **Identity Provider Integration**: SAML/OIDC integration with enterprise IdP
* **Multi-Factor Authentication**: Required for all administrative access
* **Role-Based Access Control**: Granular permissions based on principle of least privilege
* **Regular Access Reviews**: Automated access certification processes
### Compliance
* **SOC 2 Type II**: Annual compliance audits covering security, availability, and confidentiality
* **HIPAA Compliance**: Full compliance with US healthcare data privacy regulations with executed BAA
* **GDPR Compliance**: European data protection regulations support
* **Audit Logging**: Comprehensive audit trails for all system activities
***
## Observability
To ensure consistent and safe performance across our architecture we implement rigorous observability standards.
### Metrics & Monitoring
* **Infrastructure Metrics**: CPU, memory, disk, network utilization across all services
* **Application Metrics**: Conversation completion rates, latency percentiles, error rates, quality scores
* **Real-time Dashboards**: Grafana-based visualization for operations and clinical teams
* **Alerting**: PagerDuty integration for critical alerts with defined escalation procedures
### Logging
* **Centralized Logging**: ELK stack (Elasticsearch, Logstash, Kibana) for log aggregation and analysis
* **Structured Logging**: JSON-formatted logs with consistent schema across all services
* **Log Retention**: Configurable retention policies per environment and data classification
* **Search & Analytics**: Full-text search and log analytics for troubleshooting and compliance
### Tracing
* **Distributed Tracing**: End-to-end request tracking across services for every conversation
* **Performance Analysis**: Latency analysis and bottleneck identification in the conversation pipeline
* **Error Tracking**: Automatic error detection and alerting with full conversation context
* **Service Dependency Mapping**: Visual service topology and dependency graphs
# Towards ROI Based Systems
Source: https://docs.hana.health/reasoning-models/towards-roi
ROI projections combining self-hosted architecture, self-correcting models, and LRM-based quality assurance for measurable healthcare outcomes.
## Self-Hosted Architecture and Self-Correcting Models
### ROI Projections
**Quality Improvements:**
* Error reduction: Target 80% reduction in clinical data extraction errors through self-correction
* Patient satisfaction: Increase from baseline to > 4.5/5 CSAT through continuous quality improvement
* System reliability: 99.9% uptime with conversation quality guarantees
* Cost efficiency: Optimized model routing and caching reduce per-conversation inference costs
### Current Investment
**Infrastructure Costs:**
* Conversation and reasoning model hosting: integrated cloud infrastructure with auto-scaling
* Evaluation framework: LLM-as-judge integration and custom evaluation tooling
* Monitoring systems: extension of existing observability stack (Grafana, ELK, PagerDuty)
* Development resources: dedicated team for self-correction system development and protocol improvement
**Projected Savings:**
* Reduced human review: 70% reduction in manual conversation quality assurance
* Improved patient engagement: 25% increase in conversation completion rates reduces re-call costs
* Decreased support costs: 40% reduction in clinician-reported conversation issues
* Enhanced reliability: 50% reduction in conversations requiring human intervention
## LRMs as a Judge
### ROI Projections
**Quality Improvements:**
* Conversation quality increase: Target 40% improvement in average quality scores across protocols
* Error reduction: 60% decrease in quality-related clinical team escalations
* Consistency improvement: 90% reduction in quality score variance across conversations and protocols
* Protocol optimization: 50% faster identification and resolution of protocol design issues
**Cost Savings:**
* Reduced human review costs: significant annual savings in clinical quality assurance labor
* Decreased clinician support: 30% reduction in quality-related escalation volume
* Improved patient retention: higher engagement quality reduces patient opt-out rates
* Infrastructure efficiency: integration with existing compute resources minimizes additional hosting costs
## Healthcare Organization ROI
The projections below are modeled estimates for a mid-size primary care organization. Actual results vary based on patient population, EHR integration depth, staff workflows, and protocol configuration. We recommend validating assumptions with your operations team during the pilot phase.
### Direct Cost Savings (Mid-Size Primary Care, 50 Physicians)
| Current State | Annual Cost |
| ------------------------------------------------- | ------------- |
| Care coordinators for patient outreach (4 FTEs) | \$240,000 |
| Medical assistant phone time (\~30% allocation) | \$180,000 |
| Missed appointment revenue loss (8% no-show rate) | \$450,000 |
| Incomplete intake rework and re-calls | \$95,000 |
| **Total** | **\$965,000** |
| With HANA (Conservative Estimate) | Annual Cost |
| ------------------------------------------ | ------------- |
| HANA platform fee | \$180,000 |
| Reduced care coordinator need (4 → 3 FTEs) | \$180,000 |
| Reduced MA phone time (30% → 15%) | \$90,000 |
| Reduced no-show rate (8% → 5%) | \$280,000 |
| Reduced intake rework | \$45,000 |
| **Total** | **\$775,000** |
**Conservative net annual savings: \$190,000 | ROI: 106% | Payback: \~11 months**
Organizations with higher outreach volume and mature EHR integration typically see stronger results. Pilot deployments allow you to validate these projections against your specific workflows before scaling.
### Revenue Uplift
| Revenue Driver | Mechanism | Estimated Annual Impact (Range) |
| --------------------- | ------------------------------------------------------ | ------------------------------- |
| Reduced no-shows | Proactive outreach + rescheduling | $150,000 – $250,000 |
| BHI/CCM documentation | Structured documentation supporting CMS billing review | $100,000 – $180,000 |
| Care gap closure | Outreach for preventive screenings | $80,000 – $120,000 |
| Patient retention | Higher engagement reduces churn | $50,000 – $95,000 |
| **Total** | | **$380,000 – $645,000** |
BHI/CCM revenue estimates assume clinical staff validate billing eligibility per CMS guidelines. Revenue impact depends on payer mix, patient panel size, and billing compliance workflow. These are not guaranteed outcomes.
# Vocal Intelligence
Source: https://docs.hana.health/reasoning-models/vocal-intelligence
Prosodic analysis, vocal biomarker detection, and adaptive conversation dynamics derived from clinical voice research in behavioral health populations.
## Overview
HANA's Vocal Intelligence engine goes beyond speech-to-text transcription. Built on research into vocal biomarkers for mood disorders — including longitudinal studies with bipolar, PTSD, and depression populations — the system analyzes *how* patients speak, not just *what* they say, to detect emotional state, engagement level, and potential risk signals in real time.
This capability is architecturally distinct from the conversation engine. Vocal intelligence operates as a parallel analysis layer that processes raw audio features alongside the transcribed conversation, enriching the context available to both the real-time conversation engine and the post-call evaluation pipeline.
## Core Architecture
### Dual-Stream Processing
Every voice conversation produces two parallel data streams:
```mermaid theme={null}
graph TB
AUDIO["Raw Audio Input"] --> VIE["Vocal Intelligence Engine"]
AUDIO --> ASR["Speech Recognition"]
subgraph Stream1["Audio Feature Stream"]
VIE --> F0["F0 Pitch Tracking"]
VIE --> SR["Speech Rate Analysis"]
VIE --> EN["Energy Envelope"]
VIE --> SP["Spectral Features"]
VIE --> TT["Turn-Taking Dynamics"]
end
subgraph Stream2["Transcription Stream"]
ASR --> TX["Transcript"]
TX --> LS["Lexical Sentiment"]
TX --> KW["Clinical Keywords"]
TX --> SC["Semantic Coherence"]
TX --> RL["Response Latency"]
end
Stream1 --> MERGE["Merged Analysis"]
Stream2 --> MERGE
BL["Patient Vocal Baseline"] --> MERGE
MERGE --> RS["Risk Scoring"]
MERGE --> EM["Engagement Metrics"]
MERGE --> DD["Discrepancy Detection"]
RS --> SA["Safety Agents"]
EM --> CE["Conversation Engine"]
DD --> SA
```
**Audio Feature Extraction:**
* Fundamental frequency (F0) tracking for pitch contour analysis
* Speech rate variability and pause pattern detection
* Energy envelope analysis for vocal intensity dynamics
* Spectral features for voice quality assessment (breathiness, tension, tremor)
* Turn-taking dynamics between patient and agent
**Transcription-Level Analysis:**
* Lexical sentiment and emotional valence
* Clinical keyword detection for protocol-relevant content
* Semantic coherence across conversation turns
* Response latency patterns
### Baseline-Deviation Detection
Vocal intelligence is most powerful over longitudinal patient relationships. Rather than attempting absolute emotion classification from a single call — which is unreliable — the system builds a personalized vocal baseline for each patient and detects *deviations* from their normal patterns.
**How Baseline Building Works:**
1. First 2-3 conversations establish the patient's vocal profile: typical pitch range, speech rate, energy levels, pause patterns
2. Each subsequent conversation is compared against this baseline
3. Statistically significant deviations trigger clinical signals
4. Baseline continuously updates with a decay function to account for natural changes over time
**Why Baseline-Deviation > Absolute Classification:**
* Absolute emotion detection from voice has high error rates across demographics, languages, and cultural contexts
* A patient's "normal" varies enormously — what sounds flat for one person is baseline for another
* Clinical value comes from detecting *change*, not labeling a single state
* This approach reduces demographic bias because each patient is their own reference
### Clinical Signal Detection
**Engagement Signals:**
* Declining speech energy across calls may indicate reduced motivation or treatment fatigue
* Shortened responses and increased pause duration can signal disengagement
* Changes in turn-taking patterns (e.g., patient becomes less interactive) flag engagement risk
**Mood and Affect Signals:**
* Pitch flattening (reduced F0 variability) is associated with depressive episodes in clinical literature
* Increased speech rate with elevated pitch can indicate anxiety or agitation
* Vocal tremor and irregular pause patterns may signal distress
**Discrepancy Detection:**
* When a patient says "I'm doing great" but vocal features indicate flat affect, low energy, or stress markers, the system flags a text-prosody discrepancy
* These discrepancies are surfaced to the clinical team as potential indicators that warrant follow-up
* The conversation agent can adapt its approach in real time — e.g., asking a follow-up question with more empathy, or noting the discrepancy for the clinician
## Research Foundation
HANA's vocal intelligence capabilities originated from a clinical research project analyzing voice patterns in bipolar disorder patients to detect transitions between depressive and manic episodes. Key insights from this work:
* Voice-based features can detect mood state transitions before patients self-report changes
* Longitudinal tracking (baseline-deviation) significantly outperforms single-session emotion classification
* Prosodic features are more reliable than lexical sentiment for detecting clinical state changes
* Combining prosodic analysis with conversational content produces the strongest clinical signals
This research has since been extended to populations including PTSD, chronic pain, palliative care, and geriatric patients — each with specific vocal patterns associated with clinical deterioration or improvement.
## Integration with Safety Guardrails
Vocal intelligence feeds directly into HANA's observational safety agents:
* **Risk escalation**: When vocal features combined with conversation content suggest self-harm risk, the safety agent triggers the clinic's escalation protocol
* **Engagement monitoring**: When vocal patterns suggest a patient is disengaging from a care program, the system can adjust outreach strategy (timing, channel, conversation approach)
* **Clinical notes enrichment**: Post-call clinical notes include vocal engagement indicators, giving clinicians richer context than a transcript alone
## Privacy and Compliance
* Raw audio features are extracted and processed in real time; raw audio is not stored beyond the conversation recording retention period
* Vocal analysis data is classified as PHI and subject to the same encryption, access control, and audit requirements as all patient data
* Patients are informed that conversations are recorded and analyzed as part of their care program
* Vocal profiles are tied to patient records and subject to the same deletion and portability requirements
* On-premises deployments process all vocal analysis locally — no audio data leaves the organization's infrastructure
## Performance Characteristics
| Metric | Value |
| ------------------------------ | --------------------------------------------------------------------------------------------------- |
| Feature extraction latency | \< 200ms (parallel to transcription) |
| Baseline establishment | 2-3 conversations |
| Discrepancy detection accuracy | Validated against clinical reviewer agreement |
| Demographic bias | Reduced through per-patient baseline approach |
| Supported languages | Feature extraction is language-agnostic; clinical validation strongest in English, Spanish, Italian |
# Research
Source: https://docs.hana.health/research/active-research
Active research initiatives, clinical validation studies, and publications from HANA's healthcare AI research program.
## Research Origins
HANA's technology originated from a clinical research project analyzing voice patterns in bipolar disorder patients. The original work focused on detecting transitions between depressive and manic episodes through vocal biomarkers — pitch contour, speech rate variability, energy patterns, and pause dynamics. Key findings from this research informed HANA's vocal intelligence architecture:
* Voice-based features can detect mood state transitions before patients self-report changes
* Longitudinal tracking (baseline-deviation) significantly outperforms single-session emotion classification
* Prosodic features are more reliable than lexical sentiment for detecting clinical state changes
* Combining prosodic analysis with conversational content produces the strongest clinical signals
This work has since been extended to PTSD, chronic pain, palliative care, and geriatric populations — each with specific vocal patterns associated with clinical deterioration or improvement.
## Active Research
### Voice-Based Clinical Conversation Validation
* Ongoing study measuring clinical accuracy of AI-conducted patient conversations compared to human staff
* Evaluation across multiple clinical protocols: intake, chronic care management, behavioral health screening
* Metrics: information extraction accuracy, protocol compliance, patient satisfaction, clinical outcome correlation
### Vocal Biomarker Detection
* Longitudinal analysis of prosodic features as indicators of clinical state change across patient populations
* Baseline-deviation methodology validation across demographics, languages, and clinical conditions
* Integration of vocal intelligence with clinical conversation outcomes for predictive engagement models
### Deliberation Framework Validation
* Systematic evaluation of multi-model deliberation vs. single-model clinical reasoning for conversation planning
* Benchmarking against standard medical evaluation datasets
* Focus on calibration quality, hallucination reduction, and clinical safety margins
### Patient Engagement and Retention
* Longitudinal study tracking patient engagement metrics (completion rates, re-engagement, dropout rates) across voice AI vs. traditional outreach methods
* Analysis of health coaching and accountability companion features on program retention
* Multi-site study across primary care, behavioral health, and specialty organizations
* Measuring downstream clinical outcomes: no-show reduction, care gap closure, medication adherence
### Voice AI Safety in Healthcare
* Research into safety boundaries for autonomous voice-based patient interactions
* Escalation threshold optimization: when should AI defer to humans?
* Adversarial testing for rule-based safety agents, including compound risk signal detection
* Assessment of text-prosody discrepancy detection as a clinical safety signal
## Publications
Research publications will be made available as studies are completed and peer-reviewed. Current work is in preparation for submission to healthcare informatics and clinical AI journals.
## Research Partnerships
HANA collaborates with healthcare organizations and academic institutions on clinical AI research. Contact [research@hana.health](mailto:research@hana.health) for partnership inquiries.
# Cyber-Intelligence Overview
Source: https://docs.hana.health/security/cyber-intelligence
Enterprise-grade security standards with comprehensive compliance certifications, defense-in-depth architecture, and AI-specific safety controls.
## Overview
HANA maintains enterprise-grade security standards with comprehensive compliance certifications, including SOC 2 Type II, HIPAA, and GDPR. Our platform leverages cloud infrastructure to provide robust encryption, secure communications, and continuous monitoring, ensuring optimal data protection for healthcare customers.
### Compliance Certifications
| Certification | Status | Coverage | Scope |
| ------------- | ------------------------------------------------------------------ | --------------------------------------- | ---------------------------------------------------------------------------------- |
| SOC 2 Type II | ✅ Audited controls for security, availability, and confidentiality | Complete annual cycle audit | Comprehensive evaluation of trust service principles |
| HIPAA | ✅ Continuously monitored | US healthcare data privacy regulations | Essential for healthcare providers, insurers, and medical technology |
| GDPR | ✅ Continuously monitored | EU personal data protection and privacy | Global compliance for handling EU citizen data with privacy-by-design architecture |
## Security Architecture
### Multi-layered Defense Strategy
Our cyber-intelligence framework implements multiple layers of defense to ensure comprehensive protection:
1. **Perimeter Security**: Advanced threat detection at network boundaries using intrusion detection/prevention systems
2. **Infrastructure Security**: Hardened cloud infrastructure with restricted access controls
3. **Application Security**: Secure development practices with regular code audits and vulnerability assessments
4. **Data Security**: End-to-end encryption with sophisticated key management
5. **Operational Security**: Continuous monitoring with real-time alerts and automated remediation
### Data Encryption
All data within the HANA platform is protected using industry-leading encryption standards:
* **Storage Encryption**: AES-256 with cloud-managed encryption keys
* **Communication Encryption**: TLS 1.3 enforced for all traffic
* **Key Management**: Cloud KMS integration with strict access controls
* **PHI Protection**: Special handling for protected health information with additional encryption layers
### Network Security
* **Protocol Security**: HTTPS enforced across all endpoints
* **SSL Configuration**: Comprehensive SSL certificate deployment
* **Traffic Protection**: End-to-end encrypted communications
* **API Security**: Rate limiting, token-based authentication, and request validation
### Service Architecture Integration
HANA's cyber-intelligence capabilities are deeply integrated with our service architecture:
1. **Service Mesh Security**: Secure service-to-service communication with mutual TLS
2. **Zero Trust Implementation**: Verification of every request regardless of source
3. **Centralized Policy Enforcement**: Consistent security policies across all services
4. **Observability**: Comprehensive logging and monitoring for security events
## AI-Specific Security Controls
### Model Safety Mechanisms
HANA implements specialized security controls for AI components:
1. **Input Sanitization**: Advanced filtering to prevent prompt injection and other attacks on conversation engine
2. **Output Monitoring**: Automated content scanning for sensitive information leakage in voice responses
3. **Runtime Isolation**: Containerized execution environments for model inference
4. **Model Versioning**: Strict version control with cryptographic verification for all model artifacts
5. **AI Vulnerability Management**: Dedicated monitoring for AI-specific threats
### LLM Safety Framework
* **Jailbreak Prevention**: Constrained generation architecture prevents conversation engine from operating outside protocol boundaries
* **Continuous Validation**: Automated testing against known attack vectors for voice AI systems
* **Red Team Exercises**: Regular adversarial testing focused on clinical AI vulnerabilities
* **Content Filtering**: Multi-stage filtering for harmful or clinically inappropriate outputs
## Security Controls Framework
HANA maintains a comprehensive security controls framework across multiple domains:
**Access Control & Authorization (30+ Controls)**
* Comprehensive access control procedures
* Infrastructure modification restrictions
* Regular access reviews and audits
* Role-based access control with least privilege principles
**Data Privacy & Security (60+ Controls)**
* Comprehensive data protection procedures
* Anonymization and pseudonymization processes
* Data retention and disposal policies
* Secure data transfer mechanisms
**Risk & Incident Management (30+ Controls)**
* Incident response procedures
* Risk assessment frameworks
* Vendor risk management
* Business continuity planning
**IT & Operational Security (25+ Controls)**
* Application monitoring and alerting
* Asset management procedures
* Disaster recovery planning
* Change management processes
## EU AI Act Compliance
The European Union's AI Act classifies AI systems that affect access to healthcare as **high-risk applications**. This includes AI systems involved in patient triage, clinical decision support, prior authorization, and any scenario where an AI output could influence a patient's access to care.
### Current Status
HANA is actively working toward full EU AI Act compliance for healthcare deployments in Europe:
* **Risk classification assessment**: Mapping HANA's capabilities against the AI Act's high-risk categories to determine registration requirements per use case
* **Conformity assessment preparation**: Documenting technical architecture, safety measures, and quality management systems required for high-risk AI registration
* **EU database registration**: Preparing for registration in the EU database of high-risk AI systems as required before production deployment with EU patients
### Use Case-Specific Classification
Not all HANA deployments carry the same regulatory classification under the AI Act:
| Use Case | AI Act Classification | Registration Required |
| ------------------------------------------------- | --------------------- | --------------------- |
| Appointment reminders, scheduling | Lower risk | No |
| Pre-operative preparation follow-up | Lower risk | No |
| Clinical screening (PHQ-9, GAD-7) | Potentially high risk | Under assessment |
| Prior authorization / insurance verification | High risk | Yes |
| Clinical decision support influencing care access | High risk | Yes |
### What This Means for EU Customers
* **Non-high-risk use cases** (appointment management, preparation reminders, general outreach) can proceed under standard GDPR compliance
* **High-risk use cases** (anything involving clinical decisions that affect care access) require HANA to be registered in the EU AI Act database before production deployment — including POC/pilot phases with live patients
* HANA works with EU customers during scoping to classify the intended use case and determine the regulatory pathway
For EU healthcare organizations evaluating HANA: we recommend discussing your intended use case during the scoping phase so we can provide a clear regulatory timeline. Some use cases can proceed immediately; others require registration that we are actively pursuing.
***
## Contact Information
For security inquiries or compliance requests:
* Security Team Email: [security@hana.health](mailto:security@hana.health)
* Response Time: Standard business hours
* Documentation Access: Available upon request through our trust center
# Encryption
Source: https://docs.hana.health/security/encryption
Comprehensive encryption standards for data at rest, in transit, and key management across HANA's infrastructure.
## Data Encryption
* **Storage Encryption**: AES-256 with cloud-managed encryption keys for all stored data
* **Communication Encryption**: TLS 1.3 enforced for all traffic between services and external endpoints
* **Key Management**: Cloud KMS integration with strict access controls and automatic key rotation
* **Reference**: Industry-standard encryption policies aligned with NIST guidelines
## Network Security
* **Protocol**: HTTPS enforced across all endpoints — no unencrypted communication permitted
* **SSL Configuration**: Comprehensive SSL certificate deployment with automatic renewal
* **Traffic Protection**: End-to-end encrypted communications between all system components
* **Voice Data**: Real-time voice streams encrypted in transit via SRTP (Secure Real-time Transport Protocol)
## Infrastructure Security
* **Cloud Provider**: Healthcare-grade cloud infrastructure with executed BAA
* **Architecture**: Multi-service microservices architecture with service mesh encryption (mutual TLS)
* **Access Control**: Restricted infrastructure modification access with MFA and audit logging
* **Monitoring**: Real-time alerts and automated remediation for security events
## Conversation Data Encryption
* **Voice recordings**: Encrypted at rest using AES-256 immediately upon capture
* **Transcripts**: Encrypted in storage and during processing pipeline
* **Clinical extractions**: Structured data encrypted at field level for sensitive PHI elements
* **EHR data cache**: Encrypted in-memory cache with automatic expiration and secure clearing
# Handling PHI
Source: https://docs.hana.health/security/handling-phi
Framework for secure handling of Protected Health Information across its entire lifecycle: collection, access, storage, monitoring, and disposal.
## Overview
This framework covers five key areas: obtaining explicit consent and collecting only minimum necessary data, implementing role-based access controls with multi-factor authentication, securely storing and segregating PHI in cloud environments, monitoring for anomalies with incident response procedures, and establishing clear retention and disposal policies. These measures work together to ensure PHI is handled securely throughout its entire lifecycle while maintaining regulatory compliance.
## Data Collection & Consent
* Explicit consent mechanisms integrated into patient conversation workflows — patients are informed they are speaking with an AI and given the option to opt out
* Transparent privacy policies clearly communicating data use and conversation recording
* Only minimum necessary PHI collected per HIPAA regulations — conversations follow protocol-defined data collection scope
* Conversation recording consent obtained at the start of each interaction per applicable state regulations
## Data Access Management
* **Role-based access control (RBAC)** limiting PHI access strictly to necessary personnel — clinical teams see conversation outcomes, engineering teams see anonymized metrics
* **Mandatory Multi-Factor Authentication (MFA)** for all accounts with PHI access
* **Regular audits** of access logs and reviews of privileges, ensuring minimum necessary access
* **Time-limited access**: Temporary access grants for troubleshooting expire automatically
* **Break-glass procedures**: Emergency access with mandatory post-access review
## PHI Storage & Segregation
* **Logical separation** of PHI in cloud storage environments to isolate sensitive data from general workloads
* **Robust tagging and classification** of PHI for easy auditing, retrieval, and management
* **Tenant isolation**: Patient data from different healthcare organizations stored in separate encrypted partitions
* **Conversation recordings** stored with AES-256 encryption in healthcare-grade cloud storage with access logging
* **Structured clinical data** (extracted entities, screening scores) stored in encrypted databases with row-level access controls
## Monitoring & Incident Response
* **Real-time monitoring** with automated alerts specific to PHI handling anomalies
* **Defined and documented** PHI-specific incident response plan compliant with HIPAA breach notification rule
* **Regular vulnerability scanning** and penetration tests specifically targeting PHI repositories
* **Conversation pipeline monitoring**: Automated detection of unexpected PHI exposure in logs or system outputs
* **Anomaly detection**: Unusual access patterns (volume, timing, geography) trigger immediate investigation
## PHI Disposal & Retention Policies
* **Clearly defined PHI retention policies** in compliance with HIPAA requirements and state-specific regulations
* **Secure and documented procedures** for PHI disposal including permanent deletion and secure destruction
* **Conversation recording retention**: Configurable per healthcare organization with automated expiration
* **De-identification pipeline**: PHI can be de-identified for analytics and quality improvement while original records are disposed
* **Disposal audit trail**: Every deletion operation logged with timestamp, authorization, and verification
# Incidents / Policy Handling
Source: https://docs.hana.health/security/incidents-policy
Disaster recovery, business continuity, incident response procedures, and operational monitoring for HANA's clinical AI platform.
## Disaster Recovery & Business Continuity
### Backup Strategy
* **Automated Backups**: Daily automated backups with point-in-time recovery for all critical data
* **Cross-Region Replication**: Geographic distribution for disaster recovery — conversation data replicated across availability zones
* **Backup Testing**: Regular restore testing and validation on quarterly schedule
* **Retention Policies**: Configurable retention based on compliance requirements and healthcare organization policies
### High Availability
* **Multi-Zone Deployment**: Services deployed across multiple availability zones for fault tolerance
* **Auto-Scaling**: Horizontal and vertical scaling based on concurrent call volume and time-of-day patterns
* **Circuit Breakers**: Automatic failure detection and isolation — degraded service doesn't cascade to other components
* **Health Checks**: Continuous health monitoring with automatic remediation and service restart
### Incident Response
* **Runbooks**: Documented procedures for common incidents (EHR connectivity loss, voice service degradation, model performance issues)
* **On-Call Rotation**: 24/7 coverage with defined escalation procedures
* **Post-Incident Reviews**: Blameless postmortems with documented action items and follow-through tracking
* **Mean Time to Recovery**: Target MTTR of less than 30 minutes for critical issues affecting live patient conversations
### Risk & Incident Management
* **Incident response procedures**: Severity classification, communication templates, and resolution workflows
* **Risk assessment frameworks**: Regular risk assessments covering infrastructure, data, and AI-specific risks
* **Vendor risk management**: Third-party vendor security assessments and ongoing monitoring
### Operational Monitoring
* **Status**: Live monitoring with 24/7 coverage
* **Coverage**: Infrastructure, application, and conversation quality monitoring
* **Response**: Automated remediation systems for known failure patterns
* **Escalation**: Defined incident response procedures with clear ownership
## Security Team Contact
* Email: [security@hana.health](mailto:security@hana.health)
* Purpose: Security inquiries, compliance requests, and incident reporting
* Response Time: Standard business hours; critical security incidents receive immediate response
# On Premises
Source: https://docs.hana.health/security/on-premises
On-premises deployment options for healthcare organizations requiring data residency, isolated model hosting, and full operational control.
## Overview
On-premises infrastructure plays a critical role in enhancing safety for healthcare applications by ensuring that sensitive patient data remains within the provider's secure environment. By reducing reliance on external cloud services, on-premises deployments minimize potential exposure to third-party breaches and enable tighter access control. This localized, encrypted setup supports compliance with healthcare regulations and gives organizations full authority over data handling, retention, and auditability.
### Data Residency & Compliance
* On-premises deployments ensure PHI and sensitive health data never leave the provider's infrastructure, supporting strict compliance with HIPAA and region-specific regulations
* Conversation recordings, transcripts, and extracted clinical data stored entirely within the organization's data center
* Supports healthcare organizations with strict data sovereignty requirements that prohibit cloud-based PHI processing
### Isolated Model Hosting
* Self-hosted AI models and inference systems run within provider-controlled environments, eliminating third-party cloud exposure and reducing attack surfaces
* Conversation engine and reasoning engine deployed on organization-managed hardware
* Voice processing (speech recognition and synthesis) can run locally for complete data isolation
* Supports encrypted inference for secure data processing during model execution
On-premises deployment requires dedicated infrastructure provisioning. The reasoning engine requires GPU-equipped servers (minimum specifications provided during scoping). Voice processing adds additional compute requirements. HANA provides a detailed hardware requirements guide and works with your IT team to validate infrastructure readiness before deployment. Typical on-premises deployments take 6-10 weeks including infrastructure setup, compared to 2-4 weeks for cloud deployments.
### Operational Control & Auditability
* Providers retain full control over data access, retention, and key management, with the ability to define deletion schedules or revoke access instantly
* All infrastructure is auditable and designed to meet healthcare-grade standards for system integrity, access logging, and redundancy
* Organization's IT team manages updates, patches, and security configurations on their own schedule
* Complete visibility into all data flows and processing operations
## On-Premises Architecture
**Deployment Components:**
* Container orchestration (Kubernetes) running on organization-managed servers
* GPU nodes for reasoning engine inference (HANA provides minimum hardware specifications; organizations may need to provision dedicated GPU infrastructure)
* CPU nodes for real-time conversation engine
* Local telephony integration with organization's existing phone system (SIP trunking)
* Local database and storage for all conversation data
**Network Configuration:**
* No outbound data transmission of PHI — all processing happens locally
* Optional secure tunnel for model updates and system patches (no patient data transmitted)
* Integration with organization's existing network security infrastructure
* Compatible with organization's VPN and firewall configurations
**Hybrid Options (recommended for most on-prem customers):**
* On-premises data processing with cloud-based model updates (no PHI leaves premises) — most common configuration
* Conversation execution on-premises with anonymized analytics sent to cloud for quality monitoring
* Full air-gapped deployment for maximum isolation — requires additional infrastructure planning and limits model update frequency