Overview

This PR adds UUID (Universally Unique Identifier) support to all candidate data in the repository, resolving issue #[issue_number]. Previously, candidate records had no unique identifiers, making it difficult to reference specific candidates across different parts of the application.

Changes Made

1. Created UUID Update Script

Added scripts/add_uuid_to_candidates.py - a standalone, executable script that:

• Automatically discovers all candidate JSON files in the data directory
• Generates a unique UUID for each candidate record
• Is idempotent - safely handles running multiple times without creating duplicates
• Provides clear progress reporting and statistics

Example usage:

python3 scripts/add_uuid_to_candidates.py
# or
./scripts/add_uuid_to_candidates.py

2. Updated Data Models

Modified app/models/candidate.py to include UUID fields:

• Added optional uuid field to LokSabhaCandidate model
• Added optional uuid field to AssemblyCandidate model
• Fields are optional to maintain backward compatibility

Before:

class AssemblyCandidate(BaseModel):
    constituency_code: str = Field(alias="Constituency Code")
    name: str = Field(alias="Name")
    party: str = Field(alias="Party")
    # ...

After:

class AssemblyCandidate(BaseModel):
    uuid: Optional[str] = None
    constituency_code: str = Field(alias="Constituency Code")
    name: str = Field(alias="Name")
    party: str = Field(alias="Party")
    # ...

3. Updated Scrapers

Modified both scrapers to automatically generate UUIDs for newly scraped candidates:

• app/scrapers/lok_sabha.py - generates UUIDs when scraping Lok Sabha data
• app/scrapers/vidhan_sabha.py - generates UUIDs when scraping Vidhan Sabha data

This ensures all future scraped data will include unique identifiers.

4. Updated Existing Data

Ran the UUID update script to add identifiers to all existing candidate records:

• 769 Delhi Assembly 2025 candidates
• 4,424 Maharashtra Assembly 2024 candidates
• Total: 5,193 candidates now have unique UUIDs

All UUIDs follow the standard UUID4 format (e.g., baa14e3d-00e4-49de-8c56-75e06a069eb2).

5. Added Documentation

Created scripts/README.md with comprehensive documentation including:

• Usage instructions
• Feature descriptions
• Example output
• When to use the script

Sample Data Structure

Before:

{
  "Constituency Code": "DL-1",
  "Name": "RAJ KARAN KHATRI",
  "Party": "Bharatiya Janata Party",
  "Status": "WON",
  "Votes": "87215",
  "Margin": "8596"
}

After:

{
  "uuid": "baa14e3d-00e4-49de-8c56-75e06a069eb2",
  "Constituency Code": "DL-1",
  "Name": "RAJ KARAN KHATRI",
  "Party": "Bharatiya Janata Party",
  "Status": "WON",
  "Votes": "87215",
  "Margin": "8596"
}

Benefits

• Unique Identification: Each candidate can now be uniquely referenced across the system
• API Improvements: Enables better RESTful API design with stable candidate URLs
• Data Integrity: Easier to track and deduplicate candidate records
• Future-Proof: New scraped data automatically includes UUIDs
• Non-Breaking: Optional fields maintain backward compatibility

Testing

All changes have been thoroughly tested:

• ✅ Verified all 5,193 candidates have UUIDs
• ✅ Confirmed all UUIDs are unique (no duplicates)
• ✅ Validated UUID format (standard UUID4)
• ✅ Tested script idempotency (safe to run multiple times)
• ✅ Verified model compatibility with updated data

Notes

The Lok Sabha 2024 candidates file is currently empty, so no UUIDs were added to it. When data is scraped for this election, the scraper will automatically generate UUIDs.

Fixes #3

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.