@avee1234/agent-kit 0.3.4 → 0.3.6

package/README.md

@@ -6,341 +6,190 @@
 
 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?
+**[Live Playground](https://www.abhi-agent-kit.space)** | **[Blog Post](https://abhid.substack.com/p/i-built-an-open-source-ai-agent-framework)** | **[npm](https://www.npmjs.com/package/@avee1234/agent-kit)** | **[Docs](https://abhid1234.github.io/agent-kit/)**
 
-- **Persistent memory across sessions** — SQLite store keeps conversation history and auto-summarizes old exchanges. Restart your process; the agent still remembers.
-- **Simple tool system** — define a tool in five lines with `Tool.create`. No decorator magic, no class inheritance.
-- **Built-in observability** — subscribe to `message`, `tool:start`, `tool:end`, and `error` events. No paid add-on required.
-- **TypeScript-first with great types** — strict types throughout. Your editor autocompletes `AgentConfig`, `ToolDefinition`, `AgentEvent`, and everything else.
+---
 
-## Installation
-
-```bash
-npm install @avee1234/agent-kit
-```
+## Why agent-kit?
 
-## Quick Start
+<p align="center">
+  <img src="https://substack-post-media.s3.amazonaws.com/public/images/a427e237-04d0-421e-b1b7-ae2567c1d5d6_1883x981.png" alt="Comparison with LangChain, Vercel AI SDK, CrewAI" width="700" />
+</p>
 
-```typescript
-import { Agent, Tool, Memory } from '@avee1234/agent-kit';
+- **Persistent memory across sessions** — SQLite or PostgreSQL. Restart your process; the agent still remembers.
+- **Simple tool system** — define a tool in 5 lines with `Tool.create`. No decorators, no class inheritance.
+- **Multi-agent coordination** — 4 strategies: Sequential, Parallel, Debate, Hierarchical.
+- **Built-in observability** — subscribe to `tool:start`, `tool:end`, `memory:save` events. No paid add-on.
+- **TypeScript-first** — strict types throughout. Your editor autocompletes everything.
 
-const echo = Tool.create({
-  name: 'echo',
-  description: 'Echo a message back',
-  parameters: { message: { type: 'string', description: 'Text to echo' } },
-  execute: async ({ message }) => String(message),
-});
+---
 
-const agent = new Agent({
-  name: 'my-agent',
-  memory: new Memory({ store: 'sqlite' }),
-  tools: [echo],
-  system: 'You are a helpful assistant.',
-});
+## 4 Core Concepts
 
-const response = await agent.chat('Say hello');
-console.log(response.content);
-```
+<p align="center">
+  <img src="https://substack-post-media.s3.amazonaws.com/public/images/b36d2dd8-ee82-4798-864d-e56c1801293e_1883x1267.png" alt="Agent, Tool, Memory, Team — 4 core concepts" width="700" />
+</p>
 
-No model config required — `Agent` ships with a built-in `MockAdapter` so you can develop and test without any API keys.
+<p align="center">
+  <img src="https://substack-post-media.s3.amazonaws.com/public/images/6ffd48ee-59bc-4c0f-8b0f-3cae0e674a4c_1455x1470.png" alt="Agent, Tool, Memory, Team — with code examples" width="700" />
+</p>
 
-## Research Assistant Demo
+---
 
-The `examples/research-assistant` directory contains a full CLI agent that searches the web, saves notes, and remembers research across sessions.
+## Installation
 
 ```bash
-cd examples/research-assistant
-npm install
-npm start
+npm install @avee1234/agent-kit
 ```
 
-Then chat with it:
+Or scaffold a new project:
 
+```bash
+npx @avee1234/agent-kit init my-agent
 ```
-> Find recent papers on transformer alternatives
-> What did I research last time?
-> Save a note about Mamba architecture
-```
-
-Kill the process and restart — memory persists in `research.db`.
-
-## Core Concepts
 
-### Agent
+---
 
-The main class. Runs a tool-calling loop, manages memory context, and emits observability events.
+## Quick Start
 
 ```typescript
-import { Agent } from '@avee1234/agent-kit';
+import { Agent, Tool, Memory } from '@avee1234/agent-kit';
+
+const searchTool = Tool.create({
+  name: 'web_search',
+  description: 'Search the web',
+  parameters: { query: { type: 'string' } },
+  execute: async ({ query }) => fetch(`https://api.search.com?q=${query}`).then(r => r.json()),
+});
 
 const agent = new Agent({
-  name: 'assistant',
+  name: 'research-assistant',
   model: { provider: 'ollama', model: 'llama3' },
   memory: new Memory({ store: 'sqlite' }),
-  tools: [myTool],
-  system: 'You are a helpful assistant.',
-  maxToolRounds: 10,
+  tools: [searchTool],
+  system: 'You are a research assistant.',
 });
-```
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `name` | `string` | required | Unique identifier for this agent |
-| `model` | `ModelAdapter \| ModelConfig` | `MockAdapter` | Model to use for completions |
-| `memory` | `Memory` | none | Memory instance for persistence |
-| `tools` | `Tool[]` | `[]` | Tools the agent can call |
-| `system` | `string` | none | System prompt |
-| `maxToolRounds` | `number` | `10` | Max consecutive tool call rounds |
-
-**Methods:**
-
-- `agent.chat(input: string): Promise<ModelResponse>` — send a message, get a response
-- `agent.stream(input: string): AsyncIterable<ModelChunk>` — stream the response
-- `agent.on(type, handler)` / `agent.off(type, handler)` — subscribe to events
 
-### Tool
-
-Wraps a function so the agent can call it.
-
-```typescript
-import { Tool } from '@avee1234/agent-kit';
-
-const getWeather = Tool.create({
-  name: 'get_weather',
-  description: 'Get current weather for a city',
-  parameters: {
-    city: { type: 'string', description: 'City name', required: true },
-    units: { type: 'string', enum: ['celsius', 'fahrenheit'] },
-  },
-  execute: async ({ city, units }) => {
-    const u = units ?? 'celsius';
-    const res = await fetch(`https://wttr.in/${city}?format=j1`);
-    return res.json();
-  },
-});
+const response = await agent.chat('Find recent papers on transformers');
 ```
 
-| Field | Type | Description |
-|---|---|---|
-| `name` | `string` | Tool name (used by the model) |
-| `description` | `string` | What the tool does |
-| `parameters` | `Record<string, ParameterDef>` | JSON Schema-style parameter definitions |
-| `execute` | `(params) => Promise<unknown>` | The function to run |
+No model config required — ships with a built-in `MockAdapter` for development and testing without API keys.
 
-`ParameterDef` fields: `type`, `description`, `enum`, `required`.
+---
 
-### Memory
-
-Manages conversation persistence and context retrieval.
-
-```typescript
-import { Memory } from '@avee1234/agent-kit';
+## The "Wow Moment": Memory That Survives Restarts
 
-// In-memory (default, testing)
-new Memory()
-new Memory({ store: 'memory' })
-
-// SQLite (persists across restarts)
-new Memory({ store: 'sqlite' })
-new Memory({ store: 'sqlite', path: './myagent.db' })
-
-// Custom store
-new Memory({ store: myCustomStore })
-```
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `store` | `'memory' \| 'sqlite' \| MemoryStore` | `'memory'` | Storage backend |
-| `path` | `string` | `./agent-memory.db` | SQLite file path (sqlite only) |
-| `windowSize` | `number` | `20` | Number of recent messages to include in context |
-| `summarizeAfter` | `number` | `20` | Summarize after this many new messages |
-
-Auto-summarization: when `summarizeAfter` messages accumulate, the agent summarizes them and stores the summary. Older context is retrieved via `searchSummaries`.
-
-### Team (Multi-Agent Coordination)
+<p align="center">
+  <img src="https://substack-post-media.s3.amazonaws.com/public/images/fe5daa4c-39a6-4754-abf5-b5ec12ad3ebb_1406x768.png" alt="Agent remembers context across process restarts" width="700" />
+</p>
 
-Coordinate multiple agents on a single task using four strategies.
+Kill the process, restart it, same SQLite file — the agent picks up where it left off.
 
-**Sequential** — agents run in order, each getting the previous agent's output:
+<p align="center">
+  <img src="https://substack-post-media.s3.amazonaws.com/public/images/299b2c3f-97e2-4e85-baaf-81edd3965c7c_1406x602.png" alt="Short-term → Summarization → Long-term memory pipeline" width="700" />
+</p>
 
-```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
-```
+## Multi-Agent Coordination
 
-**Parallel** — all agents run concurrently, results merged:
+<p align="center">
+  <img src="https://substack-post-media.s3.amazonaws.com/public/images/ec242300-00e3-47b8-a399-695c235ecf84_1406x1402.png" alt="4 coordination strategies: Sequential, Parallel, Debate, Hierarchical" width="700" />
+</p>
 
 ```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:
+---
+
+## Built-In Observability
+
+<p align="center">
+  <img src="https://substack-post-media.s3.amazonaws.com/public/images/1588753c-8afa-4f9e-8e30-39090368c641_1406x471.png" alt="Real-time event stream: tool:start, tool:end, memory" width="700" />
+</p>
 
 ```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
+agent.on('*', (e) => console.log(e.type, e.data, e.latencyMs));
 ```
 
-| 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 |
+No LangSmith, no third-party service. Just `EventEmitter` — pipe it to whatever you use.
 
-## Model Configuration
-
-### Mock (zero config, built-in)
+---
 
-If you omit `model`, the agent uses `MockAdapter` — it echoes inputs and simulates tool calls. Useful for testing.
+## Where Each Tool Shines
 
-```typescript
-import { MockAdapter } from '@avee1234/agent-kit';
+<p align="center">
+  <img src="https://substack-post-media.s3.amazonaws.com/public/images/4ac5f833-33a0-4c48-92fe-20c27f4426e2_1406x565.png" alt="Comparison table: LangChain vs Vercel AI SDK vs CrewAI vs agent-kit" width="700" />
+</p>
 
-const agent = new Agent({ name: 'test', model: new MockAdapter() });
-```
+---
 
-### Ollama (local models)
+## Model Configuration
 
 ```typescript
-const agent = new Agent({
-  name: 'local-agent',
-  model: { provider: 'ollama', model: 'llama3' },
-  // baseURL defaults to http://localhost:11434/v1
-});
-```
-
-### OpenAI-compatible endpoints
+// Mock (zero config, built-in — great for testing)
+const agent = new Agent({ name: 'test' });
 
-Works with Together AI, OpenRouter, Anyscale, LM Studio, and any other OpenAI-compatible API.
-
-```typescript
-import { OpenAICompatibleAdapter } from '@avee1234/agent-kit';
+// Ollama (local models)
+const agent = new Agent({ name: 'local', model: { provider: 'ollama', model: 'llama3' } });
 
+// Google AI Studio (Gemini)
 const agent = new Agent({
-  name: 'agent',
+  name: 'gemini',
   model: new OpenAICompatibleAdapter({
-    baseURL: 'https://api.together.xyz/v1',
-    model: 'meta-llama/Llama-3-70b-chat-hf',
-    apiKey: process.env.TOGETHER_API_KEY,
+    baseURL: 'https://generativelanguage.googleapis.com/v1beta/openai',
+    model: 'gemini-2.0-flash',
+    apiKey: process.env.GOOGLE_AI_API_KEY,
   }),
 });
-```
-
-## Events
-
-Subscribe to events for logging, tracing, or custom observability.
-
-```typescript
-agent.on('message', (e) => {
-  console.log(`[${e.data.role}] ${e.data.content}`);
-});
-
-agent.on('tool:start', (e) => {
-  console.log(`Calling ${e.data.toolName}...`);
-});
 
-agent.on('tool:end', (e) => {
-  console.log(`${e.data.toolName} finished in ${e.latencyMs}ms`);
-});
-
-agent.on('memory:retrieve', (e) => {
-  console.log(`Loaded ${e.data.recentMessages} messages, ${e.data.summaries} summaries`);
-});
-
-agent.on('error', (e) => {
-  console.error(`Error: ${e.data.message}`);
-});
-
-// Catch all events
-agent.on('*', (e) => {
-  myTracer.record(e);
+// Any OpenAI-compatible endpoint (Together, OpenRouter, Groq, etc.)
+const agent = new Agent({
+  name: 'agent',
+  model: new OpenAICompatibleAdapter({ baseURL: '...', model: '...', apiKey: '...' }),
 });
 ```
 
-| Event type | `data` fields | Description |
-|---|---|---|
-| `message` | `role`, `content` | User or assistant message |
-| `tool:start` | `toolName`, `toolCallId`, `arguments` | Tool call started |
-| `tool:end` | `toolName`, `toolCallId`, `result`, `latencyMs` | Tool call finished |
-| `memory:retrieve` | `recentMessages`, `summaries` | Memory context loaded |
-| `error` | `message`, `toolName`, `toolCallId` | Error during tool execution |
+---
 
-All events include `type`, `timestamp`, and `agentId` fields from `AgentEvent`.
+## Try It Live
 
-## Custom MemoryStore
+<p align="center">
+  <img src="https://substack-post-media.s3.amazonaws.com/public/images/381c61cd-cc61-46de-9351-460ec3b78012_1405x563.png" alt="Live playground powered by Google Cloud Run and Gemini" width="700" />
+</p>
 
-Implement the `MemoryStore` interface to plug in any storage backend (PostgreSQL, Redis, DynamoDB, etc.).
+**[www.abhi-agent-kit.space](https://www.abhi-agent-kit.space)**
 
-```typescript
-import type { MemoryStore } from '@avee1234/agent-kit';
-import type { Message, Summary } from '@avee1234/agent-kit';
+4 pre-built agents with real-time tool execution, persistent memory, and live event streaming. Powered by Gemini 2.0 Flash on Google Cloud Run.
 
-class MyStore implements MemoryStore {
-  async saveMessages(agentId: string, messages: Message[]): Promise<void> {
-    // persist messages
-  }
+---
 
-  async getRecentMessages(agentId: string, limit: number): Promise<Message[]> {
-    // return most recent `limit` messages
-  }
+## What You Can Build
 
-  async saveSummary(agentId: string, summary: Summary): Promise<void> {
-    // persist summary
-  }
+<p align="center">
+  <img src="https://substack-post-media.s3.amazonaws.com/public/images/97e622f7-78f6-4066-bd2b-4ce4452b78f4_1405x936.png" alt="What I'd do differently — lessons learned" width="700" />
+</p>
 
-  async searchSummaries(agentId: string, query: string, limit: number): Promise<Summary[]> {
-    // return relevant summaries (keyword or vector search)
-  }
-}
+- **Travel planner** — destination search + weather + flight/hotel booking + budget calculator
+- **Research assistant** — web search + note-taking + session memory
+- **Customer support** — order lookup + conversation history
+- **Code reviewer** — security analysis + style checking
+- **Data analyst** — SQL queries + chart generation + persistent findings
+- **Personal assistant** — calendar + email + long-term preferences
 
-const agent = new Agent({
-  name: 'agent',
-  memory: new Memory({ store: new MyStore() }),
-});
-```
+---
 
-## What You Can Build
+## Read More
 
-- **Research assistant** — web search + note-taking + session memory
-- **Customer support bot** — ticket creation + knowledge base lookup + conversation history
-- **Code reviewer** — file read/write tools + PR comment integration
-- **Data analyst** — SQL query tool + chart generation + persistent findings
-- **Personal assistant** — calendar access + email tools + long-term user preferences
-- **DevOps incident responder** — log search + runbook lookup + alert suppression
+- **[Blog Post](https://abhid.substack.com/p/i-built-an-open-source-ai-agent-framework)** — the full story of why and how I built agent-kit
+- **[Documentation](https://abhid1234.github.io/agent-kit/)** — API reference, guides, and examples
+- **[npm](https://www.npmjs.com/package/@avee1234/agent-kit)** — `npm install @avee1234/agent-kit`
 
 ## Contributing
 

package/dist/index.cjs

@@ -95,7 +95,7 @@ var OpenAICompatibleAdapter = class {
   async chat(messages, tools) {
     const body = {
       model: this.config.model,
-      messages: messages.map((m) => this.toOpenAIMessage(m))
+      messages: messages.map((m) => this.toOpenAIMessage(m, messages))
     };
     if (tools?.length) {
       body.tools = tools.map((t) => ({
@@ -148,7 +148,7 @@ var OpenAICompatibleAdapter = class {
     if (this.config.apiKey) headers["Authorization"] = `Bearer ${this.config.apiKey}`;
     const body = {
       model: this.config.model,
-      messages: messages.map((m) => this.toOpenAIMessage(m)),
+      messages: messages.map((m) => this.toOpenAIMessage(m, messages)),
       stream: true
     };
     if (tools?.length) {
@@ -201,7 +201,7 @@ var OpenAICompatibleAdapter = class {
       }
     }
   }
-  toOpenAIMessage(msg) {
+  toOpenAIMessage(msg, allMessages) {
     const result = { role: msg.role, content: msg.content };
     if (msg.toolCalls) {
       result.tool_calls = msg.toolCalls.map((tc) => ({
@@ -210,7 +210,25 @@ var OpenAICompatibleAdapter = class {
         function: { name: tc.name, arguments: tc.arguments }
       }));
     }
-    if (msg.toolCallId) result.tool_call_id = msg.toolCallId;
+    if (msg.toolCallId) {
+      result.tool_call_id = msg.toolCallId;
+      let foundName = false;
+      if (allMessages) {
+        for (const m of allMessages) {
+          if (m.toolCalls) {
+            const tc = m.toolCalls.find((t) => t.id === msg.toolCallId);
+            if (tc) {
+              result.name = tc.name;
+              foundName = true;
+              break;
+            }
+          }
+        }
+      }
+      if (!foundName) {
+        result.name = "tool_result";
+      }
+    }
     return result;
   }
 };