@hypit/hypit 0.2.7 → 0.2.8

package/examples/provider-package/README.md

@@ -68,7 +68,7 @@ differ from the image example, and each is the reason the video example exists.
 **The reference vocabulary is wider, and each role maps to its own field.** The Model declares
 `referenceImage`, `referenceVideo` and `referenceAudio` as separate ports precisely so each can map
 to one wire field — a service that mixes them into one array cannot tell the roles apart. An image
-reference also carries an optional `personReference` classification, which is why those ports use
+reference also requires a boolean `personReference` classification, which is why those ports use
 `itemObject` rather than `urlArray`: the item field travels with the URL it belongs to.
 
 ```json
@@ -76,7 +76,7 @@ reference also carries an optional `personReference` classification, which is wh
 ```
 
 `firstFrame` and `lastFrame` accept at most one item each, so their body fields are URLs.
-This illustrative service accepts their optional person classification on `POST /uploads` through
+This illustrative service accepts their required visual-reference person classification on `POST /uploads` through
 `x-person-reference: true` or `false`. Their mappings declare `resourceFields: ["personReference"]`,
 and the URL resolver sends that header when supplied. Replace this with the real service’s
 documented transport; a field that the service cannot carry must be refused, never discarded.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypit/hypit",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "homepage": "https://hypit.ai",
   "repository": {
     "type": "git",

package/packages/provider-hiapi/README.md

@@ -37,7 +37,7 @@ Service limits this Provider reports as unsupported before submitting:
   `1:3`, `9:21`; 4K excludes `1:1`, `3:1`, `1:3`, `9:21`; image-to-image takes up to six references.
 - Grok Imagine renders 480p or 720p; `grok-imagine-1.5/image-to-video` animates exactly one image.
 
-Seedance visual references may carry `person-reference`; the Provider accepts the declaration and
+Seedance visual references require `person-reference`; the Provider accepts the declaration and
 transmits nothing for it, since HiAPI has no field for it. Seedance rejects reference images and
 videos that contain a real human face; HiAPI offers no way to register authorized portrait material,
 so such a request fails with the service's moderation error.

package/packages/provider-hypihub/README.md

@@ -123,12 +123,11 @@ size and part concurrency, retries a failed part with a fresh signed URL, comple
 one upload, and then passes the returned HTTPS URL to generation or transcription. Signing requests
 contain at most the service's 128-part limit; all batches belong to the same upload. One
 Resource identity with the same declared person-reference classification is uploaded once within one Runtime operation. Hypit keeps no upload catalog or
-cross-Build cache. Seedance visual references can carry `personReference` in their media fields;
+cross-Build cache. Seedance visual references require boolean `personReference` in their media fields;
 the mapping declares it as a resource-transport field and the upload session receives
-`is_person_reference`, preserving true, false and omission. It stays out of the generation body.
+`is_person_reference`, preserving true and false. It stays out of the generation body.
 This covers reference images, reference videos, and first/last frames for every declared Seedance
-variant. Omission remains absent on the wire; HypiHub's upload API currently defaults it to false,
-so omission does not enable detection or person-reference preparation.
+variant. Seedance rejects omission before upload; no automatic face detection is requested.
 HypiHub stores the authored classification and prepares the applicable upstream person reference;
 this Provider does not detect faces or select an upstream private-avatar group.
 

package/packages/provider-monid/README.md

@@ -25,7 +25,7 @@ each media input as a typed item with its `role` (`first_frame`, `last_frame`, `
 
 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
+`aspect-ratio="adaptive"`. Seedance visual references require `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.

package/packages/provider-tokendance/README.md

@@ -19,7 +19,7 @@ the models the Distribution already describes.
 Video requests write the prompt and each media input as one item of the protocol's `content`
 array with its `role` (`first_frame`, `last_frame`, `reference_image`, `reference_video`,
 `reference_audio`), then `resolution`, `ratio`, `duration` and, for Seedance, `generate_audio`;
-`web-search="true"` adds `tools: [{ "type": "web_search" }]`. Seedance visual references may carry
+`web-search="true"` adds `tools: [{ "type": "web_search" }]`. Seedance visual references require
 `person-reference`; the Provider accepts the declaration and transmits nothing for it, since the Ark
 protocol has no such field. Seedance 2.0 and 2.5 reject reference images and videos that contain a
 real human face; TokenDance offers no way to register authorized portrait material, so such a request

package/packages/seedance/README.md

@@ -34,22 +34,20 @@ responsible for any additional service-specific input limits.
 
 ## Visual reference metadata
 
-Declare whether each image or video contains a person/avatar reference, including an AI-generated
-human likeness. This describes the supplied material, independently of the prompt's requested action:
+Every supplied image or video must explicitly declare `person-reference`: `true` if it contains
+a person, `false` otherwise. Classify the supplied material, not the requested result.
 
 ```xml
-<seedance:ReferenceVideo id="dance" model="mini" prompt={direction} duration="8">
+<seedance:ReferenceVideo id="take" model="mini" prompt={direction} duration="8">
   <seedance:Reference image={presenter.image} person-reference="true"/>
-  <seedance:Reference video={motion.video} person-reference="true"/>
+  <seedance:Reference video={presenter.video} person-reference="true"/>
   <seedance:Reference image={room.image} person-reference="false"/>
 </seedance:ReferenceVideo>
 ```
 
-`person-reference` is optional, accepts literal `true` or `false`, and applies to image/video, not
-voice audio. Omission carries no classification; it is distinct from explicitly declaring false.
-Inspect the actual reference when deciding the value. For `FrameVideo`, use
-`first-frame-person-reference` and `last-frame-person-reference` beside their respective frame
-inputs. A last-frame classification requires a last-frame input.
+Missing or non-boolean declarations are rejected; there is no default or automatic face detection.
+Audio must omit this field. `FrameVideo` requires `first-frame-person-reference` and, when a last
+frame is supplied, `last-frame-person-reference`. A last-frame classification requires a last frame.
 
 | Supplied visual input | Authored attribute | Request port |
 | --- | --- | --- |
@@ -66,23 +64,18 @@ These forms apply to `standard`, `fast`, `mini` and `2.5`. For example:
   last-frame={empty-room.image} last-frame-person-reference="false"/>
 ```
 
-Classify the material supplied to this request, not the intended result. A dance video with a person
-still needs `true` when used only for motion, even if the prompt asks for a different performer.
-An empty room stays `false` when the prompt asks to add a person. Inspect video across the selected
-excerpt, not only its opening frame. This flag neither detects faces nor locks or names an identity.
-Identity and action direction remain in the prompt and references.
+Inspect the selected video excerpt, not only its opening frame. An empty room stays `false` when
+the prompt asks to add a person. The flag does not lock identity; direction and references own that.
 
 The SVML author declares this parameter on each reference input. Admitted files, generated
 images/videos and reused Results use the same attributes. For a future output, declare the intended
 reference classification explicitly; if its contents are uncertain, generate and inspect that
 material before using it downstream.
 
-The model's media ports carry this as `fields.personReference`. Providers interpret it through their
-service's media handling; it is not a prompt sentence or a Core-level identity. HypiHub sends it as
+Direct requests require the same boolean in `fields.personReference`. Providers interpret it through
+their service's media handling; it is not a prompt sentence or a Core-level identity. HypiHub sends it as
 `is_person_reference` when uploading the file, then uses the returned URL in the ordinary video
 request. A project Provider maps it according to its own API.
-Omission does not request automatic face detection. HypiHub currently treats omitted upload flags
-as unmarked (`false`); declare `true` explicitly for a person reference that needs its preparation.
 
 Video references can carry motion or camera behavior while image references carry the target
 appearance. Request duration and reference-clip duration are different limits. Check the selected

package/packages/seedance/src/index.ts

@@ -17,7 +17,7 @@ export type SeedanceModel = typeof seedanceModels[number];
 
 const ASPECT_RATIOS = ["1:1", "4:3", "3:4", "16:9", "9:16", "21:9", "adaptive"] as const;
 
-const PERSON_REFERENCE_FIELDS = [{ name: "personReference", value: { kind: "boolean" }, optional: true }] as const;
+const PERSON_REFERENCE_FIELDS = [{ name: "personReference", value: { kind: "boolean" } }] as const;
 
 const SEEDANCE_25_DURATIONS = [-1, ...Array.from({ length: 27 }, (_item, index) => index + 4)] as const;
 
@@ -175,9 +175,9 @@ const seedanceCommonAttributes: readonly SurfaceAttributeVocabulary[] = [
   },
 ];
 
-const personReferenceAttribute = (name: string): SurfaceAttributeVocabulary => ({
-  name, kind: "literal", required: false, values: ["true", "false"],
-  summary: "Declares whether this visual input contains a person/avatar reference, including an AI-generated human likeness. Omission leaves it unclassified.",
+const personReferenceAttribute = (name: string, required = false): SurfaceAttributeVocabulary => ({
+  name, kind: "literal", required, values: ["true", "false"],
+  summary: "Required for each supplied image/video, including first/last frames: true if it contains a person, false otherwise. Audio must omit it.",
 });
 
 const seedanceVideoPort: readonly SurfacePortVocabulary[] = [{
@@ -235,7 +235,7 @@ export const seedanceMarkupSurfaces = [
       summary: "Generates one video with an exact Seedance model from a Text prompt and the images the video opens and closes on.",
       attributes: [
         ...seedanceCommonAttributes,
-        personReferenceAttribute("first-frame-person-reference"),
+        personReferenceAttribute("first-frame-person-reference", true),
         personReferenceAttribute("last-frame-person-reference"),
         {
           name: "first-frame",
@@ -253,7 +253,7 @@ export const seedanceMarkupSurfaces = [
         },
       ],
       ports: seedanceVideoPort,
-      example: '<seedance:FrameVideo id="bridge" model="fast" prompt={direction} duration="5" first-frame={first.image} last-frame={last.image}/>',
+      example: '<seedance:FrameVideo id="bridge" model="fast" prompt={direction} duration="5" first-frame={first.image} first-frame-person-reference="true" last-frame={last.image} last-frame-person-reference="false"/>',
       notes: [
         ...seedanceSettingNotes,
         "Both frames are ordinary image Artifact edges; the Surface copies no runtime media into request metadata.",
@@ -316,7 +316,7 @@ export const seedanceMarkupSurfaces = [
       notes: [
         ...seedanceSettingNotes,
         "The element requires at least one `Reference` child, and the model's port limits cap how many of each role it accepts.",
-        "`person-reference` applies to image/video references; voice audio carries no visual classification. The Provider transports the declared fact according to its API.",
+        "Every image/video Reference requires `person-reference=\"true|false\"`. Classify the supplied material; audio must omit the field. The Provider transports it according to its API.",
         "A `Reference` carries exactly one of `image`, `video` or `audio`, and is empty.",
       ],
     },

package/packages/seedance/src/surface.ts

@@ -146,8 +146,10 @@ function booleanAttribute(element: StructuredElement, name: string, fallback: bo
 }
 
 function personReferenceFields(element: StructuredElement, name: string) {
-  return element.attributes[name] === undefined ? undefined
-    : { personReference: booleanAttribute(element, name, false) };
+  if (element.attributes[name] === undefined) {
+    throw new Error(`${element.name}.${name} is required for this visual reference; set true if it contains a person, false otherwise`);
+  }
+  return { personReference: booleanAttribute(element, name, false) };
 }
 
 function enumeratedPort(table: GenerationPortTable, name: string): readonly (string | number)[] {
@@ -217,8 +219,8 @@ function referenceInputs(
     const kinds = accepted.filter((kind) => child.attributes[kind] !== undefined);
     if (kinds.length !== 1) throw new Error(`${child.name} requires exactly one of ${accepted.join(", ")}`);
     const role = kinds[0]!;
-    const fields = personReferenceFields(child, "person-reference");
-    if (role === "audio" && fields !== undefined) throw new Error(`${child.name}.person-reference applies to image or video, not audio`);
+    if (role === "audio" && child.attributes["person-reference"] !== undefined) throw new Error(`${child.name}.person-reference applies to image or video, not audio`);
+    const fields = role === "audio" ? undefined : personReferenceFields(child, "person-reference");
     result.push({
       ...(fields === undefined ? {} : { fields }),
       role,
@@ -242,13 +244,12 @@ function frameInputs(
 ): MediaInput[] {
   const first = mediaReference(resolved(element, "first-frame", resolveReference), "image", `${element.name}.first-frame`);
   const firstFields = personReferenceFields(element, "first-frame-person-reference");
-  const result: MediaInput[] = [{ port: "firstFrame", role: "image", source: first, ...(firstFields === undefined ? {} : { fields: firstFields }) }];
-  const lastFields = personReferenceFields(element, "last-frame-person-reference");
-  if (lastFields !== undefined && element.attributes["last-frame"] === undefined) throw new Error(`${element.name}.last-frame-person-reference requires last-frame`);
+  const result: MediaInput[] = [{ port: "firstFrame", role: "image", source: first, fields: firstFields }];
+  if (element.attributes["last-frame-person-reference"] !== undefined && element.attributes["last-frame"] === undefined) throw new Error(`${element.name}.last-frame-person-reference requires last-frame`);
   if (element.attributes["last-frame"] !== undefined) {
     result.push({
       port: "lastFrame",
-      ...(lastFields === undefined ? {} : { fields: lastFields }),
+      fields: personReferenceFields(element, "last-frame-person-reference"),
       role: "image",
       source: mediaReference(resolved(element, "last-frame", resolveReference), "image", `${element.name}.last-frame`),
     });

package/packages/seedance-kits/README.md

@@ -23,8 +23,8 @@ ordinary explicit graph edges:
 
 <seedance:ReferenceVideo id="broll" model="mini" prompt={broll-prompt}
   duration="5" resolution="720p" aspect-ratio="9:16">
-  <seedance:Reference image={scene}/>
-  <seedance:Reference image={product}/>
+  <seedance:Reference image={scene} person-reference="false"/>
+  <seedance:Reference image={product} person-reference="false"/>
 </seedance:ReferenceVideo>
 ```
 
@@ -154,7 +154,8 @@ For a multi-scene B-roll montage, `story` can name the references in scene order
 action. Choose an edit language compatible with cuts. “Continuous within each scene” and “one
 continuous shot for the whole montage” ask for different results.
 
-Visual input classification belongs to the Seedance Reference, separately from Kit text. The
+Every Seedance image/video Reference requires `person-reference="true|false"`: true if the supplied
+material contains a person, false otherwise. Audio must omit it. The
 [Seedance author package](../seedance/README.md#visual-reference-metadata) explains `person-reference`
 and its frame variants. The Kit supplies direction; the actual reference edges supply media and
 metadata. For movement-led work, a reference video can carry the motion while the text explains what