@vaxelia/ai-openai 0.1.0

package/README.md

@@ -0,0 +1,149 @@
+# @vaxelia/ai-openai
+
+A **drop-in, compliance-instrumented** wrapper around the official OpenAI SDK
+([`openai`](https://www.npmjs.com/package/openai)). Every non-streaming
+`chat.completions.create` call is logged to your tenant's decision-log endpoint
+via [`@vaxelia/ai-core`](../sdk-ai-core/README.md) — with its resilient,
+encrypted-on-disk buffer — so an AI decision is never silently lost. Every other
+method of the OpenAI SDK passes straight through to the real client untouched.
+
+`openai` is a regular dependency of this package, so the wrapper is a true
+single-install drop-in: you do not install the OpenAI SDK separately.
+
+## Install
+
+```bash
+npm install @vaxelia/ai-openai
+```
+
+Requires Node.js >= 20.
+
+## The one-line swap
+
+Change your import — keep everything else:
+
+```diff
+- import OpenAI from 'openai'
++ import OpenAI from '@vaxelia/ai-openai'
+```
+
+## Usage
+
+```ts
+import OpenAI from '@vaxelia/ai-openai'
+
+const client = new OpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+  // Optional compliance block. Every field falls back to an env var (below),
+  // so you can also pass nothing here and configure entirely from the env.
+  compliance: {
+    aiSystemId: process.env.VAXELIA_AI_SYSTEM_ID,
+    tenantApiUrl: process.env.VAXELIA_TENANT_API_URL,
+    apiKey: process.env.VAXELIA_API_KEY,
+    bufferKey: process.env.VAXELIA_BUFFER_KEY,
+    logger: (level, msg, fields) =>
+      console[level === 'debug' ? 'log' : level](JSON.stringify({ level, msg, ...fields })),
+  },
+})
+
+// Identical to the official SDK. The decision is logged for you.
+const completion = await client.chat.completions.create({
+  model: 'gpt-4o',
+  messages: [{ role: 'user', content: 'Summarize the attached contract.' }],
+})
+```
+
+With env vars set, the `compliance` block can be omitted entirely:
+
+```ts
+const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })
+```
+
+### Reaching the raw client
+
+For methods this wrapper does not instrument, the underlying OpenAI client is
+available at `client.raw`, and `client.chat.completions` proxies every other
+completions method (`retrieve`, `update`, `list`, `delete`, `parse`, `runTools`,
+`stream`, …) directly to the real resource.
+
+### Response helpers (`.withResponse()` / `.asResponse()`)
+
+The instrumented non-streaming `chat.completions.create` returns the SDK's
+`APIPromise`, not a plain `Promise`, so the official response helpers keep
+working:
+
+```ts
+const { data, response, request_id } = await client.chat.completions.create(params).withResponse()
+const raw = await client.chat.completions.create(params).asResponse()
+```
+
+The compliance decision is logged exactly once after the response is obtained,
+regardless of whether you `await` the call, use `.withResponse()`, or use
+`.asResponse()`.
+
+## Configuration & environment variables
+
+The `compliance` block is a `ReporterConfig` from `@vaxelia/ai-core`. Every field
+is optional and falls back to a matching environment variable (12-factor):
+
+| `compliance` field | Environment variable     | Description                                                  |
+| ------------------ | ------------------------ | ------------------------------------------------------------ |
+| `aiSystemId`       | `VAXELIA_AI_SYSTEM_ID`   | Registered AI system identifier.                             |
+| `tenantApiUrl`     | `VAXELIA_TENANT_API_URL` | Full decision-log POST endpoint URL.                         |
+| `apiKey`           | `VAXELIA_API_KEY`        | Bearer token for the tenant API.                             |
+| `bufferKey`        | `VAXELIA_BUFFER_KEY`     | 32-byte AES-256-GCM key, base64-encoded. Required to buffer. |
+
+For the encrypted disk buffer, the fail-closed buffer-key rule, retention, and
+backoff behaviour, see the [`@vaxelia/ai-core` README](../sdk-ai-core/README.md).
+Note: when buffering is enabled (the default) and no valid 32-byte buffer key is
+resolvable, **construction throws** (`MissingBufferKeyError` /
+`InvalidBufferKeyError`) — this wrapper surfaces that error rather than swallow
+it. To run without a disk buffer, set `compliance.bufferingEnabled: false`.
+
+## What gets logged
+
+On each instrumented `chat.completions.create` call, one decision envelope is
+reported:
+
+| Field        | Source                                                                       |
+| ------------ | ---------------------------------------------------------------------------- |
+| `aiSystemId` | `compliance.aiSystemId` / `VAXELIA_AI_SYSTEM_ID`                             |
+| `modelUsed`  | the response's `model`, falling back to the request `model`                  |
+| `input`      | the `chat.completions.create` request params                                 |
+| `output`     | the provider response (or, on failure, `{ error }` — no raw error/secrets)   |
+| `status`     | `completed` on success, `failed` when the provider call throws               |
+| `decidedAt`  | ISO-8601 timestamp at the moment of the call                                 |
+
+## Reporter-error ordering (no silent drops)
+
+The provider response is always obtained **first**; only then is the decision
+logged. If `@vaxelia/ai-core` cannot deliver the decision *and* cannot durably
+buffer it, it throws (`DecisionNotRecordedError`) — and this wrapper lets that
+error surface to your caller. This is deliberate: the whole point of the
+compliance layer is that a recorded decision is never silently dropped. If you
+prefer delivery failures to be buffered instead of thrown, keep buffering enabled
+(the default) with a valid buffer key — transient failures (network, 5xx, 429)
+are then retried with backoff and buffered to encrypted disk for later flush.
+
+On a **failed** provider call, the `failed` decision is reported first and then
+the original provider error is rethrown unchanged.
+
+## Scope & limitations
+
+- **Streaming is not instrumented in v1.** A call with `stream: true` passes
+  straight through to the real client uninstrumented, so streaming usage never
+  breaks — but no decision is logged for it yet. Streaming compliance capture is
+  a planned enhancement.
+- Only `chat.completions.create` is instrumented. All other SDK methods and
+  resources (`responses`, `embeddings`, `files`, …) delegate to the real client;
+  reach `client.raw` for the underlying object when needed.
+
+## Development
+
+```bash
+pnpm --filter @vaxelia/ai-openai test    # vitest
+pnpm --filter @vaxelia/ai-openai build   # tsc -> dist
+pnpm --filter @vaxelia/ai-openai lint    # eslint
+```
+
+See [CLAUDE.md](./CLAUDE.md) for AI-specific conventions.

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+import type OpenAISDK from 'openai';
+import { type OpenAIComplianceOptions } from './internal';
+export type { OpenAIComplianceOptions } from './internal';
+/**
+ * Drop-in, compliance-instrumented replacement for the official OpenAI client.
+ * Swap `import OpenAI from 'openai'` for `import OpenAI from '@vaxelia/ai-openai'`
+ * and keep the rest of your code: every non-streaming `chat.completions.create`
+ * call is logged to your tenant's decision-log endpoint via `@vaxelia/ai-core`
+ * (with the resilient encrypted disk buffer), and all other SDK methods pass
+ * through to the real client untouched.
+ *
+ * Streaming calls (`stream: true`) currently pass through uninstrumented —
+ * streaming compliance capture is a planned enhancement (see README).
+ *
+ * Reporter-error ordering: the provider response is obtained first; only then is
+ * the decision logged. If logging cannot deliver *and* cannot buffer the
+ * decision, `@vaxelia/ai-core` throws (hard-fail, not silent drop) and that
+ * error surfaces to the caller — deliberately, so a compliance decision is never
+ * silently lost.
+ */
+export declare class OpenAI {
+    #private;
+    constructor(options?: OpenAIComplianceOptions);
+    /**
+     * The instrumented `chat` resource. Mirrors the real client's `chat` surface;
+     * `chat.completions.create` is wrapped for compliance logging while every
+     * other method delegates to the underlying client.
+     */
+    readonly chat: OpenAISDK['chat'];
+    /**
+     * The underlying, un-instrumented OpenAI client. Reach for it when you need a
+     * method this wrapper does not yet instrument and want the raw provider object
+     * (e.g. advanced streaming helpers, the responses or embeddings resources).
+     */
+    get raw(): OpenAISDK;
+}
+export default OpenAI;

package/dist/index.js

@@ -0,0 +1,206 @@
+import { ComplianceReporter } from '@vaxelia/ai-core';
+import { RealOpenAI, } from './internal';
+/**
+ * Render a thrown provider error as a compliance-safe envelope. We never embed
+ * the raw `Error` (it may carry headers, request bodies, or credentials in
+ * provider SDK error subclasses) — only the human-readable message.
+ */
+function errorOutput(err) {
+    if (err instanceof Error)
+        return { error: err.message };
+    return { error: String(err) };
+}
+/** A request is streaming when `stream: true` is set on the params. */
+function isStreaming(params) {
+    return (typeof params === 'object' &&
+        params !== null &&
+        params.stream === true);
+}
+/**
+ * Drop-in, compliance-instrumented replacement for the official OpenAI client.
+ * Swap `import OpenAI from 'openai'` for `import OpenAI from '@vaxelia/ai-openai'`
+ * and keep the rest of your code: every non-streaming `chat.completions.create`
+ * call is logged to your tenant's decision-log endpoint via `@vaxelia/ai-core`
+ * (with the resilient encrypted disk buffer), and all other SDK methods pass
+ * through to the real client untouched.
+ *
+ * Streaming calls (`stream: true`) currently pass through uninstrumented —
+ * streaming compliance capture is a planned enhancement (see README).
+ *
+ * Reporter-error ordering: the provider response is obtained first; only then is
+ * the decision logged. If logging cannot deliver *and* cannot buffer the
+ * decision, `@vaxelia/ai-core` throws (hard-fail, not silent drop) and that
+ * error surfaces to the caller — deliberately, so a compliance decision is never
+ * silently lost.
+ */
+export class OpenAI {
+    #client;
+    #reporter;
+    constructor(options = {}) {
+        const { compliance, __clientFactory, ...clientOptions } = options;
+        // Construct the reporter first so fail-closed buffer-key validation runs at
+        // construction time (matching the bare @vaxelia/ai-core contract).
+        this.#reporter = new ComplianceReporter(compliance ?? {});
+        const factory = __clientFactory ?? ((opts) => new RealOpenAI(opts));
+        this.#client = factory(clientOptions);
+        // Build an instrumented `chat` facade. The completion path is nested
+        // (`chat` -> `completions` -> `create`), so we proxy `chat` to override only
+        // `completions`, and proxy `completions` to override only `create`. Every
+        // other property of `chat`/`completions` delegates to the real resource so
+        // the rest of the SDK surface (`completions.list`, `chat.completions.parse`,
+        // `runTools`, `stream`, ...) stays intact.
+        const realChat = this.#client.chat;
+        const instrumentedCompletions = this.#buildInstrumentedCompletions(realChat.completions);
+        this.chat = new Proxy(realChat, {
+            get: (target, prop, receiver) => {
+                if (prop === 'completions')
+                    return instrumentedCompletions;
+                const value = Reflect.get(target, prop, receiver);
+                return typeof value === 'function' ? value.bind(target) : value;
+            },
+        });
+    }
+    /**
+     * The instrumented `chat` resource. Mirrors the real client's `chat` surface;
+     * `chat.completions.create` is wrapped for compliance logging while every
+     * other method delegates to the underlying client.
+     */
+    chat;
+    /**
+     * The underlying, un-instrumented OpenAI client. Reach for it when you need a
+     * method this wrapper does not yet instrument and want the raw provider object
+     * (e.g. advanced streaming helpers, the responses or embeddings resources).
+     */
+    get raw() {
+        return this.#client;
+    }
+    /**
+     * Build the instrumented `completions` resource: a Proxy over the real
+     * resource that overrides only `create` and delegates everything else
+     * (`retrieve`, `update`, `list`, `delete`, `parse`, `runTools`, `stream`) with
+     * `this` bound to the real resource.
+     */
+    #buildInstrumentedCompletions(realCompletions) {
+        const instrumentedCreate = this.#instrumentedCreate.bind(this);
+        return new Proxy(realCompletions, {
+            get(target, prop, receiver) {
+                if (prop === 'create')
+                    return instrumentedCreate;
+                const value = Reflect.get(target, prop, receiver);
+                return typeof value === 'function' ? value.bind(target) : value;
+            },
+        });
+    }
+    /**
+     * Instrumented `chat.completions.create`. Streaming calls pass through
+     * unchanged (preserving the SDK return). Non-streaming calls return an
+     * `APIPromise` wrapper that fires the compliance `logDecision` (after the
+     * response is obtained) on whichever consumption path the caller uses —
+     * `await`, `.withResponse()`, or `.asResponse()` — so those helpers keep
+     * working and the declared `chat` type is honoured (no plain-Promise type lie).
+     * Reporter ordering and hard-fail surfacing match the failure path.
+     */
+    #instrumentedCreate(params, requestOptions) {
+        const realCreate = this.#client.chat.completions.create.bind(this.#client.chat.completions);
+        // Streaming is out of scope for v1 compliance capture; pass it through so the
+        // wrapper never breaks streaming usage. (Documented limitation.)
+        if (isStreaming(params)) {
+            return realCreate(params, requestOptions);
+        }
+        const apiPromise = realCreate(params, requestOptions);
+        return this.#instrumentNonStreaming(apiPromise, params);
+    }
+    /**
+     * Wrap a non-streaming `APIPromise` so compliance logging fires once after the
+     * response is obtained, regardless of how the caller consumes it, while the
+     * `APIPromise`'s `.withResponse()`/`.asResponse()` helpers (and its `Promise`
+     * surface) are preserved. We override only the public consumption methods via a
+     * `Proxy`; the wrapper still passes `instanceof APIPromise`/`Promise`.
+     */
+    #instrumentNonStreaming(apiPromise, params) {
+        // The provider response has been obtained when this resolves; log the
+        // decision exactly once and let any reporter hard-fail surface here. Reuse
+        // `withResponse()` so a single underlying parse feeds every consumption path
+        // (the SDK memoises the parse), and so `.asResponse()` can log too.
+        let logged;
+        const reportOnce = () => {
+            if (logged === undefined) {
+                logged = apiPromise.withResponse().then(async (withResponse) => {
+                    await this.#logCompleted(withResponse.data, params);
+                    return withResponse;
+                }, async (err) => {
+                    await this.#logFailed(err, params);
+                    throw err;
+                });
+            }
+            return logged;
+        };
+        return new Proxy(apiPromise, {
+            get: (target, prop, receiver) => {
+                switch (prop) {
+                    case 'then':
+                        return (onfulfilled, onrejected) => reportOnce()
+                            .then((withResponse) => withResponse.data)
+                            .then(onfulfilled, onrejected);
+                    case 'catch':
+                        return (onrejected) => reportOnce()
+                            .then((withResponse) => withResponse.data)
+                            .catch(onrejected);
+                    case 'finally':
+                        return (onfinally) => reportOnce()
+                            .then((withResponse) => withResponse.data)
+                            .finally(onfinally);
+                    case 'withResponse':
+                        return () => reportOnce();
+                    case 'asResponse':
+                        return () => reportOnce().then((withResponse) => withResponse.response);
+                    default: {
+                        const value = Reflect.get(target, prop, receiver);
+                        return typeof value === 'function' ? value.bind(target) : value;
+                    }
+                }
+            },
+        });
+    }
+    /**
+     * Log a `completed` decision. If the reporter cannot deliver and cannot buffer,
+     * it throws — and we let that surface (after the response was obtained), never
+     * silently dropping the decision.
+     */
+    async #logCompleted(response, params) {
+        await this.#reporter.logDecision({
+            aiSystemId: '',
+            modelUsed: this.#responseModel(response, params),
+            input: params,
+            output: response,
+            status: 'completed',
+            decidedAt: new Date().toISOString(),
+        });
+    }
+    /**
+     * Log a `failed` decision for a provider error. The caller still receives the
+     * ORIGINAL provider error (rethrown by the consumption path), and the error is
+     * captured as `{ error }` only — never the raw `Error` (it may carry secrets).
+     */
+    async #logFailed(err, params) {
+        await this.#reporter.logDecision({
+            aiSystemId: '',
+            modelUsed: this.#requestModel(params),
+            input: params,
+            output: errorOutput(err),
+            status: 'failed',
+            decidedAt: new Date().toISOString(),
+        });
+    }
+    #responseModel(response, params) {
+        const fromResponse = response?.model;
+        if (typeof fromResponse === 'string' && fromResponse !== '')
+            return fromResponse;
+        return this.#requestModel(params);
+    }
+    #requestModel(params) {
+        const fromRequest = params?.model;
+        return typeof fromRequest === 'string' ? fromRequest : '';
+    }
+}
+export default OpenAI;

package/dist/internal.d.ts

@@ -0,0 +1,40 @@
+import OpenAISDK from 'openai';
+import type { ClientOptions } from 'openai';
+import type { ReporterConfig } from '@vaxelia/ai-core';
+/**
+ * The subset of the underlying OpenAI client surface this wrapper needs to
+ * reach directly: the nested `chat.completions.create` completion path. The full
+ * client exposes far more; the wrapper preserves the rest by proxying the real
+ * resources (see {@link OpenAI}). This type exists so tests can inject a fake
+ * without depending on the entire SDK shape.
+ */
+export interface FakeOpenAIClient {
+    chat: {
+        completions: {
+            create: (params: unknown, options?: unknown) => Promise<unknown>;
+        };
+    };
+}
+/**
+ * Options accepted by the compliance-instrumented {@link OpenAI} client: every
+ * option the official SDK accepts, plus an optional `compliance` block that
+ * configures the shared {@link ComplianceReporter}. The `compliance` block is
+ * stripped before the remaining options are handed to the real SDK, so this is a
+ * true drop-in replacement.
+ */
+export interface OpenAIComplianceOptions extends ClientOptions {
+    /**
+     * Compliance reporter configuration. Every field falls back to the matching
+     * environment variable (see `@vaxelia/ai-core`), so zero-config-from-env
+     * works. Omit entirely to configure the reporter purely from the environment.
+     */
+    compliance?: ReporterConfig;
+    /**
+     * Test-only seam: supply the underlying OpenAI client instead of letting the
+     * wrapper construct one. Never used in production; not part of the public
+     * contract. Underscore-prefixed to signal "internal".
+     */
+    __clientFactory?: (options: ClientOptions) => unknown;
+}
+/** The concrete underlying-client constructor, narrowed for reuse. */
+export declare const RealOpenAI: typeof OpenAISDK;

package/dist/internal.js

@@ -0,0 +1,3 @@
+import OpenAISDK from 'openai';
+/** The concrete underlying-client constructor, narrowed for reuse. */
+export const RealOpenAI = OpenAISDK;

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@vaxelia/ai-openai",
+  "version": "0.1.0",
+  "description": "Drop-in, compliance-instrumented wrapper around the official OpenAI SDK (openai). Logs every AI decision via @vaxelia/ai-core.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "openai": "^6.39.1",
+    "@vaxelia/ai-core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.1.0",
+    "eslint": "^9.32.0",
+    "typescript": "^5.3.0",
+    "typescript-eslint": "^8.59.4",
+    "vitest": "^1.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src test --ext .ts"
+  }
+}