Options Research Lab

A learning-first options research project that connects derivations, tested models, controlled experiments, research notes, and an interactive frontend.

The current lab implements European Black–Scholes call/put pricing, Delta, Gamma, Vega, Theta, Rho, a put–call parity diagnostic, and a spot-price profile. The full learning and research sequence is defined in pipeline.md.

Current lab

• Analytic pricing core with no web-framework dependency.
• FastAPI endpoint with validated request and response contracts.
• React/TypeScript research interface with explicit Greek unit conventions.
• Price, Delta, and Gamma profiles across the same fixed-input spot grid.
• Numerical benchmark, finite-difference, parity, validation, API, and UI tests.
• Research record: docs/research/001-black-scholes-greeks.md.

Repository structure

src/options_lab/domain/   pricing models and research calculations
src/options_lab/api/      HTTP transport and validation
tests/                    Python domain and API tests
frontend/src/             interactive research interface
docs/research/            experiment records and interpretations
docs/plans/               architecture and design decisions
pipeline.md               staged learning and research roadmap

Setup

Requirements: Python 3.11+, uv, and Node.js 20+.

uv sync --dev
cd frontend
npm install

Run locally

Start the API from the repository root:

uv run uvicorn options_lab.api.app:app --reload --host 127.0.0.1 --port 8000

In a second terminal, start the frontend:

cd frontend
npm run dev

Open http://127.0.0.1:5173. Interactive API documentation is available at http://127.0.0.1:8000/docs.

Verify

uv run pytest -q
uv run ruff check src tests
cd frontend
npm test -- --run
npm run build

Inputs use annual decimal rates and volatility. Displayed Vega and Rho are per one percentage-point change; Theta is per calendar day. These conventions are part of the API response so downstream views do not have to infer them.