@drax/ai-back 3.28.0 → 3.31.0

package/src/controllers/DraxAgentController.ts

@@ -0,0 +1,135 @@
+import {z} from "zod";
+import {CommonController} from "@drax/common-back";
+import {DraxAgent} from "../agents/DraxAgent.js";
+import {AgentPermissions} from "../permissions/AgentPermissions.js";
+
+const PromptImageSchema = z.object({
+    url: z.string().min(1),
+    detail: z.enum(["auto", "low", "high"]).optional(),
+});
+
+const PromptContentPartSchema = z.discriminatedUnion("type", [
+    z.object({
+        type: z.literal("text"),
+        text: z.string(),
+    }),
+    z.object({
+        type: z.literal("image"),
+        imageUrl: z.string().min(1),
+        detail: z.enum(["auto", "low", "high"]).optional(),
+    }),
+]);
+
+const PromptMemorySchema = z.object({
+    key: z.string().min(1),
+    value: z.string(),
+});
+
+const PromptInputFileSchema = z.object({
+    filename: z.string().optional(),
+    filepath: z.string().optional(),
+    size: z.number().nullable().optional(),
+    mimetype: z.string().optional(),
+    url: z.string().optional(),
+});
+
+const AgentSessionRequestSchema = z.object({
+    sessionId: z.string().optional(),
+    userId: z.string().optional().nullable(),
+    tenantId: z.string().optional().nullable(),
+});
+
+const AgentMessageRequestSchema = AgentSessionRequestSchema.extend({
+    message: z.string().min(1),
+    userImages: z.array(PromptImageSchema).optional(),
+    userContent: z.array(PromptContentPartSchema).optional(),
+    inputFiles: z.array(PromptInputFileSchema).optional(),
+    memory: z.array(PromptMemorySchema).optional(),
+    memoryHeader: z.string().optional(),
+    knowledgeBase: z.array(z.string()).optional(),
+    knowledgeBaseHeader: z.string().optional(),
+    model: z.string().optional(),
+    toolMaxIterations: z.number().optional(),
+    operationTitle: z.string().optional(),
+    operationGroup: z.string().optional(),
+});
+
+class DraxAgentController extends CommonController {
+    protected agent: DraxAgent;
+    protected permission: string | false;
+
+    constructor() {
+        super();
+        this.permission = AgentPermissions.Session;
+        this.agent = DraxAgent.instance();
+    }
+
+    async startSession(request, reply) {
+        try {
+            this.assertAccess(request);
+
+            const input = AgentSessionRequestSchema.parse(request.body ?? {});
+            const session = await this.agent.startSession({
+                sessionId: input.sessionId,
+                userId: this.resolveUserId(request, input.userId),
+                tenantId: this.resolveTenantId(request, input.tenantId),
+            });
+
+            return reply.send({
+                sessionId: session.id,
+                createdAt: session.createdAt,
+                updatedAt: session.updatedAt,
+            });
+        } catch (e: any) {
+            this.handleControllerError(e, reply);
+        }
+    }
+
+    async message(request, reply) {
+        try {
+            this.assertAccess(request);
+
+            const input = AgentMessageRequestSchema.parse(request.body ?? {});
+            const response = await this.agent.sendMessage({
+                ...input,
+                userId: this.resolveUserId(request, input.userId),
+                tenantId: this.resolveTenantId(request, input.tenantId),
+                ip: request.ip,
+                userAgent: request.headers["user-agent"],
+            });
+
+            return reply.send(response);
+        } catch (e: any) {
+            this.handleControllerError(e, reply);
+        }
+    }
+
+    protected assertAccess(request: any) {
+        if (this.permission === false) {
+            return;
+        }
+
+        request.rbac.assertPermission(this.permission);
+    }
+
+    protected resolveUserId(request: any, userId?: string | null) {
+        return request.rbac?.userId ?? userId ?? null;
+    }
+
+    protected resolveTenantId(request: any, tenantId?: string | null) {
+        return request.rbac?.tenantId ?? tenantId ?? null;
+    }
+
+    protected handleControllerError(e: any, reply: any) {
+        if (e?.name === "ZodError") {
+            return reply.status(400).send({
+                message: e?.message || "Drax agent validation error",
+            });
+        }
+
+        this.handleError(e, reply);
+    }
+}
+
+export default DraxAgentController;
+export {DraxAgentController};

package/src/factory/services/AgentSessionServiceFactory.ts

@@ -0,0 +1,41 @@
+
+import AgentSessionMongoRepository from '../../repository/mongo/AgentSessionMongoRepository.js'
+import AgentSessionSqliteRepository from '../../repository/sqlite/AgentSessionSqliteRepository.js'
+import type {IAgentSessionRepository} from "../../interfaces/IAgentSessionRepository";
+import {AgentSessionService} from '../../services/AgentSessionService.js'
+import {AgentSessionBaseSchema, AgentSessionSchema} from "../../schemas/AgentSessionSchema.js";
+import {COMMON, CommonConfig, DraxConfig} from "@drax/common-back";
+
+class AgentSessionServiceFactory {
+    private static service: AgentSessionService;
+
+    public static get instance(): AgentSessionService {
+        if (!AgentSessionServiceFactory.service) {
+            
+            let repository: IAgentSessionRepository
+            switch (DraxConfig.getOrLoad(CommonConfig.DbEngine)) {
+                case COMMON.DB_ENGINES.MONGODB:
+                    repository = new AgentSessionMongoRepository()
+                    break;
+                case COMMON.DB_ENGINES.SQLITE:
+                    const dbFile = DraxConfig.getOrLoad(CommonConfig.SqliteDbFile)
+                    repository = new AgentSessionSqliteRepository(dbFile, false)
+                    repository.build()
+                    break;
+                default:
+                    throw new Error("DraxConfig.DB_ENGINE must be one of " + Object.values(COMMON.DB_ENGINES).join(", "));
+            }
+            
+            const baseSchema = AgentSessionBaseSchema;
+            const fullSchema = AgentSessionSchema;
+            AgentSessionServiceFactory.service = new AgentSessionService(repository, baseSchema, fullSchema);
+        }
+        return AgentSessionServiceFactory.service;
+    }
+}
+
+export default AgentSessionServiceFactory
+export {
+    AgentSessionServiceFactory
+}
+

package/src/index.ts

@@ -7,15 +7,23 @@ import {OpenAiProviderFactory} from "./factory/OpenAiProviderFactory.js";
 import {AiProviderFactory} from "./factory/AiProviderFactory.js";
 import AILogServiceFactory from "./factory/services/AILogServiceFactory.js";
 import {OpenAiProvider} from "./providers/OpenAiProvider.js";
+import {BuilderTool} from "./tools/BuilderTool.js";
 import {KnowledgeService} from "./services/KnowledgeService.js";
 import {AILogService} from "./services/AILogService.js";
 import AILogPermissions from "./permissions/AILogPermissions.js";
+import AgentPermissions from "./permissions/AgentPermissions.js";
+import AgentSessionPermissions from "./permissions/AgentSessionPermissions.js";
 import AIPermissions from "./permissions/AIPermissions.js";
 import AILogController from "./controllers/AILogController.js";
 import AICrudController from "./controllers/AICrudController.js";
 import AIGenericController from "./controllers/AIGenericController.js";
+import DraxAgentController from "./controllers/DraxAgentController.js";
+import AgentSessionController from "./controllers/AgentSessionController.js";
 import AILogRoutes from "./routes/AILogRoutes.js";
 import AIRoutes from "./routes/AIRoutes.js";
+import DraxAgentRoutes from "./routes/DraxAgentRoutes.js";
+import AgentSessionRoutes from "./routes/AgentSessionRoutes.js";
+import {DraxAgent} from "./agents/DraxAgent.js";
 import type {IAILogRepository} from "./interfaces/IAILogRepository.js";
 import type {
     IAIProvider,
@@ -30,6 +38,29 @@ import type {
     IPromptResponse,
     IPromptTool
 } from "./interfaces/IAIProvider.js";
+import type {
+    ToolBuilderMethod,
+    ToolBuilderOptions,
+    ToolBuilderService
+} from "./interfaces/IBuilderTool.js";
+import type {
+    DraxAgentControllerOptions
+} from "./interfaces/IDraxAgentController.js";
+import type {
+    DraxAgentFastifyRoutesOptions
+} from "./interfaces/IDraxAgentRoutes.js";
+import type {
+    DraxAgentConfig,
+    DraxAgentMessageInput,
+    DraxAgentMessageOutput,
+    DraxAgentPromptContext,
+    DraxAgentSession,
+    DraxAgentSessionInput,
+    DraxAgentToolBuilder,
+    DraxAgentToolBuilderSource,
+    DraxAgentToolSource,
+    DraxAgentSystemPrompt,
+} from "./interfaces/IDraxAgent.js";
 
 export type {
 
@@ -45,6 +76,21 @@ export type {
     IPromptContentPartImage,
     IPromptContentPartText,
     IPromptResponse,
+    ToolBuilderMethod,
+    ToolBuilderOptions,
+    ToolBuilderService,
+    DraxAgentControllerOptions,
+    DraxAgentFastifyRoutesOptions,
+    DraxAgentConfig,
+    DraxAgentMessageInput,
+    DraxAgentMessageOutput,
+    DraxAgentPromptContext,
+    DraxAgentSession,
+    DraxAgentSessionInput,
+    DraxAgentToolBuilder,
+    DraxAgentToolBuilderSource,
+    DraxAgentToolSource,
+    DraxAgentSystemPrompt,
 }
 
 export {
@@ -58,13 +104,24 @@ export {
     AiProviderFactory,
     AILogServiceFactory,
     OpenAiProvider,
+    BuilderTool,
+    //Service
     KnowledgeService,
     AILogService,
+    //Permissions
     AILogPermissions,
+    AgentPermissions,
     AIPermissions,
+    AgentSessionPermissions,
+    //Controllers
     AILogController,
     AICrudController,
     AIGenericController,
+    DraxAgentController,
+    AgentSessionController,
+    DraxAgent,
     AILogRoutes,
-    AIRoutes
+    AIRoutes,
+    DraxAgentRoutes,
+    AgentSessionRoutes
 }

package/src/interfaces/IAIProvider.ts

@@ -37,6 +37,13 @@ interface IPromptTool {
     description: string;
     parameters?: object;
     execute: (args: any) => any | Promise<any>;
+    navigation?: IPromptToolNavigation;
+}
+
+interface IPromptToolNavigation {
+    entityName: string;
+    method: string;
+    basePath?: string;
 }
 
 interface IPromptParams {
@@ -88,6 +95,7 @@ export type {
     IPromptMessage,
     IPromptMemory,
     IPromptTool,
+    IPromptToolNavigation,
     IPromptImage,
     IPromptImageDetail,
     IPromptContentPart,

package/src/interfaces/IAgentSession.ts

@@ -0,0 +1,44 @@
+
+interface IAgentSessionBase {
+    sessionId: string
+    title?: string
+    lastMessageAt?: Date
+    messages?: Array<{
+    role: string
+    content: string
+    createdAt?: Date
+    }>
+    messageCount?: number
+    inputTokens?: number
+    outputTokens?: number
+    tokens?: number
+    tenant?: any
+    user?: any
+    createdAt?: Date
+    updatedAt?: Date
+}
+
+interface IAgentSession {
+    _id: string
+    sessionId: string
+    title?: string
+    lastMessageAt?: Date
+    messages?: Array<{
+    role: string
+    content: string
+    createdAt?: Date
+    }>
+    messageCount?: number
+    inputTokens?: number
+    outputTokens?: number
+    tokens?: number
+    tenant?: any
+    user?: any
+    createdAt?: Date
+    updatedAt?: Date
+}
+
+export type {
+IAgentSessionBase, 
+IAgentSession
+}

package/src/interfaces/IAgentSessionRepository.ts

@@ -0,0 +1,11 @@
+
+import type {IAgentSession, IAgentSessionBase} from './IAgentSession'
+import {IDraxCrudRepository} from "@drax/crud-share";
+
+interface IAgentSessionRepository extends IDraxCrudRepository<IAgentSession, IAgentSessionBase, IAgentSessionBase>{
+
+}
+
+export {IAgentSessionRepository}
+
+

package/src/interfaces/IBuilderTool.ts

@@ -0,0 +1,51 @@
+import type {IDraxCrudService} from "@drax/crud-share";
+import type {ZodObject, ZodRawShape} from "zod";
+
+type ToolBuilderMethod =
+    | "create"
+    | "update"
+    | "updatePartial"
+    | "delete"
+    | "findById"
+    | "findByIds"
+    | "findOneBy"
+    | "findOne"
+    | "findBy"
+    | "fetchAll"
+    | "search"
+    | "find"
+    | "paginate"
+    | "groupBy";
+
+type ToolBuilderService<T = any, C = any, U = any> = IDraxCrudService<T, C, U> & Record<string, any>;
+
+interface ToolBuilderOptions<T = any, C = any, U = any> {
+    entityName: string;
+    entityDescription?: string;
+    navigationBasePath?: string;
+    schema: ZodObject<ZodRawShape>;
+    outputSchema?: ZodObject<ZodRawShape>;
+    service: ToolBuilderService<T, C, U>;
+    methods: ToolBuilderMethod[];
+    toolNamePrefix?: string;
+}
+
+interface ToolBuilderLike {
+    inputSchema: ZodObject<ZodRawShape>;
+    partialInputSchema: ZodObject<ZodRawShape>;
+    objectParameters(schema: ZodObject<ZodRawShape>): object;
+}
+
+interface ToolDefinition<T = any, C = any, U = any> {
+    description: (entityName: string) => string;
+    parameters: (builder: ToolBuilderLike) => object;
+    execute: (service: ToolBuilderService<T, C, U>, args: any) => any | Promise<any>;
+}
+
+export type {
+    ToolBuilderLike,
+    ToolBuilderMethod,
+    ToolBuilderOptions,
+    ToolBuilderService,
+    ToolDefinition,
+};

package/src/interfaces/IDraxAgent.ts

@@ -0,0 +1,108 @@
+import type {
+    IAIProvider,
+    IPromptContentPart,
+    IPromptImage,
+    IPromptMemory,
+    IPromptMessage,
+    IPromptTool
+} from "./IAIProvider.js";
+import type {AgentSessionService} from "../services/AgentSessionService.js";
+
+type DraxAgentSystemPrompt =
+    | string
+    | ((context: DraxAgentPromptContext) => string | Promise<string>);
+
+type DraxAgentToolSource =
+    | IPromptTool[]
+    | ((context: DraxAgentPromptContext) => IPromptTool[] | Promise<IPromptTool[]>);
+
+interface DraxAgentToolBuilder {
+    getTools(): IPromptTool[];
+    getSystemPromptSection(): string;
+}
+
+type DraxAgentToolBuilderSource =
+    | DraxAgentToolBuilder[]
+    | ((context: DraxAgentPromptContext) => DraxAgentToolBuilder[] | Promise<DraxAgentToolBuilder[]>);
+
+interface DraxAgentConfig {
+    provider?: IAIProvider;
+    systemPrompt?: DraxAgentSystemPrompt;
+    toolBuilders?: DraxAgentToolBuilderSource;
+    tools?: DraxAgentToolSource;
+    historyLimit?: number;
+    toolMaxIterations?: number;
+    operationTitle?: string;
+    operationGroup?: string;
+    logToolExecution?: boolean;
+    normalizeOutput?: (output: any) => string;
+    sessionService?: AgentSessionService | false;
+}
+
+interface DraxAgentSessionInput {
+    sessionId?: string;
+    userId?: string | null;
+    tenantId?: string | null;
+}
+
+interface DraxAgentMessageInput extends DraxAgentSessionInput {
+    message: string;
+    ip?: string;
+    userAgent?: string;
+    model?: string;
+    userImages?: IPromptImage[];
+    userContent?: IPromptContentPart[];
+    inputFiles?: Array<{
+        filename?: string;
+        filepath?: string;
+        size?: number | null;
+        mimetype?: string;
+        url?: string;
+    }>;
+    memory?: IPromptMemory[];
+    memoryHeader?: string;
+    knowledgeBase?: string[];
+    knowledgeBaseHeader?: string;
+    toolMaxIterations?: number;
+    operationTitle?: string;
+    operationGroup?: string;
+}
+
+interface DraxAgentMessageOutput {
+    sessionId: string;
+    message: string;
+    navigationPath?: string | null;
+    output: any;
+    tokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    time: number;
+}
+
+interface DraxAgentSession {
+    id: string;
+    recordId?: string | null;
+    userId?: string | null;
+    tenantId?: string | null;
+    messages: IPromptMessage[];
+    createdAt: Date;
+    updatedAt: Date;
+}
+
+interface DraxAgentPromptContext {
+    session: DraxAgentSession;
+    input?: DraxAgentMessageInput;
+}
+
+export type {
+    DraxAgentConfig,
+    DraxAgentMessageInput,
+    DraxAgentMessageOutput,
+    DraxAgentPromptContext,
+    DraxAgentSession,
+    DraxAgentSessionInput,
+    DraxAgentSystemPrompt,
+    DraxAgentToolBuilder,
+    DraxAgentToolBuilderSource,
+    DraxAgentToolSource,
+};

package/src/interfaces/IDraxAgentController.ts

@@ -0,0 +1,5 @@
+interface DraxAgentControllerOptions {
+    permission?: string | false;
+}
+
+export type {DraxAgentControllerOptions};

package/src/interfaces/IDraxAgentRoutes.ts

@@ -0,0 +1,7 @@
+import type {DraxAgentControllerOptions} from "./IDraxAgentController.js";
+
+interface DraxAgentFastifyRoutesOptions extends DraxAgentControllerOptions {
+    prefix?: string;
+}
+
+export type {DraxAgentFastifyRoutesOptions};

package/src/models/AgentSessionModel.ts

@@ -0,0 +1,46 @@
+
+import {mongoose} from '@drax/common-back';
+import {PaginateModel} from "mongoose";
+import uniqueValidator from 'mongoose-unique-validator';
+import mongoosePaginate from 'mongoose-paginate-v2'
+import type {IAgentSession} from '../interfaces/IAgentSession'
+
+const AgentSessionSchema = new mongoose.Schema<IAgentSession>({
+            sessionId: {type: String,   required: true, index: true, unique: false },
+            title: {type: String,   required: false, index: false, unique: false },
+            lastMessageAt: {type: Date,   required: false, index: true, unique: false },
+            messages: [{ 
+                        role: {type: String,  enum: ['user', 'assistant', 'system'], required: true, index: false, unique: false },
+            content: {type: String,   required: true, index: false, unique: false },
+            createdAt: {type: Date,   required: false, index: false, unique: false } 
+            }],
+            messageCount: {type: Number,   required: false, index: false, unique: false },
+            inputTokens: {type: Number,   required: false, index: false, unique: false },
+            outputTokens: {type: Number,   required: false, index: false, unique: false },
+            tokens: {type: Number,   required: false, index: false, unique: false },
+            tenant: {type: mongoose.Schema.Types.ObjectId, ref: 'Tenant',  required: false, index: true, unique: false },
+            user: {type: mongoose.Schema.Types.ObjectId, ref: 'User',  required: false, index: true, unique: false }
+}, {timestamps: true});
+
+AgentSessionSchema.plugin(uniqueValidator, {message: 'validation.unique'});
+AgentSessionSchema.plugin(mongoosePaginate);
+
+AgentSessionSchema.virtual("id").get(function () {
+    return this._id.toString();
+});
+
+
+AgentSessionSchema.set('toJSON', {getters: true, virtuals: true});
+
+AgentSessionSchema.set('toObject', {getters: true, virtuals: true});
+
+const MODEL_NAME = 'AgentSession';
+const COLLECTION_NAME = 'AgentSession';
+const AgentSessionModel = mongoose.model<IAgentSession, PaginateModel<IAgentSession>>(MODEL_NAME, AgentSessionSchema,COLLECTION_NAME);
+
+export {
+    AgentSessionSchema,
+    AgentSessionModel
+}
+
+export default AgentSessionModel

package/src/permissions/AgentPermissions.ts

@@ -0,0 +1,10 @@
+
+enum AgentPermissions {
+
+    Session = "agent:session"
+
+}
+
+export { AgentPermissions };
+export default AgentPermissions;
+

package/src/permissions/AgentSessionPermissions.ts

@@ -0,0 +1,14 @@
+
+enum AgentSessionPermissions {
+
+    Create = "agentsession:create",
+    Update = "agentsession:update",
+    Delete = "agentsession:delete",
+    View = "agentsession:view",
+    Manage = "agentsession:manage"
+
+}
+
+export { AgentSessionPermissions };
+export default AgentSessionPermissions;
+

package/src/repository/mongo/AgentSessionMongoRepository.ts

@@ -0,0 +1,22 @@
+
+import {AbstractMongoRepository} from "@drax/crud-back";
+import {AgentSessionModel} from "../../models/AgentSessionModel.js";
+import type {IAgentSessionRepository} from '../../interfaces/IAgentSessionRepository'
+import type {IAgentSession, IAgentSessionBase} from "../../interfaces/IAgentSession";
+
+
+class AgentSessionMongoRepository extends AbstractMongoRepository<IAgentSession, IAgentSessionBase, IAgentSessionBase> implements IAgentSessionRepository {
+
+    constructor() {
+        super();
+        this._model = AgentSessionModel;
+        this._searchFields = ['sessionId', 'title'];
+        this._populateFields = ['tenant', 'user'];
+        this._lean = true
+    }
+
+}
+
+export default AgentSessionMongoRepository
+export {AgentSessionMongoRepository}
+

package/src/repository/sqlite/AgentSessionSqliteRepository.ts

@@ -0,0 +1,42 @@
+
+import {AbstractSqliteRepository} from "@drax/crud-back";
+import type {IAgentSessionRepository} from '../../interfaces/IAgentSessionRepository'
+import type {IAgentSession, IAgentSessionBase} from "../../interfaces/IAgentSession";
+import {SqliteTableField} from "@drax/common-back";
+
+class AgentSessionSqliteRepository extends AbstractSqliteRepository<IAgentSession, IAgentSessionBase, IAgentSessionBase> implements IAgentSessionRepository {
+
+    protected db: any;
+    protected tableName: string = 'AgentSession';
+    protected dataBaseFile: string;
+    protected searchFields: string[] = ['sessionId', 'title'];
+    protected booleanFields: string[] = [];
+    protected jsonFields: string[] = ['messages'];
+    protected identifier: string = '_id';
+    protected populateFields = [
+        { field: 'tenant', table: 'tenant', identifier: '_id' },
+{ field: 'user', table: 'user', identifier: '_id' }
+    ]
+    protected verbose: boolean = false;
+    protected tableFields: SqliteTableField[] = [
+        {name: "sessionId", type: "TEXT", unique: false, primary: false},
+{name: "title", type: "TEXT", unique: false, primary: false},
+{name: "lastMessageAt", type: "TEXT", unique: false, primary: false},
+{name: "messages", type: "TEXT", unique: false, primary: false},
+{name: "messageCount", type: "NUMERIC", unique: false, primary: false},
+{name: "messageCount", type: "TEXT", unique: false, primary: false},
+{name: "inputTokens", type: "NUMERIC", unique: false, primary: false},
+{name: "inputTokens", type: "TEXT", unique: false, primary: false},
+{name: "outputTokens", type: "NUMERIC", unique: false, primary: false},
+{name: "outputTokens", type: "TEXT", unique: false, primary: false},
+{name: "tokens", type: "NUMERIC", unique: false, primary: false},
+{name: "tokens", type: "TEXT", unique: false, primary: false},
+{name: "tenant", type: "TEXT", unique: false, primary: false},
+{name: "user", type: "TEXT", unique: false, primary: false}
+    ]
+  
+}
+
+export default AgentSessionSqliteRepository
+export {AgentSessionSqliteRepository}
+