Physics MCP Server

# Phase 6: ML/AI Augmentation Implementation ## Overview Phase 6 adds GPU-first machine learning capabilities to Phys-MCP with graphics-first outputs. This phase implements a consolidated `ml_ai_augmentation` tool with four ML methods for scientific computing applications. ## ✅ Completed Milestones ### M6-0: Preflight & Scaffolding ✅ - **Preflight Script**: `scripts/verify_phase6_prereqs.sh` - Validates ML dependencies and GPU acceleration - **Server Config**: Extended `server.config.json` with ML configuration section - **Prerequisites**: PyTorch, scikit-learn, matplotlib, sympy, optional PySR and DeepXDE ### M6-1: Symbolic Regression Training ✅ - **Implementation**: `ml_symbolic_regression` method with PySR integration and fallback - **Features**: - PySR integration for advanced symbolic regression (when available) - Polynomial fitting fallback for basic cases - GPU device detection and memory management - Graphics outputs: prediction overlays and residuals plots - Comprehensive metrics (R², MSE, MAE) - Caching by parameter hash for reproducibility ### Tool Integration ✅ - **Consolidated Tool**: `ml_ai_augmentation` with method-based routing - **Legacy Support**: Individual method names (`symbolic_regression_train`, etc.) supported - **Server Integration**: Full integration with Phys-MCP server routing - **Python Worker**: ML methods integrated into worker.py with config loading ## 🚧 Pending Milestones ### M6-2: Surrogate PDE Training - **Target**: Physics-informed neural networks (PINNs) and data-driven PDE surrogates - **Status**: Scaffolded, needs PINN implementation - **Dependencies**: DeepXDE or custom PINN implementation ### M6-3: Pattern Recognition Inference - **Target**: YOLO/U-Net for scientific imagery analysis - **Status**: Scaffolded, needs computer vision models - **Dependencies**: TorchVision, pre-trained models ### M6-4: Explain Derivation - **Target**: LLM-powered mathematical derivation and explanation - **Status**: Scaffolded, needs LLM integration - **Dependencies**: Local LLM or API integration ## 🏗️ Architecture ### Consolidated Tool Structure Following the established Phys-MCP pattern, Phase 6 implements a single consolidated tool: ```typescript // Consolidated format { "tool": "ml_ai_augmentation", "method": "symbolic_regression_train", "X": "path/to/features.csv", "y": "path/to/targets.csv", "ops": ["+", "-", "*", "/", "sin", "cos"], "use_pysr": true } // Legacy format (automatically converted) { "tool": "symbolic_regression_train", "X": "path/to/features.csv", "y": "path/to/targets.csv" } ``` ### GPU-First Design - **Device Selection**: Automatic CUDA/HIP/MPS/XPU detection with CPU fallback - **Memory Management**: VRAM monitoring and automatic batch size adjustment - **Error Handling**: Graceful degradation on GPU memory exhaustion ### Graphics-First Outputs All ML methods generate comprehensive visualizations: - **Training Curves**: Loss vs epoch plots - **Prediction Overlays**: Truth vs prediction comparisons - **Error Analysis**: Residuals plots and confusion matrices - **Animations**: Optional MP4/WebM/GIF for temporal data (PDE fields) ## 📁 File Structure ``` packages/ ├── tools-ml/ # ML tool package │ ├── src/ │ │ ├── schema.ts # TypeScript schemas for all ML methods │ │ ├── handlers.ts # Tool handlers with worker integration │ │ └── index.ts # Tool exports and definitions │ └── package.json ├── python-worker/ │ ├── ml_augmentation.py # Main ML implementation │ ├── worker.py # Updated with ML method routing │ └── utils.py # Extended with ML utility functions └── server/ └── src/index.ts # Updated with ML tool routing ``` ## 🧪 Testing ### Basic Tests ✅ - **Device Setup**: GPU detection and memory estimation - **Symbolic Regression**: Synthetic data recovery (y = 2x + 1) - **Results**: 2/2 tests passing ### Test Command ```bash python test_phase6_basic.py ``` ## 🔧 Configuration ### Server Config (`server.config.json`) ```json { "ml": { "default_backend": "torch", "max_vram_mb": 4096, "train": { "epochs": 200, "early_stop_patience": 20, "batch_size": 64, "lr": 1e-3 }, "video": { "fps": 24, "encoder_mp4": "libx264", "encoder_webm": "libvpx-vp9" } } } ``` ## 🚀 Usage Examples ### Symbolic Regression ```python # Discover equation from data result = await ml_tool({ "method": "symbolic_regression_train", "X": "features.csv", "y": "targets.csv", "ops": ["+", "-", "*", "/", "sin", "cos"], "max_depth": 12, "use_pysr": true }) print(f"Found: {result['expression_sympy']}") print(f"LaTeX: {result['expression_latex']}") print(f"R² = {result['meta']['r2_score']}") ``` ## 🔗 Integration ### Consolidated Tool Pattern Phase 6 follows the established Phys-MCP consolidation pattern: - **Single Tool**: `ml_ai_augmentation` (like `cas`, `plot`, `data`) - **Method Parameter**: Routes to specific ML functionality - **Legacy Support**: Individual tool names still work - **Backward Compatibility**: Existing code continues to function ### Server Routing ```typescript // Consolidated routing else if (name === "ml_ai_augmentation" && handleMLAugmentationTool) { result = await handleMLAugmentationTool(name, args); } // Legacy routing else if ((name === "symbolic_regression_train" || ...) && handleMLAugmentationTool) { result = await handleMLAugmentationTool(name, args); } ``` ## 🎯 Next Steps 1. **Complete M6-2**: Implement PINN/surrogate PDE training 2. **Complete M6-3**: Add YOLO/U-Net pattern recognition 3. **Complete M6-4**: Integrate LLM for derivation explanation 4. **Advanced Testing**: Comprehensive test suite with real datasets 5. **Documentation**: Usage examples and API documentation 6. **Performance**: GPU optimization and memory efficiency improvements ## 🏆 Benefits - **Unified Interface**: Single tool for all ML operations - **GPU Acceleration**: Automatic device selection and optimization - **Graphics-First**: Rich visualizations for all ML outputs - **Reproducible**: Caching and deterministic results - **Extensible**: Easy to add new ML methods - **Compatible**: Seamless integration with existing Phys-MCP tools Phase 6 establishes Phys-MCP as a comprehensive scientific computing platform with state-of-the-art ML capabilities, maintaining the project's commitment to GPU-first performance and graphics-rich outputs.