feat : Bulk Import of Institutions via CLI Command
Description
Currently, institutions must be created individually through the admin interface or API, which is inefficient and error-prone when handling large datasets. This slows down onboarding and increases the likelihood of inconsistent data entry.
The feat/admin-institutions branch introduces a new CLI command to enable bulk creation of institutions from a CSV file. The command reads structured CSV input, normalizes field values to match backend expectations, and sends individual API requests for each record.
In addition to the command, supporting logic has been implemented to handle data transformation, error handling, and progress reporting. Automated tests have also been added to validate the import functionality and normalization behavior.
Proposed Enhancement
Add a new CLI subcommand:
corpus-client admin import-institutions <csv_path>
## Key Capabilities
- Validate the existence of the input CSV file before processing
- Parse CSV rows using structured reading (`DictReader`)
- Normalize and transform input data to align with backend API requirements:
- Convert numeric fields (e.g., `college_code`, `revised_intake`) to integers
- Map district names to standardized enum values
- Normalize categorical fields (e.g., `college_type`, `management_type`, `medium`, `mode`)
- Detect and handle CBCS courses by extracting flags and cleaning course names
- Convert empty or placeholder values (`-`) to `None`
- Perform row-by-row API submission to `/api/v1/institutions`
- Provide progress feedback (spinner/progress indicator)
- Output a summary of successful and failed imports
- Introduce a silent admin request helper to improve error handling during batch processing
## Benefits
- **Efficiency**: Enables bulk creation of institutions, significantly reducing manual effort
- **Consistency**: Ensures standardized data formatting through normalization logic
- **Scalability**: Supports large datasets via batch processing
- **Resilience**: Continues processing even if individual rows fail, with clear reporting
- **Improved Developer Experience**: Cleaner error handling via silent request helper
- **Reliability**: Automated test coverage ensures correctness of import and transformation logic
## Acceptance Criteria
- A new CLI command `corpus-client admin import-institutions <csv_path>` is available
- The command exits with an error message and status code `1` if the file does not exist
- CSV rows are correctly parsed and transformed into API-compatible payloads
- Field normalization works as expected:
- Numeric fields are converted appropriately
- Enum and categorical values are standardized
- CBCS detection and transformation is correctly applied
- Empty or placeholder values are handled as `None`
- Each valid row triggers an API request to create an institution
- The command displays progress during execution and outputs a success/failure summary
- Failures in individual rows do not stop the entire import process
- Helper function `_admin_request_silent` properly raises exceptions for controlled error handling
- Test cases cover:
- Successful multi-row import
- Normalization logic
- CBCS handling
- Missing file scenario
- Handling of incomplete but processable rows