@agilesyndrome/cf-genai-llm 4.1.2 → 5.0.0

package/CONTRACT.md

@@ -1,7 +1,8 @@
 # LLM feature contract
 
 - createFeature(options) returns name and middleware.
-- createLLM(options) returns `generate`, `generateMulti`, `review`, and `reviewMulti`.
+- createLLM(options) returns `generate`, `generateJob`, `generateMulti`, `review`, and `reviewMulti`.
+- `generateJob(jobId, ...)` executes an already-dispatched base job, reports progress without model text, and stores `{}` unless `job.toJobResult` supplies a compact domain result.
 - `generateMulti` and `reviewMulti` start all requests concurrently and preserve input order.
 - The client uses the OpenAI Responses-compatible contract; OpenAI is the default endpoint and arbitrary compatible endpoints are supported.
 - `LLM_API_URL`, `LLM_API_TOKEN`, and `LLM_MODEL` are the universal configuration variables.

package/README.md

@@ -11,6 +11,26 @@ const result = await llm.generate("Write a summary", schema, { schemaName: "summ
 const reviews = await llm.reviewMulti(result, reviewerPrompts, reviewSchema);
 ```
 
+Long-running generation is explicit. Dispatch a base job to an application-owned
+Cloudflare Workflow, then execute the generation from that Workflow with the
+same job ID:
+
+```js
+const execution = await llm.generateJob(event.payload.jobId, prompt, schema, {
+  env: this.env,
+  job: {
+    toJobResult: async (recipe) => {
+      await recipes.save(recipe);
+      return { resourceType: "recipe", resourceId: recipe.id };
+    },
+  },
+});
+```
+
+`generateJob` reports phases through base's durable job events. It deliberately
+stores no generated content by default; `job.toJobResult` should persist the
+domain value and return only the small result descriptor needed by the UI.
+
 ## Providers and AI Gateway
 
 The client speaks the OpenAI Responses-compatible API. OpenAI is the default

package/changelog.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 5.0.0
+
+- Require cf-genai-base 5.
+- Add explicit durable generation through `generateJob`.
+- Report generation progress through base job events.
+- Keep model output out of durable job records unless the application supplies a compact result mapper.

package/package.json

@@ -1 +1 @@
-{"name":"@agilesyndrome/cf-genai-llm","version":"4.1.2","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","dependencies":{"@agilesyndrome/cf-genai-base":"^4.1.1"}}
+{"name":"@agilesyndrome/cf-genai-llm","version":"5.0.0","description":"Composable Cloudflare Worker LLM generation and review client.","type":"module","exports":{".":"./src/index.js"},"files":["src","tests","README.md","CONTRACT.md","changelog.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","dependencies":{"@agilesyndrome/cf-genai-base":"^5.0.0"}}

package/src/index.js

@@ -1,10 +1,10 @@
 const DEFAULT_ENDPOINT = "https://api.openai.com/v1/responses";
 const DEFAULT_MODEL = "gpt-5.4";
 export const PACKAGE_NAME = "@agilesyndrome/cf-genai-llm";
-export const VERSION = "4.1.1";
+export const VERSION = "5.0.0";
 export class LLMCircuitBreakerError extends Error { constructor(message = "LLM generation is temporarily unavailable") { super(message); this.name = "LLMCircuitBreakerError"; this.code = "circuit_breaker_open"; this.circuitBreakerOpen = true; } }
 
-import { getCircuitBreaker, registerCircuitBreaker, registerHealthcheck, setCircuitBreaker } from "@agilesyndrome/cf-genai-base";
+import { executeJob, getCircuitBreaker, registerCircuitBreaker, registerHealthcheck, setCircuitBreaker } from "@agilesyndrome/cf-genai-base";
 export class LLMResponseError extends Error {
   constructor(message, llmResponse, cause) {
     super(message, { cause });
@@ -87,6 +87,36 @@ export function createLLM(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 generateJob(jobId, promptOrRequest, schemaOrOptions, maybeOptions) {
+    const input = normalizeGenerateArgs(promptOrRequest, schemaOrOptions, maybeOptions);
+    const jobOptions = input.options.job || {};
+    const generationOptions = { ...input.options };
+    delete generationOptions.job;
+    const env = generationOptions.env || options.env;
+    if (!env?.DB) throw new TypeError("generateJob requires an environment with DB");
+    const onText = generationOptions.onText;
+    const onUsage = generationOptions.onUsage;
+    return executeJob(env, jobId, async ({ report }) => {
+      await report({ phase: "generating" });
+      const value = await generate(input.prompt, input.schema, {
+        ...generationOptions,
+        onText: async (text) => {
+          if (onText) await onText(text);
+          await report({ phase: "generated" });
+        },
+        onUsage: async (usage) => {
+          if (onUsage) await onUsage(usage);
+          await report({ phase: "generating", usage });
+        },
+      });
+      return value;
+    }, {
+      who: jobOptions.who || generationOptions.who || "system:update",
+      ctx: jobOptions.ctx || generationOptions.ctx,
+      toJobResult: jobOptions.toJobResult || emptyJobResult,
+    });
+  }
+
   async function review(originalTextOrRequest, reviewPromptOrPrompts, schemaOrOptions, maybeOptions) {
     if (Array.isArray(reviewPromptOrPrompts)) return reviewMulti(originalTextOrRequest, reviewPromptOrPrompts, schemaOrOptions, maybeOptions);
     const args = normalizeReviewArgs(originalTextOrRequest, reviewPromptOrPrompts, schemaOrOptions, maybeOptions);
@@ -102,7 +132,7 @@ export function createLLM(options = {}) {
     }));
   }
 
-  return { listModels, generate, generateMulti, generateWithSchema: generate, generateMultiWithSchema: generateMulti, review, reviewMulti, reviewWithSchema: review, reviewMultiWithSchema: reviewMulti };
+  return { listModels, generate, generateJob, generateMulti, generateWithSchema: generate, generateMultiWithSchema: generateMulti, review, reviewMulti, reviewWithSchema: review, reviewMultiWithSchema: reviewMulti };
 }
 
 function normalizeGenerateArgs(promptOrRequest, schemaOrOptions, maybeOptions) {
@@ -155,5 +185,6 @@ function validate(value, schema, path) {
   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 }; }
+function emptyJobResult() { return {}; }
 
 export function createFeature(options = {}) { const name = options.name || "cf-genai-llm"; const client = createLLM({ ...options, feature: name }); return { name, displayName: options.displayName || name, packageName: PACKAGE_NAME, version: VERSION, dataResources: options.dataResources || [], routes: options.routes || [], healthcheck: async (env) => { try { resolveConfig(options, {}, env); } catch { return [{ feature: name, component: "configuration", displayName: "LLM configuration", state: "red" }]; } try { await client.listModels({ env, who: "system:update" }); return [{ feature: name, component: "configuration", displayName: "LLM configuration", state: "green" }]; } catch { return [{ feature: name, component: "configuration", displayName: "LLM configuration", state: "yellow" }]; } }, healthchecks: options.healthchecks || [{ feature: name, component: "llm-models", displayName: "LLM model availability", state: "yellow" }], circuitBreakers: options.circuitBreakers || [{ id: name + ":llm-models", feature: name, name: "llm-models", displayName: "LLM model access", state: "on", allowSelfHealing: true, healthchecks: [name + ":llm-models"] }], 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

@@ -1,10 +1,11 @@
 import test from "node:test";
 import assert from "node:assert/strict";
+import { createJob, getJob } from "@agilesyndrome/cf-genai-base";
 import { createFeature, createLLM, LLMResponseError } from "../src/index.js";
 
 test("feature delegates to the next handler", async () => {
   const feature = createFeature({ name: "example" });
-  assert.equal(feature.version, "4.1.1");
+  assert.equal(feature.version, "5.0.0");
   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 });
@@ -13,6 +14,34 @@ test("feature delegates to the next handler", async () => {
 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" } }); }
 
+function jobDatabase() {
+  const jobs = new Map();
+  const events = [];
+  return {
+    jobs,
+    events,
+    prepare(sql) {
+      const statement = { args: [], bind(...args) { this.args = args; return this; } };
+      statement.run = async () => {
+        if (sql.includes("INSERT INTO core_jobs")) {
+          const [id, type, status, ownerId, tenantId, resourceType, resourceId, input, progress, createdAt, updatedAt, expiresAt] = statement.args;
+          jobs.set(id, { id, type, status, owner_id: ownerId, tenant_id: tenantId, resource_type: resourceType, resource_id: resourceId, input_json: input, result_json: "{}", error_json: null, progress_json: progress, created_at: createdAt, started_at: null, finished_at: null, updated_at: updatedAt, expires_at: expiresAt });
+        } else if (sql.includes("INSERT INTO core_job_events")) {
+          const [id, jobId, type, payload] = statement.args;
+          events.push({ id, job_id: jobId, type, payload_json: payload, created_at: new Date().toISOString() });
+        } else if (sql.startsWith("UPDATE core_jobs SET")) {
+          const row = jobs.get(statement.args.at(-1));
+          for (const [index, assignment] of [...sql.matchAll(/([a-z_]+) = \?/g)].entries()) row[assignment[1]] = statement.args[index];
+        }
+        return {};
+      };
+      statement.first = async () => sql.includes("SELECT * FROM core_jobs WHERE id") ? jobs.get(statement.args[0]) || null : null;
+      statement.all = async () => ({ results: [] });
+      return statement;
+    },
+  };
+}
+
 test("generate sends metadata, validates typed output, and logs token counts", async () => {
   const calls = []; const logs = [];
   const llm = createLLM({ env: { LLM_API_TOKEN: "test" }, fetch: async (url, init) => { calls.push({ url, headers: init.headers, body: 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" } });
@@ -26,6 +55,20 @@ test("generate sends metadata, validates typed output, and logs token counts", a
   assert.equal(responseLog.gateway, false);
 });
 
+test("generateJob updates a dispatched base job without persisting generated content", async () => {
+  const DB = jobDatabase();
+  const env = { DB, LLM_API_TOKEN: "test", eventHandler: async () => {} };
+  const job = await createJob(env, { type: "llm.recipe", ownerId: "user-1" });
+  const llm = createLLM({ env, fetch: async () => response("{\"answer\":\"secret output\"}") });
+  const execution = await llm.generateJob(job.id, "hello", schema, {
+    job: { toJobResult: (value) => ({ answerLength: value.answer.length }) },
+  });
+  assert.deepEqual(execution.value, { answer: "secret output" });
+  assert.deepEqual(execution.job.result, { answerLength: 13 });
+  assert.equal((await getJob(env, job.id)).status, "succeeded");
+  assert.deepEqual(DB.events.map((event) => event.type), ["job.created", "job.running", "job.progress", "job.progress", "job.progress", "job.succeeded"]);
+});
+
 test("Cloudflare AI Gateway routes Responses and model health through the gateway", async () => {
   const calls = [];
   const llm = createLLM({