Implement Model Registry

[alicup29]

Summary

Implements Step 1 (Client Registry Infrastructure) of the add-client-model-registry change proposal. This PR introduces a comprehensive client-side model registry system for tracking downloaded and imported models, complete with a web-based viewer and full test coverage.

What's New

🗄️ Core Registry System

sleap_rtc/client/client_model_registry.py (359 lines)

• JSON-based persistence at ~/.sleap-rtc/models/manifest.json
• Atomic write operations for crash safety (temp file + rename)
• Automatic corruption recovery with timestamped backups
• CRUD operations: register(), get(), list(), update(), delete(), exists()
• Advanced filtering by model type, source, location, and alias presence
• Support for optional metadata (metrics, hyperparameters, tags, notes)

🌐 Web Viewer

sleap_rtc/client/registry_server.py (448 lines)

• Beautiful web interface at http://localhost:8765
• Dashboard statistics (total models, aliases, worker sync status)
• Responsive card-based UI showing all model details
• Real-time filtering by type and location
• REST API endpoints (/api/models, /api/stats, /api/model/{id})
• Zero external dependencies (uses Python's built-in http.server)

Usage:

# Start the viewer
uv run python -m sleap_rtc.client.registry_server

# Open in browser
open http://localhost:8765

✅ Testing

tests/test_client_model_registry.py (32 tests, 100% passing)

• Registry initialization and schema validation
• CRUD operations and error handling
• Filtering and sorting functionality
• Atomic write operations and persistence
• Corruption recovery
• Metadata handling
• Concurrent access patterns

Run tests:

uv run python -m pytest tests/test_client_model_registry.py -v

📚 Documentation & Examples

Demo Scripts:

• examples/demo_client_registry.py - Interactive demonstration of all features
• examples/populate_demo_registry.py - Populate registry with sample data
• examples/test_concurrent_registries.py - Concurrent access patterns
• examples/WEBVIEW_README.md - Complete web viewer guide

Project Organization:

• Moved documentation to docs/ directory
• Moved configuration to config/ directory
• Added README files for each directory
• Updated references in main README

Key Features

📋 Model Tracking

• Track models by 8-character hash ID
• Optional human-readable aliases
• Source tracking (worker-training, local-import, worker-pull, client-upload)
• Worker synchronization status (local-only vs synced)
• Timestamps for all operations

🎯 Metadata Support

• Training metrics (validation loss, accuracy, epochs)
• Hyperparameters (learning rate, batch size, optimizer)
• User-defined tags (production, experimental, validated)
• Free-form notes
• Model type (centroid, topdown, bottomup)

🔒 Safety & Reliability

• Atomic writes prevent corruption
• Automatic backup on corruption detection
• Schema version tracking for future migrations
• Graceful degradation when registry is missing
• No data loss on crashes or interruptions

Testing

All 32 tests passing:

$ uv run python -m pytest tests/test_client_model_registry.py -v
================================ 32 passed in 0.17s ================================

Test coverage includes:

• ✅ Fresh and existing registry initialization
• ✅ Corrupted registry recovery
• ✅ All CRUD operations
• ✅ Filtering and sorting
• ✅ Atomic operations and persistence
• ✅ Metadata preservation
• ✅ Concurrent access patterns

Demo

Quick demo:

# 1. Populate with demo data
uv run python examples/populate_demo_registry.py

# 2. View in terminal
uv run python examples/demo_client_registry.py

# 3. View in browser
uv run python -m sleap_rtc.client.registry_server
# Open http://localhost:8765

Project Structure

sleap-RTC/
├── sleap_rtc/client/
│   ├── client_model_registry.py    # Core registry (NEW)
│   └── registry_server.py          # Web viewer (NEW)
├── tests/
│   └── test_client_model_registry.py  # 32 tests (NEW)
├── examples/
│   ├── demo_client_registry.py     # Demo script (NEW)
│   ├── populate_demo_registry.py   # Sample data (NEW)
│   ├── test_concurrent_registries.py  # Concurrency tests (NEW)
│   └── WEBVIEW_README.md           # Viewer docs (NEW)
├── docs/                            # Documentation (ORGANIZED)
│   ├── README.md
│   ├── DEVELOPMENT.md
│   └── INFERENCE_CLI_PROPOSAL.md
└── config/                          # Configuration (ORGANIZED)
    ├── README.md
    ├── config.example.toml
    └── sleap-rtc.toml

API Examples

Python API:

from sleap_rtc.client.client_model_registry import ClientModelRegistry

# Initialize registry
registry = ClientModelRegistry()

# Register a model
registry.register({
    "id": "a3f5e8c9",
    "model_type": "centroid",
    "alias": "production-v1",
    "source": "worker-training",
    "local_path": "~/.sleap-rtc/models/centroid_a3f5e8c9/",
    "metrics": {"final_val_loss": 0.0234}
})

# List models
models = registry.list(filters={"model_type": "centroid"})

# Get specific model
model = registry.get("a3f5e8c9")

# Update metadata
registry.update("a3f5e8c9", {"notes": "Best model for mice"})

REST API:

# Get all models
curl http://localhost:8765/api/models

# Get statistics
curl http://localhost:8765/api/stats

# Get single model
curl http://localhost:8765/api/model/a3f5e8c9

Next Steps

This PR implements Step 1 of the add-client-model-registry proposal. Future steps include:

• Step 2: Alias management system
• Step 3: Model import command
• Step 4: Enhanced list and info commands
• Step 5+: WebRTC transfer protocol and push/pull commands

Breaking Changes

None. This is fully additive and backward compatible.

Checklist

• ✅ Core registry implementation complete
• ✅ Web viewer functional
• ✅ All tests passing (32/32)
• ✅ Documentation complete
• ✅ Example scripts provided
• ✅ Project organization improved
• ✅ No breaking changes

🤖 Generated with Claude Code