DEV_SETUP.md

Development Environment Setup

✅ Environment Ready!

Your development environment is configured and ready for Blender addon development.

📦 What's Installed

• Python 3.13.5 (via virtual environment)
• Blender Python API (fake-bpy-module-4.2 for autocomplete)
• Testing: pytest, pytest-cov, pytest-mock, pytest-benchmark
• Code Quality: black, pylint, mypy, flake8, pre-commit
• AI Integration: anthropic SDK for Claude API
• Documentation: Sphinx
• Scientific: NumPy, SciPy (for geometry calculations)

🚀 Quick Start

Activate Environment

Windows (CMD):

activate.bat

Windows (Git Bash) / Linux / macOS:

source activate.sh

Verify Setup

python -c "import bpy; print('Blender API available')"
pytest --version
black --version

🛠️ Development Workflow

1. Code Formatting

black sulo_ai/

2. Linting

pylint sulo_ai/
flake8 sulo_ai/

3. Type Checking

mypy sulo_ai/

4. Run Tests

# All tests
pytest tests/

# Unit tests only
pytest tests/unit/

# With coverage
pytest tests/ --cov=sulo_ai --cov-report=html

5. Format & Lint All

# Run all code quality checks
black sulo_ai/ tests/
pylint sulo_ai/
mypy sulo_ai/
flake8 sulo_ai/

📁 Project Structure

sulo-ai/
├── sulo_ai/          # Main addon code (goes into Blender)
│   ├── core/         # Pure Python algorithms (no Blender deps)
│   ├── blender/      # Blender-specific code
│   ├── ai/           # Claude API integration
│   ├── ui/           # User interface
│   └── utils/        # Utilities
├── tests/            # Test suite
├── venv/             # Virtual environment (gitignored)
└── requirements.txt  # Python dependencies

🎨 Blender Integration

Install Addon in Blender

Option 1: Symlink (Development)

# Run the install script
bash scripts/install_dev.sh

Option 2: Manual Installation

1. In Blender: Edit → Preferences → Add-ons
2. Click "Install"
3. Navigate to sulo_ai/ folder
4. Select __init__.py
5. Enable "Sulo AI"

Reload Addon During Development

In Blender Python Console:

import bpy
bpy.ops.script.reload()

📚 Blender Versions Supported

• ✅ Blender 4.2 (primary development target)
• ✅ Blender 4.5 (tested compatible)
• ✅ Blender 4.0+ (should work)

🔍 IDE Setup

VS Code (Recommended)

Install extensions:

• Python (Microsoft)
• Pylance (Microsoft)
• Blender Development (Jacques Lucke)

Your environment already has fake-bpy-module-4.2 installed, so you'll get:

• ✅ Autocomplete for Blender API
• ✅ Type hints for bpy module
• ✅ Inline documentation

PyCharm

1. File → Settings → Project → Python Interpreter
2. Select venv/Scripts/python.exe
3. PyCharm will detect all installed packages

🧪 Testing

Run Specific Tests

# Single file
pytest tests/unit/test_packing.py

# Single test
pytest tests/unit/test_packing.py::test_pack_islands_basic

# With verbose output
pytest tests/unit/test_packing.py -v

Run with Coverage

pytest tests/ --cov=sulo_ai --cov-report=html
# Open htmlcov/index.html in browser

🐛 Debugging

Debug in VS Code

Add to .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: Current File",
      "type": "debugpy",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal",
      "python": "${workspaceFolder}/venv/Scripts/python.exe"
    }
  ]
}

📦 Dependencies

See requirements.txt for full list. Key packages:

• anthropic - Claude API client
• requests - HTTP client
• pytest - Testing framework
• black - Code formatter
• fake-bpy-module-4.2 - Blender API stubs

🔄 Updating Dependencies

# Activate environment first
source activate.sh  # or activate.bat

# Update all packages
pip install --upgrade -r requirements.txt

# Update specific package
pip install --upgrade anthropic

❓ Troubleshooting

Issue: ModuleNotFoundError: No module named 'bpy'

Solution: This is normal in the dev environment. The addon runs inside Blender's Python, which has the real bpy module.

Issue: Type hints not working

Solution: Restart your IDE after installing dependencies.

Issue: Tests failing

Solution: Make sure you've activated the virtual environment.

---

Need help? Check the context files in context/ directory for detailed documentation.