vintage

<p align="center">
  <img src="assets/banner.svg" alt="Vintage — point-in-time research terminal" width="100%">
</p>

<p align="center">
  <b>A research terminal that costs $0 and won't lie to you about your Sharpe.</b>
</p>

<p align="center">
  <a href="https://pypi.org/project/vintage-mcp/"><img alt="PyPI" src="https://img.shields.io/pypi/v/vintage-mcp?color=35e08a&labelColor=0b0f16"></a>
  <a href="https://github.com/RezaSoleymanifar/vintage/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/RezaSoleymanifar/vintage/ci.yml?branch=main&labelColor=0b0f16"></a>
  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-35e08a?labelColor=0b0f16"></a>
  <img alt="Python" src="https://img.shields.io/pypi/pyversions/vintage-mcp?labelColor=0b0f16">
</p>

<p align="center">
  <a href="https://rezasoleymanifar.github.io/vintage/"><img src="assets/demo.gif" alt="A Claude session: install Vintage, backtest three signals, watch the deflated Sharpe collapse to 0.09" width="100%"></a>
</p>

<p align="center">
  <a href="https://rezasoleymanifar.github.io/vintage/"><b>rezasoleymanifar.github.io/vintage</b></a>
</p>

---

### Data filed with, published by, and computed at

| | |
|---|---|
| **U.S. Securities & Exchange Commission** | EDGAR — the filings themselves, with accession numbers and acceptance timestamps |
| **Federal Reserve Bank of St. Louis** | FRED & ALFRED — 800,000+ series, with first-release vintages |
| **Dartmouth College** | Ken French Data Library — the Fama-French factors, from July 1926 |
| **Open Source Asset Pricing** | Chen & Zimmermann — 331 published anomalies with the return and t-stat each paper claimed |

Official filings and central-bank releases, pulled live from the institutions that publish them. Not a scrape, not a CSV dump, not a mirror of someone else's mirror.

---

Free financial data exists and is scattered across twenty APIs with twenty shapes. Everyone rebuilds the same glue, badly, and quietly ends up backtesting on restated figures and survivor-only universes.

Vintage is that glue, written once, served over [MCP](https://modelcontextprotocol.io). It hosts no data — it connects, normalizes, and preserves vintage.

## What people use it for

<p align="center">
  <a href="https://rezasoleymanifar.github.io/vintage/"><img src="assets/showcase.gif" alt="Two questions answered: whether Apple restated its 2019 revenue, and a Sharpe of 2.14 collapsing to 0.09 once 41 trials are counted" width="100%"></a>
</p>

<p align="center"><sub>Two of four scenes — <a href="https://rezasoleymanifar.github.io/vintage/">see the full reel on the site</a>.</sub></p>

## Install

One line. Nothing to clone.

**Claude Code**

```bash
claude mcp add vintage -s user -- uvx vintage-mcp
```

**Claude Desktop / any MCP client** — add to your config file:

```json
{
  "mcpServers": {
    "vintage": {
      "command": "uvx",
      "args": ["vintage-mcp"]
    }
  }
}
```

<sub>Claude Desktop config lives at `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS). Restart the app afterwards — MCP servers load once at startup.</sub>

Needs [`uv`](https://docs.astral.sh/uv/getting-started/installation/). If you'd rather use pip: `pip install vintage-mcp` and set the command to `vintage`.

### Optional configuration

Everything works with zero configuration. These make it work better:

| Variable | Why |
|---|---|
| `VINTAGE_USER_AGENT` | SEC EDGAR asks for a real contact. `"Your Name your@email.com"`. |
| `FRED_API_KEY` | [Free key](https://fredaccount.stlouisfed.org/apikeys) — unlocks 800k macro series with first-release vintages. |
| `VINTAGE_CACHE_DIR` | Defaults to `~/.cache/vintage`. |

Set them under `"env"` in the same config block:

```json
{
  "mcpServers": {
    "vintage": {
      "command": "uvx",
      "args": ["vintage-mcp"],
      "env": {
        "VINTAGE_USER_AGENT": "Jane Quant jane@example.com",
        "FRED_API_KEY": "..."
      }
    }
  }
}
```

Your key stays in this file. It is read by the server process and is never passed through the model or written into the conversation.

## Try it

Once installed, ask your assistant:

> *"What was Apple's total assets as of January 2020 — and has it been restated since?"*
>
> *"Backtest 12-1 momentum on the Dow 30 since 2010."*
>
> *"Now try short-term reversal instead. Did the alpha survive?"*

The third question is the one that matters. Watch the deflated Sharpe fall as you keep asking.

## The two dates

Every value carries both:

- `observed_at` — what period the number describes
- `known_at` — when it first became public

A backtest may only use rows whose `known_at` precedes the trade date. That is structural, not a setting: the panel is indexed on `known_at`, so any slice of it is automatically point-in-time. There is no flag to turn it off.

Sources that cannot supply an honest `known_at` are flagged `UNKNOWN_VINTAGE` rather than given a fabricated date.

### Six ways yesterday's data quietly changed

- **Lag** — the number is true in December, published in February.
- **Restatement** — the company says "oops, wrong" and changes last year's figure.
- **Revision** — the government keeps fixing old jobs and inflation numbers, for years.
- **Survivorship** — dead companies get deleted; only the winners are still listed.
- **Membership** — today's S&P 500 list is not the list from 2005.
- **Price adjustment** — splits and dividends silently rewrite every price before them.

All six say the same thing: the data you have today is not what people saw back then.

## Six verbs

Source is a parameter, never a separate tool. Twenty more sources adds zero tools.

| Verb | Does |
|---|---|
| `resolve` | Any identifier → the entity key everything else accepts |
| `discover` | Plain-English search across every source's catalog |
| `fetch` | The workhorse. Any field, any source, with `as_of` |
| `events` | Filing timeline with exact public timestamps |
| `backtest` | Cross-sectional signal → returns, costs, honesty report |
| `benchmark` | Your returns → correlation and alpha vs published factors |

Plus `status` for cache size, keys, and how many specs you have tried.

## The honesty engine

A conversational backtester is an overfitting machine unless it counts how many times you asked. Every backtest returns:

- **Deflated Sharpe** ([Bailey & López de Prado, 2014](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=2460551)) accounting for every spec tried this session
- **The Sharpe noise would have produced** given that trial count
- **First-half vs second-half Sharpe**
- Costs always charged on turnover — there is no zero-cost mode
- A standing survivorship warning until point-in-time universes land

This is the part a paid terminal does not do for you.

## The method

Vintage implements the backtest-validation literature rather than inventing its own statistics. Execution realism is a different problem, already solved by [LEAN](https://www.quantconnect.com/lean) and [Nautilus Trader](https://nautilustrader.io/) — Vintage runs before that, at the stage where most ideas should die.

| Technique | Source | Status |
|---|---|---|
| Point-in-time panel indexed on `known_at` | structural, no flag to disable | ✅ shipped |
| Costs charged on turnover, always | no zero-cost mode exists | ✅ shipped |
| Deflated Sharpe Ratio | [Bailey & López de Prado (2014)](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=2460551) | ✅ shipped |
| Session trial ledger feeding the deflation | Bailey & López de Prado (2014) | ✅ shipped |
| Probability of Backtest Overfitting, via CSCV | [Bailey, Borwein, López de Prado & Zhu (2017)](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=2326253) | ⏳ planned |
| Purged k-fold CV with embargo | *Advances in Financial Machine Learning*, ch. 7 | ⏳ planned |
| Combinatorial purged cross-validation | *Advances in Financial Machine Learning*, ch. 12 | ⏳ planned |
| Minimum Backtest Length | [Bailey, Borwein, López de Prado & Zhu (2014)](https://www.ams.org/notices/201405/rnoti-p458.pdf) | ⏳ planned |
| Newey–West adjustment for autocorrelated returns | Newey & West (1987) | ⏳ planned |
| Square-root market impact | Almgren et al. (2005) | ⏳ planned |

Citations are references, not endorsements — none of these authors is affiliated with Vintage. Anything marked planned is not in the code yet, and the `backtest` response says so at runtime rather than in the footnotes.

## Where the data comes from

<table>
<tr>
<td align="center"><b>100</b><br><sub>years, July 1926 to this morning</sub></td>
<td align="center"><b>331</b><br><sub>published anomalies, with claims</sub></td>
<td align="center"><b>10,398</b><br><sub>ticker-mapped US filers</sub></td>
<td align="center"><b>800k+</b><br><sub>macro series with vintages</sub></td>
<td align="center"><b>0</b><br><sub>API keys required</sub></td>
</tr>
</table>

**A century of market history, six sources, zero API keys.** The Fama-French factors start in July 1926 and the SEC filing stream runs to this morning — Vintage covers both ends from the same six verbs.

**Five of the six are the primary source** — not a reseller, not a scraper. The filings come from the regulator that receives them, the macro series from the central bank that publishes them, and the factors from the university that computes them.

| Source | Standing | Covers | Key | Point-in-time |
|---|---|---|---|---|
| **SEC EDGAR XBRL** | Primary · US regulator | Every concept every US filer has tagged, with accession number and filing date on each figure. Restatements arrive as rows, never as an overwrite. | none | ✅ native filing dates |
| **SEC filings stream** | Primary · US regulator | 8-K, 10-K, 10-Q, Form 4, 13D/G — timestamped to the second EDGAR accepted them. | none | ✅ exact timestamps |
| **FRED / ALFRED** | Primary · central bank | Federal Reserve Bank of St. Louis. ALFRED ke