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

pip install openpyxl

Initialization

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)

# 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

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

Check Statistics

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

manager.register_active_users(user_list)
assignments = manager.get_user_assignments(user_id)

Option 2: Flask Integration

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

from user_registration_integration import create_fastapi_router

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

Option 4: UserService Wrapper

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

# 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

count = manager.get_managed_user_count()

Get all user IDs in system

all_users = manager.get_all_user_ids()

Check if user has assignments

assignments = manager.get_user_assignments(user_id)
if assignments:
    print("User has assignments")
else:
    print("User needs to be registered")

Monitor expansion history

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

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

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

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

Testing

Run test suite

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 - Step-by-step integration with examples
• Full Guide: USER_ASSIGNMENT_GUIDE.txt - Comprehensive reference (500+ lines)
• API Reference: user_assignment_manager.py - Docstrings and type hints
• Examples: 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 TROUBLESHOOTING section
2. Review 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 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