README.md

metadata

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

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

Open:

http://127.0.0.1:4173/

Test

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

Google Services

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

$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

pip install -r requirements.txt