[v0.1.6] 2025-10-06

- Reconfigured wheel builds to keep all generated files in `pyhelios_build` directory
- Fixed README.md badge so wheel builds will show 'passing'
- Added missing files in `pyhelios/runtime/` directory to git control

Author: bnbailey-psl

.gitignore

@@ -9,16 +9,12 @@ build/
 *.egg-info/
 *.egg
 
-# Generated assets and libraries for wheel packaging (created by prepare_wheel.py)
-pyhelios/assets/build/
-# Track Python source files in plugins but ignore binary libraries
-pyhelios/plugins/*.so
-pyhelios/plugins/*.dll  
-pyhelios/plugins/*.dylib
-
 # Auto-generated version file (setuptools-scm)
 pyhelios/_version.py
 
+# Note: All other generated files (libraries, assets) are kept in pyhelios_build/
+# and are NOT in the source tree, so they don't need gitignore entries
+
 # Auto-generated documentation
 docs/generated/
 
@@ -46,4 +42,8 @@ docs/generated/
 *.~*
 
 # Auto-synced WeberPennTree resources (automatically maintained)
-/plugins/
+/plugins/
+
+# MCP memory server files (local development only)
+.aim/
+.mcp.json

CLAUDE.md

@@ -83,9 +83,16 @@ PyHelios now supports flexible plugin selection for customized builds based on y
 
 #### Clean Helios-Style Project Structure
 
-Following standard Helios C++ project conventions:
-- **pyhelios_build/** - Source files (CMakeLists.txt, main.cpp, etc.)
-- **pyhelios_build/build/** - All generated build artifacts including shared libraries for Python import
+Following standard Helios C++ project conventions with strict separation of source and generated files:
+- **pyhelios_build/** - Build source files (CMakeLists.txt, main.cpp, etc.)
+- **pyhelios_build/build/** - ALL generated build artifacts (libraries, assets, CMake cache)
+- **pyhelios/** - Python source code ONLY (no generated files)
+
+**CRITICAL BUILD ARTIFACT POLICY:**
+- ALL generated files (libraries, compiled assets, build outputs) MUST remain in `pyhelios_build/`
+- NEVER copy generated files into the source tree (`pyhelios/`)
+- Wheel packaging uses custom build commands to copy from `pyhelios_build/` to temporary build directories
+- This prevents accidental deletion of source files and maintains clean git status
 
 #### Plugin Selection Options
 

README.md

@@ -1,6 +1,6 @@
 <br><br>
 
-[![Build Wheels](https://github.com/PlantSimulationLab/PyHelios/actions/workflows/build-wheels.yml/badge.svg)](https://github.com/PlantSimulationLab/PyHelios/actions/workflows/build-wheels.yml) [![Test Linux](https://github.com/PlantSimulationLab/PyHelios/actions/workflows/pytest-linux.yml/badge.svg?branch=master)](https://github.com/PlantSimulationLab/PyHelios/actions/workflows/pytest-linux.yml) [![Test Windows](https://github.com/PlantSimulationLab/PyHelios/actions/workflows/pytest-windows.yml/badge.svg?branch=master)](https://github.com/PlantSimulationLab/PyHelios/actions/workflows/pytest-windows.yml) [![Test MacOS](https://github.com/PlantSimulationLab/PyHelios/actions/workflows/pytest-macos.yml/badge.svg?branch=master)](https://github.com/PlantSimulationLab/PyHelios/actions/workflows/pytest-macos.yml)
+[![Build Wheels](https://github.com/PlantSimulationLab/PyHelios/actions/workflows/build-wheels.yml/badge.svg?event=push)](https://github.com/PlantSimulationLab/PyHelios/actions/workflows/build-wheels.yml) [![Test Linux](https://github.com/PlantSimulationLab/PyHelios/actions/workflows/pytest-linux.yml/badge.svg?branch=master)](https://github.com/PlantSimulationLab/PyHelios/actions/workflows/pytest-linux.yml) [![Test Windows](https://github.com/PlantSimulationLab/PyHelios/actions/workflows/pytest-windows.yml/badge.svg?branch=master)](https://github.com/PlantSimulationLab/PyHelios/actions/workflows/pytest-windows.yml) [![Test MacOS](https://github.com/PlantSimulationLab/PyHelios/actions/workflows/pytest-macos.yml/badge.svg?branch=master)](https://github.com/PlantSimulationLab/PyHelios/actions/workflows/pytest-macos.yml)
 [![PyPI version](https://img.shields.io/pypi/v/pyhelios3d.svg)](https://pypi.org/project/pyhelios3d/)
 
 <div align="center">

build_scripts/prepare_wheel.py

@@ -152,19 +152,21 @@ def find_windows_dll_dependencies(lib_path, project_root):
 
 def copy_assets_for_packaging(project_root):
     """
-    Copy Helios assets to pyhelios/assets/build for packaging in wheels.
-    
+    Organize Helios assets in pyhelios_build/build/assets_for_wheel for packaging in wheels.
+
+    This keeps all generated files in pyhelios_build/ and out of the source tree.
+
     Args:
         project_root: Path to project root directory
     """
-    print("\nCopying assets for packaging...")
-    
+    print("\nOrganizing assets for packaging...")
+
     # Source directories
     build_dir = project_root / 'pyhelios_build' / 'build'
     helios_core = project_root / 'helios-core'
-    
-    # Destination: pyhelios/assets/build
-    dest_assets_dir = project_root / 'pyhelios' / 'assets' / 'build'
+
+    # Destination: pyhelios_build/build/assets_for_wheel (keeps generated files out of source tree)
+    dest_assets_dir = project_root / 'pyhelios_build' / 'build' / 'assets_for_wheel'
     dest_assets_dir.mkdir(parents=True, exist_ok=True)
 
     total_copied = 0
@@ -310,9 +312,12 @@ def copy_assets_for_packaging(project_root):
     print(f"[OK] Assets packaged in {dest_assets_dir}")
 
 def build_and_prepare(build_args):
-    """Build native libraries and copy them to pyhelios/plugins for packaging."""
+    """Build native libraries and organize assets for wheel packaging.
+
+    All generated files remain in pyhelios_build/ - nothing is copied to source tree.
+    """
     print("Building native libraries for wheel...")
-    
+
     script_dir = Path(__file__).parent
     project_root = script_dir.parent
 
@@ -355,43 +360,13 @@ def build_and_prepare(build_args):
             print(f"Build stderr: {e.stderr}")
         sys.exit(1)
 
-    # Copy built libraries to packaging location
+    # Validate built libraries exist (but don't copy them to source tree)
     build_lib_dir = project_root / 'pyhelios_build' / 'build' / 'lib'
-    plugins_dir = project_root / 'pyhelios' / 'plugins'
-    
+
     if not build_lib_dir.exists():
-        print(f"Warning: Build directory {build_lib_dir} does not exist")
-        return
-        
-    # Verify source plugins directory exists (should contain Python files)
-    if not plugins_dir.exists():
-        print(f"ERROR: Source plugins directory not found: {plugins_dir}")
-        print("The pyhelios/plugins/ directory with Python source files must exist")
-        sys.exit(1)
-        
-    # Verify it has the required Python files
-    py_files = list(plugins_dir.glob('*.py'))
-    if not py_files:
-        print(f"ERROR: No Python files found in plugins directory: {plugins_dir}")
-        print("The plugins directory must contain __init__.py and other Python source files")
+        print(f"ERROR: Build directory {build_lib_dir} does not exist")
         sys.exit(1)
-        
-    print(f"Found {len(py_files)} Python source files in plugins directory")
-    
-    # Remove any existing binary libraries from the source directory
-    # (These should not be there, but clean up just in case)
-    system = platform.system()
-    if system == 'Windows':
-        old_libs = list(plugins_dir.glob('*.dll'))
-    elif system == 'Darwin':
-        old_libs = list(plugins_dir.glob('*.dylib'))
-    else:
-        old_libs = list(plugins_dir.glob('*.so*'))
-        
-    for old_lib in old_libs:
-        print(f"Removing old library: {old_lib.name}")
-        old_lib.unlink()
-    
+
     # Platform-specific library extensions
     system = platform.system()
     if system == 'Windows':
@@ -400,13 +375,13 @@ def build_and_prepare(build_args):
         patterns = ['*.dylib']
     else:  # Linux and others
         patterns = ['*.so', '*.so.*']
-    
-    # Find and validate libraries
+
+    # Find and validate libraries (they stay in pyhelios_build/build/lib/)
     found_libraries = []
     for pattern in patterns:
         for lib_file in build_lib_dir.glob(pattern):
             found_libraries.append(lib_file)
-    
+
     if not found_libraries:
         print(f"ERROR: No libraries found matching patterns {patterns} in {build_lib_dir}")
         print("Available files in build directory:")
@@ -416,111 +391,38 @@ def build_and_prepare(build_args):
         except:
             print("  (cannot list directory contents)")
         sys.exit(1)
-    
-    # Copy and validate libraries
-    copied_count = 0
+
+    # Validate libraries (but keep them in build directory)
+    validated_count = 0
     failed_count = 0
-    
+
     for lib_file in found_libraries:
-        print(f"\nProcessing library: {lib_file.name}")
-        
-        # Validate library before copying
+        print(f"\nValidating library: {lib_file.name}")
+
+        # Validate library
         if not validate_library(lib_file):
-            print(f"[WARNING] Skipping invalid library: {lib_file.name}")
+            print(f"[WARNING] Invalid library: {lib_file.name}")
             failed_count += 1
             continue
-            
-        # Copy library
-        dest_file = plugins_dir / lib_file.name
-        try:
-            shutil.copy2(lib_file, dest_file)
-            print(f"[OK] Copied: {lib_file.name} -> {dest_file}")
-            
-            # Verify copied file
-            if not dest_file.exists() or dest_file.stat().st_size != lib_file.stat().st_size:
-                print(f"[ERROR] Copy verification failed for {lib_file.name}")
-                failed_count += 1
-                continue
-                
-            copied_count += 1
-            
-        except (OSError, PermissionError) as e:
-            print(f"[ERROR] Failed to copy {lib_file.name}: {e}")
-            failed_count += 1
-    
+
+        validated_count += 1
+
     # Summary
-    print(f"\n=== Library Copy Summary ===")
-    print(f"Found: {len(found_libraries)} libraries")
-    print(f"Copied: {copied_count} libraries")
+    print(f"\n=== Library Validation Summary ===")
+    print(f"Found: {len(found_libraries)} libraries in {build_lib_dir}")
+    print(f"Validated: {validated_count} libraries")
     print(f"Failed: {failed_count} libraries")
-    
-    if copied_count == 0:
-        print("ERROR: No libraries were successfully copied!")
+
+    if validated_count == 0:
+        print("ERROR: No valid libraries were found!")
         sys.exit(1)
     elif failed_count > 0:
-        print(f"WARNING: {failed_count} libraries could not be copied")
-        # Continue anyway - some failures might be acceptable
-    
-    print(f"[OK] Successfully prepared {copied_count} libraries for packaging")
-
-    # Windows-specific: Bundle additional DLL dependencies
-    if system == 'Windows' and copied_count > 0:
-        print(f"\n=== Windows DLL Dependency Bundling ===")
-
-        # Find the main library (usually libhelios.dll or helios.dll)
-        main_library = None
-        for lib_file in found_libraries:
-            if 'helios' in lib_file.name.lower() and lib_file.suffix == '.dll':
-                main_library = lib_file
-                break
-
-        if main_library:
-            # Find all required DLL dependencies
-            dependencies = find_windows_dll_dependencies(main_library, project_root)
-
-            dependency_copied = 0
-            dependency_failed = 0
-
-            for dep_dll in dependencies:
-                try:
-                    dest_dll = plugins_dir / dep_dll.name
-
-                    # Skip if already exists (avoid overwriting main libraries)
-                    if dest_dll.exists():
-                        print(f"[SKIP] Dependency already bundled: {dep_dll.name}")
-                        continue
-
-                    shutil.copy2(dep_dll, dest_dll)
-                    print(f"[OK] Bundled dependency: {dep_dll.name}")
-                    dependency_copied += 1
-
-                except (OSError, PermissionError) as e:
-                    print(f"[ERROR] Failed to bundle critical dependency {dep_dll.name}: {e}")
-                    print(f"This dependency is required for libhelios.dll to load properly on Windows systems")
-                    print(f"without development tools installed. The wheel will not work correctly.")
-                    dependency_failed += 1
-
-            print(f"\n=== Dependency Bundle Summary ===")
-            print(f"Found: {len(dependencies)} DLL dependencies")
-            print(f"Bundled: {dependency_copied} dependencies")
-            print(f"Failed: {dependency_failed} dependencies")
-
-            # Fail-fast: If critical dependencies are missing, the wheel is broken
-            if len(dependencies) > 0 and dependency_copied == 0:
-                print(f"[ERROR] CRITICAL: No Windows DLL dependencies were bundled!")
-                print(f"This means the wheel will fail to load on systems without development tools.")
-                print(f"Required dependencies: {[dep.name for dep in dependencies]}")
-                print(f"The wheel build cannot continue with missing critical dependencies.")
-                sys.exit(1)
-            elif dependency_failed > 0:
-                print(f"[ERROR] CRITICAL: {dependency_failed} critical dependencies could not be bundled!")
-                print(f"The wheel will not work properly on clean Windows systems.")
-                print(f"All dependencies must be bundled for the wheel to function correctly.")
-                sys.exit(1)
-            else:
-                print(f"[OK] All {dependency_copied} Windows DLL dependencies bundled successfully")
-        else:
-            print(f"[WARNING] Could not find main Helios library for dependency analysis")
+        print(f"WARNING: {failed_count} libraries could not be validated")
+
+    print(f"[OK] Libraries remain in build directory for wheel packaging: {build_lib_dir}")
+
+    # Note: Windows DLL dependencies will be handled by setup.py during wheel packaging
+    # No need to copy them to source tree
 
     # Copy assets for packaging
     copy_assets_for_packaging(project_root)
@@ -538,9 +440,10 @@ def main():
         print()
         print("This script:")
         print("  1. Calls build_scripts/build_helios.py with the provided arguments")
-        print("  2. Copies built libraries to pyhelios/plugins/ for wheel packaging")
-        print("  3. Copies required assets to pyhelios/assets/build/")
-        print("  4. Validates libraries can be loaded properly")
+        print("  2. Validates built libraries in pyhelios_build/build/lib/")
+        print("  3. Organizes assets in pyhelios_build/build/assets_for_wheel/")
+        print("  4. ALL files remain in pyhelios_build/ (NOT copied to source tree)")
+        print("  5. setup.py copies files from pyhelios_build/ during wheel creation")
         print()
         print("Common build arguments:")
         print("  --buildmode {debug,release,relwithdebinfo}  CMake build type")

docs/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+# [v0.1.6] 2025-10-06
+
+- Reconfigured wheel builds to keep all generated files in `pyhelios_build` directory
+- Fixed README.md badge so wheel builds will show 'passing'
+- Added missing files in `pyhelios/runtime/` directory to git control
+
 # [v0.1.5] 2025-10-06
 
 🚨++ New Plug-in Integrated ++ 🚨

docs/plugin_integration_guide.md

@@ -995,10 +995,12 @@ plugin_asset_dirs = {
 - **Exclude**: Source files (`.blend`, development tools, documentation)
 - **Verify**: Check helios-core/plugins/yourplugin/assets/ for directory structure
 
-**Why This Is Required**: The working directory context manager looks for assets via the asset manager, which searches multiple paths including `pyhelios/assets/build/plugins/yourplugin/`. During wheel builds, assets must be copied to this location by `prepare_wheel.py` or the plugin will fail with "assets not found" errors.
+**Why This Is Required**: The working directory context manager looks for assets via the asset manager. During wheel builds, `prepare_wheel.py` organizes assets in `pyhelios_build/build/assets_for_wheel/`, then `setup.py`'s custom build command copies them into the wheel. This keeps the source tree (`pyhelios/`) clean of all generated files.
 
 **INTEGRATION RULE**: New plugins should follow the **Stage 1 pattern** (CMake + working directory context manager) like WeberPennTree, Visualizer, and PlantArchitecture, **AND** must be added to `plugin_asset_dirs` in `prepare_wheel.py` for wheel distribution.
 
+**BUILD ARTIFACT POLICY**: All generated files (libraries, assets, build outputs) remain in `pyhelios_build/` and are NEVER copied to the source tree. Wheel packaging uses custom build commands to copy from `pyhelios_build/build/` to temporary build directories.
+
 ### 6.4 Plugin-Specific Asset Considerations
 
 Some plugins may require special asset handling:

pyhelios/runtime/__init__.py

@@ -0,0 +1,14 @@
+"""
+PyHelios runtime capability detection.
+
+This module provides runtime detection of hardware and software capabilities
+for PyHelios functionality, used primarily for test skipping and graceful
+degradation when hardware is not available.
+"""
+
+from .gpu_detector import is_gpu_runtime_available, get_gpu_runtime_info
+
+__all__ = [
+    'is_gpu_runtime_available',
+    'get_gpu_runtime_info'
+]