chat-agent-toolkit 1.2.1 → 1.2.3

package/README.md

@@ -79,9 +79,9 @@ npm install ai-research-agent
 ## Quick start
 
 ```ts
-import { generateLanguageResponse } from "ai-research-agent";
+import { writeLanguageResponse } from "ai-research-agent";
 
-const response = await generateLanguageResponse({
+const response = await writeLanguageResponse({
   provider: "groq",
   apiKey: process.env.GROQ_API_KEY,
   agent: "question",
@@ -96,9 +96,9 @@ console.log(response.content);
 ### Using Amazon Bedrock
 
 ```ts
-import { generateLanguageResponse } from "ai-research-agent";
+import { writeLanguageResponse } from "ai-research-agent";
 
-const response = await generateLanguageResponse({
+const response = await writeLanguageResponse({
   provider: "amazon",
   apiKey: process.env.AWS_BEARER_TOKEN_BEDROCK, // or "region:accessKeyId:secretAccessKey"
   model: "anthropic.claude-3-5-sonnet-20241022-v2:0",
@@ -177,7 +177,7 @@ src/
   agents/                    # prompt + tool registry, generate function, model list
     agent-prompts.ts         # AGENT_PROMPTS, extractJSONFromLanguageReply
     agent-tools.ts           # AGENT_TOOLS (web_search, extract_page, ...)
-    generate-language.ts     # generateLanguageResponse — main entry point
+    generate-language.ts     # writeLanguageResponse — main entry point
     generate-language-types.ts
     language-model-names.ts  # LANGUAGE_MODELS, LANGUAGE_PROVIDERS
     llm-providers.ts         # createLLMProvider — chat-model factory
@@ -209,7 +209,7 @@ Vite bundles ES + CJS targets to `dist/`, emits `.d.ts` files alongside, and app
 
 ### Transformer Architecture Visualizations
 
-<img src="https://i.imgur.com/uW6E9VJ.gif" alt="Transformer architecture visualization" />
+<img src="https://i.imgur.com/uW6E9VJ.gif"  alt="Transformer architecture visualization" />
 
 
 ## Alternative Agents Frameworks

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

@@ -0,0 +1,23 @@
+import { 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/dist/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/dist/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/dist/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/dist/config/language-models-database.d.ts

@@ -0,0 +1,93 @@
+/**
+ * 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;
+    }[];
+} | {
+    provider: string;
+    docs: string;
+    api_key: string;
+    models: {
+        name: string;
+        id: string;
+        contextLength: number;
+    }[];
+    default?: undefined;
+} | {
+    provider: string;
+    docs: string;
+    api_key: string;
+    default: string;
+    models: ({
+        name: string;
+        id: string;
+        contextLength: number;
+        provider: string;
+        type?: undefined;
+    } | {
+        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.
+ */
+export declare const GUEST_SAFE_MODELS: {
+    openrouter: string[];
+    nvidia: 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/dist/config/mcp-server-registry.d.ts

@@ -0,0 +1,7 @@
+import { ConfigModelProvider } from './config-types';
+export declare const getConfiguredModelProviders: () => ConfigModelProvider[];
+export declare const getConfiguredModelProviderById: (id: string) => ConfigModelProvider | undefined;
+export declare const getSearxngURL: () => any;
+export declare const getTavilyApiKey: () => any;
+export declare const getSourceScrapeCount: () => number;
+export declare const getSourceScrapeTimeout: () => number;

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

@@ -0,0 +1,69 @@
+import { 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),
+     * 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<{
+        chatModels: Model[];
+        id: string;
+        name: string;
+        type: string;
+        config: Record<string, any>;
+        hash: string;
+        isEnvBased?: boolean;
+    }>;
+    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<{
+        chatModels: Model[];
+        id: string;
+        name: string;
+        type: string;
+        config: Record<string, any>;
+        hash: string;
+        isEnvBased?: boolean;
+    }>;
+    addProviderModel(providerId: string, type: "chat", model: any): Promise<any>;
+    removeProviderModel(providerId: string, type: "chat", modelKey: string): Promise<void>;
+}

package/dist/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/dist/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/dist/config/provider-ui-config.d.ts

@@ -0,0 +1,6 @@
+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/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @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 './memory';
+export * from './tools';
+export { AGENT_TOOLS } from './tools';
+export * from './utils';
+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';

package/dist/memory/agent-memory-manager.d.ts

@@ -0,0 +1,125 @@
+import { IMemoryStorage } from './storage/storage-interface';
+import { MemoryType, MemorySearchOptions } from './types';
+/**
+ * LLM provider interface
+ */
+interface LLMProvider {
+    invoke: (prompt: string) => Promise<{
+        content: string;
+        tokensUsed: number;
+    }>;
+}
+/**
+ * Chat options
+ */
+interface ChatOptions {
+    provider?: string;
+    apiKey?: string;
+    model?: string;
+    temperature?: number;
+    systemPrompt?: string;
+    includeHistory?: boolean;
+    maxMemories?: number;
+    minImportance?: number;
+}
+/**
+ * Chat response
+ */
+interface ChatResponse {
+    content?: string;
+    memoryContext?: string;
+    success: boolean;
+    tokensUsed?: number;
+    responseTime?: number;
+    sessionId?: string;
+    timestamp: string;
+    error?: string;
+}
+/**
+ * Rate limit configuration
+ */
+interface RateLimitConfig {
+    requests: number;
+    windowMs: number;
+}
+/**
+ * Agent options
+ */
+export interface MemoryAgentOptions {
+    memoryOptions?: any;
+    defaultProvider?: string;
+    defaultApiKey?: string;
+    defaultModel?: string;
+    rateLimit?: RateLimitConfig;
+    providers?: Record<string, (apiKey: string, model: string, temperature: number) => LLMProvider>;
+}
+export declare class MemoryAgent {
+    private memory;
+    private defaultProvider;
+    private defaultApiKey?;
+    private defaultModel?;
+    private rateLimiter;
+    private rateLimitConfig;
+    private providers;
+    private sessionId;
+    private conversationHistory;
+    private analytics;
+    private userId;
+    /**
+     * Initialize memory agent
+     */
+    constructor(userId: string, storage: IMemoryStorage, options?: MemoryAgentOptions);
+    /**
+     * Get default LLM providers
+     */
+    private getDefaultProviders;
+    /**
+     * Generate unique session ID
+     */
+    private generateSessionId;
+    /**
+     * Rate limiting check with sliding window
+     */
+    private checkRateLimit;
+    /**
+     * Main chat method with comprehensive error handling
+     */
+    chat(message: string, options?: ChatOptions): Promise<ChatResponse>;
+    /**
+     * Generate LLM response with timeout and error handling
+     */
+    private generateResponse;
+    /**
+     * Build enhanced prompt with context
+     */
+    private buildPrompt;
+    /**
+     * Update analytics
+     */
+    private updateAnalytics;
+    /**
+     * Remember a fact manually
+     */
+    remember(fact: string, importance?: number, category?: MemoryType, metadata?: Record<string, any>): Promise<string>;
+    /**
+     * Get memories with filtering
+     */
+    getMemories(query?: string, limit?: number, options?: MemorySearchOptions): Promise<any[]>;
+    /**
+     * Force store summary of current conversation
+     */
+    forceStoreSummary(): Promise<boolean>;
+    /**
+     * Health check for the agent
+     */
+    healthCheck(): Promise<any>;
+    /**
+     * Get analytics and performance metrics
+     */
+    getAnalytics(): any;
+    /**
+     * Reset session and clear conversation history
+     */
+    resetSession(): void;
+}
+export {};

package/dist/memory/example.d.ts

@@ -0,0 +1,36 @@
+import { IMemoryStorage, MemoryRecord } from './index';
+declare function example1_basicMemory(db: any, userMemoriesTable: any): Promise<void>;
+declare function example2_memoryAgent(db: any, userMemoriesTable: any): Promise<void>;
+/**
+ * Example custom storage implementation using in-memory Map
+ * In production, this could be Redis, MongoDB, etc.
+ */
+declare class InMemoryStorage implements IMemoryStorage {
+    private memories;
+    private idCounter;
+    insertMemory(userId: string, memoryType: any, content: string, importance: number, metadata?: Record<string, any>): Promise<string>;
+    findMemories(userId: string, query?: string, limit?: number, options?: any): Promise<MemoryRecord[]>;
+    findSimilarMemories(userId: string, content: string, limit?: number): Promise<MemoryRecord[]>;
+    updateMemory(id: string, updates: any): Promise<void>;
+    deleteMemory(id: string): Promise<void>;
+    getMemoryById(id: string): Promise<MemoryRecord | null>;
+    batchUpdateMemories(updates: Array<{
+        id: string;
+        updates: any;
+    }>): Promise<void>;
+}
+declare function example3_customStorage(): Promise<void>;
+declare class MockStorage implements IMemoryStorage {
+    insertCalls: any[];
+    findCalls: any[];
+    insertMemory(...args: any[]): Promise<string>;
+    findMemories(...args: any[]): Promise<MemoryRecord[]>;
+    findSimilarMemories(): Promise<MemoryRecord[]>;
+    updateMemory(): Promise<void>;
+    deleteMemory(): Promise<void>;
+    getMemoryById(): Promise<MemoryRecord | null>;
+    batchUpdateMemories(): Promise<void>;
+}
+declare function example4_testing(): Promise<void>;
+declare function example5_batchOperations(db: any, userMemoriesTable: any): Promise<void>;
+export { example1_basicMemory, example2_memoryAgent, example3_customStorage, example4_testing, example5_batchOperations, InMemoryStorage, MockStorage, };

package/dist/memory/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Memory Management System
+ *
+ * Intelligent long-term memory for AI agents with persistent storage,
+ * vector-based relevance search, and automatic conversation summarization.
+ * Supports in-memory and Drizzle ORM-backed persistence.
+ *
+ * @module memory
+ * @author ai-research-agent contributors
+ */
+export { MemoryAgent } from './agent-memory-manager';
+export type { MemoryAgentOptions } from './agent-memory-manager';
+export { SimpleMemory } from './storage/in-memory-storage';
+export { DrizzleMemoryStorage, createMemorySchema } from './storage/drizzle-storage';
+export type { IMemoryStorage } from './storage/storage-interface';
+export { MEMORY_CONFIG, MEMORY_TYPES, type MemoryType, type MemoryRecord, type Message, type MemorySearchOptions, type MemoryUpdate, type MemoryContextOptions, type MemoryMetrics, type MemoryOptions, type ExtractedFact, } from './types';
+export { MastraMemoryManager, MastraD1MemoryStorage, MastraKVMemoryStorage, createMastraMemory, } from './mastra-integration';
+export type { CloudflareEnv, MastraStorageBackend, MastraMemoryConfig, } from './mastra-integration';