',
+ "This page uses the repository notebook, whose saved training and export logs date to December 2025. The [previous documentation copy](/sleepkit/notebooks/previous-docs-train-detect-model.ipynb) is retained as an archive; it contains the same code but mixes older saved outputs.",
+ "Before running, set `SK_DATASET_PATH` to your dataset directory. The fallback `../../datasets` is relative to the notebook kernel’s working directory, so it may need adjustment after downloading or opening in Colab.",
+ "This page displays saved notebook outputs; building the site does not run training.",
+]
+for ci, cell in enumerate(notebook["cells"]):
+ text = "".join(cell.get("source", []))
+ if cell["cell_type"] == "markdown":
+ if ci == 0 and "View in Colab" in text:
+ continue
+ text = re.sub(r"^# Train Sleep Detection Model\s*", "", text)
+ text = re.sub(r":[\w]+-[\w-]+:", "", text)
+ text = re.sub(r"\{\s*\.[^}]+\}", "", text)
+ text = text.replace(" markdown", "").replace("../features/fs_w_a_5.md", "/sleepkit/features/fs_w_a_5/")
+ parts.append(re.sub(r"^# ", "## ", text, flags=re.MULTILINE))
+ elif cell["cell_type"] == "code":
+ parts.append("```python\n" + text.rstrip() + "\n```")
+ for oi, output in enumerate(cell.get("outputs", [])):
+ data = output.get("data", {})
+ if "image/png" in data:
+ name = f"{source.stem}-{ci}-{oi}.png"
+ (assets / name).write_bytes(base64.b64decode("".join(data["image/png"])))
+ parts.append(f"")
+ else:
+ # Plain-text fallbacks retain tables without executing saved HTML scripts.
+ raw = "".join(output.get("text", data.get("text/plain", [])))
+ raw = re.sub(r"\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)", "", raw)
+ raw = re.sub(r"\x1b\[[0-?]*[ -/]*[@-~]", "", raw)
+ if raw.strip():
+ block = "```text\n" + raw.rstrip() + "\n```"
+ parts.append(
+ "\nSaved output\n\n" + block + "\n\n"
+ if len(raw.splitlines()) > 12
+ else block
+ )
+Path("src/content/docs/guides/train-detect-model.md").write_text("\n\n".join(parts) + "\n")
diff --git a/astro-site/scripts/build-reference.mjs b/astro-site/scripts/build-reference.mjs
new file mode 100644
index 0000000..43a2de7
--- /dev/null
+++ b/astro-site/scripts/build-reference.mjs
@@ -0,0 +1,125 @@
+import { isPrivateModule } from "./public-docs.mjs";
+import { execFileSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { resolve } from "node:path";
+const repo = resolve("..");
+const run = (cmd, args) =>
+ execFileSync(cmd, args, {
+ cwd: repo,
+ encoding: "utf8",
+ maxBuffer: 128 * 1024 * 1024,
+ });
+rmSync("public/reference", { recursive: true, force: true });
+const commit = run("git", ["rev-parse", "HEAD"]).trim();
+mkdirSync(".cache", { recursive: true });
+const dump = JSON.parse(
+ run("uv", [
+ "tool",
+ "run",
+ "--from",
+ "griffe==1.7.3",
+ "griffe",
+ "dump",
+ "sleepkit",
+ "--docstyle",
+ "google",
+ "-f",
+ ]),
+);
+function clean(node) {
+ if (node.docstring) {
+ node.docstring.value = node.docstring.value.replace(
+ /:(?:material|simple|fontawesome|octicons)-[\w-]+:/g,
+ "",
+ );
+ for (const s of node.docstring.parsed ?? [])
+ if (s.kind === "text")
+ s.value = s.value.replace(/:(?:material|simple|fontawesome|octicons)-[\w-]+:/g, "");
+ }
+ for (const [name, child] of Object.entries(node.members ?? {})) {
+ if (child.kind === "module" && isPrivateModule(name)) delete node.members[name];
+ else clean(child);
+ }
+}
+clean(dump.sleepkit);
+writeFileSync(".cache/griffe.json", JSON.stringify(dump));
+run(process.execPath, [
+ resolve("node_modules/@ambiqai/helia-ui/scripts/pyref.mjs"),
+ "--input",
+ resolve(".cache/griffe.json"),
+ "--out",
+ resolve("src/content/docs/reference/api"),
+ "--public",
+ resolve("public"),
+ "--base",
+ "/sleepkit/",
+ "--site",
+ "https://ambiqai.github.io",
+ "--source-root",
+ repo,
+ "--source-url",
+ `https://github.com/AmbiqAI/sleepkit/blob/${commit}/{path}#L{line}`,
+ "--commit",
+ commit,
+ "--quiet",
+]);
+const model = JSON.parse(
+ readFileSync("public/reference/api/reference.json", "utf8"),
+);
+const modules = [];
+function visit(m) {
+ modules.push(m);
+ (m.submodules ?? []).forEach(visit);
+}
+model.modules.forEach(visit);
+const route = (m) =>
+ "reference/api/" + m.path.toLowerCase().replaceAll(".", "/");
+const rows = modules.flatMap((m) =>
+ (m.symbols ?? [])
+ .filter((s) => ["class", "function"].includes(s.kind))
+ .map((s) => ({
+ id: s.id,
+ name: s.name,
+ kind: s.kind,
+ module: m.path,
+ href: `/sleepkit/${route(m)}/#${s.id}`,
+ summary: (s.description ?? "").split("\n")[0],
+ facets: { kind: [s.kind], category: [m.path.split(".")[1] ?? "package"] },
+ })),
+);
+writeFileSync(
+ "src/data/api-sidebar.json",
+ JSON.stringify(modules.map((m) => ({ label: m.path, slug: route(m) }))),
+);
+writeFileSync(
+ "src/data/api-index.json",
+ JSON.stringify({
+ rows,
+ filters: [
+ { id: "kind", label: "Symbol type", values: ["class", "function"] },
+ {
+ id: "category",
+ label: "Category",
+ values: [...new Set(rows.flatMap((r) => r.facets.category))].sort(),
+ },
+ ],
+ }),
+);
+writeFileSync(
+ "src/data/redirects.json",
+ JSON.stringify(
+ Object.fromEntries(
+ modules.map((m) => [
+ "/api/" + m.path.replaceAll(".", "/"),
+ "/sleepkit/" + route(m) + "/",
+ ]),
+ ),
+ ),
+);
+writeFileSync(
+ "src/content/docs/reference/index.mdx",
+ `---\ntitle: Python API catalog\ndescription: Search sleepKIT classes, functions, signatures and parameter documentation.\n---\nimport ReferenceBrowser from '@ambiqai/helia-ui/astro/ReferenceBrowser';\nimport catalog from '../../../data/api-index.json';\n\nSearch classes and functions by name or module. Documentation is generated from the Python source without importing training dependencies.\n\n\n`,
+);
+console.log(
+ `Generated ${modules.length} API modules and ${rows.length} searchable symbols.`,
+);
diff --git a/astro-site/scripts/check-doc-examples.py b/astro-site/scripts/check-doc-examples.py
new file mode 100644
index 0000000..217871d
--- /dev/null
+++ b/astro-site/scripts/check-doc-examples.py
@@ -0,0 +1,39 @@
+"""Check documented feature contracts and syntax without importing ML runtimes."""
+
+import ast
+import re
+import textwrap
+from pathlib import Path
+
+root = Path("..")
+for name in ["fs_w_a_5", "fs_c_ear_9", "fs_w_pa_14", "fs_w_p_5", "fs_h_e_10"]:
+ tree = ast.parse((root / "sleepkit/features" / f"{name}.py").read_text())
+ function = next(n for n in ast.walk(tree) if isinstance(n, ast.FunctionDef) and n.name == "feature_names")
+ names = ast.literal_eval(next(n.value for n in ast.walk(function) if isinstance(n, ast.Return)))
+ doc = (root / "docs/features" / f"{name}.md").read_text()
+ table = re.findall(r"^\| (\w+) \|", doc, re.MULTILINE)
+ assert table == names, f"{name}: feature table does not match feature_names()"
+ paths = {
+ n.args[0].value
+ for n in ast.walk(tree)
+ if isinstance(n, ast.Call)
+ and isinstance(n.func, ast.Attribute)
+ and n.func.attr == "create_dataset"
+ and n.args
+ and isinstance(n.args[0], ast.Constant)
+ }
+ documented = set(re.findall(r"`(/\w+)`", doc))
+ assert documented == paths, f"{name}: HDF5 paths differ: {documented ^ paths}"
+
+for rel in [
+ "datasets/byod.md",
+ "models/byom.md",
+ "features/byofs.md",
+ "usage/python.md",
+ "modes/demo.md",
+ "datasets/cmidss.md",
+]:
+ text = (root / "docs" / rel).read_text()
+ for match in re.finditer(r"^([ \t]*)```(?:py|python)(?:[^\n]*)\n(.*?)^\1```", text, re.MULTILINE | re.DOTALL):
+ ast.parse(textwrap.dedent(match[2]))
+print("Verified feature tables, HDF5 paths and updated Python example syntax.")
diff --git a/astro-site/scripts/check-output.mjs b/astro-site/scripts/check-output.mjs
new file mode 100644
index 0000000..563a0f0
--- /dev/null
+++ b/astro-site/scripts/check-output.mjs
@@ -0,0 +1,211 @@
+import { internalPages, isPrivateModule } from "./public-docs.mjs";
+import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { resolve, relative, join } from "node:path";
+import { parseHTML } from "linkedom";
+import assert from "node:assert/strict";
+const root = resolve("dist");
+const files = (dir) =>
+ readdirSync(dir).flatMap((n) =>
+ statSync(join(dir, n)).isDirectory() ? files(join(dir, n)) : [join(dir, n)],
+ );
+const errors = [];
+const cache = new Map();
+const doc = (file) => {
+ if (!cache.has(file))
+ cache.set(file, parseHTML(readFileSync(file, "utf8")).document);
+ return cache.get(file);
+};
+for (const file of files(root).filter((f) => f.endsWith(".html"))) {
+ const from = new URL(
+ "/sleepkit/" + relative(root, file).replace(/index\.html$/, ""),
+ "https://ambiqai.github.io",
+ );
+ for (const a of doc(file).querySelectorAll(
+ "a[href], img[src], iframe[src]",
+ )) {
+ const raw = a.getAttribute("href") ?? a.getAttribute("src");
+ if (!raw || raw.startsWith("mailto:")) continue;
+ const url = new URL(raw, from);
+ if (url.origin !== from.origin || !url.pathname.startsWith("/sleepkit/"))
+ continue;
+ const path = resolve(
+ root,
+ decodeURIComponent(url.pathname.slice("/sleepkit/".length)),
+ );
+ const target = [path, join(path, "index.html"), path + ".html"].find(
+ (p) => existsSync(p) && statSync(p).isFile(),
+ );
+ if (!target) errors.push(`${relative(root, file)} -> ${raw}`);
+ else if (
+ url.hash &&
+ target.endsWith(".html") &&
+ !doc(target).getElementById(decodeURIComponent(url.hash.slice(1)))
+ )
+ errors.push(`${relative(root, file)} -> missing anchor ${raw}`);
+ }
+}
+const index = JSON.parse(readFileSync("src/data/api-index.json", "utf8"));
+assert(index.rows.length >= 200, "API coverage unexpectedly reduced");
+assert(index.rows.every((row) => !isPrivateModule(row.module)), "Private API in catalog");
+const apiModel = JSON.parse(readFileSync("dist/reference/api/reference.json", "utf8"));
+function checkPublic(module) {
+ assert(!isPrivateModule(module.path), `Private module published: ${module.path}`);
+ (module.submodules ?? []).forEach(checkPublic);
+}
+apiModel.modules.forEach(checkPublic);
+for (const file of files(root)) {
+ const route = relative(root, file).replaceAll("\\", "/");
+ assert(!route.split("/").some((part) => part.startsWith("_") && !part.startsWith("_astro")), `Private route published: ${route}`);
+}
+assert(existsSync("dist/llms-full.txt"), "Missing LLM export");
+assert(existsSync("dist/pagefind/pagefind.js"), "Missing search index");
+assert(
+ existsSync("dist/notebooks/train-detect-model.ipynb"),
+ "Missing notebook download",
+);
+if (errors.length)
+ throw Error(
+ `Broken internal links (${errors.length}):\n${[...new Set(errors)].join("\n")}`,
+ );
+console.log(
+ `Verified internal links across ${cache.size} pages, ${index.rows.length} API symbols and discovery exports.`,
+);
+
+for (const path of files(resolve("../docs")).filter(
+ (p) => p.endsWith(".md") && !p.includes("/assets/"),
+)) {
+ const rel = relative(resolve("../docs"), path).replace(/(?:index)?\.md$/, "");
+ if (internalPages.has(relative(resolve("../docs"), path))) {
+ assert(!existsSync(join(root, rel, "index.html")), `Internal page published: ${rel}`);
+ continue;
+ }
+ assert(
+ existsSync(join(root, rel, "index.html")),
+ `Missing authored route: ${rel}`,
+ );
+}
+const notebook = JSON.parse(
+ readFileSync("../notebooks/train-detect-model.ipynb", "utf8"),
+);
+assert.deepEqual(
+ JSON.parse(readFileSync("dist/notebooks/train-detect-model.ipynb", "utf8")),
+ notebook,
+ "Notebook download changed",
+);
+const reference = readFileSync(
+ "dist/reference/api/sleepkit/defines/index.md",
+ "utf8",
+);
+assert(
+ reference.includes("TaskParams"),
+ "API Markdown lost parameter documentation",
+);
+
+for (const file of files(root).filter((f) => f.endsWith("/index.html"))) {
+ const content = doc(file).querySelector(".sl-markdown-content");
+ if (!content) continue;
+ const prose = content.cloneNode(true);
+ prose
+ .querySelectorAll("pre, code, script, style")
+ .forEach((node) => node.remove());
+ assert(
+ !/(?:^|\n)\s*(?:!!!|\?\?\?|===|--8<--)/m.test(prose.textContent),
+ `Unconverted Material block: ${relative(root, file)}`,
+ );
+ assert(
+ !/\{\s*width\s*=/.test(prose.textContent),
+ `Leaked image attribute: ${relative(root, file)}`,
+ );
+ for (const p of prose.querySelectorAll("p"))
+ assert(
+ !/^\s*\|.+\|/s.test(p.textContent),
+ `Unrendered table: ${relative(root, file)}`,
+ );
+}
+for (const route of [
+ "tasks/detect",
+ "tasks/stage",
+ "zoo/detect",
+ "zoo/stage",
+]) {
+ assert(
+ doc(join(root, route, "index.html")).querySelector(
+ ".sl-markdown-content table tbody tr",
+ ),
+ `Missing model or class table: ${route}`,
+ );
+}
+assert(
+ !doc(join(root, "quickstart/index.html")).querySelector(
+ ".sl-markdown-content aside starlight-tabs",
+ ),
+ "Installation tabs should not be in callouts",
+);
+assert(
+ readFileSync("dist/features/index.md", "utf8").includes('"class_names"'),
+ "Folded configuration missing from Markdown export",
+);
+assert(
+ readFileSync("dist/llms-full.txt", "utf8").includes('"class_names"'),
+ "Folded configuration missing from LLM export",
+);
+
+for (const file of files(root).filter(
+ (f) => f.endsWith("/index.html") && f !== join(root, "index.html"),
+)) {
+ const document = doc(file);
+ if (!document.querySelector(".sl-markdown-content")) continue;
+ assert(
+ document.querySelector("[data-helia-sidebar-heading]"),
+ `Page has no assigned section: ${relative(root, file)}`,
+ );
+}
+
+for (const file of files(root).filter((f) => f.endsWith("/index.html"))) {
+ const document = doc(file);
+ const prose = document.querySelector("main")?.cloneNode(true);
+ if (!prose) continue;
+ prose
+ .querySelectorAll("pre, code, script, style")
+ .forEach((node) => node.remove());
+ assert(
+ !/:(?:material|simple|fontawesome|octicons)-[\w-]+:/.test(
+ prose.textContent,
+ ),
+ `Unconverted icon shortcode: ${relative(root, file)}`,
+ );
+ assert(
+ !/:(?:material|simple|fontawesome|octicons)-[\w-]+:/.test(document.title),
+ `Icon shortcode in page title: ${relative(root, file)}`,
+ );
+}
+
+for (const file of files(join(root, "examples")).filter((f) =>
+ f.endsWith(".json"),
+)) {
+ JSON.parse(readFileSync(file, "utf8"));
+}
+const notebookMarkdown = readFileSync(
+ "src/content/docs/guides/train-detect-model.md",
+ "utf8",
+);
+assert(
+ !notebookMarkdown.includes("\x1b"),
+ "Notebook contains terminal control escapes",
+);
+assert(
+ !notebookMarkdown.includes("file:///workspaces/"),
+ "Notebook leaks terminal hyperlink targets",
+);
+assert(
+ !notebookMarkdown.includes("## Train Sleep Detection Model"),
+ "Notebook duplicates the page title",
+);
+assert.deepEqual(
+ readFileSync("../docs/guides/train-detect-model.ipynb"),
+ readFileSync("dist/notebooks/previous-docs-train-detect-model.ipynb"),
+);
+assert(
+ !existsSync("public/examples/models-index-1.json"),
+ "Model fragment should not be offered as a runnable configuration",
+);
diff --git a/astro-site/scripts/normalize-markdown.mjs b/astro-site/scripts/normalize-markdown.mjs
new file mode 100644
index 0000000..98605fe
--- /dev/null
+++ b/astro-site/scripts/normalize-markdown.mjs
@@ -0,0 +1,90 @@
+/** Normalize Material block syntax before the shared MDX converter runs. */
+export function normalizeMarkdown(text) {
+ const lines = text.split("\n");
+ function blocks(input) {
+ const out = [];
+ let fence;
+ for (let i = 0; i < input.length; i++) {
+ const line = input[i];
+ const token = line.match(/^\s*(`{3,}|~{3,})/);
+ if (token) {
+ if (!fence) fence = token[1];
+ else if (token[1].startsWith(fence)) fence = undefined;
+ out.push(line);
+ continue;
+ }
+ if (fence) {
+ out.push(line);
+ continue;
+ }
+ const match = line.match(
+ /^([ \t]*)(!!!|\?\?\?\+?)\s+([\w-]+)(?:\s+(.*))?$/,
+ );
+ if (match) {
+ const [, indent, marker, rawType, rawTitle = ""] = match;
+ const type = rawType.toLowerCase();
+ const title = rawTitle.replace(/^["']|["']$/g, "");
+ const body = [];
+ let j = i + 1;
+ while (
+ j < input.length &&
+ (!input[j].trim() || input[j].startsWith(indent + " "))
+ ) {
+ body.push(input[j].trim() ? input[j].slice(indent.length + 4) : "");
+ j++;
+ }
+ const inner = blocks(body).join("\n").trim();
+ if (marker.startsWith("???")) {
+ const label = title || type[0].toUpperCase() + type.slice(1);
+ out.push(
+ "",
+ `${indent}`,
+ `${indent}${label}`,
+ "",
+ ...inner.split("\n").map((l) => indent + l),
+ "",
+ `${indent}`,
+ "",
+ );
+ } else if (["example", "install"].includes(type)) {
+ if (title) out.push("", `${indent}**${title}**`, "");
+ out.push(...inner.split("\n").map((l) => indent + l), "");
+ } else {
+ out.push(
+ `${indent}!!! ${type}${title ? " " + JSON.stringify(title) : ""}`,
+ "",
+ ...inner.split("\n").map((l) => indent + " " + l),
+ "",
+ );
+ }
+ i = j - 1;
+ continue;
+ }
+ out.push(
+ line.replace(
+ /(!\[[^\]]*\]\([^)]*\))\{\s*width=["']?(\d+)["']?\s*\}/g,
+ (_, image, width) => {
+ const [, alt, src] = image.match(/!\[([^\]]*)\]\(([^)]*)\)/);
+ return ``;
+ },
+ ),
+ );
+ }
+ return out;
+ }
+ return blocks(lines).join("\n");
+}
+
+/** Keep snippet indentation local to the directive's line. */
+export function expandSnippets(text, read, seen = []) {
+ return text.replace(
+ /^([ \t]*)--8<--[ \t]+"([^"]+)"[ \t]*$/gm,
+ (_, indent, file) => {
+ if (seen.includes(file)) throw Error(`Cyclic snippet: ${file}`);
+ return expandSnippets(read(file), read, [...seen, file])
+ .split("\n")
+ .map((line) => (line ? indent + line : ""))
+ .join("\n");
+ },
+ );
+}
diff --git a/astro-site/scripts/normalize-markdown.test.mjs b/astro-site/scripts/normalize-markdown.test.mjs
new file mode 100644
index 0000000..ab1c92f
--- /dev/null
+++ b/astro-site/scripts/normalize-markdown.test.mjs
@@ -0,0 +1,64 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { normalizeMarkdown, expandSnippets } from "./normalize-markdown.mjs";
+import {
+ convertPage,
+ createState,
+} from "../node_modules/@ambiqai/helia-ui/scripts/lib/mkdocs-convert-render.mjs";
+const convert = (raw) =>
+ convertPage(normalizeMarkdown(raw), "example.md", {
+ state: createState(),
+ base: "/sleepkit",
+ }).text;
+test("snippet expansion keeps table rows adjacent and preserves surrounding blank lines", () => {
+ const table = "| Class | Label |\n| --- | --- |\n| 0 | Wake |";
+ assert.equal(
+ expandSnippets('Before\n\n--8<-- "table.md"\n\nAfter', () => table),
+ `Before\n\n${table}\n\nAfter`,
+ );
+ assert.equal(
+ expandSnippets(' --8<-- "table.md"', () => table),
+ table
+ .split("\n")
+ .map((l) => " " + l)
+ .join("\n"),
+ );
+ assert.throws(
+ () => expandSnippets('--8<-- "loop"', () => '--8<-- "loop"'),
+ /Cyclic/,
+ );
+});
+test("mixed-case examples and installation wrappers become ordinary content", () => {
+ for (const type of ["Example", "example", "install"]) {
+ const result = convert(
+ `# Test\n\n!!! ${type} "Example title"\n\n === "Python"\n\n Useful example.`,
+ );
+ assert(!result.includes("!!!"));
+ assert(!result.includes(":::note"));
+ assert(result.includes(""));
+ assert(result.includes("**Example title**"));
+ }
+});
+test("actual notes remain callouts and collapsed admonitions retain open state", () => {
+ assert(
+ convert('# Test\n\n!!! Note "Important"\n\n Keep this note.').includes(
+ ":::note[Important]",
+ ),
+ );
+ const closed = convert(
+ '# Test\n\n??? Example "Advanced"\n\n Hidden detail.',
+ );
+ assert(closed.includes(""));
+ assert(closed.includes("Advanced"));
+ assert(
+ convert('# Test\n\n???+ note "Expanded"\n\n Detail.').includes(
+ "",
+ ),
+ );
+});
+test("image attributes become image properties; code samples remain verbatim", () => {
+ const image = normalizeMarkdown('{ width="540" }');
+ assert.equal(image, '');
+ const fenced = '```text\n!!! Example\n{ width="540" }\n```';
+ assert.equal(normalizeMarkdown(fenced), fenced);
+});
diff --git a/astro-site/scripts/public-docs.mjs b/astro-site/scripts/public-docs.mjs
new file mode 100644
index 0000000..08d4fce
--- /dev/null
+++ b/astro-site/scripts/public-docs.mjs
@@ -0,0 +1,9 @@
+export const internalPages = new Set([
+ "shared-foundation.md",
+ "reusable-blocks.md",
+ "detection-preparation-performance.md",
+ "licenses/ambiq-device-model-license-draft.md",
+]);
+
+export const isPrivateModule = (path) =>
+ path.split(".").some((part) => part.startsWith("_"));
diff --git a/astro-site/scripts/publish-reference.mjs b/astro-site/scripts/publish-reference.mjs
new file mode 100644
index 0000000..3eacdc2
--- /dev/null
+++ b/astro-site/scripts/publish-reference.mjs
@@ -0,0 +1,36 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import {
+ RENDER_DEFAULTS,
+ buildIndex,
+ renderModuleMarkdown,
+} from "../node_modules/@ambiqai/helia-ui/scripts/lib/reference-render.mjs";
+
+const model = JSON.parse(
+ readFileSync("dist/reference/api/reference.json", "utf8"),
+);
+const options = {
+ ...RENDER_DEFAULTS,
+ base: "/sleepkit/",
+ site: "https://ambiqai.github.io",
+};
+const index = buildIndex(model, options);
+let full = readFileSync("dist/llms-full.txt", "utf8");
+function publish(module) {
+ const page = `${options.base}reference/api/${module.path.toLowerCase().replaceAll(".", "/")}/`;
+ const markdown = renderModuleMarkdown(module, { index, options });
+ const marker = ``;
+ const start = full.indexOf(marker);
+ if (start < 0) throw new Error(`Missing API export section: ${page}`);
+ const next = full.indexOf("\n");
+});
+
+test("review fixes preserve notebook downloads and readable mobile diagrams", async ({
+ page,
+ request,
+}) => {
+ await page.setViewportSize({ width: 390, height: 844 });
+ await page.goto("guides/train-detect-model/");
+ await expect(
+ page.getByRole("heading", {
+ name: "Train Sleep Detection Model",
+ exact: true,
+ }),
+ ).toHaveCount(1);
+ expect(await page.locator("main").textContent()).not.toContain("\x1b");
+ const alternate = page.getByRole("link", {
+ name: "previous documentation copy",
+ exact: true,
+ });
+ expect(
+ (await request.get((await alternate.getAttribute("href"))!)).ok(),
+ ).toBeTruthy();
+ await page.goto("features/");
+ const diagram = page.locator(".sl-markdown-content svg").first();
+ const bounds = await diagram.boundingBox();
+ expect(bounds!.height).toBeGreaterThan(400);
+ expect(
+ await page.evaluate(
+ () => document.documentElement.scrollWidth <= innerWidth,
+ ),
+ ).toBeTruthy();
+ await page.goto("models/");
+ await expect(page.locator('a[download$=".json"]')).toHaveCount(0);
+});
diff --git a/astro-site/tsconfig.json b/astro-site/tsconfig.json
new file mode 100644
index 0000000..12d8237
--- /dev/null
+++ b/astro-site/tsconfig.json
@@ -0,0 +1 @@
+{"extends":"astro/tsconfigs/strict","include":[".astro/types.d.ts","**/*"],"exclude":["dist"]}
diff --git a/docs/assets/usage/json-configuration.md b/docs/assets/usage/json-configuration.md
index 9a83e51..be1433e 100644
--- a/docs/assets/usage/json-configuration.md
+++ b/docs/assets/usage/json-configuration.md
@@ -1,4 +1,4 @@
-```javascript
+```json
{
"name": "sd-2-tcn-sm",
"job_dir": "./results/sd-2-tcn-sm",
diff --git a/docs/assets/usage/python-configuration.md b/docs/assets/usage/python-configuration.md
index b28e20e..a05b7bf 100644
--- a/docs/assets/usage/python-configuration.md
+++ b/docs/assets/usage/python-configuration.md
@@ -6,7 +6,7 @@ sk.TaskParams(
verbose=2,
datasets=[
- hk.NamedParams(
+ sk.NamedParams(
name="cmidss",
params={
"path": "./datasets/cmidss"
@@ -14,7 +14,7 @@ sk.TaskParams(
)
],
- feature=hk.FeatureParams(
+ feature=sk.FeatureParams(
name="FS-W-A-5",
sampling_rate=0.2,
frame_size=12,
@@ -67,7 +67,7 @@ sk.TaskParams(
backend="pc",
display_report=True,
- quantization=hk.QuantizationParams(
+ quantization=sk.QuantizationParams(
qat=False,
mode="INT8",
io_type="int8",
@@ -77,7 +77,7 @@ sk.TaskParams(
model_file="model.keras",
use_logits=False,
- architecture=hk.NamedParams(
+ architecture=sk.NamedParams(
name="tcn",
params={
"input_kernel": [1, 5],
diff --git a/docs/datasets/byod.md b/docs/datasets/byod.md
index 2f29b30..0edc66e 100644
--- a/docs/datasets/byod.md
+++ b/docs/datasets/byod.md
@@ -1,37 +1,55 @@
# 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 sleepKIT library.
+A custom dataset subclasses `sk.Dataset`, exposes subject IDs, and supplies the signal and label readers consumed by its feature extractor. There is no universal signal schema: pair the adapter with a [custom feature set](../features/byofs.md).
-## How it Works
+## Define the adapter
-1. **Create a Dataset**: Define a new dataset by creating a new Python file. The file should contain a class that inherits from the `HKDataset` base class and implements the required methods.
+This example reads an existing directory of subject `.npz` files with a `signal` array. It makes an explicit subject split and does not download or invent data.
- ```py linenums="1"
- import sleepkit as sk
+```python
+from pathlib import Path
+import random
+import numpy as np
+import sleepkit as sk
- class CustomDataset(sk.Dataset):
- def __init__(self, config):
- super().__init__(config)
+class CustomDataset(sk.Dataset):
+ @property
+ def subject_ids(self) -> list[str]:
+ return sorted(p.stem for p in self.path.glob("*.npz"))
- def download(self):
- pass
+ @property
+ def train_subject_ids(self) -> list[str]:
+ return self.subject_ids[:int(0.8 * len(self.subject_ids))]
- def generate(self):
- pass
- ```
+ @property
+ def test_subject_ids(self) -> list[str]:
+ return self.subject_ids[int(0.8 * len(self.subject_ids)):]
-2. **Register the Dataset**: Register the new dataset with the `sk.DatasetFactory` by calling the `register` method. This method takes the dataset name and the dataset class as arguments.
+ def uniform_subject_generator(self, subject_ids=None, repeat=True, shuffle=True):
+ ids = list(self.subject_ids if subject_ids is None else subject_ids)
+ if not ids:
+ return
+ while True:
+ if shuffle:
+ random.shuffle(ids)
+ yield from ids
+ if not repeat:
+ break
- ```py linenums="1"
- import sleepkit as sk
+ def load_signal_for_subject(self, subject_id: str) -> np.ndarray:
+ with np.load(self.path / f"{subject_id}.npz") as record:
+ return record["signal"].copy()
- sk.DatasetFactory.register("custom", CustomDataset)
- ```
+ def download(self, num_workers=None, force=False):
+ if not self.subject_ids:
+ raise FileNotFoundError(f"Place subject .npz files in {self.path}")
-3. **Use the Dataset**: The new dataset can now be used with the `sk.DatasetFactory` to perform various operations such as downloading and generating data.
+sk.DatasetFactory.register("custom", CustomDataset)
+dataset = sk.DatasetFactory.get("custom")(path=Path("./datasets/custom"))
+```
- ```py linenums="1"
- import sleepkit as sk
+Keep every recording from one person in the same partition. Persist the split for reproducible experiments. Extend the reader with the labels, timestamps and signal names required by your feature extractor; existing built-in extractors expect their own dataset-specific methods.
- dataset = sk.DatasetFactory.create("custom", config)
- ```
+## Use it in a task
+
+Add `custom` and its path to the task's dataset configuration, then select the matching custom feature set. Register both extensions in the Python process before invoking a task. Registering the dataset alone does not make it compatible with every built-in feature set.
diff --git a/docs/datasets/cmidss.md b/docs/datasets/cmidss.md
index 43f3322..41ff5d6 100644
--- a/docs/datasets/cmidss.md
+++ b/docs/datasets/cmidss.md
@@ -4,7 +4,7 @@
This dataset comes from the Child Mind Institute - Detect Sleep States (CMIDSS) Kaggle competition. The 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. While the original data contains 3-axis accelerometer data, this dataset only contains the euclidean norm minus one (ENMO) and z-angle reported every 5 seconds.
-More info available on [PhysioNet website](https://physionet.org/content/challenge-2018/1.0.0)
+More info available on [Kaggle competition page](https://www.kaggle.com/competitions/child-mind-institute-detect-sleep-states)
## Funding
@@ -14,21 +14,19 @@ The data was provided by the Healthy Brain Network, a landmark mental health stu
The CMIDSS dataset is available for non-commercial use under [Attribution-NonCommercial-ShareAlike 4.0 International](https://creativecommons.org/licenses/by-nc-sa/4.0/).
-## Supported Tasks
+## Task integration
-* [Sleep Detect](../tasks/detect.md)
-* [Sleep Stage](../tasks/stage.md)
-* [Sleep Apnea](../tasks/apnea.md)
-* [Sleep Arousal](../tasks/arousal.md)
+Use CMIDSS for [sleep detection](../tasks/detect.md). Its onset/wakeup annotations do not provide sleep-stage or apnea labels. See the [detection label policy](../detection-label-policy.md) for the derived target used by the experimental recipe.
## Installation
-The CMIDSS dataset is available for download from Kaggle. Please note, a user account and permission to access the dataset is required. Once the requirements are met, the dataset can be downloaded using the `kaggle` package. Please note, the `KAGGLE_USERNAME` and `KAGGLE_KEY` environment variables need to be set to the user's username and key. The dataset can be downloaded using the following command:
+The dataset adapter has two download paths. `download_raw_dataset()` retrieves the competition data through the Kaggle client and converts subject recordings to HDF5. Configure the Kaggle client and obtain competition access before running:
-```bash
+```python
+import sleepkit as sk
-export NSSR_TOKEN="INSERT_TOKEN_HERE"
-
-sleepkit -m download \
- -c '{ "ds_path": "./datasets", "datasets": ["stages"], "progress": true }'
+dataset = sk.DatasetFactory.get("cmidss")(path="./datasets/cmidss")
+dataset.download_raw_dataset()
```
+
+`dataset.download()` instead retrieves the prepared archive from the configured Ambiq S3 dataset bucket. It does not use the Kaggle client or an NSRR token. Access to that archive is separate from competition access.
diff --git a/docs/datasets/mesa.md b/docs/datasets/mesa.md
index c3d67dc..0a3b112 100644
--- a/docs/datasets/mesa.md
+++ b/docs/datasets/mesa.md
@@ -19,7 +19,6 @@ The MESA dataset is available for non-commercial and commercial use.
* [Sleep Detect](../tasks/detect.md)
* [Sleep Stage](../tasks/stage.md)
* [Sleep Apnea](../tasks/apnea.md)
-* [Sleep Arousal](../tasks/arousal.md)
## Installation
diff --git a/docs/datasets/stages.md b/docs/datasets/stages.md
index bfb9db3..577b5c9 100644
--- a/docs/datasets/stages.md
+++ b/docs/datasets/stages.md
@@ -32,7 +32,6 @@ The STAGES dataset is available for non-commercial and commercial use.
* [Sleep Detect](../tasks/detect.md)
* [Sleep Stage](../tasks/stage.md)
* [Sleep Apnea](../tasks/apnea.md)
-* [Sleep Arousal](../tasks/arousal.md)
## Installation
diff --git a/docs/datasets/synthetic.md b/docs/datasets/synthetic.md
index f54b3e2..2ce9262 100644
--- a/docs/datasets/synthetic.md
+++ b/docs/datasets/synthetic.md
@@ -15,9 +15,7 @@ NA
The tool is available under BSD-3-Clause License.
-## Supported Tasks
-
-* [Detect](../tasks/detect.md)
+## Integration
@@ -46,6 +44,4 @@ The tool is available under BSD-3-Clause License.
```
-
- --8<-- "assets/segmentation_example.html"
-
+Synthetic signal generation is a standalone preprocessing tool, not a registered sleepKIT dataset. To use generated signals in a task, provide a [custom dataset adapter](byod.md) and matching feature extraction.
diff --git a/docs/datasets/ysyw.md b/docs/datasets/ysyw.md
index 5cd1799..a54d4e2 100644
--- a/docs/datasets/ysyw.md
+++ b/docs/datasets/ysyw.md
@@ -20,4 +20,3 @@ The YSYW dataset is available commercial use under [Open Data Commons Attributio
* [Sleep Detect](../tasks/detect.md)
* [Sleep Stage](../tasks/stage.md)
* [Sleep Apnea](../tasks/apnea.md)
-* [Sleep Arousal](../tasks/arousal.md)
diff --git a/docs/detection-annotated-dataset.md b/docs/detection-annotated-dataset.md
index 0267988..c23fbb6 100644
--- a/docs/detection-annotated-dataset.md
+++ b/docs/detection-annotated-dataset.md
@@ -67,8 +67,8 @@ Every membership run retains these local files outside the public bundle:
Index creation checks every eligible target against the evaluated target sequence,
not only the total length. The index also rejects a different frozen context length.
-Its coordinates provide a basis for later common-index comparisons; this PR does
-not implement intersection with historical model outputs. Test prediction collection
+Its coordinates support the [common-index comparison](detection-comparison.md)
+with historical model outputs. Test prediction collection
currently retains batches in memory before writing NPZ; index writing streams by
subject. This is an offline recipe, not a causal streaming detector.
@@ -91,7 +91,6 @@ The legacy training/inference tests remain supported.
The [first declared experiment](detection-first-experiment.md) is complete, with
pooled and per-series membership metrics and sampled real-input Keras/TFLite parity.
-Its read-only report can be reproduced from saved scoring evidence. Next: inspect
-errors and implement a common scoring intersection for descriptive historical
-comparison. Historical training exposure, task acceptance thresholds, artifact
-licensing, quantization, and hardware validation remain separate questions.
+Its read-only report can be reproduced from saved scoring evidence. The [common scoring intersection](detection-comparison.md) and
+[INT8 conversion](detection-int8.md) are documented separately. Historical training exposure, task acceptance thresholds, artifact
+licensing and hardware validation remain separate questions.
diff --git a/docs/detection-evaluation-protocol.md b/docs/detection-evaluation-protocol.md
index 1c8c61f..be66bf7 100644
--- a/docs/detection-evaluation-protocol.md
+++ b/docs/detection-evaluation-protocol.md
@@ -1,5 +1,8 @@
# Detection evaluation checkpoint
+This page preserves a historical evaluation checkpoint. For the implemented workflow, see the [annotated dataset adapter](detection-annotated-dataset.md) and [comparison report](detection-comparison.md). The checkpoint discussion below records the decisions leading to that workflow.
+
+
The pipeline and artifact contracts are implemented. The next question is whether
a comparison is valid, before asking which model scores better. This checkpoint
adds an annotation audit and defines the evidence needed for an evaluation run.
@@ -139,12 +142,12 @@ Reproduce substantive findings, add a regression check where appropriate, fix th
owning PR, and update any stacked PRs. Avoid repeatedly reviewing unchanged code
or treating review approval as a substitute for source evidence.
-Next implementation checkpoint: raw-series alignment and a reviewed annotation
-policy. Historical model exposure and model licensing remain unresolved. No model
+At this checkpoint, raw-series alignment and annotation-policy review were
+the next steps; their completed records are linked below. Historical model exposure and model licensing remain unresolved. No model
publication is authorized by producing an audit report.
-The next policy candidate is described in [event-supported labels](detection-label-policy.md).
-It is a proposal requiring annotation-protocol evidence, not a relabeling of the audit output.
+The [event-supported label policy](detection-label-policy.md) records the
+subsequent review and adopted target. It does not overwrite the audit output.
The [raw-source verification](detection-source-alignment.md) now confirms step/index,
UTC cadence, and channel alignment for the audited local snapshot. Its 44 local-clock
diff --git a/docs/detection-label-policy.md b/docs/detection-label-policy.md
index 07af954..be9fdb0 100644
--- a/docs/detection-label-policy.md
+++ b/docs/detection-label-policy.md
@@ -1,5 +1,8 @@
# Candidate event-supported label policy
+This page preserves a historical evaluation checkpoint. For the implemented workflow, see the [annotated dataset adapter](detection-annotated-dataset.md) and [comparison report](detection-comparison.md). The checkpoint discussion below records the decisions leading to that workflow.
+
+
Status: implemented candidate policy `sleepkit.event_candidates/v1`, separate from
the active training label policy. No existing HDF5 labels or historical model inputs are rewritten here.
The policy requires verified raw-step/HDF5 alignment before materialization.
diff --git a/docs/detection-preparation-performance.md b/docs/detection-preparation-performance.md
index 1a3ef29..ae6c4fa 100644
--- a/docs/detection-preparation-performance.md
+++ b/docs/detection-preparation-performance.md
@@ -1,4 +1,10 @@
-# Bounded vectorized feature preparation
+# Feature extraction performance notes
+
+This maintainer note documents an optimization to sleep-detection feature extraction and the checks used to preserve its outputs. It is useful when changing the extractor or reproducing the performance comparison; no extra setup is needed to use it.
+
+For a training workflow, start with the [sleep detection task](tasks/detect.md) or the [golden experiment](detection-golden.md).
+
+## What changed
sleepKIT's first stage profile spent most of its time preparing a cold feature
cache. The original extractor made five separate mean/standard-deviation calls,
diff --git a/docs/detection-recipe.md b/docs/detection-recipe.md
index a4b0b16..d897de6 100644
--- a/docs/detection-recipe.md
+++ b/docs/detection-recipe.md
@@ -96,10 +96,12 @@ A feature window contains 12 source samples (60 seconds), advancing 6 samples
with population standard deviations. The time-of-day feature averages the cosine
of each source timestamp: `mean(cos(2*pi*TS/86400))`. Encoding before averaging
keeps windows spanning midnight close to +1 rather than interpreting them as noon.
-This corrects the legacy formula and changes the preprocessing contract to v2.
+The v2 contract corrected the original time-of-day formula. The default v3
+contract additionally validates continuity with an independent UTC sample clock;
+see [sample-clock alignment](detection-sample-clock.md).
Old v1 caches are bypassed, and v1 fitted states are rejected by this implementation.
Retrain and export a new bundle; do not pair v1 model weights or normalization with
-v2 features. Historical baseline packaging and its original feature requirements
+v2 or v3 features. Historical baseline packaging and its original feature requirements
remain unchanged.
A window is invalid if any source sample is nonfinite; invalid windows are not
imputed. Fitted normalization uses valid feature windows from training subjects
@@ -156,7 +158,7 @@ There is no base trainer or plugin registry. Optional integrations are explicit
Python imports; a second recipe will determine which blocks merit extraction.
Bump `SPEC.implementation_version` whenever feature extraction behavior changes,
so caches and saved states cannot silently reuse an older implementation.
-The `sleepkit.cmidss_wrist/v2` preprocessing identifier and `sleepkit.detection/v1`
+The default `sleepkit.cmidss_wrist/v3` preprocessing identifier (with v2 compatibility) and `sleepkit.detection/v1`
recipe identifier are versioned compatibility contracts. Inference refuses unknown
contracts; manifests never specify arbitrary code to import.
@@ -194,13 +196,8 @@ exactly once. The last command is a dry run. These experimental bundles intentio
have no chosen model license, so publication requires staging a licensed release
using the artifact API. License choice and publication are separate release work.
-Current limits: float32 CPU TFLite only, no quantization or MCU validation, no full
-historical-baseline parity, no full-cohort benchmark. The next useful experiment is
-an agreed subject split and annotation policy, followed by baseline comparison and
-int8 conversion with representative training inputs.
+## Validation scope
-The export path follows the native [Keras export API](https://keras.io/api/models/model_saving_apis/export/)
-and [TensorFlow-to-LiteRT conversion](https://developers.google.com/edge/litert/conversion/tensorflow/convert_tf).
+The [first experiment](detection-first-experiment.md), [historical comparison](detection-comparison.md), and [INT8 conversion](detection-int8.md) document separate completed checkpoints and their evidence. Read their declared populations, target semantics and limitations before comparing results. These reports do not establish MCU validation or equivalence to a clinical sleep/wake task.
-Before interpreting model scores, follow the [evaluation checkpoint](detection-evaluation-protocol.md).
-It includes a read-only annotation audit and the provenance requirements for a fair comparison.
+The export path uses the native [Keras export API](https://keras.io/api/models/model_saving_apis/export/) and [TensorFlow-to-LiteRT conversion](https://developers.google.com/edge/litert/conversion/tensorflow/convert_tf). The [evaluation checkpoint](detection-evaluation-protocol.md) records the annotation audit and comparison requirements.
diff --git a/docs/detection-source-alignment.md b/docs/detection-source-alignment.md
index adf689e..a5336aa 100644
--- a/docs/detection-source-alignment.md
+++ b/docs/detection-source-alignment.md
@@ -53,9 +53,9 @@ local TS, validates continuity against it, and uses local TS only for the time-o
feature. This contract carries through caching, training, and unlabeled inference.
Inputs without independent clock evidence retain the strict local-TS check.
-The [candidate event-supported label policy](detection-label-policy.md) is still a
-proposal. It must be reviewed against the source annotation protocol before being
-materialized as a new training/evaluation dataset.
+The [event-supported label policy](detection-label-policy.md) records the adopted
+derived annotated-period membership target. The [dataset adapter](detection-annotated-dataset.md)
+implements that target without overwriting source labels.
## Parquet dependency compatibility
diff --git a/docs/features/byofs.md b/docs/features/byofs.md
index 7f655fe..cae028a 100644
--- a/docs/features/byofs.md
+++ b/docs/features/byofs.md
@@ -4,7 +4,7 @@ The Bring-Your-Own-Features (BYOFS) allows users to add custom feature sets to s
## How it Works
-1. **Create a Feature Set**: Define a new feature set class that subclasses `sk.FeatureSet` and implements all abstract methods.
+1. **Create a Feature Set**: Define a new feature set class that subclasses `sk.FeatureSet` and implements the feature contract. The following is a skeleton: implement the writer before calling it.
```py linenums="1"
import sleepkit as sk
@@ -20,14 +20,14 @@ The Bring-Your-Own-Features (BYOFS) allows users to add custom feature sets to s
@staticmethod
def generate_subject_features(subject_id: str, ds_name: str, params: sk.TaskParams):
- pass
+ raise NotImplementedError("Write feature, mask and label arrays for this subject")
```
2. **Register the Feature Set**: Register the new feature set with the `sk.FeatureFactory` by calling the `register` method. This method takes the feature set name and the feature set class as arguments.
```py linenums="1"
import sleepkit as sk
- sk.FeatureFactory.register(CustomFeatureSet.name, CustomFeatureSet)
+ sk.FeatureFactory.register(CustomFeatureSet.name(), CustomFeatureSet)
```
3. **Use the Feature Set**: The new feature set can now be used to generate feature sets.
@@ -35,14 +35,10 @@ The Bring-Your-Own-Features (BYOFS) allows users to add custom feature sets to s
```py linenums="1"
import sleepkit as sk
- # Create a task params object
- params = sk.TaskParams(
- ...
- feature=sk.FeatureParams(
- name="custom",
- ...
- )
- )
+ from pathlib import Path
+
+ params = sk.TaskParams.model_validate_json(Path("configuration.json").read_text())
+ params.feature.name = "custom"
# Load a task
task = sk.TaskFactory.get("stage")
diff --git a/docs/features/fs_c_ear_9.md b/docs/features/fs_c_ear_9.md
index 6048b89..4e53777 100644
--- a/docs/features/fs_c_ear_9.md
+++ b/docs/features/fs_c_ear_9.md
@@ -18,19 +18,18 @@ The target location for this feature set is the __chest__. From this location, t
## Features
-This feature set includes the following 14 features:
+This feature set includes the following 9 features:
| Feature Name | Description | Sensor |
| --- | --- | --- |
-| hr_bpm | Mean heart rate in beats per minute | PPG |
-| hrv_td_mean_nn | Mean of the NN intervals | PPG |
-| hrv_td_sd_nn | Standard deviation of the NN intervals | PPG |
-| hrv_td_median_nn | Median of the NN intervals | PPG |
-| hrv_fd_lfhf_ratio | Ratio of low frequency to high frequency power in the frequency domain | PPG |
+| hrv_td_mean_nn | Mean of the NN intervals | ECG |
+| hrv_td_sd_nn | Standard deviation of the NN intervals | ECG |
+| hrv_td_median_nn | Median of the NN intervals | ECG |
+| hrv_fd_lfhf_ratio | Ratio of low frequency to high frequency power in the frequency domain | ECG |
| mov_mu | Mean movement | IMU |
| mov_std | Standard deviation of movement | IMU |
| mov_med | Median movement | IMU |
-| rsp_bpm | Mean respiration rate derived from the PPG signal | RSP |
+| rsp_bpm | Mean respiration rate derived from the respiratory signal | RSP |
| hrv_qos | Quality of signal derived from HRV | ECG |
@@ -40,4 +39,4 @@ The feature set is stored as HDF5 files (`.h5`) with one file per subject with p
* `/features`: Time x Feature tensor (fp32). Features are computed over windows of sensor data.
* `/mask`: Time x Mask tensor (bool). Mask indicates valid feature values.
-* `/labels`: Time x Label (int). Labels are sleep stages.
+* `/stage_labels`: Time x Label (int). Labels are sleep stages.
diff --git a/docs/features/fs_h_e_10.md b/docs/features/fs_h_e_10.md
index d747c55..455193c 100644
--- a/docs/features/fs_h_e_10.md
+++ b/docs/features/fs_h_e_10.md
@@ -2,7 +2,7 @@
## Overview
-This feature set is targeted for sleep stage classification based on single pair of ECG and EOG sensor data collected on __head__ location. The feature set computes frequency band metrics over temporal windows (e.g. 30 seconds) captured from ECG and EOG sensors.
+This feature set is targeted for sleep stage classification based on single pair of EEG and EOG sensor data collected on __head__ location. The feature set computes frequency band metrics over temporal windows (e.g. 30 seconds) captured from EEG and EOG sensors.
## Target Location/Sensors
@@ -38,4 +38,4 @@ The feature set is stored as HDF5 files (`.h5`) with one file per subject with p
* `/features`: Time x Feature tensor (fp32). Features are computed over windows of sensor data.
* `/mask`: Time x Mask tensor (bool). Mask indicates valid feature values.
-* `/labels`: Time x Label (int). Labels are sleep stages.
+* `/stage_labels`: Time x Label (int). Labels are sleep stages.
diff --git a/docs/features/fs_w_a_5.md b/docs/features/fs_w_a_5.md
index 3b92ebc..9d6a48e 100644
--- a/docs/features/fs_w_a_5.md
+++ b/docs/features/fs_w_a_5.md
@@ -33,4 +33,4 @@ The feature set is stored as HDF5 files (`.h5`) with one file per subject with p
* `/features`: Time x Feature tensor (fp32). Features are computed over windows of sensor data.
* `/mask`: Time x Mask tensor (bool). Mask indicates valid feature values.
-* `/labels`: Time x Label (int). Labels are sleep stages.
+* `/detect_labels`: Time x Label (int). Labels are sleep-detection classes.
diff --git a/docs/features/fs_w_p_5.md b/docs/features/fs_w_p_5.md
index d0dc900..898a203 100644
--- a/docs/features/fs_w_p_5.md
+++ b/docs/features/fs_w_p_5.md
@@ -16,7 +16,7 @@ The target location for this feature set is the __wrist__. From this location, t
## Features
-This feature set includes the following 4 features:
+This feature set includes the following 5 features:
| Feature Name | Description | Sensor |
| --- | --- | --- |
@@ -24,6 +24,7 @@ This feature set includes the following 4 features:
| piav | Peak-to-trough amplitude delta of PPG | PPG |
| piiv | Peak-to-peak amplitude delta of PPG | PPG |
| pifv | Peak-to-peak interval delta | PPG |
+| qos | PPG signal quality | PPG |
## Output
@@ -31,4 +32,6 @@ The feature set is stored as HDF5 files (`.h5`) with one file per subject with p
* `/features`: Time x Feature tensor (fp32). Features are computed over windows of sensor data.
* `/mask`: Time x Mask tensor (bool). Mask indicates valid feature values.
-* `/labels`: Time x Label (int). Labels are sleep stages.
+* `/stage_labels`: Time x Label (int). Labels are sleep stages.
+
+* `/apnea_labels`: Time x Label (int). Labels are apnea events.
diff --git a/docs/features/fs_w_pa_14.md b/docs/features/fs_w_pa_14.md
index dfc143a..af9a3e8 100644
--- a/docs/features/fs_w_pa_14.md
+++ b/docs/features/fs_w_pa_14.md
@@ -43,4 +43,5 @@ The feature set is stored as HDF5 files (`.h5`) with one file per subject with p
* `/features`: Time x Feature tensor (fp32). Features are computed over windows of sensor data.
* `/mask`: Time x Mask tensor (bool). Mask indicates valid feature values.
-* `/labels`: Time x Label (int). Labels are sleep stages.
+* `/stage_labels`: Time x Label (int). Labels are sleep stages.
+* `/apnea_labels`: Time x Label (int). Labels are apnea events.
diff --git a/docs/features/index.md b/docs/features/index.md
index cae15ac..f958844 100644
--- a/docs/features/index.md
+++ b/docs/features/index.md
@@ -6,7 +6,7 @@ The main method, `generate_subject_features` receives the target dataset name, s
-1. Load the configuration data (e.g. `configuration.json` (1))
+1. Load the configuration data (e.g. `configuration.json`)
1. Load datasets from DatasetFactory (e.g. `mesa`)
1. Load feature generator from FeatureFactory (e.g. `FS-W-PA-14`)
1. Generate features for each dataset/subject (e.g. `generate_subject_features`)
@@ -14,13 +14,13 @@ The main method, `generate_subject_features` receives the target dataset name, s
-1. Example configuration:
+**Example configuration**
--8<-- "assets/usage/json-configuration.md"
```mermaid
-graph LR
+graph TD
A("`Load
configuration
__TaskParams__
@@ -48,7 +48,7 @@ D ==> E
---
-## Availabel Feature Sets
+## Available Feature Sets
- **[FS-W-PA-14](./fs_w_pa_14.md)**:__14__ features derived from __PPG__ and __IMU__ on __wrist__ for __sleep stage__ classification.
- **[FS-C-EAR-9](./fs_c_ear_9.md)**: __9__ features derived from __ECG__, __RSP__, and __IMU__ on __chest__ for __sleep stage__ classification.
diff --git a/docs/guides/index.md b/docs/guides/index.md
index 05e8e05..6b1552f 100644
--- a/docs/guides/index.md
+++ b/docs/guides/index.md
@@ -1,19 +1,31 @@
-# Guides
+# User guide
-These guides cover a wide range of sleepKIT topics, from core concepts to experiments to complete notebook training examples. The goal is to provide a comprehensive understanding of the sleepKIT ADK framework and its capabilities.
+Build a sleepKIT workflow from datasets, feature extraction and model architectures. Use the guides below to configure each step, then follow a tutorial for a complete experiment.
-## Core Concepts
+## Run an experiment
-This section contains guides to explain the core concepts of sleepKIT.
+Start with a task configuration and work through the modes you need.
-## Experiments
+[Configure a run](../modes/configuration.md){ .md-button }
+[Download data](../modes/download.md){ .md-button }
+[Train](../modes/train.md){ .md-button }
+[Evaluate](../modes/evaluate.md){ .md-button }
+[Export](../modes/export.md){ .md-button }
+[Run a demo](../modes/demo.md){ .md-button }
-This section contains experiments to investigate the impact of different design choices on the performance of the model.
+## Choose your components
-- **[Sleep Stage Ablation](./stage-ablation.md)**: Ablation studies to investigate the impact of different design choices on the performance of 4-stage sleep staging.
+- **Datasets** provide recordings and labels for your task. Review each dataset's access requirements and terms.
+- **Feature sets** transform recordings into inputs for training and evaluation.
+- **Model architectures** define the network and its configurable parameters.
-## Notebook Examples
+[Browse datasets](../datasets/index.md){ .md-button }
+[Explore feature sets](../features/index.md){ .md-button }
+[Choose an architecture](../models/index.md){ .md-button }
-This section contains Jupyter notebook examples to demonstrate the training process of sleepKIT.
+## Tutorials and experiments
-- **[Train Sleep Detect Model](train-detect-model.ipynb)**: Training simple sleep detection model using IMU data on wrist.
+Train a sleep-detection model from wrist IMU data in the saved notebook, or explore how feature and model choices affect sleep staging.
+
+[Detection training notebook](train-detect-model.ipynb){ .md-button }
+[Staging ablation study](stage-ablation.md){ .md-button }
diff --git a/docs/index.md b/docs/index.md
index 74bd2ee..9ee6a2d 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,79 +1,114 @@
-#
+# From sleep signals to Edge AI
-[](https://ambiqai.github.io/sleepkit/)
-[](https://ambiqai.github.io/sleepkit/)
+
-*An AI Development Kit for real-time sleep-monitoring on ultra-low power Ambiq SoCs*
+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.
-## Overview
+
-sleepKIT is an AI Development Kit (ADK) that enables developers to easily build and deploy real-time __sleep-monitoring__ models on Ambiq's family of ultra-low power SoCs. sleepKIT explores a number of sleep related tasks including sleep detection, staging, and sleep apnea detection. The kit includes a variety of datasets, feature sets, efficient model architectures, and a number of pre-trained models. The objective of the models is to outperform conventional, hand-crafted algorithms with efficient AI models that still fit within the stringent resource constraints of embedded devices. Furthermore, the included models are trainined using a large variety datasets- using a subset of biological signals that can be captured from a single body location such as head, chest, or wrist/hand. The goal is to enable models that can be deployed in real-world commercial and consumer applications that are viable for long-term use.
+## A starting point for your sleep-monitoring application
-**Key Features:**
+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.
-* **Real-time**: Inference is performed in real-time on battery-powered, edge devices.
-* **Efficient**: Leverage modern AI techniques coupled with Ambiq's ultra-low power SoCs
-* **Generalizable**: Multi-modal, multi-task, multi-dataset
-* **Open Source Code**: Code and Ambiq-authored documentation/site content use BSD-3-Clause, except separately licensed material. Model weights and datasets have [their own terms](model-licensing-policy.md).
+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.
-Please explore the sleepKIT Docs, a comprehensive resource designed to help you understand and utilize all the built-in features and capabilities.
+## Included tasks
-## Getting Started
+Start with a built-in task, or extend the same workflow with your own training, evaluation and export routines.
-- **Install** `sleepKIT` with pip/uv and getting up and running in minutes. [:material-clock-fast: Install sleepKIT](./quickstart.md/#install-sleepkit){ .md-button }
-- **Train** a model with a custom network [:fontawesome-solid-brain: Train a Model](modes/train.md){ .md-button }
-- **Tasks** `sleepKIT` provides tasks like staging, and apnea [:material-magnify-expand: Explore Tasks](tasks/index.md){ .md-button }
-- **Datasets** Several built-in datasets can be leveraged [:material-database-outline: Explore Datasets](./datasets/index.md){ .md-button }
-- **Model Zoo** Pre-trained models are available for each task [:material-download: Explore Models](./zoo/index.md){ .md-button }
+
+
+Code and Ambiq-authored documentation use BSD-3-Clause, except separately licensed material. Model weights and datasets have [their own terms](model-licensing-policy.md).
## Installation
-To get started, first install the python package `sleepkit` along with its dependencies via `Git` or `PyPi`:
+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.
+
+
-=== "PyPI install"
-
-
+=== "uv project"
- ```console
- $ pip install sleepkit
+ Create a project with Python 3.12, then add sleepKIT. In an existing uv project, start with `uv add sleepkit`.
- ---> 100%
+ ```bash
+ uv init --python 3.12 my-sleep-project
+ cd my-sleep-project
+ uv add sleepkit
+ uv run sleepkit --help
```
-
+=== "uvx"
-=== "Git clone"
-
-
+ Run the CLI without adding sleepKIT to a project. The first invocation downloads sleepKIT and its dependencies into an isolated environment.
+
+ ```bash
+ uvx --python 3.12 sleepkit --help
+ ```
+
+ Use a project installation for Python imports and notebooks.
- ```console
- $ git clone https://github.com/AmbiqAI/sleepkit.git
- Cloning into 'sleepkit'...
- Resolving deltas: 100% (3491/3491), done.
- $ cd sleepkit
- $ uv sync
+=== "pipx"
- ---> 100%
+ Install the CLI in its own environment. This command uses an installed Python 3.12 interpreter.
+
+ ```bash
+ pipx install --python python3.12 sleepkit
+ sleepkit --help
```
-
+ If the command is not on your PATH, run `pipx ensurepath` and reopen your terminal. Use a project installation for Python imports and notebooks.
----
+=== "pip"
-## Usage
+ Install into an activated virtual environment.
-__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](./quickstart.md) to quickly get up and running in minutes.
+ ```bash
+ python -m pip install sleepkit
+ sleepkit --help
+ ```
----
+=== "Git clone"
+
+ Work with the repository source and its development dependencies.
+
+ ```bash
+ git clone https://github.com/AmbiqAI/sleepkit.git
+ cd sleepkit
+ uv sync --python 3.12
+ uv run sleepkit --help
+ ```
+
+
-## Tasks
+Need the package manager first? See the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) or [pipx installation guide](https://pipx.pypa.io/stable/installation/). The [Quickstart](./quickstart.md) covers configuration and your first workflow.
-__sleepKIT__ includes a number of built-in [tasks](./tasks/index.md). 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 __sleepKIT__ framework by creating a new task class and registering it to the __task factory__.
-- **[Detect](./tasks/detect.md)**: Detect sustained sleep/inactivity bouts
-- **[Stage](./tasks/stage.md)**: Perform advanced sleep stage assessment
-- **[Apnea](./tasks/apnea.md)**: Detect hypopnea/apnea events
-- **[BYOT](./tasks/byot.md)**: Bring-Your-Own-Task (BYOT) to create custom tasks
+---
+
+## 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](./quickstart.md) to quickly get up and running in minutes.
---
diff --git a/docs/models/byom.md b/docs/models/byom.md
index 2e9d23c..6964077 100644
--- a/docs/models/byom.md
+++ b/docs/models/byom.md
@@ -12,12 +12,12 @@ The model factory can be extended to include custom models. This is useful when
import sleepkit as sk
def custom_model_from_params(
- x: keras.KerasTensor,
+ inputs: keras.KerasTensor,
params: dict,
num_classes: int | None = None,
) -> keras.Model:
- y = x
+ y = inputs
# Create fully connected network from params
for layer in params["layers"]:
y = keras.layers.Dense(layer["units"], activation=layer["activation"])(y)
@@ -25,7 +25,7 @@ The model factory can be extended to include custom models. This is useful when
if num_classes:
y = keras.layers.Dense(num_classes, activation="softmax")(y)
- return keras.Model(inputs=x, outputs=y)
+ return keras.Model(inputs=inputs, outputs=y)
```
2. **Register the Model**: Register the new model function with the `sk.ModelFactory` by calling the `register` method. This method takes the model name and the callable as arguments.
@@ -68,7 +68,7 @@ class CustomModelParams(BaseModel):
layers: list[CustomLayerParams]
def custom_model_from_params(
- x: keras.KerasTensor,
+ inputs: keras.KerasTensor,
params: dict,
num_classes: int | None = None,
) -> keras.Model:
@@ -76,7 +76,7 @@ def custom_model_from_params(
# Convert and validate params
params = CustomModelParams(**params)
- y = x
+ y = inputs
# Create fully connected network from params
for layer in params.layers:
y = keras.layers.Dense(layer.units, activation=layer.activation)(y)
@@ -84,5 +84,5 @@ def custom_model_from_params(
if num_classes:
y = keras.layers.Dense(num_classes, activation="softmax")(y)
- return keras.Model(inputs=x, outputs=y)
+ return keras.Model(inputs=inputs, outputs=y)
```
diff --git a/docs/models/index.md b/docs/models/index.md
index 7023252..3442e8d 100644
--- a/docs/models/index.md
+++ b/docs/models/index.md
@@ -1,6 +1,6 @@
# :material-graph-outline: Models
-sleepKIT provides a number of model architectures that can be used for training __heart-monitoring tasks__. While a number of off-the-shelf models exist, they are often not efficient nor optimized for real-time, edge applications. To address this, sleepKIT provides a model factory that allows you to easily create and train customized models via [helia-edge](https://ambiqai.github.io/helia-edge/). `helia-edge` includes a growing number of state-of-the-art models that can be easily configured and trained using high-level parameters. The models are designed to be efficient and well-suited for real-time, edge applications. Most of the models are based on state-of-the-art architectures that have been modified to allow for more fine-grain customization. In addition, the models support 1D variants to allow for training on time-series data. Please check [helia-edge](https://ambiqai.github.io/helia-edge/) for list of available models and their configurations.
+sleepKIT provides a number of model architectures that can be used for training __sleep-monitoring tasks__. While a number of off-the-shelf models exist, they are often not efficient nor optimized for real-time, edge applications. To address this, sleepKIT provides a model factory that allows you to easily create and train customized models via [helia-edge](https://ambiqai.github.io/helia-edge/). `helia-edge` includes a growing number of state-of-the-art models that can be easily configured and trained using high-level parameters. The models are designed to be efficient and well-suited for real-time, edge applications. Most of the models are based on state-of-the-art architectures that have been modified to allow for more fine-grain customization. In addition, the models support 1D variants to allow for training on time-series data. Please check [helia-edge](https://ambiqai.github.io/helia-edge/) for list of available models and their configurations.
---
@@ -8,13 +8,11 @@ sleepKIT provides a number of model architectures that can be used for training
- **[TCN](https://ambiqai.github.io/helia-edge/models/tcn)**: A CNN leveraging dilated convolutions (key=`tcn`)
- **[U-Net](https://ambiqai.github.io/helia-edge/models/unet)**: A CNN with encoder-decoder architecture for segmentation tasks (key=`unet`)
-- **[U-NeXt](https://ambiqai.github.io/helia-edge/models/unext)**: A U-Net variant leveraging MBConv blocks (key=`unext`)
-- **[EfficientNetV2](https://ambiqai.github.io/helia-edge/models/efficientnet)**: A CNN leveraging MBConv blocks (key=`efficientnet`)
+- **U-NeXt**: Registered as an alias for the U-Net builder (key=`unext`)
+- **[EfficientNetV2](https://ambiqai.github.io/helia-edge/models/efficientnet)**: A CNN leveraging MBConv blocks (key=`efficientnetv2`)
- **[MobileOne](https://ambiqai.github.io/helia-edge/models/mobileone)**: A CNN aimed at sub-1ms inference (key=`mobileone`)
- **[ResNet](https://ambiqai.github.io/helia-edge/models/resnet)**: A popular CNN often used for vision tasks (key=`resnet`)
-- **[Conformer](https://ambiqai.github.io/helia-edge/models/conformer)**: A transformer composed of both convolutional and self-attention blocks (key=`conformer`)
-- **[MetaFormer](https://ambiqai.github.io/helia-edge/models/metaformer)**: A transformer composed of both spatial mixing and channel mixing blocks (key=`metaformer`)
-- **[TSMixer](https://ambiqai.github.io/helia-edge/models/tsmixer)**: An All-MLP Architecture for Time Series Classification (key=`tsmixer`)
+- **Composer**: Compose an architecture through the registered `composer` builder.
* **[Bring-Your-Own-Model](./byom.md)**: Add a custom model architecture to sleepKIT.
---
@@ -39,12 +37,11 @@ The model factory provides the following methods:
A model can be created when invoking a command via the CLI by setting [architecture](../modes/configuration.md#taskparams) in the configuration file. The task will use the supplied name to get the registered model and instantiate with the provided parameters.
-Given the following configuration file `configuration.json`:
+Merge this architecture fragment into your task configuration. It does not include dataset, feature or training settings.
-```json
+```json fragment
{
- ...
- "architecture:" {
+ "architecture": {
"name": "tcn",
"params": {
"input_kernel": [1, 3],
@@ -65,7 +62,7 @@ Given the following configuration file `configuration.json`:
}
```
-The model can be created using the following command:
+After completing the task configuration, train with:
```bash
sleepkit --mode train --task stage --config configuration.json
diff --git a/docs/modes/demo.md b/docs/modes/demo.md
index e5c82bb..8ed3189 100644
--- a/docs/modes/demo.md
+++ b/docs/modes/demo.md
@@ -13,7 +13,7 @@ Each task in sleepKIT has a corresponding demo mode that allows you to run a tas
1. Generate report (e.g. `report.html`)
```mermaid
-graph LR
+graph TD
A("`Load
configuration
__TaskParams__
@@ -71,7 +71,7 @@ The EVB backend is used to run the task-level demo on an Ambiq EVB. This is usef
1. Ensure "evb" is selected as the backend in configuration file.
1. Plug EVB into PC via two USB-C cables.
1. Build and flash firmware to EVB `cd evb && make && make deploy`
-1. Run demo `sleepkit --mode demo --task beat --config ./configs/stage-class-4.json`
+1. Run demo `sleepkit --mode demo --task stage --config ./configs/stage-class-4.json`
1. HTML report will be saved to `${job_dir}/report.html`
### Bring-Your-Own-Backend
@@ -80,29 +80,30 @@ Similar to datasets, tasks, and models, the demo mode can be customized to use y
#### How it Works
-1. **Create a Backend**: Define a new backend class that inherits from the `sk.InferenceBackend` base class and implements the required methods.
+1. **Create a Backend**: Define a new backend class that inherits from the `sk.InferenceBackend` base class and implements the required methods. This skeleton must be implemented before use.
```py linenums="1"
import sleepkit as sk
+ import numpy.typing as npt
class CustomBackend(sk.InferenceBackend):
- def __init__(self, params: TaskParams) -> None:
+ def __init__(self, params: sk.TaskParams) -> None:
self.params = params
def open(self):
- pass
+ raise NotImplementedError("Implement the backend operation")
def close(self):
- pass
+ raise NotImplementedError("Implement the backend operation")
def set_inputs(self, inputs: npt.NDArray):
- pass
+ raise NotImplementedError("Implement the backend operation")
def perform_inference(self):
- pass
+ raise NotImplementedError("Implement the backend operation")
def get_outputs(self) -> npt.NDArray:
- pass
+ raise NotImplementedError("Implement the backend operation")
```
2. **Register the Backend**: Register the new backend with the `sk.BackendFactory` by calling the `register` method. This method takes the backend name and the backend class as arguments.
@@ -117,10 +118,10 @@ Similar to datasets, tasks, and models, the demo mode can be customized to use y
```py linenums="1"
import sleepkit as sk
- params = sk.TaskParams(
- ...,
- backend="custom"
- )
+ from pathlib import Path
+
+ params = sk.TaskParams.model_validate_json(Path("configuration.json").read_text())
+ params.backend = "custom"
task = sk.TaskFactory.get("detect")
@@ -132,10 +133,10 @@ Similar to datasets, tasks, and models, the demo mode can be customized to use y
```py linenums="1"
import sleepkit as sk
- params = sk.TaskParams(
- ...,
- backend="custom"
- )
+ from pathlib import Path
+
+ params = sk.TaskParams.model_validate_json(Path("configuration.json").read_text())
+ params.backend = "custom"
backend = sk.BackendFactory.get("custom")(params)
@@ -150,7 +151,7 @@ The following is an example of a task-level demo report for the sleep staging ta
=== "CLI"
```bash
- sleepkit -m export -t stage -c ./configuration.json
+ sleepkit -m demo -t stage -c ./configuration.json
```
=== "Python"
@@ -160,9 +161,8 @@ The following is an example of a task-level demo report for the sleep staging ta
import sleepkit as sk
task = sk.TaskFactory.get("stage")
- task.export(sk.TaskParams(
- ...
- ))
+ params = sk.TaskParams.model_validate_json(Path("configuration.json").read_text())
+ task.demo(params)
```
diff --git a/docs/modes/evaluate.md b/docs/modes/evaluate.md
index 7eb7040..45025ac 100644
--- a/docs/modes/evaluate.md
+++ b/docs/modes/evaluate.md
@@ -6,7 +6,7 @@ Evaluate mode is used to test the performance of the model on the reserved test
-1. Load the configuration data (e.g. `configuration.json` (1))
+1. Load the configuration data (e.g. `configuration.json`)
1. Load features (e.g. `FS-W-A-5`)
1. Load the trained model (e.g. `model.keras`)
1. Define the metrics (e.g. `accuracy`)
@@ -15,12 +15,12 @@ Evaluate mode is used to test the performance of the model on the reserved test
-1. Example configuration:
+**Example configuration**
--8<-- "assets/usage/json-configuration.md"
```mermaid
-graph LR
+graph TD
A("`Load
configuration
__TaskParams__
@@ -68,18 +68,21 @@ sleepkit --task detect --mode evaluate --config ./configuration.json
The model can be evaluated using the following snippet:
```py linenums="1"
+from pathlib import Path
import sleepkit as sk
task = sk.TaskFactory.get("detect")
-params = sk.TaskParams(...) # (1)
+params = sk.TaskParams.model_validate_json(
+ Path("configuration.json").read_text()
+)
task.evaluate(params)
```
-1. Example configuration:
---8<-- "assets/usage/python-configuration.md"
+**Example configuration**
+--8<-- "assets/usage/json-configuration.md"
---
diff --git a/docs/modes/export.md b/docs/modes/export.md
index 793fa1c..4d74f0e 100644
--- a/docs/modes/export.md
+++ b/docs/modes/export.md
@@ -6,7 +6,7 @@ Export mode is used to convert the trained TensorFlow model into a format that c
-1. Load the configuration data (e.g. `configuration.json` (1))
+1. Load the configuration data (e.g. `configuration.json`)
1. Load the test data (e.g. `test.tfds`)
1. Load the trained model (e.g. `model.keras`)
1. Quantize the model (e.g. `16x8`)
@@ -16,12 +16,12 @@ Export mode is used to convert the trained TensorFlow model into a format that c
-1. Example configuration:
+**Example configuration**
--8<-- "assets/usage/json-configuration.md"
```mermaid
-graph LR
+graph TD
A("`Load
configuration
__TaskParams__
@@ -69,20 +69,24 @@ sleepkit --task detect --mode export --config ./configuration.json
### Python
-The model can be evaluated using the following snippet:
+The model can be exported using the following snippet:
```py linenums="1"
+from pathlib import Path
+import sleepkit as sk
task = sk.TaskFactory.get("detect")
-params = sk.TaskParams(...) # (1)
+params = sk.TaskParams.model_validate_json(
+ Path("configuration.json").read_text()
+)
task.export(params)
```
-1. Example configuration:
---8<-- "assets/usage/python-configuration.md"
+**Example configuration**
+--8<-- "assets/usage/json-configuration.md"
---
diff --git a/docs/modes/index.md b/docs/modes/index.md
index ee95f93..14fe04e 100644
--- a/docs/modes/index.md
+++ b/docs/modes/index.md
@@ -1,96 +1,28 @@
-# sleepKIT Task Modes
+# Modes overview
-## Introduction
+Modes are the steps in a sleepKIT task: acquire data, generate features, train, evaluate, export, and run a demo. Select a mode with `--mode` and provide the task configuration with `--config`.
-Rather than offering a handful of static models, sleepKIT provides a complete framework designed to cover the entire design process of creating customized ML models well-suited for low-power, wearable applications. Each mode serves a specific purpose and is engineered to offer you the flexibility and efficiency required for different tasks and use-cases.
+## Choose a mode
----
+| Mode | Purpose | Guide |
+| --- | --- | --- |
+| `download` | Fetch the datasets selected in your configuration. | [Download datasets](./download.md) |
+| `feature` | Generate features from your datasets. | [Feature generation](../features/index.md) |
+| `train` | Train the task model with the configured features and settings. | [Train a model](./train.md) |
+| `evaluate` | Evaluate the model on the configured test data. | [Evaluate a model](./evaluate.md) |
+| `export` | Convert the trained model for deployment. | [Export a model](./export.md) |
+| `demo` | Run a task-level demonstration with the configured backend. | [Run a demo](./demo.md) |
-## Available Modes
+## Run a step
-
+```bash title="Train a staging model"
+sleepkit --mode train --task stage --config configuration.json
+```
-- :material-download: [**Download** datasets](./download.md)
-- :simple-chartdotjs: [**Feature** generation](../features/index.md)
-- :material-chart-ppf: [**Train** model](./train.md)
-- :material-ab-testing: [**Evaluate** model](./evaluate.md)
-- :material-export: [**Export** model](./export.md)
-- :material-hexagon-multiple: [**Demo** model](./demo.md)
+Use the same configuration for related steps so that dataset, feature and model settings stay consistent. Complete data download and feature generation before training; evaluate the trained model before exporting it.
-
+Demo support depends on the task and backend. See the demo guide for setup and limitations; running a demo does not establish model accuracy.
----
+## Python workflow
-## [Download](./download.md)
-
-[Download mode](./download.md) is used to download the specified datasets for the task. The routine can be customized via the configuration file or by setting the parameters directly in the code. The download process involves fetching the dataset(s) from the specified source and storing them in the specified directory.
-
----
-
-## [Feature](../features/index.md)
-
-[Feature mode](../features/index.md) is used to generate features from the specified dataset(s). The routine can be customized via the configuration file or by setting the parameters directly in the code. The feature extraction process involves transforming the raw data into a format that can be used for training a machine learning model.
-
----
-
-## [Train](./train.md)
-
-[Train mode](./train.md) is used to train a model for the specified task and features. In this mode, the model is trained for a given task using the specified features, model architecture, and hyperparameters. The training process involves optimizing the model's parameters to maximize its performance on the training data.
-
----
-
-## [Evaluate](./evaluate.md)
-
-[Evaluate mode](./evaluate.md) is used to test the performance of the model on the reserved test set for the specified task. The routine can be customized via the configuration file or by setting the parameters directly in the code. The evaluation process involves testing the model's performance on the test data to measure its accuracy, precision, recall, and F1 score.
-
----
-
-## [Export](./export.md)
-
-[Export mode](./export.md) is used to convert the trained model into a format that can be used for deployment onto Ambiq's family of SoCs. Currently, the command will convert the TensorFlow model into both TensorFlow Lite (TFL) and TensorFlow Lite for micro-controller (TFLM) variants. The command will also verify the models' outputs match.
-
----
-
-## [Demo](./demo.md)
-
-[Demo mode](./demo.md) is used to run a task-level demonstration on the trained model using the specified backend inference engine (e.g. PC or EVB). This is useful to showcase the model's performance in real-time and to verify its accuracy in a real-world scenario.
-
----
-
-!!! Example "At-a-Glance"
-
- === "Download"
-
-
- Download specified datasets.
- Refer to [Download Mode](./download.md) for more details.
-
- === "Feature"
-
-
- Generate features from dataset(s).
- Refer to [Feature Mode](../features/index.md) for more details.
-
- === "Train"
-
-
- Train a model for specified task and features.
- Refer to [Train Mode](./train.md) for more details.
-
- === "Evaluate"
-
-
- Evaluate a model for specified task and features.
- Refer to [Evaluate Mode](./evaluate.md) for more details.
-
- === "Export"
-
-
- Export a trained model to TensorFlow Lite and TFLM.
- Refer to [Export Mode](./export.md) for more details.
-
- === "Demo"
-
-
- Run task-level demo on PC or EVB.
- Refer to [Demo Mode](./demo.md) for more details.
+The Python interface exposes the same task operations for scripts and notebooks. See [Quickstart](../quickstart.md#use-sleepkit-with-python) for a configuration-driven example and [Configuration](./configuration.md) for parameter definitions.
diff --git a/docs/modes/train.md b/docs/modes/train.md
index 6037a7d..598a0aa 100644
--- a/docs/modes/train.md
+++ b/docs/modes/train.md
@@ -6,7 +6,7 @@ Each task provides a mode to train a model on the specified features. The traini
-1. Load the configuration data (e.g. `configuration.json` (1))
+1. Load the configuration data (e.g. `configuration.json`)
1. Load features (e.g. `FS-W-A-5`)
1. Initialize custom model architecture (e.g. `tcn`)
1. Define the metrics, loss, and optimizer (e.g. `accuracy`, `categorical_crossentropy`, `adam`)
@@ -15,13 +15,13 @@ Each task provides a mode to train a model on the specified features. The traini
-1. Example configuration:
+**Example configuration**
--8<-- "assets/usage/json-configuration.md"
```mermaid
-graph LR
+graph TD
A("`Load
configuration
__TaskParams__
@@ -76,13 +76,15 @@ import sleepkit as sk
task = sk.TaskFactory.get("detect")
-params = sk.TaskParams(...) # (1)
+params = sk.TaskParams.model_validate_json(
+ Path("configuration.json").read_text()
+)
task.train(params)
```
-1. Example configuration:
---8<-- "assets/usage/python-configuration.md"
+**Example configuration**
+--8<-- "assets/usage/json-configuration.md"
---
diff --git a/docs/quickstart.md b/docs/quickstart.md
index e70ece2..703d6ff 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -55,8 +55,8 @@ We provide several installation methods including pip, uv, and Docker. Install _
## Requirements
-* [Python ^3.12+](https://www.python.org)
-* [uv ^1.6.1+](https://docs.astral.sh/uv/getting-started/installation/)
+* [Python 3.12–3.13](https://www.python.org)
+* [uv](https://docs.astral.sh/uv/getting-started/installation/)
Check the project's [pyproject.toml](https://github.com/AmbiqAI/sleepkit/blob/main/pyproject.toml) file for a list of up-to-date Python dependencies. Note that the installation methods above install all required dependencies. The following are optional dependencies only needed when running `demo` command using Ambiq's evaluation board (`EVB`) backend:
@@ -69,7 +69,7 @@ Once installed, __sleepKIT__ can be used as either a CLI-based tool or as a Pyth
## Use sleepKIT with CLI
-The sleepKIT command line interface (CLI) allows for simple single-line commands without the need for a Python environment. The CLI requires no customization or Python code. You can simply run all tasks from the terminal with the `sleepkit` command. Check out the [CLI Guide](./usage/cli.md) to learn more about available options.
+The sleepKIT command line interface (CLI) allows for simple single-line commands without writing Python code. The CLI requires no customization or Python code. You can simply run all tasks from the terminal with the `sleepkit` command. Check out the [CLI Guide](./usage/cli.md) to learn more about available options.
!!! example
@@ -89,7 +89,7 @@ The sleepKIT command line interface (CLI) allows for simple single-line commands
Where:
* `MODE` is one of `download`, `feature`, `train`, `evaluate`, `export`, or `demo`
- * `TASK` is one of `detect`, `stage`, `apnea`, or `arousal`
+ * `TASK` is one of `detect`, `stage`, or `apnea`
* `CONFIG` is configuration as JSON content or file path
=== "Download"
@@ -132,30 +132,24 @@ The __sleepKIT__ Python package allows for more fine-grained control and customi
For example, you can create a custom model, train it, evaluate its performance on a validation set, and even export a quantized TensorFlow Lite model for deployment. Check out the [Python Guide](./usage/python.md) to learn more about using sleepKIT as a Python package.
-!!! Example
+Load a task configuration, then call the steps you need. Replace `configuration.json` with a configuration for your dataset and model.
- ```py linenums="1"
+```python title="run_task.py"
+from pathlib import Path
+import sleepkit as sk
- import sleepkit as sk
+params = sk.TaskParams.model_validate_json(
+ Path("configuration.json").read_text()
+)
+task = sk.TaskFactory.get("stage")
- params = sk.HKTaskParams(...) # Expand to see example (1)
+task.download(params)
+task.feature(params)
+task.train(params)
+task.evaluate(params)
+task.export(params)
+```
- task = sk.TaskFactory.get("stage")
+The configuration controls dataset locations, features, class mapping and training settings. This example shows the configuration structure; adapt its paths and task-specific values before running it.
- task.download(params) # Download dataset(s)
-
- task.feature(params) # Generate features
-
- task.train(params) # Train the model
-
- task.evaluate(params) # Evaluate the model
-
- task.export(params) # Export to TFLite
-
- ```
-
- 1. Configuration parameters:
- --8<-- "assets/usage/python-configuration.md"
-
-
----
+--8<-- "assets/usage/json-configuration.md"
diff --git a/docs/reusable-blocks.md b/docs/reusable-blocks.md
index 09dc713..f174f68 100644
--- a/docs/reusable-blocks.md
+++ b/docs/reusable-blocks.md
@@ -1,4 +1,6 @@
-# Reusable blocks being evaluated for heliaEDGE
+# Reusable component experiments
+
+These maintainer notes document local experiments that may inform heliaEDGE. They are not required to use sleepKIT or train a sleep model.
sleepKIT should be able to compose a small experiment in Python, add reproducible
data and evaluation contracts, and package a release without inheriting a trainer
diff --git a/docs/shared-foundation.md b/docs/shared-foundation.md
index 074748f..d2792af 100644
--- a/docs/shared-foundation.md
+++ b/docs/shared-foundation.md
@@ -1,4 +1,6 @@
-# Shared KIT foundation and heliaEDGE direction
+# Shared architecture notes
+
+These maintainer notes describe shared architecture proposals and sleepKIT’s role as a consumer. For task workflows, start with the [task guides](tasks/index.md).
Status: architecture proposal, 2026-09-20. This extends the sleepKIT refactor to
heartKIT, sleepKIT and compressionKIT. It does not claim the shared APIs, backend
diff --git a/docs/staging-training.md b/docs/staging-training.md
index d9d1309..8c46364 100644
--- a/docs/staging-training.md
+++ b/docs/staging-training.md
@@ -24,8 +24,8 @@ manifest = create_split(
write_json("/private/split.json", manifest)
```
-The manifest contains `schema`, `dataset`, and explicit `train`, `validation`,
-and `test` lists. Lists must be nonempty, unique and disjoint, with safe filename
+The manifest contains `schema`, `dataset`, and a `partitions` object containing
+explicit `train`, `validation`, and `test` lists. Lists must be nonempty, unique and disjoint, with safe filename
stems. The generator permutes sorted IDs with NumPy `default_rng(seed)`, takes
first test IDs, then validation IDs, then training IDs, and sorts each partition.
Persist the resulting manifest; a seed alone is not membership evidence. The
diff --git a/docs/tasks/apnea.md b/docs/tasks/apnea.md
index a851dac..637b1e7 100644
--- a/docs/tasks/apnea.md
+++ b/docs/tasks/apnea.md
@@ -20,7 +20,7 @@ There are three main types of sleep apnea: obstructive, central, and mixed. Obst
Mixed sleep apnea is a combination of both obstructive and central sleep apnea. It occurs when there is a blockage of the airway and a failure of the brain to send the proper signals to the muscles that control breathing. Mixed sleep apnea is less common than OSA or CSA. Clinically, mixed sleep apnea is defined as a combination of obstructive and central apneas.
-=== "Hyopnea"
+=== "Hypopnea"
Hypopnea is a partial blockage of the airway that results in shallow breathing. It is less severe than apnea but can still disrupt sleep and lead to daytime sleepiness. Clinically, hypopnea is defined as a reduction in airflow of at least 30% for at least 10 seconds, accompanied by a decrease in oxygen saturation of at least 3%.
diff --git a/docs/tasks/arousal.md b/docs/tasks/arousal.md
index ef77ae0..471bfbc 100644
--- a/docs/tasks/arousal.md
+++ b/docs/tasks/arousal.md
@@ -1,11 +1,5 @@
-# Sleep Arousal Task
+# Sleep arousal
-## Overview
+Sleep arousal is not a registered sleepKIT task. This URL is retained for existing links; no arousal model or workflow is provided here.
-Sleep arousal detection is the process of identifying sleep arousal events. This task is useful for identifying sleep disorders and for monitoring sleep quality.
-
-## Characteristics
-
-## Model Zoo
-
-## Target Classes
+[View supported tasks](index.md){ .md-button }
diff --git a/docs/tasks/detect.md b/docs/tasks/detect.md
index 1c21d0b..8b8d8de 100644
--- a/docs/tasks/detect.md
+++ b/docs/tasks/detect.md
@@ -41,8 +41,8 @@ Below outlines the classes available for sleep detect classification. When train
"num_classes": 2,
"class_names": ["AWAKE", "SLEEP"],
"class_map": {
- "0": 0, // Map AWAKE to AWAKE
- "1": 1 // Map SLEEP to SLEEP
+ "0": 0,
+ "1": 1
}
}
```
diff --git a/docs/tasks/index.md b/docs/tasks/index.md
index aaa7192..89cdd85 100644
--- a/docs/tasks/index.md
+++ b/docs/tasks/index.md
@@ -32,35 +32,3 @@ Sleep arousal detection is the process of identifying sleep arousal events. This
### [Bring-Your-Own-Task (BYOT)](./byot.md)
Bring-Your-Own-Task (BYOT) is a feature that allows users to create custom tasks by extending the `sk.Task` base class and registering it with the task factory. This feature is useful for addressing specific use cases that are not covered by the built-in tasks.
-
----
-
-!!! Example "Recap"
-
- === "Detect"
-
- ### Sleep Detection
-
- Detect sustained sleep/inactivity bouts.
- Refer to [Sleep Detect](./detect.md) for more details.
-
- === "Stage"
-
- ### Sleep Stage Classification
-
- Perform 2, 3, 4, or 5 stage sleep detection.
- Refer to [Sleep Stages](./stage.md) for more details.
-
- === "Apnea"
-
- ### Sleep Apnea Detection
- Detect hypopnea/apnea events.
- Refer to [Sleep Apnea](./apnea.md) for more details.
-
- === "Arousal"
-
- ### Sleep Arousal Detection
- Detect sleep arousal events.
- Refer to [Sleep Arousal](./arousal.md) for more details.
-
----
diff --git a/docs/tasks/stage.md b/docs/tasks/stage.md
index 98b79a9..496c9b0 100644
--- a/docs/tasks/stage.md
+++ b/docs/tasks/stage.md
@@ -1,5 +1,9 @@
# :material-sleep: Sleep Stage Task
+## Work with saved features
+
+For a saved-feature workflow, start with the [staging baseline](../staging-baseline.md), which describes input records, preprocessing and checkpoint evaluation. Continue to [staging training](../staging-training.md) to train a model with an explicit split and configuration.
+
## Overview
The objective of sleep stage assessment is to determine the different stages of sleep (N1, N2, N3, REM, and wake) over the course of a night. The de facto standard for sleep stage assessment is polysomnography (PSG) that requires collecting numerous multi-site physiological signals and a trained sleep technician to perform the assessment. The technician uses the physiological signals to determine the sleep stage based on the American Academy of Sleep Medicine (AASM) guidelines. The identification of stages is possible due to specific electrophysiological signatures present and recorded by EEG, EOG, and EMG signals.
@@ -23,7 +27,20 @@ The focus of this project is to develop a model that can perform sleep stage ass
Sleep stages consists of wake (W), non-rapid eye movement (NREM) sleep, and rapid eye movement (REM) sleep. NREM sleep is further divided into three stages: N1, N2, and N3. N1 and N2 are considered light sleep, while N3 is considered deep sleep. REM sleep is considered the dreaming stage of sleep. During the course of a night, a subject will undergo multiple rounds of sleep cycles, each composed of the individual stages. The duration of each cycle and length of each stage various throughout the night. Each sleep cycle typically lasts around 90 to 120 minutes.
---8<-- "assets/tasks/stage/sleep-cycle-pie.html"
+
+
+
+Example sleep-stage proportions. The distribution varies between nights and individuals.
+
=== "Wake (W)"
@@ -111,12 +128,12 @@ Below outlines the classes available for sleep stage classification. When traini
"num_classes": 4,
"class_names": ["AWAKE", "LIGHT", "DEEP", "REM"],
"class_map": {
- "0": 0, // Map WAKE to WAKE
- "1": 1, // Map STAGE1 to LIGHT
- "2": 1, // Map STAGE2 to LIGHT
- "3": 2, // Map STAGE3 to DEEP
- "4": 2, // Map STAGE4 to DEEP
- "5": 3, // Map REM to REM
+ "0": 0,
+ "1": 1,
+ "2": 1,
+ "3": 2,
+ "4": 2,
+ "5": 3
}
}
```
diff --git a/docs/usage/cli.md b/docs/usage/cli.md
index 5b139d3..cceb11f 100644
--- a/docs/usage/cli.md
+++ b/docs/usage/cli.md
@@ -6,7 +6,7 @@
$ sleepkit --help
sleepKIT CLI Options:
- --task [detect, stage, apnea, arousal]
+ --task [detect, stage, apnea]
--mode [download, feature, train, evaluate, export, demo]
--config ["./path/to/config.json", or '{"raw: "json"}']
```
@@ -33,7 +33,7 @@ The sleepKIT command line interface (CLI) makes it easy to run a variety of sing
Where:
* `MODE` is one of `download`, `feature`, `train`, `evaluate`, `export`, or `demo`
- * `TASK` is one of `detect`, `stage`, `apnea`, or `arousal`
+ * `TASK` is one of `detect`, `stage`, or `apnea`
* `CONFIG` is configuration as JSON content or file path
=== "Download"
diff --git a/docs/usage/python.md b/docs/usage/python.md
index 75e16f3..2f2e84c 100644
--- a/docs/usage/python.md
+++ b/docs/usage/python.md
@@ -1,6 +1,6 @@
# :simple-python: Python Usage
-__sleepKIT__ python package allows for more fine-grained control and customization. You can use the package to train, evaluate, and deploy models for both built-in taks and custom tasks. In addition, custom datasets and model architectures can be created and registered with corresponding factories.
+__sleepKIT__ python package allows for more fine-grained control and customization. You can use the package to train, evaluate, and deploy models for both built-in tasks and custom tasks. In addition, custom datasets and model architectures can be created and registered with corresponding factories.
## Overview
@@ -23,7 +23,7 @@ A dataset inherits from the [sk.Dataset](/sleepkit/api/sleepkit/datasets/dataset
```py linenums="1"
import sleepkit as sk
-ds = sk.DatasetFactory.get('ecg-synthetic')(num_pts=100)
+ds = sk.DatasetFactory.get('cmidss')(path='./datasets/cmidss')
```
### [Features](../features/index.md)
@@ -36,13 +36,13 @@ Since each task will require specific transformations of the data, a feature sto
Lastly, sleepKIT leverages [helia-edge's](https://ambiqai.github.io/helia-edge/) customizable model architectures. To enable creating custom network topologies from configuration files, sleepKIT provides a `sk.ModelFactory` that allows you to create models by specifying the model key and the model parameters. Each item in the factory is a callable that takes a `keras.Input`, model parameters, and number of classes as arguments and returns a `keras.Model`.
-```
+```python
import keras
import sleepkit as sk
inputs = keras.Input((256, 1), dtype="float32")
num_classes = 4
-model_params = dict(...)
+model_params = {"blocks": [{"filters": 16, "kernel": [1, 3]}]}
model = sk.ModelFactory.get('tcn')(
inputs=inputs,
@@ -65,9 +65,12 @@ model = sk.ModelFactory.get('tcn')(
```py linenums="1"
-import sleepkit as hk
+from pathlib import Path
+import sleepkit as sk
-params = sk.TaskParams(...) # (1)
+params = sk.TaskParams.model_validate_json(
+ Path("configuration.json").read_text()
+)
task = sk.TaskFactory.get("stage")
@@ -83,8 +86,8 @@ task.export(params) # Export to TFLite
```
-1. Example configuration:
---8<-- "assets/usage/python-configuration.md"
+**Example configuration**
+--8<-- "assets/usage/json-configuration.md"
### Running a custom task w/ custom datasets
diff --git a/sleepkit/datasets/augmentation.py b/sleepkit/datasets/augmentation.py
index fed42b4..3fa0114 100644
--- a/sleepkit/datasets/augmentation.py
+++ b/sleepkit/datasets/augmentation.py
@@ -94,6 +94,7 @@ def create_augmentation_pipeline(augmentations: list[NamedParams]) -> helia.laye
])
y = augmenter(x)
+ ```
"""
if not augmentations:
return keras.layers.Lambda(lambda x: x)
diff --git a/sleepkit/models/__init__.py b/sleepkit/models/__init__.py
index cd34c08..1f32f91 100644
--- a/sleepkit/models/__init__.py
+++ b/sleepkit/models/__init__.py
@@ -13,16 +13,15 @@
## Available Models
-- **[TCN](https://ambiqai.github.io/helia-edge/models/tcn)**: A CNN leveraging dilated convolutions (key=`tcn`)
-- **[U-Net](https://ambiqai.github.io/helia-edge/models/unet)**: A CNN with encoder-decoder architecture for segmentation tasks (key=`unet`)
-- **[U-NeXt](https://ambiqai.github.io/helia-edge/models/unext)**: A U-Net variant leveraging MBConv blocks (key=`unext`)
-- **[EfficientNetV2](https://ambiqai.github.io/helia-edge/models/efficientnet)**: A CNN leveraging MBConv blocks (key=`efficientnet`)
-- **[MobileOne](https://ambiqai.github.io/helia-edge/models/mobileone)**: A CNN aimed at sub-1ms inference (key=`mobileone`)
-- **[ResNet](https://ambiqai.github.io/helia-edge/models/resnet)**: A popular CNN often used for vision tasks (key=`resnet`)
-- **[Conformer](https://ambiqai.github.io/helia-edge/models/conformer)**: A transformer composed of both convolutional and self-attention blocks (key=`conformer`)
-- **[MetaFormer](https://ambiqai.github.io/helia-edge/models/metaformer)**: A transformer composed of both spatial mixing and channel mixing blocks (key=`metaformer`)
-- **[TSMixer](https://ambiqai.github.io/helia-edge/models/tsmixer)**: An All-MLP Architecture for Time Series Classification (key=`tsmixer`)
+The model factory registers these names:
+- `tcn`: temporal convolutional network
+- `unet`: U-Net encoder-decoder
+- `unext`: an alias for the U-Net builder
+- `efficientnetv2`: EfficientNetV2
+- `mobileone`: MobileOne
+- `resnet`: residual network
+- `composer`: configurable model composition
## Model Factory
@@ -37,39 +36,36 @@
## Usage
-A model architecture can easily be instantied by providng a custom set of parameters to the model factory. Each model exposes a set of parameters defined using `Pydantic` to ensure type safety and consistency.
-
-
-!!! Example
-
- The following example demonstrates how to create a TCN model using the `Tcn` class. The model is defined using a set of parameters defined in the `TcnParams` and `TcnBlockParams` classes.
-
- ```py linenums="1"
- import keras
- from helia_edge.models import TcnModel, TcnParams, TcnBlockParams
-
- inputs = keras.Input(shape=(800, 1))
- num_classes = 5
-
- model = TcnModel.model_from_params(
- x=inputs,
- params=TcnParams(
- input_kernel=(1, 3),
- input_norm="batch",
- blocks=[
- TcnBlockParams(filters=8, kernel=(1, 3), dilation=(1, 1), dropout=0.1, ex_ratio=1, se_ratio=0, norm="batch"),
- TcnBlockParams(filters=16, kernel=(1, 3), dilation=(1, 2), dropout=0.1, ex_ratio=1, se_ratio=0, norm="batch"),
- TcnBlockParams(filters=24, kernel=(1, 3), dilation=(1, 4), dropout=0.1, ex_ratio=1, se_ratio=4, norm="batch"),
- TcnBlockParams(filters=32, kernel=(1, 3), dilation=(1, 8), dropout=0.1, ex_ratio=1, se_ratio=4, norm="batch"),
- ],
- output_kernel=(1, 3),
- include_top=True,
- use_logits=True,
- model_name="tcn",
- ),
- num_classes=num_classes,
- )
- ```
+A model architecture can easily be instantiated by providing a custom set of parameters to the model factory. Each model exposes a set of parameters defined using `Pydantic` to ensure type safety and consistency.
+
+The following example demonstrates how to create a TCN model using the `TcnModel` class. The model is defined using a set of parameters defined in the `TcnParams` and `TcnBlockParams` classes.
+
+```py linenums="1"
+import keras
+from helia_edge.models import TcnModel, TcnParams, TcnBlockParams
+
+inputs = keras.Input(shape=(800, 1))
+num_classes = 5
+
+model = TcnModel.model_from_params(
+ inputs=inputs,
+ params=TcnParams(
+ input_kernel=(1, 3),
+ input_norm="batch",
+ blocks=[
+ TcnBlockParams(filters=8, kernel=(1, 3), dilation=(1, 1), dropout=0.1, ex_ratio=1, se_ratio=0, norm="batch"),
+ TcnBlockParams(filters=16, kernel=(1, 3), dilation=(1, 2), dropout=0.1, ex_ratio=1, se_ratio=0, norm="batch"),
+ TcnBlockParams(filters=24, kernel=(1, 3), dilation=(1, 4), dropout=0.1, ex_ratio=1, se_ratio=4, norm="batch"),
+ TcnBlockParams(filters=32, kernel=(1, 3), dilation=(1, 8), dropout=0.1, ex_ratio=1, se_ratio=4, norm="batch"),
+ ],
+ output_kernel=(1, 3),
+ include_top=True,
+ use_logits=True,
+ model_name="tcn",
+ ),
+ num_classes=num_classes,
+)
+```
"""
diff --git a/sleepkit/utils/plotting.py b/sleepkit/utils/plotting.py
index 2b87416..413f1c8 100644
--- a/sleepkit/utils/plotting.py
+++ b/sleepkit/utils/plotting.py
@@ -83,7 +83,8 @@ def setup_plotting(theme: PlotPallette = dark_theme) -> PlotPallette:
```python
import sleepkit as sk
- plot_theme = sk.util.setup_plotting(sk.utils.light_theme)
+ plot_theme = sk.utils.setup_plotting(sk.utils.light_theme)
+ ```
"""
SMALL_SIZE = 12
MEDIUM_SIZE = 14
');
+ const fenced = '```text\n!!! Example\n{ width="540" }\n```';
+ assert.equal(normalizeMarkdown(fenced), fenced);
+});
diff --git a/astro-site/scripts/public-docs.mjs b/astro-site/scripts/public-docs.mjs
new file mode 100644
index 0000000..08d4fce
--- /dev/null
+++ b/astro-site/scripts/public-docs.mjs
@@ -0,0 +1,9 @@
+export const internalPages = new Set([
+ "shared-foundation.md",
+ "reusable-blocks.md",
+ "detection-preparation-performance.md",
+ "licenses/ambiq-device-model-license-draft.md",
+]);
+
+export const isPrivateModule = (path) =>
+ path.split(".").some((part) => part.startsWith("_"));
diff --git a/astro-site/scripts/publish-reference.mjs b/astro-site/scripts/publish-reference.mjs
new file mode 100644
index 0000000..3eacdc2
--- /dev/null
+++ b/astro-site/scripts/publish-reference.mjs
@@ -0,0 +1,36 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import {
+ RENDER_DEFAULTS,
+ buildIndex,
+ renderModuleMarkdown,
+} from "../node_modules/@ambiqai/helia-ui/scripts/lib/reference-render.mjs";
+
+const model = JSON.parse(
+ readFileSync("dist/reference/api/reference.json", "utf8"),
+);
+const options = {
+ ...RENDER_DEFAULTS,
+ base: "/sleepkit/",
+ site: "https://ambiqai.github.io",
+};
+const index = buildIndex(model, options);
+let full = readFileSync("dist/llms-full.txt", "utf8");
+function publish(module) {
+ const page = `${options.base}reference/api/${module.path.toLowerCase().replaceAll(".", "/")}/`;
+ const markdown = renderModuleMarkdown(module, { index, options });
+ const marker = ``;
+ const start = full.indexOf(marker);
+ if (start < 0) throw new Error(`Missing API export section: ${page}`);
+ const next = full.indexOf("\n");
+});
+
+test("review fixes preserve notebook downloads and readable mobile diagrams", async ({
+ page,
+ request,
+}) => {
+ await page.setViewportSize({ width: 390, height: 844 });
+ await page.goto("guides/train-detect-model/");
+ await expect(
+ page.getByRole("heading", {
+ name: "Train Sleep Detection Model",
+ exact: true,
+ }),
+ ).toHaveCount(1);
+ expect(await page.locator("main").textContent()).not.toContain("\x1b");
+ const alternate = page.getByRole("link", {
+ name: "previous documentation copy",
+ exact: true,
+ });
+ expect(
+ (await request.get((await alternate.getAttribute("href"))!)).ok(),
+ ).toBeTruthy();
+ await page.goto("features/");
+ const diagram = page.locator(".sl-markdown-content svg").first();
+ const bounds = await diagram.boundingBox();
+ expect(bounds!.height).toBeGreaterThan(400);
+ expect(
+ await page.evaluate(
+ () => document.documentElement.scrollWidth <= innerWidth,
+ ),
+ ).toBeTruthy();
+ await page.goto("models/");
+ await expect(page.locator('a[download$=".json"]')).toHaveCount(0);
+});
diff --git a/astro-site/tsconfig.json b/astro-site/tsconfig.json
new file mode 100644
index 0000000..12d8237
--- /dev/null
+++ b/astro-site/tsconfig.json
@@ -0,0 +1 @@
+{"extends":"astro/tsconfigs/strict","include":[".astro/types.d.ts","**/*"],"exclude":["dist"]}
diff --git a/docs/assets/usage/json-configuration.md b/docs/assets/usage/json-configuration.md
index 9a83e51..be1433e 100644
--- a/docs/assets/usage/json-configuration.md
+++ b/docs/assets/usage/json-configuration.md
@@ -1,4 +1,4 @@
-```javascript
+```json
{
"name": "sd-2-tcn-sm",
"job_dir": "./results/sd-2-tcn-sm",
diff --git a/docs/assets/usage/python-configuration.md b/docs/assets/usage/python-configuration.md
index b28e20e..a05b7bf 100644
--- a/docs/assets/usage/python-configuration.md
+++ b/docs/assets/usage/python-configuration.md
@@ -6,7 +6,7 @@ sk.TaskParams(
verbose=2,
datasets=[
- hk.NamedParams(
+ sk.NamedParams(
name="cmidss",
params={
"path": "./datasets/cmidss"
@@ -14,7 +14,7 @@ sk.TaskParams(
)
],
- feature=hk.FeatureParams(
+ feature=sk.FeatureParams(
name="FS-W-A-5",
sampling_rate=0.2,
frame_size=12,
@@ -67,7 +67,7 @@ sk.TaskParams(
backend="pc",
display_report=True,
- quantization=hk.QuantizationParams(
+ quantization=sk.QuantizationParams(
qat=False,
mode="INT8",
io_type="int8",
@@ -77,7 +77,7 @@ sk.TaskParams(
model_file="model.keras",
use_logits=False,
- architecture=hk.NamedParams(
+ architecture=sk.NamedParams(
name="tcn",
params={
"input_kernel": [1, 5],
diff --git a/docs/datasets/byod.md b/docs/datasets/byod.md
index 2f29b30..0edc66e 100644
--- a/docs/datasets/byod.md
+++ b/docs/datasets/byod.md
@@ -1,37 +1,55 @@
# 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 sleepKIT library.
+A custom dataset subclasses `sk.Dataset`, exposes subject IDs, and supplies the signal and label readers consumed by its feature extractor. There is no universal signal schema: pair the adapter with a [custom feature set](../features/byofs.md).
-## How it Works
+## Define the adapter
-1. **Create a Dataset**: Define a new dataset by creating a new Python file. The file should contain a class that inherits from the `HKDataset` base class and implements the required methods.
+This example reads an existing directory of subject `.npz` files with a `signal` array. It makes an explicit subject split and does not download or invent data.
- ```py linenums="1"
- import sleepkit as sk
+```python
+from pathlib import Path
+import random
+import numpy as np
+import sleepkit as sk
- class CustomDataset(sk.Dataset):
- def __init__(self, config):
- super().__init__(config)
+class CustomDataset(sk.Dataset):
+ @property
+ def subject_ids(self) -> list[str]:
+ return sorted(p.stem for p in self.path.glob("*.npz"))
- def download(self):
- pass
+ @property
+ def train_subject_ids(self) -> list[str]:
+ return self.subject_ids[:int(0.8 * len(self.subject_ids))]
- def generate(self):
- pass
- ```
+ @property
+ def test_subject_ids(self) -> list[str]:
+ return self.subject_ids[int(0.8 * len(self.subject_ids)):]
-2. **Register the Dataset**: Register the new dataset with the `sk.DatasetFactory` by calling the `register` method. This method takes the dataset name and the dataset class as arguments.
+ def uniform_subject_generator(self, subject_ids=None, repeat=True, shuffle=True):
+ ids = list(self.subject_ids if subject_ids is None else subject_ids)
+ if not ids:
+ return
+ while True:
+ if shuffle:
+ random.shuffle(ids)
+ yield from ids
+ if not repeat:
+ break
- ```py linenums="1"
- import sleepkit as sk
+ def load_signal_for_subject(self, subject_id: str) -> np.ndarray:
+ with np.load(self.path / f"{subject_id}.npz") as record:
+ return record["signal"].copy()
- sk.DatasetFactory.register("custom", CustomDataset)
- ```
+ def download(self, num_workers=None, force=False):
+ if not self.subject_ids:
+ raise FileNotFoundError(f"Place subject .npz files in {self.path}")
-3. **Use the Dataset**: The new dataset can now be used with the `sk.DatasetFactory` to perform various operations such as downloading and generating data.
+sk.DatasetFactory.register("custom", CustomDataset)
+dataset = sk.DatasetFactory.get("custom")(path=Path("./datasets/custom"))
+```
- ```py linenums="1"
- import sleepkit as sk
+Keep every recording from one person in the same partition. Persist the split for reproducible experiments. Extend the reader with the labels, timestamps and signal names required by your feature extractor; existing built-in extractors expect their own dataset-specific methods.
- dataset = sk.DatasetFactory.create("custom", config)
- ```
+## Use it in a task
+
+Add `custom` and its path to the task's dataset configuration, then select the matching custom feature set. Register both extensions in the Python process before invoking a task. Registering the dataset alone does not make it compatible with every built-in feature set.
diff --git a/docs/datasets/cmidss.md b/docs/datasets/cmidss.md
index 43f3322..41ff5d6 100644
--- a/docs/datasets/cmidss.md
+++ b/docs/datasets/cmidss.md
@@ -4,7 +4,7 @@
This dataset comes from the Child Mind Institute - Detect Sleep States (CMIDSS) Kaggle competition. The 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. While the original data contains 3-axis accelerometer data, this dataset only contains the euclidean norm minus one (ENMO) and z-angle reported every 5 seconds.
-More info available on [PhysioNet website](https://physionet.org/content/challenge-2018/1.0.0)
+More info available on [Kaggle competition page](https://www.kaggle.com/competitions/child-mind-institute-detect-sleep-states)
## Funding
@@ -14,21 +14,19 @@ The data was provided by the Healthy Brain Network, a landmark mental health stu
The CMIDSS dataset is available for non-commercial use under [Attribution-NonCommercial-ShareAlike 4.0 International](https://creativecommons.org/licenses/by-nc-sa/4.0/).
-## Supported Tasks
+## Task integration
-* [Sleep Detect](../tasks/detect.md)
-* [Sleep Stage](../tasks/stage.md)
-* [Sleep Apnea](../tasks/apnea.md)
-* [Sleep Arousal](../tasks/arousal.md)
+Use CMIDSS for [sleep detection](../tasks/detect.md). Its onset/wakeup annotations do not provide sleep-stage or apnea labels. See the [detection label policy](../detection-label-policy.md) for the derived target used by the experimental recipe.
## Installation
-The CMIDSS dataset is available for download from Kaggle. Please note, a user account and permission to access the dataset is required. Once the requirements are met, the dataset can be downloaded using the `kaggle` package. Please note, the `KAGGLE_USERNAME` and `KAGGLE_KEY` environment variables need to be set to the user's username and key. The dataset can be downloaded using the following command:
+The dataset adapter has two download paths. `download_raw_dataset()` retrieves the competition data through the Kaggle client and converts subject recordings to HDF5. Configure the Kaggle client and obtain competition access before running:
-```bash
+```python
+import sleepkit as sk
-export NSSR_TOKEN="INSERT_TOKEN_HERE"
-
-sleepkit -m download \
- -c '{ "ds_path": "./datasets", "datasets": ["stages"], "progress": true }'
+dataset = sk.DatasetFactory.get("cmidss")(path="./datasets/cmidss")
+dataset.download_raw_dataset()
```
+
+`dataset.download()` instead retrieves the prepared archive from the configured Ambiq S3 dataset bucket. It does not use the Kaggle client or an NSRR token. Access to that archive is separate from competition access.
diff --git a/docs/datasets/mesa.md b/docs/datasets/mesa.md
index c3d67dc..0a3b112 100644
--- a/docs/datasets/mesa.md
+++ b/docs/datasets/mesa.md
@@ -19,7 +19,6 @@ The MESA dataset is available for non-commercial and commercial use.
* [Sleep Detect](../tasks/detect.md)
* [Sleep Stage](../tasks/stage.md)
* [Sleep Apnea](../tasks/apnea.md)
-* [Sleep Arousal](../tasks/arousal.md)
## Installation
diff --git a/docs/datasets/stages.md b/docs/datasets/stages.md
index bfb9db3..577b5c9 100644
--- a/docs/datasets/stages.md
+++ b/docs/datasets/stages.md
@@ -32,7 +32,6 @@ The STAGES dataset is available for non-commercial and commercial use.
* [Sleep Detect](../tasks/detect.md)
* [Sleep Stage](../tasks/stage.md)
* [Sleep Apnea](../tasks/apnea.md)
-* [Sleep Arousal](../tasks/arousal.md)
## Installation
diff --git a/docs/datasets/synthetic.md b/docs/datasets/synthetic.md
index f54b3e2..2ce9262 100644
--- a/docs/datasets/synthetic.md
+++ b/docs/datasets/synthetic.md
@@ -15,9 +15,7 @@ NA
The tool is available under BSD-3-Clause License.
-## Supported Tasks
-
-* [Detect](../tasks/detect.md)
+## Integration
@@ -46,6 +44,4 @@ The tool is available under BSD-3-Clause License.
```
-