以 NumPy 從零實作經典機器學習與深度學習模型
Python 3.12.4 | MIT License

本專案探索「完全不依賴高階框架」的 AI 實作路線，
透過 NumPy 向量化 ＋ 手寫梯度／反向傳播，
深入理解演算法數學本質、數值穩定性與效能瓶頸。

⚠️ 性能警告：純 NumPy 訓練大型網路效能遠低於 PyTorch/JAX；本專案以學術／教學為主，不建議直接用於生產環境。

• 零依賴：僅需 NumPy；執行期不額外安裝任何機器學習框架
• 單元測試覆蓋：每個演算法皆附 pytest 測例與梯度檢查
• Sphinx 文件：API 自動化生成功能可選
• CI/CD：GitHub Actions 針對 lint / type check / test 全流程把關
• 可擴充：模組化 Layer / Optimizer 介面，方便加新模型

# 1. 取得程式碼
git clone https://github.com/your-username/ai-from-scratch.git
cd ai-from-scratch

# 2. 建立與啟用虛擬環境（任選）
python -m venv .venv && source .venv/bin/activate   # Windows 改用 .venv\Scripts\activate

# 3. 安裝執行期依賴
pip install -r requirements.txt

# 4. （可選）安裝開發／測試工具
pip install -e .[dev]

# 5. 執行最小驗證
python -m src.examples.mnist_mlp

ai-from-scratch/
├── src/               ← 主要程式碼包
│   ├── linalg/        ← 線性代數封裝
│   ├── layers/        ← 神經網路層 (Dense, Conv, ...)
│   ├── optim/         ← 優化器 (SGD, Adam, ...)
│   ├── models/        ← 高階模型封裝
│   └── datasets/      ← 資料前處理與載入器
├── tests/             ← pytest 測例
├── examples/          ← 範例腳本 (mnist_mlp.py 等)
├── docs/              ← Sphinx 文件（可選）
├── requirements.txt   ← 執行期依賴（僅 NumPy）
├── pyproject.toml     ← 專案與工具設定
└── .gitignore

詳細時程與 Issue 追蹤請見 docs/roadmap.md。

# 只跑單元測試
pytest -q

# Lint 与型別檢查
ruff src tests
mypy src

所有 Pull Request 必須 CI 綠燈 方可合併，守門規則見 .github/workflows/ci.yml。

1. Fork → 新建 feature branch → 提交 PR

2. 請遵守 CONTRIBUTING.md：

   • 嚴禁 import torch, jax, tensorflow 等框架
   • 新增模組須附單元測試 ＋ 文件註解

3. 提交前執行 pre-commit run --all-files 保持程式碼風格一致

歡迎 Issue／PR，亦歡迎對數值穩定性與效能提出質疑。

本專案採用 MIT License，詳見 LICENSE。

使用或修改本程式碼請保留原作者資訊與授權條款。若有商業應用需求，請遵守 MIT 條款或額外聯繫作者。

• 將上述內容存為 README.md，並依自身 GitHub 使用者名稱與實際目錄調整連結（如徽章 URL、repo 路徑）。
• 若後續新增更多執行期依賴，請同步更新 requirements.txt 與文件說明。