chat-agent-toolkit 1.2.1

package/src/types.d.ts

@@ -0,0 +1,137 @@
+/**
+ * @fileoverview Global Type Definitions
+ *
+ * Shared TypeScript types for UI configuration, model providers,
+ * and MCP server configuration used throughout the toolkit.
+ */
+
+import { Model } from "./config/config-types";
+
+type BaseUIConfigField = {
+  name: string;
+  key: string;
+  required: boolean;
+  description: string;
+  scope: "client" | "server";
+  env?: string;
+};
+
+type StringUIConfigField = BaseUIConfigField & {
+  type: "string";
+  placeholder?: string;
+  default?: string;
+};
+
+type SelectUIConfigFieldOptions = {
+  name: string;
+  value: string;
+};
+
+type SelectUIConfigField = BaseUIConfigField & {
+  type: "select";
+  default?: string;
+  options: SelectUIConfigFieldOptions[];
+};
+
+type PasswordUIConfigField = BaseUIConfigField & {
+  type: "password";
+  placeholder?: string;
+  default?: string;
+};
+
+type TextareaUIConfigField = BaseUIConfigField & {
+  type: "textarea";
+  placeholder?: string;
+  default?: string;
+};
+
+type SwitchUIConfigField = BaseUIConfigField & {
+  type: "switch";
+  default?: boolean;
+};
+
+type UIConfigField =
+  | StringUIConfigField
+  | SelectUIConfigField
+  | PasswordUIConfigField
+  | TextareaUIConfigField
+  | SwitchUIConfigField;
+
+type ConfigModelProvider = {
+  id: string;
+  name: string;
+  type: string;
+  chatModels: Model[];
+  config: { [key: string]: any };
+  hash: string;
+  isEnvBased?: boolean; // True if provider was created from environment variables (global keys)
+};
+
+type MCPServerConfig = {
+  id: string;
+  name: string;
+  type: string;
+  url?: string;
+  apiKey?: string;
+  config: { [key: string]: any };
+  enabled: boolean;
+  hash: string;
+};
+
+type Config = {
+  version: number;
+  setupComplete: boolean;
+  preferences: {
+    [key: string]: any;
+  };
+  personalization: {
+    [key: string]: any;
+  };
+  modelProviders: ConfigModelProvider[];
+  mcpServers: MCPServerConfig[];
+  search: {
+    [key: string]: any;
+  };
+};
+
+type EnvMap = {
+  [key: string]: {
+    fieldKey: string;
+    providerKey: string;
+  };
+};
+
+type ModelProviderUISection = {
+  name: string;
+  key: string;
+  fields: UIConfigField[];
+};
+
+type MCPServerUISection = {
+  name: string;
+  key: string;
+  fields: UIConfigField[];
+};
+
+type UIConfigSections = {
+  preferences: UIConfigField[];
+  personalization: UIConfigField[];
+  modelProviders: ModelProviderUISection[];
+  mcpServers: MCPServerUISection[];
+  search: UIConfigField[];
+};
+
+export type {
+  UIConfigField,
+  Config,
+  EnvMap,
+  UIConfigSections,
+  SelectUIConfigField,
+  StringUIConfigField,
+  ModelProviderUISection,
+  MCPServerUISection,
+  ConfigModelProvider,
+  MCPServerConfig,
+  TextareaUIConfigField,
+  SwitchUIConfigField,
+};

package/src/utils/README.md

@@ -0,0 +1,98 @@
+# Provider Image Cropper
+
+Utility for extracting individual provider logos from a sprite sheet.
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { cropProvider, cropProviderAsDataURL, getProviderImage } from 'agent-toolkit';
+
+// Method 1: Load image first, then crop
+const img = new Image();
+img.src = '/providers-sprite.png';
+await img.decode();
+const canvas = await cropProvider(img, 'openai');
+
+// Method 2: Get as data URL (for React/Vue components)
+const dataUrl = await cropProviderAsDataURL(img, 'anthropic');
+
+// Method 3: Load and crop in one step
+const canvas = await getProviderImage('/providers-sprite.png', 'gemini');
+```
+
+### React Component Example
+
+```tsx
+import { useEffect, useState } from 'react';
+import { cropProviderAsDataURL, Provider } from 'agent-toolkit';
+
+function ProviderIcon({ providerType }: { providerType: Provider }) {
+  const [iconUrl, setIconUrl] = useState<string | null>(null);
+
+  useEffect(() => {
+    const loadIcon = async () => {
+      const img = new Image();
+      img.src = '/providers-sprite.png';
+      await img.decode();
+      const url = await cropProviderAsDataURL(img, providerType);
+      setIconUrl(url);
+    };
+    loadIcon();
+  }, [providerType]);
+
+  return iconUrl ? <img src={iconUrl} alt={providerType} /> : null;
+}
+```
+
+## Sprite Sheet Layout
+
+The sprite sheet must be organized in a 6×4 grid (6 columns, 4 rows) with the following layout:
+
+| Row 0 | Col 0 | Col 1 | Col 2 | Col 3 | Col 4 | Col 5 |
+|-------|-------|-------|-------|-------|-------|-------|
+| **0** | openrouter | tongyi | ollama | huggingface | localai | openllm |
+| **1** | zhipu | replicate | azure | anthropic | groq | sagemaker |
+| **2** | 01ai | bedrock | openai | cohere | together | xorbits |
+| **3** | wenxin | moonshot | gemini | mistral | jina | chatglm |
+
+## Available Providers
+
+Use `getProviderNames()` to get all supported providers:
+
+```typescript
+import { getProviderNames } from 'agent-toolkit';
+
+const providers = getProviderNames();
+// ['openrouter', 'tongyi', 'ollama', 'huggingface', ...]
+```
+
+## API Reference
+
+### `cropProvider(image, provider)`
+Returns a canvas element with the cropped provider logo.
+
+### `cropProviderAsBlob(image, provider, type?, quality?)`
+Returns a Blob of the cropped logo. Useful for file uploads.
+
+### `cropProviderAsDataURL(image, provider, type?, quality?)`
+Returns a data URL string. Best for inline images in HTML/React.
+
+### `getProviderImage(spriteSheetUrl, provider)`
+Loads the sprite sheet and returns the cropped canvas in one call.
+
+### `getProviderNames()`
+Returns an array of all supported provider names.
+
+## Creating a Sprite Sheet
+
+To create a compatible sprite sheet:
+
+1. Collect 24 provider logos (one for each provider)
+2. Arrange them in a 6×4 grid following the layout above
+3. Ensure all logos are the same size
+4. Export as PNG with transparency
+5. Save to `public/images/providers-sprite.png`
+
+Recommended tile size: 128×128px or 256×256px per provider.

package/src/utils/chat-helpers.ts

@@ -0,0 +1,18 @@
+/**
+ * Chat history formatting utilities
+ */
+
+type ChatHistoryMessage = {
+  content?: unknown;
+  role?: string;
+  type?: string;
+};
+
+export const formatChatHistoryAsString = (history: ChatHistoryMessage[]) => {
+  return history
+    .map(
+      (message) =>
+        `${message.role === 'assistant' || message.type === 'ai' ? 'AI' : 'User'}: ${String(message.content ?? '')}`,
+    )
+    .join('\n');
+};

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+export * from './chat-helpers';
+export * from './outputParser';

package/src/utils/markdown-to-html.ts

@@ -0,0 +1,53 @@
+/**
+ * @module research/agents/markdown-to-html
+ * @description Converts Markdown to HTML with Highlight.js syntax highlighting.
+ */
+import { marked } from "marked";
+import hljs from "highlight.js";
+import { encode, decode } from "html-entities";
+
+// Inline onclick: self-contained per button, works in dangerouslySetInnerHTML contexts
+const COPY_ONCLICK = [
+  "(function(b){",
+  "var c=b.closest('figure.code-block')?.querySelector('pre code');",
+  "if(!c)return;",
+  "navigator.clipboard.writeText(c.innerText).then(function(){",
+  "var t=b.textContent;b.textContent='Copied!';",
+  "setTimeout(function(){b.textContent=t},2000)",
+  "})",
+  "})(this)",
+].join("");
+
+// Configure marked once at module load \u2014 stacking use() calls would duplicate extensions
+marked.use({ breaks: true, gfm: true, async: true });
+
+marked.use({
+  renderer: {
+    code({ text, lang }) {
+      const language = lang || "plaintext";
+      let highlighted: string;
+
+      try {
+        if (language && hljs.getLanguage(language)) {
+          highlighted = hljs.highlight(text, { language }).value;
+        } else {
+          highlighted = hljs.highlightAuto(text).value;
+        }
+      } catch (e) {
+        highlighted = encode(text);
+      }
+
+      return `<figure class="code-block"><button class="code-copy-btn" type="button" onclick="${COPY_ONCLICK}">Copy</button><pre><code class="hljs language-${language}">${highlighted}</code></pre></figure>`;
+    },
+  },
+});
+
+/**
+ * Convert markdown text to HTML with Highlight.js syntax highlighting.
+ * Unescapes HTML entities like `&amp;` \u2192 `&`.
+ */
+export async function convertMarkdownToHTMLEscaped(
+  markdown: string,
+): Promise<string> {
+  return (await marked.parse(decode(markdown))).trim();
+}

package/src/utils/outputParser.ts

@@ -0,0 +1,73 @@
+/**
+ * @module agent-toolkit/utils/outputParser
+ * @description Parsers that extract values from XML-tagged sections of LLM
+ * output (e.g. `<links>...</links>`, `<question>...</question>`).
+ */
+
+const LIST_MARKER_REGEX = /^(\s*(-|\*|\d+\.\s|\d+\)\s|•)\s*)+/;
+
+interface LineListOutputParserArgs {
+  key?: string;
+}
+
+export class LineListOutputParser {
+  private key = "questions";
+
+  constructor(args?: LineListOutputParserArgs) {
+    this.key = args?.key ?? this.key;
+  }
+
+  async parse(text: string): Promise<string[]> {
+    text = text.trim() || "";
+
+    const startKeyIndex = text.indexOf(`<${this.key}>`);
+    const endKeyIndex = text.indexOf(`</${this.key}>`);
+
+    if (startKeyIndex === -1 || endKeyIndex === -1) {
+      return [];
+    }
+
+    const questionsStartIndex = startKeyIndex + `<${this.key}>`.length;
+    const lines = text
+      .slice(questionsStartIndex, endKeyIndex)
+      .trim()
+      .split("\n")
+      .filter((line) => line.trim() !== "")
+      .map((line) => line.replace(LIST_MARKER_REGEX, ""));
+
+    return lines;
+  }
+}
+
+interface LineOutputParserArgs {
+  key?: string;
+}
+
+export class LineOutputParser {
+  private key = "questions";
+
+  constructor(args?: LineOutputParserArgs) {
+    this.key = args?.key ?? this.key;
+  }
+
+  async parse(text: string): Promise<string | undefined> {
+    text = text.trim() || "";
+
+    const startKeyIndex = text.indexOf(`<${this.key}>`);
+    const endKeyIndex = text.indexOf(`</${this.key}>`);
+
+    if (startKeyIndex === -1 || endKeyIndex === -1) {
+      return undefined;
+    }
+
+    const questionsStartIndex = startKeyIndex + `<${this.key}>`.length;
+    const line = text
+      .slice(questionsStartIndex, endKeyIndex)
+      .trim()
+      .replace(LIST_MARKER_REGEX, "");
+
+    return line;
+  }
+}
+
+export default LineOutputParser;

package/src/utils/provider-image-cropper.ts

@@ -0,0 +1,130 @@
+const PROVIDERS = {
+  openrouter: { row: 0, col: 0 },
+  tongyi: { row: 0, col: 1 },
+  ollama: { row: 0, col: 2 },
+  huggingface: { row: 0, col: 3 },
+  localai: { row: 0, col: 4 },
+  openllm: { row: 0, col: 5 },
+  zhipu: { row: 1, col: 0 },
+  replicate: { row: 1, col: 1 },
+  azure: { row: 1, col: 2 },
+  anthropic: { row: 1, col: 3 },
+  groq: { row: 1, col: 4 },
+  sagemaker: { row: 1, col: 5 },
+  "01ai": { row: 2, col: 0 },
+  bedrock: { row: 2, col: 1 },
+  openai: { row: 2, col: 2 },
+  cohere: { row: 2, col: 3 },
+  together: { row: 2, col: 4 },
+  xorbits: { row: 2, col: 5 },
+  wenxin: { row: 3, col: 0 },
+  moonshot: { row: 3, col: 1 },
+  gemini: { row: 3, col: 2 },
+  mistral: { row: 3, col: 3 },
+  jina: { row: 3, col: 4 },
+  chatglm: { row: 3, col: 5 },
+} as const;
+
+export type Provider = keyof typeof PROVIDERS;
+
+const COLS = 6;
+const ROWS = 4;
+
+/**
+ * Returns a cropped canvas containing just the provider box.
+ */
+export async function cropProvider(
+  image: HTMLImageElement | ImageBitmap,
+  provider: Provider
+): Promise<HTMLCanvasElement> {
+  if (!(provider in PROVIDERS)) {
+    throw new Error(`Unknown provider: ${provider}`);
+  }
+
+  const { row, col } = PROVIDERS[provider];
+
+  const tileWidth = image.width / COLS;
+  const tileHeight = image.height / ROWS;
+
+  const canvas = document.createElement("canvas");
+  canvas.width = tileWidth;
+  canvas.height = tileHeight;
+
+  const ctx = canvas.getContext("2d");
+  if (!ctx) {
+    throw new Error("Failed to get 2D context");
+  }
+
+  ctx.drawImage(
+    image,
+    col * tileWidth,
+    row * tileHeight,
+    tileWidth,
+    tileHeight,
+    0,
+    0,
+    tileWidth,
+    tileHeight
+  );
+
+  return canvas;
+}
+
+/**
+ * Returns the provider image as a Blob.
+ */
+export async function cropProviderAsBlob(
+  image: HTMLImageElement | ImageBitmap,
+  provider: Provider,
+  type: "image/png" | "image/jpeg" | "image/webp" = "image/png",
+  quality?: number
+): Promise<Blob> {
+  const canvas = await cropProvider(image, provider);
+
+  return new Promise<Blob>((resolve, reject) => {
+    canvas.toBlob(
+      (blob) => {
+        if (blob) {
+          resolve(blob);
+        } else {
+          reject(new Error("Failed to create blob"));
+        }
+      },
+      type,
+      quality
+    );
+  });
+}
+
+/**
+ * Returns the provider image as a data URL.
+ */
+export async function cropProviderAsDataURL(
+  image: HTMLImageElement | ImageBitmap,
+  provider: Provider,
+  type: "image/png" | "image/jpeg" | "image/webp" = "image/png",
+  quality?: number
+): Promise<string> {
+  const canvas = await cropProvider(image, provider);
+  return canvas.toDataURL(type, quality);
+}
+
+/**
+ * Helper to load and crop in one call.
+ */
+export async function getProviderImage(
+  spriteSheetUrl: string,
+  provider: Provider
+): Promise<HTMLCanvasElement> {
+  const img = new Image();
+  img.src = spriteSheetUrl;
+  await img.decode();
+  return cropProvider(img, provider);
+}
+
+/**
+ * Get all available provider names.
+ */
+export function getProviderNames(): Provider[] {
+  return Object.keys(PROVIDERS) as Provider[];
+}