@daihum/ai-model-contracts 0.1.0

package/README.md

@@ -0,0 +1,29 @@
+# @daihum/ai-model-contracts
+
+Pure, serializable **model-operation payload contracts** for DAIHUM AI. The stable
+vocabulary leaf: zero dependencies, no behavior, no environment assumptions.
+
+Subpaths: `./chat`, `./embedding`, `./candidate-rank`, `./tools`, `./usage`,
+`./embedding-compat`. Prefer subpath imports over the root barrel.
+
+## What this package is NOT
+
+By rule (boundary gate R1/R7/R8) it carries **only** model I/O. It must never grow:
+
+- `routePlan` or any routing/provider-selection structure — that lives in
+  `@daihum/ai-routing`, which lowers a route plan into resolved
+  `providerId`/`modelId`/`routeId` + a provider call context.
+- execution/authority context (workspaceId, actorId, dataClass, …) — that travels
+  in the provider call context (`@daihum/ai-provider-contracts`), never in a payload.
+- provider registries/interfaces/errors — `@daihum/ai-provider-contracts`.
+- secrets, catalog, pricing, cost, audit, config, runtime code, fetch/fs, RAG hits.
+
+Test: these types should be copy-pasteable into another repo as plain TypeScript
+without bringing behavior, environment, provider knowledge, or product assumptions.
+
+## candidate-rank vs rerank
+
+`candidate-rank` is the **model-level** ranking op (query + candidate texts → ids/
+order/scores), a peer of chat/embedding. The word **rerank** is reserved for the
+RAG pipeline stage in `@daihum/ai-rag`. Candidates are `{ candidateId, text }` only
+(no metadata backdoor); result `score` is optional (`scoreKind` documents its origin).

package/dist/candidate-rank-CFpxmTMM.d.ts

@@ -0,0 +1,65 @@
+import { t as DaihumAiUsage } from "./usage-Db6aaBEO.js";
+
+//#region src/candidate-rank.d.ts
+
+/**
+ * Model-level candidate ranking (renamed from the former "rerank" model op;
+ * "rerank" is reserved for the RAG pipeline stage in @daihum/ai-rag).
+ *
+ * Operation shape: query + candidate texts -> candidate ids / order / scores.
+ * This is a peer of chat and embedding, NOT an optimization of chat — some
+ * runtimes serve it natively (e.g. an OpenRouter /rerank endpoint), others via
+ * a candidate-rank-from-chat adapter (@daihum/ai-candidate-rank-adapters).
+ */
+/**
+ * A candidate to rank. Model-visible payload ONLY: an opaque id + the text the
+ * model sees. Deliberately has NO `metadata?: unknown` — that would be a
+ * fat-envelope backdoor for hydrated hits / provenance / authority / secrets.
+ * Callers map their own source ids through *ephemeral* candidateIds.
+ */
+interface DaihumAiCandidateRankCandidate {
+  readonly candidateId: string;
+  readonly text: string;
+}
+interface DaihumAiCandidateRankRequest {
+  readonly requestId?: string;
+  readonly providerId?: string;
+  readonly modelId?: string;
+  readonly routeId?: string;
+  readonly query: string;
+  readonly candidates: readonly DaihumAiCandidateRankCandidate[];
+  /** If set, the response MAY be partial (top-K). Omitted candidates are not errors. */
+  readonly topK?: number;
+  readonly signal?: AbortSignal;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Where a result's score came from. A chat-prompted ranker can order reliably
+ * but cannot calibrate a score; in that case `score` is omitted (rank is
+ * authoritative) and the RAG blend stage derives a score from rank. */
+type DaihumAiCandidateRankScoreKind = "provider" | "normalized" | "rank-derived";
+interface DaihumAiCandidateRankResult {
+  readonly candidateId: string;
+  /** 1-based, unique within the response. Response order SHOULD match rank ascending. */
+  readonly rank: number;
+  /** Optional on purpose — see DaihumAiCandidateRankScoreKind. */
+  readonly score?: number;
+  readonly scoreKind?: DaihumAiCandidateRankScoreKind;
+}
+interface DaihumAiCandidateRankWarning {
+  readonly code: string;
+  readonly message?: string;
+  readonly candidateId?: string;
+}
+interface DaihumAiCandidateRankResponse {
+  readonly providerId: string;
+  readonly modelId: string;
+  readonly routeId?: string;
+  readonly results: readonly DaihumAiCandidateRankResult[];
+  readonly usage?: DaihumAiUsage;
+  readonly warnings?: readonly DaihumAiCandidateRankWarning[];
+  readonly rawResponse?: unknown;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+//#endregion
+export { DaihumAiCandidateRankScoreKind as a, DaihumAiCandidateRankResult as i, DaihumAiCandidateRankRequest as n, DaihumAiCandidateRankWarning as o, DaihumAiCandidateRankResponse as r, DaihumAiCandidateRankCandidate as t };
+//# sourceMappingURL=candidate-rank-CFpxmTMM.d.ts.map

package/dist/candidate-rank.d.ts

@@ -0,0 +1,3 @@
+import "./usage-Db6aaBEO.js";
+import { a as DaihumAiCandidateRankScoreKind, i as DaihumAiCandidateRankResult, n as DaihumAiCandidateRankRequest, o as DaihumAiCandidateRankWarning, r as DaihumAiCandidateRankResponse, t as DaihumAiCandidateRankCandidate } from "./candidate-rank-CFpxmTMM.js";
+export { DaihumAiCandidateRankCandidate, DaihumAiCandidateRankRequest, DaihumAiCandidateRankResponse, DaihumAiCandidateRankResult, DaihumAiCandidateRankScoreKind, DaihumAiCandidateRankWarning };

package/dist/candidate-rank.js

@@ -0,0 +1 @@
+import "./candidate-rank-DYi3Kcdp.js";

package/dist/chat-BZgfxuBU.d.ts

@@ -0,0 +1,116 @@
+import { t as DaihumAiUsage } from "./usage-Db6aaBEO.js";
+import { a as DaihumAiToolDefinition, i as DaihumAiToolChoice, n as DaihumAiPartialToolCall, r as DaihumAiToolCall } from "./tools-VkZPo3Sc.js";
+
+//#region src/chat.d.ts
+type DaihumAiMessageRole = "system" | "user" | "assistant" | "tool";
+interface DaihumAiTextPart {
+  readonly type: "text";
+  readonly text: string;
+}
+interface DaihumAiImagePart {
+  readonly type: "image";
+  readonly image: string | URL | Uint8Array | ArrayBuffer;
+  readonly mediaType?: string;
+}
+interface DaihumAiJsonPart {
+  readonly type: "json";
+  readonly value: unknown;
+}
+type DaihumAiContentPart = DaihumAiTextPart | DaihumAiImagePart | DaihumAiJsonPart | (Readonly<Record<string, unknown>> & {
+  readonly type: string;
+});
+interface DaihumAiMessage {
+  readonly role: DaihumAiMessageRole;
+  readonly content?: string | readonly DaihumAiContentPart[];
+  readonly name?: string;
+  readonly toolCallId?: string;
+  readonly toolCalls?: readonly DaihumAiToolCall[];
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+type DaihumAiFinishReason = "stop" | "length" | "tool-calls" | "content-filter" | "error" | "unknown" | (string & {});
+/** Recommended shape for DaihumAiChatRequest.responseFormat (the field stays
+ * `unknown` for adapter flexibility; adapters narrow against this). */
+type DaihumAiResponseFormat = Readonly<{
+  kind: "text";
+}> | Readonly<{
+  kind: "json";
+}> | Readonly<{
+  kind: "json-schema";
+  name?: string;
+  strict?: boolean;
+  schema: Readonly<Record<string, unknown>>;
+}>;
+/**
+ * Pure chat model-operation payload. Carries model I/O only.
+ *
+ * NOT present (by design — these are NOT model payload):
+ *  - routePlan  -> routing concern; @daihum/ai-routing lowers a route plan into
+ *    providerId/modelId/routeId (resolved below) + a provider call context.
+ *  - execution context (workspaceId/actorId/dataClass/...) -> product authority;
+ *    travels in the provider call context (@daihum/ai-provider-contracts), never here.
+ *
+ * providerId/modelId/routeId are the *already-resolved* execution target hints
+ * (populated by routing before the call), not a route plan.
+ */
+interface DaihumAiChatRequest {
+  readonly requestId?: string;
+  readonly providerId?: string;
+  readonly modelId?: string;
+  readonly routeId?: string;
+  readonly messages: readonly DaihumAiMessage[];
+  readonly tools?: readonly DaihumAiToolDefinition[];
+  readonly toolChoice?: DaihumAiToolChoice;
+  readonly temperature?: number;
+  readonly topP?: number;
+  readonly maxOutputTokens?: number;
+  readonly reasoningBudget?: number;
+  readonly seed?: number;
+  readonly frequencyPenalty?: number;
+  readonly presencePenalty?: number;
+  readonly stopSequences?: readonly string[];
+  readonly responseFormat?: unknown;
+  readonly signal?: AbortSignal;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+type DaihumAiChatResponseKind = "message" | "tool-calls";
+interface DaihumAiChatResponse {
+  readonly kind: DaihumAiChatResponseKind;
+  readonly providerId: string;
+  readonly modelId: string;
+  readonly routeId?: string;
+  readonly text?: string;
+  readonly toolCalls?: readonly DaihumAiToolCall[];
+  readonly finishReason?: DaihumAiFinishReason;
+  readonly usage?: DaihumAiUsage;
+  readonly providerRequestId?: string;
+  readonly rawResponse?: unknown;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+type DaihumAiChatStreamEvent = Readonly<{
+  type: "text-delta";
+  textDelta: string;
+}> | Readonly<{
+  type: "tool-call-start";
+  toolCall: DaihumAiPartialToolCall;
+}> | Readonly<{
+  type: "tool-call-delta";
+  toolCall: DaihumAiPartialToolCall;
+}> | Readonly<{
+  type: "tool-call-end";
+  toolCall: DaihumAiToolCall | DaihumAiPartialToolCall;
+}> | Readonly<{
+  type: "tool-call";
+  toolCall: DaihumAiToolCall;
+}> | Readonly<{
+  type: "reasoning-delta";
+  reasoningDelta: string;
+}> | Readonly<{
+  type: "finish";
+  response: DaihumAiChatResponse;
+}> | Readonly<{
+  type: "error";
+  error: unknown;
+}>;
+//#endregion
+export { DaihumAiContentPart as a, DaihumAiJsonPart as c, DaihumAiResponseFormat as d, DaihumAiTextPart as f, DaihumAiChatStreamEvent as i, DaihumAiMessage as l, DaihumAiChatResponse as n, DaihumAiFinishReason as o, DaihumAiChatResponseKind as r, DaihumAiImagePart as s, DaihumAiChatRequest as t, DaihumAiMessageRole as u };
+//# sourceMappingURL=chat-BZgfxuBU.d.ts.map

package/dist/chat.d.ts

@@ -0,0 +1,4 @@
+import "./usage-Db6aaBEO.js";
+import "./tools-VkZPo3Sc.js";
+import { a as DaihumAiContentPart, c as DaihumAiJsonPart, d as DaihumAiResponseFormat, f as DaihumAiTextPart, i as DaihumAiChatStreamEvent, l as DaihumAiMessage, n as DaihumAiChatResponse, o as DaihumAiFinishReason, r as DaihumAiChatResponseKind, s as DaihumAiImagePart, t as DaihumAiChatRequest, u as DaihumAiMessageRole } from "./chat-BZgfxuBU.js";
+export { DaihumAiChatRequest, DaihumAiChatResponse, DaihumAiChatResponseKind, DaihumAiChatStreamEvent, DaihumAiContentPart, DaihumAiFinishReason, DaihumAiImagePart, DaihumAiJsonPart, DaihumAiMessage, DaihumAiMessageRole, DaihumAiResponseFormat, DaihumAiTextPart };

package/dist/chat.js

@@ -0,0 +1 @@
+import "./chat-BEsGPeX0.js";

package/dist/embedding-B7HPKvpY.d.ts

@@ -0,0 +1,39 @@
+import { t as DaihumAiUsage } from "./usage-Db6aaBEO.js";
+
+//#region src/embedding.d.ts
+
+/**
+ * Pure embedding model-operation payload. Carries model I/O only.
+ * routePlan/execution-context intentionally absent (see chat.ts).
+ */
+interface DaihumAiEmbeddingRequest {
+  readonly requestId?: string;
+  readonly providerId?: string;
+  readonly modelId?: string;
+  readonly routeId?: string;
+  readonly input: string | readonly string[];
+  readonly dimensions?: number;
+  readonly signal?: AbortSignal;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+interface DaihumAiEmbedding {
+  readonly inputIndex: number;
+  readonly vector: Float32Array;
+  readonly dimensions: number;
+  readonly providerId: string;
+  readonly modelId: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+interface DaihumAiEmbeddingResponse {
+  readonly providerId: string;
+  readonly modelId: string;
+  readonly routeId?: string;
+  readonly embeddings: readonly DaihumAiEmbedding[];
+  readonly usage?: DaihumAiUsage;
+  readonly providerRequestId?: string;
+  readonly rawResponse?: unknown;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+//#endregion
+export { DaihumAiEmbeddingRequest as n, DaihumAiEmbeddingResponse as r, DaihumAiEmbedding as t };
+//# sourceMappingURL=embedding-B7HPKvpY.d.ts.map

package/dist/embedding-compat-ClR_h_ED.d.ts

@@ -0,0 +1,23 @@
+//#region src/embedding-compat.d.ts
+interface DaihumAiCompatibilityFingerprintInput {
+  readonly providerId: string;
+  readonly modelId?: string;
+  readonly routeId?: string;
+  readonly dimensions?: number;
+  readonly normalization?: string;
+  readonly distanceMetric?: string;
+  readonly chunkerId?: string;
+  readonly chunkStrategyId?: string;
+  readonly chunkStrategyVersion?: number | string;
+  readonly chunkStrategyConfigHash?: string;
+  readonly extra?: Readonly<Record<string, unknown>>;
+}
+interface DaihumAiCompatibilityFingerprint {
+  readonly algorithm: "daihum-ai.compatibility.v1";
+  readonly value: string;
+  readonly basis: DaihumAiCompatibilityFingerprintInput;
+}
+declare function buildDaihumAiCompatibilityFingerprint(input: DaihumAiCompatibilityFingerprintInput): DaihumAiCompatibilityFingerprint;
+//#endregion
+export { DaihumAiCompatibilityFingerprintInput as n, buildDaihumAiCompatibilityFingerprint as r, DaihumAiCompatibilityFingerprint as t };
+//# sourceMappingURL=embedding-compat-ClR_h_ED.d.ts.map

package/dist/embedding-compat-Ov4JeVna.js

@@ -0,0 +1,54 @@
+//#region src/internal/normalize.ts
+function normalizeId(value) {
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : void 0;
+}
+function normalizeRequiredId(value, fieldName) {
+	const normalized = normalizeId(value);
+	if (!normalized) throw new Error(`Invalid ${fieldName}: expected a non-empty string.`);
+	return normalized;
+}
+function normalizePositiveInteger(value) {
+	if (typeof value !== "number" || !Number.isFinite(value)) return void 0;
+	const normalized = Math.trunc(value);
+	return normalized > 0 ? normalized : void 0;
+}
+function normalizeVersionIdentifier(value) {
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) return void 0;
+		const normalized = Math.trunc(value);
+		return normalized >= 0 ? normalized : void 0;
+	}
+	return normalizeId(value);
+}
+function stableObject(value) {
+	return Object.fromEntries(Object.entries(value).filter(([, entryValue]) => entryValue !== void 0).sort(([left], [right]) => left.localeCompare(right)));
+}
+
+//#endregion
+//#region src/embedding-compat.ts
+function buildDaihumAiCompatibilityFingerprint(input) {
+	const basis = stableObject({
+		providerId: normalizeRequiredId(input.providerId, "providerId"),
+		modelId: normalizeId(input.modelId),
+		routeId: normalizeId(input.routeId),
+		dimensions: normalizePositiveInteger(input.dimensions),
+		normalization: normalizeId(input.normalization),
+		distanceMetric: normalizeId(input.distanceMetric),
+		chunkerId: normalizeId(input.chunkerId),
+		chunkStrategyId: normalizeId(input.chunkStrategyId),
+		chunkStrategyVersion: normalizeVersionIdentifier(input.chunkStrategyVersion),
+		chunkStrategyConfigHash: normalizeId(input.chunkStrategyConfigHash),
+		extra: input.extra ? stableObject(input.extra) : void 0
+	});
+	return {
+		algorithm: "daihum-ai.compatibility.v1",
+		value: `daihum-ai.compatibility.v1:${JSON.stringify(basis)}`,
+		basis
+	};
+}
+
+//#endregion
+export { buildDaihumAiCompatibilityFingerprint as t };
+//# sourceMappingURL=embedding-compat-Ov4JeVna.js.map

package/dist/embedding-compat-Ov4JeVna.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-compat-Ov4JeVna.js","names":[],"sources":["../src/internal/normalize.ts","../src/embedding-compat.ts"],"sourcesContent":["// Vendored from the former @daihum/ai-core/internal/normalize so this package\n// stays a zero-dependency leaf (see embedding-compat.ts).\n\nexport function normalizeId(value: string | undefined): string | undefined {\n  if (typeof value !== \"string\") return undefined;\n  const trimmed = value.trim();\n  return trimmed.length > 0 ? trimmed : undefined;\n}\n\nexport function normalizeRequiredId(value: string, fieldName: string): string {\n  const normalized = normalizeId(value);\n  if (!normalized) {\n    throw new Error(`Invalid ${fieldName}: expected a non-empty string.`);\n  }\n  return normalized;\n}\n\nexport function normalizePositiveInteger(value: number | undefined): number | undefined {\n  if (typeof value !== \"number\" || !Number.isFinite(value)) return undefined;\n  const normalized = Math.trunc(value);\n  return normalized > 0 ? normalized : undefined;\n}\n\nexport function normalizeVersionIdentifier(\n  value: number | string | undefined,\n): number | string | undefined {\n  if (typeof value === \"number\") {\n    if (!Number.isFinite(value)) return undefined;\n    const normalized = Math.trunc(value);\n    return normalized >= 0 ? normalized : undefined;\n  }\n  return normalizeId(value);\n}\n\nexport function stableObject<T extends Readonly<Record<string, unknown>>>(value: T): T {\n  return Object.fromEntries(\n    Object.entries(value)\n      .filter(([, entryValue]) => entryValue !== undefined)\n      .sort(([left], [right]) => left.localeCompare(right)),\n  ) as T;\n}\n","import {\n  normalizeId,\n  normalizePositiveInteger,\n  normalizeRequiredId,\n  normalizeVersionIdentifier,\n  stableObject,\n} from \"./internal/normalize.js\";\n\nexport interface DaihumAiCompatibilityFingerprintInput {\n  readonly providerId: string;\n  readonly modelId?: string;\n  readonly routeId?: string;\n  readonly dimensions?: number;\n  readonly normalization?: string;\n  readonly distanceMetric?: string;\n  readonly chunkerId?: string;\n  readonly chunkStrategyId?: string;\n  readonly chunkStrategyVersion?: number | string;\n  readonly chunkStrategyConfigHash?: string;\n  readonly extra?: Readonly<Record<string, unknown>>;\n}\n\nexport interface DaihumAiCompatibilityFingerprint {\n  readonly algorithm: \"daihum-ai.compatibility.v1\";\n  readonly value: string;\n  readonly basis: DaihumAiCompatibilityFingerprintInput;\n}\n\nexport function buildDaihumAiCompatibilityFingerprint(\n  input: DaihumAiCompatibilityFingerprintInput,\n): DaihumAiCompatibilityFingerprint {\n  const basis = stableObject({\n    providerId: normalizeRequiredId(input.providerId, \"providerId\"),\n    modelId: normalizeId(input.modelId),\n    routeId: normalizeId(input.routeId),\n    dimensions: normalizePositiveInteger(input.dimensions),\n    normalization: normalizeId(input.normalization),\n    distanceMetric: normalizeId(input.distanceMetric),\n    chunkerId: normalizeId(input.chunkerId),\n    chunkStrategyId: normalizeId(input.chunkStrategyId),\n    chunkStrategyVersion: normalizeVersionIdentifier(input.chunkStrategyVersion),\n    chunkStrategyConfigHash: normalizeId(input.chunkStrategyConfigHash),\n    extra: input.extra ? stableObject(input.extra) : undefined,\n  });\n\n  return {\n    algorithm: \"daihum-ai.compatibility.v1\",\n    value: `daihum-ai.compatibility.v1:${JSON.stringify(basis)}`,\n    basis,\n  };\n}\n"],"mappings":";AAGA,SAAgB,YAAY,OAA+C;AACzE,KAAI,OAAO,UAAU,SAAU,QAAO;CACtC,MAAM,UAAU,MAAM,MAAM;AAC5B,QAAO,QAAQ,SAAS,IAAI,UAAU;;AAGxC,SAAgB,oBAAoB,OAAe,WAA2B;CAC5E,MAAM,aAAa,YAAY,MAAM;AACrC,KAAI,CAAC,WACH,OAAM,IAAI,MAAM,WAAW,UAAU,gCAAgC;AAEvE,QAAO;;AAGT,SAAgB,yBAAyB,OAA+C;AACtF,KAAI,OAAO,UAAU,YAAY,CAAC,OAAO,SAAS,MAAM,CAAE,QAAO;CACjE,MAAM,aAAa,KAAK,MAAM,MAAM;AACpC,QAAO,aAAa,IAAI,aAAa;;AAGvC,SAAgB,2BACd,OAC6B;AAC7B,KAAI,OAAO,UAAU,UAAU;AAC7B,MAAI,CAAC,OAAO,SAAS,MAAM,CAAE,QAAO;EACpC,MAAM,aAAa,KAAK,MAAM,MAAM;AACpC,SAAO,cAAc,IAAI,aAAa;;AAExC,QAAO,YAAY,MAAM;;AAG3B,SAAgB,aAA0D,OAAa;AACrF,QAAO,OAAO,YACZ,OAAO,QAAQ,MAAM,CAClB,QAAQ,GAAG,gBAAgB,eAAe,OAAU,CACpD,MAAM,CAAC,OAAO,CAAC,WAAW,KAAK,cAAc,MAAM,CAAC,CACxD;;;;;ACXH,SAAgB,sCACd,OACkC;CAClC,MAAM,QAAQ,aAAa;EACzB,YAAY,oBAAoB,MAAM,YAAY,aAAa;EAC/D,SAAS,YAAY,MAAM,QAAQ;EACnC,SAAS,YAAY,MAAM,QAAQ;EACnC,YAAY,yBAAyB,MAAM,WAAW;EACtD,eAAe,YAAY,MAAM,cAAc;EAC/C,gBAAgB,YAAY,MAAM,eAAe;EACjD,WAAW,YAAY,MAAM,UAAU;EACvC,iBAAiB,YAAY,MAAM,gBAAgB;EACnD,sBAAsB,2BAA2B,MAAM,qBAAqB;EAC5E,yBAAyB,YAAY,MAAM,wBAAwB;EACnE,OAAO,MAAM,QAAQ,aAAa,MAAM,MAAM,GAAG;EAClD,CAAC;AAEF,QAAO;EACL,WAAW;EACX,OAAO,8BAA8B,KAAK,UAAU,MAAM;EAC1D;EACD"}

package/dist/embedding-compat.d.ts

@@ -0,0 +1,2 @@
+import { n as DaihumAiCompatibilityFingerprintInput, r as buildDaihumAiCompatibilityFingerprint, t as DaihumAiCompatibilityFingerprint } from "./embedding-compat-ClR_h_ED.js";
+export { DaihumAiCompatibilityFingerprint, DaihumAiCompatibilityFingerprintInput, buildDaihumAiCompatibilityFingerprint };

package/dist/embedding-compat.js

@@ -0,0 +1,3 @@
+import { t as buildDaihumAiCompatibilityFingerprint } from "./embedding-compat-Ov4JeVna.js";
+
+export { buildDaihumAiCompatibilityFingerprint };

package/dist/embedding.d.ts

@@ -0,0 +1,3 @@
+import "./usage-Db6aaBEO.js";
+import { n as DaihumAiEmbeddingRequest, r as DaihumAiEmbeddingResponse, t as DaihumAiEmbedding } from "./embedding-B7HPKvpY.js";
+export { DaihumAiEmbedding, DaihumAiEmbeddingRequest, DaihumAiEmbeddingResponse };

package/dist/embedding.js

@@ -0,0 +1 @@
+import "./embedding-DqA2ZBzJ.js";

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { t as DaihumAiUsage } from "./usage-Db6aaBEO.js";
+import { a as DaihumAiCandidateRankScoreKind, i as DaihumAiCandidateRankResult, n as DaihumAiCandidateRankRequest, o as DaihumAiCandidateRankWarning, r as DaihumAiCandidateRankResponse, t as DaihumAiCandidateRankCandidate } from "./candidate-rank-CFpxmTMM.js";
+import { a as DaihumAiToolDefinition, i as DaihumAiToolChoice, n as DaihumAiPartialToolCall, o as fromDaihumAiWireToolDefinition, r as DaihumAiToolCall, s as toDaihumAiWireToolDefinition, t as DaihumAiFlatToolDefinition } from "./tools-VkZPo3Sc.js";
+import { a as DaihumAiContentPart, c as DaihumAiJsonPart, d as DaihumAiResponseFormat, f as DaihumAiTextPart, i as DaihumAiChatStreamEvent, l as DaihumAiMessage, n as DaihumAiChatResponse, o as DaihumAiFinishReason, r as DaihumAiChatResponseKind, s as DaihumAiImagePart, t as DaihumAiChatRequest, u as DaihumAiMessageRole } from "./chat-BZgfxuBU.js";
+import { n as DaihumAiCompatibilityFingerprintInput, r as buildDaihumAiCompatibilityFingerprint, t as DaihumAiCompatibilityFingerprint } from "./embedding-compat-ClR_h_ED.js";
+import { n as DaihumAiEmbeddingRequest, r as DaihumAiEmbeddingResponse, t as DaihumAiEmbedding } from "./embedding-B7HPKvpY.js";
+export { DaihumAiCandidateRankCandidate, DaihumAiCandidateRankRequest, DaihumAiCandidateRankResponse, DaihumAiCandidateRankResult, DaihumAiCandidateRankScoreKind, DaihumAiCandidateRankWarning, DaihumAiChatRequest, DaihumAiChatResponse, DaihumAiChatResponseKind, DaihumAiChatStreamEvent, DaihumAiCompatibilityFingerprint, DaihumAiCompatibilityFingerprintInput, DaihumAiContentPart, DaihumAiEmbedding, DaihumAiEmbeddingRequest, DaihumAiEmbeddingResponse, DaihumAiFinishReason, DaihumAiFlatToolDefinition, DaihumAiImagePart, DaihumAiJsonPart, DaihumAiMessage, DaihumAiMessageRole, DaihumAiPartialToolCall, DaihumAiResponseFormat, DaihumAiTextPart, DaihumAiToolCall, DaihumAiToolChoice, DaihumAiToolDefinition, DaihumAiUsage, buildDaihumAiCompatibilityFingerprint, fromDaihumAiWireToolDefinition, toDaihumAiWireToolDefinition };

package/dist/index.js

@@ -0,0 +1,8 @@
+import { n as toDaihumAiWireToolDefinition, t as fromDaihumAiWireToolDefinition } from "./tools-DYtxGkWR.js";
+import "./usage-F8ETXDpy.js";
+import "./chat-BEsGPeX0.js";
+import "./embedding-DqA2ZBzJ.js";
+import "./candidate-rank-DYi3Kcdp.js";
+import { t as buildDaihumAiCompatibilityFingerprint } from "./embedding-compat-Ov4JeVna.js";
+
+export { buildDaihumAiCompatibilityFingerprint, fromDaihumAiWireToolDefinition, toDaihumAiWireToolDefinition };

package/dist/tools-DYtxGkWR.js

@@ -0,0 +1,22 @@
+//#region src/tools.ts
+function toDaihumAiWireToolDefinition(flat) {
+	return {
+		type: "function",
+		function: {
+			name: flat.name,
+			description: flat.description,
+			parameters: flat.parameters
+		}
+	};
+}
+function fromDaihumAiWireToolDefinition(wire) {
+	return {
+		name: wire.function.name,
+		description: wire.function.description,
+		parameters: wire.function.parameters
+	};
+}
+
+//#endregion
+export { toDaihumAiWireToolDefinition as n, fromDaihumAiWireToolDefinition as t };
+//# sourceMappingURL=tools-DYtxGkWR.js.map

package/dist/tools-DYtxGkWR.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools-DYtxGkWR.js","names":[],"sources":["../src/tools.ts"],"sourcesContent":["export interface DaihumAiToolCall {\n  readonly id: string;\n  readonly type: \"function\";\n  readonly function: {\n    readonly name: string;\n    readonly arguments: string;\n  };\n}\n\nexport interface DaihumAiPartialToolCall {\n  readonly index?: number;\n  readonly id?: string;\n  readonly type?: \"function\" | (string & {});\n  readonly function?: {\n    readonly name?: string;\n    readonly arguments?: string;\n    readonly argumentsDelta?: string;\n  };\n  readonly metadata?: Readonly<Record<string, unknown>>;\n}\n\nexport interface DaihumAiToolDefinition {\n  readonly type: \"function\";\n  readonly function: {\n    readonly name: string;\n    readonly description?: string;\n    readonly parameters?: unknown;\n  };\n}\n\nexport type DaihumAiToolChoice =\n  | \"auto\"\n  | \"none\"\n  | \"required\"\n  | Readonly<{ readonly type: \"tool\"; readonly toolName: string }>\n  | (string & {});\n\n/** Flat, wire-agnostic tool description (the domain-level canonical form). */\nexport interface DaihumAiFlatToolDefinition {\n  readonly name: string;\n  readonly description?: string;\n  readonly parameters?: unknown;\n}\n\nexport function toDaihumAiWireToolDefinition(flat: DaihumAiFlatToolDefinition): DaihumAiToolDefinition {\n  return { type: \"function\", function: { name: flat.name, description: flat.description, parameters: flat.parameters } };\n}\n\nexport function fromDaihumAiWireToolDefinition(wire: DaihumAiToolDefinition): DaihumAiFlatToolDefinition {\n  return { name: wire.function.name, description: wire.function.description, parameters: wire.function.parameters };\n}\n"],"mappings":";AA4CA,SAAgB,6BAA6B,MAA0D;AACrG,QAAO;EAAE,MAAM;EAAY,UAAU;GAAE,MAAM,KAAK;GAAM,aAAa,KAAK;GAAa,YAAY,KAAK;GAAY;EAAE;;AAGxH,SAAgB,+BAA+B,MAA0D;AACvG,QAAO;EAAE,MAAM,KAAK,SAAS;EAAM,aAAa,KAAK,SAAS;EAAa,YAAY,KAAK,SAAS;EAAY"}

package/dist/tools-VkZPo3Sc.d.ts

@@ -0,0 +1,43 @@
+//#region src/tools.d.ts
+interface DaihumAiToolCall {
+  readonly id: string;
+  readonly type: "function";
+  readonly function: {
+    readonly name: string;
+    readonly arguments: string;
+  };
+}
+interface DaihumAiPartialToolCall {
+  readonly index?: number;
+  readonly id?: string;
+  readonly type?: "function" | (string & {});
+  readonly function?: {
+    readonly name?: string;
+    readonly arguments?: string;
+    readonly argumentsDelta?: string;
+  };
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+interface DaihumAiToolDefinition {
+  readonly type: "function";
+  readonly function: {
+    readonly name: string;
+    readonly description?: string;
+    readonly parameters?: unknown;
+  };
+}
+type DaihumAiToolChoice = "auto" | "none" | "required" | Readonly<{
+  readonly type: "tool";
+  readonly toolName: string;
+}> | (string & {});
+/** Flat, wire-agnostic tool description (the domain-level canonical form). */
+interface DaihumAiFlatToolDefinition {
+  readonly name: string;
+  readonly description?: string;
+  readonly parameters?: unknown;
+}
+declare function toDaihumAiWireToolDefinition(flat: DaihumAiFlatToolDefinition): DaihumAiToolDefinition;
+declare function fromDaihumAiWireToolDefinition(wire: DaihumAiToolDefinition): DaihumAiFlatToolDefinition;
+//#endregion
+export { DaihumAiToolDefinition as a, DaihumAiToolChoice as i, DaihumAiPartialToolCall as n, fromDaihumAiWireToolDefinition as o, DaihumAiToolCall as r, toDaihumAiWireToolDefinition as s, DaihumAiFlatToolDefinition as t };
+//# sourceMappingURL=tools-VkZPo3Sc.d.ts.map

package/dist/tools.d.ts

@@ -0,0 +1,2 @@
+import { a as DaihumAiToolDefinition, i as DaihumAiToolChoice, n as DaihumAiPartialToolCall, o as fromDaihumAiWireToolDefinition, r as DaihumAiToolCall, s as toDaihumAiWireToolDefinition, t as DaihumAiFlatToolDefinition } from "./tools-VkZPo3Sc.js";
+export { DaihumAiFlatToolDefinition, DaihumAiPartialToolCall, DaihumAiToolCall, DaihumAiToolChoice, DaihumAiToolDefinition, fromDaihumAiWireToolDefinition, toDaihumAiWireToolDefinition };

package/dist/tools.js

@@ -0,0 +1,3 @@
+import { n as toDaihumAiWireToolDefinition, t as fromDaihumAiWireToolDefinition } from "./tools-DYtxGkWR.js";
+
+export { fromDaihumAiWireToolDefinition, toDaihumAiWireToolDefinition };

package/dist/usage-Db6aaBEO.d.ts

@@ -0,0 +1,11 @@
+//#region src/usage.d.ts
+interface DaihumAiUsage {
+  readonly inputTokens?: number;
+  readonly outputTokens?: number;
+  readonly totalTokens?: number;
+  readonly requestCount?: number;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+//#endregion
+export { DaihumAiUsage as t };
+//# sourceMappingURL=usage-Db6aaBEO.d.ts.map

package/dist/usage.d.ts

@@ -0,0 +1,2 @@
+import { t as DaihumAiUsage } from "./usage-Db6aaBEO.js";
+export { DaihumAiUsage };

package/dist/usage.js

@@ -0,0 +1 @@
+import "./usage-F8ETXDpy.js";

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@daihum/ai-model-contracts",
+  "version": "0.1.0",
+  "description": "DAIHUM AI pure, serializable model-operation payload contracts: chat, embedding, candidate-rank, tools, usage, embedding-compat. Zero dependencies. Carries NO routing (routePlan), provider selection, secrets, catalog/pricing, runtime, RAG, or product authority. The stable vocabulary leaf.",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./chat": {
+      "types": "./dist/chat.d.ts",
+      "import": "./dist/chat.js"
+    },
+    "./embedding": {
+      "types": "./dist/embedding.d.ts",
+      "import": "./dist/embedding.js"
+    },
+    "./candidate-rank": {
+      "types": "./dist/candidate-rank.d.ts",
+      "import": "./dist/candidate-rank.js"
+    },
+    "./tools": {
+      "types": "./dist/tools.d.ts",
+      "import": "./dist/tools.js"
+    },
+    "./usage": {
+      "types": "./dist/usage.d.ts",
+      "import": "./dist/usage.js"
+    },
+    "./embedding-compat": {
+      "types": "./dist/embedding-compat.d.ts",
+      "import": "./dist/embedding-compat.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "devDependencies": {
+    "tsdown": "^0.16.6",
+    "typescript": "~5.6.2"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsdown",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/candidate-rank.ts

@@ -0,0 +1,66 @@
+import type { DaihumAiUsage } from "./usage.js";
+
+/**
+ * Model-level candidate ranking (renamed from the former "rerank" model op;
+ * "rerank" is reserved for the RAG pipeline stage in @daihum/ai-rag).
+ *
+ * Operation shape: query + candidate texts -> candidate ids / order / scores.
+ * This is a peer of chat and embedding, NOT an optimization of chat — some
+ * runtimes serve it natively (e.g. an OpenRouter /rerank endpoint), others via
+ * a candidate-rank-from-chat adapter (@daihum/ai-candidate-rank-adapters).
+ */
+
+/**
+ * A candidate to rank. Model-visible payload ONLY: an opaque id + the text the
+ * model sees. Deliberately has NO `metadata?: unknown` — that would be a
+ * fat-envelope backdoor for hydrated hits / provenance / authority / secrets.
+ * Callers map their own source ids through *ephemeral* candidateIds.
+ */
+export interface DaihumAiCandidateRankCandidate {
+  readonly candidateId: string;
+  readonly text: string;
+}
+
+export interface DaihumAiCandidateRankRequest {
+  readonly requestId?: string;
+  readonly providerId?: string;
+  readonly modelId?: string;
+  readonly routeId?: string;
+  readonly query: string;
+  readonly candidates: readonly DaihumAiCandidateRankCandidate[];
+  /** If set, the response MAY be partial (top-K). Omitted candidates are not errors. */
+  readonly topK?: number;
+  readonly signal?: AbortSignal;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+/** Where a result's score came from. A chat-prompted ranker can order reliably
+ * but cannot calibrate a score; in that case `score` is omitted (rank is
+ * authoritative) and the RAG blend stage derives a score from rank. */
+export type DaihumAiCandidateRankScoreKind = "provider" | "normalized" | "rank-derived";
+
+export interface DaihumAiCandidateRankResult {
+  readonly candidateId: string;
+  /** 1-based, unique within the response. Response order SHOULD match rank ascending. */
+  readonly rank: number;
+  /** Optional on purpose — see DaihumAiCandidateRankScoreKind. */
+  readonly score?: number;
+  readonly scoreKind?: DaihumAiCandidateRankScoreKind;
+}
+
+export interface DaihumAiCandidateRankWarning {
+  readonly code: string;
+  readonly message?: string;
+  readonly candidateId?: string;
+}
+
+export interface DaihumAiCandidateRankResponse {
+  readonly providerId: string;
+  readonly modelId: string;
+  readonly routeId?: string;
+  readonly results: readonly DaihumAiCandidateRankResult[];
+  readonly usage?: DaihumAiUsage;
+  readonly warnings?: readonly DaihumAiCandidateRankWarning[];
+  readonly rawResponse?: unknown;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}

package/src/chat.ts

@@ -0,0 +1,115 @@
+import type {
+  DaihumAiPartialToolCall,
+  DaihumAiToolCall,
+  DaihumAiToolChoice,
+  DaihumAiToolDefinition,
+} from "./tools.js";
+import type { DaihumAiUsage } from "./usage.js";
+
+export type DaihumAiMessageRole = "system" | "user" | "assistant" | "tool";
+
+export interface DaihumAiTextPart {
+  readonly type: "text";
+  readonly text: string;
+}
+
+export interface DaihumAiImagePart {
+  readonly type: "image";
+  readonly image: string | URL | Uint8Array | ArrayBuffer;
+  readonly mediaType?: string;
+}
+
+export interface DaihumAiJsonPart {
+  readonly type: "json";
+  readonly value: unknown;
+}
+
+export type DaihumAiContentPart =
+  | DaihumAiTextPart
+  | DaihumAiImagePart
+  | DaihumAiJsonPart
+  | (Readonly<Record<string, unknown>> & { readonly type: string });
+
+export interface DaihumAiMessage {
+  readonly role: DaihumAiMessageRole;
+  readonly content?: string | readonly DaihumAiContentPart[];
+  readonly name?: string;
+  readonly toolCallId?: string;
+  readonly toolCalls?: readonly DaihumAiToolCall[];
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+export type DaihumAiFinishReason =
+  | "stop"
+  | "length"
+  | "tool-calls"
+  | "content-filter"
+  | "error"
+  | "unknown"
+  | (string & {});
+
+/** Recommended shape for DaihumAiChatRequest.responseFormat (the field stays
+ * `unknown` for adapter flexibility; adapters narrow against this). */
+export type DaihumAiResponseFormat =
+  | Readonly<{ kind: "text" }>
+  | Readonly<{ kind: "json" }>
+  | Readonly<{ kind: "json-schema"; name?: string; strict?: boolean; schema: Readonly<Record<string, unknown>> }>;
+
+/**
+ * Pure chat model-operation payload. Carries model I/O only.
+ *
+ * NOT present (by design — these are NOT model payload):
+ *  - routePlan  -> routing concern; @daihum/ai-routing lowers a route plan into
+ *    providerId/modelId/routeId (resolved below) + a provider call context.
+ *  - execution context (workspaceId/actorId/dataClass/...) -> product authority;
+ *    travels in the provider call context (@daihum/ai-provider-contracts), never here.
+ *
+ * providerId/modelId/routeId are the *already-resolved* execution target hints
+ * (populated by routing before the call), not a route plan.
+ */
+export interface DaihumAiChatRequest {
+  readonly requestId?: string;
+  readonly providerId?: string;
+  readonly modelId?: string;
+  readonly routeId?: string;
+  readonly messages: readonly DaihumAiMessage[];
+  readonly tools?: readonly DaihumAiToolDefinition[];
+  readonly toolChoice?: DaihumAiToolChoice;
+  readonly temperature?: number;
+  readonly topP?: number;
+  readonly maxOutputTokens?: number;
+  readonly reasoningBudget?: number;
+  readonly seed?: number;
+  readonly frequencyPenalty?: number;
+  readonly presencePenalty?: number;
+  readonly stopSequences?: readonly string[];
+  readonly responseFormat?: unknown;
+  readonly signal?: AbortSignal;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+export type DaihumAiChatResponseKind = "message" | "tool-calls";
+
+export interface DaihumAiChatResponse {
+  readonly kind: DaihumAiChatResponseKind;
+  readonly providerId: string;
+  readonly modelId: string;
+  readonly routeId?: string;
+  readonly text?: string;
+  readonly toolCalls?: readonly DaihumAiToolCall[];
+  readonly finishReason?: DaihumAiFinishReason;
+  readonly usage?: DaihumAiUsage;
+  readonly providerRequestId?: string;
+  readonly rawResponse?: unknown;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+export type DaihumAiChatStreamEvent =
+  | Readonly<{ type: "text-delta"; textDelta: string }>
+  | Readonly<{ type: "tool-call-start"; toolCall: DaihumAiPartialToolCall }>
+  | Readonly<{ type: "tool-call-delta"; toolCall: DaihumAiPartialToolCall }>
+  | Readonly<{ type: "tool-call-end"; toolCall: DaihumAiToolCall | DaihumAiPartialToolCall }>
+  | Readonly<{ type: "tool-call"; toolCall: DaihumAiToolCall }>
+  | Readonly<{ type: "reasoning-delta"; reasoningDelta: string }>
+  | Readonly<{ type: "finish"; response: DaihumAiChatResponse }>
+  | Readonly<{ type: "error"; error: unknown }>;

package/src/embedding-compat.ts

@@ -0,0 +1,51 @@
+import {
+  normalizeId,
+  normalizePositiveInteger,
+  normalizeRequiredId,
+  normalizeVersionIdentifier,
+  stableObject,
+} from "./internal/normalize.js";
+
+export interface DaihumAiCompatibilityFingerprintInput {
+  readonly providerId: string;
+  readonly modelId?: string;
+  readonly routeId?: string;
+  readonly dimensions?: number;
+  readonly normalization?: string;
+  readonly distanceMetric?: string;
+  readonly chunkerId?: string;
+  readonly chunkStrategyId?: string;
+  readonly chunkStrategyVersion?: number | string;
+  readonly chunkStrategyConfigHash?: string;
+  readonly extra?: Readonly<Record<string, unknown>>;
+}
+
+export interface DaihumAiCompatibilityFingerprint {
+  readonly algorithm: "daihum-ai.compatibility.v1";
+  readonly value: string;
+  readonly basis: DaihumAiCompatibilityFingerprintInput;
+}
+
+export function buildDaihumAiCompatibilityFingerprint(
+  input: DaihumAiCompatibilityFingerprintInput,
+): DaihumAiCompatibilityFingerprint {
+  const basis = stableObject({
+    providerId: normalizeRequiredId(input.providerId, "providerId"),
+    modelId: normalizeId(input.modelId),
+    routeId: normalizeId(input.routeId),
+    dimensions: normalizePositiveInteger(input.dimensions),
+    normalization: normalizeId(input.normalization),
+    distanceMetric: normalizeId(input.distanceMetric),
+    chunkerId: normalizeId(input.chunkerId),
+    chunkStrategyId: normalizeId(input.chunkStrategyId),
+    chunkStrategyVersion: normalizeVersionIdentifier(input.chunkStrategyVersion),
+    chunkStrategyConfigHash: normalizeId(input.chunkStrategyConfigHash),
+    extra: input.extra ? stableObject(input.extra) : undefined,
+  });
+
+  return {
+    algorithm: "daihum-ai.compatibility.v1",
+    value: `daihum-ai.compatibility.v1:${JSON.stringify(basis)}`,
+    basis,
+  };
+}

package/src/embedding.ts

@@ -0,0 +1,36 @@
+import type { DaihumAiUsage } from "./usage.js";
+
+/**
+ * Pure embedding model-operation payload. Carries model I/O only.
+ * routePlan/execution-context intentionally absent (see chat.ts).
+ */
+export interface DaihumAiEmbeddingRequest {
+  readonly requestId?: string;
+  readonly providerId?: string;
+  readonly modelId?: string;
+  readonly routeId?: string;
+  readonly input: string | readonly string[];
+  readonly dimensions?: number;
+  readonly signal?: AbortSignal;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+export interface DaihumAiEmbedding {
+  readonly inputIndex: number;
+  readonly vector: Float32Array;
+  readonly dimensions: number;
+  readonly providerId: string;
+  readonly modelId: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+export interface DaihumAiEmbeddingResponse {
+  readonly providerId: string;
+  readonly modelId: string;
+  readonly routeId?: string;
+  readonly embeddings: readonly DaihumAiEmbedding[];
+  readonly usage?: DaihumAiUsage;
+  readonly providerRequestId?: string;
+  readonly rawResponse?: unknown;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+// Convenience root barrel. Prefer subpath imports
+// (e.g. `@daihum/ai-model-contracts/candidate-rank`) as the dominant style —
+// the package is universal, the root import should not be.
+export * from "./tools.js";
+export * from "./usage.js";
+export * from "./chat.js";
+export * from "./embedding.js";
+export * from "./candidate-rank.js";
+export * from "./embedding-compat.js";

package/src/internal/normalize.ts

@@ -0,0 +1,41 @@
+// Vendored from the former @daihum/ai-core/internal/normalize so this package
+// stays a zero-dependency leaf (see embedding-compat.ts).
+
+export function normalizeId(value: string | undefined): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+export function normalizeRequiredId(value: string, fieldName: string): string {
+  const normalized = normalizeId(value);
+  if (!normalized) {
+    throw new Error(`Invalid ${fieldName}: expected a non-empty string.`);
+  }
+  return normalized;
+}
+
+export function normalizePositiveInteger(value: number | undefined): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
+  const normalized = Math.trunc(value);
+  return normalized > 0 ? normalized : undefined;
+}
+
+export function normalizeVersionIdentifier(
+  value: number | string | undefined,
+): number | string | undefined {
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) return undefined;
+    const normalized = Math.trunc(value);
+    return normalized >= 0 ? normalized : undefined;
+  }
+  return normalizeId(value);
+}
+
+export function stableObject<T extends Readonly<Record<string, unknown>>>(value: T): T {
+  return Object.fromEntries(
+    Object.entries(value)
+      .filter(([, entryValue]) => entryValue !== undefined)
+      .sort(([left], [right]) => left.localeCompare(right)),
+  ) as T;
+}

package/src/tools.ts

@@ -0,0 +1,51 @@
+export interface DaihumAiToolCall {
+  readonly id: string;
+  readonly type: "function";
+  readonly function: {
+    readonly name: string;
+    readonly arguments: string;
+  };
+}
+
+export interface DaihumAiPartialToolCall {
+  readonly index?: number;
+  readonly id?: string;
+  readonly type?: "function" | (string & {});
+  readonly function?: {
+    readonly name?: string;
+    readonly arguments?: string;
+    readonly argumentsDelta?: string;
+  };
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+export interface DaihumAiToolDefinition {
+  readonly type: "function";
+  readonly function: {
+    readonly name: string;
+    readonly description?: string;
+    readonly parameters?: unknown;
+  };
+}
+
+export type DaihumAiToolChoice =
+  | "auto"
+  | "none"
+  | "required"
+  | Readonly<{ readonly type: "tool"; readonly toolName: string }>
+  | (string & {});
+
+/** Flat, wire-agnostic tool description (the domain-level canonical form). */
+export interface DaihumAiFlatToolDefinition {
+  readonly name: string;
+  readonly description?: string;
+  readonly parameters?: unknown;
+}
+
+export function toDaihumAiWireToolDefinition(flat: DaihumAiFlatToolDefinition): DaihumAiToolDefinition {
+  return { type: "function", function: { name: flat.name, description: flat.description, parameters: flat.parameters } };
+}
+
+export function fromDaihumAiWireToolDefinition(wire: DaihumAiToolDefinition): DaihumAiFlatToolDefinition {
+  return { name: wire.function.name, description: wire.function.description, parameters: wire.function.parameters };
+}

package/src/usage.ts

@@ -0,0 +1,7 @@
+export interface DaihumAiUsage {
+  readonly inputTokens?: number;
+  readonly outputTokens?: number;
+  readonly totalTokens?: number;
+  readonly requestCount?: number;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}