Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
91 lines (70 loc) · 4.29 KB

CONTRIBUTING.md

File metadata and controls

91 lines (70 loc) · 4.29 KB
Raw

Contributing to Penrose

Thanks for your interest. Penrose is an open research referee for quantitative performance claims — it evaluates whether a strategy's evidence holds up, with explicit multiple-testing and power accounting. It is not a trading system and does not generate or hold positions.

Project intent

Penrose is open-sourced research-first: the goal is a transparent, calibrated, reproducible standard for evaluating quantitative claims that others can adopt, audit, and extend. We welcome contributions that make the referee more rigorous or more broadly usable — and we are deliberately conservative about anything that weakens a control to make a result look better.

The two highest-value contribution surfaces:

  1. Data adapters — point-in-time, leakage-safe sources for new domains (equities, futures, FX, macro). One reference adapter ships; the contract is defined in src/penrose/data/contract.py.
  2. Strategy modules — reviewed, deterministic implementations of strategy classes the pipeline can route claims to.

Also welcome: additional calibration controls, robustness gates, documentation, and bug fixes.

Non-negotiables (these are the point of the project)

  • Never weaken a gate or a test to make a result pass. If a change breaks a calibration or evaluation invariant, the change is wrong, not the gate. The eval suite (python scripts/eval_suite.py) and the placebo (python scripts/calibration_placebo.py) must stay green.
  • Discovery and confirmation stay separated. Nothing on the discovery side may read reserved/confirmation data. PRs that cross this firewall will be declined.
  • Determinism. Reproducibility is a feature. Avoid nondeterministic ordering, unseeded randomness, or wall-clock dependence in evaluation paths.
  • No alpha claims. Penrose evaluates claims; it does not assert profitability. Keep language to verdicts (kill / underpowered / watch / research-supported) — never "alpha" or "profitable."

Getting started

git clone <repo>
cd penrose
pip install -e .
# optional in-process embeddings (vector retrieval; lexical fallback works without it):
pip install -e '.[embed]'

python scripts/eval_suite.py                          # must exit 0
python scripts/calibration_placebo.py                 # placebo: no no-edge signal certified
python scripts/worked_example_process_conditional.py  # the process-conditional verdict demo
python -m pytest -q

The default test command and make test are serial and require only the test extra. For an opt-in parallel local run, install pip install -e '.[dev]' and use make test-fast. File-lock and multiprocessing tests are kept in one serial xdist group. Use make test-profile (equivalent to a serial pytest --durations=25 run) when profiling the slowest tests.

No API key, network, or external service is required for the test suite, the calibration scripts, or the worked example. A language-model key is only needed for the optional ingestion/generation paths.

Local CI mirror

Run these commands before opening a pull request. They are intentionally exit-status based: the expected invariant/test total can grow as coverage is added and must not be hardcoded in contributor instructions.

make test
make eval
make calib-placebo
make calib-persistence
make calib-nulls
make calib-synth
make repo-hygiene
PYTHON=.venv/bin/python scripts/wheel_smoke.sh --require
.venv/bin/python scripts/build_site.py --output /tmp/penrose-site
.venv/bin/python -m penrose.protected_state verify
ruff check --output-format=github .       # reporting-only during W3
mypy                                      # reporting-only during W3; foundation modules only

The pull-request workflow runs keyless and does not receive PENROSE_LLM_API_KEY or any other model/API secret. Any future credential-using job must be gated to a trusted non-fork event or explicit workflow_dispatch.

Pull requests

  • Keep changes focused; explain why, not just what.
  • Add a deterministic regression test for any bug fix or new gate.
  • Keep the full gate green (exit-zero eval + placebo PASS + pytest exit 0).
  • Be explicit if a change touches verdict logic — those PRs get the most scrutiny.

License

By contributing, you agree your contributions are licensed under the repository's LICENSE.