nepher 0.1.0__py3-none-any.whl

nepher/loader/base.py

@@ -0,0 +1,27 @@
+"""
+Base loader interface.
+"""
+
+from abc import ABC, abstractmethod
+from nepher.core import Environment
+from nepher.env_cfgs.base import BaseEnvCfg
+
+
+class BaseLoader(ABC):
+    """Base interface for environment loaders."""
+
+    @abstractmethod
+    def load(self, env: Environment, scene_idx: int, category: str) -> BaseEnvCfg:
+        """
+        Load scene config.
+
+        Args:
+            env: Environment object
+            scene_idx: Scene index
+            category: Environment category
+
+        Returns:
+            Category-appropriate config class
+        """
+        pass
+

nepher/loader/category_loaders/__init__.py

@@ -0,0 +1,2 @@
+"""Category-specific loaders (optional extensions)."""
+

nepher/loader/preset_loader.py

@@ -0,0 +1,80 @@
+"""
+Preset environment loader.
+"""
+
+import importlib.util
+import sys
+from pathlib import Path
+from typing import Optional
+from nepher.core import Environment
+from nepher.loader.base import BaseLoader
+from nepher.env_cfgs.registry import get_config_class
+
+
+def load_preset_module(preset_path: str, base_path: Optional[Path] = None):
+    """Load preset module from path.
+    
+    Args:
+        preset_path: Path to preset file (e.g., "my_preset.py") or module path
+        base_path: Base directory for resolving relative file paths
+    
+    Returns:
+        Preset config class
+        
+    Raises:
+        FileNotFoundError: If preset file is not found
+        ImportError: If preset module cannot be loaded
+        ValueError: If no preset config class is found
+    """
+    if preset_path.endswith(".py"):
+        if base_path:
+            file_path = base_path / preset_path
+        else:
+            file_path = Path(preset_path)
+        
+        if not file_path.exists():
+            raise FileNotFoundError(f"Preset file not found: {file_path}")
+        
+        module_name = f"nepher_preset_{file_path.stem}_{id(file_path)}"
+        
+        spec = importlib.util.spec_from_file_location(module_name, file_path)
+        if spec is None or spec.loader is None:
+            raise ImportError(f"Could not load preset from {file_path}")
+        
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[module_name] = module
+        spec.loader.exec_module(module)
+        
+        for attr_name in dir(module):
+            attr = getattr(module, attr_name)
+            if (isinstance(attr, type) and 
+                (attr_name.endswith("Cfg") or attr_name.endswith("PresetCfg")) and
+                attr_name != "PresetNavigationEnvCfg"):
+                return attr
+        
+        raise ValueError(f"No preset config class found in {file_path}")
+    else:
+        parts = preset_path.split(".")
+        module_path = ".".join(parts[:-1])
+        class_name = parts[-1]
+        
+        module = importlib.import_module(module_path)
+        return getattr(module, class_name)
+
+
+class PresetLoader(BaseLoader):
+    """Generic preset loader that returns category-specific configs."""
+
+    def load(self, env: Environment, scene_idx: int, category: str):
+        """Load preset scene config."""
+        if scene_idx >= len(env.preset_scenes):
+            raise IndexError(f"Preset scene index {scene_idx} out of range")
+
+        scene = env.preset_scenes[scene_idx]
+
+        if not scene.preset:
+            raise ValueError("Preset scene missing preset path")
+
+        preset_class = load_preset_module(scene.preset, base_path=env.cache_path)
+        return preset_class()
+

nepher/loader/registry.py

@@ -0,0 +1,63 @@
+"""
+Loader registry and convenience functions.
+"""
+
+from typing import Optional, Union
+from nepher.core import Environment
+from nepher.storage.cache import get_cache_manager
+from nepher.storage.manifest import ManifestParser
+from nepher.api.client import get_client
+from nepher.loader.usd_loader import UsdLoader
+from nepher.loader.preset_loader import PresetLoader
+
+
+def load_env(env_id: str, category: str) -> Environment:
+    """
+    Load environment from cache or download if needed.
+
+    Args:
+        env_id: Environment ID
+        category: Environment category
+
+    Returns:
+        Environment object
+    """
+    cache_manager = get_cache_manager(category=category)
+    cache_path = cache_manager.get_env_cache_path(env_id)
+
+    if cache_manager.is_cached(env_id):
+        manifest_path = cache_path / "manifest.yaml"
+        return ManifestParser.parse(manifest_path)
+
+    raise FileNotFoundError(
+        f"Environment {env_id} not found in cache. Use download() first."
+    )
+
+
+def load_scene(env: Environment, scene: Union[str, int], category: str):
+    """
+    Load scene config.
+
+    Args:
+        env: Environment object
+        scene: Scene name or index
+        category: Environment category
+
+    Returns:
+        Category-appropriate config class
+    """
+    scene_obj = env.get_scene(scene)
+    if not scene_obj:
+        raise ValueError(f"Scene {scene} not found in environment {env.id}")
+
+    if scene_obj.usd:
+        loader = UsdLoader()
+        scene_idx = env.scenes.index(scene_obj)
+        return loader.load(env, scene_idx, category)
+    elif scene_obj.preset:
+        loader = PresetLoader()
+        scene_idx = env.preset_scenes.index(scene_obj)
+        return loader.load(env, scene_idx, category)
+    else:
+        raise ValueError(f"Scene {scene} has no USD or preset path")
+

nepher/loader/usd_loader.py

@@ -0,0 +1,49 @@
+"""
+USD environment loader.
+"""
+
+from pathlib import Path
+from nepher.core import Environment
+from nepher.loader.base import BaseLoader
+from nepher.loader.preset_loader import load_preset_module
+from nepher.env_cfgs.registry import get_config_class
+
+
+class UsdLoader(BaseLoader):
+    """Generic USD loader that returns category-specific configs."""
+
+    def load(self, env: Environment, scene_idx: int, category: str):
+        """Load USD scene config.
+        
+        If the scene has a Python scene file, it will be loaded and used to configure
+        the USD environment. Otherwise, a basic config is created from the manifest.
+        """
+        if scene_idx >= len(env.scenes):
+            raise IndexError(f"Scene index {scene_idx} out of range")
+
+        scene = env.scenes[scene_idx]
+
+        if scene.scene:
+            scene_class = load_preset_module(scene.scene, base_path=env.cache_path)
+            cfg = scene_class()
+            
+            if scene.usd and not cfg.usd_path:
+                cfg.usd_path = str(scene.usd)
+            if scene.omap_meta and not cfg.occupancy_map_yaml:
+                cfg.occupancy_map_yaml = str(scene.omap_meta)
+            if scene.name and not cfg.name:
+                cfg.name = scene.name
+            if scene.description and not cfg.description:
+                cfg.description = scene.description
+            
+            return cfg
+        
+        config_class = get_config_class(category=category, type="usd")
+        cfg = config_class()
+        cfg.usd_path = str(scene.usd) if scene.usd else None
+        cfg.occupancy_map_yaml = str(scene.omap_meta) if scene.omap_meta else None
+        cfg.name = scene.name
+        cfg.description = scene.description
+
+        return cfg
+

nepher/storage/__init__.py

@@ -0,0 +1,8 @@
+"""Storage and cache management."""
+
+from nepher.storage.cache import CacheManager, get_cache_manager
+from nepher.storage.bundle import BundleManager
+from nepher.storage.manifest import ManifestParser
+
+__all__ = ["CacheManager", "get_cache_manager", "BundleManager", "ManifestParser"]
+

nepher/storage/bundle.py

@@ -0,0 +1,78 @@
+"""
+Bundle validation and extraction.
+"""
+
+import zipfile
+import shutil
+from pathlib import Path
+from typing import Optional
+from nepher.storage.manifest import ManifestParser
+from nepher.core import Environment
+
+
+class BundleManager:
+    """Manages environment bundle operations."""
+
+    @staticmethod
+    def extract_bundle(zip_path: Path, dest_dir: Path) -> Environment:
+        """
+        Extract and validate bundle.
+
+        Args:
+            zip_path: Path to bundle ZIP file
+            dest_dir: Destination directory for extraction
+
+        Returns:
+            Environment object from manifest
+        """
+        dest_dir.mkdir(parents=True, exist_ok=True)
+
+        try:
+            with zipfile.ZipFile(zip_path, "r") as zip_ref:
+                zip_ref.extractall(dest_dir)
+        except zipfile.BadZipFile as e:
+            raise ValueError(f"Invalid ZIP file: {zip_path}") from e
+        except (PermissionError, OSError) as e:
+            raise RuntimeError(f"Cannot extract bundle to {dest_dir}: {e}") from e
+
+        manifest_path = dest_dir / "manifest.yaml"
+        if not manifest_path.exists():
+            raise ValueError(f"Manifest not found in bundle: {manifest_path}")
+
+        env = ManifestParser.parse(manifest_path)
+
+        for scene in env.scenes:
+            if scene.usd:
+                scene.usd = dest_dir / scene.usd
+            if scene.omap_meta:
+                scene.omap_meta = dest_dir / scene.omap_meta
+
+        env.cache_path = dest_dir
+
+        return env
+
+    @staticmethod
+    def validate_bundle(bundle_path: Path) -> bool:
+        """
+        Validate bundle structure.
+
+        Args:
+            bundle_path: Path to bundle (ZIP file or directory)
+
+        Returns:
+            True if valid, False otherwise
+        """
+        try:
+            if bundle_path.is_dir():
+                manifest_path = bundle_path / "manifest.yaml"
+                return manifest_path.exists()
+            
+            if bundle_path.suffix.lower() == ".zip":
+                with zipfile.ZipFile(bundle_path, "r") as zip_ref:
+                    namelist = zip_ref.namelist()
+                    return "manifest.yaml" in namelist
+            
+            return False
+        except Exception:
+            return False
+

nepher/storage/cache.py

@@ -0,0 +1,145 @@
+"""
+Cache management for downloaded environments.
+
+Handles user-configurable cache directories and cache operations.
+"""
+
+import shutil
+from pathlib import Path
+from typing import List, Optional, Dict, Any
+from nepher.config import get_config
+
+
+class CacheManager:
+    """Manages local cache for environments."""
+
+    def __init__(self, cache_dir: Optional[Path] = None, category: Optional[str] = None):
+        """
+        Initialize cache manager.
+
+        Args:
+            cache_dir: Override cache directory (from CLI flag)
+            category: Category for category-specific cache
+        """
+        config = get_config()
+        self.cache_dir = cache_dir or config.get_cache_dir(category=category)
+        self.category = category
+
+    def get_env_cache_path(self, env_id: str) -> Path:
+        """Get cache path for a specific environment."""
+        return self.cache_dir / env_id
+
+    def is_cached(self, env_id: str) -> bool:
+        """Check if environment is cached."""
+        cache_path = self.get_env_cache_path(env_id)
+        return cache_path.exists() and (cache_path / "manifest.yaml").exists()
+
+    def list_cached(self) -> List[str]:
+        """
+        List all cached environment IDs.
+        
+        Returns:
+            List of cached environment ID strings
+        """
+        if not self.cache_dir.exists():
+            return []
+
+        cached = []
+        try:
+            for item in self.cache_dir.iterdir():
+                if item.is_dir() and (item / "manifest.yaml").exists():
+                    cached.append(item.name)
+        except (PermissionError, OSError) as e:
+            raise RuntimeError(f"Cannot access cache directory {self.cache_dir}: {e}") from e
+
+        return cached
+
+    def clear_cache(self, env_id: Optional[str] = None):
+        """
+        Clear cache.
+
+        Args:
+            env_id: Specific environment ID to clear, or None to clear all
+            
+        Raises:
+            RuntimeError: If cache directory cannot be accessed
+        """
+        try:
+            if env_id:
+                cache_path = self.get_env_cache_path(env_id)
+                if cache_path.exists():
+                    shutil.rmtree(cache_path)
+            else:
+                if self.cache_dir.exists():
+                    shutil.rmtree(self.cache_dir)
+                    self.cache_dir.mkdir(parents=True, exist_ok=True)
+        except (PermissionError, OSError) as e:
+            raise RuntimeError(f"Cannot clear cache: {e}") from e
+
+    def get_cache_info(self) -> Dict[str, Any]:
+        """Get cache statistics."""
+        if not self.cache_dir.exists():
+            return {
+                "cache_dir": str(self.cache_dir),
+                "total_size": 0,
+                "env_count": 0,
+                "environments": [],
+            }
+
+        envs = self.list_cached()
+        total_size = 0
+        env_sizes = {}
+
+        for env_id in envs:
+            try:
+                env_path = self.get_env_cache_path(env_id)
+                size = sum(f.stat().st_size for f in env_path.rglob("*") if f.is_file())
+                env_sizes[env_id] = size
+                total_size += size
+            except (PermissionError, OSError):
+                continue
+
+        return {
+            "cache_dir": str(self.cache_dir),
+            "total_size": total_size,
+            "env_count": len(envs),
+            "environments": [{"id": eid, "size": env_sizes[eid]} for eid in envs],
+        }
+
+    def migrate_cache(self, new_cache_dir: Path):
+        """
+        Migrate cache to new location.
+
+        Args:
+            new_cache_dir: New cache directory path
+            
+        Raises:
+            RuntimeError: If migration fails
+        """
+        if not self.cache_dir.exists():
+            return
+
+        try:
+            new_cache_dir.mkdir(parents=True, exist_ok=True)
+
+            for env_id in self.list_cached():
+                old_path = self.get_env_cache_path(env_id)
+                new_path = new_cache_dir / env_id
+                shutil.move(str(old_path), str(new_path))
+        except (PermissionError, OSError, shutil.Error) as e:
+            raise RuntimeError(f"Cannot migrate cache to {new_cache_dir}: {e}") from e
+
+
+# Global cache manager instance
+_cache_manager_instance: Optional[CacheManager] = None
+
+
+def get_cache_manager(
+    cache_dir: Optional[Path] = None, category: Optional[str] = None
+) -> CacheManager:
+    """Get global cache manager instance."""
+    global _cache_manager_instance
+    if _cache_manager_instance is None:
+        _cache_manager_instance = CacheManager(cache_dir=cache_dir, category=category)
+    return _cache_manager_instance
+

nepher/storage/manifest.py

@@ -0,0 +1,80 @@
+"""
+Manifest parsing for environment bundles.
+"""
+
+import yaml
+from pathlib import Path
+from typing import Dict, Any, List, Optional
+from nepher.core import Environment, Scene
+
+
+class ManifestParser:
+    """Parser for environment manifest files."""
+
+    @staticmethod
+    def parse(manifest_path: Path) -> Environment:
+        """
+        Parse manifest YAML file.
+
+        Args:
+            manifest_path: Path to manifest.yaml
+
+        Returns:
+            Environment object
+        """
+        try:
+            with open(manifest_path, "r", encoding="utf-8") as f:
+                data = yaml.safe_load(f)
+        except FileNotFoundError:
+            raise FileNotFoundError(f"Manifest file not found: {manifest_path}")
+        except yaml.YAMLError as e:
+            raise ValueError(f"Invalid YAML in manifest file {manifest_path}: {e}") from e
+
+        env_id = data.get("id", manifest_path.parent.name)
+        name = data.get("name", env_id)
+        description = data.get("description")
+        category = data.get("category", "navigation")
+        version = data.get("version")
+        author = data.get("author")
+        benchmark = data.get("benchmark", False)
+        metadata = data.get("metadata", {})
+
+        env_type = "preset" if data.get("preset_scenes") else "usd"
+
+        scenes = []
+        for scene_data in data.get("scenes", []):
+            scene = Scene(
+                name=scene_data.get("scene_id") or scene_data.get("name", ""),
+                description=scene_data.get("description"),
+                usd=Path(scene_data["usd"]) if scene_data.get("usd") else None,
+                scene=scene_data.get("scene"),  # Python scene file for USD scenes
+                omap_meta=Path(scene_data["omap_meta"]) if scene_data.get("omap_meta") else None,
+                metadata=scene_data.get("metadata"),
+            )
+            scenes.append(scene)
+
+        preset_scenes = []
+        for preset_data in data.get("preset_scenes", []):
+            scene = Scene(
+                name=preset_data.get("scene_id") or preset_data.get("name", ""),
+                description=preset_data.get("description"),
+                preset=preset_data.get("preset"),
+                metadata=preset_data.get("metadata"),
+            )
+            preset_scenes.append(scene)
+
+        return Environment(
+            id=env_id,
+            name=name,
+            description=description,
+            category=category,
+            type=env_type,
+            version=version,
+            author=author,
+            scenes=scenes,
+            preset_scenes=preset_scenes,
+            benchmark=benchmark,
+            metadata=metadata,
+            cache_path=manifest_path.parent,
+        )
+

nepher/utils/__init__.py

@@ -0,0 +1,12 @@
+"""Utility functions for the Nepher platform."""
+
+from nepher.utils.free_zone_finder import FreeZone, Rectangle, find_free_zones
+from nepher.utils.fast_spawn_sampler import FastSpawnSampler, OccupancyMapConfig
+
+__all__ = [
+    "FreeZone",
+    "Rectangle", 
+    "find_free_zones",
+    "FastSpawnSampler",
+    "OccupancyMapConfig",
+]