Skip to content

armgit / hypit

Public Imported from GitHub
0

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

11.3 KB
Raw Blame
import { canonicalize } from "@hypit/hypit/protocol";
import type { BlobRef, CanonicalValue, CapabilityRef } from "@hypit/hypit/protocol";

import { isMediaPort } from "./ports.js";
import type { GenerationMediaValue, GenerationPortTable } from "./ports.js";
import { presentPorts } from "./request.js";
import type { GenerationRequest } from "./request.js";

/** Per-reference fields consumed by the service's resource transport rather than its generation body. */
export type GenerationArtifactUrlResolver = (
  artifact: BlobRef,
  fields?: Readonly<Record<string, string | number | boolean>>,
) => Promise<string>;

/**
 * How one service names the fields of one model's declared input ports.
 *
 * A mapping is data, not code, and it references its Capability by name. A
 * Provider package therefore never imports a model package: the model owns what
 * it eats, the service owns what it calls that on the wire.
 */
export type GenerationFieldMapping =
  /** One scalar written as-is. */
  | { readonly as: "value"; readonly field: string; readonly whenAbsent?: CanonicalValue }
  /** One scalar coerced to its string form, for services that type it loosely. */
  | { readonly as: "string"; readonly field: string; readonly whenAbsent?: CanonicalValue }
  /** Several scalars written as one array. */
  | { readonly as: "valueArray"; readonly field: string; readonly whenAbsent?: CanonicalValue }
  /** One media item written as a resolved URL. */
  | { readonly as: "url"; readonly field: string; readonly resourceFields?: readonly string[]; readonly whenAbsent?: CanonicalValue }
  /** Several media items written as one array of resolved URLs. */
  | { readonly as: "urlArray"; readonly field: string; readonly resourceFields?: readonly string[]; readonly whenAbsent?: CanonicalValue }
  /** Media items written as objects carrying the resolved URL and their item fields. */
  | {
      readonly as: "itemObject";
      readonly field: string;
      readonly urlKey: string;
      readonly resourceFields?: readonly string[];
      readonly fieldKeys: Readonly<Record<string, string>>;
      readonly whenAbsent?: CanonicalValue;
    };

/** Selects the service-side model identifier. The first matching route wins. */
export type GenerationWireRoute = {
  readonly model: string;
  readonly whenPresent?: readonly string[];
};

export type GenerationWireMapping = {
  /**
   * The exact Capability implemented, named as data. Binding the module version
   * here keeps a port change visible: a mapping written for one model version
   * cannot silently serve another.
   */
  readonly capability: CapabilityRef;
  readonly result: "audio" | "image" | "video";
  readonly routes: readonly GenerationWireRoute[];
  readonly fields: Readonly<Record<string, GenerationFieldMapping>>;
  readonly constants?: Readonly<Record<string, CanonicalValue>>;
};

export type GenerationWireRequest = {
  readonly model: string;
  readonly input: CanonicalValue;
};

function assert(condition: unknown, message: string): asserts condition {
  if (!condition) throw new Error(message);
}

export function selectWireModel(mapping: GenerationWireMapping, present: ReadonlySet<string>): string {
  for (const route of mapping.routes) {
    if (route.whenPresent === undefined || route.whenPresent.every((name) => present.has(name))) {
      return route.model;
    }
  }
  throw new Error(`${mapping.capability.name} has no route for ports ${[...present].sort().join(", ")}`);
}

/**
 * Select one service model from the authored request shape.
 *
 * During planning, `pendingPorts` names graph inputs the model package has
 * already attached even though their Resource bytes do not exist yet. They are
 * ordinary model port names, not graph traversal instructions.
 */
export function selectWireModelForRequest(
  mapping: GenerationWireMapping,
  request: GenerationRequest,
  pendingPorts: readonly string[] = [],
): string {
  const unsupported = unsupportedRequestField(mapping, request);
  assert(unsupported === undefined,
    `${mapping.capability.name} request contains ${unsupported} this Provider cannot map`);
  const present = new Set(presentPorts(request));
  for (const port of pendingPorts) {
    assert(mapping.fields[port] !== undefined,
      `${mapping.capability.name} request contains future port ${port} this Provider cannot map`);
    present.add(port);
  }
  return selectWireModel(mapping, present);
}

function resourceFields(item: GenerationMediaValue, names: readonly string[] = []) {
  return Object.fromEntries(names.filter((name) => item.fields?.[name] !== undefined)
    .map((name) => [name, item.fields![name]!]));
}

/**
 * Compile one port-shaped request into one service payload. The engine needs
 * only the mapping and the request, never the model package.
 */
export async function compileWireRequest(
  mapping: GenerationWireMapping,
  request: GenerationRequest,
  resolve: GenerationArtifactUrlResolver,
): Promise<GenerationWireRequest> {
  const model = selectWireModelForRequest(mapping, request);
  const input: Record<string, CanonicalValue> = { ...(mapping.constants ?? {}) };

  for (const [port, field] of Object.entries(mapping.fields)) {
    const supplied = request.ports[port];
    if (supplied === undefined) {
      if (field.whenAbsent !== undefined) input[field.field] = field.whenAbsent;
      continue;
    }
    if (field.as === "value") {
      input[field.field] = supplied[0] as CanonicalValue;
    } else if (field.as === "string") {
      input[field.field] = String(supplied[0]);
    } else if (field.as === "valueArray") {
      input[field.field] = supplied as readonly CanonicalValue[];
    } else if (field.as === "url") {
      const item = supplied[0] as GenerationMediaValue;
      input[field.field] = await resolve(item.artifact, resourceFields(item, field.resourceFields));
    } else if (field.as === "urlArray") {
      input[field.field] = await Promise.all((supplied as readonly GenerationMediaValue[])
        .map((item) => resolve(item.artifact, resourceFields(item, field.resourceFields))));
    } else {
      const media = supplied as readonly GenerationMediaValue[];
      input[field.field] = await Promise.all(media.map(async (item) => ({
        [field.urlKey]: await resolve(item.artifact, resourceFields(item, field.resourceFields)),
        ...Object.fromEntries(Object.entries(field.fieldKeys)
          .filter(([source]) => item.fields?.[source] !== undefined)
          .map(([source, target]) => [target, item.fields![source] as CanonicalValue])),
      })));
    }
  }

  return { model, input: canonicalize(input) };
}

/** Describe only a supplied value the mapping cannot carry; no model table or saved verdict. */
function unsupportedRequestField(mapping: GenerationWireMapping, value: unknown): string | undefined {
  const request = value as GenerationRequest | undefined;
  if (request === undefined || request === null || request.ports === null || typeof request.ports !== "object") {
    return "invalid ports";
  }
  for (const [port, supplied] of Object.entries(request.ports)) {
    const field = mapping.fields[port];
    if (field === undefined) return `port ${port}`;
    if (field.as !== "url" && field.as !== "urlArray" && field.as !== "itemObject") continue;
    for (const item of supplied as readonly GenerationMediaValue[]) {
      for (const name of Object.keys(item.fields ?? {})) {
        if (!field.resourceFields?.includes(name)
          && !(field.as === "itemObject" && Object.hasOwn(field.fieldKeys, name))) {
          return `field ${port}.${name}`;
        }
      }
    }
  }
  return undefined;
}

/** Optional fields may be omitted by authors, but supplied fields must reach the service. */
export function mappingSupportsRequest(mapping: GenerationWireMapping, value: unknown): boolean {
  return unsupportedRequestField(mapping, value) === undefined;
}

/**
 * Check structural port coverage and required item fields against the model declaration.
 *
 * A service may omit optional item capabilities. mappingSupportsRequest and final compilation
 * additionally refuse requests that actually supply such an unmapped field.
 */
export function assertMappingCoversPorts(
  table: GenerationPortTable,
  mapping: GenerationWireMapping,
): void {
  assert(mapping.capability.name === table.model,
    `mapping names Capability ${mapping.capability.name} but the port table declares ${table.model}`);
  assert(mapping.result === table.result,
    `${table.model} mapping result ${mapping.result} differs from the port table`);

  const declared = new Map(table.ports.map((port) => [port.name, port]));
  Object.keys(mapping.fields).forEach((name) => assert(declared.has(name),
    `${table.model} mapping names undeclared port ${name}`));

  for (const port of table.ports) {
    const field = mapping.fields[port.name];
    assert(field !== undefined, `${table.model} mapping does not cover port ${port.name}`);
    const subject = `${table.model} mapping for port ${port.name}`;
    if (isMediaPort(port)) {
      const media = port.value;
      const itemFields = media.itemFields ?? [];
      assert(itemFields.length > 0 || media.accepts.length === 1,
        `${subject} accepts ${media.accepts.join(", ")}; declare one port per media role so each maps to one wire field`);
      assert(field.as === "url" || field.as === "urlArray" || field.as === "itemObject",
        `${subject} must resolve media to a URL`);
      if (field.as === "url") {
        assert(port.maxItems === 1, `${subject} uses url but the port accepts up to ${port.maxItems} items`);
      }
      const mappedFields = [
        ...(field.resourceFields ?? []),
        ...(field.as === "itemObject" ? Object.keys(field.fieldKeys) : []),
      ];
      for (const item of itemFields) {
        if (item.optional !== true) assert(mappedFields.includes(item.name),
          `${subject} does not map required item field ${item.name}`);
      }
      for (const name of mappedFields) assert(itemFields.some((item) => item.name === name),
        `${subject} maps unknown item field ${name}`);
      continue;
    }
    if (port.maxItems > 1) {
      assert(field.as === "valueArray", `${subject} must use valueArray because the port accepts several values`);
      continue;
    }
    // A single-value port may still be written as a wire array when the service types it that way.
    assert(field.as === "value" || field.as === "string" || field.as === "valueArray",
      `${subject} must write a scalar or a single-element array`);
  }

  const emitted = Object.values(mapping.fields).map((field) => field.field);
  assert(new Set(emitted).size === emitted.length,
    `${table.model} mapping writes one wire field from two ports`);
  Object.keys(mapping.constants ?? {}).forEach((name) => assert(!emitted.includes(name),
    `${table.model} mapping constant ${name} collides with a mapped port`));

  assert(mapping.routes.length > 0, `${table.model} mapping declares no route`);
  mapping.routes.forEach((route, index) => {
    assert(route.model.trim().length > 0, `${table.model} route ${index} has an empty service model`);
    (route.whenPresent ?? []).forEach((name) => assert(declared.has(name),
      `${table.model} route ${index} names undeclared port ${name}`));
    const unconditional = route.whenPresent === undefined || route.whenPresent.length === 0;
    assert(unconditional === (index === mapping.routes.length - 1),
      `${table.model} must end with exactly one unconditional route`);
  });
}