Value Steward

Systematic, Risk-Aware Portfolio Management Agent

Value Steward is an automated trading agent that ranks assets by momentum, volatility, and drawdown, sizes positions within hard risk limits, and learns from the forward returns of its own past decisions — including the trades it chose not to make. It pairs a news-derived macro-context layer with a rule-based decision engine and runs on a live paper-trading schedule.

⚠️ Status: experimental research project — paper trading only. Value Steward is a personal engineering + machine-learning learning project, currently running a live paper-trading experiment (simulated money, no real capital). It is not financial advice, not a product, and is provided with no warranty (Apache-2.0). Nothing here recommends buying or selling any security. Do not run it with real money. See the Disclaimer and Roadmap below.

---

🏛 Architecture

The system uses a Hybrid-Language, Unified-State Architecture:

• World Layer (Node.js): Continuous global financial news ingestion, sentiment scoring, and macro risk classification.
• Brain Layer (Python): Deterministic signal ranking (Momentum, Volatility, Drawdown), portfolio rebalancing, and risk governance.
• Execution Layer (Python): Order submission using "Fishing" (mid-point limit) strategies to reduce the bid-ask spread paid.
• Unified State: A shared JSON source of truth that ensures all system components operate on identical daily equity baselines and safety toggles.

🚀 Key Features

• Dynamic Risk Modes: Support for LOW, MEDIUM, and HIGH target risk exposures.
• Execution: Mid-point limit orders with "Cancel & Catch" logic to reduce the bid-ask spread paid.
• Safety Circuit Breakers: Multi-layered checks, including a 3% daily equity kill-switch, a 2.0 SD per-position vol-stop (panic exit), and stale-data guards.
• Capital Discipline + Rotation: A hard deployment cap bounds total at-risk capital. Appreciation above the cap is allowed — winners run. The system only sells to free room when a genuinely stronger new candidate is otherwise blocked, rotating out the weakest holding (buy-coupled rotation, not forced trimming).
• Strategic Hold Logic: Lets winners run by refusing to sell strong assets for marginal opportunities.
• Auditability: Comprehensive JSONL logs of every intent, decision, and execution for performance attribution and learning.

🧠 Adaptive Learning Loop

The signal scoring and decision gates are no longer static. Every end-of-day cycle, the system grades its own decisions against the next-day, 5-day, and 20-day forward returns of the symbols it bought and the symbols it blocked (counterfactuals), and updates its policy:

• Ridge-regularized OLS regression over the three rank features (momentum / vol / drawdown) against forward alpha (excess_vs_benchmark). Per-feature t-statistic gating (|t| ≥ 2.0, ~p < 0.05) skips updates that aren't statistically distinguishable from noise.
• Thompson sampling on the score gate (opt-in): per-symbol Beta posteriors built from the scorecard let high-conviction winners through easily and rarely admit known losers.
• Regime-conditional weights: separate [w_mom, w_vol, w_dd] triplets per macro regime (calm / watchful / stressed / crisis-prone), trained independently from records taken in that regime.
• Out-of-sample evaluation (data/oos-eval.jsonl) tracks rolling Sharpe of decisions made under the current policy.
• Champion-challenger auto-rollback (opt-in): the trainer preserves a "champion" snapshot of the last weights that proved their OOS Sharpe; if the live policy underperforms the champion for 3 consecutive cycles it auto-reverts.

All learning is gated by significance / sample-size floors and behind env vars so the system fails closed — defaults preserve the original deterministic behavior until enough data accumulates. See docs/ML_BACKLOG.md for the Tier 2 / Tier 3 roadmap to revisit after each Phase 1 run.

🛠 Quickstart

Prerequisites

• Node.js (v18+)
• Python 3.10+
• Alpaca Paper Trading Account

Setup

1. Clone & Install:

   git clone https://github.com/lukeinthecity/value-steward.git
   cd value-steward
   npm install
   python -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   pip install -e .

2. Configure: Copy .env.example to .env and provide your Alpaca API keys.

3. Initialize Automation:

   sudo cp docs/systemd/*.timer /etc/systemd/system/
   sudo cp docs/systemd/*.service /etc/systemd/system/
   sudo systemctl daemon-reload
   sudo systemctl enable --now value-steward-world.timer
   sudo systemctl enable --now value-steward-tick.timer

📟 Operations & Observability

Day-to-day health is visible without depending on email (a silent SMTP failure can no longer go unnoticed):

npm run runtime:status     # one-shot snapshot: phase day count, cron pulse,
                           # positions, recent trades/blocks, ML training +
                           # OOS state, email health, feature flags
npm run runtime:watch      # same view, auto-refreshing in the terminal (10s)
npm run runtime:append     # append a compact JSON line to data/runtime.log
                           # (wire to cron for a historical record)
npm run email:test         # send a test email and verify SMTP + AI summary

The desktop app (npm start from desktop/) mirrors this in a live-updating Runtime Status panel.

Every email send outcome is recorded to data/email-health.json and surfaced in runtime:status, so credential or transport failures show up immediately.

Operating discipline and the per-run review checklist live in docs/SESSION_BRIEF.md and docs/PLAYBOOK_WEEKLY_REVIEW.md.

📊 Reporting

Value Steward automatically generates a Weekly Performance Report every Sunday at 6:00 PM ET, summarizing:

• Hit rates across 1, 5, and 20-day horizons.
• Excess returns versus the benchmark (SPY).
• Execution quality (Average Slippage).
• Strategic Hold counts (Decisions influenced by safety gates).

Daily End-of-Day and Health emails include an AI-synthesized "Steward's Insight" (Google Gemini via the generateContent API) over the cycle's technical data.

🗺 Roadmap

Value Steward is under active development as a live paper-trading experiment. The full backlog — with the reasoning and the decision rule behind every item — lives in docs/ML_BACKLOG.md. At a glance:

Recently shipped

• Intent → fill reconciliation, execution fill-rate / adverse-selection metric, and per-gate calibration reporting (observation tooling).
• Strict out-of-sample evaluation restored (a policy version-semantics fix).
• Repeatable phase-run reset tooling; CI; hermetic test suite.

Next / under evaluation

• Statistical audit + pruning of the pattern library and entry gates.
• Recency-decay and empirical-Bayes priors for the score-gate posteriors.
• Champion-challenger margin sensitivity analysis.
• Risk-adjusted training label; continuous macro-score feature.
• Predictive sell-side trainer.
• Walk-forward backtest harness (price-signal core; the macro layer can't be reconstructed for past dates, so it would be stubbed — a documented limitation).
• Transaction-cost modeling — a hard gate before any hypothetical live-money graduation.

The guiding discipline: most of the above is deliberately deferred until the live run produces the evidence to justify it, rather than added speculatively. A documented "why I'm waiting" is the point, not a gap.

🤝 Contributing

This is a personal research project, but issues and PRs are welcome — see CONTRIBUTING.md. Please treat it as a study of how an automated trading agent can be built and governed, not as software to run with real money.

⚠️ Disclaimer

Value Steward is experimental software for education and research, and trades only on a simulated (paper) account. It is not investment or financial advice, not a recommendation to buy or sell any security, and not a product or service. Algorithmic trading carries substantial financial risk; any use with real capital is entirely at your own risk. Past or simulated performance does not indicate future results. The software is provided "AS IS" without warranty of any kind under the Apache License 2.0.

📜 License

This project is licensed under the Apache License 2.0 — see the LICENSE file for details.