@hypit/hypit 0.0.1 → 0.1.1

package/packages/generation/src/mapping.ts

@@ -0,0 +1,231 @@
+import { canonicalize } from "@hypit/protocol";
+import type { BlobRef, CanonicalValue, CapabilityRef } from "@hypit/protocol";
+
+import { isMediaPort } from "./ports.js";
+import type { GenerationMediaRole, GenerationMediaValue, GenerationPortTable } from "./ports.js";
+import { presentPorts } from "./request.js";
+import type { GenerationRequest } from "./request.js";
+
+/**
+ * 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 GenerationArtifactUrlResolver = (artifact: BlobRef) => Promise<string>;
+
+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 whenAbsent?: CanonicalValue }
+  /** Several media items written as one array of resolved URLs. */
+  | { readonly as: "urlArray"; readonly field: 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 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 {
+  assert(mappingSupportsRequest(mapping, request),
+    `${mapping.capability.name} request contains a port 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);
+}
+
+async function urlsOf(
+  values: readonly GenerationMediaValue[],
+  resolve: GenerationArtifactUrlResolver,
+): Promise<string[]> {
+  return await Promise.all(values.map((item) => resolve(item.artifact)));
+}
+
+/**
+ * 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") {
+      input[field.field] = await resolve((supplied[0] as GenerationMediaValue).artifact);
+    } else if (field.as === "urlArray") {
+      input[field.field] = await urlsOf(supplied as readonly GenerationMediaValue[], resolve);
+    } else {
+      const media = supplied as readonly GenerationMediaValue[];
+      input[field.field] = await Promise.all(media.map(async (item) => ({
+        [field.urlKey]: await resolve(item.artifact),
+        ...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) };
+}
+
+/** Does this request only use ports this mapping can write? Needs no model package. */
+export function mappingSupportsRequest(mapping: GenerationWireMapping, value: unknown): boolean {
+  const request = value as GenerationRequest | undefined;
+  if (request === undefined || request.ports === null || typeof request.ports !== "object") return false;
+  return Object.keys(request.ports).every((port) => mapping.fields[port] !== undefined);
+}
+
+/**
+ * Prove one service mapping covers every port the model declares.
+ *
+ * This is the check the old hand-written per-model translators could not have:
+ * a forgotten reference role or item field used to surface only after a paid
+ * generation returned the wrong result.
+ */
+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 ?? [];
+      if (itemFields.length > 0) {
+        assert(field.as === "itemObject", `${subject} must use itemObject because the port carries item fields`);
+        for (const item of itemFields) {
+          if (item.optional === true) continue;
+          assert(field.fieldKeys[item.name] !== undefined,
+            `${subject} does not map required item field ${item.name}`);
+        }
+        Object.keys(field.fieldKeys).forEach((name) => assert(
+          itemFields.some((item) => item.name === name),
+          `${subject} maps unknown item field ${name}`,
+        ));
+        continue;
+      }
+      assert(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`);
+      }
+      if (field.as === "itemObject") {
+        assert(field.fieldKeys !== undefined && Object.keys(field.fieldKeys).length === 0,
+          `${subject} itemObject must not map undeclared item fields`);
+      }
+      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`);
+  });
+}

package/packages/generation/src/ports.ts

@@ -0,0 +1,222 @@
+import type { BlobRef } from "@hypit/protocol";
+
+/**
+ * The closed vocabulary describing what one exact generation model accepts.
+ *
+ * A model's input ports are decided when the model is trained: which reference
+ * images, audio, video or text it can consume is a property of the model, not
+ * of the service reselling it. A Provider therefore never redeclares this
+ * shape; it only maps each declared port onto its own wire fields.
+ *
+ * Adding a port kind changes this package's public vocabulary, not one model's table.
+ */
+export type GenerationMediaRole = "image" | "video" | "audio";
+
+export const GENERATION_MEDIA_ROLES: readonly GenerationMediaRole[] = ["image", "video", "audio"];
+
+export type GenerationPortScalarKind =
+  | { readonly kind: "text"; readonly maxChars?: number }
+  | { readonly kind: "token"; readonly minLength: number; readonly maxLength: number }
+  | { readonly kind: "enum"; readonly values: readonly (string | number)[] }
+  | {
+      readonly kind: "number";
+      readonly integer?: boolean;
+      readonly minimum?: number;
+      readonly maximum?: number;
+    }
+  | { readonly kind: "boolean" };
+
+/** A scalar carried alongside one media item, such as a trimmed excerpt boundary. */
+export type GenerationPortItemField = {
+  readonly name: string;
+  readonly value: GenerationPortScalarKind;
+  readonly optional?: boolean;
+};
+
+/** Relation between two item fields of the same media item, such as a trim window. */
+export type GenerationItemRequirement = {
+  readonly kind: "strictlyIncreasing";
+  readonly fields: readonly string[];
+};
+
+export type GenerationMediaPortKind = {
+  readonly kind: "media";
+  readonly accepts: readonly GenerationMediaRole[];
+  readonly itemFields?: readonly GenerationPortItemField[];
+  readonly itemRequires?: readonly GenerationItemRequirement[];
+};
+
+export type GenerationPortKind = GenerationPortScalarKind | GenerationMediaPortKind;
+
+type GenerationPortBase = {
+  readonly name: string;
+  readonly minItems: number;
+  readonly maxItems: number;
+};
+
+export type GenerationScalarPort = GenerationPortBase & { readonly value: GenerationPortScalarKind };
+export type GenerationMediaPort = GenerationPortBase & { readonly value: GenerationMediaPortKind };
+
+/**
+ * One named input port. `minItems: 0` means the model works without it;
+ * `maxItems: 1` means the port carries a single value rather than a list.
+ */
+export type GenerationPort = GenerationScalarPort | GenerationMediaPort;
+
+export type GenerationPortRequirement =
+  | { readonly kind: "atMostOneOf"; readonly ports: readonly string[] }
+  | { readonly kind: "requiresPresent"; readonly port: string; readonly needs: readonly string[] }
+  /** This port needs company, but any one of several will do — reference audio needs a visual. */
+  | { readonly kind: "requiresAnyOf"; readonly port: string; readonly anyOf: readonly string[] }
+  /** A shared budget several ports draw from, such as a total reference quota. */
+  | {
+      readonly kind: "weightedTotal";
+      readonly weights: Readonly<Record<string, number>>;
+      readonly maximum: number;
+    };
+
+export type GenerationPortTable = {
+  /** Exact model identity; this is also the Capability name. */
+  readonly model: string;
+  readonly result: "audio" | "image" | "video";
+  readonly ports: readonly GenerationPort[];
+  readonly requires: readonly GenerationPortRequirement[];
+};
+
+export type GenerationMediaValue = {
+  readonly role: GenerationMediaRole;
+  readonly artifact: BlobRef;
+  readonly fields?: Readonly<Record<string, string | number | boolean>>;
+};
+
+export type GenerationPortValue = string | number | boolean | GenerationMediaValue;
+
+const PORT_NAME = /^[a-z][A-Za-z0-9]*$/u;
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+export function isMediaPort(port: GenerationPort): port is GenerationMediaPort {
+  return port.value.kind === "media";
+}
+
+function assertScalarKind(value: GenerationPortScalarKind, subject: string): void {
+  if (value.kind === "text") {
+    if (value.maxChars !== undefined) {
+      assert(Number.isSafeInteger(value.maxChars) && value.maxChars > 0, `${subject} maxChars is invalid`);
+    }
+    return;
+  }
+  if (value.kind === "token") {
+    assert(Number.isSafeInteger(value.minLength) && value.minLength >= 1, `${subject} minLength is invalid`);
+    assert(Number.isSafeInteger(value.maxLength) && value.maxLength >= value.minLength, `${subject} maxLength is invalid`);
+    return;
+  }
+  if (value.kind === "enum") {
+    assert(value.values.length > 0, `${subject} enum is empty`);
+    assert(new Set(value.values).size === value.values.length, `${subject} enum repeats a value`);
+    value.values.forEach((item) => assert(
+      typeof item === "string" ? item.length > 0 : Number.isFinite(item),
+      `${subject} enum contains an invalid value`,
+    ));
+    return;
+  }
+  if (value.kind === "number") {
+    if (value.minimum !== undefined) assert(Number.isFinite(value.minimum), `${subject} minimum is invalid`);
+    if (value.maximum !== undefined) assert(Number.isFinite(value.maximum), `${subject} maximum is invalid`);
+    if (value.minimum !== undefined && value.maximum !== undefined) {
+      assert(value.maximum >= value.minimum, `${subject} numeric bounds are inverted`);
+    }
+    return;
+  }
+  assert(value.kind === "boolean", `${subject} has an unsupported port kind`);
+}
+
+export function assertGenerationPortTable(value: GenerationPortTable): void {
+  assert(typeof value.model === "string" && value.model.trim().length > 0, "Generation port table model is empty");
+  assert(value.result === "audio" || value.result === "image" || value.result === "video",
+    `${value.model} port table result is invalid`);
+  assert(value.ports.length > 0, `${value.model} declares no input port`);
+
+  const names = new Set<string>();
+  for (const port of value.ports) {
+    const subject = `${value.model} port ${port.name}`;
+    assert(PORT_NAME.test(port.name), `${subject} name is invalid`);
+    assert(!names.has(port.name), `${subject} is declared twice`);
+    names.add(port.name);
+    assert(Number.isSafeInteger(port.minItems) && port.minItems >= 0, `${subject} minItems is invalid`);
+    assert(Number.isSafeInteger(port.maxItems) && port.maxItems >= Math.max(1, port.minItems),
+      `${subject} maxItems is invalid`);
+    if (isMediaPort(port)) {
+      const media = port.value;
+      assert(media.accepts.length > 0, `${subject} accepts no media role`);
+      assert(new Set(media.accepts).size === media.accepts.length, `${subject} repeats a media role`);
+      media.accepts.forEach((role) => assert(GENERATION_MEDIA_ROLES.includes(role), `${subject} media role ${role} is invalid`));
+      const fields = new Set<string>();
+      for (const field of media.itemFields ?? []) {
+        assert(PORT_NAME.test(field.name), `${subject} item field name is invalid`);
+        assert(!fields.has(field.name), `${subject} item field ${field.name} is declared twice`);
+        fields.add(field.name);
+        assertScalarKind(field.value, `${subject} item field ${field.name}`);
+      }
+      for (const rule of media.itemRequires ?? []) {
+        assert(rule.kind === "strictlyIncreasing", `${subject} declares an unsupported item requirement`);
+        assert(rule.fields.length >= 2, `${subject} strictlyIncreasing needs at least two item fields`);
+        rule.fields.forEach((name) => assert(fields.has(name),
+          `${subject} strictlyIncreasing names unknown item field ${name}`));
+      }
+    } else {
+      assertScalarKind(port.value, subject);
+    }
+  }
+
+  for (const requirement of value.requires) {
+    if (requirement.kind === "atMostOneOf") {
+      assert(requirement.ports.length >= 2, `${value.model} atMostOneOf needs at least two ports`);
+      requirement.ports.forEach((name) => assert(names.has(name),
+        `${value.model} atMostOneOf names unknown port ${name}`));
+      assert(new Set(requirement.ports).size === requirement.ports.length,
+        `${value.model} atMostOneOf repeats a port`);
+      continue;
+    }
+    if (requirement.kind === "requiresAnyOf") {
+      assert(names.has(requirement.port), `${value.model} requiresAnyOf names unknown port ${requirement.port}`);
+      assert(requirement.anyOf.length >= 1, `${value.model} requiresAnyOf lists no companion port`);
+      requirement.anyOf.forEach((name) => {
+        assert(names.has(name), `${value.model} requiresAnyOf names unknown port ${name}`);
+        assert(name !== requirement.port, `${value.model} requiresAnyOf ${name} depends on itself`);
+      });
+      continue;
+    }
+    if (requirement.kind === "weightedTotal") {
+      const entries = Object.entries(requirement.weights);
+      assert(entries.length >= 1, `${value.model} weightedTotal lists no port`);
+      entries.forEach(([name, weight]) => {
+        assert(names.has(name), `${value.model} weightedTotal names unknown port ${name}`);
+        assert(Number.isFinite(weight) && weight > 0, `${value.model} weightedTotal weight for ${name} is invalid`);
+      });
+      assert(Number.isFinite(requirement.maximum) && requirement.maximum > 0,
+        `${value.model} weightedTotal maximum is invalid`);
+      continue;
+    }
+    assert(requirement.kind === "requiresPresent", `${value.model} declares an unsupported requirement`);
+    assert(names.has(requirement.port), `${value.model} requiresPresent names unknown port ${requirement.port}`);
+    assert(requirement.needs.length > 0, `${value.model} requiresPresent lists no prerequisite`);
+    requirement.needs.forEach((name) => {
+      assert(names.has(name), `${value.model} requiresPresent names unknown port ${name}`);
+      assert(name !== requirement.port, `${value.model} requiresPresent ${name} depends on itself`);
+    });
+  }
+}
+
+export function sealGenerationPortTable(value: GenerationPortTable): GenerationPortTable {
+  assertGenerationPortTable(value);
+  return value;
+}
+
+export function generationPort(table: GenerationPortTable, name: string): GenerationPort {
+  const port = table.ports.find((item) => item.name === name);
+  if (port === undefined) throw new Error(`${table.model} declares no port ${name}`);
+  return port;
+}