@hypit/hypit 0.2.3 → 0.2.5

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

@@ -0,0 +1,154 @@
+import {
+  compileWireRequest,
+  selectWireModelForRequest,
+  generationTypes,
+  sealGeneratedImageSet,
+  sealGeneratedVideoSet,
+} from "@hypit/generation";
+import type { GenerationArtifactUrlResolver, GenerationRequest, GenerationWireMapping } from "@hypit/generation";
+import { canonicalize } from "@hypit/protocol";
+import type { BlobRef, CapabilityRef, CanonicalValue, StoredValue, TypeRef } from "@hypit/protocol";
+import type { EndpointRequest, EndpointSupport } from "@hypit/endpoint-kit";
+import { hiApiMappings } from "./mapping.js";
+
+/** Documented byte limits for inline media on one HiAPI model; an absent kind carries no documented cap. */
+export type HiApiMediaLimits = {
+  readonly image?: number;
+  readonly audio?: number;
+  /** Documented cap on the combined size of all reference images. */
+  readonly imagesTotal?: number;
+};
+
+const MB = 1_000_000;
+
+/** Per-file sizes HiAPI's model pages state for images and audio; videos travel by public URL. */
+const hiApiMediaLimits: Readonly<Record<string, HiApiMediaLimits>> = {
+  "seedance-2.0-mini": { image: 30 * MB, audio: 15 * MB },
+  "seedance-2.5/image-to-video": { image: 30 * MB, audio: 15 * MB, imagesTotal: 120 * MB },
+  "seedance-2.5/reference-to-video": { image: 30 * MB, audio: 15 * MB, imagesTotal: 120 * MB },
+  "seedream-5.0-lite/image-to-image": { image: 10 * MB },
+  "Nano-Banana-Pro": { image: 30 * MB },
+  "grok-imagine/image-to-video": { image: 10 * MB },
+  "grok-imagine-1.5/image-to-video": { image: 20 * MB },
+};
+
+export type HiApiPreparedRequest = {
+  readonly model: string;
+  readonly mediaLimits: HiApiMediaLimits;
+  readonly compile: (resolve: GenerationArtifactUrlResolver) => Promise<Record<string, unknown>>;
+};
+
+export type HiApiRoute = GenerationWireMapping & {
+  readonly key: string;
+  readonly returns: TypeRef;
+  readonly supports: (request: EndpointRequest) => EndpointSupport;
+  readonly prepare: (constraints: CanonicalValue) => HiApiPreparedRequest;
+  readonly packageResult: (artifacts: readonly BlobRef[]) => StoredValue;
+};
+
+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;
+}
+function count(request: GenerationRequest, port: string): number {
+  return request.ports[port]?.length ?? 0;
+}
+
+const SEEDREAM_RESOLUTION: Readonly<Record<string, string>> = { basic: "2K", ultra: "4K" };
+const GPT_IMAGE_UNAVAILABLE: Readonly<Record<string, readonly string[]>> = {
+  "2K": ["5:4", "4:5", "3:1", "1:3", "9:21"],
+  "4K": ["1:1", "3:1", "1:3", "9:21"],
+};
+
+/** HiAPI's documented input ranges for each mapped model, checked before any reference is resolved. */
+function rejection(mapping: GenerationWireMapping, request: GenerationRequest): string | undefined {
+  const { name } = mapping.capability;
+  const ratio = scalar(request, "aspectRatio");
+  const resolution = scalar(request, "resolution");
+  let model: string;
+  try { model = selectWireModelForRequest(mapping, request); } catch (error) { return error instanceof Error ? error.message : String(error); }
+  if (name === "seedance-2-mini" && scalar(request, "webSearch") === true) {
+    return "HiAPI seedance-2.0-mini has no web_search field";
+  }
+  if (name === "seedance-2.5") {
+    if (model === "seedance-2.5/image-to-video" && ratio !== "adaptive") {
+      return `HiAPI ${model} takes only aspect-ratio adaptive, not ${String(ratio)}`;
+    }
+    if (model !== "seedance-2.5/reference-to-video" && resolution === "480p") {
+      return `HiAPI ${model} renders 720p or 1080p, not 480p`;
+    }
+  }
+  if (name === "seedream-5-lite" && SEEDREAM_RESOLUTION[String(scalar(request, "quality"))] === undefined) {
+    return `HiAPI Seedream 5.0 lite renders 2K (basic) or 4K (ultra), not quality ${String(scalar(request, "quality"))}`;
+  }
+  if (name === "minimax-h3") {
+    if (resolution !== undefined && resolution !== "2K") return `HiAPI minimax-h3 renders 2K only, not ${String(resolution)}`;
+    if (count(request, "referenceImage") > 5) return "HiAPI minimax-h3 accepts up to five reference images";
+  }
+  if (name === "gpt-image-2") {
+    if (count(request, "images") > 6) return "HiAPI gpt-image-2/image-to-image accepts up to six reference images";
+    if (scalar(request, "background") !== undefined && resolution !== "1K") return `HiAPI GPT Image 2 accepts background only at 1K; omit it at ${String(resolution)}`;
+    if (ratio === "auto" && resolution !== "1K") return "HiAPI GPT Image 2 renders aspect-ratio auto only at 1K";
+    if (GPT_IMAGE_UNAVAILABLE[String(resolution)]?.includes(String(ratio))) return `HiAPI GPT Image 2 does not render ${String(ratio)} at ${String(resolution)}`;
+  }
+  if (mapping.capability.module.name === "@hypit/grok-imagine") {
+    if (resolution === "1080p") return `HiAPI ${model} renders 480p or 720p, not 1080p`;
+    if (name === "grok-imagine-video-1.5-preview" && count(request, "images") !== 1) {
+      return "HiAPI grok-imagine-1.5/image-to-video animates exactly one image";
+    }
+  }
+  return undefined;
+}
+
+/** Fields the model package requires that HiAPI names differently or does not take. */
+function normalize(mapping: GenerationWireMapping, input: Record<string, unknown>): Record<string, unknown> {
+  const { name } = mapping.capability;
+  if (name === "seedance-2-mini" && input.web_search === false) delete input.web_search;
+  if (name === "seedream-5-lite") {
+    input.resolution = SEEDREAM_RESOLUTION[String(input.quality)];
+    delete input.quality;
+    delete input.output_format;
+    delete input.nsfw_check;
+  }
+  return input;
+}
+
+function capabilityKey(capability: CapabilityRef): string {
+  return `${capability.module.name}@${capability.module.version}#${capability.name}`;
+}
+
+export const hiApiRoutes: readonly HiApiRoute[] = hiApiMappings.map((mapping) => ({
+  ...mapping,
+  key: capabilityKey(mapping.capability),
+  returns: mapping.result === "image" ? generationTypes.imageSet : generationTypes.videoSet,
+  supports: (request) => {
+    const reason = rejection(mapping, request.constraints as unknown as GenerationRequest);
+    return reason === undefined ? { status: "supported" } : { status: "unsupported", reason };
+  },
+  prepare: (constraints) => {
+    const request = constraints as unknown as GenerationRequest;
+    const reason = rejection(mapping, request);
+    if (reason !== undefined) throw new Error(reason);
+    const model = selectWireModelForRequest(mapping, request);
+    return {
+      model,
+      mediaLimits: hiApiMediaLimits[model] ?? {},
+      compile: async (resolve) => ({
+        model,
+        input: normalize(mapping, (await compileWireRequest(mapping, request, resolve)).input as Record<string, unknown>),
+      }),
+    };
+  },
+  packageResult: (artifacts) => ({
+    kind: "inline",
+    value: canonicalize(mapping.result === "image"
+      ? sealGeneratedImageSet({ images: artifacts })
+      : sealGeneratedVideoSet({ videos: artifacts })),
+  }),
+}));
+
+const byCapability = new Map(hiApiRoutes.map((route) => [route.key, route]));
+
+export function hiApiRouteForCapability(capability: CapabilityRef): HiApiRoute | undefined {
+  return byCapability.get(capabilityKey(capability));
+}

package/packages/provider-monid/README.md

@@ -0,0 +1,72 @@
+# `@hypit/provider-monid`
+
+Hypit Runtime Provider for a [Monid](https://monid.ai) workspace. It runs Monid's generation
+endpoints through `POST /v1/run`, polls `GET /v1/runs/{runId}` until the run is terminal, downloads
+the returned video and stores it in the current Build.
+
+| Capability | Monid endpoint |
+| --- | --- |
+| `@hypit/seedance@1#seedance-2` | `bytedance` `/v1/video/seedance-2.0` |
+| `@hypit/seedance@1#seedance-2-fast` | `bytedance` `/v1/video/seedance-2.0-fast` |
+| `@hypit/seedance@1#seedance-2-mini` | `bytedance` `/v1/video/seedance-2.0-mini` |
+| `@hypit/seedance@1#seedance-2.5` | `bytedance` `/v1/video/seedance-2.5` |
+| `@hypit/minimax-h3@1#minimax-h3` | `minimax` `/v1/video/minimax-h3` |
+
+Monid's catalogue lists further generation endpoints, including the H3 Fast, Max and Max Turbo
+variants and Hailuo 2.3; their models are not the ones the Distribution describes. Input schemas
+are published through the authenticated `inspect` operation, which is where the request bodies
+above come from.
+
+Every mapped endpoint relays a BytePlus ModelArk request: one `content` array holding the prompt
+and each media input as a typed item with its `role` (`first_frame`, `last_frame`,
+`reference_image`, `reference_video`, `reference_audio`), then `resolution`, `ratio` and
+`duration`.
+
+The Seedance endpoints add `generate_audio`. Monid documents no web search field for them, so
+`web-search="true"` is unsupported, and Seedance 2.5 frame mode (`first-frame` present) requires
+`aspect-ratio="adaptive"`. Seedance visual references may carry `person-reference`; the Provider
+accepts the declaration and transmits nothing for it, since the endpoint has no field for it.
+Seedance rejects reference images and videos that contain a real human face; Monid offers no way to
+register authorized portrait material, so such a request fails with the upstream moderation error.
+
+MiniMax H3 names its model in the body and takes neither of those two fields. The endpoint requires
+a resolution, so a request that states none is sent at `2K`, the resolution the HypiHub Provider
+also selects. It also requires a ratio that is not `adaptive` for text-to-video, while frame mode
+resolves the framing from the uploaded image and reference-to-video defaults to adaptive: a
+text-to-video request carrying no `aspect-ratio` is reported unsupported before any reference is
+resolved, and the other two modes are sent as `adaptive`. H3 returns its video at `content.url`
+rather than the ModelArk `video_url`.
+
+Reference media are uploaded through the workspace file system Monid provides for this purpose
+(`sfs`): `/put` signs an upload for `hypit/<resource>.<ext>`, the bytes are `PUT` to that URL, and
+`/cat` mints a one-day download URL that the generation endpoint fetches. Uploaded files stay in the
+workspace until removed with `/rm`. Embedded callers may replace this transport with
+`publicAssetUrl`.
+
+A run ends with Monid's own status (`COMPLETED`, `FAILED`, `BLOCKED`, `STOPPED`, `TIMED_OUT`) and,
+when completed, the provider's HTTP status in `providerResponse`. A completed run whose provider
+answered 4xx or 5xx fails with that status and the provider's error message; a `BLOCKED` run keeps
+Monid's `reason`. Signed URLs in messages are redacted.
+
+Runtime Profile example:
+
+```json
+{
+  "endpoints": {
+    "monid.default": {
+      "use": "@hypit/provider-monid",
+      "pool": "monid.default",
+      "config": {
+        "apiKey": { "store": "platform", "key": "monid.api-key" },
+        "defaultConcurrency": 3,
+        "pollIntervalMs": 10000
+      }
+    }
+  }
+}
+```
+
+`baseUrl` defaults to `https://api.monid.ai`. Store the API key with
+`hypit auth login monid.default --runtime hypit.runtime.json`. Optional `requestTimeoutMs`,
+`operationTimeoutMs` and `actionLimits` bound single HTTP calls, the whole remote run and action
+concurrency; file-system runs poll at most every five seconds within `requestTimeoutMs`.

package/packages/provider-monid/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@hypit/provider-monid",
+  "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/minimax-h3": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/runtime": "workspace:*",
+    "@hypit/runtime-kit": "workspace:*"
+  },
+  "devDependencies": {
+    "@hypit/seedance": "workspace:*"
+  }
+}

package/packages/provider-monid/src/activation.ts

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

package/packages/provider-monid/src/errors.ts

@@ -0,0 +1,55 @@
+/** Monid's `{ code, message }` error envelope and run outcome fields, kept at the service boundary. */
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown> : undefined;
+}
+function text(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+// Responses may mention a signed asset URL. Keep the reason, not its access capability.
+export function safeMonidReason(value: string): string {
+  return value.replace(/https?:\/\/\S+/giu, "[redacted-url]");
+}
+
+export class MonidServiceError extends Error {
+  constructor(readonly code: string, message: string) { super(message); }
+}
+
+export class MonidHttpError extends MonidServiceError {
+  constructor(readonly status: number, response: { readonly headers: Headers }, bodyText: string,
+    request: { readonly method: string; readonly path: string }) {
+    let body: Record<string, unknown> | undefined;
+    try { body = record(JSON.parse(bodyText)); } catch { /* Non-JSON gateway failures still have HTTP evidence. */ }
+    const reason = text(body?.message) ?? (body === undefined ? text(bodyText.slice(0, 2000)) : undefined);
+    const requestId = text(response.headers.get("x-request-id"));
+    const facts = [
+      `Monid HTTP ${status}`, `${request.method} ${request.path}`,
+      ...(requestId === undefined ? [] : [`request=${requestId}`]),
+    ];
+    super("MONID_HTTP_ERROR", `${facts.join("; ")}${reason === undefined ? "" : `: ${safeMonidReason(reason)}`}`);
+  }
+}
+
+export const monidTerminalStatuses = ["COMPLETED", "FAILED", "BLOCKED", "STOPPED", "TIMED_OUT"] as const;
+
+/**
+ * A run that ended without provider output: a non-COMPLETED terminal status, or COMPLETED with a
+ * provider HTTP error. `undefined` while the run is pending or when the provider answered 2xx.
+ */
+export function monidRunFailure(run: Record<string, unknown>, id: string): MonidServiceError | undefined {
+  const status = String(run.status);
+  if (status !== "COMPLETED") {
+    if (!monidTerminalStatuses.includes(status as typeof monidTerminalStatuses[number])) return undefined;
+    const reason = text(run.reason);
+    return new MonidServiceError(`MONID_RUN_${status}`,
+      `Monid run ${id} ${status}${reason === undefined ? "" : `: ${safeMonidReason(reason)}`}`);
+  }
+  const provider = record(run.providerResponse);
+  const httpStatus = typeof provider?.httpStatus === "number" ? provider.httpStatus : 200;
+  if (httpStatus < 400) return undefined;
+  const error = record(provider?.error);
+  const detail = text(error?.message) ?? text(record(error?.error)?.message) ?? text(provider?.error);
+  return new MonidServiceError("MONID_PROVIDER_ERROR",
+    `Monid run ${id} completed with provider HTTP ${httpStatus}${detail === undefined ? "" : `: ${safeMonidReason(detail)}`}`);
+}

package/packages/provider-monid/src/index.ts

@@ -0,0 +1,2 @@
+export { createMonidProvider, monidProviderModuleRef } from "./provider.js";
+export type { CreateMonidProviderOptions } from "./provider.js";

package/packages/provider-monid/src/mapping.ts

@@ -0,0 +1,66 @@
+import type { ModuleRef } from "@hypit/protocol";
+import type { GenerationWireMapping } from "@hypit/generation";
+
+const SEEDANCE: ModuleRef = { name: "@hypit/seedance", version: "1" };
+const MINIMAX_H3: ModuleRef = { name: "@hypit/minimax-h3", version: "1" };
+
+/**
+ * One mapping plus the Monid provider that relays the endpoint. Monid addresses an endpoint by
+ * provider and path, so the provider travels with the mapping rather than being assumed.
+ */
+export type MonidMapping = GenerationWireMapping & { readonly service: string };
+
+/**
+ * Monid `bytedance` endpoints and the fields their ModelArk request body takes. Media fields name
+ * the `role` of a `content` item; routes.ts folds them into that array. `personReference` is
+ * accepted on visual references and not transmitted: the endpoint has no field for it.
+ */
+const seedance = (name: string, endpoint: string): MonidMapping => ({
+  service: "bytedance",
+  capability: { module: SEEDANCE, name }, result: "video", routes: [{ model: endpoint }],
+  fields: {
+    prompt: { as: "value", field: "text" },
+    referenceImage: { as: "urlArray", field: "reference_image", resourceFields: ["personReference"] },
+    referenceVideo: { as: "urlArray", field: "reference_video", resourceFields: ["personReference"] },
+    referenceAudio: { as: "urlArray", field: "reference_audio" },
+    firstFrame: { as: "url", field: "first_frame", resourceFields: ["personReference"] },
+    lastFrame: { as: "url", field: "last_frame", resourceFields: ["personReference"] },
+    resolution: { as: "value", field: "resolution" },
+    aspectRatio: { as: "value", field: "ratio" },
+    duration: { as: "value", field: "duration" },
+    generateAudio: { as: "value", field: "generate_audio" },
+    webSearch: { as: "value", field: "web_search" },
+  },
+});
+
+/**
+ * Monid's `minimax` MiniMax-H3 endpoint. It takes the same role-tagged `content` array as the
+ * ModelArk endpoints above, names the model in the body, and carries neither a generated-audio nor
+ * a web-search field. `resolution` is required by the endpoint while the model's port is optional,
+ * so an unstated resolution is sent as the 2K the HypiHub Provider also selects.
+ */
+const minimaxH3: MonidMapping = {
+  service: "minimax",
+  capability: { module: MINIMAX_H3, name: "minimax-h3" }, result: "video",
+  routes: [{ model: "/v1/video/minimax-h3" }],
+  constants: { model: "MiniMax-H3" },
+  fields: {
+    prompt: { as: "value", field: "text" },
+    referenceImage: { as: "urlArray", field: "reference_image" },
+    referenceVideo: { as: "urlArray", field: "reference_video" },
+    referenceAudio: { as: "urlArray", field: "reference_audio" },
+    firstFrame: { as: "url", field: "first_frame" },
+    lastFrame: { as: "url", field: "last_frame" },
+    resolution: { as: "value", field: "resolution", whenAbsent: "2K" },
+    aspectRatio: { as: "value", field: "ratio" },
+    duration: { as: "value", field: "duration" },
+  },
+};
+
+export const monidMappings: readonly MonidMapping[] = [
+  seedance("seedance-2", "/v1/video/seedance-2.0"),
+  seedance("seedance-2-fast", "/v1/video/seedance-2.0-fast"),
+  seedance("seedance-2-mini", "/v1/video/seedance-2.0-mini"),
+  seedance("seedance-2.5", "/v1/video/seedance-2.5"),
+  minimaxH3,
+];