Skip to content
sleepKIT
Home
HELIA
sleepKITv0.11.1

From sleep signals
to Edge AI.

sleepKIT is a Python development kit for building sleep-monitoring AI for Ambiq devices. Turn sensor recordings into features, train and evaluate models, and prepare them for deployment at the edge.

One configurable workflow

  1. 01
    Prepare signalsDataset loaders and feature extraction
  2. 02
    Build modelsConfigurable architectures and training
  3. 03
    Evaluate resultsTask metrics and saved experiments
  4. 04
    Prepare for the edgeModel export and task-level demos

A starting point for your sleep-monitoring application

Section titled “A starting point for your sleep-monitoring application”

Building a sleep model takes more than choosing a network. You need recordings and labels, consistent signal processing, a training setup and a way to evaluate the results. sleepKIT brings these pieces together in a configurable development workflow for engineers and researchers working on wearable and edge applications.

Start with the included dataset integrations, feature sets, model configurations and examples. Run experiments from the command line or compose a custom workflow with the Python API. You can replace individual components as your application develops, then use the export tools to prepare models for integration on Ambiq devices.

Included tasks

Section titled “Included tasks”

Start with a built-in task, or extend the same workflow with your own training, evaluation and export routines.

Sleep detectionIdentify sleep and wake periods from wrist-worn motion signals.Explore detection →Sleep stagingExplore feature sets and models for classifying sleep stages.Explore staging →Sleep apneaExplore the task and available resources for apnea event detection.Explore apnea →Bring your own taskRegister a custom task and reuse sleepKIT’s configuration, datasets and development workflow.Create a task →

Code and Ambiq-authored documentation use BSD-3-Clause, except separately licensed material. Model weights and datasets have their own terms.

Installation

Section titled “Installation”

Use uv for a Python project, uvx to run the CLI in an isolated environment, or pipx to keep the CLI installed. Choose Git clone when developing sleepKIT itself.

Create a project with Python 3.12, then add sleepKIT. In an existing uv project, start with uv add sleepkit.

Terminal
uv init --python 3.12 my-sleep-project
cd my-sleep-project
uv add sleepkit
uv run sleepkit --help

Need the package manager first? See the uv installation guide or pipx installation guide. The Quickstart covers configuration and your first workflow.

Usage

Section titled “Usage”

sleepKIT can be used as either a CLI-based tool or as a Python package to perform advanced development. In both forms, sleepKIT exposes a number of modes and tasks outlined below. In addition, by leveraging highly-customizable configurations, sleepKIT can be used to create custom workflows for a given application with minimal coding. Refer to the Quickstart to quickly get up and running in minutes.

Modes

Section titled “Modes”

The ADK provides a number of modes that can be invoked for a given task. These modes can be accessed via the CLI or directly within the Python package. Each mode is accompanied by a set of task parameters that can be customized to fit the user’s needs.

  • Download: Download specified datasets
  • Feature: Generate features from datasets
  • Train: Train a model for specified task and feature set
  • Evaluate: Evaluate a model for specified task and feature set
  • Export: Export a trained model to TensorFlow Lite and TFLM
  • Demo: Run task-level demo on PC or remotely on Ambiq EVB

Datasets

Section titled “Datasets”

sleepKIT includes several open-source datasets via the dataset factory. Each dataset has a corresponding Python class to aid in downloading and extracting the data. The datasets are used to generate feature sets that are then used to train and evaluate the models. Check out the Datasets Guide to learn more about the available datasets along with their corresponding licenses and limitations.

  • MESA: A longitudinal investigation of factors associated with the development of subclinical cardiovascular disease and the progression of subclinical to clinical cardiovascular disease in 6,814 black, white, Hispanic, and Chinese
  • CMIDSS: The Child Mind Institute - Detect Sleep States (CMIDSS) dataset comprises 300 subjects with over 500 multi-day recordings of wrist-worn accelerometer data annotated with two event types: onset, the beginning of sleep, and wakeup, the end of sleep.
  • YSYW: A total of 1,983 PSG recordings were provided by the Massachusetts General Hospital’s (MGH) Sleep Lab in the Sleep Division together with the Computational Clinical Neurophysiology Laboratory, and the Clinical Data Ani- mation Center.
  • STAGES: The Stanford Technology Analytics and Genomics in Sleep (STAGES) study is a prospective cross-sectional, multi-site study involving 20 data collection sites from six centers including Stanford University, Bogan Sleep Consulting, Geisinger Health, Mayo Clinic, MedSleep, and St. Luke’s Hospital.

Models

Section titled “Models”

The ADK provides a variety of model architectures geared towards efficient, real-time edge applications. These models are provided by Ambiq’s helia-edge and expose a set of parameters that can be used to fully customize the network for a given application. In addition, sleepKIT includes a model factory, ModelFactory, to register current models as well as allow new custom architectures to be added. Check out the Models Guide to learn more about the available network architectures and model factory.

Features

Section titled “Features”

The ADK provides a feature store that allows you to easily create and extract features from the given datasets. The feature store includes a number of feature sets used to train the included model zoo. Each feature set exposes a number of high-level parameters that can be used to customize the feature extraction process for a given application. These parameters can be set as part of the configuration accessible via the CLI and Python package. Check out the Features Guide to learn more about the available feature set generators.

Model Zoo

Section titled “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, sleepKIT provides the corresponding configuration files and performance metrics. The configuration files allow you to easily recreate the models or use them as a starting point for custom solutions. 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 to learn more about the available models and their corresponding performance metrics.

Guides

Section titled “Guides”

Checkout the Guides to see detailed examples and tutorials on how to use sleepKIT 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 capabilities provided by sleepKIT.