@drax/ai-back 3.29.0 → 3.31.0

package/src/routes/AgentSessionRoutes.ts

@@ -0,0 +1,38 @@
+
+import AgentSessionController from "../controllers/AgentSessionController.js";
+import {CrudSchemaBuilder} from "@drax/crud-back";
+import {AgentSessionSchema, AgentSessionBaseSchema} from '../schemas/AgentSessionSchema.js'
+
+async function AgentSessionRoutes(fastify, options) {
+
+    const controller: AgentSessionController = new AgentSessionController()
+    const schemas = new CrudSchemaBuilder(AgentSessionSchema, AgentSessionBaseSchema,AgentSessionBaseSchema, 'AgentSession', 'openapi-3.0', ['ai']);
+
+    fastify.get('/api/agentsession', {schema: schemas.paginateSchema}, (req,rep) => controller.paginate(req,rep))
+
+    fastify.get('/api/agentsession/find', {schema: schemas.findSchema}, (req,rep) => controller.find(req,rep))
+
+    fastify.get('/api/agentsession/search', {schema: schemas.searchSchema}, (req,rep) => controller.search(req,rep))
+
+    fastify.get('/api/agentsession/:id', {schema: schemas.findByIdSchema}, (req,rep) => controller.findById(req,rep))
+
+    fastify.get('/api/agentsession/find-one', {schema: schemas.findOneSchema}, (req,rep) => controller.findOne(req,rep))
+
+    fastify.get('/api/agentsession/group-by', {schema: schemas.groupBySchema}, (req,rep) => controller.groupBy(req,rep))
+
+    fastify.post('/api/agentsession', {schema: schemas.createSchema}, (req,rep) =>controller.create(req,rep))
+
+    fastify.put('/api/agentsession/:id', {schema: schemas.updateSchema}, (req,rep) =>controller.update(req,rep))
+
+    fastify.patch('/api/agentsession/:id', {schema: schemas.updateSchema}, (req,rep) =>controller.updatePartial(req,rep))
+
+    fastify.delete('/api/agentsession/:id', {schema: schemas.deleteSchema}, (req,rep) =>controller.delete(req,rep))
+
+    fastify.get('/api/agentsession/export', (req,rep) =>controller.export(req,rep))
+
+    fastify.post('/api/agentsession/import', (req,rep) => controller.import(req,rep))
+
+}
+
+export default AgentSessionRoutes;
+export {AgentSessionRoutes}

package/src/routes/DraxAgentRoutes.ts

@@ -0,0 +1,12 @@
+import DraxAgentController from "../controllers/DraxAgentController.js";
+
+async function DraxAgentRoutes(fastify, options:any) {
+    const controller = new DraxAgentController();
+    const prefix = "/api/ai/agent";
+
+    fastify.post(`${prefix}/session`, (req, rep) => controller.startSession(req, rep));
+    fastify.post(`${prefix}/message`, (req, rep) => controller.message(req, rep));
+}
+
+export default DraxAgentRoutes;
+export {DraxAgentRoutes};

package/src/schemas/AgentSessionSchema.ts

@@ -0,0 +1,30 @@
+import {z} from 'zod';
+
+const AgentSessionBaseSchema = z.object({
+    sessionId: z.string().min(1, 'validation.required'),
+    title: z.string().optional(),
+    lastMessageAt: z.coerce.date().nullable().optional(),
+    messages: z.array(
+        z.object({
+            role: z.enum(['user', 'assistant', 'system']),
+            content: z.string().min(1, 'validation.required'),
+            createdAt: z.coerce.date().nullable().optional()
+        })
+    ).optional(),
+    messageCount: z.number().nullable().optional(),
+    inputTokens: z.number().nullable().optional(),
+    outputTokens: z.number().nullable().optional(),
+    tokens: z.number().nullable().optional(),
+    tenant: z.coerce.string().optional().nullable(),
+    user: z.coerce.string().optional().nullable()
+});
+
+const AgentSessionSchema = AgentSessionBaseSchema
+    .extend({
+        _id: z.coerce.string(),
+        tenant: z.object({_id: z.coerce.string(), name: z.string().optional()}).nullable(),
+        user: z.object({_id: z.coerce.string(), username: z.string().optional()}).nullable()
+    })
+
+export default AgentSessionSchema;
+export {AgentSessionSchema, AgentSessionBaseSchema}

package/src/services/AgentSessionService.ts

@@ -0,0 +1,20 @@
+
+import type{IAgentSessionRepository} from "../interfaces/IAgentSessionRepository";
+import type {IAgentSessionBase, IAgentSession} from "../interfaces/IAgentSession";
+import {AbstractService} from "@drax/crud-back";
+import type {ZodObject, ZodRawShape} from "zod";
+
+class AgentSessionService extends AbstractService<IAgentSession, IAgentSessionBase, IAgentSessionBase> {
+
+
+    constructor(AgentSessionRepository: IAgentSessionRepository, baseSchema?: ZodObject<ZodRawShape>, fullSchema?: ZodObject<ZodRawShape>) {
+        super(AgentSessionRepository, baseSchema, fullSchema);
+        
+        this._validateOutput = true
+        
+    }
+
+}
+
+export default AgentSessionService
+export {AgentSessionService}

package/src/tools/BuilderTool.ts

@@ -0,0 +1,289 @@
+import {z, type ZodObject, type ZodRawShape, type ZodTypeAny} from "zod";
+import type {IPromptTool} from "../interfaces/IAIProvider.js";
+import type {
+    ToolBuilderMethod,
+    ToolBuilderOptions,
+    ToolBuilderService,
+    ToolDefinition
+} from "../interfaces/IBuilderTool.js";
+
+const emptyParameters = {
+    type: "object",
+    properties: {},
+    additionalProperties: false,
+};
+
+const idSchema = z.object({
+    id: z.string().describe("Entity identifier"),
+});
+
+const filtersSchema = z.array(z.object({
+    field: z.string(),
+    operator: z.string(),
+    value: z.any(),
+    orGroup: z.string().optional(),
+})).optional().describe("Optional Drax field filters");
+
+const toolDefinitions: Record<ToolBuilderMethod, ToolDefinition> = {
+    create: {
+        description: entityName => `Crear un registro de ${entityName}`,
+        parameters: builder => builder.objectParameters(z.object({
+            data: builder.inputSchema.describe("Data for the entity to create"),
+        })),
+        execute: (service, args) => service.create?.(args.data),
+    },
+    update: {
+        description: entityName => `Reemplazar un registro de ${entityName} por id`,
+        parameters: builder => builder.objectParameters(z.object({
+            id: z.string().describe("Entity identifier"),
+            data: builder.inputSchema.describe("Complete replacement data"),
+        })),
+        execute: (service, args) => service.update?.(args.id, args.data),
+    },
+    updatePartial: {
+        description: entityName => `Actualizar parcialmente un registro de ${entityName} por id`,
+        parameters: builder => builder.objectParameters(z.object({
+            id: z.string().describe("Entity identifier"),
+            data: builder.partialInputSchema.describe("Partial data to update"),
+        })),
+        execute: (service, args) => service.updatePartial?.(args.id, args.data),
+    },
+    delete: {
+        description: entityName => `Eliminar un registro de ${entityName} por id`,
+        parameters: builder => builder.objectParameters(idSchema),
+        execute: (service, args) => service.delete?.(args.id),
+    },
+    findById: {
+        description: entityName => `Buscar un registro de ${entityName} por id`,
+        parameters: builder => builder.objectParameters(idSchema),
+        execute: (service, args) => service.findById?.(args.id),
+    },
+    findByIds: {
+        description: entityName => `Buscar multiples registros de ${entityName} por ids`,
+        parameters: builder => builder.objectParameters(z.object({
+            ids: z.array(z.string()).describe("Entity identifiers"),
+        })),
+        execute: (service, args) => service.findByIds?.(args.ids),
+    },
+    findOneBy: {
+        description: entityName => `Buscar un registro de ${entityName} por valor de campo`,
+        parameters: builder => builder.objectParameters(z.object({
+            field: z.string(),
+            value: z.any(),
+            filters: filtersSchema,
+        })),
+        execute: (service, args) => service.findOneBy?.(args.field, args.value, args.filters ?? []),
+    },
+    findOne: {
+        description: entityName => `Buscar el primer registro de ${entityName} que coincida con busqueda y filtros`,
+        parameters: builder => builder.objectParameters(z.object({
+            search: z.string().optional(),
+            filters: filtersSchema,
+        })),
+        execute: (service, args) => service.findOne?.({
+            search: args.search ?? "",
+            filters: args.filters ?? [],
+        }),
+    },
+    findBy: {
+        description: entityName => `Buscar registros de ${entityName} por valor de campo`,
+        parameters: builder => builder.objectParameters(z.object({
+            field: z.string(),
+            value: z.any(),
+            limit: z.number().optional(),
+            filters: filtersSchema,
+        })),
+        execute: (service, args) => service.findBy?.(args.field, args.value, args.limit ?? 1000, args.filters ?? []),
+    },
+    fetchAll: {
+        description: entityName => `Obtener todos los registros de ${entityName}`,
+        parameters: () => emptyParameters,
+        execute: service => service.fetchAll?.(),
+    },
+    search: {
+        description: entityName => `Buscar registros de ${entityName} por texto`,
+        parameters: builder => builder.objectParameters(z.object({
+            value: z.string().describe("Search text"),
+            limit: z.number().optional(),
+            filters: filtersSchema,
+        })),
+        execute: (service, args) => service.search?.(args.value, args.limit ?? 1000, args.filters ?? []),
+    },
+    find: {
+        description: entityName => `Buscar registros de ${entityName} usando opciones de listado`,
+        parameters: builder => builder.objectParameters(z.object({
+            orderBy: z.string().optional(),
+            order: z.union([z.enum(["asc", "desc"]), z.boolean()]).optional(),
+            search: z.string().optional(),
+            filters: filtersSchema,
+            limit: z.number().optional(),
+        })),
+        execute: (service, args) => service.find?.({
+            orderBy: args.orderBy ?? "",
+            order: args.order ?? false,
+            search: args.search ?? "",
+            filters: args.filters ?? [],
+            limit: args.limit ?? 0,
+        }),
+    },
+    paginate: {
+        description: entityName => `Paginar registros de ${entityName}`,
+        parameters: builder => builder.objectParameters(z.object({
+            page: z.number().optional(),
+            limit: z.number().optional(),
+            orderBy: z.string().optional(),
+            order: z.enum(["asc", "desc"]).optional(),
+            search: z.string().optional(),
+            filters: filtersSchema,
+        })),
+        execute: (service, args) => service.paginate({
+            page: args.page ?? 1,
+            limit: args.limit ?? 10,
+            orderBy: args.orderBy,
+            order: args.order ?? "asc",
+            search: args.search ?? "",
+            filters: args.filters ?? [],
+        }),
+    },
+    groupBy: {
+        description: entityName => `Agrupar registros de ${entityName} por campos`,
+        parameters: builder => builder.objectParameters(z.object({
+            fields: z.array(z.string()).optional(),
+            filters: filtersSchema,
+            dateFormat: z.enum(["year", "month", "day", "hour", "minute", "second"]).optional(),
+        })),
+        execute: (service, args) => service.groupBy?.({
+            fields: args.fields ?? [],
+            filters: args.filters ?? [],
+            dateFormat: args.dateFormat ?? "day",
+        }),
+    },
+};
+
+class BuilderTool<T = any, C = any, U = any> {
+    protected _inputSchema: ZodObject<ZodRawShape>;
+    protected _partialInputSchema: ZodObject<ZodRawShape>;
+    protected _outputSchema?: ZodObject<ZodRawShape>;
+
+    constructor(protected options: ToolBuilderOptions<T, C, U>) {
+        this._inputSchema = this.schemaAdapter(options.schema);
+        this._partialInputSchema = this._inputSchema.partial();
+        this._outputSchema = options.outputSchema ? this.schemaAdapter(options.outputSchema) : undefined;
+    }
+
+    get inputSchema() {
+        return this._inputSchema;
+    }
+
+    get partialInputSchema() {
+        return this._partialInputSchema;
+    }
+
+    get outputSchema() {
+        return this._outputSchema;
+    }
+
+    getTools(): IPromptTool[] {
+        return this.options.methods.map(method => this.buildTool(method));
+    }
+
+    getSystemPromptSection(): string {
+        const entityDescription = this.options.entityDescription
+            ? `\n${this.options.entityDescription}`
+            : "";
+
+        const tools = this.options.methods
+            .map(method => {
+                const definition = toolDefinitions[method];
+                return `- ${this.getToolName(method)}: ${definition.description(this.options.entityName)}`;
+            })
+            .join("\n");
+
+        const entitySchema = JSON.stringify(this.toJsonSchema(this._outputSchema ?? this._inputSchema));
+
+        return [
+            `[ENTIDAD: ${this.options.entityName}]${entityDescription}`,
+            `Schema JSON de la entidad: ${entitySchema}`,
+            "Tools disponibles:",
+            tools,
+        ].join("\n");
+    }
+
+    objectParameters(schema: ZodObject<ZodRawShape>) {
+        return this.toJsonSchema(this.schemaAdapter(schema));
+    }
+
+    protected buildTool(method: ToolBuilderMethod): IPromptTool {
+        const definition = toolDefinitions[method];
+        const serviceMethod = this.options.service[method];
+
+        if (typeof serviceMethod !== "function") {
+            throw new Error(`Tool method not available on service: ${method}`);
+        }
+
+        return {
+            name: this.getToolName(method),
+            description: definition.description(this.options.entityName),
+            parameters: definition.parameters(this),
+            navigation: {
+                entityName: this.options.entityName,
+                method,
+                basePath: this.options.navigationBasePath,
+            },
+            execute: async (args: any) => definition.execute(this.options.service, args),
+        };
+    }
+
+    protected getToolName(method: ToolBuilderMethod) {
+        return `${this.options.toolNamePrefix ?? this.options.entityName}_${method}`;
+    }
+
+    protected toJsonSchema(schema: ZodObject<ZodRawShape>) {
+        return z.toJSONSchema(schema, {target: "openAi"});
+    }
+
+    protected getTypeName(field: any): string | undefined {
+        return field?.constructor?.name;
+    }
+
+    protected fieldAdapter(field: unknown): ZodTypeAny {
+        const f: any = field;
+        const typeName = this.getTypeName(f);
+
+        if (typeof f?.unwrap === "function" && typeName === "ZodOptional") {
+            return this.fieldAdapter(f.unwrap()).optional();
+        }
+
+        if (typeof f?.unwrap === "function" && typeName === "ZodNullable") {
+            return this.fieldAdapter(f.unwrap()).nullable();
+        }
+
+        if (typeName === "ZodArray" && f?.element) {
+            return z.array(this.fieldAdapter(f.element));
+        }
+
+        if (typeName === "ZodObject" && f?.shape) {
+            return this.schemaAdapter(f);
+        }
+
+        if (typeName === "ZodDate") {
+            return z.iso.datetime();
+        }
+
+        return f as ZodTypeAny;
+    }
+
+    protected schemaAdapter<TObj extends ZodObject<ZodRawShape>>(schema: TObj): TObj {
+        const shape = (schema as any).shape as Record<string, unknown>;
+        const newShape: Record<string, ZodTypeAny> = {};
+
+        for (const key of Object.keys(shape)) {
+            newShape[key] = this.fieldAdapter(shape[key]);
+        }
+
+        return z.object(newShape) as unknown as TObj;
+    }
+}
+
+export default BuilderTool;
+export {BuilderTool};

package/test/DraxAgent.test.ts

@@ -0,0 +1,221 @@
+import {describe, expect, test} from "vitest";
+import {DraxAgent} from "../src/agents/DraxAgent.js";
+import type {IAIProvider, IPromptParams, IPromptResponse, IPromptTool} from "../src/interfaces/IAIProvider.js";
+
+class MockProvider implements IAIProvider {
+    requests: IPromptParams[] = [];
+
+    async prompt(input: IPromptParams): Promise<IPromptResponse> {
+        this.requests.push(input);
+
+        if (input.tools && input.tools.length > 0) {
+            await input.tools[0].execute({value: "Ada"});
+        }
+
+        return {
+            output: "respuesta",
+            tokens: 10,
+            inputTokens: 6,
+            outputTokens: 4,
+            time: 12,
+        };
+    }
+}
+
+describe("DraxAgent", () => {
+    test("creates a session and sends messages through the injected provider", async () => {
+        const provider = new MockProvider();
+        const agent = DraxAgent.instance().clearSessions().configure({
+            provider,
+            systemPrompt: "Sos un asistente.",
+            sessionService: false,
+        });
+
+        const session = await agent.startSession({userId: "user-1", tenantId: "tenant-1"});
+        const response = await agent.sendMessage({
+            sessionId: session.id,
+            userId: "user-1",
+            tenantId: "tenant-1",
+            message: "Hola",
+        });
+
+        expect(response).toMatchObject({
+            sessionId: session.id,
+            message: "respuesta",
+            tokens: 10,
+        });
+        expect(provider.requests[0]).toMatchObject({
+            userInput: "Hola",
+            tenant: "tenant-1",
+            user: "user-1",
+        });
+        expect(provider.requests[0].systemPrompt).toContain("Sos un asistente.");
+        expect(provider.requests[0].systemPrompt).toContain("[CONTEXTO RBAC]");
+        expect(provider.requests[0].systemPrompt).toContain("tenantId: tenant-1");
+        expect(provider.requests[0].systemPrompt).toContain("userId: user-1");
+        expect(provider.requests[0].systemPrompt).toContain("tenant, tenantId, user, userId o createdBy");
+    });
+
+    test("injects builder tools, custom tools and builder prompt sections", async () => {
+        const calls: any[] = [];
+        const provider = new MockProvider();
+        const customTool: IPromptTool = {
+            name: "custom_search",
+            description: "Buscar datos custom",
+            parameters: {
+                type: "object",
+                properties: {
+                    value: {type: "string"},
+                },
+            },
+            execute: async args => {
+                calls.push(args);
+                return [{name: args.value}];
+            },
+        };
+
+        const agent = DraxAgent.instance().clearSessions().configure({
+            provider,
+            systemPrompt: "Prompt base.",
+            sessionService: false,
+            toolBuilders: [{
+                getTools: () => [],
+                getSystemPromptSection: () => "[ENTIDAD: person]\nTools disponibles:",
+            }],
+            tools: [customTool],
+        });
+
+        await agent.sendMessage({
+            userId: "user-1",
+            message: "Busca Ada",
+        });
+
+        expect(provider.requests[0].systemPrompt).toContain("Prompt base.");
+        expect(provider.requests[0].systemPrompt).toContain("[ENTIDADES Y TOOLS]");
+        expect(provider.requests[0].systemPrompt).toContain("[ENTIDAD: person]");
+        expect(provider.requests[0].tools?.map(tool => tool.name)).toEqual(["custom_search"]);
+        expect(calls).toEqual([{value: "Ada"}]);
+    });
+
+    test("uses previous session messages as history", async () => {
+        const provider = new MockProvider();
+        const agent = DraxAgent.instance().clearSessions().configure({
+            provider,
+            systemPrompt: "Sos un asistente.",
+            sessionService: false,
+            toolBuilders: undefined,
+            tools: undefined,
+        });
+
+        const first = await agent.sendMessage({
+            userId: "user-1",
+            message: "Primer mensaje",
+        });
+        await agent.sendMessage({
+            sessionId: first.sessionId,
+            userId: "user-1",
+            message: "Segundo mensaje",
+        });
+
+        expect(provider.requests[1].history).toEqual([
+            {role: "user", content: "Primer mensaje"},
+            {role: "assistant", content: "respuesta"},
+        ]);
+    });
+
+    test("returns a navigation path from tool execution metadata", async () => {
+        const provider = new MockProvider();
+        const agent = DraxAgent.instance().clearSessions().configure({
+            provider,
+            systemPrompt: "Sos un asistente.",
+            sessionService: false,
+            toolBuilders: undefined,
+            tools: [{
+                name: "task_findOne",
+                description: "Buscar una tarea",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        value: {type: "string"},
+                    },
+                },
+                navigation: {
+                    entityName: "task",
+                    method: "findOne",
+                },
+                execute: async () => ({id: "task-1", title: "Ada"}),
+            }],
+        });
+
+        const response = await agent.sendMessage({
+            userId: "user-1",
+            message: "Busca Ada",
+        });
+
+        expect(response.navigationPath).toBe("/crud/task?mode=view&id=task-1");
+    });
+
+    test("persists agent session creation and message updates", async () => {
+        const provider = new MockProvider();
+        const created: any[] = [];
+        const updates: any[] = [];
+        const sessionService = {
+            create: async (data: any) => {
+                created.push(data);
+                return {_id: "agent-session-1", ...data};
+            },
+            updatePartial: async (id: string, data: any) => {
+                updates.push({id, data});
+                return {_id: id, ...data};
+            },
+            findBy: async () => [],
+            findById: async () => ({
+                _id: "agent-session-1",
+                sessionId: "session-1",
+                inputTokens: 1,
+                outputTokens: 2,
+                tokens: 3,
+            }),
+        } as any;
+
+        const agent = DraxAgent.instance().clearSessions().configure({
+            provider,
+            systemPrompt: "Sos un asistente.",
+            sessionService,
+            toolBuilders: undefined,
+            tools: undefined,
+        });
+
+        const response = await agent.sendMessage({
+            sessionId: "session-1",
+            userId: "user-1",
+            tenantId: "tenant-1",
+            message: "Hola",
+        });
+
+        expect(response.sessionId).toBe("session-1");
+        expect(created[0]).toMatchObject({
+            sessionId: "session-1",
+            tenant: "tenant-1",
+            user: "user-1",
+            messageCount: 0,
+        });
+        expect(updates[0]).toMatchObject({
+            id: "agent-session-1",
+            data: {
+                sessionId: "session-1",
+                tenant: "tenant-1",
+                user: "user-1",
+                title: "Hola",
+                messageCount: 2,
+                inputTokens: 7,
+                outputTokens: 6,
+                tokens: 13,
+            },
+        });
+        expect(updates[0].data.messages).toEqual([
+            expect.objectContaining({role: "user", content: "Hola"}),
+            expect.objectContaining({role: "assistant", content: "respuesta"}),
+        ]);
+    });
+});