agent-swarm-kit 1.0.12 → 1.0.14

package/README.md

@@ -1,6 +1,6 @@
 # 🐝 agent-swarm-kit
 
-> A TypeScript library for building orchestrated framework-agnostic multi-agent AI systems
+> A TypeScript library for building orchestrated framework-agnostic multi-agent AI systems. Documentation [available in docs folder](https://github.com/tripolskypetr/agent-swarm-kit/tree/master/docs)
 
 ## Installation
 
@@ -10,6 +10,109 @@ In comparison with langchain js this library provide the lightweight API so you
 npm install agent-swarm-kit
 ```
 
+## The Idea
+
+1. Several chatgpt sessions (agents) [execute tool calls](https://ollama.com/blog/tool-support). Each agent can use different model, for example, [mistral 7b](https://ollama.com/library/mistral) for small talk, [nemotron](https://ollama.com/library/nemotron) for business conversation
+
+2. The agent swarm navigate messages to the active chatgpt session (agent) for each `WebSocket` channel [by using `clientId` url parameter](src/routes/session.ts#L5)
+
+3. The active chatgpt session (agent) in the swarm could be changed [by executing function tool](https://platform.openai.com/docs/assistants/tools/function-calling) 
+
+4. Each client sessions [share the same chat message history](https://platform.openai.com/docs/api-reference/messages/getMessage) for all agents. Each client chat history keep the last 25 messages with rotation. Only `assistant` and `user` messages are shared between chatgpt sessions (agents), the `system` and `tool` messages are agent-scoped so each agent knows only those tools related to It. As a result, each chatgpt session (agent) has it's [unique system prompt](https://platform.openai.com/docs/api-reference/messages/createMessage#messages-createmessage-role)
+
+5. If the agent output do not pass the validation (not existing tool call, tool call with invalid arguments, empty output, XML tags in output or JSON in output by default), the resque algorithm will try to fix the model. At first it will hide the previos messeges from a model, if this will not help, it return a placeholder like `Sorry, I missed that. Could you say it again?`
+
+## Test Cases
+
+### Validation Test Cases
+
+1. **Passes validation when all dependencies are provided**
+   - Tests if validation passes when all dependencies are present.
+
+2. **Fails validation when swarm is missing**
+   - Tests if validation fails when the swarm is missing.
+
+3. **Fails validation when completion is missing**
+   - Tests if validation fails when the completion is missing.
+
+4. **Fails validation when agent is missing**
+   - Tests if validation fails when the agent is missing.
+
+5. **Fails validation when tool is missing**
+   - Tests if validation fails when the tool is missing.
+
+6. **Fails validation when swarm's default agent is not in the list**
+   - Tests if validation fails when the swarm's default agent is not included in the list.
+
+### Model Recovery Test Cases
+
+7. **Rescues model on non-existing tool call**
+   - Tests if the model can recover when a non-existing tool is called.
+
+8. **Rescues model on empty output**
+   - Tests if the model can recover when the output is empty.
+
+9. **Rescues model on failed tool validation**
+   - Tests if the model can recover when tool validation fails.
+
+10. **Failed rescue raises a placeholder**
+    - Tests if a placeholder is returned when the rescue algorithm fails.
+
+### Navigation Test Cases
+
+11. **Navigates to sales agent on request**
+    - Tests if the system navigates to the sales agent upon request.
+
+12. **Navigates to refund agent on request**
+    - Tests if the system navigates to the refund agent upon request.
+
+### Deadlock Prevention Test Cases
+
+13. **Avoids deadlock if commitToolOutput was not executed before navigation**
+    - Tests if the system avoids deadlock when commitToolOutput is not executed before navigation.
+
+14. **Avoids deadlock when commitToolOutput is executed in parallel with next completion**
+    - Tests if the system avoids deadlock when commitToolOutput is executed in parallel with the next completion.
+
+### Agent Execution Test Cases
+
+15. **Ignores execution due to obsolete agent**
+    - Tests if the system ignores execution due to an obsolete agent.
+
+16. **Ignores commitToolOutput due to obsolete agent**
+    - Tests if the system ignores commitToolOutput due to an obsolete agent.
+
+17. **Ignores commitSystemMessage due to obsolete agent**
+    - Tests if the system ignores commitSystemMessage due to an obsolete agent.
+
+### Connection Disposal Test Cases
+
+18. **Disposes connections for session function**
+    - Tests if the system disposes of connections for the session function.
+
+19. **Disposes connections for makeConnection function**
+    - Tests if the system disposes of connections for the makeConnection function.
+
+20. **Disposes connections for complete function**
+    - Tests if the system disposes of connections for the complete function.
+
+### Additional System Behavior Test Cases
+
+21. **Uses different completions on multiple agents**
+    - Tests if the system uses different completions for multiple agents.
+
+22. **Clears history for similar clientId after each parallel complete call**
+    - Tests if the system clears history for similar clientId after each parallel complete call.
+
+23. **Orchestrates swarms for each connection**
+    - Tests if the system orchestrates swarms for each connection.
+
+24. **Queues user messages in connection**
+    - Tests if the system queues user messages in connection.
+
+25. **Allows server-side emit for makeConnection**
+    - Tests if the system allows server-side emit for makeConnection.
+
 ## Code sample
 
 ```tsx

package/build/index.cjs

@@ -425,7 +425,7 @@ var ClientAgent = /** @class */ (function () {
                                     case 1:
                                         _f.sent();
                                         if (!!targetFn) return [3 /*break*/, 4];
-                                        this_1.params.logger.debug("ClientAgent agentName=".concat(this_1.params.agentName, " clientId=").concat(this_1.params.clientId, " functionName=").concat(tool.function.name, " tool function not found"));
+                                        this_1.params.logger.debug("ClientAgent agentName=".concat(this_1.params.agentName, " clientId=").concat(this_1.params.clientId, " functionName=").concat(tool.function.name, " tool function not found"), this_1.params.tools);
                                         return [4 /*yield*/, this_1._resurrectModel("No target function for ".concat(tool.function.name))];
                                     case 2:
                                         result_2 = _f.sent();
@@ -522,7 +522,9 @@ var ClientAgent = /** @class */ (function () {
                 }
             });
         }); });
-        this.params.logger.debug("ClientAgent agentName=".concat(this.params.agentName, " clientId=").concat(this.params.clientId, " CTOR"));
+        this.params.logger.debug("ClientAgent agentName=".concat(this.params.agentName, " clientId=").concat(this.params.clientId, " CTOR"), {
+            params: params,
+        });
     }
     return ClientAgent;
 }());
@@ -848,7 +850,9 @@ var ClientHistory = /** @class */ (function () {
                 }
             });
         }); };
-        this.params.logger.debug("ClientHistory agentName=".concat(this.params.agentName, " clientId=").concat(this.params.clientId, " CTOR"));
+        this.params.logger.debug("ClientHistory agentName=".concat(this.params.agentName, " clientId=").concat(this.params.clientId, " CTOR"), {
+            params: params,
+        });
     }
     return ClientHistory;
 }());
@@ -1044,7 +1048,9 @@ var ClientSwarm = /** @class */ (function () {
                 return [2 /*return*/];
             });
         }); };
-        this.params.logger.debug("ClientSwarm swarmName=".concat(this.params.swarmName, " clientId=").concat(this.params.clientId, " CTOR"));
+        this.params.logger.debug("ClientSwarm swarmName=".concat(this.params.swarmName, " clientId=").concat(this.params.clientId, " CTOR"), {
+            params: params,
+        });
         this._activeAgent = params.defaultAgent;
     }
     return ClientSwarm;
@@ -1308,7 +1314,9 @@ var ClientSession = /** @class */ (function () {
                 });
             }); };
         };
-        this.params.logger.debug("ClientSession clientId=".concat(this.params.clientId, " CTOR"));
+        this.params.logger.debug("ClientSession clientId=".concat(this.params.clientId, " CTOR"), {
+            params: params,
+        });
     }
     return ClientSession;
 }());
@@ -2318,30 +2326,46 @@ var swarm = __assign(__assign(__assign(__assign(__assign({}, baseServices), conn
 init();
 
 var addAgent = function (agentSchema) {
+    swarm.loggerService.log('function addAgent', {
+        agentSchema: agentSchema
+    });
     swarm.agentValidationService.addAgent(agentSchema.agentName, agentSchema);
     swarm.agentSchemaService.register(agentSchema.agentName, agentSchema);
     return agentSchema.agentName;
 };
 
 var addCompletion = function (completionSchema) {
+    swarm.loggerService.log('function addCompletion', {
+        completionSchema: completionSchema,
+    });
     swarm.completionValidationService.addCompletion(completionSchema.completionName);
     swarm.completionSchemaService.register(completionSchema.completionName, completionSchema);
     return completionSchema.completionName;
 };
 
 var addSwarm = function (swarmSchema) {
+    swarm.loggerService.log('function addSwarm', {
+        swarmSchema: swarmSchema,
+    });
     swarm.swarmValidationService.addSwarm(swarmSchema.swarmName, swarmSchema);
     swarm.swarmSchemaService.register(swarmSchema.swarmName, swarmSchema);
     return swarmSchema.swarmName;
 };
 
 var addTool = function (toolSchema) {
+    swarm.loggerService.log('function addTool', {
+        toolSchema: toolSchema,
+    });
     swarm.toolValidationService.addTool(toolSchema.toolName, toolSchema);
     swarm.toolSchemaService.register(toolSchema.toolName, toolSchema);
     return toolSchema.toolName;
 };
 
 var makeConnection = function (connector, clientId, swarmName) {
+    swarm.loggerService.log("function makeConnection", {
+        clientId: clientId,
+        swarmName: swarmName,
+    });
     swarm.swarmValidationService.validate(swarmName, "makeConnection");
     swarm.sessionValidationService.addSession(clientId, swarmName);
     var send = swarm.sessionPublicService.connect(connector, clientId, swarmName);
@@ -2415,7 +2439,12 @@ var changeAgent = function (agentName, clientId) { return __awaiter(void 0, void
     var run;
     return __generator(this, function (_a) {
         switch (_a.label) {
-            case 0: return [4 /*yield*/, createChangeAgent(clientId)];
+            case 0:
+                swarm.loggerService.log('function changeAgent', {
+                    agentName: agentName,
+                    clientId: clientId,
+                });
+                return [4 /*yield*/, createChangeAgent(clientId)];
             case 1:
                 run = _a.sent();
                 createGc$1();
@@ -2429,6 +2458,10 @@ var disposeConnection = function (clientId, swarmName) { return __awaiter(void 0
     return __generator(this, function (_a) {
         switch (_a.label) {
             case 0:
+                swarm.loggerService.log("function disposeConnection", {
+                    clientId: clientId,
+                    swarmName: swarmName,
+                });
                 swarm.swarmValidationService.validate(swarmName, "disposeConnection");
                 swarm.sessionValidationService.removeSession(clientId);
                 return [4 /*yield*/, swarm.sessionPublicService.dispose(clientId, swarmName)];
@@ -2498,7 +2531,13 @@ var complete = function (content, clientId, swarmName) { return __awaiter(void 0
     var run;
     return __generator(this, function (_a) {
         switch (_a.label) {
-            case 0: return [4 /*yield*/, createComplete(clientId, swarmName)];
+            case 0:
+                swarm.loggerService.log("function complete", {
+                    content: content,
+                    clientId: clientId,
+                    swarmName: swarmName,
+                });
+                return [4 /*yield*/, createComplete(clientId, swarmName)];
             case 1:
                 run = _a.sent();
                 createGc();
@@ -2509,6 +2548,10 @@ var complete = function (content, clientId, swarmName) { return __awaiter(void 0
 }); };
 
 var session = function (clientId, swarmName) {
+    swarm.loggerService.log("function session", {
+        clientId: clientId,
+        swarmName: swarmName,
+    });
     swarm.swarmValidationService.validate(swarmName, "session");
     swarm.sessionValidationService.addSession(clientId, swarmName);
     return {
@@ -2538,6 +2581,9 @@ var getRawHistory = function (clientId) { return __awaiter(void 0, void 0, void
     return __generator(this, function (_a) {
         switch (_a.label) {
             case 0:
+                swarm.loggerService.log("function getRawHistory", {
+                    clientId: clientId,
+                });
                 swarm.sessionValidationService.validate(clientId, "getRawHistory");
                 swarmName = swarm.sessionValidationService.getSwarm(clientId);
                 swarm.swarmValidationService.validate(swarmName, "getRawHistory");
@@ -2557,6 +2603,10 @@ var getAgentHistory = function (clientId, agentName) { return __awaiter(void 0,
     return __generator(this, function (_a) {
         switch (_a.label) {
             case 0:
+                swarm.loggerService.log("function getAgentHistory", {
+                    clientId: clientId,
+                    agentName: agentName,
+                });
                 swarm.agentValidationService.validate(agentName, "getAgentHistory");
                 prompt = swarm.agentSchemaService.get(agentName).prompt;
                 return [4 /*yield*/, swarm.historyPublicService.toArrayForAgent(prompt, clientId, agentName)];
@@ -2572,6 +2622,11 @@ var commitToolOutput = function (content, clientId, agentName) { return __awaite
     return __generator(this, function (_a) {
         switch (_a.label) {
             case 0:
+                swarm.loggerService.log('function commitToolOutput', {
+                    content: content,
+                    clientId: clientId,
+                    agentName: agentName,
+                });
                 swarm.agentValidationService.validate(agentName, "commitSystemMessage");
                 swarm.sessionValidationService.validate(clientId, "commitToolOutput");
                 swarmName = swarm.sessionValidationService.getSwarm(clientId);
@@ -2600,6 +2655,11 @@ var commitSystemMessage = function (content, clientId, agentName) { return __awa
     return __generator(this, function (_a) {
         switch (_a.label) {
             case 0:
+                swarm.loggerService.log('function commitSystemMessage', {
+                    content: content,
+                    clientId: clientId,
+                    agentName: agentName,
+                });
                 swarm.agentValidationService.validate(agentName, "commitSystemMessage");
                 swarm.sessionValidationService.validate(clientId, "commitSystemMessage");
                 swarmName = swarm.sessionValidationService.getSwarm(clientId);
@@ -2628,6 +2688,11 @@ var execute = function (content, clientId, agentName) { return __awaiter(void 0,
     return __generator(this, function (_a) {
         switch (_a.label) {
             case 0:
+                swarm.loggerService.log("function execute", {
+                    content: content,
+                    clientId: clientId,
+                    agentName: agentName,
+                });
                 swarm.agentValidationService.validate(agentName, "commitSystemMessage");
                 swarm.sessionValidationService.validate(clientId, "execute");
                 swarmName = swarm.sessionValidationService.getSwarm(clientId);

package/build/index.mjs

@@ -423,7 +423,7 @@ var ClientAgent = /** @class */ (function () {
                                     case 1:
                                         _f.sent();
                                         if (!!targetFn) return [3 /*break*/, 4];
-                                        this_1.params.logger.debug("ClientAgent agentName=".concat(this_1.params.agentName, " clientId=").concat(this_1.params.clientId, " functionName=").concat(tool.function.name, " tool function not found"));
+                                        this_1.params.logger.debug("ClientAgent agentName=".concat(this_1.params.agentName, " clientId=").concat(this_1.params.clientId, " functionName=").concat(tool.function.name, " tool function not found"), this_1.params.tools);
                                         return [4 /*yield*/, this_1._resurrectModel("No target function for ".concat(tool.function.name))];
                                     case 2:
                                         result_2 = _f.sent();
@@ -520,7 +520,9 @@ var ClientAgent = /** @class */ (function () {
                 }
             });
         }); });
-        this.params.logger.debug("ClientAgent agentName=".concat(this.params.agentName, " clientId=").concat(this.params.clientId, " CTOR"));
+        this.params.logger.debug("ClientAgent agentName=".concat(this.params.agentName, " clientId=").concat(this.params.clientId, " CTOR"), {
+            params: params,
+        });
     }
     return ClientAgent;
 }());
@@ -846,7 +848,9 @@ var ClientHistory = /** @class */ (function () {
                 }
             });
         }); };
-        this.params.logger.debug("ClientHistory agentName=".concat(this.params.agentName, " clientId=").concat(this.params.clientId, " CTOR"));
+        this.params.logger.debug("ClientHistory agentName=".concat(this.params.agentName, " clientId=").concat(this.params.clientId, " CTOR"), {
+            params: params,
+        });
     }
     return ClientHistory;
 }());
@@ -1042,7 +1046,9 @@ var ClientSwarm = /** @class */ (function () {
                 return [2 /*return*/];
             });
         }); };
-        this.params.logger.debug("ClientSwarm swarmName=".concat(this.params.swarmName, " clientId=").concat(this.params.clientId, " CTOR"));
+        this.params.logger.debug("ClientSwarm swarmName=".concat(this.params.swarmName, " clientId=").concat(this.params.clientId, " CTOR"), {
+            params: params,
+        });
         this._activeAgent = params.defaultAgent;
     }
     return ClientSwarm;
@@ -1306,7 +1312,9 @@ var ClientSession = /** @class */ (function () {
                 });
             }); };
         };
-        this.params.logger.debug("ClientSession clientId=".concat(this.params.clientId, " CTOR"));
+        this.params.logger.debug("ClientSession clientId=".concat(this.params.clientId, " CTOR"), {
+            params: params,
+        });
     }
     return ClientSession;
 }());
@@ -2316,30 +2324,46 @@ var swarm = __assign(__assign(__assign(__assign(__assign({}, baseServices), conn
 init();
 
 var addAgent = function (agentSchema) {
+    swarm.loggerService.log('function addAgent', {
+        agentSchema: agentSchema
+    });
     swarm.agentValidationService.addAgent(agentSchema.agentName, agentSchema);
     swarm.agentSchemaService.register(agentSchema.agentName, agentSchema);
     return agentSchema.agentName;
 };
 
 var addCompletion = function (completionSchema) {
+    swarm.loggerService.log('function addCompletion', {
+        completionSchema: completionSchema,
+    });
     swarm.completionValidationService.addCompletion(completionSchema.completionName);
     swarm.completionSchemaService.register(completionSchema.completionName, completionSchema);
     return completionSchema.completionName;
 };
 
 var addSwarm = function (swarmSchema) {
+    swarm.loggerService.log('function addSwarm', {
+        swarmSchema: swarmSchema,
+    });
     swarm.swarmValidationService.addSwarm(swarmSchema.swarmName, swarmSchema);
     swarm.swarmSchemaService.register(swarmSchema.swarmName, swarmSchema);
     return swarmSchema.swarmName;
 };
 
 var addTool = function (toolSchema) {
+    swarm.loggerService.log('function addTool', {
+        toolSchema: toolSchema,
+    });
     swarm.toolValidationService.addTool(toolSchema.toolName, toolSchema);
     swarm.toolSchemaService.register(toolSchema.toolName, toolSchema);
     return toolSchema.toolName;
 };
 
 var makeConnection = function (connector, clientId, swarmName) {
+    swarm.loggerService.log("function makeConnection", {
+        clientId: clientId,
+        swarmName: swarmName,
+    });
     swarm.swarmValidationService.validate(swarmName, "makeConnection");
     swarm.sessionValidationService.addSession(clientId, swarmName);
     var send = swarm.sessionPublicService.connect(connector, clientId, swarmName);
@@ -2413,7 +2437,12 @@ var changeAgent = function (agentName, clientId) { return __awaiter(void 0, void
     var run;
     return __generator(this, function (_a) {
         switch (_a.label) {
-            case 0: return [4 /*yield*/, createChangeAgent(clientId)];
+            case 0:
+                swarm.loggerService.log('function changeAgent', {
+                    agentName: agentName,
+                    clientId: clientId,
+                });
+                return [4 /*yield*/, createChangeAgent(clientId)];
             case 1:
                 run = _a.sent();
                 createGc$1();
@@ -2427,6 +2456,10 @@ var disposeConnection = function (clientId, swarmName) { return __awaiter(void 0
     return __generator(this, function (_a) {
         switch (_a.label) {
             case 0:
+                swarm.loggerService.log("function disposeConnection", {
+                    clientId: clientId,
+                    swarmName: swarmName,
+                });
                 swarm.swarmValidationService.validate(swarmName, "disposeConnection");
                 swarm.sessionValidationService.removeSession(clientId);
                 return [4 /*yield*/, swarm.sessionPublicService.dispose(clientId, swarmName)];
@@ -2496,7 +2529,13 @@ var complete = function (content, clientId, swarmName) { return __awaiter(void 0
     var run;
     return __generator(this, function (_a) {
         switch (_a.label) {
-            case 0: return [4 /*yield*/, createComplete(clientId, swarmName)];
+            case 0:
+                swarm.loggerService.log("function complete", {
+                    content: content,
+                    clientId: clientId,
+                    swarmName: swarmName,
+                });
+                return [4 /*yield*/, createComplete(clientId, swarmName)];
             case 1:
                 run = _a.sent();
                 createGc();
@@ -2507,6 +2546,10 @@ var complete = function (content, clientId, swarmName) { return __awaiter(void 0
 }); };
 
 var session = function (clientId, swarmName) {
+    swarm.loggerService.log("function session", {
+        clientId: clientId,
+        swarmName: swarmName,
+    });
     swarm.swarmValidationService.validate(swarmName, "session");
     swarm.sessionValidationService.addSession(clientId, swarmName);
     return {
@@ -2536,6 +2579,9 @@ var getRawHistory = function (clientId) { return __awaiter(void 0, void 0, void
     return __generator(this, function (_a) {
         switch (_a.label) {
             case 0:
+                swarm.loggerService.log("function getRawHistory", {
+                    clientId: clientId,
+                });
                 swarm.sessionValidationService.validate(clientId, "getRawHistory");
                 swarmName = swarm.sessionValidationService.getSwarm(clientId);
                 swarm.swarmValidationService.validate(swarmName, "getRawHistory");
@@ -2555,6 +2601,10 @@ var getAgentHistory = function (clientId, agentName) { return __awaiter(void 0,
     return __generator(this, function (_a) {
         switch (_a.label) {
             case 0:
+                swarm.loggerService.log("function getAgentHistory", {
+                    clientId: clientId,
+                    agentName: agentName,
+                });
                 swarm.agentValidationService.validate(agentName, "getAgentHistory");
                 prompt = swarm.agentSchemaService.get(agentName).prompt;
                 return [4 /*yield*/, swarm.historyPublicService.toArrayForAgent(prompt, clientId, agentName)];
@@ -2570,6 +2620,11 @@ var commitToolOutput = function (content, clientId, agentName) { return __awaite
     return __generator(this, function (_a) {
         switch (_a.label) {
             case 0:
+                swarm.loggerService.log('function commitToolOutput', {
+                    content: content,
+                    clientId: clientId,
+                    agentName: agentName,
+                });
                 swarm.agentValidationService.validate(agentName, "commitSystemMessage");
                 swarm.sessionValidationService.validate(clientId, "commitToolOutput");
                 swarmName = swarm.sessionValidationService.getSwarm(clientId);
@@ -2598,6 +2653,11 @@ var commitSystemMessage = function (content, clientId, agentName) { return __awa
     return __generator(this, function (_a) {
         switch (_a.label) {
             case 0:
+                swarm.loggerService.log('function commitSystemMessage', {
+                    content: content,
+                    clientId: clientId,
+                    agentName: agentName,
+                });
                 swarm.agentValidationService.validate(agentName, "commitSystemMessage");
                 swarm.sessionValidationService.validate(clientId, "commitSystemMessage");
                 swarmName = swarm.sessionValidationService.getSwarm(clientId);
@@ -2626,6 +2686,11 @@ var execute = function (content, clientId, agentName) { return __awaiter(void 0,
     return __generator(this, function (_a) {
         switch (_a.label) {
             case 0:
+                swarm.loggerService.log("function execute", {
+                    content: content,
+                    clientId: clientId,
+                    agentName: agentName,
+                });
                 swarm.agentValidationService.validate(agentName, "commitSystemMessage");
                 swarm.sessionValidationService.validate(clientId, "execute");
                 swarmName = swarm.sessionValidationService.getSwarm(clientId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-swarm-kit",
-  "version": "1.0.12",
+  "version": "1.0.14",
   "description": "A TypeScript library for building orchestrated framework-agnostic multi-agent AI systems",
   "author": {
     "name": "Petr Tripolsky",