@hypit/hypit 0.0.1 → 0.1.1

package/packages/workspace-fs-node/src/workspace.ts

@@ -0,0 +1,226 @@
+import { randomUUID } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { readFile, realpath, stat } from "node:fs/promises";
+import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
+
+import type {
+  Awaitable,
+  SourceAssetRequest,
+  SourceImportRequest,
+  SourceUnit,
+} from "@hypit/source";
+import type {
+  ArtifactAttachment,
+  Workspace,
+  WorkspaceSession,
+} from "@hypit/workspace";
+import { WorkspaceError } from "@hypit/workspace";
+import type { BlobRef } from "@hypit/protocol";
+
+function isWithin(root: string, path: string): boolean {
+  const relation = relative(root, path);
+  return relation === "" || (!relation.startsWith("..") && !isAbsolute(relation));
+}
+
+export type NodeFilesystemExternalSource = {
+  readonly root: string;
+  readonly source: string;
+};
+
+export type NodeFilesystemExternalSourceResolver = (
+  importer: SourceUnit,
+  request: SourceImportRequest,
+) => Awaitable<NodeFilesystemExternalSource>;
+
+class NodeFilesystemWorkspaceSession implements WorkspaceSession {
+  readonly root: string;
+  readonly entry: SourceUnit;
+  readonly #assetRoots: readonly string[];
+  readonly #externalSourceResolver: NodeFilesystemExternalSourceResolver | undefined;
+  readonly #sourceCache = new Map<string, SourceUnit>();
+  readonly #sourceRoots = new Map<string, string>();
+  readonly #assetIdentity = new Map<string, {
+    readonly resource: BlobRef["resource"];
+    readonly size: number;
+  }>();
+  readonly #attachments = new Map<string, ArtifactAttachment>();
+
+  private constructor(
+    root: string,
+    entry: SourceUnit,
+    assetRoots: readonly string[],
+    externalSourceResolver: NodeFilesystemExternalSourceResolver | undefined,
+  ) {
+    this.root = root;
+    this.entry = entry;
+    this.#assetRoots = assetRoots;
+    this.#externalSourceResolver = externalSourceResolver;
+    this.#sourceCache.set(entry.id, entry);
+    this.#sourceRoots.set(entry.id, root);
+  }
+
+  static async open(
+    rootLocator: string,
+    entryLocator: string,
+    assetRootLocators: readonly string[],
+    externalSourceResolver: NodeFilesystemExternalSourceResolver | undefined,
+  ): Promise<NodeFilesystemWorkspaceSession> {
+    const root = await realpath(resolve(rootLocator));
+    const assetRoots = await Promise.all(assetRootLocators.map(async (path) => await realpath(resolve(path))));
+    const canonicalEntry = await realpath(resolve(entryLocator));
+    if (!isWithin(root, canonicalEntry)) {
+      throw new WorkspaceError(
+        "SOURCE_OUTSIDE_ROOT",
+        `Source ${canonicalEntry} is outside workspace root ${root}`,
+        canonicalEntry,
+      );
+    }
+    const entry: SourceUnit = {
+      id: canonicalEntry,
+      name: relative(root, canonicalEntry) || basename(canonicalEntry) || canonicalEntry,
+      text: await readFile(canonicalEntry, "utf8"),
+    };
+    return new NodeFilesystemWorkspaceSession(root, entry, [root, ...assetRoots], externalSourceResolver);
+  }
+
+  async #loadSource(path: string, sourceRootLocator: string): Promise<SourceUnit> {
+    const sourceRoot = await realpath(resolve(sourceRootLocator));
+    const canonical = await realpath(resolve(path));
+    if (!isWithin(sourceRoot, canonical)) {
+      throw new WorkspaceError(
+        "SOURCE_OUTSIDE_ROOT",
+        `Source ${canonical} is outside its source root ${sourceRoot}`,
+        canonical,
+      );
+    }
+    const cached = this.#sourceCache.get(canonical);
+    if (cached !== undefined) {
+      const previousRoot = this.#sourceRoots.get(canonical);
+      if (previousRoot !== sourceRoot) {
+        throw new WorkspaceError(
+          "SOURCE_ROOT_CONFLICT",
+          `Source ${canonical} was resolved through both ${previousRoot ?? "an unknown root"} and ${sourceRoot}`,
+          canonical,
+        );
+      }
+      return cached;
+    }
+    const unit: SourceUnit = {
+      id: canonical,
+      name: relative(sourceRoot, canonical) || basename(canonical) || canonical,
+      text: await readFile(canonical, "utf8"),
+    };
+    this.#sourceCache.set(canonical, unit);
+    this.#sourceRoots.set(canonical, sourceRoot);
+    return unit;
+  }
+
+  readonly resolveSource = async (
+    importer: SourceUnit,
+    request: SourceImportRequest,
+  ): Promise<SourceUnit> => {
+    const importerRoot = this.#sourceRoots.get(importer.id);
+    if (importerRoot === undefined) {
+      throw new WorkspaceError("UNKNOWN_SOURCE_IMPORTER", `${importer.id} is outside this Workspace`, importer.id);
+    }
+    if (request.from.startsWith("./") || request.from.startsWith("../")) {
+      return await this.#loadSource(resolve(dirname(importer.id), request.from), importerRoot);
+    }
+    if (this.#externalSourceResolver === undefined) {
+      throw new WorkspaceError(
+        "UNSUPPORTED_SOURCE_IMPORT",
+        `Source import ${request.from} has no resolver in this Workspace`,
+        request.from,
+      );
+    }
+    const external = await this.#externalSourceResolver(importer, request);
+    return await this.#loadSource(external.source, external.root);
+  };
+
+  readonly resolveAsset = async (
+    importer: SourceUnit,
+    request: SourceAssetRequest,
+  ) => {
+    if (!request.from.startsWith("./") && !request.from.startsWith("../")) {
+      throw new WorkspaceError(
+        "UNSUPPORTED_SOURCE_ASSET",
+        `Source asset ${request.from} must be relative`,
+        request.from,
+      );
+    }
+    const importerRoot = this.#sourceRoots.get(importer.id);
+    if (importerRoot === undefined) {
+      throw new WorkspaceError("UNKNOWN_SOURCE_IMPORTER", `${importer.id} is outside this Workspace`, importer.id);
+    }
+    const canonical = await realpath(resolve(dirname(importer.id), request.from));
+    const allowedRoots = importerRoot === this.root ? this.#assetRoots : [importerRoot];
+    if (!allowedRoots.some((root) => isWithin(root, canonical))) {
+      throw new WorkspaceError(
+        "SOURCE_ASSET_OUTSIDE_ROOT",
+        `Source asset ${canonical} is outside the workspace and every allowed asset root`,
+        canonical,
+      );
+    }
+    let identity = this.#assetIdentity.get(canonical);
+    if (identity === undefined) {
+      const size = (await stat(canonical)).size;
+      identity = { resource: `res_${randomUUID()}`, size };
+      this.#assetIdentity.set(canonical, identity);
+    }
+    const artifact: BlobRef = {
+      kind: "blob",
+      resource: identity.resource,
+      size: identity.size,
+      mediaType: request.mediaType,
+    };
+    const attachmentKey = `${artifact.resource}\u0000${artifact.mediaType}`;
+    if (!this.#attachments.has(attachmentKey)) {
+      this.#attachments.set(attachmentKey, {
+        artifact: { ...artifact },
+        open: () => createReadStream(canonical),
+      });
+    }
+    return { artifact: { ...artifact } };
+  };
+
+  attachments(): readonly ArtifactAttachment[] {
+    return [...this.#attachments.values()]
+      .sort((left, right) => {
+        const byResource = left.artifact.resource.localeCompare(right.artifact.resource);
+        return byResource === 0 ? left.artifact.mediaType.localeCompare(right.artifact.mediaType) : byResource;
+      })
+      .map((item) => ({ artifact: { ...item.artifact }, open: item.open }));
+  }
+}
+
+export type NodeFilesystemWorkspaceOptions = {
+  /** Fixed containment root. Defaults to the entry SourceUnit directory for each session. */
+  readonly root?: string;
+  /** Additional read-only roots for asset bytes. They never permit Source imports. */
+  readonly assetRoots?: readonly string[];
+  /** Host-owned resolver for explicit non-relative Source locators, each with its own read boundary. */
+  readonly externalSourceResolver?: NodeFilesystemExternalSourceResolver;
+};
+
+/** Node filesystem implementation of the host-neutral, one-compilation Workspace contract. */
+export class NodeFilesystemWorkspace implements Workspace {
+  readonly #root: string | undefined;
+  readonly #assetRoots: readonly string[];
+  readonly #externalSourceResolver: NodeFilesystemExternalSourceResolver | undefined;
+
+  constructor(options: NodeFilesystemWorkspaceOptions = {}) {
+    this.#root = options.root;
+    this.#assetRoots = options.assetRoots ?? [];
+    this.#externalSourceResolver = options.externalSourceResolver;
+  }
+
+  async open(entryLocator: string): Promise<WorkspaceSession> {
+    const entry = resolve(entryLocator);
+    return await NodeFilesystemWorkspaceSession.open(
+      this.#root ?? dirname(entry),
+      entry,
+      this.#assetRoots,
+      this.#externalSourceResolver,
+    );
+  }
+}

package/packages/yt-dlp/README.md

@@ -0,0 +1,31 @@
+# Fetching video with yt-dlp
+
+`@hypit/yt-dlp` owns video download for the Hypit Distribution. Video CLI exposes it as:
+
+```bash
+hypit media fetch "https://example.com/watch?v=VIDEO_ID" --to references/source.mp4
+```
+
+The CLI creates destination directories, refuses existing output paths and probes the completed
+file. Add `--json` for the source URL, saved path and media properties. This operation opens no
+Runtime Profile and creates no Build.
+
+## Package boundary
+
+- `isVideoUrl(value)` recognizes HTTP and HTTPS links. Local paths, including Windows drive paths,
+  remain file inputs.
+- `downloadVideo(url, target)` downloads one video to the given path. Its caller owns destination
+  preparation and overwrite policy. The target extension must be `.mp4`, `.mkv`, `.webm` or `.mov`.
+
+The downloader invokes the locked Python project in `services/yt-dlp` through `uv`, located relative
+to the installed Distribution. Ship its `pyproject.toml` and `uv.lock` with this package's source.
+`uv` and `ffmpeg` must be available on PATH; the CLI also uses `ffprobe` to report the saved media.
+
+The request selects `bv*+ba/b`, with `res:1080,vcodec:h264` format preferences and `--no-playlist`.
+Available source streams determine the result. It stages the download in the OS temporary directory,
+then moves the completed file to the target, copying on a cross-volume `EXDEV` error. Temporary
+files are removed when the operation ends. Download errors retain the tool's diagnostic output.
+
+The package supplies download behavior; the CLI owns command arguments and reporting. Production
+use is described in the Hypit Skill's **Downloading a video from a link** page. The installed
+`services/yt-dlp/README.md` covers direct invocation when a source needs additional yt-dlp options.

package/packages/yt-dlp/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@hypit/yt-dlp",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  }
+}

package/packages/yt-dlp/src/download.ts

@@ -0,0 +1,104 @@
+/**
+ * Fetch a video that lives at a link rather than on disk.
+ *
+ * Most of the videos anybody wants to reconstruct are on TikTok, YouTube, Instagram or Bilibili
+ * rather than in a folder. `yt-dlp` is what turns one into a file; everything after that reads the
+ * file and never learns where it came from.
+ *
+ * The tool is a pinned Python dependency under `services/yt-dlp`, reached through `uv`, and not a
+ * binary the machine happens to carry. `yt-dlp` releases constantly because it is chasing sites that
+ * keep changing, so an unpinned copy makes the same link fetch differently on two machines. This is
+ * the same shape WhisperX and OpenCV already use for their Python programs.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { copyFile, mkdtemp, readdir, rename, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, extname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Whether this is a link to fetch rather than a path to open.
+ *
+ * Only `http` and `https`. A Windows path opens as a URL with a single-letter scheme (`c:\clip.mp4`
+ * parses with protocol `c:`), and reading that as a link would hand the whole path to `yt-dlp` and
+ * report a network failure for a file sitting on the disk.
+ */
+export function isVideoUrl(value: string): boolean {
+  try {
+    const parsed = new URL(value.trim());
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The uv project holding the pinned `yt-dlp`, found by walking up from this module rather than from
+ * the working directory, which is wherever the author happened to run the command from.
+ */
+function serviceProject(): string {
+  let directory = dirname(fileURLToPath(import.meta.url));
+  while (true) {
+    const candidate = join(directory, "services", "yt-dlp", "pyproject.toml");
+    if (existsSync(candidate)) return dirname(candidate);
+    const parent = dirname(directory);
+    if (parent === directory) {
+      throw new Error("no services/yt-dlp project above this module; the Distribution is incomplete");
+    }
+    directory = parent;
+  }
+}
+
+/**
+ * Fetch one video into exactly the file the caller named.
+ *
+ * Video and audio are asked for together and muxed: sites serve the two separately now, so the best
+ * single file resolves to a video-only stream, and a video with no audio has no transcript. H.264 at
+ * 1080 is preferred rather than required; a `height<=1080` filter would refuse a link that offers
+ * nothing under the bound. `--no-playlist` keeps a link inside a playlist from fetching the playlist.
+ * The container follows the target's extension.
+ */
+export async function downloadVideo(url: string, target: string): Promise<void> {
+  const container = extname(target).slice(1).toLowerCase();
+  if (!["mp4", "mkv", "webm", "mov"].includes(container)) {
+    throw new Error(`${target} must end in .mp4, .mkv, .webm or .mov`);
+  }
+  const work = await mkdtemp(join(tmpdir(), "hypit-fetch-"));
+  try {
+    const result = spawnSync("uv", [
+      "run", "--project", serviceProject(), "--frozen", "yt-dlp",
+      "--no-playlist", "--no-progress", "--quiet",
+      "--format", "bv*+ba/b",
+      "--merge-output-format", container,
+      "--format-sort", "res:1080,vcodec:h264",
+      "--output", join(work, "video.%(ext)s"),
+      url,
+    ], { encoding: "utf8", windowsHide: true, timeout: 900_000 });
+
+    if (result.error !== undefined && (result.error as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new Error(
+        "uv is not installed, and a link is fetched by a pinned yt-dlp that uv installs. It is the same "
+        + "tool the WhisperX and OpenCV programs need. Install it (https://docs.astral.sh/uv/), or download "
+        + "the video yourself and pass the path instead.");
+    }
+    if (result.status !== 0) {
+      throw new Error(`yt-dlp could not fetch ${url}: ${(result.stderr ?? "").trim().slice(-2000)}`);
+    }
+    const finished = (await readdir(work)).filter((name) => !name.endsWith(".part"));
+    const [file] = finished.sort();
+    if (file === undefined) throw new Error(`yt-dlp reported success for ${url} but wrote no file`);
+    const staged = join(work, file);
+    try {
+      await rename(staged, target);
+    } catch (cause) {
+      // Staging lives in the OS temp directory, which is often on a different volume from the
+      // project. A rename cannot cross volumes, so copy the bytes over instead; the staging
+      // directory is removed either way.
+      if ((cause as NodeJS.ErrnoException).code !== "EXDEV") throw cause;
+      await copyFile(staged, target);
+    }
+  } finally {
+    await rm(work, { recursive: true, force: true });
+  }
+}

package/packages/yt-dlp/src/index.ts

@@ -0,0 +1 @@
+export { downloadVideo, isVideoUrl } from "./download.js";

package/services/image-opencv/README.md

@@ -0,0 +1,33 @@
+# SVML local OpenCV runtime
+
+This is the locked Python environment used by `@hypit/provider-image-opencv-local`. It is deployment
+state, not an author-importable SVML package, a queue, a service daemon or part of Core.
+
+For an ordinary installed Distribution, select the Provider and let `hypit runtime up` create and
+reuse this environment in the machine Program Home. The commands below are only for a contributor
+or operator deliberately managing a custom interpreter:
+
+```bash
+uv python install 3.13
+uv sync --project services/image-opencv --frozen
+uv run --project services/image-opencv --frozen --no-sync python -c \
+  'import cv2, numpy; print(cv2.__version__, numpy.__version__)'
+```
+
+Then configure the Provider with the environment's interpreter:
+
+```json
+{
+  "use": "@hypit/provider-image-opencv-local",
+  "instance": "image.opencv.local",
+  "config": {
+    "pythonExecutable": "./services/image-opencv/.venv/bin/python",
+    "defaultConcurrency": 2
+  }
+}
+```
+
+The Provider starts one bounded, shell-free Python process for each admitted Need. The ordinary
+SVML Runtime Scheduler owns concurrency. The Python process reads only its explicit temporary input
+and Program files and writes one explicit output image; it has no network, Resource Store, author
+source or BuildState API.

package/services/image-opencv/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@hypit/image-opencv-runtime",
+  "version": "0.1.0",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "exports": {
+    "./pyproject.toml": "./pyproject.toml"
+  },
+  "files": [
+    "pyproject.toml",
+    "uv.lock",
+    "README.md"
+  ]
+}

package/services/image-opencv/pyproject.toml

@@ -0,0 +1,13 @@
+[project]
+name = "hypit-image-opencv-runtime"
+version = "0.1.0"
+description = "Locked Python runtime for the SVML local OpenCV image Provider"
+requires-python = ">=3.13,<3.14"
+license = { text = "Hypit Open Source License (Apache-2.0 with additional conditions); see LICENSE at the repository root" }
+dependencies = [
+  "numpy>=2.1,<3",
+  "opencv-python-headless>=4.10,<5",
+]
+
+[tool.uv]
+package = false

package/services/image-opencv/uv.lock

@@ -0,0 +1,56 @@
+version = 1
+revision = 3
+requires-python = "==3.13.*"
+
+[[package]]
+name = "numpy"
+version = "2.5.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/22/fd/89965aa4ac08c74998539fcbf24fa3540f3e15237fbeb6bcf9c908f4aade/numpy-2.5.1.tar.gz", hash = "sha256:a48a113e6afea91f5608793bafa7ef2ad481fefbda87ec5069f483de61cb9fa3", size = 20755553, upload-time = "2026-07-04T17:08:00.933Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/eb/07/ec2a3f0c91761581d4b7104a740791800025983f9a4dc4e73f91a99aeac4/numpy-2.5.1-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:0bfebd8695f9863592fe744be833a258120b14a9f39da255e8aa8fade2c0ddd1", size = 16796419, upload-time = "2026-07-04T17:06:40.37Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/ab/ddb499fc4f8780354395face5b65c7fd107bcd6e1d667a5f07d046956f6f/numpy-2.5.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:30b44a6b53a7ae63c54c089a8726e5563ed302716c5b7ccc85afade40b0e7ff6", size = 11765832, upload-time = "2026-07-04T17:06:42.768Z" },
+    { url = "https://files.pythonhosted.org/packages/88/b3/3c28c558a09fc72100c646dac6d2fce8e834c471b0edca01a29996706117/numpy-2.5.1-cp313-cp313-macosx_14_0_arm64.whl", hash = "sha256:6165343f81b56ef8f514f396989e529b61d9dc709b99421b07e9f3e698e2287d", size = 5325143, upload-time = "2026-07-04T17:06:45.466Z" },
+    { url = "https://files.pythonhosted.org/packages/5e/0e/ce19b985bb15c596f4f05954e76cccc77c845083b3b8f938a6c68e523128/numpy-2.5.1-cp313-cp313-macosx_14_0_x86_64.whl", hash = "sha256:4939237038ada79308dda3204ac6462df056b5672b2e25db1149cf873668b3e1", size = 6659749, upload-time = "2026-07-04T17:06:47.288Z" },
+    { url = "https://files.pythonhosted.org/packages/2e/20/1ee6614d64332a1bba6411f38e68cb79eec1b2459e20a623777c5c5492a2/numpy-2.5.1-cp313-cp313-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:1c6759f538fb912fc46de0a6b1758ccf7b57bc7c7ebebc23974fdac3de8db0cd", size = 15164716, upload-time = "2026-07-04T17:06:49.494Z" },
+    { url = "https://files.pythonhosted.org/packages/ed/a7/2bcd3fdbb87804755c35b729bf8709d62025c5f4cfd7d5b2415997097515/numpy-2.5.1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9726558e8db4a5bf7929a70ae50f63abda4daf0efe810e3bfbab95976f75fc1a", size = 16661440, upload-time = "2026-07-04T17:06:52.061Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/d7/a41e3310c886fe457d36e670bbf24fae411aca8a7b6ad92a32afd924077c/numpy-2.5.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:3935f3b419b244a02732676fa5317a9193cc596a4c0646db07e5b421229ac9f7", size = 16526305, upload-time = "2026-07-04T17:06:54.605Z" },
+    { url = "https://files.pythonhosted.org/packages/53/75/4333a9a707c1edd3a4e1a0c58eca52c0f31e55089fa80db02b5565b24df7/numpy-2.5.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:dc932a65ded7ce9013d120845a2514dcccb1a67bfc8deb8d37633762951904a6", size = 18423008, upload-time = "2026-07-04T17:06:57.54Z" },
+    { url = "https://files.pythonhosted.org/packages/ee/90/e314a32b1c11a2ffe818ddad3a57b50b4b6e1b6c487192eb50cdef0415d0/numpy-2.5.1-cp313-cp313-win32.whl", hash = "sha256:4b4ff1608417eb7a59da7b967bbb798cacfe071d2caf526a24281cd562072ed9", size = 6063885, upload-time = "2026-07-04T17:07:00.14Z" },
+    { url = "https://files.pythonhosted.org/packages/10/70/800b3fca480af32df9e8ea9f3d4a0c8feb4b32d7f195d174eabbda4829ad/numpy-2.5.1-cp313-cp313-win_amd64.whl", hash = "sha256:6c3fe51bc6a16453d452997053454f309e8e0ed7b42d6b361ce4ac8c32913d74", size = 12425674, upload-time = "2026-07-04T17:07:02.387Z" },
+    { url = "https://files.pythonhosted.org/packages/8b/0b/196350c122f50f6ca56846f2d71efd5e0d24b7b2e07355e019b2e2c7a11e/numpy-2.5.1-cp313-cp313-win_arm64.whl", hash = "sha256:f7feb014281029e628ba2d5a007407443b06e418b6fe451d1e2adcbc8eba0107", size = 10350256, upload-time = "2026-07-04T17:07:04.878Z" },
+]
+
+[[package]]
+name = "opencv-python-headless"
+version = "4.14.0.94"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "numpy" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/67/8a/51ff1c6287be0b6cd3070cf095875da4ff7d6eda38507e6ada5608786a78/opencv_python_headless-4.14.0.94.tar.gz", hash = "sha256:4afa2ea1214453648be88259f035712454faa9039b686de7753569ba8eec1577", size = 96405664, upload-time = "2026-07-28T19:23:48.758Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9a/56/12f9b05628cf4ab6aad54479b9124f7c1f2f92b6a4e47c071beb63d926a2/opencv_python_headless-4.14.0.94-cp37-abi3-macosx_13_0_arm64.whl", hash = "sha256:bc7db37dc234f7bb3190a158fd9dd750357246fc7d8adb23698843ef721a993b", size = 46491231, upload-time = "2026-07-29T03:52:11.902Z" },
+    { url = "https://files.pythonhosted.org/packages/23/3b/2f9c42466f62aa27e97aaf6c9d914008895ecde28013ba4beed7f541f593/opencv_python_headless-4.14.0.94-cp37-abi3-macosx_14_0_x86_64.whl", hash = "sha256:1777f43c9fa064f54b916ad70d944b4fde0a644a17e49f04a966bb24a4b5f1e1", size = 33084176, upload-time = "2026-07-28T20:05:59.902Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/91/83c51e3fe000b5dfce4f3be5c5d320e07ebab5c1742abc4e45674503f90f/opencv_python_headless-4.14.0.94-cp37-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:29714d7716dbfddf9fec20ffb878765e94ccaecd7d3ebd6750877420296e2dc5", size = 35405458, upload-time = "2026-07-28T19:19:29.997Z" },
+    { url = "https://files.pythonhosted.org/packages/de/06/14c8c5d331bc72738683a9b227966aceaa4c6d08752f33d64578aebcb6f8/opencv_python_headless-4.14.0.94-cp37-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:5e02669eac0ba67b2a22d7245af1e8ee1a2ef1185ee526a063d8f0555224bd52", size = 57534165, upload-time = "2026-07-28T19:19:52.742Z" },
+    { url = "https://files.pythonhosted.org/packages/3f/0e/0b98bd582582253f61c4506f9b465cf5a8aa7fa4f7237dd99e1b5151a159/opencv_python_headless-4.14.0.94-cp37-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:97c6e818c6f71c0cfa214e12293b1d0266d679c38f4e086de08357c8ac6ece0d", size = 38104309, upload-time = "2026-07-28T19:20:08.818Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/ce/7f538891722a4f06921419d55bac6f41729258d54442861edb2de0dbdf5e/opencv_python_headless-4.14.0.94-cp37-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:211e581f5a4670acbbe08fff36a35e9946039d2eea28b80394632d036d1be527", size = 61960165, upload-time = "2026-07-28T19:20:33.074Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/91/ded03abad74d7264fa6bc7c923d7cade6f94a9023eeb372cfad54c2d0334/opencv_python_headless-4.14.0.94-cp37-abi3-win32.whl", hash = "sha256:f70296aa7ac9d7ade0d925c43fdc006c83e20a23f30e2f40f1b82c74a7a54460", size = 33030271, upload-time = "2026-07-28T18:32:39.447Z" },
+    { url = "https://files.pythonhosted.org/packages/ad/8d/db8673846ee53cbb5de4c2b4decc11cf733e203eb7d5146297869f69bd48/opencv_python_headless-4.14.0.94-cp37-abi3-win_amd64.whl", hash = "sha256:cbed65415b8f6a9541c705afe3e64795840524d0ff3bc58f507826284a1dc64b", size = 41028030, upload-time = "2026-07-28T18:32:36.724Z" },
+]
+
+[[package]]
+name = "hypit-image-opencv-runtime"
+version = "0.1.0"
+source = { virtual = "." }
+dependencies = [
+    { name = "numpy" },
+    { name = "opencv-python-headless" },
+]
+
+[package.metadata]
+requires-dist = [
+    { name = "numpy", specifier = ">=2.1,<3" },
+    { name = "opencv-python-headless", specifier = ">=4.10,<5" },
+]

package/services/whisperx/README.md

@@ -0,0 +1,82 @@
+# SVML WhisperX Service
+
+This is the trusted, warm Python process used by `@hypit/provider-whisperx-local`. It is a Runtime
+deployment package, not an author-importable SVML module and not part of Core.
+
+The service has one narrow job:
+
+```text
+canonical 16 kHz mono PCM s16 WAV
+  -> faster-whisper ASR
+  -> language-specific WhisperX alignment
+  -> raw measured words and optional acoustic time windows
+```
+
+It does not run FFmpeg, modify the authored script, split caption cues, infer SVML Segments, cache
+Build results or create a SemanticTake. Missing WhisperX word timing stays missing; the author-side
+semantic projection combines this evidence with one explicit Script Segment later.
+
+## Install
+
+For an ordinary installed Distribution, select the local WhisperX Endpoint and run
+`hypit runtime up`. The Runtime creates this environment in the machine Program Home only when it is
+missing, and reuses it across projects and sessions. The commands below are contributor/operator
+diagnostics for a deliberately managed deployment:
+
+WhisperX 3.8.6 supports Python 3.10 through 3.13. The checked-in lock selects Python 3.13:
+
+```bash
+uv python install 3.13
+uv sync --project services/whisperx --frozen
+uv run --project services/whisperx --frozen hypit-whisperx-prepare
+uv run --project services/whisperx --frozen hypit-whisperx-check
+```
+
+The first model start may download ASR and alignment weights. Production should put the relevant
+Hugging Face cache on persistent storage. `hypit-whisperx-prepare` separately installs NLTK's
+`punkt_tab` sentence data through NLTK's own downloader. This resource is required by WhisperX
+alignment and is prepared explicitly before the warm service starts, never inside an inference request.
+
+## Run
+
+```bash
+uv run --project services/whisperx --frozen hypit-whisperx-service
+curl http://127.0.0.1:8765/health
+```
+
+Default identity:
+
+```text
+model       small
+device      cpu
+compute     int8
+batch size  8
+protocol    hypit.whisperx-service@1
+```
+
+Configuration is deployment state:
+
+| Variable | Default | Meaning |
+|---|---:|---|
+| `HYPIT_WHISPERX_PORT` | `8765` | loopback port |
+| `HYPIT_WHISPERX_MODEL` | `small` | faster-whisper model |
+| `HYPIT_WHISPERX_DEVICE` | `cpu` | `cpu` or the deployed accelerator |
+| `HYPIT_WHISPERX_COMPUTE` | `int8` on CPU | CTranslate2 compute type |
+| `HYPIT_WHISPERX_BATCH_SIZE` | `8` | bounded ASR batch size |
+| `HYPIT_WHISPERX_INPUT_ROOTS` | OS temp directory | path-separated roots the service may read |
+| `HYPIT_WHISPERX_NLTK_DATA` | user SVML cache | prepared, identity-checked NLTK data root |
+| `HYPIT_WHISPERX_MAX_REQUEST_BYTES` | `65536` | HTTP JSON bound |
+| `HYPIT_WHISPERX_MAX_AUDIO_BYTES` | `536870912` | staged canonical WAV bound |
+
+The Node Provider must configure the same model, device, compute, batch size, service version and
+WhisperX version. A mismatch fails before transcription results are accepted.
+
+## Queue and concurrency
+
+The SVML Runtime Scheduler decides how many WhisperX Needs may enter this Provider lane. One service
+process admits exactly one inference because its ASR/alignment models are shared process state. A
+second direct request receives `503 BUSY` instead of entering a hidden service queue.
+`ThreadingHTTPServer` keeps `/health` responsive while the admitted inference runs.
+
+Run multiple service processes on different devices/ports only when the Runtime registers and
+locks them as distinct Provider instances.

package/services/whisperx/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@hypit/whisperx-service-runtime",
+  "version": "0.1.0",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "exports": {
+    "./pyproject.toml": "./pyproject.toml"
+  },
+  "files": [
+    "pyproject.toml",
+    "uv.lock",
+    "src/**/*.py",
+    "README.md"
+  ]
+}

package/services/whisperx/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "hypit-whisperx-service"
+version = "0.1.0"
+description = "Warm, loopback-only WhisperX alignment service for the SVML local Provider"
+readme = "README.md"
+requires-python = ">=3.10,<3.14"
+license = { text = "Hypit Open Source License (Apache-2.0 with additional conditions); see LICENSE at the repository root" }
+dependencies = [
+  "numpy>=2.1,<3",
+  "whisperx==3.8.6",
+]
+
+[project.scripts]
+hypit-whisperx-service = "hypit_whisperx_service.__main__:main"
+hypit-whisperx-check = "hypit_whisperx_service.check:main"
+hypit-whisperx-prepare = "hypit_whisperx_service.prepare:main"
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.uv]
+package = true

package/services/whisperx/src/hypit_whisperx_service/__init__.py

@@ -0,0 +1,6 @@
+"""SVML's trusted local WhisperX process boundary."""
+
+SERVICE_VERSION = "0.1.0"
+PROTOCOL = "hypit.whisperx-service@1"
+
+__all__ = ["PROTOCOL", "SERVICE_VERSION"]

package/services/whisperx/src/hypit_whisperx_service/__main__.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import logging
+
+from .application import WhisperXApplication
+from .config import ServiceConfig
+from .engine import WhisperXEngine
+from .server import serve
+
+
+def main() -> None:
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s [%(name)s] %(message)s",
+    )
+    config = ServiceConfig.from_environment()
+    logging.getLogger("hypit.whisperx").info(
+        "loading model=%s device=%s compute=%s batch=%d",
+        config.model,
+        config.device,
+        config.compute,
+        config.batch_size,
+    )
+    engine = WhisperXEngine(config)
+    serve(WhisperXApplication(config, engine))
+
+
+if __name__ == "__main__":
+    main()