@qualve/ai 0.0.1

package/providers/anthropic/src/index.js

@@ -0,0 +1,164 @@
+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

@@ -0,0 +1,54 @@
+# @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

@@ -0,0 +1,29 @@
+{
+  "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

@@ -0,0 +1,210 @@
+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

@@ -0,0 +1,53 @@
+# @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

package/providers/openai/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@qualve/openai",
+  "version": "0.0.1",
+  "description": "OpenAI 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/openai"
+  },
+  "contributors": [
+    "Dmitry Sharabin",
+    "Lea Verou"
+  ],
+  "peerDependencies": {
+    "qualve": "*"
+  },
+  "dependencies": {
+    "@qualve/llm": "*",
+    "openai": "^6.31.0"
+  }
+}