Packaging & Installation Ecosystem
Relevant source files
The following files were used as context for generating this wiki page:
The Packaging & Installation Ecosystem of NeuralDBG is designed to provide a zero-friction experience for developers and researchers. It utilizes standard Python packaging tools to ensure the core causal inference engine is easily deployable across different environments, including local development setups, Docker containers, and CI/CD pipelines.
The ecosystem is built around a "Hub & Spokes" architectural principle, where the core packaging logic (the Hub) remains stable, while various distribution methods (the Spokes)—such as PyPI, Docker images, and automated GitHub Actions—facilitate installation. This structure ensures that the system is resilient to dependency churn and easy to extend as the project grows.
Sources: copilot-instructions.md, README.md, infrastructure_planning/CODEBASE_GUIDE.md
Core Configuration and Metadata
The project uses pyproject.toml as the primary configuration file for build systems and project metadata. This file defines how the package is constructed and its primary dependencies. Additionally, the neuraldbg.egg-info directory contains metadata generated during the build process, such as the top-level module names.
| Component | Description |
|---|---|
pyproject.toml | The central configuration file for building the Python package. |
top_level.txt | Lists the top-level Python modules (e.g., neuraldbg). |
requires.txt | Defines the dependencies required for installation. |
Sources: pyproject.toml, neuraldbg.egg-info/top_level.txt, neuraldbg.egg-info/SOURCES.txt
Project Versioning
NeuralDBG adheres to a specific versioning scheme: SemVer-Author (e.g., v0.1.0-kuro). This allows for clear tracking of releases while identifying the primary author or orchestrator.
Sources: copilot-instructions.md, CHANGELOG.md
Installation Workflows
The ecosystem supports several installation methods depending on the user's role and environment.
User Installation
For standard users, installation is performed via the Python package manager:
pip install neuraldbg
Sources: README.md:53-55
Developer Installation
Contributors are required to install the package in "editable" mode to ensure changes are reflected immediately. This is part of a standardized onboarding checklist.
pip install -e .
Sources: copilot-instructions.md, infrastructure_planning/CODEBASE_GUIDE.md:104-107
Hermetic Environments (Docker)
To solve the "it works on my machine" problem, the ecosystem includes Docker-based installation. This involves a Dockerfile and docker-compose.yml tailored for PyTorch, allowing for a standardized environment across different development machines.
Sources: infrastructure_planning/milestone_0_tasks.md, infrastructure_planning/milestone_25_tasks.md
Automation and CI/CD Gates
The installation process is protected by "unbreakable digital bouncers" in the form of GitHub Actions. These CI/CD gates ensure that the package can be built and installed successfully on both Linux and Windows runners before any code is merged into the stable branch.
The following diagram illustrates the workflow from a developer push to the CI gate verification:
The diagram shows how local code pushes are intercepted by cloud-based CI gates to enforce test coverage and security standards before merging.
Sources: infrastructure_planning/milestone_0_tasks.md, infrastructure_planning/milestone_25_tasks.md
Onboarding and Stack Verification
A mandatory onboarding checklist ensures every team member has the required tools and environment configured before contributing.
| Step | Action | Required |
|---|---|---|
| Python | Install Python 3.10+ | Yes |
| Virtual Env | Create .venv | Yes |
| Dependencies | pip install -e . | Yes |
| Linear | Connect Linear account | Yes |
| Git | Configure branch naming | Yes |
Sources: copilot-instructions.md, infrastructure_planning/CODEBASE_GUIDE.md
The sequence of a new developer onboarding is as follows:
This sequence ensures that the local installation is verified by running the demo before any development work begins on a new branch.
Sources: copilot-instructions.md, infrastructure_planning/CODEBASE_GUIDE.md, infrastructure_planning/RULE_SYNC_PROCEDURE.md
Conclusion
The Packaging & Installation Ecosystem of NeuralDBG prioritizes reproducibility and reliability. By combining standard Python pyproject.toml configurations with Docker hermeticity and strict CI/CD gates, the project ensures that the causal inference engine can be deployed consistently across diverse hardware and software platforms.
Sources: infrastructure_planning/milestone_0_tasks.md, infrastructure_planning/milestone_25_tasks.md