mirror of
https://github.com/MLSysBook/TinyTorch.git
synced 2026-07-10 16:56:14 -05:00
docs: Major cleanup - 46 → 12 essential docs
MASSIVE DOCUMENTATION CLEANUP: - Reduced from 46 docs to 12 essential files - Archived 34 outdated planning and analysis documents ✅ KEPT (Essential for current operations): - STUDENT_QUICKSTART.md - Student onboarding - INSTRUCTOR_GUIDE.md - Instructor setup - cifar10-training-guide.md - North star achievement - tinytorch-assumptions.md - Complexity framework (NEW) - tinytorch-textbook-alignment.md - Academic alignment - NBGrader integration docs (3 files) - Development standards (3 files) - docs/README.md - Navigation guide (NEW) 🗑️ ARCHIVED (Completed/outdated planning): - All optimization-modules-* planning docs - All milestone-* system docs - All tutorial-master-plan and analysis docs - Module reordering and structure analysis - Agent setup and workflow case studies RESULT: Clean, focused documentation structure Only active, current docs remain - easy to find what you need!
This commit is contained in:
Vijay Janapa Reddi
@@ -1,116 +0,0 @@
|
||||
# Universal Agent Setup Prompt for Any Project
|
||||
|
||||
Copy and paste this prompt to set up the same agent orchestration system in your other projects:
|
||||
|
||||
---
|
||||
|
||||
## 🤖 Multi-Agent Team Setup Request
|
||||
|
||||
I want to set up a professional multi-agent workflow system for this project. Please create a `CLAUDE.md` file in the project root that establishes the following:
|
||||
|
||||
### 1. **Agent Team Structure**
|
||||
Create these specialized agents with clear responsibilities:
|
||||
|
||||
```
|
||||
Workflow Coordinator (Team Lead)
|
||||
├── Architect (Strategy & Design)
|
||||
├── Developer (Implementation)
|
||||
├── Quality Assurance (Testing & Validation)
|
||||
└── Documentation (Communication & Docs)
|
||||
```
|
||||
|
||||
### 2. **Mandatory QA Testing Protocol**
|
||||
- QA Agent MUST test ALL code changes before ANY commit
|
||||
- QA has veto power - can block commits if tests fail
|
||||
- Developer CANNOT mark tasks complete without QA approval
|
||||
- Every code change triggers automatic QA review
|
||||
- Create comprehensive test suites that check:
|
||||
- Code imports without errors
|
||||
- Functions/classes work correctly
|
||||
- No syntax errors present
|
||||
- All tests pass successfully
|
||||
|
||||
### 3. **Standard Workflow Pattern**
|
||||
Enforce this sequence for EVERY code update:
|
||||
|
||||
1. **Planning Phase** (Coordinator + Architect)
|
||||
- Define objectives and structure
|
||||
2. **Implementation Phase** (Developer)
|
||||
- Write code following specifications
|
||||
- MUST notify QA when done
|
||||
3. **Testing Phase** (QA) - MANDATORY
|
||||
- Run comprehensive tests
|
||||
- Block progress if tests fail
|
||||
4. **Documentation Phase** (Documentation)
|
||||
- Add clear documentation
|
||||
5. **Review Phase** (Coordinator)
|
||||
- Verify all agents completed tasks
|
||||
- Ensure QA tests passed
|
||||
|
||||
### 4. **Agent Communication Rules**
|
||||
- Structured handoffs between agents
|
||||
- Each handoff includes checklist of completed/pending items
|
||||
- Test results must accompany all code changes
|
||||
- Clear accountability for each agent
|
||||
|
||||
### 5. **Git Workflow Standards**
|
||||
- Always use feature branches (never commit to main)
|
||||
- Test before committing
|
||||
- Descriptive commit messages
|
||||
- Clean commit history
|
||||
|
||||
### 6. **Enforcement Mechanisms**
|
||||
- File should be named `CLAUDE.md` in project root
|
||||
- Claude reads this automatically at session start
|
||||
- Rules override default behavior
|
||||
- QA testing cannot be skipped
|
||||
|
||||
### 7. **Project-Specific Customization**
|
||||
Adapt the agents for this specific project:
|
||||
- What type of project is this? [Web app, ML system, API, etc.]
|
||||
- What testing frameworks should QA use?
|
||||
- What documentation standards apply?
|
||||
- Any special requirements?
|
||||
|
||||
Please create the CLAUDE.md file with these specifications, ensuring that:
|
||||
1. Every future Claude session will automatically follow these rules
|
||||
2. QA testing is mandatory and cannot be bypassed
|
||||
3. The agent team works as a cohesive unit
|
||||
4. Code quality is maintained through enforced testing gates
|
||||
|
||||
Also create any supporting test files or scripts needed for the QA agent to properly validate code changes.
|
||||
|
||||
---
|
||||
|
||||
## 📋 Quick Setup Instructions
|
||||
|
||||
1. **Copy the above prompt**
|
||||
2. **Paste it in your other Claude project**
|
||||
3. **Claude will create the CLAUDE.md file**
|
||||
4. **The system activates automatically in future sessions**
|
||||
|
||||
## 🎯 Benefits You'll Get
|
||||
|
||||
- ✅ Automatic QA testing before commits
|
||||
- ✅ Structured agent teamwork
|
||||
- ✅ Consistent code quality
|
||||
- ✅ Clear accountability
|
||||
- ✅ Professional development workflow
|
||||
- ✅ No broken code in your repository
|
||||
|
||||
## 💡 Pro Tips
|
||||
|
||||
- Customize agent names for your project type
|
||||
- Add project-specific testing requirements
|
||||
- Include your preferred git workflow
|
||||
- Specify documentation standards
|
||||
- Add any unique project rules
|
||||
|
||||
## 🔄 Verification
|
||||
|
||||
After setup, test by asking Claude:
|
||||
- "What are the agent responsibilities?"
|
||||
- "Can you commit without QA testing?"
|
||||
- "Show me the workflow for updating code"
|
||||
|
||||
Claude should respond following the established protocols.
|
||||
@@ -1,214 +0,0 @@
|
||||
# 📦 Package Manager Agent Specification
|
||||
|
||||
## Overview
|
||||
The Package Manager Agent is a critical specialist responsible for ensuring all student-developed modules properly integrate into the complete TinyTorch package. This agent bridges the gap between individual module development and a working, installable ML framework.
|
||||
|
||||
## Current System Analysis
|
||||
|
||||
### 🔍 What Exists Now:
|
||||
1. **Module Structure**:
|
||||
- Development files: `modules/source/XX_module/module_dev.py`
|
||||
- Package destination: `tinytorch/core/module.py`
|
||||
- Export system: Using nbdev with `#| default_exp` directives
|
||||
|
||||
2. **Build Tools**:
|
||||
- `tito export` - Converts .py → .ipynb → tinytorch package
|
||||
- `tito package` - Package management commands
|
||||
- nbdev integration for notebook → package conversion
|
||||
|
||||
3. **Testing**:
|
||||
- Integration tests in `/tests/` directory
|
||||
- Individual module tests within each module
|
||||
- No systematic package validation after export
|
||||
|
||||
4. **Issues Identified**:
|
||||
- No automated verification that exported modules work together
|
||||
- Integration tests in root folder (should be better organized)
|
||||
- No clear dependency resolution between modules
|
||||
- Missing validation that all module pieces "click together"
|
||||
|
||||
## 🎯 Package Manager Agent Responsibilities
|
||||
|
||||
### Primary Duties:
|
||||
|
||||
1. **Module Integration Validation**
|
||||
- Verify all module exports are compatible
|
||||
- Check inter-module dependencies
|
||||
- Ensure no naming conflicts or circular imports
|
||||
- Validate that all pieces form a complete system
|
||||
|
||||
2. **Build Pipeline Management**
|
||||
```python
|
||||
# The agent ensures this workflow:
|
||||
Student Code (module_dev.py)
|
||||
↓ [Convert]
|
||||
Notebook (.ipynb)
|
||||
↓ [Export]
|
||||
Package Module (tinytorch/core/module.py)
|
||||
↓ [Validate]
|
||||
Working TinyTorch Package
|
||||
```
|
||||
|
||||
3. **Dependency Resolution**
|
||||
- Map module dependencies (e.g., Tensor → Autograd → Training)
|
||||
- Ensure proper import order
|
||||
- Verify all required components are present
|
||||
- Check version compatibility
|
||||
|
||||
4. **Package Testing**
|
||||
- Run integration tests after EVERY export
|
||||
- Verify the complete package can be imported
|
||||
- Test that all modules work together
|
||||
- Validate student can use the final system
|
||||
|
||||
5. **Export Coordination**
|
||||
- Work with Module Developer to ensure export tags are correct
|
||||
- Verify `#| default_exp` directives match expected structure
|
||||
- Ensure consistent naming conventions
|
||||
- Manage module versioning
|
||||
|
||||
## 🔄 Workflow Integration
|
||||
|
||||
### When Package Manager Agent is Invoked:
|
||||
|
||||
1. **After Module Development**
|
||||
```
|
||||
Module Developer completes work
|
||||
↓
|
||||
QA Agent tests module
|
||||
↓
|
||||
Package Manager validates export and integration ← YOU ARE HERE
|
||||
↓
|
||||
Workflow Coordinator approves
|
||||
```
|
||||
|
||||
2. **During Export Process**
|
||||
- Pre-export: Verify module is ready for export
|
||||
- During export: Monitor for issues
|
||||
- Post-export: Validate integration
|
||||
- Final check: Ensure complete system works
|
||||
|
||||
3. **For System Integration**
|
||||
- Student completes Module 1-16
|
||||
- Package Manager assembles complete TinyTorch
|
||||
- Runs comprehensive system tests
|
||||
- Validates students can use their creation
|
||||
|
||||
## 🛠️ Specific Implementation Tasks
|
||||
|
||||
### 1. Export Validation Pipeline
|
||||
```bash
|
||||
# Package Manager ensures this sequence:
|
||||
tito export --all # Export all modules
|
||||
tito test integration # Run integration tests
|
||||
tito package validate # Verify complete package
|
||||
tito package build # Build installable package
|
||||
```
|
||||
|
||||
### 2. Module Dependency Map
|
||||
```python
|
||||
DEPENDENCY_GRAPH = {
|
||||
"tensor": [],
|
||||
"activations": ["tensor"],
|
||||
"layers": ["tensor"],
|
||||
"dense": ["tensor", "layers"],
|
||||
"spatial": ["tensor", "layers"],
|
||||
"attention": ["tensor", "layers"],
|
||||
"dataloader": ["tensor"],
|
||||
"autograd": ["tensor"],
|
||||
"optimizers": ["tensor", "autograd"],
|
||||
"training": ["tensor", "layers", "optimizers", "dataloader"],
|
||||
"compression": ["tensor", "layers"],
|
||||
"kernels": ["tensor"],
|
||||
"benchmarking": ["all"],
|
||||
"mlops": ["all"],
|
||||
"capstone": ["all"]
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Integration Test Organization
|
||||
```
|
||||
tests/
|
||||
├── unit/ # Individual module tests
|
||||
├── integration/ # Inter-module tests
|
||||
├── system/ # Complete system tests
|
||||
└── validation/ # Package validation tests
|
||||
```
|
||||
|
||||
### 4. Validation Checklist
|
||||
- [ ] All modules export successfully
|
||||
- [ ] No import errors in tinytorch package
|
||||
- [ ] All integration tests pass
|
||||
- [ ] Complete ML pipeline works (data → model → train → predict)
|
||||
- [ ] Package can be pip installed
|
||||
- [ ] Documentation is complete
|
||||
|
||||
## 🚨 Critical Rules for Package Manager
|
||||
|
||||
1. **NEVER allow broken exports to reach the package**
|
||||
2. **MUST validate after EVERY module change**
|
||||
3. **Block package build if integration tests fail**
|
||||
4. **Ensure backward compatibility**
|
||||
5. **Maintain clean module boundaries**
|
||||
|
||||
## 📝 Communication Protocol
|
||||
|
||||
### With Module Developer:
|
||||
- "Module X export validation failed: [specific issue]"
|
||||
- "Please add #| default_exp directive to module"
|
||||
- "Module dependencies not satisfied"
|
||||
|
||||
### With QA Agent:
|
||||
- "Running integration tests for exported modules"
|
||||
- "Package validation requires these tests to pass"
|
||||
- "Found integration issue between Module X and Y"
|
||||
|
||||
### With Workflow Coordinator:
|
||||
- "Package build successful, all modules integrated"
|
||||
- "Integration failed, blocking release"
|
||||
- "Ready for student testing"
|
||||
|
||||
## 🎯 Success Metrics
|
||||
|
||||
The Package Manager succeeds when:
|
||||
1. Students can run: `pip install -e .` and it works
|
||||
2. All modules are accessible via `from tinytorch import *`
|
||||
3. Complete ML pipeline runs without errors
|
||||
4. Integration tests achieve 100% pass rate
|
||||
5. Students can build end-to-end models using their code
|
||||
|
||||
## 🔧 Implementation Commands
|
||||
|
||||
### New tito commands needed:
|
||||
```bash
|
||||
tito package validate # Validate all exports
|
||||
tito package test # Run integration tests
|
||||
tito package build # Build complete package
|
||||
tito package verify # Verify student can use it
|
||||
tito package report # Generate integration report
|
||||
```
|
||||
|
||||
## 📋 Handoff Requirements
|
||||
|
||||
When Package Manager completes work:
|
||||
- [ ] Export validation report
|
||||
- [ ] Integration test results
|
||||
- [ ] Dependency graph verification
|
||||
- [ ] Package build status
|
||||
- [ ] Student usability confirmation
|
||||
|
||||
## 🚀 Why This Matters
|
||||
|
||||
The Package Manager ensures that the educational journey results in a **working ML framework** that students built themselves. Without this agent, students might have great individual modules that don't work together - defeating the purpose of building a complete system.
|
||||
|
||||
This agent is the difference between:
|
||||
- ❌ 16 separate modules that don't integrate
|
||||
- ✅ One cohesive TinyTorch framework that actually works
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Add to CLAUDE.md** agent hierarchy
|
||||
2. **Implement validation commands** in tito
|
||||
3. **Reorganize tests** into proper structure
|
||||
4. **Create automated integration pipeline**
|
||||
5. **Add to agent orchestration workflow**
|
||||
@@ -1,142 +0,0 @@
|
||||
# TinyTorch Shared Testing Pattern
|
||||
|
||||
## 🎯 Problem Solved
|
||||
|
||||
Previously, each module had inconsistent test summaries and duplicated formatting code. Now all modules use **shared testing utilities** for:
|
||||
|
||||
✅ **Perfect Consistency** - All modules have identical output format
|
||||
✅ **Zero Code Duplication** - Testing utilities are shared across all modules
|
||||
✅ **Easy Maintenance** - Changes only need to be made in one place
|
||||
✅ **Scalable** - Works for any number of modules and tests
|
||||
|
||||
## 📋 Usage Pattern
|
||||
|
||||
### 1. Import the Shared Utilities
|
||||
|
||||
```python
|
||||
from tinytorch.utils.testing import create_test_runner
|
||||
```
|
||||
|
||||
### 2. Write Your Test Functions
|
||||
|
||||
```python
|
||||
def test_feature_a():
|
||||
"""Test feature A functionality."""
|
||||
# Your test code here
|
||||
assert something_works(), "Feature A should work"
|
||||
print("✅ Feature A tests passed!")
|
||||
|
||||
def test_feature_b():
|
||||
"""Test feature B functionality."""
|
||||
# Your test code here
|
||||
assert something_else_works(), "Feature B should work"
|
||||
print("✅ Feature B tests passed!")
|
||||
```
|
||||
|
||||
### 3. Register and Run Tests
|
||||
|
||||
```python
|
||||
if __name__ == "__main__":
|
||||
# Create test runner for this module
|
||||
test_runner = create_test_runner("YourModule")
|
||||
|
||||
# Register all tests
|
||||
test_runner.register_test("Feature A", test_feature_a)
|
||||
test_runner.register_test("Feature B", test_feature_b)
|
||||
|
||||
# Run all tests with consistent output
|
||||
success = test_runner.run_all_tests()
|
||||
```
|
||||
|
||||
## 🎭 Standard Output Format
|
||||
|
||||
Every module produces **identical output**:
|
||||
|
||||
```
|
||||
🔬 Running YourModule Module Tests...
|
||||
==================================================
|
||||
🧪 Testing Feature A... ✅ PASSED
|
||||
🧪 Testing Feature B... ✅ PASSED
|
||||
|
||||
============================================================
|
||||
🎯 YOURMODULE MODULE TESTING COMPLETE
|
||||
============================================================
|
||||
🎉 CONGRATULATIONS! All tests passed!
|
||||
|
||||
✅ YourModule Module Status: 2/2 tests passed (100%)
|
||||
|
||||
📊 Detailed Results:
|
||||
Feature A: ✅ PASSED
|
||||
Feature B: ✅ PASSED
|
||||
|
||||
📈 Progress: YourModule Module ✓ COMPLETE
|
||||
|
||||
🚀 Ready for the next module!
|
||||
```
|
||||
|
||||
## 🏗️ Architecture
|
||||
|
||||
### Shared Utilities Location
|
||||
- **Main utilities**: `tinytorch/utils/testing.py`
|
||||
- **Import from**: `from tinytorch.utils.testing import create_test_runner`
|
||||
|
||||
### ModuleTestRunner Class
|
||||
The core class that provides:
|
||||
- `register_test(name, function)` - Register test functions
|
||||
- `run_all_tests()` - Execute all tests with consistent output
|
||||
- Error handling and detailed reporting
|
||||
|
||||
## 📈 Migration Guide
|
||||
|
||||
To migrate an existing module:
|
||||
|
||||
### Before (Inconsistent)
|
||||
```python
|
||||
# Old way - inconsistent format
|
||||
def test_something():
|
||||
# test code
|
||||
pass
|
||||
|
||||
# Manual summary - different across modules
|
||||
print("Some tests passed!")
|
||||
```
|
||||
|
||||
### After (Consistent)
|
||||
```python
|
||||
# New way - consistent format
|
||||
from tinytorch.utils.testing import create_test_runner
|
||||
|
||||
def test_something():
|
||||
# test code
|
||||
print("✅ Something tests passed!")
|
||||
|
||||
if __name__ == "__main__":
|
||||
test_runner = create_test_runner("ModuleName")
|
||||
test_runner.register_test("Something", test_something)
|
||||
success = test_runner.run_all_tests()
|
||||
```
|
||||
|
||||
## ✅ Benefits Achieved
|
||||
|
||||
1. **Consistency**: All modules have identical testing output
|
||||
2. **No Duplication**: Testing utilities are shared across modules
|
||||
3. **Easy Maintenance**: Changes to format only need to be made in one place
|
||||
4. **Scalable**: Works for any number of tests and modules
|
||||
5. **Professional**: Clean, standardized output suitable for educational use
|
||||
6. **Error Handling**: Detailed error reporting for failed tests
|
||||
|
||||
## 🚀 Implementation Status
|
||||
|
||||
- **✅ Shared utilities created**: `tinytorch/utils/testing.py`
|
||||
- **✅ Documentation complete**: Usage patterns and examples
|
||||
- **✅ Testing verified**: Confirmed working with example modules
|
||||
- **⏳ Migration pending**: Apply pattern to all existing modules
|
||||
|
||||
## 🔧 Next Steps
|
||||
|
||||
1. **Apply to all modules**: Migrate existing modules to use shared pattern
|
||||
2. **Test thoroughly**: Ensure all modules work with new pattern
|
||||
3. **Update documentation**: Module-specific docs reference shared pattern
|
||||
4. **Commit changes**: Save the improved testing infrastructure
|
||||
|
||||
This shared testing pattern eliminates code duplication while ensuring perfect consistency across all TinyTorch modules!
|
||||
Reference in New Issue
Block a user