wcag_AI_validation/UI/user_task_assignment/README.md

# User Assignment Manager Integration

## Overview

This package provides automatic user-to-assignment management for your alt-text assessment system. When new users register/activate, the system automatically:

1. **Checks current capacity** - How many users are already managed
2. **Expands if needed** - Runs AssignmentSystem Round 2+ mode when new users exceed current capacity
3. **Stores mappings** - Saves all user-to-site-images mappings in SQLite database
4. **Maintains files** - Keeps JSON/XLSX files updated with same names (no versioning needed)
5. **Tracks history** - Logs all expansion events for auditing

## Files in this Package

### Core System Files

| File | Purpose |
|------|---------|
| `user_assignment_manager.py` | Main manager class - handles all assignment logic |
| `user_registration_integration.py` | Flask/FastAPI integration examples and UserService wrapper |
| `alt_text_assignment_target_overlap_multiple_round.py` | Assignment algorithm (existing - DO NOT MODIFY) |

### Configuration & Data Files

| File | Purpose |
|------|---------|
| `sites_config.json` | Configuration of websites and images per user |
| `alt_text_assignments_output_target_overlap.json` | Current assignments (updated by system) |
| `alt_text_assignments_output_target_overlap.xlsx` | Excel export of assignments (updated) |
| `wcag_validator_ui.db` | SQLite database with user-assignment mappings (auto-created) |

### Documentation Files

| File | Purpose |
|------|---------|
| `README.md` | This file - overview and quick reference |
| `QUICK_START.md` | Step-by-step integration guide with code examples |
| `USER_ASSIGNMENT_GUIDE.txt` | Comprehensive documentation (500+ lines) |

### Testing & Examples

| File | Purpose |
|------|---------|
| `test_user_assignment_manager.py` | Test suite to verify functionality |

## Quick Usage

### Installation

```bash
pip install openpyxl
```

### Initialization

```python
from user_assignment_manager import UserAssignmentManager

manager = UserAssignmentManager(
    db_path="path/to/wcag_validator_ui.db",
    config_json_path="sites_config.json",
    assignments_json_path="alt_text_assignments_output_target_overlap.json",
    assignments_xlsx_path="alt_text_assignments_output_target_overlap.xlsx"
)
```

### Register Users (with auto-expansion)

```python
# When users activate, call this with ALL active users
active_users = ["user1", "user2", "user3", "user4", "user5"]
assignments = manager.register_active_users(active_users)

# If count exceeds previous capacity:
# - AssignmentSystem runs Round 2+ mode
# - New assignments generated
# - JSON/XLSX files updated
# - Database populated
```

### Get User Assignments

```python
user_assignments = manager.get_user_assignments("user1")
# Returns: {"https://site1.com": [1, 2, 3, 4, 5, 6], ...}
```

### Check Statistics

```python
stats = manager.get_statistics()
history = manager.get_generation_history()
```

## Database Schema

### Table: `user_assignments`
Stores user-to-image-assignment mappings
- `user_id` - Unique user identifier
- `site_url` - Website URL
- `image_indices` - JSON array of image numbers
- `created_at` / `updated_at` - Timestamps

### Table: `assignment_generation_log`
Tracks expansion events
- `generation_round` - Round number (1, 2, 3, ...)
- `users_before` - User count before expansion
- `users_after` - User count after expansion
- `new_users_added` - How many new users in this round
- `generated_at` - When expansion occurred

## Integration Points

### Option 1: Direct API Usage
```python
manager.register_active_users(user_list)
assignments = manager.get_user_assignments(user_id)
```

### Option 2: Flask Integration
```python
from user_registration_integration import get_flask_blueprint

app.register_blueprint(
    get_flask_blueprint(manager), 
    url_prefix="/api/assignments"
)
# Endpoints: GET /api/assignments/user/<id>, POST /api/assignments/activate
```

### Option 3: FastAPI Integration
```python
from user_registration_integration import create_fastapi_router

app.include_router(
    create_fastapi_router(manager),
    prefix="/api/assignments"
)
```

### Option 4: UserService Wrapper
```python
from user_registration_integration import UserService

service = UserService(manager)
service.on_users_activated(["user1", "user2", ...])
```

## How Auto-Expansion Works

### Before
```
Managed users: 15
Current JSON has assignments for: user1 to user15
```

### User Registration Event
```python
# New users activate
manager.register_active_users(["user1", ..., "user15", "user16", "user17", "user18"])
# Count: 18 users > 15 managed → Expansion triggered!
```

### Round 2+ Execution
1. **Load**: Read existing assignments from XLSX (user1-user15)
2. **Generate**: Create new assignments for user16-user18 using AssignmentSystem
3. **Ensure**: Maintain target_overlap >= 2 images between users per site
4. **Save**: Write ALL assignments to JSON/XLSX (same filenames)
5. **Persist**: Insert new users into SQLite database
6. **Log**: Record expansion event in generation_generation_log table

### After
```
Managed users: 18
JSON/XLSX: Completely updated with user1 to user18
Database: Contains all 18 users
Log: Round 2 event recorded (15→18, +3 users)
```

## System Capabilities

| Capability | Implementation |
|------------|-----------------|
| **Automatic Scaling** | No manual user management needed |
| **Round 2+ Support** | Built-in, triggered automatically |
| **Database Persistence** | SQLite with fast indexed lookups |
| **File Compatibility** | Same JSON/XLSX format as original system |
| **History Tracking** | Complete generation audit trail |
| **Statistics** | Real-time coverage metrics per site |
| **Multi-site Support** | Handles multiple assessment websites |
| **Reproducible** | Configurable seed for reproducibility |
| **Error Handling** | Graceful fallbacks and detailed logging |

## Typical Workflow

```
1. Day 1: System initialized with 15 users
   └─ JSON has assignments for user1-user15
   └─ Database populated from JSON

2. Day 5: 8 more users register/activate
   └─ Call: register_active_users(["user1", ..., "user23"])
   └─ Detected: 23 users > 15 managed
   └─ Action: Run Round 2+ with 8 new users
   └─ Result: JSON/XLSX updated with user1-user23
   └─ Database: 23 users now managed

3. Day 10: Check on capacity
   └─ managed_count = 23
   └─ Still serving all 23 users
   └─ No expansion needed

4. Day 15: 7 more users activate
   └─ Call: register_active_users(["user1", ..., "user30"])
   └─ Detected: 30 users > 23 managed
   └─ Action: Run Round 3 with 7 new users
   └─ Result: JSON/XLSX updated with user1-user30
   └─ Database: 30 users now managed

5. At any time: Check statistics
   └─ Total users managed: 30
   └─ Coverage per site: 30 users each
   └─ Expansion history: 3 events tracked
```

## Key Features

### ✓ Transparent Scaling
Users don't care about capacity - system handles it automatically

### ✓ Maintains Constraints
Respects `target_overlap` parameter for inter-rater reliability

### ✓ Backward Compatible
Uses same JSON/XLSX format as original `alt_text_assignment_target_overlap.py`

### ✓ Auditable
Complete history of all expansions with timestamps

### ✓ Predictable Behavior
Uses same AssignmentSystem algorithm for consistency

### ✓ Web-Ready
Flask/FastAPI examples provided for easy integration

## Common Tasks

### Get current managed user count
```python
count = manager.get_managed_user_count()
```

### Get all user IDs in system
```python
all_users = manager.get_all_user_ids()
```

### Check if user has assignments
```python
assignments = manager.get_user_assignments(user_id)
if assignments:
    print("User has assignments")
else:
    print("User needs to be registered")
```

### Monitor expansion history
```python
history = manager.get_generation_history()
for event in history:
    print(f"Round {event['generation_round']}: "
          f"{event['users_before']}→{event['users_after']} users")
```

### Export current statistics
```python
import json
stats = manager.get_statistics()
print(json.dumps(stats, indent=2))
```

## Configuration

### Default Paths (relative to script location)
```
Database:       ../persistence/wcag_validator_ui.db
Config JSON:    sites_config.json
Assignments:    alt_text_assignments_output_target_overlap.json
Excel Export:   alt_text_assignments_output_target_overlap.xlsx
```

### Custom Paths
```python
manager = UserAssignmentManager(
    db_path="/custom/db.db",
    config_json_path="/custom/config.json",
    assignments_json_path="/custom/out.json",
    assignments_xlsx_path="/custom/out.xlsx"
)
```

### Parameters
```python
target_overlap=2      # Min images shared between users per site
seed=42              # Random seed for reproducibility
```

## Testing

### Run test suite
```bash
python test_user_assignment_manager.py
```

### Expected output
- All initialization tests pass
- Database schema created
- Existing assignments loaded
- Auto-expansion triggered (if user count > current)
- Statistics retrieved
- History logged

## Troubleshooting

| Issue | Solution |
|-------|----------|
| `ModuleNotFoundError: openpyxl` | `pip install openpyxl` |
| `No assignments found for user` | Call `register_active_users()` with user in list |
| `Round 2+ not triggered` | Check that new user count > current managed count |
| `Database locked` | SQLite handles this. Check file permissions. |
| `File not found` | Verify config paths are correct and readable |

See `USER_ASSIGNMENT_GUIDE.txt` section on TROUBLESHOOTING for more details.

## Documentation

- **Quick Start**: [QUICK_START.md](QUICK_START.md) - Step-by-step integration with examples
- **Full Guide**: [USER_ASSIGNMENT_GUIDE.txt](USER_ASSIGNMENT_GUIDE.txt) - Comprehensive reference (500+ lines)
- **API Reference**: [user_assignment_manager.py](user_assignment_manager.py) - Docstrings and type hints
- **Examples**: [user_registration_integration.py](user_registration_integration.py) - Flask/FastAPI examples

## Architecture

```
┌─────────────────────────────────────┐
│  User Registration System           │
│  (Your Flask/FastAPI/Django app)    │
└────────────┬────────────────────────┘
             │
             └─ register_active_users([user_ids])
                        │
             ┌──────────▼───────────┐
             │ UserAssignmentManager│
             ├──────────────────────┤
             │ • Check capacity     │
             │ • Trigger expansion  │
             │ • Persist to DB      │
             │ • Update files       │
             │ • Log events         │
             └──────────┬───────────┘
                        │
        ┌───────────────┼───────────────┐
        │               │               │
        ▼               ▼               ▼
    SQLite DB      JSON File         XLSX File
    user_assignments
    generation_log    assignments    Excel GUI
```

## Performance

- **User lookup**: O(1) via indexed SQLite query
- **Registration**: O(n) where n = number of active users
- **Expansion**: O(n) for Round 2+ generation (background operation)
- **Database size**: ~10-20KB per 1000 users

## Support

For questions or issues:

1. Check [USER_ASSIGNMENT_GUIDE.txt](USER_ASSIGNMENT_GUIDE.txt) TROUBLESHOOTING section
2. Review [QUICK_START.md](QUICK_START.md) examples
3. Run `python test_user_assignment_manager.py` to verify setup
4. Check database directly: `sqlite3 wcag_validator_ui.db`

## Version

- **Current**: 1.0 (2025-02-07)
- **Python**: 3.7+
- **Dependencies**: openpyxl

## Next Steps

1. Install openpyxl: `pip install openpyxl`
2. Read [QUICK_START.md](QUICK_START.md) for integration steps
3. Run test suite to verify setup
4. Integrate `register_active_users()` in your user auth flow
5. Start using `get_user_assignments()` to retrieve tasks

---

**Created**: February 7, 2025  
**Updated**: February 7, 2025  
**Status**: Ready for integration