From Zero: A Personal AI Research Monorepo

A modern AI research monorepo designed for from-zero deep learning exploration, model architecture design, and experimental applications. Built on a cutting-edge Python tool stack using Python 3.12+, Astral's uv workspace, Ruff, and Ty.

---

🎯 Project Scope

This monorepo serves as a collaborative sandbox and a library for core machine learning components, neural networks, and domain-specific applications:

• From-Zero Architecture Implementation: Pure PyTorch implementations of attention heads, multi-head attention (MHA), grouped-query attention (GQA), mixture of experts (MoE), rotary positional embeddings (RoPE), transformers, loss functions, and vision models.
• Flexible Training Infrastructure: Custom training abstractions, schedulers, and metrics, designed to scale seamlessly from single-device environments to multi-GPU FSDP (Fully Sharded Data Parallel) setups.
• Independent Application Sandboxes: Modular projects leveraging the shared library code for target tasks (such as Speculative Decoding and vision-focused training).

---

Project Structure

The workspace follows a strict Library vs. Applications layout:

├── research/                  # Core Shared Library Code (PEP 561 typed)
│   ├── ...
│
├── projects/                  # Modular Workspace Application Projects
│   ├── ...
│
├── tests/                     # Standardized PyTest Unit Testing Directory
├── docs/                      # Reference manuals and guides generated by ProperDocs
├── scripts/                   # Workspace-wide PEP 723 inline-metadata scripts
├── properdocs.yml             # ProperDocs Static Site Generator Configuration
├── ruff.toml                  # Standalone Ruff configuration tailored for ML research
├── mypy.ini                   # Standalone Mypy configuration for ML research
├── pyproject.toml             # Root uv workspace and dependency configuration
└── justfile                   # Task runner commands replacing Makefile

---

🛠️ Tool Stack

• Runtime: Python 3.12+
• Workspace & Package Manager: uv (speeds up installs and locks full monorepo dependencies in a unified uv.lock).
• Build Backend: uv-build (lightweight and fast package compiler).
• Task Runner: just (provides cross-platform command recipes).
• Formatter & Linter: Ruff (sensible, lightning-fast formatting and lint rules for deep learning notation).
• Static Type Checker: Mypy (configured with loose, research-friendly rules for easy prototyping).
• Documentation: ProperDocs with the styled shadcn theme, including search and excalidraw plugins.

---

Quick Start & Development Workflow

All standard tasks are run through just. Make sure you have uv and just installed on your machine.

1. Installation

Create your local virtual environment and synchronize all workspace libraries, application projects, and optional packages:

just install

2. Formatting & Linting

Format and auto-fix all fixable issues instantly:

just fmt

Perform static analysis and lint checks:

just lint

3. Running Tests

Run the pytest test suite:

just test

4. Documentation

Build the complete ProperDocs static reference site:

just docs-build

Preview the documentation server locally at http://127.0.0.1:8000:

just docs-preview