@revealui/ai 0.1.0

package/dist/tools/cms/media-tools.js

@@ -0,0 +1,140 @@
+/**
+ * CMS Media Tools
+ * Tools for managing media files (images, videos, documents)
+ */
+import { z } from 'zod/v4';
+/**
+ * Tool: List media files
+ * Browse the media library
+ */
+export const listMediaTool = {
+    name: 'list_media',
+    description: 'Get a list of media files from the CMS media library. Use this to browse uploaded images, videos, and documents.',
+    parameters: z.object({
+        page: z.number().optional().describe('Page number for pagination (default: 1)'),
+        limit: z.number().optional().describe('Number of results per page (default: 10)'),
+        mimeType: z
+            .string()
+            .optional()
+            .describe('Filter by MIME type (e.g., "image/jpeg", "image/png", "video/mp4")'),
+    }),
+    async execute(params) {
+        const { page: _page = 1, limit: _limit = 10, mimeType: _mimeType, } = params;
+        try {
+            // API client will be injected at runtime
+            // This will use the collection tools to query the media collection
+            throw new Error('API client not configured. This tool must be registered with an API client instance.');
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: `Failed to list media: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    },
+};
+/**
+ * Tool: Get media by ID
+ * Retrieve a specific media file
+ */
+export const getMediaTool = {
+    name: 'get_media',
+    description: 'Get details of a specific media file by ID, including URL, filename, and metadata.',
+    parameters: z.object({
+        id: z.string().describe('The media file ID'),
+    }),
+    async execute(params) {
+        const { id: _id } = params;
+        try {
+            // API client will be injected at runtime
+            throw new Error('API client not configured. This tool must be registered with an API client instance.');
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: `Failed to get media: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    },
+};
+/**
+ * Tool: Upload media
+ * Upload a new media file
+ */
+export const uploadMediaTool = {
+    name: 'upload_media',
+    description: 'Upload a new media file (image, video, or document) to the CMS. The file should be provided as a base64-encoded string.',
+    parameters: z.object({
+        filename: z.string().describe('The filename (e.g., "logo.png")'),
+        mimeType: z.string().describe('The MIME type (e.g., "image/png", "image/jpeg")'),
+        data: z
+            .string()
+            .describe('The file content as a base64-encoded string or data URL (data:image/png;base64,...)'),
+        alt: z.string().optional().describe('Alt text for accessibility (recommended for images)'),
+    }),
+    async execute(params) {
+        const { filename: _filename, mimeType: _mimeType, data: _data, alt: _alt, } = params;
+        try {
+            // API client will be injected at runtime
+            // This will handle file upload to storage and create media document
+            throw new Error('API client not configured. This tool must be registered with an API client instance.');
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: `Failed to upload media: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    },
+};
+/**
+ * Tool: Delete media
+ * Remove a media file from the library
+ */
+export const deleteMediaTool = {
+    name: 'delete_media',
+    description: 'Delete a media file from the CMS media library. This removes both the database record and the file from storage. This action is permanent.',
+    parameters: z.object({
+        id: z.string().describe('The media file ID to delete'),
+    }),
+    async execute(params) {
+        const { id: _id } = params;
+        try {
+            // API client will be injected at runtime
+            throw new Error('API client not configured. This tool must be registered with an API client instance.');
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: `Failed to delete media: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    },
+};
+/**
+ * Tool: Update media metadata
+ * Update media file metadata (alt text, title, etc.)
+ */
+export const updateMediaTool = {
+    name: 'update_media',
+    description: 'Update metadata for a media file such as alt text, title, or description. Does not change the actual file.',
+    parameters: z.object({
+        id: z.string().describe('The media file ID'),
+        alt: z.string().optional().describe('Alt text for accessibility'),
+        title: z.string().optional().describe('Title/name of the media'),
+        description: z.string().optional().describe('Description of the media content'),
+    }),
+    async execute(params) {
+        const { id: _id, alt: _alt, title: _title, description: _description, } = params;
+        try {
+            // API client will be injected at runtime
+            throw new Error('API client not configured. This tool must be registered with an API client instance.');
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: `Failed to update media: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    },
+};

package/dist/tools/cms/user-tools.d.ts

@@ -0,0 +1,31 @@
+/**
+ * CMS User Tools
+ * Tools for user management and authentication
+ */
+import type { Tool } from '../base.js';
+/**
+ * Tool: Get current user
+ * Retrieve information about the logged-in user
+ */
+export declare const getCurrentUserTool: Tool;
+/**
+ * Tool: List users
+ * Get all users (admin only)
+ */
+export declare const listUsersTool: Tool;
+/**
+ * Tool: Create user
+ * Create a new user account
+ */
+export declare const createUserTool: Tool;
+/**
+ * Tool: Update user
+ * Update user account information
+ */
+export declare const updateUserTool: Tool;
+/**
+ * Tool: Delete user
+ * Remove a user account
+ */
+export declare const deleteUserTool: Tool;
+//# sourceMappingURL=user-tools.d.ts.map

package/dist/tools/cms/user-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-tools.d.ts","sourceRoot":"","sources":["../../../src/tools/cms/user-tools.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,YAAY,CAAA;AAElD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,IAoBhC,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,IAiC3B,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,IAsC5B,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,IAsC5B,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,IAuB5B,CAAA"}

package/dist/tools/cms/user-tools.js

@@ -0,0 +1,135 @@
+/**
+ * CMS User Tools
+ * Tools for user management and authentication
+ */
+import { z } from 'zod/v4';
+/**
+ * Tool: Get current user
+ * Retrieve information about the logged-in user
+ */
+export const getCurrentUserTool = {
+    name: 'get_current_user',
+    description: 'Get information about the currently logged-in user, including their role, email, and permissions.',
+    parameters: z.object({}),
+    async execute() {
+        try {
+            // API client will be injected at runtime
+            // This will check auth token and return user data
+            throw new Error('API client not configured. This tool must be registered with an API client instance.');
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: `Failed to get current user: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    },
+};
+/**
+ * Tool: List users
+ * Get all users (admin only)
+ */
+export const listUsersTool = {
+    name: 'list_users',
+    description: 'Get a list of all users in the system. This is typically restricted to admin users only.',
+    parameters: z.object({
+        page: z.number().optional().describe('Page number for pagination (default: 1)'),
+        limit: z.number().optional().describe('Number of results per page (default: 10)'),
+        role: z.string().optional().describe('Filter by user role (e.g., "admin", "editor", "user")'),
+    }),
+    async execute(params) {
+        const { page: _page = 1, limit: _limit = 10, role: _role, } = params;
+        try {
+            // API client will be injected at runtime
+            throw new Error('API client not configured. This tool must be registered with an API client instance.');
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: `Failed to list users: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    },
+};
+/**
+ * Tool: Create user
+ * Create a new user account
+ */
+export const createUserTool = {
+    name: 'create_user',
+    description: 'Create a new user account. Typically requires admin permissions.',
+    parameters: z.object({
+        email: z.string().email().describe('User email address'),
+        password: z.string().min(8).describe('User password (minimum 8 characters)'),
+        name: z.string().optional().describe('User full name'),
+        role: z
+            .string()
+            .optional()
+            .describe('User role (e.g., "admin", "editor", "user"). Defaults to "user"'),
+    }),
+    async execute(params) {
+        const { email: _email, password: _password, name: _name, role: _role, } = params;
+        try {
+            // API client will be injected at runtime
+            throw new Error('API client not configured. This tool must be registered with an API client instance.');
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: `Failed to create user: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    },
+};
+/**
+ * Tool: Update user
+ * Update user account information
+ */
+export const updateUserTool = {
+    name: 'update_user',
+    description: 'Update a user account. Users can update their own account, admins can update any.',
+    parameters: z.object({
+        id: z.string().describe('User ID to update'),
+        email: z.string().email().optional().describe('New email address'),
+        name: z.string().optional().describe('New full name'),
+        role: z.string().optional().describe('New role (admin only)'),
+        password: z.string().min(8).optional().describe('New password'),
+    }),
+    async execute(params) {
+        const { id: _id, email: _email, name: _name, role: _role, password: _password, } = params;
+        try {
+            // API client will be injected at runtime
+            throw new Error('API client not configured. This tool must be registered with an API client instance.');
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: `Failed to update user: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    },
+};
+/**
+ * Tool: Delete user
+ * Remove a user account
+ */
+export const deleteUserTool = {
+    name: 'delete_user',
+    description: 'Delete a user account. Typically requires admin permissions. This action is permanent.',
+    parameters: z.object({
+        id: z.string().describe('User ID to delete'),
+    }),
+    async execute(params) {
+        const { id: _id } = params;
+        try {
+            // API client will be injected at runtime
+            throw new Error('API client not configured. This tool must be registered with an API client instance.');
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: `Failed to delete user: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    },
+};

package/dist/tools/deduplicator.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Tool Call Deduplicator
+ *
+ * Prevents redundant tool invocations within a single agent run.
+ * Key: deterministic hash of (toolName, sorted params JSON).
+ *
+ * AnythingLLM lesson: without deduplication, an agent in a loop will
+ * make the same web scrape or DB query dozens of times per response cycle.
+ */
+import type { ToolResult } from './base.js';
+export declare class ToolCallDeduplicator {
+    private cache;
+    isDuplicate(toolName: string, params: unknown): boolean;
+    getResult(toolName: string, params: unknown): ToolResult | undefined;
+    record(toolName: string, params: unknown, result: ToolResult): void;
+    clear(): void;
+    get size(): number;
+}
+//# sourceMappingURL=deduplicator.d.ts.map

package/dist/tools/deduplicator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deduplicator.d.ts","sourceRoot":"","sources":["../../src/tools/deduplicator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AA8B3C,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,KAAK,CAAqC;IAElD,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO;IAIvD,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS;IAIpE,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI;IAInE,KAAK,IAAI,IAAI;IAIb,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/tools/deduplicator.js

@@ -0,0 +1,53 @@
+/**
+ * Tool Call Deduplicator
+ *
+ * Prevents redundant tool invocations within a single agent run.
+ * Key: deterministic hash of (toolName, sorted params JSON).
+ *
+ * AnythingLLM lesson: without deduplication, an agent in a loop will
+ * make the same web scrape or DB query dozens of times per response cycle.
+ */
+function stableStringify(obj) {
+    if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
+        return JSON.stringify(obj);
+    }
+    const record = obj;
+    const sorted = Object.keys(record)
+        .sort()
+        .reduce((acc, k) => {
+        acc[k] = record[k];
+        return acc;
+    }, {});
+    return JSON.stringify(sorted);
+}
+/**
+ * Compute a stable cache key for a (toolName, params) pair.
+ * Uses a simple djb2-style hash — no crypto dep required.
+ */
+function hashKey(toolName, params) {
+    const raw = `${toolName}::${stableStringify(params)}`;
+    // djb2 hash
+    let hash = 5381;
+    for (let i = 0; i < raw.length; i++) {
+        hash = ((hash << 5) + hash + (raw.charCodeAt(i) | 0)) >>> 0;
+    }
+    return hash.toString(16);
+}
+export class ToolCallDeduplicator {
+    cache = new Map();
+    isDuplicate(toolName, params) {
+        return this.cache.has(hashKey(toolName, params));
+    }
+    getResult(toolName, params) {
+        return this.cache.get(hashKey(toolName, params));
+    }
+    record(toolName, params, result) {
+        this.cache.set(hashKey(toolName, params), result);
+    }
+    clear() {
+        this.cache.clear();
+    }
+    get size() {
+        return this.cache.size;
+    }
+}

package/dist/tools/document-summarizer.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Document Summarizer Tool
+ *
+ * Fetches all chunks for a RAG document and either returns them directly
+ * (if short enough) or asks the LLM for a summary.
+ */
+import type { Database } from '@revealui/db/client';
+import type { LLMClient } from '../llm/client.js';
+import type { Tool } from './base.js';
+export declare function createDocumentSummarizerTool(_db: Database, llmClient: LLMClient): Tool;
+//# sourceMappingURL=document-summarizer.d.ts.map

package/dist/tools/document-summarizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-summarizer.d.ts","sourceRoot":"","sources":["../../src/tools/document-summarizer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAGnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,WAAW,CAAA;AAUjD,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,GAAG,IAAI,CA8EtF"}

package/dist/tools/document-summarizer.js

@@ -0,0 +1,82 @@
+/**
+ * Document Summarizer Tool
+ *
+ * Fetches all chunks for a RAG document and either returns them directly
+ * (if short enough) or asks the LLM for a summary.
+ */
+import { z } from 'zod/v4';
+import { RagVectorService } from '../ingestion/rag-vector-service.js';
+const SummarizerParams = z.object({
+    documentId: z.string().min(1),
+    focusQuestion: z.string().optional(),
+});
+const SHORT_DOCUMENT_TOKENS = 4000;
+const CHARS_PER_TOKEN = 4;
+export function createDocumentSummarizerTool(_db, llmClient) {
+    const vectorService = new RagVectorService();
+    return {
+        name: 'document_summarize',
+        description: 'Summarize a RAG document by ID. Optionally focus the summary on a specific question. Use when a web_scrape result was truncated.',
+        parameters: SummarizerParams,
+        async execute(params) {
+            const start = Date.now();
+            const parsed = SummarizerParams.safeParse(params);
+            if (!parsed.success) {
+                return { success: false, error: `Invalid parameters: ${parsed.error.message}` };
+            }
+            const { documentId, focusQuestion } = parsed.data;
+            try {
+                const chunks = await vectorService.getChunksByDocument(documentId);
+                if (chunks.length === 0) {
+                    return { success: false, error: `Document "${documentId}" not found or has no chunks` };
+                }
+                const fullContent = chunks.map((c) => c.content).join('\n\n');
+                const estimatedTokens = Math.ceil(fullContent.length / CHARS_PER_TOKEN);
+                // Short document — return directly without LLM call
+                if (estimatedTokens <= SHORT_DOCUMENT_TOKENS) {
+                    return {
+                        success: true,
+                        data: {
+                            documentId,
+                            summary: fullContent,
+                            wordCount: fullContent.split(/\s+/).filter((w) => w.length > 0).length,
+                            summarized: false,
+                        },
+                        metadata: { executionTime: Date.now() - start },
+                    };
+                }
+                // Long document — summarize with LLM
+                const focusInstruction = focusQuestion
+                    ? `Focus especially on answering: "${focusQuestion}"`
+                    : '';
+                const response = await llmClient.chat([
+                    {
+                        role: 'system',
+                        content: `Summarize the following document, preserving key facts, figures, and conclusions. ${focusInstruction}`.trim(),
+                    },
+                    { role: 'user', content: fullContent },
+                ]);
+                return {
+                    success: true,
+                    data: {
+                        documentId,
+                        summary: response.content,
+                        wordCount: response.content.split(/\s+/).filter((w) => w.length > 0).length,
+                        summarized: true,
+                        chunkCount: chunks.length,
+                    },
+                    metadata: {
+                        executionTime: Date.now() - start,
+                        tokensUsed: response.usage?.totalTokens,
+                    },
+                };
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        },
+    };
+}

package/dist/tools/mcp-adapter.d.ts

@@ -0,0 +1,66 @@
+/**
+ * MCP Tool Adapter
+ *
+ * Bridges MCP (Model Context Protocol) servers to the tool system
+ */
+import type { Tool } from './base.js';
+export interface MCPTool {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+export interface MCPClient {
+    listTools(): Promise<MCPTool[]>;
+    callTool(name: string, args: unknown): Promise<unknown>;
+}
+/**
+ * Interface for an MCP tool source (e.g. MCPHypervisor from @revealui/mcp).
+ * Using an interface here keeps @revealui/ai decoupled from @revealui/mcp.
+ */
+export interface MCPToolSource {
+    getAllTools(): Array<{
+        namespacedName: string;
+        serverName: string;
+        tool: MCPTool;
+    }>;
+    callTool(serverName: string, toolName: string, args: unknown): Promise<unknown>;
+}
+/**
+ * Create a Tool from an MCP tool definition
+ */
+export declare function createToolFromMCP(mcpTool: MCPTool, mcpClient: MCPClient): Tool;
+/**
+ * Register all MCP tools in the registry
+ */
+export declare function registerMCPTools(mcpClient: MCPClient, registry: {
+    register(tool: Tool): void;
+}): Promise<void>;
+/**
+ * Serialize an MCP tool result safely:
+ * - bigint values → string (JSON.stringify fails on bigint)
+ * - Circular references → replaced with "[Circular]"
+ */
+export declare function serializeMCPResult(value: unknown): unknown;
+/**
+ * Discover all tools from a running MCPHypervisor (or any MCPToolSource)
+ * and return them as RevealUI Tool instances.
+ *
+ * Tool names use the hypervisor's namespacing (@@mcp_{server}_{tool}) so
+ * collisions across servers are impossible.
+ *
+ * @example
+ * ```typescript
+ * import { MCPHypervisor } from '@revealui/mcp'
+ * import { discoverMCPTools } from '@revealui/ai'
+ *
+ * const hypervisor = MCPHypervisor.getInstance()
+ * const tools = discoverMCPTools(hypervisor)
+ * agent.tools.push(...tools)
+ * ```
+ */
+export declare function discoverMCPTools(source: MCPToolSource): Tool[];
+//# sourceMappingURL=mcp-adapter.d.ts.map

package/dist/tools/mcp-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-adapter.d.ts","sourceRoot":"","sources":["../../src/tools/mcp-adapter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,WAAW,CAAA;AAEjD,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAA;QACd,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QACnC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;KACpB,CAAA;CACF;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACxD;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,WAAW,IAAI,KAAK,CAAC;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;IACnF,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CAChF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,GAAG,IAAI,CAuB9E;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAA;CAAE,GACvC,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAa1D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,EAAE,CAkC9D"}