# Academic tutorials (master scope §83)

Runnable course notebooks. Each works locally and on Google Colab, needs only
an API key (minted at api.edi.finance/developer), and **falls back to plain
HTTP if the `edifinance` package is not installed** — nothing in them is
magic, and a student can read every request they make.

Every notebook teaches the platform's standing discipline alongside its
subject: **diagnostics before data** (coverage, withheld facts, drop reasons
are read before any statistic), and every build ends in a citable Research
Snapshot. Methods are documented in `../methodology/`; notebooks cite their
chapters.

## Inventory — honest status against the scope's list of ten

| notebook | status |
|---|---|
| 01_building_a_panel | **shipped** |
| 02_point_in_time_financials | **shipped** |
| 03_value_sort | **shipped**, in three editions — English, Spanish at `es/03_ordenamiento_por_valor.ipynb`, and Portuguese at `pt/03_ordenacao_por_valor.ipynb` (full translations: prose, code identifiers, outputs, chart labels; the pt edition uses P/VPA, the Brazilian term for price-to-book). The Tarea 1 companion: per-December PIT rebuilds, P/B quintiles, forward returns, and the honesty section. (A momentum leg stays blocked on the registry placeholder.) |
| 04_event_study | **shipped** |
| 05_portfolio_optimization | **shipped** — min-variance, capped max-Sharpe, a hand-traced frontier (the external surface deliberately has no frontier endpoint), and the estimator-fingerprint exercise. Uses `/api/content/portfolio/v1`. |
| 06_black_litterman | **shipped** — historical-mean vs equilibrium-prior vs viewed books; the benchmark-sensitivity measurement; the honesty section names the dials (δ, τ, confidence) the external surface pins to defaults. |
| 07_dcf_valuation | **shipped** — defaults-with-sources, the beta menu, WACC × g grid, reverse DCF both directions. `/api/valuation` accepts API keys since 2026-08-28 (it was session-only). |
| 08_fixed_income_duration | **cannot be written honestly** — the platform has no bond pricing engine; per-bond duration/convexity are ingested where supplied, not computed. A notebook implying otherwise would misteach. |
| 09_fund_holdings_analysis | **shipped** — 13F book (additive-amendment doctrine), N-PORT ETF book, within-kind holders, and rankings from as-reported monthly returns — including the endpoint's two deliberate refusals. |
| 10_cross_country_equities | **shipped** |

## Language editions

Every shipped notebook (01–07, 09, 10) ships in three editions — English
at the root, Spanish under `es/`, Portuguese under `pt/`. These are full
translations (prose, code identifiers, printed strings, chart labels),
not caption swaps; API payload keys and response fields stay verbatim
because they are the wire contract. Every edition is executed end to end
against the live API before shipping.

## Getting the package

Everything here is self-hosted on the platform (no PyPI while Academia is
staging): [edi-academic-package.zip](https://api.edi.finance/static/academic/edi-academic-package.zip)
bundles the SDK wheel, all notebook editions, the Excel workbooks, and the
twelve methodology chapters. The SDK alone installs with

    pip install https://api.edi.finance/static/academic/edifinance-0.1.1-py3-none-any.whl

(works on Colab). The developer portal's Research section links the same
files. Rebuild/redeploy with `fin-platform-api/scripts/build_academic_package.py`.

## Running

- **Locally**: Jupyter with `pandas`, `matplotlib`, `requests`. Optionally the
  `edifinance` package (distributed with the academic package).
- **Colab**: upload the notebook; the setup cell prompts for the API key
  (or set `EDI_API_KEY` as a Colab secret). No other installs needed —
  the fallback path uses `requests`, which Colab ships.
- While Academia is in staging, research endpoints require the research role
  on the account behind the key.