@agilesyndrome/cf-genai-llm 0.1.3

package/CONTRACT.md

@@ -0,0 +1,12 @@
+# LLM feature contract
+
+- createFeature(options) returns name and middleware.
+- createLLM(options) returns `generate`, `generateMulti`, `review`, and `reviewMulti`.
+- `generateMulti` and `reviewMulti` start all requests concurrently and preserve input order.
+- A JSON Schema may be passed as the second argument or in `{ schema }`; invalid model data gets one repair request.
+- Failed responses throw `LLMResponseError` with `code=response_failed`, `responseFailed=true`, and the raw `llmResponse`.
+- Each request emits one-line JSON request/response logs with request ID, metadata, duration, status, and token counts.
+- Middleware may return a response or call next().
+- Request state belongs in the state object supplied by cf-genai-base.
+- Cloudflare bindings are supplied by the consuming Worker environment.
+- Feature-owned migrations and schemas must be versioned with the feature.

package/LICENSE

@@ -0,0 +1,10 @@
+MIT License
+
+Copyright (c) 2026 Agile Syndrome
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:

package/README.md

@@ -0,0 +1,25 @@
+# @agilesyndrome/cf-genai-llm
+
+Reusable Cloudflare Worker LLM access with typed generation, parallel batches,
+reviews, one-shot schema repair, structured logs, and token accounting.
+
+```js
+import { createLLM } from "@agilesyndrome/cf-genai-llm";
+
+const llm = createLLM({ env, metadata: { app: "cookbook" } });
+const result = await llm.generate("Write a summary", schema, { schemaName: "summary" });
+const reviews = await llm.reviewMulti(result, reviewerPrompts, reviewSchema);
+```
+
+A feature exports an object with middleware(request, env, ctx, next, state).
+Applications layer it into @agilesyndrome/cf-genai-base:
+
+    import { createWorker } from "@agilesyndrome/cf-genai-base";
+    import { createFeature } from "@agilesyndrome/cf-genai-feature";
+
+    const feature = createFeature();
+    export default createWorker({ features: [feature], fetch: router });
+
+Keep migrations, binding names, API clients, schemas, and route policy in the
+feature package. The site supplies only its D1/R2 bindings and domain handlers.
+Do not use module-level mutable request state.

package/package.json

@@ -0,0 +1 @@
+{"name":"@agilesyndrome/cf-genai-llm","version":"0.1.3","description":"Composable Cloudflare Worker LLM generation and review client.","type":"module","exports":{".":"./src/index.js"},"files":["src","tests","README.md","CONTRACT.md","LICENSE"],"scripts":{"check":"node --check src/index.js","test":"node --test tests/*.test.mjs","build":"npm run check && npm test && npm pack --dry-run"},"license":"MIT","publishConfig":{"access":"public","provenance":true},"repository":{"type":"git","url":"git+https://github.com/agilesyndrome/cf-genai-llm.git"},"homepage":"https://github.com/agilesyndrome/cf-genai-llm#readme"}

package/src/index.js

@@ -0,0 +1,123 @@
+const DEFAULT_ENDPOINT = "https://api.openai.com/v1/responses";
+const DEFAULT_MODEL = "gpt-5.4";
+
+export class LLMResponseError extends Error {
+  constructor(message, llmResponse, cause) {
+    super(message, { cause });
+    this.name = "LLMResponseError";
+    this.code = "response_failed";
+    this.responseFailed = true;
+    this.llmResponse = llmResponse;
+  }
+}
+
+export function createLLM(options = {}) {
+  const fetcher = options.fetch || globalThis.fetch;
+  const logger = options.logger || console;
+  const endpoint = options.endpoint || ((env) => env?.OPENAI_COMPLETIONS_URL || DEFAULT_ENDPOINT);
+  const model = options.model || ((env) => env?.OPENAI_MODEL || DEFAULT_MODEL);
+  const defaults = options.metadata || {};
+  const debugLogging = options.debugLogging === true;
+  if (typeof fetcher !== "function") throw new TypeError("createLLM requires fetch");
+
+  const log = (level, event) => {
+    if (level === "debug" && !debugLogging) return;
+    try { (logger[level] || logger.info || (() => {})).call(logger, JSON.stringify({ source: "cf-genai-llm", ...event })); } catch { /* logging cannot break a request */ }
+  };
+
+  async function request(prompt, schema, requestOptions = {}) {
+    const started = Date.now();
+    const requestId = requestOptions.requestId || crypto.randomUUID();
+    const env = requestOptions.env || options.env;
+    const apiKey = requestOptions.apiKey || options.apiKey || env?.OPENAI_API_KEY;
+    if (!apiKey) throw new Error("OPENAI_API_KEY is not configured");
+    const metadata = { ...defaults, ...(requestOptions.metadata || {}) };
+    const body = { model: requestOptions.model || (typeof model === "function" ? model(env) : model), input: prompt, store: false };
+    if (Object.keys(metadata).length) body.metadata = metadata;
+    if (schema) body.text = { format: { type: "json_schema", name: requestOptions.schemaName || "response", strict: true, schema } };
+    log("debug", { event: "llm.request", requestId, metadata, model: body.model, hasSchema: Boolean(schema) });
+    let response, payload;
+    try {
+      response = await fetcher(typeof endpoint === "function" ? endpoint(env) : endpoint, { method: "POST", headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" }, body: JSON.stringify(body), signal: requestOptions.signal });
+      payload = await response.json();
+    } catch (error) {
+      log("error", { event: "llm.error", requestId, durationMs: Date.now() - started, error: error.message });
+      throw error;
+    }
+    const usage = normalizeUsage(payload?.usage);
+    if (requestOptions.onUsage) await requestOptions.onUsage(usage);
+    log(response.ok ? "info" : "error", { event: "llm.response", requestId, status: response.status, durationMs: Date.now() - started, usage, metadata });
+    if (!response.ok) throw new LLMResponseError(`LLM request failed (${response.status})`, payload);
+    const text = extractText(payload);
+    if (!text) throw new LLMResponseError("LLM returned no text", payload);
+    if (requestOptions.onText) await requestOptions.onText(text);
+    return { text, payload, usage, requestId, metadata };
+  }
+
+  async function generate(promptOrRequest, schemaOrOptions, maybeOptions) {
+    const input = normalizeGenerateArgs(promptOrRequest, schemaOrOptions, maybeOptions);
+    const first = await request(input.prompt, input.schema, input.options);
+    if (!input.schema) return parseBestEffort(first.text);
+    try { return validateAndReturn(first.text, input.schema); } catch (error) {
+      const repairPrompt = `${input.prompt}\n\nYour previous response was invalid for the required schema. Return only corrected JSON matching this schema exactly.\nSchema: ${JSON.stringify(input.schema)}\nPrevious response: ${first.text}\nValidation error: ${error.message}`;
+      let repairedResponse;
+      try {
+        repairedResponse = await request(repairPrompt, input.schema, { ...input.options, schemaName: `${input.options.schemaName || "response"}_repair` });
+        return validateAndReturn(repairedResponse.text, input.schema);
+      } catch (repairError) {
+        if (repairError instanceof LLMResponseError) throw repairError;
+        throw new LLMResponseError(`LLM response did not match the requested schema after one repair attempt: ${repairError.message}`, repairedResponse?.payload || first.payload, repairError);
+      }
+    }
+  }
+
+  async function generateMulti(requests, options = {}) {
+    const items = Array.isArray(requests) ? requests : requests.requests;
+    if (!Array.isArray(items)) throw new TypeError("generateMulti requires an array of requests");
+    const shared = options?.type ? { schema: options, options: {} } : { schema: options.schema, options };
+    return Promise.all(items.map((item) => generate(typeof item === "string" ? { prompt: item, schema: shared.schema } : { ...item, schema: item.schema || shared.schema }, { ...shared.options, ...(item.options || {}) })));
+  }
+
+  async function review(originalTextOrRequest, reviewPromptOrPrompts, schemaOrOptions, maybeOptions) {
+    if (Array.isArray(reviewPromptOrPrompts)) return reviewMulti(originalTextOrRequest, reviewPromptOrPrompts, schemaOrOptions, maybeOptions);
+    const args = normalizeReviewArgs(originalTextOrRequest, reviewPromptOrPrompts, schemaOrOptions, maybeOptions);
+    return generate(`${args.prompt}\n\nOriginal output to review:\n${args.originalText}`, args.schema, args.options);
+  }
+
+  async function reviewMulti(originalText, reviewPrompts, schemaOrOptions, maybeOptions) {
+    const { schema, options: shared } = normalizeSchemaOptions(schemaOrOptions, maybeOptions);
+    return Promise.all(reviewPrompts.map((item) => {
+      const prompt = typeof item === "string" ? item : item.prompt;
+      const name = typeof item === "string" ? undefined : item.name;
+      return review(originalText, prompt, schema, { ...shared, ...(typeof item === "object" ? item.options : {}), metadata: { ...shared.metadata, ...(name ? { reviewer: name } : {}) } });
+    }));
+  }
+
+  return { generate, generateMulti, generateWithSchema: generate, generateMultiWithSchema: generateMulti, review, reviewMulti, reviewWithSchema: review, reviewMultiWithSchema: reviewMulti };
+}
+
+function normalizeGenerateArgs(promptOrRequest, schemaOrOptions, maybeOptions) {
+  if (promptOrRequest && typeof promptOrRequest === "object" && !Array.isArray(promptOrRequest)) return { prompt: String(promptOrRequest.prompt || ""), schema: promptOrRequest.schema, options: { ...promptOrRequest.options, ...maybeOptions } };
+  const { schema, options } = normalizeSchemaOptions(schemaOrOptions, maybeOptions);
+  return { prompt: String(promptOrRequest || ""), schema, options };
+}
+function normalizeReviewArgs(originalText, reviewPrompt, schemaOrOptions, maybeOptions) { const { schema, options } = normalizeSchemaOptions(schemaOrOptions, maybeOptions); return { originalText: String(originalText || ""), prompt: String(reviewPrompt || ""), schema, options }; }
+function normalizeSchemaOptions(value, options) { if (value && value.type) return { schema: value, options: options || {} }; return { schema: value?.schema, options: { ...(value || {}), ...(options || {}) } }; }
+function extractText(payload) { return payload?.output_text || payload?.output?.flatMap((item) => item.content || []).find((item) => item.type === "output_text")?.text || ""; }
+function parseBestEffort(text) { try { return JSON.parse(text); } catch { return text; } }
+function validateAndReturn(text, schema) { let value; try { value = JSON.parse(text); } catch (error) { throw new Error(`response is not JSON: ${error.message}`); } validate(value, schema, "$root"); return value; }
+function validate(value, schema, path) {
+  if (!schema) return;
+  if (schema.type === "object") { if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${path} must be an object`); for (const key of schema.required || []) if (!(key in value)) throw new Error(`${path}.${key} is required`); if (schema.additionalProperties === false) for (const key of Object.keys(value)) if (!schema.properties?.[key]) throw new Error(`${path}.${key} is not allowed`); for (const [key, child] of Object.entries(schema.properties || {})) if (key in value) validate(value[key], child, `${path}.${key}`); return; }
+  if (schema.type === "array") { if (!Array.isArray(value)) throw new Error(`${path} must be an array`); if (schema.minItems !== undefined && value.length < schema.minItems) throw new Error(`${path} has too few items`); if (schema.maxItems !== undefined && value.length > schema.maxItems) throw new Error(`${path} has too many items`); value.forEach((item, index) => validate(item, schema.items, `${path}[${index}]`)); return; }
+  if (schema.type === "string" && typeof value !== "string") throw new Error(`${path} must be a string`);
+  if (schema.type === "integer" && !Number.isInteger(value)) throw new Error(`${path} must be an integer`);
+  if (schema.type === "number" && (typeof value !== "number" || Number.isNaN(value))) throw new Error(`${path} must be a number`);
+  if (schema.type === "boolean" && typeof value !== "boolean") throw new Error(`${path} must be a boolean`);
+  if (schema.enum && !schema.enum.includes(value)) throw new Error(`${path} must be one of ${schema.enum.join(", ")}`);
+  if (schema.minimum !== undefined && value < schema.minimum) throw new Error(`${path} is below minimum`);
+  if (schema.maximum !== undefined && value > schema.maximum) throw new Error(`${path} is above maximum`);
+}
+function normalizeUsage(usage = {}) { return { inputTokens: usage.input_tokens ?? usage.prompt_tokens ?? 0, outputTokens: usage.output_tokens ?? usage.completion_tokens ?? 0, totalTokens: usage.total_tokens ?? 0 }; }
+
+export function createFeature(options = {}) { const name = options.name || "cf-genai-llm"; return { name, middleware: async (request, env, ctx, next, state) => { if (options.boot) await options.boot(env, { request, ctx, state }); return options.handle ? options.handle(request, env, ctx, next, state) : next(); } }; }

package/tests/feature.test.mjs

@@ -0,0 +1,37 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createFeature, createLLM, LLMResponseError } from "../src/index.js";
+
+test("feature delegates to the next handler", async () => {
+  const feature = createFeature({ name: "example" });
+  const response = await feature.middleware(new Request("https://example.test/"), {}, {}, () => Response.json({ ok: true }), {});
+  assert.equal(response.status, 200);
+  assert.deepEqual(await response.json(), { ok: true });
+});
+
+const schema = { type: "object", additionalProperties: false, properties: { answer: { type: "string" } }, required: ["answer"] };
+function response(text, usage = { input_tokens: 3, output_tokens: 2, total_tokens: 5 }) { return new Response(JSON.stringify({ output_text: text, usage }), { status: 200, headers: { "content-type": "application/json" } }); }
+
+test("generate sends metadata, validates typed output, and logs token counts", async () => {
+  const calls = []; const logs = [];
+  const llm = createLLM({ apiKey: "test", fetch: async (_url, init) => { calls.push(JSON.parse(init.body)); return response("{\"answer\":\"ok\"}"); }, logger: { debug: (line) => logs.push(JSON.parse(line)), info: (line) => logs.push(JSON.parse(line)) }, metadata: { app: "test" } });
+  assert.deepEqual(await llm.generate("hello", schema, { schemaName: "answer", metadata: { type: "unit" } }), { answer: "ok" });
+  assert.equal(calls[0].metadata.type, "unit");
+  assert.equal(logs.find((entry) => entry.event === "llm.response").usage.totalTokens, 5);
+});
+
+test("generateMulti starts parallel typed requests and reviewMulti preserves order", async () => {
+  let active = 0; let peak = 0;
+  const llm = createLLM({ apiKey: "test", fetch: async (_url, init) => { active++; peak = Math.max(peak, active); const body = JSON.parse(init.body); await new Promise((resolve) => setTimeout(resolve, 5)); active--; return response(JSON.stringify({ answer: body.input.includes("two") ? "two" : "one" })); } });
+  const results = await llm.generateMulti(["one", "two"], schema);
+  assert.deepEqual(results, [{ answer: "one" }, { answer: "two" }]); assert.equal(peak, 2);
+  assert.deepEqual(await llm.reviewMulti("source", ["first", "second"], schema), [{ answer: "one" }, { answer: "one" }]);
+});
+
+test("invalid typed output gets one repair, then exposes the raw model response", async () => {
+  let count = 0;
+  const llm = createLLM({ apiKey: "test", fetch: async () => { count++; return response(count === 1 ? "{\"wrong\":true}" : "{\"answer\":\"fixed\"}"); } });
+  assert.deepEqual(await llm.generate("repair me", schema), { answer: "fixed" }); assert.equal(count, 2);
+  const failing = createLLM({ apiKey: "test", fetch: async () => response("{\"wrong\":true}") });
+  await assert.rejects(() => failing.generate("fail", schema), (error) => error instanceof LLMResponseError && error.responseFailed && error.llmResponse.output_text === "{\"wrong\":true}");
+});