@qualve/ai 0.0.1

package/.prettierignore

@@ -0,0 +1,2 @@
+package-lock.json
+package.json

package/.prettierrc

@@ -0,0 +1,17 @@
+{
+	"plugins": [
+		"prettier-plugin-brace-style",
+		"prettier-plugin-space-before-function-paren",
+		"prettier-plugin-merge"
+	],
+	"braceStyle": "stroustrup",
+	"arrowParens": "avoid",
+	"bracketSpacing": true,
+	"endOfLine": "auto",
+	"semi": true,
+	"singleQuote": false,
+	"tabWidth": 4,
+	"useTabs": true,
+	"trailingComma": "all",
+	"printWidth": 100
+}

package/README.md

@@ -0,0 +1,96 @@
+# @qualve/ai
+
+Meta-package for [Qualve](https://npmjs.com/package/qualve) LLM support.
+Installs the core LLM framework and all official provider adapters in one go.
+
+## Setup
+
+Requires **Node.js v23+**.
+
+```sh
+npm install @qualve/ai
+```
+
+This installs:
+- [@qualve/llm](https://npmjs.com/package/@qualve/llm) — Core LLM task framework
+- [@qualve/anthropic](https://npmjs.com/package/@qualve/anthropic) — Claude provider
+- [@qualve/openai](https://npmjs.com/package/@qualve/openai) — OpenAI provider
+- [@qualve/googleai](https://npmjs.com/package/@qualve/googleai) — Gemini provider
+
+If you only need specific providers, install them individually instead (each pulls in `@qualve/llm` automatically).
+
+## Usage
+
+```js
+import "@qualve/ai";
+```
+
+Importing the package registers all three providers with the Qualve task system.
+
+You can also import individual providers via sub-paths:
+
+```js
+import "@qualve/ai/anthropic";
+import "@qualve/ai/openai";
+import "@qualve/ai/googleai";
+```
+
+Or import the core framework:
+
+```js
+import { LLMTask } from "@qualve/ai/core";
+```
+
+## API Keys
+
+Create a `.env` file with API keys for the providers you want to use:
+
+```sh
+GEMINI_API_KEY=...     # https://aistudio.google.com/api-keys
+OPENAI_API_KEY=...     # https://platform.openai.com/api-keys
+ANTHROPIC_API_KEY=...  # https://platform.claude.com/settings/keys
+```
+
+## Packages
+
+| Package | Description |
+| --- | --- |
+| [@qualve/llm](https://npmjs.com/package/@qualve/llm) | Core LLM task framework (`LLMTask` class) |
+| [@qualve/anthropic](https://npmjs.com/package/@qualve/anthropic) | Claude adapter |
+| [@qualve/openai](https://npmjs.com/package/@qualve/openai) | OpenAI adapter |
+| [@qualve/googleai](https://npmjs.com/package/@qualve/googleai) | Gemini adapter |
+
+## Models
+
+| Provider | Model | Context window | Max output |
+| --- | --- | --- | --- |
+| Gemini | `gemini-3.1-pro-preview`\* | 1,048,576 | 65,536 |
+| Gemini | `gemini-3.1-flash-preview` | 1,048,576 | 65,536 |
+| Gemini | `gemini-3.1-flash-lite-preview` | 1,048,576 | 65,536 |
+| OpenAI | `gpt-5.4`\* | 1,050,000 | 128K |
+| OpenAI | `gpt-5-mini` | 400K | 128K |
+| OpenAI | `gpt-5-nano` | 400K | 128K |
+| Claude | `claude-sonnet-4-6`\* | 1M | 64K |
+| Claude | `claude-haiku-4-6` | 200K | 64K |
+| Claude | `claude-opus-4-5` | 1M | 128K |
+
+\* Default
+
+## Options
+
+| Option | Flag | Description |
+| --- | --- | --- |
+| `llm` | `--llm` | Provider to use (`gemini`, `openai`, `claude`) |
+| `model` | `--model` | Model name (see table above) |
+| `thinking` | `--thinking` | Reasoning effort level |
+| `fresh` | `--fresh` | Force re-upload of input files |
+
+### Thinking levels
+
+Control reasoning effort via `--thinking <LEVEL>` or the `thinking` task property.
+
+| Provider | Accepted values |
+| --- | --- |
+| [Gemini](https://ai.google.dev/gemini-api/docs/thinking) | `minimal`, `low`, `medium`, `high`\* |
+| [OpenAI](https://platform.openai.com/docs/guides/reasoning) | `none`, `minimal`, `low`, `medium`\*, `high`, `xhigh` |
+| [Claude](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) | _(not yet configurable)_ |

package/core/README.md

@@ -0,0 +1,74 @@
+# @qualve/llm
+
+Core LLM task framework for [Qualve](https://npmjs.com/package/qualve).
+Provides the `LLMTask` base class that all LLM provider adapters extend.
+
+If you want all providers out of the box, install [@qualve/llms](https://npmjs.com/package/@qualve/llms) instead.
+
+## Setup
+
+Requires **Node.js v23+**.
+
+```sh
+npm install @qualve/llm
+```
+
+## Usage
+
+Import alongside a provider to register the `llm` task type:
+
+```js
+import "@qualve/anthropic"; // or @qualve/openai, @qualve/googleai
+```
+
+### Writing a custom provider
+
+```js
+import { LLMTask } from "@qualve/llm";
+
+export default class MyProvider extends LLMTask {
+	static id = "my-provider";
+	static name = "My Provider";
+	static models = ["my-model-v1"];
+	static capabilities = {};
+
+	// Required: implement these abstract methods
+	async uploadFile (filepath, { mimeType, contents }) { /* ... */ }
+	async getFile (filepath) { /* ... */ }
+	async deleteFile (filepath) { /* ... */ }
+	async listFiles () { /* ... */ }
+	async createStream () { /* ... */ }
+}
+
+LLMTask.register(MyProvider);
+```
+
+## API
+
+### `LLMTask`
+
+Extends the base Qualve `Task` class with LLM-specific functionality:
+
+- **Provider dispatch** — `LLMTask.create()` routes to the registered provider based on `task.llm`
+- **File management** — Upload, retrieve, and manage files on the provider
+- **Streaming** — `handleStream()` writes streamed responses to disk with backpressure handling
+- **Prompt helpers** — `this.inputFile()`, `this.inputFiles()`, `this.outputFile()` generate prompt text describing task I/O
+- **Thinking levels** — Normalized across providers via `thinkingLevels` and per-provider `levelMap`
+- **Stop reasons** — Normalized stop reasons (`COMPLETE`, `MAX_TOKENS`, `ABORTED`, `UNKNOWN`)
+
+### Abstract methods (providers must implement)
+
+| Method | Description |
+| --- | --- |
+| `uploadFile(filepath, { mimeType, contents })` | Upload data to the provider |
+| `getFile(filepath)` | Retrieve a previously uploaded file, or `null` |
+| `deleteFile(filepath)` | Delete a previously uploaded file |
+| `listFiles()` | List all uploaded files |
+| `createStream()` | Create the streaming API call; returns `{ stream, transformChunk, onChunk?, onFinish? }` |
+
+### Optional overrides
+
+| Method | Description |
+| --- | --- |
+| `getStatus(chunk)` | Extract a human-readable status from a streaming chunk |
+| `countTokens()` | Count input tokens for a dry run |

package/core/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@qualve/llm",
+  "version": "0.0.1",
+  "description": "Core LLM task framework for Qualve.",
+  "type": "module",
+  "engines": {
+    "node": ">=23"
+  },
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/qualve/ai.git",
+    "directory": "core"
+  },
+  "author": "Lea Verou",
+  "contributors": [
+    "Dmitry Sharabin"
+  ],
+  "peerDependencies": {
+    "qualve": "*"
+  },
+  "dependencies": {
+    "dedent": "^1.7.2"
+  }
+}

package/core/src/index.js

@@ -0,0 +1 @@
+export { default as LLMTask } from "./types/llm.js";

package/core/src/prompts.js

@@ -0,0 +1,83 @@
+import path from "node:path";
+
+/**
+ * Describe a single input file for inclusion in the prompt.
+ * Called with `this` bound to the LLMTask instance.
+ * @param {object} file
+ * @returns {string}
+ */
+export function inputFile (file) {
+	let ret = [];
+
+	if (file.description && !this.capabilities.inputDescriptions) {
+		ret.push(`containing ${file.description}`);
+	}
+
+	if (file.schema && !this.capabilities.inputSchema) {
+		ret.push(`follows the JSON schema: ${JSON.stringify(file.schema, null, "\t")}`);
+	}
+
+	ret = ret.join(" and ");
+
+	if (!ret.startsWith("containing")) {
+		ret = "which " + ret;
+	}
+
+	ret = `\`${path.basename(file.filePath)}\` ${ret}.`;
+
+	if (file.schema) {
+		ret += "\nRead the field descriptions in the JSON schema for details on each field.";
+	}
+
+	return ret;
+}
+
+/**
+ * Describe all input files for inclusion in the prompt.
+ * Called with `this` bound to the LLMTask instance.
+ * @param {Array} files
+ * @returns {string}
+ */
+export function inputFiles (files) {
+	if (files.length === 0) {
+		return "";
+	}
+
+	return `I provide the contents of the following files:
+${files.map(file => inputFile.call(this, file)).join("\n")}`;
+}
+
+/**
+ * Describe the expected output file for inclusion in the prompt.
+ * Called with `this` bound to the LLMTask instance.
+ * @param {object} file
+ * @returns {string}
+ */
+export function outputFile (file) {
+	let ret = [`Produce a JSON file that I’m going to save as \`${path.basename(file.filePath)}\``];
+
+	if (file.description && !this.capabilities.outputDescriptions) {
+		ret.push(`containing ${file.description}`);
+	}
+
+	if (file.schema && !this.capabilities.outputSchema) {
+		ret.push(`following the JSON schema: ${JSON.stringify(file.schema, null, "\t")}`);
+	}
+
+	if (ret.length <= 1) {
+		ret = ret[0];
+	}
+	else {
+		if (ret.length === 3) {
+			ret[2] = "and " + ret[2];
+		}
+
+		ret = ret.join(", ");
+	}
+
+	if (file.schema) {
+		ret += ".\nRead the field descriptions in the JSON schema for details on each field.";
+	}
+
+	return ret;
+}