@qualve/ai 0.0.1 → 0.1.0

package/core/src/util.js

@@ -1,111 +0,0 @@
-import {
-	rmSync,
-	renameSync,
-	createWriteStream,
-} from "node:fs";
-import { once } from "node:events";
-import { addFilenameSuffix, readJSONSync, writeJSONSync } from "qualve/util";
-
-export { default as dedent } from "dedent";
-
-/**
- * @typedef {Object} StreamResult
- * @property {boolean} complete - Whether the stream completed normally.
- * @property {string} reason - Normalized stop reason (@see LLM.stopReasons).
- * @property {string|null} reasonRaw - Provider-specific stop reason, for low-level handling.
- */
-
-/**
- * Safely handles an async iterable stream of chunks from an LLM response,
- * writing them to a file with proper error handling and cleanup.
- * When no outputPath is provided, collects the response text in memory and returns it.
- * @param {Object} options
- * @param {AsyncIterable<Object>} options.stream - An async iterable of chunks to be written.
- * @param {string} [options.outputPath] - The path to the file where chunks will be written. If omitted, text is collected in memory.
- * @param {(chunk: Object) => string} [options.transformChunk] - An optional transform function to apply to each chunk before writing.
- * @param {(result: Object) => Object} [options.transformResult] - An optional transform function to apply to the final result after all chunks have been written and read back.
- * @param {(chunk: Object) => void} [options.onChunk] - An optional callback to handle each chunk as it is processed (e.g. for progress updates).
- * @param {() => (StreamResult | null | undefined)} [options.onFinish] - An optional callback invoked after the stream ends, before file promotion. Return a StreamResult with complete: false to prevent file promotion and throw.
- * @returns {Promise<string|undefined>} The collected text when no outputPath is given, otherwise undefined.
- */
-export async function handleStream ({
-	stream,
-	outputPath,
-	transformChunk,
-	transformResult,
-	onChunk = () => {},
-	onFinish = () => {},
-} = {}) {
-	// No output file — collect text in memory
-	if (!outputPath) {
-		let chunks = [];
-		for await (let chunk of stream) {
-			onChunk(chunk);
-			chunks.push(transformChunk ? transformChunk(chunk) : chunk);
-		}
-		return chunks.join("");
-	}
-
-	const tmpFile = addFilenameSuffix(outputPath, ".tmp");
-
-	const ws = createWriteStream(tmpFile);
-
-	let writeError;
-	ws.on("error", err => {
-		writeError = err;
-	});
-
-	try {
-		for await (let chunk of stream) {
-			if (writeError) {
-				// Something went wrong while writing to disk.
-				// That shouldn't happen, but if it does, we stop processing further chunks.
-				throw writeError;
-			}
-
-			onChunk(chunk);
-
-			if (transformChunk) {
-				chunk = transformChunk(chunk);
-			}
-
-			if (!ws.write(chunk)) {
-				// Handle backpressure
-				await once(ws, "drain");
-			}
-		}
-
-		ws.end();
-		await once(ws, "finish");
-
-		// var (not let) hoists `streamResult` out of the try block so it's accessible below.
-		var streamResult = onFinish();
-	}
-	catch (e) {
-		throw new Error(`Stream handling failed for ${outputPath}`, { cause: e });
-	}
-	finally {
-		ws.destroy();
-	}
-
-	// Checked after stream I/O so the error isn't buried under "Stream handling failed".
-	// Callers can inspect error.cause.streamResult.reason (normalized) and error.cause.streamResult.reasonRaw (provider-specific).
-	if (streamResult && !streamResult.complete) {
-		let cause = new Error(`Provider stop reason: ${streamResult.reasonRaw}`);
-		cause.streamResult = streamResult;
-		throw new Error(`An error occurred while generating the response: ${streamResult.reason}`, {
-			cause,
-		});
-	}
-
-	// Clean up: prettify the result and write it to the final file
-	if (transformResult) {
-		let result = readJSONSync(tmpFile);
-		result = transformResult(result);
-		writeJSONSync(outputPath, result);
-		rmSync(tmpFile);
-	}
-	else {
-		renameSync(tmpFile, outputPath);
-	}
-}

package/providers/anthropic/README.md

@@ -1,52 +0,0 @@
-# @qualve/anthropic
-
-[Anthropic Claude](https://www.anthropic.com/) provider for [Qualve](https://npmjs.com/package/qualve) LLM tasks.
-
-## Setup
-
-Requires **Node.js v23+**.
-
-```sh
-npm install @qualve/anthropic
-```
-
-Set the `ANTHROPIC_API_KEY` environment variable (or add it to `.env`).
-Get a key at https://platform.claude.com/settings/keys.
-
-## Usage
-
-```js
-import "@qualve/anthropic";
-```
-
-Importing the package registers the `claude` provider with the Qualve task system.
-
-Then use `llm: "claude"` in your task definitions:
-
-```js
-export default {
-	type: "llm",
-	llm: "claude",
-	system: "You are a helpful assistant.",
-	prompt: "Summarize this data.",
-	input: [{ name: "data", schema: mySchema }],
-	output: { name: "summary", schema: summarySchema },
-};
-```
-
-## Models
-
-| Model | Context window | Max output |
-| --- | --- | --- |
-| `claude-sonnet-4-6` (default) | 1M | 64K |
-| `claude-haiku-4-6` | 200K | 64K |
-| `claude-opus-4-5` | 1M | 128K |
-
-## Capabilities
-
-| Capability | Supported |
-| --- | --- |
-| Structured output (JSON schema) | Yes |
-| Input file descriptions in prompt | Yes (automatic) |
-| Thinking levels | No |
-| Token counting | Yes |

package/providers/anthropic/package.json

@@ -1,29 +0,0 @@
-{
-  "name": "@qualve/anthropic",
-  "version": "0.0.1",
-  "description": "Anthropic Claude provider for Qualve LLM tasks.",
-  "type": "module",
-  "engines": {
-    "node": ">=23"
-  },
-  "main": "src/index.js",
-  "exports": {
-    ".": "./src/index.js"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/qualve/ai.git",
-    "directory": "providers/anthropic"
-  },
-  "contributors": [
-    "Dmitry Sharabin",
-    "Lea Verou"
-  ],
-  "peerDependencies": {
-    "qualve": "*"
-  },
-  "dependencies": {
-    "@qualve/llm": "*",
-    "@anthropic-ai/sdk": "^0.79.0"
-  }
-}

package/providers/anthropic/src/index.js

@@ -1,164 +0,0 @@
-import { LLMTask } from "@qualve/llm";
-import Anthropic, { toFile } from "@anthropic-ai/sdk";
-
-export default class Claude extends LLMTask {
-	static id = "claude";
-	static name = "Claude";
-	static models = ["claude-sonnet-4-6", "claude-haiku-4-6", "claude-opus-4-5"];
-	static capabilities = {
-		inputDescriptions: true,
-		outputSchema: true,
-	};
-
-	client = new Anthropic({
-		apiKey: process.env.ANTHROPIC_API_KEY,
-		timeout: 30 * 60_000, // 30 minutes — LLM tasks with thinking can be very slow
-	});
-
-	async uploadFile (filepath, { mimeType, contents }) {
-		let { name } = this.getFileInfo(filepath);
-
-		return this.client.beta.files.upload(
-			{
-				// The Claude Files API doesn't support JSON files directly,
-				// so to use them in prompts, we upload them with a text/plain MIME type that Claude supports.
-				// See https://platform.claude.com/docs/en/build-with-claude/files#file-types-and-content-blocks
-				file: await toFile(new Blob([contents], { type: mimeType }), name, {
-					type: "text/plain",
-				}),
-			},
-			{
-				betas: ["files-api-2025-04-14"],
-			},
-		);
-	}
-
-	async getFile (filepath) {
-		let { name } = this.getFileInfo(filepath);
-		const list = await this.listFiles();
-		return list.find(f => f.filename === name);
-	}
-
-	async deleteFile (filepath) {
-		let fileId = (await this.getFile(filepath))?.id;
-		if (!fileId) {
-			// Not found
-			return;
-		}
-		return this.client.beta.files.delete(fileId, {
-			betas: ["files-api-2025-04-14"],
-		});
-	}
-
-	async listFiles () {
-		const meta = [];
-
-		for await (const file of this.client.beta.files.list({
-			betas: ["files-api-2025-04-14"],
-		})) {
-			meta.push(file);
-		}
-
-		return meta;
-	}
-
-	async countTokens () {
-		let { system, prompt, input = [] } = this;
-		let result = await this.client.messages.countTokens({
-			model: this.model,
-			system: system?.join("\n"),
-			messages: [
-				{
-					role: "user",
-					content: [
-						...prompt.map(t => ({ type: "text", text: t })),
-						...input.map(f => ({
-							type: "document",
-							context: this.inputFile(f),
-							source: {
-								type: "text",
-								media_type: "text/plain",
-								data:
-									this.readFile(f.filePath, { contents: f.contents })?.contents ??
-									"",
-							},
-						})),
-					],
-				},
-			],
-		});
-
-		return result.input_tokens;
-	}
-
-	async createStream () {
-		let { system, prompt, output, input = [] } = this;
-		let responseSchema = output?.schema;
-		let output_format = responseSchema
-			? {
-					type: "json_schema",
-					schema: responseSchema.schema,
-				}
-			: undefined;
-		const stream = this.client.beta.messages.stream({
-			model: this.model,
-			max_tokens: 64000, // maximum for claude-sonnet-4-5
-			betas: ["structured-outputs-2025-11-13", "files-api-2025-04-14"],
-			system: system?.join("\n"),
-			messages: [
-				{
-					role: "user",
-					content: [
-						...prompt.map(t => ({ type: "text", text: t })),
-						...input.map(f => ({
-							type: "document",
-							context: this.inputFile(f),
-							source: {
-								type: "file",
-								file_id: f.remoteFile.id,
-							},
-						})),
-					],
-				},
-			],
-			// Claude API doesn't allow extra properties in the schema root.
-			// It throws an "invalid_request_error" error (output_format.description: Extra inputs are not permitted)
-			output_format,
-		});
-
-		let stopReason;
-		return {
-			stream,
-			transformChunk: chunk =>
-				chunk.type === "content_block_delta" && chunk.delta?.type === "text_delta"
-					? chunk.delta.text
-					: "",
-			onChunk: chunk => {
-				if (chunk.type === "message_delta") {
-					stopReason = chunk.delta?.stop_reason;
-				}
-			},
-			onFinish: () => {
-				// See https://platform.claude.com/docs/en/agent-sdk/stop-reasons#available-stop-reasons
-				if (!stopReason || ["end_turn", "stop_sequence"].includes(stopReason)) {
-					return {
-						complete: true,
-						reason: LLMTask.stopReasons.COMPLETE,
-						reasonRaw: stopReason ?? null,
-					};
-				}
-
-				return {
-					complete: false,
-					reason:
-						stopReason === "max_tokens"
-							? LLMTask.stopReasons.MAX_TOKENS
-							: LLMTask.stopReasons.UNKNOWN,
-					reasonRaw: stopReason,
-				};
-			},
-		};
-	}
-}
-
-LLMTask.register(Claude);

package/providers/googleai/README.md

@@ -1,54 +0,0 @@
-# @qualve/googleai
-
-[Google Gemini](https://ai.google.dev/) provider for [Qualve](https://npmjs.com/package/qualve) LLM tasks.
-
-## Setup
-
-Requires **Node.js v23+**.
-
-```sh
-npm install @qualve/googleai
-```
-
-Set the `GEMINI_API_KEY` environment variable (or add it to `.env`).
-Get a key at https://aistudio.google.com/api-keys.
-
-## Usage
-
-```js
-import "@qualve/googleai";
-```
-
-Importing the package registers the `gemini` provider with the Qualve task system.
-
-Then use `llm: "gemini"` in your task definitions:
-
-```js
-export default {
-	type: "llm",
-	llm: "gemini",
-	system: "You are a helpful assistant.",
-	prompt: "Summarize this data.",
-	input: [{ name: "data", schema: mySchema }],
-	output: { name: "summary", schema: summarySchema },
-};
-```
-
-## Models
-
-| Model | Context window | Max output |
-| --- | --- | --- |
-| `gemini-3.1-pro-preview` (default) | 1,048,576 | 65,536 |
-| `gemini-3.1-flash-preview` | 1,048,576 | 65,536 |
-| `gemini-3.1-flash-lite-preview` | 1,048,576 | 65,536 |
-
-## Capabilities
-
-| Capability | Supported |
-| --- | --- |
-| Structured output (JSON schema) | Yes |
-| Thinking levels | Yes (`minimal`, `low`, `medium`, `high`\*) |
-| Web search | Yes (pro models only) |
-| Token counting | Yes |
-
-\* Default

package/providers/googleai/package.json

@@ -1,29 +0,0 @@
-{
-  "name": "@qualve/googleai",
-  "version": "0.0.1",
-  "description": "Google Gemini provider for Qualve LLM tasks.",
-  "type": "module",
-  "engines": {
-    "node": ">=23"
-  },
-  "main": "src/index.js",
-  "exports": {
-    ".": "./src/index.js"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/qualve/ai.git",
-    "directory": "providers/googleai"
-  },
-  "contributors": [
-    "Dmitry Sharabin",
-    "Lea Verou"
-  ],
-  "peerDependencies": {
-    "qualve": "*"
-  },
-  "dependencies": {
-    "@qualve/llm": "*",
-    "@google/genai": "^1.45.0"
-  }
-}

package/providers/googleai/src/index.js

@@ -1,210 +0,0 @@
-import { createHash } from "node:crypto";
-import { LLMTask } from "@qualve/llm";
-import { createUserContent, createPartFromUri, GoogleGenAI } from "@google/genai";
-
-export default class Gemini extends LLMTask {
-	static id = "gemini";
-	static name = "Gemini";
-	static models = [
-		"gemini-3.1-pro-preview",
-		"gemini-3.1-flash-preview",
-		"gemini-3.1-flash-lite-preview",
-	];
-	static levelMap = { none: "minimal", xhigh: "high" };
-	static capabilities = {
-		outputSchema: true,
-		thinkingLevel: true,
-	};
-
-	get capabilities () {
-		return {
-			...super.capabilities,
-			webSearch: /-pro(?:-|$)/.test(this.model),
-		};
-	}
-
-	client = new GoogleGenAI({
-		apiKey: process.env.GEMINI_API_KEY,
-		httpOptions: { timeout: 30 * 60_000 }, // 30 minutes — LLM tasks with thinking can be very slow
-	});
-
-	getFileInfo (filepath) {
-		let { name, dirName } = super.getFileInfo(filepath);
-		let displayName = name;
-
-		// Gemini file ID: lowercase alphanumeric or dashes, no leading/trailing dashes.
-		name = name.replace(/[_.]/g, "-").replace(/^-|-$/g, "");
-
-		// Gemini file IDs are limited to 40 chars.
-		// Batch slice inputs can exceed this (e.g. "ba-answers-normalized-unique-500-999-json").
-		// Truncate with a hash suffix to preserve uniqueness.
-		let maxLength = 40;
-		if (name.length > maxLength) {
-			let hash = createHash("sha256").update(name).digest("hex").slice(0, 6);
-			name = name.slice(0, maxLength - 7) + "-" + hash;
-		}
-
-		return { name, dirName, displayName };
-	}
-
-	async uploadFile (filepath, { mimeType, contents }) {
-		let { name, displayName } = this.getFileInfo(filepath);
-		return this.client.files.upload({
-			file: new Blob([contents], { type: mimeType }),
-			config: { name, displayName, mimeType },
-		});
-	}
-
-	/**
-	 * Execute a file operation with shared error handling for not-found cases.
-	 * Gemini returns 403 (not 404) when a file doesn't exist, so we disambiguate
-	 * by listing files to check whether it's a real permission error.
-	 * @param {string} filepath - The local file path (used for name resolution and error messages).
-	 * @param {"get" | "delete"} method - The method name on `this.client.files` to call.
-	 * @returns {Promise<object|null>} The operation result, or null if the file was not found.
-	 */
-	async #safeFileOp (filepath, method) {
-		let { name } = this.getFileInfo(filepath);
-		name = "files/" + name;
-
-		try {
-			// If we don't await here, the error is unhandled
-			return await this.client.files[method]({ name });
-		}
-		catch (e) {
-			if (e.status === 403 || e.status === 404) {
-				// 403 can mean "not found" on Gemini — verify by listing files.
-				// 404 is a straightforward not-found.
-				if (e.status === 403) {
-					let files = await this.client.files.list();
-					for await (let file of files) {
-						if (file.name === name) {
-							throw new Error(
-								`You don't have permission to access file ${filepath}`,
-								{
-									cause: e,
-								},
-							);
-						}
-					}
-				}
-			}
-			else {
-				throw new Error(`Failed to ${method} file ${filepath}`, { cause: e });
-			}
-		}
-
-		// Not found
-		return null;
-	}
-
-	async getFile (filepath) {
-		return this.#safeFileOp(filepath, "get");
-	}
-
-	async deleteFile (filepath) {
-		return this.#safeFileOp(filepath, "delete");
-	}
-
-	async listFiles () {
-		return [...(await this.client.files.list())];
-	}
-
-	async countTokens () {
-		let { system, prompt, input = [] } = this;
-		const result = await this.client.models.countTokens({
-			model: this.model,
-			contents: createUserContent([
-				// FIXME: Correctly pass system instructions via `config.systemInstruction` instead of including them in contents once countTokens supports it.
-				...system,
-				...prompt,
-				...input
-					.map(f => this.readFile(f.filePath, { contents: f.contents })?.contents)
-					.filter(Boolean),
-			]),
-		});
-
-		return result.totalTokens;
-	}
-
-	async createStream () {
-		let { system, prompt, output, input = [] } = this;
-		let responseSchema;
-		if (output?.schema) {
-			responseSchema = {
-				responseMimeType: "application/json",
-				responseJsonSchema: output?.schema.schema,
-			};
-		}
-
-		const stream = await this.client.models.generateContentStream({
-			model: this.model,
-			contents: createUserContent([
-				...prompt,
-				...input.map(f => createPartFromUri(f.remoteFile.uri, f.remoteFile.mimeType)),
-			]),
-			config: {
-				systemInstruction: system?.join("\n"),
-				tools: this.capabilities.webSearch ? [{ googleSearch: {} }] : undefined,
-				...responseSchema,
-				thinkingConfig: {
-					thinkingLevel: this.thinking ?? "high",
-				},
-			},
-		});
-
-		let finishReason;
-		return {
-			stream,
-			transformChunk: chunk => {
-				// Filter out thought-parts so thinking text is never written to the output
-				let part = chunk.candidates?.[0]?.content?.parts?.find(p => !p.thought);
-				return part?.text ?? "";
-			},
-			onChunk: chunk => {
-				// See https://googleapis.github.io/js-genai/release_docs/enums/types.FinishReason.html
-				finishReason = chunk.candidates?.[0]?.finishReason ?? finishReason;
-			},
-			onFinish: () => {
-				if (!finishReason) {
-					// No finishReason means no evidence of failure — treat as complete.
-					return {
-						complete: true,
-						reason: LLMTask.stopReasons.COMPLETE,
-						reasonRaw: null,
-					};
-				}
-
-				// Gemini finish reasons → normalized stop reasons.
-				// See https://googleapis.github.io/js-genai/release_docs/enums/types.FinishReason.html
-				// STOP:               Natural stop or configured stop sequence reached.
-				// MAX_TOKENS:         Configured maximum output tokens reached.
-				// SAFETY:             Content potentially contains safety violations.
-				// RECITATION:         Content potentially recites training data.
-				// LANGUAGE:           Unsupported language detected.
-				// BLOCKLIST:          Content contains forbidden terms.
-				// PROHIBITED_CONTENT: Content potentially contains prohibited material.
-				// SPII:               Content potentially contains Sensitive Personally Identifiable Information.
-				let reasons = {
-					STOP: LLMTask.stopReasons.COMPLETE,
-					MAX_TOKENS: LLMTask.stopReasons.MAX_TOKENS,
-					SAFETY: LLMTask.stopReasons.ABORTED,
-					RECITATION: LLMTask.stopReasons.ABORTED,
-					LANGUAGE: LLMTask.stopReasons.ABORTED,
-					BLOCKLIST: LLMTask.stopReasons.ABORTED,
-					PROHIBITED_CONTENT: LLMTask.stopReasons.ABORTED,
-					SPII: LLMTask.stopReasons.ABORTED,
-				};
-
-				let normalized = reasons[finishReason] ?? LLMTask.stopReasons.UNKNOWN;
-				return {
-					complete: normalized === LLMTask.stopReasons.COMPLETE,
-					reason: normalized,
-					reasonRaw: finishReason,
-				};
-			},
-		};
-	}
-}
-
-LLMTask.register(Gemini);

package/providers/openai/README.md

@@ -1,53 +0,0 @@
-# @qualve/openai
-
-[OpenAI](https://openai.com/) provider for [Qualve](https://npmjs.com/package/qualve) LLM tasks.
-
-## Setup
-
-Requires **Node.js v23+**.
-
-```sh
-npm install @qualve/openai
-```
-
-Set the `OPENAI_API_KEY` environment variable (or add it to `.env`).
-Get a key at https://platform.openai.com/api-keys.
-
-## Usage
-
-```js
-import "@qualve/openai";
-```
-
-Importing the package registers the `openai` provider with the Qualve task system.
-
-Then use `llm: "openai"` in your task definitions:
-
-```js
-export default {
-	type: "llm",
-	llm: "openai",
-	system: "You are a helpful assistant.",
-	prompt: "Summarize this data.",
-	input: [{ name: "data", schema: mySchema }],
-	output: { name: "summary", schema: summarySchema },
-};
-```
-
-## Models
-
-| Model | Context window | Max output |
-| --- | --- | --- |
-| `gpt-5.4` (default) | 1,050,000 | 128K |
-| `gpt-5-mini` | 400K | 128K |
-| `gpt-5-nano` | 400K | 128K |
-
-## Capabilities
-
-| Capability | Supported |
-| --- | --- |
-| Structured output (JSON schema) | Yes |
-| Thinking levels | Yes (`none`, `minimal`, `low`, `medium`\*, `high`, `xhigh`) |
-| Token counting | No |
-
-\* Default