vovk 3.0.0-draft.99 → 3.0.2

package/dist/tools/deriveTools.d.ts

@@ -0,0 +1,46 @@
+import type { DefaultModelOutput } from './toModelOutputDefault.js';
+import type { VovkRequest } from '../types/request.js';
+import type { VovkToolDerived, ToModelOutputFn } from '../types/tools.js';
+type DerivedToolInput = {
+    body?: unknown;
+    query?: unknown;
+    params?: unknown;
+};
+type DeriveToolsBaseOptions<TOutput = unknown, TFormattedOutput = unknown> = {
+    modules: Record<string, object>;
+    meta?: Record<string, unknown>;
+    onExecute?: (result: unknown, tool: VovkToolDerived<DerivedToolInput, TOutput, TFormattedOutput>, req: Pick<VovkRequest, 'vovk'> | null) => void;
+    onError?: (error: Error, tool: VovkToolDerived<DerivedToolInput, TOutput, TFormattedOutput>, req: Pick<VovkRequest, 'vovk'> | null) => void;
+};
+type DeriveToolsResult<TOutput, TFormattedOutput> = {
+    tools: VovkToolDerived<DerivedToolInput, TOutput, TFormattedOutput>[];
+    toolsByName: Record<string, VovkToolDerived<DerivedToolInput, TOutput, TFormattedOutput>>;
+};
+/**
+ * Derives AI tools from controllers and RPC modules.
+ * @see https://vovk.dev/tools
+ * @example
+ * ```ts
+ * import { deriveTools, ToModelOutput } from 'vovk';
+ * import { UserRPC } from 'vovk-client';
+ *
+ * // Derive AI tools from the UserRPC module
+ * const { tools, toolsByName } = deriveTools({
+ *   modules: { UserRPC },
+ *   toModelOutput: ToModelOutput.MCP,
+ *   onExecute: (result, tool) => {
+ *     console.log(`Tool ${tool.name} executed successfully.`);
+ *   },
+ *   onError: (error, tool) => {
+ *     console.error(`Tool ${tool.name} execution failed:`, error);
+ *   },
+ * });
+ * ```
+ */
+export declare function deriveTools<TOutput = unknown, TFormattedOutput = DefaultModelOutput<TOutput>>(options: DeriveToolsBaseOptions & {
+    toModelOutput?: never;
+}): DeriveToolsResult<TOutput, TFormattedOutput>;
+export declare function deriveTools<TOutput = unknown, TFormattedOutput = unknown>(options: DeriveToolsBaseOptions & {
+    toModelOutput: ToModelOutputFn<unknown, TOutput, TFormattedOutput>;
+}): DeriveToolsResult<TOutput, TFormattedOutput>;
+export {};

package/dist/tools/deriveTools.js

@@ -0,0 +1,132 @@
+import { ToModelOutput } from './ToModelOutput.js';
+async function caller({ handler, handlerName, body, query, params, meta, toModelOutput }, tool) {
+    if (!handler.isRPC && !handler.fn) {
+        throw new Error('Handler is not a valid RPC or controller method');
+    }
+    try {
+        let result;
+        let req = null;
+        if (handler.isRPC) {
+            result = await handler({
+                handler,
+                body,
+                query,
+                params,
+                meta,
+            });
+        }
+        else if (handler.fn) {
+            [result, req] = await handler.fn({
+                body,
+                query,
+                params,
+                meta,
+                transform: (result, req) => [result, req],
+            });
+        }
+        else {
+            throw new Error(`Unable to call handler "${handlerName}". It's neither RPC nor controller method with "fn" interface.`);
+        }
+        return [
+            await toModelOutput(result, tool, req),
+            req,
+        ];
+    }
+    catch (e) {
+        return [await toModelOutput(e, tool, null), null];
+    }
+}
+const makeTool = ({ moduleName, handlerName, module, meta, toModelOutput, onExecute, onError, }) => {
+    if (!module) {
+        throw new Error(`Module "${moduleName}" not found.`);
+    }
+    const handler = module[handlerName];
+    if (!handler) {
+        throw new Error(`Handler "${handlerName}" not found in module "${moduleName}".`);
+    }
+    const { schema, definition } = handler;
+    const inputSchemas = Object.fromEntries(['body', 'query', 'params'].map((key) => [key, definition?.[key]]).filter(([, value]) => Boolean(value)));
+    if (!schema || !schema.operationObject) {
+        throw new Error(`Handler "${handlerName}" in module "${moduleName}" does not have a valid schema.`);
+    }
+    const execute = async (input) => {
+        const { body, query, params } = input;
+        const callerInput = {
+            schema,
+            inputSchemas,
+            handler,
+            body,
+            query,
+            params,
+            meta,
+            handlerName,
+            moduleName,
+            toModelOutput,
+        };
+        const [result, req] = await caller(callerInput, tool);
+        if (result instanceof Error) {
+            onError(result, tool, req);
+        }
+        else {
+            onExecute(result, tool, req);
+        }
+        return result;
+    };
+    const parametersProperties = {
+        ...(schema?.validation?.body
+            ? {
+                body: schema.validation.body,
+            }
+            : {}),
+        ...(schema?.validation?.query
+            ? {
+                query: schema.validation.query,
+            }
+            : {}),
+        ...(schema?.validation?.params
+            ? {
+                params: schema.validation.params,
+            }
+            : {}),
+    };
+    const tool = {
+        type: 'function',
+        execute,
+        name: schema.operationObject?.['x-tool']?.name ?? `${moduleName}_${handlerName}`,
+        inputSchema: undefined,
+        outputSchema: definition?.output,
+        title: schema.operationObject?.['x-tool']?.title ?? schema.operationObject?.summary,
+        description: schema.operationObject?.['x-tool']?.description ??
+            ([schema.operationObject?.summary ?? '', schema.operationObject?.description ?? ''].filter(Boolean).join('\n') ||
+                handlerName),
+        parameters: {
+            type: 'object',
+            properties: parametersProperties,
+            required: Object.keys(parametersProperties),
+            additionalProperties: false,
+        },
+        inputSchemas,
+    };
+    return tool;
+};
+export function deriveTools(options) {
+    const { modules, meta, toModelOutput = ToModelOutput.DEFAULT, onExecute = (result) => result, onError = () => { }, } = options;
+    const tools = Object.entries(modules ?? {}).flatMap(([moduleName, module]) => {
+        return Object.entries(module ?? {})
+            .filter(([, handler]) => handler?.schema?.operationObject && !handler?.schema?.operationObject?.['x-tool']?.hidden)
+            .map(([handlerName]) => makeTool({
+            moduleName,
+            handlerName,
+            module,
+            meta,
+            toModelOutput,
+            onExecute,
+            onError,
+        }));
+    });
+    const toolsByName = Object.fromEntries(tools.map((tool) => [tool.name, tool]));
+    return {
+        tools,
+        toolsByName,
+    };
+}

package/dist/tools/toModelOutputDefault.d.ts

@@ -0,0 +1,7 @@
+import type { VovkRequest } from '../types/request.js';
+import type { VovkTool } from '../types/tools.js';
+export type DefaultModelOutput<T> = T | {
+    error: string;
+};
+export type ToModelOutputDefaultFn = <TInput, TOutput>(result: TOutput | Error, tool: VovkTool<TInput, TOutput, unknown>, req: Pick<VovkRequest, 'vovk'> | null) => DefaultModelOutput<TOutput>;
+export declare const toModelOutputDefault: ToModelOutputDefaultFn;

package/dist/tools/toModelOutputDefault.js

@@ -0,0 +1,7 @@
+export const toModelOutputDefault = (result, 
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+_tool, 
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+_req) => {
+    return result instanceof Error ? { error: result.message } : result;
+};

package/dist/tools/toModelOutputMCP.d.ts

@@ -0,0 +1,30 @@
+import type { VovkRequest } from '../types/request.js';
+import type { VovkTool } from '../types/tools.js';
+export type MCPModelOutput = {
+    content: [
+        {
+            type: 'audio';
+            mimeType: string;
+            data: string;
+        } | {
+            type: 'image';
+            mimeType: string;
+            data: string;
+        } | {
+            type: 'text';
+            text: string;
+        }
+    ];
+    annotations?: {
+        audience?: ('user' | 'assistant')[];
+        priority?: number;
+        lastModified?: string;
+    };
+    structuredContent?: {
+        [key: string]: unknown;
+    };
+    isError?: boolean;
+};
+type ToModelOutputMCPFn = <TOutput>(result: TOutput | Error, tool: VovkTool, req: Pick<VovkRequest, 'vovk'> | null) => Promise<MCPModelOutput>;
+export declare const toModelOutputMCP: ToModelOutputMCPFn;
+export {};

package/dist/tools/toModelOutputMCP.js

@@ -0,0 +1,54 @@
+import { reqMeta } from '../req/reqMeta.js';
+// converts array to object with "items" key for MCP structured content
+const structuredContentToObject = (data) => {
+    if (Array.isArray(data)) {
+        return { items: data };
+    }
+    return data;
+};
+const toBase64 = (buf) => typeof Buffer !== 'undefined'
+    ? Buffer.from(buf).toString('base64')
+    : btoa([...new Uint8Array(buf)].map((b) => String.fromCharCode(b)).join(''));
+async function responseToMCP(res) {
+    const mimeType = res.headers.get('Content-Type')?.split(';')[0].trim() || '';
+    if (mimeType.startsWith('audio/')) {
+        return { content: [{ type: 'audio', mimeType, data: toBase64(await res.arrayBuffer()) }] };
+    }
+    if (mimeType.startsWith('image/')) {
+        return { content: [{ type: 'image', mimeType, data: toBase64(await res.arrayBuffer()) }] };
+    }
+    if (mimeType === 'application/json') {
+        const structuredContent = await res.json();
+        return {
+            content: [{ type: 'text', text: JSON.stringify(structuredContent) }],
+            structuredContent: structuredContentToObject(structuredContent),
+        };
+    }
+    if (mimeType.startsWith('text/') || /xml|javascript|yaml/.test(mimeType)) {
+        return { content: [{ type: 'text', text: await res.text() }] };
+    }
+    return {
+        content: [{ type: 'text', text: `Unsupported response content type ${mimeType}` }],
+        isError: true,
+    };
+}
+export const toModelOutputMCP = async (result, _tool, req) => {
+    const mcpOutputMeta = req ? reqMeta(req).mcpOutput : null;
+    if (result instanceof Response) {
+        return { ...(await responseToMCP(result)), ...(mcpOutputMeta || {}) };
+    }
+    const isError = result instanceof Error;
+    return {
+        content: [
+            {
+                type: 'text',
+                text: isError ? result.message : JSON.stringify(result),
+            },
+        ],
+        ...(isError ? { isError: true } : {}),
+        ...(!isError && typeof result === 'object' && result !== null
+            ? { structuredContent: structuredContentToObject(result) }
+            : {}),
+        ...(mcpOutputMeta || {}),
+    };
+};