# Source Layout

This directory now uses `src` as the single Python import root.

## Packages

- `optionMiner/`: Stage 1 search pipeline and Miner-specific logic.
- `optionComposer/`: Stage 2 composition pipeline and Composer-specific logic.
- `optionShared/`: code shared by both stages. Only modules with identical behavior should live here.

## Import Rules

- Run code with `PYTHONPATH=src`.
- Prefer module execution:
  - `python -m optionMiner.main`
  - `python -m optionComposer.main`
- Shared modules should be imported from `optionShared`, for example:
  - `from optionShared.implementation import code_manipulation`
  - `from optionShared import bin_packing_utils`
- Stage-specific modules should stay package-qualified:
  - `from optionMiner.implementation import evaluator`
  - `from optionComposer.implementation import option_miner_bridge`

## Deduplication Policy

- If a file is byte-for-byte identical in `optionMiner` and `optionComposer`, keep only one copy in `optionShared`.
- If two files are only similar, keep them separate unless the common logic can be extracted without hiding real behavioral differences.
- Avoid reintroducing directory-local imports such as `from implementation import ...` or script execution patterns that require `cd src/optionMiner` or `cd src/optionComposer`.

## Notes

- Some legacy utility scripts under `optionShared` used to execute file or network side effects at import time. Shared modules should remain import-safe and only perform work inside functions or `if __name__ == "__main__":`.
- The VM scheduling evaluator entrypoints are executed as modules, not by referencing deleted duplicate files directly.
