AmbiqAI · apage224 · Jan 16, 2026 · Jan 16, 2026 · Jan 16, 2026
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -1,9 +1,9 @@
-name: HeartKit CI
+name: heartKIT CI
 
 on: [push]
 
 env:
-  PYTHON_VERSION: '3.11'
+  PYTHON_VERSION: '3.12'
 
 jobs:
   build:

diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
@@ -8,12 +8,20 @@ on:
       - "v*"
   workflow_dispatch:
 
+env:
+  PACKAGE_NAME: heartkit
+  PYTHON_VERSION: "3.12"
+
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout 🛎️
         uses: actions/checkout@v4
+      - name: Setup Python 🐍
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
       - name: Install uv
         uses: astral-sh/setup-uv@v5
         with:
@@ -33,7 +41,7 @@ jobs:
       - build
     environment:
       name: pypi
-      url: https://pypi.org/p/heartkit
+      url: https://pypi.org/p/${{ env.PACKAGE_NAME }}
     permissions:
       id-token: write
     steps:

diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,7 @@
+# AGENTS
+
+Repo-specific notes for automation and maintenance:
+- Python target is 3.12; use `uv sync` for installs and `uv run pytest tests/` for tests.
+- Docs use MkDocs Material; preview with `mkdocs serve` and keep headings plain Markdown (no span wrappers).
+- Prefer `rg` for searches and avoid touching binary assets unless requested.
+- Commit messages follow Conventional Commits (e.g., `feat: ...`, `fix: ...`, `chore: ...`).
diff --git a/README.md b/README.md
@@ -1,29 +1,26 @@
 
-<p align="center">
-  <a href="https://github.com/AmbiqAI/heartkit"><img src="./docs/assets/heartkit-banner.png" alt="HeartKit"></a>
-</p>
+# heartKIT
 
----
-
-**Documentation**: <a href="https://ambiqai.github.io/heartkit" target="_blank">https://ambiqai.github.io/heartkit</a>
+> An AI Development Kit for real-time heart-monitoring on ultra-low power SoCs
 
-**Source Code**: <a href="https://github.com/AmbiqAI/heartkit" target="_blank">https://github.com/AmbiqAI/heartkit</a>
+[![CI](https://github.com/AmbiqAI/heartkit/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/AmbiqAI/heartkit/actions/workflows/ci.yaml)
+[![Docs](https://github.com/AmbiqAI/heartkit/actions/workflows/docs.yaml/badge.svg?branch=main)](https://github.com/AmbiqAI/heartkit/actions/workflows/docs.yaml)
+[![Release](https://github.com/AmbiqAI/heartkit/actions/workflows/release.yaml/badge.svg?branch=main)](https://github.com/AmbiqAI/heartkit/actions/workflows/release.yaml)
 
----
 
-HeartKit is an AI Development Kit (ADK) that enables developers to easily train and deploy real-time __heart-monitoring__ models onto [Ambiq's family of ultra-low power SoCs](https://ambiq.com/soc/). The kit provides a variety of datasets, efficient model architectures, and heart-related tasks. In addition, HeartKit provides optimization and deployment routines to generate efficient inference models. Finally, the kit includes a number of pre-trained models and task-level demos to showcase the capabilities.
+heartKIT is an AI Development Kit (ADK) that enables developers to easily train and deploy real-time __heart-monitoring__ models onto [Ambiq's family of ultra-low power SoCs](https://ambiq.com/soc/). The kit provides a variety of datasets, efficient model architectures, and heart-related tasks. In addition, heartKIT provides optimization and deployment routines to generate efficient inference models. Finally, the kit includes a number of pre-trained models and task-level demos to showcase the capabilities.
 
 **Key Features:**
 
 * **Real-time**: Inference is performed in real-time on battery-powered, edge devices.
 * **Efficient**: Leverage Ambiq's ultra low-power SoCs for extreme energy efficiency.
 * **Extensible**: Easily add new tasks, models, and datasets to the framework.
-* **Open Source**: HeartKit is open source and available on GitHub.
+* **Open Source**: heartKIT is open source and available on GitHub.
 
 
-## <span class="sk-h2-span">Requirements
+## Requirements
 
-* [Python ^3.11+](https://www.python.org)
+* [Python ^3.12+](https://www.python.org)
 * [uv ^1.6.1+](https://docs.astral.sh/uv/getting-started/installation/)
 
 The following are also required to compile/flash the binary for the EVB demo:
@@ -34,7 +31,7 @@ The following are also required to compile/flash the binary for the EVB demo:
 !!! note
     A [VSCode Dev Container](https://code.visualstudio.com/docs/devcontainers/containers) is also available and defined in [./.devcontainer](https://github.com/AmbiqAI/heartkit/tree/main/.devcontainer).
 
-## <span class="sk-h2-span">Installation</span>
+## Installation
 
 To get started, first install the local python package `heartkit` along with its dependencies via `PyPi`:
 
@@ -52,15 +49,15 @@ uv sync
 
 ---
 
-## <span class="sk-h2-span">Usage</span>
+## Usage
 
-__HeartKit__ can be used as either a CLI-based tool or as a Python package to perform advanced development. In both forms, HeartKit exposes a number of modes and tasks outlined below. In addition, by leveraging highly-customizable configurations, HeartKit can be used to create custom workflows for a given application with minimal coding. Refer to the [Quickstart](https://ambiqai.github.io/heartkit/quickstart/) to quickly get up and running in minutes.
+__heartKIT__ can be used as either a CLI-based tool or as a Python package to perform advanced development. In both forms, heartKIT exposes a number of modes and tasks outlined below. In addition, by leveraging highly-customizable configurations, heartKIT can be used to create custom workflows for a given application with minimal coding. Refer to the [Quickstart](https://ambiqai.github.io/heartkit/quickstart/) to quickly get up and running in minutes.
 
 ---
 
-## <span class="sk-h2-span">Tasks</span>
+## Tasks
 
-__HeartKit__ includes a number of built-in **tasks**. Each task provides reference routines for training, evaluating, and exporting the model. The routines can be customized by providing a configuration file or by setting the parameters directly in the code. Additional tasks can be easily added to the __HeartKit__ framework by creating a new task class and registering it to the __task factory__.
+__heartKIT__ includes a number of built-in **tasks**. Each task provides reference routines for training, evaluating, and exporting the model. The routines can be customized by providing a configuration file or by setting the parameters directly in the code. Additional tasks can be easily added to the __heartKIT__ framework by creating a new task class and registering it to the __task factory__.
 
 - **Denoise**: Remove noise and artifacts from signals
 - **Segmentation**: Perform ECG/PPG based segmentation
@@ -70,9 +67,9 @@ __HeartKit__ includes a number of built-in **tasks**. Each task provides referen
 
 ---
 
-## <span class="sk-h2-span">Modes</span>
+## Modes
 
-__HeartKit__ provides a number of **modes** that can be invoked for a given task. These modes can be accessed via the CLI or directly from the `task` within the Python package.
+__heartKIT__ provides a number of **modes** that can be invoked for a given task. These modes can be accessed via the CLI or directly from the `task` within the Python package.
 
 - **Download**: Download specified datasets
 - **Train**: Train a model for specified task and datasets
@@ -82,23 +79,23 @@ __HeartKit__ provides a number of **modes** that can be invoked for a given task
 
 ---
 
-## <span class="sk-h2-span">Datasets</span>
+## Datasets
 
-__HeartKit__ exposes several open-source datasets for training each of the HeartKit tasks via a __dataset factory__. For certain tasks, we also provide synthetic data provided by [PhysioKit](https://ambiqai.github.io/physiokit) to help improve model generalization. Each dataset has a corresponding Python class to aid in downloading and generating data for the given task. Additional datasets can be easily added to the HeartKit framework by creating a new dataset class and registering it to the dataset factory.
+__heartKIT__ exposes several open-source datasets for training each of the heartKIT tasks via a __dataset factory__. For certain tasks, we also provide synthetic data provided by [physioKIT](https://ambiqai.github.io/physiokit) to help improve model generalization. Each dataset has a corresponding Python class to aid in downloading and generating data for the given task. Additional datasets can be easily added to the heartKIT framework by creating a new dataset class and registering it to the dataset factory.
 
 * **Icentia11k**: 11-lead ECG data collected from 11,000 subjects captured continously over two weeks.
 * **LUDB**: 200 ten-second 12-lead ECG records w/ annotated P-wave, QRS, and T-wave boundaries.
 * **QTDB**: 100+ fifteen-minute two-lead ECG recordings w/ annotated P-wave, QRS, and T-wave boundaries.
 * **LSAD**: 10-second, 12-lead ECG dataset collected from 45,152 subjects w/ over 100 scp codes.
 * **PTB-XL**: 10-second, 12-lead ECG dataset collected from 18,885 subjects w/ 72 different diagnostic classes.
-* **Synthetic**: A synthetic dataset generator from [PhysioKit](https://ambiqai.github.io/physiokit).
+* **Synthetic**: A synthetic dataset generator from [physioKIT](https://ambiqai.github.io/physiokit).
 * **BYOD**: Bring-Your-Own-Dataset (BYOD) to add additional datasets.
 
 ---
 
-## <span class="sk-h2-span">Models</span>
+## Models
 
-__HeartKit__ provides a __model factory__ that allows you to easily create and train customized models. The model factory includes a number of modern networks well suited for efficient, real-time edge applications. Each model architecture exposes a number of high-level parameters that can be used to customize the network for a given application. These parameters can be set as part of the configuration accessible via the CLI and Python package.
+__heartKIT__ provides a __model factory__ that allows you to easily create and train customized models. The model factory includes a number of modern networks well suited for efficient, real-time edge applications. Each model architecture exposes a number of high-level parameters that can be used to customize the network for a given application. These parameters can be set as part of the configuration accessible via the CLI and Python package.
 
 - **[TCN](https://ambiqai.github.io/helia-edge/api/helia_edge/models/tcn)**: A CNN leveraging dilated convolutions (key=`tcn`)
 - **[U-Net](https://ambiqai.github.io/helia-edge/api/helia_edge/models/unet)**: A CNN with encoder-decoder architecture for segmentation tasks (key=`unet`)
@@ -113,14 +110,14 @@ __HeartKit__ provides a __model factory__ that allows you to easily create and t
 
 ---
 
-## <span class="sk-h2-span">Model Zoo</span>
+## Model Zoo
 
-A number of pre-trained models are available for each task. These models are trained on a variety of datasets and are optimized for deployment on Ambiq's ultra-low power SoCs. In addition to providing links to download the models, __HeartKit__ provides the corresponding configuration files and performance metrics. The configuration files allow you to easily retrain the models or use them as a starting point for a custom model. Furthermore, the performance metrics provide insights into the model's accuracy, precision, recall, and F1 score. For a number of the models, we provide experimental and ablation studies to showcase the impact of various design choices. Check out the [Model Zoo](https://ambiqai.github.io/heartkit/zoo) to learn more about the available models and their corresponding performance metrics.
+A number of pre-trained models are available for each task. These models are trained on a variety of datasets and are optimized for deployment on Ambiq's ultra-low power SoCs. In addition to providing links to download the models, __heartKIT__ provides the corresponding configuration files and performance metrics. The configuration files allow you to easily retrain the models or use them as a starting point for a custom model. Furthermore, the performance metrics provide insights into the model's accuracy, precision, recall, and F1 score. For a number of the models, we provide experimental and ablation studies to showcase the impact of various design choices. Check out the [Model Zoo](https://ambiqai.github.io/heartkit/zoo) to learn more about the available models and their corresponding performance metrics.
 
 ---
 
-## <span class="sk-h2-span">Guides</span>
+## Guides
 
-Checkout the [Guides](https://ambiqai.github.io/heartkit/guides) to see detailed examples and tutorials on how to use HeartKit for a variety of tasks. The guides provide step-by-step instructions on how to train, evaluate, and deploy models for a given task. In addition, the guides provide insights into the design choices and performance metrics for the models. The guides are designed to help you get up and running quickly and to provide a deeper understanding of the models and tasks available in HeartKit.
+Checkout the [Guides](https://ambiqai.github.io/heartkit/guides) to see detailed examples and tutorials on how to use heartKIT for a variety of tasks. The guides provide step-by-step instructions on how to train, evaluate, and deploy models for a given task. In addition, the guides provide insights into the design choices and performance metrics for the models. The guides are designed to help you get up and running quickly and to provide a deeper understanding of the models and tasks available in heartKIT.
 
 ---
diff --git a/docs/assets/favicon.png b/docs/assets/favicon.png
diff --git a/docs/assets/heartkit-icon-color.png b/docs/assets/heartkit-icon-color.png
diff --git a/docs/assets/heartkit-logo-dark.png b/docs/assets/heartkit-logo-dark.png
diff --git a/docs/assets/heartkit-logo-light.png b/docs/assets/heartkit-logo-light.png
diff --git a/docs/assets/logo-white.png b/docs/assets/logo-white.png
diff --git a/docs/assets/logo.png b/docs/assets/logo.png
diff --git a/docs/assets/tasks/rhythm/rhythm-demo.html b/docs/assets/tasks/rhythm/rhythm-demo.html
diff --git a/docs/assets/tasks/segmentation/segmentation-demo.html b/docs/assets/tasks/segmentation/segmentation-demo.html
diff --git a/docs/css/custom.css b/docs/css/custom.css
@@ -207,3 +207,7 @@ th, td {
   font-size: 24px;
   font-weight: 300;
 }
+
+.md-typeset h2 {
+  color: #F52543;
+}
diff --git a/docs/datasets/byod.md b/docs/datasets/byod.md
@@ -1,8 +1,8 @@
 # Bring-Your-Own-Dataset (BYOD)
 
-The Bring-Your-Own-Dataset (BYOD) feature allows users to add custom datasets for training and evaluating models. This feature is useful when working with proprietary or custom datasets that are not available in the HeartKit library.
+The Bring-Your-Own-Dataset (BYOD) feature allows users to add custom datasets for training and evaluating models. This feature is useful when working with proprietary or custom datasets that are not available in the heartKIT library.
 
-## <span class="sk-h2-span">How it Works</span>
+## How it Works
 
 1. **Create a Dataset**: Define a new dataset that inherits `HKDataset` and implements the required abstract methods.
 

diff --git a/docs/datasets/icentia11k.md b/docs/datasets/icentia11k.md
@@ -1,12 +1,12 @@
 # Icentia11k Dataset
 
-## <span class="sk-h2-span">Overview</span>
+## Overview
 
 This dataset consists of ECG recordings from 11,000 patients and 2 billion labelled beats. The data was collected by the CardioSTAT, a single-lead heart monitor device from Icentia. The raw signals were recorded with a 16-bit resolution and sampled at 250 Hz with the CardioSTAT in a modified lead 1 position. We provide derived version of the dataset where each patient is stored in separate [HDF5 files](https://www.hdfgroup.org/solutions/hdf5/) on S3. This makes it faster to download as well as makes it possible to leverage TensorFlow `prefetch` and `interleave` to parallelize data loading.
 
 More info available on [PhysioNet website](https://physionet.org/content/icentia11k-continuous-ecg/1.0)
 
-## <span class="sk-h2-span">Usage</span>
+## Usage
 
 !!! Example Python
 
@@ -39,16 +39,16 @@ More info available on [PhysioNet website](https://physionet.org/content/icentia
     The __Icentia11k dataset__ requires roughly 200 GB of disk space and can take around 2 hours to download.
 
 
-## <span class="sk-h2-span">Funding</span>
+## Funding
 
 This work is partially funded by a grant from Icentia, Fonds de Recherche en Santé du Québec, and the Institute of Data Valorization (IVADO).
 
-## <span class="sk-h2-span">Licensing</span>
+## Licensing
 
 The Icentia11k dataset is available for non-commercial use only.
 [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](https://physionet.org/content/icentia11k-continuous-ecg/view-license/1.0/)
 
-<!-- ## <span class="sk-h2-span">Supported Tasks</span>
+<!-- ## Supported Tasks
 
 * [Rhythm](../tasks/rhythm.md)
 * [Beat](../tasks/beat.md)

diff --git a/docs/datasets/index.md b/docs/datasets/index.md
@@ -1,11 +1,11 @@
 
 # :material-database: Datasets
 
-HeartKit provides support for a number of datasets to facilitate training the __heart-monitoring tasks__. Most of the datasets are readily available and can be downloaded and used for training and evaluation. The datasets inherit from [HKDataset](/heartkit/api/heartkit/datasets/dataset) and can be accessed either directly or through the factory singleton [`DatasetFactory`](#dataset-factory).
+heartKIT provides support for a number of datasets to facilitate training the __heart-monitoring tasks__. Most of the datasets are readily available and can be downloaded and used for training and evaluation. The datasets inherit from [HKDataset](/heartkit/api/heartkit/datasets/dataset) and can be accessed either directly or through the factory singleton [`DatasetFactory`](#dataset-factory).
 
-## <span class="sk-h2-span">Available Datasets</span>
+## Available Datasets
 
-Below is a list of the currently available datasets in HeartKit. Please make sure to review each dataset's license for terms and limitations.
+Below is a list of the currently available datasets in heartKIT. Please make sure to review each dataset's license for terms and limitations.
 
 * **[Icentia11k](./icentia11k.md)**: This dataset consists of ECG recordings from 11,000 patients and 2 billion labelled beats. The data was collected by the CardioSTAT, a single-lead heart monitor device from Icentia. The raw signals were recorded with a 16-bit resolution and sampled at 250 Hz with the CardioSTAT in a modified lead 1 position.
 
@@ -17,13 +17,13 @@ Below is a list of the currently available datasets in HeartKit. Please make sur
 
 * **[QTDB](./qtdb.md)**: Over 100 fifteen-minute two-lead ECG recordings with onset, peak, and end markers for P, QRS, T, and (where present) U waves of from 30 to 50 selected beats in each recording.
 
-* **[ECG Synthetic](./synthetic.md)**: An ECG synthetic dataset generated using PhysioKit. The dataset enables the generation of 12-lead ECG signals with a variety of heart conditions and noise levels along with segmentations and fiducial points.
+* **[ECG Synthetic](./synthetic.md)**: An ECG synthetic dataset generated using physioKIT. The dataset enables the generation of 12-lead ECG signals with a variety of heart conditions and noise levels along with segmentations and fiducial points.
 
-* **[PPG Synthetic](./synthetic.md)**: A PPG synthetic dataset generated using PhysioKit. The dataset enables the generation of a 1-lead PPG signal with segmentations and fiducials.
+* **[PPG Synthetic](./synthetic.md)**: A PPG synthetic dataset generated using physioKIT. The dataset enables the generation of a 1-lead PPG signal with segmentations and fiducials.
 
-* **[Bring-Your-Own-Data](./byod.md)**: Add new datasets to HeartKit by providing your own data. Subclass `HKDataset` and register it with the `DatasetFactory`.
+* **[Bring-Your-Own-Data](./byod.md)**: Add new datasets to heartKIT by providing your own data. Subclass `HKDataset` and register it with the `DatasetFactory`.
 
-## <span class="sk-h2-span">Dataset Factory</span>
+## Dataset Factory
 
 The dataset factory, `DatasetFactory`, provides a convenient way to access the datasets. The factory is a thread-safe singleton class that provides a single point of access to the datasets via the datasets' slug names. The benefit of using the factory is it allows registering new additional datasets that can then be leveraged by existing and new tasks.