@letsrunit/ai 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# AI Package (`@letsrunit/ai`)
+
+## Installation
+
+```bash
+npm install @letsrunit/ai
+# or
+yarn add @letsrunit/ai
+```
+
+Provides AI-driven capabilities for the `letsrunit` platform, leveraging the [AI SDK](https://sdk.vercel.ai/). It serves as a unified interface for generating text or structured objects using LLMs.
+
+## Exported Functions
+
+### `generate<T>(system, prompt, opts)`
+
+The primary function for interacting with LLMs. It supports both text generation and structured object generation (via Zod schemas).
+
+- **`system`**: The system prompt. Can be a string or a template object `{ template: string; vars: object }` (rendered using Mustache).
+- **`prompt`**: The user prompt (string) or an array of `ModelMessage`.
+- **`opts`**:
+    - `model`: `'large' | 'medium' | 'small'` (defaults to `medium`).
+    - `reasoningEffort`: `'minimal' | 'low' | 'medium'` (defaults to `low`).
+    - `schema`: A Zod schema. If provided, `generate` returns a typed object.
+    - `tools`: A set of AI SDK tools (cannot be used with `schema`).
+    - `abortSignal`: An `AbortSignal` to cancel the request.
+
+### `translate<T>(input, lang, options)`
+
+Translates text or JSON objects from English to a target language.
+
+- **`input`**: A string or a JSON-serializable value.
+- **`lang`**: Target language code (e.g., `'nl'`, `'fr'`).
+- **`options`**:
+    - `cache`: An optional `cache-manager` instance to cache translations.
+    - `prompt`: An optional custom translation prompt.
+    - `reasoningEffort`: LLM reasoning effort level.
+
+## Environment Variables
+
+- `OPENAI_API_KEY`
+- `TOGETHER_AI_API_KEY`
+
+### LangSmith tracing (optional)
+
+- `LANGSMITH_TRACING`
+- `LANGSMITH_WORKSPACE_ID`
+- `LANGSMITH_API_KEY`
+- `LANGSMITH_ENDPOINT`
+
+## Testing
+
+Run tests for this package:
+
+```bash
+yarn test
+```

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import { ModelMessage, ToolSet } from 'ai';
+import * as z from 'zod';
+import { Cache } from 'cache-manager';
+
+interface GenerateOptions<T extends z.Schema | undefined = undefined> {
+    model?: 'large' | 'medium' | 'small';
+    reasoningEffort?: 'minimal' | 'low' | 'medium';
+    schema?: T;
+    tools?: ToolSet;
+    abortSignal?: AbortSignal;
+}
+declare function generate<T extends z.Schema | undefined = undefined>(system: string | {
+    template: string;
+    vars: {
+        [key: string]: any;
+    };
+}, prompt: string | ModelMessage[], opts?: GenerateOptions<T>): Promise<T extends z.Schema ? z.infer<Exclude<T, undefined>> : string>;
+
+interface TranslateOptions {
+    cache?: Cache;
+    prompt?: string;
+    model?: 'large' | 'medium' | 'small';
+    reasoningEffort?: 'minimal' | 'low' | 'medium';
+}
+type JSONValue = string | number | boolean | null | JSONValue[] | {
+    [key: string]: JSONValue | undefined;
+};
+declare function translate<T extends JSONValue = JSONValue>(input: T, lang: string, options?: TranslateOptions): Promise<T>;
+
+export { generate, translate };

package/dist/index.js

@@ -0,0 +1,82 @@
+import * as ai from 'ai';
+import { wrapAISDK } from 'langsmith/experimental/vercel';
+import Mustache from 'mustache';
+import { openai } from '@ai-sdk/openai';
+import { hashKey } from '@letsrunit/utils';
+import ISO6391 from 'iso-639-1';
+
+// src/generate.ts
+var modelGpt5 = openai("gpt-5");
+var modelGpt5Mini = openai("gpt-5-mini");
+var modelGpt5Nano = openai("gpt-5-nano");
+function getModel(type = "medium") {
+  switch (type) {
+    case "large":
+      return modelGpt5;
+    case "medium":
+      return modelGpt5Mini;
+    case "small":
+      return modelGpt5Nano;
+  }
+}
+
+// src/generate.ts
+Mustache.escape = (text) => text;
+var { generateText, generateObject } = wrapAISDK(ai);
+async function generate(system, prompt, opts = {}) {
+  if (opts.tools && opts.schema) {
+    throw new Error("It's not possible to pass both a schema and tools");
+  }
+  if (typeof system === "object") {
+    system = Mustache.render(system.template, system.vars).trim();
+  }
+  const arg = {
+    model: getModel(opts.model),
+    system,
+    prompt,
+    providerOptions: {
+      openai: {
+        reasoningEffort: opts.reasoningEffort ?? "low"
+      }
+    },
+    abortSignal: opts.abortSignal
+  };
+  if (opts.schema) {
+    const result = await generateObject({ ...arg, schema: opts.schema });
+    return result.object;
+  } else {
+    const result = await generateText({ ...arg, tools: opts.tools });
+    return result.text;
+  }
+}
+var PROMPT_TEXT = `Translate the text from English to {lang}.`;
+var PROMPT_JSON = `Translate all text values within the provided JSON string from English to {lang}. Keep the JSON structure identical, translating only object values (never keys), array elements, or string contents. Do not alter numbers, booleans, nulls, or formatting. Return valid JSON.`;
+var dummyCache = { wrap: async (_, fn) => await fn() };
+function normalizeLang(locale) {
+  return locale.replace(/_.+/, "");
+}
+async function translate(input, lang, options = {}) {
+  lang = normalizeLang(lang);
+  if (lang === "en") {
+    return input;
+  }
+  const isString = typeof input === "string";
+  const str = isString ? input : JSON.stringify(input, null, 2);
+  const cache = options.cache ?? dummyCache;
+  const cacheKey = await hashKey(`{hash}:en:${lang}`, str);
+  return cache.wrap(cacheKey, async () => {
+    const prompt = (options.prompt ?? (isString ? PROMPT_TEXT : PROMPT_JSON)).replaceAll(
+      "{lang}",
+      ISO6391.getName(lang) || lang
+    );
+    const translated = await generate(prompt, str, {
+      model: options.model || "small",
+      reasoningEffort: options.reasoningEffort
+    });
+    return isString ? translated : JSON.parse(translated);
+  });
+}
+
+export { generate, translate };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/models.ts","../src/generate.ts","../src/translate.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import { openai } from '@ai-sdk/openai';\nimport { LanguageModel } from 'ai';\n\ntype LanguageModelV2 = Exclude<LanguageModel, string>;\n\nconst modelGpt5 = openai('gpt-5');\nconst modelGpt5Mini = openai('gpt-5-mini');\nconst modelGpt5Nano = openai('gpt-5-nano');\n\nexport function getModel(type: 'large' | 'medium' | 'small' = 'medium'): LanguageModelV2 {\n  switch (type) {\n    case 'large':\n      return modelGpt5;\n    case 'medium':\n      return modelGpt5Mini;\n    case 'small':\n      return modelGpt5Nano;\n  }\n}\n","import * as ai from 'ai';\nimport { ModelMessage, ToolSet } from 'ai';\nimport { wrapAISDK } from 'langsmith/experimental/vercel';\nimport Mustache from 'mustache';\nimport * as z from 'zod';\nimport { getModel } from './models';\n\nMustache.escape = (text: string) => text;\n\nlet { generateText, generateObject } = wrapAISDK(ai);\n\nexport function mockAi(genText: typeof generateText, genObject?: typeof generateObject) {\n  generateText = genText;\n  if (genObject) generateObject = genObject;\n\n  return () => {\n    const wrapped = wrapAISDK(ai);\n    generateText = wrapped.generateText;\n    generateObject = wrapped.generateObject;\n  };\n}\n\ninterface GenerateOptions<T extends z.Schema | undefined = undefined> {\n  model?: 'large' | 'medium' | 'small';\n  reasoningEffort?: 'minimal' | 'low' | 'medium';\n  schema?: T;\n  tools?: ToolSet;\n  abortSignal?: AbortSignal;\n}\n\nexport async function generate<T extends z.Schema | undefined = undefined>(\n  system: string | { template: string; vars: { [key: string]: any } },\n  prompt: string | ModelMessage[],\n  opts: GenerateOptions<T> = {},\n): Promise<T extends z.Schema ? z.infer<Exclude<T, undefined>> : string> {\n  if (opts.tools && opts.schema) {\n    throw new Error(\"It's not possible to pass both a schema and tools\");\n  }\n\n  if (typeof system === 'object') {\n    system = Mustache.render(system.template, system.vars).trim();\n  }\n\n  const arg = {\n    model: getModel(opts.model),\n    system,\n    prompt,\n    providerOptions: {\n      openai: {\n        reasoningEffort: opts.reasoningEffort ?? 'low',\n      },\n    },\n    abortSignal: opts.abortSignal,\n  };\n\n  if (opts.schema) {\n    const result = await generateObject({ ...arg, schema: opts.schema });\n    return result.object as any;\n  } else {\n    const result = await generateText({ ...arg, tools: opts.tools });\n    return result.text as any;\n  }\n}\n","import { hashKey } from '@letsrunit/utils';\nimport type { Cache } from 'cache-manager';\nimport ISO6391 from 'iso-639-1';\nimport { generate } from './generate';\n\nconst PROMPT_TEXT = `Translate the text from English to {lang}.`;\nconst PROMPT_JSON = `Translate all text values within the provided JSON string from English to {lang}. Keep the JSON structure identical, translating only object values (never keys), array elements, or string contents. Do not alter numbers, booleans, nulls, or formatting. Return valid JSON.`;\n\ninterface TranslateOptions {\n  cache?: Cache;\n  prompt?: string;\n  model?: 'large' | 'medium' | 'small';\n  reasoningEffort?: 'minimal' | 'low' | 'medium';\n}\n\ntype JSONValue = string | number | boolean | null | JSONValue[] | { [key: string]: JSONValue | undefined };\n\nconst dummyCache = { wrap: async <T>(_: unknown, fn: () => Promise<T>) => await fn() };\n\nfunction normalizeLang(locale: string): string {\n  return locale.replace(/_.+/, '');\n}\n\nexport async function translate<T extends JSONValue = JSONValue>(\n  input: T,\n  lang: string,\n  options: TranslateOptions = {},\n): Promise<T> {\n  lang = normalizeLang(lang);\n\n  if (lang === 'en') {\n    return input;\n  }\n\n  const isString = typeof input === 'string';\n  const str = isString ? input : JSON.stringify(input, null, 2);\n\n  const cache = options.cache ?? dummyCache;\n  const cacheKey = await hashKey(`{hash}:en:${lang}`, str);\n\n  return cache.wrap(cacheKey, async () => {\n    const prompt = (options.prompt ?? (isString ? PROMPT_TEXT : PROMPT_JSON)).replaceAll(\n      '{lang}',\n      ISO6391.getName(lang) || lang,\n    );\n\n    const translated = await generate(prompt, str, {\n      model: options.model || 'small',\n      reasoningEffort: options.reasoningEffort,\n    });\n\n    return isString ? translated : JSON.parse(translated);\n  });\n}\n"]}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@letsrunit/ai",
+  "version": "0.1.0",
+  "description": "AI integration for test generation with letsrunit",
+  "keywords": [
+    "testing",
+    "ai",
+    "llm",
+    "letsrunit"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/letsrunit/letsrunit.git",
+    "directory": "packages/ai"
+  },
+  "bugs": "https://github.com/letsrunit/letsrunit/issues",
+  "homepage": "https://github.com/letsrunit/letsrunit#readme",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "../../node_modules/.bin/tsup",
+    "test": "vitest run",
+    "test:cov": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  },
+  "packageManager": "yarn@4.10.3",
+  "dependencies": {
+    "@ai-sdk/openai": "^2.0.89",
+    "@ai-sdk/togetherai": "^1.0.31",
+    "@letsrunit/utils": "workspace:*",
+    "ai": "^5.0.121",
+    "cache-manager": "^7.2.8",
+    "iso-639-1": "^3.1.5",
+    "langsmith": "^0.4.7",
+    "mustache": "^4.2.0",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@types/mustache": "^4.2.6",
+    "@types/node": "^25.0.9",
+    "@vitest/coverage-v8": "4.0.17",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.17"
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  }
+}

package/src/generate.ts

@@ -0,0 +1,63 @@
+import * as ai from 'ai';
+import { ModelMessage, ToolSet } from 'ai';
+import { wrapAISDK } from 'langsmith/experimental/vercel';
+import Mustache from 'mustache';
+import * as z from 'zod';
+import { getModel } from './models';
+
+Mustache.escape = (text: string) => text;
+
+let { generateText, generateObject } = wrapAISDK(ai);
+
+export function mockAi(genText: typeof generateText, genObject?: typeof generateObject) {
+  generateText = genText;
+  if (genObject) generateObject = genObject;
+
+  return () => {
+    const wrapped = wrapAISDK(ai);
+    generateText = wrapped.generateText;
+    generateObject = wrapped.generateObject;
+  };
+}
+
+interface GenerateOptions<T extends z.Schema | undefined = undefined> {
+  model?: 'large' | 'medium' | 'small';
+  reasoningEffort?: 'minimal' | 'low' | 'medium';
+  schema?: T;
+  tools?: ToolSet;
+  abortSignal?: AbortSignal;
+}
+
+export async function generate<T extends z.Schema | undefined = undefined>(
+  system: string | { template: string; vars: { [key: string]: any } },
+  prompt: string | ModelMessage[],
+  opts: GenerateOptions<T> = {},
+): Promise<T extends z.Schema ? z.infer<Exclude<T, undefined>> : string> {
+  if (opts.tools && opts.schema) {
+    throw new Error("It's not possible to pass both a schema and tools");
+  }
+
+  if (typeof system === 'object') {
+    system = Mustache.render(system.template, system.vars).trim();
+  }
+
+  const arg = {
+    model: getModel(opts.model),
+    system,
+    prompt,
+    providerOptions: {
+      openai: {
+        reasoningEffort: opts.reasoningEffort ?? 'low',
+      },
+    },
+    abortSignal: opts.abortSignal,
+  };
+
+  if (opts.schema) {
+    const result = await generateObject({ ...arg, schema: opts.schema });
+    return result.object as any;
+  } else {
+    const result = await generateText({ ...arg, tools: opts.tools });
+    return result.text as any;
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { generate } from './generate';
+export * from './translate';

package/src/models.ts

@@ -0,0 +1,19 @@
+import { openai } from '@ai-sdk/openai';
+import { LanguageModel } from 'ai';
+
+type LanguageModelV2 = Exclude<LanguageModel, string>;
+
+const modelGpt5 = openai('gpt-5');
+const modelGpt5Mini = openai('gpt-5-mini');
+const modelGpt5Nano = openai('gpt-5-nano');
+
+export function getModel(type: 'large' | 'medium' | 'small' = 'medium'): LanguageModelV2 {
+  switch (type) {
+    case 'large':
+      return modelGpt5;
+    case 'medium':
+      return modelGpt5Mini;
+    case 'small':
+      return modelGpt5Nano;
+  }
+}

package/src/translate.ts

@@ -0,0 +1,54 @@
+import { hashKey } from '@letsrunit/utils';
+import type { Cache } from 'cache-manager';
+import ISO6391 from 'iso-639-1';
+import { generate } from './generate';
+
+const PROMPT_TEXT = `Translate the text from English to {lang}.`;
+const PROMPT_JSON = `Translate all text values within the provided JSON string from English to {lang}. Keep the JSON structure identical, translating only object values (never keys), array elements, or string contents. Do not alter numbers, booleans, nulls, or formatting. Return valid JSON.`;
+
+interface TranslateOptions {
+  cache?: Cache;
+  prompt?: string;
+  model?: 'large' | 'medium' | 'small';
+  reasoningEffort?: 'minimal' | 'low' | 'medium';
+}
+
+type JSONValue = string | number | boolean | null | JSONValue[] | { [key: string]: JSONValue | undefined };
+
+const dummyCache = { wrap: async <T>(_: unknown, fn: () => Promise<T>) => await fn() };
+
+function normalizeLang(locale: string): string {
+  return locale.replace(/_.+/, '');
+}
+
+export async function translate<T extends JSONValue = JSONValue>(
+  input: T,
+  lang: string,
+  options: TranslateOptions = {},
+): Promise<T> {
+  lang = normalizeLang(lang);
+
+  if (lang === 'en') {
+    return input;
+  }
+
+  const isString = typeof input === 'string';
+  const str = isString ? input : JSON.stringify(input, null, 2);
+
+  const cache = options.cache ?? dummyCache;
+  const cacheKey = await hashKey(`{hash}:en:${lang}`, str);
+
+  return cache.wrap(cacheKey, async () => {
+    const prompt = (options.prompt ?? (isString ? PROMPT_TEXT : PROMPT_JSON)).replaceAll(
+      '{lang}',
+      ISO6391.getName(lang) || lang,
+    );
+
+    const translated = await generate(prompt, str, {
+      model: options.model || 'small',
+      reasoningEffort: options.reasoningEffort,
+    });
+
+    return isString ? translated : JSON.parse(translated);
+  });
+}