Add SPINE_CONFIG_PATH support for config include resolution

- Added resolve_config_path() function with smart path resolution
- Supports SPINE_CONFIG_PATH environment variable (colon-separated list)
- Resolution order: absolute → relative → SPINE_CONFIG_PATH
- Auto-adds .yaml/.yml extensions if not found
- Relative paths take precedence over search paths
- Added 5 comprehensive tests for all resolution scenarios
- Updated config README with SPINE_CONFIG_PATH documentation

Author: francois-drielsma

src/spine/config/README.md

@@ -72,6 +72,44 @@ model:
   head: !include model/head.yaml
 ```
 
+#### Include Path Resolution
+
+SPINE searches for included files in this order:
+
+1. **Absolute paths**: Used as-is if they exist
+2. **Relative paths**: Resolved relative to the including config file
+3. **SPINE_CONFIG_PATH**: Searches through directories specified in the `SPINE_CONFIG_PATH` environment variable
+
+**Extension handling**: If a file isn't found, SPINE automatically tries adding `.yaml` or `.yml` extensions.
+
+**Example with SPINE_CONFIG_PATH**:
+
+```bash
+# Set shared config directories
+export SPINE_CONFIG_PATH="/usr/local/spine/configs:/home/user/shared_configs"
+
+# Now configs can include files from these directories without absolute paths
+```
+
+```yaml
+# config.yaml - can include files from SPINE_CONFIG_PATH
+include:
+  - base/default.yaml      # Found in /usr/local/spine/configs/base/default.yaml
+  - detectors/icarus       # Auto-adds .yaml, finds in /home/user/shared_configs/detectors/icarus.yaml
+  
+io:
+  reader:
+    batch_size: 32
+```
+
+**Multiple search paths**: Separate paths with `:` (like `PATH` or `PYTHONPATH`):
+
+```bash
+export SPINE_CONFIG_PATH="$HOME/.spine/configs:/opt/spine/configs:/shared/configs"
+```
+
+**Path precedence**: Relative paths (from the config's directory) always take precedence over `SPINE_CONFIG_PATH` entries. This allows local overrides of shared configs.
+
 ### Parameter Overrides with `override:`
 
 Override specific parameters using dot notation:

src/spine/config/loader.py

@@ -75,9 +75,88 @@
     "extract_includes_and_overrides",
     "apply_collection_operation",
     "ConfigLoader",
+    "resolve_config_path",
 ]
 
 
+def resolve_config_path(
+    filename: str, current_dir: str, search_paths: Optional[List[str]] = None
+) -> str:
+    """Resolve a configuration file path with SPINE_CONFIG_PATH support.
+
+    Resolution order:
+    1. If absolute path, return as-is
+    2. Try relative to current_dir
+    3. Try relative to current_dir with .yaml/.yml extension
+    4. Search through SPINE_CONFIG_PATH directories
+    5. Search through SPINE_CONFIG_PATH directories with .yaml/.yml extension
+
+    Parameters
+    ----------
+    filename : str
+        Config filename or path to resolve
+    current_dir : str
+        Directory of the config file doing the including
+    search_paths : Optional[List[str]]
+        List of search paths (defaults to SPINE_CONFIG_PATH env var)
+
+    Returns
+    -------
+    str
+        Resolved absolute path
+
+    Raises
+    ------
+    ConfigIncludeError
+        If file cannot be found in any location
+    """
+    # If absolute path, check if it exists
+    if os.path.isabs(filename):
+        if os.path.exists(filename):
+            return filename
+        raise ConfigIncludeError(f"Absolute path not found: {filename}")
+
+    # Try relative to current directory
+    relative_path = os.path.join(current_dir, filename)
+    if os.path.exists(relative_path):
+        return os.path.abspath(relative_path)
+
+    # Try with .yaml/.yml extension relative to current directory
+    for ext in [".yaml", ".yml"]:
+        if not filename.endswith(ext):
+            relative_path_with_ext = relative_path + ext
+            if os.path.exists(relative_path_with_ext):
+                return os.path.abspath(relative_path_with_ext)
+
+    # Get search paths from environment variable if not provided
+    if search_paths is None:
+        env_paths = os.environ.get("SPINE_CONFIG_PATH", "")
+        search_paths = [p.strip() for p in env_paths.split(":") if p.strip()]
+
+    # Search through SPINE_CONFIG_PATH
+    for search_dir in search_paths:
+        search_path = os.path.join(search_dir, filename)
+        if os.path.exists(search_path):
+            return os.path.abspath(search_path)
+
+        # Try with extensions
+        for ext in [".yaml", ".yml"]:
+            if not filename.endswith(ext):
+                search_path_with_ext = search_path + ext
+                if os.path.exists(search_path_with_ext):
+                    return os.path.abspath(search_path_with_ext)
+
+    # File not found anywhere
+    search_locations = [f"Relative to: {current_dir}"]
+    if search_paths:
+        search_locations.append(f"SPINE_CONFIG_PATH: {':'.join(search_paths)}")
+
+    raise ConfigIncludeError(
+        f"Config file '{filename}' not found.\n"
+        f"Searched in:\n  - " + "\n  - ".join(search_locations)
+    )
+
+
 class ConfigLoader(yaml.SafeLoader):
     """YAML loader with !include tag support.
 
@@ -109,11 +188,10 @@ def include(self, node: yaml.Node) -> Any:
         Any
             Loaded configuration content
         """
-        filename = os.path.join(
-            self._root, self.construct_scalar(cast(yaml.ScalarNode, node))
-        )
+        filename = self.construct_scalar(cast(yaml.ScalarNode, node))
+        resolved_path = resolve_config_path(filename, self._root)
 
-        with open(filename, "r", encoding="utf-8") as f:
+        with open(resolved_path, "r", encoding="utf-8") as f:
             return yaml.load(f, Loader=ConfigLoader)
 
 
@@ -568,9 +646,8 @@ def _load_config_recursive(
 
     # Process includes
     for include_file in includes:
-        include_path = os.path.join(root_dir, include_file)
-        if not os.path.exists(include_path):
-            raise ConfigIncludeError(f"Included file not found: {include_path}")
+        # Resolve include path with SPINE_CONFIG_PATH support
+        include_path = resolve_config_path(include_file, root_dir)
 
         # Recursively load
         (

test/test_config.py

@@ -1287,3 +1287,139 @@ def test_override_creates_final_key_if_parent_exists(self, tmp_path):
         # new_key should be created because io.reader exists
         assert cfg["io"]["reader"]["new_key"] == "new_value"
         assert cfg["io"]["reader"]["batch_size"] == 4
+
+    def test_spine_config_path(self, tmp_path, monkeypatch):
+        """Test SPINE_CONFIG_PATH environment variable for include resolution."""
+        # Create a shared config directory
+        shared_dir = tmp_path / "shared_configs"
+        shared_dir.mkdir()
+
+        # Create a shared base config
+        shared_base = shared_dir / "shared_base.yaml"
+        shared_base.write_text(
+            """
+base:
+  world_size: 1
+  iterations: 1000
+"""
+        )
+
+        # Create a local config directory
+        local_dir = tmp_path / "local"
+        local_dir.mkdir()
+
+        # Create a local config that includes the shared base
+        local_config = local_dir / "config.yaml"
+        local_config.write_text(
+            """
+include: shared_base.yaml
+
+io:
+  reader:
+    batch_size: 32
+"""
+        )
+
+        # Set SPINE_CONFIG_PATH
+        monkeypatch.setenv("SPINE_CONFIG_PATH", str(shared_dir))
+
+        # Load the config - should find shared_base.yaml via SPINE_CONFIG_PATH
+        cfg = load_config(str(local_config))
+
+        assert cfg["base"]["world_size"] == 1
+        assert cfg["base"]["iterations"] == 1000
+        assert cfg["io"]["reader"]["batch_size"] == 32
+
+    def test_spine_config_path_multiple_dirs(self, tmp_path, monkeypatch):
+        """Test SPINE_CONFIG_PATH with multiple search directories."""
+        # Create multiple config directories
+        shared_dir1 = tmp_path / "shared1"
+        shared_dir1.mkdir()
+        shared_dir2 = tmp_path / "shared2"
+        shared_dir2.mkdir()
+
+        # Create configs in different directories
+        config1 = shared_dir1 / "config1.yaml"
+        config1.write_text("base:\n  value1: 100")
+
+        config2 = shared_dir2 / "config2.yaml"
+        config2.write_text("io:\n  value2: 200")
+
+        # Create local config
+        local_dir = tmp_path / "local"
+        local_dir.mkdir()
+        local_config = local_dir / "main.yaml"
+        local_config.write_text(
+            """
+include:
+  - config1.yaml
+  - config2.yaml
+"""
+        )
+
+        # Set SPINE_CONFIG_PATH with multiple paths
+        monkeypatch.setenv("SPINE_CONFIG_PATH", f"{shared_dir1}:{shared_dir2}")
+
+        cfg = load_config(str(local_config))
+
+        assert cfg["base"]["value1"] == 100
+        assert cfg["io"]["value2"] == 200
+
+    def test_spine_config_path_auto_extension(self, tmp_path, monkeypatch):
+        """Test automatic .yaml extension addition."""
+        shared_dir = tmp_path / "shared"
+        shared_dir.mkdir()
+
+        shared_base = shared_dir / "base.yaml"
+        shared_base.write_text("base:\n  value: 42")
+
+        local_dir = tmp_path / "local"
+        local_dir.mkdir()
+        local_config = local_dir / "config.yaml"
+        # Include without extension
+        local_config.write_text("include: base")
+
+        monkeypatch.setenv("SPINE_CONFIG_PATH", str(shared_dir))
+
+        cfg = load_config(str(local_config))
+        assert cfg["base"]["value"] == 42
+
+    def test_spine_config_path_relative_takes_precedence(self, tmp_path, monkeypatch):
+        """Test that relative paths take precedence over SPINE_CONFIG_PATH."""
+        # Create shared directory
+        shared_dir = tmp_path / "shared"
+        shared_dir.mkdir()
+        shared_config = shared_dir / "config.yaml"
+        shared_config.write_text("value: shared")
+
+        # Create local directory with same-named file
+        local_dir = tmp_path / "local"
+        local_dir.mkdir()
+        local_config = local_dir / "config.yaml"
+        local_config.write_text("value: local")
+
+        # Create main config that includes config.yaml
+        main_config = local_dir / "main.yaml"
+        main_config.write_text("include: config.yaml")
+
+        # Set SPINE_CONFIG_PATH to shared dir
+        monkeypatch.setenv("SPINE_CONFIG_PATH", str(shared_dir))
+
+        # Should load local version (relative path takes precedence)
+        cfg = load_config(str(main_config))
+        assert cfg["value"] == "local"
+
+    def test_spine_config_path_not_found(self, tmp_path, monkeypatch):
+        """Test error when config not found in SPINE_CONFIG_PATH."""
+        shared_dir = tmp_path / "shared"
+        shared_dir.mkdir()
+
+        local_dir = tmp_path / "local"
+        local_dir.mkdir()
+        local_config = local_dir / "main.yaml"
+        local_config.write_text("include: nonexistent.yaml")
+
+        monkeypatch.setenv("SPINE_CONFIG_PATH", str(shared_dir))
+
+        with pytest.raises(ConfigIncludeError, match="not found"):
+            load_config(str(local_config))