Context
The repo will have multiple Python projects needing to share code:
orcahello/
├── InferenceSystem/ # inference model + audio processing
│ └── src/
│ └── model/
│ └── audio_frontend.py ← other projects need this
├── ModelDevelopment/
│ └── dataset-toolkit/ # fine-tuning data pipeline
│ └── src/
│ └── build_dataset.py ← needs to import audio_frontend
In this example, dataset-toolkit needs to import the audio frontend from InferenceSystem (resampling, downmix, mel spectrogram) to ensure preprocessing parity between dataset creation and inference.
Problem
InferenceSystem uses src/ as a top-level Python package directory. It also doesn't have an __init__.py file, getting treated as a namespace package.
If dataset-toolkit depends on InferenceSystem as a uv path dependency, both src/ trees end up on sys.path and collide — Python can only resolve one src package. In theory working with namespace packages named as src everywhere can work around by merging both src/ trees, but this is fragile.
The root cause is that src is not a meaningfully named self-contained package.
Proposal
Rename InferenceSystem's package directory to give it a unique importable identity:
InferenceSystem/
src/ → orcahello_inference/
__init__.py
model/ model/
__init__.py __init__.py
inference.py inference.py
audio_frontend.py audio_frontend.py
types.py types.py
orcasound_hls/ orcasound_hls/
... ...
With hatch config:
[tool.hatch.build.targets.wheel]
packages = ["orcahello_inference"]
Desired import structure after rename
# In any project that depends on inference package (clear provenance):
from orcahello_inference.model import OrcaHelloSRKWDetectorV1
from orcahello_inference.model.audio_frontend import load_processed_waveform
from orcahello_inference.model.types import DetectorInferenceConfig
# Local code within another project (no collision):
from src.build_dataset import build_recording_dataset
No namespace package tricks needed — each package has a unique name.
Scope
- Rename
InferenceSystem/src/ → InferenceSystem/orcahello_inference/ and add __init__.py to avoid it being a namespace package
- Update all internal imports (
from src.model → from orcahello_inference.model)
- Update
scripts/, tests/, LiveInferenceOrchestrator.py, Dockerfile
- Update any downstream consumers
Context
The repo will have multiple Python projects needing to share code:
In this example,
dataset-toolkitneeds to import the audio frontend from InferenceSystem (resampling, downmix, mel spectrogram) to ensure preprocessing parity between dataset creation and inference.Problem
InferenceSystem uses
src/as a top-level Python package directory. It also doesn't have an__init__.pyfile, getting treated as a namespace package.If
dataset-toolkitdepends on InferenceSystem as a uv path dependency, bothsrc/trees end up onsys.pathand collide — Python can only resolve onesrcpackage. In theory working with namespace packages named assrceverywhere can work around by merging bothsrc/trees, but this is fragile.The root cause is that
srcis not a meaningfully named self-contained package.Proposal
Rename InferenceSystem's package directory to give it a unique importable identity:
With hatch config:
Desired import structure after rename
No namespace package tricks needed — each package has a unique name.
Scope
InferenceSystem/src/→InferenceSystem/orcahello_inference/and add__init__.pyto avoid it being a namespace packagefrom src.model→from orcahello_inference.model)scripts/,tests/,LiveInferenceOrchestrator.py, Dockerfile