# CTF Overview

The Common Task Framework (CTF) is a live competition for evaluating portfolio
construction strategies on a shared holdout dataset. It was introduced in Hoberg,
Jensen, Kelly and Pedersen (2025) and is hosted at
[jkpfactors.com](https://jkpfactors.com).

## What the CTF evaluates

Participants submit a Python script that implements a `main()` function. The CTF
server calls this function with three data inputs:

- `chars` — a panel of 402 firm characteristics (153 JKP + 249 additional GFD factors)
  for each stock and month-end date
- `features` — a list of the 402 characteristic names
- `daily_ret` — daily excess returns for each stock

The script must return a DataFrame of portfolio weights (`id`, `eom`, `w`) covering
all test-period month-end dates. The server then evaluates the resulting portfolio
using 10% annualized volatility targeting and reports the Sharpe ratio on the
leaderboard.

## Evaluation methodology

The CTF server scales all submitted portfolios to 10% annualized volatility before
computing performance statistics. `eapctf.ctf.compute_metrics()` replicates this
methodology exactly, allowing local evaluation that closely reproduces server results.

The test period covers 408 month-end dates. Returns are compounded from daily excess
return data rather than from the monthly characteristic snapshot dates, which is an
important detail for accurate replication.

## The 402 characteristics

The full feature set consists of 153 JKP characteristics from Jensen, Kelly and
Pedersen (2023) plus 249 additional factors from the Global Factor Database. They
span many anomaly clusters including accruals, debt issuance, investment, momentum,
profitability, and value. A complete annotated catalogue is available in
`docs/ctf_features.yaml`.

## How eapctf supports CTF

`eapctf.ctf` provides the following tools:

| Function / Class | Purpose |
|-----------------|---------|
| `run_local()` | Execute a model script against local CTF data files |
| `compute_metrics()` | Evaluate with CTF-compatible vol-targeting |
| `validate()` | Run 23 compliance checks (14 automated, 9 manual) |
| `fetch_leaderboard()` | Scrape current leaderboard from jkpfactors.com |
| `build_submission()` | Package model, weights, requirements, and methodology PDF |
| `submit()` | Programmatic submission (falls back to manual if reCAPTCHA blocks) |
| `pipeline()` | End-to-end orchestration of all above steps |
| `download_ctf_data()` | Download the three CTF tables from WRDS |

See [Running Locally](running-locally.md) for usage details and
[Replication Results](replication-results.md) for verified benchmark comparisons.
