Thanks for contributing to Aetherius.
This project is a per-target risk-report pipeline: SEC EDGAR ingestion, conservative entity mapping, deterministic scoring, and human-supervised PDF delivery — with historical detection-timing backtests as its credibility artifact.
Please keep contributions reproducible, evidence-based, and honest.
- Create a feature branch.
- Keep changes focused to one area (ingestion, mapping, scoring, delivery, backtests, docs).
- Run tests locally before opening a PR.
- In the PR description, include:
- what changed
- why it changed
- how it was validated
- Treat generated outputs as ephemeral:
simulations/artifacts/, runtime logs. - Do not commit secrets (
.env, API keys, tokens). - Keep root docs technical and evidence-based. Marketing claims must match implementation reality.
- Prefer small, testable functions.
- Preserve deterministic behavior in the scoring and mapping paths — an LLM must never gate what the pipeline flags.
- Match the surrounding code's style (comment density, naming, idiom).
- Use ASCII unless the file already uses Unicode.
Run the full test suite:
pytest aetherius/testsThe SVB-2023 backtest is a pinned integration test — any change that breaks it must be justified in the PR description.
For scoring, mapping, or ingestion changes, add or update a fixture-driven test alongside the change.
When adding a new backtest event under simulations/backtest/events/:
- Include
watchlist.json,ground_truth.json, andobservations.jsonl. - Observations must come from a real primary-source archive (GDELT, SEC EDGAR, Wayback, etc.) — not hand-authored summaries. The
provenancefield must state the archive and query used. - Include a non-affected control name in the watchlist to test for false positives.
- Do not tune the pipeline against a fixture, then claim the fixture as validation.
- Scope is focused and documented
- No secrets committed
- No generated artifacts committed
-
pytest aetherius/testspasses - SVB backtest still passes if scoring/mapping changed
- Docs updated when behavior changes
- Claims in README / landing page match implementation reality