@hypit/hypit 0.0.1 → 0.1.0

package/packages/provider-kie/src/routes.ts

@@ -0,0 +1,150 @@
+import { artifactTypes } from "@hypit/artifact";
+import {
+  assertBackgroundRemovalRequest,
+  backgroundRemovalCapabilities,
+} from "@hypit/background-removal";
+import type { BackgroundRemovalRequest } from "@hypit/background-removal";
+import {
+  compileWireRequest,
+  generationTypes,
+  selectWireModelForRequest,
+  sealGeneratedImageSet,
+  sealGeneratedVideoSet,
+} from "@hypit/generation";
+import type { GenerationArtifactUrlResolver, GenerationRequest, GenerationWireMapping } from "@hypit/generation";
+import { canonicalize } from "@hypit/protocol";
+import type { BlobRef, CanonicalValue, CapabilityRef, StoredValue, TypeRef } from "@hypit/protocol";
+import type { EndpointRequest, EndpointSupport } from "@hypit/endpoint-kit";
+
+import { kieModelCatalog, verifyKieModelCatalog } from "./mapping.js";
+
+export type KieTaskRequest = {
+  readonly model: string;
+  readonly input: CanonicalValue;
+};
+
+export type KieRoute = {
+  readonly key: string;
+  readonly capability: CapabilityRef;
+  readonly returns: TypeRef;
+  readonly media: "image" | "video";
+  readonly maxResults: number;
+  readonly supports?: (request: EndpointRequest) => EndpointSupport;
+  /** Select the same service model before or during execution, without resolving Resource bytes. */
+  readonly selectModel: (request: EndpointRequest) => string;
+  readonly compile: (
+    constraints: CanonicalValue,
+    resolve: GenerationArtifactUrlResolver,
+  ) => Promise<KieTaskRequest>;
+  readonly packageResult: (artifacts: readonly BlobRef[]) => StoredValue;
+};
+
+function capabilityKey(ref: CapabilityRef): string {
+  return `${ref.module.name}@${ref.module.version}#${ref.name}`;
+}
+
+function scalar(request: GenerationRequest, port: string): string | number | boolean | undefined {
+  const value = request.ports[port]?.[0];
+  return typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? value : undefined;
+}
+
+/** Returns the KIE-wire limitation that rejects an otherwise valid model request. */
+function kieGenerationRejection(mapping: GenerationWireMapping, request: GenerationRequest): string | undefined {
+  if (mapping.capability.module.name === "@hypit/gpt-image" && mapping.capability.name === "gpt-image-2") {
+    const ratio = scalar(request, "aspectRatio");
+    const resolution = scalar(request, "resolution");
+    const background = scalar(request, "background");
+    const unsupportedRatios = resolution === "2K"
+      ? ["5:4", "4:5", "3:1", "1:3", "9:21"]
+      : resolution === "4K" ? ["3:1", "1:3", "9:21"] : [];
+    if (unsupportedRatios.includes(String(ratio))) {
+      return `KIE GPT Image 2 does not accept ${String(ratio)} at ${String(resolution)}`;
+    }
+    if (background !== undefined && resolution !== "1K") {
+      return `KIE GPT Image 2 accepts the background option only at 1K; omit it at ${String(resolution)}`;
+    }
+  }
+  if (mapping.capability.module.name === "@hypit/grok-imagine"
+    && (mapping.capability.name === "grok-imagine-video"
+      || mapping.capability.name === "grok-imagine-video-1.5-preview")
+    && scalar(request, "resolution") === "1080p"
+    && (request.ports.images?.length ?? 0) > 1) {
+    return `KIE ${mapping.capability.name} accepts at most one reference image at 1080p`;
+  }
+  return undefined;
+}
+
+const kieGenerationMappings: readonly (GenerationWireMapping & { readonly result: "image" | "video" })[] = kieModelCatalog.map((mapping) => {
+  if (mapping.result === "audio") {
+    throw new Error(`KIE route ${mapping.capability.name} declares unsupported audio output`);
+  }
+  return mapping as GenerationWireMapping & { readonly result: "image" | "video" };
+});
+
+const generationRoutes: readonly KieRoute[] = kieGenerationMappings.map((mapping) => ({
+  key: capabilityKey(mapping.capability),
+  capability: mapping.capability,
+  returns: mapping.result === "image" ? generationTypes.imageSet : generationTypes.videoSet,
+  media: mapping.result,
+  maxResults: mapping.result === "image" ? 16 : 8,
+  supports: (need: EndpointRequest) => {
+    const reason = kieGenerationRejection(mapping, need.constraints as unknown as GenerationRequest);
+    return reason === undefined ? { status: "supported" } : { status: "unsupported", reason };
+  },
+  selectModel: (need) => selectWireModelForRequest(
+    mapping,
+    need.constraints as unknown as GenerationRequest,
+    need.pendingInputs?.map((input) => input.input),
+  ),
+  compile: async (constraints, resolve) => {
+    const request = constraints as unknown as GenerationRequest;
+    const rejection = kieGenerationRejection(mapping, request);
+    if (rejection !== undefined) throw new Error(rejection);
+    return await compileWireRequest(mapping, request, resolve);
+  },
+  packageResult: (artifacts) => ({
+    kind: "inline",
+    value: canonicalize(mapping.result === "image"
+      ? sealGeneratedImageSet({ images: artifacts })
+      : sealGeneratedVideoSet({ videos: artifacts })),
+  }),
+}));
+
+const backgroundRemovalRoute: KieRoute = {
+  key: capabilityKey(backgroundRemovalCapabilities.remove),
+  capability: backgroundRemovalCapabilities.remove,
+  returns: artifactTypes.blob,
+  media: "image",
+  maxResults: 1,
+  selectModel: () => "recraft/remove-background",
+  compile: async (constraints, resolve) => {
+    const request = constraints as unknown as BackgroundRemovalRequest;
+    assertBackgroundRemovalRequest(request);
+    return {
+      model: "recraft/remove-background",
+      input: canonicalize({ image: await resolve(request.source) }),
+    };
+  },
+  packageResult: (artifacts) => {
+    if (artifacts.length !== 1 || artifacts[0] === undefined) {
+      throw new Error("KIE Background Removal requires exactly one image result");
+    }
+    return artifacts[0];
+  },
+};
+
+export const kieRoutes: readonly KieRoute[] = [...generationRoutes, backgroundRemovalRoute];
+const routeByCapability = new Map(kieRoutes.map((route) => [route.key, route]));
+
+export function kieRouteForCapability(capability: CapabilityRef): KieRoute | undefined {
+  return routeByCapability.get(capabilityKey(capability));
+}
+
+export function verifyKieRoutes(): void {
+  verifyKieModelCatalog();
+  if (routeByCapability.size !== kieRoutes.length) throw new Error("KIE routes repeat a capability");
+  kieRoutes.forEach((route) => {
+    if (route.key !== capabilityKey(route.capability)) throw new Error("KIE route key differs from its capability");
+    if (!Number.isSafeInteger(route.maxResults) || route.maxResults <= 0) throw new Error("KIE route result limit is invalid");
+  });
+}

package/packages/provider-media-local/README.md

@@ -0,0 +1,58 @@
+# `@hypit/provider-media-local`
+
+Trusted local ffprobe/ffmpeg implementation of `@hypit/media-pipeline`'s nine exact byte-operation
+capabilities. It is Runtime configuration and is never imported by author `.svml`.
+
+```ts
+import { createLocalMediaProvider } from "@hypit/provider-media-local";
+
+const media = createLocalMediaProvider({ instance: "media.local", defaultConcurrency: 1 });
+```
+
+An embedding adds `media` to a complete explicit Runtime assembly and grants `process:media`; the
+declarative form selects this package through the Runtime Profile.
+
+The Endpoint:
+
+- bounds subprocess duration and ffprobe JSON size;
+- invokes binaries without a shell;
+- enumerates all streams and records ffprobe implementation identity;
+- maps explicit stream indexes into ffmpeg instead of relying on `0:v:0` / `0:a:0` guesses;
+- uses the selected authority stream's presentation interval;
+- preserves source A/V offset through deterministic trim, delay, pad and crop operations;
+- emits a silent CFR visual and, when selected, an exact-length 48 kHz stereo PCM WAV;
+- transforms synchronized A/V, extracts generic reference audio and extracts exact source frames;
+- encodes one authored image frame as an ordinary finite video-only MP4 before normalization;
+- renders an explicit `AudioProgramPlan` into one exact-length 48 kHz stereo PCM `TimelineAudio`;
+- muxes exactly one verified silent visual stream and one verified program-audio stream into MP4;
+- distinguishes AAC coding-frame padding from the authoritative packet presentation span.
+
+Normalize preserves alpha: transparent input becomes VP9 / `yuva420p` WebM, while opaque input
+uses H.264 / `yuv420p` MP4. The input pixel format and WebM alpha metadata determine the choice.
+Animated WebP is also normalized through an alpha-capable output. Transparent VP8/VP9 input uses libvpx
+decoders so FFmpeg retains the alpha sidecar, including during PNG frame extraction.
+Transparent normalization requires an FFmpeg build with the `libvpx-vp9` encoder; the normal
+process error reports a missing codec if a custom deployment does not provide it.
+These are this FFmpeg implementation's intermediate encodings; Source and Track inputs continue
+to use ordinary SynchronizedMedia. Transform currently emits opaque MP4, so perform trim/retime
+before matting when the resulting clip needs transparency.
+
+The result is ordinary SynchronizedMedia. Speech Track and Media Track consume its transparent
+picture through their existing visual outputs; choosing the A-roll or B-roll role belongs to the
+Source. Local HyperFrames extracts alpha-preserving PNGs and composites them against the authored
+Canvas and lower visual layers before encoding the final MP4.
+
+The Runtime Adapter declares the selected `ffmpeg`/`ffprobe` pair as an external, non-daemon Program.
+Its shared probe checks the encoders and filters used by the execution body. Compatible custom paths
+remain valid; the package neither pins a semantic Capability to one FFmpeg version nor mutates a
+system package manager.
+
+The reusable display-materialization capabilities—inspection, normalization, transform, extraction,
+StillVideo—also opt into transient authoring execution. Speech-evidence projection,
+programme-audio rendering and final muxing remain Build-only. This is declared per capability; the
+Runtime and Studio contain no media capability allowlist.
+
+Video-backed normalization is video-authoritative so an AAC packet tail cannot extend the program
+past its final picture. Audio-only normalization is audio-authoritative. The AWS Lambda media Provider
+must return the same public contracts and timing laws; Lambda is an execution topology, not another
+author meaning.

package/packages/provider-media-local/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@hypit/provider-media-local",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "hypit": {
+    "activation": "./src/activation.ts"
+  },
+  "dependencies": {
+    "@hypit/artifact": "workspace:*",
+    "@hypit/endpoint-kit": "workspace:*",
+    "@hypit/media": "workspace:*",
+    "@hypit/media-execution": "workspace:*",
+    "@hypit/media-pipeline": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/runtime": "workspace:*",
+    "@hypit/runtime-kit": "workspace:*",
+    "@hypit/runtime-host-node": "workspace:*",
+    "@hypit/speech": "workspace:*"
+  },
+  "devDependencies": {
+    "@hypit/driver-node": "workspace:*"
+  }
+}

package/packages/provider-media-local/src/activation.ts

@@ -0,0 +1,65 @@
+import {
+  createRuntimeEndpointAdapterFacet,
+  runtimeConfigExact,
+  runtimeConfigObject,
+  runtimeConfigPositiveInteger,
+  runtimeConfigString,
+} from "@hypit/runtime-kit";
+import {
+  diagnoseRuntimeExecutable,
+  resolveRuntimeExecutable,
+} from "@hypit/runtime-host-node";
+
+import { createLocalMediaProvider } from "./provider.js";
+import { localMediaToolchainProgram } from "./program.js";
+
+const localMediaRuntimeAdapter = createRuntimeEndpointAdapterFacet({
+  use: "@hypit/provider-media-local",
+  activate(context) {
+    if (context.pool === undefined) throw new Error("local media Provider Pool is required");
+    const config = runtimeConfigObject(context.config, "local media");
+    runtimeConfigExact(config, [
+      "ffmpegPath", "ffprobePath", "defaultConcurrency", "processTimeoutMs", "maxProbeOutputBytes",
+    ], "local media");
+    const configuredFfmpeg = runtimeConfigString(config.ffmpegPath, "media ffmpegPath");
+    const configuredFfprobe = runtimeConfigString(config.ffprobePath, "media ffprobePath");
+    const ffmpegPath = resolveRuntimeExecutable(context.dataRoot, configuredFfmpeg ?? "ffmpeg");
+    const ffprobePath = resolveRuntimeExecutable(context.dataRoot, configuredFfprobe ?? "ffprobe");
+    const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "media defaultConcurrency");
+    const processTimeoutMs = runtimeConfigPositiveInteger(config.processTimeoutMs, "media processTimeoutMs");
+    const maxProbeOutputBytes = runtimeConfigPositiveInteger(config.maxProbeOutputBytes, "media maxProbeOutputBytes");
+    return {
+      endpoint: createLocalMediaProvider({
+        instance: context.instance,
+        pool: context.pool,
+        ffmpegPath,
+        ffprobePath,
+        ...(defaultConcurrency === undefined ? {} : { defaultConcurrency }),
+        ...(processTimeoutMs === undefined ? {} : { processTimeoutMs }),
+        ...(maxProbeOutputBytes === undefined ? {} : { maxProbeOutputBytes }),
+      }),
+      program: localMediaToolchainProgram({ id: context.instance, ffmpegPath, ffprobePath }),
+      diagnose: async () => [
+        ...await diagnoseRuntimeExecutable({
+          root: context.dataRoot,
+          configured: configuredFfmpeg,
+          fallback: "ffmpeg",
+          subject: "FFmpeg",
+        }),
+        ...await diagnoseRuntimeExecutable({
+          root: context.dataRoot,
+          configured: configuredFfprobe,
+          fallback: "ffprobe",
+          subject: "FFprobe",
+        }),
+      ],
+    };
+  },
+});
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  hostFacets: [localMediaRuntimeAdapter],
+};
+
+export default hypitPackage;

package/packages/provider-media-local/src/index.ts

@@ -0,0 +1,2 @@
+export { createLocalMediaProvider, localMediaProviderModuleRef } from "./provider.js";
+export type { CreateLocalMediaProviderOptions } from "./provider.js";

package/packages/provider-media-local/src/program.ts

@@ -0,0 +1,19 @@
+import { probeMediaToolchain } from "@hypit/media-execution";
+import type { ManagedProgram } from "@hypit/runtime-kit";
+
+/** A system/custom FFmpeg deployment is external: programs up probes it but never mutates a package manager. */
+export function localMediaToolchainProgram(input: {
+  readonly id: string;
+  readonly ffmpegPath: string;
+  readonly ffprobePath: string;
+}): ManagedProgram {
+  return {
+    id: input.id,
+    async probe() {
+      const state = await probeMediaToolchain({ ffmpegPath: input.ffmpegPath, ffprobePath: input.ffprobePath });
+      return state.state === "ready"
+        ? { state: "ready" as const }
+        : { state: state.state, detail: state.detail };
+    },
+  };
+}

package/packages/provider-media-local/src/provider.ts

@@ -0,0 +1,150 @@
+import { mediaTypes } from "@hypit/media";
+import { artifactTypes } from "@hypit/artifact";
+import {
+  executeExtractAudio,
+  executeExtractFrame,
+  executeInspectMedia,
+  executeMuxProgramMedia,
+  executeNormalizeMedia,
+  executeProjectSpeechEvidenceAudio,
+  executeRenderTimelineAudio,
+  executeRenderStillVideo,
+  executeTransformMedia,
+} from "@hypit/media-execution";
+import type { MediaExecutionEnvironment, MediaOperationResult } from "@hypit/media-execution";
+import { mediaPipelineCapabilities } from "@hypit/media-pipeline";
+import { isStreamingResourceStore } from "@hypit/runtime";
+import { speechTypes } from "@hypit/speech";
+import { defineEndpointPackage } from "@hypit/endpoint-kit";
+import type { EndpointFulfillment, EndpointInvocationContext } from "@hypit/endpoint-kit";
+
+export const localMediaProviderModuleRef = { name: "@hypit/provider-media-local", version: "1" } as const;
+
+export type CreateLocalMediaProviderOptions = {
+  readonly instance?: string;
+  readonly pool?: string;
+  readonly ffmpegPath?: string;
+  readonly ffprobePath?: string;
+  readonly defaultConcurrency?: number;
+  readonly processTimeoutMs?: number;
+  readonly maxProbeOutputBytes?: number;
+};
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+function positiveInteger(value: number, subject: string): number {
+  assert(Number.isSafeInteger(value) && value > 0, `${subject} must be a positive integer`);
+  return value;
+}
+
+function fulfillment(result: MediaOperationResult): EndpointFulfillment {
+  return { value: result.value };
+}
+
+/**
+ * The Build's own ResourceStore, and whatever ffmpeg this machine has. The
+ * operations themselves live in `@hypit/media-execution`, shared with the
+ * AWS Provider so one Need cannot mean two different transforms.
+ */
+export function createLocalMediaProvider(config: CreateLocalMediaProviderOptions) {
+  const ffmpegPath = config.ffmpegPath ?? "ffmpeg";
+  const ffprobePath = config.ffprobePath ?? "ffprobe";
+  const processTimeoutMs = positiveInteger(config.processTimeoutMs ?? 10 * 60_000, "processTimeoutMs");
+  const maxProbeOutputBytes = positiveInteger(config.maxProbeOutputBytes ?? 256 * 1024 * 1024,
+    "maxProbeOutputBytes");
+  const common = { ffmpegPath, ffprobePath, processTimeoutMs, maxProbeOutputBytes };
+  const environment = (context: EndpointInvocationContext): MediaExecutionEnvironment => ({
+    ...common,
+    artifacts: {
+      get: async (source) => await context.resources.get(source.resource),
+      open: async (source) => isStreamingResourceStore(context.resources)
+        ? await context.resources.open(source.resource)
+        : await context.resources.get(source.resource).then((bytes) => bytes === undefined
+          ? undefined
+          : (async function* () { yield bytes; })()),
+      put: async (bytes, mediaType) => await context.resources.put(bytes, mediaType),
+      putFile: async (path, mediaType) => isStreamingResourceStore(context.resources)
+        ? await context.resources.putStream(createReadStream(path), mediaType)
+        : await context.resources.put(await readFile(path), mediaType),
+    },
+  });
+  const operation = (
+    execute: (env: MediaExecutionEnvironment, constraints: never) => Promise<MediaOperationResult>,
+  ) => async (context: EndpointInvocationContext): Promise<EndpointFulfillment> =>
+    fulfillment(await execute(environment(context), context.need.constraints as never));
+
+  return defineEndpointPackage({
+    module: localMediaProviderModuleRef,
+    facet: "media",
+    instance: config.instance ?? "media.local",
+    pool: config.pool ?? config.instance ?? "media.local",
+    pricing: { kind: "local" },
+    defaultConcurrency: config.defaultConcurrency ?? 1,
+    capabilities: [
+      {
+        lifecycle: "immediate" as const,
+        transient: true,
+        capability: mediaPipelineCapabilities.inspect,
+        returns: mediaTypes.inspection,
+        handler: operation(executeInspectMedia),
+      },
+      {
+        lifecycle: "immediate" as const,
+        transient: true,
+        capability: mediaPipelineCapabilities.normalize,
+        returns: mediaTypes.synchronized,
+        handler: operation(executeNormalizeMedia),
+      },
+      {
+        lifecycle: "immediate" as const,
+        transient: true,
+        capability: mediaPipelineCapabilities.transform,
+        returns: artifactTypes.blob,
+        handler: operation(executeTransformMedia),
+      },
+      {
+        lifecycle: "immediate" as const,
+        transient: true,
+        capability: mediaPipelineCapabilities.extractAudio,
+        returns: artifactTypes.blob,
+        handler: operation(executeExtractAudio),
+      },
+      {
+        lifecycle: "immediate" as const,
+        transient: true,
+        capability: mediaPipelineCapabilities.extractFrame,
+        returns: artifactTypes.blob,
+        handler: operation(executeExtractFrame),
+      },
+      {
+        lifecycle: "immediate" as const,
+        transient: true,
+        capability: mediaPipelineCapabilities.renderStill,
+        returns: artifactTypes.blob,
+        handler: operation(executeRenderStillVideo),
+      },
+      {
+        lifecycle: "immediate" as const,
+        capability: mediaPipelineCapabilities.projectSpeechEvidenceAudio,
+        returns: speechTypes.evidenceAudio,
+        handler: operation(executeProjectSpeechEvidenceAudio),
+      },
+      {
+        lifecycle: "immediate" as const,
+        capability: mediaPipelineCapabilities.renderAudio,
+        returns: mediaTypes.timelineAudio,
+        handler: operation(executeRenderTimelineAudio),
+      },
+      {
+        lifecycle: "immediate" as const,
+        capability: mediaPipelineCapabilities.mux,
+        returns: mediaTypes.muxed,
+        handler: operation(executeMuxProgramMedia),
+      },
+    ],
+  });
+}
+import { createReadStream } from "node:fs";
+import { readFile } from "node:fs/promises";

package/packages/provider-whisperx-local/README.md

@@ -0,0 +1,44 @@
+# @hypit/provider-whisperx-local
+
+Trusted local Provider for the explicit `@hypit/whisperx#whisperx-alignment` capability. It talks to
+the warm Python service in `services/whisperx` through `/health` and `/transcribe`.
+
+The Provider accepts only canonical 16 kHz mono PCM s16 WAV bytes produced by the separate media
+projection Need. It validates those bytes and stages them unchanged. WhisperX is therefore never
+allowed to hide a second ffmpeg conversion or change the speech-master clock.
+
+WhisperX's wire response uses floating-point seconds. This adapter converts those boundaries once
+to integer positions in the 16 kHz evidence-audio sample domain. It preserves WhisperX acoustic
+passages but never receives or assigns authored Script Segment identities.
+
+```ts
+createLocalWhisperXProvider({
+  baseUrl: "http://127.0.0.1:8765",
+  expectedModel: "small",
+  expectedDevice: "cpu",
+  expectedCompute: "int8",
+  expectedBatchSize: 8,
+  defaultConcurrency: 1,
+});
+```
+
+The service must be on loopback because this protocol deliberately passes a local staged path. A
+future persistent remote Provider should use an Artifact URL or request payload owned by that
+Provider; it is a different deployment package but must return the same
+`AlignedTranscriptEvidence` type. Lambda is deliberately not the target for this warm model.
+
+The configured model, device, compute mode and batch size are checked through `/health` before use.
+This prevents a warm process with an incompatible inference configuration from accepting work.
+
+The Runtime installs and starts the packaged service in the machine Program Home when this Endpoint
+is selected. The environment is reused across projects and sessions. The current local package and
+service are trusted code; this is not a community-plugin sandbox.
+
+`hypit paths` reports the machine `hostState`. The managed installation lives below
+`<hostState>/programs/whisperx-<encoded Endpoint instance>-<encoded service host>/`, with Python in
+`.venv/` and the service's NLTK data in `nltk_data/`. Both identifiers use `encodeURIComponent`;
+the service host includes its port. The default service is `http://127.0.0.1:8765` and exposes
+its configuration through `/health`. Inspect an existing Profile's address and expected settings
+when locating that service. A custom `serviceCommand` supplies its own installation and start command.
+`hypit programs status` checks the Programs selected by the supplied Profile; `programs up` prepares
+and starts them. The managed installation does not require a global `whisperx` shell command.

package/packages/provider-whisperx-local/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@hypit/provider-whisperx-local",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "hypit": {
+    "activation": "./src/activation.ts"
+  },
+  "dependencies": {
+    "@hypit/endpoint-kit": "workspace:*",
+    "@hypit/package-loader-node": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/runtime-host-node": "workspace:*",
+    "@hypit/runtime-kit": "workspace:*",
+    "@hypit/speech-evidence": "workspace:*",
+    "@hypit/whisperx": "workspace:*",
+    "@hypit/whisperx-service-runtime": "workspace:*"
+  },
+  "devDependencies": {
+    "@hypit/driver-node": "workspace:*",
+    "@hypit/speech": "workspace:*"
+  }
+}

package/packages/provider-whisperx-local/src/activation.ts

@@ -0,0 +1,93 @@
+import {
+  createRuntimeEndpointAdapterFacet,
+  runtimeConfigExact,
+  runtimeConfigObject,
+  runtimeConfigPositiveInteger,
+  runtimeConfigString,
+} from "@hypit/runtime-kit";
+
+import { createLocalWhisperXProvider, localWhisperXDefaults } from "./provider.js";
+import { localWhisperXProgram } from "./program.js";
+
+const localWhisperXRuntimeAdapter = createRuntimeEndpointAdapterFacet({
+  use: "@hypit/provider-whisperx-local",
+  activate(context) {
+    if (context.pool === undefined) throw new Error("WhisperX Provider Pool is required");
+    const config = runtimeConfigObject(context.config, "local WhisperX");
+    runtimeConfigExact(config, [
+      "baseUrl", "expectedModel", "expectedDevice", "expectedCompute", "expectedBatchSize",
+      "expectedServiceVersion", "expectedWhisperXVersion",
+      "defaultConcurrency", "requestTimeoutMs", "maxResponseBytes",
+      "serviceCommand",
+    ], "local WhisperX");
+    const baseUrl = runtimeConfigString(config.baseUrl, "WhisperX baseUrl");
+    if (baseUrl !== undefined) {
+      const parsed = new URL(baseUrl);
+      if (parsed.protocol !== "http:"
+        || !["127.0.0.1", "localhost", "::1", "[::1]"].includes(parsed.hostname)) {
+        throw new Error("local WhisperX Provider requires a loopback HTTP service");
+      }
+    }
+    const expectedModel = runtimeConfigString(config.expectedModel, "WhisperX expectedModel");
+    const expectedDevice = runtimeConfigString(config.expectedDevice, "WhisperX expectedDevice");
+    const expectedCompute = runtimeConfigString(config.expectedCompute, "WhisperX expectedCompute");
+    const expectedBatchSize = runtimeConfigPositiveInteger(config.expectedBatchSize, "WhisperX expectedBatchSize");
+    const expectedServiceVersion = runtimeConfigString(config.expectedServiceVersion, "WhisperX expectedServiceVersion");
+    const expectedWhisperXVersion = runtimeConfigString(config.expectedWhisperXVersion, "WhisperX expectedWhisperXVersion");
+    const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "WhisperX defaultConcurrency");
+    const requestTimeoutMs = runtimeConfigPositiveInteger(config.requestTimeoutMs, "WhisperX requestTimeoutMs");
+    const maxResponseBytes = runtimeConfigPositiveInteger(config.maxResponseBytes, "WhisperX maxResponseBytes");
+    const serviceCommandValue = config.serviceCommand;
+    if (serviceCommandValue !== undefined
+      && (!Array.isArray(serviceCommandValue) || serviceCommandValue.length === 0
+        || serviceCommandValue.some((item) => typeof item !== "string" || item.length === 0))) {
+      throw new Error("WhisperX serviceCommand must be a non-empty array of non-empty strings");
+    }
+    const selectedBaseUrl = baseUrl ?? localWhisperXDefaults.baseUrl;
+    const selectedModel = expectedModel ?? localWhisperXDefaults.expectedModel;
+    const selectedDevice = expectedDevice ?? localWhisperXDefaults.expectedDevice;
+    const selectedCompute = expectedCompute ?? (selectedDevice === "cpu" ? "int8" : "float16");
+    const selectedBatchSize = expectedBatchSize ?? localWhisperXDefaults.expectedBatchSize;
+    const selectedServiceVersion = expectedServiceVersion ?? localWhisperXDefaults.expectedServiceVersion;
+    const selectedWhisperXVersion = expectedWhisperXVersion ?? localWhisperXDefaults.expectedWhisperXVersion;
+    const serviceCommand = serviceCommandValue === undefined ? undefined : {
+      command: serviceCommandValue[0] as string,
+      args: (serviceCommandValue as string[]).slice(1),
+    };
+    return {
+      endpoint: createLocalWhisperXProvider({
+        instance: context.instance,
+        pool: context.pool,
+        baseUrl: selectedBaseUrl,
+        expectedModel: selectedModel,
+        expectedDevice: selectedDevice,
+        expectedCompute: selectedCompute,
+        expectedBatchSize: selectedBatchSize,
+        expectedServiceVersion: selectedServiceVersion,
+        expectedWhisperXVersion: selectedWhisperXVersion,
+        ...(defaultConcurrency === undefined ? {} : { defaultConcurrency }),
+        ...(requestTimeoutMs === undefined ? {} : { requestTimeoutMs }),
+        ...(maxResponseBytes === undefined ? {} : { maxResponseBytes }),
+      }),
+      program: localWhisperXProgram({
+        id: context.instance,
+        hostStateRoot: context.hostStateRoot,
+        baseUrl: selectedBaseUrl,
+        expectedModel: selectedModel,
+        expectedDevice: selectedDevice,
+        expectedCompute: selectedCompute,
+        expectedBatchSize: selectedBatchSize,
+        expectedServiceVersion: selectedServiceVersion,
+        expectedWhisperXVersion: selectedWhisperXVersion,
+        ...(serviceCommand === undefined ? {} : { serviceCommand }),
+      }),
+    };
+  },
+});
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  hostFacets: [localWhisperXRuntimeAdapter],
+};
+
+export default hypitPackage;

package/packages/provider-whisperx-local/src/index.ts

@@ -0,0 +1,5 @@
+export { createLocalWhisperXProvider, interpretWhisperXResponse, localWhisperXProviderModuleRef } from "./provider.js";
+export type {
+  CreateLocalWhisperXProviderOptions,
+  WhisperXServiceResponse,
+} from "./provider.js";