fix: remote snakemake imports and align module with Modelblocks conventions

[bobbyxng]

Fixes Issue #9 @jnnr

Summary of changes in this pull request

• fix imports through Snakemake’s github() helper, resolving the reported ImportError: cannot import name 'load_region_configs' from 'scripts._schema'. Load module sources and regional configuration independently of the consuming workflow.
• export locked execution environments and align paths with Modeblocks conventions: intermediates under <resources>/automatic, final outputs under <results>, and configurable output pathvars.
• update the interface, configuration schema, and documentation, including import examples and a horizontal rule graph. Add regression coverage for remote imports and output rewiring.

Reviewer checklist

• There are no pip dependencies in the module's environment files (workflow/envs/).
• All rules use pathvars (e.g., <results>) in their inputs and outputs.
• The integration test-suite is successful, including:
  • pre-commit.ci tests pass.
  • tests pass for all relevant OS configurations (linux, osx, windows).
• Module documentation is up-to-date, including:
  • INTERFACE.yaml mentions all relevant pathvars and wildcards.
  • README.md describes how to use the module and has the necessary citations.

[bobbyxng]

I used module_powerplants as a reference for the module structure and environment setup, adapting these conventions to grid-builder’s workflow. Any tips and comments from our Modelblocks experts is very welcome @jnnr @brynpickering @irm-codebase

[Copilot]

Copilot review overview

🟡 Changes recommended

INTERFACE.yaml must document the retrieval pathvars and country wildcard exposed by the workflow.

Review effort: Lite
Findings: 1

Open (1)

• Declare retrieval pathvars and country wildcard in public API · New

What changed in this PR

Fixes remote Snakemake imports and aligns workflow paths, environments, configuration, and documentation with Modelblocks conventions.

Changes:

• Resolves remote scripts, schemas, helpers, and regional configurations.
• Rewires workflow outputs through configurable pathvars.
• Consolidates locked environments and adds regression coverage.
• Updates interface metadata and documentation.

File	Summary
workflow/​Snakefile	Remote source loading and pathvars
workflow/​scripts/​retrieve_osm_pbf.py	Retrieval imports and configuration
workflow/​scripts/​retrieve_osm_overpass.py	Overpass retrieval updates
workflow/​scripts/​clean.py	Cleaning workflow updates
workflow/​scripts/​build_network.py	Network build imports and paths
workflow/​scripts/​build_interactive_map.py	Interactive map updates
workflow/​scripts/​_schema.py	Schema handling
workflow/​scripts/​_helpers.py	Shared helper imports
workflow/​rules/​retrieve.smk	Retrieval rule rewiring
workflow/​rules/​plot.smk	Plot rule paths
workflow/​rules/​network.smk	Network rule paths and environment
workflow/​internal/​config.schema.yaml	Configuration schema
workflow/​envs/​retrieve.yaml	Retrieval environment
workflow/​envs/​network.yaml	Network environment
workflow/​envs/​module.yaml	Consolidated module environment
workflow/​envs/​module.win-64.pin.txt	Windows package pins
workflow/​envs/​module.osx-arm64.pin.txt	macOS package pins
workflow/​envs/​module.linux-64.pin.txt	Linux package pins
tests/​test_module_import.py	Remote import and rewiring tests
tests/​test_environments.py	Environment validation
tests/​test_config.py	Configuration tests
tests/​integration/​Snakefile	Integration pathvars
tests/​integration_test.py	Updated integration paths
scripts/​export_snakemake_env.py	Environment export utility
README.md	Usage and development documentation
pytest.ini	Python path configuration
pixi.toml	Module environment definitions
pixi.lock	Locked dependencies
mypy.ini	Module search path
INTERFACE.yaml	Interface metadata; retrieval pathvars and wildcard are missing
config/​regions/​index.yaml	Regional source manifest
config/​README.md	Configuration documentation
config/​config.yaml	Schema reference

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.