fa-quant 1.2.1__tar.gz

fa_quant-1.2.1/.gitignore

@@ -0,0 +1,225 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# macOS
+.DS_Store
+
+# Project-local artifacts
+tensorboard_log/
+
+# Equity-agent reproducible working data; keep durable reports in output/.
+agents/equity/.work/
+
+# Harness run locks (removed on exit; a leftover one marks a crashed run).
+agents/equity/output/.locks/
+
+# Harness run journals (one JSON per (model, date) run attempt).
+agents/equity/output/.runs/
+
+# Quant research downloads (never commit market data).
+.quant-cache/

fa_quant-1.2.1/CHANGELOG.md

@@ -0,0 +1,149 @@
+# Changelog
+
+All notable changes are documented here, following [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.2.1] - 2026-10-20
+
+### Added
+
+- The Release workflow can publish to PyPI through trusted publishing once the
+  `PYPI_PUBLISH` repository variable is `true`. Manual dispatch rehearses the
+  upload on TestPyPI. Pull requests and releases run `twine check --strict`. See
+  `docs/releasing.md`.
+
+### Changed
+
+- The distribution is renamed `fa-quant`, because `financial-agent` on PyPI is an
+  unrelated project. The `financial_agent` import package (declared as PEP 794
+  `import-names`) and the `fa-quant` command are unchanged. Certificates and MCP
+  report the `fa-quant` version. Run `uv sync` after pulling.
+- Packaging uses the SPDX license expression `MIT`. The sdist holds only what
+  building the wheel needs (31.7 MB to 0.2 MB). The PyPI description links to the
+  tagged repository files.
+
+## [1.2.0] - 2026-10-19
+
+### Added
+
+- `fa-quant status` shows live readiness for Alpaca and IBKR paper configs:
+  clean sessions, halts and breaks in the evidence window, mean and per-fill
+  slippage against the allowance, certificate verdict, identity match, age and
+  expiry, and every unmet reason. It reads only the journal and certificate,
+  makes no broker call and grants nothing.
+- `deploy/quant/run-session.py`, a stdlib-only scheduler wrapper. It loads
+  credentials from a chmod 600 env file (refused when a symlink,
+  group/other-accessible or not user-owned), runs `fa-quant run --json`, passes
+  output and the exit code through (128 + N after signal N), and on a non-zero
+  exit posts one sanitized JSON alert (status, session, reasons) to
+  `FA_QUANT_ALERT_WEBHOOK` when set. The launchd, cron and systemd templates call
+  it; the launchd template gives a Pacific-host example (`Hour=5`, `Minute=45`)
+  and the `pmset` wake command.
+
+### Changed
+
+- `live_readiness(config, *, now)` holds the certificate and paper-evidence
+  evaluation; `authorize_live` adds the `FA_QUANT_ALLOW_LIVE` opt-in and the
+  grant. Thresholds and reasons are unchanged.
+
+## [1.1.1] - 2026-10-19
+
+### Fixed
+
+- Broker-backed (Alpaca, IBKR) sessions submit opening-auction orders only when
+  the New York date equals the session date and the time is before the packaged
+  09:25 ET `[execution] opening_auction_cutoff`. The check runs before journaling
+  submission intents and before every submission, including interrupted-submission
+  recovery; otherwise the session halts with the observed time. Late or replayed
+  runs can no longer queue orders for a later auction. Local paper and the demo
+  are unchanged.
+- `fa-quant run --today` defaults to the current New York date instead of the
+  host-local date.
+- CHANGELOG link references cover every release.
+
+### Changed
+
+- `run_session` accepts `now`, an injectable clock returning timezone-aware
+  datetimes. Adding the policy section changes `quant_policy.toml` bytes, so new
+  certificates record a different `policy_sha256`; thresholds are unchanged and
+  existing certificates still verify.
+
+## [1.1.0] - 2026-10-13
+
+### Added
+
+- IBKR Client Portal Gateway execution with guarded paper/live accounts, USD
+  portfolio observation, whole-share opening-auction orders, contract resolution,
+  precaution allow-lists, order recovery and gateway operations guidance.
+
+### Changed
+
+- Public broker `lookup(client_order_id)` supports runner recovery across adapters.
+- Live evidence must come from the same broker as the live configuration;
+  local simulation never authorizes live execution.
+
+### Fixed
+
+- Finalize broker-backed opening-auction intents after observing their auction
+  session, preventing vanished zero-fill or partial orders from halting later runs.
+  Reconciliation still halts on unreported fills.
+- Validate IBKR account metadata once per adapter and cache authentication status
+  for 60 seconds, refreshing immediately after HTTP 401, to reduce gateway pacing
+  delays without bypassing live guards.
+
+## [1.0.1] - 2026-10-13
+
+### Fixed
+
+- Wheel installations can run trading sessions and the offline demo outside a
+  source checkout without failing with `FileNotFoundError` for missing helper scripts.
+
+## [1.0.0] - 2026-10-13
+
+### Added
+
+- Risk-managed systematic ETF platform with binding strategy/data/broker contracts
+  and research → certify → paper → live delivery plan (#91).
+- Adjusted Yahoo/CSV data, incremental revision-aware cache, quality checks and
+  deterministic synthetic fixtures (#92).
+- Cost-aware, next-bar portfolio backtesting, shared weight-to-share sizing,
+  trend/volatility targeting, dual momentum and fixed-weight benchmarks (#93).
+- Tighten-only pre-trade limits, account loss/drawdown state and persistent
+  operator-released kill switch (#94).
+- Embargoed walk-forward validation, DSR, CSCV/PBO diagnostics, bootstrap,
+  execution stress, policy gates and hashed certificates (#95).
+- Dated research-forecast adapter and honest failing short-history evidence (#97).
+- Persisted paper broker, guarded Alpaca REST execution, idempotent orders,
+  reconciliation and hash-chained audit journal (#98).
+- Operator CLI, session runner, live authorization from certificate and clean
+  Alpaca-paper evidence, offline demo, paper-only MCP previews and deployment
+  templates (#99).
+- Release documentation, real-data comparison with unchanged gate verdicts,
+  wheel installation smoke and tag-triggered release workflow.
+
+### Changed
+
+- Core installation is separated from optional RL, deep-learning, notebook and
+  development stacks; NumPy/pandas pins remain unchanged (#96).
+- Package metadata now describes the platform and uses the existing maintainer
+  identity. Version 1.0.0 is classified beta: live performance is unproven.
+- CLI help describes every command/option; session reports retain every attempt
+  and show last planned targets on off-cadence days.
+- MCP initialization reports the installed package version.
+
+### Fixed
+
+- A single pre-registered parameter set can clear the promotion gate: CSCV now
+  computes its absolute OOS loss frequency instead of rejecting one-column input.
+  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
+[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
+[1.1.0]: https://github.com/BichengWang/financial-agent/compare/v1.0.1...v1.1.0
+[1.0.1]: https://github.com/BichengWang/financial-agent/compare/v1.0.0...v1.0.1
+[1.0.0]: https://github.com/BichengWang/financial-agent/releases/tag/v1.0.0

fa_quant-1.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kenneth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fa_quant-1.2.1/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.5
+Name: fa-quant
+Version: 1.2.1
+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://github.com/BichengWang/financial-agent/tree/main/docs/quant
+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
+
+A Python platform for systematic ETF research, cost-aware portfolio backtesting,
+statistical certification, paper trading and explicitly gated Alpaca and IBKR execution.
+It also retains an equity-research harness and separate RL/deep-learning research
+stacks. The platform is **beta**: live performance is unproven, and neither a
+historical gate pass nor paper results guarantee profit.
+
+## Five-minute offline quickstart
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/); Python 3.12
+is selected by `.python-version`. From the repository root:
+
+```sh
+uv sync --locked
+uv run fa-quant demo
+uv run fa-quant --help
+```
+
+The demo uses seeded synthetic data with a planted trend. It runs backtest,
+validation/certificate creation, 25 local paper sessions and status without
+network access after dependencies are installed. Its printed numbers demonstrate
+software behavior, not market performance. To keep the artifacts, use a fresh
+state directory:
+
+```sh
+uv run fa-quant demo --sessions 25 --state-dir /tmp/fa-quant-demo-release
+```
+
+Core dependencies include NumPy `<2`, pandas `>=2,<3`, yfinance, Gymnasium and
+requests. Default development tools are installed by `uv sync`; optional `rl`,
+`dl`, `notebooks` and `research` extras add the heavier research stacks. Full
+release verification uses `uv sync --locked --all-extras`.
+
+Once a release is published to PyPI, `pip install fa-quant` installs the
+`fa-quant` command and the `financial_agent` import package. The PyPI project
+`financial-agent` is unrelated. Python 3.12 is the tested version; on 3.13+ the
+NumPy `<2` pin builds NumPy from source. Examples, docs and evidence stay in this
+repository; see [releasing](https://github.com/BichengWang/financial-agent/blob/v1.2.1/docs/releasing.md).
+
+## Real-data research
+
+The example uses SPY, QQQ, IWM, EFA, EEM, TLT, IEF, LQD, GLD, DBC and VNQ,
+weekly next-open fills, whole shares and a 2% cash buffer. 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-12 --json
+uv run fa-quant validate --config examples/quant/paper.toml --end 2026-10-12 --json
+uv run fa-quant certify --config examples/quant/paper.toml --end 2026-10-12 \
+  --output var/quant-paper/certificate.json
+```
+
+`validate`/`certify` return 2 when any gate fails; failed certificates can be saved
+but cannot authorize live trading. With `--config`, settings come from the TOML;
+standalone strategy/provider/start flags do not override it. See
+[strategy research](https://github.com/BichengWang/financial-agent/blob/v1.2.1/docs/quant/strategy-research.md) for grids and interpretation.
+
+The [committed real-data evidence](https://github.com/BichengWang/financial-agent/blob/v1.2.1/reports/quant/2026-10-default-strategy-evidence.md)
+uses the earliest common ETF date, **2006-02-06 through 2026-10-12**, unchanged
+default costs and the disclosed four-variant trend grid. All four full-period
+default comparisons are shown here:
+
+| 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× |
+
+Trend passes all eight historical checks: OOS Sharpe 0.729, DSR 0.996, OOS
+maximum drawdown 17.114%. PBO 0.650 warns that in-sample parameter selection adds
+no reliable value. Single-default dual momentum and 60/40 also pass all eight
+statistical checks; SPY fails the OOS drawdown limit. For a single pre-registered
+variant, CSCV computes absolute OOS loss frequency; PBO and degradation slope
+are not applicable. Warmup/OOS windows differ; read the report for dates, exact
+checks, costs, bootstrap intervals, stress results and data caveats. No parameters
+or thresholds were tuned to pass. Statistical passes do not override execution
+limits: default dual momentum's three slots allocate 33.3% each versus the 30%
+per-name cap, and concentrated SPY/60-40 benchmarks also exceed runtime caps.
+
+The dated equity `research_forecast` strategy also [fails its real-ledger gate](https://github.com/BichengWang/financial-agent/blob/v1.2.1/reports/quant/research-forecast-validation.md):
+there is too little history to support promotion. This is the retained result
+for the LLM research signal, not an implied trading edge.
+
+## Paper trading and live gate
+
+Load Alpaca **paper** keys into the process environment as `APCA_API_KEY_ID` and
+`APCA_API_SECRET_KEY`; keep them out of TOML, git and command history. With keys
+loaded, preview and run before the opening auction (around 08:45 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
+```
+
+IBKR uses the locally running **Client Portal Gateway**, with daily browser login.
+Copy [ibkr-paper.toml](https://github.com/BichengWang/financial-agent/blob/v1.2.1/examples/quant/ibkr-paper.toml), set your USD paper account
+ID (`DU…`/`DF…`) and gateway port, then use the same `fa-quant run` command.
+TLS verification can be disabled only on loopback; remote gateways require a
+trusted certificate or CA path. Order questions halt unless every message ID is
+explicitly allowed. Follow the [gateway setup](https://github.com/BichengWang/financial-agent/blob/v1.2.1/docs/quant/operations.md#ibkr-client-portal-gateway).
+
+The release verifies execution through local paper and fake Alpaca/IBKR transports;
+a real credentialed paper run is still an owner step. A dry run suppresses new
+orders but journals observations and can synchronize earlier fills.
+
+Live needs `mode = "live"`, `FA_QUANT_ALLOW_LIVE=1`, a passing certificate no older
+than 90 days matching the exact strategy/params, at least 20 distinct clean
+paper sessions from the same broker (Alpaca or IBKR), no recent risk halts/reconciliation breaks, and observed
+paper slippage within twice modeled allowance. Runtime risk limits cannot be
+loosened by config. MCP exposes research and paper previews only. Read
+[safety and go-live steps](https://github.com/BichengWang/financial-agent/blob/v1.2.1/docs/quant/safety.md) before changing mode, and
+[operations](https://github.com/BichengWang/financial-agent/blob/v1.2.1/docs/quant/operations.md) for scheduling, kill/unkill and incidents.
+Kill stops new submissions; it does not cancel orders or liquidate positions.
+
+## Research harness, equity workflow and RL
+
+The [native ticker workflow](https://github.com/BichengWang/financial-agent/blob/v1.2.1/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.2.1/docs/research/index.md) remains provisional. The
+[daily equity workflow](https://github.com/BichengWang/financial-agent/blob/v1.2.1/agents/equity/daily_investment_system/main.md) produces
+dated source/prediction packages. The harness provides deterministic report
+checks and ledger audits, not autonomous completion of every prompt stage:
+
+```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/evaluation loops. [Examples](https://github.com/BichengWang/financial-agent/blob/v1.2.1/example/rl/) demonstrate learning APIs;
+[notebooks](https://github.com/BichengWang/financial-agent/blob/v1.2.1/notebooks/README.md) retain historical experiment outputs. Install
+`--extra rl`, `--extra dl` or `--extra notebooks` as needed. The FinRL-derived
+`trading/` and TensorFlow `dl/` stacks are experimental; they do not feed capital
+unless adapted to `Strategy` and passed through the same gates. The historical
+autotrain entrypoint has unresolved signature/name issues and is not turnkey.
+
+## Repository map
+
+| Path | Purpose |
+|---|---|
+| [src/financial_agent/quant](https://github.com/BichengWang/financial-agent/blob/v1.2.1/src/financial_agent/quant/) | Data, strategies, backtest, validation, risk, execution, runner and CLI/MCP |
+| [docs/quant](https://github.com/BichengWang/financial-agent/blob/v1.2.1/docs/quant/) | [Architecture](https://github.com/BichengWang/financial-agent/blob/v1.2.1/docs/quant/architecture.md), safety, operations, strategy guide |
+| [examples/quant](https://github.com/BichengWang/financial-agent/blob/v1.2.1/examples/quant/) / [deploy/quant](https://github.com/BichengWang/financial-agent/blob/v1.2.1/deploy/quant/) | Paper TOML and cron/launchd/systemd templates |
+| [reports/quant](https://github.com/BichengWang/financial-agent/blob/v1.2.1/reports/quant/) | Computed default and research-forecast evidence |
+| [tests/quant](https://github.com/BichengWang/financial-agent/blob/v1.2.1/tests/quant/) | Deterministic offline regression coverage |
+| [src/financial_agent/harness](https://github.com/BichengWang/financial-agent/blob/v1.2.1/src/financial_agent/harness/) | Equity schemas, gates, kernels and policy |
+| [agents/equity](https://github.com/BichengWang/financial-agent/blob/v1.2.1/agents/equity/) / [skills](https://github.com/BichengWang/financial-agent/blob/v1.2.1/skills/) | Daily/native equity workflows and Turtle research |
+| [src/financial_agent/rl](https://github.com/BichengWang/financial-agent/blob/v1.2.1/src/financial_agent/rl/) / [example/rl](https://github.com/BichengWang/financial-agent/blob/v1.2.1/example/rl/) | Generic RL APIs and examples |
+| [src/financial_agent/trading](https://github.com/BichengWang/financial-agent/blob/v1.2.1/src/financial_agent/trading/) / [src/financial_agent/dl](https://github.com/BichengWang/financial-agent/blob/v1.2.1/src/financial_agent/dl/) | Financial RL and prediction research |
+| [notebooks](https://github.com/BichengWang/financial-agent/blob/v1.2.1/notebooks/) / [archive](https://github.com/BichengWang/financial-agent/blob/v1.2.1/archive/) | Saved research outputs; avoid incidental reruns |
+
+## Limitations
+
+Yahoo's retrospectively adjusted OHLCV can change and is not raw auction
+execution data. The fixed ETF universe retains selection bias. Simulations omit
+taxes, cash interest, capacity/market impact and exact live corporate-action
+accounting. Statistics measure this historical sample, not future profitability.
+The scheduled runner does not continuously monitor intraday loss or guarantee
+fills; reference-price limits do not eliminate gap risk. State/journal hashes
+are integrity checks, not signatures. The POSIX runner targets macOS/Linux.
+
+## License
+
+[MIT](https://github.com/BichengWang/financial-agent/blob/v1.2.1/LICENSE). Software is provided as is, without warranty.