@idemcore/ai-sdk-provider 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# @idemcore/ai-sdk-provider
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Vercel AI SDK provider for the [Idemcore](https://idemcore.net) API. Every
+answer comes with a signed, independently verifiable, bit-exact receipt,
+exposed on `providerMetadata.idemcore`.
+
+This package implements the current `LanguageModelV4` / `ProviderV4`
+specification used by the `ai` package v7 (`@ai-sdk/provider` v4).
+
+Private package. Do not publish to npm without explicit approval.
+
+## Install (local)
+
+```bash
+# from this directory
+npm install
+export IDEMCORE_API_KEY=ick_...
+```
+
+Peer: `ai` >= 7. Depends on `@idemcore/sdk` 0.3.0 (r2 receipts) and
+`@ai-sdk/provider` ^4.
+
+## Quickstart
+
+```ts
+import { generateText, streamText } from "ai";
+import { createIdemcore } from "@idemcore/ai-sdk-provider";
+
+const idemcore = createIdemcore(); // reads IDEMCORE_API_KEY
+const { text, providerMetadata } = await generateText({
+  model: idemcore("your-model-id"),
+  prompt: "Name the three primary colours.",
+  maxOutputTokens: 64,
+});
+
+console.log(text);
+console.log(providerMetadata?.idemcore?.receiptId); // rcpt_...
+console.log(providerMetadata?.idemcore?.receipt);   // full signed receipt
+```
+
+Optional privacy (passed through as `providerOptions`):
+
+```ts
+await generateText({
+  model: idemcore("your-model-id"),
+  prompt: "Hello",
+  providerOptions: { idemcore: { privacy: "hash_only" } },
+});
+```
+
+Streaming yields text deltas. The receipt arrives on the final `finish` part
+via `providerMetadata.idemcore`, once the answer is complete.
+
+You can re-check a receipt locally with `verifyReceipt` (re-exported from
+`@idemcore/sdk`).
+
+## Sampling
+
+Idemcore decoding is greedy: **temperature is fixed at 0**. A non-zero
+temperature throws before a request is made. Other sampling settings
+(`topP`, `topK`, penalties, `seed`, `stopSequences`) and tool calling produce
+`unsupported` warnings (or an error if `toolChoice` requires a tool).
+`maxOutputTokens` is forwarded as the SDK's `maxTokens` (1–2048).
+
+Auth is `IDEMCORE_API_KEY` (or `createIdemcore({ apiKey })`). Billing is
+measured server-side in tokens.
+
+Embeddings, image, and speech models are not available; those provider
+methods throw `NoSuchModelError`.
+
+## Tests
+
+```bash
+npm test
+npm run build
+```
+
+Unit tests mock the SDK. A live smoke test runs only when `IDEMCORE_API_KEY`
+is set in the environment.

package/dist/convert.d.ts

@@ -0,0 +1,18 @@
+import type { LanguageModelV4CallOptions, LanguageModelV4FinishReason, LanguageModelV4Prompt, LanguageModelV4Usage, SharedV4Warning } from "@ai-sdk/provider";
+import type { ChatOptions, Message } from "@idemcore/sdk";
+export type PreparedCall = {
+    messages: Message[];
+    options: ChatOptions;
+    warnings: SharedV4Warning[];
+};
+export declare function convertPrompt(prompt: LanguageModelV4Prompt): Message[];
+export declare function mapFinishReason(raw: string | null | undefined): LanguageModelV4FinishReason;
+export declare function mapUsage(usage: {
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    total_tokens?: number;
+} | null): LanguageModelV4Usage;
+export declare function prepareCall(call: LanguageModelV4CallOptions, defaults: {
+    model: string;
+    privacy?: "hash_only" | "full";
+}): PreparedCall;

package/dist/convert.js

@@ -0,0 +1,171 @@
+import { IdemcoreProviderError } from "./errors.js";
+function textFromParts(parts, role) {
+    const texts = [];
+    for (const part of parts) {
+        if (part.type === "text" && typeof part.text === "string") {
+            texts.push(part.text);
+            continue;
+        }
+        if (part.type === "file") {
+            throw new IdemcoreProviderError("Idemcore chat accepts text messages only; file or image parts are not supported.");
+        }
+        if (part.type === "tool-call" || part.type === "tool-result") {
+            throw new IdemcoreProviderError("Idemcore chat does not support tool calling.");
+        }
+        if (part.type === "reasoning") {
+            // Reasoning parts are not sent to the text-only API.
+            continue;
+        }
+        throw new IdemcoreProviderError(`Unsupported ${role} content part type: ${String(part.type)}.`);
+    }
+    return texts.join("");
+}
+export function convertPrompt(prompt) {
+    const messages = [];
+    for (const msg of prompt) {
+        if (msg.role === "system") {
+            messages.push({ role: "system", content: msg.content });
+            continue;
+        }
+        if (msg.role === "user") {
+            messages.push({ role: "user", content: textFromParts(msg.content, "user") });
+            continue;
+        }
+        if (msg.role === "assistant") {
+            messages.push({
+                role: "assistant",
+                content: textFromParts(msg.content, "assistant"),
+            });
+            continue;
+        }
+        if (msg.role === "tool") {
+            throw new IdemcoreProviderError("Idemcore chat does not accept tool messages.");
+        }
+        throw new IdemcoreProviderError(`Unsupported message role: ${msg.role}.`);
+    }
+    if (messages.length < 1 || messages.length > 64) {
+        throw new IdemcoreProviderError("Idemcore chat requires between 1 and 64 messages.");
+    }
+    return messages;
+}
+export function mapFinishReason(raw) {
+    if (raw === "stop")
+        return { unified: "stop", raw: raw };
+    if (raw === "length")
+        return { unified: "length", raw: raw };
+    if (raw === "content_filter" || raw === "content-filter") {
+        return { unified: "content-filter", raw: raw };
+    }
+    if (!raw)
+        return { unified: "other", raw: undefined };
+    return { unified: "other", raw };
+}
+export function mapUsage(usage) {
+    const input = usage?.prompt_tokens;
+    const output = usage?.completion_tokens;
+    return {
+        inputTokens: {
+            total: input,
+            noCache: undefined,
+            cacheRead: undefined,
+            cacheWrite: undefined,
+        },
+        outputTokens: {
+            total: output,
+            text: output,
+            reasoning: undefined,
+        },
+        raw: usage ? { ...usage } : undefined,
+    };
+}
+export function prepareCall(call, defaults) {
+    const warnings = [];
+    if (call.temperature !== undefined && call.temperature !== 0) {
+        throw new IdemcoreProviderError("Idemcore uses greedy decoding: temperature is fixed at 0.");
+    }
+    if (call.topP !== undefined && call.topP !== 1) {
+        warnings.push({
+            type: "unsupported",
+            feature: "topP",
+            details: "Idemcore decoding is greedy; topP is ignored.",
+        });
+    }
+    if (call.topK !== undefined) {
+        warnings.push({
+            type: "unsupported",
+            feature: "topK",
+            details: "Idemcore decoding is greedy; topK is ignored.",
+        });
+    }
+    if (call.presencePenalty) {
+        warnings.push({
+            type: "unsupported",
+            feature: "presencePenalty",
+            details: "Idemcore decoding is greedy; presencePenalty is ignored.",
+        });
+    }
+    if (call.frequencyPenalty) {
+        warnings.push({
+            type: "unsupported",
+            feature: "frequencyPenalty",
+            details: "Idemcore decoding is greedy; frequencyPenalty is ignored.",
+        });
+    }
+    if (call.seed !== undefined) {
+        warnings.push({
+            type: "unsupported",
+            feature: "seed",
+            details: "The public Idemcore SDK chat API does not accept a seed.",
+        });
+    }
+    if (call.stopSequences && call.stopSequences.length > 0) {
+        warnings.push({
+            type: "unsupported",
+            feature: "stopSequences",
+            details: "Idemcore does not support stop sequences; they would not be reflected in the signed receipt.",
+        });
+    }
+    if (call.responseFormat?.type === "json") {
+        warnings.push({
+            type: "unsupported",
+            feature: "responseFormat",
+            details: "Idemcore chat returns plain text; JSON responseFormat is ignored.",
+        });
+    }
+    if (call.reasoning && call.reasoning !== "provider-default" && call.reasoning !== "none") {
+        warnings.push({
+            type: "unsupported",
+            feature: "reasoning",
+            details: "Idemcore chat does not expose a separate reasoning setting.",
+        });
+    }
+    if (call.tools && call.tools.length > 0) {
+        if (call.toolChoice && call.toolChoice.type !== "none" && call.toolChoice.type !== "auto") {
+            throw new IdemcoreProviderError("Idemcore chat does not support tool calling, so a required toolChoice cannot be honored.");
+        }
+        warnings.push({
+            type: "unsupported",
+            feature: "tools",
+            details: "Idemcore chat accepts text messages only; tool calling is not available.",
+        });
+    }
+    else if (call.toolChoice && call.toolChoice.type !== "none" && call.toolChoice.type !== "auto") {
+        throw new IdemcoreProviderError("Idemcore chat does not support tool calling, so a required toolChoice cannot be honored.");
+    }
+    const provider = (call.providerOptions?.idemcore ?? {});
+    const privacy = provider.privacy ?? defaults.privacy;
+    const options = { model: defaults.model };
+    if (call.maxOutputTokens !== undefined) {
+        options.maxTokens = call.maxOutputTokens;
+    }
+    if (privacy !== undefined) {
+        options.privacy = privacy;
+    }
+    if (call.temperature === 0) {
+        options.temperature = 0;
+    }
+    if (call.abortSignal) {
+        options.signal = call.abortSignal;
+    }
+    return { messages: convertPrompt(call.prompt), options, warnings };
+}

package/dist/errors.d.ts

@@ -0,0 +1,10 @@
+/** Errors raised when a request cannot be sent to the Idemcore chat API. */
+export declare class IdemcoreProviderError extends Error {
+    readonly status?: number;
+    readonly type: string;
+    constructor(message: string, opts?: {
+        type?: string;
+        status?: number;
+        cause?: unknown;
+    });
+}

package/dist/errors.js

@@ -0,0 +1,14 @@
+/** Errors raised when a request cannot be sent to the Idemcore chat API. */
+export class IdemcoreProviderError extends Error {
+    status;
+    type;
+    constructor(message, opts) {
+        super(message);
+        this.name = "IdemcoreProviderError";
+        this.type = opts?.type ?? "invalid_request_error";
+        this.status = opts?.status;
+        if (opts?.cause !== undefined) {
+            this.cause = opts.cause;
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { createIdemcore, idemcore } from "./provider.js";
+export type { IdemcoreProvider, IdemcoreProviderSettings } from "./provider.js";
+export { IdemcoreLanguageModel } from "./language-model.js";
+export type { IdemcoreLanguageModelConfig } from "./language-model.js";
+export { IdemcoreProviderError } from "./errors.js";
+export { receiptMetadata, providerMetadata } from "./receipt.js";
+export type { IdemcoreReceiptMetadata } from "./receipt.js";
+export { verifyReceipt } from "@idemcore/sdk";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { createIdemcore, idemcore } from "./provider.js";
+export { IdemcoreLanguageModel } from "./language-model.js";
+export { IdemcoreProviderError } from "./errors.js";
+export { receiptMetadata, providerMetadata } from "./receipt.js";
+export { verifyReceipt } from "@idemcore/sdk";

package/dist/language-model.d.ts

@@ -0,0 +1,21 @@
+import type { LanguageModelV4, LanguageModelV4CallOptions, LanguageModelV4GenerateResult, LanguageModelV4StreamResult } from "@ai-sdk/provider";
+import { Idemcore, type ChatResult, type ClientOptions } from "@idemcore/sdk";
+export type IdemcoreLanguageModelConfig = ClientOptions & {
+    /** Default receipt privacy for this model (`hash_only` or `full`). */
+    privacy?: "hash_only" | "full";
+    /** Injected client (tests). */
+    client?: Idemcore;
+};
+export declare class IdemcoreLanguageModel implements LanguageModelV4 {
+    readonly specificationVersion: "v4";
+    readonly provider = "idemcore";
+    readonly modelId: string;
+    readonly supportedUrls: Record<string, RegExp[]>;
+    private readonly config;
+    private clientInstance?;
+    constructor(modelId: string, config?: IdemcoreLanguageModelConfig);
+    private client;
+    doGenerate(options: LanguageModelV4CallOptions): Promise<LanguageModelV4GenerateResult>;
+    doStream(options: LanguageModelV4CallOptions): Promise<LanguageModelV4StreamResult>;
+}
+export declare function toGenerateResult(result: ChatResult, warnings?: LanguageModelV4GenerateResult["warnings"]): LanguageModelV4GenerateResult;

package/dist/language-model.js

@@ -0,0 +1,113 @@
+import { Idemcore } from "@idemcore/sdk";
+import { prepareCall } from "./convert.js";
+import { mapFinishReason, mapUsage } from "./convert.js";
+import { IdemcoreProviderError } from "./errors.js";
+import { providerMetadata } from "./receipt.js";
+export class IdemcoreLanguageModel {
+    specificationVersion = "v4";
+    provider = "idemcore";
+    modelId;
+    supportedUrls = {};
+    config;
+    clientInstance;
+    constructor(modelId, config = {}) {
+        this.modelId = modelId;
+        this.config = config;
+        this.clientInstance = config.client;
+    }
+    client() {
+        if (!this.clientInstance) {
+            this.clientInstance = new Idemcore({
+                apiKey: this.config.apiKey,
+                baseURL: this.config.baseURL,
+                timeout: this.config.timeout,
+                maxRetries: this.config.maxRetries,
+                headers: this.config.headers,
+                fetch: this.config.fetch,
+            });
+        }
+        return this.clientInstance;
+    }
+    async doGenerate(options) {
+        const prepared = prepareCall(options, {
+            model: this.modelId,
+            privacy: this.config.privacy,
+        });
+        const result = await this.client().chat(prepared.messages, prepared.options);
+        return toGenerateResult(result, prepared.warnings);
+    }
+    async doStream(options) {
+        const prepared = prepareCall(options, {
+            model: this.modelId,
+            privacy: this.config.privacy,
+        });
+        const stream = this.client().chatStream(prepared.messages, prepared.options);
+        const includeRaw = options.includeRawChunks === true;
+        const textId = "idemcore-text";
+        const output = new ReadableStream({
+            async start(controller) {
+                controller.enqueue({ type: "stream-start", warnings: prepared.warnings });
+                let started = false;
+                try {
+                    for await (const chunk of stream) {
+                        if (includeRaw) {
+                            controller.enqueue({ type: "raw", rawValue: chunk.raw });
+                        }
+                        if (!chunk.delta) {
+                            continue;
+                        }
+                        if (!started) {
+                            controller.enqueue({ type: "text-start", id: textId });
+                            started = true;
+                        }
+                        controller.enqueue({ type: "text-delta", id: textId, delta: chunk.delta });
+                    }
+                    const result = await stream.finalResult();
+                    if (started) {
+                        controller.enqueue({ type: "text-end", id: textId });
+                    }
+                    else {
+                        controller.enqueue({ type: "text-start", id: textId });
+                        controller.enqueue({ type: "text-end", id: textId });
+                    }
+                    controller.enqueue({
+                        type: "response-metadata",
+                        id: result.id || undefined,
+                        modelId: result.model || undefined,
+                    });
+                    controller.enqueue({
+                        type: "finish",
+                        finishReason: mapFinishReason(result.finishReason),
+                        usage: mapUsage(result.usage),
+                        providerMetadata: providerMetadata(result),
+                    });
+                    controller.close();
+                }
+                catch (error) {
+                    controller.enqueue({ type: "error", error });
+                    controller.close();
+                }
+            },
+            cancel() {
+                // The SDK stream is consumed in start(); abort is passed via ChatOptions.signal.
+            },
+        });
+        return { stream: output };
+    }
+}
+export function toGenerateResult(result, warnings = []) {
+    if (!result.receiptId) {
+        throw new IdemcoreProviderError("Idemcore response did not include a receipt id.");
+    }
+    return {
+        content: [{ type: "text", text: result.text }],
+        finishReason: mapFinishReason(result.finishReason),
+        usage: mapUsage(result.usage),
+        providerMetadata: providerMetadata(result),
+        response: {
+            id: result.id || undefined,
+            modelId: result.model || undefined,
+        },
+        warnings,
+    };
+}

package/dist/provider.d.ts

@@ -0,0 +1,17 @@
+import { type ProviderV4 } from "@ai-sdk/provider";
+import type { Idemcore } from "@idemcore/sdk";
+import type { ClientOptions } from "@idemcore/sdk";
+import { IdemcoreLanguageModel } from "./language-model.js";
+export type IdemcoreProviderSettings = ClientOptions & {
+    /** Default receipt privacy (`hash_only` or `full`). */
+    privacy?: "hash_only" | "full";
+    /** Injected client (tests). */
+    client?: Idemcore;
+};
+export type IdemcoreProvider = ProviderV4 & {
+    (modelId: string): IdemcoreLanguageModel;
+    chat(modelId: string): IdemcoreLanguageModel;
+};
+export declare function createIdemcore(options?: IdemcoreProviderSettings): IdemcoreProvider;
+/** Default provider that reads IDEMCORE_API_KEY from the environment. */
+export declare const idemcore: IdemcoreProvider;

package/dist/provider.js

@@ -0,0 +1,24 @@
+import { NoSuchModelError } from "@ai-sdk/provider";
+import { IdemcoreLanguageModel } from "./language-model.js";
+function unsupported(modelType, modelId) {
+    throw new NoSuchModelError({
+        modelId,
+        modelType,
+        message: `Idemcore does not offer ${modelType} '${modelId}'.`,
+    });
+}
+export function createIdemcore(options = {}) {
+    const languageModel = (modelId) => new IdemcoreLanguageModel(modelId, options);
+    const provider = Object.assign(function idemcore(modelId) {
+        return languageModel(modelId);
+    }, {
+        specificationVersion: "v4",
+        languageModel,
+        chat: languageModel,
+        embeddingModel: (modelId) => unsupported("embeddingModel", modelId),
+        imageModel: (modelId) => unsupported("imageModel", modelId),
+    });
+    return provider;
+}
+/** Default provider that reads IDEMCORE_API_KEY from the environment. */
+export const idemcore = createIdemcore();

package/dist/receipt.d.ts

@@ -0,0 +1,13 @@
+import type { ChatResult } from "@idemcore/sdk";
+import type { JSONObject, SharedV4ProviderMetadata } from "@ai-sdk/provider";
+export type IdemcoreReceiptMetadata = {
+    receiptId: string;
+    receipt: JSONObject;
+    salt: string | null;
+    privacy: string;
+    model: string;
+    finishReason: string | null;
+    id: string;
+};
+export declare function receiptMetadata(result: ChatResult): IdemcoreReceiptMetadata;
+export declare function providerMetadata(result: ChatResult): SharedV4ProviderMetadata;

package/dist/receipt.js

@@ -0,0 +1,16 @@
+export function receiptMetadata(result) {
+    return {
+        receiptId: result.receiptId,
+        receipt: (result.receipt ?? {}),
+        salt: result.salt,
+        privacy: result.privacy,
+        model: result.model,
+        finishReason: result.finishReason,
+        id: result.id,
+    };
+}
+export function providerMetadata(result) {
+    return {
+        idemcore: receiptMetadata(result),
+    };
+}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@idemcore/ai-sdk-provider",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Vercel AI SDK provider for Idemcore, exposing signed verifiable receipts via providerMetadata.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsx --test tests/*.test.ts"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@ai-sdk/provider": "^4.0.0",
+    "@idemcore/sdk": "0.3.0"
+  },
+  "peerDependencies": {
+    "ai": ">=7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ai": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "ai": "^7.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}