agent-pulse 1.0.0

package/README.md

@@ -0,0 +1,361 @@
+# Agent Pulse
+
+**Agent Pulse** is a lightweight, native-first, event-driven framework for building agentic AI applications in JavaScript and TypeScript.
+
+It is designed to be "Zero Boilerplate," getting you from install to running agent in seconds, while supporting powerful patterns like streaming, tool execution, and workflow chaining.
+
+## Features
+
+- **Native First**: Built directly on official SDKs (`@google/genai`, `openai`).
+- **Tree-Shakeable**: Modular architecture allows you to import only what you need.
+- **Event-Driven**: Emit `token` events for streaming and `response` events for logic.
+- **Zero Boilerplate**: Simple `config`-based initialization.
+- **Auto Tool Execution**: Automatically executes tools and returns results for "Intent Detection" patterns.
+- **Provider Agnostic**: Easily switch between OpenAI, Google Gemini, and Grok by injecting different providers.
+
+## Installation
+
+```bash
+npm install agent-pulse
+```
+
+## Quick Start
+### 1. Setup Environment
+Create a `.env` file with your API keys. You only need the key for the provider you intend to use.
+
+```env
+OPENAI_API_KEY=sk-...
+GOOGLE_API_KEY=AIza...
+GROK_API_KEY=...
+```
+
+### 2. Basic Chat Bot (Streaming)
+
+```typescript
+import { Agent, openAI } from 'agent-pulse';
+import * as dotenv from 'dotenv';
+dotenv.config();
+
+// Instantiate the provider directly
+const agent = new Agent({
+  name: 'my-bot',
+  provider: new openAI('gpt-4o'), // Or new google('gemini-1.5-pro'), new grok('grok-beta')
+  system: 'You are a helpful assistant.'
+});
+
+// Real-time typing effect
+agent.on('token', (chunk) => {
+  process.stdout.write(chunk);
+});
+
+// Final logic
+agent.on('response', (result) => {
+  console.log('\nDone!', result.meta);
+});
+
+await agent.run('Hello!');
+```
+
+### 3. Chatbots & history (Multi-Turn)
+
+To run a chatbot with memory, maintain a history array and pass it to `agent.run()`.
+
+```typescript
+import { Agent, openAI } from 'agent-pulse';
+
+const agent = new Agent({
+  name: 'chatbot',
+  provider: new openAI('gpt-4o'),
+  system: 'You are a helpful assistant.'
+});
+
+const history = [
+  { role: 'user', content: 'What is the capital of France?' },
+  { role: 'assistant', content: 'The capital of France is Paris.' },
+  { role: 'user', content: 'And what is its famous tower?' }
+];
+
+const result = await agent.run(history);
+console.log(result.content); // "The famous tower in Paris is the Eiffel Tower."
+
+// To continue the conversation, append the new assistant response:
+history.push({ role: 'assistant', content: result.content });
+```
+
+## Modular Imports & Providers
+
+Agent Pulse exports aliases for common providers to make your code clean:
+
+```typescript
+import { Agent, openAI, google, grok } from 'agent-pulse';
+
+// OpenAI
+const bot1 = new Agent({
+    name: 'gpt-bot',
+    provider: new openAI('gpt-4o')
+});
+
+// Google Gemini
+const bot2 = new Agent({
+    name: 'gemini-bot',
+    provider: new google('gemini-1.5-pro')
+});
+
+// xAI / Grok
+const bot3 = new Agent({
+    name: 'grok-bot',
+    provider: new grok('grok-beta')
+});
+```
+
+You can also import the classes directly if you prefer:
+```typescript
+import { Agent, OpenAIProvider, GoogleProvider, GrokProvider } from 'agent-pulse';
+```
+
+## Configuration
+
+| Option | Type | Description |
+|---|---|---|
+| `name` | string | Unique identifier for debugging. |
+| `provider` | LLMProvider | An instance of a provider class (e.g., `new OpenAIProvider(...)`). |
+| `system` | string | System instructions. |
+| `prompt` | string | Base prompt template (optional). |
+| `files` | string[] | Array of file paths or content strings to include in context. |
+| `tools` | Array | List of executable tools with Zod schemas. |
+| `output_schema` | ZodSchema | Enforce structured JSON output (if supported by provider). |
+| `saveFunction` | function | Async function to persist messages (`(msg) => Promise<void>`). |
+
+## Events
+
+Agent Pulse is built on `EventEmitter`. You can listen to the following events:
+
+| Event Name | Description | Payload Structure |
+| :--- | :--- | :--- |
+| `start` | Fired when `agent.run()` is called. | `{ timestamp: number, inputContext: string\|any[] }` |
+| `token` | Fired for each chunk of text generated (streaming). | `string` |
+| `tool_start` | Fired before a tool is executed. | `{ tool: string, arguments: any }` |
+| `tool_end` | Fired after a tool has executed. | `{ tool: string, result: any }` |
+| `response` | Fired when generation is complete. | `AgentResponse` object |
+| `error` | Fired when an error occurs. | `{ error_key: string, message: string, details?: any }` |
+| `log` | General logging event. | `{ level: string, message: string }` |
+
+## Response Structure & Token Usage
+
+The `response` event and the `agent.run()` promise resolve to a standardized `AgentResponse` object:
+
+```typescript
+{
+    content: string | object, // The Markdown text or parsed JSON
+    usage: {
+        input_tokens: number,
+        output_tokens: number,
+        total_tokens: number
+    },
+    meta: {
+        model: string,
+        latency_ms: number
+    }
+}
+```
+
+You can access token usage stats from the `usage` property.
+
+## Error Codes
+
+
+The `error` event payload contains an `error_key` to help you handle specific failure scenarios:
+
+- `network_error`: Connection failures or timeouts.
+- `auth_error`: Invalid API keys or permission issues.
+- `json_error`: Failure parsing structured outputs.
+- `execution_error`: General runtime errors during agent execution.
+- `retry_error`: Max retries exceeded.
+
+### Handling Errors
+
+```typescript
+agent.on('error', (err) => {
+  console.error(`[${err.error_key}]`, err.message);
+});
+```
+
+## Usage Examples
+
+### 1. Tool Use & Intent Detection
+
+Use tools to perform actions or structured data extraction. You can handle the results in two ways: via **events** (for monitoring/side-effects) or via **return values** (for control flow).
+
+#### Option A: Control Flow (Async/Await)
+Best for logic. The tool's return value becomes the agent's final response if the agent decides the task is complete.
+
+```typescript
+import { Agent, google } from 'agent-pulse';
+import { z } from 'zod';
+
+const summaryTool = {
+  name: 'summarize_trip_intent',
+  description: 'Call when you have destination and date.',
+  parameters: z.object({ destination: z.string(), date: z.string() }),
+  execute: async ({ destination, date }) => {
+    // Return a payload. The agent maps this to the final response.
+    return { type: 'INTENT_COMPLETE', payload: { destination, date } };
+  }
+};
+
+const agent = new Agent({
+  name: 'intake',
+  provider: new google('gemini-1.5-pro'),
+  tools: [summaryTool]
+});
+
+// Await the result directly
+const result = await agent.run("I want to go to Paris next week.");
+
+if (result.content?.type === 'INTENT_COMPLETE') {
+  console.log("✅ Intent Detected via Return:", result.content.payload);
+  // Proceed with your app logic...
+}
+```
+
+#### Option B: Events (Side Effects)
+Best for logging, UI updates, or real-time monitoring.
+
+```typescript
+// Listen to 'tool_start' and 'tool_end' for visibility
+agent.on('tool_start', (evt) => {
+  console.log(`[UI] ⏳ Executing tool: ${evt.tool}...`);
+});
+
+agent.on('tool_end', (evt) => {
+  console.log(`[UI] ✔️ Tool finished:`, evt.result);
+});
+
+await agent.run("I want to go to Tokyo.");
+```
+
+### 2. File Input
+
+Pass file content context to the agent.
+
+```typescript
+import { Agent, openAI } from 'agent-pulse';
+
+const agent = new Agent({
+  name: 'analyst',
+  provider: new openAI('gpt-4o'),
+  // You can pass file paths (if handled by environment) or load content yourself
+  files: ['/path/to/data.txt'] 
+});
+```
+
+### 3. Structured Output (JSON)
+
+Enforce a specific JSON schema for the response.
+
+```typescript
+import { Agent, google } from 'agent-pulse';
+import { z } from 'zod';
+
+const recipeSchema = z.object({
+  title: z.string(),
+  ingredients: z.array(z.string()),
+  steps: z.array(z.string())
+});
+
+const agent = new Agent({
+  name: 'chef',
+  provider: new google('gemini-1.5-pro'),
+  output_schema: recipeSchema
+});
+
+agent.on('response', (result) => {
+  // result.content will be a typed object
+  console.log("Recipe:", result.content); 
+});
+
+await agent.run("How do I make pancakes?");
+```
+
+### 4. Server-Side Streaming (SSE)
+
+Bridge agent events to a Server-Sent Events stream for frontend consumption (e.g., in Express).
+
+```typescript
+import { Agent, openAI, bridgeToSSE, setupSSEHeaders } from 'agent-pulse';
+import express from 'express';
+
+const app = express();
+
+app.get('/chat', async (req, res) => {
+  setupSSEHeaders(res);
+
+  const agent = new Agent({ 
+      name: 'web-bot', 
+      provider: new openAI('gpt-4o') 
+  });
+  
+  // Connect agent events to the response stream
+  bridgeToSSE(res, agent);
+
+  await agent.run(req.query.prompt);
+  // Response ends automatically after agent finishes
+});
+```
+
+### 5. Google Search Grounding
+
+Enable real-time search results and citations with Google models.
+
+```typescript
+import { Agent, google } from 'agent-pulse';
+
+const agent = new Agent({
+  name: 'researcher',
+  provider: new google('gemini-2.5-flash-lite'),
+  config: {
+    googleSearch: true
+  }
+});
+
+agent.on('response', (result) => {
+    // Access citation metadata
+    if (result.meta.groundingMetadata) {
+        console.log('Sources:', result.meta.groundingMetadata);
+    }
+});
+
+await agent.run("Who won the Super Bowl in 2024?");
+```
+
+## Extensibility: Custom Providers
+
+To add a new provider (e.g. Anthropic, Mistral), create a class that implements the `LLMProvider` interface.
+
+```typescript
+import { LLMProvider, AgentResponse } from 'agent-pulse/types';
+
+export class MyProvider implements LLMProvider {
+  constructor(private modelName: string) {}
+
+  async generate(system, prompt, files, tools, config, schema, onToken) {
+     // Implement generation logic
+     // Call onToken(chunk) for streaming
+     // Return Promise<AgentResponse>
+  }
+}
+
+// Usage
+const agent = new Agent({
+    name: 'custom-bot',
+    provider: new MyProvider('my-model')
+});
+```
+# To locally link the package
+
+1. Run `npm link` in the agent-pulse directory
+2. Run `npm link agent-pulse --legacy-peer-deps` in your project directory
+
+## License
+
+MIT

package/dist/agent.d.ts

@@ -0,0 +1,8 @@
+import { EventEmitter } from 'events';
+import { AgentConfig, AgentResponse } from './types';
+export declare class Agent extends EventEmitter {
+    private config;
+    private provider;
+    constructor(config: AgentConfig);
+    run(inputContext: string | any[]): Promise<AgentResponse>;
+}

package/dist/agent.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Agent = void 0;
+const events_1 = require("events");
+class Agent extends events_1.EventEmitter {
+    constructor(config) {
+        super();
+        this.config = config;
+        this.provider = config.provider;
+    }
+    async run(inputContext) {
+        this.emit('start', { timestamp: Date.now(), inputContext });
+        const startTime = Date.now();
+        // Persistence: Save User Message if input is a string (new message)
+        if (typeof inputContext === 'string' && this.config.saveFunction) {
+            try {
+                await this.config.saveFunction({ role: 'user', content: inputContext });
+            }
+            catch (err) {
+                console.error("Failed to save user message:", err);
+            }
+        }
+        // Normalize input context
+        let finalPrompt;
+        if (Array.isArray(inputContext)) {
+            finalPrompt = inputContext;
+        }
+        else {
+            const prompt = typeof inputContext === 'string' ? inputContext : String(inputContext);
+            finalPrompt = this.config.prompt ? `${this.config.prompt}\n\n${prompt}` : prompt;
+        }
+        try {
+            const response = await this.provider.generate(this.config.system, finalPrompt, this.config.files, this.config.tools, this.config.config, this.config.output_schema, (token) => this.emit('token', token));
+            // Handle Tool Execution
+            if (response.tool_calls && this.config.tools) {
+                for (const call of response.tool_calls) {
+                    const tool = this.config.tools.find(t => t.name === call.name);
+                    if (tool) {
+                        try {
+                            // Execute the tool
+                            // Note: In this lightweight framework, we return the tool result as the final content.
+                            // This supports the "Intent Detection" pattern where the goal is to trigger an action, not just chat.
+                            this.emit('tool_start', { tool: tool.name, arguments: call.arguments });
+                            const result = await tool.execute(call.arguments);
+                            this.emit('tool_end', { tool: tool.name, result });
+                            response.content = result;
+                        }
+                        catch (e) {
+                            console.error(`Error executing tool ${tool.name}:`, e);
+                        }
+                    }
+                }
+            }
+            // Add latency to meta
+            response.meta.latency_ms = Date.now() - startTime;
+            // Persistence: Save Assistant Response
+            if (this.config.saveFunction) {
+                try {
+                    await this.config.saveFunction({
+                        role: 'assistant',
+                        content: response.content,
+                        usage: response.usage,
+                        meta: response.meta
+                    });
+                }
+                catch (err) {
+                    console.error("Failed to save assistant response:", err);
+                }
+            }
+            this.emit('response', response);
+            return response;
+        }
+        catch (error) {
+            this.emit('error', {
+                error_key: 'execution_error',
+                message: error.message || String(error),
+                details: error
+            });
+            throw error;
+        }
+    }
+}
+exports.Agent = Agent;

package/dist/chain.d.ts

@@ -0,0 +1,53 @@
+import { Agent } from './agent';
+import { AgentResponse } from './types';
+/**
+ * Configuration for a single agent in the chain
+ */
+export interface ChainStep {
+    agent: Agent;
+    input: string | any[] | ((previousResults: AgentResponse[]) => string | any[] | any);
+}
+/**
+ * Result of executing a chain of agents
+ */
+export interface ChainResult {
+    results: AgentResponse[];
+    totalLatency: number;
+    totalTokens: number;
+}
+/**
+ * Chains multiple agents to run sequentially.
+ * Each agent waits for the previous one to complete before starting.
+ *
+ * @param steps - Array of chain steps, each containing an agent and its input
+ * @returns Promise that resolves with all agent responses
+ *
+ * @example
+ * ```typescript
+ * const result = await chain([
+ *   { agent: chatBot, input: 'Hello' },
+ *   { agent: planner, input: (results) => results[0].content },
+ *   { agent: executor, input: (results) => JSON.stringify(results[1].content) }
+ * ]);
+ *
+ * console.log(result.results[0].content); // First agent output
+ * console.log(result.results[1].content); // Second agent output
+ * console.log(result.totalTokens); // Total tokens used
+ * ```
+ */
+export declare function chain(steps: ChainStep[]): Promise<ChainResult>;
+/**
+ * Simplified chain function that accepts just agents and uses previous output as next input.
+ * The first agent must be provided with an initial input separately.
+ *
+ * @param agents - Array of agents to chain
+ * @param initialInput - Input for the first agent
+ * @returns Promise that resolves with all agent responses
+ *
+ * @example
+ * ```typescript
+ * const result = await simpleChain([chatBot, planner, executor], 'Hello');
+ * // Each agent receives the previous agent's content as input
+ * ```
+ */
+export declare function simpleChain(agents: Agent[], initialInput: string | any[]): Promise<ChainResult>;

package/dist/chain.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.chain = chain;
+exports.simpleChain = simpleChain;
+/**
+ * Chains multiple agents to run sequentially.
+ * Each agent waits for the previous one to complete before starting.
+ *
+ * @param steps - Array of chain steps, each containing an agent and its input
+ * @returns Promise that resolves with all agent responses
+ *
+ * @example
+ * ```typescript
+ * const result = await chain([
+ *   { agent: chatBot, input: 'Hello' },
+ *   { agent: planner, input: (results) => results[0].content },
+ *   { agent: executor, input: (results) => JSON.stringify(results[1].content) }
+ * ]);
+ *
+ * console.log(result.results[0].content); // First agent output
+ * console.log(result.results[1].content); // Second agent output
+ * console.log(result.totalTokens); // Total tokens used
+ * ```
+ */
+async function chain(steps) {
+    const results = [];
+    let totalLatency = 0;
+    let totalTokens = 0;
+    for (const step of steps) {
+        // Determine the input for this agent
+        let input;
+        if (typeof step.input === 'function') {
+            input = step.input(results);
+        }
+        else {
+            input = step.input;
+        }
+        // Run the agent and wait for completion
+        const response = await new Promise((resolve, reject) => {
+            // Set up one-time listeners
+            const onResponse = (res) => {
+                cleanup();
+                resolve(res);
+            };
+            const onError = (error) => {
+                cleanup();
+                reject(error);
+            };
+            const cleanup = () => {
+                step.agent.removeListener('response', onResponse);
+                step.agent.removeListener('error', onError);
+            };
+            step.agent.once('response', onResponse);
+            step.agent.once('error', onError);
+            // Start the agent
+            step.agent.run(input).catch(reject);
+        });
+        // Collect results
+        results.push(response);
+        totalLatency += response.meta.latency_ms || 0;
+        totalTokens += response.usage?.total_tokens || 0;
+    }
+    return {
+        results,
+        totalLatency,
+        totalTokens
+    };
+}
+/**
+ * Simplified chain function that accepts just agents and uses previous output as next input.
+ * The first agent must be provided with an initial input separately.
+ *
+ * @param agents - Array of agents to chain
+ * @param initialInput - Input for the first agent
+ * @returns Promise that resolves with all agent responses
+ *
+ * @example
+ * ```typescript
+ * const result = await simpleChain([chatBot, planner, executor], 'Hello');
+ * // Each agent receives the previous agent's content as input
+ * ```
+ */
+async function simpleChain(agents, initialInput) {
+    const steps = agents.map((agent, index) => ({
+        agent,
+        input: index === 0
+            ? initialInput
+            : (results) => results[index - 1].content
+    }));
+    return chain(steps);
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from './agent';
+export * from './types';
+export * from './providers';
+export * from './sse';
+export * from './chain';
+export { OpenAIProvider as openAI } from './providers';
+export { GoogleProvider as google } from './providers';
+export { GrokProvider as xai, GrokProvider as grok } from './providers';
+export * from './utils/image-utils';

package/dist/index.js

@@ -0,0 +1,31 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.grok = exports.xai = exports.google = exports.openAI = void 0;
+__exportStar(require("./agent"), exports);
+__exportStar(require("./types"), exports);
+__exportStar(require("./providers"), exports); // Export classes directly
+__exportStar(require("./sse"), exports);
+__exportStar(require("./chain"), exports);
+// Aliases for better DX and modular imports
+var providers_1 = require("./providers");
+Object.defineProperty(exports, "openAI", { enumerable: true, get: function () { return providers_1.OpenAIProvider; } });
+var providers_2 = require("./providers");
+Object.defineProperty(exports, "google", { enumerable: true, get: function () { return providers_2.GoogleProvider; } });
+var providers_3 = require("./providers");
+Object.defineProperty(exports, "xai", { enumerable: true, get: function () { return providers_3.GrokProvider; } });
+Object.defineProperty(exports, "grok", { enumerable: true, get: function () { return providers_3.GrokProvider; } });
+__exportStar(require("./utils/image-utils"), exports);

package/dist/providers/google.d.ts

@@ -0,0 +1,8 @@
+import { LLMProvider, AgentTool, AgentResponse } from '../types';
+import { z } from 'zod';
+export declare class GoogleProvider implements LLMProvider {
+    private client;
+    private model;
+    constructor(model: string);
+    generate(system: string | undefined, prompt: string | any[], files: string[] | undefined, tools: AgentTool[] | undefined, config: Record<string, any> | undefined, output_schema: z.ZodType<any> | undefined, onToken: (token: string) => void): Promise<AgentResponse>;
+}