agent-swarm-kit 1.0.159 → 1.0.161

package/README.md

@@ -1,123 +1,40 @@
-# 🐝 agent-swarm-kit
+# 🐝 Agent Swarm Kit
 
-> 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)
+> **A lightweight TypeScript library for building orchestrated, framework-agnostic multi-agent AI systems.**
 
-![schema](./schema.png)
+Unleash the power of collaborative AI with `agent-swarm-kit`! This library empowers you to create intelligent, modular agent networks that work together seamlessly—perfect for automating workflows, solving complex problems, or designing next-gen AI systems. With a simple API, robust validation, and flexible architecture, it’s your toolkit for building smarter solutions, faster.
 
-## Installation
+📚 **[Full Documentation](https://github.com/tripolskypetr/agent-swarm-kit/tree/master/docs)** | 🌟 **[Try It Now](#getting-started)**
 
-In comparison with langchain js this library provide the lightweight API so you can delegate the prompt engineering to other junior developers. It support message scheduling so user can interrupt the ai agent with additional details in few messages
+![Agent Swarm Schema](https://raw.githubusercontent.com/tripolskypetr/agent-swarm-kit/master/schema.png)
 
-```bash
-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.
+## ✨ Why Choose Agent Swarm Kit?
 
-9. **Rescues model on failed tool validation**
-   - Tests if the model can recover when tool validation fails.
+- **Multi-Agent Collaboration**: Orchestrate multiple AI agents, each with unique roles—like triage, sales, or refunds—working as a team.
+- **Lightweight & Flexible**: Unlike bulky frameworks, our API is simple and delegates prompt engineering to your team.
+- **Framework-Agnostic**: Works with any AI model—OpenAI, Ollama, Mistral, Nemotron, you name it!
+- **Robust Validation**: Built-in checks ensure tools, agents, and outputs are always on point.
+- **Real-Time Interaction**: Supports message scheduling and WebSocket channels for dynamic user input.
 
-10. **Failed rescue raises a placeholder**
-    - Tests if a placeholder is returned when the rescue algorithm fails.
+---
 
-### Navigation Test Cases
+## 🚀 Getting Started
 
-11. **Navigates to sales agent on request**
-    - Tests if the system navigates to the sales agent upon request.
+### Installation
 
-12. **Navigates to refund agent on request**
-    - Tests if the system navigates to the refund agent upon request.
+Get up and running in seconds:
 
-### 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.
+```bash
+npm install agent-swarm-kit
+```
 
-25. **Allows server-side emit for makeConnection**
-    - Tests if the system allows server-side emit for makeConnection.
+### Quick Example
 
-## Code sample
+Here’s a taste of what `agent-swarm-kit` can do—create a swarm with a triage agent that navigates to specialized agents:
 
-```tsx
+```typescript
 import {
   addAgent,
   addCompletion,
@@ -163,7 +80,7 @@ const MOCK_COMPLETION = addCompletion({
    * @see https://github.com/tripolskypetr/agent-swarm-kit/tree/master/test
    */
   getCompletion: async ({ messages, tools }) => {
-    return ollama.chat({
+    return await ollama.chat({
       model: CC_OLLAMA_CHAT_MODEL,
       keep_alive: "1h",
       messages,
@@ -201,7 +118,6 @@ const TEST_SWARM = addSwarm({
 
 ...
 
-
 app.get("/api/v1/session/:clientId", upgradeWebSocket((ctx) => {
   const clientId = ctx.req.param("clientId");
 
@@ -222,48 +138,178 @@ app.get("/api/v1/session/:clientId", upgradeWebSocket((ctx) => {
 
 The feature of this library is dependency inversion for agents injection. The agents are being lazy loaded during runtime, so you can declare them in separate modules and connect them to swarm with a string constant
 
-```tsx
+```typescript
+export enum ToolName {
+  TestTool = "test-tool",
+}
+
+export enum AgentName {
+  TestAgent = "test-agent",
+}
+
+export enum CompletionName {
+  TestCompletion = "test-completion"
+}
+
+export enum SwarmName {
+  TestSwarm = "test-swarm"
+}
+
+...
 
 addTool({
-    toolName: "test-tool",
+    toolName: ToolName.TestTool
     ...
 })
 
 addAgent({
-  agentName: "test-agent",
-  completion: "openai-completion",
+  agentName: AgentName.TestAgent,
+  completion: CompletionName.TestCompletion,
   prompt: "...",
-  tools: ["test-tool"],
+  tools: [ToolName.TestTool],
 });
 
 addSwarm({
-  agentList: ["test-agent"],
-  defaultAgent: "test-agent",
-  swarmName: "test-swarm",
+  agentList: [AgentName.TestAgent],
+  defaultAgent: AgentName.TestAgent,
+  swarmName: SwarmName.TestSwarm,
 });
 
-const { complete, dispose } = session(clientId, "test-swarm")
+const { complete, dispose } = session(clientId, SwarmName.TestSwarm)
 ```
 
-## Briefing
+---
+
+## 🌟 Key Features
+
+- **Agent Orchestration**: Seamlessly switch between agents (e.g., triage → sales) with a single tool call.
+- **Shared History**: Agents share a rotating 25-message history, scoped to `assistant` and `user` roles.
+- **Custom Tools**: Define tools with validation and execution logic tailored to your needs.
+- **Model Recovery**: Automatically rescues invalid outputs with smart fallbacks like "Sorry, I missed that."
+- **Dependency Inversion**: Lazy-load agents at runtime for modular, scalable designs.
+
+---
+
+## 🎯 Use Cases
+
+- **Workflow Automation**: Automate customer support with triage, sales, and refund agents.
+- **Collaborative AI**: Build systems where agents solve problems together.
+- **Task Distribution**: Assign specialized tasks to dedicated agents.
+- **Chatbots & Beyond**: Create dynamic, multi-role conversational systems.
+
+---
+
+## 📖 API Highlights
+
+- **`addAgent`**: Define agents with custom prompts, tools, and completions.
+- **`addSwarm`**: Group agents into a coordinated network.
+- **`session`**: Start a client session with real-time message handling.
+- **`addTool`**: Create reusable tools with validation and execution logic.
+- **`Storage.take`**: Search and retrieve data using embeddings (e.g., vector search).
+
+Check out the **[API Reference](https://github.com/tripolskypetr/agent-swarm-kit/blob/master/docs/api-reference.md)** for more!
+
+---
+
+## 🛠 Advanced Example: Vector Search with Embeddings
+
+Integrate vector search with embeddings for smarter agents:
+
+```typescript
+import { addAgent, addSwarm, addStorage, addEmbedding, session, Storage } from "agent-swarm-kit";
+import { Ollama } from "ollama";
+
+const ollama = new Ollama();
+
+// Define an embedding with similarity calculation
+const NOMIC_EMBEDDING = addEmbedding({
+  embeddingName: "nomic_embedding",
+  calculateSimilarity: (a, b) => {
+    return tidy(() => {
+      const tensorA = tensor1d(a);
+      const tensorB = tensor1d(b);
+      const dotProduct = sum(mul(tensorA, tensorB));
+      const normA = norm(tensorA);
+      const normB = norm(tensorB);
+      const cosineData = div(dotProduct, mul(normA, normB)).dataSync();
+      const cosineSimilarity = cosineData[0];
+      return cosineSimilarity;
+    });
+  },
+  createEmbedding: async (text) => {
+    const { embedding } = await ollama.embeddings({
+      model: "nomic-embed-text",
+      prompt: text,
+    });
+    return embedding;
+  },
+});
+
+// Set up storage with sample data
+const TEST_STORAGE = addStorage({
+  storageName: "test_storage",
+  embedding: NOMIC_EMBEDDING,
+  createIndex: ({ description }) => description,
+  getData: () => JSON.parse(readFileSync("./data.json", "utf8")).slice(0, 100),
+});
+
+// Create an agent with storage
+const TEST_AGENT = addAgent({
+  agentName: "test_agent",
+  completion: {/* completion config */},
+  prompt: "Search and assist.",
+  storages: [TEST_STORAGE],
+});
+
+// Build the swarm
+const TEST_SWARM = addSwarm({
+  swarmName: "test_swarm",
+  agentList: [TEST_AGENT],
+  defaultAgent: TEST_AGENT,
+});
+
+// Search with a client session
+const { complete } = session("client-123", TEST_SWARM);
+complete("I need a refund!").then(console.log);
+
+// Use vector search in a tool call
+Storage.take("reduce pain, fever", 1, "client-xyz", TEST_AGENT, TEST_STORAGE)
+  .then(result => console.log("Found:", result));
+```
+
+## ❓ Orchestration Principles
+
+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?`
+
+
+---
+
+## ✅ Tested & Reliable
+
+`agent-swarm-kit` comes with a robust test suite covering:
+- **Validation**: Ensures all components (agents, tools, swarms) are properly configured.
+- **Recovery**: Handles edge cases like invalid tool calls or empty outputs.
+- **Navigation**: Smoothly switches between agents without deadlocks.
+- **Performance**: Efficient connection disposal and history management.
+
+See the **[Test Cases](#test-cases)** section in the docs for details.
+
+---
+
+## 🤝 Contribute
 
-Agent Swarm Kit lets you build intelligent multi-agent systems where different agents can collaborate, execute tasks, and communicate seamlessly. Think of it like creating a team of specialized AI agents that can work together, share information, validate their actions, and track their interactions - all through a structured TypeScript framework. It's essentially a toolkit for creating complex, coordinated AI workflows where agents can execute commands, commit outputs, and maintain a history of their interactions.
+We’d love your input! Fork the repo, submit a PR, or open an issue on **[GitHub](https://github.com/tripolskypetr/agent-swarm-kit)**.
 
-**Key Features:**
-- Create and manage complex agent networks
-- Enable agents to execute tasks, communicate, and collaborate
-- Provide robust validation for tools, agents, and sessions
-- Track agent interactions and maintain comprehensive history
-- Support seamless message passing and output tracking
+---
 
-**Core Components:**
-- Agent Management: Create, validate, and connect agents
-- Session Handling: Execute commands across agent networks
-- Tool Validation: Ensure agent tools calls meet argument requirements
-- History Tracking: Log and retrieve agent interactions
+## 📜 License
 
-**Use Cases:**
-- AI-powered workflow automation
-- Collaborative problem-solving systems
-- Complex task distribution across specialized agents
-- Intelligent system design with modular agent architecture
+MIT © [tripolskypetr](https://github.com/tripolskypetr)