heartvoice ECG Analysis Skill

Analyze ECG data via the heartvoice (心之声) cloud API. The agent is responsible for detecting user intent (1-lead vs 12-lead) and language (Chinese vs English), then passing the appropriate explicit flags to the CLI script. The script itself requires explicit --mode and --lang parameters — all "automatic" behavior lives in the agent layer, not the script.

When to Activate

• User wants to analyze ECG / heart rhythm / electrocardiogram data
• User provides a JSON file containing ECG signal data
• Code or conversation mentions 心电图, ECG, 心电分析, 心律分析
• Keywords: 单导联, 十二导联, 1-lead, 12-lead, single lead, twelve lead
• User asks about arrhythmia detection, QRS/QT intervals, or signal quality
• User says "analyze ECG", "分析心电", "ecg diagnosis", or similar

Environment Setup

# Required — get your key at https://www.heartvoice.com.cn/aiCloud
export HEARTVOICE_API_KEY="your_api_key"

# Install dependencies
pip install requests

Never hardcode API keys. Always use environment variables or .env files.

Agent Responsibilities

The agent (not the CLI script) is responsible for two kinds of detection:

1. Detect analysis type → pass as CLI mode

Scan the user message for keywords and map to the explicit CLI mode argument:

If the user does not specify a type, ask before running the script:

• Chinese: "请问您要分析的是单导联信号还是十二导联信号？"
• English: "Would you like to analyze a single-lead or 12-lead signal?"

2. Detect user language → pass as --lang flag

Detect the language the user writes in and pass it as the --lang CLI flag:

Then respond entirely in that language throughout the session.

Workflow

1. Agent detects analysis type (1-lead / 12-lead) from user message keywords. If ambiguous, ask.
2. Agent detects user language (zh / en) from the message.
3. Agent extracts file path from the user message.
4. Agent runs the CLI script with explicit arguments: python3 scripts/call_api.py --json_path --lang .
5. Agent parses the structured JSON output from stdout.
6. Agent presents the result as a natural-language report in the user's language.

Script Commands

# 1-lead signal analysis (Chinese output)
python3 scripts/call_api.py 1-lead --json_path <path/to/file.json>

# 1-lead signal analysis (English output)
python3 scripts/call_api.py 1-lead --json_path <path/to/file.json> --lang en

# 12-lead signal analysis (Chinese output)
python3 scripts/call_api.py 12-lead --json_path <path/to/file.json>

# 12-lead signal analysis (English output)
python3 scripts/call_api.py 12-lead --json_path <path/to/file.json> --lang en

Set --lang zh (default) or --lang en based on the language the user writes in.

Input File Formats

ADC Conversion Formula

The data arrays contain raw sample values from your recording device (integers or floats, depending on the device). The API internally converts them to millivolts (mV) using:

voltage_mV = (sampleValue - adcZero) / adcGain

• adcZero — the sample value that corresponds to 0 mV (baseline offset)
• adcGain — the number of sample units per 1 mV

Example 1 (integer samples): adcGain = 1000, adcZero = 0, sample = 512 → voltage = (512 - 0) / 1000 = 0.512 mV.

Example 2 (float samples, already in mV): if your device outputs values already in millivolts (e.g. 0.512), set adcGain = 1.0 and adcZero = 0.0 so the formula becomes a no-op: voltage = (0.512 - 0) / 1 = 0.512 mV.

These two parameters must match your recording device's output configuration; incorrect values will produce wrong voltage readings and unreliable diagnoses.

1-lead JSON

{
  "ecgData": [0.512, 0.515, 0.520, 0.518, 0.525, 0.530, 0.528, 0.535],
  "ecgSampleRate": 500,
  "adcGain": 1.0,
  "adcZero": 0.0
}

In this example, values are already in mV, so adcGain = 1.0 and adcZero = 0.0 (identity conversion). If your device outputs raw integer ADC values instead, adjust adcGain and adcZero accordingly.

12-lead JSON

{
  "dataI":   [...], "dataII":  [...], "dataIII": [...],
  "dataAVR": [...], "dataAVL": [...], "dataAVF": [...],
  "dataV1":  [...], "dataV2":  [...], "dataV3":  [...],
  "dataV4":  [...], "dataV5":  [...], "dataV6":  [...],
  "ecgSampleRate": 500,
  "adcGain": 1000.0,
  "adcZero": 0.0
}

In this example, values are raw integer ADC samples with adcGain = 1000 (1000 units = 1 mV).

Response Format

The fields below are the script's output (printed to stdout as JSON). The script normalizes the API's camelCase field names (e.g. avgHr, avgQrs, isAbnormal) to snake_case (e.g. avg_hr, avg_qrs, is_abnormal) for consistency. When reading the script output, always use the snake_case names listed here.

1-lead response fields

12-lead response fields

Examples

Example 1 — Chinese user, single-lead

> 用户：请帮我分析这个单导联信号，数据放在 data/ecg_data.json 里

Agent runs:

python3 scripts/call_api.py 1-lead --json_path data/ecg_data.json --lang zh

Output:

{
  "status": "success",
  "summary": "检测到：窦性心律。平均心率 72 次/分钟，QRS 宽度 86 毫秒，PR 间期 156 毫秒，QT 间期 380 毫秒，QTc 412 毫秒，P 波宽度 102 毫秒。信号质量 0.95。房性早搏 0 次，室性早搏 0 次。",
  "diagnosis": ["SN"],
  "possible_diagnosis": [],
  "is_abnormal": false,
  "avg_hr": 72,
  "sq_grade": "0.95"
}

Agent responds:

> 分析完成。该心电信号显示窦性心律，平均心率 72 次/分钟，各项参数均在正常范围内。信号质量评分 0.95（优秀），未检测到房性或室性早搏。

Example 2 — English user, 12-lead

> User: Analyze my 12-lead ECG data from records/12lead.json

Agent runs:

python3 scripts/call_api.py 12-lead --json_path records/12lead.json --lang en

Output:

{
  "status": "success",
  "summary": "Detected: Sinus Rhythm. Heart rate 75 bpm, QRS duration 88 ms, PR interval 160 ms, QT interval 376 ms, QTc 420 ms, P wave 100 ms, T wave 180 ms. Risk assessment: normal.",
  "diagnoses": [{"label": "SN", "result": "Sinus Rhythm", "description": "Normal sinus rhythm"}],
  "risk_level": 0,
  "HR": 75
}

Agent responds:

> Analysis complete. The 12-lead ECG shows Sinus Rhythm with a heart rate of 75 bpm. All intervals are within normal range. Risk level: normal (0).

Example 3 — Ambiguous intent

> User: Can you analyze this ECG for me? The file is at data/signal.json

Agent asks:

> Would you like to analyze a single-lead (1-lead) or 12-lead signal?

Error Handling

Security & Privacy

Data flow: This skill reads a user-specified local JSON file and sends its contents (ECG signal data, sample rate, ADC parameters) over HTTPS to the heartvoice cloud API (api.heartvoice.com.cn) for analysis. The user should be aware that their ECG data leaves the local machine. No other files or environment variables beyond HEARTVOICE_API_KEY are accessed.

• Never hardcode API keys in scripts or commit them to version control
• ECG data is sensitive medical data — do not log or store raw signal data unnecessarily; inform the user before transmitting
• Always use HTTPS (the API endpoint enforces TLS)
• Add .env to .gitignore if using dotenv files
• The skill only reads the file path explicitly provided by the user — it does not scan or access other files
• This tool provides AI-assisted analysis only; it is NOT a substitute for professional medical diagnosis

Tips

• Signal quality (sq_grade) below 0.6 usually indicates noisy data — suggest the user re-record or check electrode contact
• For 12-lead analysis, all 12 lead arrays must be present; partial data will fail field validation
• The adcGain and adcZero values must match your recording device's ADC configuration — see the ADC Conversion Formula section for how they translate raw samples to millivolts
• JSON file size limit is 5 MB
• Typical ecgSampleRate values: 250, 500, 1000 Hz — check your device specs
• Use the example files in data/ to verify your setup before analyzing real signals

Programmatic Usage

You can also import the script functions directly in Python:

import os
from scripts.call_api import load_json, build_1lead_payload, call_api, format_1lead_result

api_key = os.environ["HEARTVOICE_API_KEY"]
data = load_json("data/example_1lead.json")
payload = build_1lead_payload(data)
raw_result = call_api(
    "https://api.heartvoice.com.cn/api/v1/basic/ecg/1-lead/analyze",
    payload, api_key
)
output = format_1lead_result(raw_result)
print(output["summary"])
print(f"Heart rate: {output['avg_hr']} bpm")