@mseep/ai-tech-app-agent 1.0.0

package/src/config/llm.config.ts

@@ -0,0 +1,220 @@
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+export interface LLMConfig {
+  provider: 'ollama' | 'openai' | 'anthropic' | 'custom';
+  
+  // Connection settings
+  connection: {
+    baseUrl: string;
+    timeout: number;
+    retryAttempts: number;
+    retryDelay: number;
+  };
+
+  // Model settings
+  model: {
+    name: string;
+    temperature: number;
+    maxTokens: number;
+    topP: number;
+    topK: number;
+    frequencyPenalty: number;
+    presencePenalty: number;
+  };
+
+  // Prompt configuration
+  prompt: {
+    systemMessage: string;
+    includeAppContext: boolean;
+    includeUIContext: boolean;
+    maxUIElements: number;
+    maxContextTokens: number;
+    includeReasoningInResponse: boolean;
+    strictJsonMode: boolean;
+  };
+
+  // Performance
+  performance: {
+    cachingEnabled: boolean;
+    cacheTTL: number;
+    batchRequests: boolean;
+    maxBatchSize: number;
+    streamResponse: boolean;
+  };
+
+  // Fallback
+  fallback: {
+    enabled: boolean;
+    fallbackModel?: string;
+    maxFallbackAttempts: number;
+  };
+}
+
+const llmConfig: LLMConfig = {
+  provider: (process.env.LLM_PROVIDER as 'ollama' | 'openai' | 'anthropic' | 'custom') || 'ollama',
+
+  connection: {
+    baseUrl: process.env.OLLAMA_BASE_URL || process.env.LLM_BASE_URL || 'http://localhost:11434',
+    timeout: parseInt(process.env.LLM_TIMEOUT || '60000'),
+    retryAttempts: parseInt(process.env.LLM_RETRY_ATTEMPTS || '3'),
+    retryDelay: parseInt(process.env.LLM_RETRY_DELAY || '2000'),
+  },
+
+  model: {
+    name: process.env.LLM_MODEL || 'llama3.2:3b',
+    temperature: parseFloat(process.env.LLM_TEMPERATURE || '0.1'),
+    maxTokens: parseInt(process.env.LLM_MAX_TOKENS || '2000'),
+    topP: parseFloat(process.env.LLM_TOP_P || '0.9'),
+    topK: parseInt(process.env.LLM_TOP_K || '40'),
+    frequencyPenalty: parseFloat(process.env.LLM_FREQUENCY_PENALTY || '0.0'),
+    presencePenalty: parseFloat(process.env.LLM_PRESENCE_PENALTY || '0.0'),
+  },
+
+  prompt: {
+    systemMessage: process.env.LLM_SYSTEM_MESSAGE || 
+      'You are an expert mobile test automation agent specialized in Appium automation.',
+    includeAppContext: process.env.LLM_INCLUDE_APP_CONTEXT !== 'false',
+    includeUIContext: process.env.LLM_INCLUDE_UI_CONTEXT !== 'false',
+    maxUIElements: parseInt(process.env.LLM_MAX_UI_ELEMENTS || '30'),
+    maxContextTokens: parseInt(process.env.LLM_MAX_CONTEXT_TOKENS || '4000'),
+    includeReasoningInResponse: process.env.LLM_INCLUDE_REASONING !== 'false',
+    strictJsonMode: process.env.LLM_STRICT_JSON_MODE !== 'false',
+  },
+
+  performance: {
+    cachingEnabled: process.env.LLM_CACHING_ENABLED === 'true',
+    cacheTTL: parseInt(process.env.LLM_CACHE_TTL || '3600'),
+    batchRequests: process.env.LLM_BATCH_REQUESTS === 'true',
+    maxBatchSize: parseInt(process.env.LLM_MAX_BATCH_SIZE || '5'),
+    streamResponse: process.env.LLM_STREAM_RESPONSE === 'true',
+  },
+
+  fallback: {
+    enabled: process.env.LLM_FALLBACK_ENABLED === 'true',
+    fallbackModel: process.env.LLM_FALLBACK_MODEL,
+    maxFallbackAttempts: parseInt(process.env.LLM_FALLBACK_ATTEMPTS || '1'),
+  },
+};
+
+// Predefined prompt templates
+export const PromptTemplates = {
+  actionPlanning: `You are an expert mobile test automation agent. Your task is to generate precise Appium actions to accomplish a test step.
+
+**Your Capabilities:**
+- Analyze mobile app UI hierarchies (XML format)
+- Identify the best element selectors (text, id, accessibility-id, xpath, class)
+- Generate reliable action sequences (tap, type, scroll, swipe, wait, assert)
+- Handle both Android and iOS platforms
+- Adapt to different screen sizes and device configurations
+
+**Priority for Element Selection:**
+1. Text content (exact or partial match)
+2. Accessibility ID or Content Description
+3. Resource ID (Android) or Name (iOS)
+4. Class name with additional attributes
+5. XPath (only when necessary)
+6. Coordinates (last resort)
+
+**Action Types Available:**
+- tap: Click/tap on an element
+- type: Enter text into an input field
+- scroll: Scroll in a direction (up, down, left, right)
+- swipe: Swipe gesture in a direction
+- wait: Wait for a duration or element
+- assert: Verify element state (exists, visible, text, enabled)
+- screenshot: Capture screen state`,
+
+  contextAnalysis: `Analyze the current UI context and identify key interactive elements that are relevant for accomplishing the given test step.
+
+**Focus on:**
+- Interactive elements (buttons, inputs, links)
+- Navigation elements (tabs, back buttons)
+- Text labels and headers for context
+- Error messages or alerts
+- Permission dialogs
+- Loading indicators`,
+
+  errorRecovery: `The previous action attempt failed. Analyze the current UI state and suggest alternative approaches.
+
+**Consider:**
+- Is the target element visible and enabled?
+- Are there any blocking dialogs or overlays?
+- Is the app in an unexpected state?
+- Are there alternative selectors for the same element?
+- Should we wait for animations or transitions to complete?`,
+
+  assertionGeneration: `Generate appropriate assertions to verify the expected outcome of the test step.
+
+**Common Assertions:**
+- Element exists on screen
+- Element is visible and enabled
+- Text content matches expected value
+- Specific screen or activity is displayed
+- No error messages are present`,
+};
+
+// Helper function to get appropriate template
+export function getPromptTemplate(type: keyof typeof PromptTemplates): string {
+  return PromptTemplates[type];
+}
+
+// Validation
+export function validateLLMConfig(): void {
+  const errors: string[] = [];
+
+  // Check base URL
+  if (!llmConfig.connection.baseUrl) {
+    errors.push('LLM_BASE_URL or OLLAMA_BASE_URL is required');
+  }
+
+  // Validate model name
+  if (!llmConfig.model.name) {
+    errors.push('LLM_MODEL is required');
+  }
+
+  // Validate temperature range
+  if (llmConfig.model.temperature < 0 || llmConfig.model.temperature > 2) {
+    errors.push('LLM_TEMPERATURE must be between 0 and 2');
+  }
+
+  // Validate max tokens
+  if (llmConfig.model.maxTokens < 100 || llmConfig.model.maxTokens > 100000) {
+    errors.push('LLM_MAX_TOKENS must be between 100 and 100000');
+  }
+
+  // Validate timeout
+  if (llmConfig.connection.timeout < 5000) {
+    errors.push('LLM_TIMEOUT must be at least 5000ms');
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`LLM configuration validation failed:\n${errors.join('\n')}`);
+  }
+}
+
+// Get configuration for specific provider
+export function getProviderConfig(provider: string) {
+  const configs = {
+    ollama: {
+      endpoint: '/api/generate',
+      healthEndpoint: '/api/tags',
+      format: 'ollama',
+    },
+    openai: {
+      endpoint: '/v1/chat/completions',
+      healthEndpoint: '/v1/models',
+      format: 'openai',
+    },
+    anthropic: {
+      endpoint: '/v1/messages',
+      healthEndpoint: '/v1/models',
+      format: 'anthropic',
+    },
+  };
+
+  return configs[provider as keyof typeof configs] || configs.ollama;
+}
+
+export default llmConfig;

package/src/config/mcp.config.ts

@@ -0,0 +1,291 @@
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+export interface MCPConfig {
+  server: {
+    type: 'mcp-appium' | 'mobile-mcp' | 'custom';
+    host: string;
+    port: number;
+    protocol: 'http' | 'https' | 'stdio';
+    timeout: number;
+  };
+
+  appium: {
+    serverUrl: string;
+    sessionId?: string;
+    capabilities: {
+      platformName?: string;
+      platformVersion?: string;
+      deviceName?: string;
+      automationName?: string;
+      app?: string;
+      appPackage?: string;
+      appActivity?: string;
+      bundleId?: string;
+    };
+  };
+
+  tools: {
+    enabledTools: string[];
+    customTools?: Record<string, any>;
+  };
+
+  uiContext: {
+    capturePageSource: boolean;
+    parseXML: boolean;
+    includeInvisibleElements: boolean;
+    maxElementDepth: number;
+    elementFilters: {
+      excludeClasses: string[];
+      includeOnlyInteractive: boolean;
+      minTextLength: number;
+    };
+  };
+
+  actions: {
+    tapStrategy: 'center' | 'visible-center' | 'coordinates';
+    typeStrategy: 'native' | 'adb' | 'auto';
+    scrollStrategy: 'uiautomator' | 'gesture' | 'auto';
+    swipeStrategy: 'touch-action' | 'gesture' | 'auto';
+    waitStrategy: 'implicit' | 'explicit' | 'smart';
+  };
+
+  errorHandling: {
+    retryOnStaleElement: boolean;
+    retryOnNoSuchElement: boolean;
+    retryAttempts: number;
+    retryDelay: number;
+    captureScreenshotOnError: boolean;
+    capturePageSourceOnError: boolean;
+  };
+
+  performance: {
+    cacheUIContext: boolean;
+    cacheDuration: number;
+    parallelActions: boolean;
+    throttleActions: number;
+  };
+}
+
+const mcpConfig: MCPConfig = {
+  server: {
+    type: (process.env.MCP_SERVER_TYPE as 'mcp-appium' | 'mobile-mcp' | 'custom') || 'mcp-appium',
+    host: process.env.MCP_SERVER_HOST || 'localhost',
+    port: parseInt(process.env.MCP_SERVER_PORT || '3000'),
+    protocol: (process.env.MCP_PROTOCOL as 'http' | 'https' | 'stdio') || 'http',
+    timeout: parseInt(process.env.MCP_TIMEOUT || '30000'),
+  },
+
+  appium: {
+    serverUrl: process.env.APPIUM_SERVER_URL || 'http://localhost:4723',
+    sessionId: process.env.APPIUM_SESSION_ID,
+    capabilities: {
+      platformName: process.env.PLATFORM_NAME,
+      platformVersion: process.env.PLATFORM_VERSION,
+      deviceName: process.env.DEVICE_NAME,
+      automationName: process.env.AUTOMATION_NAME,
+      app: process.env.APP_PATH,
+      appPackage: process.env.APP_PACKAGE,
+      appActivity: process.env.APP_ACTIVITY,
+      bundleId: process.env.BUNDLE_ID,
+    },
+  },
+
+  tools: {
+    enabledTools: (process.env.MCP_ENABLED_TOOLS || 
+      'find_element,tap,type,scroll,swipe,get_page_source,take_screenshot').split(','),
+    customTools: {},
+  },
+
+  uiContext: {
+    capturePageSource: process.env.MCP_CAPTURE_PAGE_SOURCE !== 'false',
+    parseXML: process.env.MCP_PARSE_XML !== 'false',
+    includeInvisibleElements: process.env.MCP_INCLUDE_INVISIBLE === 'true',
+    maxElementDepth: parseInt(process.env.MCP_MAX_ELEMENT_DEPTH || '10'),
+    elementFilters: {
+      excludeClasses: (process.env.MCP_EXCLUDE_CLASSES || 
+        'android.view.ViewGroup,android.widget.LinearLayout,UIView').split(','),
+      includeOnlyInteractive: process.env.MCP_ONLY_INTERACTIVE === 'true',
+      minTextLength: parseInt(process.env.MCP_MIN_TEXT_LENGTH || '1'),
+    },
+  },
+
+  actions: {
+    tapStrategy: (process.env.MCP_TAP_STRATEGY as 'center' | 'visible-center' | 'coordinates') || 'center',
+    typeStrategy: (process.env.MCP_TYPE_STRATEGY as 'native' | 'adb' | 'auto') || 'native',
+    scrollStrategy: (process.env.MCP_SCROLL_STRATEGY as 'uiautomator' | 'gesture' | 'auto') || 'auto',
+    swipeStrategy: (process.env.MCP_SWIPE_STRATEGY as 'touch-action' | 'gesture' | 'auto') || 'auto',
+    waitStrategy: (process.env.MCP_WAIT_STRATEGY as 'implicit' | 'explicit' | 'smart') || 'smart',
+  },
+
+  errorHandling: {
+    retryOnStaleElement: process.env.MCP_RETRY_STALE !== 'false',
+    retryOnNoSuchElement: process.env.MCP_RETRY_NO_ELEMENT === 'true',
+    retryAttempts: parseInt(process.env.MCP_ERROR_RETRY_ATTEMPTS || '2'),
+    retryDelay: parseInt(process.env.MCP_ERROR_RETRY_DELAY || '1000'),
+    captureScreenshotOnError: process.env.MCP_SCREENSHOT_ON_ERROR !== 'false',
+    capturePageSourceOnError: process.env.MCP_PAGE_SOURCE_ON_ERROR === 'true',
+  },
+
+  performance: {
+    cacheUIContext: process.env.MCP_CACHE_UI_CONTEXT === 'true',
+    cacheDuration: parseInt(process.env.MCP_CACHE_DURATION || '5000'),
+    parallelActions: process.env.MCP_PARALLEL_ACTIONS === 'true',
+    throttleActions: parseInt(process.env.MCP_THROTTLE_ACTIONS || '0'),
+  },
+};
+
+// MCP Tool definitions
+export const MCPTools = {
+  find_element: {
+    name: 'find_element',
+    description: 'Find an element on the screen using various selector strategies',
+    parameters: {
+      strategy: ['id', 'xpath', 'accessibility-id', 'text', 'class'],
+      value: 'string',
+      multiple: 'boolean',
+    },
+  },
+  tap: {
+    name: 'tap',
+    description: 'Tap/click on an element',
+    parameters: {
+      selector: 'object',
+      x: 'number (optional)',
+      y: 'number (optional)',
+      duration: 'number (optional)',
+    },
+  },
+  type: {
+    name: 'type',
+    description: 'Type text into an element',
+    parameters: {
+      selector: 'object',
+      text: 'string',
+      clear: 'boolean (optional)',
+    },
+  },
+  scroll: {
+    name: 'scroll',
+    description: 'Scroll the screen',
+    parameters: {
+      direction: ['up', 'down', 'left', 'right'],
+      percentage: 'number (optional)',
+      element: 'object (optional)',
+    },
+  },
+  swipe: {
+    name: 'swipe',
+    description: 'Perform swipe gesture',
+    parameters: {
+      direction: ['up', 'down', 'left', 'right'],
+      startX: 'number (optional)',
+      startY: 'number (optional)',
+      endX: 'number (optional)',
+      endY: 'number (optional)',
+      duration: 'number (optional)',
+    },
+  },
+  get_page_source: {
+    name: 'get_page_source',
+    description: 'Get the current page source (XML hierarchy)',
+    parameters: {},
+  },
+  take_screenshot: {
+    name: 'take_screenshot',
+    description: 'Capture a screenshot',
+    parameters: {
+      path: 'string (optional)',
+    },
+  },
+  wait: {
+    name: 'wait',
+    description: 'Wait for element or duration',
+    parameters: {
+      selector: 'object (optional)',
+      condition: ['exists', 'visible', 'enabled', 'clickable'],
+      timeout: 'number (optional)',
+      duration: 'number (optional)',
+    },
+  },
+  get_current_activity: {
+    name: 'get_current_activity',
+    description: 'Get current activity (Android) or bundle ID (iOS)',
+    parameters: {},
+  },
+  press_key: {
+    name: 'press_key',
+    description: 'Press device key',
+    parameters: {
+      key: ['home', 'back', 'enter', 'menu', 'volume_up', 'volume_down'],
+    },
+  },
+};
+
+// Selector strategies priority
+export const SelectorPriority = [
+  'accessibility-id',
+  'id',
+  'text',
+  'class',
+  'xpath',
+  'coordinates',
+];
+
+// Platform-specific configurations
+export const PlatformConfig = {
+  android: {
+    automationName: 'UiAutomator2',
+    defaultTimeout: 30000,
+    keyboardStrategy: 'adb',
+    preferredSelectors: ['resource-id', 'content-desc', 'text'],
+  },
+  ios: {
+    automationName: 'XCUITest',
+    defaultTimeout: 30000,
+    keyboardStrategy: 'native',
+    preferredSelectors: ['accessibility-id', 'name', 'label'],
+  },
+};
+
+// Validation
+export function validateMCPConfig(): void {
+  const errors: string[] = [];
+
+  // Check Appium server URL
+  if (!mcpConfig.appium.serverUrl) {
+    errors.push('APPIUM_SERVER_URL is required');
+  }
+
+  // Validate server port
+  if (mcpConfig.server.port < 1 || mcpConfig.server.port > 65535) {
+    errors.push('MCP_SERVER_PORT must be between 1 and 65535');
+  }
+
+  // Validate timeout
+  if (mcpConfig.server.timeout < 1000) {
+    errors.push('MCP_TIMEOUT must be at least 1000ms');
+  }
+
+  // Validate element depth
+  if (mcpConfig.uiContext.maxElementDepth < 1 || mcpConfig.uiContext.maxElementDepth > 20) {
+    errors.push('MCP_MAX_ELEMENT_DEPTH must be between 1 and 20');
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`MCP configuration validation failed:\n${errors.join('\n')}`);
+  }
+}
+
+// Helper to get platform-specific config
+export function getPlatformConfig(platform: 'android' | 'ios') {
+  return PlatformConfig[platform];
+}
+
+// Helper to check if tool is enabled
+export function isToolEnabled(toolName: string): boolean {
+  return mcpConfig.tools.enabledTools.includes(toolName);
+}
+
+export default mcpConfig;

package/src/index.ts

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import path from 'path';
+import fs from 'fs';
+import dotenv from 'dotenv';
+import logger from './utils/logger';
+import AITestRunner from './orchestrator/aiTestRunner';
+
+dotenv.config();
+
+const program = new Command();
+
+program
+  .name('ai-test-runner')
+  .description('AI-powered mobile test automation using MCP and LLM')
+  .version('1.0.0');
+
+program
+  .command('run')
+  .description('Run AI-powered test specs')
+  .argument('<spec-path>', 'Path to test spec file or directory')
+  .option('-s, --session-id <id>', 'Existing Appium session ID')
+  .option('-k, --knowledge <path>', 'Path to app knowledge file')
+  .option('-o, --output <path>', 'Output path for test report', './reports/test-report.json')
+  .action(async (specPath: string, options: any) => {
+    try {
+      logger.info('Starting AI Test Runner...');
+      logger.info(`Spec path: ${specPath}`);
+
+      const runner = new AITestRunner();
+
+      // Load app knowledge if provided
+      if (options.knowledge) {
+        await runner.loadAppKnowledge(options.knowledge);
+      }
+
+      const results = [];
+
+      // Check if spec path is a file or directory
+      const stats = fs.statSync(specPath);
+      
+      if (stats.isDirectory()) {
+        // Run all specs in directory
+        const files = fs.readdirSync(specPath)
+          .filter(f => f.endsWith('.yaml') || f.endsWith('.yml') || f.endsWith('.json'))
+          .map(f => path.join(specPath, f));
+
+        logger.info(`Found ${files.length} test spec(s) in directory`);
+
+        for (const file of files) {
+          const result = await runner.runTestSpec(file, options.sessionId);
+          results.push(result);
+        }
+      } else {
+        // Run single spec
+        const result = await runner.runTestSpec(specPath, options.sessionId);
+        results.push(result);
+      }
+
+      // Generate report
+      await runner.generateReport(results, options.output);
+
+      // Print summary
+      console.log('\n' + '='.repeat(60));
+      console.log('TEST EXECUTION SUMMARY');
+      console.log('='.repeat(60));
+      
+      const passed = results.filter(r => r.status === 'passed').length;
+      const failed = results.filter(r => r.status === 'failed').length;
+      const total = results.length;
+
+      console.log(`Total Tests: ${total}`);
+      console.log(`Passed: ${passed}`);
+      console.log(`Failed: ${failed}`);
+      console.log(`Success Rate: ${((passed / total) * 100).toFixed(2)}%`);
+      console.log('='.repeat(60) + '\n');
+
+      // Exit with appropriate code
+      process.exit(failed > 0 ? 1 : 0);
+
+    } catch (error: any) {
+      logger.error(`Test execution failed: ${error.message}`);
+      console.error(`Error: ${error.message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('validate')
+  .description('Validate test spec file(s)')
+  .argument('<spec-path>', 'Path to test spec file or directory')
+  .action((specPath: string) => {
+    try {
+      const stats = fs.statSync(specPath);
+      const files = stats.isDirectory()
+        ? fs.readdirSync(specPath)
+            .filter(f => f.endsWith('.yaml') || f.endsWith('.yml') || f.endsWith('.json'))
+            .map(f => path.join(specPath, f))
+        : [specPath];
+
+      let valid = 0;
+      let invalid = 0;
+
+      files.forEach(file => {
+        try {
+          const content = fs.readFileSync(file, 'utf-8');
+          const ext = path.extname(file).toLowerCase();
+
+          if (ext === '.json') {
+            JSON.parse(content);
+          } else {
+            // For YAML, we'd need to validate structure
+            // This is a basic check
+          }
+
+          console.log(`✓ ${file} - Valid`);
+          valid++;
+        } catch (error: any) {
+          console.error(`✗ ${file} - Invalid: ${error.message}`);
+          invalid++;
+        }
+      });
+
+      console.log(`\nValidation complete: ${valid} valid, ${invalid} invalid`);
+      process.exit(invalid > 0 ? 1 : 0);
+
+    } catch (error: any) {
+      console.error(`Validation failed: ${error.message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('health')
+  .description('Check health of LLM and MCP components')
+  .action(async () => {
+    try {
+      const runner = new AITestRunner();
+      
+      console.log('Checking LLM health...');
+      const llamaClient = new (await import('./llm/llamaClient')).default();
+      const llmHealthy = await llamaClient.healthCheck();
+      
+      if (llmHealthy) {
+        console.log('✓ LLM is healthy');
+      } else {
+        console.error('✗ LLM is not available');
+      }
+
+      // Add MCP health check here if needed
+
+      process.exit(llmHealthy ? 0 : 1);
+
+    } catch (error: any) {
+      console.error(`Health check failed: ${error.message}`);
+      process.exit(1);
+    }
+  });
+
+program.parse(process.argv);