@hypit/hypit 0.0.1 → 0.1.0

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

@@ -0,0 +1,157 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+import { resolveNodePackageResource } from "@hypit/package-loader-node";
+import type {
+  ManagedProgram,
+  ManagedProgramCommand,
+  ManagedProgramState,
+} from "@hypit/runtime-kit";
+import { pythonEnvironmentCommand } from "@hypit/runtime-host-node";
+
+/**
+ * WhisperX loads multi-gigabyte weights before it can answer, so it is a warm
+ * program a developer keeps running, not a process spawned for each Need. The
+ * Provider declares how to bring it up; the Runtime Profile may override the
+ * command for an environment that installs WhisperX differently.
+ *
+ * The locked project is a package asset. Its environment lives in the Host's
+ * program home, while this read-only project remains replaceable Distribution
+ * input. A custom service command transfers process ownership to that deployment.
+ */
+export const localWhisperXManagedProject = join(
+  resolveNodePackageResource("@hypit/whisperx-service-runtime", "pyproject.toml", { from: import.meta.url }),
+  "..",
+);
+
+function run(command: ManagedProgramCommand): Promise<{ readonly ok: boolean; readonly output: string }> {
+  return new Promise((resolve) => {
+    execFile(command.command, [...command.args], {
+      cwd: command.cwd,
+      env: { ...process.env, ...command.env },
+      timeout: 60_000,
+      shell: false,
+      windowsHide: true,
+    }, (error, stdout, stderr) => {
+      resolve(error === null
+        ? { ok: true, output: stdout.trim() }
+        : { ok: false, output: (stderr.trim() || error.message).split(/\r?\n/u).at(-1) ?? "" });
+    });
+  });
+}
+
+export type LocalWhisperXProgramOptions = {
+  readonly id: string;
+  readonly hostStateRoot: string;
+  readonly baseUrl: string;
+  readonly expectedModel: string;
+  readonly expectedDevice: string;
+  readonly expectedCompute: string;
+  readonly expectedBatchSize: number;
+  readonly expectedServiceVersion: string;
+  readonly expectedWhisperXVersion: string;
+  readonly serviceCommand?: ManagedProgramCommand;
+};
+
+export function localWhisperXProgram(options: LocalWhisperXProgramOptions): ManagedProgram {
+  const baseUrl = options.baseUrl.replace(/\/+$/u, "");
+  const serviceUrl = new URL(baseUrl);
+  const expected = {
+    protocol: "hypit.whisperx-service@1",
+    serviceVersion: options.expectedServiceVersion,
+    whisperxVersion: options.expectedWhisperXVersion,
+    model: options.expectedModel,
+    device: options.expectedDevice,
+    compute: options.expectedCompute,
+    batchSize: options.expectedBatchSize,
+  };
+  const customStart = options.serviceCommand;
+  const managed = customStart === undefined;
+  if (managed && !existsSync(localWhisperXManagedProject)) {
+    throw new Error("local WhisperX has no packaged managed runtime; configure serviceCommand explicitly");
+  }
+  const stateRoot = join(
+    options.hostStateRoot,
+    "programs",
+    `whisperx-${encodeURIComponent(options.id)}-${encodeURIComponent(serviceUrl.host)}`,
+  );
+  const environment = join(stateRoot, ".venv");
+  const nltkData = join(stateRoot, "nltk_data");
+  const serviceEnvironment = {
+    HYPIT_WHISPERX_PORT: serviceUrl.port || "80",
+    HYPIT_WHISPERX_MODEL: expected.model,
+    HYPIT_WHISPERX_DEVICE: expected.device,
+    HYPIT_WHISPERX_COMPUTE: expected.compute,
+    HYPIT_WHISPERX_BATCH_SIZE: String(expected.batchSize),
+    HYPIT_WHISPERX_NLTK_DATA: nltkData,
+  };
+  const check: ManagedProgramCommand = {
+    command: pythonEnvironmentCommand(environment, "hypit-whisperx-check"),
+    args: [],
+    env: { HYPIT_WHISPERX_NLTK_DATA: nltkData },
+  };
+  const managedStart: ManagedProgramCommand = {
+    command: pythonEnvironmentCommand(environment, "hypit-whisperx-service"),
+    args: [],
+    env: serviceEnvironment,
+  };
+  const installationProbe = async (): Promise<ManagedProgramState> => {
+    const result = await run(check);
+    if (!result.ok) return { state: "down", detail: `${check.command} is not ready: ${result.output}` };
+    let report: {
+      readonly protocol?: unknown;
+      readonly serviceVersion?: unknown;
+      readonly packages?: Record<string, unknown>;
+    };
+    try {
+      report = JSON.parse(result.output) as typeof report;
+    } catch {
+      return { state: "mismatch", detail: `${check.command} returned an invalid installation report` };
+    }
+    const differs = [
+      report.protocol === expected.protocol ? undefined : `protocol is ${String(report.protocol)}`,
+      report.serviceVersion === expected.serviceVersion ? undefined : `serviceVersion is ${String(report.serviceVersion)}`,
+      report.packages?.whisperx === expected.whisperxVersion ? undefined : `whisperx is ${String(report.packages?.whisperx)}`,
+    ].filter((item): item is string => item !== undefined);
+    return differs.length === 0
+      ? { state: "ready" }
+      : { state: "mismatch", detail: differs.join("; ") };
+  };
+  return {
+    id: options.id,
+    ...(managed ? {
+      stateRoot,
+      installation: {
+        probe: installationProbe,
+        commands: [{
+          command: "uv",
+          args: ["sync", "--project", localWhisperXManagedProject, "--frozen", "--no-editable"],
+          env: { UV_PROJECT_ENVIRONMENT: environment },
+        }, {
+          command: pythonEnvironmentCommand(environment, "hypit-whisperx-prepare"),
+          args: ["--nltk-data", nltkData],
+          env: { HYPIT_WHISPERX_NLTK_DATA: nltkData },
+        }],
+      },
+    } : {}),
+    start: customStart ?? managedStart,
+    async probe(): Promise<ManagedProgramState> {
+      let health: Record<string, unknown>;
+      try {
+        const response = await fetch(`${baseUrl}/health`, { signal: AbortSignal.timeout(2000) });
+        if (!response.ok) return { state: "down", detail: `${baseUrl}/health answered ${response.status}` };
+        health = await response.json() as Record<string, unknown>;
+      } catch {
+        return { state: "down", detail: `nothing is answering at ${baseUrl}` };
+      }
+      const differs = Object.entries(expected)
+        .filter(([key, want]) => health[key] !== want)
+        .map(([key, want]) => `${key} is ${String(health[key])}, expected ${String(want)}`);
+      if (health.ok !== true) differs.push("the service reports itself unhealthy");
+      return differs.length === 0
+        ? { state: "ready" }
+        : { state: "mismatch", detail: differs.join("; ") };
+    },
+  };
+}

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

@@ -0,0 +1,191 @@
+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 } 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 { WhisperXTranscriptResponse } from "@hypit/whisperx";
+
+export const localWhisperXProviderModuleRef = {
+  name: "@hypit/provider-whisperx-local",
+  version: "1",
+} as const;
+export const localWhisperXDefaults = {
+  baseUrl: "http://127.0.0.1:8765",
+  expectedModel: "small",
+  expectedDevice: "cpu",
+  expectedBatchSize: 8,
+  expectedServiceVersion: "0.1.0",
+  expectedWhisperXVersion: "3.8.6",
+} as const;
+export type CreateLocalWhisperXProviderOptions = {
+  readonly instance?: string;
+  readonly pool?: string;
+  /** Must resolve to the same machine because the protocol passes a staged local path. */
+  readonly baseUrl?: string;
+  readonly expectedModel?: string;
+  readonly expectedDevice?: string;
+  readonly expectedCompute?: string;
+  readonly expectedBatchSize?: number;
+  readonly expectedServiceVersion?: string;
+  readonly expectedWhisperXVersion?: string;
+  readonly defaultConcurrency?: number;
+  readonly requestTimeoutMs?: number;
+  readonly maxResponseBytes?: number;
+};
+
+export type WhisperXServiceResponse = WhisperXTranscriptResponse;
+
+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;
+}
+
+export const interpretWhisperXResponse = interpretWhisperXTranscript;
+
+async function limitedJson(response: Response, maxBytes: number, subject: string): Promise<{
+  readonly value: unknown;
+}> {
+  const reader = response.body?.getReader();
+  let bytes: Uint8Array;
+  if (reader === undefined) {
+    bytes = new Uint8Array(await response.arrayBuffer());
+    assert(bytes.byteLength <= maxBytes, `${subject} exceeded the configured response limit`);
+  } else {
+    const chunks: Uint8Array[] = [];
+    let size = 0;
+    try {
+      while (true) {
+        const item = await reader.read();
+        if (item.done) break;
+        size += item.value.byteLength;
+        if (size > maxBytes) {
+          await reader.cancel();
+          throw new Error(`${subject} exceeded the configured response limit`);
+        }
+        chunks.push(item.value);
+      }
+    } finally {
+      reader.releaseLock();
+    }
+    bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+      bytes.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+  }
+  assert(response.ok, `${subject} failed with HTTP ${response.status}: ${Buffer.from(bytes).toString("utf8").slice(0, 500)}`);
+  try {
+    return { value: JSON.parse(Buffer.from(bytes).toString("utf8")) };
+  } catch {
+    throw new Error(`${subject} returned invalid JSON`);
+  }
+}
+
+function result(value: CanonicalValue): EndpointFulfillment {
+  return { value: { kind: "inline", value } };
+}
+
+export function createLocalWhisperXProvider(config: CreateLocalWhisperXProviderOptions) {
+  const baseUrl = new URL(config.baseUrl ?? localWhisperXDefaults.baseUrl);
+  assert(baseUrl.protocol === "http:" && ["127.0.0.1", "localhost", "::1", "[::1]"].includes(baseUrl.hostname),
+    "local WhisperX Provider requires a loopback HTTP service");
+  const normalizedBaseUrl = baseUrl.href.replace(/\/+$/u, "");
+  const expectedModel = config.expectedModel ?? localWhisperXDefaults.expectedModel;
+  const expectedDevice = config.expectedDevice ?? localWhisperXDefaults.expectedDevice;
+  const expectedCompute = config.expectedCompute ?? (expectedDevice === "cpu" ? "int8" : "float16");
+  const expectedBatchSize = positiveInteger(config.expectedBatchSize ?? localWhisperXDefaults.expectedBatchSize, "expectedBatchSize");
+  const expectedServiceVersion = config.expectedServiceVersion ?? localWhisperXDefaults.expectedServiceVersion;
+  const expectedWhisperXVersion = config.expectedWhisperXVersion ?? localWhisperXDefaults.expectedWhisperXVersion;
+  assert(expectedModel.trim().length > 0, "expectedModel is empty");
+  assert(expectedDevice.trim().length > 0, "expectedDevice is empty");
+  assert(expectedCompute.trim().length > 0, "expectedCompute is empty");
+  assert(expectedServiceVersion.trim().length > 0, "expectedServiceVersion is empty");
+  assert(expectedWhisperXVersion.trim().length > 0, "expectedWhisperXVersion is empty");
+  const requestTimeoutMs = positiveInteger(config.requestTimeoutMs ?? 10 * 60_000, "requestTimeoutMs");
+  const maxResponseBytes = positiveInteger(config.maxResponseBytes ?? 64 * 1024 * 1024, "maxResponseBytes");
+
+  return defineEndpointPackage({
+    module: localWhisperXProviderModuleRef,
+    facet: "alignment",
+    instance: config.instance ?? "whisperx.local",
+    pool: config.pool ?? config.instance ?? "whisperx.local",
+    pricing: { kind: "local" },
+    defaultConcurrency: config.defaultConcurrency ?? 1,
+    capabilities: [{
+      lifecycle: "immediate" as const,
+      capability: whisperXCapabilities.alignment,
+      returns: speechEvidenceTypes.alignedTranscript,
+      handler: async (context: EndpointInvocationContext) => {
+        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`);
+        assertWhisperXEvidenceWav(audio, request.sampleFrames);
+        const work = await mkdtemp(join(tmpdir(), "hypit-whisperx-local-"));
+        try {
+          const audioPath = join(work, "alignment-evidence.wav");
+          await writeFile(audioPath, audio);
+          const signal = AbortSignal.timeout(requestTimeoutMs);
+          const healthResponse = await fetch(`${normalizedBaseUrl}/health`, { signal });
+          const health = await limitedJson(healthResponse, Math.min(maxResponseBytes, 64 * 1024), "WhisperX health");
+          assert(health.value !== null && typeof health.value === "object" && !Array.isArray(health.value),
+            "WhisperX health response is invalid");
+          const healthValue = health.value as {
+            readonly ok?: unknown;
+            readonly protocol?: unknown;
+            readonly serviceVersion?: unknown;
+            readonly whisperxVersion?: unknown;
+            readonly model?: unknown;
+            readonly device?: unknown;
+            readonly compute?: unknown;
+            readonly batchSize?: unknown;
+          };
+          assert(healthValue.ok === true
+            && healthValue.protocol === "hypit.whisperx-service@1"
+            && healthValue.serviceVersion === expectedServiceVersion
+            && healthValue.whisperxVersion === expectedWhisperXVersion
+            && healthValue.model === expectedModel
+            && healthValue.device === expectedDevice
+            && healthValue.compute === expectedCompute
+            && healthValue.batchSize === expectedBatchSize,
+          "WhisperX service runtime identity differs from the configured Provider");
+          const transcriptionResponse = await fetch(`${normalizedBaseUrl}/transcribe`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+              audio_path: audioPath,
+              language: request.language,
+            }),
+            signal,
+          });
+          const raw = await limitedJson(transcriptionResponse, maxResponseBytes, "WhisperX transcription");
+          assert(raw.value !== null && typeof raw.value === "object" && !Array.isArray(raw.value),
+            "WhisperX transcription response is invalid");
+          const response = raw.value as WhisperXServiceResponse;
+          const passages = interpretWhisperXResponse(response, request.sampleFrames);
+          const evidence: AlignedTranscriptEvidence = sealAlignedTranscriptEvidence({
+            passages,
+          });
+          return result(canonicalize(evidence));
+        } finally {
+          await rm(work, { recursive: true, force: true }).catch(() => {});
+        }
+      },
+    }],
+  });
+}

package/packages/provider-xiaomi-mimo/README.md

@@ -0,0 +1,32 @@
+# `@hypit/provider-xiaomi-mimo`
+
+Immediate Runtime Endpoint for Xiaomi's official MiMo V2.5 Voice Design and Voice Clone APIs.
+
+This package owns the `chat/completions` wire shape, `api-key` credential, timeout, response bounds,
+voice-reference encoding and ResourceStore ingestion. It names `@hypit/mimo-speech@1` capabilities
+as versioned data and does not import the model package at runtime.
+
+Runtime Profile example:
+
+```json
+{
+  "endpoints": {
+    "mimo.official": {
+      "use": "@hypit/provider-xiaomi-mimo",
+      "pool": "mimo.official",
+      "config": {
+        "apiKey": { "store": "os", "key": "xiaomi-mimo.api-key" },
+        "defaultConcurrency": 2
+      }
+    }
+  }
+}
+```
+
+Voice Design sends the authored voice description. Voice Clone reads the selected audio Resource,
+checks Xiaomi's accepted MP3/WAV formats and sends it as the vendor's data-URL voice reference.
+The Provider always requests final WAV bytes.
+
+Selecting this Provider in the Runtime Profile is independent from author syntax. Its pool and
+capability claims participate in the shared Runtime capacity model; the package has no private
+scheduler.

package/packages/provider-xiaomi-mimo/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@hypit/provider-xiaomi-mimo",
+  "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/generation": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/runtime": "workspace:*",
+    "@hypit/runtime-kit": "workspace:*"
+  },
+  "devDependencies": {
+    "@hypit/driver-node": "workspace:*",
+    "@hypit/mimo-speech": "workspace:*"
+  }
+}

package/packages/provider-xiaomi-mimo/src/activation.ts

@@ -0,0 +1,57 @@
+import {
+  createRuntimeEndpointAdapterFacet,
+  runtimeConfigCredentialRef,
+  runtimeConfigExact,
+  runtimeConfigObject,
+  runtimeConfigPositiveInteger,
+  runtimeConfigString,
+} from "@hypit/runtime-kit";
+
+import { createXiaomiMimoProvider } from "./provider.js";
+
+const adapter = createRuntimeEndpointAdapterFacet({
+  use: "@hypit/provider-xiaomi-mimo",
+  activate(context) {
+    if (context.pool === undefined) throw new Error("Xiaomi MiMo Provider Pool is required");
+    const config = runtimeConfigObject(context.config, "Xiaomi MiMo");
+    runtimeConfigExact(config, [
+      "apiBaseUrl", "apiKey", "defaultConcurrency", "requestTimeoutMs",
+      "maxResponseBytes", "maxVoiceReferenceBase64Bytes",
+    ], "Xiaomi MiMo");
+    const apiBaseUrl = runtimeConfigString(config.apiBaseUrl, "Xiaomi MiMo apiBaseUrl");
+    if (apiBaseUrl !== undefined) {
+      const url = new URL(apiBaseUrl);
+      if (url.protocol !== "https:" && url.hostname !== "localhost" && url.hostname !== "127.0.0.1") {
+        throw new Error("Xiaomi MiMo apiBaseUrl must use HTTPS or loopback");
+      }
+    }
+    const apiKey = runtimeConfigCredentialRef(config.apiKey, "Xiaomi MiMo apiKey");
+    if (apiKey === undefined) throw new Error("Xiaomi MiMo apiKey CredentialRef is required");
+    const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "Xiaomi MiMo defaultConcurrency");
+    const requestTimeoutMs = runtimeConfigPositiveInteger(config.requestTimeoutMs, "Xiaomi MiMo requestTimeoutMs");
+    const maxResponseBytes = runtimeConfigPositiveInteger(config.maxResponseBytes, "Xiaomi MiMo maxResponseBytes");
+    const maxVoiceReferenceBase64Bytes = runtimeConfigPositiveInteger(
+      config.maxVoiceReferenceBase64Bytes,
+      "Xiaomi MiMo maxVoiceReferenceBase64Bytes",
+    );
+    return {
+      endpoint: createXiaomiMimoProvider({
+        instance: context.instance,
+        pool: context.pool,
+        ...(apiBaseUrl === undefined ? {} : { apiBaseUrl }),
+        apiKey,
+        ...(defaultConcurrency === undefined ? {} : { defaultConcurrency }),
+        ...(requestTimeoutMs === undefined ? {} : { requestTimeoutMs }),
+        ...(maxResponseBytes === undefined ? {} : { maxResponseBytes }),
+        ...(maxVoiceReferenceBase64Bytes === undefined ? {} : { maxVoiceReferenceBase64Bytes }),
+      }),
+    };
+  },
+});
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  hostFacets: [adapter],
+};
+
+export default hypitPackage;

package/packages/provider-xiaomi-mimo/src/index.ts

@@ -0,0 +1,5 @@
+export {
+  createXiaomiMimoProvider,
+  xiaomiMimoProviderModuleRef,
+} from "./provider.js";
+export type { CreateXiaomiMimoProviderOptions } from "./provider.js";