@hypit/hypit 0.0.1 → 0.1.0

package/packages/provider-kie/README.md

@@ -0,0 +1,134 @@
+# `@hypit/provider-kie`
+
+Asynchronous KIE Market Provider for the eleven explicitly selected exact models and one generic
+background-removal capability.
+
+This package is deployment code. Author source imports model modules such as `@hypit/seedance` or
+`@hypit/gpt-image`; trusted Runtime configuration installs `createKieProvider()`. The Provider binds
+only those exact model capabilities and never interprets a generic image/video request as permission to
+choose another model.
+
+It imports no exact-model package. Every supported Capability contributes one `KieRoute`: exact
+Capability, return Type, request compiler, media/count limits and result packer. All Routes share one
+upload, paid submission, durable Operation polling, download and working-Resource write path. Model mappings
+generate eleven Routes; Background Removal contributes the twelfth.
+
+## Supported catalog
+
+One Capability per exact model; a service that splits a model across endpoints expresses that as
+routes rather than extra Capabilities.
+
+| Author module | Exact models | KIE model slugs |
+|---|---|---|
+| `@hypit/seedance` | `seedance-2`, `-fast`, `-mini`, `seedance-2.5` | `bytedance/seedance-2*`, `bytedance/seedance-2-5` |
+| `@hypit/minimax-h3` | `minimax-h3` | `minimax-h3/{text,image,reference}-to-video` |
+| `@hypit/grok-imagine` | `grok-imagine-video`, `-1.5-preview` | Grok Imagine video endpoints |
+| `@hypit/gpt-image` | `gpt-image-2` | `gpt-image-2-{text,image}-to-image` |
+| `@hypit/nano-banana` | `nano-banana-2`, `-pro` | `nano-banana-2`, `nano-banana-pro` |
+| `@hypit/seedream` | `seedream-5-lite` | `seedream/5-lite-{text,image}-to-image` |
+| `@hypit/background-removal` | `remove-background` | `recraft/remove-background` |
+
+KIE's current GPT Image 2 request surface is:
+
+| Resolution | Ratios unavailable at this Endpoint | `background` |
+| --- | --- | --- |
+| `1K` | none | optional |
+| `2K` | `5:4`, `4:5`, `3:1`, `1:3`, `9:21` | omit |
+| `4K` | `3:1`, `1:3`, `9:21` | omit |
+
+These facts were checked against KIE's live `createTask` endpoint on 2026-09-07. The live API accepts
+`5:4` and `4:5` at 4K even though KIE's [model page](https://kie.ai/gpt-image-2) currently lists a
+broader restriction. At 2K and 4K, any explicit `background` value is rejected, including `opaque`
+and `auto`. The KIE Endpoint checks this boundary before upload or paid submission; the GPT Image
+model package continues to expose the complete Provider-neutral vocabulary.
+
+KIE's Grok Imagine endpoints accept up to seven reference images, but only one at 1080p. This is
+also checked by the KIE Endpoint; the Grok model packages retain their model-level seven-image
+capacity.
+
+KIE publishes a public model-pricing catalogue at `POST /client/v1/model-pricing/page`. For each
+selected Need, `readPricing` derives the same KIE wire model used for execution, reads the catalogue's
+pages with that wire model in KIE's `modelDescription` query, and preserves the returned records. The
+Provider contains no Hypit model-price table and does not interpret KIE's descriptions or formulas.
+All returned parameter rows remain intact for the Agent to read beside the Need. Reading this public
+catalogue does not resolve the generation API credential and submits no work.
+The optional document summary presents each row's model description, USD price, credit price and
+billing unit. Comparison prices and promotion fields remain in the original data for JSON or verbose
+inspection; the summary does not guess a matching tier from KIE's description text.
+
+There is deliberately no Grok image capability and no MiMo capability in this release. Seedream's
+`nsfwCheck` is explicit author request content; KIE cannot silently enable or disable it. A
+customer-specific “spicy” treatment belongs in a Recipe that selects and parameterizes exact model
+requests, not in Provider routing.
+
+## Local Runtime
+
+Declarative activation names an ordinary CredentialRef, not an environment-specific Provider field:
+
+```json
+"kie.personal": {
+  "use": "@hypit/provider-kie",
+  "config": {
+    "apiKey": { "store": "os", "key": "kie.api-key" },
+    "defaultConcurrency": 8,
+    "capabilityConcurrency": {
+      "seedance-2.5": 4,
+      "gpt-image-2": 3
+    }
+  }
+}
+```
+
+The selected writable CredentialStore then enables `hypit auth login kie.personal --runtime
+hypit.runtime.json`; KIE contributes the credential description and the generic CLI contains no KIE
+branch.
+
+```ts
+import { createKieProvider } from "@hypit/provider-kie";
+import { credentialRef } from "@hypit/runtime";
+
+const kie = createKieProvider({
+  instance: "kie.personal",
+  apiKey: credentialRef("env", "KIE_API_KEY"),
+  defaultConcurrency: 8,
+  capabilityConcurrency: {
+    "seedance-2.5": 4,
+    "gpt-image-2": 3,
+  },
+});
+```
+
+`defaultConcurrency` is the total capacity of this configured KIE Endpoint across all Builds. Each
+optional `capabilityConcurrency` entry narrows the capacity of one exact KIE model inside that total. By
+default the Endpoint instance is the shared-resource identity. Set Profile `pool` only when multiple
+Endpoint instances really use the same account or deployment quota. Another Provider is independent
+unless the Profile explicitly gives it that same real-resource identity.
+One Need execution acquires its total and model-specific capacity claims atomically. These are shared-resource
+limits, not parent and child queues.
+
+Optional `actionLimits` uses the shared Endpoint vocabulary for `submit`, `poll` and `collect`.
+For example, `submit: { rate: { limit: 1, periodMs: 200 } }` admits one start action every 200 ms,
+with an initial burst of one. It is shared by instances in the same pool. A start includes reference
+preparation and submission; this is an action-admission limit, not a timestamp guarantee for each
+HTTP request. `collect: { concurrency: 2 }` separately bounds concurrent result downloads.
+Polling transport errors and operation deadlines fail the attempt and retain the task receipt.
+
+An advanced embedding adds `kie` to its Endpoint list beside a complete, explicit set of Runtime
+service packages and selections. The `.svml` Module Closure separately contains only the model
+Manifests actually imported by the author document; installing KIE does not add author intent.
+
+## Task execution and receipts
+
+Reference Resources are uploaded before `createTask`. An acknowledged task ID is saved immediately;
+normal polling uses that same ID. Submission, polling or collection errors end the attempt with the
+actual error. A timeout without an ID records the missing acknowledgement; the next attempt can be a
+new Build. No failure changes the selected Endpoint or account.
+
+On success, poll reports artifacts ready and `collect` downloads them into the Build's working byte
+area. The Result retains completed public Outputs and non-secret task receipts after active Runtime
+state is removed. A task receipt identifies `/api/v1/jobs/recordInfo?taskId=<id>` on the configured
+KIE API base URL; the selected credential reference supplies access without storing the key in Result.
+These records support inspection and explicit reuse in a new Run, not restarting the old Build.
+
+The automated tests exercise submission errors, accepted-task polling, full-response deadlines and
+bounded downloads against fake services, without paid generation.

package/packages/provider-kie/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@hypit/provider-kie",
+  "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/artifact": "workspace:*",
+    "@hypit/background-removal": "workspace:*",
+    "@hypit/endpoint-kit": "workspace:*",
+    "@hypit/generation": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/runtime": "workspace:*",
+    "@hypit/runtime-kit": "workspace:*"
+  },
+  "devDependencies": {
+    "@hypit/resource-store-fs": "workspace:*",
+    "@hypit/component-kit": "workspace:*",
+    "@hypit/core": "workspace:*",
+    "@hypit/credential-store-env": "workspace:*",
+    "@hypit/driver-node": "workspace:*",
+    "@hypit/elaborator": "workspace:*",
+    "@hypit/gpt-image": "workspace:*",
+    "@hypit/grok-imagine": "workspace:*",
+    "@hypit/runtime-local": "workspace:*",
+    "@hypit/media": "workspace:*",
+    "@hypit/minimax-h3": "workspace:*",
+    "@hypit/model-kit": "workspace:*",
+    "@hypit/nano-banana": "workspace:*",
+    "@hypit/narrative": "workspace:*",
+    "@hypit/seedance": "workspace:*",
+    "@hypit/seedream": "workspace:*",
+    "@hypit/store-sqlite": "workspace:*",
+    "@hypit/text": "workspace:*",
+    "@hypit/validation": "workspace:*"
+  }
+}

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

@@ -0,0 +1,71 @@
+import {
+  createRuntimeEndpointAdapterFacet,
+  runtimeConfigCredentialRef,
+  runtimeConfigActionLimits,
+  runtimeConfigExact,
+  runtimeConfigObject,
+  runtimeConfigPositiveInteger,
+  runtimeConfigString,
+} from "@hypit/runtime-kit";
+
+import { createKieProvider } from "./provider.js";
+
+const kieRuntimeAdapter = createRuntimeEndpointAdapterFacet({
+  use: "@hypit/provider-kie",
+  activate(context) {
+    if (context.pool === undefined) throw new Error("KIE Provider Pool is required");
+    const config = runtimeConfigObject(context.config, "KIE");
+    runtimeConfigExact(config, [
+      "apiBaseUrl", "uploadBaseUrl", "apiKey", "defaultConcurrency", "pollIntervalMs",
+      "capabilityConcurrency", "actionLimits", "requestTimeoutMs", "maxOperationMs", "maxArtifactBytes",
+    ], "KIE");
+    const apiBaseUrl = runtimeConfigString(config.apiBaseUrl, "KIE apiBaseUrl");
+    const uploadBaseUrl = runtimeConfigString(config.uploadBaseUrl, "KIE uploadBaseUrl");
+    for (const [value, subject] of [[apiBaseUrl, "KIE apiBaseUrl"], [uploadBaseUrl, "KIE uploadBaseUrl"]] as const) {
+      if (value === undefined) continue;
+      const url = new URL(value);
+      if (url.protocol !== "https:" && url.hostname !== "localhost") {
+        throw new Error(`${subject} must use HTTPS or localhost`);
+      }
+    }
+    const apiKey = runtimeConfigCredentialRef(config.apiKey, "KIE apiKey");
+    if (apiKey === undefined) throw new Error("KIE apiKey CredentialRef is required");
+    const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "KIE defaultConcurrency");
+    const capabilityConcurrency = config.capabilityConcurrency === undefined
+      ? undefined
+      : Object.fromEntries(Object.entries(runtimeConfigObject(config.capabilityConcurrency, "KIE capabilityConcurrency"))
+        .map(([capability, value]) => {
+          const concurrency = runtimeConfigPositiveInteger(value, `KIE capabilityConcurrency.${capability}`);
+          if (concurrency === undefined) throw new Error(`KIE capabilityConcurrency.${capability} is required`);
+          return [capability, concurrency];
+        }));
+    const pollIntervalMs = runtimeConfigPositiveInteger(config.pollIntervalMs, "KIE pollIntervalMs");
+    const actionLimits = runtimeConfigActionLimits(config.actionLimits);
+    const requestTimeoutMs = runtimeConfigPositiveInteger(config.requestTimeoutMs, "KIE requestTimeoutMs");
+    const maxOperationMs = runtimeConfigPositiveInteger(config.maxOperationMs, "KIE maxOperationMs");
+    const maxArtifactBytes = runtimeConfigPositiveInteger(config.maxArtifactBytes, "KIE maxArtifactBytes");
+    return {
+      endpoint: createKieProvider({
+        instance: context.instance,
+        pool: context.pool,
+        ...(apiBaseUrl === undefined ? {} : { apiBaseUrl }),
+        ...(uploadBaseUrl === undefined ? {} : { uploadBaseUrl }),
+        apiKey,
+        ...(defaultConcurrency === undefined ? {} : { defaultConcurrency }),
+        ...(capabilityConcurrency === undefined ? {} : { capabilityConcurrency }),
+        ...(pollIntervalMs === undefined ? {} : { pollIntervalMs }),
+        ...(actionLimits === undefined ? {} : { actionLimits }),
+        ...(requestTimeoutMs === undefined ? {} : { requestTimeoutMs }),
+        ...(maxOperationMs === undefined ? {} : { maxOperationMs }),
+        ...(maxArtifactBytes === undefined ? {} : { maxArtifactBytes }),
+      }),
+    };
+  },
+});
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  hostFacets: [kieRuntimeAdapter],
+};
+
+export default hypitPackage;

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

@@ -0,0 +1,10 @@
+export {
+  kieMappingForCapability,
+  kieModelCatalog,
+  verifyKieModelCatalog,
+} from "./mapping.js";
+export {
+  createKieProvider,
+  kieProviderModuleRef,
+} from "./provider.js";
+export type { CreateKieProviderOptions } from "./provider.js";

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

@@ -0,0 +1,182 @@
+import type { CapabilityRef, ModuleRef } from "@hypit/protocol";
+import type { GenerationWireMapping } from "@hypit/generation";
+
+/**
+ * How KIE names each model's declared input ports.
+ *
+ * This file contains data only. It references Capabilities by module and model
+ * name, so this Provider package imports no model package: a model owns what it
+ * accepts, and KIE owns what it calls that on its wire. Splitting one model
+ * across several KIE endpoints is a KIE fact and lives in `routes`.
+ */
+
+/** Model packages this KIE release is written against. A version bump is a mapping review. */
+const SEEDANCE: ModuleRef = { name: "@hypit/seedance", version: "1" };
+const MINIMAX: ModuleRef = { name: "@hypit/minimax-h3", version: "1" };
+const GROK: ModuleRef = { name: "@hypit/grok-imagine", version: "1" };
+const GPT_IMAGE: ModuleRef = { name: "@hypit/gpt-image", version: "1" };
+const NANO_BANANA: ModuleRef = { name: "@hypit/nano-banana", version: "1" };
+const SEEDREAM: ModuleRef = { name: "@hypit/seedream", version: "1" };
+
+/** KIE keeps each reference modality in its own array, as its schema documents. */
+const referenceFields = {
+  referenceImage: { as: "urlArray", field: "reference_image_urls" },
+  referenceVideo: { as: "urlArray", field: "reference_video_urls" },
+  referenceAudio: { as: "urlArray", field: "reference_audio_urls" },
+} as const;
+
+function seedanceMapping(model: string, kieModel: string): GenerationWireMapping {
+  return {
+    capability: { module: SEEDANCE, name: model },
+    result: "video",
+    routes: [{ model: kieModel }],
+    fields: {
+      prompt: { as: "value", field: "prompt" },
+      ...referenceFields,
+      firstFrame: { as: "url", field: "first_frame_url" },
+      lastFrame: { as: "url", field: "last_frame_url" },
+      resolution: { as: "value", field: "resolution" },
+      aspectRatio: { as: "value", field: "aspect_ratio" },
+      duration: { as: "value", field: "duration" },
+      generateAudio: { as: "value", field: "generate_audio" },
+      webSearch: { as: "value", field: "web_search" },
+    },
+  };
+}
+
+const minimaxMapping: GenerationWireMapping = {
+  capability: { module: MINIMAX, name: "minimax-h3" },
+  result: "video",
+  routes: [
+    { model: "minimax-h3/image-to-video", whenPresent: ["lastFrame"] },
+    { model: "minimax-h3/image-to-video", whenPresent: ["firstFrame"] },
+    { model: "minimax-h3/reference-to-video", whenPresent: ["referenceImage"] },
+    { model: "minimax-h3/reference-to-video", whenPresent: ["referenceVideo"] },
+    { model: "minimax-h3/text-to-video" },
+  ],
+  fields: {
+    prompt: { as: "value", field: "prompt" },
+    duration: { as: "value", field: "duration" },
+    resolution: { as: "value", field: "resolution" },
+    aspectRatio: { as: "value", field: "aspect_ratio" },
+    ...referenceFields,
+    firstFrame: { as: "url", field: "first_frame_url" },
+    lastFrame: { as: "url", field: "last_frame_url" },
+  },
+};
+
+const grokVideoMapping: GenerationWireMapping = {
+  capability: { module: GROK, name: "grok-imagine-video" },
+  result: "video",
+  routes: [
+    { model: "grok-imagine/image-to-video", whenPresent: ["images"] },
+    { model: "grok-imagine/text-to-video" },
+  ],
+  fields: {
+    prompt: { as: "value", field: "prompt" },
+    aspectRatio: { as: "value", field: "aspect_ratio" },
+    resolution: { as: "value", field: "resolution" },
+    duration: { as: "string", field: "duration" },
+    images: { as: "urlArray", field: "image_urls" },
+  },
+  constants: { mode: "normal" },
+};
+
+const grokPreviewMapping: GenerationWireMapping = {
+  capability: { module: GROK, name: "grok-imagine-video-1.5-preview" },
+  result: "video",
+  routes: [{ model: "grok-imagine-video-1-5-preview" }],
+  fields: {
+    prompt: { as: "value", field: "prompt" },
+    aspectRatio: { as: "value", field: "aspect_ratio" },
+    resolution: { as: "value", field: "resolution" },
+    duration: { as: "value", field: "duration" },
+    images: { as: "urlArray", field: "image_urls" },
+  },
+};
+
+const gptImageMapping: GenerationWireMapping = {
+  capability: { module: GPT_IMAGE, name: "gpt-image-2" },
+  result: "image",
+  routes: [
+    { model: "gpt-image-2-image-to-image", whenPresent: ["images"] },
+    { model: "gpt-image-2-text-to-image" },
+  ],
+  fields: {
+    prompt: { as: "value", field: "prompt" },
+    aspectRatio: { as: "value", field: "aspect_ratio" },
+    resolution: { as: "value", field: "resolution" },
+    background: { as: "value", field: "background" },
+    images: { as: "urlArray", field: "input_urls" },
+  },
+};
+
+function nanoBananaMapping(model: string): GenerationWireMapping {
+  return {
+    capability: { module: NANO_BANANA, name: model },
+    result: "image",
+    routes: [{ model }],
+    fields: {
+      prompt: { as: "value", field: "prompt" },
+      /** KIE expects the key even with no input image. */
+      images: { as: "urlArray", field: "image_input", whenAbsent: [] },
+      aspectRatio: { as: "value", field: "aspect_ratio" },
+      resolution: { as: "value", field: "resolution" },
+      outputFormat: { as: "value", field: "output_format" },
+    },
+  };
+}
+
+const seedreamMapping: GenerationWireMapping = {
+  capability: { module: SEEDREAM, name: "seedream-5-lite" },
+  result: "image",
+  routes: [
+    { model: "seedream/5-lite-image-to-image", whenPresent: ["images"] },
+    { model: "seedream/5-lite-text-to-image" },
+  ],
+  fields: {
+    prompt: { as: "value", field: "prompt" },
+    aspectRatio: { as: "value", field: "aspect_ratio" },
+    quality: { as: "value", field: "quality" },
+    outputFormat: { as: "value", field: "output_format" },
+    nsfwCheck: { as: "value", field: "nsfw_checker" },
+    images: { as: "urlArray", field: "image_urls" },
+  },
+};
+
+export const kieModelCatalog: readonly GenerationWireMapping[] = [
+  seedanceMapping("seedance-2", "bytedance/seedance-2"),
+  seedanceMapping("seedance-2-fast", "bytedance/seedance-2-fast"),
+  seedanceMapping("seedance-2-mini", "bytedance/seedance-2-mini"),
+  {
+    ...seedanceMapping("seedance-2.5", "bytedance/seedance-2-5"),
+    // These are KIE output-envelope choices, not Seedance model inputs.
+    constants: { return_last_frame: false, output_format: "mp4" },
+  },
+  minimaxMapping,
+  grokVideoMapping,
+  grokPreviewMapping,
+  gptImageMapping,
+  nanoBananaMapping("nano-banana-2"),
+  nanoBananaMapping("nano-banana-pro"),
+  seedreamMapping,
+];
+
+function capabilityKey(ref: CapabilityRef): string {
+  return `${ref.module.name}@${ref.module.version}#${ref.name}`;
+}
+
+const catalogByCapability = new Map(kieModelCatalog.map((item) => [capabilityKey(item.capability), item]));
+
+export function kieMappingForCapability(capability: CapabilityRef): GenerationWireMapping | undefined {
+  return catalogByCapability.get(capabilityKey(capability));
+}
+
+export function verifyKieModelCatalog(): void {
+  if (catalogByCapability.size !== kieModelCatalog.length) {
+    throw new Error("KIE model catalog repeats a capability");
+  }
+  kieModelCatalog.forEach((item) => {
+    if (item.capability.name.trim().length === 0) throw new Error("KIE model catalog contains an empty model");
+  });
+}