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

For Python orchestration work:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'

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

Any change to TPE numerical arithmetic or RNG consumption must bump kTpeAlgorithmRevision in src/core/tpe_algorithm.hpp. Revalidate the numerical identity keyed serial goldens and checkpoint compatibility after such a change.

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.
Run the checks that touch the changed code and record the targeted commands in the pull request.
Add a test only when no existing test covers the target; each test must cover one specific target.
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 the checks that touch the changed code and record the targeted commands and results. The final CI workflows run the repository's normal build and test suite.

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 the [PineForge Source License 1.2](LICENSE) starting with v0.11.0. Releases up to and including v0.10.0 were released under Apache-2.0 and remain available under that license.