Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

feat(runtime): establish honest starter environment

kashorincb0b061e5c8b
diff --git a/docs/guide/packages.md b/docs/guide/packages.md
index 46525097..5eadbe14 100644
--- a/docs/guide/packages.md
+++ b/docs/guide/packages.md
@@ -125,7 +125,7 @@ never on exact-model packages or the CLI.
```text
@hypit/provider-kie KIE generation plus background removal
-@hypit/provider-hypihub HypiHub paid generation and Gemini VLM gateway
+@hypit/provider-hypihub HypiHub generation, Gemini VLM and WhisperX gateway
@hypit/provider-media-local local ffprobe/ffmpeg
@hypit/provider-whisperx-local local WhisperX service
@hypit/provider-hyperframes-local local Chrome rendering
diff --git a/docs/guide/providers.md b/docs/guide/providers.md
index 6d96d9e1..edea4345 100644
--- a/docs/guide/providers.md
+++ b/docs/guide/providers.md
@@ -135,6 +135,18 @@ start work. It keeps environment names as references until a matching Need is ha
presence is diagnosed through the generic CredentialStore path; a Provider must not special-case
environment variables as a secret Store.
+An activation may also return `diagnose(context)`. It runs only for an explicit active `doctor`, after
+the Runtime has resolved that Endpoint's declared credential slots. It may make a bounded, read-only
+request to the real service, such as reading the authenticated model catalog. It must not be called by
+Build preflight and must never submit generation work.
+
+A paid capability may declare `quote(context)` beside its handler. The quote belongs to the Provider
+because the selected Provider owns the currency, rate card and routing facts. It receives one exact
+`Need`, may read a live rate card, and returns either an estimate with its source and observation time
+or an honest `unknown`; it never submits work. Do not copy changing service prices into Core, model
+packages, the CLI or Skill. A static graph plan does not yet claim a complete total when exact downstream
+Needs are only produced during execution.
+
## 5. Declare a Managed Program when needed
If the Provider depends on a warm external program, export its declaration beside the Endpoint.
@@ -170,10 +182,10 @@ const adapter = createRuntimeEndpointAdapterFacet({
});
```
-`hypit runtime up` prepares, starts and probes declared Managed Programs before starting the
+`hypit runtime up` prepares, starts and probes declared **local** Managed Programs before starting the
durable Worker. `build` only preflights Programs backing capabilities demanded by its plan and
fails before submission when one is not ready; it never installs or starts one. Providers that call
-only remote APIs omit `program` entirely.
+only remote APIs omit `program` entirely; Hypit has no `up` or `down` lifecycle for those services.
## 6. Install
diff --git a/docs/guide/runtime.md b/docs/guide/runtime.md
index 16e83eae..bc341498 100644
--- a/docs/guide/runtime.md
+++ b/docs/guide/runtime.md
@@ -196,6 +196,7 @@ their declared programs. The commands do not open SQLite or Credential Stores.
## Lifecycle
```bash
+hypit runtime init
hypit runtime use hypit.runtime.json
hypit runtime up
hypit runtime status
@@ -203,6 +204,13 @@ hypit runtime logs
hypit runtime down
```
+`runtime init` writes the video Distribution's starter Profile to `hypit.runtime.json` and selects
+it for the resolved project. It refuses to overwrite an existing file. This is a local file operation:
+it installs no package, contacts no service, requests no credential and starts no Worker. The official
+starter selects HypiHub for remote generation, Gemini and WhisperX, plus local media processing and
+HyperFrames rendering. This is a Distribution default, not a Core rule; edit the Profile or select a
+different one when using BYOK or local Providers.
+
`runtime use` binds one explicit Profile to one already resolved project. The project comes from
`--workspace`, or from the current directory's declared package boundary; the selection never
defines that boundary. Commands read only `<project>/.hypit/runtime`: they do not scan for a
@@ -210,8 +218,18 @@ conventionally named Profile and do not inherit a selection from a parent projec
therefore select separately, even when their Profiles declare equivalent external Endpoints.
`runtime up` asks npm to prepare the selected adapters' exact upstream packages in the shared
-machine home, prepares declared Managed Programs, then starts the local Worker. `build` performs no
-provisioning: it runs cheap read-only preflight, submits work only when ready, and ensures the Worker
+machine home, prepares declared **local** Managed Programs, then starts the local Worker. It does not
+start, restart, log into or probe remote Endpoints such as HypiHub. `runtime down` stops only the
+local Worker; separately managed local Programs remain available until `programs down`.
+
+`doctor` is the active read-only environment check. It resolves declared credentials and lets each
+selected Endpoint verify its real environment; a remote Provider may therefore contact its bounded
+catalog or capability endpoint. Login proves only that a credential exists, while a successful doctor
+proves that the selected Endpoint's declared capabilities can be routed by that account at that moment.
+Ordinary `check`, `plan` and Build preflight
+never run these active probes and never turn environment inspection into a hidden network request.
+
+`build` performs no provisioning: it runs cheap read-only preflight, submits work only when ready, and ensures the Worker
is available. `activity` and `cancel` observe or control active work. `status` reads Runtime and Result as
independent sources, so failure on one side neither invents nor hides facts on the other. Without a
Runtime, a finished Result proves only its own outcome.
diff --git a/docs/quickstart.md b/docs/quickstart.md
index c0404e42..8911a12f 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -110,11 +110,19 @@ Keep project files and generated media outside the installed Hypit Distribution.
```bash
cd /path/to/my-video
-hypit runtime use hypit.runtime.json
+hypit runtime init
+hypit auth login hypihub.default
+hypit doctor
hypit plan build.svrun
```
+`runtime init` creates and selects the official starter Profile without installing anything or
+contacting a service. That Profile uses HypiHub for remote generation, Gemini vision and WhisperX
+alignment, and local Endpoints for media processing and HyperFrames rendering. If the project already
+has an intentional Profile, select it with `hypit runtime use <profile>` instead; initialization never
+overwrites one.
+
A project with `package.json` owns its third-party packages. A plain creative folder needs no Node
project and uses official packages from the installed Distribution. Source and exported files remain in the
project. By default, Build Results live under the project's `.hypit/results`; a project-owned
@@ -141,7 +149,8 @@ hypit build build.svrun --follow
`build` first repeats the same cheap local preflight, then assigns a fresh Build id, stores the Build
and ensures its Worker is available. It never installs a package or starts a Managed Program. Run
-`hypit runtime up` explicitly when the selected deployment is not ready. `--follow` is only an
+`hypit runtime up` explicitly when the selected local Runtime is not ready. It prepares local
+dependencies, Programs and the Worker; it does not start or probe HypiHub. `--follow` is only an
observer; closing it does not stop the Build.
Use `check` while editing a source. Use `doctor` to diagnose a new or broken deployment. They are
@@ -171,7 +180,7 @@ Install only what your selected Runtime Profile needs:
| `ffmpeg` / `ffprobe` | using local media inspection, normalization or muxing |
| Python 3.10–3.13 and `uv` | using local WhisperX or OpenCV |
| Chromium | managed automatically by local HyperFrames rendering |
-| API credentials | selecting remote KIE, Xiaomi or AWS endpoints |
+| API credentials | selecting HypiHub or other remote Endpoints |
Upstream npm packages are demand-loaded into the shared machine package home shown by `hypit
paths`; they are not copied into every project. `runtime up` prepares the exact npm packages required
diff --git a/docs/quickstart/run.md b/docs/quickstart/run.md
index e7fc0db7..e33d0ff7 100644
--- a/docs/quickstart/run.md
+++ b/docs/quickstart/run.md
@@ -229,12 +229,14 @@ as Endpoint capacity. It never selects the Runtime Host or defines the Source Wo
packages or project Result repository.
```bash
-hypit runtime use hypit.runtime.json
+hypit runtime init
hypit paths
```
-`runtime use` writes only `.hypit/runtime`. It does not start a Worker, create Runtime data or
-change installed packages. See [Runtime](../guide/runtime.md) for the Profile schema and boundaries.
+`runtime init` writes the video Distribution's starter `hypit.runtime.json` and selects it. It refuses
+to overwrite an existing file, installs nothing, contacts no service and starts no Worker. For an
+existing intentional Profile, use `hypit runtime use <profile>`; that command writes only
+`.hypit/runtime`. See [Runtime](../guide/runtime.md) for the Profile schema and boundaries.
The CLI resolves the project first: `--workspace` is an explicit boundary; otherwise the nearest
`package.json` above the current directory is the boundary, falling back to the current directory
for a plain creative folder. It then reads only that project's `.hypit/runtime`. It never discovers
@@ -249,7 +251,7 @@ variables referenced by the selected Runtime Profile:
| Variable | Provider/use |
|---|---|
-| HypiHub OAuth | HypiHub paid generation and Gemini VLM; run `hypit auth login hypihub.default --runtime hypit.runtime.json` |
+| HypiHub OAuth | HypiHub paid generation, Gemini VLM and WhisperX alignment; run `hypit auth login hypihub.default --runtime hypit.runtime.json` |
| `KIE_API_KEY` | Explicit KIE Provider only |
| `MIMO_API_KEY` | Xiaomi MiMo VoiceDesign, only when the official Endpoint is explicitly selected |
@@ -346,8 +348,10 @@ external-program diagnostics. It never starts external work.
`plan` may run without a Runtime at all. Both `plan` and `build` may omit `--runtime` after
`hypit runtime use`; `build` requires either that selection or an explicit Profile.
-Use `runtime up` after selecting or changing a deployment to install selected upstream packages,
-prepare Managed Programs and start the Worker. `build` repeats only the cheap read-only preflight
+Use `runtime up` after selecting or changing a Profile to install selected upstream packages,
+prepare local Managed Programs and start the local Worker. It does not start or probe remote
+Endpoints. Use `doctor` for an active, read-only check of configured remote capabilities. `build`
+repeats only the cheap read-only preflight
and refuses before submission when a required package or Program is missing; it never provisions
dependencies. When the deployment is already prepared and only its Worker is stopped, `build`
starts that Worker before durable submission. `runtime status` observes
diff --git a/docs/zh/guide/packages.md b/docs/zh/guide/packages.md
index a29e8b12..8141056b 100644
--- a/docs/zh/guide/packages.md
+++ b/docs/zh/guide/packages.md
@@ -117,7 +117,7 @@ Frontend;不存在一个认识全部语法的中央解析器。
```text
@hypit/provider-kie KIE 生成与去背景
-@hypit/provider-hypihub HypiHub 付费生成与 Gemini VLM 网关
+@hypit/provider-hypihub HypiHub 生成、Gemini VLM 与 WhisperX 网关
@hypit/provider-media-local local ffprobe/ffmpeg
@hypit/provider-whisperx-local local WhisperX service
@hypit/provider-hyperframes-local local Chrome rendering
diff --git a/docs/zh/guide/providers.md b/docs/zh/guide/providers.md
index c2427e60..ea7330d0 100644
--- a/docs/zh/guide/providers.md
+++ b/docs/zh/guide/providers.md
@@ -129,6 +129,16 @@ export default hypitPackage;
capability 和调度事实。Activation 不得解析密钥或环境来源的部署值、访问网络或启动任务;环境变量名会作为引用保留到真正处理匹配 Need 时。凭据是否存在由通用 CredentialStore 路径诊断,
Provider 不得把环境变量硬编码成特殊的密钥 Store。
+Activation 还可以返回 `diagnose(context)`。它只会在用户显式运行主动 `doctor` 时执行,而且
+Runtime 会先解析该 Endpoint 自己声明的凭据槽。它可以对真实服务做一次有界只读请求,例如读取
+已认证账户的模型目录;Build 预检不能调用它,它也绝不能提交生成任务。
+
+付费 capability 可以在 handler 旁声明 `quote(context)`。价格属于 Provider,因为币种、价目和
+真实路由都是所选 Provider 的事实。报价接收一项已经完整形成的准确 `Need`,可以读取实时价目,
+返回带来源和观察时间的估价,或诚实返回 `unknown`;它绝不提交任务。不能把会变动的服务价格
+复制进 Core、模型包、CLI 或 Skill。当下游准确 Need 只能在执行中产生时,静态图 Plan 暂时不能
+假装给出完整总价。
+
## 5. 按需声明 Managed Program
如果 Provider 依赖需要保持温热的外部程序,就在 Endpoint 旁边导出它的声明。这里没有第二个
@@ -164,9 +174,9 @@ const adapter = createRuntimeEndpointAdapterFacet({
});
```
-`hypit runtime up` 会准备、启动并探测 Managed Program,然后启动耐久 Worker。`build` 只预检
+`hypit runtime up` 会准备、启动并探测**本地** Managed Program,然后启动耐久 Worker。`build` 只预检
本次 Plan 所需 Capability 对应的 Program;未就绪时在提交前失败,绝不安装或启动它。只调用
-远程 API 的 Provider 不返回 `program`。
+远程 API 的 Provider 不返回 `program`,Hypit 也没有可以启动或停止这类服务的生命周期。
## 6. 声明依赖
diff --git a/docs/zh/guide/runtime.md b/docs/zh/guide/runtime.md
index 43f8bafb..0ced6a4d 100644
--- a/docs/zh/guide/runtime.md
+++ b/docs/zh/guide/runtime.md
@@ -181,6 +181,7 @@ SQLite 或 Credential Store。
## 生命周期
```bash
+hypit runtime init
hypit runtime use hypit.runtime.json
hypit runtime up
hypit runtime status
@@ -188,13 +189,28 @@ hypit runtime logs
hypit runtime down
```
+`runtime init` 会把视频 Distribution 提供的起始 Profile 写入 `hypit.runtime.json`,并为已经解析
+出的项目选择它;已有文件一律拒绝覆盖。这只是本地文件操作:不安装包、不连接服务、不索取凭据,
+也不启动 Worker。官方起始 Profile 使用 HypiHub 提供远程生成、Gemini 与 WhisperX,使用本地
+Endpoint 处理媒体并通过 HyperFrames 渲染。这是 Distribution 的开箱选择,不是 Core 规则;使用
+BYOK 或本地 Provider 时可以编辑 Profile 或选择另一份 Profile。
+
`runtime use` 把一份显式 Profile 绑定到一个已经解析完成的项目。项目来自 `--workspace`,
或当前目录声明的 package 边界;Runtime 选择不能反过来定义项目。命令只读取
`<project>/.hypit/runtime`,不会扫描约定文件名,也不会继承父项目的选择。即使几个项目声明
了等价的外部 Endpoint,它们也必须分别完成选择。
-`runtime up` 先让 npm 把所选 Adapter 的精确上游包准备到机器共享目录,再准备 Managed
-Program 并启动本地 Worker。`build` 不做部署:它执行便宜只读预检,只在就绪后提交,并确保
+`runtime up` 先让 npm 把所选 Adapter 的精确上游包准备到机器共享目录,再准备所选的**本地**
+Managed Program 并启动本地 Worker。它不会启动、重启、登录或探测 HypiHub 这类远程 Endpoint。
+`runtime down` 只停止本地 Worker;由 Runtime 管理的本地 Program 会继续可用,直到显式运行
+`programs down`。
+
+`doctor` 才是主动但只读的环境检查。它解析已声明的凭据,并允许每个所选 Endpoint 检查真实
+环境;远程 Provider 因而可以访问一次有界的模型目录或能力接口。登录成功只证明凭据存在,
+doctor 成功才证明该账户此刻可以路由所选 Endpoint 声明的能力。普通 `check`、`plan` 和 Build 预检都不会运行这类
+主动探测,也不会把环境检查偷换成隐藏网络请求。
+
+`build` 不做部署:它执行便宜只读预检,只在就绪后提交,并确保
Worker 可用。`activity`、`cancel` 用来观察和控制活跃工作;`status` 分别读取 Runtime 与 Result,一边失败
不会伪造或吞掉另一边的事实。没有 Runtime 时,已完成 Result 也只证明 Result 的 outcome,不能反推 Runtime。
diff --git a/docs/zh/quickstart.md b/docs/zh/quickstart.md
index f4009e24..c74b6c24 100644
--- a/docs/zh/quickstart.md
+++ b/docs/zh/quickstart.md
@@ -106,11 +106,18 @@ Runtime Profile 说明在哪里做。
```bash
cd /path/to/my-video
-hypit runtime use hypit.runtime.json
+hypit runtime init
+hypit auth login hypihub.default
+hypit doctor
hypit plan build.svrun
```
+`runtime init` 会创建并选择官方起始 Profile,但不安装任何东西,也不连接服务。该 Profile 让
+HypiHub 提供远程生成、Gemini 视觉观察和 WhisperX 对齐,让本地 Endpoint 负责媒体处理与
+HyperFrames 渲染。项目已经拥有明确 Profile 时,改用 `hypit runtime use <profile>`;初始化绝不
+覆盖已有文件。
+
含有 `package.json` 的项目负责自己的第三方包;普通创作文件夹不需要成为 Node 项目,直接使用
Distribution 里的官方包。默认情况下,完整 Build Result 位于项目的 `.hypit/results`;Profile
不管理 Result,项目根的 `hypit.results.json` 可以把同一套 Result 模型指向 S3。Runtime 活跃状态与临时
@@ -134,7 +141,8 @@ hypit build build.svrun --follow
`build` 会先重复同一套便宜的本地预检,再分配新的 Build id、持久化 Build 并确保 Worker
可用。它不会安装包,也不会启动 Managed Program;部署未就绪时应显式运行
-`hypit runtime up`。`--follow` 只是观察器;关掉它不会停止 Build。
+`hypit runtime up`。它只准备本地依赖、Program 与 Worker,不会启动或探测 HypiHub。
+`--follow` 只是观察器;关掉它不会停止 Build。
编辑源码时使用 `check`;配置或排查部署时使用 `doctor`。它们都不会提交工作,但也不是每次
Build 前必须重复的仪式。
@@ -162,7 +170,7 @@ Scalar 与 Resource 导出为文件;Composite 导出为包含 `value.json` 及
| `ffmpeg` / `ffprobe` | 使用本地媒体检查、归一化或 mux 时 |
| Python 3.10–3.13 与 `uv` | 使用本地 WhisperX 或 OpenCV 时 |
| Chromium | 本地 HyperFrames 渲染时由 Adapter 管理 |
-| API 凭据 | 选择 KIE、Xiaomi 或 AWS Endpoint 时 |
+| API 凭据 | 选择 HypiHub 或其他远程 Endpoint 时 |
准备本地 Python 程序:
diff --git a/docs/zh/quickstart/run.md b/docs/zh/quickstart/run.md
index 9196044a..1fc048b6 100644
--- a/docs/zh/quickstart/run.md
+++ b/docs/zh/quickstart/run.md
@@ -195,10 +195,14 @@ Store 与 Endpoint,并配置 Endpoint 容量等部署参数;它不选择 Run
Workspace、Author 包或项目 Result Repository。
```bash
-hypit runtime use hypit.runtime.json
+hypit runtime init
hypit paths
```
+`runtime init` 会写入视频 Distribution 提供的起始 `hypit.runtime.json` 并完成选择。它不覆盖
+已有文件,不安装任何东西、不连接服务,也不启动 Worker。项目已有明确 Profile 时,使用
+`hypit runtime use <profile>`;该命令只写入 `.hypit/runtime`。
+
`runtime use` 只写入 `.hypit/runtime`,不会启动 Worker、创建 Runtime 数据或修改已安装
包。Profile 结构和完整边界见 [Runtime](../guide/runtime.md)。
CLI 必须先确定项目:显式 `--workspace` 直接给出边界;否则使用当前目录向上的最近
@@ -212,7 +216,7 @@ CLI 必须先确定项目:显式 `--workspace` 直接给出边界;否则使
| 变量 | Provider / 用途 |
|---|---|
-| HypiHub OAuth | HypiHub 付费生成与 Gemini VLM;运行 `hypit auth login hypihub.default --runtime hypit.runtime.json` 并在 https://hypit.ai 登录 |
+| HypiHub OAuth | HypiHub 付费生成、Gemini VLM 与 WhisperX 对齐;运行 `hypit auth login hypihub.default --runtime hypit.runtime.json` 并在 https://hypit.ai 登录 |
| `KIE_API_KEY` | 仅在显式选择 KIE Provider 时使用 |
| `MIMO_API_KEY` | Xiaomi MiMo VoiceDesign;只有明确选择官方 Endpoint 时才需要 |
@@ -338,7 +342,8 @@ Runtime 后只预检这次计划真正需要的 Endpoint、凭据和外部程序
`plan` 可以完全不带 Runtime;执行过 `hypit runtime use` 后,`plan` 和 `build` 都不必再写
`--runtime`。`build` 必须能找到所选或显式 Profile。
-选择或改变部署后,用 `runtime up` 安装所选上游依赖、准备 Managed Program 并启动 Worker。
+选择或改变 Profile 后,用 `runtime up` 安装所选上游依赖、准备本地 Managed Program 并启动
+本地 Worker。它不会启动或探测远程 Endpoint;需要主动只读检查远程能力时使用 `doctor`。
`build` 只重跑便宜的只读预检;任何依赖或 Program 未就绪都会在提交前失败,绝不在 Build
中准备它们。若部署已经准备完毕而只有 Worker 停止,`build` 会在耐久提交前启动该 Worker。
`runtime status` 用于观察,`programs up|status|down` 只管理外部程序。
diff --git a/examples/interview/hypit.runtime.json b/examples/interview/hypit.runtime.json
index 1cda8ac8..603a636b 100644
--- a/examples/interview/hypit.runtime.json
+++ b/examples/interview/hypit.runtime.json
@@ -1,49 +1,47 @@
{
- "format": "hypit.runtime-profile@1",
- "runtime": {
- "use": "@hypit/runtime-local",
- "config": {
- "dataRoot": ".hypit/runtimes/local",
- "artifacts": {
- "use": "@hypit/artifact-store-fs",
- "config": { "path": "artifacts" }
- },
- "credentials": {
- "os": { "use": "@hypit/credential-store-os" }
- },
- "endpoints": {
- "hypihub.hypit-interview": {
- "use": "@hypit/provider-hypihub",
- "pool": "generation",
- "config": {
- "baseUrl": "https://hypit.ai",
- "apiKey": { "store": "os", "key": "hypihub.oauth" },
- "defaultConcurrency": 4,
- "requestTimeoutMs": 120000
- }
- },
- "media.hypit-interview": {
- "use": "@hypit/provider-media-local",
- "pool": "media",
- "config": { "defaultConcurrency": 2 }
- },
- "whisperx.hypit-interview": {
- "use": "@hypit/provider-whisperx-local",
- "pool": "alignment",
- "config": {
- "expectedModel": "large-v3",
- "defaultConcurrency": 1
- }
+ "format": "hypit.runtime-local@1",
+ "dataRoot": ".hypit/runtimes/local",
+ "credentials": {
+ "os": {
+ "use": "@hypit/credential-store-os"
+ }
+ },
+ "endpoints": {
+ "hypihub.hypit-interview": {
+ "use": "@hypit/provider-hypihub",
+ "pool": "generation",
+ "config": {
+ "baseUrl": "https://hypit.ai",
+ "apiKey": {
+ "store": "os",
+ "key": "hypihub.oauth"
},
- "hyperframes.hypit-interview": {
- "use": "@hypit/provider-hyperframes-local",
- "pool": "render",
- "config": {
- "workers": 2,
- "quality": "standard",
- "defaultConcurrency": 1
- }
- }
+ "defaultConcurrency": 4,
+ "requestTimeoutMs": 120000
+ }
+ },
+ "media.hypit-interview": {
+ "use": "@hypit/provider-media-local",
+ "pool": "media",
+ "config": {
+ "defaultConcurrency": 2
+ }
+ },
+ "whisperx.hypit-interview": {
+ "use": "@hypit/provider-whisperx-local",
+ "pool": "alignment",
+ "config": {
+ "expectedModel": "large-v3",
+ "defaultConcurrency": 1
+ }
+ },
+ "hyperframes.hypit-interview": {
+ "use": "@hypit/provider-hyperframes-local",
+ "pool": "render",
+ "config": {
+ "workers": 2,
+ "quality": "standard",
+ "defaultConcurrency": 1
}
}
}
diff --git a/examples/podcast/hypit.runtime.json b/examples/podcast/hypit.runtime.json
index ac0724a0..75956ab7 100644
--- a/examples/podcast/hypit.runtime.json
+++ b/examples/podcast/hypit.runtime.json
@@ -1,50 +1,50 @@
{
- "format": "hypit.runtime-profile@1",
- "runtime": {
- "use": "@hypit/runtime-local",
- "config": {
- "dataRoot": ".hypit/runtimes/local",
- "artifacts": {
- "use": "@hypit/artifact-store-fs",
- "config": { "path": "artifacts" }
- },
- "credentials": {
- "env": { "use": "@hypit/credential-store-env" },
- "os": { "use": "@hypit/credential-store-os" }
- },
- "endpoints": {
- "hypihub.hypit-podcast": {
- "use": "@hypit/provider-hypihub",
- "pool": "generation",
- "config": {
- "baseUrl": "https://hypit.ai",
- "apiKey": { "store": "os", "key": "hypihub.oauth" },
- "defaultConcurrency": 4,
- "requestTimeoutMs": 120000
- }
- },
- "media.hypit-podcast": {
- "use": "@hypit/provider-media-local",
- "pool": "media",
- "config": { "defaultConcurrency": 2 }
- },
- "whisperx.hypit-podcast": {
- "use": "@hypit/provider-whisperx-local",
- "pool": "alignment",
- "config": {
- "expectedModel": "small",
- "defaultConcurrency": 1
- }
+ "format": "hypit.runtime-local@1",
+ "dataRoot": ".hypit/runtimes/local",
+ "credentials": {
+ "env": {
+ "use": "@hypit/credential-store-env"
+ },
+ "os": {
+ "use": "@hypit/credential-store-os"
+ }
+ },
+ "endpoints": {
+ "hypihub.hypit-podcast": {
+ "use": "@hypit/provider-hypihub",
+ "pool": "generation",
+ "config": {
+ "baseUrl": "https://hypit.ai",
+ "apiKey": {
+ "store": "os",
+ "key": "hypihub.oauth"
},
- "hyperframes.hypit-podcast": {
- "use": "@hypit/provider-hyperframes-local",
- "pool": "render",
- "config": {
- "workers": 2,
- "quality": "standard",
- "defaultConcurrency": 1
- }
- }
+ "defaultConcurrency": 4,
+ "requestTimeoutMs": 120000
+ }
+ },
+ "media.hypit-podcast": {
+ "use": "@hypit/provider-media-local",
+ "pool": "media",
+ "config": {
+ "defaultConcurrency": 2
+ }
+ },
+ "whisperx.hypit-podcast": {
+ "use": "@hypit/provider-whisperx-local",
+ "pool": "alignment",
+ "config": {
+ "expectedModel": "small",
+ "defaultConcurrency": 1
+ }
+ },
+ "hyperframes.hypit-podcast": {
+ "use": "@hypit/provider-hyperframes-local",
+ "pool": "render",
+ "config": {
+ "workers": 2,
+ "quality": "standard",
+ "defaultConcurrency": 1
}
}
}
diff --git a/examples/ranking-football/hypit.runtime.json b/examples/ranking-football/hypit.runtime.json
index 17b03ee2..b9ec1353 100644
--- a/examples/ranking-football/hypit.runtime.json
+++ b/examples/ranking-football/hypit.runtime.json
@@ -1,46 +1,46 @@
{
- "format": "hypit.runtime-profile@1",
- "runtime": {
- "use": "@hypit/runtime-local",
- "config": {
- "dataRoot": ".hypit/runtimes/local",
- "artifacts": {
- "use": "@hypit/artifact-store-fs",
- "config": { "path": "artifacts" }
- },
- "credentials": {
- "os": { "use": "@hypit/credential-store-os" }
- },
- "endpoints": {
- "hypihub.football-ranking": {
- "use": "@hypit/provider-hypihub",
- "pool": "generation",
- "config": {
- "baseUrl": "https://hypit.ai",
- "apiKey": { "store": "os", "key": "hypihub.oauth" },
- "defaultConcurrency": 4,
- "requestTimeoutMs": 120000
- }
- },
- "media.football-ranking": {
- "use": "@hypit/provider-media-local",
- "pool": "media",
- "config": { "defaultConcurrency": 2 }
- },
- "whisperx.football-ranking": {
- "use": "@hypit/provider-whisperx-local",
- "pool": "alignment",
- "config": { "defaultConcurrency": 1 }
+ "format": "hypit.runtime-local@1",
+ "dataRoot": ".hypit/runtimes/local",
+ "credentials": {
+ "os": {
+ "use": "@hypit/credential-store-os"
+ }
+ },
+ "endpoints": {
+ "hypihub.football-ranking": {
+ "use": "@hypit/provider-hypihub",
+ "pool": "generation",
+ "config": {
+ "baseUrl": "https://hypit.ai",
+ "apiKey": {
+ "store": "os",
+ "key": "hypihub.oauth"
},
- "hyperframes.football-ranking": {
- "use": "@hypit/provider-hyperframes-local",
- "pool": "render",
- "config": {
- "workers": 2,
- "quality": "standard",
- "defaultConcurrency": 1
- }
- }
+ "defaultConcurrency": 4,
+ "requestTimeoutMs": 120000
+ }
+ },
+ "media.football-ranking": {
+ "use": "@hypit/provider-media-local",
+ "pool": "media",
+ "config": {
+ "defaultConcurrency": 2
+ }
+ },
+ "whisperx.football-ranking": {
+ "use": "@hypit/provider-whisperx-local",
+ "pool": "alignment",
+ "config": {
+ "defaultConcurrency": 1
+ }
+ },
+ "hyperframes.football-ranking": {
+ "use": "@hypit/provider-hyperframes-local",
+ "pool": "render",
+ "config": {
+ "workers": 2,
+ "quality": "standard",
+ "defaultConcurrency": 1
}
}
}
diff --git a/examples/ranking-football/reference-banana-from-swap/hypit.runtime.json b/examples/ranking-football/reference-banana-from-swap/hypit.runtime.json
index d35b42b3..57bc60ea 100644
--- a/examples/ranking-football/reference-banana-from-swap/hypit.runtime.json
+++ b/examples/ranking-football/reference-banana-from-swap/hypit.runtime.json
@@ -1,45 +1,47 @@
{
- "format": "hypit.runtime-profile@1",
- "runtime": {
- "use": "@hypit/runtime-local",
- "config": {
- "dataRoot": ".hypit/runtimes/local",
- "artifacts": {
- "use": "@hypit/artifact-store-fs",
- "config": { "path": "artifacts" }
- },
- "credentials": {
- "os": { "use": "@hypit/credential-store-os" },
- "env": { "use": "@hypit/credential-store-env" }
- },
- "endpoints": {
- "kie.football-ranking": {
- "use": "@hypit/provider-kie",
- "pool": "generation",
- "config": {
- "apiKey": { "store": "env", "key": "KIE_API_KEY" },
- "defaultConcurrency": 10
- }
- },
- "media.football-ranking": {
- "use": "@hypit/provider-media-local",
- "pool": "media",
- "config": { "defaultConcurrency": 2 }
- },
- "whisperx.football-ranking": {
- "use": "@hypit/provider-whisperx-local",
- "pool": "alignment",
- "config": { "defaultConcurrency": 1 }
+ "format": "hypit.runtime-local@1",
+ "dataRoot": ".hypit/runtimes/local",
+ "credentials": {
+ "os": {
+ "use": "@hypit/credential-store-os"
+ },
+ "env": {
+ "use": "@hypit/credential-store-env"
+ }
+ },
+ "endpoints": {
+ "kie.football-ranking": {
+ "use": "@hypit/provider-kie",
+ "pool": "generation",
+ "config": {
+ "apiKey": {
+ "store": "env",
+ "key": "KIE_API_KEY"
},
- "hyperframes.football-ranking": {
- "use": "@hypit/provider-hyperframes-local",
- "pool": "render",
- "config": {
- "workers": 2,
- "quality": "standard",
- "defaultConcurrency": 1
- }
- }
+ "defaultConcurrency": 10
+ }
+ },
+ "media.football-ranking": {
+ "use": "@hypit/provider-media-local",
+ "pool": "media",
+ "config": {
+ "defaultConcurrency": 2
+ }
+ },
+ "whisperx.football-ranking": {
+ "use": "@hypit/provider-whisperx-local",
+ "pool": "alignment",
+ "config": {
+ "defaultConcurrency": 1
+ }
+ },
+ "hyperframes.football-ranking": {
+ "use": "@hypit/provider-hyperframes-local",
+ "pool": "render",
+ "config": {
+ "workers": 2,
+ "quality": "standard",
+ "defaultConcurrency": 1
}
}
}
diff --git a/examples/ranking-football/reference-banana/hypit.runtime.json b/examples/ranking-football/reference-banana/hypit.runtime.json
index a284ccd1..a7b6ca08 100644
--- a/examples/ranking-football/reference-banana/hypit.runtime.json
+++ b/examples/ranking-football/reference-banana/hypit.runtime.json
@@ -1,44 +1,44 @@
{
- "format": "hypit.runtime-profile@1",
- "runtime": {
- "use": "@hypit/runtime-local",
- "config": {
- "dataRoot": ".hypit/runtimes/local",
- "artifacts": {
- "use": "@hypit/artifact-store-fs",
- "config": { "path": "artifacts" }
- },
- "credentials": {
- "os": { "use": "@hypit/credential-store-os" }
- },
- "endpoints": {
- "kie.football-ranking": {
- "use": "@hypit/provider-kie",
- "pool": "generation",
- "config": {
- "apiKey": { "store": "os", "key": "KIE_API_KEY" },
- "defaultConcurrency": 10
- }
- },
- "media.football-ranking": {
- "use": "@hypit/provider-media-local",
- "pool": "media",
- "config": { "defaultConcurrency": 2 }
- },
- "whisperx.football-ranking": {
- "use": "@hypit/provider-whisperx-local",
- "pool": "alignment",
- "config": { "defaultConcurrency": 1 }
+ "format": "hypit.runtime-local@1",
+ "dataRoot": ".hypit/runtimes/local",
+ "credentials": {
+ "os": {
+ "use": "@hypit/credential-store-os"
+ }
+ },
+ "endpoints": {
+ "kie.football-ranking": {
+ "use": "@hypit/provider-kie",
+ "pool": "generation",
+ "config": {
+ "apiKey": {
+ "store": "os",
+ "key": "KIE_API_KEY"
},
- "hyperframes.football-ranking": {
- "use": "@hypit/provider-hyperframes-local",
- "pool": "render",
- "config": {
- "workers": 2,
- "quality": "standard",
- "defaultConcurrency": 1
- }
- }
+ "defaultConcurrency": 10
+ }
+ },
+ "media.football-ranking": {
+ "use": "@hypit/provider-media-local",
+ "pool": "media",
+ "config": {
+ "defaultConcurrency": 2
+ }
+ },
+ "whisperx.football-ranking": {
+ "use": "@hypit/provider-whisperx-local",
+ "pool": "alignment",
+ "config": {
+ "defaultConcurrency": 1
+ }
+ },
+ "hyperframes.football-ranking": {
+ "use": "@hypit/provider-hyperframes-local",
+ "pool": "render",
+ "config": {
+ "workers": 2,
+ "quality": "standard",
+ "defaultConcurrency": 1
}
}
}
diff --git a/examples/ranking-football/swap-effect-banana-reference-sync/hypit.runtime.json b/examples/ranking-football/swap-effect-banana-reference-sync/hypit.runtime.json
index d35b42b3..57bc60ea 100644
--- a/examples/ranking-football/swap-effect-banana-reference-sync/hypit.runtime.json
+++ b/examples/ranking-football/swap-effect-banana-reference-sync/hypit.runtime.json
@@ -1,45 +1,47 @@
{
- "format": "hypit.runtime-profile@1",
- "runtime": {
- "use": "@hypit/runtime-local",
- "config": {
- "dataRoot": ".hypit/runtimes/local",
- "artifacts": {
- "use": "@hypit/artifact-store-fs",
- "config": { "path": "artifacts" }
- },
- "credentials": {
- "os": { "use": "@hypit/credential-store-os" },
- "env": { "use": "@hypit/credential-store-env" }
- },
- "endpoints": {
- "kie.football-ranking": {
- "use": "@hypit/provider-kie",
- "pool": "generation",
- "config": {
- "apiKey": { "store": "env", "key": "KIE_API_KEY" },
- "defaultConcurrency": 10
- }
- },
- "media.football-ranking": {
- "use": "@hypit/provider-media-local",
- "pool": "media",
- "config": { "defaultConcurrency": 2 }
- },
- "whisperx.football-ranking": {
- "use": "@hypit/provider-whisperx-local",
- "pool": "alignment",
- "config": { "defaultConcurrency": 1 }
+ "format": "hypit.runtime-local@1",
+ "dataRoot": ".hypit/runtimes/local",
+ "credentials": {
+ "os": {
+ "use": "@hypit/credential-store-os"
+ },
+ "env": {
+ "use": "@hypit/credential-store-env"
+ }
+ },
+ "endpoints": {
+ "kie.football-ranking": {
+ "use": "@hypit/provider-kie",
+ "pool": "generation",
+ "config": {
+ "apiKey": {
+ "store": "env",
+ "key": "KIE_API_KEY"
},
- "hyperframes.football-ranking": {
- "use": "@hypit/provider-hyperframes-local",
- "pool": "render",
- "config": {
- "workers": 2,
- "quality": "standard",
- "defaultConcurrency": 1
- }
- }
+ "defaultConcurrency": 10
+ }
+ },
+ "media.football-ranking": {
+ "use": "@hypit/provider-media-local",
+ "pool": "media",
+ "config": {
+ "defaultConcurrency": 2
+ }
+ },
+ "whisperx.football-ranking": {
+ "use": "@hypit/provider-whisperx-local",
+ "pool": "alignment",
+ "config": {
+ "defaultConcurrency": 1
+ }
+ },
+ "hyperframes.football-ranking": {
+ "use": "@hypit/provider-hyperframes-local",
+ "pool": "render",
+ "config": {
+ "workers": 2,
+ "quality": "standard",
+ "defaultConcurrency": 1
}
}
}
diff --git a/examples/ranking-football/swap-effect-banana/hypit.runtime.json b/examples/ranking-football/swap-effect-banana/hypit.runtime.json
index d35b42b3..57bc60ea 100644
--- a/examples/ranking-football/swap-effect-banana/hypit.runtime.json
+++ b/examples/ranking-football/swap-effect-banana/hypit.runtime.json
@@ -1,45 +1,47 @@
{
- "format": "hypit.runtime-profile@1",
- "runtime": {
- "use": "@hypit/runtime-local",
- "config": {
- "dataRoot": ".hypit/runtimes/local",
- "artifacts": {
- "use": "@hypit/artifact-store-fs",
- "config": { "path": "artifacts" }
- },
- "credentials": {
- "os": { "use": "@hypit/credential-store-os" },
- "env": { "use": "@hypit/credential-store-env" }
- },
- "endpoints": {
- "kie.football-ranking": {
- "use": "@hypit/provider-kie",
- "pool": "generation",
- "config": {
- "apiKey": { "store": "env", "key": "KIE_API_KEY" },
- "defaultConcurrency": 10
- }
- },
- "media.football-ranking": {
- "use": "@hypit/provider-media-local",
- "pool": "media",
- "config": { "defaultConcurrency": 2 }
- },
- "whisperx.football-ranking": {
- "use": "@hypit/provider-whisperx-local",
- "pool": "alignment",
- "config": { "defaultConcurrency": 1 }
+ "format": "hypit.runtime-local@1",
+ "dataRoot": ".hypit/runtimes/local",
+ "credentials": {
+ "os": {
+ "use": "@hypit/credential-store-os"
+ },
+ "env": {
+ "use": "@hypit/credential-store-env"
+ }
+ },
+ "endpoints": {
+ "kie.football-ranking": {
+ "use": "@hypit/provider-kie",
+ "pool": "generation",
+ "config": {
+ "apiKey": {
+ "store": "env",
+ "key": "KIE_API_KEY"
},
- "hyperframes.football-ranking": {
- "use": "@hypit/provider-hyperframes-local",
- "pool": "render",
- "config": {
- "workers": 2,
- "quality": "standard",
- "defaultConcurrency": 1
- }
- }
+ "defaultConcurrency": 10
+ }
+ },
+ "media.football-ranking": {
+ "use": "@hypit/provider-media-local",
+ "pool": "media",
+ "config": {
+ "defaultConcurrency": 2
+ }
+ },
+ "whisperx.football-ranking": {
+ "use": "@hypit/provider-whisperx-local",
+ "pool": "alignment",
+ "config": {
+ "defaultConcurrency": 1
+ }
+ },
+ "hyperframes.football-ranking": {
+ "use": "@hypit/provider-hyperframes-local",
+ "pool": "render",
+ "config": {
+ "workers": 2,
+ "quality": "standard",
+ "defaultConcurrency": 1
}
}
}
diff --git a/packages/cli/src/arguments.ts b/packages/cli/src/arguments.ts
index b57f9b48..53175c1b 100644
--- a/packages/cli/src/arguments.ts
+++ b/packages/cli/src/arguments.ts
@@ -265,9 +265,20 @@ function parseResultCommand(tail: readonly string[]): ProjectResultCommand | Exe
function parseRuntimeCommand(tail: readonly string[]): RuntimeSelectionCommand | RuntimeOperationCommand {
const [action, ...values] = tail;
- if (action !== "use" && action !== "unset" && action !== "up" && action !== "down"
+ if (action !== "init" && action !== "use" && action !== "unset" && action !== "up" && action !== "down"
&& action !== "status" && action !== "logs") {
- throw new Error("runtime takes use, unset, up, down, status or logs");
+ throw new Error("runtime takes init, use, unset, up, down, status or logs");
+ }
+ if (action === "init") {
+ const [profile, rest] = optionalPositional(values);
+ const options = commandOptions("runtime init", rest, "--workspace");
+ return {
+ command: "runtime",
+ action,
+ presentation: options.presentation,
+ ...optionalProject(options),
+ ...(profile === undefined ? {} : { profile }),
+ };
}
if (action === "use") {
const [profile, rest] = requiredPositional(values, "runtime use requires a Runtime Profile");
diff --git a/packages/cli/src/command.ts b/packages/cli/src/command.ts
index 283b7777..8d1096e4 100644
--- a/packages/cli/src/command.ts
+++ b/packages/cli/src/command.ts
@@ -92,6 +92,11 @@ export type ExecutionCommand =
});
export type RuntimeSelectionCommand =
+ | (CommandBase & ProjectOption & {
+ readonly command: "runtime";
+ readonly action: "init";
+ readonly profile?: string;
+ })
| (CommandBase & ProjectOption & {
readonly command: "runtime";
readonly action: "use";
diff --git a/packages/cli/src/commands/environment.ts b/packages/cli/src/commands/environment.ts
index 6de5ceec..78cfcd77 100644
--- a/packages/cli/src/commands/environment.ts
+++ b/packages/cli/src/commands/environment.ts
@@ -206,11 +206,11 @@ export async function runEnvironmentCommand(input: {
total: external.programs.length,
ready: external.programs.filter((item) => item.state.state === "ready").length,
},
- }, ok ? "Runtime deployment ready" : "Runtime deployment needs attention", ok ? "success" : "warning", [
+ }, ok ? "Local Runtime ready" : "Local Runtime needs attention", ok ? "success" : "warning", [
...(!args.presentation.verbose && ok ? [] : [
["Machine packages", String(prepared.length)] as const,
["Worker", processState.state] as const,
- ["External programs", `${external.programs.filter((item) => item.state.state === "ready").length}/${external.programs.length} ready`] as const,
+ ["Managed programs", `${external.programs.filter((item) => item.state.state === "ready").length}/${external.programs.length} ready`] as const,
]),
]);
if (!ok) io.setExitCode?.(1);
@@ -238,7 +238,7 @@ export async function runEnvironmentCommand(input: {
});
write({ format: "hypit.cli-runtime-down@2", worker: worker.state },
"Runtime Worker is down", "success", [["Worker", worker.state]],
- ["External programs were left running. Stop them explicitly with hypit programs down."]);
+ ["Managed programs were left running. Stop them explicitly with hypit programs down."]);
return;
}
@@ -284,8 +284,8 @@ export async function runEnvironmentCommand(input: {
},
};
write(machine, attention
- ? "Runtime deployment needs attention"
- : ready ? "Runtime deployment ready" : "Runtime Worker stopped",
+ ? "Local Runtime needs attention"
+ : ready ? "Local Runtime ready" : "Runtime Worker stopped",
attention ? "warning" : ready ? "success" : "info", [
["Worker", worker.state],
["Active Builds", String(activity.builds.length)],
@@ -309,7 +309,7 @@ export async function runEnvironmentCommand(input: {
if (args.command === "auth") {
if (runtimeProfile === undefined) {
- throw new Error("auth requires a Runtime; run hypit runtime use <profile> or pass --runtime <profile>");
+ throw new Error("auth requires a Runtime; run hypit runtime init, select one with runtime use, or pass --runtime <profile>");
}
const credentialsControl = await (await runtimeHost(runtimeProfile)).openCredentials(args.endpoint);
try {
diff --git a/packages/cli/src/commands/execution.ts b/packages/cli/src/commands/execution.ts
index 07f5dc2f..3cdc642d 100644
--- a/packages/cli/src/commands/execution.ts
+++ b/packages/cli/src/commands/execution.ts
@@ -65,7 +65,7 @@ export async function runExecutionCommand(input: {
}
if (runtimeProfile === undefined) {
- throw new Error(`${args.command} requires a Runtime; run hypit runtime use <profile> or pass --runtime <profile>`);
+ throw new Error(`${args.command} requires a Runtime; run hypit runtime init, select one with runtime use, or pass --runtime <profile>`);
}
const selectedHost = await runtimeHost(runtimeProfile);
diff --git a/packages/cli/src/distribution.ts b/packages/cli/src/distribution.ts
index 2a294124..4c0c88e7 100644
--- a/packages/cli/src/distribution.ts
+++ b/packages/cli/src/distribution.ts
@@ -4,6 +4,7 @@ import type { NodeRuntimeHost } from "@hypit/runtime-host-node";
import type { BuildResultRepository } from "@hypit/build-result";
import type { BuildResultRepositoryLocation } from "@hypit/build-result-kit";
import type { BuildResultRepositoryDiagnostic } from "@hypit/build-result-kit";
+import type { CanonicalValue } from "@hypit/protocol";
export type CliCompilerOptions = {
/** Canonical containment boundary for Author and Run Sources plus source assets. */
@@ -24,6 +25,8 @@ export type CliDistribution = {
readonly packageRoot?: string;
/** Explicit Host bootstrap packages; never inferred from Source contents. */
readonly bootstrapPackages: readonly LoadedPackage[];
+ /** Product-owned starter Profile. The generic CLI only writes this explicit value. */
+ readonly initialRuntimeProfile?: CanonicalValue;
createCompiler(options: CliCompilerOptions): NodeCompiler;
/**
* Read the self-described Run Source and its Author Source closure, then return
diff --git a/packages/cli/src/machine-view.ts b/packages/cli/src/machine-view.ts
index e9ca531f..a56d70d1 100644
--- a/packages/cli/src/machine-view.ts
+++ b/packages/cli/src/machine-view.ts
@@ -4,6 +4,7 @@ type ProgramStateView = { readonly id: string; readonly state: string; readonly
type AttentionView = { readonly message: string; readonly action?: string };
export type OperationalMachineView =
+ | { readonly format: "hypit.cli-runtime-init@1"; readonly profile: string; readonly project: string; readonly selected: true }
| { readonly format: "hypit.cli-runtime-selection@2"; readonly selected: boolean; readonly removed?: boolean; readonly profile?: string; readonly project?: string }
| { readonly format: "hypit.cli-paths@1"; readonly project: string; readonly projectState: string; readonly profile?: string; readonly runtimeData?: string; readonly hostState: string; readonly machinePackages: string; readonly distribution?: string }
| { readonly format: "hypit.cli-package@2"; readonly action: "install" | "status"; readonly package: string; readonly ready: boolean }
diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.ts
index 7efa102f..bc6d3a14 100644
--- a/packages/cli/src/main.ts
+++ b/packages/cli/src/main.ts
@@ -1,4 +1,5 @@
import { randomBytes } from "node:crypto";
+import { writeFile } from "node:fs/promises";
import { resolve } from "node:path";
import type { NodeRuntimeHost } from "@hypit/runtime-host-node";
@@ -119,6 +120,35 @@ export async function runCli(
)).runWorker(args.readyFile, args.workerOwner);
return;
}
+ if (args.command === "runtime" && args.action === "init") {
+ if (distribution.initialRuntimeProfile === undefined) {
+ throw new Error("This Hypit Distribution does not provide an initial Runtime Profile");
+ }
+ const projectRoot = await commandProjectRoot();
+ const profile = resolve(args.profile ?? resolve(projectRoot, "hypit.runtime.json"));
+ try {
+ await writeFile(profile, `${JSON.stringify(distribution.initialRuntimeProfile, undefined, 2)}\n`, {
+ encoding: "utf8",
+ flag: "wx",
+ });
+ } catch (error) {
+ if (error instanceof Error && "code" in error && error.code === "EEXIST") {
+ throw new Error(`Runtime Profile already exists: ${profile}; select it with hypit runtime use or choose another path`);
+ }
+ throw error;
+ }
+ const selected = await selectRuntimeProfile(projectRoot, profile);
+ writeOperational({
+ format: "hypit.cli-runtime-init@1",
+ profile: selected.profile,
+ project: selected.projectRoot,
+ selected: true,
+ }, "Runtime Profile created", "success", [
+ ["Profile", selected.profile],
+ ["Project", selected.projectRoot],
+ ], ["No package was installed, no service was contacted and no Worker was started."]);
+ return;
+ }
if (args.command === "runtime" && args.action === "use") {
const profile = resolve(args.profile);
const selected = await selectRuntimeProfile(await commandProjectRoot(), profile);
@@ -310,7 +340,7 @@ export async function runCli(
}
if (args.command === "build") {
if (runtimeProfile === undefined) {
- throw new Error("build requires a Runtime; run hypit runtime use <profile> or pass --runtime <profile>");
+ throw new Error("build requires a Runtime; run hypit runtime init, select one with runtime use, or pass --runtime <profile>");
}
const buildResults = await projectResults(projectResultsRoot);
let loadedRun;
diff --git a/packages/cli/src/output.ts b/packages/cli/src/output.ts
index 6932ec4e..d2a4b495 100644
--- a/packages/cli/src/output.ts
+++ b/packages/cli/src/output.ts
@@ -461,17 +461,19 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undefi
],
runtime: [
colors.accent(colors.strong("hypit runtime")),
- colors.dim("Select a project Runtime Profile, then operate its durable Worker."),
+ colors.dim("Select a project Runtime Profile, then operate the local Build Worker."),
"",
+ " hypit runtime init [<profile>] [--workspace <project>] create and select a starter Profile",
" hypit runtime use <profile> [--workspace <project>] select the project Profile",
" hypit runtime unset [--workspace <project>] remove only that selection",
- " hypit runtime up [<profile>] prepare selected packages, programs and Worker",
- " hypit runtime status [<profile>] inspect Worker, active Builds and declared programs",
+ " hypit runtime up [<profile>] prepare local packages and programs, then start the Worker",
+ " hypit runtime status [<profile>] inspect the local Worker, active Builds and programs",
" hypit runtime logs [<profile>] [--lines <count>]",
" hypit runtime down [<profile>] stop the Worker; external programs keep running",
"",
"The project is resolved first. Selection is read only from that project's .hypit/runtime.",
"No Profile filename discovery or parent-project inheritance is performed.",
+ "Remote Endpoints such as HypiHub are not started by this command; use doctor to test them.",
],
packages: [
colors.accent(colors.strong("hypit packages")),
@@ -599,8 +601,8 @@ export function writeCliHelp(io: CliIo, topic?: string): void {
"",
colors.strong("Runtime"),
row("doctor [profile]", "diagnose selected external setup"),
- row("runtime use|unset", "select this project's Runtime Profile"),
- row("runtime up|status|logs|down", "prepare deployment and manage the Worker"),
+ row("runtime init|use|unset", "create or select this project's Runtime Profile"),
+ row("runtime up|status|logs|down", "prepare and manage the local Build Runtime"),
row("programs up|status|down", "manage declared external programs only"),
row("packages install|status", "manage pinned upstream packages in the machine home"),
row("activity [--watch]", "inspect active Builds and shared capacity"),
diff --git a/packages/cli/test/programs-command.test.ts b/packages/cli/test/programs-command.test.ts
index 18fdab94..4fb54b29 100644
--- a/packages/cli/test/programs-command.test.ts
+++ b/packages/cli/test/programs-command.test.ts
@@ -163,7 +163,7 @@ test("runtime status keeps scheduling phases out of the default view", async ()
write(text) { output += text; },
}, selected);
- assert.match(output, /Runtime deployment ready/u);
+ assert.match(output, /Local Runtime ready/u);
assert.match(output, /Active Builds\s+0/u);
assert.doesNotMatch(output, /\bStarting\b|\bWaiting\b|\bDecided\b|Running turn|Capacity in use/u);
});
diff --git a/packages/cli/test/runtime-selection.test.ts b/packages/cli/test/runtime-selection.test.ts
index 2981b5a4..5a73918e 100644
--- a/packages/cli/test/runtime-selection.test.ts
+++ b/packages/cli/test/runtime-selection.test.ts
@@ -105,6 +105,48 @@ test("runtime use lets later CLI commands reuse the selected Profile", async ()
}
});
+test("runtime init writes and selects the Distribution starter without opening a Runtime", async () => {
+ const root = await mkdtemp(join(tmpdir(), "hypit-runtime-init-"));
+ const previous = process.cwd();
+ try {
+ await writeFile(join(root, "package.json"), "{}\n", "utf8");
+ process.chdir(root);
+ let opened = false;
+ const starter = {
+ format: "hypit.runtime-local@1" as const,
+ dataRoot: ".hypit/runtimes/local",
+ credentials: {},
+ endpoints: {},
+ };
+ const distribution = {
+ initialRuntimeProfile: starter,
+ openRuntimeHost: async () => {
+ opened = true;
+ throw new Error("runtime init must not open the Runtime");
+ },
+ } as unknown as CliDistribution;
+ let output = "";
+ await runCli(["runtime", "init", "--workspace", root], {
+ write(text) { output += text; },
+ }, distribution);
+
+ const profile = join(root, "hypit.runtime.json");
+ assert.deepEqual(JSON.parse(await readFile(profile, "utf8")), starter);
+ assert.equal((await findRuntimeProfile(root))?.profile, await realpath(profile));
+ assert.equal(opened, false);
+ assert.match(output, /No package was installed, no service was contacted and no Worker was started/u);
+
+ await assert.rejects(
+ runCli(["runtime", "init", "--workspace", root], { write() {} }, distribution),
+ /Runtime Profile already exists/u,
+ );
+ assert.deepEqual(JSON.parse(await readFile(profile, "utf8")), starter);
+ } finally {
+ process.chdir(previous);
+ await rm(root, { recursive: true, force: true });
+ }
+});
+
test("runtime status without a selected Profile reports the missing context instead of generic usage", async () => {
const root = await mkdtemp(join(tmpdir(), "hypit-runtime-missing-"));
const previous = process.cwd();
diff --git a/packages/endpoint-kit/src/index.ts b/packages/endpoint-kit/src/index.ts
index a3a87f03..d421d1b6 100644
--- a/packages/endpoint-kit/src/index.ts
+++ b/packages/endpoint-kit/src/index.ts
@@ -31,6 +31,33 @@ export type EndpointInvocationContext = {
readonly credentials: Readonly<Record<string, CredentialValue>>;
};
+export type EndpointPriceQuote =
+ | {
+ readonly status: "estimated";
+ readonly amount: number;
+ readonly currency: string;
+ readonly basis: {
+ readonly mode: string;
+ readonly quantity: number;
+ readonly rate: number;
+ readonly base?: number;
+ readonly multiplier?: number;
+ };
+ readonly source: string;
+ readonly observedAt: number;
+ }
+ | { readonly status: "unknown"; readonly reason: string };
+
+export type EndpointQuoteContext = {
+ readonly need: Need;
+ /** Only slots explicitly declared by this configured Endpoint instance are present. */
+ readonly credentials: Readonly<Record<string, CredentialValue>>;
+};
+
+export type EndpointQuoteHandler = (
+ context: EndpointQuoteContext,
+) => Awaitable<EndpointPriceQuote>;
+
export type ImmediateEndpointHandler = (
context: EndpointInvocationContext,
) => Awaitable<EndpointFulfillment>;
@@ -124,6 +151,8 @@ export type EndpointOffer = {
readonly capability: CapabilityRef;
readonly returns: TypeRef;
readonly endpoint: string;
+ readonly supports?: (need: Need) => boolean;
+ readonly quote?: EndpointQuoteHandler;
};
export type EndpointCredentialDescription = {
@@ -139,6 +168,8 @@ type EndpointCapabilityBase = {
readonly capability: CapabilityRef;
readonly returns: TypeRef;
readonly supports?: (need: Need) => boolean;
+ /** Provider-owned live or stable price estimate for this exact Need. */
+ readonly quote?: EndpointQuoteHandler;
/** Stable Provider-local queue lane. Defaults to the capability name. */
readonly lane?: string;
/** Lane capacity; the Provider pool keeps its independent total capacity. */
@@ -240,6 +271,8 @@ export function defineEndpointPackage(options: DefineEndpointPackageOptions): En
const fulfills = options.capabilities.map((item) => ({
capability: structuredClone(item.capability),
returns: structuredClone(item.returns),
+ ...(item.supports === undefined ? {} : { supports: item.supports }),
+ ...(item.quote === undefined ? {} : { quote: item.quote }),
}));
const instance = {
id: options.instance,
diff --git a/packages/provider-hypihub/README.md b/packages/provider-hypihub/README.md
index 8d1e9013..d578f1f9 100644
--- a/packages/provider-hypihub/README.md
+++ b/packages/provider-hypihub/README.md
@@ -1,7 +1,7 @@
# `@hypit/provider-hypihub`
Thin Hypit Runtime Provider for a HypiHub deployment. It is an optional default gateway for
-paid generation and Gemini VLM requests; callers may keep their own Provider and select HypiHub only
+paid generation, Gemini VLM and WhisperX alignment requests; callers may keep their own Provider and select HypiHub only
when its OAuth login is configured.
It maps the currently shipped image/video model capabilities to HypiHub, including image edits and
@@ -31,7 +31,9 @@ Runtime Profile example:
}
```
-Gemini VLM is also exposed as the provider-neutral `@hypit/gemini` Runtime capability, so an Author
+Gemini VLM is exposed as the Provider-neutral `@hypit/gemini` Runtime capability, and remote
+transcription is exposed as the same `@hypit/whisperx` alignment capability implemented by the local
+WhisperX Provider. An Author
Source can select the exact model while the Runtime chooses HypiHub or Vertex. Existing embedded
callers can still use the exported `createHypiHubGeminiGenerator`. Run `hypit auth login hypihub.default --runtime hypit.runtime.json` to sign in with HypiHub OAuth (and optionally set `HYPIHUB_BASE_URL`; either the origin or
an existing `/v1`/`/v1beta` base is accepted) only when choosing HypiHub. The Runtime Provider also
@@ -41,5 +43,11 @@ Artifacts are uploaded automatically through `POST /v1/files`, then their return
URLs are used in image and video requests. One referenced Resource is uploaded once within one
Runtime operation. Embedded callers may override that transport with `publicAssetUrl`.
+The default remote alignment model is `victor-upmeet/whisperx`; `transcriptionModel` may select another
+HypiHub model that exposes the `transcriptions` route. `hypit doctor` reads the authenticated model
+catalog to verify configured capabilities; ordinary preflight never makes that request. Each paid
+offer can quote one exact Need from the current model card in HypiHub credits. Changing prices are not
+copied into Hypit, and unsupported pricing modes remain explicitly unknown.
+
HypiHub exposes MiMo VoiceDesign by default. Set `audio: false` only when the user explicitly selects
another VoiceDesign Provider. Hypit does not expose MiMo preset-voice or voice-cloning models.
diff --git a/packages/provider-hypihub/package.json b/packages/provider-hypihub/package.json
index fc837de1..5825b163 100644
--- a/packages/provider-hypihub/package.json
+++ b/packages/provider-hypihub/package.json
@@ -13,11 +13,14 @@
"@hypit/protocol": "workspace:*",
"@hypit/runtime": "workspace:*",
"@hypit/runtime-kit": "workspace:*",
- "@hypit/text": "workspace:*"
+ "@hypit/speech-evidence": "workspace:*",
+ "@hypit/text": "workspace:*",
+ "@hypit/whisperx": "workspace:*"
},
"devDependencies": {
"@hypit/driver-node": "workspace:*",
"@hypit/mimo-tts": "workspace:*",
- "@hypit/seedance": "workspace:*"
+ "@hypit/seedance": "workspace:*",
+ "@hypit/speech": "workspace:*"
}
}
diff --git a/packages/provider-hypihub/src/activation.ts b/packages/provider-hypihub/src/activation.ts
index c1daa94a..967a5021 100644
--- a/packages/provider-hypihub/src/activation.ts
+++ b/packages/provider-hypihub/src/activation.ts
@@ -8,14 +8,17 @@ import {
runtimeConfigString,
} from "@hypit/runtime-kit";
-import { createHypiHubProvider } from "./provider.js";
+import { createHypiHubProvider, diagnoseHypiHubProvider } from "./provider.js";
const adapter = createRuntimeEndpointAdapterFacet({
use: "@hypit/provider-hypihub",
activate(context) {
if (context.pool === undefined) throw new Error("HypiHub Provider Pool is required");
const config = runtimeConfigObject(context.config, "HypiHub");
- runtimeConfigExact(config, ["baseUrl", "apiKey", "defaultConcurrency", "pollIntervalMs", "requestTimeoutMs", "audio"], "HypiHub");
+ runtimeConfigExact(config, [
+ "baseUrl", "apiKey", "defaultConcurrency", "pollIntervalMs", "requestTimeoutMs", "audio",
+ "transcriptionModel",
+ ], "HypiHub");
const baseUrl = runtimeConfigString(config.baseUrl, "HypiHub baseUrl");
if (baseUrl !== undefined) {
const url = new URL(baseUrl);
@@ -29,8 +32,8 @@ const adapter = createRuntimeEndpointAdapterFacet({
const pollIntervalMs = runtimeConfigPositiveInteger(config.pollIntervalMs, "HypiHub pollIntervalMs");
const requestTimeoutMs = runtimeConfigPositiveInteger(config.requestTimeoutMs, "HypiHub requestTimeoutMs");
const audio = runtimeConfigBoolean(config.audio, "HypiHub audio");
- return {
- endpoint: createHypiHubProvider({
+ const transcriptionModel = runtimeConfigString(config.transcriptionModel, "HypiHub transcriptionModel");
+ const options = {
instance: context.instance,
pool: context.pool,
...(baseUrl === undefined ? {} : { baseUrl }),
@@ -39,7 +42,11 @@ const adapter = createRuntimeEndpointAdapterFacet({
...(pollIntervalMs === undefined ? {} : { pollIntervalMs }),
...(requestTimeoutMs === undefined ? {} : { requestTimeoutMs }),
...(audio === undefined ? {} : { audio }),
- }),
+ ...(transcriptionModel === undefined ? {} : { transcriptionModel }),
+ };
+ return {
+ endpoint: createHypiHubProvider(options),
+ diagnose: async (doctor) => await diagnoseHypiHubProvider(options, doctor),
};
},
});
diff --git a/packages/provider-hypihub/src/provider.ts b/packages/provider-hypihub/src/provider.ts
index faf43a41..5c7c4bc6 100644
--- a/packages/provider-hypihub/src/provider.ts
+++ b/packages/provider-hypihub/src/provider.ts
@@ -1,4 +1,4 @@
-import type { AsyncEndpoint, EndpointFulfillment, EndpointInvocationContext, EndpointPollContext, EndpointStartContext, EndpointOutcome, ImmediateEndpointHandler } from "@hypit/endpoint-kit";
+import type { AsyncEndpoint, EndpointFulfillment, EndpointInvocationContext, EndpointPollContext, EndpointStartContext, EndpointOutcome, EndpointPriceQuote, EndpointQuoteContext, ImmediateEndpointHandler } from "@hypit/endpoint-kit";
import { defineEndpointPackage, wakeAfter } from "@hypit/endpoint-kit";
import { geminiCapabilities, geminiModels, verifyGeminiRequest } from "@hypit/gemini";
import type { GeminiRequest } from "@hypit/gemini";
@@ -6,10 +6,19 @@ import { canonicalize } from "@hypit/protocol";
import type { BlobRef, CapabilityRef } from "@hypit/protocol";
import { credentialRef } from "@hypit/runtime";
import type { CredentialRef, ResourceStore } from "@hypit/runtime";
+import { sealAlignedTranscriptEvidence, speechEvidenceTypes } from "@hypit/speech-evidence";
import { sealText } from "@hypit/text";
import { textTypes } from "@hypit/text";
+import {
+ assertWhisperXEvidenceWav,
+ interpretWhisperXTranscript,
+ verifyWhisperXAlignmentRequest,
+ whisperXCapabilities,
+} from "@hypit/whisperx";
+import type { WhisperXTranscriptResponse } from "@hypit/whisperx";
import { createHypiHubGeminiGenerator } from "./gemini.js";
import { hypiHubRouteForCapability, hypiHubRoutes } from "./routes.js";
+import type { RuntimeDoctorDiagnostic } from "@hypit/runtime-kit";
export const hypiHubProviderModuleRef = { name: "@hypit/provider-hypihub", version: "1" } as const;
@@ -23,6 +32,8 @@ export type CreateHypiHubProviderOptions = {
readonly requestTimeoutMs?: number;
/** Expose HypiHub VoiceDesign. Defaults to enabled; set false only for an explicit alternate Provider. */
readonly audio?: boolean;
+ /** HypiHub model used for the Provider-neutral WhisperX alignment capability. */
+ readonly transcriptionModel?: string;
readonly fetch?: typeof globalThis.fetch;
/** Overrides the default POST /v1/files upload for referenced artifacts. */
readonly publicAssetUrl?: (artifact: BlobRef, artifacts: ResourceStore) => Promise<string>;
@@ -47,6 +58,11 @@ function credential(context: EndpointInvocationContext): string {
assert(typeof value === "string" && value.length > 0, "HypiHub login is unavailable; run hypit auth login for HypiHub");
return value;
}
+function quoteCredential(context: EndpointQuoteContext): string {
+ const value = context.credentials.apiKey?.secret;
+ assert(typeof value === "string" && value.length > 0, "HypiHub login is unavailable; run hypit auth login for HypiHub");
+ return value;
+}
function guidedMessage(error: unknown): string {
const message = error instanceof Error ? error.message : String(error);
return /API key is unavailable|HypiHub login is unavailable|HTTP (?:401|403|404)\b|not enabled for|model_not_found|no_capable_provider/iu.test(message)
@@ -69,11 +85,121 @@ function jobId(value: Record<string, unknown>): string {
return id;
}
-async function verifyModelRoute(client: HypiHubClient, apiKey: string, model: string, operation: "images" | "image_edits" | "videos" | "audio_speech"): Promise<void> {
+type HypiHubModelOperation = "images" | "image_edits" | "videos" | "audio_speech" | "transcriptions" | "gemini";
+
+async function verifyModelRoute(client: HypiHubClient, apiKey: string, model: string, operation: HypiHubModelOperation): Promise<Record<string, unknown>> {
const card = await client.json(`/models/${encodeURIComponent(model)}`, apiKey);
const endpoints = card.endpoints;
assert(Array.isArray(endpoints) && endpoints.includes(operation),
`HypiHub model ${model} is not enabled for ${operation} with this API key`);
+ return card;
+}
+
+function numeric(value: unknown): number | undefined {
+ return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
+function firstNumber(input: Record<string, unknown>, keys: readonly string[]): number | undefined {
+ for (const key of keys) {
+ const value = numeric(input[key]);
+ if (value !== undefined) return value;
+ }
+ return undefined;
+}
+
+function ratioKey(value: unknown): string | undefined {
+ if (typeof value !== "string") return undefined;
+ const normalized = value.toLowerCase();
+ if (normalized === "1024x1024") return "1k";
+ if (normalized === "2048x2048") return "2k";
+ if (normalized === "3840x2160") return "4k";
+ return normalized;
+}
+
+function ratio(table: unknown, key: string | undefined): number | undefined {
+ if (table === undefined || table === null) return 1;
+ if (typeof table !== "object" || Array.isArray(table)) return undefined;
+ if (key === undefined) return 1;
+ return numeric((table as Record<string, unknown>)[key]);
+}
+
+function modelQuote(
+ card: Record<string, unknown>,
+ input: Record<string, unknown>,
+ options: { readonly quantity?: number; readonly source: string; readonly observedAt: number },
+): EndpointPriceQuote {
+ const pricing = object(card.pricing, "HypiHub model pricing");
+ const mode = pricing.mode;
+ assert(typeof mode === "string" && mode.length > 0, "HypiHub model card has no pricing mode");
+ if (pricing.free === true) return {
+ status: "estimated",
+ amount: 0,
+ currency: "credits",
+ basis: { mode: "free", quantity: options.quantity ?? 1, rate: 0 },
+ source: options.source,
+ observedAt: options.observedAt,
+ };
+ const credits = object(pricing.credits, "HypiHub credit pricing");
+ let quantity: number;
+ let rate: number | undefined;
+ let base: number | undefined;
+ if (mode === "per_image") {
+ quantity = options.quantity ?? firstNumber(input, ["n"]) ?? 1;
+ rate = numeric(credits.base);
+ } else if (mode === "per_request") {
+ quantity = options.quantity ?? 1;
+ rate = numeric(credits.base);
+ } else if (mode === "per_second") {
+ quantity = options.quantity ?? firstNumber(input, ["seconds", "duration_seconds", "duration"]) ?? NaN;
+ rate = numeric(credits.per_second);
+ } else if (mode === "per_audio_second") {
+ quantity = options.quantity ?? NaN;
+ rate = numeric(credits.per_audio_second);
+ base = numeric(credits.base);
+ } else if (mode === "per_k_char") {
+ const text = [input.input, input.text, input.prompt].find((value) => typeof value === "string");
+ quantity = typeof text === "string" ? text.length / 1_000 : NaN;
+ rate = numeric(credits.per_k_char);
+ } else {
+ return { status: "unknown", reason: `HypiHub pricing mode ${mode} cannot be estimated before execution` };
+ }
+ if (!Number.isFinite(quantity) || quantity < 0 || rate === undefined) {
+ return { status: "unknown", reason: `HypiHub model card lacks the inputs required for ${mode} pricing` };
+ }
+ const factors = [
+ ratio(pricing.resolution_ratio, ratioKey(input.resolution)),
+ ratio(pricing.size_ratio, ratioKey(input.size)),
+ ratio(pricing.quality_ratio, ratioKey(input.quality)),
+ ];
+ const flagRatios = pricing.flag_ratio === undefined || pricing.flag_ratio === null
+ ? {}
+ : (typeof pricing.flag_ratio === "object" && !Array.isArray(pricing.flag_ratio)
+ ? pricing.flag_ratio as Record<string, unknown> : undefined);
+ if (flagRatios === undefined) {
+ return { status: "unknown", reason: "HypiHub model card has an invalid flag price table" };
+ }
+ for (const [flag, candidate] of Object.entries(flagRatios)) {
+ if (input[flag] === true) factors.push(numeric(candidate));
+ }
+ if (factors.some((factor) => factor === undefined)) {
+ return { status: "unknown", reason: "HypiHub model card has no price factor for this exact request" };
+ }
+ const multiplier = factors.reduce<number>((value, factor) => value * factor!, 1);
+ const amount = Math.round((((base ?? 0) + quantity * rate) * multiplier) * 10_000) / 10_000;
+ return {
+ status: "estimated",
+ amount,
+ currency: "credits",
+ basis: {
+ mode,
+ quantity,
+ rate,
+ ...(base === undefined ? {} : { base }),
+ ...(multiplier === 1 ? {} : { multiplier }),
+ },
+ source: options.source,
+ observedAt: options.observedAt,
+ };
}
function dataUrl(bytes: Uint8Array, mediaType: string): string {
@@ -148,6 +274,111 @@ class HypiHubClient {
}
}
+function cardEndpoints(card: Record<string, unknown> | undefined): readonly string[] {
+ return Array.isArray(card?.endpoints)
+ ? card.endpoints.filter((item): item is string => typeof item === "string")
+ : [];
+}
+
+/** Active, read-only HypiHub check used only by doctor. */
+export async function diagnoseHypiHubProvider(
+ options: CreateHypiHubProviderOptions,
+ context: {
+ readonly credentials: Readonly<Record<string, { readonly secret: string }>>;
+ readonly capabilities?: readonly CapabilityRef[];
+ },
+): Promise<readonly RuntimeDoctorDiagnostic[]> {
+ const apiKey = context.credentials.apiKey?.secret;
+ assert(typeof apiKey === "string" && apiKey.length > 0, "HypiHub login is unavailable");
+ const client = new HypiHubClient({
+ baseUrl: apiBaseUrl(options.baseUrl ?? "https://hypit.ai/v1"),
+ timeout: options.requestTimeoutMs ?? 30_000,
+ fetcher: options.fetch ?? globalThis.fetch,
+ });
+ const response = await client.json("/models", apiKey);
+ assert(Array.isArray(response.data), "HypiHub model catalogue has no data array");
+ const cards = new Map<string, Record<string, unknown>>();
+ for (const value of response.data) {
+ if (value === null || typeof value !== "object" || Array.isArray(value)) continue;
+ const card = value as Record<string, unknown>;
+ if (typeof card.id === "string") cards.set(card.id, card);
+ }
+ const transcriptionModel = options.transcriptionModel?.trim() || "victor-upmeet/whisperx";
+ const diagnostics: RuntimeDoctorDiagnostic[] = [];
+ for (const capability of context.capabilities ?? []) {
+ let available = false;
+ if (capabilityKey(capability) === capabilityKey(whisperXCapabilities.alignment)) {
+ available = cardEndpoints(cards.get(transcriptionModel)).includes("transcriptions");
+ } else if (geminiModels.some((model) => model === capability.name)
+ && capability.module.name === geminiCapabilities[geminiModels[0]].module.name
+ && capability.module.version === geminiCapabilities[geminiModels[0]].module.version) {
+ available = cardEndpoints(cards.get(capability.name)).includes("gemini");
+ } else {
+ const route = hypiHubRouteForCapability(capability);
+ if (route !== undefined) {
+ const acceptable = route.media === "image" ? ["images", "image_edits"]
+ : route.media === "video" ? ["videos"] : ["audio_speech"];
+ available = route.routes.some(({ model }) => cardEndpoints(cards.get(model))
+ .some((endpoint) => acceptable.includes(endpoint)));
+ }
+ }
+ if (!available) diagnostics.push({
+ severity: "error",
+ code: "HYPIHUB_CAPABILITY_UNAVAILABLE",
+ message: `HypiHub login cannot currently route ${capabilityKey(capability)}`,
+ subject: capabilityKey(capability),
+ });
+ }
+ return diagnostics;
+}
+
+function generationOperation(route: (typeof hypiHubRoutes)[number], input: Record<string, unknown>): HypiHubModelOperation {
+ if (route.media === "audio") return "audio_speech";
+ if (route.media === "video") return "videos";
+ const hasReferences = Object.entries(input).some(([key, value]) => {
+ if (!["images", "reference_images", "reference_image_urls", "reference_videos", "reference_audios", "first_frame", "last_frame"].includes(key)) return false;
+ return Array.isArray(value) ? value.length > 0 : typeof value === "string" && value.length > 0;
+ });
+ return hasReferences ? "image_edits" : "images";
+}
+
+async function quoteHypiHubNeed(
+ client: HypiHubClient,
+ context: EndpointQuoteContext,
+ transcriptionModel: string,
+): Promise<EndpointPriceQuote> {
+ const observedAt = Date.now();
+ const apiKey = quoteCredential(context);
+ if (capabilityKey(context.need.capability) === capabilityKey(whisperXCapabilities.alignment)) {
+ const request = verifyWhisperXAlignmentRequest(context.need.constraints);
+ const card = await verifyModelRoute(client, apiKey, transcriptionModel, "transcriptions");
+ return modelQuote(card, {}, {
+ quantity: request.sampleFrames / 16_000,
+ source: `${client.baseUrl}/models/${encodeURIComponent(transcriptionModel)}`,
+ observedAt,
+ });
+ }
+ if (geminiModels.some((model) => model === context.need.capability.name)
+ && context.need.capability.module.name === geminiCapabilities[geminiModels[0]].module.name
+ && context.need.capability.module.version === geminiCapabilities[geminiModels[0]].module.version) {
+ const model = context.need.capability.name;
+ const card = await verifyModelRoute(client, apiKey, model, "gemini");
+ return modelQuote(card, {}, {
+ source: `${client.baseUrl}/models/${encodeURIComponent(model)}`,
+ observedAt,
+ });
+ }
+ const route = hypiHubRouteForCapability(context.need.capability);
+ if (route === undefined) return { status: "unknown", reason: "HypiHub does not quote this capability" };
+ const compiled = await route.compile(context.need.constraints, async () => "https://quote.invalid/reference");
+ const input = compiled.input as Record<string, unknown>;
+ const card = await verifyModelRoute(client, apiKey, compiled.model, generationOperation(route, input));
+ return modelQuote(card, input, {
+ source: `${client.baseUrl}/models/${encodeURIComponent(compiled.model)}`,
+ observedAt,
+ });
+}
+
async function complete(client: HypiHubClient, apiKey: string, route: (typeof hypiHubRoutes)[number], id: string, artifacts: ResourceStore): Promise<EndpointOutcome> {
const response = await client.json(`/jobs/${encodeURIComponent(id)}/assets`, apiKey); const items = response.items;
assert(Array.isArray(items) && items.length > 0, "HypiHub job has no assets"); const blobs: BlobRef[] = [];
@@ -186,15 +417,10 @@ function endpoint(client: HypiHubClient, pollIntervalMs: number, maxOperationMs:
const compiled = await route.compile(context.need.constraints, resolve);
assert(route.media !== "audio", "HypiHub audio capabilities use an immediate endpoint");
const input = compiled.input as Record<string, unknown>;
- const hasReferences = Object.entries(input).some(([key, value]) => {
- if (!["images", "reference_images", "reference_image_urls", "reference_videos", "reference_audios", "first_frame", "last_frame"].includes(key)) return false;
- return Array.isArray(value) ? value.length > 0 : typeof value === "string" && value.length > 0;
- });
- const path = route.media === "image"
- ? (hasReferences ? "/images/edits" : "/images/generations")
- : "/videos";
- await verifyModelRoute(client, apiKey, compiled.model,
- path === "/images/edits" ? "image_edits" : path === "/images/generations" ? "images" : "videos");
+ const operation = generationOperation(route, input);
+ const path = operation === "image_edits" ? "/images/edits"
+ : operation === "images" ? "/images/generations" : "/videos";
+ await verifyModelRoute(client, apiKey, compiled.model, operation);
const response = await client.json(path, apiKey, { method: "POST", headers: { "content-type": "application/json", "idempotency-key": context.operation }, body: JSON.stringify({ model: compiled.model, ...input }) });
const status = response.status; if (status === "succeeded" || status === "completed") return await complete(client, apiKey, route, jobId(response), context.resources);
const handle: Handle = { contract: "hypit.hypihub-operation@1", jobId: jobId(response), route: capabilityKey(route.capability), startedAt: Date.now() };
@@ -250,6 +476,34 @@ export function createHypiHubProvider(options: CreateHypiHubProviderOptions = {}
const value = await generate({ parts, instruction: request.instruction });
return { value: { kind: "inline", value: canonicalize(sealText(value)) } };
};
+ const transcriptionModel = options.transcriptionModel?.trim() || "victor-upmeet/whisperx";
+ const whisperXEndpoint: ImmediateEndpointHandler = async (context) => {
+ try {
+ const request = verifyWhisperXAlignmentRequest(context.need.constraints);
+ const bytes = await context.resources.get(request.audio.resource);
+ assert(bytes !== undefined && bytes.byteLength === request.audio.size,
+ `WhisperX evidence Artifact ${request.audio.resource} is unavailable or has changed`);
+ assertWhisperXEvidenceWav(bytes, request.sampleFrames);
+ const apiKey = credential(context);
+ await verifyModelRoute(client, apiKey, transcriptionModel, "transcriptions");
+ const copy = new ArrayBuffer(bytes.byteLength);
+ new Uint8Array(copy).set(bytes);
+ const form = new FormData();
+ form.append("model", transcriptionModel);
+ form.append("file", new Blob([copy], { type: request.audio.mediaType }), "alignment-evidence.wav");
+ form.append("response_format", "verbose_json");
+ form.append("language", request.language);
+ form.append("timestamp_granularities[]", "segment");
+ form.append("timestamp_granularities[]", "word");
+ const response = await client.json("/audio/transcriptions", apiKey, { method: "POST", body: form });
+ const evidence = sealAlignedTranscriptEvidence({
+ passages: interpretWhisperXTranscript(response as WhisperXTranscriptResponse, request.sampleFrames),
+ });
+ return { value: { kind: "inline", value: canonicalize(evidence) } };
+ } catch (error) {
+ throw new Error(guidedMessage(error), { cause: error });
+ }
+ };
return defineEndpointPackage({
module: hypiHubProviderModuleRef, facet: "gateway", instance: options.instance ?? "hypihub.default", pool: options.pool ?? options.instance ?? "hypihub.default",
credentials: { apiKey: options.apiKey ?? credentialRef("os", "hypihub.oauth") },
@@ -268,15 +522,26 @@ export function createHypiHubProvider(options: CreateHypiHubProviderOptions = {}
...hypiHubRoutes
.filter((route) => options.audio !== false || route.media !== "audio")
.map((route) => route.media === "audio"
- ? { capability: route.capability, returns: route.returns, lifecycle: "immediate" as const, handler: audioEndpoint, lane: route.capability.name }
- : { capability: route.capability, returns: route.returns, lifecycle: "asynchronous" as const, endpoint: asyncEndpoint, lane: route.capability.name }),
+ ? { capability: route.capability, returns: route.returns, lifecycle: "immediate" as const, handler: audioEndpoint, lane: route.capability.name,
+ quote: async (context: EndpointQuoteContext) => await quoteHypiHubNeed(client, context, transcriptionModel) }
+ : { capability: route.capability, returns: route.returns, lifecycle: "asynchronous" as const, endpoint: asyncEndpoint, lane: route.capability.name,
+ quote: async (context: EndpointQuoteContext) => await quoteHypiHubNeed(client, context, transcriptionModel) }),
...geminiModels.map((model) => ({
capability: geminiCapabilities[model],
returns: textTypes.text,
lifecycle: "immediate" as const,
handler: geminiEndpoint,
lane: "gemini",
+ quote: async (context: EndpointQuoteContext) => await quoteHypiHubNeed(client, context, transcriptionModel),
})),
+ {
+ capability: whisperXCapabilities.alignment,
+ returns: speechEvidenceTypes.alignedTranscript,
+ lifecycle: "immediate" as const,
+ handler: whisperXEndpoint,
+ lane: "transcription",
+ quote: async (context: EndpointQuoteContext) => await quoteHypiHubNeed(client, context, transcriptionModel),
+ },
],
});
}
diff --git a/packages/provider-hypihub/test/provider.test.ts b/packages/provider-hypihub/test/provider.test.ts
index ae0b1ed9..df232201 100644
--- a/packages/provider-hypihub/test/provider.test.ts
+++ b/packages/provider-hypihub/test/provider.test.ts
@@ -8,8 +8,11 @@ import type { CanonicalValue, Need } from "@hypit/protocol";
import { mimoTtsEndpoints } from "@hypit/mimo-tts";
import { textTypes } from "@hypit/text";
import { sealSeedanceRequest, seedanceEndpoints } from "@hypit/seedance";
+import { sealSpeechEvidenceAudio } from "@hypit/speech";
+import { speechEvidenceTypes } from "@hypit/speech-evidence";
+import { whisperXCapabilities, whisperXRequestForEvidenceAudio } from "@hypit/whisperx";
-import { createHypiHubProvider } from "../src/provider.js";
+import { createHypiHubProvider, diagnoseHypiHubProvider } from "../src/provider.js";
function need(constraints: CanonicalValue): Need {
return {
@@ -30,6 +33,28 @@ async function endpointFor(request: Need, fetch: typeof globalThis.fetch): Promi
return resolution.registration.endpoint;
}
+function wav(sampleFrames: number): Uint8Array {
+ const bytes = new Uint8Array(44 + sampleFrames * 2);
+ const view = new DataView(bytes.buffer);
+ const write = (offset: number, value: string): void => {
+ for (let index = 0; index < value.length; index += 1) bytes[offset + index] = value.charCodeAt(index);
+ };
+ write(0, "RIFF");
+ view.setUint32(4, bytes.byteLength - 8, true);
+ write(8, "WAVE");
+ write(12, "fmt ");
+ view.setUint32(16, 16, true);
+ view.setUint16(20, 1, true);
+ view.setUint16(22, 1, true);
+ view.setUint32(24, 16_000, true);
+ view.setUint32(28, 32_000, true);
+ view.setUint16(32, 2, true);
+ view.setUint16(34, 16, true);
+ write(36, "data");
+ view.setUint32(40, sampleFrames * 2, true);
+ return bytes;
+}
+
test("HypiHub declares its own credential acquisition flow", () => {
const [credential] = createHypiHubProvider().credentials;
assert.equal(credential?.acquisition?.kind, "oauth2-pkce");
@@ -37,6 +62,79 @@ test("HypiHub declares its own credential acquisition flow", () => {
assert.equal(credential?.acquisition?.tokenEndpoint, "https://hypit.ai/oauth/token");
});
+test("HypiHub quotes an exact generation Need from the authenticated model card", async () => {
+ const request = need(sealSeedanceRequest("seedance-2-mini", {
+ prompt: ["A presenter turns toward camera."],
+ resolution: ["720p"],
+ aspectRatio: ["16:9"],
+ duration: [5],
+ generateAudio: [false],
+ webSearch: [false],
+ }) as unknown as CanonicalValue);
+ const provider = createHypiHubProvider({ fetch: async (input) => {
+ assert.match(String(input), /\/v1\/models\/bytedance%2Fseedance-2-mini$/u);
+ return Response.json({
+ endpoints: ["videos"],
+ pricing: {
+ mode: "per_second",
+ resolution_ratio: { "480p": 1, "720p": 2.1579 },
+ credits: { per_second: 5.648 },
+ },
+ });
+ } });
+ const offer = provider.offers.find((item) => item.capability.name === "seedance-2-mini");
+ assert.ok(offer?.quote !== undefined);
+ const quote = await offer.quote({ need: request, credentials: { apiKey: { secret: "test-key" } } });
+ assert.deepEqual(quote, {
+ status: "estimated",
+ amount: 60.9391,
+ currency: "credits",
+ basis: { mode: "per_second", quantity: 5, rate: 5.648, multiplier: 2.1579 },
+ source: "https://hypit.ai/v1/models/bytedance%2Fseedance-2-mini",
+ observedAt: quote.status === "estimated" ? quote.observedAt : -1,
+ });
+});
+
+test("HypiHub refuses to underquote an exact request whose price factor is absent", async () => {
+ const request = need(sealSeedanceRequest("seedance-2-mini", {
+ prompt: ["A presenter turns toward camera."],
+ resolution: ["720p"],
+ aspectRatio: ["16:9"],
+ duration: [5],
+ generateAudio: [false],
+ webSearch: [false],
+ }) as unknown as CanonicalValue);
+ const provider = createHypiHubProvider({ fetch: async () => Response.json({
+ endpoints: ["videos"],
+ pricing: {
+ mode: "per_second",
+ resolution_ratio: { "480p": 1 },
+ credits: { per_second: 5.648 },
+ },
+ }) });
+ const offer = provider.offers.find((item) => item.capability.name === "seedance-2-mini");
+ assert.ok(offer?.quote !== undefined);
+ assert.deepEqual(await offer.quote({ need: request, credentials: { apiKey: { secret: "test-key" } } }), {
+ status: "unknown",
+ reason: "HypiHub model card has no price factor for this exact request",
+ });
+});
+
+test("HypiHub doctor checks the authenticated catalogue only when actively invoked", async () => {
+ let calls = 0;
+ const diagnostics = await diagnoseHypiHubProvider({ fetch: async (input, init) => {
+ calls += 1;
+ assert.match(String(input), /\/v1\/models$/u);
+ assert.equal((init?.headers as Record<string, string>).authorization, "Bearer test-key");
+ return Response.json({ data: [{ id: "victor-upmeet/whisperx", endpoints: ["transcriptions"] }] });
+ } }, {
+ credentials: { apiKey: { secret: "test-key" } },
+ capabilities: [whisperXCapabilities.alignment],
+ });
+ assert.equal(calls, 1);
+ assert.deepEqual(diagnostics, []);
+});
+
test("HypiHub exposes VoiceDesign by default and permits an explicit alternate audio Provider", async () => {
const registry = new EndpointRegistry();
await createHypiHubProvider({ fetch: async () => { throw new Error("audio must not call fetch"); } }).install(registry);
@@ -171,3 +269,66 @@ test("HypiHub fulfills Gemini through the Runtime endpoint and uploads every med
{ fileData: { mimeType: "video/mp4", fileUri: "https://hypit.ai/files/2" } },
] }]);
});
+
+test("HypiHub fulfills the Provider-neutral WhisperX alignment capability", async () => {
+ const resources = new MemoryResourceStore();
+ const bytes = wav(32_000);
+ const artifact = await resources.put(bytes, "audio/wav");
+ const request: Need = {
+ id: "need:hypihub-whisperx",
+ capability: whisperXCapabilities.alignment,
+ returns: speechEvidenceTypes.alignedTranscript,
+ constraints: whisperXRequestForEvidenceAudio(sealSpeechEvidenceAudio({
+ artifact,
+ sampleFrames: 32_000,
+ }), { language: "en" }) as unknown as CanonicalValue,
+ result: "record:hypihub-whisperx",
+ };
+ let submitted = false;
+ const registry = new EndpointRegistry();
+ await createHypiHubProvider({ fetch: async (input, init) => {
+ const url = String(input);
+ if (url.endsWith("/v1/models/victor-upmeet%2Fwhisperx")) {
+ return Response.json({ endpoints: ["transcriptions"] });
+ }
+ if (url.endsWith("/v1/audio/transcriptions")) {
+ submitted = true;
+ assert.ok(init?.body instanceof FormData);
+ assert.equal(init.body.get("model"), "victor-upmeet/whisperx");
+ assert.equal(init.body.get("language"), "en");
+ assert.equal(init.body.get("response_format"), "verbose_json");
+ assert.deepEqual(init.body.getAll("timestamp_granularities[]"), ["segment", "word"]);
+ const file = init.body.get("file");
+ assert.ok(file instanceof File);
+ assert.equal(file.type, "audio/wav");
+ assert.deepEqual(new Uint8Array(await file.arrayBuffer()), bytes);
+ return Response.json({
+ language: "en",
+ words: [
+ { word: "hello", start: 0.1, end: 0.4 },
+ { word: "world", start: 1.2, end: 1.6 },
+ ],
+ });
+ }
+ throw new Error(`Unexpected URL ${url}`);
+ } }).install(registry);
+ const resolution = registry.resolve(request);
+ assert.equal(resolution.status, "resolved");
+ assert.equal(resolution.registration.kind, "immediate");
+ const result = await resolution.registration.handler({
+ command: { kind: "fulfill-need", id: "command:hypihub-whisperx", need: request },
+ need: request,
+ resources,
+ credentials: { apiKey: { secret: "test-key" } },
+ });
+ assert.equal(submitted, true);
+ assert.deepEqual(result.value, { kind: "inline", value: { passages: [{
+ startSample: 1_600,
+ endSampleExclusive: 25_600,
+ words: [
+ { text: "hello", startSample: 1_600, endSampleExclusive: 6_400 },
+ { text: "world", startSample: 19_200, endSampleExclusive: 25_600 },
+ ],
+ chars: [],
+ }] } });
+});
diff --git a/packages/provider-whisperx-local/src/provider.ts b/packages/provider-whisperx-local/src/provider.ts
index a899aa86..0e160a5f 100644
--- a/packages/provider-whisperx-local/src/provider.ts
+++ b/packages/provider-whisperx-local/src/provider.ts
@@ -2,15 +2,18 @@ import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { sealAlignedTranscriptEvidence, speechEvidenceTypes } from "@hypit/speech-evidence";
-import type { AlignedTranscriptEvidence, SpeechTranscriptPassage } from "@hypit/speech-evidence";
+import type { AlignedTranscriptEvidence } from "@hypit/speech-evidence";
import type { EndpointInvocationContext, EndpointFulfillment } from "@hypit/endpoint-kit";
import { canonicalize } from "@hypit/protocol";
import type { CanonicalValue } from "@hypit/protocol";
import { defineEndpointPackage } from "@hypit/endpoint-kit";
import {
+ assertWhisperXEvidenceWav,
+ interpretWhisperXTranscript,
+ verifyWhisperXAlignmentRequest,
whisperXCapabilities,
} from "@hypit/whisperx";
-import type { WhisperXAlignmentRequest } from "@hypit/whisperx";
+import type { WhisperXTranscriptResponse } from "@hypit/whisperx";
export const localWhisperXProviderModuleRef = {
name: "@hypit/provider-whisperx-local",
@@ -32,24 +35,7 @@ export type CreateLocalWhisperXProviderOptions = {
readonly maxResponseBytes?: number;
};
-type RawWord = {
- readonly text?: unknown;
- readonly word?: unknown;
- readonly start?: unknown;
- readonly end?: unknown;
- readonly score?: unknown;
-};
-
-type RawSegment = {
- readonly start?: unknown;
- readonly end?: unknown;
- readonly words?: unknown;
-};
-
-export type WhisperXServiceResponse = {
- readonly language?: unknown;
- readonly segments?: unknown;
-};
+export type WhisperXServiceResponse = WhisperXTranscriptResponse;
function assert(condition: unknown, message: string): asserts condition {
if (!condition) throw new Error(message);
@@ -60,111 +46,7 @@ function positiveInteger(value: number, subject: string): number {
return value;
}
-function finite(value: unknown): value is number {
- return typeof value === "number" && Number.isFinite(value);
-}
-
-function alignmentRequest(value: CanonicalValue): WhisperXAlignmentRequest {
- assert(value !== null && typeof value === "object" && !Array.isArray(value),
- "WhisperX alignment request must be an object");
- const item = value as unknown as WhisperXAlignmentRequest;
- assert(item.audio?.kind === "blob"
- && item.audio.mediaType === "audio/wav"
- && Number.isSafeInteger(item.sampleFrames)
- && item.sampleFrames > 0
- && (item.language === "en" || item.language === "zh" || item.language === "es"),
- "WhisperX alignment request is invalid");
- return item;
-}
-
-function fourCc(bytes: Uint8Array, offset: number): string {
- return String.fromCharCode(...bytes.subarray(offset, offset + 4));
-}
-
-/** Fail closed if the Provider would cause the service to normalize audio a second time. */
-function assertCanonicalEvidenceWav(bytes: Uint8Array, sampleFrames: number): void {
- assert(bytes.byteLength >= 44 && fourCc(bytes, 0) === "RIFF" && fourCc(bytes, 8) === "WAVE",
- "WhisperX evidence Artifact is not a WAV file");
- const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
- let offset = 12;
- let format: { readonly codec: number; readonly channels: number; readonly sampleRate: number; readonly bits: number }
- | undefined;
- let dataBytes: number | undefined;
- while (offset + 8 <= bytes.byteLength) {
- const name = fourCc(bytes, offset);
- const size = view.getUint32(offset + 4, true);
- const body = offset + 8;
- assert(body + size <= bytes.byteLength, "WhisperX evidence WAV has a truncated chunk");
- if (name === "fmt ") {
- assert(size >= 16, "WhisperX evidence WAV fmt chunk is invalid");
- format = {
- codec: view.getUint16(body, true),
- channels: view.getUint16(body + 2, true),
- sampleRate: view.getUint32(body + 4, true),
- bits: view.getUint16(body + 14, true),
- };
- } else if (name === "data") {
- dataBytes = size;
- }
- offset = body + size + (size % 2);
- }
- assert(format?.codec === 1 && format.channels === 1 && format.sampleRate === 16_000 && format.bits === 16,
- "WhisperX evidence must be 16 kHz mono PCM s16 WAV");
- assert(dataBytes === sampleFrames * 2, "WhisperX evidence sample count differs from its contract");
-}
-
-function sampleWindow(
- startSec: unknown,
- endSec: unknown,
- sampleFrames: number,
-): { readonly startSample: number; readonly endSampleExclusive: number } | undefined {
- if (!finite(startSec) || !finite(endSec) || startSec < 0 || endSec < startSec) return undefined;
- const startSample = Math.round(startSec * 16_000);
- const endSampleExclusive = Math.round(endSec * 16_000);
- if (!Number.isSafeInteger(startSample) || !Number.isSafeInteger(endSampleExclusive)
- || startSample > sampleFrames || endSampleExclusive > sampleFrames) return undefined;
- return { startSample, endSampleExclusive };
-}
-
-/** Lower WhisperX's wire-level seconds once into exact 16 kHz evidence-sample boundaries. */
-export function interpretWhisperXResponse(
- response: WhisperXServiceResponse,
- sampleFrames: number,
-): readonly SpeechTranscriptPassage[] {
- positiveInteger(sampleFrames, "WhisperX evidence sample count");
- assert(Array.isArray(response.segments), "WhisperX response has no Segment array");
- return response.segments.map((rawSegmentValue): SpeechTranscriptPassage => {
- assert(rawSegmentValue !== null && typeof rawSegmentValue === "object" && !Array.isArray(rawSegmentValue),
- "WhisperX response Segment is invalid");
- const rawSegment = rawSegmentValue as RawSegment;
- const passageWindow = sampleWindow(rawSegment.start, rawSegment.end, sampleFrames);
- assert(Array.isArray(rawSegment.words), "WhisperX response Segment has no Word array");
- const words: Array<SpeechTranscriptPassage["words"][number]> = [];
- for (const rawWordValue of rawSegment.words) {
- assert(rawWordValue !== null && typeof rawWordValue === "object" && !Array.isArray(rawWordValue),
- "WhisperX response Word is invalid");
- const rawWord = rawWordValue as RawWord;
- const text = typeof rawWord.text === "string"
- ? rawWord.text.trim()
- : typeof rawWord.word === "string" ? rawWord.word.trim() : "";
- if (text.length === 0) continue;
- const wordWindow = sampleWindow(rawWord.start, rawWord.end, sampleFrames);
- const score = finite(rawWord.score) && rawWord.score >= 0 && rawWord.score <= 1
- ? rawWord.score
- : undefined;
- words.push({
- text,
- ...wordWindow,
- ...(score === undefined ? {} : { score }),
- });
- }
- return {
- ...passageWindow,
- words,
- chars: [],
- };
- });
-}
+export const interpretWhisperXResponse = interpretWhisperXTranscript;
async function limitedJson(response: Response, maxBytes: number, subject: string): Promise<{
readonly value: unknown;
@@ -240,11 +122,11 @@ export function createLocalWhisperXProvider(config: CreateLocalWhisperXProviderO
capability: whisperXCapabilities.alignment,
returns: speechEvidenceTypes.alignedTranscript,
handler: async (context: EndpointInvocationContext) => {
- const request = alignmentRequest(context.need.constraints);
+ const request = verifyWhisperXAlignmentRequest(context.need.constraints);
const audio = await context.resources.get(request.audio.resource);
assert(audio !== undefined && audio.byteLength === request.audio.size,
`WhisperX evidence Artifact ${request.audio.resource} is unavailable or has changed`);
- assertCanonicalEvidenceWav(audio, request.sampleFrames);
+ assertWhisperXEvidenceWav(audio, request.sampleFrames);
const work = await mkdtemp(join(tmpdir(), "hypit-whisperx-local-"));
try {
const audioPath = join(work, "alignment-evidence.wav");
diff --git a/packages/runtime-host-node/src/index.ts b/packages/runtime-host-node/src/index.ts
index 5ac5e9bd..0158f5c6 100644
--- a/packages/runtime-host-node/src/index.ts
+++ b/packages/runtime-host-node/src/index.ts
@@ -5,7 +5,7 @@ import { delimiter, isAbsolute, join, resolve } from "node:path";
import type { ArtifactAttachment } from "@hypit/workspace";
import type { BuildResultForward } from "@hypit/build-result";
import type { BuildResultRepositoryLocation } from "@hypit/build-result-kit";
-import type { BuildDefinition, BuildState, CapabilityRef } from "@hypit/protocol";
+import type { BuildDefinition, BuildState, CapabilityRef, Need } from "@hypit/protocol";
import type {
BuildCatalogDescriptor,
BuildCompletion,
@@ -127,6 +127,28 @@ export type RuntimeHostDoctorResult = {
readonly diagnostics: readonly RuntimeDoctorDiagnostic[];
};
+export type RuntimeHostNeedQuote = {
+ readonly need: string;
+ readonly capability: CapabilityRef;
+ readonly endpoint?: string;
+ readonly quote:
+ | {
+ readonly status: "estimated";
+ readonly amount: number;
+ readonly currency: string;
+ readonly basis: {
+ readonly mode: string;
+ readonly quantity: number;
+ readonly rate: number;
+ readonly base?: number;
+ readonly multiplier?: number;
+ };
+ readonly source: string;
+ readonly observedAt: number;
+ }
+ | { readonly status: "unknown"; readonly reason: string };
+};
+
export type ManagedProgramProgress = {
readonly id: string;
readonly phase: "checking" | "installing" | "starting" | "waiting" | "ready";
@@ -209,6 +231,8 @@ export type NodeRuntimeHost = {
doctor(options?: {
readonly capabilities?: readonly CapabilityRef[];
}): Promise<RuntimeHostDoctorResult>;
+ /** Ask the selected Provider for the current price of each exact Need; never submits work. */
+ quote(needs: readonly Need[]): Promise<readonly RuntimeHostNeedQuote[]>;
runWorker(readyFile: string, owner: string): Promise<void>;
};
diff --git a/packages/runtime-kit/src/index.ts b/packages/runtime-kit/src/index.ts
index 0fef61ed..ce97edf7 100644
--- a/packages/runtime-kit/src/index.ts
+++ b/packages/runtime-kit/src/index.ts
@@ -2,7 +2,7 @@ import type { EndpointPackage } from "@hypit/endpoint-kit";
import type { HostFacet } from "@hypit/host";
import type { CanonicalValue } from "@hypit/protocol";
import { credentialRef } from "@hypit/runtime";
-import type { CredentialRef, CredentialStore } from "@hypit/runtime";
+import type { CredentialRef, CredentialStore, CredentialValue } from "@hypit/runtime";
export const runtimeEndpointAdapterHostAbi = "hypit.runtime-endpoint-adapter-host@1";
export const runtimeCredentialStoreAdapterHostAbi = "hypit.runtime-credential-store-adapter-host@1";
@@ -63,7 +63,10 @@ export type ManagedProgram = {
export type RuntimeEndpointActivation = {
readonly endpoint: EndpointPackage;
readonly program?: ManagedProgram;
- readonly diagnose?: () => readonly RuntimeDoctorDiagnostic[] | Promise<readonly RuntimeDoctorDiagnostic[]>;
+ readonly diagnose?: (context: {
+ readonly credentials: Readonly<Record<string, CredentialValue>>;
+ readonly capabilities?: readonly import("@hypit/protocol").CapabilityRef[];
+ }) => readonly RuntimeDoctorDiagnostic[] | Promise<readonly RuntimeDoctorDiagnostic[]>;
};
export type RuntimeOpened<T> = {
diff --git a/packages/runtime-local/README.md b/packages/runtime-local/README.md
index f19d796e..f656bcb9 100644
--- a/packages/runtime-local/README.md
+++ b/packages/runtime-local/README.md
@@ -49,3 +49,12 @@ for a submission that never became active and therefore has no Result to save.
Source imports select author packages. Runtime Profile entries select only code allowed to access files,
credentials, processes or networks. Installing a package changes neither selection.
+
+The lifecycle commands have deliberately narrow meanings:
+
+- `hypit runtime init` writes and selects the Distribution's starter Profile; it performs no setup or
+ network access and never overwrites an existing Profile.
+- `hypit runtime up|down` manages local package preparation, declared local Programs and the Worker.
+ Remote services have no lifecycle for Hypit to start or stop.
+- `hypit doctor` is the active, read-only check. Endpoint-owned diagnostics may authenticate and read a
+ remote capability catalog; normal preflight never does.
diff --git a/packages/runtime-local/src/config.ts b/packages/runtime-local/src/config.ts
index dfa0d03c..1b7b86d9 100644
--- a/packages/runtime-local/src/config.ts
+++ b/packages/runtime-local/src/config.ts
@@ -8,11 +8,11 @@ import {
} from "@hypit/package-loader-node";
import type { NodePackageSelectionRequest } from "@hypit/package-loader-node";
import { assertBuildId, canonicalize, canonicalStringify } from "@hypit/protocol";
-import type { CanonicalValue, CapabilityRef } from "@hypit/protocol";
+import type { CanonicalValue, CapabilityRef, Need } from "@hypit/protocol";
import {
CompositeCredentialStore,
} from "@hypit/runtime";
-import type { CredentialStore } from "@hypit/runtime";
+import type { CredentialStore, CredentialValue } from "@hypit/runtime";
import { FileResourceStore } from "@hypit/resource-store-fs";
import { FileBuildResultRepository } from "@hypit/build-result";
import {
@@ -44,7 +44,7 @@ import {
hypitHostStateRoot,
prepareHostPackages,
} from "@hypit/runtime-host-node";
-import type { HostPackageProgress, HostPackageReport } from "@hypit/runtime-host-node";
+import type { HostPackageProgress, HostPackageReport, RuntimeHostNeedQuote } from "@hypit/runtime-host-node";
import { SqliteRuntimeState } from "@hypit/store-sqlite";
import { createLocalRuntime } from "./runtime.js";
@@ -382,6 +382,15 @@ function capabilityKey(capability: CapabilityRef): string {
return `${capability.module.name}@${capability.module.version}#${capability.name}`;
}
+function sameRef(
+ left: { readonly module: { readonly name: string; readonly version: string }; readonly name: string },
+ right: { readonly module: { readonly name: string; readonly version: string }; readonly name: string },
+): boolean {
+ return left.module.name === right.module.name
+ && left.module.version === right.module.version
+ && left.name === right.name;
+}
+
function adapterContext(
root: string,
hostStateRoot: string,
@@ -516,7 +525,7 @@ async function inspectRuntimeConfig(
? undefined
: new Set(options.capabilities.map(capabilityKey));
const covered = new Set<string>();
- const credentialEndpoints: RuntimeEndpointActivation[] = [];
+ const selectedEndpoints: Array<{ readonly item: LocalRuntimeAdapterSelection; readonly activation: RuntimeEndpointActivation }> = [];
for (const item of document.endpoints) {
let activation: RuntimeEndpointActivation;
try {
@@ -530,12 +539,7 @@ async function inspectRuntimeConfig(
}
if (requested !== undefined && !activation.endpoint.offers.some((offer) => requested.has(capabilityKey(offer.capability)))) continue;
for (const offer of activation.endpoint.offers) covered.add(capabilityKey(offer.capability));
- try {
- diagnostics.push(...(activation.diagnose === undefined ? [] : await activation.diagnose()));
- } catch (error) {
- diagnostics.push(diagnostic(error, "RUNTIME_ADAPTER_DOCTOR_FAILED", item.instance));
- }
- credentialEndpoints.push(activation);
+ selectedEndpoints.push({ item, activation });
const program = activation.program;
if (program === undefined) continue;
let state: ManagedProgramState;
@@ -562,13 +566,20 @@ async function inspectRuntimeConfig(
subject: capabilityKey(capability),
});
}
- if (credentialEndpoints.some((item) => item.endpoint.credentials.length > 0)) {
+ if (selectedEndpoints.length > 0) {
let stores: Awaited<ReturnType<typeof openCredentialStores>> | undefined;
try {
stores = await openCredentialStores(document, root, hostStateRoot, registry);
- for (const activation of credentialEndpoints) {
+ for (const { item, activation } of selectedEndpoints) {
+ const credentials: Record<string, CredentialValue> = {};
+ let missing = false;
for (const slot of activation.endpoint.credentials) {
- if (await stores.store.resolve(slot.ref) !== undefined) continue;
+ const value = await stores.store.resolve(slot.ref);
+ if (value !== undefined) {
+ credentials[slot.slot] = value;
+ continue;
+ }
+ missing = true;
diagnostics.push({
severity: "error",
code: "RUNTIME_CREDENTIAL_MISSING",
@@ -579,6 +590,18 @@ async function inspectRuntimeConfig(
subject: `${slot.endpoint}.${slot.slot}`,
});
}
+ if (!options.active || missing || activation.diagnose === undefined) continue;
+ try {
+ const capabilities = (options.capabilities ?? activation.endpoint.offers.map((offer) => offer.capability))
+ .filter((capability) => activation.endpoint.offers
+ .some((offer) => capabilityKey(offer.capability) === capabilityKey(capability)));
+ diagnostics.push(...await activation.diagnose({
+ credentials,
+ capabilities,
+ }));
+ } catch (error) {
+ diagnostics.push(diagnostic(error, "RUNTIME_ADAPTER_DOCTOR_FAILED", item.instance));
+ }
}
} catch (error) {
diagnostics.push(diagnostic(error, "RUNTIME_CREDENTIAL_CHECK_FAILED"));
@@ -609,6 +632,74 @@ export async function doctorRuntimeConfig(
return await inspectRuntimeConfig(path, { ...options, active: true });
}
+/** Provider-owned price estimates for exact Needs. This may read remote rate cards but never submits work. */
+export async function quoteRuntimeConfig(
+ path: string,
+ needs: readonly Need[],
+ options: LoadRuntimeConfigOptions = {},
+): Promise<readonly RuntimeHostNeedQuote[]> {
+ if (needs.length === 0) return [];
+ const { document, root, packageRoot } = await openRuntimeConfig(path, options.packageRoot);
+ const hostStateRoot = resolve(options.hostStateRoot ?? hypitHostStateRoot());
+ const registry = options.registry ?? new RuntimeAdapterRegistry();
+ await installRuntimeAdapters(registry, packageRoot, runtimePackageSelection(document), options.distributionPackageRoot);
+ const endpoints = await activatedEndpoints(document, root, hostStateRoot, registry);
+ let stores: Awaited<ReturnType<typeof openCredentialStores>> | undefined;
+ try {
+ stores = await openCredentialStores(document, root, hostStateRoot, registry);
+ return await Promise.all(needs.map(async (need): Promise<RuntimeHostNeedQuote> => {
+ const matches = endpoints.flatMap(({ activation }) => activation.endpoint.offers
+ .filter((offer) => sameRef(offer.capability, need.capability)
+ && sameRef(offer.returns, need.returns)
+ && (offer.supports?.(need) ?? true))
+ .map((offer) => ({ activation, offer })));
+ const base = { need: need.id, capability: structuredClone(need.capability) };
+ if (matches.length === 0) return {
+ ...base,
+ quote: { status: "unknown", reason: "No selected Endpoint implements this exact Need" },
+ };
+ if (matches.length > 1) return {
+ ...base,
+ quote: {
+ status: "unknown",
+ reason: `Several selected Endpoints implement this Need: ${matches.map((item) => item.offer.endpoint).sort().join(", ")}`,
+ },
+ };
+ const match = matches[0]!;
+ if (match.offer.quote === undefined) return {
+ ...base,
+ endpoint: match.offer.endpoint,
+ quote: { status: "unknown", reason: "The selected Provider does not expose a price estimate" },
+ };
+ const credentials: Record<string, CredentialValue> = {};
+ for (const slot of match.activation.endpoint.credentials) {
+ const value = await stores!.store.resolve(slot.ref);
+ if (value === undefined) return {
+ ...base,
+ endpoint: match.offer.endpoint,
+ quote: { status: "unknown", reason: `${slot.label} is not configured` },
+ };
+ credentials[slot.slot] = value;
+ }
+ try {
+ return {
+ ...base,
+ endpoint: match.offer.endpoint,
+ quote: await match.offer.quote({ need, credentials }),
+ };
+ } catch (error) {
+ return {
+ ...base,
+ endpoint: match.offer.endpoint,
+ quote: { status: "unknown", reason: error instanceof Error ? error.message : String(error) },
+ };
+ }
+ }));
+ } finally {
+ await stores?.close();
+ }
+}
+
export async function createRuntimeFromConfig(
path: string,
options: LoadRuntimeConfigOptions = {},
diff --git a/packages/runtime-local/src/host.ts b/packages/runtime-local/src/host.ts
index 2b3f62b6..77bf6b00 100644
--- a/packages/runtime-local/src/host.ts
+++ b/packages/runtime-local/src/host.ts
@@ -15,6 +15,7 @@ import {
doctorRuntimeConfig,
prepareRuntimeConfigPackages,
preflightRuntimeConfig,
+ quoteRuntimeConfig,
resolveRuntimeConfigPaths,
} from "./config.js";
import {
@@ -130,6 +131,10 @@ export async function openLocalRuntimeHost(
...distribution,
...(options?.capabilities === undefined ? {} : { capabilities: options.capabilities }),
}),
+ quote: async (needs) => await quoteRuntimeConfig(profile, needs, {
+ packageRoot: basePackageRoot,
+ ...distribution,
+ }),
runWorker: async (readyFile, owner) => {
const selected = await resolveRuntimeConfigPaths(profile, { packageRoot: basePackageRoot, ...distribution });
const leaseState = new SqliteRuntimeState(join(selected.dataRoot, "runtime.sqlite"));
diff --git a/packages/runtime-local/src/index.ts b/packages/runtime-local/src/index.ts
index b7256ea2..624402d5 100644
--- a/packages/runtime-local/src/index.ts
+++ b/packages/runtime-local/src/index.ts
@@ -19,6 +19,7 @@ export {
doctorRuntimeConfig,
prepareRuntimeConfigPackages,
preflightRuntimeConfig,
+ quoteRuntimeConfig,
parseLocalRuntimeProfile,
resolveRuntimeConfigPaths,
} from "./config.js";
diff --git a/packages/runtime-local/test/config.test.ts b/packages/runtime-local/test/config.test.ts
index 2ad823b2..cbf7a719 100644
--- a/packages/runtime-local/test/config.test.ts
+++ b/packages/runtime-local/test/config.test.ts
@@ -14,6 +14,8 @@ import {
createBuildResultRepositoryHostFacet,
} from "@hypit/build-result-kit";
import { FileBuildResultRepository } from "@hypit/build-result";
+import { defineEndpointPackage } from "@hypit/endpoint-kit";
+import { credentialRef } from "@hypit/runtime";
import { SqliteRuntimeState } from "@hypit/store-sqlite";
import {
createRuntimeControlFromConfig,
@@ -24,6 +26,7 @@ import {
openProjectBuildResultRepository,
parseLocalRuntimeProfile,
preflightRuntimeConfig,
+ quoteRuntimeConfig,
} from "@hypit/runtime-local";
function profile(config: {
readonly dataRoot?: string;
@@ -217,3 +220,112 @@ test("preflight validates credential stores without running their active doctor"
await rm(root, { recursive: true, force: true });
}
});
+
+test("preflight never runs an Endpoint's active doctor", async () => {
+ const root = await mkdtemp(join(tmpdir(), "hypit-runtime-endpoint-preflight-"));
+ const path = join(root, "hypit.runtime.json");
+ await writeFile(path, JSON.stringify(profile({
+ dataRoot: ".",
+ endpoints: { remote: { use: "example.remote" } },
+ })));
+ let activeChecks = 0;
+ const capability = { module: { name: "example.remote", version: "1" }, name: "observe" } as const;
+ const returns = { module: { name: "example.value", version: "1" }, name: "Observation" } as const;
+ let diagnosedCapabilities: readonly string[] = [];
+ const registry = new RuntimeAdapterRegistry();
+ registry.registerFacet(createRuntimeEndpointAdapterFacet({
+ use: "example.remote",
+ activate: (context) => ({
+ endpoint: {
+ instance: { id: context.instance, pool: context.pool ?? context.instance },
+ offers: [{ capability, returns, endpoint: context.instance }],
+ credentials: [],
+ install() {},
+ },
+ diagnose: async ({ capabilities }) => {
+ activeChecks += 1;
+ diagnosedCapabilities = (capabilities ?? []).map((item) => item.name);
+ return [];
+ },
+ }),
+ }));
+ try {
+ await preflightRuntimeConfig(path, { registry });
+ assert.equal(activeChecks, 0);
+ await doctorRuntimeConfig(path, { registry });
+ assert.equal(activeChecks, 1);
+ assert.deepEqual(diagnosedCapabilities, ["observe"]);
+ } finally {
+ await rm(root, { recursive: true, force: true });
+ }
+});
+
+test("Runtime quote selects one exact Endpoint and resolves only its declared credential", async () => {
+ const root = await mkdtemp(join(tmpdir(), "hypit-runtime-quote-"));
+ const path = join(root, "hypit.runtime.json");
+ await writeFile(path, JSON.stringify(profile({
+ dataRoot: ".",
+ credentials: { secrets: { use: "example.credentials" } },
+ endpoints: { paid: { use: "example.paid" } },
+ })));
+ const capability = { module: { name: "example.model", version: "1" }, name: "generate" } as const;
+ const returns = { module: { name: "example.value", version: "1" }, name: "Output" } as const;
+ const registry = new RuntimeAdapterRegistry();
+ registry.registerFacet(createRuntimeCredentialStoreAdapterFacet({
+ use: "example.credentials",
+ validate() {},
+ open: () => ({
+ value: {
+ async resolve(ref) {
+ return ref.store === "secrets" && ref.key === "paid.key" ? { secret: "configured" } : undefined;
+ },
+ },
+ }),
+ }));
+ registry.registerFacet(createRuntimeEndpointAdapterFacet({
+ use: "example.paid",
+ activate: (context) => ({
+ endpoint: defineEndpointPackage({
+ module: { name: "example.provider", version: "1" },
+ facet: "paid",
+ instance: context.instance,
+ pool: context.pool ?? context.instance,
+ credentials: { apiKey: credentialRef("secrets", "paid.key") },
+ capabilities: [{
+ capability,
+ returns,
+ lifecycle: "immediate",
+ handler: () => ({ value: { kind: "inline", value: null } }),
+ quote: ({ credentials }) => ({
+ status: "estimated",
+ amount: credentials.apiKey?.secret === "configured" ? 2 : 999,
+ currency: "credits",
+ basis: { mode: "per_request", quantity: 1, rate: 2 },
+ source: "https://prices.example/model",
+ observedAt: 1,
+ }),
+ }],
+ }),
+ }),
+ }));
+ try {
+ const [quote] = await quoteRuntimeConfig(path, [{
+ id: "need:priced",
+ capability,
+ returns,
+ constraints: {},
+ result: "record:priced",
+ }], { registry });
+ assert.equal(quote?.endpoint, "paid");
+ assert.deepEqual(quote?.quote, {
+ status: "estimated",
+ amount: 2,
+ currency: "credits",
+ basis: { mode: "per_request", quantity: 1, rate: 2 },
+ source: "https://prices.example/model",
+ observedAt: 1,
+ });
+ } finally {
+ await rm(root, { recursive: true, force: true });
+ }
+});
diff --git a/packages/video-cli/README.md b/packages/video-cli/README.md
index bcd333fd..5e174227 100644
--- a/packages/video-cli/README.md
+++ b/packages/video-cli/README.md
@@ -1,7 +1,8 @@
# `@hypit/video-cli`
-Official video command application. It selects the Markup compiler Host, but deliberately carries
-no built-in author, Run, Provider or Store package.
+Official video command application. It selects the Markup compiler Host and supplies one editable
+starter Runtime Profile. The CLI still imports no Provider or Store implementation; installed packages
+are activated only by explicit Source imports or Profile `use` entries.
Every Frontend, Surface, deterministic Producer and Validator is activated from Source imports.
Installing a new author package therefore does not require a video CLI or Core release. Source
@@ -11,7 +12,10 @@ From any project:
```bash
cd path/to/project
-hypit runtime use hypit.runtime.json
+hypit runtime init
+hypit auth login hypihub.default
+hypit doctor
+hypit runtime up
hypit check main.svml
hypit plan build.svrun
hypit build build.svrun --follow
diff --git a/packages/video-cli/src/distribution.ts b/packages/video-cli/src/distribution.ts
index bd0cd9a2..6aaba9bb 100644
--- a/packages/video-cli/src/distribution.ts
+++ b/packages/video-cli/src/distribution.ts
@@ -19,6 +19,31 @@ const installedLauncher = process.env.HYPIT_CLI_LAUNCHER;
export const videoCliDistribution: CliDistribution = {
packageRoot,
bootstrapPackages: [],
+ initialRuntimeProfile: {
+ format: "hypit.runtime-local@1",
+ dataRoot: ".hypit/runtimes/local",
+ credentials: {
+ os: { use: "@hypit/credential-store-os" },
+ },
+ endpoints: {
+ "hypihub.default": {
+ use: "@hypit/provider-hypihub",
+ pool: "hypihub.default",
+ config: {
+ baseUrl: "https://hypit.ai",
+ apiKey: { store: "os", key: "hypihub.oauth" },
+ },
+ },
+ "media.local": {
+ use: "@hypit/provider-media-local",
+ pool: "media.local",
+ },
+ "hyperframes.local": {
+ use: "@hypit/provider-hyperframes-local",
+ pool: "hyperframes.local",
+ },
+ },
+ },
createCompiler: createVideoCompiler,
discoverSourcePackages: async (path, options) => {
const { discoverVideoSourcePackages } = await import("./package-selection.js");
diff --git a/packages/whisperx/src/evidence.ts b/packages/whisperx/src/evidence.ts
index 3a61869a..46a1cc7b 100644
--- a/packages/whisperx/src/evidence.ts
+++ b/packages/whisperx/src/evidence.ts
@@ -2,6 +2,60 @@ import { assertSpeechEvidenceAudioIdentity } from "@hypit/speech";
import type { SpeechEvidenceAudio } from "@hypit/speech";
import type { WhisperXAlignmentRequest, WhisperXLanguage } from "./types.js";
+function assert(condition: unknown, message: string): asserts condition {
+ if (!condition) throw new Error(message);
+}
+
+/** Verify the Provider-neutral request carried by the WhisperX alignment capability. */
+export function verifyWhisperXAlignmentRequest(value: unknown): WhisperXAlignmentRequest {
+ assert(value !== null && typeof value === "object" && !Array.isArray(value),
+ "WhisperX alignment request must be an object");
+ const request = value as WhisperXAlignmentRequest;
+ assert(request.audio?.kind === "blob"
+ && request.audio.mediaType === "audio/wav"
+ && Number.isSafeInteger(request.sampleFrames)
+ && request.sampleFrames > 0
+ && (request.language === "en" || request.language === "zh" || request.language === "es"),
+ "WhisperX alignment request is invalid");
+ return request;
+}
+
+function fourCc(bytes: Uint8Array, offset: number): string {
+ return String.fromCharCode(...bytes.subarray(offset, offset + 4));
+}
+
+/** Refuse evidence bytes that would require a Provider to normalize audio a second time. */
+export function assertWhisperXEvidenceWav(bytes: Uint8Array, sampleFrames: number): void {
+ assert(bytes.byteLength >= 44 && fourCc(bytes, 0) === "RIFF" && fourCc(bytes, 8) === "WAVE",
+ "WhisperX evidence Artifact is not a WAV file");
+ const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+ let offset = 12;
+ let format: { readonly codec: number; readonly channels: number; readonly sampleRate: number; readonly bits: number }
+ | undefined;
+ let dataBytes: number | undefined;
+ while (offset + 8 <= bytes.byteLength) {
+ const name = fourCc(bytes, offset);
+ const size = view.getUint32(offset + 4, true);
+ const body = offset + 8;
+ assert(body + size <= bytes.byteLength, "WhisperX evidence WAV has a truncated chunk");
+ if (name === "fmt ") {
+ assert(size >= 16, "WhisperX evidence WAV fmt chunk is invalid");
+ format = {
+ codec: view.getUint16(body, true),
+ channels: view.getUint16(body + 2, true),
+ sampleRate: view.getUint32(body + 4, true),
+ bits: view.getUint16(body + 14, true),
+ };
+ } else if (name === "data") {
+ dataBytes = size;
+ }
+ offset = body + size + (size % 2);
+ }
+ assert(format?.codec === 1 && format.channels === 1 && format.sampleRate === 16_000 && format.bits === 16,
+ "WhisperX evidence must be 16 kHz mono PCM s16 WAV");
+ assert(dataBytes === sampleFrames * 2, "WhisperX evidence sample count differs from its contract");
+}
+
export function whisperXRequestForEvidenceAudio(
evidence: SpeechEvidenceAudio,
options: { readonly language: WhisperXLanguage },
diff --git a/packages/whisperx/src/index.ts b/packages/whisperx/src/index.ts
index f750a6f0..a39f9cdf 100644
--- a/packages/whisperx/src/index.ts
+++ b/packages/whisperx/src/index.ts
@@ -2,7 +2,13 @@ export {
whisperXComponent,
} from "./component.js";
export { whisperXSemanticTakeFragment } from "./fragment.js";
-export { whisperXRequestForEvidenceAudio } from "./evidence.js";
+export {
+ assertWhisperXEvidenceWav,
+ verifyWhisperXAlignmentRequest,
+ whisperXRequestForEvidenceAudio,
+} from "./evidence.js";
export { whisperXCapabilities, whisperXManifest, whisperXMarkupSurfaces, whisperXModuleRef, whisperXProducers, whisperXTypes } from "./manifest.js";
export { decodeWhisperXSemanticTakeSurface } from "./surface.js";
+export { interpretWhisperXTranscript } from "./transcript.js";
+export type { WhisperXTranscriptResponse } from "./transcript.js";
export type * from "./types.js";
diff --git a/packages/whisperx/src/transcript.ts b/packages/whisperx/src/transcript.ts
new file mode 100644
index 00000000..73a65bb3
--- /dev/null
+++ b/packages/whisperx/src/transcript.ts
@@ -0,0 +1,97 @@
+import type { SpeechTranscriptPassage } from "@hypit/speech-evidence";
+
+type RawWord = {
+ readonly text?: unknown;
+ readonly word?: unknown;
+ readonly start?: unknown;
+ readonly end?: unknown;
+ readonly score?: unknown;
+};
+
+type RawSegment = {
+ readonly start?: unknown;
+ readonly end?: unknown;
+ readonly words?: unknown;
+};
+
+/** Common transcription response accepted from local WhisperX and remote transcription APIs. */
+export type WhisperXTranscriptResponse = {
+ readonly language?: unknown;
+ readonly segments?: unknown;
+ readonly words?: unknown;
+};
+
+function assert(condition: unknown, message: string): asserts condition {
+ if (!condition) throw new Error(message);
+}
+
+function finite(value: unknown): value is number {
+ return typeof value === "number" && Number.isFinite(value);
+}
+
+function sampleWindow(
+ startSec: unknown,
+ endSec: unknown,
+ sampleFrames: number,
+): { readonly startSample: number; readonly endSampleExclusive: number } | undefined {
+ if (!finite(startSec) || !finite(endSec) || startSec < 0 || endSec < startSec) return undefined;
+ const startSample = Math.round(startSec * 16_000);
+ const endSampleExclusive = Math.round(endSec * 16_000);
+ if (!Number.isSafeInteger(startSample) || !Number.isSafeInteger(endSampleExclusive)
+ || startSample > sampleFrames || endSampleExclusive > sampleFrames) return undefined;
+ return { startSample, endSampleExclusive };
+}
+
+function words(value: unknown, sampleFrames: number): SpeechTranscriptPassage["words"] {
+ assert(Array.isArray(value), "WhisperX response has no Word array");
+ const result: Array<SpeechTranscriptPassage["words"][number]> = [];
+ for (const rawValue of value) {
+ assert(rawValue !== null && typeof rawValue === "object" && !Array.isArray(rawValue),
+ "WhisperX response Word is invalid");
+ const raw = rawValue as RawWord;
+ const text = typeof raw.text === "string"
+ ? raw.text.trim()
+ : typeof raw.word === "string" ? raw.word.trim() : "";
+ if (text.length === 0) continue;
+ const window = sampleWindow(raw.start, raw.end, sampleFrames);
+ const score = finite(raw.score) && raw.score >= 0 && raw.score <= 1 ? raw.score : undefined;
+ result.push({ text, ...window, ...(score === undefined ? {} : { score }) });
+ }
+ return result;
+}
+
+/** Lower wire-level seconds once into exact 16 kHz evidence-sample boundaries. */
+export function interpretWhisperXTranscript(
+ response: WhisperXTranscriptResponse,
+ sampleFrames: number,
+): readonly SpeechTranscriptPassage[] {
+ assert(Number.isSafeInteger(sampleFrames) && sampleFrames > 0,
+ "WhisperX evidence sample count must be a positive integer");
+ if (Array.isArray(response.segments)) {
+ const passages = response.segments.map((rawValue): SpeechTranscriptPassage => {
+ assert(rawValue !== null && typeof rawValue === "object" && !Array.isArray(rawValue),
+ "WhisperX response Segment is invalid");
+ const raw = rawValue as RawSegment;
+ return {
+ ...sampleWindow(raw.start, raw.end, sampleFrames),
+ words: raw.words === undefined ? [] : words(raw.words, sampleFrames),
+ chars: [],
+ };
+ });
+ if (passages.some((passage) => passage.words.length > 0) || response.words === undefined) {
+ return passages;
+ }
+ }
+ if (response.words !== undefined) {
+ const aligned = words(response.words, sampleFrames);
+ const first = aligned.find((word) => word.startSample !== undefined);
+ const last = [...aligned].reverse().find((word) => word.endSampleExclusive !== undefined);
+ return [{
+ ...(first?.startSample === undefined ? {} : { startSample: first.startSample }),
+ ...(last?.endSampleExclusive === undefined ? {} : { endSampleExclusive: last.endSampleExclusive }),
+ words: aligned,
+ chars: [],
+ }];
+ }
+ throw new Error("WhisperX response has no Segment or Word array");
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 1e0eb506..e20253f0 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -2072,9 +2072,15 @@ importers:
'@hypit/runtime-kit':
specifier: workspace:*
version: link:../runtime-kit
+ '@hypit/speech-evidence':
+ specifier: workspace:*
+ version: link:../speech-evidence
'@hypit/text':
specifier: workspace:*
version: link:../text
+ '@hypit/whisperx':
+ specifier: workspace:*
+ version: link:../whisperx
devDependencies:
'@hypit/driver-node':
specifier: workspace:*
@@ -2085,6 +2091,9 @@ importers:
'@hypit/seedance':
specifier: workspace:*
version: link:../seedance
+ '@hypit/speech':
+ specifier: workspace:*
+ version: link:../speech
packages/provider-image-opencv-local:
dependencies: