chat-agent-toolkit 1.2.1

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

@@ -0,0 +1,196 @@
+/**
+ * @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 const getModelProvidersUIConfigSection =
+  (): ModelProviderUISection[] => {
+    // Import statically defined metadata instead of loading the providers
+    // This breaks the circular dependency
+    return [
+      {
+        key: "openai",
+        name: "OpenAI",
+        fields: getOpenAIConfigFields(),
+      },
+      {
+        key: "anthropic",
+        name: "Anthropic",
+        fields: getAnthropicConfigFields(),
+      },
+      {
+        key: "gemini",
+        name: "Google Gemini",
+        fields: getGeminiConfigFields(),
+      },
+      {
+        key: "groq",
+        name: "Groq",
+        fields: getGroqConfigFields(),
+      },
+      {
+        key: "deepseek",
+        name: "DeepSeek",
+        fields: getDeepSeekConfigFields(),
+      },
+      {
+        key: "nvidia",
+        name: "NVIDIA",
+        fields: getNvidiaConfigFields(),
+      },
+      {
+        key: "openrouter",
+        name: "OpenRouter",
+        fields: getOpenRouterConfigFields(),
+      },
+    ];
+  };
+
+// Static config field definitions to avoid loading provider classes
+// These match the providerConfigFields in each provider file
+function getOpenAIConfigFields() {
+  return [
+    {
+      type: "password" as const,
+      name: "API Key",
+      key: "apiKey",
+      description: "Your OpenAI API key",
+      required: true,
+      placeholder: "OpenAI API Key",
+      env: "OPENAI_API_KEY",
+      scope: "server" as const,
+    },
+    {
+      type: "string" as const,
+      name: "Base URL",
+      key: "baseURL",
+      description: "The base URL for the OpenAI API",
+      required: true,
+      placeholder: "OpenAI Base URL",
+      default: "https://api.openai.com/v1",
+      env: "OPENAI_BASE_URL",
+      scope: "server" as const,
+    },
+  ];
+}
+
+
+function getAnthropicConfigFields() {
+  return [
+    {
+      type: "password" as const,
+      name: "API Key",
+      key: "apiKey",
+      description: "Your Anthropic API key",
+      required: true,
+      placeholder: "Anthropic API Key",
+      env: "ANTHROPIC_API_KEY",
+      scope: "server" as const,
+    },
+  ];
+}
+
+function getGeminiConfigFields() {
+  return [
+    {
+      type: "password" as const,
+      name: "API Key",
+      key: "apiKey",
+      description: "Your Google Gemini API key",
+      required: true,
+      placeholder: "Google Gemini API Key",
+      env: "GEMINI_API_KEY",
+      scope: "server" as const,
+    },
+  ];
+}
+
+function getGroqConfigFields() {
+  return [
+    {
+      type: "password" as const,
+      name: "API Key",
+      key: "apiKey",
+      description: "Your Groq API key. Free tier includes fast inference on Llama and Mixtral models - get yours at console.groq.com",
+      required: true,
+      placeholder: "gsk_...",
+      env: "GROQ_API_KEY",
+      scope: "server" as const,
+    },
+  ];
+}
+
+function getDeepSeekConfigFields() {
+  return [
+    {
+      type: "password" as const,
+      name: "API Key",
+      key: "apiKey",
+      description: "Your DeepSeek API key",
+      required: true,
+      placeholder: "DeepSeek API Key",
+      env: "DEEPSEEK_API_KEY",
+      scope: "server" as const,
+    },
+  ];
+}
+
+function getNvidiaConfigFields() {
+  return [
+    {
+      type: "password" as const,
+      name: "API Key",
+      key: "apiKey",
+      description: "Your NVIDIA API key. Free tier includes access to Nemotron, Llama, and other models - get yours at build.nvidia.com",
+      required: true,
+      placeholder: "nvapi-...",
+      env: "NVIDIA_API_KEY",
+      scope: "server" as const,
+    },
+    {
+      type: "string" as const,
+      name: "Base URL",
+      key: "baseURL",
+      description: "The base URL for NVIDIA's OpenAI-compatible API",
+      required: true,
+      placeholder: "https://integrate.api.nvidia.com/v1",
+      default: "https://integrate.api.nvidia.com/v1",
+      env: "NVIDIA_BASE_URL",
+      scope: "server" as const,
+    },
+  ];
+}
+
+function getOpenRouterConfigFields() {
+  return [
+    {
+      type: "password" as const,
+      name: "API Key",
+      key: "apiKey",
+      description: "Your OpenRouter API key. Get one free at openrouter.ai - includes free access to Llama 3.3 70B, Nemotron, and other models.",
+      required: true,
+      placeholder: "sk-or-v1-...",
+      env: "OPENROUTER_API_KEY",
+      scope: "server" as const,
+    },
+    {
+      type: "string" as const,
+      name: "Base URL",
+      key: "baseURL",
+      description: "The base URL for OpenRouter's OpenAI-compatible API",
+      required: true,
+      placeholder: "https://openrouter.ai/api/v1",
+      default: "https://openrouter.ai/api/v1",
+      env: "OPENROUTER_BASE_URL",
+      scope: "server" as const,
+    },
+  ];
+}

package/src/connectors/composio.json

@@ -0,0 +1,154 @@
+{
+  "connectors": [
+    {
+      "name": "Gmail",
+      "composio_id": "gmail",
+      "domain": "gmail.com",
+      "description": "Google's email service. Search inboxes, send/reply/draft messages, manage labels and threads."
+    },
+    {
+      "name": "Google Calendar",
+      "composio_id": "googlecalendar",
+      "domain": "calendar.google.com",
+      "description": "Time management and scheduling. Create/update/list events, manage calendars and attendees."
+    },
+    {
+      "name": "Outlook",
+      "composio_id": "outlook",
+      "domain": "outlook.com",
+      "description": "Microsoft's email and calendaring platform. Manage mail, contacts, calendars and rules."
+    },
+    {
+      "name": "Notion",
+      "composio_id": "notion",
+      "domain": "notion.so",
+      "description": "Workspace for docs, wikis and databases. Search, read, create and update pages and database items."
+    },
+    {
+      "name": "Linear",
+      "composio_id": "linear",
+      "domain": "linear.app",
+      "description": "Issue tracking and project management for software teams. Create, query and update issues, projects and cycles."
+    },
+    {
+      "name": "GitHub",
+      "composio_id": "github",
+      "domain": "github.com",
+      "description": "Code hosting and collaboration. Manage repos, issues, pull requests, branches and reviews."
+    },
+    {
+      "name": "Google Drive",
+      "composio_id": "googledrive",
+      "domain": "drive.google.com",
+      "description": "Cloud file storage. Search, upload, share and manage files, folders and permissions."
+    },
+    {
+      "name": "SharePoint",
+      "composio_id": "share_point",
+      "domain": "sharepoint.com",
+      "description": "Microsoft document management and intranet platform. Search and manage sites, lists and files."
+    },
+    {
+      "name": "OneDrive",
+      "composio_id": "one_drive",
+      "domain": "onedrive.live.com",
+      "description": "Microsoft cloud file storage. Upload, share and manage personal/business files and folders."
+    },
+    {
+      "name": "Slack",
+      "composio_id": "slack",
+      "domain": "slack.com",
+      "description": "Channel-based team messaging. Search history, post messages, manage channels and users."
+    },
+    {
+      "name": "Box",
+      "composio_id": "box",
+      "domain": "box.com",
+      "description": "Enterprise cloud content management. Manage files, folders, sharing and collaboration."
+    },
+    {
+      "name": "Dropbox",
+      "composio_id": "dropbox",
+      "domain": "dropbox.com",
+      "description": "Cloud file syncing and sharing. Upload, list, move and share files across devices."
+    },
+    {
+      "name": "HubSpot",
+      "composio_id": "hubspot",
+      "domain": "hubspot.com",
+      "description": "CRM and marketing platform. Manage contacts, companies, deals, tickets and engagements."
+    },
+    {
+      "name": "Jira",
+      "composio_id": "jira",
+      "domain": "atlassian.com",
+      "description": "Atlassian issue and project tracking. Create/search/update tickets, manage sprints and boards."
+    },
+    {
+      "name": "Confluence",
+      "composio_id": "confluence",
+      "domain": "atlassian.com",
+      "description": "Atlassian knowledge base and team wiki. Search, create and edit pages and spaces."
+    },
+    {
+      "name": "Asana",
+      "composio_id": "asana",
+      "domain": "asana.com",
+      "description": "Task and project management. Create/update tasks, projects, sections and assignments."
+    },
+    {
+      "name": "Databricks",
+      "composio_id": "databricks",
+      "domain": "databricks.com",
+      "description": "Unified analytics and lakehouse platform. Run SQL/jobs, manage clusters, notebooks and Unity Catalog."
+    },
+    {
+      "name": "Snowflake",
+      "composio_id": "snowflake",
+      "domain": "snowflake.com",
+      "description": "Cloud data warehouse. Query structured data, manage warehouses, databases and roles."
+    },
+    {
+      "name": "Salesforce",
+      "composio_id": "salesforce",
+      "domain": "salesforce.com",
+      "description": "Enterprise CRM. Manage leads, accounts, opportunities, cases and custom objects."
+    },
+    {
+      "name": "ServiceNow",
+      "composio_id": "servicenow",
+      "domain": "servicenow.com",
+      "description": "IT service management platform. Manage incidents, change requests, knowledge base and CMDB."
+    },
+    {
+      "name": "Microsoft Teams",
+      "composio_id": "microsoft_teams",
+      "domain": "teams.microsoft.com",
+      "description": "Microsoft collaboration platform. Send messages, manage channels, teams and meetings."
+    },
+    {
+      "name": "Zapier",
+      "composio_id": null,
+      "domain": null,
+      "description": "Not available as a Composio toolkit — Zapier is a direct competitor to Composio's integration platform."
+    },
+    {
+      "name": "Make.com",
+      "composio_id": null,
+      "domain": null,
+      "description": "Not available as a Composio toolkit — Make (formerly Integromat) is a direct competitor."
+    },
+    {
+      "name": "Google Workspace",
+      "composio_id": null,
+      "domain": null,
+      "description": "Not a single Composio toolkit. Use the individual Google toolkits instead: gmail, googledrive, googlecalendar, googledocs, googlesheets, etc."
+    },
+    {
+      "name": "Custom Remote MCPs",
+      "composio_id": null,
+      "domain": null,
+      "description": "Not applicable — Composio is itself an MCP gateway. Custom MCPs are handled via Composio's auth-config/integration system or by registering a custom toolkit."
+    }
+  ]
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+/**
+ * @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 { 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/src/memory/ARCHITECTURE.md

@@ -0,0 +1,302 @@
+# Memory Module Architecture
+
+## Overview
+
+The memory system has been refactored from a single monolithic file into a modular, well-abstracted architecture that separates concerns and eliminates direct dependencies on Drizzle ORM.
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         Application Layer                        │
+│                  (Your app using the memory module)              │
+└────────────────────────────┬────────────────────────────────────┘
+                             │
+                             │ imports
+                             ↓
+┌─────────────────────────────────────────────────────────────────┐
+│                         index.ts                                 │
+│                   (Public API exports)                           │
+└────────────────────────────┬────────────────────────────────────┘
+                             │
+         ┌───────────────────┼───────────────────┐
+         │                   │                   │
+         ↓                   ↓                   ↓
+┌─────────────────┐ ┌─────────────────┐ ┌──────────────────┐
+│  memory-agent.ts│ │ simple-memory.ts│ │  types.ts        │
+│                 │ │                 │ │                  │
+│ • Rate limiting │ │ • Message mgmt  │ │ • MemoryRecord   │
+│ • LLM providers │ │ • Caching       │ │ • MEMORY_CONFIG  │
+│ • Chat handling │ │ • Summarization │ │ • MEMORY_TYPES   │
+│ • Analytics     │ │ • Batch ops     │ │ • Interfaces     │
+└────────┬────────┘ └────────┬────────┘ └──────────────────┘
+         │                   │
+         │                   │ uses
+         │                   ↓
+         │          ┌─────────────────────┐
+         │          │ storage-interface.ts│
+         │          │                     │
+         │          │  IMemoryStorage     │
+         │          │  (Abstract Interface)│
+         │          └──────────┬──────────┘
+         │                     │
+         │                     │ implements
+         │                     ↓
+         │          ┌─────────────────────┐
+         └─────────→│ drizzle-storage.ts  │
+                    │                     │
+                    │ DrizzleMemoryStorage│
+                    │ (Concrete Impl)     │
+                    └──────────┬──────────┘
+                               │
+                               │ uses
+                               ↓
+                    ┌─────────────────────┐
+                    │    Drizzle ORM      │
+                    │    (External Dep)   │
+                    └─────────────────────┘
+```
+
+## Component Responsibilities
+
+### 1. **types.ts**
+- **Purpose**: Central type definitions and constants
+- **Exports**:
+  - `MemoryRecord`, `Message`, `MemoryType`
+  - `MEMORY_CONFIG`, `MEMORY_TYPES`
+  - All TypeScript interfaces
+- **Dependencies**: None
+- **Used by**: All other modules
+
+### 2. **storage-interface.ts**
+- **Purpose**: Abstract interface for storage operations
+- **Exports**: `IMemoryStorage` interface
+- **Dependencies**: `types.ts`
+- **Used by**: `simple-memory.ts`, `memory-agent.ts`
+- **Key Methods**:
+  - `insertMemory()`
+  - `findMemories()`
+  - `findSimilarMemories()`
+  - `updateMemory()`
+  - `deleteMemory()`
+  - `batchUpdateMemories()`
+
+### 3. **drizzle-storage.ts**
+- **Purpose**: Drizzle ORM implementation of `IMemoryStorage`
+- **Exports**: `DrizzleMemoryStorage` class
+- **Dependencies**: `drizzle-orm`, `types.ts`, `storage-interface.ts`
+- **Used by**: Application code (when using Drizzle)
+- **Isolation**: This is the ONLY file that imports `drizzle-orm`
+
+### 4. **simple-memory.ts**
+- **Purpose**: Core memory management logic
+- **Exports**: `SimpleMemory` class
+- **Dependencies**: `storage-interface.ts`, `types.ts`, `generateLanguageResponse`
+- **Features**:
+  - Message deduplication
+  - Auto-summarization
+  - Caching (in-memory)
+  - Batch processing
+  - Memory recall with filtering
+
+### 5. **memory-agent.ts**
+- **Purpose**: High-level agent with LLM integration
+- **Exports**: `MemoryAgent` class
+- **Dependencies**: `simple-memory.ts`, `storage-interface.ts`, `types.ts`
+- **Features**:
+  - Rate limiting
+  - Multi-provider LLM support
+  - Chat management
+  - Session tracking
+  - Analytics
+
+### 6. **index.ts**
+- **Purpose**: Public API surface
+- **Exports**: All public classes, interfaces, and types
+- **Role**: Single entry point for consumers
+
+### 7. **memory.ts** (Deprecated)
+- **Purpose**: Backward compatibility
+- **Exports**: Re-exports from `index.ts`
+- **Status**: Deprecated, will be removed in future version
+
+## Data Flow
+
+### Storing a Memory
+```
+Application
+    ↓ memory.storeFact("content", importance, category)
+SimpleMemory
+    ↓ storage.insertMemory(userId, type, content, importance)
+IMemoryStorage (interface)
+    ↓
+DrizzleMemoryStorage
+    ↓ db.insert().values()
+Database
+```
+
+### Recalling Memories
+```
+Application
+    ↓ memory.recallRelevantMemories(query, limit)
+SimpleMemory
+    ↓ Check cache
+    ↓ storage.findMemories(userId, query, limit, options)
+IMemoryStorage (interface)
+    ↓
+DrizzleMemoryStorage
+    ↓ db.select().where().orderBy()
+Database
+    ↓
+SimpleMemory (apply filters, cache results)
+    ↓
+Application
+```
+
+## Benefits of New Architecture
+
+### 1. **Separation of Concerns**
+- Storage logic is isolated from business logic
+- Each file has a single, clear responsibility
+- Easy to understand and maintain
+
+### 2. **Testability**
+```typescript
+// Mock storage for testing
+class MockStorage implements IMemoryStorage {
+  private data = new Map();
+
+  async insertMemory(...) { /* mock */ }
+  async findMemories(...) { /* mock */ }
+  // ...
+}
+
+const memory = new SimpleMemory("user", new MockStorage());
+// Test without database!
+```
+
+### 3. **Flexibility**
+```typescript
+// Can swap implementations easily
+const sqliteStorage = new SQLiteMemoryStorage(db);
+const postgresStorage = new PostgresMemoryStorage(pool);
+const redisStorage = new RedisMemoryStorage(client);
+
+// Same interface, different backends
+const memory = new SimpleMemory("user", sqliteStorage);
+```
+
+### 4. **No Vendor Lock-in**
+- Core logic doesn't depend on Drizzle
+- Can migrate to different ORMs
+- Can use raw SQL if needed
+
+### 5. **Better Dependency Management**
+- Drizzle is only imported in one file
+- Easier to upgrade or replace
+- Smaller bundle size if using tree-shaking
+
+## Migration from Old Structure
+
+### Old (Monolithic)
+```typescript
+import { SimpleMemory } from "./agents/memory/memory";
+
+const memory = new SimpleMemory(userId, db, options);
+```
+
+### New (Modular)
+```typescript
+import { SimpleMemory, DrizzleMemoryStorage } from "./agents/memory";
+
+const storage = new DrizzleMemoryStorage(db);
+const memory = new SimpleMemory(userId, storage, options);
+```
+
+### Key Changes
+1. **Constructor change**: `db` → `storage` (IMemoryStorage)
+2. **Explicit adapter**: Must create storage adapter first
+3. **Better typing**: Full TypeScript support with interfaces
+
+## Design Patterns Used
+
+### 1. **Dependency Injection**
+- `SimpleMemory` receives `IMemoryStorage` via constructor
+- Enables loose coupling and testability
+
+### 2. **Strategy Pattern**
+- `IMemoryStorage` defines the storage strategy interface
+- Different implementations can be swapped at runtime
+
+### 3. **Facade Pattern**
+- `MemoryAgent` provides simple interface to complex subsystems
+- Hides complexity of memory management, LLM calls, rate limiting
+
+### 4. **Repository Pattern**
+- Storage layer acts as repository for memory entities
+- Abstracts data access logic
+
+## Future Extensions
+
+### Adding New Storage Backend
+```typescript
+// 1. Implement IMemoryStorage
+export class MongoMemoryStorage implements IMemoryStorage {
+  constructor(private collection: Collection) {}
+
+  async insertMemory(...) {
+    return await this.collection.insertOne({...});
+  }
+
+  // ... implement other methods
+}
+
+// 2. Use it
+const storage = new MongoMemoryStorage(collection);
+const memory = new SimpleMemory("user", storage);
+```
+
+### Adding New Features to SimpleMemory
+- Modify only `simple-memory.ts`
+- No need to touch storage layer
+- Business logic stays separate
+
+### Replacing Drizzle
+- Create new storage adapter (e.g., `prisma-storage.ts`)
+- Implement `IMemoryStorage` interface
+- Swap at initialization time
+- Core logic remains unchanged
+
+## Performance Considerations
+
+### Caching Layer
+- In-memory cache in `SimpleMemory`
+- Reduces database queries
+- TTL-based expiration
+
+### Batch Operations
+- `batchUpdateMemories()` for bulk updates
+- Reduces round trips to database
+- Better performance for summarization
+
+### Query Optimization
+- Indexed queries in storage layer
+- Limit results to prevent over-fetching
+- Efficient filtering and sorting
+
+## Security Considerations
+
+### Rate Limiting
+- Prevents abuse of memory storage
+- Configurable limits per user
+- Sliding window implementation
+
+### Input Validation
+- Validates all inputs in `SimpleMemory`
+- Prevents injection attacks
+- Sanitizes content before storage
+
+### Access Control
+- User ID-based isolation
+- Each user only sees their memories
+- No cross-user data leakage