hsimatp 0.0.1

A Python SDK for tracking AI and simulation experiments like HSimAtp

HSimAtp Python SDK

HSimAtp 是一个轻量级、兼具高性能离线记录与实时云端同步的 Python 实验追踪 SDK。它可以帮助你跟踪 AI 训练、仿真程序的运行状态，记录超参数、指标数据以及系统硬件性能，并支持通过 WebSocket 接收服务端下发的热更新配置。

🎯 核心功能特性

• 无缝网络同步与离线回滚：通过 login 验证后，各项 log 与 init 将自动通过 HTTP 接入服务器。如果断网或未配置服务器，系统自动优雅降级为离线模式，一切照常记录到本地目录。
• 异步高性能日志列队：无论你的训练步频有多快，hsimatp.log()` 都会以 O(1) 的超低延迟将数据推入内存队列，后台独立守护线程完全接管磁盘 I/O 和网络上传，绝不阻塞主程序。
• WebSocket 动态参数热更：启动实验时，SDK 自动建立 WebSocket 长链接，不但能随时读取服务端推送的最新实验参数，更可通过 on_config_update 触发实时回调，在训练中途动态调整学习率等关键参数。
• 多级嵌套参数平铺：传入任意深度的嵌套 config 字典，内部会自动智能拍平为单层（如 model/layer/type），完美匹配扁平化的看板分析；也可随时通过 hsimatp.convert.unflatten_json()` 轻松逆向恢复。
• 极简全局 API：在工程任何地方通过 hsimatp.config() 均可拉取实验级别的全局最新参数字典。
• 硬件性能监控：底层利用 psutil 开启后台线程，定时记录 CPU 使用率、内存占用等信息。

---

📦 安装

从源码安装

# 在含有 setup.py 的根目录下跑
pip install .

# 如果是离线环境，可以通过本地 wheel 包安装：
pip install hsimatp-0.1.0-py3-none-any.whl --no-index --find-links .

(环境要求：python >= 3.7，自动依赖：psutil >= 5.0.0, websocket-client >= 1.0.0)

---

🚀 快速上手 (Quick Start)

以下是一个完整的服务端通讯与参数热更新演示：

import hsimatp
import time
import random

# 0. 用户认证 (只需执行一次，会自动将鉴权 Key 和 Host 保存到 ~/.hsimatp/credentials.json)
# host 地址可以直接填 ip:port 或带 http:// 皆可，SDK 会自动解析处理转换
hsimatp.login(api_key="your-api-key", host="127.0.0.1:8080")

# 可选：定义一个回调函数，用于第一时间接收平台 WebSocket 动态推送的新参数
def on_param_changed(updated_config):
    print(f"\n[来自云端的热更新] 实验参数已变更为: {updated_config}\n")

# 1. 初始化实验 (如果不传 experiment_name, 将自动生成形如 'aBcD-12' 的随机名)
run = hsimatp.init(
    project="Simulation-Engine",
    description="This is an advanced tracking experiment.",
    config={
        "learning_rate": 0.001,
        "batch_size": 32,
        "model": {"type": "Q-Learning", "layers": 3} # 支持多级嵌套对象字典
    },
    on_config_update=on_param_changed
)

print("Starting main training loop...")

# 2. 动感记录！
for step in range(1, 100):
    # 动态获取随时可能被云端更改的最新学习率
    current_lr = hsimatp.get_config("learning_rate") 
    # 或者通过 hsimatp.config()["learning_rate"] 获取
    
    loss = 10.0 / step + current_lr * random.uniform(-0.1, 0.1)
    acc = min(0.5 + step * 0.05 + random.uniform(-0.02, 0.02), 1.0)
    
    # 瞬间推入异步记录队列，后台守护线程接管上传，绝不卡顿主程序！
    hsimatp.log({"train/loss": loss, "eval/accuracy": acc, "step": step})
    time.sleep(1) # 模拟每步耗时

# 3. 安全结束实验，程序会自动最多等待5秒确保异步队列中积压的日志全部落盘与上传完成
hsimatp.finish()

---

📂 本地日志保留机制

哪怕配置了远程服务端（HTTP API），SDK 依旧秉持数据的绝对本地安全优先原则。在当前环境生成的 hsimatplog/ 目录下（受 log_dir_name 参数控制）总会忠实保留一份结构化副本：

your_project_dir/
└── hsimatplog/
    └── runs/
        └── Simulation-Engine-<ExpName>-<UUID>/
            ├── config.json       # ✅ 本次实验被 flatten 拍平后的 Config (随 WebSokcet 下发实时覆写)
            ├── run.json          # ✅ 实验的基础元数据
            ├── logs.jsonl        # ✅ 指标记录的时序步骤落盘
            └── system.jsonl      # ✅ 硬件监控时序数据落盘