Code improvements for AEO Update

[yingli-NREL]

Put this one on hold for now. Will focus on the AEO 2026 update first. #613

related issue: #503

1. Extract Hardcoded Constants to Config
   Benefit: Single point of change, better documentation.

2. Replace Print Statements with Logging
   Benefit: Better debugging, log filtering by severity.

3. Add Request Timeouts=30
   Benefit: Prevents hanging requests, improves reliability.

4. Add Type Hints for api_query(), data_processor() in converter.py
   Benefit: IDE support, type checking (mypy), self-documenting code.

5. Add API Response Validation
   Benefit: Checks the JSON structure before accessing nested keys. Catches data corruption early, prevents silent failures

6. Create validate_user_input() function with retry limits
   Benefit: Eliminates infinite loops, improves user experience

7. Create safe_update() helper function to improve the Try-Except Error Handling in converter.py
   Benefit: Reduces code, eliminates duplication

8. Add Data Validation Before File Writes
   Validate annual emissions/price JSON before writing to file. Checks that CO2 intensity data contains expected regions and that year-keyed values are numeric and non-negative
   Validate hourly scaling factor JSON before writing to file. Checks that the expected metric key exists, each region has EXPECTED_HOURS_PER_YEAR values per year, and values are numeric.
   Benefit: Prevents corrupted output files, catches calculation errors

9. Refactor Duplicated State/EMM Processing
   Extract geographic processing into single parameterized function
   Benefit: Eliminates code duplication, easier maintenance

[github-actions]

✅ Integration Test Results

Ubuntu (Baseline)

Item	Detail
Status	success
Results changed vs master	No
Profiler	Disabled
Artifacts & Logs	View workflow run

Cross-Platform Results

Platform	Status	JSON Diffs vs Master
Windows	✅ Pass	No
macOS	✅ Pass	No

[rHorsey]

@yingli-NREL The network graph shows this PR as having commits that aren't covered by the aeo2026-update branch - #613 - so I think we don't want to close this yet?

[yingli-NREL]

@yingli-NREL The network graph shows this PR as having commits that aren't covered by the aeo2026-update branch - #613 - so I think we don't want to close this yet?

Do not close it. Will first get the aeo2026-update branch done. Then work on this.