@theihtisham/ai-agent-starter-kit 1.0.0

package/src/lib/agents/tools/registry.ts

@@ -0,0 +1,182 @@
+/**
+ * Tool Registry — Dynamic tool registration and execution.
+ *
+ * Provides a centralized registry for managing agent tools.
+ * Tools can be registered, unregistered, listed, and executed dynamically.
+ */
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  parameters: Record<
+    string,
+    {
+      type: string;
+      description: string;
+      required?: boolean;
+      enum?: string[];
+      default?: unknown;
+    }
+  >;
+  handler: (params: Record<string, unknown>) => Promise<string>;
+}
+
+export interface ToolExecutionResult {
+  success: boolean;
+  result: string;
+  durationMs: number;
+  error?: string;
+}
+
+export class ToolRegistry {
+  private tools: Map<string, ToolDefinition> = new Map();
+
+  /** Register a new tool */
+  register(tool: ToolDefinition): void {
+    if (this.tools.has(tool.name)) {
+      throw new Error(
+        `Tool "${tool.name}" is already registered. Unregister it first or use a different name.`,
+      );
+    }
+    this.tools.set(tool.name, tool);
+  }
+
+  /** Unregister a tool by name */
+  unregister(name: string): boolean {
+    return this.tools.delete(name);
+  }
+
+  /** Get a tool definition by name */
+  get(name: string): ToolDefinition | undefined {
+    return this.tools.get(name);
+  }
+
+  /** Check if a tool is registered */
+  has(name: string): boolean {
+    return this.tools.has(name);
+  }
+
+  /** List all registered tools */
+  list(): ToolDefinition[] {
+    return Array.from(this.tools.values());
+  }
+
+  /** List tool names only */
+  listNames(): string[] {
+    return Array.from(this.tools.keys());
+  }
+
+  /**
+   * Execute a tool by name with the given parameters.
+   * Returns a structured result with timing and error info.
+   */
+  async execute(name: string, params: Record<string, unknown>): Promise<ToolExecutionResult> {
+    const startTime = Date.now();
+    const tool = this.tools.get(name);
+
+    if (!tool) {
+      return {
+        success: false,
+        result: '',
+        durationMs: Date.now() - startTime,
+        error: `Tool "${name}" not found. Available: ${this.listNames().join(', ')}`,
+      };
+    }
+
+    // Validate required parameters
+    for (const [paramName, paramDef] of Object.entries(tool.parameters)) {
+      if (paramDef.required && (params[paramName] === undefined || params[paramName] === null)) {
+        return {
+          success: false,
+          result: '',
+          durationMs: Date.now() - startTime,
+          error: `Missing required parameter "${paramName}" for tool "${name}"`,
+        };
+      }
+    }
+
+    // Apply defaults for missing optional parameters
+    const fullParams: Record<string, unknown> = { ...params };
+    for (const [paramName, paramDef] of Object.entries(tool.parameters)) {
+      if (fullParams[paramName] === undefined && paramDef.default !== undefined) {
+        fullParams[paramName] = paramDef.default;
+      }
+    }
+
+    try {
+      const result = await tool.handler(fullParams);
+      return {
+        success: true,
+        result,
+        durationMs: Date.now() - startTime,
+      };
+    } catch (err) {
+      return {
+        success: false,
+        result: '',
+        durationMs: Date.now() - startTime,
+        error: `Tool "${name}" execution error: ${(err as Error).message}`,
+      };
+    }
+  }
+
+  /**
+   * Get the tool definitions in OpenAI function-calling format.
+   */
+  toOpenAITools(): Array<{
+    type: 'function';
+    function: {
+      name: string;
+      description: string;
+      parameters: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required: string[];
+      };
+    };
+  }> {
+    return Array.from(this.tools.values()).map((tool) => ({
+      type: 'function' as const,
+      function: {
+        name: tool.name,
+        description: tool.description,
+        parameters: {
+          type: 'object' as const,
+          properties: Object.fromEntries(
+            Object.entries(tool.parameters).map(([key, def]) => [
+              key,
+              {
+                type: def.type,
+                description: def.description,
+                ...(def.enum ? { enum: def.enum } : {}),
+              },
+            ]),
+          ),
+          required: Object.entries(tool.parameters)
+            .filter(([, def]) => def.required)
+            .map(([key]) => key),
+        },
+      },
+    }));
+  }
+
+  /** Clear all registered tools */
+  clear(): void {
+    this.tools.clear();
+  }
+
+  /** Get the number of registered tools */
+  get count(): number {
+    return this.tools.size;
+  }
+}
+
+/** Global singleton registry instance */
+let globalRegistry: ToolRegistry | undefined;
+
+export function getGlobalRegistry(): ToolRegistry {
+  if (!globalRegistry) {
+    globalRegistry = new ToolRegistry();
+  }
+  return globalRegistry;
+}

package/src/lib/agents/tools/web-search.ts

@@ -0,0 +1,83 @@
+/**
+ * Web Search Tool — Mock implementation returning structured results.
+ *
+ * In production, replace the handler with a real search API call
+ * (SearXNG, SerpAPI, Google Custom Search, Tavily, etc.)
+ */
+
+import type { ToolDefinition } from './registry';
+
+export interface SearchResult {
+  title: string;
+  url: string;
+  snippet: string;
+  relevanceScore: number;
+}
+
+export const webSearchTool: ToolDefinition = {
+  name: 'web_search',
+  description:
+    'Search the web for information. Returns structured results with titles, URLs, and snippets.',
+  parameters: {
+    query: {
+      type: 'string',
+      description: 'Search query string',
+      required: true,
+    },
+    max_results: {
+      type: 'number',
+      description: 'Maximum number of results to return (1-10)',
+      required: false,
+      default: 5,
+    },
+  },
+  handler: async (params): Promise<string> => {
+    const query = params.query as string;
+    const maxResults = Math.min(Math.max((params.max_results as number) ?? 5, 1), 10);
+
+    // Mock search results — replace with real API in production
+    const mockResults: SearchResult[] = generateMockResults(query, maxResults);
+
+    return formatSearchResults(query, mockResults);
+  },
+};
+
+function generateMockResults(query: string, count: number): SearchResult[] {
+  const results: SearchResult[] = [];
+  const terms = query.split(/\s+/);
+
+  for (let i = 0; i < count; i++) {
+    const term = terms[i % terms.length] ?? query;
+    results.push({
+      title: `${capitalize(query)} — Result ${i + 1}`,
+      url: `https://example.com/search?q=${encodeURIComponent(query)}&result=${i + 1}`,
+      snippet: `This is a mock search result for "${term}". In production, this would contain a real snippet from the web page. Configure your search provider (SearXNG, SerpAPI, or Tavily) to get real results.`,
+      relevanceScore: 1 - i * 0.1,
+    });
+  }
+
+  return results;
+}
+
+function formatSearchResults(query: string, results: SearchResult[]): string {
+  const lines = [`Search results for "${query}":`, ''];
+
+  for (const result of results) {
+    lines.push(`**${result.title}**`);
+    lines.push(`URL: ${result.url}`);
+    lines.push(`${result.snippet}`);
+    lines.push('');
+  }
+
+  lines.push('---');
+  lines.push(`Found ${results.length} results.`);
+
+  return lines.join('\n');
+}
+
+function capitalize(str: string): string {
+  return str
+    .split(' ')
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+}

package/src/lib/ai/agent.ts

@@ -0,0 +1,275 @@
+import OpenAI from 'openai';
+import type { Message } from '@prisma/client';
+import { buildChatContext, estimateTokens } from './context';
+import { createSSEStream } from './streaming';
+import { getToolsByIds, type ToolDefinition } from './tools';
+import { logger } from '../utils/logger';
+
+export interface AgentConfig {
+  model: string;
+  systemPrompt: string;
+  temperature: number;
+  maxTokens: number;
+  toolIds: string[];
+  apiKey?: string;
+  apiBase?: string;
+}
+
+export interface ChatResult {
+  content: string;
+  inputTokens: number;
+  outputTokens: number;
+  toolCalls: number;
+}
+
+/**
+ * Core AI Agent Engine.
+ * Supports OpenAI-compatible APIs (OpenAI, local models, etc.)
+ */
+export class AgentEngine {
+  private config: AgentConfig;
+  private client: OpenAI;
+  private tools: ToolDefinition[];
+
+  constructor(config: AgentConfig) {
+    this.config = config;
+    this.client = new OpenAI({
+      apiKey: config.apiKey ?? process.env.OPENAI_API_KEY ?? '',
+      baseURL: config.apiBase ?? 'https://api.openai.com/v1',
+    });
+    this.tools = getToolsByIds(config.toolIds);
+  }
+
+  /**
+   * Non-streaming chat — returns complete response
+   */
+  async chat(history: Message[], userMessage: string): Promise<ChatResult> {
+    const context = buildChatContext({
+      systemPrompt: this.config.systemPrompt,
+      history,
+      newMessage: userMessage,
+      maxTokens: this.config.maxTokens,
+    });
+
+    const messages: OpenAI.ChatCompletionMessageParam[] = context as unknown as OpenAI.ChatCompletionMessageParam[];
+    const openaiTools = this.tools.length > 0 ? this.buildOpenAITools() : undefined;
+
+    let totalInputTokens = estimateTokens(context.map((m) => m.content).join(''));
+    let totalOutputTokens = 0;
+    let toolCallCount = 0;
+    let finalContent = '';
+
+    // Conversation loop with tool calling (max 5 rounds)
+    for (let round = 0; round < 5; round++) {
+      const response = await this.client.chat.completions.create({
+        model: this.config.model,
+        messages,
+        temperature: this.config.temperature,
+        max_tokens: Math.min(this.config.maxTokens, 4096),
+        tools: openaiTools,
+        stream: false,
+      });
+
+      const choice = response.choices[0];
+      if (!choice) throw new Error('No response choice from AI');
+
+      const assistantMessage = choice.message;
+      totalOutputTokens += response.usage?.completion_tokens ?? 0;
+      totalInputTokens = Math.max(totalInputTokens, response.usage?.prompt_tokens ?? 0);
+
+      // Handle tool calls
+      if (assistantMessage.tool_calls && assistantMessage.tool_calls.length > 0) {
+        toolCallCount += assistantMessage.tool_calls.length;
+        messages.push({
+          role: 'assistant',
+          content: assistantMessage.content ?? '',
+          tool_calls: assistantMessage.tool_calls,
+        });
+
+        for (const toolCall of assistantMessage.tool_calls) {
+          const toolResult = await this.executeToolCall(toolCall);
+          messages.push({
+            role: 'tool',
+            content: toolResult,
+            tool_call_id: toolCall.id,
+          });
+        }
+        continue;
+      }
+
+      // No tool calls — we have our final answer
+      finalContent = assistantMessage.content ?? '';
+      break;
+    }
+
+    return {
+      content: finalContent,
+      inputTokens: totalInputTokens,
+      outputTokens: totalOutputTokens,
+      toolCalls: toolCallCount,
+    };
+  }
+
+  /**
+   * Streaming chat — returns ReadableStream for SSE
+   */
+  async chatStream(history: Message[], userMessage: string): Promise<{
+    stream: ReadableStream<Uint8Array>;
+    getResult: () => Promise<ChatResult>;
+  }> {
+    const context = buildChatContext({
+      systemPrompt: this.config.systemPrompt,
+      history,
+      newMessage: userMessage,
+      maxTokens: this.config.maxTokens,
+    });
+
+    const messages: OpenAI.ChatCompletionMessageParam[] = context as unknown as OpenAI.ChatCompletionMessageParam[];
+    const openaiTools = this.tools.length > 0 ? this.buildOpenAITools() : undefined;
+    const sse = createSSEStream();
+
+    let totalInputTokens = estimateTokens(context.map((m) => m.content).join(''));
+    let totalOutputTokens = 0;
+    let toolCallCount = 0;
+    let finalContent = '';
+
+    const resultPromise = (async (): Promise<ChatResult> => {
+      try {
+        for (let round = 0; round < 5; round++) {
+          const stream = await this.client.chat.completions.create({
+            model: this.config.model,
+            messages,
+            temperature: this.config.temperature,
+            max_tokens: Math.min(this.config.maxTokens, 4096),
+            tools: openaiTools,
+            stream: true,
+          });
+
+          let currentContent = '';
+          let currentToolCalls: OpenAI.ChatCompletionMessageToolCall[] = [];
+
+          for await (const chunk of stream) {
+            const delta = chunk.choices[0]?.delta;
+            if (!delta) continue;
+
+            // Text content
+            if (delta.content) {
+              currentContent += delta.content;
+              sse.send({ type: 'text', content: delta.content });
+            }
+
+            // Tool calls
+            if (delta.tool_calls) {
+              for (const tc of delta.tool_calls) {
+                const idx = tc.index ?? 0;
+                if (!currentToolCalls[idx]) {
+                  currentToolCalls[idx] = {
+                    id: tc.id ?? '',
+                    type: 'function',
+                    function: { name: '', arguments: '' },
+                  };
+                }
+                if (tc.id) currentToolCalls[idx].id = tc.id;
+                if (tc.function?.name) currentToolCalls[idx].function.name += tc.function.name;
+                if (tc.function?.arguments) currentToolCalls[idx].function.arguments += tc.function.arguments;
+              }
+            }
+
+            totalOutputTokens++;
+          }
+
+          // Handle tool calls
+          if (currentToolCalls.length > 0) {
+            toolCallCount += currentToolCalls.length;
+            messages.push({
+              role: 'assistant',
+              content: currentContent || null,
+              tool_calls: currentToolCalls,
+            });
+
+            for (const toolCall of currentToolCalls) {
+              sse.send({
+                type: 'tool_call',
+                content: toolCall.function.name,
+                metadata: { id: toolCall.id },
+              });
+
+              const toolResult = await this.executeToolCall(toolCall);
+              sse.send({
+                type: 'tool_result',
+                content: toolResult.slice(0, 500),
+                metadata: { toolCallId: toolCall.id },
+              });
+
+              messages.push({
+                role: 'tool',
+                content: toolResult,
+                tool_call_id: toolCall.id,
+              });
+            }
+            continue;
+          }
+
+          // No tool calls — final answer
+          finalContent = currentContent;
+          break;
+        }
+      } catch (err) {
+        logger.error('Agent streaming error', { error: (err as Error).message });
+        sse.send({ type: 'error', content: (err as Error).message });
+      } finally {
+        sse.close();
+      }
+
+      return {
+        content: finalContent,
+        inputTokens: totalInputTokens,
+        outputTokens: totalOutputTokens,
+        toolCalls: toolCallCount,
+      };
+    })();
+
+    return {
+      stream: sse.stream,
+      getResult: () => resultPromise,
+    };
+  }
+
+  private buildOpenAITools(): OpenAI.ChatCompletionTool[] {
+    return this.tools.map((tool) => ({
+      type: 'function' as const,
+      function: {
+        name: tool.id,
+        description: tool.description,
+        parameters: {
+          type: 'object',
+          properties: tool.parameters,
+          required: Object.entries(tool.parameters)
+            .filter(([, config]) => config.required)
+            .map(([key]) => key),
+        },
+      },
+    }));
+  }
+
+  private async executeToolCall(
+    toolCall: OpenAI.ChatCompletionMessageToolCall,
+  ): Promise<string> {
+    const toolId = toolCall.function.name;
+    const tool = this.tools.find((t) => t.id === toolId);
+
+    if (!tool) {
+      return `Tool "${toolId}" not found. Available tools: ${this.tools.map((t) => t.id).join(', ')}`;
+    }
+
+    try {
+      const params = JSON.parse(toolCall.function.arguments || '{}');
+      logger.info('Executing tool', { tool: toolId, params });
+      const result = await tool.handler(params);
+      return result;
+    } catch (err) {
+      logger.error('Tool execution error', { tool: toolId, error: (err as Error).message });
+      return `Tool execution error: ${(err as Error).message}`;
+    }
+  }
+}

package/src/lib/ai/context.ts

@@ -0,0 +1,68 @@
+import type { Message } from '@prisma/client';
+
+const DEFAULT_MAX_CONTEXT_TOKENS = 100000;
+
+/**
+ * Rough token estimation: ~4 chars per token for English text
+ */
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+/**
+ * Trim conversation history to fit within the model's context window.
+ * Keeps the system prompt + most recent messages that fit within the budget.
+ */
+export function trimHistory(
+  messages: Message[],
+  systemPrompt: string,
+  maxContextTokens: number = DEFAULT_MAX_CONTEXT_TOKENS,
+  reservedForResponse: number = 4096,
+): Message[] {
+  const budget = maxContextTokens - reservedForResponse;
+  const systemTokens = estimateTokens(systemPrompt);
+  let remaining = budget - systemTokens;
+
+  if (remaining <= 0) return [];
+
+  // Work backwards from most recent messages
+  const selected: Message[] = [];
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (!msg) break;
+    const msgTokens = estimateTokens(msg.content);
+    if (msgTokens > remaining) break;
+    remaining -= msgTokens;
+    selected.unshift(msg);
+  }
+
+  return selected;
+}
+
+/**
+ * Build the full context for an AI request
+ */
+export function buildChatContext(params: {
+  systemPrompt: string;
+  history: Message[];
+  newMessage: string;
+  maxTokens: number;
+}): Array<{ role: 'system' | 'user' | 'assistant' | 'tool'; content: string }> {
+  const { systemPrompt, history, newMessage, maxTokens } = params;
+  const trimmed = trimHistory(history, systemPrompt, maxTokens);
+
+  const messages: Array<{ role: 'system' | 'user' | 'assistant' | 'tool'; content: string }> = [];
+
+  // System prompt first
+  messages.push({ role: 'system', content: systemPrompt });
+
+  // Then trimmed history
+  for (const msg of trimmed) {
+    messages.push({ role: msg.role as 'system' | 'user' | 'assistant' | 'tool', content: msg.content });
+  }
+
+  // Then the new user message
+  messages.push({ role: 'user', content: newMessage });
+
+  return messages;
+}

package/src/lib/ai/memory.ts

@@ -0,0 +1,98 @@
+import prisma from '../db/client';
+import { logger } from '../utils/logger';
+
+export interface ConversationMemory {
+  agentId: string;
+  userId: string;
+  maxHistoryMessages: number;
+}
+
+/**
+ * Load conversation history for an agent chat.
+ */
+export async function loadHistory(chatId: string, limit: number = 50) {
+  const messages = await prisma.message.findMany({
+    where: { chatId },
+    orderBy: { createdAt: 'asc' },
+    take: limit,
+  });
+
+  return messages;
+}
+
+/**
+ * Save a message to the conversation.
+ */
+export async function saveMessage(
+  chatId: string,
+  role: 'user' | 'assistant' | 'system' | 'tool',
+  content: string,
+  metadata?: Record<string, unknown>,
+) {
+  const message = await prisma.message.create({
+    data: {
+      chatId,
+      role,
+      content,
+      metadata: metadata ? (metadata as never) : undefined,
+    },
+  });
+
+  logger.debug('Message saved', { chatId, role, messageId: message.id });
+  return message;
+}
+
+/**
+ * Create a new chat for an agent.
+ */
+export async function createChat(agentId: string, _userId: string, title: string) {
+  return prisma.chat.create({
+    data: {
+      agentId,
+      title,
+    },
+  });
+}
+
+/**
+ * Get or create a chat session for ad-hoc conversations.
+ */
+export async function getOrCreateChat(agentId: string, _userId: string, title?: string) {
+  const existing = await prisma.chat.findFirst({
+    where: { agentId },
+    orderBy: { updatedAt: 'desc' },
+  });
+
+  if (existing) return existing;
+
+  return createChat(agentId, _userId, title ?? 'New Chat');
+}
+
+/**
+ * Get all chats for an agent.
+ */
+export async function getChatsForAgent(agentId: string, _userId: string) {
+  return prisma.chat.findMany({
+    where: { agentId },
+    orderBy: { updatedAt: 'desc' },
+    include: {
+      _count: { select: { messages: true } },
+    },
+  });
+}
+
+/**
+ * Delete a chat and all its messages.
+ */
+export async function deleteChat(chatId: string, _userId: string) {
+  const chat = await prisma.chat.findFirst({
+    where: { id: chatId },
+  });
+
+  if (!chat) return false;
+
+  await prisma.message.deleteMany({ where: { chatId } });
+  await prisma.chat.delete({ where: { id: chatId } });
+
+  return true;
+}