@jterrazz/intelligence 3.0.1 → 4.0.0

package/dist/index.js

@@ -1,7 +1,622 @@
-export { createLoggingMiddleware } from './middleware/logging.middleware.js';
-export { createSchemaPrompt } from './parsing/create-schema-prompt.js';
-export { parseObject, ParseObjectError } from './parsing/parse-object.js';
-export { parseText } from './parsing/parse-text.js';
-export { createOpenRouterProvider } from './providers/openrouter.provider.js';
+import { Langfuse } from "langfuse";
+import { generateText } from "ai";
+import { jsonrepair } from "jsonrepair";
+import { z } from "zod/v4";
+import { createOpenRouter } from "@openrouter/ai-sdk-provider";
 
+//#region src/logging/logging.middleware.ts
+/**
+* Creates middleware that logs AI SDK requests and responses.
+*/
+function createLoggingMiddleware(options) {
+	const { logger, include = {} } = options;
+	const { params: includeParams, content: includeContent, usage: includeUsage = true } = include;
+	return {
+		specificationVersion: "v3",
+		wrapGenerate: async ({ doGenerate, params, model }) => {
+			const startTime = Date.now();
+			logger.debug("ai.generate.start", {
+				model: model.modelId,
+				...includeParams && { params }
+			});
+			try {
+				const result = await doGenerate();
+				const textContent = result.content.filter((c) => c.type === "text").map((c) => c.text).join("");
+				logger.debug("ai.generate.complete", {
+					model: model.modelId,
+					durationMs: Date.now() - startTime,
+					finishReason: result.finishReason,
+					...includeUsage && { usage: result.usage },
+					...includeContent && { content: textContent }
+				});
+				return result;
+			} catch (error) {
+				logger.error("ai.generate.error", {
+					model: model.modelId,
+					durationMs: Date.now() - startTime,
+					error: error instanceof Error ? error.message : "Unknown error"
+				});
+				throw error;
+			}
+		},
+		wrapStream: async ({ doStream, params, model }) => {
+			const startTime = Date.now();
+			logger.debug("ai.stream.start", {
+				model: model.modelId,
+				...includeParams && { params }
+			});
+			try {
+				const result = await doStream();
+				const chunks = [];
+				const transformStream = new TransformStream({
+					transform(chunk, controller) {
+						if (includeContent && chunk.type === "text-delta") chunks.push(chunk.delta);
+						controller.enqueue(chunk);
+					},
+					flush() {
+						logger.debug("ai.stream.complete", {
+							model: model.modelId,
+							durationMs: Date.now() - startTime,
+							...includeContent && { content: chunks.join("") }
+						});
+					}
+				});
+				return {
+					specificationVersion: "v3",
+					...result,
+					stream: result.stream.pipeThrough(transformStream)
+				};
+			} catch (error) {
+				logger.error("ai.stream.error", {
+					model: model.modelId,
+					durationMs: Date.now() - startTime,
+					error: error instanceof Error ? error.message : "Unknown error"
+				});
+				throw error;
+			}
+		}
+	};
+}
+
+//#endregion
+//#region src/observability/observability.middleware.ts
+/**
+* Helper to create type-safe observability metadata for providerOptions
+*/
+function withObservability(meta) {
+	return { observability: meta };
+}
+/**
+* Creates middleware that sends generation data to an observability platform.
+*/
+function createObservabilityMiddleware(options) {
+	const { observability, providerMetadata } = options;
+	return {
+		specificationVersion: "v3",
+		wrapGenerate: async ({ doGenerate, params, model }) => {
+			const startTime = /* @__PURE__ */ new Date();
+			const meta = params.providerOptions?.observability;
+			const result = await doGenerate();
+			const endTime = /* @__PURE__ */ new Date();
+			if (meta?.traceId) {
+				const extracted = providerMetadata?.extract(result.providerMetadata);
+				const outputText = result.content.filter((c) => c.type === "text").map((c) => c.text).join("");
+				observability.generation({
+					traceId: meta.traceId,
+					name: meta.name ?? "generation",
+					model: model.modelId,
+					input: params.prompt,
+					output: outputText,
+					startTime,
+					endTime,
+					usage: extracted?.usage,
+					cost: extracted?.cost,
+					metadata: meta.metadata
+				});
+			}
+			return result;
+		},
+		wrapStream: async ({ doStream, params, model }) => {
+			const startTime = /* @__PURE__ */ new Date();
+			const meta = params.providerOptions?.observability;
+			const result = await doStream();
+			if (!meta?.traceId) return result;
+			const chunks = [];
+			const transformStream = new TransformStream({
+				transform(chunk, controller) {
+					if (chunk.type === "text-delta") chunks.push(chunk.delta);
+					controller.enqueue(chunk);
+				},
+				flush() {
+					const endTime = /* @__PURE__ */ new Date();
+					observability.generation({
+						traceId: meta.traceId,
+						name: meta.name ?? "generation",
+						model: model.modelId,
+						input: params.prompt,
+						output: chunks.join(""),
+						startTime,
+						endTime,
+						metadata: meta.metadata
+					});
+				}
+			});
+			return {
+				specificationVersion: "v3",
+				...result,
+				stream: result.stream.pipeThrough(transformStream)
+			};
+		}
+	};
+}
+
+//#endregion
+//#region src/observability/langfuse.adapter.ts
+/**
+* Langfuse adapter implementing ObservabilityPort
+*/
+var LangfuseAdapter = class {
+	client;
+	constructor(config) {
+		this.client = new Langfuse({
+			secretKey: config.secretKey,
+			publicKey: config.publicKey,
+			baseUrl: config.baseUrl,
+			environment: config.environment,
+			release: config.release
+		});
+	}
+	async flush() {
+		await this.client.flushAsync();
+	}
+	generation(params) {
+		const usageDetails = params.usage ? {
+			input: params.usage.input,
+			output: params.usage.output,
+			total: params.usage.total ?? params.usage.input + params.usage.output,
+			...params.usage.reasoning !== void 0 && { reasoning: params.usage.reasoning },
+			...params.usage.cacheRead !== void 0 && { cache_read: params.usage.cacheRead },
+			...params.usage.cacheWrite !== void 0 && { cache_write: params.usage.cacheWrite }
+		} : void 0;
+		const costDetails = params.cost ? {
+			total: params.cost.total,
+			...params.cost.input !== void 0 && { input: params.cost.input },
+			...params.cost.output !== void 0 && { output: params.cost.output }
+		} : void 0;
+		this.client.generation({
+			traceId: params.traceId,
+			name: params.name,
+			model: params.model,
+			input: params.input,
+			output: params.output,
+			startTime: params.startTime,
+			endTime: params.endTime,
+			usageDetails,
+			costDetails,
+			metadata: params.metadata
+		});
+	}
+	async shutdown() {
+		await this.client.shutdownAsync();
+	}
+	trace(params) {
+		this.client.trace({
+			id: params.id,
+			name: params.name,
+			metadata: params.metadata
+		});
+	}
+};
+
+//#endregion
+//#region src/observability/noop.adapter.ts
+/**
+* No-op adapter that silently discards all observability data.
+* Useful for testing, development, or when observability is disabled.
+*/
+var NoopObservabilityAdapter = class {
+	async flush() {}
+	generation(_params) {}
+	async shutdown() {}
+	trace(_params) {}
+};
+
+//#endregion
+//#region src/result/result.ts
+/**
+* Create a successful result
+*/
+function generationSuccess(data) {
+	return {
+		success: true,
+		data
+	};
+}
+/**
+* Create a failed result
+*/
+function generationFailure(code, message, cause) {
+	return {
+		success: false,
+		error: {
+			code,
+			message,
+			cause
+		}
+	};
+}
+/**
+* Classify an error into a GenerationErrorCode
+*/
+function classifyError(error) {
+	if (error instanceof Error) {
+		const message = error.message.toLowerCase();
+		if (message.includes("timeout") || message.includes("timed out")) return "TIMEOUT";
+		if (message.includes("rate limit") || message.includes("429")) return "RATE_LIMITED";
+		if (message.includes("parse") || message.includes("json") || message.includes("unexpected token")) return "PARSING_FAILED";
+		if (message.includes("valid") || message.includes("schema") || message.includes("zod")) return "VALIDATION_FAILED";
+	}
+	return "AI_GENERATION_FAILED";
+}
+/**
+* Check if a result is successful (type guard)
+*/
+function isSuccess(result) {
+	return result.success;
+}
+/**
+* Check if a result is a failure (type guard)
+*/
+function isFailure(result) {
+	return !result.success;
+}
+/**
+* Unwrap a result, throwing if it fails
+*/
+function unwrap(result) {
+	if (result.success) return result.data;
+	throw new Error(`${result.error.code}: ${result.error.message}`);
+}
+/**
+* Unwrap a result with a default value for failures
+*/
+function unwrapOr(result, defaultValue) {
+	return result.success ? result.data : defaultValue;
+}
+
+//#endregion
+//#region src/parsing/parse-object.ts
+const MARKDOWN_CODE_BLOCK_RE = /```(?:json)?\r?\n([^`]*?)\r?\n```/g;
+/**
+* Error thrown when object parsing fails.
+* Contains the original text for debugging purposes.
+*/
+var ParseObjectError = class extends Error {
+	name = "ParseObjectError";
+	constructor(message, cause, text) {
+		super(message);
+		this.cause = cause;
+		this.text = text;
+	}
+};
+function convertToPrimitive(value, schema) {
+	if (schema instanceof z.ZodBoolean) return Boolean(value);
+	if (schema instanceof z.ZodNull) return null;
+	if (schema instanceof z.ZodNumber) return Number(value);
+	if (schema instanceof z.ZodString) return String(value);
+	return value;
+}
+function extractArray(text, originalText) {
+	const start = text.indexOf("[");
+	const end = text.lastIndexOf("]");
+	if (start === -1 || end === -1) throw new ParseObjectError("No array found in response", void 0, originalText);
+	try {
+		const raw = text.slice(start, end + 1);
+		return JSON.parse(jsonrepair(raw));
+	} catch (error) {
+		throw new ParseObjectError("Failed to parse array JSON", error, originalText);
+	}
+}
+function extractObject(text, originalText) {
+	const start = text.indexOf("{");
+	const end = text.lastIndexOf("}");
+	if (start === -1 || end === -1) throw new ParseObjectError("No object found in response", void 0, originalText);
+	try {
+		const raw = text.slice(start, end + 1);
+		return JSON.parse(jsonrepair(raw));
+	} catch (error) {
+		throw new ParseObjectError("Failed to parse object JSON", error, originalText);
+	}
+}
+function extractPrimitive(text, schema) {
+	const trimmed = text.trim();
+	try {
+		return convertToPrimitive(JSON.parse(trimmed), schema);
+	} catch {
+		return convertToPrimitive(trimmed, schema);
+	}
+}
+function extractBySchemaType(text, schema, originalText) {
+	if (schema instanceof z.ZodArray) return extractArray(text, originalText);
+	if (schema instanceof z.ZodObject) return extractObject(text, originalText);
+	if (schema instanceof z.ZodBoolean || schema instanceof z.ZodNull || schema instanceof z.ZodNumber || schema instanceof z.ZodString) return extractPrimitive(text, schema);
+	if (schema instanceof z.ZodUnion || schema instanceof z.ZodDiscriminatedUnion) {
+		if (text.indexOf("{") !== -1) return extractObject(text, originalText);
+		if (text.indexOf("[") !== -1) return extractArray(text, originalText);
+		throw new ParseObjectError("No object or array found for union type", void 0, originalText);
+	}
+	if (schema instanceof z.ZodOptional || schema instanceof z.ZodNullable) return extractBySchemaType(text, schema.unwrap(), originalText);
+	if (schema instanceof z.ZodDefault) return extractBySchemaType(text, schema.def.innerType, originalText);
+	if (schema instanceof z.ZodPipe) return extractBySchemaType(text, schema.def.in, originalText);
+	throw new ParseObjectError("Unsupported schema type", void 0, originalText);
+}
+function extractJsonFromCodeBlock(block) {
+	const content = block.replace(/```(?:json)?\r?\n([^`]*?)\r?\n```/, "$1").trim();
+	try {
+		JSON.parse(content);
+		return content;
+	} catch {
+		return null;
+	}
+}
+function findLongestString(strings) {
+	return strings.reduce((longest, current) => current.length > longest.length ? current : longest);
+}
+function findJsonStructures(text) {
+	const matches = [];
+	let depth = 0;
+	let start = -1;
+	for (let i = 0; i < text.length; i++) {
+		const char = text[i];
+		if (char === "{" || char === "[") {
+			if (depth === 0) start = i;
+			depth++;
+		} else if (char === "}" || char === "]") {
+			depth--;
+			if (depth === 0 && start !== -1) {
+				const candidate = text.slice(start, i + 1);
+				try {
+					JSON.parse(candidate);
+					matches.push(candidate);
+				} catch {}
+			}
+		}
+	}
+	return matches;
+}
+function extractJsonString(text) {
+	const codeBlocks = text.match(MARKDOWN_CODE_BLOCK_RE);
+	if (codeBlocks && codeBlocks.length > 0) {
+		const validBlocks = codeBlocks.map((block) => extractJsonFromCodeBlock(block)).filter((block) => block !== null);
+		if (validBlocks.length > 0) return findLongestString(validBlocks);
+	}
+	const structures = findJsonStructures(text);
+	if (structures.length > 0) return findLongestString(structures);
+	return text.replace(/\s+/g, " ").trim();
+}
+function unescapeString(text) {
+	return text.replace(/\\"/g, "\"").replace(/\\n/g, "\n").replace(/\\r/g, "\r").replace(/\\t/g, "	").replace(/\\\\/g, "\\").replace(/\\u([0-9a-fA-F]{4})/g, (_, code) => String.fromCharCode(Number.parseInt(code, 16)));
+}
+function unescapeJsonValues(json) {
+	if (typeof json === "string") return unescapeString(json);
+	if (Array.isArray(json)) return json.map(unescapeJsonValues);
+	if (typeof json === "object" && json !== null) return Object.fromEntries(Object.entries(json).map(([key, value]) => [key, unescapeJsonValues(value)]));
+	return json;
+}
+/**
+* Parses AI-generated text into structured data validated against a Zod schema.
+*
+* Handles common AI response formats:
+* - JSON wrapped in markdown code blocks
+* - JSON embedded in prose text
+* - Malformed JSON (auto-repaired)
+* - Escaped unicode and special characters
+*
+* @param text - The raw AI response text
+* @param schema - A Zod schema to validate and type the result
+* @returns The parsed and validated data
+* @throws {ParseObjectError} When parsing or validation fails
+*
+* @example
+* ```ts
+* const schema = z.object({ title: z.string(), tags: z.array(z.string()) });
+* const result = parseObject(aiResponse, schema);
+* // result is typed as { title: string; tags: string[] }
+* ```
+*/
+function parseObject(text, schema) {
+	try {
+		const unescaped = unescapeJsonValues(extractBySchemaType(extractJsonString(text), schema, text));
+		return schema.parse(unescaped);
+	} catch (error) {
+		if (error instanceof ParseObjectError) throw error;
+		if (error instanceof z.ZodError) throw new ParseObjectError("Failed to validate response against schema", error, text);
+		throw error;
+	}
+}
+
+//#endregion
+//#region src/generation/generate-structured.ts
+/**
+* Generate structured data from an AI model with automatic parsing and error handling.
+* Observability is handled by middleware - no metadata exposed to caller.
+*/
+async function generateStructured(options) {
+	const { model, prompt, system, schema, providerOptions, abortSignal, maxOutputTokens, temperature } = options;
+	try {
+		const response = await generateText({
+			model,
+			prompt,
+			system,
+			providerOptions,
+			abortSignal,
+			maxOutputTokens,
+			temperature
+		});
+		if (!response.text || response.text.trim() === "") return generationFailure("EMPTY_RESULT", "AI returned empty response");
+		try {
+			return generationSuccess(parseObject(response.text, schema));
+		} catch (error) {
+			if (error instanceof ParseObjectError) return generationFailure("PARSING_FAILED", error.message, error);
+			return generationFailure("VALIDATION_FAILED", "Schema validation failed", error);
+		}
+	} catch (error) {
+		return generationFailure(classifyError(error), error instanceof Error ? error.message : "Unknown error", error);
+	}
+}
+
+//#endregion
+//#region src/parsing/create-schema-prompt.ts
+/**
+* Creates a system prompt that instructs the model to output structured data
+* matching the provided Zod schema.
+*
+* Use this with `generateText` when the provider doesn't support native
+* structured outputs, then parse the response with `parseObject`.
+*
+* @param schema - A Zod schema defining the expected output structure
+* @returns A system prompt string with JSON schema instructions
+*
+* @example
+* ```ts
+* import { generateText } from 'ai';
+* import { createSchemaPrompt, parseObject } from '@jterrazz/intelligence';
+*
+* const schema = z.object({ title: z.string(), tags: z.array(z.string()) });
+*
+* const { text } = await generateText({
+*   model,
+*   prompt: 'Generate an article about TypeScript',
+*   system: createSchemaPrompt(schema),
+* });
+*
+* const result = parseObject(text, schema);
+* ```
+*/
+function createSchemaPrompt(schema) {
+	const jsonSchema = z.toJSONSchema(schema);
+	const schemaJson = JSON.stringify(jsonSchema, null, 2);
+	if ([
+		"boolean",
+		"integer",
+		"number",
+		"string"
+	].includes(jsonSchema.type)) return `<OUTPUT_FORMAT>
+You must respond with a ${jsonSchema.type} value that matches this schema:
+
+\`\`\`json
+${schemaJson}
+\`\`\`
+
+Your response should be only the ${jsonSchema.type} value, without any JSON wrapping or additional text.
+</OUTPUT_FORMAT>`;
+	return `<OUTPUT_FORMAT>
+You must respond with valid JSON that matches this JSON schema:
+
+\`\`\`json
+${schemaJson}
+\`\`\`
+
+Your response must be parseable JSON that validates against this schema. Do not include any text outside the JSON.
+</OUTPUT_FORMAT>`;
+}
+
+//#endregion
+//#region src/parsing/parse-text.ts
+const INVISIBLE_CHARS_RE = /[\u00AD\u180E\u200B-\u200C\u200E-\u200F\u202A-\u202E\u2060-\u2064\u2066-\u2069\uFEFF]/g;
+const ASCII_CTRL_RE = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g;
+const SPACE_LIKE_RE = /[\u00A0\u1680\u2000-\u200A\u202F\u205F\u3000]/g;
+const MULTIPLE_SPACES_RE = / {2,}/g;
+const CR_RE = /\r\n?/g;
+const CITATION_RE = / *\(oaicite:\d+\)\{index=\d+\}/g;
+const EM_DASH_SEPARATOR_RE = /\s*[—–―‒]\s*/g;
+const TYPOGRAPHY_REPLACEMENTS = [
+	{
+		pattern: /[\u2018\u2019\u201A]/g,
+		replacement: "'"
+	},
+	{
+		pattern: /[\u201C\u201D\u201E]/g,
+		replacement: "\""
+	},
+	{
+		pattern: /\u2026/g,
+		replacement: "..."
+	},
+	{
+		pattern: /[\u2022\u25AA-\u25AB\u25B8-\u25B9\u25CF]/g,
+		replacement: "-"
+	}
+];
+/**
+* Parses and sanitizes text by removing AI artifacts and normalizing typography.
+*
+* @param text - The text to parse
+* @param options - Parsing options
+* @returns The cleaned text
+*/
+function parseText(text, options = {}) {
+	const { normalizeEmDashesToCommas = true, collapseSpaces = true } = options;
+	if (!text) return "";
+	let result = text;
+	result = result.replace(CR_RE, "\n");
+	result = result.replace(CITATION_RE, "");
+	result = result.normalize("NFKC");
+	result = result.replace(INVISIBLE_CHARS_RE, "");
+	result = result.replace(ASCII_CTRL_RE, "");
+	if (normalizeEmDashesToCommas) result = result.replace(EM_DASH_SEPARATOR_RE, ", ");
+	result = result.replace(SPACE_LIKE_RE, " ");
+	for (const { pattern, replacement } of TYPOGRAPHY_REPLACEMENTS) result = result.replace(pattern, replacement);
+	if (collapseSpaces) result = result.replace(MULTIPLE_SPACES_RE, " ").trim();
+	return result;
+}
+
+//#endregion
+//#region src/provider/openrouter.provider.ts
+/**
+* Creates an OpenRouter provider for AI SDK models.
+*
+* @example
+* ```ts
+* const provider = createOpenRouterProvider({ apiKey: process.env.OPENROUTER_API_KEY });
+* const model = provider.model('anthropic/claude-sonnet-4-20250514');
+*
+* const { text } = await generateText({ model, prompt: 'Hello!' });
+* ```
+*/
+function createOpenRouterProvider(config) {
+	const openrouter = createOpenRouter({ apiKey: config.apiKey });
+	return { model(name, options = {}) {
+		return openrouter(name, {
+			...options.maxTokens !== void 0 && { maxTokens: options.maxTokens },
+			...options.reasoning && { extraBody: { reasoning: options.reasoning } }
+		});
+	} };
+}
+
+//#endregion
+//#region src/provider/openrouter-metadata.adapter.ts
+/**
+* OpenRouter adapter for extracting usage and cost from provider metadata
+*/
+var OpenRouterMetadataAdapter = class {
+	extract(providerMetadata) {
+		const meta = providerMetadata?.openrouter;
+		if (!meta?.usage) return {};
+		const usage = meta.usage;
+		return {
+			usage: {
+				input: usage.promptTokens ?? 0,
+				output: usage.completionTokens ?? 0,
+				total: usage.totalTokens,
+				reasoning: usage.completionTokensDetails?.reasoningTokens,
+				cacheRead: usage.promptTokensDetails?.cachedTokens
+			},
+			cost: usage.cost !== void 0 ? { total: usage.cost } : void 0
+		};
+	}
+};
+
+//#endregion
+export { LangfuseAdapter, NoopObservabilityAdapter, OpenRouterMetadataAdapter, ParseObjectError, classifyError, createLoggingMiddleware, createObservabilityMiddleware, createOpenRouterProvider, createSchemaPrompt, generateStructured, generationFailure, generationSuccess, isFailure, isSuccess, parseObject, parseText, unwrap, unwrapOr, withObservability };
 //# sourceMappingURL=index.js.map