Thank you for improving PineForge HPO. The project accepts focused bug fixes, tests, documentation, benchmark improvements, and proposals for new optimizer or execution capabilities.

Development setup

The native build consumes the public headers generated by the pinned pineforge-engine submodule. Initialize only the two direct integration submodules; the engine's nested corpus/assets are not needed:

git clone https://github.com/pineforge-4pass/pineforge-hpo.git
cd pineforge-hpo
git submodule update --init \
  external/pineforge-engine \
  external/pineforge-codegen-oss
 
cmake -S external/pineforge-engine -B external/pineforge-engine/build \
  -DCMAKE_BUILD_TYPE=Release \
  -DPINEFORGE_BUILD_TESTS=OFF \
  -DPINEFORGE_BUILD_TUTORIAL=OFF
 
cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DPINEFORGE_ENGINE_ROOT="$PWD/external/pineforge-engine" \
  -DPINEFORGE_HPO_BUILD_EXAMPLES=ON
cmake --build build -j4
ctest --test-dir build --output-on-failure

For Python orchestration work:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
python -m unittest discover -s tests/python -v

Tests of the optional PineScript bridge also need external/pineforge-codegen-oss importable as pineforge_codegen.

Build the API reference with Doxygen 1.9.8 or newer:

rm -rf build/docs
mkdir -p build/docs
PROJECT_NUMBER="$(tr -d '\n' < VERSION)" doxygen Doxyfile
test ! -s build/docs/doxygen-warnings.log
python3 docs/pages/validate_generated_site.py build/docs/html

Open build/docs/html/index.html to inspect the generated site. Benchmark setup and smoke commands are maintained separately in `benchmarks/README.md`.

Architecture boundaries

HPO is a consumer of strategy plugins and the public PineForge C ABI; it is not a BacktestEngine subclass.
Transpilation happens once during artifact initialization, outside the native trial loop.
Every trial receives a fresh strategy handle. Plugins and immutable OHLCV may be shared, but handles and reports may not.
Independent strategy reports are not a shared-account simulation. Shared cash, margin, and order sequencing require a separate execution contract.
New optimizer or persistence dependencies need an ADR under docs/adr/.

See docs/architecture.md before changing an integration boundary.

Changes and tests

Use C++17, four-space indentation, and the repository .clang-format file.
Seed stochastic tests explicitly; do not use wall-clock or system entropy.
Add a regression test for every fixed defect.
Keep benchmark results separate from correctness assertions. A benchmark change must state its hypothesis, problem definition, budgets, seeds, environment metadata, and comparison rule.
Do not commit build trees, virtual environments, downloaded datasets, or ad-hoc benchmark output. A small raw evidence set may be committed only under benchmarks/optuna/evidence/ when it is tied to a reviewed published result and includes its metadata sidecar plus verified hashes.

Before opening a pull request, run:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \
  -DPINEFORGE_ENGINE_ROOT="$PWD/external/pineforge-engine"
cmake --build build -j4
ctest --test-dir build --output-on-failure
python -m unittest discover -s tests/python -v
ruff check python tests/python benchmarks
ruff format --check python tests/python benchmarks

Pull requests should explain the user-visible behavior, compatibility impact, verification performed, and any benchmark claims. By contributing, you agree that your contribution is licensed under Apache-2.0.