[Task] Establish Reproducible Windows Packaging Pipeline via PyInstaller

[brightyorcerf]

Problem statement

MUIOGO currently lacks a standardized method for binary distribution. Requiring non-technical users (like policy analysts) to manually configure Python environments with complex scientific dependencies like pandas, numpy, and OSeMOSYS solvers creates a significant barrier to entry.

Proposed solution

Implement the functional packaging layer for MUIOGO by introducing a production-ready muiogo.spec. This builds upon the dependency separation work merged in #133, providing the actual logic required to utilize those build-time dependencies for binary generation.

Acceptance criteria

• muiogo.spec syntax-validated for cross-platform portability.
• Build-time dependencies documented in requirements-build-win.txt.
• Directory mapping for WebAPP/ assets successfully established in the bundle logic.

Dependencies and constraints

• Dependency: pyinstaller>=6.0.0
• Constraint: Requires a Windows environment for final .exe generation; however, the .spec logic is platform-agnostic.

Related work checked

"Checked #120, #231, and #110 (Testing/CI). Crucially reviewed #133, which handled the preparatory phase of splitting requirements. This issue targets the subsequent implementation phase.

Proposed track

None

[SeaCelo]

@brightyorcerf We currently have a setup script that installs in any platform. It would be nice to have a pypi package or something in the future. You can use this issue to explore how that would work, but we are not ready to open and PRs related to this yet.

[brightyorcerf]

Hi @SeaCelo,

Thank you for the guidance; I completely agree that a formal PyPI package is the more sustainable, lightweight distribution path for MUIOGO. I’ve completed an architectural audit to map the transition to a PEP 517/518 compliant structure. This audit confirms that the "Stability" track you've prioritized is the critical path for any future distribution:

• Pathlib as the Bedrock (refactor(logic): standardize OS-agnostic path handling via pathlib #286): My audit confirms that completing the pathlib refactor (refactor(logic): standardize OS-agnostic path handling via pathlib #286) is a high priority specifically to unblock [Task] Port the DataFile model/log diagnostics from MUIO v5.5 #391. Standardizing OS-agnostic path handling ensures that when we pull the v5.5 backend changes (specifically the new ModelFile and readLogFile helpers) they land on a stable runtime layer that won't trigger path-resolution errors on Windows or macOS

• Resource Discovery & Entry Points: To achieve location-independence, I’ve identified the need to move toward importlib.resources for the WebAPP/ folder and define a formal main() entry point in app.py. This ensures the app remains stable regardless of where it is installed.

• Vendored Asset Mapping: I’ve mapped the JS/CSS dependencies in WebAPP/References that require explicit package-data inclusion to preserve the interactive Plotly dashboards in a distributed environment.

I will focus my immediate efforts on the Stability and Cross-Platform issues you've opened (#388–#393), specifically ensuring the Pathlib foundation is ready for the v5.5 pull. Does this focus on unblocking the v5.5 sync align with your current timeline?

[SeaCelo]

@brightyorcerf

Thanks for the exploration here. I want to clarify repo priority before more work continues on this.

At the moment, Windows packaging via PyInstaller is not part of the active MUIOGO priority stack. Our current focus is the upstream MUIO v5.5 sync and the related stability work in #388 through #393, especially #389 to #392.

I am already working locally on landing the v5.5 update stack, so I do not want packaging implementation work moving in parallel right now unless and until we explicitly decide that distribution/packaging has become a current repo priority.

A few scope clarifications:

• this issue is a downstream packaging/distribution topic, not part of the active v5.5 sync track
• it does not currently unblock [Task] Port the DataFile model/log diagnostics from MUIO v5.5 #391 or the rest of the v5.5 work
• refactor(deps): separate runtime and Windows-only build dependencies #133 was useful groundwork for dependency separation, but that does not make packaging the current next step
• broader ideas like importlib.resources, entry-point restructuring, or packaging architecture should be treated as future exploration, not as part of the current stability/v5.5 execution path

So the direction here is:

• keep this issue as future exploration
• pause further implementation/PR work on it for now
• revisit it later once the current stability and v5.5 priorities are landed and we are ready to make packaging a deliberate repo priority

When we do revisit this, we should first decide which problem we are solving:

• Windows binary/installer for non-technical users
• PyPI/package distribution for technical users
• or both

Those are related, but they are not the same delivery path.
I'll keep this issue open for future tracking and to pick it up in the future.

[brightyorcerf]

@SeaCelo

Thanks for the clarity on the roadmap. I'll shift my focus to the Stability track and see in what way I can contribute to align with this vision!