[Refactor] Group records by reference in annotation queue

[JonnyTran]

Description

Group records by reference in the annotation queue to improve the user experience when working with document extraction data. This issue is part of the larger workspace-level schema configuration enhancement and leverages the new SchemaService for intelligent record grouping.

Problem

• Records from the same document/reference appear scattered throughout the annotation queue
• Users need to switch between different records that are part of the same document
• No consistent grouping mechanism exists for related records
• Current implementation doesn't leverage workspace schema configuration

Proposed Solution

1. Leverage Workspace Schema Configuration: Use the workspace schema configuration to understand document structure and references
2. Integrate with SchemaService: Use the new SchemaService to determine proper grouping logic
3. Enhance Backend Search API: Modify the search API to support schema-aware reference grouping
4. Update Frontend Components: Update UI to display grouped records with schema context

Implementation Details

Dependencies

• Workspace schema configuration infrastructure must be implemented first
• SchemaService must be available for reference resolution
• Document-centric APIs should be available for optimal implementation

Backend Changes

The search API in argilla-server/src/argilla_server/api/handlers/v1/datasets/records.py needs to be modified to:

1. Use SchemaService for grouping logic:

   schema_service = SchemaService(workspace_id, db)
   reference_field = schema_service.get_reference_field()
   grouping_config = schema_service.get_grouping_configuration()

2. Add workspace-aware grouping parameter to the search query

3. Sort records by reference and schema order using workspace configuration

4. Return schema context in the API response for proper frontend rendering

Frontend Changes

The frontend record handling needs to:

1. Fetch workspace schema configuration on dataset load
2. Use schema-aware grouping in record retrieval
3. Display records with schema context and proper ordering
4. Support navigation between related records within the same reference group

Related Files

• extralit/argilla-server/src/argilla_server/services/SchemaService.py - Core grouping logic
• extralit/argilla-server/src/argilla_server/api/handlers/v1/datasets/records.py - Enhanced search API
• extralit/argilla-frontend/v1/domain/usecases/get-records-by-criteria-use-case.ts - Updated record retrieval
• extralit/argilla-frontend/components/features/record-grouping/ - New grouping components

Acceptance Criteria

• Backend API leverages workspace schema configuration for grouping
• SchemaService is used for reference field identification and grouping logic
• Records with the same reference are grouped together using schema context
• UI clearly indicates schema-based record relationships
• Groups are ordered according to workspace schema configuration
• Existing functionality works correctly (filtering, sorting, etc.)
• Integration tests verify proper grouping behavior
• Performance is maintained or improved

Related Issues

This is part of the strategic workspace-level schema management enhancement:

• Depends on: Workspace Schema Configuration Infrastructure
• Related to: [Refactor] Implement schema topological ordering in record display #88 (Schema ordering), [Feature] Support multi-status filtering in record search #89 (Multi-status filtering)
• Part of: [Refactor] Phase 1: Improve record grouping, ordering, and filtering #95 (Phase 1 improvements)

[JonnyTran]

This issue is part of Phase 1 refactoring for Extralit Document Extraction Data Architecture. See the parent issue #95 for the overall plan and related issues.