@exulu/backend 1.53.1 → 1.54.0

package/dist/index.d.cts

@@ -65,6 +65,7 @@ interface ExuluAgent {
     source: "code" | "database";
     memory?: string;
     welcomemessage?: string;
+    defaultagent?: boolean;
     type: "agent";
     name: string;
     image?: string;
@@ -752,12 +753,14 @@ declare class ExuluProvider {
     get providerName(): string;
     get modelName(): string;
     tool: (instance: string, providers: ExuluProvider[], contexts: ExuluContext[], rerankers: ExuluReranker[]) => Promise<ExuluTool | null>;
-    generateSync: ({ prompt, req, user, session, inputMessages, currentTools, allExuluTools, statistics, toolConfigs, providerapikey, contexts, rerankers, exuluConfig, outputSchema, agent, instructions, }: {
+    generateSync: ({ prompt, req, user, session, inputMessages, approvedTools, currentTools, allExuluTools, statistics, toolConfigs, providerapikey, contexts, rerankers, exuluConfig, outputSchema, agent, instructions, maxStepCount, }: {
         prompt?: string;
         user?: User;
+        maxStepCount?: number;
         req?: Request;
         session?: string;
         agent?: ExuluAgent;
+        approvedTools?: string[];
         inputMessages?: UIMessage[];
         currentTools?: ExuluTool[];
         allExuluTools?: ExuluTool[];
@@ -778,10 +781,11 @@ declare class ExuluProvider {
      * - Image files -> image parts (which ARE supported by Responses API)
      */
     private processFilePartsInMessages;
-    generateStream: ({ user, session, agent, message, previousMessages, currentTools, approvedTools, allExuluTools, toolConfigs, providerapikey, contexts, rerankers, exuluConfig, instructions, req, }: {
+    generateStream: ({ user, session, agent, message, previousMessages, currentTools, approvedTools, allExuluTools, toolConfigs, providerapikey, contexts, rerankers, exuluConfig, instructions, req, maxStepCount }: {
         user?: User;
         session?: string;
         agent?: ExuluAgent;
+        maxStepCount?: number;
         message?: UIMessage;
         previousMessages?: UIMessage[];
         currentTools?: ExuluTool[];
@@ -988,6 +992,15 @@ declare class ExuluQueues {
 }
 declare const queues: ExuluQueues;
 
+/**
+ * Module-level registry so external callers (e.g. test scripts) can read
+ * the path of the most recently saved trajectory file.
+ * Works because both the trajectory logger and the test run in the same process.
+ */
+declare const trajectoryRegistry: {
+    lastFile: string | undefined;
+};
+
 /**
  * Represents the data structure for a chunk object.
  *
@@ -1899,7 +1912,9 @@ declare class MarkdownChunker {
      */
     private findLogicalBreakpoint;
     private headers;
-    chunk(text: string, chunkSize: number, prefix?: string): Promise<{
+    chunk(text: string, chunkSize: number, prefix?: string, config?: {
+        pageBreakTags?: boolean;
+    }): Promise<{
         text: string;
         page: number;
     }[]>;
@@ -2024,6 +2039,43 @@ declare function documentProcessor({ file, name, config }: {
     config?: DocumentProcessorConfig;
 }): Promise<ProcessedDocument | undefined>;
 
+/**
+ * Creates the v3 ExuluTool for agentic context retrieval.
+ *
+ * Compared to v2:
+ * - Single LLM call per step (vs two in v2)
+ * - Query classification upfront → strategy-based step budget (1–3 vs hardcoded 2)
+ * - Context example records sampled at init and cached
+ * - Strategy-specific instructions and tool sets
+ */
+declare function createAgenticRetrievalToolV3({ contexts, instructions: adminInstructions, rerankers, user, role, model, }: {
+    contexts: ExuluContext[];
+    rerankers: ExuluReranker[];
+    user?: User;
+    role?: string;
+    model?: LanguageModel;
+    instructions?: string;
+}): ExuluTool | undefined;
+
+/**
+ * Creates the V4 ExuluTool for agentic context retrieval.
+ *
+ * V4 uses an observe-infer-act loop with two primitive tools:
+ * - execute_query: raw PostgreSQL SELECT via db.raw (with embed() helper for semantic search)
+ * - grep: iterative search on large result files
+ *
+ * Unlike V3, there is no upfront query classification or strategy routing.
+ * The agent writes its own SQL and decides when it has found enough information.
+ */
+declare function createAgenticRetrievalToolV4({ contexts, instructions: adminInstructions, rerankers, user, role, model, }: {
+    contexts: ExuluContext[];
+    rerankers: ExuluReranker[];
+    user?: User;
+    role?: string;
+    model?: LanguageModel;
+    instructions?: string;
+}): ExuluTool | undefined;
+
 type JOB_STATUS = "completed" | "failed" | "delayed" | "active" | "waiting" | "paused" | "stuck";
 declare const JOB_STATUS_ENUM: {
     completed: string;
@@ -2038,6 +2090,16 @@ declare const JOB_STATUS_ENUM: {
 declare const ExuluJobs: {
     redis: typeof redisClient;
 };
+declare const ExuluDefaultTools: {
+    agentic: {
+        retrieval: {
+            create: {
+                v3: typeof createAgenticRetrievalToolV3;
+                v4: typeof createAgenticRetrievalToolV4;
+            };
+        };
+    };
+};
 declare const ExuluDefaultProviders: {
     anthropic: {
         opus4: ExuluProvider;
@@ -2123,4 +2185,4 @@ declare const ExuluPython: {
     instructions: typeof getPythonSetupInstructions;
 };
 
-export { type JOB_STATUS as EXULU_JOB_STATUS, JOB_STATUS_ENUM as EXULU_JOB_STATUS_ENUM, type STATISTICS_TYPE as EXULU_STATISTICS_TYPE, STATISTICS_TYPE_ENUM as EXULU_STATISTICS_TYPE_ENUM, type ExuluAgent, ExuluApp, ExuluAuthentication, ExuluChunkers, ExuluContext, ExuluDatabase, ExuluDefaultProviders, ExuluDocumentProcessor, ExuluEmbedder, ExuluEval, type Item as ExuluItem, ExuluJobs, ExuluOtel, ExuluProvider, ExuluPython, queues as ExuluQueues, ExuluReranker, ExuluTool, ExuluVariables };
+export { type JOB_STATUS as EXULU_JOB_STATUS, JOB_STATUS_ENUM as EXULU_JOB_STATUS_ENUM, type STATISTICS_TYPE as EXULU_STATISTICS_TYPE, STATISTICS_TYPE_ENUM as EXULU_STATISTICS_TYPE_ENUM, type ExuluAgent, ExuluApp, ExuluAuthentication, ExuluChunkers, ExuluContext, ExuluDatabase, ExuluDefaultProviders, ExuluDefaultTools, ExuluDocumentProcessor, ExuluEmbedder, ExuluEval, type Item as ExuluItem, ExuluJobs, ExuluOtel, ExuluProvider, ExuluPython, queues as ExuluQueues, ExuluReranker, ExuluTool, trajectoryRegistry as ExuluTrajectoryRegistry, ExuluVariables };

package/dist/index.d.ts

@@ -65,6 +65,7 @@ interface ExuluAgent {
     source: "code" | "database";
     memory?: string;
     welcomemessage?: string;
+    defaultagent?: boolean;
     type: "agent";
     name: string;
     image?: string;
@@ -752,12 +753,14 @@ declare class ExuluProvider {
     get providerName(): string;
     get modelName(): string;
     tool: (instance: string, providers: ExuluProvider[], contexts: ExuluContext[], rerankers: ExuluReranker[]) => Promise<ExuluTool | null>;
-    generateSync: ({ prompt, req, user, session, inputMessages, currentTools, allExuluTools, statistics, toolConfigs, providerapikey, contexts, rerankers, exuluConfig, outputSchema, agent, instructions, }: {
+    generateSync: ({ prompt, req, user, session, inputMessages, approvedTools, currentTools, allExuluTools, statistics, toolConfigs, providerapikey, contexts, rerankers, exuluConfig, outputSchema, agent, instructions, maxStepCount, }: {
         prompt?: string;
         user?: User;
+        maxStepCount?: number;
         req?: Request;
         session?: string;
         agent?: ExuluAgent;
+        approvedTools?: string[];
         inputMessages?: UIMessage[];
         currentTools?: ExuluTool[];
         allExuluTools?: ExuluTool[];
@@ -778,10 +781,11 @@ declare class ExuluProvider {
      * - Image files -> image parts (which ARE supported by Responses API)
      */
     private processFilePartsInMessages;
-    generateStream: ({ user, session, agent, message, previousMessages, currentTools, approvedTools, allExuluTools, toolConfigs, providerapikey, contexts, rerankers, exuluConfig, instructions, req, }: {
+    generateStream: ({ user, session, agent, message, previousMessages, currentTools, approvedTools, allExuluTools, toolConfigs, providerapikey, contexts, rerankers, exuluConfig, instructions, req, maxStepCount }: {
         user?: User;
         session?: string;
         agent?: ExuluAgent;
+        maxStepCount?: number;
         message?: UIMessage;
         previousMessages?: UIMessage[];
         currentTools?: ExuluTool[];
@@ -988,6 +992,15 @@ declare class ExuluQueues {
 }
 declare const queues: ExuluQueues;
 
+/**
+ * Module-level registry so external callers (e.g. test scripts) can read
+ * the path of the most recently saved trajectory file.
+ * Works because both the trajectory logger and the test run in the same process.
+ */
+declare const trajectoryRegistry: {
+    lastFile: string | undefined;
+};
+
 /**
  * Represents the data structure for a chunk object.
  *
@@ -1899,7 +1912,9 @@ declare class MarkdownChunker {
      */
     private findLogicalBreakpoint;
     private headers;
-    chunk(text: string, chunkSize: number, prefix?: string): Promise<{
+    chunk(text: string, chunkSize: number, prefix?: string, config?: {
+        pageBreakTags?: boolean;
+    }): Promise<{
         text: string;
         page: number;
     }[]>;
@@ -2024,6 +2039,43 @@ declare function documentProcessor({ file, name, config }: {
     config?: DocumentProcessorConfig;
 }): Promise<ProcessedDocument | undefined>;
 
+/**
+ * Creates the v3 ExuluTool for agentic context retrieval.
+ *
+ * Compared to v2:
+ * - Single LLM call per step (vs two in v2)
+ * - Query classification upfront → strategy-based step budget (1–3 vs hardcoded 2)
+ * - Context example records sampled at init and cached
+ * - Strategy-specific instructions and tool sets
+ */
+declare function createAgenticRetrievalToolV3({ contexts, instructions: adminInstructions, rerankers, user, role, model, }: {
+    contexts: ExuluContext[];
+    rerankers: ExuluReranker[];
+    user?: User;
+    role?: string;
+    model?: LanguageModel;
+    instructions?: string;
+}): ExuluTool | undefined;
+
+/**
+ * Creates the V4 ExuluTool for agentic context retrieval.
+ *
+ * V4 uses an observe-infer-act loop with two primitive tools:
+ * - execute_query: raw PostgreSQL SELECT via db.raw (with embed() helper for semantic search)
+ * - grep: iterative search on large result files
+ *
+ * Unlike V3, there is no upfront query classification or strategy routing.
+ * The agent writes its own SQL and decides when it has found enough information.
+ */
+declare function createAgenticRetrievalToolV4({ contexts, instructions: adminInstructions, rerankers, user, role, model, }: {
+    contexts: ExuluContext[];
+    rerankers: ExuluReranker[];
+    user?: User;
+    role?: string;
+    model?: LanguageModel;
+    instructions?: string;
+}): ExuluTool | undefined;
+
 type JOB_STATUS = "completed" | "failed" | "delayed" | "active" | "waiting" | "paused" | "stuck";
 declare const JOB_STATUS_ENUM: {
     completed: string;
@@ -2038,6 +2090,16 @@ declare const JOB_STATUS_ENUM: {
 declare const ExuluJobs: {
     redis: typeof redisClient;
 };
+declare const ExuluDefaultTools: {
+    agentic: {
+        retrieval: {
+            create: {
+                v3: typeof createAgenticRetrievalToolV3;
+                v4: typeof createAgenticRetrievalToolV4;
+            };
+        };
+    };
+};
 declare const ExuluDefaultProviders: {
     anthropic: {
         opus4: ExuluProvider;
@@ -2123,4 +2185,4 @@ declare const ExuluPython: {
     instructions: typeof getPythonSetupInstructions;
 };
 
-export { type JOB_STATUS as EXULU_JOB_STATUS, JOB_STATUS_ENUM as EXULU_JOB_STATUS_ENUM, type STATISTICS_TYPE as EXULU_STATISTICS_TYPE, STATISTICS_TYPE_ENUM as EXULU_STATISTICS_TYPE_ENUM, type ExuluAgent, ExuluApp, ExuluAuthentication, ExuluChunkers, ExuluContext, ExuluDatabase, ExuluDefaultProviders, ExuluDocumentProcessor, ExuluEmbedder, ExuluEval, type Item as ExuluItem, ExuluJobs, ExuluOtel, ExuluProvider, ExuluPython, queues as ExuluQueues, ExuluReranker, ExuluTool, ExuluVariables };
+export { type JOB_STATUS as EXULU_JOB_STATUS, JOB_STATUS_ENUM as EXULU_JOB_STATUS_ENUM, type STATISTICS_TYPE as EXULU_STATISTICS_TYPE, STATISTICS_TYPE_ENUM as EXULU_STATISTICS_TYPE_ENUM, type ExuluAgent, ExuluApp, ExuluAuthentication, ExuluChunkers, ExuluContext, ExuluDatabase, ExuluDefaultProviders, ExuluDefaultTools, ExuluDocumentProcessor, ExuluEmbedder, ExuluEval, type Item as ExuluItem, ExuluJobs, ExuluOtel, ExuluProvider, ExuluPython, queues as ExuluQueues, ExuluReranker, ExuluTool, trajectoryRegistry as ExuluTrajectoryRegistry, ExuluVariables };