Blame for README.md

---
title: Slipstream
emoji: 📈
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
pinned: false
short_description: Smart-money, quality, trend-adaptive paper fund
---

# Slipstream

A quality, trend-adaptive equity **paper fund** that drafts the smart money.

**Strategy (rule v2, Oct 2026):** hold the large-caps that concentrated 13F managers are collectively
buying — every filer with 10–150 positions, $250M–$100B and ≥40% in its top 10 (rule-based, ~900–1,500 a
quarter); signal = 2·new + add − 2·exit conviction positions — restricted to the top-1,000 by market cap
and to companies whose ROA is in the **top 30% of their sector**; top-20 dollar-weighted (**1–10% per
name**, ≤5 per sector) with a **dynamic sector cap** (each sector 30% ± its 12-1m relative strength,
15–45%) and a **regime overlay** that rotates into large-cap momentum when SPY is in a confirmed
downtrend. An AI overlay excludes only names hit by a critical adverse event. Rebalanced monthly.

Backtest 2014-03 → 2026-10 (survivorship-free, data through *d* − 1, 20 bp/side, Sharpe net of T-bills):
CAGR 19.9% vs SPY 13.9%, Sharpe 0.85 vs 0.73, max drawdown -37.5% vs -33.7%,
alpha +3.9% (t 1.8), β 1.17. Chosen on 2016–2021 from ~210 configurations; it trailed SPY over the
never-used 2014-03 → 2016-02 window. Research and pre-registrations: `Quant Model/data/research/slipstream/`.

The page shows the live Alpaca **paper** portfolio, performance vs SPY, and the current
target book. The informational **Top AI Picks of the Month** panels moved to the
[Signalflow](https://huggingface.co/spaces/s-ttp/signalflow) Space (Nov 2026); `/picks` redirects there.

## Setup (Space secrets)

Add these under *Settings → Variables and secrets*:

| Secret | Purpose |
|---|---|
| `ALPACA_API_KEY`, `ALPACA_SECRET_KEY` | your Alpaca **paper** account (required) |
| `ALPACA_PAPER_ENDPOINT` | optional, defaults to `https://paper-api.alpaca.markets` |
| `REBALANCE_TOKEN` | enables the rebalance executor (send as `X-Rebalance-Token`) |
| `GEMINI_API_KEY` | optional — the AI event-risk overlay. Model via `GEMINI_MODEL`, default `gemini-flash-lite-latest`. Without it the overlay is off and the book is purely rule-based |
| `SLIPSTREAM_CASH_BUFFER` | optional, default `0.01` — fraction of equity the executor keeps in cash |

The fund only ever trades the **paper** endpoint. Rebalance is dry-run by default; a real
submit needs `dry=0` **and** the matching `REBALANCE_TOKEN`.

## Rebalance

`POST /api/rebalance?dry=1` returns the trade plan (no orders). Monthly, trigger a real
rebalance with `POST /api/rebalance?dry=0` and header `X-Rebalance-Token: <token>`. A Hugging
Face scheduled Job (`rebalance`, weekdays 15:00 UTC, `ops/hf_ops.py` in the Refinery Space) does this
every weekday, and the Space no-ops until the first market-open day of the month.

The executor sizes the book off `(1 − CASH_BUFFER) × equity`, never 100%: a fully-invested
target plus the min-trade deadband (small overweights are never sold) had left the account on a
standing margin balance. Sells are placed first and **waited for** before buys go in.

## Ops

- **Supervisor** — `GET /api/supervisor` is a flag-only monitor (tracking vs SPY, guardrails,
  freshness). The HF scheduled Job `supervisor` runs it **daily** (13:00 UTC). On ALERT it opens
  a discussion on this Space, which HF notifies you about. It doubles as the keep-alive: free Spaces
  sleep after 48 h idle, and the weekday-only rebalance ping left it asleep every weekend.
  All schedules (refresh, rebalance, supervisor, shadow book) are HF Jobs. See the Refinery README.
- **Restarts are safe.** All fund state lives in Alpaca. The `data/` risk-screen cache is
  ephemeral inside the container — a restart just recomputes it (one LLM call).
- **Public by design.** The dashboard, holdings and dry-run plan are world-readable (it's a paper
  account). If you flip the Space to private under *Settings*, give the Jobs' requests an
  `Authorization: Bearer` header (`ops/hf_ops.py` currently calls the public URL).

## Data refresh

The smart-money signal bundle in `data/` is regenerated by `engine/export_bundle.py` (run where
the licensed Sharadar cache lives) and committed. Refresh it **weekly**: 13F is quarterly and
~45-day lagged, but `prices.parquet` feeds the sector-strength and momentum sleeves, and the
supervisor WATCHes at 10 days / ALERTs at 14. The regime test (SPY vs 200-day MA) additionally
pulls SPY **live** from Alpaca, so the fund's biggest switch never waits on the bundle.