def assign_records_to_groups(
    groups: Dict[str, List[Any]], records: List[Any], overlap: int, shuffle: bool = True
) -> Dict[str, Dict[str, Any]]:
    """
    Assign records to predefined groups with controlled overlap (for the groups) and optional shuffle. All members of the same group will annotate the same records.

    Args:
        groups: A dictionary where keys are group names and values are lists of users names or objects.
        records: A list of records to be assigned.
        overlap: The number of times each record is assigned to consecutive groups (0 for no overlap).
        shuffle: If True, shuffle the records before assignment. Defaults to True.

    Returns:
        A dictionary where each key is a group and its value is another dictionary, which maps usernames to their respective assigned records.

    Raises:
        ValueError: If `overlap` is higher than the number of groups or negative.
    """
    if overlap < 0 or overlap >= len(groups.keys()):
        raise ValueError("Overlap must be less than the number of groups and must not be negative.")

    if len(records) < len(groups.keys()):
        warnings.warn(
            "The number of groups is higher than the number of records. Some users will not be assigned any records.",
            UserWarning,
        )

    if shuffle:
        random.shuffle(records)

    assignments = {}
    assignments_grouped = {}
    group_names = list(groups.keys())
    num_groups = len(group_names)
    overlap = 1 if overlap == 0 else overlap

    group_records = defaultdict(list)
    with Progress() as progress:
        task = progress.add_task("[green]Processing records...", total=len(records))

        for idx, record in enumerate(records):
            for offset in range(overlap):
                group_index = (idx + offset) % num_groups
                group_name = group_names[group_index]
                group_records[group_name].append(record)

            progress.update(task, advance=1)

    for group, users in groups.items():
        users = [check_user(user) for user in users]
        for user in users:
            assignments[user] = group_records[group]

        assignments_grouped[group] = {user.username: assignments.get(user, []) for user in users}

    return assignments_grouped

    Assign records to predefined groups with controlled overlap (for the groups) and optional shuffle. All members of the same group will annotate the same records.

    Args:
        groups: A dictionary where keys are group names and values are lists of users names or objects.
        records: A list of records to be assigned.
        overlap: The number of times each record is assigned to consecutive groups (0 for no overlap).
        shuffle: If True, shuffle the records before assignment. Defaults to True.

    Returns:
        A dictionary where each key is a group and its value is another dictionary, which maps usernames to their respective assigned records.

    Raises:
        ValueError: If `overlap` is higher than the number of groups or negative.
    
argilla-v1/src/argilla_v1/client/feedback/utils/assignment.py