agent-pulse 1.0.0

package/dist/sse.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupSSEHeaders = setupSSEHeaders;
+exports.bridgeToSSE = bridgeToSSE;
+/**
+ * Sets up standard Server-Sent Events (SSE) headers on the response object.
+ * Compatible with Node.js http.ServerResponse and Express Response.
+ * @param res The response object
+ */
+function setupSSEHeaders(res) {
+    if (typeof res.setHeader === 'function') {
+        res.setHeader('Content-Type', 'text/event-stream');
+        res.setHeader('Cache-Control', 'no-cache');
+        res.setHeader('Connection', 'keep-alive');
+        // Ensure flushing validation
+        if (typeof res.flushHeaders === 'function') {
+            res.flushHeaders();
+        }
+    }
+}
+/**
+ * Bridges Agent events to a Server-Sent Events (SSE) stream.
+ * Automatically attaches listeners to the agent and writes formatted SSE events to the response.
+ *
+ * @param res The response object (Node.js or Express)
+ * @param agent The Agent instance to listen to
+ */
+function bridgeToSSE(res, agent) {
+    const sendEvent = (event, data) => {
+        // We use JSON.stringify to safely serialize the data (strings or objects)
+        // This handles newlines and special characters correctly in the SSE format.
+        res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+        // Optional: Flush if method exists (some environments need explicit flush)
+        if (typeof res.flush === 'function') {
+            res.flush();
+        }
+    };
+    // Listen to 'token' events for streaming
+    const tokenListener = (token) => {
+        sendEvent('token', token);
+    };
+    // Listen to 'response' event for final completion
+    const responseListener = (response) => {
+        sendEvent('response', response);
+        cleanup();
+        res.end();
+    };
+    // Listen to 'error' event
+    const errorListener = (error) => {
+        sendEvent('error', error);
+        cleanup();
+        res.end();
+    };
+    // Cleanup listeners to avoid memory leaks if the agent is reused (though usually one-off)
+    const cleanup = () => {
+        agent.off('token', tokenListener);
+        agent.off('response', responseListener);
+        agent.off('error', errorListener);
+    };
+    agent.on('token', tokenListener);
+    agent.on('response', responseListener);
+    agent.on('error', errorListener);
+    // Handle client disconnect if possible
+    if (res.on) {
+        res.on('close', cleanup);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+export interface AgentConfig {
+    name: string;
+    provider: LLMProvider;
+    prompt?: string;
+    system?: string;
+    files?: string[];
+    config?: Record<string, any>;
+    tools?: AgentTool[];
+    output_schema?: z.ZodType<any>;
+    saveFunction?: (message: any) => Promise<void> | void;
+}
+export interface AgentTool {
+    name: string;
+    description: string;
+    parameters: z.ZodType<any>;
+    execute: (args: any) => Promise<any>;
+}
+export interface AgentResponse {
+    content: string | object;
+    tool_calls?: any[];
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+        total_tokens: number;
+        reasoning_tokens?: number;
+    };
+    meta: {
+        model: string;
+        latency_ms: number;
+        [key: string]: any;
+    };
+}
+export interface AgentEvent {
+    type: 'start' | 'token' | 'tool_start' | 'tool_end' | 'response' | 'error' | 'log';
+    payload: any;
+}
+export interface AgentError {
+    error_key: 'network_error' | 'auth_error' | 'json_error' | 'execution_error' | 'retry_error';
+    message: string;
+    details?: any;
+}
+export interface LLMProvider {
+    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>;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils/file-utils.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Validates if a file has an allowed extension
+ */
+export declare function validateFileExtension(filePath: string, allowedExtensions: string[]): boolean;
+/**
+ * Reads a markdown file and returns its content
+ * @throws Error if file doesn't exist, can't be read, or has wrong extension
+ */
+export declare function readMarkdownFile(filePath: string): string;
+/**
+ * Checks if a file is a supported image type
+ */
+export declare function isImageFile(filePath: string): boolean;
+/**
+ * Reads an image file and returns base64 content
+ */
+export declare function readImageFile(filePath: string): string;
+/**
+ * Reads multiple files (markdown or image) and formats them for provider consumption.
+ * Returns an array of file objects to be processed by the provider.
+ * Note: This changes the return signature from string to object array, so we'll keep the string return for text-only
+ * compatibility for now, but providers should likely use a richer internal format if we were doing a full refactor.
+ * For this "Native First" approach, we will keep `readMarkdownFiles` as is for text, and let providers call specific readers.
+ * actually, let's keep `readMarkdownFiles` as is for backward compatibility and just export the new helpers.
+ */
+export declare function readMarkdownFiles(filePaths: string[]): string;

package/dist/utils/file-utils.js

@@ -0,0 +1,128 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateFileExtension = validateFileExtension;
+exports.readMarkdownFile = readMarkdownFile;
+exports.isImageFile = isImageFile;
+exports.readImageFile = readImageFile;
+exports.readMarkdownFiles = readMarkdownFiles;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Validates if a file has an allowed extension
+ */
+function validateFileExtension(filePath, allowedExtensions) {
+    const ext = path.extname(filePath).toLowerCase();
+    return allowedExtensions.includes(ext);
+}
+/**
+ * Reads a markdown file and returns its content
+ * @throws Error if file doesn't exist, can't be read, or has wrong extension
+ */
+function readMarkdownFile(filePath) {
+    // Validate extension
+    if (!validateFileExtension(filePath, ['.md', '.markdown'])) {
+        throw new Error(`Invalid file extension for ${filePath}. Only .md and .markdown files are supported.`);
+    }
+    // Check if file exists
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`File not found: ${filePath}`);
+    }
+    // Read file
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        return content;
+    }
+    catch (error) {
+        throw new Error(`Failed to read file ${filePath}: ${error.message}`);
+    }
+}
+// Image extensions supported by Gemini and common web usage
+const IMAGE_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.webp', '.heic', '.heif'];
+/**
+ * Checks if a file is a supported image type
+ */
+function isImageFile(filePath) {
+    return validateFileExtension(filePath, IMAGE_EXTENSIONS);
+}
+/**
+ * Reads an image file and returns base64 content
+ */
+function readImageFile(filePath) {
+    if (!isImageFile(filePath)) {
+        throw new Error(`Invalid image file extension for ${filePath}`);
+    }
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`File not found: ${filePath}`);
+    }
+    try {
+        const fileBuffer = fs.readFileSync(filePath);
+        return fileBuffer.toString('base64');
+    }
+    catch (error) {
+        throw new Error(`Failed to read image file ${filePath}: ${error.message}`);
+    }
+}
+/**
+ * Reads multiple files (markdown or image) and formats them for provider consumption.
+ * Returns an array of file objects to be processed by the provider.
+ * Note: This changes the return signature from string to object array, so we'll keep the string return for text-only
+ * compatibility for now, but providers should likely use a richer internal format if we were doing a full refactor.
+ * For this "Native First" approach, we will keep `readMarkdownFiles` as is for text, and let providers call specific readers.
+ * actually, let's keep `readMarkdownFiles` as is for backward compatibility and just export the new helpers.
+ */
+function readMarkdownFiles(filePaths) {
+    if (!filePaths || filePaths.length === 0) {
+        return '';
+    }
+    const fileContents = [];
+    for (const filePath of filePaths) {
+        // Skip non-markdown files silently in this specific text-aggregator function
+        // so we don't break existing text-only prompts if an image is passed in the mixed list.
+        // The provider will handle the image files separately.
+        if (validateFileExtension(filePath, ['.md', '.markdown'])) {
+            try {
+                const content = readMarkdownFile(filePath);
+                const fileName = path.basename(filePath);
+                fileContents.push(`--- File: ${fileName} ---\n\n${content}\n\n--- End of ${fileName} ---`);
+            }
+            catch (error) {
+                // Re-throw to be handled by the provider
+                throw error;
+            }
+        }
+    }
+    return fileContents.join('\n\n');
+}

package/dist/utils/image-utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Extracts a base64 encoded image from a text response and saves it to a file.
+ *
+ * @param content The text content containing the data URL (e.g. "data:image/png;base64,...")
+ * @param outputDir The directory where the image should be saved
+ * @param filename Optional filename. If not provided, a timestamp-based name will be used.
+ * @returns The absolute path to the saved file, or throws an error if no image data is found.
+ */
+export declare function saveImage(content: string, outputDir: string, filename?: string): string;

package/dist/utils/image-utils.js

@@ -0,0 +1,36 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.saveImage = saveImage;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/**
+ * Extracts a base64 encoded image from a text response and saves it to a file.
+ *
+ * @param content The text content containing the data URL (e.g. "data:image/png;base64,...")
+ * @param outputDir The directory where the image should be saved
+ * @param filename Optional filename. If not provided, a timestamp-based name will be used.
+ * @returns The absolute path to the saved file, or throws an error if no image data is found.
+ */
+function saveImage(content, outputDir, filename) {
+    // Regex to find the data URL pattern and capture the base64 data
+    // Matches: data:image/<type>;base64,<data>
+    const dataUrlRegex = /data:image\/(\w+);base64,([A-Za-z0-9+/=]+)/;
+    const match = content.match(dataUrlRegex);
+    if (!match || !match[2]) {
+        throw new Error("No base64 image data found in content.");
+    }
+    const imageType = match[1]; // e.g., 'png', 'jpeg'
+    const base64Data = match[2];
+    const buffer = Buffer.from(base64Data, 'base64');
+    // Ensure output directory exists
+    if (!fs_1.default.existsSync(outputDir)) {
+        fs_1.default.mkdirSync(outputDir, { recursive: true });
+    }
+    const finalFilename = filename || `generated_image_${Date.now()}.${imageType}`;
+    const outputPath = path_1.default.resolve(outputDir, finalFilename);
+    fs_1.default.writeFileSync(outputPath, buffer);
+    return outputPath;
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+    "name": "agent-pulse",
+    "version": "1.0.0",
+    "description": "A lightweight, agentic AI framework for JavaScript/TypeScript",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "sideEffects": false,
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "watch": "tsc --watch",
+        "test": "vitest",
+        "prepublishOnly": "npm run build"
+    },
+    "keywords": [
+        "ai",
+        "agent",
+        "framework",
+        "llm",
+        "openai",
+        "gemini"
+    ],
+    "author": "Mihir Panchal",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/mehere14/Agentic-Framework.git",
+        "directory": "agent-pulse"
+    },
+    "bugs": {
+        "url": "https://github.com/mehere14/Agentic-Framework/issues"
+    },
+    "homepage": "https://github.com/mehere14/Agentic-Framework/tree/main/agent-pulse#readme",
+    "dependencies": {
+        "@google/genai": "^1.33.0",
+        "dotenv": "^16.4.5",
+        "openai": "^4.28.0",
+        "zod": "^4.0.0"
+    },
+    "devDependencies": {
+        "@types/node": "^20.19.26",
+        "ts-node": "^10.9.2",
+        "typescript": "^5.3.3",
+        "vitest": "^1.3.1"
+    }
+}