Metadata-Version: 2.4
Name: eggnest
Version: 0.1.0
Summary: EggNest - Monte Carlo financial planning with real tax calculations
Author-email: EggNest <hello@eggnest.co>
License: MIT
Keywords: cli,finance,monte-carlo,planning,retirement,simulation
Requires-Python: >=3.11
Requires-Dist: click>=8.0
Requires-Dist: fastapi>=0.109.0
Requires-Dist: httpx>=0.26.0
Requires-Dist: numpy-financial>=1.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: policyengine-us>=1.0.0
Requires-Dist: pydantic-settings>=2.1.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: uvicorn[standard]>=0.27.0
Provides-Extra: cli
Requires-Dist: python-jose[cryptography]>=3.3.0; extra == 'cli'
Requires-Dist: supabase>=2.0.0; extra == 'cli'
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: enhanced
Requires-Dist: arch>=6.0.0; extra == 'enhanced'
Requires-Dist: statsmodels>=0.14.0; extra == 'enhanced'
Requires-Dist: yfinance>=0.2.0; extra == 'enhanced'
Description-Content-Type: text/markdown

# EggNest

Monte Carlo retirement simulation with real tax calculations.

**[eggnest.co](https://eggnest.co)** | **[app.eggnest.co](https://app.eggnest.co)**

## What is EggNest?

EggNest is a retirement planning simulator that runs thousands of Monte Carlo simulations to show you the probability distribution of outcomes—not just a single "expected" result. Unlike other calculators, EggNest uses PolicyEngine to calculate actual federal and state taxes, giving you accurate after-tax projections.

## Features

- **Monte Carlo Simulation**: 10,000+ scenarios showing the range of possible outcomes
- **Real Tax Calculations**: Federal + state income tax via PolicyEngine-US (not estimates)
- **Social Security Optimization**: Model different claiming ages (62-70)
- **Spouse Support**: Joint simulation with mortality modeling
- **Annuity Comparison**: Compare guaranteed income vs. portfolio withdrawals
- **What-If Scenarios**: Quickly explore spending and savings changes

## Architecture

```
eggnest/
├── app/                     # React frontend (app.eggnest.co)
│   └── src/
│       ├── components/      # Wizard, SimulationProgress
│       ├── pages/           # SimulatorPage
│       └── lib/api.ts       # API client with SSE streaming
├── web/                     # Landing page (eggnest.co)
│   └── src/pages/           # HomePage, ThesisPage
├── api/                     # Python FastAPI backend
│   └── eggnest/
│       ├── simulation.py    # MonteCarloSimulator (vectorized NumPy)
│       ├── tax.py           # PolicyEngine-US integration
│       └── models.py        # Pydantic models
└── supabase/                # Database migrations
```

## Development

### Backend (Python/FastAPI)
```bash
cd api
uv venv && uv pip install -e ".[dev]"
uv run uvicorn main:app --reload --port 8000
```

### Frontend (React/Vite)
```bash
cd app
npm install
npm run dev  # Runs on port 5174
```

### Landing Page
```bash
cd web
npm install
npm run dev  # Runs on port 5173
```

## Stack

- **Frontend**: React 19 + Vite + TypeScript + Plotly
- **Backend**: Python + FastAPI + NumPy + PolicyEngine-US
- **Database**: Supabase (Postgres + Auth)
- **Hosting**: Vercel (frontend) + Modal (API)
- **Tax Engine**: [PolicyEngine-US](https://github.com/PolicyEngine/policyengine-us)

## License

MIT
