@avee1234/agent-kit 0.1.0 → 0.2.0

package/README.md

@@ -2,6 +2,10 @@
 
 TypeScript-first library for building stateful, persistent AI agents.
 
+<p align="center">
+  <img src="assets/demo.svg" alt="agent-kit demo — memory persists across sessions" width="750" />
+</p>
+
 ## Why agent-kit?
 
 - **Persistent memory across sessions** — SQLite store keeps conversation history and auto-summarizes old exchanges. Restart your process; the agent still remembers.
@@ -12,13 +16,13 @@ TypeScript-first library for building stateful, persistent AI agents.
 ## Installation
 
 ```bash
-npm install agent-kit
+npm install @avee1234/agent-kit
 ```
 
 ## Quick Start
 
 ```typescript
-import { Agent, Tool, Memory } from 'agent-kit';
+import { Agent, Tool, Memory } from '@avee1234/agent-kit';
 
 const echo = Tool.create({
   name: 'echo',
@@ -67,7 +71,7 @@ Kill the process and restart — memory persists in `research.db`.
 The main class. Runs a tool-calling loop, manages memory context, and emits observability events.
 
 ```typescript
-import { Agent } from 'agent-kit';
+import { Agent } from '@avee1234/agent-kit';
 
 const agent = new Agent({
   name: 'assistant',
@@ -99,7 +103,7 @@ const agent = new Agent({
 Wraps a function so the agent can call it.
 
 ```typescript
-import { Tool } from 'agent-kit';
+import { Tool } from '@avee1234/agent-kit';
 
 const getWeather = Tool.create({
   name: 'get_weather',
@@ -130,7 +134,7 @@ const getWeather = Tool.create({
 Manages conversation persistence and context retrieval.
 
 ```typescript
-import { Memory } from 'agent-kit';
+import { Memory } from '@avee1234/agent-kit';
 
 // In-memory (default, testing)
 new Memory()
@@ -153,6 +157,66 @@ new Memory({ store: myCustomStore })
 
 Auto-summarization: when `summarizeAfter` messages accumulate, the agent summarizes them and stores the summary. Older context is retrieved via `searchSummaries`.
 
+### Team (Multi-Agent Coordination)
+
+Coordinate multiple agents on a single task using four strategies.
+
+**Sequential** — agents run in order, each getting the previous agent's output:
+
+```typescript
+import { Agent, Team } from '@avee1234/agent-kit';
+
+const team = new Team({
+  agents: [researcher, writer],
+  strategy: 'sequential',
+});
+const result = await team.run('Research AI frameworks and write a summary');
+// writer receives researcher's output as context
+```
+
+**Parallel** — all agents run concurrently, results merged:
+
+```typescript
+const team = new Team({
+  agents: [researcher, writer, critic],
+  strategy: 'parallel',
+});
+const result = await team.run('Analyze this codebase');
+// result.responses has each agent's individual output
+```
+
+**Debate** — agents take turns critiquing and refining:
+
+```typescript
+const team = new Team({
+  agents: [proposer, critic],
+  strategy: 'debate',
+  maxRounds: 3,
+});
+const result = await team.run('What is the best database for embeddings?');
+// 3 rounds of back-and-forth, then final answer
+```
+
+**Hierarchical** — a manager delegates tasks to specialists:
+
+```typescript
+const team = new Team({
+  agents: [researcher, writer, critic],
+  strategy: 'hierarchical',
+  manager: new Agent({ name: 'manager', system: 'You coordinate a team of specialists.' }),
+});
+const result = await team.run('Write a blog post about transformer alternatives');
+// manager decides who does what and when
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `agents` | `Agent[]` | — | The agents to coordinate |
+| `strategy` | `string` | — | `'sequential'`, `'parallel'`, `'debate'`, or `'hierarchical'` |
+| `manager` | `Agent` | — | Required for hierarchical strategy |
+| `maxRounds` | `number` | `3` | Number of debate rounds |
+| `maxDelegations` | `number` | `10` | Max delegations for hierarchical |
+
 ## Model Configuration
 
 ### Mock (zero config, built-in)
@@ -160,7 +224,7 @@ Auto-summarization: when `summarizeAfter` messages accumulate, the agent summari
 If you omit `model`, the agent uses `MockAdapter` — it echoes inputs and simulates tool calls. Useful for testing.
 
 ```typescript
-import { MockAdapter } from 'agent-kit';
+import { MockAdapter } from '@avee1234/agent-kit';
 
 const agent = new Agent({ name: 'test', model: new MockAdapter() });
 ```
@@ -180,7 +244,7 @@ const agent = new Agent({
 Works with Together AI, OpenRouter, Anyscale, LM Studio, and any other OpenAI-compatible API.
 
 ```typescript
-import { OpenAICompatibleAdapter } from 'agent-kit';
+import { OpenAICompatibleAdapter } from '@avee1234/agent-kit';
 
 const agent = new Agent({
   name: 'agent',
@@ -238,8 +302,8 @@ All events include `type`, `timestamp`, and `agentId` fields from `AgentEvent`.
 Implement the `MemoryStore` interface to plug in any storage backend (PostgreSQL, Redis, DynamoDB, etc.).
 
 ```typescript
-import type { MemoryStore } from 'agent-kit';
-import type { Message, Summary } from 'agent-kit';
+import type { MemoryStore } from '@avee1234/agent-kit';
+import type { Message, Summary } from '@avee1234/agent-kit';
 
 class MyStore implements MemoryStore {
   async saveMessages(agentId: string, messages: Message[]): Promise<void> {

package/dist/index.cjs

@@ -27,6 +27,7 @@ __export(index_exports, {
   MockAdapter: () => MockAdapter,
   OpenAICompatibleAdapter: () => OpenAICompatibleAdapter,
   SQLiteStore: () => SQLiteStore,
+  Team: () => Team,
   Tool: () => Tool,
   createMessage: () => createMessage,
   createSummary: () => createSummary,
@@ -273,6 +274,9 @@ var Agent = class {
   isModelAdapter(obj) {
     return typeof obj.chat === "function";
   }
+  getModel() {
+    return this.model;
+  }
   on(type, handler) {
     this.emitter.on(type, handler);
   }
@@ -428,6 +432,144 @@ var Agent = class {
   }
 };
 
+// src/strategy/sequential.ts
+var SequentialStrategy = class {
+  async execute(agents, task, _options, emitter) {
+    const responses = [];
+    let previousOutput;
+    for (const agent of agents) {
+      const input = previousOutput !== void 0 ? `${task}
+
+Previous agent output:
+${previousOutput}` : task;
+      emitter.emit({
+        type: "team:agent:start",
+        timestamp: Date.now(),
+        agentId: "team",
+        data: { agentName: agent.name, input }
+      });
+      const startTime = Date.now();
+      const result = await agent.chat(input);
+      const latencyMs = Date.now() - startTime;
+      emitter.emit({
+        type: "team:agent:end",
+        timestamp: Date.now(),
+        agentId: "team",
+        data: { agentName: agent.name, output: result.content },
+        latencyMs
+      });
+      responses.push({ agent: agent.name, content: result.content });
+      previousOutput = result.content;
+    }
+    return {
+      content: responses[responses.length - 1]?.content ?? "",
+      responses
+    };
+  }
+};
+
+// src/strategy/parallel.ts
+var ParallelStrategy = class {
+  async execute(agents, task, _options, emitter) {
+    const agentPromises = agents.map(async (agent) => {
+      emitter.emit({
+        type: "team:agent:start",
+        timestamp: Date.now(),
+        agentId: "team",
+        data: { agentName: agent.name, input: task }
+      });
+      const startTime = Date.now();
+      const result = await agent.chat(task);
+      const latencyMs = Date.now() - startTime;
+      emitter.emit({
+        type: "team:agent:end",
+        timestamp: Date.now(),
+        agentId: "team",
+        data: { agentName: agent.name, output: result.content },
+        latencyMs
+      });
+      return { agent: agent.name, content: result.content };
+    });
+    const responses = await Promise.all(agentPromises);
+    const content = responses.map((r) => `[${r.agent}]: ${r.content}`).join("\n\n");
+    return { content, responses };
+  }
+};
+
+// src/strategy/debate.ts
+var DebateStrategy = class {
+  async execute(agents, task, options, emitter) {
+    const maxRounds = options.maxRounds ?? 3;
+    const responses = [];
+    const priorOutputs = [];
+    for (let round = 1; round <= maxRounds; round++) {
+      emitter.emit({
+        type: "team:round",
+        timestamp: Date.now(),
+        agentId: "team",
+        data: { round, totalRounds: maxRounds }
+      });
+      for (const agent of agents) {
+        const context = priorOutputs.length > 0 ? `${task}
+
+Debate so far:
+${priorOutputs.join("\n\n")}
+
+Your turn (Round ${round}):` : `${task}
+
+(Round ${round}):`;
+        emitter.emit({
+          type: "team:agent:start",
+          timestamp: Date.now(),
+          agentId: "team",
+          data: { agentName: agent.name, round }
+        });
+        const startTime = Date.now();
+        const result = await agent.chat(context);
+        const latencyMs = Date.now() - startTime;
+        emitter.emit({
+          type: "team:agent:end",
+          timestamp: Date.now(),
+          agentId: "team",
+          data: { agentName: agent.name, output: result.content, round },
+          latencyMs
+        });
+        const agentResponse = {
+          agent: agent.name,
+          content: result.content,
+          round
+        };
+        responses.push(agentResponse);
+        priorOutputs.push(`[${agent.name}, Round ${round}]: ${result.content}`);
+      }
+    }
+    const firstAgent = agents[0];
+    const synthesisInput = `${task}
+
+Debate summary:
+${priorOutputs.join("\n\n")}
+
+Provide your final answer:`;
+    emitter.emit({
+      type: "team:agent:start",
+      timestamp: Date.now(),
+      agentId: "team",
+      data: { agentName: firstAgent.name, phase: "final" }
+    });
+    const finalResult = await firstAgent.chat(synthesisInput);
+    emitter.emit({
+      type: "team:agent:end",
+      timestamp: Date.now(),
+      agentId: "team",
+      data: { agentName: firstAgent.name, output: finalResult.content, phase: "final" }
+    });
+    return {
+      content: finalResult.content,
+      responses
+    };
+  }
+};
+
 // src/tool.ts
 var Tool = class _Tool {
   name;
@@ -452,6 +594,136 @@ var Tool = class _Tool {
   }
 };
 
+// src/strategy/hierarchical.ts
+var HierarchicalStrategy = class {
+  async execute(agents, task, options, emitter) {
+    const { manager, maxDelegations = 10 } = options;
+    if (!manager) {
+      throw new Error("HierarchicalStrategy requires a manager agent");
+    }
+    const agentMap = new Map(agents.map((a) => [a.name, a]));
+    const responses = [];
+    const delegateTool = Tool.create({
+      name: "delegate",
+      description: "Delegate a sub-task to a specialist agent. Use this to assign work to workers.",
+      parameters: {
+        agentName: {
+          type: "string",
+          description: "The name of the agent to delegate to",
+          required: true
+        },
+        task: {
+          type: "string",
+          description: "The task to assign to the agent",
+          required: true
+        }
+      },
+      execute: async (params) => {
+        const agentName = params.agentName;
+        const subTask = params.task;
+        const worker = agentMap.get(agentName);
+        if (!worker) {
+          return `Error: No agent named "${agentName}" found. Available agents: ${[...agentMap.keys()].join(", ")}`;
+        }
+        emitter.emit({
+          type: "team:delegate",
+          timestamp: Date.now(),
+          agentId: "team",
+          data: { agentName, task: subTask }
+        });
+        const result = await worker.chat(subTask);
+        const response = { agent: agentName, content: result.content };
+        responses.push(response);
+        return result.content;
+      }
+    });
+    const orchestratorAgent = new Agent({
+      name: manager.name,
+      model: manager.getModel(),
+      tools: [delegateTool],
+      system: `You are an orchestrating manager. You have access to specialist agents: ${[...agentMap.keys()].join(", ")}. Use the delegate tool to assign sub-tasks to them.`,
+      maxToolRounds: maxDelegations
+    });
+    const finalResult = await orchestratorAgent.chat(task);
+    return {
+      content: finalResult.content,
+      responses
+    };
+  }
+};
+
+// src/team.ts
+var Team = class {
+  agents;
+  strategyName;
+  manager;
+  maxRounds;
+  maxDelegations;
+  emitter;
+  constructor(config) {
+    this.agents = config.agents;
+    this.strategyName = config.strategy;
+    this.manager = config.manager;
+    this.maxRounds = config.maxRounds;
+    this.maxDelegations = config.maxDelegations;
+    this.emitter = new AgentEventEmitter();
+  }
+  on(type, handler) {
+    this.emitter.on(type, handler);
+  }
+  off(type, handler) {
+    this.emitter.off(type, handler);
+  }
+  async run(task) {
+    this.emitter.emit({
+      type: "team:start",
+      timestamp: Date.now(),
+      agentId: "team",
+      data: {
+        strategy: this.strategyName,
+        agentCount: this.agents.length,
+        task
+      }
+    });
+    const startTime = Date.now();
+    const strategy = this.resolveStrategy();
+    const result = await strategy.execute(
+      this.agents,
+      task,
+      {
+        maxRounds: this.maxRounds,
+        maxDelegations: this.maxDelegations,
+        manager: this.manager
+      },
+      this.emitter
+    );
+    const latencyMs = Date.now() - startTime;
+    this.emitter.emit({
+      type: "team:end",
+      timestamp: Date.now(),
+      agentId: "team",
+      data: {
+        strategy: this.strategyName,
+        responseCount: result.responses.length
+      },
+      latencyMs
+    });
+    return result;
+  }
+  resolveStrategy() {
+    switch (this.strategyName) {
+      case "sequential":
+        return new SequentialStrategy();
+      case "parallel":
+        return new ParallelStrategy();
+      case "debate":
+        return new DebateStrategy();
+      case "hierarchical":
+        return new HierarchicalStrategy();
+    }
+  }
+};
+
 // src/store/in-memory.ts
 var InMemoryStore = class {
   messages = /* @__PURE__ */ new Map();
@@ -649,6 +921,7 @@ var Memory = class {
   MockAdapter,
   OpenAICompatibleAdapter,
   SQLiteStore,
+  Team,
   Tool,
   createMessage,
   createSummary,