chat-agent-toolkit 1.2.367 → 1.2.369

package/dist/chat-agent-toolkit/src/tools/qwksearch-api-tools.d.ts

@@ -81,8 +81,8 @@ export declare const AGENT_TOOLS: ({
         bypassCaptcha: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
         sessionId: z.ZodDefault<z.ZodOptional<z.ZodString>>;
         format: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
-            html: "html";
             json: "json";
+            html: "html";
         }>>>;
         scraperUrl: z.ZodOptional<z.ZodString>;
         scraperApiKey: z.ZodOptional<z.ZodString>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chat-agent-toolkit",
-  "version": "1.2.367",
+  "version": "1.2.369",
   "description": "Multi-provider AI agent toolkit: generate language responses, search the web, extract content, and manage memory across 10+ LLM providers.",
   "author": "vtempest <grokthiscontact@gmail.com>",
   "license": "rights.institute/PROSPER",
@@ -98,7 +98,7 @@
     "html-entities": "^2.6.0",
     "manage-storage": "^0.0.47",
     "marked": "^18.0.12",
-    "qwksearch-api-client": "^1.0.39",
+    "qwksearch-api-client": "^1.0.41",
     "write-language": "^0.1.153",
     "zod": "^4.5.4"
   },

package/src/config/config-manager.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Configuration Manager
+ *
+ * Manages model providers, MCP servers, and search configuration in memory.
+ * Handles environment variable loading, provider hashing, and config updates.
+ */
+import type { ConfigModelProvider, Config, UIConfigSections } from "./config-types";
+declare class ConfigManager {
+    configVersion: number;
+    currentConfig: Config;
+    uiConfigSections: UIConfigSections;
+    private initialized;
+    constructor();
+    private ensureInitialized;
+    private initialize;
+    getConfig(key: string, defaultValue?: any): any;
+    updateConfig(key: string, val: any): void;
+    addModelProvider(type: string, name: string, config: any): ConfigModelProvider;
+    removeModelProvider(id: string): void;
+    updateModelProvider(id: string, name: string, config: any): Promise<ConfigModelProvider>;
+    addProviderModel(providerId: string, type: "chat", model: any): any;
+    removeProviderModel(providerId: string, type: "chat", modelKey: string): void;
+    isSetupComplete(): boolean;
+    markSetupComplete(): void;
+    getUIConfigSections(): UIConfigSections;
+    getCurrentConfig(): Config;
+}
+declare const configManager: ConfigManager;
+export default configManager;

package/src/config/config-types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @module research/models/types
+ * @description Shared types for the config system and model registry.
+ */
+/** A chat model entry as shown in provider model lists. */
+export type Model = {
+    name: string;
+    key: string;
+};
+/** Provider shape consumed by model-selector UI components. */
+export type MinimalProvider = {
+    id: string;
+    name: string;
+    chatModels: Model[];
+};
+/** Client-side model selection: which provider and model key to use. */
+export type ModelWithProvider = {
+    key?: string;
+    providerId?: string;
+};
+/** A configured model provider (env-based or user-added). */
+export type ConfigModelProvider = {
+    id: string;
+    name: string;
+    /** Provider type key, e.g. "openai", "anthropic", "gemini". */
+    type: string;
+    /** User-added chat models (defaults come from LANGUAGE_MODELS). */
+    chatModels: Model[];
+    /** Provider connection config, e.g. { apiKey, baseURL }. */
+    config: Record<string, any>;
+    /** Hash of the config, used as the provider id. */
+    hash: string;
+    /** True when the provider was configured from environment variables. */
+    isEnvBased?: boolean;
+};
+export type MCPServerConfig = {
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    [key: string]: any;
+};
+export type Config = {
+    version: number;
+    setupComplete: boolean;
+    preferences: Record<string, any>;
+    personalization: Record<string, any>;
+    modelProviders: ConfigModelProvider[];
+    mcpServers: MCPServerConfig[];
+    search: Record<string, any>;
+};
+/** UI field/section definitions consumed by the settings screens. */
+export type UIConfigSections = {
+    preferences: any[];
+    personalization: any[];
+    modelProviders: any[];
+    mcpServers: any[];
+    search: any[];
+};

package/src/config/environment-variables.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Runtime env-var accessor.
+ * Supports both local development (process.env) and Cloudflare Workers
+ * (cloudflare:workers virtual module) via dynamic import.
+ */
+export declare function getEnv(key: string): string | undefined;

package/src/config/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Configuration Management Module
+ *
+ * Manages model providers, environment variables, and UI configuration
+ * for the AI agent toolkit. Provides in-memory config storage with
+ * support for multiple LLM providers and MCP servers.
+ *
+ * @module config
+ * @author ai-research-agent contributors
+ */
+export { default as configManager } from "./config-manager";
+export { default as ModelRegistry } from "./model-registry";
+export { getEnv } from "./environment-variables";
+export { LANGUAGE_MODELS } from "./language-models-database";
+export { getModelProvidersUIConfigSection } from "./provider-ui-config";
+export * from "./model-tester";
+export * from "./model-utils";
+export type { Config, ConfigModelProvider, MCPServerConfig, UIConfigSections, Model, ModelWithProvider, } from "./config-types";

package/src/config/language-models-database.d.ts

@@ -0,0 +1,95 @@
+/**
+ * List of default models for the chat providers and a list of models
+ * @property {string} provider - The provider name
+ * @property {string} docs - The documentation URL for the model
+ * @property {string} api_key - The API key  url for the model
+ * @property {string} default - The default model for the chat provider
+ * @property {Object[]} models - The list of models available for the chat provider
+ * @category Generate
+ */
+export declare const LANGUAGE_MODELS: ({
+    provider: string;
+    docs: string;
+    api_key: string;
+    default: string;
+    models: {
+        name: string;
+        id: string;
+        contextLength: number;
+        free: boolean;
+        type: string;
+    }[];
+} | {
+    provider: string;
+    docs: string;
+    api_key: string;
+    default: string;
+    models: {
+        name: string;
+        id: string;
+        contextLength: number;
+    }[];
+} | {
+    provider: string;
+    docs: string;
+    api_key: string;
+    default: string;
+    models: {
+        name: string;
+        id: string;
+        contextLength: number;
+        free: boolean;
+        type: string;
+        rateLimit: string;
+    }[];
+} | {
+    default?: undefined;
+    provider: string;
+    docs: string;
+    api_key: string;
+    models: {
+        name: string;
+        id: string;
+        contextLength: number;
+    }[];
+} | {
+    provider: string;
+    docs: string;
+    api_key: string;
+    default: string;
+    models: ({
+        type?: undefined;
+        name: string;
+        id: string;
+        contextLength: number;
+        provider: string;
+    } | {
+        name: string;
+        id: string;
+        contextLength: number;
+        provider: string;
+        type: string;
+    })[];
+})[];
+/** List of available LLM provider services */
+export declare const LANGUAGE_PROVIDERS: string[];
+/**
+ * Guest-safe models that are known to work reliably.
+ * Based on test results: only models with HTTP 200 status.
+ * Last tested: 2026-07-22
+ */
+export declare const GUEST_SAFE_MODELS: {
+    nvidia: string[];
+    anyapi: string[];
+    openrouter: string[];
+};
+/**
+ * Filter models to only those in the guest-safe list.
+ * Returns models with `free: true` property.
+ */
+export declare function filterModelsForGuests(models: any[]): any[];
+/**
+ * Get guest-safe provider list (only tested working models).
+ * Uses GUEST_SAFE_MODELS whitelist to ensure reliability.
+ */
+export declare function getGuestSafeProviders(): typeof LANGUAGE_MODELS;

package/src/config/model-registry.d.ts

@@ -0,0 +1,70 @@
+import type { ConfigModelProvider, Model } from "./config-types";
+export default class ModelRegistry {
+    /**
+     * Currently configured providers (env-based + user-added).
+     * Sync getter used by the chat handler for logging and lookups.
+     */
+    get activeProviders(): ConfigModelProvider[];
+    /**
+     * Providers with their full chat model lists (defaults merged with
+     * user-added models), shaped for the settings/providers UI.
+     */
+    getActiveProviders(guestMode?: boolean): Promise<{
+        id: string;
+        name: string;
+        type: string;
+        chatModels: Model[];
+    }[]>;
+    /**
+     * Get guest-safe chat models for a provider (only tested working models).
+     */
+    private getGuestChatModels;
+    /**
+     * Finds a provider by id, falling back to free providers in order:
+     * OpenRouter (no daily limits, best for guests), Groq (fastest, daily limits),
+     * AnyAPI (100,000 anyTokens/day free), then NVIDIA, then the first
+     * configured provider.
+     * Client-side provider ids are config hashes that go stale whenever
+     * server env config changes, so a graceful fallback keeps existing
+     * chat sessions working after a redeploy.
+     */
+    private findProvider;
+    /** Whether the resolved provider was configured from environment variables. */
+    isProviderEnvBased(providerId?: string): boolean;
+    /**
+     * Instantiates a Vercel AI SDK language model for the given provider and
+     * model key. Falls back to the provider's first/default model when no key
+     * is given. Temperature is a per-call setting in the AI SDK, so callers
+     * pass it to generateText/streamText rather than the model instance.
+     */
+    loadChatModel(providerId?: string, modelKey?: string): Promise<any>;
+    /**
+     * Registers a new provider. Accepts both `(type, config)` — used by the
+     * providers API route — and `(type, name, config)`.
+     */
+    addProvider(type: string, nameOrConfig: any, config?: Record<string, any>): Promise<{
+        id: string;
+        name: string;
+        type: string;
+        config: Record<string, any>;
+        hash: string;
+        isEnvBased?: boolean;
+        chatModels: Model[];
+    }>;
+    removeProvider(providerId: string): Promise<void>;
+    /**
+     * Updates a provider's config. Accepts both `(id, config)` — used by the
+     * providers API route — and `(id, name, config)`.
+     */
+    updateProvider(providerId: string, nameOrConfig: any, config?: Record<string, any>): Promise<{
+        id: string;
+        name: string;
+        type: string;
+        config: Record<string, any>;
+        hash: string;
+        isEnvBased?: boolean;
+        chatModels: Model[];
+    }>;
+    addProviderModel(providerId: string, type: "chat", model: any): Promise<any>;
+    removeProviderModel(providerId: string, type: "chat", modelKey: string): Promise<void>;
+}

package/src/config/model-tester.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview Model availability testing and validation
+ * Tests which models are actually working for a given provider
+ */
+export interface ModelTestResult {
+    modelId: string;
+    modelName: string;
+    available: boolean;
+    error?: string;
+    latency?: number;
+    type?: string;
+}
+export interface ProviderTestResult {
+    provider: string;
+    totalModels: number;
+    availableModels: ModelTestResult[];
+    unavailableModels: ModelTestResult[];
+    testDuration: number;
+}
+/**
+ * Test a single model to see if it's working
+ */
+export declare function testModel(provider: string, apiKey: string, modelId: string, modelName: string, modelType?: string, timeout?: number): Promise<ModelTestResult>;
+/**
+ * Test all models for a provider
+ */
+export declare function testProviderModels(provider: string, apiKey: string, models: Array<{
+    id: string;
+    name: string;
+    type?: string;
+    free?: boolean;
+}>, options?: {
+    onlyFree?: boolean;
+    concurrency?: number;
+    timeout?: number;
+    onProgress?: (current: number, total: number, modelName: string) => void;
+}): Promise<ProviderTestResult>;
+/**
+ * Get only free models from a model list
+ */
+export declare function getOnlyFreeModels<T extends {
+    free?: boolean;
+}>(models: T[]): T[];
+/**
+ * Categorize models by type
+ */
+export declare function categorizeModelsByType<T extends {
+    type?: string;
+    id: string;
+    name: string;
+}>(models: T[]): Record<string, T[]>;

package/src/config/model-utils.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Utility functions for working with AI models
+ */
+/**
+ * List of model IDs that are free to use (no per-token cost)
+ * Updated regularly as providers change their pricing
+ */
+export declare const FREE_MODELS: Set<string>;
+/**
+ * Providers that offer free tiers with generous limits
+ */
+export declare const FREE_TIER_PROVIDERS: Set<string>;
+/**
+ * Check if a model is free to use (no per-token cost)
+ * Note: Free models may have rate limits
+ */
+export declare function isModelFree(modelId: string): boolean;
+/**
+ * Check if a provider offers a free tier
+ */
+export declare function hasFreeTier(providerType: string): boolean;
+/**
+ * Get a display name for a model with cost indicator
+ * Example: "Llama 3.3 70B (Free)" or "GPT-4o"
+ */
+export declare function getModelDisplayName(modelName: string, modelId: string): string;
+/**
+ * Get provider-specific information
+ */
+export declare function getProviderInfo(providerType: string): {
+    name: string;
+    hasFreeTier: boolean;
+    signupUrl: string;
+    docsUrl: string;
+};
+/**
+ * Get recommended free providers for getting started
+ */
+export declare function getRecommendedFreeProviders(): Array<{
+    type: string;
+    name: string;
+    reason: string;
+    signupUrl: string;
+}>;

package/src/config/provider-ui-config.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @module research/models/providers/index
+ * @description Research library module.
+ *
+ * This file provides metadata about providers without importing them directly,
+ * to avoid circular dependency issues with the config system.
+ */
+import { ModelProviderUISection } from "../types";
+/**
+ * Gets provider UI configuration without triggering circular dependencies.
+ * This function uses static metadata instead of importing provider classes.
+ */
+export declare const getModelProvidersUIConfigSection: () => ModelProviderUISection[];

package/src/connectors/index.d.ts

@@ -0,0 +1,84 @@
+/**
+ * OpenConnector Integration for OOMOL SaaS
+ *
+ * Multi-tenant connector platform for OAuth & credential management.
+ * Allows users to link external accounts (Gmail, Slack, GitHub, Airtable, etc.)
+ * securely managed by OOMOL Cloud.
+ *
+ * @module connectors
+ * @see {@link https://connector.oomol.com}
+ * @example
+ * ```ts
+ * import { ProjectConnector } from "chat-agent-toolkit/connectors";
+ *
+ * const project = new ProjectConnector({
+ *   apiKey: process.env.OOMOL_PROJECT_API_KEY,
+ * });
+ *
+ * const user = project.forUser(userId);
+ * const oauth = await user.connect.oauth({
+ *   service: "gmail",
+ *   returnUri: "https://myapp.com/oauth-callback",
+ * });
+ * ```
+ */
+export type { ConnectorError as OOMOLConnectorError, ProjectConnector as OOMOLProjectConnector, } from "@oomol-lab/connector";
+export { ConnectorError, ProjectConnector } from "@oomol-lab/connector";
+export type CatalogProvider = {
+    service: string;
+    displayName: string;
+    categories: string[];
+    authTypes: ("oauth2" | "api_key" | "custom_credential" | "no_auth")[];
+    actionCount: number;
+};
+export type ProviderIndexEntry = CatalogProvider & {
+    homepageUrl?: string;
+    actions?: string[];
+};
+/**
+ * Lightweight provider catalog (basic info: service, display name, auth types).
+ * ~900 providers, fast catalog search and picker UI.
+ */
+export declare const catalog: CatalogProvider[];
+/**
+ * Detailed provider index with action lists and metadata.
+ * Use for deep integration: listing available actions, mapping capabilities.
+ */
+export declare const providerIndex: ProviderIndexEntry[];
+/**
+ * Search the catalog by service name or display name.
+ * @param query Search term (case-insensitive)
+ * @param limit Max results
+ * @returns Matching providers
+ */
+export declare function searchCatalog(query: string, limit?: number): CatalogProvider[];
+/**
+ * Get a provider by service ID.
+ * @param serviceId The provider's service identifier (e.g., "gmail", "slack")
+ * @returns Provider info or undefined
+ */
+export declare function getCatalogProvider(serviceId: string): CatalogProvider | undefined;
+/**
+ * Get detailed provider info including actions.
+ * @param serviceId The provider's service identifier
+ * @returns Detailed provider entry or undefined
+ */
+export declare function getProviderDetails(serviceId: string): ProviderIndexEntry | undefined;
+/**
+ * Filter catalog by authentication type.
+ * @param authType The auth type to filter by
+ * @returns Providers supporting this auth type
+ */
+export declare function getCatalogByAuthType(authType: "oauth2" | "api_key" | "custom_credential" | "no_auth"): CatalogProvider[];
+/**
+ * Filter catalog by category.
+ * @param category The category to filter by (e.g., "Communication", "Productivity")
+ * @returns Providers in this category
+ */
+export declare function getCatalogByCategory(category: string): CatalogProvider[];
+/**
+ * Get all unique categories in the catalog.
+ * @returns Sorted list of category names
+ */
+export declare function getCatalogCategories(): string[];
+export type { Express } from "express";

package/src/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview AI Agent Toolkit
+ *
+ * Multi-provider AI agent toolkit for generating language responses, searching the web,
+ * extracting page content, and managing long-term memory across 10+ LLM providers.
+ *
+ * Built on Vercel AI SDK with prompt templates for research, summarization, citation
+ * answering, query resolution, and knowledge-graph extraction.
+ *
+ * @module ai-research-agent
+ * @author vtempest <grokthiscontact@gmail.com>
+ * @license AGPL-3.0
+ * @see {@link https://github.com/vtempest/ai-research-agent}
+ */
+export * from "write-language";
+export * from "./prompts";
+export * from "./memory";
+export * from "./tools";
+export { AGENT_TOOLS } from "./tools";
+export * from "./utils";
+export * from "./mastra";
+export { configManager, ModelRegistry, getEnv, getModelProvidersUIConfigSection } from "./config";
+export type { Config, ConfigModelProvider, MCPServerConfig, UIConfigSections, Model, ModelWithProvider } from "./config";
+export { cropProvider, cropProviderAsBlob, cropProviderAsDataURL, getProviderImage, getProviderNames } from "./utils/provider-image-cropper";
+export type { Provider } from "./utils/provider-image-cropper";
+export * from "./connectors";
+export * as connectors from "./connectors";

package/src/mastra/agents.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview Mastra Agent Factory
+ *
+ * Creates typed Mastra agents with tool-calling, model selection,
+ * and optional memory integration.
+ */
+import { Agent } from "@mastra/core/agent";
+import { z } from "zod";
+export interface MastraAgentConfig {
+    id: string;
+    name: string;
+    instructions: string;
+    model: any;
+    tools?: Record<string, any>;
+    maxSteps?: number;
+    memory?: {
+        enabled: boolean;
+        threadId?: string;
+        userId?: string;
+    };
+}
+/**
+ * Create a Mastra agent with full configuration.
+ * Supports tool-calling, multi-step reasoning, and memory.
+ *
+ * @example
+ * ```ts
+ * import { createMastraAgent } from "chat-agent-toolkit/mastra";
+ * import { openai } from "@ai-sdk/openai";
+ *
+ * const agent = createMastraAgent({
+ *   id: "research-assistant",
+ *   name: "Research Assistant",
+ *   instructions: "Help users research topics thoroughly.",
+ *   model: openai("gpt-4o"),
+ *   tools: { webSearch, extractPage },
+ * });
+ *
+ * const result = await agent.generate("What is RAG?");
+ * ```
+ */
+export declare function createMastraAgent(config: MastraAgentConfig): Agent;
+/**
+ * Create a Mastra agent with inline tool definitions using Zod schemas.
+ * Convenience wrapper for quick prototyping.
+ *
+ * @example
+ * ```ts
+ * const agent = createToolAgent({
+ *   id: "calculator",
+ *   name: "Calculator",
+ *   instructions: "Perform math operations.",
+ *   model: openai("gpt-4o"),
+ *   toolDefs: [{
+ *     id: "add",
+ *     description: "Add two numbers",
+ *     inputSchema: z.object({ a: z.number(), b: z.number() }),
+ *     outputSchema: z.object({ result: z.number() }),
+ *     execute: async ({ context }) => ({ result: context.a + context.b }),
+ *   }],
+ * });
+ * ```
+ */
+export declare function createToolAgent(config: {
+    id: string;
+    name: string;
+    instructions: string;
+    model: any;
+    toolDefs: Array<{
+        id: string;
+        description: string;
+        inputSchema: z.ZodType;
+        outputSchema: z.ZodType;
+        execute: (params: {
+            context: any;
+        }) => Promise<any>;
+    }>;
+}): Agent;

package/src/mastra/evals.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @fileoverview Mastra Evals
+ *
+ * Scorer-based evaluation functions for LLM outputs.
+ * Assess factuality, relevance, coherence, and safety.
+ */
+export interface EvalResult {
+    score: number;
+    reason: string;
+}
+export interface EvalSuiteResult {
+    overall: number;
+    results: Record<string, EvalResult>;
+}
+/**
+ * Evaluate factuality/groundedness of a response.
+ * Checks whether the output references sources or evidence.
+ *
+ * @example
+ * ```ts
+ * const result = await factualityEval(
+ *   "The earth orbits the sun (source: NASA).",
+ *   "What does the earth orbit?"
+ * );
+ * // { score: 0.9, reason: "Response includes source attribution." }
+ * ```
+ */
+export declare function factualityEval(output: string, _query?: string, sources?: string[]): Promise<EvalResult>;
+/**
+ * Evaluate relevance of a response to the query.
+ * Uses keyword overlap and length heuristics.
+ */
+export declare function relevanceEval(output: string, query: string): Promise<EvalResult>;
+/**
+ * Evaluate coherence and structure of a response.
+ * Checks sentence structure, paragraph flow, and logical markers.
+ */
+export declare function coherenceEval(output: string): Promise<EvalResult>;
+/**
+ * Evaluate output for toxic or harmful content.
+ * Basic keyword/pattern-based detection.
+ */
+export declare function toxicityEval(output: string): Promise<EvalResult>;
+/**
+ * Run a full evaluation suite against a response.
+ *
+ * @example
+ * ```ts
+ * const results = await runEvalSuite({
+ *   output: agentResponse,
+ *   query: "What is photosynthesis?",
+ *   sources: ["Biology textbook chapter 3"],
+ * });
+ *
+ * console.log(results.overall); // 0.78
+ * console.log(results.results.factuality.score); // 0.85
+ * ```
+ */
+export declare function runEvalSuite(params: {
+    output: string;
+    query?: string;
+    sources?: string[];
+}): Promise<EvalSuiteResult>;