From API key to first alert in one page.

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.

1. Download the app.
   Install Noti from the App Store, Google Play, or the direct APK.
2. 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_.
3. Install the SDK.
   Run pip install notiboard in the Python environment that runs your training job.
4. 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。

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

1.1 Migrate an existing TensorBoard project to Noti

1.1 把现有 TensorBoard 项目切换到 Noti

You are modifying an existing Python training project that already uses TensorBoard for visualization.
Assume you know nothing about the Notiboard library unless it is explicitly described in this prompt.
Assume I am using an AI coding agent such as Claude Code to edit the project in place.

Current training script path:
YOUR_SCRIPT_PATH

Task:
Convert the existing TensorBoard-based training script at the path above to Notiboard.

What Notiboard is for this task:
- Import with: from notiboard import NotiWriter
- It is a TensorBoard-style writer that should keep local TensorBoard logs working through log_dir.
- Initialize it like:
  writer = NotiWriter(
      log_dir="runs/experiment1",
      noti_api_key="YOUR_API_KEY",
      noti_project="YOUR_PROJECT_NAME",
      noti_run_name="YOUR_RUN_NAME",
  )

Requirements:
- First inspect the file at YOUR_SCRIPT_PATH and modify that real file, not a toy example.
- Replace SummaryWriter with NotiWriter from notiboard.
- Keep all existing scalar / histogram / text / image logging if present.
- Preserve existing training logic and loop structure.
- Keep log_dir working so local TensorBoard event files are still written and the user's original TensorBoard viewing workflow does not change.
- Add noti_api_key="YOUR_API_KEY".
- Add noti_project="YOUR_PROJECT_NAME".
- Add noti_run_name="YOUR_RUN_NAME" if the script already has a stable experiment name, checkpoint name, config name, or run label that makes sense to reuse.
- Add writer.set_progress(current_step, total_steps, message) inside the training loop using the real loop variables from the script.
- If the script tracks validation metrics, add a printed reminder such as "New best validation result" and also push writer.send_alert(...) when the validation set reaches a new best result.
- Add writer.send_notification(...) when training completes successfully.
- If the script already has exception handling, integrate writer.send_error(...) on failure without breaking the existing behavior.
- If the script does not already have exception handling but there is a safe place to add it, add minimal failure reporting.
- Keep the code runnable after your change.

Placeholders I will replace before using this prompt:
- YOUR_SCRIPT_PATH = path to my current training script
- YOUR_API_KEY = my Noti API key from the mobile app
- YOUR_PROJECT_NAME = project name shown in the Noti app
- YOUR_RUN_NAME = readable run name if I want to force one

Return the final edited code only.

Replace these placeholders first

Placeholder	Replace with	Why
YOUR_SCRIPT_PATH	The real path to your current training script	The agent should inspect and edit your actual file, not invent a new sample.
YOUR_API_KEY	Your key from the Noti app	This authenticates your training job.
YOUR_PROJECT_NAME	A project label such as vision-bench	Runs are grouped by project in the app.
YOUR_RUN_NAME	A readable run name such as resnet50-lr1e-3	Helps you distinguish runs in the dashboard.

Manual migration steps

1. Install the package.
   Run pip install notiboard.
2. Change the import.
   Replace from torch.utils.tensorboard import SummaryWriter with from notiboard import NotiWriter.
3. Swap the writer constructor.
   Create NotiWriter(...) and keep your existing log_dir.
4. Keep your logging calls.
   Methods such as add_scalar, add_histogram, and add_text stay the same.
5. Add progress updates.
   Call writer.set_progress(step + 1, total_steps, "...") inside the loop.
6. Add notifications.
   Use send_notification, send_alert, or send_error where they are useful.

先替换这些占位符

占位符	替换成什么	原因
YOUR_SCRIPT_PATH	你当前训练脚本的真实路径	这样 AI agent 才会去读取并修改真实文件，而不是凭空写一个示例。
YOUR_API_KEY	你在 Noti App 里创建的 key	训练任务需要用它进行认证。
YOUR_PROJECT_NAME	例如 vision-bench 这样的项目名	App 会按项目分组展示 run。
YOUR_RUN_NAME	例如 resnet50-lr1e-3	方便你在 Dashboard 里区分不同训练。

手动改造步骤

1. 先安装包。
   执行 pip install notiboard。
2. 改 import。
   把 from torch.utils.tensorboard import SummaryWriter 改成 from notiboard import NotiWriter。
3. 替换 writer 构造方式。
   用 NotiWriter(...)，同时保留原来的 log_dir。
4. 原来的日志调用基本不用改。
   add_scalar、add_histogram、add_text 等方法都可以继续用。
5. 补充进度更新。
   在训练循环里调用 writer.set_progress(step + 1, total_steps, "...")。
6. 补充通知。
   在合适的位置调用 send_notification、send_alert 或 send_error。

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

1.2 新建一个 Notiboard 训练脚本

Create a runnable Python training script that uses Notiboard.
Assume you know nothing about the Notiboard library unless it is explicitly described here.
Assume the user is likely using an AI coding agent such as Claude Code.

What Notiboard is for this task:
- Import with: from notiboard import NotiWriter
- It should still write normal local TensorBoard logs through log_dir.
- Initialize it like:
  writer = NotiWriter(
      log_dir="runs/YOUR_RUN_FOLDER",
      noti_api_key="YOUR_API_KEY",
      noti_project="YOUR_PROJECT_NAME",
      noti_run_name="YOUR_RUN_NAME",
  )

Requirements:
- Import NotiWriter from notiboard.
- Initialize the writer correctly with log_dir, noti_api_key, noti_project, and noti_run_name.
- Simulate or implement a training loop with:
  - writer.add_scalar(...)
  - writer.set_progress(current_step, total_steps, message)
- If the script includes validation metrics, print a console reminder when a new best validation result is reached and also send writer.send_alert(...).
- Optionally include richer logging with:
  - writer.add_histogram(...)
  - writer.add_text(...)
  - writer.add_image(...)
- Send writer.send_notification(...) at the end of successful training.
- If you add exception handling, use writer.send_error(...) on failure.
- Use a context manager or otherwise ensure writer.close() is called correctly.
- Keep the code clean and runnable.

Placeholders I will replace before using this prompt:
- YOUR_RUN_FOLDER = local TensorBoard log folder
- YOUR_API_KEY = my Noti API key
- YOUR_PROJECT_NAME = project name shown in the app
- YOUR_RUN_NAME = readable run name

Return runnable Python code only.

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

1. Install Notiboard.
   Run pip install notiboard.
2. Create your writer.
   Pass log_dir, noti_api_key, noti_project, and optionally noti_run_name.
3. Log metrics.
   Start with add_scalar inside the training loop.
4. Keep the app updated.
   Send set_progress on every loop or every few steps.
5. Add richer outputs when useful.
   Use histograms for distributions, text for logs, and images for visual results.
6. 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 里查看和区分。

手动配置教程

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

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 时关闭同步。

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 中展示。

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 创建。