@shop-os/modelkit 0.1.0

package/README.md

@@ -0,0 +1,136 @@
+# @shop-os/modelkit
+
+One catalog and one call path for every generative model ShopOS uses. A new model on an existing provider API is a catalog row. A new provider API is one adapter.
+
+## Use
+
+```ts
+import { createDefaultModelKit } from "@shop-os/modelkit";
+
+const kit = createDefaultModelKit({
+    routing: {
+        text: "cloudflare",
+        fal: "cloudflare-passthrough",
+        cloudflare: { accountId, gatewayId },
+    },
+    onUsage: (event) => usageClient.emit(event),
+});
+
+const image = await kit.generateImage(
+    { model: "nb-2", prompt, references: [{ url }], aspectRatio: "4:5", size: "2K" },
+    { tier: "enterprise" },
+);
+
+const job = await kit.generateVideo({
+    model: "seedance-2.0",
+    prompt,
+    firstFrame: { url },
+    durationSeconds: 8,
+});
+const video = await job.result({ timeoutMs: 15 * 60_000 });
+
+const reply = kit.streamText({ model: "claude-sonnet-4-6", messages }); // or model: openai("gpt-4o")
+for await (const chunk of reply.textStream) process.stdout.write(chunk);
+
+const song = await kit.generateAudio({
+    model: "lyria-3-clip-preview",
+    prompt,
+    references: [{ url }],
+});
+const score = await kit.generateAudio({ model: "mmaudio", prompt, sourceVideo: { url } });
+
+const clip = await kit.prepareMediaPart(
+    "gemini-2.5-flash",
+    { bytes, mime: "video/mp4" },
+    "video/mp4",
+);
+await kit.generateText({
+    model: "gemini-2.5-flash",
+    messages: [{ role: "user", content: [clip, { type: "text", text }] }],
+});
+await clip.cleanup?.();
+```
+
+Keys come from `process.env` by default: bare names for pro (`OPENAI_API_KEY`, `FAL_KEY`, `ARK_API_KEY` ...) and the `ENTERPRISE_` prefix for enterprise. Pass `keys: { pro, enterprise }` to override.
+
+## A superset of `ai`
+
+Every export of `ai` (the Vercel AI SDK) is re-exported here, so this import swap is
+the whole migration:
+
+```ts
+import {
+    generateText,
+    streamText,
+    generateObject,
+    tool,
+    jsonSchema,
+    Output,
+} from "@shop-os/modelkit";
+```
+
+The generation functions replace their `ai` namesakes with the same option and result
+shapes. `model` is either a catalog id or alias, or the provider instance `ai` takes.
+Both spellings work in every call:
+
+```ts
+import { openai } from "@ai-sdk/openai";
+
+await generateText({ model: "claude-sonnet-4-6", prompt }); // catalog: keys, routing, providerOptions, usage
+await generateText({ model: openai("gpt-4o"), prompt }); // pass-through: the SDK runs it unchanged
+```
+
+A pass-through model has no catalog row, so it gets no defaults and no key resolution,
+and usage is attributed to its own `provider` and `modelId`. Use it for a model the
+catalog does not carry yet; the next step is a catalog row.
+
+| `ai` function                                                                                   | Here                                                                                                                                                                                                                                                   |
+| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `generateText`, `streamText`                                                                    | Same. Catalog `providerOptions` are merged under the caller's; `prepareStep` model switches resolve through the catalog; usage per step.                                                                                                               |
+| `generateObject`, `streamObject`                                                                | Same, including `output: "array" \| "enum" \| "no-schema"`.                                                                                                                                                                                            |
+| `generateImage`                                                                                 | Takes `n`, `size: "WxH"`, `aspectRatio`, `seed`, `abortSignal`, `providerOptions` plus the kit's `references`, `size: "2K"`, `quality`, `outputFormat`. Returns `image` and `images` with `uint8Array`, `base64`, `mediaType` next to `bytes`, `mime`. |
+| `experimental_generateVideo`                                                                    | The kit's `generateVideo` returns a job; `duration` is an alias of `durationSeconds`. An `ai` video model instance is wrapped as a settled job. The `ai` function is also re-exported as-is.                                                           |
+| `experimental_generateSpeech`, `transcribe`, `embed`, `embedMany`, `rerank`, agents, UI streams | Re-exported from `ai` unchanged; the catalog has no rows for them.                                                                                                                                                                                     |
+
+An optional second `CallContext` argument selects enterprise keys, adds cancellation
+(combined with `abortSignal`), and sets `onUnsupported`. Package-level functions read
+keys from the environment; a configured kit adds routing, catalog overrides, custom
+fetch, logging, and the `onUsage` sink.
+
+`providerOptions` on `generateImage`/`generateVideo` reach the provider only for
+pass-through instances; catalog rows carry their own and the caller's are dropped
+with an `option_ignored` warning.
+
+The kit keeps its `Warning` type for coercions; the SDK's warning type is `AiWarning`.
+`languageModel()` remains the low-level handle for Mastra and custom middleware.
+
+## What the package owns
+
+| Concern     | Rule                                                                                                                                                                                                                                                                                                                        |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Ids         | `id` is the pro-backend pricing key. Every historical id (`nb-pro`, `veo-3.1-generate-001`, `kling-v2.5-turbo-pro`) is an alias.                                                                                                                                                                                            |
+| Options     | `resolveOptions` fills catalog defaults, coerces aspect ratio to the nearest supported one, errors on unsupported size or resolution (`onUnsupported: "coerce"` snaps down instead), clamps duration, trims references (audio first, then video), and drops options the model ignores with a warning.                       |
+| Keys        | Enterprise keys win only when every key the adapter needs is set on the enterprise tier.                                                                                                                                                                                                                                    |
+| Routing     | Cloudflare AI Gateway for text only. Never for Gemini images or Omni. fal passthrough for geo-blocked regions. OpenRouter optional for text.                                                                                                                                                                                |
+| Retry       | One classifier. Never on content blocks or 4xx except 429.                                                                                                                                                                                                                                                                  |
+| Errors      | `ModelKitError` with `code`, `provider`, `status`, `body`. Gemini `blockReason` and fal `body.detail` are lifted into `body`.                                                                                                                                                                                               |
+| Usage       | One event per call with the canonical model id. Video usage is emitted on completion. Audio: Lyria 3 returns no duration, so it emits `unit: "images", quantity: 1` (token counts ride along as `inputTokens`/`outputTokens`); Replicate audio (Lyria 2, MMAudio) emits `unit: "compute_seconds"` with the prediction time. |
+| Media parts | `prepareMediaPart` turns a `MediaRef` into an AI SDK file part. Google inlines bytes up to 20 MB and uploads larger payloads through the Files API; call the returned `cleanup` after the request. Other providers get the reference inline.                                                                                |
+
+## Add a model
+
+1. Add a row to `src/catalog/{image,video,text,other}.ts`. Copy `constraints` from the provider docs.
+2. Run `pnpm test`. The catalog test checks id and alias uniqueness.
+3. Bump `version` in `package.json`. Merging to `dev` publishes.
+
+## Adapters
+
+`ai-sdk-text`, `google-image`, `openai-image`, `google-genai` (Veo, Omni, Lyria 3, Files API media parts), `ark` (Seedream, Seedance), `fal`, `replicate` (images, video, Lyria 2, MMAudio), `prodia`, `higgsfield`, `xai-video`. See `src/adapters/`.
+
+## Not in the package
+
+Prompt construction, agent tools, node schemas and UI, S3 upload, credit reserve and settle, post-generation crop (needs `sharp`, caller side).
+
+## Live smoke test
+
+`pnpm smoke [filter...]` runs one cheap real call per adapter (about $5 for the full matrix, 15 minutes, mostly video polling). Keys load from the `trigger-workflows`, `cowork`, and `vibe-triggers` env files next to this monorepo. Outputs land in `scripts/smoke-out/`. Run it before every release and after any adapter change. Never wire it into CI.