agentnet 0.0.1

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "agentnet",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Agent library used by Smartness",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@google/genai": "^0.12.0",
+    "@nats-io/nats-core": "^3.0.2",
+    "@nats-io/transport-node": "^3.0.2",
+    "colors": "^1.4.0",
+    "openai": "^4.97.0",
+    "pg": "^8.15.6",
+    "redis": "^5.0.1",
+    "uuid": "^11.1.0",
+    "yaml": "^2.7.1"
+  }
+}

package/src/agent/agent-loader.js

@@ -0,0 +1,274 @@
+import fs from 'fs'
+import { parse } from 'yaml'
+import { Gemini } from "../index.js"
+import { Agent } from "./agent.js"
+
+/**
+ * Loads agent definitions from a YAML file
+ * @param {string} path - Path to the YAML file
+ * @param {object} config - Configuration options
+ * @returns {Promise<object>} Map of loaded agents
+ */
+export async function AgentLoaderFile(path, config) {
+    try {
+        const yamlFileContent = fs.readFileSync(path, 'utf8');
+        const agentDefinitions = parseAgentDefinitionsFromYaml(yamlFileContent);
+        return await AgentLoader(agentDefinitions, config);
+    } catch (error) {
+        throw new Error(`Failed to load agents from file ${path}: ${error.message}`);
+    }
+}
+
+/**
+ * Loads agent definitions from JSON
+ * @param {object} json - JSON definition
+ * @param {object} config - Configuration options
+ * @returns {Promise<object>} Map of loaded agents
+ */
+export async function AgentLoaderJSON(json, config) {
+    return await AgentLoader([json], config);
+}
+
+/**
+ * Parses agent definitions from YAML content
+ * @param {string} yamlContent - YAML content to parse
+ * @returns {Array} Array of agent definitions
+ */
+function parseAgentDefinitionsFromYaml(yamlContent) {
+    const agentDefsYaml = yamlContent.split(/^---$/m)
+        .map(s => s.trim())
+        .filter(s => s);
+    
+    const agentDefinitions = [];
+    
+    for (const agentDef of agentDefsYaml) {
+        try {
+            const definition = parse(agentDef);
+            if (isValidAgentDefinition(definition)) {
+                agentDefinitions.push(definition);
+            } else {
+                console.warn("Skipping invalid or non-AgentDefinition document in YAML.");
+            }
+        } catch (error) {
+            console.warn(`Failed to parse YAML document: ${error.message}`);
+        }
+    }
+    
+    return agentDefinitions;
+}
+
+/**
+ * Checks if a definition is a valid agent definition
+ * @param {object} definition - Definition to validate
+ * @returns {boolean} Whether definition is valid
+ */
+function isValidAgentDefinition(definition) {
+    return definition && definition.kind === 'AgentDefinition' && definition.spec;
+}
+
+/**
+ * Loads an LLM provider instance
+ * @param {string} providerName - Name of the provider
+ * @returns {object} LLM provider instance
+ */
+async function loadLlmProvider(providerName) {
+    if (providerName === 'Gemini') {
+        return Gemini;
+    }
+    
+    try {
+        return global[providerName] || await import(providerName);
+    } catch (error) {
+        throw new Error(`LLM Provider "${providerName}" could not be loaded: ${error.message}`);
+    }
+}
+
+/**
+ * Configures IO for an agent
+ * @param {object} agentBuilder - Agent builder instance
+ * @param {Array} ioDefinitions - IO definitions
+ * @param {object} bindings - IO bindings
+ * @returns {object} Updated agent builder
+ */
+function configureIO(agentBuilder, ioDefinitions, bindings) {
+    if (!ioDefinitions || !Array.isArray(ioDefinitions)) {
+        return agentBuilder;
+    }
+    
+    for (const ioDef of ioDefinitions) {
+        if (!bindings[ioDef.type]) {
+            throw new Error(`Missing binding for IO type: ${ioDef.type}`);
+        }
+        
+        if (ioDef.type === 'NatsIO') {
+            agentBuilder = agentBuilder.addIO(bindings[ioDef.type], ioDef);
+        } else {
+            throw new Error(`Unsupported IO type: ${ioDef.type}`);
+        }
+    }
+    
+    return agentBuilder;
+}
+
+/**
+ * Configures store for an agent
+ * @param {object} agentBuilder - Agent builder instance
+ * @param {object} storeSpec - Store specification
+ * @param {object} bindings - Store bindings
+ * @returns {object} Updated agent builder
+ */
+function configureStore(agentBuilder, storeSpec, bindings) {
+    if (!storeSpec) {
+        return agentBuilder;
+    }
+    
+    const storeType = storeSpec.type;
+    
+    if (!bindings[storeType]) {
+        throw new Error(`Missing binding for store type: ${storeType}`);
+    }
+    
+    // Add store to agent builder
+    return agentBuilder.withStore(bindings[storeType], storeSpec);
+}
+
+/**
+ * Configures LLM for an agent
+ * @param {object} agentBuilder - Agent builder instance
+ * @param {object} llmSpec - LLM specification
+ * @returns {Promise<object>} Updated agent builder
+ */
+async function configureLLM(agentBuilder, llmSpec) {
+    if (!llmSpec) {
+        return agentBuilder;
+    }
+    
+    const llmProviderInstance = await loadLlmProvider(llmSpec.provider);
+    
+    return agentBuilder.withLLM(llmProviderInstance, {
+        model: llmSpec.model,
+        systemInstruction: llmSpec.systemInstruction,
+        config: llmSpec.config
+    });
+}
+
+/**
+ * Configures discovery schemas for an agent
+ * @param {object} agentBuilder - Agent builder instance
+ * @param {Array} schemas - Discovery schemas
+ * @returns {object} Updated agent builder
+ */
+function configureDiscoverySchemas(agentBuilder, schemas) {
+    if (!schemas || !Array.isArray(schemas)) {
+        return agentBuilder;
+    }
+    
+    for (const schema of schemas) {
+        agentBuilder = agentBuilder.addDiscoverySchema(schema);
+    }
+    
+    return agentBuilder;
+}
+
+/**
+ * Configures tools for an agent
+ * @param {object} agentBuilder - Agent builder instance
+ * @param {Array} toolsSpec - Tools specification
+ * @returns {object} Tool map
+ */
+function configureTools(agentBuilder, toolsSpec) {
+    const toolMap = {};
+    
+    if (!toolsSpec || !Array.isArray(toolsSpec)) {
+        return toolMap;
+    }
+    
+    for (const toolDef of toolsSpec) {
+        agentBuilder._config.toolsSchemas[toolDef.name] = {
+            name: toolDef.name,
+            schema: toolDef,
+            function: null
+        };
+        
+        toolMap[toolDef.name] = {
+            bind: (handlerFunction) => {
+                agentBuilder._config.toolsSchemas[toolDef.name].function = handlerFunction;
+            }
+        };
+    }
+    
+    return toolMap;
+}
+
+/**
+ * Creates an agent interface
+ * @param {object} agentBuilder - Agent builder instance
+ * @param {object} toolMap - Tool map
+ * @returns {object} Agent interface
+ */
+function createAgentInterface(agentBuilder, toolMap) {
+    return {
+        tools: toolMap,
+        prompt: (callback) => {
+            agentBuilder._config.on.prompt = callback;
+        },
+        response: (callback) => {
+            agentBuilder._config.on.response = callback;
+        },
+        compile: async () => {
+            return await agentBuilder.compile();
+        }
+    };
+}
+
+/**
+ * Main agent loading function
+ * @param {Array} agentsDefinitions - Array of agent definitions
+ * @param {object} config - Configuration options
+ * @returns {Promise<object>} Map of loaded agents
+ */
+async function AgentLoader(agentsDefinitions, config = {}) {
+    const bindings = config.bindings || {};
+    const loadedAgents = {};
+
+    for (const definition of agentsDefinitions) {
+        try {
+            if (!definition.spec) {
+                throw new Error(`Invalid agent definition: missing spec`);
+            }
+            
+            const spec = definition.spec;
+            const metadata = definition.metadata || { 
+                name: "default", 
+                description: "Agent from definition" 
+            };
+            
+            if (!metadata.name) {
+                throw new Error("Agent definition is missing metadata.name");
+            }
+            
+            // Initialize agent builder with metadata
+            let agentBuilder = Agent().setMetadata(metadata);
+            
+            // Configure different aspects of the agent
+            agentBuilder = configureIO(agentBuilder, spec.io, bindings);
+            agentBuilder = configureStore(agentBuilder, spec.store, bindings);
+            agentBuilder = await configureLLM(agentBuilder, spec.llm);
+            agentBuilder = configureDiscoverySchemas(agentBuilder, spec.discoverySchemas);
+            
+            // Set up tools
+            const toolMap = configureTools(agentBuilder, spec.tools);
+            
+            // Create the agent interface
+            loadedAgents[metadata.name] = createAgentInterface(agentBuilder, toolMap);
+            
+        } catch (error) {
+            const agentName = definition.metadata?.name || 'Unnamed Agent';
+            console.error(`Failed to load agent "${agentName}": ${error.message}`);
+            // Optional: decide whether to throw or just log and continue
+            // throw error;
+        }
+    }
+
+    return loadedAgents;
+}

package/src/agent/agent.js

@@ -0,0 +1,416 @@
+import { AgentRuntime } from "./runtime.js"
+import { 
+    validateRequired, 
+    validateType, 
+    validateObject, 
+    validateEnum
+} from "../utils/validation.js"
+import { CompilationError, ConfigurationError } from "../errors/index.js"
+import { logger } from "../utils/logger.js"
+
+/**
+ * Default hooks for agent events
+ */
+const DEFAULT_HOOKS = {
+    prompt: async (state, formattedInput) => formattedInput,
+    response: async (state, conversation, result) => result
+}
+
+/**
+ * Default agent configuration
+ */
+const DEFAULT_CONFIG = {
+    metadata: {
+        name: "default",
+        description: "A default agent"
+    },
+    runner: { 
+        maxRuns: 10
+    }
+}
+
+/**
+ * Schema for agent configuration validation
+ */
+const AGENT_CONFIG_SCHEMA = {
+    type: 'object',
+    properties: {
+        metadata: {
+            type: 'object',
+            properties: {
+                name: { type: 'string' },
+                description: { type: 'string' }
+            },
+            required: ['name']
+        },
+        llm: {
+            type: 'object',
+            properties: {
+                api: { type: 'object' },
+                config: { type: 'object' }
+            },
+            required: ['api']
+        },
+        store: {
+            type: 'object',
+            properties: {
+                instance: { type: 'object' },
+                config: { type: 'object' }
+            }
+        },
+        io: { type: 'array' },
+        handoffs: { type: 'array' },
+        discoverySchemas: { type: 'array' },
+        toolsAndHandoffsMap: { 
+            type: 'object',
+            properties: {
+                tools: { type: 'array' }
+            }
+        },
+        toolsSchemas: { type: 'object' },
+        runner: {
+            type: 'object',
+            properties: {
+                maxRuns: { type: 'number' }
+            }
+        },
+        on: { type: 'object' }
+    },
+    required: ['metadata', 'llm']
+}
+
+/**
+ * Creates a new Agent builder
+ * @returns {Object} Agent builder interface
+ */
+export function Agent() {
+    // Initialize agent configuration
+    const config = {
+        metadata: { ...DEFAULT_CONFIG.metadata },
+        llm: {},
+        store: null,
+        io: [],
+        handoffs: [],
+        discoverySchemas: [],
+        hooks: null,
+        toolsAndHandoffsMap: { 
+            tools: []
+        },
+        toolsSchemas: {},
+        runner: { ...DEFAULT_CONFIG.runner },
+        on: { ...DEFAULT_HOOKS }
+    }
+
+    /**
+     * Validates that required configuration is present and well-formed
+     * @throws {ConfigurationError} If configuration is invalid
+     */
+    function validateConfiguration() {
+        try {
+            // Validate overall structure against schema
+            validateObject(config, AGENT_CONFIG_SCHEMA, 'agent_config');
+            
+            // Additional specific validations
+            
+            // Metadata validation
+            if (!config.metadata.name.trim()) {
+                throw new ConfigurationError("Agent name cannot be empty", { 
+                    metadata: config.metadata 
+                });
+            }
+            
+            // LLM API validation
+            if (typeof config.llm.api !== 'object' || config.llm.api === null) {
+                throw new ConfigurationError("LLM API must be a valid object", { 
+                    api: config.llm.api 
+                });
+            }
+            
+            if (!config.llm.api.getClient || typeof config.llm.api.getClient !== 'function') {
+                throw new ConfigurationError("LLM API must have a getClient method", { 
+                    apiMethods: Object.keys(config.llm.api)
+                });
+            }
+            
+            if (!config.llm.api.callModel || typeof config.llm.api.callModel !== 'function') {
+                throw new ConfigurationError("LLM API must have a callModel method", { 
+                    apiMethods: Object.keys(config.llm.api)
+                });
+            }
+            
+            // Store validation if present
+            if (config.store) {
+                if (typeof config.store.instance !== 'object' || config.store.instance === null) {
+                    throw new ConfigurationError("Store instance must be a valid object", { 
+                        store: config.store 
+                    });
+                }
+                
+                if (!config.store.instance.connect || typeof config.store.instance.connect !== 'function') {
+                    throw new ConfigurationError("Store instance must have a connect method", { 
+                        storeInstanceMethods: Object.keys(config.store.instance)
+                    });
+                }
+            }
+            
+            // IO validation
+            if (config.io.length > 0) {
+                config.io.forEach((io, index) => {
+                    if (!io.type) {
+                        throw new ConfigurationError(`IO interface at index ${index} has no type`, { 
+                            io 
+                        });
+                    }
+                    
+                    if (!io.instance) {
+                        throw new ConfigurationError(`IO interface ${io.type} at index ${index} has no instance`, { 
+                            io 
+                        });
+                    }
+                    
+                    if (!io.config) {
+                        throw new ConfigurationError(`IO interface ${io.type} at index ${index} has no configuration`, { 
+                            io 
+                        });
+                    }
+                });
+            }
+            
+            // Tool schemas validation
+            const toolSchemas = Object.values(config.toolsSchemas);
+            toolSchemas.forEach(schema => {
+                if (!schema.name) {
+                    throw new ConfigurationError("Tool schema must have a name", { 
+                        schema 
+                    });
+                }
+            });
+            
+            // Event handlers validation
+            Object.entries(config.on).forEach(([eventName, handler]) => {
+                if (typeof handler !== 'function') {
+                    throw new ConfigurationError(`Event handler for '${eventName}' must be a function`, { 
+                        eventName, 
+                        handlerType: typeof handler 
+                    });
+                }
+            });
+            
+            // Runner validation
+            validateType(config.runner.maxRuns, 'number', 'runner.maxRuns', 'agent_config');
+            if (config.runner.maxRuns <= 0) {
+                throw new ConfigurationError("runner.maxRuns must be greater than 0", { 
+                    maxRuns: config.runner.maxRuns 
+                });
+            }
+            
+            logger.debug(`Agent ${config.metadata.name} configuration validated successfully`);
+            
+        } catch (error) {
+            if (error instanceof ConfigurationError) {
+                logger.error(`Agent configuration validation failed: ${error.message}`, {
+                    configContext: error.configContext,
+                    agentName: config.metadata?.name || 'unknown'
+                });
+                throw error;
+            }
+            
+            // Wrap other errors
+            logger.error(`Agent configuration validation failed with unexpected error`, {
+                error,
+                agentName: config.metadata?.name || 'unknown'
+            });
+            
+            throw new ConfigurationError(
+                `Agent configuration validation failed: ${error.message}`,
+                { cause: error }
+            );
+        }
+    }
+    
+    /**
+     * Adds an IO interface to the agent
+     * @param {Object} instance - IO provider instance
+     * @param {Object} ioConfig - IO configuration
+     * @returns {Object} Agent builder for chaining
+     */
+    function addIO(instance, ioConfig) {
+        if (!instance || !instance.type) {
+            throw new ConfigurationError("IO instance must have a type", {
+                instance: instance ? Object.keys(instance) : null
+            });
+        }
+        
+        config.io.push({
+            type: instance.type,
+            instance: instance,
+            config: ioConfig || {}
+        });
+        
+        return this;
+    }
+    
+    /**
+     * Configures the LLM for the agent
+     * @param {Object} llmApi - LLM API provider
+     * @param {Object} llmConfig - LLM configuration
+     * @returns {Object} Agent builder for chaining
+     */
+    function withLLM(llmApi, llmConfig) {
+        if (!llmApi) {
+            throw new ConfigurationError("LLM API is required", {
+                provided: llmApi
+            });
+        }
+        
+        config.llm = {
+            api: llmApi,
+            config: llmConfig || {}
+        };
+        
+        return this;
+    }
+    
+    /**
+     * Configures the store for the agent
+     * @param {Object} storeInstance - Store instance
+     * @param {Object} storeConfig - Store configuration
+     * @returns {Object} Agent builder for chaining
+     */
+    function withStore(storeInstance, storeConfig) {
+        if (!storeInstance) {
+            throw new ConfigurationError("Store instance is required", {
+                provided: storeInstance
+            });
+        }
+        
+        config.store = {
+            instance: storeInstance,
+            config: storeConfig || {}
+        };
+        
+        return this;
+    }
+    
+    /**
+     * Registers an event handler
+     * @param {String} eventName - Event name
+     * @param {Function} handler - Event handler function
+     * @returns {Object} Agent builder for chaining
+     */
+    function on(eventName, handler) {
+        if (typeof handler !== 'function') {
+            throw new ConfigurationError(`Event handler for ${eventName} must be a function`, {
+                provided: typeof handler
+            });
+        }
+        
+        config.on[eventName] = handler;
+        return this;
+    }
+    
+    /**
+     * Adds a discovery schema
+     * @param {Object} schema - Discovery schema
+     * @returns {Object} Agent builder for chaining
+     */
+    function addDiscoverySchema(schema) {
+        if (!schema) {
+            throw new ConfigurationError("Discovery schema is required", {
+                provided: schema
+            });
+        }
+        
+        config.discoverySchemas.push(schema);
+        return this;
+    }
+
+    /**
+     * Adds a tool schema
+     * @param {Object} schema - Tool schema
+     * @returns {Object} Agent builder for chaining
+     */
+    function addToolSchema(schema) {
+        if (!schema || !schema.name) {
+            throw new ConfigurationError("Tool schema must have a name", {
+                schema: schema
+            });
+        }
+        
+        config.toolsSchemas[schema.name] = schema;
+        return this;
+    }
+
+    /**
+     * Sets agent metadata
+     * @param {Object} metadata - Agent metadata
+     * @returns {Object} Agent builder for chaining
+     */
+    function setMetadata(metadata) {
+        if (!metadata) {
+            throw new ConfigurationError("Metadata is required", {
+                provided: metadata
+            });
+        }
+        
+        config.metadata = {
+            ...config.metadata,
+            ...metadata
+        };
+        
+        return this;
+    }
+
+    /**
+     * Gets all registered tool schemas
+     * @returns {Object} Map of tool schemas
+     */
+    function getToolsSchemas() {
+        return { ...config.toolsSchemas };
+    }
+    
+    /**
+     * Compiles the agent configuration into a runnable agent
+     * @returns {Promise<Object>} Compiled agent interface
+     */
+    async function compile() {
+        // Validate configuration before compiling
+        validateConfiguration();
+        
+        try {
+            logger.info(`Compiling agent ${config.metadata.name}`);
+            const runtime = await AgentRuntime(config);
+
+            return {
+                query: runtime
+            };
+        } catch (error) {
+            logger.error(`Agent compilation error: ${error.message}`, {
+                agentName: config.metadata.name,
+                error
+            });
+            
+            throw new CompilationError(
+                `Failed to compile agent ${config.metadata.name}: ${error.message}`,
+                config.metadata.name,
+                error
+            );
+        }
+    }
+
+    // Return the agent builder interface
+    return {
+        addIO,
+        withLLM,
+        withStore,
+        on,
+        addDiscoverySchema,
+        addToolSchema,
+        compile,
+        setMetadata,
+        getToolsSchemas,
+        
+        // Expose config for backward compatibility
+        _config: config
+    };
+}