# Deep Learning for Demand Forecasting

This project is a CS230-inspired deep learning curriculum focused on demand forecasting. It assumes CS and classical ML fundamentals, then moves from neural-network basics toward senior-level modeling, evaluation, strategy, production readiness, and Data Scientist portfolio quality.

The curriculum uses Stanford CS230's public syllabus as a structural reference: neural-network foundations, optimization and regularization, ML strategy, CNNs, sequence models, attention/transformers, interpretability, project work, and research habits. Source consulted: https://cs230.stanford.edu/syllabus/

The supplemental modules were added after a hiring-manager review for Data Scientist readiness. See `HIRING_MANAGER_REVIEW.md` for the gap analysis and rationale.

## Setup

```bash
uv sync
uv run python -m ipykernel install --user --name deep-learning-demand --display-name "Python (deep-learning-demand)"
uv run jupyter lab
```

## Curriculum

Notebooks live in `notebooks/` and are numbered in the intended order:

1. `00_course_orientation.ipynb`
2. `01_synthetic_demand_data_generation_and_validation.ipynb`
3. `02_forecasting_framing_and_baselines.ipynb`
4. `03_neural_network_basics_from_scratch.ipynb`
5. `04_pytorch_mlp_forecaster.ipynb`
6. `05_optimization_regularization_and_initialization.ipynb`
7. `06_ml_strategy_splits_and_error_analysis.ipynb`
8. `07_convolutions_for_temporal_patterns.ipynb`
9. `08_sequence_models_rnn_gru_lstm.ipynb`
10. `09_attention_and_transformers.ipynb`
11. `10_probabilistic_forecasting_and_quantiles.ipynb`
12. `11_global_models_and_entity_embeddings.ipynb`
13. `12_hyperparameter_tuning_and_experiments.ipynb`
14. `13_ralph_loops_for_deep_learning_iteration.ipynb`
15. `14_interpretability_and_diagnostics.ipynb`
16. `15_robustness_drift_and_monitoring.ipynb`
17. `16_system_design_and_deployment_readiness.ipynb`
18. `17_capstone_senior_readiness_project.ipynb`
19. `18_sql_feature_engineering_and_data_contracts.ipynb`
20. `19_experimentation_and_causal_inference_for_promotions.ipynb`
21. `20_hierarchical_forecasting_and_reconciliation.ipynb`
22. `21_decision_optimization_inventory_and_business_impact.ipynb`
23. `22_portfolio_interview_readiness_and_case_defense.ipynb`

## Useful Commands

```bash
uv lock
uv run python tools/generate_notebooks.py
uv run python tools/validate_notebooks.py
uv run python -m compileall src tools
uv run pytest
```

`tools/validate_notebooks.py` enforces notebook quality gates: sequential lesson numbers, matching titles, required front matter, detailed explanations before every code cell, lesson recaps, exercises, clean code cells, no committed outputs, and code-cell syntax. See `NOTEBOOK_QUALITY_AUDIT.md` for the audit standard.

## Repository Layout

```text
.
├── AGENTS.md
├── NOTEBOOK_QUALITY_AUDIT.md
├── README.md
├── notebooks/
├── pyproject.toml
├── src/demand_forecasting_curriculum/
├── tests/
└── tools/
```