@shop-os/modelkit 0.1.4 → 0.1.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +36 -13
- package/dist/index.cjs +938 -609
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +48 -9
- package/dist/index.d.ts +48 -9
- package/dist/index.js +937 -609
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -113,30 +113,53 @@ Opt into thinking per call, for example
|
|
|
113
113
|
`providerOptions: { anthropic: { thinking: { type: "enabled", budgetTokens: 4000 } } }`.
|
|
114
114
|
|
|
115
115
|
The kit keeps its `Warning` type for coercions; the SDK's warning type is `AiWarning`.
|
|
116
|
-
`languageModel()` remains the low-level handle for Mastra and custom middleware.
|
|
116
|
+
`languageModel()` remains the low-level handle for Mastra and custom middleware; its `providerOptions` carry no kit-internal keys.
|
|
117
117
|
|
|
118
118
|
## What the package owns
|
|
119
119
|
|
|
120
|
-
| Concern | Rule
|
|
121
|
-
| ----------- |
|
|
122
|
-
| 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.
|
|
123
|
-
| Options | Image tiers are `512` (Gemini 3.1 Flash only), `1K`, `2K`, `4K`. `resolveOptions` fills catalog defaults,
|
|
124
|
-
| Keys | Enterprise keys win only when every key the adapter (and its route, e.g. the cloudflare token for gateway
|
|
125
|
-
| Routing | Cloudflare AI Gateway for text only. Never for Gemini images or Omni. fal passthrough for geo-blocked regions.
|
|
126
|
-
| Retry | One classifier. Never on content blocks or 4xx except 429.
|
|
127
|
-
| Errors | `ModelKitError` with `code`, `provider`, `status`, `body`. Gemini `blockReason` and fal `body.detail` are lifted into `body`.
|
|
128
|
-
| Usage | One event per call with the canonical model id. Gemini image events carry the token counts too (`inputTokens`/`outputTokens`); Google's raw `usageMetadata` rides on `raw.providerMetadata.google`. Video usage is emitted on completion
|
|
129
|
-
| 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.
|
|
120
|
+
| Concern | Rule |
|
|
121
|
+
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
122
|
+
| 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. |
|
|
123
|
+
| Options | Image tiers are `512` (Gemini 3.1 Flash only), `1K`, `2K`, `4K`. `resolveOptions` fills catalog defaults, errors on an unsupported aspect ratio, size, resolution or duration (`onUnsupported: "coerce"` snaps to the nearest supported value with a warning instead; since 0.1.6 ratio and duration honour this too, so pass `"coerce"` where the old code snapped silently), trims references (audio first, then video), and drops options the model ignores with a warning. Audio requests go through the same resolver and take `abortSignal` (a row without `supports` supports nothing). `aspectRatio: "adaptive"` means "send no ratio": it is never coerced or replaced by the row default, and Gemini, Muse, Kling and Kling O1 omit the field so the model infers it from the references. Every coercion is also logged once per call through `logger.warn`. Gemini image `safetySettings` and `temperature` are sent only when the caller passes them. A reference with a `label` gets a text part with that label right before the image on Gemini image and Omni ("Image 2:", "Here is the brand logo:"). Topaz takes `upscale` (`enhanceModel`, `subjectDetection`, `faceEnhancement` and its creativity/strength) next to `scaleFactor`/`outputFormat`; Seedance takes `watermark`; MiniMax takes `lastFrame` and `safetyChecker`; Seedream 4.5 goes to `4K` and `9:21`. |
|
|
124
|
+
| Keys | Enterprise keys win only when every key the adapter (and its route, e.g. the cloudflare token for a vendor that really goes through the gateway) needs is set on the enterprise tier; a fallback to pro keys is logged once per call. |
|
|
125
|
+
| Routing | Cloudflare AI Gateway for text only. Never for Gemini images or Omni. fal passthrough for geo-blocked regions; the fal direct route submits to the queue and polls, so `job.result({ timeoutMs, signal })` is live. |
|
|
126
|
+
| Retry | One classifier, one policy. Never on content blocks, aborts, or 4xx except 429; SDKs with their own retry (Replicate) run under a single kit attempt; a 429 on a status poll keeps polling. |
|
|
127
|
+
| Errors | `ModelKitError` with `code`, `provider`, `status`, `body`. Gemini `blockReason` and fal `body.detail` are lifted into `body`. A throw with no HTTP status (fetch failed, reset, DNS) is a retryable `network` error on every adapter. |
|
|
128
|
+
| Usage | One event per call with the canonical model id and the row's `usage.unit` (adapters supply the quantity in that unit). Gemini image events carry the token counts too (`inputTokens`/`outputTokens`); Google's raw `usageMetadata` rides on `raw.providerMetadata.google`. Video usage is emitted on completion; Seedance keeps `usage`, `duration`, `framespersecond` and `resolution` from the poll on `raw`. 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. |
|
|
129
|
+
| 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. |
|
|
130
130
|
|
|
131
131
|
## Add a model
|
|
132
132
|
|
|
133
133
|
1. Add a row to `src/catalog/{image,video,text,other}.ts`. Copy `constraints` from the provider docs.
|
|
134
134
|
2. Run `pnpm test`. The catalog test checks id and alias uniqueness.
|
|
135
|
-
3. Bump `version` in `package.json
|
|
135
|
+
3. Bump `version` in `package.json` in a PR that touches only `packages/modelkit/**`.
|
|
136
|
+
Merging it to `dev` runs `modelkit-publish.yml`, which publishes through the npm
|
|
137
|
+
trusted publisher.
|
|
138
|
+
4. Once the version is on npm, bump `@shop-os/modelkit` in every consumer in a second PR.
|
|
139
|
+
|
|
140
|
+
## Consumers
|
|
141
|
+
|
|
142
|
+
Every app takes the published package from npm, not a `workspace:*` link. This is a
|
|
143
|
+
deliberate decision (AGENTS.md §3.1): consumers span three repos and must agree on one
|
|
144
|
+
version, the package bundles provider SDKs the Docker whitelist recipe would have to
|
|
145
|
+
rebuild per app, and the Trigger.dev deploys have no `packages/` in their build context.
|
|
146
|
+
The accepted cost: a kit change and its consumer change never land in one PR, and a
|
|
147
|
+
change here reaches an app only after a publish and a version bump there.
|
|
148
|
+
|
|
149
|
+
| Repo | Apps |
|
|
150
|
+
| ----------------- | -------------------------------------------------------------------------- |
|
|
151
|
+
| shopos-backend-ts | cowork, asset-service, template-service, brand-memory-service, pro-backend |
|
|
152
|
+
| shopos-ui | vibe-api, pro-admin, vibe-triggers |
|
|
153
|
+
| trigger-workflows | the root package (vibe-primitives, geo, model-providers) |
|
|
154
|
+
|
|
155
|
+
Each app owns one lazy kit in a `modelkit.ts` module (`getModelKit()` plus a
|
|
156
|
+
`resetModelKit()` test seam) and reads its keys from the environment. Gemini
|
|
157
|
+
calls go direct everywhere: they need `GOOGLE_API_KEY` (or `GEMINI_API_KEY`) in
|
|
158
|
+
the app's secrets, not a Cloudflare gateway token.
|
|
136
159
|
|
|
137
160
|
## Adapters
|
|
138
161
|
|
|
139
|
-
`ai-sdk-text`, `google-image`, `openai-image`, `google-genai` (Veo, Omni
|
|
162
|
+
`ai-sdk-text`, `google-image`, `openai-image`, `google-genai` (Veo, Omni with `delivery: "uri"`, Lyria 3, Files API media parts), `ark` (Seedream, Seedance), `fal`, `replicate` (images, video, Lyria 2, MMAudio), `prodia`, `higgsfield`, `xai-video`. See `src/adapters/`.
|
|
140
163
|
|
|
141
164
|
## Not in the package
|
|
142
165
|
|