comfy-env 0.1.15__tar.gz → 0.1.16__tar.gz

comfy_env-0.1.16/PKG-INFO

@@ -0,0 +1,279 @@
+Metadata-Version: 2.4
+Name: comfy-env
+Version: 0.1.16
+Summary: Environment management for ComfyUI custom nodes - CUDA wheel resolution and process isolation
+Project-URL: Homepage, https://github.com/PozzettiAndrea/comfy-env
+Project-URL: Repository, https://github.com/PozzettiAndrea/comfy-env
+Project-URL: Issues, https://github.com/PozzettiAndrea/comfy-env/issues
+Author: Andrea Pozzetti
+License: MIT
+License-File: LICENSE
+Keywords: comfyui,cuda,environment,isolation,process,venv,wheels
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: pip>=21.0
+Requires-Dist: tomli-w>=1.0.0
+Requires-Dist: tomli>=2.0.0
+Requires-Dist: uv>=0.4.0
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# comfy-env
+
+Environment management for ComfyUI custom nodes.
+
+## Quick Start
+
+```bash
+pip install comfy-env
+```
+
+**1. Create `comfy-env.toml` in your node directory:**
+
+```toml
+[cuda]
+packages = ["nvdiffrast", "pytorch3d"]
+
+[pypi-dependencies]
+trimesh = { version = "*", extras = ["easy"] }
+```
+
+**2. In `install.py`:**
+
+```python
+from comfy_env import install
+install()
+```
+
+**3. In `prestartup_script.py`:**
+
+```python
+from comfy_env import setup_env
+setup_env()
+```
+
+That's it. CUDA wheels install without compilation, and the environment is ready.
+
+---
+
+## Configuration
+
+Create `comfy-env.toml` in your node directory:
+
+```toml
+# Python version for isolated environment (optional)
+python = "3.11"
+
+# CUDA packages from cuda-wheels index (no compilation needed)
+[cuda]
+packages = ["nvdiffrast", "pytorch3d", "flash-attn"]
+
+# System packages (Linux only)
+[apt]
+packages = ["libgl1-mesa-glx", "libglu1-mesa"]
+
+# Environment variables
+[env_vars]
+KMP_DUPLICATE_LIB_OK = "TRUE"
+OMP_NUM_THREADS = "1"
+
+# Dependent custom nodes to auto-install
+[node_reqs]
+ComfyUI_essentials = "cubiq/ComfyUI_essentials"
+
+# Conda packages (via pixi)
+[dependencies]
+cgal = "*"
+
+# PyPI packages
+[pypi-dependencies]
+trimesh = { version = "*", extras = ["easy"] }
+numpy = "*"
+```
+
+---
+
+## Process Isolation
+
+For nodes with conflicting dependencies, use isolated execution:
+
+```python
+# In nodes/__init__.py
+from pathlib import Path
+from comfy_env import wrap_isolated_nodes
+
+# Import your isolated nodes
+from .cgal import NODE_CLASS_MAPPINGS as cgal_mappings
+
+# Wrap them for isolated execution
+NODE_CLASS_MAPPINGS = wrap_isolated_nodes(
+    cgal_mappings,
+    Path(__file__).parent / "cgal"  # Directory with comfy-env.toml
+)
+```
+
+Each wrapped node runs in a subprocess with its own Python environment.
+
+---
+
+## CLI Commands
+
+```bash
+# Show detected environment
+comfy-env info
+
+# Install dependencies
+comfy-env install
+
+# Preview without installing
+comfy-env install --dry-run
+
+# Verify packages
+comfy-env doctor
+
+# Install system packages
+comfy-env apt-install
+```
+
+---
+
+## API Reference
+
+### install()
+
+Install dependencies from comfy-env.toml:
+
+```python
+from comfy_env import install
+
+install()                    # Auto-detect config
+install(dry_run=True)        # Preview only
+install(config="path.toml")  # Explicit config
+```
+
+### setup_env()
+
+Set up environment at ComfyUI startup:
+
+```python
+from comfy_env import setup_env
+
+setup_env()  # Auto-detects node directory from caller
+```
+
+Sets library paths, environment variables, and injects site-packages.
+
+### wrap_isolated_nodes()
+
+Wrap nodes for subprocess isolation:
+
+```python
+from comfy_env import wrap_isolated_nodes
+
+wrapped = wrap_isolated_nodes(NODE_CLASS_MAPPINGS, node_dir)
+```
+
+### Detection
+
+```python
+from comfy_env import (
+    detect_cuda_version,      # Returns "12.8", "12.4", or None
+    detect_gpu,               # Returns GPUInfo or None
+    get_gpu_summary,          # Human-readable string
+    RuntimeEnv,               # Combined runtime info
+)
+
+env = RuntimeEnv.detect()
+print(env)  # Python 3.11, CUDA 12.8, PyTorch 2.8.0, GPU: RTX 4090
+```
+
+### Workers
+
+Low-level process isolation:
+
+```python
+from comfy_env import MPWorker, SubprocessWorker
+
+# Same Python version (multiprocessing)
+worker = MPWorker()
+result = worker.call(my_function, arg1, arg2)
+
+# Different Python version (subprocess)
+worker = SubprocessWorker(python="/path/to/python")
+result = worker.call(my_function, arg1, arg2)
+```
+
+---
+
+## Real Example
+
+See [ComfyUI-GeometryPack](https://github.com/PozzettiAndrea/ComfyUI-GeometryPack) for a production example with:
+
+- Multiple isolated environments (CGAL, Blender, GPU)
+- Per-subdirectory comfy-env.toml
+- Prestartup asset copying
+- Different Python versions (3.11 for Blender API)
+
+---
+
+## Architecture
+
+### Layers
+
+```
+comfy_env/
+├── detection/     # Pure functions - CUDA, GPU, platform detection
+├── config/        # Pure parsing - comfy-env.toml → typed config
+├── environment/   # Side effects - cache, paths, setup
+├── packages/      # Side effects - pixi, cuda-wheels, apt
+├── isolation/     # Side effects - subprocess workers, node wrapping
+└── install.py     # Orchestration
+```
+
+### Why Isolation?
+
+ComfyUI nodes share a single Python environment. This breaks when:
+
+1. **Dependency conflicts**: Node A needs `torch==2.4`, Node B needs `torch==2.8`
+2. **Native library conflicts**: Two packages bundle incompatible libomp
+3. **Python version requirements**: Blender API requires Python 3.11
+
+Solution: Run each node group in its own subprocess with isolated dependencies.
+
+### Why CUDA Wheels?
+
+Installing packages like `nvdiffrast` normally requires:
+- CUDA toolkit
+- C++ compiler
+- 30+ minutes of compilation
+
+CUDA wheels from [cuda-wheels](https://pozzettiandrea.github.io/cuda-wheels/) are pre-built for common configurations:
+
+| GPU | CUDA | PyTorch |
+|-----|------|---------|
+| Blackwell (sm_100+) | 12.8 | 2.8 |
+| Ada/Hopper/Ampere | 12.8 | 2.8 |
+| Turing | 12.8 | 2.8 |
+| Pascal | 12.4 | 2.4 |
+
+### How Environments Work
+
+1. **Central cache**: Environments stored at `~/.comfy-env/envs/`
+2. **Marker files**: `.comfy-env-marker.toml` links node → env
+3. **Orphan cleanup**: Envs deleted when their node is removed
+4. **Hash-based naming**: Config changes create new envs
+
+---
+
+## License
+
+MIT

comfy_env-0.1.16/README.md

@@ -0,0 +1,250 @@
+# comfy-env
+
+Environment management for ComfyUI custom nodes.
+
+## Quick Start
+
+```bash
+pip install comfy-env
+```
+
+**1. Create `comfy-env.toml` in your node directory:**
+
+```toml
+[cuda]
+packages = ["nvdiffrast", "pytorch3d"]
+
+[pypi-dependencies]
+trimesh = { version = "*", extras = ["easy"] }
+```
+
+**2. In `install.py`:**
+
+```python
+from comfy_env import install
+install()
+```
+
+**3. In `prestartup_script.py`:**
+
+```python
+from comfy_env import setup_env
+setup_env()
+```
+
+That's it. CUDA wheels install without compilation, and the environment is ready.
+
+---
+
+## Configuration
+
+Create `comfy-env.toml` in your node directory:
+
+```toml
+# Python version for isolated environment (optional)
+python = "3.11"
+
+# CUDA packages from cuda-wheels index (no compilation needed)
+[cuda]
+packages = ["nvdiffrast", "pytorch3d", "flash-attn"]
+
+# System packages (Linux only)
+[apt]
+packages = ["libgl1-mesa-glx", "libglu1-mesa"]
+
+# Environment variables
+[env_vars]
+KMP_DUPLICATE_LIB_OK = "TRUE"
+OMP_NUM_THREADS = "1"
+
+# Dependent custom nodes to auto-install
+[node_reqs]
+ComfyUI_essentials = "cubiq/ComfyUI_essentials"
+
+# Conda packages (via pixi)
+[dependencies]
+cgal = "*"
+
+# PyPI packages
+[pypi-dependencies]
+trimesh = { version = "*", extras = ["easy"] }
+numpy = "*"
+```
+
+---
+
+## Process Isolation
+
+For nodes with conflicting dependencies, use isolated execution:
+
+```python
+# In nodes/__init__.py
+from pathlib import Path
+from comfy_env import wrap_isolated_nodes
+
+# Import your isolated nodes
+from .cgal import NODE_CLASS_MAPPINGS as cgal_mappings
+
+# Wrap them for isolated execution
+NODE_CLASS_MAPPINGS = wrap_isolated_nodes(
+    cgal_mappings,
+    Path(__file__).parent / "cgal"  # Directory with comfy-env.toml
+)
+```
+
+Each wrapped node runs in a subprocess with its own Python environment.
+
+---
+
+## CLI Commands
+
+```bash
+# Show detected environment
+comfy-env info
+
+# Install dependencies
+comfy-env install
+
+# Preview without installing
+comfy-env install --dry-run
+
+# Verify packages
+comfy-env doctor
+
+# Install system packages
+comfy-env apt-install
+```
+
+---
+
+## API Reference
+
+### install()
+
+Install dependencies from comfy-env.toml:
+
+```python
+from comfy_env import install
+
+install()                    # Auto-detect config
+install(dry_run=True)        # Preview only
+install(config="path.toml")  # Explicit config
+```
+
+### setup_env()
+
+Set up environment at ComfyUI startup:
+
+```python
+from comfy_env import setup_env
+
+setup_env()  # Auto-detects node directory from caller
+```
+
+Sets library paths, environment variables, and injects site-packages.
+
+### wrap_isolated_nodes()
+
+Wrap nodes for subprocess isolation:
+
+```python
+from comfy_env import wrap_isolated_nodes
+
+wrapped = wrap_isolated_nodes(NODE_CLASS_MAPPINGS, node_dir)
+```
+
+### Detection
+
+```python
+from comfy_env import (
+    detect_cuda_version,      # Returns "12.8", "12.4", or None
+    detect_gpu,               # Returns GPUInfo or None
+    get_gpu_summary,          # Human-readable string
+    RuntimeEnv,               # Combined runtime info
+)
+
+env = RuntimeEnv.detect()
+print(env)  # Python 3.11, CUDA 12.8, PyTorch 2.8.0, GPU: RTX 4090
+```
+
+### Workers
+
+Low-level process isolation:
+
+```python
+from comfy_env import MPWorker, SubprocessWorker
+
+# Same Python version (multiprocessing)
+worker = MPWorker()
+result = worker.call(my_function, arg1, arg2)
+
+# Different Python version (subprocess)
+worker = SubprocessWorker(python="/path/to/python")
+result = worker.call(my_function, arg1, arg2)
+```
+
+---
+
+## Real Example
+
+See [ComfyUI-GeometryPack](https://github.com/PozzettiAndrea/ComfyUI-GeometryPack) for a production example with:
+
+- Multiple isolated environments (CGAL, Blender, GPU)
+- Per-subdirectory comfy-env.toml
+- Prestartup asset copying
+- Different Python versions (3.11 for Blender API)
+
+---
+
+## Architecture
+
+### Layers
+
+```
+comfy_env/
+├── detection/     # Pure functions - CUDA, GPU, platform detection
+├── config/        # Pure parsing - comfy-env.toml → typed config
+├── environment/   # Side effects - cache, paths, setup
+├── packages/      # Side effects - pixi, cuda-wheels, apt
+├── isolation/     # Side effects - subprocess workers, node wrapping
+└── install.py     # Orchestration
+```
+
+### Why Isolation?
+
+ComfyUI nodes share a single Python environment. This breaks when:
+
+1. **Dependency conflicts**: Node A needs `torch==2.4`, Node B needs `torch==2.8`
+2. **Native library conflicts**: Two packages bundle incompatible libomp
+3. **Python version requirements**: Blender API requires Python 3.11
+
+Solution: Run each node group in its own subprocess with isolated dependencies.
+
+### Why CUDA Wheels?
+
+Installing packages like `nvdiffrast` normally requires:
+- CUDA toolkit
+- C++ compiler
+- 30+ minutes of compilation
+
+CUDA wheels from [cuda-wheels](https://pozzettiandrea.github.io/cuda-wheels/) are pre-built for common configurations:
+
+| GPU | CUDA | PyTorch |
+|-----|------|---------|
+| Blackwell (sm_100+) | 12.8 | 2.8 |
+| Ada/Hopper/Ampere | 12.8 | 2.8 |
+| Turing | 12.8 | 2.8 |
+| Pascal | 12.4 | 2.4 |
+
+### How Environments Work
+
+1. **Central cache**: Environments stored at `~/.comfy-env/envs/`
+2. **Marker files**: `.comfy-env-marker.toml` links node → env
+3. **Orphan cleanup**: Envs deleted when their node is removed
+4. **Hash-based naming**: Config changes create new envs
+
+---
+
+## License
+
+MIT

{comfy_env-0.1.15 → comfy_env-0.1.16}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "comfy-env"
-version = "0.1.15"
+version = "0.1.16"
 description = "Environment management for ComfyUI custom nodes - CUDA wheel resolution and process isolation"
 readme = "README.md"
 license = {text = "MIT"}

comfy_env-0.1.16/src/comfy_env/__init__.py

@@ -0,0 +1,186 @@
+"""
+comfy-env - Environment management for ComfyUI custom nodes.
+
+Features:
+- CUDA wheel resolution (pre-built wheels without compilation)
+- Process isolation (run nodes in separate Python environments)
+- Central environment cache (~/.comfy-env/envs/)
+"""
+
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("comfy-env")
+except PackageNotFoundError:
+    __version__ = "0.0.0-dev"
+
+
+# =============================================================================
+# Primary API (what most users need)
+# =============================================================================
+
+# Install API
+from .install import install, verify_installation, USE_COMFY_ENV_VAR
+
+# Prestartup helpers
+from .environment.setup import setup_env
+from .environment.paths import copy_files
+
+# Isolation
+from .isolation import wrap_isolated_nodes, wrap_nodes
+
+
+# =============================================================================
+# Config Layer
+# =============================================================================
+
+from .config import (
+    ComfyEnvConfig,
+    NodeDependency,
+    NodeReq,  # Backwards compatibility alias
+    load_config,
+    discover_config,
+    CONFIG_FILE_NAME,
+)
+
+
+# =============================================================================
+# Detection Layer
+# =============================================================================
+
+from .detection import (
+    # CUDA detection
+    detect_cuda_version,
+    detect_cuda_environment,
+    get_recommended_cuda_version,
+    # GPU detection
+    GPUInfo,
+    CUDAEnvironment,
+    detect_gpu,
+    get_gpu_summary,
+    # Platform detection
+    detect_platform,
+    get_platform_tag,
+    # Runtime detection
+    RuntimeEnv,
+    detect_runtime,
+)
+
+
+# =============================================================================
+# Packages Layer
+# =============================================================================
+
+from .packages import (
+    # Pixi
+    ensure_pixi,
+    get_pixi_path,
+    get_pixi_python,
+    pixi_run,
+    pixi_clean,
+    # CUDA wheels
+    CUDA_WHEELS_INDEX,
+    get_wheel_url,
+    get_cuda_torch_mapping,
+)
+
+
+# =============================================================================
+# Environment Layer
+# =============================================================================
+
+from .environment import (
+    # Cache management
+    get_cache_dir,
+    cleanup_orphaned_envs,
+    resolve_env_path,
+    CACHE_DIR,
+    MARKER_FILE,
+)
+
+
+# =============================================================================
+# Isolation Layer
+# =============================================================================
+
+from .isolation import (
+    # Workers
+    Worker,
+    WorkerError,
+    MPWorker,
+    SubprocessWorker,
+    # Tensor utilities
+    TensorKeeper,
+)
+
+
+# =============================================================================
+# Exports
+# =============================================================================
+
+__all__ = [
+    # Install API
+    "install",
+    "verify_installation",
+    "USE_COMFY_ENV_VAR",
+    # Prestartup
+    "setup_env",
+    "copy_files",
+    # Isolation
+    "wrap_isolated_nodes",
+    "wrap_nodes",
+    # Config
+    "ComfyEnvConfig",
+    "NodeDependency",
+    "NodeReq",
+    "load_config",
+    "discover_config",
+    "CONFIG_FILE_NAME",
+    # Detection
+    "detect_cuda_version",
+    "detect_cuda_environment",
+    "get_recommended_cuda_version",
+    "GPUInfo",
+    "CUDAEnvironment",
+    "detect_gpu",
+    "get_gpu_summary",
+    "detect_platform",
+    "get_platform_tag",
+    "RuntimeEnv",
+    "detect_runtime",
+    # Packages
+    "ensure_pixi",
+    "get_pixi_path",
+    "get_pixi_python",
+    "pixi_run",
+    "pixi_clean",
+    "CUDA_WHEELS_INDEX",
+    "get_wheel_url",
+    "get_cuda_torch_mapping",
+    # Environment
+    "get_cache_dir",
+    "cleanup_orphaned_envs",
+    "resolve_env_path",
+    "CACHE_DIR",
+    "MARKER_FILE",
+    # Workers
+    "Worker",
+    "WorkerError",
+    "MPWorker",
+    "SubprocessWorker",
+    "TensorKeeper",
+]
+
+
+# =============================================================================
+# Startup cleanup
+# =============================================================================
+
+def _run_startup_cleanup():
+    """Clean orphaned envs on startup."""
+    try:
+        cleanup_orphaned_envs(log=lambda x: None)  # Silent
+    except Exception:
+        pass  # Never fail startup due to cleanup
+
+_run_startup_cleanup()