Agent guide

Use this path to find evidence and run a bounded task. For a guided explanation of the first research result, follow the human quickstart. Both paths use the same APIs and checks; this page is an index, not a second API specification.

For programmatic discovery, read the generated plain-text index. It lists these same guides and public Python references, with page status and the source revision. It is rebuilt with the site, rather than maintained as a second list of APIs.

Start with the task

Task	Read first	Check against
Call an API from Python	Python API, then its module guide	Exact import, signature, return shape and documented limitations
Change the Rust core	Rust workflow and rustdoc	The implementation and its independent-reference tests
Run or reproduce a research experiment	Research workflow and runbooks	Notebook tier, dataset hash, seed, trial count, costs and out-of-sample evaluation
Select data available at a decision cutoff	Point-in-time data workflow	Observation versus availability time, revision selection and policy identity; synthetic checks do not verify a provider’s history
Build or repartition bars	Bar contract examples and reset policy	Retained trades, closing-row membership, overshoot, partial tails and session boundaries; equal output counts do not establish equivalent bars
Load or adapt market data	Data and adapters	Timestamp units, row order, missing values and provenance; a converted frame is not a quality certificate
Connect market-data rows to named allocations	Multi-asset allocation walkthrough	Common observation times, matrix axes, weight names and fitting boundary; calculated weights are not a realized backtest
Select parameters and assess a final holdout	Model-selection walkthrough, then cross-validation	Development-only search, fold-local preprocessing, final refit and an untouched assessment span
Interpret supplied evaluation results	Evaluation	Return conventions, label spans and the complete inventory of tried configurations
Resume or audit saved work	Journey readback and grid artifacts	Saved inputs/configuration, exact output paths and artifact consistency; a leaderboard is not a trial registry
Diagnose a failed command	Troubleshooting	Exact command, interpreter/import paths and the first failing gate
Edit documentation	Local build	Source generators, example checks, links and page status

Working in a checkout? Read AI-DLC.md, CONTRIBUTING.md and any instructions applying to the files you change before editing. The repository skills cover experiment runs, notebook execution, artifact auditing, feature discovery, parity checks and promotion gates. Choose the skill matching the task rather than running every workflow. Read skill files in the selected checkout and check their command descriptions against that checkout’s scripts.

Match a skill to its evidence

Repository skill	What its entry point establishes	Read alongside it
flywheel-runner	Synthetic configured runs and artifacts; no forecasting model is fitted by the CLI	Artifact readback
notebook-executor	The current executor uses a real Jupyter kernel and saves rich outputs; it is not a plain Python cell loop	Execution and comparison scope
artifact-auditor	Checks a selected run directory for required files, core columns and grid membership; does not recompute numerical results or prove provenance	Catalog artifact checks
parity-check	Scaffold tests compare selected outputs through shared implementation paths, not an independent numerical reference	Validation layers
feature-discovery	Feature screening and diagnostic calls; selection must stay inside training boundaries	Feature diagnostics
promotion-gate	A summary of configured threshold flags, not proof of out-of-sample validity or publication authority	Research assumptions

These are capability notes, not replacements for skill instructions. Select the exact single-run or grid-run directory printed by the runner for the artifact audit; its structural pass is only one part of reviewing data lineage and research validity.

Resolve the source of truth

The website describes the published documentation revision. When changing code, use files from your checkout’s commit, not a signature copied from a different release. Start by recording git rev-parse HEAD and git status --short; preserve unrelated changes.

Question	Canonical repository source
Which Python names can I import?	python/openquant/__init__.py, public Python modules and generated _core/*.pyi stubs
What does a binding accept and return?	crates/pyopenquant/src/ plus the built extension’s signatures/docstrings
What is the Rust behavior?	crates/openquant/src/ and crates/openquant/tests/
What versions and commands apply?	rust-toolchain.toml, pyproject.toml, lockfiles, justfile and .github/workflows/ci.yml
Where do research results come from?	Executed notebooks, dataset hashes and experiment manifests, not a prose summary
Which files generate the site?	The mapping below and docs-site/package.json

The distribution name is pyopenquant; the Python import is openquant. The module index distinguishes Rust, compiled bindings and Python wrappers. Use the supported wrapper when one exists. For example, Python purged CV is openquant.cross_validation, not a guessed Rust-to-Python name.

Generated documentation

Edit the source, then regenerate. Do not patch generated outputs alone.

Output	Source / generator
Python type stubs	Rust bindings → scripts/generate_python_stubs.py
API inventory	Rust and Python source → scripts/generate_api_inventory.py
Python API reference	Built extension, generated stubs and public Python source → scripts/generate_python_api_reference.py
Research gallery, performance and changelog pages	Notebooks, benchmarks, CHANGELOG.md → scripts/docs/generate_site_pages.py --write
Coverage dashboard	Current source and documentation tree → scripts/docs/check_coverage.py --write

Authored runbooks and generated gallery summaries can describe the same notebook. When a result or interpretation changes, update its canonical notebook and check both destinations; regenerating the gallery does not rewrite an authored runbook.

See Contributing for the regeneration order. Rebuild the extension after Rust changes before checking Python behavior: an older installed extension can make a test pass against the wrong code.

The Python reference generator imports the package from its interpreter. Its compiled signatures are checked against the stubs; its wrapper signatures come from the imported Python source. Confirm both openquant.__file__ and openquant._core.__file__ point to the intended checkout/build before regenerating or validating examples. Matching the package version alone is insufficient: different source revisions may share that version.

Select the environment before running

Choose whether you are checking a source checkout or a packaged wheel. The bindings setup separates locked dependency installation from the explicit native build; its wheel check uses a separate environment and isolated imports. Do not use a checkout import as evidence that a wheel contains the same files.

For an existing environment, record sys.executable, openquant.__file__ and openquant._core.__file__ with the selected interpreter. Use the documented --no-sync diagnostic commands to inspect it without triggering another project synchronization. Restart a process after rebuilding its loaded extension. A notebook launches the named python3 kernel, so verify those paths inside the kernel as well.

Before rerunning research, identify the selected data source, registry and output paths. Temporary notebook output is not a sandbox for cache or registry writes. The journey script refuses to overwrite its report; the experiment runner also rejects an existing configuration-derived output directory or a symlink at that target. Follow the linked artifact instructions and use new output locations when preserving a baseline.

Run and verify

Follow the local setup rather than installing a package with a similar name. Start with the smallest relevant check, then run the required aggregate gates for the change.

• Rust: format, clippy, the fast suite and doctests. Run the explicit slow SADF test when changing structural breaks. Benchmark hot-path changes.
• Python: rebuild the extension, run pytest python/tests -q, then the lint, type and stub checks from CONTRIBUTING.md.
• Docs: bun run check:docs from docs-site/. This includes rustdoc staging, so Rust is required even for a full documentation check. The local build guide separates the lightweight preview from the full gate.
• Notebooks: execute the affected notebooks, verify committed outputs and run the notebook contract lint. Regenerate the gallery if results change.

Record the exact command, revision and outcome. Separate passed, failed and not run; a missing compiler or extension is a blocker, not a successful check. A site build alone does not prove the Python examples execute or numerical results match an independent reference.

Keep example coverage precise. check:examples compiles Rust fences on module pages and the complete Rust core workflow without running them; it does not scan every Rust fence across the site. check:rust-output separately runs crates/openquant/examples/docs_etf_trick.rs and compares its complete stdout with both displayed output blocks on the ETF page. check:module-figures runs the independent figure-reference tests and detects SVG drift. Edit scripts/docs/generate_rust_module_figures.py, then regenerate with --write; do not hand-edit its SVGs. These diagrams explain mechanics, not observed trading performance or evidence that all Rust examples executed. check:python-examples scans the Markdown content tree and executes each runnable Python fence in a separate interpreter. For runnable fences, a following text fence is also compared with captured stdout unless marked doc-output=skip; rerunning code alone does not verify its printed-output example. Fences marked doc-check=skip receive a syntax check only. Neither gate executes code embedded in API docstrings or notebooks. Check those through their own tests and notebook workflow, and report any walkthrough that falls outside the gates as unverified until checked directly.

Set DOC_PYTHON to an absolute executable path for reproducible handoffs. An explicit selection fails closed on a missing interpreter or failed import; unset/empty values still enable environment discovery. The gate may load an installed package when the checkout has no local extension. Its success alone therefore does not establish that the checkout’s Python implementation ran. Rebuild locally and verify import locations when using the result as evidence for a source change.

When handing work to another agent, preserve the base revision and uncommitted changes, interpreter/import locations, configuration and dataset identity, registry/output paths, and exact checks with their outcomes. A commit alone does not identify local edits or the loaded binary. Include the saved artifacts and unresolved failures so the next agent can read back evidence before rerunning or overwriting it. Distinguish an API tour from a research runbook using the notebook contract; successful execution of a tour is not experimental validation.

Before changing a bar pipeline

Use the bar-construction handoff as the task’s acceptance checklist. The module page contains independent literal expectations for aggregation, overshoot, partial tails, equal-timestamp cleaning and chunk boundaries, plus run/imbalance direction traces. Its runnable Python fences and displayed output are covered by check:python-examples.

1. Identify whether the input rows are trades or already aggregated OHLCV bars. The frame wrapper aggregates closes, not input highs and lows.
2. Compare raw and retained rows before explaining a missing bar. The frame cleaner deduplicates (symbol, ts); switching to _core.bars preserves duplicates but also transfers sorting and input validation to the caller.
3. Keep a continuous symbol history together, or record the intended reset rule. A batch-size optimization that splits a symbol can change behavior. Verify equivalence against one continuous pass, including any state carried between batches. Equal time-bar counts can conceal different membership, timestamps and OHLC.
4. Preserve the policy’s information boundary. A threshold estimated from completed past sessions differs from one fitted to the full future assessment session. Record the effective time and estimation window alongside the threshold.
5. Verify complete bar records against a small independently calculated case before comparing downstream labels or scores. Rebuild the extension if its Rust behavior changed; the gate’s interpreter discovery is not proof of build identity.
6. For run/imbalance work, trace the stopping statistic separately from the output totals. Include a flat prefix, a signed flat trade, a reversal, a completed-bar reset and an unfinished tail. The first trade of each bar is unsigned but is still aggregated. A run counts consecutive equal signs; an imbalance sums signed weights. The weighted example shows why reported volume cannot identify the closing threshold.

If changing the cross-bar direction rule, treat it as a sampling-policy change: preserve a before/after membership example, update the Rust and binding contracts and their generated references, and rerun downstream results affected by the new bar boundaries. Describing today’s reset rule does not settle the choice tracked in #279.

These checks establish the selected boundary behavior. They do not establish state-preserving streaming, exchange-calendar handling, provider trade completeness, independent returns, or profitable execution.

Preserve research safeguards

• Use synthetic data for the documented smoke paths. A synthetic example is not evidence of a tradable strategy.
• Keep label end times, purging and embargo explicit. Do not disable a leakage guard merely to make an example pass.
• Define trial identity before selecting a winner. The evaluation registry keys entries by configuration JSON: another data window or seed must be represented explicitly when it defines a different trial. Re-recording a key replaces its entry; output-directory counts and leaderboard rows are not automatically the registry’s count. Report the trial inventory, costs and out-of-sample results together. Follow the shared-registry guidance before reading another writer’s results; reloading does not make concurrent writes safe.
• Keep reference fixtures independent of the implementation being tested. A value produced by the function under test cannot validate that function.
• Do not raise an AI-authored page to reviewed or validated. Those statuses require human review. Keep skipped examples visible and explain why they cannot run.

The full policy and its limits are in Governance. Return to the human quickstart when you need the rationale behind an output, or the module index for a different API.

Ownership

Repository maintainers own this navigation guide. Its source links point to existing behavior and contribution rules; it introduces no new release, research-promotion or publication authority.