agentnet 0.0.2 → 0.0.3

package/README.md

@@ -4,6 +4,7 @@
 
 - [Introduction](#introduction)
 - [Installation](#installation)
+- [API Keys Configuration](#api-keys-configuration)
 - [Super Simple Example (Quick Start)](#super-simple-example-quick-start)
 - [Declarative Agent Definitions (YAML & JavaScript)](#declarative-agent-definitions-yaml--javascript)
 - [State Management](#state-management)
@@ -41,6 +42,32 @@ Key aspects include:
 npm install agentnet
 ```
 
+## API Keys Configuration
+
+Agentnet requires API keys for accessing the LLM providers you plan to use. The keys should be set as environment variables:
+
+- **Gemini**: Set `GEMINI_API_KEY` for using Google's Gemini models
+- **OpenAI**: Set `OPENAI_API_KEY` for using OpenAI's GPT models
+
+You can set these environment variables in your deployment environment or use a `.env` file with a package like `dotenv`:
+
+```javascript
+// In your main file, before importing agentnet
+import dotenv from 'dotenv';
+dotenv.config();
+
+// Now the API keys are available to agentnet
+import { Agent, Gemini } from "agentnet";
+```
+
+Example `.env` file:
+```
+GEMINI_API_KEY=your_gemini_api_key_here
+OPENAI_API_KEY=your_openai_api_key_here
+```
+
+> Note: If you try to use an LLM provider without setting the corresponding API key, Agentnet will throw an error indicating which environment variable is missing.
+
 ## Super Simple Example (Quick Start)
 
 Here's how you can quickly get an agent up and running:
@@ -88,7 +115,7 @@ Define agent metadata, LLM configurations, transport, tools, and discovery schem
 
 ```yaml
 ---
-apiVersion: agentnet.io/v1alpha1
+apiVersion: agentnet/v1alpha1
 kind: AgentDefinition
 metadata:
   name: bookingAgent
@@ -131,6 +158,47 @@ spec:
       # parameters schema for the discovery...
 ```
 
+### API Versioning
+
+Agentnet supports API versioning to maintain backwards compatibility while evolving the platform:
+
+```yaml
+apiVersion: agentnet/v1alpha1  # Specify which API version this definition uses
+```
+
+Currently supported API versions:
+
+- `agentnet/v1alpha1`: Current API version
+
+When creating agent definitions, you should specify which API version you're targeting. This allows Agentnet to:
+
+1. Apply the correct validation rules
+2. Handle differences in configuration format
+3. Maintain backward compatibility with older definitions
+4. Enable new features only available in newer versions
+
+If you don't specify an `apiVersion`, Agentnet will default to `agentnet/v1alpha1` but will log a warning.
+
+#### Version Migration Tool
+
+Agentnet includes a command-line tool to help migrate your agent definitions to newer API versions:
+
+```bash
+# Migrate a YAML file to the latest version
+node src/tools/migrate-version.js ./agents.yaml
+
+# Specify a target version
+node src/tools/migrate-version.js ./agents.yaml --version agentnet.io/v1alpha1
+
+# Write to a specific output file
+node src/tools/migrate-version.js ./agents.yaml --output ./agents-new.yaml
+
+# Just check if migration is needed without modifying
+node src/tools/migrate-version.js ./agents.yaml --check
+```
+
+This tool helps you keep your agent definitions up-to-date with the latest features while maintaining compatibility with the Agentnet platform.
+
 ### Dynamic Implementation (JavaScript)
 
 Load YAML definitions and bind tool implementations dynamically:

package/examples/simple/simple.js

@@ -1,7 +1,7 @@
-import { AgentLoaderJSON, Message, Bindings, PostgresStore } from "../index.js"
+import { AgentLoaderJSON, Message, Bindings, PostgresStore } from "../../src/index.js"
 
 const agentDefinition = {
-    "apiVersion": "smartagent.io/v1alpha1",
+    "apiVersion": "agentnet/v1alpha1",
     "kind": "AgentDefinition",
     "metadata": {
       "name": "accomodationAgent",

package/jest.config.js

@@ -0,0 +1 @@
+export default { transform: {} }

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "agentnet",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "type": "module",
   "description": "Agent library used by Smartness",
   "main": "index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node --experimental-vm-modules ./node_modules/.bin/jest --rootDir=src/tests"
   },
   "author": "",
   "license": "ISC",
@@ -19,5 +19,8 @@
     "redis": "^5.0.1",
     "uuid": "^11.1.0",
     "yaml": "^2.7.1"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
   }
 }

package/src/agent/agent-loader.js

@@ -2,6 +2,18 @@ import fs from 'fs'
 import { parse } from 'yaml'
 import { Gemini } from "../index.js"
 import { Agent } from "./agent.js"
+import { logger } from "../utils/logger.js"
+import { ConfigurationError } from "../errors/index.js"
+import { validateApiVersion, DEFAULT_API_VERSION, API_VERSIONS } from '../utils/version.js'
+
+/**
+ * Version handlers for different API versions
+ */
+const VERSION_HANDLERS = {
+    'smartagent.io/v1alpha1': processV1Alpha1Definition,
+    'agentnet.io/v1alpha1': processV1Alpha1Definition
+    // Additional version handlers can be added here as the API evolves
+};
 
 /**
  * Loads agent definitions from a YAML file
@@ -47,10 +59,10 @@ function parseAgentDefinitionsFromYaml(yamlContent) {
             if (isValidAgentDefinition(definition)) {
                 agentDefinitions.push(definition);
             } else {
-                console.warn("Skipping invalid or non-AgentDefinition document in YAML.");
+                logger.warn("Skipping invalid or non-AgentDefinition document in YAML.");
             }
         } catch (error) {
-            console.warn(`Failed to parse YAML document: ${error.message}`);
+            logger.warn(`Failed to parse YAML document: ${error.message}`);
         }
     }
     
@@ -66,6 +78,58 @@ function isValidAgentDefinition(definition) {
     return definition && definition.kind === 'AgentDefinition' && definition.spec;
 }
 
+/**
+ * Gets the appropriate version handler for a definition
+ * @param {object} definition - Agent definition
+ * @returns {Function} Version handler function
+ * @throws {ConfigurationError} If version is unsupported
+ */
+function getVersionHandler(definition) {
+    // Validate the API version using our utility
+    const versionData = validateApiVersion(definition);
+    const apiVersion = versionData.version;
+    
+    // Get the appropriate handler for this version
+    const handler = VERSION_HANDLERS[apiVersion];
+    
+    if (!handler) {
+        throw new ConfigurationError(
+            `No implementation handler for apiVersion '${apiVersion}'`,
+            { apiVersion, supportedHandlers: Object.keys(VERSION_HANDLERS) }
+        );
+    }
+    
+    return handler;
+}
+
+/**
+ * Process a v1alpha1 agent definition
+ * @param {object} definition - Agent definition
+ * @param {object} agentBuilder - Agent builder
+ * @param {object} bindings - IO and store bindings
+ * @returns {object} Processed agent interface and tool map
+ */
+async function processV1Alpha1Definition(definition, agentBuilder, bindings) {
+    const spec = definition.spec;
+    
+    // Add apiVersion to agent metadata
+    agentBuilder.setMetadata({
+        ...agentBuilder._config.metadata,
+        apiVersion: definition.apiVersion || DEFAULT_API_VERSION
+    });
+    
+    // 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);
+    
+    return { agentBuilder, toolMap };
+}
+
 /**
  * Loads an LLM provider instance
  * @param {string} providerName - Name of the provider
@@ -237,7 +301,6 @@ async function AgentLoader(agentsDefinitions, config = {}) {
                 throw new Error(`Invalid agent definition: missing spec`);
             }
             
-            const spec = definition.spec;
             const metadata = definition.metadata || { 
                 name: "default", 
                 description: "Agent from definition" 
@@ -250,21 +313,21 @@ async function AgentLoader(agentsDefinitions, config = {}) {
             // 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);
+            // Get the appropriate version handler
+            const versionHandler = getVersionHandler(definition);
             
-            // Set up tools
-            const toolMap = configureTools(agentBuilder, spec.tools);
+            // Process according to API version
+            const { agentBuilder: updatedBuilder, toolMap } = 
+                await versionHandler(definition, agentBuilder, bindings);
             
             // Create the agent interface
-            loadedAgents[metadata.name] = createAgentInterface(agentBuilder, toolMap);
+            loadedAgents[metadata.name] = createAgentInterface(updatedBuilder, toolMap);
+            
+            logger.info(`Agent '${metadata.name}' loaded successfully with apiVersion: ${definition.apiVersion || DEFAULT_API_VERSION}`);
             
         } catch (error) {
             const agentName = definition.metadata?.name || 'Unnamed Agent';
-            console.error(`Failed to load agent "${agentName}": ${error.message}`);
+            logger.error(`Failed to load agent "${agentName}": ${error.message}`, { error });
             // Optional: decide whether to throw or just log and continue
             // throw error;
         }

package/src/agent/agent.js

@@ -23,7 +23,8 @@ const DEFAULT_CONFIG = {
     metadata: {
         name: "default",
         namespace: "default",
-        description: "A default agent"
+        description: "A default agent",
+        apiVersion: "agentnet/v1alpha1" // Default API version
     },
     runner: { 
         maxRuns: 10
@@ -41,7 +42,8 @@ const AGENT_CONFIG_SCHEMA = {
             properties: {
                 name: { type: 'string' },
                 namespace: { type: 'string' },
-                description: { type: 'string' }
+                description: { type: 'string' },
+                apiVersion: { type: 'string' }
             },
             required: ['name', 'namespace']
         },

package/src/agent/runtime.js

@@ -1,7 +1,7 @@
 import { build, makeToolsAndHandoffsMap } from "./executor.js"
-import { NatsIOAgentRuntime } from "./runtimes/nats.js"
 import { logger } from "../utils/logger.js"
 import { Response, SessionStore } from "../index.js"
+import { createAgentRuntime } from "../transport/index.js"
 
 export async function AgentRuntime(agentConfig) {
     const {
@@ -19,11 +19,14 @@ export async function AgentRuntime(agentConfig) {
     } = agentConfig
     
     // Initialize IO runtime
-    const natsInterfaces = ioInterfaces.filter(x => x.type === 'NatsIO')
-    const { handleTask, discoveredAgents } = await NatsIOAgentRuntime(
+    const transportType = ioInterfaces.length > 0 ? ioInterfaces[0].type.replace('IO', '').toLowerCase() : 'nats';
+    logger.info(`Creating agent runtime with transport type: ${transportType}`);
+    
+    const { handleTask, discoveredAgents } = await createAgentRuntime(
+        transportType,
         namespace,
         agentName, 
-        natsInterfaces, 
+        ioInterfaces, 
         discoverySchemas
     )
     

package/src/llm/base.js

@@ -0,0 +1,131 @@
+import { logger } from '../utils/logger.js'
+import { LLMError } from '../errors/index.js'
+
+/**
+ * Base class for LLM implementations
+ * Provides common functionality and defines required interface
+ */
+export class BaseLLM {
+  /**
+   * @param {string} providerType - The LLM provider type (e.g., 'gemini', 'openai')
+   */
+  constructor(providerType) {
+    this.type = providerType;
+  }
+
+  /**
+   * Initialize and get the LLM client
+   * @returns {Promise<any>} Initialized LLM client
+   * @throws {LLMError} If initialization fails
+   */
+  async getClient() {
+    throw new Error('getClient() must be implemented by subclasses');
+  }
+
+  /**
+   * Call the LLM model with the provided configuration and context
+   * @param {Object} config - LLM-specific configuration
+   * @param {Object} context - Context containing client, tools map and conversation
+   * @returns {Promise<Object>} The model response
+   * @throws {LLMError} If the API call fails
+   */
+  async callModel(config, context) {
+    throw new Error('callModel() must be implemented by subclasses');
+  }
+
+  /**
+   * Process the model response, handling text responses and function calls
+   * @param {Object} state - Current application state
+   * @param {Array} conversation - The conversation history
+   * @param {Object} toolsAndHandoffsMap - Map of available tools
+   * @param {Object} response - The model response to process
+   * @returns {Promise<string|null>} Text response or null if processing tool calls
+   */
+  async onResponse(state, conversation, toolsAndHandoffsMap, response) {
+    throw new Error('onResponse() must be implemented by subclasses');
+  }
+
+  /**
+   * Add a user prompt to the conversation
+   * @param {Array} conversation - The conversation history
+   * @param {string} formattedPrompt - The formatted user prompt
+   * @returns {Promise<void>}
+   */
+  async prompt(conversation, formattedPrompt) {
+    logger.debug('Adding user prompt to conversation', {
+      promptPreview: formattedPrompt.substring(0, 100)
+    });
+    
+    // Subclasses must implement appropriate conversation format
+  }
+
+  /**
+   * Check if required API key is set in environment variables
+   * @param {string} keyName - Environment variable name for the API key
+   * @returns {void}
+   * @throws {LLMError} If API key is not set
+   */
+  checkApiKey(keyName) {
+    if (!process.env[keyName]) {
+      throw new LLMError(
+        `${keyName} environment variable is not set`,
+        this.type
+      );
+    }
+  }
+
+  /**
+   * Execute a tool call from the model response
+   * @param {Object} toolCall - The tool call to execute
+   * @param {Object} state - Current application state
+   * @param {Array} conversation - The conversation history
+   * @param {Object} toolsAndHandoffsMap - Map of available tools
+   * @returns {Promise<any>} Result of the tool execution
+   */
+  async executeToolCall(toolCall, name, args, state, conversation, toolsAndHandoffsMap) {
+    logger.debug(`Executing tool from ${this.type}`, { 
+      toolName: name,
+      argsPreview: JSON.stringify(args).substring(0, 100)
+    });
+    
+    try {
+      if (!toolsAndHandoffsMap[name] || !toolsAndHandoffsMap[name].function) {
+        throw new Error(`Tool "${name}" not found or has no function implementation`);
+      }
+
+      let result = null;
+      if (toolsAndHandoffsMap[name].type === 'handoff') {
+        result = await toolsAndHandoffsMap[name].function(conversation, state, args);
+        // Process handoff results if needed
+        this.processHandoffResult(result, state);
+      } else {
+        result = await toolsAndHandoffsMap[name].function(state, args);
+      }
+      
+      logger.debug('Tool execution successful', { toolName: name });
+      return result;
+      
+    } catch (error) {
+      logger.error(`Error executing tool "${name}"`, { error });
+      throw error;
+    }
+  }
+  
+  /**
+   * Process the result of a handoff operation
+   * @param {string} result - The JSON string result from handoff
+   * @param {Object} state - The state to update
+   */
+  processHandoffResult(result, state) {
+    try {
+      const resultParsed = JSON.parse(result);
+      if (resultParsed.session) {
+        Object.entries(resultParsed.session).forEach(([key, value]) => {
+          state[key] = value;
+        });
+      }
+    } catch (error) {
+      logger.error('Failed to process handoff result', { error });
+    }
+  }
+}