t212-selector

A deterministic, portfolio-aware candidate selector for a Trading 212 workflow.

This project is read-only by design: it scores data supplied in JSON and never places orders. A future live integration should keep data collection, research, and human-approved execution as separate layers.

Current features

• transparent 0–100 candidate score;
• momentum, relative strength, trend, catalyst, and liquidity inputs;
• penalties for volatility, drawdown, correlation, and leverage;
• stale-data rejection;
• portfolio, theme, position-size, cash-floor, and per-trade limits;
• JSON CLI suitable for a no-agent cron/data pipeline;
• read-only Trading 212 client for summary, positions, orders, and instruments;
• normalized account snapshots via t212-snapshot;
• provider-independent candle loading and deterministic feature calculation;
• Yahoo daily-history adapter for research, with explicit underlying-proxy handling;
• offline walk-forward backtesting with transaction costs and drawdown metrics;
• JSON backtest report export via t212-backtest;
• deterministic green-only trim/rebalance policy with no same-day re-entry;
• append-only, expiring human approval tickets via t212-approval;
• hard-disabled execution boundary with preflight checks and append-only execution audit events;
• isolated Trading 212 write adapter that is default-deny and only accepts exact approved ticket payloads;
• unit tests for the scoring, safety rules, credential resolution, snapshot mapping, market features, backtests, and approval lifecycle.

Run

python -m pip install -e ".[dev]"
python -m pytest
PYTHONPATH=src python -m t212_selector.cli examples/input.json
# with a JSON config containing data_dir, symbols, themes, and optional config:
t212-backtest backtest.json --output report.json
# rolling out-of-sample validation with complete fixed-length test windows:
t212-validate validation.json --output validation-report.json
# analyse a previously captured read-only snapshot with underlying proxies:
t212-analyse snapshot.json examples/underlying-mappings.json --start 2025-08-01 --end 2026-08-06 --output analysis.json
# apply a prior analysis to a local paper ledger at explicit next-day prices:
t212-shadow shadow.json analysis.json next-day-prices.json --execution-date 2026-08-07
# one-shot read-only daily capture + analysis (cron/systemd compatible):
t212-daily --environment live --mapping examples/underlying-mappings.json --output-dir data/daily --ledger-path /secure/path/approvals.jsonl
# create a local-only 15-minute approval ticket:
t212-approval create --ticker OKL3l_EQ --action TRIM --notional-gbp 1.25 --quantity 1 --report-hash sha256:report
# inspect or decide a ticket; this never calls Trading 212:
t212-approval status 20260806T133000Z_OKL3l_EQ
t212-approval decide 20260806T133000Z_OKL3l_EQ deny

The isolated writer in t212_selector.broker is present only as a separately reviewed boundary and defaults to disabled. ExecutionBoundary performs fresh-state checks (cash floor, pending orders, price drift, position availability, green-only exits, position limits, and HNX3l_EQ protection), writes audit events, and then raises ExecutionDisabledError. No scheduled job enables it, and no broker-write call is made by the approval or notification paths.

Fetch a read-only snapshot only when you explicitly select the environment:

T212_ENV=demo t212-snapshot --environment demo --captured-at "2026-08-06T12:00:00Z" --output snapshot.json

The collector performs GET requests only. It does not place, cancel, or modify orders.

Or install locally:

python -m pip install -e .
t212-score examples/input.json

Data contract

The input contains a portfolio and candidates. Positive features are 0–100; risk features are ratios from 0–1. See examples/input.json.

The next planned layer is a real historical market-data provider and richer sell/rebalance rules. For now, CsvMarketDataProvider keeps calculations reproducible and vendor-neutral. The backtester deliberately has no sell signal: it measures entry selection and risk constraints without pretending that exit logic has been validated. No live credentials belong in this repo. The read-only API client follows the published Trading 212 agent-skill reference mirrored at: ssh://git@git.snez.coffee:2222/keir/t212-agent-skills.git.

The published skill includes order placement; this project keeps that capability in an isolated default-deny adapter and does not enable it from any scheduled or HA path. Live execution remains a separate, human-approved layer.