README.md

---
title: Virtual Prompt War
emoji: 🗳️
colorFrom: indigo
colorTo: blue
sdk: docker
app_port: 7860
pinned: false
---

# Election Process Assistant

Python-first implementation of a smart election assistant built for a voter guidance persona. The app helps a user understand registration, deadlines, ballot research, polling access, and official next steps using country-aware logic with deep Google service integration.

## Challenge Submission

### Chosen Vertical

This submission is built around a **civic assistance / voter guidance** persona:

- A person needs help understanding election rules for their country or state
- The assistant adapts guidance based on country, jurisdiction, address, age, residency, and registration state
- The app prioritizes official election authority links before any manual or fallback guidance
- AI-powered Q&A via Google Gemini helps users ask natural-language civic questions

### Approach And Logic

The solution uses a layered decision model with Google service integration at every layer:

1. Collect onboarding context such as country, state or region, address, age, citizenship, and residency.
2. Resolve a jurisdiction through a country adapter.
3. Use richer live or seeded data where available — Google Civic API for US addresses.
4. AI assistant (Google Gemini) answers voter questions in natural language.
5. Google Translate provides real-time translation of election guidance.
6. Google Calendar integration lets users push deadlines directly to their calendar.
7. Google Safe Browsing validates candidate and official URLs.
8. Google Sheets export supports registration drive organizers.
9. Google OAuth enables secure sign-in without passwords.
10. Google Cloud Logging provides production observability.
11. Fall back to structured official-source guidance when live data is unavailable.
12. Preserve session-specific ballot and polling refresh results locally in SQLite.

### How The Solution Works

- `election_assistant/google_services.py` provides unified Google service integration (Gemini, Translate, Calendar, Sheets, Safe Browsing, OAuth, Cloud Logging).
- `election_assistant/data_sources.py` provides dynamic country and region adapters.
- `election_assistant/web.py` serves the WSGI application, form actions, API endpoints, and session flow.
- `election_assistant/render.py` renders accessible server-side HTML for dashboard, timeline, ballot, polling, guide, support, learning, and services pages.
- `election_assistant/integrations.py` integrates Google Civic and Google Maps when configured.
- `election_assistant/state.py` stores isolated per-session application state in SQLite.
- `election_assistant/constants.py` centralises action paths and configuration values.

### Assumptions

- Official election authority sources are the source of truth for production voting decisions.
- Google Civic live ballot and polling support is only available for supported US addresses.
- For jurisdictions without live official feeds, the app should be explicit about coverage gaps instead of pretending exact booth or candidate data exists.
- Local SQLite persistence is acceptable for challenge evaluation and demo hosting.
- All Google services degrade gracefully when API keys are not configured.

### Why This Is Practical

- Supports India, all 50 US states, and generic international fallback flows.
- Produces a personalized voter guide with deadlines, polling details, and research notes.
- Uses official links and conservative fallback behavior for real-world safety.
- Works without a JavaScript SPA build pipeline, keeping deployment simple and maintainable.
- 10 Google service integrations provide meaningful, production-grade capabilities.

## Run Locally

```powershell
python server.py --host 127.0.0.1 --port 4173
```

Open:

```text
http://127.0.0.1:4173/
```

## Test

```powershell
python -m pytest tests/ -v
python -m unittest tests.test_python_app
```

## Google Services

Set these environment variables to enable live Google-backed behavior:

```powershell
$env:GOOGLE_CIVIC_API_KEY='your-civic-api-key'
$env:GOOGLE_MAPS_EMBED_KEY='your-maps-embed-key'
$env:GOOGLE_GEMINI_API_KEY='your-gemini-api-key'
$env:GOOGLE_TRANSLATE_API_KEY='your-translate-api-key'
$env:GOOGLE_CALENDAR_API_KEY='your-calendar-api-key'
$env:GOOGLE_SHEETS_API_KEY='your-sheets-api-key'
$env:GOOGLE_SAFE_BROWSING_API_KEY='your-safe-browsing-key'
$env:GOOGLE_OAUTH_CLIENT_ID='your-oauth-client-id'
$env:GOOGLE_OAUTH_CLIENT_SECRET='your-oauth-client-secret'
$env:GOOGLE_CLOUD_PROJECT='your-gcp-project-id'
```

Without keys, the app uses offline fallback behavior for each service. Use `.env.example` as the template.

### Google Services Used (10 integrations)

| # | Service | Purpose | Fallback |
|---|---------|---------|----------|
| 1 | **Google Gemini API** | AI-powered voter Q&A — answers natural-language civic questions | Curated FAQ answers |
| 2 | **Google Translate API** | Real-time translation of election guidance into 100+ languages | Returns original text |
| 3 | **Google Calendar API** | Push election deadlines directly to user's Google Calendar | ICS file download |
| 4 | **Google Sheets API** | Export registration drive data to Google Sheets | CSV download |
| 5 | **Google Safe Browsing API** | Validate candidate and official URLs for threats | Skips validation |
| 6 | **Google OAuth 2.0** | Secure sign-in via Google accounts | Password-based auth |
| 7 | **Google Cloud Logging** | Structured application logging for observability | Python stderr logging |
| 8 | **Google Civic Information API** | Live US ballot and polling information | Country adapter fallback |
| 9 | **Google Maps Embed API** | Embedded polling location map | Grid map placeholder |
| 10 | **Google Maps Directions** | Directions links for polling destinations | Official authority link |

### API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/health` | GET | Application health check |
| `/api/status` | GET | Session and jurisdiction status |
| `/api/google-services` | GET | Google service configuration status |
| `/api/calendar-link` | GET | Generate Google Calendar event URL |
| `/action/ask-gemini` | POST | Ask AI assistant a civic question |
| `/action/translate` | POST | Translate text via Google Translate |
| `/action/export-sheets` | POST | Export data to Google Sheets/CSV |
| `/action/check-url` | POST | Validate URL via Google Safe Browsing |
| `/auth/google` | GET | Start Google OAuth sign-in |
| `/auth/google/callback` | GET | Complete Google OAuth sign-in |

## Country Data

- `election_assistant/data_sources.py` is the country-aware adapter layer.
- `seed_data.py` remains the rich US fallback and shared metadata source.
- `data/countries/*.json` contains static country configs for non-US fallback coverage.
- Current built-in coverage includes India, all 50 US states, United Kingdom, Canada, EU, and a generic other-country fallback.

## Hugging Face Space

This repository is configured as a Docker Space for `https://huggingface.co/spaces/vettri06/virtual_prompt_war`.

Build/runtime details:

- Container entrypoint: `python server.py --host 0.0.0.0 --port 7860`
- Docker configuration: `Dockerfile`
- Space port: `7860`
- Health endpoint: `/api/health`

## Quality Signals

- Security headers are sent on application responses (CSP, HSTS, nosniff, no-referrer).
- CSRF protection is enforced on form actions.
- Private vault storage uses `cryptography` Fernet when the package is installed.
- Keyboard focus styles, skip links, and touch-friendly form controls are built in.
- Automated tests cover routing, security, fallback behavior, adapter refresh logic, and Google services.
- `pyproject.toml` configures ruff linting, mypy type checking, and pytest.
- Structured logging via Google Cloud Logging or Python stdlib.
- All 10 Google services degrade gracefully when API keys are absent.

## Optional Production Dependencies

```powershell
pip install -r requirements.txt
```