feat: comprehensive Argilla user and workspace management

[ivyleavedtoadflax]

Summary

Add comprehensive Argilla user and workspace management commands.

New Commands

• add-users: Bulk create users with random secure passwords
• add-user: Create single user with multi-workspace support
• add-to-workspace: Add existing user to multiple workspaces
• list-users: Show workspace users (usernames only)
• list-workspaces: Show all available workspaces
• list-datasets: Show datasets in a workspace
• track-progress: Monitor annotation progress with optimized performance
• delete-user: Remove user from Argilla

Usage Examples

# Bulk create users with random passwords
gsma argilla add-users -w tsg-wg --count 10 --output-csv users.csv

# Create user in multiple workspaces
gsma argilla add-user -u alice -p secret123 -w tsg -w fasg -w ng

# Track annotation progress
gsma argilla track-progress -w TSG

Breaking Changes

• upload-by-subgroup: --working-group shorthand changed from -w to -g

[claude]

Comprehensive PR Review - PR #78: Bulk User Creation for Argilla Workspaces

Overview

This PR adds extensive Argilla user and workspace management functionality with 8 new commands and comprehensive test coverage. The implementation is well-structured and follows the project's patterns.

---

🟢 Strengths

1. Excellent Security Practices

• ✅ Cryptographically secure random passwords using secrets module (lines 15-26)
• ✅ Proper password generation with 8-character minimum
• ✅ API credentials properly sourced from environment variables with fallback options
• ✅ No hardcoded secrets or credentials

2. Robust Error Handling

• ✅ Comprehensive validation (workspace exists, user exists/doesn't exist as appropriate)
• ✅ Graceful failure handling with continue-on-error for bulk operations
• ✅ Clear error messages with actionable guidance
• ✅ Proper exit codes throughout

3. User Experience

• ✅ Consistent CLI patterns with short flags (-w, -u, -o)
• ✅ Rich console output with emojis and clear status indicators
• ✅ Optional tabulate integration for formatted tables with graceful fallback
• ✅ Helpful examples in docstrings

4. Code Quality

• ✅ Well-documented functions with clear docstrings
• ✅ Type hints used consistently
• ✅ Follows existing code patterns from the codebase
• ✅ Good test coverage (264 lines of tests for core functionality)

5. Feature Completeness

• ✅ Comprehensive command suite: add-user, add-users, add-to-workspace, list-users, list-workspaces, list-datasets, track-progress, delete-user
• ✅ CSV export functionality for user management
• ✅ Progress tracking with detailed metrics

---

🟡 Issues & Concerns

1. Critical: Breaking Change Not Highlighted Enough

Location: Line 261 in argilla_cli.py

working_group: str | None = typer.Option(
    None,
    "--working-group",
    "-g",  # Changed from -w
    ...
)

Issue: The upload-by-subgroup command's --working-group shorthand changed from -w to -g to free up -w for --workspace. While mentioned in PR description, this could break existing scripts/workflows.

Recommendation:

• Add a deprecation notice in CLAUDE.md under "Recent Changes"
• Consider if any CI/CD scripts or DVC pipeline commands use the old flag
• Document the migration path clearly

2. Security: Unused Import in add-users Command

Location: Lines 769-770

from gsma_dataset_creation.validation.argilla_subgroup_uploader import \
    create_valid_password

Issue: The add-users command imports create_valid_password from argilla_subgroup_uploader but never uses it. Instead, it correctly uses the new generate_random_password() function.

Impact:

• Unused code increases maintenance burden
• Could confuse future developers about which password function to use
• The old create_valid_password uses predictable passwords ({username}-gsma), while new function uses secure random passwords - mixing these would be inconsistent

Recommendation: Remove the unused import on lines 769-770.

3. Inconsistency: Password Strategy Divergence

Issue: Two different password strategies exist:

• Old pattern (CLAUDE.md line 523, argilla_subgroup_uploader.py): Predictable {username}-gsma pattern
• New pattern (add-users command): Random 8-character secure passwords

Impact:

• CLAUDE.md documentation claims passwords follow {username}-gsma pattern
• Actual implementation now uses random passwords
• Documentation is outdated and misleading

Recommendation:

• Update CLAUDE.md lines 523-532 to reflect the new random password approach
• Clarify that predictable passwords are only for the old upload-by-subgroup workflow
• Document when to use which approach

4. Documentation Gap: Command Not Listed

Issue: The add-user, add-to-workspace, list-users, list-workspaces, list-datasets, track-progress, and delete-user commands are implemented but not documented in CLAUDE.md's "CLI Commands" section (line 502).

Recommendation: Add all new commands to the CLAUDE.md CLI Commands list with brief descriptions.

5. Potential Bug: list-users Password Reconstruction

Location: Lines 880-892 (docstring)

"""
This command retrieves all users associated with a workspace and exports their
usernames and reconstructed passwords (following the {username}-gsma pattern).
"""

Issue: The docstring claims to export "reconstructed passwords" but:

1. The actual implementation only exports usernames (lines 940-969)
2. Passwords cannot be retrieved from Argilla (they're hashed)
3. The implementation correctly notes this (lines 974-975)

Impact: Misleading documentation could lead users to expect password recovery functionality that doesn't exist.

Recommendation: Update the docstring to remove the misleading "reconstructed passwords" claim.

6. Code Quality: Import Style Inconsistency

Location: Lines 74-75, 104-105, 152-153, etc.

from gsma_dataset_creation.validation.argilla_uploader import \
    upload_dataset_to_argilla

Issue: Most imports use backslash line continuation, but Python prefers implicit line continuation within parentheses.

Recommendation: Consider using:

from gsma_dataset_creation.validation.argilla_uploader import (
    upload_dataset_to_argilla
)

This is minor but follows PEP 8 best practices.

7. Performance: track-progress Could Be Slow

Location: Lines 1078-1110

for dataset in datasets_to_track:
    progress = dataset.progress(with_users_distribution=True)

Issue: The track-progress command iterates through all datasets and calls dataset.progress() for each one. For workspaces with many datasets, this could be slow (network calls per dataset).

Recommendation:

• Add a progress indicator for long-running operations
• Consider adding a --timeout parameter
• Document expected performance characteristics

---

🔵 Suggestions for Future Enhancement

1. Password Length Configuration

The generate_random_password() function defaults to 8 characters. Consider making this configurable:

password_length: int = typer.Option(8, "--password-length", help="Length of generated passwords (minimum 8)")

2. Bulk User Import from CSV

Consider adding a command to import users from CSV (reverse of export), useful for pre-planned annotation campaigns.

3. User Role Management

The add-user command supports role parameter, but there's no update-user command to change roles later.

4. Progress Export Format

The track-progress CSV export is excellent. Consider adding JSON export option for programmatic consumption.

---

🟢 Test Coverage Assessment

The test file (tests/test_argilla_cli_add_users.py) provides solid coverage:

✅ Well-covered scenarios:

• Workspace validation
• User creation with correct naming patterns
• Existing user skipping
• CSV output format
• Missing API credentials handling
• Partial failure handling

⚠️ Missing test coverage:

• add-user command (multi-workspace support)
• add-to-workspace command
• list-users command
• track-progress command
• list-workspaces command
• list-datasets command
• delete-user command

Recommendation: Add tests for the other 7 commands to maintain consistency with project's TDD approach.

---

📋 Action Items Summary

Must Fix Before Merge:

1. ❌ Remove unused create_valid_password import (lines 769-770)
2. ❌ Fix misleading list-users docstring about password reconstruction
3. ❌ Update CLAUDE.md password documentation to reflect random password approach
4. ❌ Document breaking change for -w → -g flag in upload-by-subgroup

Should Fix Before Merge:

5. ⚠️ Add all 8 new commands to CLAUDE.md CLI Commands section
6. ⚠️ Add test coverage for the 7 untested commands

Nice to Have:

7. 💡 Improve import style consistency (backslash → parentheses)
8. 💡 Add progress indicators for slow operations
9. 💡 Consider configurable password length

---

✅ Final Verdict

Status: Approve with Required Changes

This is a high-quality PR that adds valuable functionality with good security practices. The core implementation is solid, but there are 4 critical issues that must be addressed before merge:

1. Remove unused import
2. Fix misleading documentation
3. Update CLAUDE.md for accuracy
4. Document breaking change properly

Once these issues are resolved, this PR will be ready to merge. The additional test coverage can be added in a follow-up PR if needed.

---

Great work overall! The comprehensive command suite and attention to UX details (emojis, table formatting, CSV exports) show thoughtful design. 🎉