@avee1234/agent-kit 0.1.0 → 0.3.0

package/README.md

@@ -1,7 +1,15 @@
 # agent-kit
 
+[![CI](https://github.com/abhid1234/agent-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/abhid1234/agent-kit/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@avee1234/agent-kit)](https://www.npmjs.com/package/@avee1234/agent-kit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
 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 +20,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 +75,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 +107,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 +138,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 +161,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 +228,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 +248,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 +306,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/cli.cjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/cli.ts
+var import_fs = __toESM(require("fs"), 1);
+var import_path = __toESM(require("path"), 1);
+var args = process.argv.slice(2);
+var command = args[0];
+var projectName = args[1] ?? "my-agent";
+if (command !== "init") {
+  console.error(`Unknown command: ${command}`);
+  console.error("Usage: agent-kit init [project-name]");
+  process.exit(1);
+}
+var targetDir = import_path.default.resolve(process.cwd(), projectName);
+if (import_fs.default.existsSync(targetDir)) {
+  console.error(`Directory already exists: ${targetDir}`);
+  process.exit(1);
+}
+import_fs.default.mkdirSync(targetDir, { recursive: true });
+var packageJson = {
+  name: projectName,
+  version: "1.0.0",
+  private: true,
+  type: "module",
+  scripts: {
+    start: "npx tsx agent.ts"
+  },
+  dependencies: {
+    "@avee1234/agent-kit": "^0.2.0"
+  },
+  devDependencies: {
+    tsx: "^4.0.0"
+  }
+};
+var agentTs = `import { Agent, Tool, Memory } from '@avee1234/agent-kit';
+
+const greet = Tool.create({
+  name: 'greet',
+  description: 'Greet someone by name',
+  parameters: {
+    name: { type: 'string', description: 'Name to greet' },
+  },
+  execute: async ({ name }) => \`Hello, \${name}!\`,
+});
+
+const agent = new Agent({
+  name: 'my-agent',
+  memory: new Memory({ store: 'sqlite', path: './memory.db' }),
+  tools: [greet],
+  system: 'You are a helpful assistant.',
+});
+
+const response = await agent.chat(process.argv[2] ?? 'Hello!');
+console.log(response.content);
+`;
+var readmeMd = `# ${projectName}
+
+Built with [agent-kit](https://github.com/abhid1234/agent-kit).
+
+## Quick Start
+
+\`\`\`bash
+npm install
+npm start "Hello, what can you do?"
+\`\`\`
+`;
+import_fs.default.writeFileSync(import_path.default.join(targetDir, "package.json"), JSON.stringify(packageJson, null, 2) + "\n");
+import_fs.default.writeFileSync(import_path.default.join(targetDir, "agent.ts"), agentTs);
+import_fs.default.writeFileSync(import_path.default.join(targetDir, "README.md"), readmeMd);
+console.log(`
+Scaffolded project: ${projectName}
+`);
+console.log("Next steps:\n");
+console.log(`  cd ${projectName}`);
+console.log("  npm install");
+console.log('  npm start "Hello, what can you do?"\n');
+//# sourceMappingURL=cli.cjs.map

package/dist/cli.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n\nimport fs from 'fs';\nimport path from 'path';\n\nconst args = process.argv.slice(2);\nconst command = args[0];\nconst projectName = args[1] ?? 'my-agent';\n\nif (command !== 'init') {\n  console.error(`Unknown command: ${command}`);\n  console.error('Usage: agent-kit init [project-name]');\n  process.exit(1);\n}\n\nconst targetDir = path.resolve(process.cwd(), projectName);\n\nif (fs.existsSync(targetDir)) {\n  console.error(`Directory already exists: ${targetDir}`);\n  process.exit(1);\n}\n\nfs.mkdirSync(targetDir, { recursive: true });\n\nconst packageJson = {\n  name: projectName,\n  version: '1.0.0',\n  private: true,\n  type: 'module',\n  scripts: {\n    start: 'npx tsx agent.ts',\n  },\n  dependencies: {\n    '@avee1234/agent-kit': '^0.2.0',\n  },\n  devDependencies: {\n    tsx: '^4.0.0',\n  },\n};\n\nconst agentTs = `import { Agent, Tool, Memory } from '@avee1234/agent-kit';\n\nconst greet = Tool.create({\n  name: 'greet',\n  description: 'Greet someone by name',\n  parameters: {\n    name: { type: 'string', description: 'Name to greet' },\n  },\n  execute: async ({ name }) => \\`Hello, \\${name}!\\`,\n});\n\nconst agent = new Agent({\n  name: 'my-agent',\n  memory: new Memory({ store: 'sqlite', path: './memory.db' }),\n  tools: [greet],\n  system: 'You are a helpful assistant.',\n});\n\nconst response = await agent.chat(process.argv[2] ?? 'Hello!');\nconsole.log(response.content);\n`;\n\nconst readmeMd = `# ${projectName}\n\nBuilt with [agent-kit](https://github.com/abhid1234/agent-kit).\n\n## Quick Start\n\n\\`\\`\\`bash\nnpm install\nnpm start \"Hello, what can you do?\"\n\\`\\`\\`\n`;\n\nfs.writeFileSync(path.join(targetDir, 'package.json'), JSON.stringify(packageJson, null, 2) + '\\n');\nfs.writeFileSync(path.join(targetDir, 'agent.ts'), agentTs);\nfs.writeFileSync(path.join(targetDir, 'README.md'), readmeMd);\n\nconsole.log(`\\nScaffolded project: ${projectName}\\n`);\nconsole.log('Next steps:\\n');\nconsole.log(`  cd ${projectName}`);\nconsole.log('  npm install');\nconsole.log('  npm start \"Hello, what can you do?\"\\n');\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAEA,gBAAe;AACf,kBAAiB;AAEjB,IAAM,OAAO,QAAQ,KAAK,MAAM,CAAC;AACjC,IAAM,UAAU,KAAK,CAAC;AACtB,IAAM,cAAc,KAAK,CAAC,KAAK;AAE/B,IAAI,YAAY,QAAQ;AACtB,UAAQ,MAAM,oBAAoB,OAAO,EAAE;AAC3C,UAAQ,MAAM,sCAAsC;AACpD,UAAQ,KAAK,CAAC;AAChB;AAEA,IAAM,YAAY,YAAAA,QAAK,QAAQ,QAAQ,IAAI,GAAG,WAAW;AAEzD,IAAI,UAAAC,QAAG,WAAW,SAAS,GAAG;AAC5B,UAAQ,MAAM,6BAA6B,SAAS,EAAE;AACtD,UAAQ,KAAK,CAAC;AAChB;AAEA,UAAAA,QAAG,UAAU,WAAW,EAAE,WAAW,KAAK,CAAC;AAE3C,IAAM,cAAc;AAAA,EAClB,MAAM;AAAA,EACN,SAAS;AAAA,EACT,SAAS;AAAA,EACT,MAAM;AAAA,EACN,SAAS;AAAA,IACP,OAAO;AAAA,EACT;AAAA,EACA,cAAc;AAAA,IACZ,uBAAuB;AAAA,EACzB;AAAA,EACA,iBAAiB;AAAA,IACf,KAAK;AAAA,EACP;AACF;AAEA,IAAM,UAAU;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAsBhB,IAAM,WAAW,KAAK,WAAW;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAYjC,UAAAA,QAAG,cAAc,YAAAD,QAAK,KAAK,WAAW,cAAc,GAAG,KAAK,UAAU,aAAa,MAAM,CAAC,IAAI,IAAI;AAClG,UAAAC,QAAG,cAAc,YAAAD,QAAK,KAAK,WAAW,UAAU,GAAG,OAAO;AAC1D,UAAAC,QAAG,cAAc,YAAAD,QAAK,KAAK,WAAW,WAAW,GAAG,QAAQ;AAE5D,QAAQ,IAAI;AAAA,sBAAyB,WAAW;AAAA,CAAI;AACpD,QAAQ,IAAI,eAAe;AAC3B,QAAQ,IAAI,QAAQ,WAAW,EAAE;AACjC,QAAQ,IAAI,eAAe;AAC3B,QAAQ,IAAI,yCAAyC;","names":["path","fs"]}

package/dist/cli.d.cts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import fs from "fs";
+import path from "path";
+var args = process.argv.slice(2);
+var command = args[0];
+var projectName = args[1] ?? "my-agent";
+if (command !== "init") {
+  console.error(`Unknown command: ${command}`);
+  console.error("Usage: agent-kit init [project-name]");
+  process.exit(1);
+}
+var targetDir = path.resolve(process.cwd(), projectName);
+if (fs.existsSync(targetDir)) {
+  console.error(`Directory already exists: ${targetDir}`);
+  process.exit(1);
+}
+fs.mkdirSync(targetDir, { recursive: true });
+var packageJson = {
+  name: projectName,
+  version: "1.0.0",
+  private: true,
+  type: "module",
+  scripts: {
+    start: "npx tsx agent.ts"
+  },
+  dependencies: {
+    "@avee1234/agent-kit": "^0.2.0"
+  },
+  devDependencies: {
+    tsx: "^4.0.0"
+  }
+};
+var agentTs = `import { Agent, Tool, Memory } from '@avee1234/agent-kit';
+
+const greet = Tool.create({
+  name: 'greet',
+  description: 'Greet someone by name',
+  parameters: {
+    name: { type: 'string', description: 'Name to greet' },
+  },
+  execute: async ({ name }) => \`Hello, \${name}!\`,
+});
+
+const agent = new Agent({
+  name: 'my-agent',
+  memory: new Memory({ store: 'sqlite', path: './memory.db' }),
+  tools: [greet],
+  system: 'You are a helpful assistant.',
+});
+
+const response = await agent.chat(process.argv[2] ?? 'Hello!');
+console.log(response.content);
+`;
+var readmeMd = `# ${projectName}
+
+Built with [agent-kit](https://github.com/abhid1234/agent-kit).
+
+## Quick Start
+
+\`\`\`bash
+npm install
+npm start "Hello, what can you do?"
+\`\`\`
+`;
+fs.writeFileSync(path.join(targetDir, "package.json"), JSON.stringify(packageJson, null, 2) + "\n");
+fs.writeFileSync(path.join(targetDir, "agent.ts"), agentTs);
+fs.writeFileSync(path.join(targetDir, "README.md"), readmeMd);
+console.log(`
+Scaffolded project: ${projectName}
+`);
+console.log("Next steps:\n");
+console.log(`  cd ${projectName}`);
+console.log("  npm install");
+console.log('  npm start "Hello, what can you do?"\n');
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n\nimport fs from 'fs';\nimport path from 'path';\n\nconst args = process.argv.slice(2);\nconst command = args[0];\nconst projectName = args[1] ?? 'my-agent';\n\nif (command !== 'init') {\n  console.error(`Unknown command: ${command}`);\n  console.error('Usage: agent-kit init [project-name]');\n  process.exit(1);\n}\n\nconst targetDir = path.resolve(process.cwd(), projectName);\n\nif (fs.existsSync(targetDir)) {\n  console.error(`Directory already exists: ${targetDir}`);\n  process.exit(1);\n}\n\nfs.mkdirSync(targetDir, { recursive: true });\n\nconst packageJson = {\n  name: projectName,\n  version: '1.0.0',\n  private: true,\n  type: 'module',\n  scripts: {\n    start: 'npx tsx agent.ts',\n  },\n  dependencies: {\n    '@avee1234/agent-kit': '^0.2.0',\n  },\n  devDependencies: {\n    tsx: '^4.0.0',\n  },\n};\n\nconst agentTs = `import { Agent, Tool, Memory } from '@avee1234/agent-kit';\n\nconst greet = Tool.create({\n  name: 'greet',\n  description: 'Greet someone by name',\n  parameters: {\n    name: { type: 'string', description: 'Name to greet' },\n  },\n  execute: async ({ name }) => \\`Hello, \\${name}!\\`,\n});\n\nconst agent = new Agent({\n  name: 'my-agent',\n  memory: new Memory({ store: 'sqlite', path: './memory.db' }),\n  tools: [greet],\n  system: 'You are a helpful assistant.',\n});\n\nconst response = await agent.chat(process.argv[2] ?? 'Hello!');\nconsole.log(response.content);\n`;\n\nconst readmeMd = `# ${projectName}\n\nBuilt with [agent-kit](https://github.com/abhid1234/agent-kit).\n\n## Quick Start\n\n\\`\\`\\`bash\nnpm install\nnpm start \"Hello, what can you do?\"\n\\`\\`\\`\n`;\n\nfs.writeFileSync(path.join(targetDir, 'package.json'), JSON.stringify(packageJson, null, 2) + '\\n');\nfs.writeFileSync(path.join(targetDir, 'agent.ts'), agentTs);\nfs.writeFileSync(path.join(targetDir, 'README.md'), readmeMd);\n\nconsole.log(`\\nScaffolded project: ${projectName}\\n`);\nconsole.log('Next steps:\\n');\nconsole.log(`  cd ${projectName}`);\nconsole.log('  npm install');\nconsole.log('  npm start \"Hello, what can you do?\"\\n');\n"],"mappings":";;;AAEA,OAAO,QAAQ;AACf,OAAO,UAAU;AAEjB,IAAM,OAAO,QAAQ,KAAK,MAAM,CAAC;AACjC,IAAM,UAAU,KAAK,CAAC;AACtB,IAAM,cAAc,KAAK,CAAC,KAAK;AAE/B,IAAI,YAAY,QAAQ;AACtB,UAAQ,MAAM,oBAAoB,OAAO,EAAE;AAC3C,UAAQ,MAAM,sCAAsC;AACpD,UAAQ,KAAK,CAAC;AAChB;AAEA,IAAM,YAAY,KAAK,QAAQ,QAAQ,IAAI,GAAG,WAAW;AAEzD,IAAI,GAAG,WAAW,SAAS,GAAG;AAC5B,UAAQ,MAAM,6BAA6B,SAAS,EAAE;AACtD,UAAQ,KAAK,CAAC;AAChB;AAEA,GAAG,UAAU,WAAW,EAAE,WAAW,KAAK,CAAC;AAE3C,IAAM,cAAc;AAAA,EAClB,MAAM;AAAA,EACN,SAAS;AAAA,EACT,SAAS;AAAA,EACT,MAAM;AAAA,EACN,SAAS;AAAA,IACP,OAAO;AAAA,EACT;AAAA,EACA,cAAc;AAAA,IACZ,uBAAuB;AAAA,EACzB;AAAA,EACA,iBAAiB;AAAA,IACf,KAAK;AAAA,EACP;AACF;AAEA,IAAM,UAAU;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAsBhB,IAAM,WAAW,KAAK,WAAW;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAYjC,GAAG,cAAc,KAAK,KAAK,WAAW,cAAc,GAAG,KAAK,UAAU,aAAa,MAAM,CAAC,IAAI,IAAI;AAClG,GAAG,cAAc,KAAK,KAAK,WAAW,UAAU,GAAG,OAAO;AAC1D,GAAG,cAAc,KAAK,KAAK,WAAW,WAAW,GAAG,QAAQ;AAE5D,QAAQ,IAAI;AAAA,sBAAyB,WAAW;AAAA,CAAI;AACpD,QAAQ,IAAI,eAAe;AAC3B,QAAQ,IAAI,QAAQ,WAAW,EAAE;AACjC,QAAQ,IAAI,eAAe;AAC3B,QAAQ,IAAI,yCAAyC;","names":[]}