agentnet 0.0.2 → 0.0.3

package/src/transport/README.md

@@ -0,0 +1,123 @@
+# Transport Module
+
+This module provides a common interface for different messaging transports used in the agent communication system.
+
+## Architecture
+
+The transport module follows an abstract factory pattern with the following components:
+
+- **Transport Interface**: A base class that defines common methods for all transports
+- **TransportMessage**: A base class for messages exchanged between agents
+- **DiscoveryMessage**: A specialized message class for agent capability discovery
+- **Concrete Implementations**: Implementations of the Transport interface for different messaging systems
+
+## Supported Transports
+
+- NATS
+- Kafka (template implementation)
+- Redis (template implementation)
+- RabbitMQ (template implementation)
+
+## Usage
+
+### Creating a Transport
+
+```javascript
+import { createTransport } from './transport/index.js';
+
+// Create a specific transport
+const natsTransport = createTransport('nats');
+const kafkaTransport = createTransport('kafka');
+const redisTransport = createTransport('redis');
+const rabbitMqTransport = createTransport('rabbitmq');
+
+// Connect to the messaging system
+await natsTransport.connect(config);
+```
+
+### Creating an Agent Runtime
+
+```javascript
+import { createAgentRuntime } from './transport/index.js';
+
+// Create a runtime for an agent with a specific transport
+const runtime = await createAgentRuntime('nats', namespace, agentName, ioInterfaces, discoverySchemas);
+
+// Use the runtime to handle tasks
+await runtime.handleTask(async (message) => {
+  // Process the task
+  return responseMessage;
+});
+
+// Access discovered agents
+const discoveredAgents = runtime.discoveredAgents;
+```
+
+### Using the Transport Directly
+
+```javascript
+import { createTransport } from './transport/index.js';
+
+// Create and connect a transport
+const transport = createTransport('nats');
+await transport.connect(config);
+
+// Publish a message
+await transport.publish('topic', message);
+
+// Subscribe to a topic
+await transport.subscribe('topic', handleMessage);
+
+// Send a request and wait for a response
+const response = await transport.request('target', message);
+```
+
+## Extending with New Transports
+
+To add a new transport:
+
+1. Create a new file (e.g., `myTransport.js`) that implements the Transport interface
+2. Create a factory function that returns a new instance of your transport
+3. Register the factory in the `transportFactories` map in `index.js`
+4. Create a runtime function and register it in the `runtimeFactories` map
+
+Example:
+
+```javascript
+// myTransport.js
+import { Transport } from './base.js';
+
+export class MyTransport extends Transport {
+  // Implement all required methods
+}
+
+export function createMyTransport() {
+  return new MyTransport();
+}
+
+export async function MyTransportIOAgentRuntime(namespace, agentName, ioInterfaces, discoverySchemas) {
+  // Implementation
+}
+
+// index.js - update the factory maps
+const transportFactories = {
+  // ...existing transports
+  'mytransport': createMyTransport
+};
+
+const runtimeFactories = {
+  // ...existing runtimes
+  'mytransport': MyTransportIOAgentRuntime
+};
+```
+
+## Common Interface
+
+All transports must implement these key methods:
+
+- `connect(config)`: Connect to the messaging system
+- `disconnect()`: Disconnect from the messaging system
+- `publish(topic, message)`: Publish a message to a topic
+- `subscribe(topic, options)`: Subscribe to a topic
+- `request(target, message, options)`: Send a request and wait for a response
+- `createRuntime(namespace, agentName, discoverySchemas, config)`: Create a runtime for agent communication 

package/src/transport/base.js

@@ -0,0 +1,237 @@
+/**
+ * Base Transport Interface
+ * Defines common functionality across different transport implementations (NATS, Kafka, RabbitMQ, Redis, etc.)
+ */
+import { TransportError } from '../errors/index.js';
+import { logger } from '../utils/logger.js';
+
+/**
+ * Base TransportMessage class that can be extended by specific transport implementations
+ */
+export class TransportMessage {
+    constructor(type, payload) {
+        this.type = type;
+        this.payload = payload;
+    }
+    
+    serialize() {
+        return JSON.stringify({
+            type: this.type,
+            payload: this.payload
+        });
+    }
+    
+    static fromString(data) {
+        try {
+            const parsed = JSON.parse(data);
+            return new TransportMessage(parsed.type, parsed.payload);
+        } catch (error) {
+            throw new Error(`Failed to parse message: ${error.message}`);
+        }
+    }
+}
+
+/**
+ * Discovery Message format for agent discovery
+ */
+export class DiscoveryMessage extends TransportMessage {
+    constructor(namespace, agentName, schemas) {
+        if (!namespace) throw new Error('Namespace is required');
+        if (!agentName) throw new Error('Agent name is required');
+        if (!Array.isArray(schemas)) throw new Error('Schemas must be an array');
+        
+        const payload = {
+            network: `${namespace}.${agentName}`,
+            agentName: agentName,
+            schemas: schemas
+        };
+        
+        super('discovery', payload);
+    }
+    
+    get network() {
+        return this.payload.network;
+    }
+    
+    get agentName() {
+        return this.payload.agentName;
+    }
+    
+    get schemas() {
+        return this.payload.schemas;
+    }
+    
+    static fromString(data) {
+        const message = TransportMessage.fromString(data);
+        
+        if (message.type !== 'discovery') {
+            throw new Error('Not a discovery message');
+        }
+        
+        // Extract namespace from network (format: namespace.agentName)
+        const networkParts = message.payload.network.split('.');
+        if (networkParts.length !== 2) {
+            throw new Error('Invalid network format in discovery message');
+        }
+        
+        const namespace = networkParts[0];
+        return new DiscoveryMessage(
+            namespace, 
+            message.payload.agentName, 
+            message.payload.schemas
+        );
+    }
+    
+    static isValid(payload) {
+        return (
+            payload &&
+            typeof payload === 'object' &&
+            payload.type === 'discovery' &&
+            typeof payload.payload.network === 'string' &&
+            typeof payload.payload.agentName === 'string' &&
+            Array.isArray(payload.payload.schemas)
+        );
+    }
+}
+
+/**
+ * Base Transport Interface - all transport implementations should implement this interface
+ */
+export class Transport {
+    /**
+     * Create a new transport instance
+     * @param {string} transportType - The type of transport (e.g., 'NATS', 'Kafka')
+     */
+    constructor(transportType) {
+        this.transportType = transportType;
+        this.connected = false;
+        this.intervals = [];
+    }
+    
+    /**
+     * Connect to the transport
+     * @param {Object} config - Configuration options
+     * @returns {Promise<any>} - The connection instance
+     */
+    async connect(config) {
+        throw new Error('Method connect() must be implemented by subclass');
+    }
+    
+    /**
+     * Disconnect from the transport
+     * @returns {Promise<void>}
+     */
+    async disconnect() {
+        // Clean up intervals
+        this.intervals.forEach(clearInterval);
+        this.intervals = [];
+        
+        this.connected = false;
+    }
+    
+    /**
+     * Publish a message to a topic/channel
+     * @param {string} topic - The topic/channel to publish to
+     * @param {string|Buffer|Object} message - The message to publish
+     * @returns {Promise<void>}
+     */
+    async publish(topic, message) {
+        throw new Error('Method publish() must be implemented by subclass');
+    }
+    
+    /**
+     * Subscribe to a topic/channel
+     * @param {string} topic - The topic/channel to subscribe to
+     * @param {Object} options - Subscription options
+     * @returns {Promise<any>} - The subscription instance
+     */
+    async subscribe(topic, options = {}) {
+        throw new Error('Method subscribe() must be implemented by subclass');
+    }
+    
+    /**
+     * Send a request and wait for a response
+     * @param {string} target - The target to send the request to
+     * @param {string|Buffer|Object} message - The message to send
+     * @param {Object} options - Request options
+     * @returns {Promise<any>} - The response
+     */
+    async request(target, message, options = {}) {
+        throw new Error('Method request() must be implemented by subclass');
+    }
+    
+    /**
+     * Set up heartbeat to announce agent capabilities
+     * @param {string} topic - The topic to publish heartbeats to
+     * @param {string} namespace - The agent namespace
+     * @param {string} agentName - The agent name
+     * @param {Array} schemas - The agent capability schemas
+     * @param {number} interval - The heartbeat interval in milliseconds
+     * @returns {number} - The interval ID
+     */
+    setupHeartbeat(topic, namespace, agentName, schemas, interval = 1000) {
+        const heartbeatInterval = setInterval(async () => {
+            try {
+                const discoveryMessage = new DiscoveryMessage(namespace, agentName, schemas);
+                await this.publish(topic, discoveryMessage.serialize());
+            } catch (error) {
+                logger.error(`Failed to publish heartbeat for ${agentName}`, {
+                    error,
+                    transportType: this.transportType
+                });
+            }
+        }, interval);
+        
+        this.intervals.push(heartbeatInterval);
+        return heartbeatInterval;
+    }
+    
+    /**
+     * Creates a runtime for agent communication
+     * @param {string} namespace - The agent namespace
+     * @param {string} agentName - The agent name
+     * @param {Array} discoverySchemas - The agent capability schemas for discovery
+     * @param {Object} config - Additional configuration
+     * @returns {Promise<Object>} - The runtime { handleTask, discoveredAgents }
+     */
+    async createRuntime(namespace, agentName, discoverySchemas, config = {}) {
+        throw new Error('Method createRuntime() must be implemented by subclass');
+    }
+}
+
+/**
+ * Safely connect to a transport with retry logic
+ * @param {Transport} transport - The transport instance
+ * @param {Object} config - Connection configuration
+ * @param {Object} options - Retry options
+ * @returns {Promise<any>} - The connection instance
+ */
+export async function safeConnect(transport, config, options = {}) {
+    const { maxRetries = 5 } = options;
+    
+    let attempt = 0;
+    let lastError = null;
+    
+    while (attempt < maxRetries) {
+        try {
+            attempt++;
+            return await transport.connect(config);
+        } catch (error) {
+            lastError = error;
+            logger.warn(`Transport connect attempt ${attempt}/${maxRetries} failed, retrying...`, {
+                transportType: transport.transportType,
+                error: error.message
+            });
+            
+            // Exponential backoff
+            const delay = Math.min(1000 * Math.pow(2, attempt - 1), 10000);
+            await new Promise(resolve => setTimeout(resolve, delay));
+        }
+    }
+    
+    throw new TransportError(
+        `Failed to connect after ${maxRetries} attempts: ${lastError?.message}`,
+        transport.transportType,
+        { details: lastError?.message }
+    );
+} 

package/src/transport/index.js

@@ -0,0 +1,89 @@
+/**
+ * Transport Factory Module
+ * Provides a unified interface to create transport instances
+ */
+import { Transport } from './base.js';
+import { createNatsTransport, NatsIOAgentRuntime } from './nats.js';
+import { createKafkaTransport, KafkaIOAgentRuntime } from './kafka.js';
+import { createRedisTransport, RedisIOAgentRuntime } from './redis.js';
+import { createRabbitMQTransport, RabbitMQIOAgentRuntime } from './rabbitmq.js';
+import { TransportError } from '../errors/index.js';
+import { logger } from '../utils/logger.js';
+
+// Map of transport types to their factory functions
+const transportFactories = {
+    'nats': createNatsTransport,
+    'kafka': createKafkaTransport,
+    'redis': createRedisTransport,
+    'rabbitmq': createRabbitMQTransport,
+};
+
+// Map of transport types to their runtime functions
+const runtimeFactories = {
+    'nats': NatsIOAgentRuntime,
+    'kafka': KafkaIOAgentRuntime,
+    'redis': RedisIOAgentRuntime,
+    'rabbitmq': RabbitMQIOAgentRuntime,
+};
+
+/**
+ * Create a transport instance based on the specified type
+ * @param {string} type - The transport type (e.g., 'nats', 'kafka', 'redis', 'rabbitmq')
+ * @returns {Transport} - A transport instance
+ * @throws {TransportError} - If the transport type is not supported
+ */
+export function createTransport(type) {
+    const factoryFn = transportFactories[type.toLowerCase()];
+    
+    if (!factoryFn) {
+        throw new TransportError(
+            `Unsupported transport type: ${type}`,
+            'TransportFactory',
+            { supportedTypes: Object.keys(transportFactories) }
+        );
+    }
+    
+    return factoryFn();
+}
+
+/**
+ * Create a transport runtime for an agent
+ * @param {string} type - The transport type (e.g., 'nats', 'kafka', 'redis', 'rabbitmq')
+ * @param {string} namespace - The agent namespace
+ * @param {string} agentName - The agent name
+ * @param {Array} ioInterfaces - The IO interfaces
+ * @param {Array} discoverySchemas - The agent capability schemas for discovery
+ * @returns {Promise<Object>} - The runtime { handleTask, discoveredAgents }
+ * @throws {TransportError} - If the transport type is not supported
+ */
+export async function createAgentRuntime(type, namespace, agentName, ioInterfaces, discoverySchemas) {
+    const runtimeFn = runtimeFactories[type.toLowerCase()];
+    
+    if (!runtimeFn) {
+        throw new TransportError(
+            `Unsupported transport runtime type: ${type}`,
+            'TransportFactory',
+            { supportedTypes: Object.keys(runtimeFactories) }
+        );
+    }
+    
+    try {
+        return await runtimeFn(namespace, agentName, ioInterfaces, discoverySchemas);
+    } catch (error) {
+        logger.error(`Failed to create ${type} agent runtime`, { error, agentName });
+        throw error;
+    }
+}
+
+/**
+ * Export base classes and interfaces for extensibility
+ */
+export * from './base.js';
+
+/**
+ * Export specific transport implementations
+ */
+export * from './nats.js';
+export * from './kafka.js';
+export * from './redis.js';
+export * from './rabbitmq.js';