sequence-base 0.3.0__tar.gz

sequence_base-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+# Run the test suite on every push and pull request.
+#
+# In one sentence: install the [codec] extra (pillow + numpy) and run pytest, so the codec
+# round-trip / geometry drift guard runs on every change — base is what the SDK, gateway, and
+# container all build on, so a break here breaks all three.
+#
+# Upstream trigger  — push to main, or any pull request
+# Downstream effect — a red check on the commit / PR
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"   # base is requires-python >=3.11
+      - name: Install
+        run: |
+          python -m pip install -q --upgrade pip
+          python -m pip install -q -e '.[codec,test]'
+      - name: Test
+        run: python -m pytest -q

sequence_base-0.3.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.env
+.venv/
+*.egg-info/
+.DS_Store

sequence_base-0.3.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.5
+Name: sequence-base
+Version: 0.3.0
+Summary: Shared foundation for the Sequences platform — wire contract, correlation, error taxonomy, constants. Used by the robot SDK, gateway, and container harness.
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.0
+Provides-Extra: codec
+Requires-Dist: numpy>=1.26; extra == 'codec'
+Requires-Dist: pillow>=10; extra == 'codec'
+Provides-Extra: test
+Requires-Dist: jsonschema>=4; extra == 'test'
+Requires-Dist: pytest; extra == 'test'

sequence_base-0.3.0/README.md

@@ -0,0 +1,38 @@
+# sequence-base
+
+The **shared foundation** for the Sequences platform — the wire protocol + primitives that the robot
+SDK, the gateway, and the container harness ALL use, defined once so they cannot drift.
+
+```python
+from sequence_base import Observation, ActionChunk          # contract
+from sequence_base import log, new_rid, HEADER               # correlation
+from sequence_base import TransportWarming, TransportOverloaded  # error taxonomy
+```
+
+## Layout (a subpackage per concern; each grows independently)
+
+```
+sequence_base/
+  contract/     act.py — Observation / ActionChunk / ImageFrame / Proprioception / ActionSpace / ActionStep
+                (grows: chat.py, perceive.py)                          · sdk + gateway + container
+  obs/          rid.py (HEADER, new_rid, clean) · log.py (log, Timer)  · sdk + gateway + container
+  errors/       transport.py (Warming / Rejected / Overloaded / Unavailable)  · gateway + container
+                (grows: client.py)
+  constants/    headers.py · env.py · version.py                       · all three
+  codec/        [P1] image.py (encode/decode) · resize.py — sdk encodes, container decodes; MUST match
+  telemetry/    [P1] events.py — container→gateway event shapes
+```
+
+## The one rule for what goes in here
+
+Only things **used by ≥2 of {sdk, gateway, container}** *and* that would **silently drift** if each
+kept its own copy. Model-specific code (handlers), provider-specific code (drivers), and catalogue
+values (per-model client_resize, pricing, licensing) stay out — in container / gateway / spec.py.
+
+## Install
+
+`pip install -e .` (core = pydantic). The image codec pulls PIL/numpy, so it is an optional extra —
+`pip install -e ".[codec]"` — which the gateway (which never encodes/decodes) skips.
+
+Extracted from `general-sequences/backend/sequences/` (`api/schema.py`, `obs.py`,
+`api/handoff/runpod.py`). Renamed from `sequence-contract` once it grew past just the contract.

sequence_base-0.3.0/docs/platform/README.md

@@ -0,0 +1,66 @@
+# GS deploy platform — 设计总览(Modal-way,GCP-first)
+
+> 本文件夹是**三个 repo(gateway / container / sdk)统一设计文档**的入口。canonical 设计在此(sequence-base 是三方都 import 的共享仓,放这不漂移)。两个 session 协同:一侧做 SDK(用户面),一侧做 container/GPU/gateway/GCP(runtime + control plane);契约见 [contracts.md](contracts.md),eval / CI-CD 半边见 [eval.md](eval.md),账户 / secret 机制见 [accounts.md](accounts.md),定价 / 成本 / 统一费率表 / GCP 成本硬闸见 [billing.md](billing.md),debugging / latency / telemetry 见 [observability.md](observability.md),全部参考见 [references.md](references.md)。**怎么建(workflow + subagent 执行计划、WU 依赖图)→ [START.md](START.md)。**
+
+## 我们要造什么(一句话)
+
+让用户把**自己训好的 policy(如 fine-tuned pi0.5:一个 checkpoint + 一个 `@seq.policy` 类)** 一行 `seq deploy` 上到 GS,`connect(model)` 就能 `act` —— 像 Modal 部署一个 GPU 服务那样,但 policy 的 obs→ActionChunk 合同、episode/streaming、warming 由平台内建。**我们不做训练**(只部署已训好的 checkpoint),不拥有 model / sim / 数据。
+
+这是更大 thesis(GS = 跑 Real2Sim2Real loop 的 compute+编排引擎)的**入口(on-ramp)**:先把「部署 + 服务一个 policy」(loop 的 Stage 6)做实,再扩到大规模 rollout/eval(Stage 3)。deploy 层是入口,不是终点。
+
+## MVP 架构(先做这个):1 worker = 1 VM = 1 L4,on-demand + stop-to-zero
+
+**最简形状 —— 不养 pool、不做 snapshot。**
+- **worker = 一台 GCE L4 VM**(g2-standard-8:8 vCPU / 32GB / 1× L4),跑 harness 容器、装一个 policy。**1 worker = 1 VM = 1 L4 = 1 policy**(pi05 独占显存,一张卡装不下两个 policy)。
+- **按 policy(deployment)现起**:有人 connect 而没有在跑的 worker → gateway `driver.create` 起一台(冷启 boot ~1-2min + 加载 86s)。
+- **scale-to-zero = 关 VM**:reaper 见 idle 过 cooldown → `driver.stop`(GPU 费归零、保 boot 盘);下次 connect 再 start(GCE GPU VM 不能 suspend,只能 stop/start,吃全 boot)。
+- **并行 = 进程级 replica + 加 worker**:一台 worker 内用**进程级 replica(`SubprocessReplica`,非线程)**并发,受 VRAM 限(L4 24GB / pi05 8.6GB ≈ 1~2 个,JAX 关预分配才放得下 2);超了 → 加 VM(每台一张卡),gateway 分流,受 GPU quota + 成本限。
+- **存储 3 处**:① 你本地(deploy)② GCS(耐久,checkpoint 永久存 `gs://…`)③ worker 的 **boot disk**(首次 create 从 GCS 拷权重 45s;**boot disk 在 stop 后存活**,gce-1 → 重启免重拉,权重别放会被清的 Local SSD)。
+
+## 为什么 GCE 裸 VM(不是 Cloud Run)
+
+- **gateway 自己控 scale-to-zero**:按闭环 idle 精确关 / 起 worker(见 reaper),不借云商内建 serverless 的黑盒伸缩。
+- **direct-connect 要一个可直达的 worker**:机器人 `act` 直连 worker 的公网 IP(绕开 gateway 省 hop);Cloud Run 只给代理在前的 URL,拿不到直连 pod。
+- **driver 形状可移植**:`gcloud compute instances create` 起 L4 VM,同形状可复制到 AWS/Azure。
+- L4 24GB 装 pi05 宽裕(serving VRAM ~8.6GB)。
+- ⚠️ **GCE GPU VM 不能 suspend/resume** —— 只能 stop/start,吃全 OS boot(~1-2min)。但 **boot disk 存活**(gce-1):**首次 create** = boot + 45s 拉权重 + JIT;**start-after-stop** = boot + JIT(权重已在盘,免那 45s)。⚠️ warm 83ms / JIT 34s / cold 86s 是 **RTX 4090** 实测(RS-3),L4 带宽只 ~1/3(300 vs 1010 GB/s)→ L4 大概率更慢,**真机重测再定预算**;MVP 接受冷启,SDK warming-wait 兜底。
+
+## 三个 repo 的分工
+
+| repo | 角色 | 详见 |
+|---|---|---|
+| **sequence-sdk** | 用户面:`@seq.*` authoring 装饰器 + `Image`/`Volume` 声明 + `seq deploy` CLI + `connect/act` client。copy Modal 的 DX。 | [sdk.md](sdk.md) |
+| **sequence-container** | harness runtime:跑在 GCE VM 上的容器,加载用户 policy(或 benchmark)、`/act /ping /health`、GCS 拉权重。 | [container.md](container.md) |
+| **sequence-gateway** | control plane / scheduler:`POST /v1/deployments` 注册、`gcp_gce` driver、scheduler(MVP:找 / 起 worker)、fleet state、connect/lease 发直连坐标、gateway 控 scale-to-zero(关 VM)。 | [gateway.md](gateway.md) |
+| **sequence-base** | 共享 wire 契约(三方 import,不漂移):`@seq.*` registry、`POST /v1/deployments` payload、`/act` req/resp。 | [contracts.md](contracts.md) |
+
+数据流(一次 deploy + 一次 act):
+```
+seq deploy  →  gateway POST /v1/deployments(handler ref + manifest + weights URI + image 声明)
+            →  Cloud Build 出 policy 镜像(harness base + 用户 Handler + deps)
+            →  scheduler:有 running worker? 复用 : driver.create/boot GCE L4 VM 跑 harness
+            →  harness:GCS 拉权重 → @seq.load → serve
+connect(model)           →  gateway /v1/act/connect(一次):scheduler.acquire → ensure worker up
+                         →  返回 { worker_url(static IP), cert 指纹, direct_secret(per-worker Bearer), lease_ttl }
+act(obs)  [稳态]         →  worker_url/act 直连(Bearer secret,keepalive)→ ActionChunk   ← 无 gateway hop
+直连失败/归零/lease 过期 →  SDK 回退 gateway 重 connect(ensure_up: start/boot VM → 新 url+secret)→ 恢复直连
+idle → reaper:cooldown 后 stop VM;下次 connect 再 start
+```
+
+**⚠️ 关键:control plane / data plane 分离(不要每步过 gateway)**。每次 `act` 都过 gateway 会给机器人闭环**每步加一个 gateway hop**,正好抵消 SDK 连接复用省下的握手(~184.9ms)。所以:
+- **connect() 经 gateway 一次**(control plane):resolve model → `scheduler.acquire` → ensure worker up → 返回 **worker 直连 URL(static IP)+ cert 指纹 + `SEQ_DIRECT_SECRET`(per-worker、按代数轮换)+ lease**。
+- **之后 act() 直连 worker**(data plane):SDK 保一条 kept-alive 连接到 worker,`Bearer direct_secret` 打 worker `/act` —— **gateway 不在热路径**,一跳保温。
+- **gateway 仍控 scale-to-zero + 兜底**:worker 归零 / 直连失败 / lease 过期 → SDK 透明回退 gateway 重 acquire(ensure_up:start/boot VM)→ 换新 url+secret → 恢复直连。
+- **复用已有件**:harness `transport/auth.py::make_guard(SEQ_DIRECT_SECRET)` 就是这个直连守卫(早期为「pod 公网 IP 上 /act 直连」建的)。
+- **这正是 Modal 的做法(不是分野)**:Modal 同一 deployed function 有两条路 —— `.remote()` 走控制面任务队列(~100ms 派发开销),`@modal.fastapi_endpoint` 是容器**直连 web 端点、绕开队列**;机器人走后者。我们 direct-connect = 后者,gateway = Modal 控制面(只在 setup/warming 在路径里)。
+- **metering**:gateway 不在热路径 → GPU-秒由 gateway lifecycle 计、request 数由 worker 异步 telemetry(`coldstart.emit` 同模式)上报。
+
+## 范围(只做 v1,不过早复杂化)
+
+- **v1(MVP)**:stock pi05 → 自定义 pi 在 GCE L4 上端到端跑通;**1 worker = 1 VM = 1 L4**;`deploy → provision(GCS 拉权重)→ serve → direct-connect → idle 过 cooldown 关 VM`;冷启:首次 create = boot + 45s 拉权重 + JIT,重启免 45s(boot disk 存活,gce-1);83ms/86s 是 4090 数、待 L4 重测(RS-3);SDK warming-wait 兜底。eval 半边:`eval(policy, benchmark)` 批量并行(见 [eval.md](eval.md))。
+- **冷启优化(snapshot / warm pool / weight-cache 等)= 明确不做**,已从本设计删,别过早复杂化;真需要时再从 git 历史捞回。
+
+## 非目标 / 边界
+- **不做训练**;不拥有 model / sim engine / 用户数据(用户 checkpoint pre-stage 到 GCS,平台不 train、不跨租户复用)。
+- **不做 warm pool、不做 snapshot、不做冷启优化**(已从设计删);不做 self-serve 自动镜像 build(先 operator-assisted register)、不做多 region、不做多 provider。
+- eval 半边**已开始规划**(见 [eval.md](eval.md)):**benchmark 是第二类可授权 artifact** —— `@seq.benchmark`「create a benchmark」(LIBERO 是例子,对称于 `@seq.policy`/pi05);`eval()` 是 deploy 后可调的**批量并行函数**(与 `act` 服务解耦、无 gate)。spec 分落 sdk/container/gateway/contracts。首个目标 = agentic VLM + pi0.5 在 LIBERO 上测。simulation-as-product / 更大 Real2Sim2Real loop 仍在此设计之外。

sequence_base-0.3.0/docs/platform/REVIEW.md

@@ -0,0 +1,86 @@
+# plan review —— 2026-09-27(8 个 Opus reviewer,4 维 × review+skeptic)
+
+四维度 reviewer(correctness / trust-and-money / executability / architecture)各配一个反驳型 skeptic 复核。**28 条发现 → 26 确认、2 驳回**(6 blocker / 15 major / 5 minor)。本文是审计线索 + 修复状态;修复直接改进各 md。
+
+## 决策(用户 2026-09-27)
+
+- **worker 直连 TLS**(blocker F1/TM1/A4):选 **公网 IP + 自签证书 + SDK pin**。worker 保留 static external IP(地址稳定跨 stop/start);harness uvicorn 加载自签 cert;connect 响应下发 cert 指纹;SDK 用自定义 SSLContext pin 该指纹(不走默认 CA)。保住「直连省 hop」。
+
+## 状态图例
+
+> ✅ **两轮的确认修复已全部落到各设计 md**(commit 见 git log;含 START 的 E1–E9、accounts 的 A1 secret 模型 + ⑨ TLS + TM2/5/7、billing 的 F1/F3/TM3/TM4/A6、contracts/README/eval/references/container/gateway/sdk/observability 的外部事实与 TLS/composite 修正)。➖=驳回(不改)。落完做过残留自检(无「一次性 secret」「restore/boot」「:8000」「Spot ÷3」等矛盾)。
+
+### Blocker
+| id | doc | 一句话 | 状态 |
+|---|---|---|---|
+| F1 / TM1 / A4 | contracts/container/accounts/gateway/sdk/README | 数据面无 TLS,direct_secret 明文可截获重放;GCE ephemeral IP 会变 | ✅ 公网+自签+pin+static IP |
+| E1 | START | 四 repo 无 `integration` 分支,第一个 `worktree add integration` 就 fatal | ✅ runbook 建分支 + build agent fallback |
+| E2 | START | 跨 repo 的 goal-diff 完整性闸算不出(goals 在 base、commit 在目标 repo) | ✅ verifier 在 base 仓查 goal diff |
+| E3 | START | 每个 WU 强制 USER-TEST,基础件(W0.1/C1/C2/G1/A2)无用户面必 escalate | ✅ USER-TEST 降到里程碑级 + user_task 可选 |
+| A1 | accounts | direct_secret per-worker 单值、每 connect 覆盖 → 多机器人互踢 | ✅ 改长寿命 secret、epoch=worker 代数 |
+
+### Major
+| id | doc | 一句话 | 状态 |
+|---|---|---|---|
+| E4 | START | BUILD schema 单 commit 装不下跨仓 WU(W0.2/G1/O5) | ✅ commits[] 数组 |
+| E5 | START/sdk | `@seq.plan` 只在 C4,SDK 侧无 WU 建装饰器 | ✅ PLAN flag 进 W0.1、装饰器进 S1 |
+| E6 | START | O1–O5 没排进 wave 图;「同 wave」违反无 barrier | ✅ 排进 wave 图 |
+| E7 | START/billing | real-tier VM 预算 ≤2 单 agent vs 整 run 口径打架 | ✅ 每 WU ≤1 VM、real run 串行 |
+| E8 | START | REVIEW reviewer 挂掉 fail-open 放行 | ✅ `(!rv || rv.blocking)` |
+| TM2 | accounts/billing | eval `reserved_usd` 余额判定不读 → 并发 eval 穿透超花 | ✅ 预留落成 usage 行 + 缓存同步 |
+| TM3 | gateway/billing | `daily_spend_cap` 算瞬时燃烧非当日累计 → churn 绕过 | ✅ 改当日累计 |
+| TM4 | billing/gateway | killswitch 删 Cloud Run service、不碰 GCE VM → GPU 照烧 | ✅ 改按标签停 GCE 实例 |
+| TM5 | accounts | GPU-秒三处写入无幂等键 → 重复计费 | ✅ record_id=(instance,window) |
+| TM7 | accounts | serve 敞口低估,应是 (boot+cooldown)×单价 | ✅ 改敞口不变式 |
+| A2 | container/sdk/eval | batched composite 与单例 self.instruction 冲突 | ✅ plan 状态 keyed by env |
+| A3 | eval/container | openpi main.py 是 websocket、单 env,不「正好对上 /act」 | ✅ 改「抽 sim 驱动 + 向量化」 |
+| A6 | billing/gateway | serve+eval GPU 上限画在 2 卡池、无全局记账 | ✅ 全局 GPU 会计 |
+| A7 | container/accounts | pi05 真 checkpoint 可能首-load 联网自取,与「从你桶挂载」冲突 | ✅ 加 provenance 核实 |
+
+### Minor
+| id | doc | 一句话 | 状态 |
+|---|---|---|---|
+| F2 | contracts | 端口 8000 应是 8080 | ✅ |
+| F3 | accounts | 漏 `/v1/perceive`(代码注释警告过的 stale) | ✅ |
+| F4 | references | 还留被删的 snapshot 归零结论、与 v1 矛盾 | ✅ 标为已弃 |
+| E9 | START | C5 依赖标成 S5 应是 W0.1 | ✅ |
+| A8 | README/gateway | 权重落盘持久性三处互斥 | ✅ 定死放被保留的 boot disk |
+
+### 驳回(skeptic 判 real=false,不改)
+| id | 为什么不改 |
+|---|---|
+| TM6 | 脱敏「矛盾」不成立:不变式限的是「不进主进程**环境**/端点」,不是「值绝不进主进程内存」;harness 主进程本就是取 secret 注入子进程的那方,建脱敏表不违反 |
+| A5 | reaper idle「只靠异步 usage」不成立:gateway.md 已明写 last_used 由 usage 上报 **+ lease 续租**两条腿刷新 |
+
+---
+
+# 第 2 轮:联网核对外部事实(gs-plan-webcheck,task wuvobw554)
+
+4 维(gce-compute / gcp-billing-security / modal / robotics-stack)× reviewer + skeptic(独立**重搜**证伪),每条带 source_url。**11 条 → 7 确认记错(0 blocker / 5 major / 2 minor)、4 驳回;32 条 load-bearing 外部主张验证为对**(Modal DX 映射、GCE suspend/quota/实例身份 JWT/metadata 限额、budget 非硬顶 + Pub/Sub killswitch + detach-billing、Secret Manager 角色、GCS/AR/disk 价、on-demand $0.85 —— 全部核实无误)。
+
+### 确认记错(real=true,待改)
+| id | doc | plan 记错 | 实际(官方) | 状态 |
+|---|---|---|---|---|
+| RS-1 | eval/container | openpi `main.py`「正好对上 harness /act」 | 它是 **msgpack-over-websocket**(`WebsocketClientPolicy` → `serve_policy` 的 `WebsocketPolicyServer`),单-env 顺序 loop,非 HTTP REST | ✅ 改「复用 env-loop,把 infer 那步换成进程内 batched policy.act」(= 一轮 A3) |
+| RS-2 | eval | 用 `pi05_droid` 跑 LIBERO baseline | LIBERO SOTA 是 **`pi05_libero`** checkpoint(README 96.85 avg);droid 的 LIBERO 数不可比 | ✅ baseline 用 pi05_libero;droid 仅作 wire 占位须标注 |
+| RS-3 | references/README | 83ms/34s JIT/86s 当 L4 冷启预算 | 那是 **RTX 4090** 数;L4 带宽 ~1/3(300 vs 1010 GB/s)、FP16 tensor ~73% → L4 warm 大概率数百 ms、JIT 更久 | ✅ 标注 4090 基线、R1/M3 真机重测(= 一轮 improvement) |
+| gce-1 | README | 权重「VM 关即失」、start-after-stop 吃全 45s 重拉 | **boot disk 在 stop 后存活**(只 Local SSD 丢);权重放 boot disk → 重启免 GCS 重拉,只 JIT | ✅ 权重落 boot disk;重启建模为 JIT-only(顺带定死 A8) |
+| F1 | billing | Spot ≈ on-demand 的 1/3 | L4 spot 只省 ~15%($0.72–0.74 vs $0.85);「91% off」不适用抢手的 L4/G2 | ✅ 改 gpu_rates spot 价 + 删「÷3」措辞 |
+| F2 | accounts | `roles/compute.instanceAdmin`(无 .v1) | 预定义角色是 `roles/compute.instanceAdmin.v1`;且 gateway SA 还需 `roles/iam.serviceAccountUser` 才能把 worker SA 附到 VM | ✅ |
+| F3 | billing | 成本表漏 external IP | in-use external IPv4 ~$0.005/hr(spot VM ~$0.0025);teardown 随 VM release,别留 reserved 空转 | ✅ 加一行 |
+
+### 驳回(real=false / 不构成 plan 错)
+| id | 结论 |
+|---|---|
+| modal-tls-gap | Modal 自带 managed TLS(*.modal.run)属实,但我们**已决**公网+自签+pin 正是为补这个 gap → 非 plan 错,已在 TLS 决策里 own |
+| RS-4 | Isaac Sim「几十 GB」不算错:NGC 当前 tag 压缩 9.9GB、解压几十 GB;finding 引的 7GB 是过时值 |
+| gce-2 | finding 的 web_says 错了:static IP 挂在**停机**实例上仍算 in-use($0.005/hr),不是它说的 $0.01/hr 更贵档 → 用 F3 的正确版 |
+| F4 | killswitch 官方 sample 确实硬编 zone/无 label,但 plan 本就说要「adapt」→ 已被一轮 TM4 覆盖 |
+
+## 高价值 improvement(已并入对应修复)
+- secret 模型简化(长寿命 per-worker,epoch=worker 代数)→ 解 A1。
+- 活性权威归一:reaper 认 `lease_expires_at`,lease 过期先探 `/ping` 再 terminate。
+- pi05 的 83ms/86s/290MB/s 是 RunPod-4090/S3 基线,非 L4 → R1/M3 goal 改「量出并记录 L4 数」。
+- eval 端点校验 caller 拥有 model+benchmark(403)。
+- USER-TEST 前由 workflow 显式拉起 mock 端点。
+- dashboard/results-store 补归属 WU 或把 `dashboard_url` 标 optional。