octaflow 0.22.0 → 0.23.0

package/dist/ai/index.d.ts

@@ -1,7 +1,7 @@
 import { E as RetryPolicy, g as TypedWorkflow, h as TypedStepContext, m as TypedStep, nt as Result, tt as FlowErrorShape } from "../index-BURAYZui.js";
 import { n as Logger } from "../logger-BCus3AOa.js";
 import { i as BuildStepContextArgs, o as WorkflowHooks } from "../hooks-BdxIcc92.js";
-import { a as AiProviderMeta, c as DEFAULT_AI_PROVIDER, d as EMBEDDING_PROVIDER_IDS, f as EmbeddingProviderId, i as AiProviderId, l as DEFAULT_EMBEDDING_PROVIDER, m as embeddingDimensionsFor, n as AI_PROVIDER_IDS, o as AiProviderModelOption, p as EmbeddingProviderMeta, r as AiProcessingRegion, s as AiVendorResidency, t as AI_PROVIDERS, u as EMBEDDING_PROVIDERS } from "../provider-registry-bXGOmyeh.js";
+import { C as isSubprocessorResidency, S as embeddingDimensionsFor, _ as EmbeddingProviderMeta, a as AiProcessingRegion, b as OpenAiCompatibleProviderId, c as AiProviderModelOption, d as AiVendorResidency, f as DEFAULT_AI_PROVIDER, g as EmbeddingProviderId, h as EMBEDDING_PROVIDER_IDS, i as AiEndpointResidency, l as AiResidencyError, m as EMBEDDING_PROVIDERS, n as AI_PROVIDER_IDS, o as AiProviderId, p as DEFAULT_EMBEDDING_PROVIDER, r as AiEndpointRegion, s as AiProviderMeta, t as AI_PROVIDERS, u as AiResidencyResult, v as OPENAI_COMPATIBLE_PROVIDER, w as resolveEndpointResidency, x as OpenAiCompatibleProviderMeta, y as OPENAI_COMPATIBLE_PROVIDER_ID } from "../provider-registry-BDKSe_iO.js";
 import { z } from "zod";
 import { EmbeddingModelV4, LanguageModelV4, SharedV4ProviderMetadata } from "@ai-sdk/provider";
 //#region src/ai/instrumented-model.d.ts
@@ -82,6 +82,13 @@ export interface TokenUsage {
  * pinned ids (`mistral-medium-2508`) fall to the fallback.
  */
 export declare const DEFAULT_MODEL_PRICING: Record<string, ModelPricing>;
+/**
+ * A zero row for a model that costs nothing per token, such as one on a server
+ * you run. Add it per model id: `{ ...DEFAULT_MODEL_PRICING, 'qwen3-32b': ZERO_MODEL_PRICING }`.
+ * An id missing from the table prices at the priciest row, which is safe for a
+ * vendor and makes quota refuse a free model long before it should.
+ */
+export declare const ZERO_MODEL_PRICING: ModelPricing;
 export interface CostEstimatorOptions {
   /** Pricing table keyed by model id. Defaults to `DEFAULT_MODEL_PRICING`. */
   pricing?: Record<string, ModelPricing>;
@@ -543,4 +550,4 @@ export declare function thinkingSettingsFor(providerId: string, modelId: string,
   budgetTokens: number;
 }): ThinkingSettings;
 //#endregion
-export { AI_PROVIDERS, AI_PROVIDER_IDS, AiProcessingRegion, AiProviderId, AiProviderMeta, AiProviderModelOption, AiVendorResidency, DEFAULT_AI_PROVIDER, DEFAULT_EMBEDDING_PROVIDER, EMBEDDING_PROVIDERS, EMBEDDING_PROVIDER_IDS, EmbeddingProviderId, EmbeddingProviderMeta, embeddingDimensionsFor };
+export { AI_PROVIDERS, AI_PROVIDER_IDS, AiEndpointRegion, AiEndpointResidency, AiProcessingRegion, AiProviderId, AiProviderMeta, AiProviderModelOption, AiResidencyError, AiResidencyResult, AiVendorResidency, DEFAULT_AI_PROVIDER, DEFAULT_EMBEDDING_PROVIDER, EMBEDDING_PROVIDERS, EMBEDDING_PROVIDER_IDS, EmbeddingProviderId, EmbeddingProviderMeta, OPENAI_COMPATIBLE_PROVIDER, OPENAI_COMPATIBLE_PROVIDER_ID, OpenAiCompatibleProviderId, OpenAiCompatibleProviderMeta, embeddingDimensionsFor, isSubprocessorResidency, resolveEndpointResidency };

package/dist/ai/index.js

@@ -1,6 +1,6 @@
 import { S as ok, b as noopLogger, f as defineStep, l as buildWorkflow, x as err } from "../core-DNWPwFaE.js";
 import { a as readRefusalDetails, i as isAiRefusalError, n as REFUSAL_FINISH_REASON, r as createRefusalAwareModel, t as AiRefusalError } from "../refusal-BsL2HPDb.js";
-import { a as EMBEDDING_PROVIDERS, i as DEFAULT_EMBEDDING_PROVIDER, n as AI_PROVIDER_IDS, o as EMBEDDING_PROVIDER_IDS, r as DEFAULT_AI_PROVIDER, s as embeddingDimensionsFor, t as AI_PROVIDERS } from "../provider-registry-DcRDsjtT.js";
+import { a as EMBEDDING_PROVIDERS, c as OPENAI_COMPATIBLE_PROVIDER_ID, d as resolveEndpointResidency, i as DEFAULT_EMBEDDING_PROVIDER, l as embeddingDimensionsFor, n as AI_PROVIDER_IDS, o as EMBEDDING_PROVIDER_IDS, r as DEFAULT_AI_PROVIDER, s as OPENAI_COMPATIBLE_PROVIDER, t as AI_PROVIDERS, u as isSubprocessorResidency } from "../provider-registry-DHL-Ed-L.js";
 import { wrapEmbeddingModel, wrapLanguageModel } from "ai";
 //#region src/ai/instrumented-model.ts
 function createUsageAccumulator() {
@@ -266,6 +266,18 @@ const DEFAULT_MODEL_PRICING = {
 		cacheWritePerMillion: 0
 	}
 };
+/**
+* A zero row for a model that costs nothing per token, such as one on a server
+* you run. Add it per model id: `{ ...DEFAULT_MODEL_PRICING, 'qwen3-32b': ZERO_MODEL_PRICING }`.
+* An id missing from the table prices at the priciest row, which is safe for a
+* vendor and makes quota refuse a free model long before it should.
+*/
+const ZERO_MODEL_PRICING = Object.freeze({
+	inputPerMillion: 0,
+	outputPerMillion: 0,
+	cacheReadPerMillion: 0,
+	cacheWritePerMillion: 0
+});
 function priciest(pricing) {
 	let best;
 	for (const p of Object.values(pricing)) if (!best || p.outputPerMillion > best.outputPerMillion) best = p;
@@ -650,4 +662,4 @@ function thinkingSettingsFor(providerId, modelId, opts) {
 	return { temperature: opts.temperature };
 }
 //#endregion
-export { AI_PROVIDERS, AI_PROVIDER_IDS, AiRefusalError, DEFAULT_AI_PROVIDER, DEFAULT_AI_QUOTA, DEFAULT_EMBEDDING_PROVIDER, DEFAULT_MODEL_PRICING, EMBEDDING_PROVIDERS, EMBEDDING_PROVIDER_IDS, REFUSAL_FINISH_REASON, anthropicThinkingSettings, buildAiWorkflow, createAiQuotaService, createAiUsageAggregationService, createAiWorkflowHooks, createCostEstimator, createEmbeddingUsageAccumulator, createInstrumentedEmbeddingModel, createInstrumentedModel, createRefusalAwareModel, createUsageAccumulator, defineAiStep, embeddingDimensionsFor, estimateCostMicros, isAiRefusalError, readRefusalDetails, supportsAdaptiveThinking, supportsToolSearch, thinkingSettingsFor };
+export { AI_PROVIDERS, AI_PROVIDER_IDS, AiRefusalError, DEFAULT_AI_PROVIDER, DEFAULT_AI_QUOTA, DEFAULT_EMBEDDING_PROVIDER, DEFAULT_MODEL_PRICING, EMBEDDING_PROVIDERS, EMBEDDING_PROVIDER_IDS, OPENAI_COMPATIBLE_PROVIDER, OPENAI_COMPATIBLE_PROVIDER_ID, REFUSAL_FINISH_REASON, ZERO_MODEL_PRICING, anthropicThinkingSettings, buildAiWorkflow, createAiQuotaService, createAiUsageAggregationService, createAiWorkflowHooks, createCostEstimator, createEmbeddingUsageAccumulator, createInstrumentedEmbeddingModel, createInstrumentedModel, createRefusalAwareModel, createUsageAccumulator, defineAiStep, embeddingDimensionsFor, estimateCostMicros, isAiRefusalError, isSubprocessorResidency, readRefusalDetails, resolveEndpointResidency, supportsAdaptiveThinking, supportsToolSearch, thinkingSettingsFor };

package/dist/ai/providers/index.d.ts

@@ -1,4 +1,4 @@
-import { f as EmbeddingProviderId, i as AiProviderId } from "../../provider-registry-bXGOmyeh.js";
+import { b as OpenAiCompatibleProviderId, g as EmbeddingProviderId, i as AiEndpointResidency, o as AiProviderId } from "../../provider-registry-BDKSe_iO.js";
 import { EmbeddingModelV4, LanguageModelV4 } from "@ai-sdk/provider";
 //#region src/ai/providers/index.d.ts
 export type LanguageModelFactory = (modelId: string) => LanguageModelV4;
@@ -66,4 +66,81 @@ export interface LazyEmbeddingModelMeta {
  * next call rather than cached.
  */
 export declare function createLazyEmbeddingModel(meta: LazyEmbeddingModelMeta, load: () => Promise<EmbeddingModelV4>): EmbeddingModelV4;
+export type AiProviderConfigErrorKey = 'ai_residency_undeclared' | 'ai_residency_invalid' | 'ai_base_url_invalid' | 'ai_model_required' | 'ai_embedding_dimensions_invalid';
+/**
+ * A provider configuration that cannot work. Thrown before any SDK is loaded
+ * or any request is made: it is a deployment mistake, found at wiring time.
+ */
+export declare class AiProviderConfigError extends Error {
+  readonly key: AiProviderConfigErrorKey;
+  constructor(key: AiProviderConfigErrorKey, message: string);
+}
+export interface OpenAiCompatibleEndpointConfig {
+  /** The API root including its version segment, e.g. `http://vllm.ai.svc:8000/v1`. Required: there is no default host. */
+  baseUrl: string;
+  /** Sent as `Authorization: Bearer …` when set. Most self-hosted servers need none. */
+  apiKey?: string;
+  /** Where the endpoint processes payloads. Required, validated by `resolveEndpointResidency`. */
+  residency: AiEndpointResidency;
+  /** Reported as the model's `provider`. Defaults to `openai-compatible`. */
+  name?: string;
+  headers?: Record<string, string>;
+  /** A fetch implementation, for middleware or tests. Defaults to the global `fetch`. */
+  fetch?: typeof globalThis.fetch;
+}
+export interface OpenAiCompatibleModelProviderConfig extends OpenAiCompatibleEndpointConfig {
+  /** The model a call without an id uses. Required: a server you run has no registry default. */
+  defaultModel: string;
+  /** Cheap model for classifier-style passes. Defaults to `defaultModel`. */
+  classifierModel?: string;
+  /** Set when the server enforces a JSON schema on output (vLLM does); otherwise `generateObject` uses JSON mode. */
+  structuredOutputs?: boolean;
+  /**
+   * Ask for token usage on streamed responses. Defaults to `true`, because the
+   * instrumented model meters what the stream reports and a stream without it
+   * reports zero tokens. Turn it off only for a server that rejects the option.
+   */
+  includeUsage?: boolean;
+}
+export interface OpenAiCompatibleModelProvider {
+  providerId: OpenAiCompatibleProviderId;
+  /** The declared residency, validated — what a badge or an audit record shows. */
+  residency: AiEndpointResidency;
+  classifierModelId: string;
+  /** A Chat Completions model, wrapped for refusal detection like the vendor ones. */
+  languageModel(modelId?: string): LanguageModelV4;
+}
+export interface OpenAiCompatibleEmbeddingProviderConfig extends OpenAiCompatibleEndpointConfig {
+  model: string;
+  /**
+   * The model's vector width, which must match your `vector(N)` column.
+   * Required: a guessed width, such as the registry's 1536 fallback, silently
+   * breaks a 1024-wide model like `bge-m3` at the first insert.
+   */
+  dimensions: number;
+}
+export interface OpenAiCompatibleEmbeddingProvider {
+  providerId: OpenAiCompatibleProviderId;
+  residency: AiEndpointResidency;
+  modelId: string;
+  dimensions: number;
+  embeddingModel(): EmbeddingModelV4;
+}
+/**
+ * A model server you run, or any host with the OpenAI-compatible API, as
+ * refusal-aware models. Language models go through **Chat Completions**, which
+ * is what vLLM, Ollama and llama.cpp speak — not the Responses API that
+ * `@ai-sdk/openai` defaults to.
+ *
+ * ```ts
+ * const models = await createOpenAiCompatibleModelProvider({
+ *   baseUrl: 'http://vllm.ai.svc:8000/v1',
+ *   residency: { region: 'self-hosted' },
+ *   defaultModel: 'qwen3-32b',
+ * });
+ * ```
+ */
+export declare function createOpenAiCompatibleModelProvider(config: OpenAiCompatibleModelProviderConfig): Promise<OpenAiCompatibleModelProvider>;
+/** An embedding model on an OpenAI-compatible endpoint, with its declared width. */
+export declare function createOpenAiCompatibleEmbeddingProvider(config: OpenAiCompatibleEmbeddingProviderConfig): Promise<OpenAiCompatibleEmbeddingProvider>;
 //#endregion

package/dist/ai/providers/index.js

@@ -1,5 +1,5 @@
 import { r as createRefusalAwareModel } from "../../refusal-BsL2HPDb.js";
-import { a as EMBEDDING_PROVIDERS, t as AI_PROVIDERS } from "../../provider-registry-DcRDsjtT.js";
+import { a as EMBEDDING_PROVIDERS, c as OPENAI_COMPATIBLE_PROVIDER_ID, d as resolveEndpointResidency, t as AI_PROVIDERS } from "../../provider-registry-DHL-Ed-L.js";
 //#region src/ai/providers/index.ts
 const LLM_LOADERS = {
 	anthropic: async (apiKey, baseURL) => {
@@ -103,5 +103,87 @@ function createLazyEmbeddingModel(meta, load) {
 		doEmbed: (options) => model().then((m) => m.doEmbed(options))
 	};
 }
+/**
+* A provider configuration that cannot work. Thrown before any SDK is loaded
+* or any request is made: it is a deployment mistake, found at wiring time.
+*/
+var AiProviderConfigError = class extends Error {
+	key;
+	constructor(key, message) {
+		super(message);
+		this.name = "AiProviderConfigError";
+		this.key = key;
+	}
+};
+function checkEndpoint(config) {
+	const residency = resolveEndpointResidency(config.residency);
+	if (!residency.ok) throw new AiProviderConfigError(residency.error.key, residency.error.message);
+	let url;
+	try {
+		url = new URL(config.baseUrl);
+	} catch {
+		url = void 0;
+	}
+	if (url === void 0 || url.protocol !== "http:" && url.protocol !== "https:") throw new AiProviderConfigError("ai_base_url_invalid", `baseUrl must be an absolute http(s) URL, got ${JSON.stringify(config.baseUrl)}`);
+	return residency.value;
+}
+function requireModel(modelId, field) {
+	if (typeof modelId !== "string" || modelId.trim() === "") throw new AiProviderConfigError("ai_model_required", `${field} is required for an OpenAI-compatible endpoint`);
+	return modelId;
+}
+async function loadOpenAiCompatible(config, options = {}) {
+	const { createOpenAICompatible } = await import("@ai-sdk/openai-compatible");
+	return createOpenAICompatible({
+		name: config.name ?? "openai-compatible",
+		baseURL: config.baseUrl.replace(/\/+$/, ""),
+		apiKey: config.apiKey,
+		headers: config.headers,
+		fetch: config.fetch,
+		includeUsage: options.includeUsage ?? true,
+		supportsStructuredOutputs: options.structuredOutputs
+	});
+}
+/**
+* A model server you run, or any host with the OpenAI-compatible API, as
+* refusal-aware models. Language models go through **Chat Completions**, which
+* is what vLLM, Ollama and llama.cpp speak — not the Responses API that
+* `@ai-sdk/openai` defaults to.
+*
+* ```ts
+* const models = await createOpenAiCompatibleModelProvider({
+*   baseUrl: 'http://vllm.ai.svc:8000/v1',
+*   residency: { region: 'self-hosted' },
+*   defaultModel: 'qwen3-32b',
+* });
+* ```
+*/
+async function createOpenAiCompatibleModelProvider(config) {
+	const residency = checkEndpoint(config);
+	const defaultModel = requireModel(config.defaultModel, "defaultModel");
+	const provider = await loadOpenAiCompatible(config, {
+		structuredOutputs: config.structuredOutputs,
+		includeUsage: config.includeUsage
+	});
+	return {
+		providerId: OPENAI_COMPATIBLE_PROVIDER_ID,
+		residency,
+		classifierModelId: config.classifierModel ?? defaultModel,
+		languageModel: (modelId) => createRefusalAwareModel(provider.chatModel(modelId ?? defaultModel))
+	};
+}
+/** An embedding model on an OpenAI-compatible endpoint, with its declared width. */
+async function createOpenAiCompatibleEmbeddingProvider(config) {
+	const residency = checkEndpoint(config);
+	const modelId = requireModel(config.model, "model");
+	if (!Number.isInteger(config.dimensions) || config.dimensions <= 0) throw new AiProviderConfigError("ai_embedding_dimensions_invalid", `dimensions must be a positive integer matching your vector column, got ${JSON.stringify(config.dimensions)}`);
+	const provider = await loadOpenAiCompatible(config);
+	return {
+		providerId: OPENAI_COMPATIBLE_PROVIDER_ID,
+		residency,
+		modelId,
+		dimensions: config.dimensions,
+		embeddingModel: () => provider.embeddingModel(modelId)
+	};
+}
 //#endregion
-export { createEmbeddingModelFactory, createEmbeddingModelProvider, createLanguageModelFactory, createLanguageModelProvider, createLazyEmbeddingModel };
+export { AiProviderConfigError, createEmbeddingModelFactory, createEmbeddingModelProvider, createLanguageModelFactory, createLanguageModelProvider, createLazyEmbeddingModel, createOpenAiCompatibleEmbeddingProvider, createOpenAiCompatibleModelProvider };

package/dist/ai/registry.d.ts

@@ -1,2 +1,2 @@
-import { a as AiProviderMeta, c as DEFAULT_AI_PROVIDER, d as EMBEDDING_PROVIDER_IDS, f as EmbeddingProviderId, i as AiProviderId, l as DEFAULT_EMBEDDING_PROVIDER, m as embeddingDimensionsFor, n as AI_PROVIDER_IDS, o as AiProviderModelOption, p as EmbeddingProviderMeta, r as AiProcessingRegion, s as AiVendorResidency, t as AI_PROVIDERS, u as EMBEDDING_PROVIDERS } from "../provider-registry-bXGOmyeh.js";
-export { AI_PROVIDERS, AI_PROVIDER_IDS, AiProcessingRegion, AiProviderId, AiProviderMeta, AiProviderModelOption, AiVendorResidency, DEFAULT_AI_PROVIDER, DEFAULT_EMBEDDING_PROVIDER, EMBEDDING_PROVIDERS, EMBEDDING_PROVIDER_IDS, EmbeddingProviderId, EmbeddingProviderMeta, embeddingDimensionsFor };
+import { C as isSubprocessorResidency, S as embeddingDimensionsFor, _ as EmbeddingProviderMeta, a as AiProcessingRegion, b as OpenAiCompatibleProviderId, c as AiProviderModelOption, d as AiVendorResidency, f as DEFAULT_AI_PROVIDER, g as EmbeddingProviderId, h as EMBEDDING_PROVIDER_IDS, i as AiEndpointResidency, l as AiResidencyError, m as EMBEDDING_PROVIDERS, n as AI_PROVIDER_IDS, o as AiProviderId, p as DEFAULT_EMBEDDING_PROVIDER, r as AiEndpointRegion, s as AiProviderMeta, t as AI_PROVIDERS, u as AiResidencyResult, v as OPENAI_COMPATIBLE_PROVIDER, w as resolveEndpointResidency, x as OpenAiCompatibleProviderMeta, y as OPENAI_COMPATIBLE_PROVIDER_ID } from "../provider-registry-BDKSe_iO.js";
+export { AI_PROVIDERS, AI_PROVIDER_IDS, AiEndpointRegion, AiEndpointResidency, AiProcessingRegion, AiProviderId, AiProviderMeta, AiProviderModelOption, AiResidencyError, AiResidencyResult, AiVendorResidency, DEFAULT_AI_PROVIDER, DEFAULT_EMBEDDING_PROVIDER, EMBEDDING_PROVIDERS, EMBEDDING_PROVIDER_IDS, EmbeddingProviderId, EmbeddingProviderMeta, OPENAI_COMPATIBLE_PROVIDER, OPENAI_COMPATIBLE_PROVIDER_ID, OpenAiCompatibleProviderId, OpenAiCompatibleProviderMeta, embeddingDimensionsFor, isSubprocessorResidency, resolveEndpointResidency };

package/dist/ai/registry.js

@@ -1,2 +1,2 @@
-import { a as EMBEDDING_PROVIDERS, i as DEFAULT_EMBEDDING_PROVIDER, n as AI_PROVIDER_IDS, o as EMBEDDING_PROVIDER_IDS, r as DEFAULT_AI_PROVIDER, s as embeddingDimensionsFor, t as AI_PROVIDERS } from "../provider-registry-DcRDsjtT.js";
-export { AI_PROVIDERS, AI_PROVIDER_IDS, DEFAULT_AI_PROVIDER, DEFAULT_EMBEDDING_PROVIDER, EMBEDDING_PROVIDERS, EMBEDDING_PROVIDER_IDS, embeddingDimensionsFor };
+import { a as EMBEDDING_PROVIDERS, c as OPENAI_COMPATIBLE_PROVIDER_ID, d as resolveEndpointResidency, i as DEFAULT_EMBEDDING_PROVIDER, l as embeddingDimensionsFor, n as AI_PROVIDER_IDS, o as EMBEDDING_PROVIDER_IDS, r as DEFAULT_AI_PROVIDER, s as OPENAI_COMPATIBLE_PROVIDER, t as AI_PROVIDERS, u as isSubprocessorResidency } from "../provider-registry-DHL-Ed-L.js";
+export { AI_PROVIDERS, AI_PROVIDER_IDS, DEFAULT_AI_PROVIDER, DEFAULT_EMBEDDING_PROVIDER, EMBEDDING_PROVIDERS, EMBEDDING_PROVIDER_IDS, OPENAI_COMPATIBLE_PROVIDER, OPENAI_COMPATIBLE_PROVIDER_ID, embeddingDimensionsFor, isSubprocessorResidency, resolveEndpointResidency };

package/dist/{provider-registry-bXGOmyeh.d.ts → provider-registry-BDKSe_iO.d.ts}

@@ -72,10 +72,57 @@ interface EmbeddingProviderMeta {
 }
 declare const EMBEDDING_PROVIDERS: Record<EmbeddingProviderId, EmbeddingProviderMeta>;
 /**
- * Vector dimensions for an embedding model id. Unknown ids fall back to
- * `fallback` (default 1536, the common OpenAI-compatible dimension) so
- * free-form model ids keep a working column.
+ * Vector dimensions for an embedding model id in the vendor lists above.
+ * Unknown ids fall back to `fallback` (default 1536) so free-form vendor model
+ * ids keep a working column. A self-hosted model never goes through this
+ * guess: its width is declared (`createOpenAiCompatibleEmbeddingProvider`'s
+ * `dimensions`), because a wrong one fails at the first `vector(N)` insert.
  */
 declare function embeddingDimensionsFor(modelId: string, fallback?: number): number;
+/**
+ * Where a model endpoint the *deployment* names processes payloads. A vendor in
+ * the lists above has a fixed residency; an OpenAI-compatible endpoint does not:
+ * the same client talks to vLLM in your own cluster, to Ollama on a workstation,
+ * or to a hosted inference vendor. So whoever deploys it declares the residency,
+ * and `'self-hosted'` is the value that adds no subprocessor.
+ *
+ * Kept apart from {@link AiProcessingRegion} on purpose: that union describes the
+ * vendors above, and a picker that iterates `AI_PROVIDERS` keeps working unchanged.
+ */
+type AiEndpointRegion = AiProcessingRegion | 'self-hosted';
+/** `{ region: 'self-hosted' }` for infrastructure you operate; a vendor's full residency otherwise. */
+type AiEndpointResidency = {
+  region: 'self-hosted';
+} | AiVendorResidency;
+declare const OPENAI_COMPATIBLE_PROVIDER_ID = "openai-compatible";
+type OpenAiCompatibleProviderId = typeof OPENAI_COMPATIBLE_PROVIDER_ID;
+interface OpenAiCompatibleProviderMeta {
+  id: OpenAiCompatibleProviderId;
+  label: string;
+  /** Never fixed in the registry — see {@link resolveEndpointResidency}. */
+  residency: 'declared-by-deployment';
+}
+declare const OPENAI_COMPATIBLE_PROVIDER: OpenAiCompatibleProviderMeta;
+interface AiResidencyError {
+  key: 'ai_residency_undeclared' | 'ai_residency_invalid';
+  message: string;
+}
+type AiResidencyResult = {
+  ok: true;
+  value: AiEndpointResidency;
+} | {
+  ok: false;
+  error: AiResidencyError;
+};
+/**
+ * Validates a residency declared by a deployment — from config, an env file, a
+ * database row — before any call is made. A missing one is
+ * `ai_residency_undeclared`: an endpoint whose data location nobody stated is
+ * refused, never assumed to be local. A vendor region needs the legal name and
+ * the ISO country a subprocessor annex prints.
+ */
+declare function resolveEndpointResidency(declared: unknown): AiResidencyResult;
+/** Whether calling an endpoint with this residency makes its operator a subprocessor. A self-hosted endpoint does not. */
+declare function isSubprocessorResidency(residency: AiEndpointResidency): boolean;
 //#endregion
-export { AiProviderMeta as a, DEFAULT_AI_PROVIDER as c, EMBEDDING_PROVIDER_IDS as d, EmbeddingProviderId as f, AiProviderId as i, DEFAULT_EMBEDDING_PROVIDER as l, embeddingDimensionsFor as m, AI_PROVIDER_IDS as n, AiProviderModelOption as o, EmbeddingProviderMeta as p, AiProcessingRegion as r, AiVendorResidency as s, AI_PROVIDERS as t, EMBEDDING_PROVIDERS as u };
+export { isSubprocessorResidency as C, embeddingDimensionsFor as S, EmbeddingProviderMeta as _, AiProcessingRegion as a, OpenAiCompatibleProviderId as b, AiProviderModelOption as c, AiVendorResidency as d, DEFAULT_AI_PROVIDER as f, EmbeddingProviderId as g, EMBEDDING_PROVIDER_IDS as h, AiEndpointResidency as i, AiResidencyError as l, EMBEDDING_PROVIDERS as m, AI_PROVIDER_IDS as n, AiProviderId as o, DEFAULT_EMBEDDING_PROVIDER as p, AiEndpointRegion as r, AiProviderMeta as s, AI_PROVIDERS as t, AiResidencyResult as u, OPENAI_COMPATIBLE_PROVIDER as v, resolveEndpointResidency as w, OpenAiCompatibleProviderMeta as x, OPENAI_COMPATIBLE_PROVIDER_ID as y };

package/dist/{provider-registry-DcRDsjtT.js → provider-registry-DHL-Ed-L.js}

@@ -106,9 +106,11 @@ const EMBEDDING_PROVIDERS = {
 	}
 };
 /**
-* Vector dimensions for an embedding model id. Unknown ids fall back to
-* `fallback` (default 1536, the common OpenAI-compatible dimension) so
-* free-form model ids keep a working column.
+* Vector dimensions for an embedding model id in the vendor lists above.
+* Unknown ids fall back to `fallback` (default 1536) so free-form vendor model
+* ids keep a working column. A self-hosted model never goes through this
+* guess: its width is declared (`createOpenAiCompatibleEmbeddingProvider`'s
+* `dimensions`), because a wrong one fails at the first `vector(N)` insert.
 */
 function embeddingDimensionsFor(modelId, fallback = 1536) {
 	for (const meta of Object.values(EMBEDDING_PROVIDERS)) {
@@ -117,5 +119,57 @@ function embeddingDimensionsFor(modelId, fallback = 1536) {
 	}
 	return fallback;
 }
+const OPENAI_COMPATIBLE_PROVIDER_ID = "openai-compatible";
+const OPENAI_COMPATIBLE_PROVIDER = {
+	id: OPENAI_COMPATIBLE_PROVIDER_ID,
+	label: "OpenAI-compatible endpoint",
+	residency: "declared-by-deployment"
+};
+/**
+* Validates a residency declared by a deployment — from config, an env file, a
+* database row — before any call is made. A missing one is
+* `ai_residency_undeclared`: an endpoint whose data location nobody stated is
+* refused, never assumed to be local. A vendor region needs the legal name and
+* the ISO country a subprocessor annex prints.
+*/
+function resolveEndpointResidency(declared) {
+	if (declared === void 0 || declared === null) return {
+		ok: false,
+		error: {
+			key: "ai_residency_undeclared",
+			message: "an OpenAI-compatible endpoint needs a declared residency: { region: \"self-hosted\" }, or a vendor region with its legalName and country"
+		}
+	};
+	if (typeof declared !== "object") return invalidResidency("residency must be an object");
+	const { region, legalName, country } = declared;
+	if (region === "self-hosted") return {
+		ok: true,
+		value: { region: "self-hosted" }
+	};
+	if (region !== "eu" && region !== "third-country") return invalidResidency(`unknown region ${JSON.stringify(region)}; expected "self-hosted", "eu" or "third-country"`);
+	if (typeof legalName !== "string" || legalName.trim() === "") return invalidResidency(`region "${region}" names a vendor, so legalName is required`);
+	if (typeof country !== "string" || !/^[A-Z]{2}$/.test(country)) return invalidResidency(`region "${region}" needs country as an ISO 3166-1 alpha-2 code`);
+	return {
+		ok: true,
+		value: {
+			region,
+			legalName,
+			country
+		}
+	};
+}
+function invalidResidency(message) {
+	return {
+		ok: false,
+		error: {
+			key: "ai_residency_invalid",
+			message
+		}
+	};
+}
+/** Whether calling an endpoint with this residency makes its operator a subprocessor. A self-hosted endpoint does not. */
+function isSubprocessorResidency(residency) {
+	return residency.region !== "self-hosted";
+}
 //#endregion
-export { EMBEDDING_PROVIDERS as a, DEFAULT_EMBEDDING_PROVIDER as i, AI_PROVIDER_IDS as n, EMBEDDING_PROVIDER_IDS as o, DEFAULT_AI_PROVIDER as r, embeddingDimensionsFor as s, AI_PROVIDERS as t };
+export { EMBEDDING_PROVIDERS as a, OPENAI_COMPATIBLE_PROVIDER_ID as c, resolveEndpointResidency as d, DEFAULT_EMBEDDING_PROVIDER as i, embeddingDimensionsFor as l, AI_PROVIDER_IDS as n, EMBEDDING_PROVIDER_IDS as o, DEFAULT_AI_PROVIDER as r, OPENAI_COMPATIBLE_PROVIDER as s, AI_PROVIDERS as t, isSubprocessorResidency as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octaflow",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Durable DAG workflow engine: Zod-typed steps over Postgres + pg-boss, with an optional AI add-on (token/cost/quota). Layered single package.",
   "license": "MIT",
   "type": "module",
@@ -71,6 +71,7 @@
     "@ai-sdk/anthropic": "^4.0.0",
     "@ai-sdk/mistral": "^4.0.0",
     "@ai-sdk/openai": "^4.0.0",
+    "@ai-sdk/openai-compatible": "^3.0.0",
     "@ai-sdk/provider": "^4.0.0",
     "ai": "^7.0.0",
     "pg": "^8.0.0",
@@ -88,6 +89,9 @@
     "@ai-sdk/openai": {
       "optional": true
     },
+    "@ai-sdk/openai-compatible": {
+      "optional": true
+    },
     "@ai-sdk/provider": {
       "optional": true
     },
@@ -105,6 +109,7 @@
     "@ai-sdk/anthropic": "^4.0.52",
     "@ai-sdk/mistral": "^4.0.42",
     "@ai-sdk/openai": "^4.0.65",
+    "@ai-sdk/openai-compatible": "^3.0.48",
     "@ai-sdk/provider": "^4.0.13",
     "@testcontainers/postgresql": "^12.1.0",
     "@types/node": "^26.5.1",