@arnilo/prism 0.1.5 → 0.1.7

package/templates/provider/README.md.tmpl

@@ -0,0 +1,41 @@
+# __PACKAGE_NAME__
+
+__PROVIDER_ID__ provider package for Prism (OpenAI-compatible Chat Completions).
+
+## Quick start
+
+```bash
+npm install __PACKAGE_NAME__ @arnilo/prism
+```
+
+Wire the provider and models into your Prism host. The package registers an
+`api_key` auth method; hosts resolve the credential value — typically from the
+`__ENV_KEY__` environment variable:
+
+```ts
+import { createResolver } from "@arnilo/prism";
+import { create__PROVIDER_PASCAL__ProviderPackage } from "__PACKAGE_NAME__";
+
+const resolver = createResolver();
+resolver.registerProviderPackage(
+  create__PROVIDER_PASCAL__ProviderPackage({
+    apiKey: () => process.env.__ENV_KEY__,
+  }),
+);
+```
+
+## Models
+
+Starter catalog in `src/models.ts` (`__MODEL_ID__`). Replace with
+docs-verified model metadata (limits, costs, cache behavior) before publishing.
+
+## Conformance
+
+`npm test` builds the package and runs the offline conformance suite wired to
+`@arnilo/prism/testing/provider-conformance` (stream shape, tool-call delta
+reconstruction, header ownership, secret-leak redaction, serialized content
+coverage).
+
+## Docs
+
+See `docs/providers/__PROVIDER_ID__.md`.

package/templates/provider/docs/providers/NAME.md.tmpl

@@ -0,0 +1,61 @@
+# __PROVIDER_ID__ provider
+
+> Scaffold stub — replace with docs-verified provider documentation before publishing.
+
+## What it does
+
+`__PACKAGE_NAME__` is an OpenAI-compatible provider package for Prism
+(chat-completions style). It builds on `createOpenAICompatibleProvider` from
+`@arnilo/prism/providers/openai-compatible`.
+
+## When to use it
+
+Use it for OpenAI-compatible endpoints that follow the Chat Completions
+convention. Skip it for providers with bespoke serialization or auth.
+
+## Inputs / request
+
+- Base URL: `__BASE_URL__` (`--base-url` at scaffold time).
+- Auth: `api_key` auth method; hosts resolve the credential value (e.g. from
+  `__ENV_KEY__`).
+
+## Outputs / response / events
+
+Standard `ProviderEvent` stream: `content_delta`, `done` (with usage), or
+`error`. Tool calls arrive as deltas and are reconstructed by the host.
+
+## Request/response example
+
+```ts
+import { createResolver } from "@arnilo/prism";
+import { create__PROVIDER_PASCAL__ProviderPackage } from "__PACKAGE_NAME__";
+
+const resolver = createResolver();
+resolver.registerProviderPackage(
+  create__PROVIDER_PASCAL__ProviderPackage({ apiKey: () => process.env.__ENV_KEY__ }),
+);
+```
+
+## Implementation example
+
+`src/provider.ts` calls `createOpenAICompatibleProvider` with the scaffolded
+base URL, api key, and `doneUsage: true`. Model metadata lives in `src/models.ts`;
+cache-hint mapping helpers live in `src/cache.ts`.
+
+## Extension and configuration notes
+
+- Override `baseUrl`, `id`, `models`, `apiKey`, and `fetch` per provider
+  package/instance.
+- Cache behavior is scaffolded as `cache: { kind: "implicit" }` — confirm
+  against the provider's actual caching before relying on it.
+
+## Security and performance notes
+
+- API keys are host-resolved credentials; generated code stores no secrets.
+- Cache keys are identifiers only, sanitized via shared core helpers.
+
+## Related APIs
+
+- [OpenAI-compatible provider base](../../providers/openai-compatible.md)
+- [Provider conformance](../../provider-conformance.md)
+- [Provider layer](../../provider-layer.md)

package/templates/provider/package.json.tmpl

@@ -0,0 +1,49 @@
+{
+  "name": "__PACKAGE_NAME__",
+  "version": "__PRISM_VERSION__",
+  "description": "__PROVIDER_ID__ provider package for Prism.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/__tests__",
+    "!dist/**/*.map",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test dist/__tests__/*.test.js",
+    "pack:dry-run": "npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@arnilo/prism": "__PRISM_VERSION__"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "keywords": [
+    "prism",
+    "provider",
+    "__PROVIDER_ID__",
+    "agent",
+    "llm"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/templates/provider/src/cache.ts.tmpl

@@ -0,0 +1,20 @@
+import type { ModelConfig, ProviderRequestOptions } from "@arnilo/prism";
+import { mapCacheRetention, sanitizeCacheKey } from "@arnilo/prism";
+
+/** OpenAI-compatible `prompt_cache_key` accepted length cap. */
+export const __PROVIDER_UPPER___PROMPT_CACHE_KEY_MAX_LENGTH = 64;
+
+export function __PROVIDER_ID__PromptCacheKey(options: ProviderRequestOptions | undefined): string | undefined {
+  // Sanitize + clamp via the shared core helper so cache keys cannot carry
+  // disallowed characters or exceed the provider limit. Cache keys are
+  // session/customer identifiers only, never credentials.
+  return sanitizeCacheKey(options?.cacheKey ?? options?.sessionId, __PROVIDER_UPPER___PROMPT_CACHE_KEY_MAX_LENGTH);
+}
+
+/** Retention mapping via the shared core helper; `"short"`/`"long"` only when the model supports it. */
+export function __PROVIDER_ID__PromptCacheRetention(
+  retention: ProviderRequestOptions["cacheRetention"] | undefined,
+  model: ModelConfig,
+): "short" | "long" | undefined {
+  return mapCacheRetention(retention, model);
+}

package/templates/provider/src/index.ts.tmpl

@@ -0,0 +1,33 @@
+import { type CredentialValueSource, defineProviderPackage, type ModelConfig, type ProviderPackage } from "@arnilo/prism";
+import { __PROVIDER_ID__Models } from "./models.js";
+import { create__PROVIDER_PASCAL__Provider } from "./provider.js";
+
+export interface __PROVIDER_PASCAL__ProviderPackageOptions {
+  readonly apiKey?: CredentialValueSource;
+  readonly fetch?: typeof fetch;
+  readonly baseUrl?: string;
+  readonly id?: string;
+  readonly models?: readonly ModelConfig[];
+}
+
+export function create__PROVIDER_PASCAL__ProviderPackage(options: __PROVIDER_PASCAL__ProviderPackageOptions = {}): ProviderPackage {
+  const providerId = options.id ?? "__PROVIDER_ID__";
+  return defineProviderPackage({
+    name: "__PACKAGE_NAME__",
+    description: "__PROVIDER_ID__ provider package for Prism.",
+    docs: { links: ["docs/providers/__PROVIDER_ID__.md"] },
+    setup(api) {
+      api.registerProvider(create__PROVIDER_PASCAL__Provider(options));
+      for (const model of options.models ?? __PROVIDER_ID__Models) api.registerModel({ ...model, provider: providerId });
+      api.registerAuthMethod({ kind: "api_key", provider: providerId, credentialName: "apiKey" });
+    },
+  });
+}
+
+export { __PROVIDER_ID__Models, type __PROVIDER_PASCAL__ModelConfig } from "./models.js";
+export { create__PROVIDER_PASCAL__Provider, __PROVIDER_UPPER___DEFAULT_BASE_URL, type __PROVIDER_PASCAL__ProviderOptions } from "./provider.js";
+export {
+  __PROVIDER_ID__PromptCacheKey,
+  __PROVIDER_ID__PromptCacheRetention,
+  __PROVIDER_UPPER___PROMPT_CACHE_KEY_MAX_LENGTH,
+} from "./cache.js";

package/templates/provider/src/models.ts.tmpl

@@ -0,0 +1,16 @@
+import type { ModelConfig } from "@arnilo/prism";
+
+/** Starter catalog for __PROVIDER_ID__: replace with docs-verified model metadata. */
+export interface __PROVIDER_PASCAL__ModelConfig extends Omit<ModelConfig, "provider"> {
+  readonly provider: "__PROVIDER_ID__";
+}
+
+export const __PROVIDER_ID__Models: readonly __PROVIDER_PASCAL__ModelConfig[] = [
+  {
+    provider: "__PROVIDER_ID__",
+    model: "__MODEL_ID__",
+    limits: { contextWindow: 128_000 },
+    cost: { input: 1, output: 2, cacheRead: 0.5, unit: "per_million_tokens" },
+    cache: { kind: "implicit" },
+  },
+];

package/templates/provider/src/provider.ts.tmpl

@@ -0,0 +1,23 @@
+import type { AIProvider, CredentialValueSource } from "@arnilo/prism";
+import { createOpenAICompatibleProvider } from "@arnilo/prism/providers/openai-compatible";
+
+/** Default Chat Completions base URL for __PROVIDER_ID__ (override per provider docs). */
+export const __PROVIDER_UPPER___DEFAULT_BASE_URL = "__BASE_URL__";
+
+export interface __PROVIDER_PASCAL__ProviderOptions {
+  readonly id?: string;
+  readonly baseUrl?: string;
+  readonly apiKey?: CredentialValueSource;
+  readonly fetch?: typeof fetch;
+}
+
+export function create__PROVIDER_PASCAL__Provider(options: __PROVIDER_PASCAL__ProviderOptions = {}): AIProvider {
+  return createOpenAICompatibleProvider({
+    id: options.id ?? "__PROVIDER_ID__",
+    baseUrl: (options.baseUrl ?? __PROVIDER_UPPER___DEFAULT_BASE_URL).replace(/\/+$/, ""),
+    apiKey: options.apiKey,
+    fetch: options.fetch,
+    doneUsage: true,
+    requestFailedPrefix: "__PROVIDER_PASCAL__ request failed",
+  });
+}

package/templates/provider/src/tests/provider.test.ts.tmpl

@@ -0,0 +1,104 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { ProviderRequest } from "@arnilo/prism";
+import {
+  assertNoSecretLeak,
+  assertProviderOwnedHeadersWin,
+  assertProviderStreamConforms,
+  assertSerializedRequestCoversContent,
+  assertToolCallDeltasReconstruct,
+} from "@arnilo/prism/testing/provider-conformance";
+import { create__PROVIDER_PASCAL__Provider } from "../index.js";
+import { __PROVIDER_ID__Models } from "../models.js";
+
+const request: ProviderRequest = {
+  model: __PROVIDER_ID__Models[0],
+  messages: [
+    { role: "system", content: [{ type: "text", text: "developer instructions" }] },
+    { role: "user", content: [{ type: "text", text: "hi" }] },
+  ],
+  tools: [{ name: "lookup", parameters: { type: "object" }, execute: () => ({ toolCallId: "call_1", name: "lookup", content: [] }) }],
+};
+
+const API_KEY = "fake-__PROVIDER_ID__-key";
+
+describe("__PROVIDER_ID__ provider scaffold", () => {
+  it("streams text, usage, and done; owns its headers; leaks no secrets", async () => {
+    let captured: RequestInit | undefined;
+    const provider = create__PROVIDER_PASCAL__Provider({
+      apiKey: API_KEY,
+      fetch: (async (_input, init) => {
+        captured = init;
+        return ok(
+          sse([
+            { id: "chatcmpl-1", object: "chat.completion.chunk", choices: [{ index: 0, delta: { role: "assistant", content: "hi" } }] },
+            {
+              id: "chatcmpl-1",
+              object: "chat.completion.chunk",
+              choices: [{ index: 0, delta: {} }],
+              usage: { prompt_tokens: 5, completion_tokens: 2, total_tokens: 7 },
+            },
+          ]),
+        );
+      }) as typeof fetch,
+    });
+    const events = await assertProviderStreamConforms({
+      provider,
+      request: {
+        ...request,
+        options: {
+          ...request.options,
+          headers: { authorization: "Bearer caller-key", "content-type": "text/plain", "x-caller": "kept" },
+        },
+      },
+      expect: { text: "hi", usage: { inputTokens: 5, outputTokens: 2, totalTokens: 7 } },
+    });
+    assertNoSecretLeak(events, [API_KEY]);
+    const headers = new Headers(captured?.headers);
+    assertProviderOwnedHeadersWin(headers, {
+      owned: { authorization: `Bearer ${API_KEY}`, "content-type": "application/json" },
+      caller: { authorization: "Bearer caller-key", "content-type": "text/plain", "x-caller": "kept" },
+    });
+  });
+
+  it("serializes request content and reconstructs tool-call deltas", async () => {
+    let body: unknown;
+    const provider = create__PROVIDER_PASCAL__Provider({
+      apiKey: API_KEY,
+      fetch: (async (_input, init) => {
+        body = JSON.parse(String(init?.body));
+        return ok(
+          sse([
+            {
+              id: "c1",
+              object: "chat.completion.chunk",
+              choices: [{ index: 0, delta: { tool_calls: [{ index: 0, id: "call_1", function: { name: "lookup", arguments: "" } }] } }],
+            },
+            {
+              id: "c1",
+              object: "chat.completion.chunk",
+              choices: [{ index: 0, delta: { tool_calls: [{ index: 0, function: { arguments: '{"q":"x"}' } }] } }],
+            },
+          ]),
+        );
+      }) as typeof fetch,
+    });
+    const events = await assertProviderStreamConforms({ provider, request });
+    assertToolCallDeltasReconstruct(events, [{ index: 0, id: "call_1", name: "lookup", arguments: { q: "x" } }]);
+    assertSerializedRequestCoversContent(request, body);
+  });
+});
+
+function ok(body: ReadableStream<Uint8Array>): Response {
+  return new Response(body, { status: 200 });
+}
+
+function sse(events: readonly object[]): ReadableStream<Uint8Array> {
+  const text = `${events.map((event) => `data: ${JSON.stringify(event)}\n\n`).join("")}data: [DONE]\n\n`;
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(new TextEncoder().encode(text));
+      controller.close();
+    },
+  });
+}

package/templates/provider/tsconfig.json.tmpl

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["node"]
+  },
+  "include": ["src"]
+}