fix: resolve file paths relative to scenario file location

Paths in scenario.yaml (population_spec, agents_file, network_file) are
now stored relative to the scenario file and resolved correctly when
loading from any working directory.

- Add resolve_relative_to() and make_relative_to() utilities
- Fix scenario command to store relative paths when saving
- Fix validate command to resolve paths relative to scenario file
- Add tests for path utilities

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: DeveshParagiri

entropy/cli/commands/scenario.py

@@ -49,6 +49,7 @@ def scenario_command(
     """
     from ...core.models import PopulationSpec
     from ...scenario import create_scenario
+    from ...utils import make_relative_to
 
     start_time = time.time()
     console.print()
@@ -238,6 +239,11 @@ def run_pipeline():
             console.print("[dim]Cancelled.[/dim]")
             raise typer.Exit(0)
 
+    # Convert paths to be relative to output file before saving
+    result_spec.meta.population_spec = make_relative_to(population, output_path)
+    result_spec.meta.agents_file = make_relative_to(agents, output_path)
+    result_spec.meta.network_file = make_relative_to(network, output_path)
+
     # Save to YAML
     result_spec.to_yaml(output_path)
 

entropy/cli/commands/validate.py

@@ -169,23 +169,25 @@ def _validate_scenario_spec(spec_file: Path, out: Output) -> int:
 
     # Show file references (human mode only)
     if not get_json_mode():
+        from ...utils import resolve_relative_to
+
         out.text("[bold]File References:[/bold]")
 
-        pop_path = Path(spec.meta.population_spec)
+        pop_path = resolve_relative_to(spec.meta.population_spec, spec_file)
         if pop_path.exists():
             out.text(f"  [green]✓[/green] Population: {spec.meta.population_spec}")
         else:
             out.text(
                 f"  [red]✗[/red] Population: {spec.meta.population_spec} (not found)"
             )
 
-        agents_path = Path(spec.meta.agents_file)
+        agents_path = resolve_relative_to(spec.meta.agents_file, spec_file)
         if agents_path.exists():
             out.text(f"  [green]✓[/green] Agents: {spec.meta.agents_file}")
         else:
             out.text(f"  [red]✗[/red] Agents: {spec.meta.agents_file} (not found)")
 
-        network_path = Path(spec.meta.network_file)
+        network_path = resolve_relative_to(spec.meta.network_file, spec_file)
         if network_path.exists():
             out.text(f"  [green]✓[/green] Network: {spec.meta.network_file}")
         else:

entropy/scenario/validator.py

@@ -525,18 +525,20 @@ def load_and_validate_scenario(
     agent_count = None
     network = None
 
-    pop_path = Path(spec.meta.population_spec)
+    from ..utils import resolve_relative_to
+
+    pop_path = resolve_relative_to(spec.meta.population_spec, scenario_path)
     if pop_path.exists():
         try:
             population_spec = PopulationSpec.from_yaml(pop_path)
         except Exception:
             pass  # Will be caught as validation error
 
-    agents_path = Path(spec.meta.agents_file)
+    agents_path = resolve_relative_to(spec.meta.agents_file, scenario_path)
     if agents_path.exists():
         agent_count = get_agent_count(agents_path)
 
-    network_path = Path(spec.meta.network_file)
+    network_path = resolve_relative_to(spec.meta.network_file, scenario_path)
     if network_path.exists():
         try:
             with open(network_path) as f:

entropy/utils/__init__.py

@@ -36,6 +36,10 @@
     ConditionError,
     SAFE_BUILTINS,
 )
+from .paths import (
+    resolve_relative_to,
+    make_relative_to,
+)
 
 __all__ = [
     # Graphs
@@ -62,4 +66,7 @@
     "FormulaError",
     "ConditionError",
     "SAFE_BUILTINS",
+    # Paths
+    "resolve_relative_to",
+    "make_relative_to",
 ]

entropy/utils/paths.py

@@ -0,0 +1,67 @@
+"""Path resolution utilities for Entropy.
+
+This module provides consistent path handling across all CLI commands,
+ensuring relative paths in YAML files are resolved correctly regardless
+of the current working directory.
+"""
+
+from pathlib import Path
+
+
+def resolve_relative_to(path: str | Path, base_file: Path) -> Path:
+    """
+    Resolve a path relative to a base file's directory.
+
+    If path is absolute, returns it unchanged.
+    If path is relative, resolves it against base_file's parent directory.
+
+    Args:
+        path: Path string or Path object to resolve
+        base_file: The file that contains the path reference (e.g., scenario.yaml)
+
+    Returns:
+        Resolved absolute Path
+
+    Example:
+        >>> resolve_relative_to("population.yaml", Path("/project/study/scenario.yaml"))
+        PosixPath('/project/study/population.yaml')
+
+        >>> resolve_relative_to("/abs/path/pop.yaml", Path("/project/scenario.yaml"))
+        PosixPath('/abs/path/pop.yaml')
+    """
+    path = Path(path)
+    if path.is_absolute():
+        return path
+    return (base_file.parent / path).resolve()
+
+
+def make_relative_to(path: str | Path, base_file: Path) -> str:
+    """
+    Convert a path to be relative to a base file's directory.
+
+    Used when storing file references in YAML files (e.g., scenario.yaml).
+    If the path cannot be made relative (different drives on Windows, etc.),
+    returns the absolute path as a string.
+
+    Args:
+        path: Path to convert (can be relative to cwd or absolute)
+        base_file: The file that will contain the reference (e.g., scenario.yaml)
+
+    Returns:
+        Relative path string if possible, otherwise absolute path string
+
+    Example:
+        >>> make_relative_to("/project/study/population.yaml", Path("/project/study/scenario.yaml"))
+        'population.yaml'
+
+        >>> make_relative_to("studies/netflix/pop.yaml", Path("studies/netflix/scenario.yaml"))
+        'pop.yaml'
+    """
+    path = Path(path).resolve()
+    base_dir = base_file.parent.resolve()
+
+    try:
+        return str(path.relative_to(base_dir))
+    except ValueError:
+        # Path is not under base_dir, return absolute
+        return str(path)

studies/netflix-password-sharing/scenario.yaml

@@ -2,9 +2,9 @@ meta:
   name: netflix_announces_enforcement_of
   description: 'Netflix announces enforcement of password-sharing rules: users must
     pay .99/month extra per shared member outside household or stop sharing'
-  population_spec: studies/netflix-password-sharing/population.yaml
-  agents_file: studies/netflix-password-sharing/agents.json
-  network_file: studies/netflix-password-sharing/network.json
+  population_spec: population.yaml
+  agents_file: agents.json
+  network_file: network.json
   created_at: '2026-02-02T15:05:10.271096'
 event:
   type: announcement

tests/test_paths.py

@@ -0,0 +1,118 @@
+"""Tests for path resolution utilities."""
+
+from pathlib import Path
+import tempfile
+import os
+
+from entropy.utils import resolve_relative_to, make_relative_to
+
+
+class TestResolveRelativeTo:
+    """Tests for resolve_relative_to function."""
+
+    def test_relative_path_resolved(self):
+        """Relative paths should be resolved against base file's directory."""
+        result = resolve_relative_to(
+            "population.yaml", Path("/project/study/scenario.yaml")
+        )
+        assert result == Path("/project/study/population.yaml")
+
+    def test_absolute_path_unchanged(self):
+        """Absolute paths should be returned unchanged."""
+        result = resolve_relative_to(
+            "/abs/path/pop.yaml", Path("/project/scenario.yaml")
+        )
+        assert result == Path("/abs/path/pop.yaml")
+
+    def test_nested_relative_path(self):
+        """Nested relative paths should resolve correctly."""
+        result = resolve_relative_to(
+            "data/agents.json", Path("/project/study/scenario.yaml")
+        )
+        assert result == Path("/project/study/data/agents.json")
+
+    def test_parent_relative_path(self):
+        """Parent-relative paths (../) should resolve correctly."""
+        result = resolve_relative_to(
+            "../common/pop.yaml", Path("/project/study/scenario.yaml")
+        )
+        assert result == Path("/project/common/pop.yaml")
+
+    def test_path_object_input(self):
+        """Should accept Path objects as input."""
+        result = resolve_relative_to(
+            Path("population.yaml"), Path("/project/study/scenario.yaml")
+        )
+        assert result == Path("/project/study/population.yaml")
+
+
+class TestMakeRelativeTo:
+    """Tests for make_relative_to function."""
+
+    def test_sibling_file_relative(self):
+        """Files in same directory should return just filename."""
+        result = make_relative_to(
+            "/project/study/population.yaml", Path("/project/study/scenario.yaml")
+        )
+        assert result == "population.yaml"
+
+    def test_nested_file_relative(self):
+        """Files in subdirectory should return relative path."""
+        result = make_relative_to(
+            "/project/study/data/agents.json", Path("/project/study/scenario.yaml")
+        )
+        assert result == "data/agents.json"
+
+    def test_unrelated_path_absolute(self):
+        """Unrelated paths should return absolute path."""
+        result = make_relative_to(
+            "/other/path/pop.yaml", Path("/project/study/scenario.yaml")
+        )
+        assert result == "/other/path/pop.yaml"
+
+    def test_relative_input_resolved(self):
+        """Relative input paths should be resolved against cwd first."""
+        # Use a temp directory to test this
+        with tempfile.TemporaryDirectory() as tmpdir:
+            # Create structure: tmpdir/study/scenario.yaml and tmpdir/study/pop.yaml
+            study_dir = Path(tmpdir) / "study"
+            study_dir.mkdir()
+            scenario = study_dir / "scenario.yaml"
+            pop = study_dir / "population.yaml"
+            scenario.touch()
+            pop.touch()
+
+            # Save original cwd
+            orig_cwd = os.getcwd()
+            try:
+                os.chdir(tmpdir)
+                # When cwd is tmpdir, "study/population.yaml" should become "population.yaml"
+                # relative to "study/scenario.yaml"
+                result = make_relative_to("study/population.yaml", Path("study/scenario.yaml"))
+                assert result == "population.yaml"
+            finally:
+                os.chdir(orig_cwd)
+
+
+class TestRoundTrip:
+    """Test that make_relative_to and resolve_relative_to are inverses."""
+
+    def test_roundtrip_same_directory(self):
+        """Roundtrip for files in same directory."""
+        base = Path("/project/study/scenario.yaml")
+        original = "/project/study/population.yaml"
+
+        relative = make_relative_to(original, base)
+        resolved = resolve_relative_to(relative, base)
+
+        assert str(resolved) == original
+
+    def test_roundtrip_nested(self):
+        """Roundtrip for nested files."""
+        base = Path("/project/study/scenario.yaml")
+        original = "/project/study/data/agents.json"
+
+        relative = make_relative_to(original, base)
+        resolved = resolve_relative_to(relative, base)
+
+        assert str(resolved) == original