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; Python 3.12 is selected by .python-version. From the repository root:

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:

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.

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:

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 for grids and interpretation.

The committed real-data evidence 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:

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: 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):

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, 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.

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 before changing mode, and operations 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 combines sourced evidence, Decimal arithmetic, optional earnings/DCF/comps models and structural audits; retained research remains provisional. The daily equity workflow produces dated source/prediction packages. The harness provides deterministic report checks and ledger audits, not autonomous completion of every prompt stage:

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 demonstrate learning APIs; notebooks 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

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. Software is provided as is, without warranty.