write-language 0.1.3

package/README.md

@@ -0,0 +1,211 @@
+# write-language
+
+Multi-provider language generation toolkit using Vercel AI SDK. Generate AI responses with 10+ LLM providers including OpenAI, Anthropic, Google, AWS Bedrock, and more.
+
+## Features
+
+- 🤖 **Multi-Provider Support**: Works with 10+ LLM providers
+  - OpenAI (GPT-4, GPT-3.5)
+  - Anthropic (Claude 3.5, Claude 3)
+  - Google (Gemini, PaLM)
+  - AWS Bedrock
+  - Groq
+  - xAI (Grok)
+  - Cloudflare Workers AI
+  - Ollama (local models)
+  - OpenRouter
+  - And more!
+
+- 📝 **Flexible Response Generation**: Stream or non-stream responses
+- 🔧 **Model Registry**: Complete catalog of available models by provider
+- 🎯 **Provider Factory**: Easy provider initialization
+- 📋 **Pre-built Prompts**: Ready-to-use agent prompt templates
+- 🛠️ **Tool Support**: Function calling and tool use capabilities
+- 🎨 **Markdown to HTML**: Built-in markdown rendering with syntax highlighting
+
+## Installation
+
+```bash
+npm install write-language
+```
+
+## Usage
+
+### Basic Response Generation
+
+```typescript
+import { generateLanguageResponse } from 'write-language';
+
+const result = await generateLanguageResponse({
+  provider: 'openai',
+  model: 'gpt-4-turbo',
+  prompt: 'Explain quantum computing in simple terms',
+  apiKey: process.env.OPENAI_API_KEY
+});
+
+console.log(result.text);
+```
+
+### Streaming Responses
+
+```typescript
+const result = await generateLanguageResponse({
+  provider: 'anthropic',
+  model: 'claude-3-5-sonnet-20241022',
+  prompt: 'Write a short story about AI',
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  stream: true
+});
+
+for await (const chunk of result.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
+### Using the Model Registry
+
+```typescript
+import { 
+  LANGUAGE_MODELS, 
+  getModelsByProvider,
+  getModelsByCapability 
+} from 'write-language';
+
+// Get all OpenAI models
+const openaiModels = getModelsByProvider('openai');
+
+// Get all multimodal models
+const multimodalModels = getModelsByCapability('multimodal');
+
+// Check specific model info
+const gpt4Info = LANGUAGE_MODELS['gpt-4-turbo'];
+console.log(gpt4Info);
+// {
+//   name: 'GPT-4 Turbo',
+//   provider: 'openai',
+//   contextWindow: 128000,
+//   capabilities: ['text', 'multimodal', 'function-calling'],
+//   ...
+// }
+```
+
+### Custom Provider Setup
+
+```typescript
+import { createLLMProvider } from 'write-language';
+
+const provider = createLLMProvider(
+  'groq',
+  process.env.GROQ_API_KEY
+);
+
+const model = provider('llama-3.3-70b-versatile');
+```
+
+### Using Agent Prompts
+
+```typescript
+import { AGENT_PROMPTS } from 'write-language';
+
+const result = await generateLanguageResponse({
+  provider: 'openai',
+  model: 'gpt-4',
+  prompt: AGENT_PROMPTS.researchAgent.systemPrompt,
+  messages: [
+    {
+      role: 'user',
+      content: 'Research the latest developments in fusion energy'
+    }
+  ],
+  apiKey: process.env.OPENAI_API_KEY
+});
+```
+
+### Markdown to HTML Conversion
+
+```typescript
+import { convertMarkdownToHTMLEscaped } from 'write-language';
+
+const markdown = '# Hello\n\n```javascript\nconsole.log("world");\n```';
+const html = convertMarkdownToHTMLEscaped(markdown);
+```
+
+## API Reference
+
+### `generateLanguageResponse(options)`
+
+Generate an AI language response.
+
+**Options:**
+- `provider` (string): LLM provider name
+- `model` (string): Model identifier
+- `prompt` (string): System prompt or initial prompt
+- `apiKey` (string): Provider API key
+- `messages` (array, optional): Conversation history
+- `stream` (boolean, optional): Enable streaming
+- `maxTokens` (number, optional): Maximum tokens to generate
+- `temperature` (number, optional): Sampling temperature
+- `tools` (array, optional): Available tools for function calling
+
+**Returns:** `GenerateLanguageResult` with `text`, `textStream`, `finishReason`, etc.
+
+### `createLLMProvider(provider, apiKey, options)`
+
+Create a provider instance.
+
+**Parameters:**
+- `provider`: Provider name
+- `apiKey`: API key
+- `options`: Additional provider options
+
+**Returns:** Provider function
+
+### Model Registry Functions
+
+- `getModelsByProvider(provider)`: Get all models for a provider
+- `getAllModels()`: Get all available models
+- `getModelsByCapability(capability)`: Filter by capability
+- `getTextOnlyModels()`: Get text-only models
+- `getMultimodalModels()`: Get multimodal models
+
+## Supported Providers
+
+| Provider | Models | Capabilities |
+|----------|--------|--------------|
+| OpenAI | GPT-4, GPT-3.5, o1, o3 | Text, Multimodal, Functions |
+| Anthropic | Claude 3.5, Claude 3 | Text, Multimodal, Functions |
+| Google | Gemini 2.0, Gemini 1.5 | Text, Multimodal |
+| AWS Bedrock | Claude, Llama, Mistral | Text, Multimodal |
+| Groq | Llama 3, Mixtral | Text, Fast Inference |
+| xAI | Grok | Text |
+| Cloudflare | Various | Text, Edge Deployment |
+| Ollama | Local Models | Text, Privacy |
+| OpenRouter | 100+ Models | Text, Aggregator |
+
+## Environment Variables
+
+Set API keys for the providers you want to use:
+
+```bash
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+GOOGLE_API_KEY=...
+GROQ_API_KEY=gsk_...
+XAI_API_KEY=xai-...
+AWS_ACCESS_KEY_ID=...
+AWS_SECRET_ACCESS_KEY=...
+CLOUDFLARE_ACCOUNT_ID=...
+CLOUDFLARE_API_TOKEN=...
+```
+
+## License
+
+AGPL-3.0
+
+## Author
+
+vtempest <grokthiscontact@gmail.com>
+
+## Contributing
+
+Issues and PRs welcome at [github.com/vtempest/ai-research-agent](https://github.com/vtempest/ai-research-agent)

package/package.json

@@ -0,0 +1,106 @@
+{
+  "name": "write-language",
+  "version": "0.1.3",
+  "description": "Multi-provider language generation toolkit using Vercel AI SDK - generate responses with 10+ LLM providers including OpenAI, Anthropic, Google, and more.",
+  "author": "vtempest <grokthiscontact@gmail.com>",
+  "license": "rights.institute/PROSPER",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vtempest/ai-research-agent",
+    "directory": "packages/write-language"
+  },
+  "bugs": {
+    "url": "https://github.com/vtempest/ai-research-agent/issues"
+  },
+  "main": "./dist/write-language.cjs.js",
+  "types": "./dist/types.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/write-language.es.js",
+      "require": "./dist/write-language.cjs.js"
+    },
+    "./*": {
+      "types": "./src/*.ts",
+      "react-server": "./src/*",
+      "import": "./src/*",
+      "require": "./src/*"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "src/*"
+      ]
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest",
+    "test-ui": "vitest --ui --watch",
+    "make": "rm -rf dist/*; NODE_OPTIONS=--max-old-space-size=15192 vite build",
+    "ship": "npx standard-version --release-as patch && npm publish --access public"
+  },
+  "peerDependencies": {
+    "next": ">=15.0.0",
+    "vinext": ">=0.1.0 || >=1.0.0-0"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    },
+    "vinext": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@vitest/ui": "^4.0.18",
+    "terser": "^5.46.0",
+    "typescript": "^5.9.3",
+    "vite": "^8.1.3",
+    "vite-plugin-dts": "^5.0.3",
+    "vite-plugin-node-polyfills": "^0.28.0",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "@ai-sdk/amazon-bedrock": "^3.0.0",
+    "@ai-sdk/anthropic": "^2.0.0",
+    "@ai-sdk/google": "^2.0.0",
+    "@ai-sdk/google-vertex": "^3.0.0",
+    "@ai-sdk/groq": "^2.0.0",
+    "@ai-sdk/mcp": "^1.0.0",
+    "@ai-sdk/openai": "^2.0.0",
+    "@ai-sdk/xai": "^2.0.0",
+    "@openrouter/ai-sdk-provider": "^1.2.0",
+    "ai": "^5.0.0",
+    "highlight.js": "^11.11.1",
+    "html-entities": "^2.6.0",
+    "marked": "^17.0.4",
+    "workers-ai-provider": "^3.1.14",
+    "zod": "^4.3.6"
+  },
+  "keywords": [
+    "ai",
+    "llm",
+    "language-generation",
+    "vercel-ai-sdk",
+    "nlp",
+    "multi-provider",
+    "groq",
+    "openai",
+    "anthropic",
+    "google",
+    "aws-bedrock",
+    "cloudflare-workers",
+    "ollama",
+    "hacktoberfest"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/generate-response.ts

@@ -0,0 +1,196 @@
+/**
+ * @fileoverview Core logic for generating AI language responses using Vercel AI SDK and various LLM providers.
+ * Handles prompt interpolation, tool calling, and response formatting.
+ */
+import { generateText, stepCountIs, tool } from "ai";
+import { AGENT_PROMPTS } from "./prompt-templates";
+import { AGENT_TOOLS } from "../tools/qwksearch-api-tools";
+import { LANGUAGE_MODELS, LANGUAGE_PROVIDERS } from "./language-model-registry";
+import { createLLMProvider } from "./provider-factory";
+import { convertMarkdownToHTMLEscaped } from "../utils/markdown-to-html";
+import type {
+  AgentPrompt,
+  AgentTool,
+  GenerateLanguageOptions,
+  GenerateLanguageResult,
+} from "./generation-types";
+
+export type {
+  LLMProviderName,
+  GenerateLanguageOptions,
+  GenerateLanguageResult,
+} from "./generation-types";
+export { convertMarkdownToHTMLEscaped } from "../utils/markdown-to-html";
+
+/**
+ * ### Generate Language Response
+ * Writes a language response that shows human-like understanding of the
+ * question and context.
+ * - _Requires_: LLM provider, API key, agent name, and context variables.
+ * - _Providers_: groq, togetherai, openai, anthropic, xai, google,
+ *   perplexity, cloudflare, nvidia
+ * - _Agent Templates_: custom local entries defined in AGENT_PROMPTS.
+ * - _How it Works_: Language models predict the most likely next token given
+ *   a prompt. They represent words as high-dimensional vectors, use
+ *   transformer attention across all prior tokens, and sample from the
+ *   resulting probability distribution to produce human-like text.
+ *
+ * @see [Vercel AI SDK generateText docs](https://sdk.vercel.ai/docs/reference/ai-sdk-core/generate-text)
+ * @see [Hugging Face tutorials](https://huggingface.co/learn)
+ * @see [Illustrated Transformer](https://jalammar.github.io/illustrated-transformer/)
+ * @see [Building a Transformer with PyTorch](https://www.datacamp.com/tutorial/building-a-transformer-with-py-torch)
+ * @see [LLM training example](https://github.com/vtempest/ai-research-agent/blob/master/packages/neural-net/src/train/predict-next-word.js)
+ *
+ * @param options - Configuration for the language-model call
+ * @returns Resolved response object with `content`, optional `extract`, or `error`
+ * @author [Language Model Researchers](https://arc.net/folder/D0472A20-9C20-4D3F-B145-D2865C0A9FEE)
+ * @example
+ * const response = await generateLanguageResponse({
+ *   query: "Explain neural networks",
+ *   agent: "question",
+ *   provider: "groq",
+ *   apiKey: "your-api-key",
+ * });
+ */
+export async function generateLanguageResponse(
+  options: GenerateLanguageOptions = {} as GenerateLanguageOptions,
+): Promise<GenerateLanguageResult> {
+  const {
+    apiKey,
+    agent = "question",
+    temperature = 1,
+    html = true,
+    applyContextLimit = true,
+    ...context
+  } = options;
+
+  // Normalise provider to lowercase for consistent switch matching
+  const provider = options.provider?.toLowerCase();
+
+  // Resolve model: explicit override \u2192 provider's registered default
+  const model =
+    options.model ??
+    (LANGUAGE_MODELS as Array<{ provider: string; default?: string }>).find(
+      (m) => m.provider.toLowerCase() === provider,
+    )?.default ??
+    "";
+
+  try {
+    // \u2500\u2500 1. Validate required inputs \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    const validProviders = LANGUAGE_PROVIDERS as string[];
+    if (!apiKey || !provider || !validProviders.includes(provider)) {
+      return {
+        error:
+          "API key and provider are required. Valid providers: " +
+          validProviders.join(", "),
+      };
+    }
+
+    // \u2500\u2500 2. Load agent prompt from local registry \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    const agentObject = (AGENT_PROMPTS as AgentPrompt[]).find(
+      (p) => p?.name === agent,
+    );
+
+    if (!agentObject) return { error: `Agent "${agent}" not found` };
+
+    // \u2500\u2500 3. Pre-process the prompt template via optional `before` hook \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    if (agentObject.before) {
+      agentObject.prompt = agentObject.before(agentObject.prompt, options);
+    }
+
+    // \u2500\u2500 4. Build template variable map and interpolate placeholders \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    const templateVars: Record<string, unknown> = {
+      ...options,
+      input: `${context.query ?? ""} ${context.article ?? ""}`,
+    };
+    let prompt = interpolateTemplate(agentObject.template ?? "", templateVars);
+
+    // \u2500\u2500 5. Trim prompt to the model's context window \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    if (applyContextLimit) {
+      const modelConfig = (
+        LANGUAGE_MODELS as Array<{
+          provider: string;
+          models: Array<{ id: string; contextLength: number }>;
+        }>
+      )
+        .find((m) => m.provider.toLowerCase() === provider)
+        ?.models.find((m) => m.id === model);
+
+      if (modelConfig) {
+        prompt = prompt.slice(0, modelConfig.contextLength);
+      }
+    }
+
+    // \u2500\u2500 6. Instantiate the LLM provider \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    const llm = createLLMProvider(provider, apiKey, model, temperature);
+    if (!llm) return { error: "Invalid provider selected" };
+
+    // \u2500\u2500 7. Resolve tools declared by the agent \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    const agentToolDefs = (AGENT_TOOLS as AgentTool[]).filter((t) =>
+      agentObject.tools?.includes(t.name),
+    );
+    const tools =
+      agentToolDefs.length > 0
+        ? Object.fromEntries(
+            agentToolDefs.map((t) => [
+              t.name,
+              tool({
+                description: t.description as string,
+                inputSchema: t.schema as any,
+                execute: t.func as (args: any) => Promise<string>,
+              }),
+            ]),
+          )
+        : undefined;
+
+    // \u2500\u2500 8. Invoke LLM via Vercel AI SDK generateText \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    const { text: rawReply } = await generateText({
+      model: llm,
+      prompt,
+      temperature,
+      ...(tools && { tools, stopWhen: stepCountIs(10) }),
+    });
+
+    // \u2500\u2500 9. Format output (HTML or raw Markdown) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    const content: string = html
+      ? await convertMarkdownToHTMLEscaped(rawReply)
+      : rawReply;
+
+    // \u2500\u2500 10. Extract structured data via optional `after` hook \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    const extract = agentObject.after?.(rawReply, options);
+
+    return { content, ...(extract !== undefined && { extract }) };
+  } catch (err) {
+    const error = err as { response?: { status?: number }; message?: string };
+    return {
+      error:
+        error.response?.status === 429
+          ? "Rate limit exceeded. Please wait before trying again."
+          : (error.message ??
+            "Failed to generate response. Please try again later."),
+    };
+  }
+}
+
+/**
+ * Substitutes `{variableName}` placeholders in a template string with values
+ * from `vars`. Object/array values are pretty-printed without braces or
+ * commas. Unmatched keys fall back to `"[not provided]"`.
+ *
+ * @param template - Template string containing `{key}` placeholders
+ * @param vars     - Map of variable names to their replacement values
+ * @returns The fully interpolated string
+ */
+function interpolateTemplate(
+  template: string,
+  vars: Record<string, unknown>,
+): string {
+  return template.replace(/\{(.+?)\}/g, (_match, key: string) => {
+    if (!(key in vars)) return "[not provided]";
+    const value = vars[key];
+    if (typeof value === "string") return value;
+    return JSON.stringify(value, null, 2)
+      .replace(/[{}"]/g, "")
+      .replace(/,/g, "\n");
+  });
+}

package/src/generation-types.ts

@@ -0,0 +1,90 @@
+// @ts-nocheck
+/**
+ * @module research/agents/generate-language-types
+ * @description Shared types for the generate-language module.
+ */
+
+/** Supported LLM provider identifiers */
+export type LLMProviderName =
+  | "nvidia"
+  | "openrouter"
+  | "anthropic"
+  | "google"
+  | "openai"
+  | "xai"
+  | "groq"
+  | "cloudflare"
+  | "perplexity"
+  | "amazon"
+  | "bedrock"
+  | "togetherai"
+  | (string & {}); // preserve autocomplete while allowing arbitrary strings
+
+/**
+ * Configuration options for {@link generateLanguageResponse}.
+ */
+export interface GenerateLanguageOptions {
+  /** LLM provider to use */
+  provider: LLMProviderName;
+  /**
+   * API key for the provider.
+   * For `cloudflare`, use the `"apiToken:accountId"` format.
+   * For `amazon`/`bedrock`, use bearer token or `"region:accessKeyId:secretAccessKey"` format.
+   */
+  apiKey?: string;
+  /** Agent prompt template name (default: `"question"`) */
+  agent?: string;
+  /** Specific model ID. Falls back to the provider's registered default. */
+  model?: string;
+  /**
+   * Sampling temperature (0\u20132).
+   * Lower = more deterministic; higher = more creative. Default: `1`
+   */
+  temperature?: number;
+  /** User query text */
+  query?: string;
+  /** Article or document text to process */
+  article?: string;
+  /** Prior conversation history for context-aware agents */
+  chat_history?: string;
+  /** Return `HTML` (`true`) or raw Markdown (`false`). Default: `true` */
+  html?: boolean;
+  /** Truncate the prompt to the model's context window length. Default: `true` */
+  applyContextLimit?: boolean;
+  /** Additional template variables forwarded to the agent prompt */
+  [key: string]: unknown;
+}
+
+/** Return value of {@link generateLanguageResponse} */
+export interface GenerateLanguageResult {
+  /** Generated response in HTML or Markdown format */
+  content?: string;
+  /** Structured data extracted by the agent's `after` callback */
+  extract?: unknown;
+  /** Human-readable error message when generation fails */
+  error?: string;
+}
+
+/** Agent prompt template definition */
+export interface AgentPrompt {
+  name: string;
+  /** Mustache-style template string with `{variableName}` placeholders */
+  template?: string;
+  prompt?: string;
+  /** Called before template substitution to pre-process the prompt */
+  before?: (
+    prompt: string | undefined,
+    options: GenerateLanguageOptions,
+  ) => string;
+  /** Called after generation to extract structured data from the raw reply */
+  after?: (reply: string, options: GenerateLanguageOptions) => unknown;
+  /** Names of registered agent tools to attach to this agent */
+  tools?: string[];
+}
+
+/** A registered agent tool with a name, schema, and async handler */
+export interface AgentTool {
+  name: string;
+  func: (...args: unknown[]) => unknown | Promise<unknown>;
+  [key: string]: unknown;
+}

package/src/index.ts

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Language Generation Module
+ *
+ * Centralized exports for AI language model response generation using Vercel AI SDK.
+ * Provides prompt templates, model registries, provider factories, and response
+ * generation functions for 10+ LLM providers.
+ *
+ * @module language-generation
+ * @author ai-research-agent contributors
+ */
+
+export {
+  generateLanguageResponse,
+  convertMarkdownToHTMLEscaped,
+} from "./generate-response";
+
+export type {
+  LLMProviderName,
+  GenerateLanguageOptions,
+  GenerateLanguageResult,
+} from "./generate-response";
+
+export type {
+  AgentPrompt,
+  AgentTool,
+} from "./generation-types";
+
+export { AGENT_PROMPTS, extractJSONFromLanguageReply } from "./prompt-templates";
+export {
+  LANGUAGE_MODELS,
+  LANGUAGE_PROVIDERS,
+  getModelsByProvider,
+  getAllModels,
+  getModelsByCapability,
+  getTextOnlyModels,
+  getMultimodalModels,
+} from "./language-model-registry";
+export type { ModelCapability, ModelInfo } from "./language-model-registry";
+export { createLLMProvider } from "./provider-factory";
+export * from "./prompts";