@bpmnkit/casen-worker-ai 0.1.0

package/package.json

@@ -0,0 +1,69 @@
+{
+	"name": "@bpmnkit/casen-worker-ai",
+	"version": "0.1.0",
+	"private": false,
+	"description": "AI task worker plugin for casen — classify, summarize, extract, and decide using Claude",
+	"type": "module",
+	"main": "./dist/index.js",
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"keywords": [
+		"casen-plugin",
+		"casen-worker",
+		"camunda",
+		"worker",
+		"ai",
+		"claude",
+		"anthropic",
+		"bpmnkit"
+	],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/bpmnkit/monorepo"
+	},
+	"homepage": "https://bpmnkit.com",
+	"bugs": {
+		"url": "https://github.com/bpmnkit/monorepo/issues"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"casen": {
+		"group": "ai-worker",
+		"commands": [
+			{
+				"name": "classify",
+				"description": "Classify text into one of the given categories"
+			},
+			{
+				"name": "summarize",
+				"description": "Summarize text to a given length and style"
+			},
+			{
+				"name": "extract",
+				"description": "Extract structured fields from unstructured text"
+			},
+			{
+				"name": "decide",
+				"description": "Make a boolean decision based on a question, context, and optional policy"
+			}
+		]
+	},
+	"scripts": {
+		"build": "tsc",
+		"typecheck": "tsc --noEmit",
+		"check": "biome check .",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"@anthropic-ai/sdk": "^0.40.0"
+	},
+	"devDependencies": {
+		"@bpmnkit/cli-sdk": "workspace:*"
+	}
+}

package/src/config.test.ts

@@ -0,0 +1,40 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest"
+import { resolveConfig } from "./config.js"
+
+describe("resolveConfig", () => {
+	const original = { ...process.env }
+
+	beforeEach(() => {
+		for (const key of ["ANTHROPIC_API_KEY", "AI_MODEL", "AI_MAX_TOKENS", "AI_TIMEOUT_MS"]) {
+			Reflect.deleteProperty(process.env, key)
+		}
+	})
+
+	afterEach(() => {
+		Object.assign(process.env, original)
+	})
+
+	it("throws when ANTHROPIC_API_KEY is not set", () => {
+		expect(() => resolveConfig()).toThrow("ANTHROPIC_API_KEY")
+	})
+
+	it("returns defaults when only API key is set", () => {
+		process.env.ANTHROPIC_API_KEY = "sk-test"
+		const cfg = resolveConfig()
+		expect(cfg.apiKey).toBe("sk-test")
+		expect(cfg.model).toBe("claude-3-5-haiku-20241022")
+		expect(cfg.maxTokens).toBe(1024)
+		expect(cfg.timeoutMs).toBe(60000)
+	})
+
+	it("overrides defaults from env vars", () => {
+		process.env.ANTHROPIC_API_KEY = "sk-test"
+		process.env.AI_MODEL = "claude-opus-4-6"
+		process.env.AI_MAX_TOKENS = "2048"
+		process.env.AI_TIMEOUT_MS = "30000"
+		const cfg = resolveConfig()
+		expect(cfg.model).toBe("claude-opus-4-6")
+		expect(cfg.maxTokens).toBe(2048)
+		expect(cfg.timeoutMs).toBe(30000)
+	})
+})

package/src/config.ts

@@ -0,0 +1,27 @@
+export interface AiWorkerConfig {
+	apiKey: string
+	model: string
+	maxTokens: number
+	timeoutMs: number
+}
+
+/**
+ * Resolves config from environment variables.
+ * Throws immediately if ANTHROPIC_API_KEY is absent so the error surfaces at
+ * worker startup rather than mid-job.
+ */
+export function resolveConfig(): AiWorkerConfig {
+	const apiKey = process.env.ANTHROPIC_API_KEY
+	if (!apiKey) {
+		throw new Error(
+			"ANTHROPIC_API_KEY is not set. Export it before starting the AI worker:\n" +
+				"  export ANTHROPIC_API_KEY=sk-ant-...",
+		)
+	}
+	return {
+		apiKey,
+		model: process.env.AI_MODEL ?? "claude-3-5-haiku-20241022",
+		maxTokens: Number(process.env.AI_MAX_TOKENS ?? "1024"),
+		timeoutMs: Number(process.env.AI_TIMEOUT_MS ?? "60000"),
+	}
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+import { type CasenPlugin, createWorkerCommand } from "@bpmnkit/cli-sdk"
+import { resolveConfig } from "./config.js"
+import { classify } from "./operations/classify.js"
+import { decide } from "./operations/decide.js"
+import { extract } from "./operations/extract.js"
+import { summarize } from "./operations/summarize.js"
+
+const plugin: CasenPlugin = {
+	id: "com.bpmnkit.casen-worker-ai",
+	name: "AI Worker",
+	version: "0.1.0",
+	groups: [
+		{
+			name: "ai-worker",
+			description: "AI-powered job workers — classify, summarize, extract, decide",
+			commands: [
+				createWorkerCommand({
+					jobType: "com.bpmnkit.ai.classify",
+					description: "Classify text into one of the given categories",
+					defaultVariables: { category: "unknown", confidence: 0, rationale: "no handler" },
+					async processJob(job) {
+						return classify(job, resolveConfig())
+					},
+				}),
+				createWorkerCommand({
+					jobType: "com.bpmnkit.ai.summarize",
+					description: "Summarize text to a given length and style",
+					defaultVariables: { summary: "", wordCount: 0 },
+					async processJob(job) {
+						return summarize(job, resolveConfig())
+					},
+				}),
+				createWorkerCommand({
+					jobType: "com.bpmnkit.ai.extract",
+					description: "Extract structured fields from unstructured text",
+					defaultVariables: { extracted: {}, missingFields: [] },
+					async processJob(job) {
+						return extract(job, resolveConfig())
+					},
+				}),
+				createWorkerCommand({
+					jobType: "com.bpmnkit.ai.decide",
+					description: "Make a boolean decision based on a question, context, and optional policy",
+					defaultVariables: { decision: false, rationale: "", confidence: 0 },
+					async processJob(job) {
+						return decide(job, resolveConfig())
+					},
+				}),
+			],
+		},
+	],
+}
+
+export default plugin

package/src/llm.ts

@@ -0,0 +1,67 @@
+import Anthropic from "@anthropic-ai/sdk"
+import type { AiWorkerConfig } from "./config.js"
+
+export class RetryableError extends Error {
+	constructor(message: string) {
+		super(message)
+		this.name = "RetryableError"
+	}
+}
+
+/**
+ * Calls the Anthropic messages API and returns the text content.
+ *
+ * Throws {@link RetryableError} for transient failures (rate limits, timeouts,
+ * 5xx errors) so callers can return `{ outcome: "fail" }` and let Camunda retry.
+ * Throws a plain Error for hard failures (auth, invalid request).
+ */
+export async function callLlm(
+	systemPrompt: string,
+	userMessage: string,
+	config: AiWorkerConfig,
+): Promise<string> {
+	const client = new Anthropic({
+		apiKey: config.apiKey,
+		timeout: config.timeoutMs,
+		maxRetries: 0, // we let Camunda handle retries via failJob
+	})
+
+	let message: Anthropic.Message
+	try {
+		message = await client.messages.create({
+			model: config.model,
+			max_tokens: config.maxTokens,
+			system: systemPrompt,
+			messages: [{ role: "user", content: userMessage }],
+		})
+	} catch (err) {
+		if (
+			err instanceof Anthropic.RateLimitError ||
+			err instanceof Anthropic.APIConnectionTimeoutError
+		) {
+			throw new RetryableError(err.message)
+		}
+		if (err instanceof Anthropic.InternalServerError) {
+			throw new RetryableError(err.message)
+		}
+		throw err
+	}
+
+	const block = message.content[0]
+	if (!block || block.type !== "text") {
+		throw new Error("Unexpected response shape from Anthropic API")
+	}
+	return block.text
+}
+
+/**
+ * Parses an LLM response as JSON. Handles responses wrapped in a markdown
+ * code fence (```json ... ```) which models sometimes emit.
+ */
+export function parseJsonResponse<T>(text: string): T {
+	const stripped = text
+		.replace(/^```(?:json)?\s*/i, "")
+		.replace(/\s*```\s*$/, "")
+		.trim()
+	return JSON.parse(stripped) as T
+}

package/src/operations/classify.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it, vi } from "vitest"
+import type { AiWorkerConfig } from "../config.js"
+import * as llmModule from "../llm.js"
+import { classify } from "./classify.js"
+
+const cfg: AiWorkerConfig = {
+	apiKey: "test",
+	model: "claude-test",
+	maxTokens: 512,
+	timeoutMs: 5000,
+}
+
+function makeJob(variables: Record<string, unknown>) {
+	return {
+		jobKey: "1",
+		processDefinitionId: "p1",
+		elementId: "e1",
+		processInstanceKey: "i1",
+		variables,
+	}
+}
+
+describe("classify", () => {
+	it("returns complete with valid category", async () => {
+		vi.spyOn(llmModule, "callLlm").mockResolvedValue(
+			JSON.stringify({ category: "billing", confidence: 0.9, rationale: "mentions invoice" }),
+		)
+		const result = await classify(
+			makeJob({ input: "I need help with my invoice", categories: ["billing", "technical"] }),
+			cfg,
+		)
+		expect(result.outcome).toBe("complete")
+		if (result.outcome === "complete") {
+			expect(result.variables.category).toBe("billing")
+			expect(result.variables.confidence).toBe(0.9)
+		}
+	})
+
+	it("returns error when model returns category outside allowed list", async () => {
+		vi.spyOn(llmModule, "callLlm").mockResolvedValue(
+			JSON.stringify({ category: "other", confidence: 0.5, rationale: "unsure" }),
+		)
+		const result = await classify(
+			makeJob({ input: "anything", categories: ["billing", "technical"] }),
+			cfg,
+		)
+		expect(result.outcome).toBe("error")
+		if (result.outcome === "error") {
+			expect(result.errorCode).toBe("AI_INVALID_CATEGORY")
+		}
+	})
+
+	it("returns error when model returns non-JSON", async () => {
+		vi.spyOn(llmModule, "callLlm").mockResolvedValue("Sorry, I cannot classify this.")
+		const result = await classify(
+			makeJob({ input: "anything", categories: ["billing", "technical"] }),
+			cfg,
+		)
+		expect(result.outcome).toBe("error")
+		if (result.outcome === "error") {
+			expect(result.errorCode).toBe("AI_PARSE_ERROR")
+		}
+	})
+
+	it("returns fail on RetryableError", async () => {
+		vi.spyOn(llmModule, "callLlm").mockRejectedValue(new llmModule.RetryableError("rate limited"))
+		const result = await classify(makeJob({ input: "anything", categories: ["billing"] }), cfg)
+		expect(result.outcome).toBe("fail")
+		if (result.outcome === "fail") {
+			expect(result.retryBackOff).toBe(30_000)
+		}
+	})
+
+	it("returns error on hard API failure", async () => {
+		vi.spyOn(llmModule, "callLlm").mockRejectedValue(new Error("invalid api key"))
+		const result = await classify(makeJob({ input: "anything", categories: ["billing"] }), cfg)
+		expect(result.outcome).toBe("error")
+		if (result.outcome === "error") {
+			expect(result.errorCode).toBe("AI_API_ERROR")
+		}
+	})
+
+	it("returns error when categories variable is missing", async () => {
+		const result = await classify(makeJob({ input: "text" }), cfg)
+		expect(result.outcome).toBe("error")
+		if (result.outcome === "error") {
+			expect(result.errorCode).toBe("AI_INVALID_INPUT")
+		}
+	})
+
+	it("handles markdown code-fence wrapped JSON", async () => {
+		vi.spyOn(llmModule, "callLlm").mockResolvedValue(
+			`\`\`\`json\n${JSON.stringify({ category: "billing", confidence: 0.8, rationale: "invoice" })}\n\`\`\``,
+		)
+		const result = await classify(
+			makeJob({ input: "invoice question", categories: ["billing", "technical"] }),
+			cfg,
+		)
+		expect(result.outcome).toBe("complete")
+	})
+})

package/src/operations/classify.ts

@@ -0,0 +1,85 @@
+import type { WorkerJob, WorkerJobResult } from "@bpmnkit/cli-sdk"
+import type { AiWorkerConfig } from "../config.js"
+import { RetryableError, callLlm, parseJsonResponse } from "../llm.js"
+
+interface ClassifyResponse {
+	category: string
+	confidence: number
+	rationale: string
+}
+
+const SYSTEM_PROMPT = `You are a text classification assistant.
+The user will provide text to classify and a list of allowed categories.
+Respond ONLY with valid JSON matching this exact shape:
+{ "category": "<one of the allowed categories>", "confidence": <0.0–1.0>, "rationale": "<one sentence>" }
+Do not include any prose outside the JSON object.`
+
+/**
+ * Classifies job.variables.input into one of job.variables.categories.
+ *
+ * Required job variables:
+ * - input: string — the text to classify
+ * - categories: string[] — allowed category names
+ *
+ * Optional:
+ * - context: string — additional domain context for the model
+ *
+ * Output variables: category, confidence, rationale, aiModel, processedAt
+ */
+export async function classify(job: WorkerJob, config: AiWorkerConfig): Promise<WorkerJobResult> {
+	const input = String(job.variables.input ?? "")
+	const categories = job.variables.categories
+	if (!Array.isArray(categories) || categories.length === 0) {
+		return {
+			outcome: "error",
+			errorCode: "AI_INVALID_INPUT",
+			errorMessage: 'Job variable "categories" must be a non-empty array of strings.',
+		}
+	}
+	const context = job.variables.context ? `\nContext: ${String(job.variables.context)}` : ""
+	const userMessage = `Allowed categories: ${JSON.stringify(categories)}${context}\n\nText to classify:\n${input}`
+
+	let raw: string
+	try {
+		raw = await callLlm(SYSTEM_PROMPT, userMessage, config)
+	} catch (err) {
+		if (err instanceof RetryableError) {
+			return { outcome: "fail", errorMessage: err.message, retries: 2, retryBackOff: 30_000 }
+		}
+		return {
+			outcome: "error",
+			errorCode: "AI_API_ERROR",
+			errorMessage: err instanceof Error ? err.message : String(err),
+		}
+	}
+
+	let parsed: ClassifyResponse
+	try {
+		parsed = parseJsonResponse<ClassifyResponse>(raw)
+	} catch {
+		return {
+			outcome: "error",
+			errorCode: "AI_PARSE_ERROR",
+			errorMessage: `Model returned non-JSON response: ${raw.slice(0, 200)}`,
+		}
+	}
+
+	if (!categories.includes(parsed.category)) {
+		return {
+			outcome: "error",
+			errorCode: "AI_INVALID_CATEGORY",
+			errorMessage: `Model returned category "${parsed.category}" which is not in the allowed list: ${JSON.stringify(categories)}`,
+		}
+	}
+
+	return {
+		outcome: "complete",
+		variables: {
+			category: parsed.category,
+			confidence: parsed.confidence,
+			rationale: parsed.rationale,
+			aiModel: config.model,
+			processedAt: new Date().toISOString(),
+		},
+	}
+}

package/src/operations/decide.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it, vi } from "vitest"
+import type { AiWorkerConfig } from "../config.js"
+import * as llmModule from "../llm.js"
+import { decide } from "./decide.js"
+
+const cfg: AiWorkerConfig = {
+	apiKey: "test",
+	model: "claude-test",
+	maxTokens: 512,
+	timeoutMs: 5000,
+}
+
+function makeJob(variables: Record<string, unknown>) {
+	return {
+		jobKey: "1",
+		processDefinitionId: "p1",
+		elementId: "e1",
+		processInstanceKey: "i1",
+		variables,
+	}
+}
+
+describe("decide", () => {
+	it("returns complete with decision=true", async () => {
+		vi.spyOn(llmModule, "callLlm").mockResolvedValue(
+			JSON.stringify({ decision: true, rationale: "Meets all criteria.", confidence: 0.92 }),
+		)
+		const result = await decide(
+			makeJob({ question: "Should we approve?", context: "Score 720, amount 30000" }),
+			cfg,
+		)
+		expect(result.outcome).toBe("complete")
+		if (result.outcome === "complete") {
+			expect(result.variables.decision).toBe(true)
+			expect(result.variables.confidence).toBe(0.92)
+		}
+	})
+
+	it("returns complete with decision=false", async () => {
+		vi.spyOn(llmModule, "callLlm").mockResolvedValue(
+			JSON.stringify({ decision: false, rationale: "Exceeds threshold.", confidence: 0.87 }),
+		)
+		const result = await decide(makeJob({ question: "Approve?", context: "debt ratio 55%" }), cfg)
+		expect(result.outcome).toBe("complete")
+		if (result.outcome === "complete") {
+			expect(result.variables.decision).toBe(false)
+		}
+	})
+
+	it("returns error on parse failure", async () => {
+		vi.spyOn(llmModule, "callLlm").mockResolvedValue("I recommend approval based on the data.")
+		const result = await decide(makeJob({ question: "Approve?", context: "context" }), cfg)
+		expect(result.outcome).toBe("error")
+		if (result.outcome === "error") expect(result.errorCode).toBe("AI_PARSE_ERROR")
+	})
+
+	it("returns fail on RetryableError", async () => {
+		vi.spyOn(llmModule, "callLlm").mockRejectedValue(new llmModule.RetryableError("503"))
+		const result = await decide(makeJob({ question: "Approve?", context: "context" }), cfg)
+		expect(result.outcome).toBe("fail")
+		if (result.outcome === "fail") expect(result.retries).toBe(2)
+	})
+
+	it("includes policy in prompt when provided", async () => {
+		const spy = vi
+			.spyOn(llmModule, "callLlm")
+			.mockResolvedValue(
+				JSON.stringify({ decision: false, rationale: "Violates policy.", confidence: 0.95 }),
+			)
+		await decide(
+			makeJob({
+				question: "Approve?",
+				context: "score 650",
+				policy: "Minimum score is 680.",
+			}),
+			cfg,
+		)
+		const call = spy.mock.calls[0]
+		const [, userMessage] = call ?? []
+		expect(userMessage).toContain("Minimum score is 680.")
+	})
+})

package/src/operations/decide.ts

@@ -0,0 +1,70 @@
+import type { WorkerJob, WorkerJobResult } from "@bpmnkit/cli-sdk"
+import type { AiWorkerConfig } from "../config.js"
+import { RetryableError, callLlm, parseJsonResponse } from "../llm.js"
+
+interface DecideResponse {
+	decision: boolean
+	rationale: string
+	confidence: number
+}
+
+const SYSTEM_PROMPT = `You are a decision-making assistant.
+The user will provide a yes/no question, relevant context, and optionally a policy to apply.
+Respond ONLY with valid JSON matching this exact shape:
+{ "decision": <true|false>, "rationale": "<one or two sentences>", "confidence": <0.0–1.0> }
+Apply the policy strictly if provided. Do not include any prose outside the JSON object.`
+
+/**
+ * Makes a boolean decision for job.variables.question based on context and an optional policy.
+ *
+ * Required job variables:
+ * - question: string — the yes/no question to answer
+ * - context: string — relevant facts for the decision
+ *
+ * Optional:
+ * - policy: string — natural language policy text the model must apply
+ *
+ * Output variables: decision (boolean), rationale, confidence, aiModel, processedAt
+ */
+export async function decide(job: WorkerJob, config: AiWorkerConfig): Promise<WorkerJobResult> {
+	const question = String(job.variables.question ?? "")
+	const context = String(job.variables.context ?? "")
+	const policy = job.variables.policy ? `\nPolicy to apply:\n${String(job.variables.policy)}` : ""
+	const userMessage = `Question: ${question}\n\nContext:\n${context}${policy}`
+
+	let raw: string
+	try {
+		raw = await callLlm(SYSTEM_PROMPT, userMessage, config)
+	} catch (err) {
+		if (err instanceof RetryableError) {
+			return { outcome: "fail", errorMessage: err.message, retries: 2, retryBackOff: 30_000 }
+		}
+		return {
+			outcome: "error",
+			errorCode: "AI_API_ERROR",
+			errorMessage: err instanceof Error ? err.message : String(err),
+		}
+	}
+
+	let parsed: DecideResponse
+	try {
+		parsed = parseJsonResponse<DecideResponse>(raw)
+	} catch {
+		return {
+			outcome: "error",
+			errorCode: "AI_PARSE_ERROR",
+			errorMessage: `Model returned non-JSON response: ${raw.slice(0, 200)}`,
+		}
+	}
+
+	return {
+		outcome: "complete",
+		variables: {
+			decision: parsed.decision,
+			rationale: parsed.rationale,
+			confidence: parsed.confidence,
+			aiModel: config.model,
+			processedAt: new Date().toISOString(),
+		},
+	}
+}

package/src/operations/extract.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it, vi } from "vitest"
+import type { AiWorkerConfig } from "../config.js"
+import * as llmModule from "../llm.js"
+import { extract } from "./extract.js"
+
+const cfg: AiWorkerConfig = {
+	apiKey: "test",
+	model: "claude-test",
+	maxTokens: 512,
+	timeoutMs: 5000,
+}
+
+function makeJob(variables: Record<string, unknown>) {
+	return {
+		jobKey: "1",
+		processDefinitionId: "p1",
+		elementId: "e1",
+		processInstanceKey: "i1",
+		variables,
+	}
+}
+
+describe("extract", () => {
+	it("returns complete with extracted fields and empty missingFields", async () => {
+		vi.spyOn(llmModule, "callLlm").mockResolvedValue(
+			JSON.stringify({
+				extracted: { vendorName: "Acme Corp", totalAmount: 1250.0 },
+				missingFields: [],
+			}),
+		)
+		const result = await extract(
+			makeJob({
+				input: "Invoice from Acme Corp, total $1250",
+				fields: ["vendorName", "totalAmount"],
+			}),
+			cfg,
+		)
+		expect(result.outcome).toBe("complete")
+		if (result.outcome === "complete") {
+			expect(result.variables.extracted).toEqual({ vendorName: "Acme Corp", totalAmount: 1250.0 })
+			expect(result.variables.missingFields).toEqual([])
+		}
+	})
+
+	it("returns complete even when some fields are missing", async () => {
+		vi.spyOn(llmModule, "callLlm").mockResolvedValue(
+			JSON.stringify({
+				extracted: { vendorName: "Acme Corp", invoiceDate: null },
+				missingFields: ["invoiceDate"],
+			}),
+		)
+		const result = await extract(
+			makeJob({ input: "Invoice from Acme Corp", fields: ["vendorName", "invoiceDate"] }),
+			cfg,
+		)
+		expect(result.outcome).toBe("complete")
+		if (result.outcome === "complete") {
+			expect(result.variables.missingFields).toEqual(["invoiceDate"])
+		}
+	})
+
+	it("returns error when fields variable is missing", async () => {
+		const result = await extract(makeJob({ input: "text" }), cfg)
+		expect(result.outcome).toBe("error")
+		if (result.outcome === "error") expect(result.errorCode).toBe("AI_INVALID_INPUT")
+	})
+
+	it("returns error on parse failure", async () => {
+		vi.spyOn(llmModule, "callLlm").mockResolvedValue("The fields are: name=Acme")
+		const result = await extract(makeJob({ input: "text", fields: ["name"] }), cfg)
+		expect(result.outcome).toBe("error")
+		if (result.outcome === "error") expect(result.errorCode).toBe("AI_PARSE_ERROR")
+	})
+
+	it("returns fail on RetryableError", async () => {
+		vi.spyOn(llmModule, "callLlm").mockRejectedValue(new llmModule.RetryableError("rate limited"))
+		const result = await extract(makeJob({ input: "text", fields: ["name"] }), cfg)
+		expect(result.outcome).toBe("fail")
+	})
+})