fa-quant 1.2.1__tar.gz → 1.3.0__tar.gz

{fa_quant-1.2.1 → fa_quant-1.3.0}/.gitignore

@@ -223,3 +223,4 @@ agents/equity/output/.runs/
 
 # Quant research downloads (never commit market data).
 .quant-cache/
+_site/

{fa_quant-1.2.1 → fa_quant-1.3.0}/CHANGELOG.md

@@ -5,6 +5,65 @@ and [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-10-28
+
+### Fixed
+
+- Research CLI commands honor `--provider yahoo` when `--csv-dir` is also set.
+- Non-object cache metadata raises a data error instead of an uncaught attribute error.
+
+### Added
+
+- A documentation site at <https://bichengwang.github.io/financial-agent/>, built
+  with MkDocs Material and deployed from `main` by the Pages workflow: on push,
+  and within 30 minutes of an auto-merge, whose `GITHUB_TOKEN` push starts no
+  workflows. It serves the README, `docs/` (quant guides, releasing, equity research
+  reports), the quant evidence reports and this changelog. Repository links that
+  aren't site pages open on GitHub. Pull requests that touch these files run a
+  strict build. Preview locally with
+  `uv run --only-group docs mkdocs serve`.
+- Two agent skills for the quant platform, discoverable through `.agents/skills/`:
+  `quant-strategy-research` (backtest, validate and certify a strategy, read the
+  eight promotion checks, write dated evidence) and `quant-paper-operations`
+  (dry-run and scheduled paper sessions, status and live readiness, and the
+  kill/unkill incident runbook). Neither can enable live trading.
+- Contributor and security docs: `CONTRIBUTING.md` (setup, checks, quant and
+  pull request rules), `SECURITY.md` (private vulnerability reporting, now enabled),
+  `CODE_OF_CONDUCT.md`, issue forms for bugs and features, and a pull request
+  template. The README shows CI, PyPI, Python, docs and license badges.
+- `[promotion] disclosed_trials` lists every variant tried when the certified
+  grid is narrower, e.g. one frozen identity. DSR then deflates by all of them:
+  their count and the variance of their full-period Sharpes on the certified
+  data. The certificate records `n_trials` and `trial_sharpe_variance` in its
+  diagnostics; certificates without a disclosure are unchanged. The disclosure
+  must list each grid variant once. `evaluate_promotion` takes it as the
+  keyword `disclosed_trials`.
+
+### Changed
+
+- The `Documentation` project URL and the README link to the site.
+- The Alpaca and IBKR example configs freeze the certified identity
+  (`target_vol=0.12, max_weight=0.25`): it is the configured strategy and the
+  only grid variant, with the four searched variants disclosed. A
+  re-certification can no longer switch parameters and restart paper evidence.
+  Pass the four-variant `--grid` to rerun the original search.
+- The README opens with the current paper-to-live status, installs from PyPI,
+  compares the four-variant and frozen-identity gate results, lists the live
+  gate's conditions and documents the scheduler wrapper.
+- Saved notebooks shrank from 10.9 MB to 3.1 MB without re-execution: training
+  logs keep their first and last 40 lines, very long printed lines are clipped,
+  and plots are 256-colour PNGs. Each cut is marked in the output.
+- GitHub language statistics exclude `.ipynb` files (`linguist-documentation`),
+  so the repository reports as Python rather than Jupyter Notebook.
+- The notebooks README lists each notebook and how to run it.
+
+### Removed
+
+- Six research notebooks: the three AI4Finance FinRL tutorial copies in
+  `archive/`, the upstream `Crypto_Binance_Historical_Data` tutorial, and
+  `multistock_variant_2` and `this_works_1_18`, which largely duplicate
+  `multistock_docker`. They remain in git history.
+
 ## [1.2.1] - 2026-10-20
 
 ### Added
@@ -140,7 +199,8 @@ and [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   PBO and degradation slope remain not applicable; multi-variant calculations
   and every promotion threshold are unchanged.
 
-[Unreleased]: https://github.com/BichengWang/financial-agent/compare/v1.2.1...HEAD
+[Unreleased]: https://github.com/BichengWang/financial-agent/compare/v1.3.0...HEAD
+[1.3.0]: https://github.com/BichengWang/financial-agent/compare/v1.2.1...v1.3.0
 [1.2.1]: https://github.com/BichengWang/financial-agent/compare/v1.2.0...v1.2.1
 [1.2.0]: https://github.com/BichengWang/financial-agent/compare/v1.1.1...v1.2.0
 [1.1.1]: https://github.com/BichengWang/financial-agent/compare/v1.1.0...v1.1.1

fa_quant-1.3.0/PKG-INFO

@@ -0,0 +1,283 @@
+Metadata-Version: 2.5
+Name: fa-quant
+Version: 1.3.0
+Import-Name: financial_agent
+Summary: Risk-managed systematic ETF trading, statistical validation, and financial research
+Project-URL: Homepage, https://github.com/BichengWang/financial-agent
+Project-URL: Repository, https://github.com/BichengWang/financial-agent
+Project-URL: Documentation, https://bichengwang.github.io/financial-agent/
+Project-URL: Issues, https://github.com/BichengWang/financial-agent/issues
+Project-URL: Changelog, https://github.com/BichengWang/financial-agent/blob/main/CHANGELOG.md
+Author-email: "Bicheng (Kenneth)" <31808103+BichengWang@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: backtesting,portfolio,reinforcement-learning,risk-management,systematic-trading
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.12
+Requires-Dist: gymnasium
+Requires-Dist: numpy<2.0,>=1.24.0
+Requires-Dist: pandas<3,>=2.0
+Requires-Dist: requests<3,>=2.32
+Requires-Dist: yfinance
+Provides-Extra: all
+Requires-Dist: beautifulsoup4; extra == 'all'
+Requires-Dist: ipython; extra == 'all'
+Requires-Dist: keras-nightly; extra == 'all'
+Requires-Dist: matplotlib; extra == 'all'
+Requires-Dist: notebook; extra == 'all'
+Requires-Dist: pyfolio-reloaded; extra == 'all'
+Requires-Dist: scikit-learn; extra == 'all'
+Requires-Dist: seaborn; extra == 'all'
+Requires-Dist: stable-baselines3; extra == 'all'
+Requires-Dist: stockstats; extra == 'all'
+Requires-Dist: tensorflow; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: black>=22.0.0; extra == 'dev'
+Requires-Dist: flake8>=6.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest-custom-exit-code; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Provides-Extra: dl
+Requires-Dist: ipython; extra == 'dl'
+Requires-Dist: keras-nightly; extra == 'dl'
+Requires-Dist: matplotlib; extra == 'dl'
+Requires-Dist: scikit-learn; extra == 'dl'
+Requires-Dist: seaborn; extra == 'dl'
+Requires-Dist: tensorflow; extra == 'dl'
+Provides-Extra: notebooks
+Requires-Dist: ipython; extra == 'notebooks'
+Requires-Dist: matplotlib; extra == 'notebooks'
+Requires-Dist: notebook; extra == 'notebooks'
+Requires-Dist: seaborn; extra == 'notebooks'
+Provides-Extra: research
+Requires-Dist: openpyxl<4,>=3.1; extra == 'research'
+Provides-Extra: rl
+Requires-Dist: beautifulsoup4; extra == 'rl'
+Requires-Dist: matplotlib; extra == 'rl'
+Requires-Dist: pyfolio-reloaded; extra == 'rl'
+Requires-Dist: scikit-learn; extra == 'rl'
+Requires-Dist: stable-baselines3; extra == 'rl'
+Requires-Dist: stockstats; extra == 'rl'
+Requires-Dist: tensorflow; extra == 'rl'
+Description-Content-Type: text/markdown
+
+# financial-agent
+
+[![Python quality](https://github.com/BichengWang/financial-agent/actions/workflows/python-quality.yml/badge.svg?branch=main)](https://github.com/BichengWang/financial-agent/actions/workflows/python-quality.yml)
+[![PyPI](https://img.shields.io/pypi/v/fa-quant)](https://pypi.org/project/fa-quant/)
+[![Python 3.12](https://img.shields.io/badge/python-3.12-blue)](https://www.python.org/)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://bichengwang.github.io/financial-agent/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/BichengWang/financial-agent/blob/v1.3.0/LICENSE)
+
+A Python platform for systematic ETF trading that has to earn its way to capital:
+cost-aware backtests, a statistical promotion gate, journaled paper trading and
+explicitly gated Alpaca and IBKR execution. It also holds an equity-research
+harness and separate RL/deep-learning research stacks. The platform is **beta**:
+live performance is unproven, and neither a historical pass nor paper results
+guarantee profit.
+
+**Docs:** <https://bichengwang.github.io/financial-agent/> has the quant guides,
+evidence reports, equity research and changelog.
+
+## Status (2026-10-28)
+
+| Stage | State |
+|---|---|
+| Research gate | `trend_vol_target` passes all eight checks with its frozen identity `target_vol=0.12, max_weight=0.25` (data through 2026-10-27, DSR 0.994) |
+| Paper evidence | Alpaca paper sessions scheduled weekdays before the open: first session 2026-10-29, first orders 2026-11-02; 0 of 20 clean sessions |
+| Live | Not authorized. Earliest decision 2026-11-25, if no paper session halts |
+
+The [paper-to-live plan](https://github.com/BichengWang/financial-agent/blob/v1.3.0/plan/2026-10-18-quant-paper-to-live.md) tracks the
+remaining steps and decisions.
+
+## Quickstart (offline, five minutes)
+
+```sh
+pip install fa-quant
+fa-quant demo --sessions 25 --state-dir /tmp/fa-quant-demo
+```
+
+Or from a clone, with [uv](https://docs.astral.sh/uv/getting-started/installation/)
+(Python 3.12 is pinned by `.python-version`):
+
+```sh
+uv sync --locked
+uv run fa-quant demo
+uv run fa-quant --help
+```
+
+The demo runs backtest, validation, certification, local paper sessions and
+status on seeded synthetic data with a planted trend, without network access.
+Its numbers show the software working, not market performance.
+
+The PyPI distribution is `fa-quant`; it installs the `fa-quant` command and the
+`financial_agent` import package. The unrelated `financial-agent` PyPI project is
+not this one. Python 3.12 is tested; on 3.13+ the NumPy `<2` pin builds NumPy
+from source. Examples, docs and evidence live in this repository. Optional `rl`,
+`dl`, `notebooks` and `research` extras add the heavier research stacks;
+`uv sync --locked --all-extras` installs everything.
+
+## Real-data research
+
+The example universe is SPY, QQQ, IWM, EFA, EEM, TLT, IEF, LQD, GLD, DBC and VNQ
+with weekly next-open fills, whole shares, a 2% cash buffer and 2 bps half-spread
+plus 3 bps slippage per side. Downloads are cached under gitignored `var/`. Use
+the latest completed session as the inclusive end:
+
+```sh
+uv run fa-quant backtest --config examples/quant/paper.toml --end 2026-10-27 --json
+uv run fa-quant validate --config examples/quant/paper.toml --end 2026-10-27 --json
+uv run fa-quant certify --config examples/quant/paper.toml --end 2026-10-27 \
+  --output var/quant-paper/certificate.json
+```
+
+`validate` and `certify` exit 2 when any check fails; a failed certificate can be
+saved but never authorizes trading. With `--config`, all settings come from the
+TOML. See [strategy research](https://github.com/BichengWang/financial-agent/blob/v1.3.0/docs/quant/strategy-research.md) for grids,
+disclosed trials and how to read each statistic.
+
+### Results
+
+The [committed evidence](https://github.com/BichengWang/financial-agent/blob/v1.3.0/reports/quant/2026-10-default-strategy-evidence.md)
+covers 2006-02-06 through 2026-10-12. Full-period backtests at default
+parameters:
+
+| Strategy | CAGR | Net Sharpe | Max drawdown | Turnover/year |
+|---|---:|---:|---:|---:|
+| Trend vol target | 5.625% | 0.740 | 16.533% | 14.375× |
+| Dual momentum | 11.100% | 0.754 | 26.397% | 10.550× |
+| SPY buy-and-hold | 11.122% | 0.652 | 54.299% | 0.048× |
+| 60/40 SPY/IEF | 8.212% | 0.785 | 31.979% | 0.206× |
+
+The trend strategy's promotion gate (walk-forward out-of-sample, 3,528 sessions):
+
+| Protocol | Data | OOS Sharpe | DSR | OOS max drawdown | PBO | Verdict |
+|---|---|---:|---:|---:|---:|---|
+| Four-variant search | 2006-02-06 to 2026-10-12 | 0.729 | 0.996 | 17.1% | 0.650 | Pass; selects 0.12 / 0.25 |
+| Frozen 0.12 / 0.25, four trials disclosed | 2006-03-01 to 2026-10-27 | 0.704 | 0.994 | 13.7% | n/a | Pass |
+
+PBO 0.650 means picking the in-sample winner added no reliable value, and the
+choice switched 6 times in 13 folds. So the selected identity is now frozen:
+re-certification can no longer switch parameters and restart the paper clock.
+DSR still deflates by all four variants tried. The frozen row's walk-forward
+returns aren't out-of-sample for the choice of identity, which used the same
+history; the freeze stabilizes the identity, it doesn't strengthen the
+statistical case.
+
+Dual momentum and 60/40 also pass all eight checks as single pre-registered
+variants; SPY fails the 25% OOS drawdown limit. Statistical passes don't override
+execution limits: dual momentum's three 33.3% slots and the concentrated
+benchmarks exceed the 30% per-name cap. The equity `research_forecast` signal
+[fails its real-ledger gate](https://github.com/BichengWang/financial-agent/blob/v1.3.0/reports/quant/research-forecast-validation.md) for
+lack of history. No parameter or threshold was tuned to pass.
+
+## Paper trading
+
+Put Alpaca **paper** keys in the environment as `APCA_API_KEY_ID` and
+`APCA_API_SECRET_KEY`, never in TOML, git or shell history. Preview, run and
+inspect before the opening auction (orders must go out before 09:25 New York
+time):
+
+```sh
+uv run fa-quant run --config examples/quant/paper.toml --dry-run
+uv run fa-quant run --config examples/quant/paper.toml
+uv run fa-quant status --config examples/quant/paper.toml
+```
+
+For unattended runs, schedule
+[`deploy/quant/run-session.py`](https://github.com/BichengWang/financial-agent/blob/v1.3.0/deploy/quant/run-session.py) with the launchd,
+cron or systemd templates beside it. It loads keys from a `chmod 600` env file,
+passes the exit code through and posts a sanitized alert to
+`FA_QUANT_ALERT_WEBHOOK` when a session halts. `status` reports live readiness:
+clean sessions, halts, slippage against the allowance and certificate age. See
+the [daily schedule](https://github.com/BichengWang/financial-agent/blob/v1.3.0/docs/quant/operations.md#daily-schedule).
+
+IBKR uses the locally running Client Portal Gateway with a daily browser login.
+Copy [ibkr-paper.toml](https://github.com/BichengWang/financial-agent/blob/v1.3.0/examples/quant/ibkr-paper.toml), set your USD paper account
+ID and gateway port, and follow the
+[gateway setup](https://github.com/BichengWang/financial-agent/blob/v1.3.0/docs/quant/operations.md#ibkr-client-portal-gateway). TLS
+verification can be disabled only on loopback, and order questions halt unless
+their message IDs are explicitly allowed.
+
+## Live gate
+
+Every live session re-checks all of these:
+
+- `mode = "live"` in a separate TOML and `FA_QUANT_ALLOW_LIVE=1` in the
+  environment.
+- A passing certificate at most 90 days old for exactly the configured strategy
+  and parameters.
+- At least 20 distinct clean paper sessions with the same broker and identity,
+  with fills, no halts or reconciliation breaks in that window, and mean
+  slippage within twice the modeled cost.
+
+Configs can tighten runtime risk limits, never loosen them. The MCP server
+exposes research and paper previews only and can't place orders. The kill switch
+persists and blocks new submissions, but doesn't cancel orders or liquidate.
+Read [safety and go-live steps](https://github.com/BichengWang/financial-agent/blob/v1.3.0/docs/quant/safety.md) before changing mode and
+[operations](https://github.com/BichengWang/financial-agent/blob/v1.3.0/docs/quant/operations.md) for kill/unkill and incidents.
+
+## Equity research and RL
+
+The [native ticker workflow](https://github.com/BichengWang/financial-agent/blob/v1.3.0/docs/research/README.md) combines sourced evidence,
+Decimal arithmetic, optional earnings/DCF/comps models and structural audits;
+[retained research](https://github.com/BichengWang/financial-agent/blob/v1.3.0/docs/research/index.md) remains provisional. The
+[daily equity workflow](https://github.com/BichengWang/financial-agent/blob/v1.3.0/agents/equity/daily_investment_system/main.md) produces
+dated source/prediction packages. The harness provides deterministic report
+checks and ledger audits:
+
+```sh
+uv run python -m financial_agent.harness --help
+uv run python -m financial_agent.harness audit --output-dir agents/equity/output
+```
+
+Generic RL supplies tabular Q-learning, GridWorld, Gymnasium wrappers and bounded
+training loops; [examples](https://github.com/BichengWang/financial-agent/blob/v1.3.0/example/rl/) show the APIs and
+[notebooks](https://github.com/BichengWang/financial-agent/blob/v1.3.0/notebooks/README.md) keep historical outputs. The FinRL-derived
+`trading/` and TensorFlow `dl/` stacks are experimental: nothing reaches capital
+unless it implements `Strategy` and passes the same gates. The historical
+autotrain entrypoint is not turnkey.
+
+## Repository map
+
+| Path | Purpose |
+|---|---|
+| [src/financial_agent/quant](https://github.com/BichengWang/financial-agent/blob/v1.3.0/src/financial_agent/quant/) | Data, strategies, backtest, validation, risk, execution, runner and CLI/MCP |
+| [docs/quant](https://github.com/BichengWang/financial-agent/blob/v1.3.0/docs/quant/) | [Architecture](https://github.com/BichengWang/financial-agent/blob/v1.3.0/docs/quant/architecture.md), safety, operations, strategy guide |
+| [examples/quant](https://github.com/BichengWang/financial-agent/blob/v1.3.0/examples/quant/) / [deploy/quant](https://github.com/BichengWang/financial-agent/blob/v1.3.0/deploy/quant/) | Paper configs, scheduler wrapper and launchd/cron/systemd templates |
+| [reports/quant](https://github.com/BichengWang/financial-agent/blob/v1.3.0/reports/quant/) | Dated strategy and research-forecast evidence |
+| [tests/quant](https://github.com/BichengWang/financial-agent/blob/v1.3.0/tests/quant/) | Deterministic offline regression tests |
+| [plan](https://github.com/BichengWang/financial-agent/blob/v1.3.0/plan/) | Dated design plans and the paper-to-live roadmap |
+| [src/financial_agent/harness](https://github.com/BichengWang/financial-agent/blob/v1.3.0/src/financial_agent/harness/) | Equity schemas, gates, kernels and policy |
+| [agents/equity](https://github.com/BichengWang/financial-agent/blob/v1.3.0/agents/equity/) / [skills](https://github.com/BichengWang/financial-agent/blob/v1.3.0/skills/) | Daily/native equity workflows and agent skills, including quant research and paper operations |
+| [src/financial_agent/rl](https://github.com/BichengWang/financial-agent/blob/v1.3.0/src/financial_agent/rl/) / [example/rl](https://github.com/BichengWang/financial-agent/blob/v1.3.0/example/rl/) | Generic RL APIs and examples |
+| [src/financial_agent/trading](https://github.com/BichengWang/financial-agent/blob/v1.3.0/src/financial_agent/trading/) / [src/financial_agent/dl](https://github.com/BichengWang/financial-agent/blob/v1.3.0/src/financial_agent/dl/) | Experimental financial RL and prediction research |
+| [notebooks](https://github.com/BichengWang/financial-agent/blob/v1.3.0/notebooks/) | Saved research outputs; avoid incidental reruns |
+
+## Limitations
+
+- Yahoo's adjusted OHLCV is revised retrospectively and isn't raw auction data;
+  paper slippage is measured against those adjusted opens.
+- The fixed ETF universe carries selection bias. Simulations omit taxes, cash
+  interest, capacity, market impact and exact corporate-action accounting.
+- Statistics describe this historical sample, not future profitability.
+- The scheduled runner doesn't monitor intraday loss or guarantee fills;
+  reference-price limits don't remove gap risk.
+- State and journal hashes are integrity checks, not signatures. The runner
+  targets macOS and Linux.
+
+## Contributing and security
+
+See [CONTRIBUTING.md](https://github.com/BichengWang/financial-agent/blob/v1.3.0/CONTRIBUTING.md) for setup, checks and pull request rules,
+and the [code of conduct](https://github.com/BichengWang/financial-agent/blob/v1.3.0/CODE_OF_CONDUCT.md). Report vulnerabilities privately as
+described in [SECURITY.md](https://github.com/BichengWang/financial-agent/blob/v1.3.0/SECURITY.md).
+
+## License
+
+[MIT](https://github.com/BichengWang/financial-agent/blob/v1.3.0/LICENSE). Software is provided as is, without warranty.

fa_quant-1.3.0/README.md

@@ -0,0 +1,224 @@
+# financial-agent
+
+[![Python quality](https://github.com/BichengWang/financial-agent/actions/workflows/python-quality.yml/badge.svg?branch=main)](https://github.com/BichengWang/financial-agent/actions/workflows/python-quality.yml)
+[![PyPI](https://img.shields.io/pypi/v/fa-quant)](https://pypi.org/project/fa-quant/)
+[![Python 3.12](https://img.shields.io/badge/python-3.12-blue)](https://www.python.org/)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://bichengwang.github.io/financial-agent/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+A Python platform for systematic ETF trading that has to earn its way to capital:
+cost-aware backtests, a statistical promotion gate, journaled paper trading and
+explicitly gated Alpaca and IBKR execution. It also holds an equity-research
+harness and separate RL/deep-learning research stacks. The platform is **beta**:
+live performance is unproven, and neither a historical pass nor paper results
+guarantee profit.
+
+**Docs:** <https://bichengwang.github.io/financial-agent/> has the quant guides,
+evidence reports, equity research and changelog.
+
+```mermaid
+flowchart LR
+  R[Research: data + Strategy] --> B[Backtest: next-bar fills + costs]
+  B --> V[Validate + certify: OOS, DSR, CSCV, bootstrap, stress]
+  V --> P[Paper: journal + reconciliation]
+  P --> L[Live: fresh certificate + paper evidence + human opt-in]
+  K[Risk limits + persistent kill switch] --- P
+  K --- L
+```
+
+## Status (2026-10-28)
+
+| Stage | State |
+|---|---|
+| Research gate | `trend_vol_target` passes all eight checks with its frozen identity `target_vol=0.12, max_weight=0.25` (data through 2026-10-27, DSR 0.994) |
+| Paper evidence | Alpaca paper sessions scheduled weekdays before the open: first session 2026-10-29, first orders 2026-11-02; 0 of 20 clean sessions |
+| Live | Not authorized. Earliest decision 2026-11-25, if no paper session halts |
+
+The [paper-to-live plan](plan/2026-10-18-quant-paper-to-live.md) tracks the
+remaining steps and decisions.
+
+## Quickstart (offline, five minutes)
+
+```sh
+pip install fa-quant
+fa-quant demo --sessions 25 --state-dir /tmp/fa-quant-demo
+```
+
+Or from a clone, with [uv](https://docs.astral.sh/uv/getting-started/installation/)
+(Python 3.12 is pinned by `.python-version`):
+
+```sh
+uv sync --locked
+uv run fa-quant demo
+uv run fa-quant --help
+```
+
+The demo runs backtest, validation, certification, local paper sessions and
+status on seeded synthetic data with a planted trend, without network access.
+Its numbers show the software working, not market performance.
+
+The PyPI distribution is `fa-quant`; it installs the `fa-quant` command and the
+`financial_agent` import package. The unrelated `financial-agent` PyPI project is
+not this one. Python 3.12 is tested; on 3.13+ the NumPy `<2` pin builds NumPy
+from source. Examples, docs and evidence live in this repository. Optional `rl`,
+`dl`, `notebooks` and `research` extras add the heavier research stacks;
+`uv sync --locked --all-extras` installs everything.
+
+## Real-data research
+
+The example universe is SPY, QQQ, IWM, EFA, EEM, TLT, IEF, LQD, GLD, DBC and VNQ
+with weekly next-open fills, whole shares, a 2% cash buffer and 2 bps half-spread
+plus 3 bps slippage per side. Downloads are cached under gitignored `var/`. Use
+the latest completed session as the inclusive end:
+
+```sh
+uv run fa-quant backtest --config examples/quant/paper.toml --end 2026-10-27 --json
+uv run fa-quant validate --config examples/quant/paper.toml --end 2026-10-27 --json
+uv run fa-quant certify --config examples/quant/paper.toml --end 2026-10-27 \
+  --output var/quant-paper/certificate.json
+```
+
+`validate` and `certify` exit 2 when any check fails; a failed certificate can be
+saved but never authorizes trading. With `--config`, all settings come from the
+TOML. See [strategy research](docs/quant/strategy-research.md) for grids,
+disclosed trials and how to read each statistic.
+
+### Results
+
+The [committed evidence](reports/quant/2026-10-default-strategy-evidence.md)
+covers 2006-02-06 through 2026-10-12. Full-period backtests at default
+parameters:
+
+| Strategy | CAGR | Net Sharpe | Max drawdown | Turnover/year |
+|---|---:|---:|---:|---:|
+| Trend vol target | 5.625% | 0.740 | 16.533% | 14.375× |
+| Dual momentum | 11.100% | 0.754 | 26.397% | 10.550× |
+| SPY buy-and-hold | 11.122% | 0.652 | 54.299% | 0.048× |
+| 60/40 SPY/IEF | 8.212% | 0.785 | 31.979% | 0.206× |
+
+The trend strategy's promotion gate (walk-forward out-of-sample, 3,528 sessions):
+
+| Protocol | Data | OOS Sharpe | DSR | OOS max drawdown | PBO | Verdict |
+|---|---|---:|---:|---:|---:|---|
+| Four-variant search | 2006-02-06 to 2026-10-12 | 0.729 | 0.996 | 17.1% | 0.650 | Pass; selects 0.12 / 0.25 |
+| Frozen 0.12 / 0.25, four trials disclosed | 2006-03-01 to 2026-10-27 | 0.704 | 0.994 | 13.7% | n/a | Pass |
+
+PBO 0.650 means picking the in-sample winner added no reliable value, and the
+choice switched 6 times in 13 folds. So the selected identity is now frozen:
+re-certification can no longer switch parameters and restart the paper clock.
+DSR still deflates by all four variants tried. The frozen row's walk-forward
+returns aren't out-of-sample for the choice of identity, which used the same
+history; the freeze stabilizes the identity, it doesn't strengthen the
+statistical case.
+
+Dual momentum and 60/40 also pass all eight checks as single pre-registered
+variants; SPY fails the 25% OOS drawdown limit. Statistical passes don't override
+execution limits: dual momentum's three 33.3% slots and the concentrated
+benchmarks exceed the 30% per-name cap. The equity `research_forecast` signal
+[fails its real-ledger gate](reports/quant/research-forecast-validation.md) for
+lack of history. No parameter or threshold was tuned to pass.
+
+## Paper trading
+
+Put Alpaca **paper** keys in the environment as `APCA_API_KEY_ID` and
+`APCA_API_SECRET_KEY`, never in TOML, git or shell history. Preview, run and
+inspect before the opening auction (orders must go out before 09:25 New York
+time):
+
+```sh
+uv run fa-quant run --config examples/quant/paper.toml --dry-run
+uv run fa-quant run --config examples/quant/paper.toml
+uv run fa-quant status --config examples/quant/paper.toml
+```
+
+For unattended runs, schedule
+[`deploy/quant/run-session.py`](deploy/quant/run-session.py) with the launchd,
+cron or systemd templates beside it. It loads keys from a `chmod 600` env file,
+passes the exit code through and posts a sanitized alert to
+`FA_QUANT_ALERT_WEBHOOK` when a session halts. `status` reports live readiness:
+clean sessions, halts, slippage against the allowance and certificate age. See
+the [daily schedule](docs/quant/operations.md#daily-schedule).
+
+IBKR uses the locally running Client Portal Gateway with a daily browser login.
+Copy [ibkr-paper.toml](examples/quant/ibkr-paper.toml), set your USD paper account
+ID and gateway port, and follow the
+[gateway setup](docs/quant/operations.md#ibkr-client-portal-gateway). TLS
+verification can be disabled only on loopback, and order questions halt unless
+their message IDs are explicitly allowed.
+
+## Live gate
+
+Every live session re-checks all of these:
+
+- `mode = "live"` in a separate TOML and `FA_QUANT_ALLOW_LIVE=1` in the
+  environment.
+- A passing certificate at most 90 days old for exactly the configured strategy
+  and parameters.
+- At least 20 distinct clean paper sessions with the same broker and identity,
+  with fills, no halts or reconciliation breaks in that window, and mean
+  slippage within twice the modeled cost.
+
+Configs can tighten runtime risk limits, never loosen them. The MCP server
+exposes research and paper previews only and can't place orders. The kill switch
+persists and blocks new submissions, but doesn't cancel orders or liquidate.
+Read [safety and go-live steps](docs/quant/safety.md) before changing mode and
+[operations](docs/quant/operations.md) for kill/unkill and incidents.
+
+## Equity research and RL
+
+The [native ticker workflow](docs/research/README.md) combines sourced evidence,
+Decimal arithmetic, optional earnings/DCF/comps models and structural audits;
+[retained research](docs/research/index.md) remains provisional. The
+[daily equity workflow](agents/equity/daily_investment_system/main.md) produces
+dated source/prediction packages. The harness provides deterministic report
+checks and ledger audits:
+
+```sh
+uv run python -m financial_agent.harness --help
+uv run python -m financial_agent.harness audit --output-dir agents/equity/output
+```
+
+Generic RL supplies tabular Q-learning, GridWorld, Gymnasium wrappers and bounded
+training loops; [examples](example/rl/) show the APIs and
+[notebooks](notebooks/README.md) keep historical outputs. The FinRL-derived
+`trading/` and TensorFlow `dl/` stacks are experimental: nothing reaches capital
+unless it implements `Strategy` and passes the same gates. The historical
+autotrain entrypoint is not turnkey.
+
+## Repository map
+
+| Path | Purpose |
+|---|---|
+| [src/financial_agent/quant](src/financial_agent/quant/) | Data, strategies, backtest, validation, risk, execution, runner and CLI/MCP |
+| [docs/quant](docs/quant/) | [Architecture](docs/quant/architecture.md), safety, operations, strategy guide |
+| [examples/quant](examples/quant/) / [deploy/quant](deploy/quant/) | Paper configs, scheduler wrapper and launchd/cron/systemd templates |
+| [reports/quant](reports/quant/) | Dated strategy and research-forecast evidence |
+| [tests/quant](tests/quant/) | Deterministic offline regression tests |
+| [plan](plan/) | Dated design plans and the paper-to-live roadmap |
+| [src/financial_agent/harness](src/financial_agent/harness/) | Equity schemas, gates, kernels and policy |
+| [agents/equity](agents/equity/) / [skills](skills/) | Daily/native equity workflows and agent skills, including quant research and paper operations |
+| [src/financial_agent/rl](src/financial_agent/rl/) / [example/rl](example/rl/) | Generic RL APIs and examples |
+| [src/financial_agent/trading](src/financial_agent/trading/) / [src/financial_agent/dl](src/financial_agent/dl/) | Experimental financial RL and prediction research |
+| [notebooks](notebooks/) | Saved research outputs; avoid incidental reruns |
+
+## Limitations
+
+- Yahoo's adjusted OHLCV is revised retrospectively and isn't raw auction data;
+  paper slippage is measured against those adjusted opens.
+- The fixed ETF universe carries selection bias. Simulations omit taxes, cash
+  interest, capacity, market impact and exact corporate-action accounting.
+- Statistics describe this historical sample, not future profitability.
+- The scheduled runner doesn't monitor intraday loss or guarantee fills;
+  reference-price limits don't remove gap risk.
+- State and journal hashes are integrity checks, not signatures. The runner
+  targets macOS and Linux.
+
+## Contributing and security
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, checks and pull request rules,
+and the [code of conduct](CODE_OF_CONDUCT.md). Report vulnerabilities privately as
+described in [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE). Software is provided as is, without warranty.

{fa_quant-1.2.1 → fa_quant-1.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fa-quant"
-version = "1.2.1"
+version = "1.3.0"
 description = "Risk-managed systematic ETF trading, statistical validation, and financial research"
 authors = [{name = "Bicheng (Kenneth)", email = "31808103+BichengWang@users.noreply.github.com"}]
 keywords = ["systematic-trading", "portfolio", "backtesting", "risk-management", "reinforcement-learning"]
@@ -30,7 +30,7 @@ dependencies = [
 [project.urls]
 Homepage = "https://github.com/BichengWang/financial-agent"
 Repository = "https://github.com/BichengWang/financial-agent"
-Documentation = "https://github.com/BichengWang/financial-agent/tree/main/docs/quant"
+Documentation = "https://bichengwang.github.io/financial-agent/"
 Issues = "https://github.com/BichengWang/financial-agent/issues"
 Changelog = "https://github.com/BichengWang/financial-agent/blob/main/CHANGELOG.md"
 
@@ -122,6 +122,10 @@ dev = [
     "pytest-cov",
     "pytest-custom-exit-code",
 ]
+docs = [
+    "mkdocs>=1.6.1,<2",
+    "mkdocs-material>=9.5,<10",
+]
 
 [tool.black]
 line-length = 88

{fa_quant-1.2.1 → fa_quant-1.3.0}/src/financial_agent/quant/__main__.py

@@ -28,7 +28,12 @@ from .runner.session import EXCHANGE_TZ, session_lock
 from .execution import Journal
 from .risk import KillSwitch
 from .strategies import build_strategy
-from .validation import PromotionPolicy, evaluate_promotion, write_certificate
+from .validation import (
+    PromotionPolicy,
+    check_disclosed_trials,
+    evaluate_promotion,
+    write_certificate,
+)
 
 ETF_UNIVERSE = (
     "SPY",
@@ -253,7 +258,7 @@ def research_inputs(
 
     if args.provider == "csv" and args.csv_dir is None:
         raise ConfigError("csv-dir: required for csv provider")
-    provider = CsvProvider(args.csv_dir) if args.csv_dir else YahooProvider()
+    provider = CsvProvider(args.csv_dir) if args.provider == "csv" else YahooProvider()
     data = CachedProvider(provider, args.cache_dir).fetch(
         args.universe, args.start, args.end
     )
@@ -414,12 +419,19 @@ def main(argv: Sequence[str] | None = None) -> int:
                     print("\n".join(f"{k}: {v}" for k, v in backtest_summary.items()))
                 return 0
             config = TradingConfig.load(args.config) if args.config else None
+            grid = parameter_grid(args.grid, config, params)
+            disclosed = config.disclosed_trials if config else ()
+            try:
+                check_disclosed_trials(name, grid, disclosed)
+            except ValueError as exc:
+                raise ConfigError(str(exc)) from None
             report = evaluate_promotion(
                 name,
-                parameter_grid(args.grid, config, params),
+                grid,
                 data,
                 backtest,
                 PromotionPolicy.load(args.policy),
+                disclosed_trials=disclosed,
             )
             if args.command == "certify":
                 write_certificate(report, args.output)