Upload folder using huggingface_hub

README.md

@@ -7,17 +7,23 @@ sdk: gradio
 sdk_version: 5.50.0
 app_file: app.py
 pinned: false
-short_description: Read-only monitor of a MarketFM paper-trading agent
+short_description: Hybrid autonomous fund — deterministic engine + agentic AI
 ---
 
 # DeepQuant
 
-A transparent, **read-only** monitor of an agent that trades the **MarketFM Tactical** strategy on an
-Alpaca **paper** account. Phase 0 shows the live account — equity, cash, today's P&L, open positions, and
-an equity curve vs the S&P 500 — auto-refreshing every 30 minutes.
+A **hybrid autonomous fund** running end-to-end on an Alpaca **paper** account: a deterministic quant engine
+executes a 20-year-validated, regime-aware multi-asset strategy, while an **agentic AI layer** supervises it,
+narrates it, and — within strict evidence gates — recalibrates it. No human in the loop.
 
-This page only *observes*: it contains no order-placing code and cannot trade. Execution is handled in a
-later phase by a separate, guardrailed scheduled agent (paper-only, long-only, position-capped).
+**Division of labour, by design:**
+- **Deterministic:** stock ranking (MarketFM, ~11,800-name survivorship-free universe), order execution over the
+  Alpaca API, risk rails (long-only, 10% cap, no leverage), daily statistical health checks vs the strategy's own
+  backtest distribution.
+- **Agentic (Claude Opus 5):** a weekly role-separated crew — Analyst → adversarial Critic → PM — that assesses
+  the evidence and decides to hold, adopt a better-validated strategy variant, or pause trading; every action is
+  re-checked by a code validator (full walk-forward acceptance criteria, 90-day rate limit, hard rails).
+- **MarketGuruLLM** (fine-tuned Qwen2.5-14B) narrates every rebalance and decision in plain English.
 
-**Roadmap:** P0 read-only monitor → P1 dry-run rebalance preview → P2 paper execution → P3 MarketGuru
-narration + scheduled weekly agent → P4 reconciliation & drift alerts.
+The page is **read-only**: live positions, equity vs S&P 500 since inception, agent health, the latest decision
+with its reasoning, and a dry-run rebalance preview. Backtested results, paper trading — not investment advice.

app.py

@@ -245,19 +245,53 @@ def rebalance_preview():
 with gr.Blocks(title="DeepQuant — live paper monitor", theme=gr.themes.Soft()) as demo:
     gr.Markdown(
         "# 🤖 DeepQuant\n"
-        "### An agent that autonomously **executes** a strategy backtested to beat the S&P 500 over 20+ years\n"
-        "DeepQuant runs a regime-aware, **multi-asset** strategy end-to-end — using the **Alpaca API to both execute "
-        "*and* monitor** every trade on a live paper account.\n\n"
-        "**Under the hood:**\n"
-        "- 🧠 **[MarketFM](https://huggingface.co/spaces/s-ttp/marketfm-ranker)** — a survivorship-free quant model — ranks the universe and sets the target portfolio\n"
-        "- 💬 **[MarketGuruLLM](https://huggingface.co/s-ttp/qwen25-14b-fin-lora)** — a fine-tuned analyst LLM — reasons over and narrates every rebalance\n"
-        "- ⚡ **Alpaca API** — the brokerage rails the **quant execution engine** drives to place orders and stream live fills, positions and P&L\n"
-        "- 🔁 **Autonomous recalibration** — tracks live vs backtest over rolling 8-week windows; on statistically unusual deviation it re-runs the full walk-forward due diligence and adopts a better-validated variant on its own\n\n"
-        "**The strategy:** large-cap **momentum + quality** while the trend is up; when it turns down it de-risks into a "
-        "blend of **stocks + bonds + gold** (60 / 20 / 20). Backtested 2002–2026: **~14% / yr vs the S&P 500's ~11%**, "
-        "higher Sharpe, smaller drawdown.\n"
-        "<sub>Phase 0 — live paper-account monitor below; autonomous weekly execution rolls out next. "
-        "Backtested results, paper trading — not investment advice.</sub>")
+        "### A hybrid autonomous fund — deterministic quant engine, agentic AI judgment\n"
+        "DeepQuant runs a 20-year-validated, regime-aware multi-asset strategy **end-to-end on a live paper account** — "
+        "it selects, executes, monitors, explains, recalibrates and even pauses itself, with no human in the loop. "
+        "Every responsibility is assigned by one principle: **deterministic code wherever correctness must be provable, "
+        "agentic AI wherever judgment adds value** — never the other way around.\n\n"
+        "**The stack:**\n"
+        "- 🧠 **[MarketFM](https://huggingface.co/spaces/s-ttp/marketfm-ranker)** — a survivorship-free quant model "
+        "(~11,800 US stocks, 21 point-in-time factors) ranks the cross-section and sets the target portfolio\n"
+        "- ⚙️ **Deterministic execution engine** — turns targets into orders over the **Alpaca API**: weekly rebalances, "
+        "market-open checks, notional market orders, idempotent reconciliation — inside uncrossable rails "
+        "(long-only, 10% position cap, no leverage, cash buffer)\n"
+        "- 🩺 **Deterministic supervision** — daily health checks locate live performance *inside the strategy's own "
+        "20-year backtest distribution* and watch guardrails, drift and pipeline freshness\n"
+        "- 🤝 **Agentic decision crew** (Claude Opus 5) — every week an **Analyst** assesses the evidence, an adversarial "
+        "**Critic** stress-tests it, and a **PM** decides: hold, adopt a better-validated strategy variant, or pause "
+        "trading — each action gated by a **code validator** (walk-forward acceptance criteria, 90-day rate limit, hard rails)\n"
+        "- 💬 **[MarketGuruLLM](https://huggingface.co/s-ttp/qwen25-14b-fin-lora)** — a fine-tuned analyst model narrates "
+        "every rebalance and every decision in plain English\n\n"
+        "**The strategy:** large-cap **momentum + quality** while the market trend is up; when it turns down, de-risk into "
+        "a blend of **stocks + bonds + gold** (60 / 20 / 20). Backtested 2002–2026, net of costs: **~14% / yr vs the "
+        "S&P 500's ~11%**, higher Sharpe, −35% max drawdown vs the index's −49%.\n"
+        "<sub>Fully autonomous, paper trading, this page is read-only. Backtested results — past performance ≠ future. "
+        "Not investment advice.</sub>")
+    with gr.Accordion("🧬 Why hybrid? Who decides what — and why", open=False):
+        gr.Markdown(
+            "The lesson from building this system: **neither pure determinism nor pure agency is enough.** Rules can't "
+            "weigh ambiguous evidence; models can't be allowed to improvise with money. So each job goes to the framework "
+            "that has *earned* it:\n\n"
+            "| Responsibility | Framework | Why |\n|---|---|---|\n"
+            "| Stock ranking & target weights | **Deterministic** (MarketFM factors + fixed rules) | Validated on a 20-year "
+            "walk-forward, survivorship-free, net of costs — and reproducible to the penny |\n"
+            "| Order execution & risk rails | **Deterministic** | Execution is arithmetic — the last place you want a model "
+            "hallucinating. The rails (long-only, caps, no leverage) are code no one can override |\n"
+            "| Daily monitoring | **Deterministic** | Statistical checks against the strategy's own history — e.g. \"is this "
+            "drawdown inside the envelope of 280 historical 8-week windows?\" |\n"
+            "| Weekly assessment & judgment | **Agentic** — a role-separated crew (Analyst → adversarial Critic → PM) on "
+            "Claude Opus 5 | Weighing noisy, conflicting evidence is judgment; separating the roles makes each argument "
+            "survive an adversarial challenge before any decision |\n"
+            "| Strategy changes | **Hybrid** | The crew may adopt *only* variants that beat the incumbent across a bounded "
+            "menu (selection signal × regime rule × defense sleeve × cadence) on the full 20-year walk-forward, net of cost — "
+            "re-checked by a code validator; max one change per 90 days. Trigger on recent data, validate on all data |\n"
+            "| Emergency brake | **Hybrid** | The crew can pause execution up to 2 weeks on operational anomalies; holding "
+            "the validated book is always the safe default — and any AI failure automatically resolves to HOLD |\n"
+            "| Explanations | **Agentic** (MarketGuruLLM) | Language is what language models are for |\n\n"
+            "Every weekly decision is logged in full — the Analyst's assessment, the Critic's objections, the PM's ruling "
+            "and the evidence they cite — and the current strategy configuration is versioned, so the fund's entire "
+            "decision history is auditable. **AI proposes and judges; validated evidence admits; code enforces.**")
     with gr.Tabs():
         with gr.Tab("📊 Live account"):
             stats = gr.Markdown()
@@ -273,8 +307,9 @@ with gr.Blocks(title="DeepQuant — live paper monitor", theme=gr.themes.Soft())
                 updated = gr.Markdown("_loading…_")
                 btn = gr.Button("↻ Refresh now", scale=0)
         with gr.Tab("🔄 Rebalance preview"):
-            gr.Markdown("What the agent **would** trade at the next rebalance — computed live from the MarketFM target "
-                        "and your current account. **Nothing is placed** (Phase 1, dry-run).")
+            gr.Markdown("What the deterministic engine **would** trade right now — the live target portfolio from the "
+                        "current (versioned) strategy config, diffed against the account. Display only: orders are placed "
+                        "solely by the scheduled Monday agent, inside its guardrails.")
             pv_banner = gr.Markdown()
             pbtn = gr.Button("⟳ Recompute preview", scale=0)
             with gr.Row():