Skip to content

Repository files navigation

Autotrader

CI Paper Portfolio MIT License

Autonomous daily-market research and guarded broker-execution platform powered by the Kronos financial foundation model.

Dashboard: https://pklavc.com/Autotrader/

The research portfolio is paper trading. Broker execution is disabled until an owner explicitly configures credentials and safety gates. Profit is not guaranteed and the project is not investment advice.

Architecture

Adjusted daily market data + corporate actions
                    |
                    v
       deterministic Kronos forecast
                    |
                    v
       risk-adjusted rank + constraints
                    |
             close-of-day signal
                    |
                    v
       next-session-open paper execution
                    |
       accounting + costs + state audit

Optional broker lane (separate book):
signal report -> guarded plan -> Alpaca paper -> reconciliation audit
                                      |
                         live remains hard-locked

Private fleet lane:
one signal -> isolated queue job per account -> private account snapshots
                                            -> one-time-link dashboards

The research ledger and broker account are intentionally separate. Broker failures, partial fills, or delayed jobs cannot rewrite the research history.

Correctness and safety properties

  • A signal generated from a session close is not filled retroactively at that close.
  • Each market session is processed at most once, including manual retries and holidays.
  • Same-day daily candles are rejected until 16:15 New York time so partial bars cannot become signals.
  • Forecast sampling is seeded by symbol and market session for repeatability.
  • Regular NYSE holidays are excluded from forecast timestamps; downloaded sessions remain authoritative.
  • Splits adjust held quantities and dividends credit paper cash exactly once.
  • Adjusted OHLC data prevents historical split discontinuities from reaching Kronos.
  • Paper fills include slippage and a conservative per-order commission model.
  • Implausible forecasts above the configured absolute-return ceiling are rejected.
  • Volatility-adjusted scores rank eligible signals while position and cash caps remain enforced.
  • Multiple share classes of one issuer (such as GOOG/GOOGL) count as one company, including at execution time for previously queued signals.
  • The paper ledger checks per-asset 6% overnight gaps and 8% average-cost losses at the next session's opening price. Triggered assets are exited or excluded from that opening's entries; all other candidates continue trading. These checks cannot protect against the gap itself and are not guaranteed stop fills.
  • Broker plans are long-only, cash-limited, notional-limited, and idempotent.
  • Live mode requires multiple independent opt-ins and never activates from credentials alone.

Strategy defaults

Setting Default
Model NeoQuasar/Kronos-base
Starting research cash US$10,000
Lookback 400 market sessions
Forecast horizon 5 market sessions
Maximum positions 5
Maximum position 12%
Minimum cash 40%
Planned risk budget per position 0.5% NAV
Adaptive stop distance 4–15%
Entry forecast floor +1.5%
Forecast plausibility ceiling +30%
Rebalance threshold 5% of NAV
Overnight gap risk exit (per symbol) 6% down
Position cost-basis risk exit (per symbol) 8% down
Slippage 10 bps
Paper commission US$0.0035/share, minimum US$0.35/order

Configuration lives in autotrader/config.py. These are research assumptions, not claims that the values are optimal.

Market universe and signal quality (2026-10)

The monitored universe contains 49 liquid US stocks/ETFs from technology, financials, healthcare, consumer, industrials, energy, utilities, materials, real estate, communication and broad-market ETFs. These are a fixed watchlist, not a survivorship-free index constituent database.

To bound the CPU-only Kronos runtime, all 49 are downloaded/validated daily, but at most 28 reach the forecast model. A deterministic sector-balanced, recent dollar-volume screen selects these candidates; existing holdings and pending-order symbols have priority. The screen has no predictive claim and must not be evaluated as if it were a trained alpha signal.

The single active research strategy uses 0.5% of portfolio equity as an estimated risk budget per position, with no more than 12% in one name and a minimum 40% cash allocation. Completed-market-session OHLC bars supply 20/50-day trend confirmation, realized volatility and a 14-day ATR-based initial stop distance. Weak signals are discarded; five positions are not mandatory. Long-held names have a ranking preference to reduce churn.

The simulator trails protective levels using completed closing prices, executes stop breaches only at a subsequent session opening and excludes those tickers for five calendar days. All other instruments continue trading. These are not broker-resident intraday stops, and an overnight gap can cause losses larger than the planned 0.5% budget. This is not a guaranteed profitable strategy. Existing research balance/history/tax lots are preserved; no parallel legacy strategy is executed.

The daily JSON report now includes universe.configured, available, model_capacity, screened_for_model, model_forecasts_completed, and screened_out. Do not confuse a security being downloaded with it being predicted by Kronos. Asset history is not reset and no broker live gate changes.

Research before further changes: compare against the unmodified strategy, SPY and a simple momentum baseline using point-in-time data, realistic spreads, and multiple out-of-sample market regimes. A 13-observation portfolio is insufficient to conclude that diversification or anti-churn improves profits. Third-party research optimizers (e.g. PyPortfolioOpt/vectorbt) have not been added to the production dependency chain without such validation.

Adaptive market discovery and evidence-based learning

The research paper lane now downloads a validated current S&P 500 constituent roster from a publicly maintained daily-updated CSV and rotates through 20 additional stocks per completed market session in addition to the 49 curated baseline securities. It does not pretend to download 500 full price histories daily. Discovery fails closed to the baseline watchlist if the external source becomes unavailable. The actual number of complete histories is logged on each run; the CPU-only Kronos model remains limited to 28 forecasts, including up to three liquid exploration candidates and existing/pending positions.

The next market sessions generate new daily candidates automatically; their sector mapping is taken from current GICS metadata, so dynamically discovered stocks count toward the existing two-per-sector limit. Existing cash, position caps and next-session-open execution remain unchanged.

A separate data/learning.json archive stores selected forecast predictions and grades them only after five subsequent market sessions using observed adjusted close returns compared with SPY. With fewer than 40 completed signals or fewer than 12 observations for a sector, no adaptation is applied. After reaching both thresholds, Bayesian-smoothed outperformance frequency can change a sector's ranking weight by at most 5%. The Kronos weights are never rewritten or retrained, and the learning archive never authorizes trades. Each new paper run persists the archive alongside state/report as one Actions artifact.

This does not guarantee an increased return. Small or biased samples, changing index membership, and market regime changes can still cause losses. The current constituents file is unsuitable for historical backtests due to survivorship bias; store dated memberships and use walk-forward validation before increasing risk. No live broker authorization is enabled by this feature.

Automated workflows

Research portfolio

.github/workflows/paper-trade.yml runs after the US regular session, downloads the pinned Kronos release, tests the project, produces a new signal, audits state invariants, and commits the new paper ledger. The schedule uses America/New_York so daylight-saving changes do not shift its market-relative time.

The first v2 run migrates the existing state without resetting cash, positions, or history. Legacy executions remain identifiable because they do not have v2 execution metadata.

Broker paper execution

.github/workflows/broker-paper.yml is inert until the repository variable AUTOTRADER_BROKER_ENABLED=true exists. It runs after the regular market opens and defaults to Alpaca paper mode. It can produce dry-run plans or submit guarded paper orders.

Read Broker setup before enabling it. Do not enable live execution until every gate in Operations and promotion is satisfied.

Private multi-account fleet

fleet-worker/ adds an encrypted Cloudflare D1 account registry, isolated Queue execution, one-time dashboard invitations, revocable sessions, and per-account audit/snapshots. The same validated signal is applied to every enabled account, but no account can spend another's cash, sell another's holdings, see another's data, or block another's run.

The fleet is paper-only and all order gates default to disabled. See Private fleet setup. Live authorization for other people must use an approved broker OAuth/Broker integration; raw customer credentials do not belong in GitHub.

AudaceFi league (optional Solana devnet)

The Crypto Bro league now has a separate league_strategy.py decision engine and league_plan.py guarded proposal adapter. They follow the five-day competition's net USDC return ranking, require verified category/season/wallet inputs, reject unsupported tokens, reserve time for the mandatory USDC-only snapshots and never authorize execution. The season remains read-only pending official wallet and API qualification. See the league strategy.

The optional AudaceFi integration lives in integrations/audacefi. It includes isolated manual crypto research, a crypto-only risk-gated operation preparer, and a wiring layer for the official AudaceFi TypeScript kit. The existing equity portfolio and broker remain unchanged. No recurring workflow or execution is enabled; participation requires independent onboarding, a qualifying deployment profile, and an external wallet signer.

Safe upstream updates

.github/workflows/upstream-sync.yml validates upstream source/model candidates before advancing UPSTREAM_REF, MODEL_REF, or TOKENIZER_REF. Upstream code executes in a read-only job; the write-enabled job only persists validated revision identifiers.

Local validation

Use Python 3.11, matching CI:

python -m pip install -r requirements.txt
python -m pytest -q
python scripts/audit_state.py data/state.json data/latest.json

A full forecast additionally downloads the pinned Kronos source and model weights.

Point-in-time forecast archives can be replayed without same-bar fills:

python scripts/walk_forward.py path/to/sessions.jsonl --output data/backtest-latest.json

Each JSONL row must contain a unique increasing market_date, per-symbol adjusted open and close prices, and the forecasts that were available at that close. The final session's signal is reported as pending rather than falsely counted as an executed trade.

Repository map

autotrader/
  broker.py        pure broker planning + Alpaca client
  broker_run.py    guarded broker command
  calendar.py      regular NYSE session calendar
  config.py        research and cost assumptions
  data.py          adjusted OHLCV and corporate actions
  forecast.py      deterministic Kronos adapter
  paper.py         v2 ledger, execution and metrics
  portfolio.py     signal filtering, ranking and targets
  run.py           daily research orchestration

data/
  state.json          persistent research ledger
  latest.json         latest research signal/report
  broker-latest.json  sanitized broker audit, once configured

fleet-worker/
  src/              private API, encrypted registry and queue consumer
  migrations/       D1 schema for accounts, sessions, snapshots and audits

account/
  index.html        private per-account dashboard shell (data stays in the API)

Scope and limitations

Kronos produces raw forecasts, not guaranteed alpha. The present fixed universe can carry sector concentration and survivorship bias. GitHub Actions is suitable for daily research and guarded paper automation, but it does not provide deterministic low-latency scheduling. An intraday system would require a different dataset, validation regime, execution service, and risk model.

Attribution

Autotrader is maintained by Patrick Araujo (PkLavc). Kronos was created by ShiYu and contributors and is distributed under the MIT License. See third-party notices.

Eulerpool data verification

When the GitHub Actions secret EULERPOOL_API_KEY is present, the scheduled paper run queries the official equity/candles/{ticker} API for the five portfolio targets and writes a per-symbol price comparison to data/latest.json under eulerpool. The key is never logged. Missing or divergent responses are reported without interrupting paper trading. Yahoo Finance remains the source for Kronos inputs because current Eulerpool candle responses have fewer than the required 400 sessions and omit volume and adjusted OHLCV; this avoids silently mixing incompatible data. This integration is verification-only until full historical parity is established.