Noti Documentation | Notiboard quick start and API guide

1. Quick start

The full Noti workflow has four parts: install the mobile app, create your API key, install the Python package, then run training with NotiWriter.

Download the app.
Install Noti from the App Store, Google Play, or the direct APK.
Create an account and API key.
Open the app, sign in, then go to Settings → API Keys and create a key. It starts with nk_.
Install the SDK.
Run pip install notiboard in the Python environment that runs your training job.
Pick your setup path.
If you already use TensorBoard, follow section 1.1. If you are creating a fresh training script, follow section 1.2.

1. 快速入门

使用 Noti 的完整流程只有四步：先安装手机 App，再创建 API Key，然后安装 Python 包，最后在训练代码里使用 NotiWriter。

下载 App。
从 App Store、Google Play 或直接下载 APK 安装 Noti。
注册账号并创建 API Key。
打开 App 登录，然后进入 Settings → API Keys 创建一个 key。 key 会以 nk_ 开头。
安装 SDK。
在运行训练任务的 Python 环境中执行 pip install notiboard。
选择接入路径。
如果你已经在用 TensorBoard，请看 1.1；如果你要从零新建一个训练脚本，请看 1.2。

Install and verify

pip install notiboard

1.1 Migrate an existing TensorBoard project to Noti

Vibe coding prompt
Copy this prompt into your coding assistant before doing the migration by hand.

1.1 把现有 TensorBoard 项目切换到 Noti

Vibe coding 提示词
如果你想先让 AI 帮你改代码，可以先复制下面这段提示词。

Prompt for migrating an existing TensorBoard project

Read and modify the file at: YOUR_SCRIPT_PATH

Replace `SummaryWriter` with `NotiWriter` from the `notiboard` package (pip install notiboard).
NotiWriter is a drop-in superset of SummaryWriter — all existing add_scalar / add_histogram / add_text / add_image calls keep working unchanged.

Constructor signature:
  from notiboard import NotiWriter
  writer = NotiWriter(
      log_dir="YOUR_LOG_DIR",          # keep whatever log_dir the script already uses
      noti_api_key="YOUR_API_KEY",     # required — from Noti app → Settings → API Keys
      noti_project="YOUR_PROJECT",     # groups runs in the app dashboard
      noti_run_name="YOUR_RUN_NAME",   # optional; reuse any existing experiment/config name
      noti_complete_on_close=True,     # default; marks run completed when writer closes
  )

Methods to add:
  writer.set_progress(current_step, total_steps, message=None)
    → call inside the training loop with real loop variables

  writer.send_notification(title, preview=None, content=None)
    → call after training finishes successfully

  writer.send_alert(title, preview=None, content=None)
    → call when a new best validation result is reached (yellow ⚡ badge)

  writer.send_error(title, preview=None, content=None)
    → call in except blocks on failure (red ❌ badge)

  writer.mark_failed(message=None) / writer.mark_stopped()
    → use instead of send_error when you want to set the run status explicitly

Context manager: `with NotiWriter(...) as writer:` auto-marks completed on clean exit, failed on exception.

Rules:
- Edit the actual file; do not return a code block.
- Preserve all existing logic, imports, and training structure.
- Keep log_dir so local TensorBoard event files continue to be written.
- If the script has no exception handling, add a minimal try/except around the training loop.

Placeholders to replace before using:
YOUR_SCRIPT_PATH  YOUR_LOG_DIR  YOUR_API_KEY  YOUR_PROJECT  YOUR_RUN_NAME

Replace these placeholders

Placeholder	Replace with
`YOUR_SCRIPT_PATH`	Absolute or relative path to your training script — the agent reads and edits this file directly.
`YOUR_LOG_DIR`	Keep the same `log_dir` the script already uses, or choose a new folder.
`YOUR_API_KEY`	Your `nk_…` key from the Noti app → Settings → API Keys.
`YOUR_PROJECT`	A project label such as `vision-bench` — groups runs in the dashboard.
`YOUR_RUN_NAME`	Optional readable name such as `resnet50-lr1e-3`. Reuse any existing config or checkpoint name.

替换这些占位符

占位符	替换成什么
`YOUR_SCRIPT_PATH`	训练脚本的绝对路径或相对路径，AI agent 会直接读取并修改该文件。
`YOUR_LOG_DIR`	沿用脚本已有的 `log_dir`，或填写新目录。
`YOUR_API_KEY`	Noti App → Settings → API Keys 里生成的 `nk_…` key。
`YOUR_PROJECT`	项目名，如 `vision-bench`，App 里按项目分组展示 run。
`YOUR_RUN_NAME`	可读的 run 名，如 `resnet50-lr1e-3`，可复用脚本里已有的实验/配置名。

Minimal migration example

from notiboard import NotiWriter

writer = NotiWriter(
    log_dir="runs/experiment1",
    noti_api_key="nk_your_key_here",
    noti_project="vision-bench",
    noti_run_name="resnet50-lr1e-3",
)

for step in range(total_steps):
    loss = train_step()
    writer.add_scalar("loss/train", loss, step)
    writer.set_progress(step + 1, total_steps, f"Step {step + 1}/{total_steps}")

writer.send_notification(
    "Training complete",
    "Run finished successfully",
    "Open the Noti app to inspect the final charts.",
)
writer.close()

1.2 Create a brand-new Notiboard training run

Vibe coding prompt
Use this if you want an assistant to generate a clean starter script.

1.2 新建一个 Notiboard 训练脚本

Vibe coding 提示词
如果你想直接让 AI 帮你生成新的训练脚本，可以先用这段提示词。

Prompt for a new Notiboard training script

Create a new Python training script that uses Notiboard for metric logging and mobile notifications.

Package: pip install notiboard
Import:  from notiboard import NotiWriter

Constructor:
  writer = NotiWriter(
      log_dir="YOUR_LOG_DIR",          # local TensorBoard log folder (also writes .tfevents files)
      noti_api_key="YOUR_API_KEY",     # from Noti app → Settings → API Keys
      noti_project="YOUR_PROJECT",     # groups runs in the dashboard
      noti_run_name="YOUR_RUN_NAME",   # human-readable run identifier
  )

Use as a context manager so the run is always marked completed or failed:
  with NotiWriter(...) as writer:
      ...training loop...

API reference:
  writer.add_scalar(tag, scalar_value, global_step)           # log a metric
  writer.add_scalars(main_tag, tag_scalar_dict, global_step)  # log several at once
  writer.add_histogram(tag, values, global_step)              # weight/gradient distributions
  writer.add_text(tag, text_string, global_step)              # epoch summaries, eval notes
  writer.add_image(tag, img_tensor_or_array, global_step)     # sample outputs, attention maps
  writer.set_progress(current_step, total_steps, message=None) # updates progress bar in app
  writer.send_notification(title, preview=None, content=None)  # info push (blue ℹ️)
  writer.send_alert(title, preview=None, content=None)         # milestone push (yellow ⚡)
  writer.send_error(title, preview=None, content=None)         # failure push (red ❌)

Script requirements:
- Implement a realistic training loop for: YOUR_TASK_DESCRIPTION
- Call set_progress on every step or epoch.
- Call send_alert when a new best validation result is reached.
- Call send_notification when training completes successfully.
- Wrap the loop in try/except; call send_error in the except block.
- Keep the code clean and runnable with no placeholder stubs.

Placeholders to replace before using:
YOUR_LOG_DIR  YOUR_API_KEY  YOUR_PROJECT  YOUR_RUN_NAME  YOUR_TASK_DESCRIPTION

Replace these placeholders first

Placeholder	Replace with	Why
`YOUR_RUN_FOLDER`	A local TensorBoard log folder	Notiboard still writes standard local event files.
`YOUR_API_KEY`	Your Noti API key	Required unless you disable sync.
`YOUR_PROJECT_NAME`	A stable project name	Keeps runs grouped cleanly in the app.
`YOUR_RUN_NAME`	A readable run identifier	Makes the dashboard understandable later.

Manual setup tutorial

Install Notiboard.
Run pip install notiboard.
Create your writer.
Pass log_dir, noti_api_key, noti_project, and optionally noti_run_name.
Log metrics.
Start with add_scalar inside the training loop.
Keep the app updated.
Send set_progress on every loop or every few steps.
Add richer outputs when useful.
Use histograms for distributions, text for logs, and images for visual results.
Finish cleanly.
Call close(), or use with NotiWriter(...) as writer:.

先替换这些占位符

占位符	替换成什么	原因
`YOUR_RUN_FOLDER`	本地 TensorBoard 日志目录	Notiboard 仍然会写标准的本地 event 文件。
`YOUR_API_KEY`	你的 Noti API Key	除非关闭同步，否则这是必须的。
`YOUR_PROJECT_NAME`	稳定的项目名	App 会按项目把 run 归类。
`YOUR_RUN_NAME`	易读的 run 名称	方便以后在 Dashboard 里查看和区分。

手动配置教程

安装 Notiboard。
执行 pip install notiboard。
创建 writer。
传入 log_dir、noti_api_key、noti_project，需要的话再加 noti_run_name。
记录基础指标。
先在训练循环里用 add_scalar。
保持 App 进度同步。
每轮或每几步调用一次 set_progress。
按需增加更丰富的输出。
分布用 histogram，文本日志用 text，图像结果用 image。
正确结束 run。
调用 close()，或者直接使用 with NotiWriter(...) as writer:。

Minimal new project example

from notiboard import NotiWriter

total_steps = 1000

with NotiWriter(
    log_dir="runs/my_first_noti_run",
    noti_api_key="nk_your_key_here",
    noti_project="my-first-project",
    noti_run_name="baseline",
) as writer:
    best_val = float("inf")

    for step in range(total_steps):
        train_loss = train_step()
        val_loss = validate_step()

        writer.add_scalar("loss/train", train_loss, step)
        writer.add_scalar("loss/val", val_loss, step)
        writer.set_progress(step + 1, total_steps, f"Step {step + 1}/{total_steps}")

        if val_loss < best_val:
            best_val = val_loss
            writer.send_alert(
                title=f"New best val loss: {best_val:.4f}",
                preview="Validation improved",
                content="A new best checkpoint is ready.",
            )

    writer.send_notification(
        title="Training complete",
        preview="The run finished successfully",
        content="Open the Noti app to review the full run.",
    )

2. Detailed Notiboard SDK guide

The SDK is designed as a drop-in writer. If PyTorch is installed it uses torch.utils.tensorboard. Otherwise it falls back to tensorboardX. Your local TensorBoard logs still exist; Noti is an extra sync layer, not a replacement for local event files.

2. Notiboard SDK 详细指南

这个 SDK 的设计目标就是“尽量无痛替换”。如果环境里安装了 PyTorch，它会使用 torch.utils.tensorboard；否则会自动回退到 tensorboardX。本地 TensorBoard 日志仍然会保留，Noti 只是额外增加一层同步能力。

Constructor and configuration

Argument	Default	Meaning
`log_dir`	None	Local TensorBoard log directory.
`noti_api_key`	from `NOTI_API_KEY`	Required when sync is enabled.
`noti_server`	`https://notiapi.tech-webs.com`	The server base URL.
`noti_project`	`"default"`	Project grouping name in the app.
`noti_run_name`	auto-generated	Readable run label.
`noti_enabled`	`True`	Disable sync while keeping local TensorBoard output.
`noti_complete_on_close`	`True`	Automatically mark the run as completed on close.

Environment variables

Variable	Meaning
`NOTI_API_KEY`	Default API key.
`NOTI_SERVER`	Default server URL.
`NOTI_ENABLED`	Set to `0` to disable sync.

构造参数与配置

参数	默认值	含义
`log_dir`	None	本地 TensorBoard 日志目录。
`noti_api_key`	从 `NOTI_API_KEY` 读取	只要启用同步，这就是必须的。
`noti_server`	`https://notiapi.tech-webs.com`	服务端地址。
`noti_project`	`"default"`	App 里用于分组的项目名。
`noti_run_name`	自动生成	易读的 run 名称。
`noti_enabled`	`True`	关闭远程同步但保留本地 TensorBoard 输出。
`noti_complete_on_close`	`True`	在 close 时自动把 run 标记为 completed。

环境变量

变量	含义
`NOTI_API_KEY`	默认 API Key。
`NOTI_SERVER`	默认服务端 URL。
`NOTI_ENABLED`	设为 `0` 时关闭同步。

Configuration example

from notiboard import NotiWriter

writer = NotiWriter(
    log_dir="runs/exp1",
    noti_api_key="nk_your_key_here",
    noti_server="https://notiapi.tech-webs.com",
    noti_project="instrument-classification",
    noti_run_name="vit-b32-lr3e-4",
)

TensorBoard-compatible methods

Keep using your normal writer methods. Notiboard preserves local behavior and mirrors supported data to the server.

Method	Typical use
`add_scalar(tag, value, step)`	Loss, accuracy, learning rate, throughput.
`add_scalars(main_tag, mapping, step)`	Log several related scalars at once.
`add_histogram(tag, values, step)`	Gradient or weight distributions.
`add_text(tag, text, step)`	Epoch summaries, prompts, logs, reports.
`add_image(tag, image, step)`	Sample outputs, masks, attention maps, visual QA.

兼容 TensorBoard 的方法

你原来常用的 writer 方法基本都可以继续用。Notiboard 会保留本地行为，并把支持的数据同步到服务端。

方法	常见用途
`add_scalar(tag, value, step)`	loss、accuracy、learning rate、throughput。
`add_scalars(main_tag, mapping, step)`	一次记录一组相关 scalar。
`add_histogram(tag, values, step)`	梯度或权重分布。
`add_text(tag, text, step)`	epoch 总结、提示词、日志、报告。
`add_image(tag, image, step)`	样例输出、mask、attention map、视觉 QA。

Notifications and progress

Method	What it does
`set_progress(current_step, total_steps, message=None)`	Updates the app progress bar and ETA context.
`send_notification(title, preview, content)`	Sends a standard info notification.
`send_alert(title, preview=None, content=None)`	Sends a highlighted milestone alert.
`send_error(title, preview=None, content=None)`	Sends a red error notification for failures or anomalies.

A good pattern is: progress every step or every few steps, alerts on new best metrics, errors on exceptions, and one final completion notification.

通知与训练进度

方法	作用
`set_progress(current_step, total_steps, message=None)`	更新 App 里的进度条和状态文案。
`send_notification(title, preview, content)`	发送普通信息类通知。
`send_alert(title, preview=None, content=None)`	发送高亮的里程碑通知。
`send_error(title, preview=None, content=None)`	发送红色错误通知，用于异常或失败。

一个比较稳妥的实践是：训练中持续更新 progress，指标刷新到新最好结果时发 alert，发生异常时发 error，结束时再发一条完成通知。

Histograms, text, and images

Histograms: use them for gradients, activations, confidence distributions, or weights.
Text: use them for epoch summaries, evaluation notes, prompts, or export-friendly logs.
Images: pass tensors or arrays and Notiboard uploads PNG images for app viewing.

Histogram、文本与图像

Histogram：适合记录梯度、激活值、置信度分布、权重分布。
Text：适合记录 epoch 总结、评估结论、提示词、日志文本。
Image：可以传 tensor 或数组，Notiboard 会把图像上传为 PNG 并在 App 中展示。

Rich logging example

writer.add_histogram("gradients/all", gradients, global_step=step)
writer.add_text(
    "training/epoch_log",
    f"Epoch {epoch} complete | loss={loss:.4f} | val={val_loss:.4f}",
    global_step=step,
)
writer.add_image(
    "viz/activation_map",
    image_array,
    global_step=step,
    dataformats="HWC",
)

Run lifecycle and failure handling

Method	Use when
`mark_completed()`	You want to end the run early and explicitly mark success.
`mark_failed(message=None)`	Your training crashed or produced a non-recoverable error.
`mark_stopped()`	You intentionally interrupted the run.
`close()`	Flushes queued metrics and closes the writer.

If you use with NotiWriter(...) as writer: and an exception leaves the block, the writer marks the run as failed automatically.

Run 生命周期与失败处理

方法	适用场景
`mark_completed()`	你想提前显式结束 run，并标记成功。
`mark_failed(message=None)`	训练崩溃或出现不可恢复错误时。
`mark_stopped()`	你主动中断训练时。
`close()`	刷新缓冲队列并关闭 writer。

如果你使用 with NotiWriter(...) as writer:，并且代码块抛出异常退出，writer 会自动把该 run 标记为 failed。

FAQ

Do I lose normal TensorBoard logs?

No. Notiboard keeps writing local event files through the underlying TensorBoard writer.

What if I want a different server?

Pass noti_server="https://your-server" or set NOTI_SERVER.

What if I only want local TensorBoard output for a while?

Set noti_enabled=False or NOTI_ENABLED=0.

How do I get my API key?

Open the mobile app and go to Settings → API Keys.

常见问题

我会失去原来的 TensorBoard 本地日志吗？

不会。Notiboard 仍然会通过底层 writer 写本地 event 文件。

如果我想连自己的服务端怎么办？

传入 noti_server="https://your-server"，或者设置 NOTI_SERVER。

如果我暂时只想保留本地 TensorBoard 输出呢？

设置 noti_enabled=False 或 NOTI_ENABLED=0。

API Key 在哪里拿？

打开手机 App，进入 Settings → API Keys 创建。

From API key to first alert in one page.

1. Quick start

1. 快速入门

1.1 Migrate an existing TensorBoard project to Noti

1.1 把现有 TensorBoard 项目切换到 Noti

Replace these placeholders

替换这些占位符

1.2 Create a brand-new Notiboard training run

1.2 新建一个 Notiboard 训练脚本

Replace these placeholders first

Manual setup tutorial

先替换这些占位符

手动配置教程

2. Detailed Notiboard SDK guide

2. Notiboard SDK 详细指南

Constructor and configuration

Environment variables

构造参数与配置

环境变量

TensorBoard-compatible methods

兼容 TensorBoard 的方法

Notifications and progress

通知与训练进度

Histograms, text, and images

Histogram、文本与图像

Run lifecycle and failure handling

Run 生命周期与失败处理

FAQ

Do I lose normal TensorBoard logs?

What if I want a different server?

What if I only want local TensorBoard output for a while?

How do I get my API key?

常见问题

我会失去原来的 TensorBoard 本地日志吗？

如果我想连自己的服务端怎么办？

如果我暂时只想保留本地 TensorBoard 输出呢？

API Key 在哪里拿？