Clean HuggingFace deployment without binary files

.dockerignore

@@ -0,0 +1,87 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+ENV/
+env/
+
+# Node
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+frontend/dist/
+frontend/node_modules/
+website/build/
+website/node_modules/
+website/.docusaurus/
+
+# Data and cache
+data/
+cache/
+logs/
+output/
+*.db
+*.sqlite
+
+# Git
+.git/
+.gitignore
+.github/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Documentation (we copy specific dirs)
+docs/
+*.md
+!README.md
+
+# Test and development
+tests/
+examples/
+notebooks/
+*.ipynb
+
+# Large files
+*.zip
+*.tar.gz
+*.mp4
+*.avi
+*.mov
+
+# Environment
+.env
+.env.local
+*.key
+*.pem
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+
+# Temporary
+tmp/
+temp/
+*.tmp
+
+# Scripts we don't need in container
+start-all.sh
+stop-all.sh
+deploy-huggingface.sh
+test-huggingface-build.sh
+migrate-docs.sh
+install.sh

.gitignore

@@ -0,0 +1,100 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+!frontend/src/lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Node.js
+node_modules/
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv
+.venv-intel
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+.env.production
+.env.development
+.env.test
+
+# Credentials and secrets
+credentials.json
+service-account.json
+*_credentials.json
+auth.json
+token.json
+*_token.txt
+*-token.txt
+gcp-*.json
+bigquery-*.json
+.gcp/
+
+# Logs
+logs/
+*.log
+
+# Jupyter Notebook
+.ipynb_checkpoints
+*.ipynb
+
+# Data files
+data/
+.migration_backup/
+*.csv
+*.parquet
+*.delta
+
+# Delta Lake
+_delta_log/
+
+# Testing
+.coverage
+htmlcov/
+.pytest_cache/
+.tox/
+
+# Documentation
+docs/_build/
+
+# Databricks
+.databricks/
+
+# Secrets
+secrets/
+*.key
+*.pem
+
+# OS
+Thumbs.db
+# Binary files for Docker build only (not in git)
+website/static/img/communityone_card.png

.huggingface/README.md

@@ -0,0 +1,101 @@
+---
+title: CommunityOne - Open Navigator
+emoji: 🏛️
+colorFrom: blue
+colorTo: green
+sdk: docker
+app_port: 7860
+pinned: false
+license: apache-2.0
+tags:
+  - civic-engagement
+  - policy-tracking
+  - government-transparency
+  - nonprofit-discovery
+  - open-data
+---
+
+# 🏛️ CommunityOne - Open Navigator
+
+**Track 90,000+ jurisdictions. Monitor 1.8M nonprofits. Amplify your voice.**
+
+CommunityOne is a civic engagement platform that helps you discover advocacy opportunities, track policy changes, and connect with organizations working on the causes you care about.
+
+## ✨ Features
+
+- **🔍 Unified Search**: Find contacts, meetings, organizations, and causes across the entire United States
+- **📊 Real-time Stats**: Track policy activity across 90,000+ cities, counties, and states
+- **🏢 Nonprofit Discovery**: Explore 1.8M organizations from IRS data enriched with Every.org
+- **📅 Meeting Minutes**: Search 250,000+ government meeting transcripts and agendas
+- **🎯 Geographic Filtering**: Browse by state, county, or city to find local opportunities
+- **🔐 OAuth Login**: Sign in with HuggingFace, GitHub, or Google to save your preferences
+
+## 🚀 Three Services Architecture
+
+This deployment runs three integrated services:
+
+1. **📚 Documentation** (Docusaurus) - `/docs/`
+2. **🖥️ Main Application** (React + Vite) - `/`
+3. **⚡ API Backend** (FastAPI) - `/api/`
+
+All services are reverse-proxied through nginx on port 7860.
+
+## 📖 Quick Start
+
+### Browse Without Login
+- Click "Browse All" to explore data by state
+- Use the search bar to find organizations, contacts, or causes
+- Filter by location using the state/county/city selectors
+
+### Sign In for Personalization
+- Click "Login" in the top right
+- Choose your OAuth provider (HuggingFace, GitHub, or Google)
+- Follow organizations, leaders, and causes you care about
+- Get personalized recommendations
+
+### Explore the API
+- Visit `/redoc` for interactive API documentation
+- Try the search endpoints with state filters
+- Export data in JSON format for your own projects
+
+## 🛠️ Technology Stack
+
+- **Frontend**: React 18 + TypeScript + Vite + TailwindCSS + shadcn/ui
+- **Backend**: Python 3.11 + FastAPI + Pydantic
+- **Data**: Delta Lake + Parquet (90GB+ of civic data)
+- **Docs**: Docusaurus v3
+- **Infrastructure**: nginx + supervisor + Docker
+
+## 📊 Data Sources
+
+- **IRS BMF**: 1.8M tax-exempt organizations
+- **Every.org**: Nonprofit enrichment (logos, causes, revenue)
+- **Open States**: State legislators and bills (7,300+ officials)
+- **Census**: Jurisdictions and boundaries (90,000+)
+- **CityScrapers**: Local government meetings
+- **OpenCivicData**: Standardized government data
+
+## 🔗 Links
+
+- **Repository**: [github.com/getcommunityone/open-navigator](https://github.com/getcommunityone/open-navigator)
+- **Documentation**: Click "📚 Browse Documentation" on the homepage
+- **API Docs**: `/redoc` endpoint
+- **Website**: [www.communityone.com](https://www.communityone.com)
+
+## 📝 License
+
+Apache License 2.0 - Free for commercial and non-commercial use
+
+## 🤝 Contributing
+
+We welcome contributions! See CONTRIBUTING.md in the repository for guidelines.
+
+## 💬 Support
+
+- **Issues**: [GitHub Issues](https://github.com/getcommunityone/open-navigator/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/getcommunityone/open-navigator/discussions)
+- **Email**: hello@communityone.com
+
+---
+
+Built with ❤️ for civic engagement and government transparency.

.huggingface/nginx.conf

@@ -0,0 +1,125 @@
+worker_processes auto;
+pid /tmp/nginx.pid;
+
+events {
+    worker_connections 1024;
+}
+
+http {
+    include /etc/nginx/mime.types;
+    default_type application/octet-stream;
+    
+    # Logging
+    access_log /app/logs/nginx-access.log;
+    error_log /app/logs/nginx-error.log;
+    
+    # Performance
+    sendfile on;
+    tcp_nopush on;
+    tcp_nodelay on;
+    keepalive_timeout 65;
+    types_hash_max_size 2048;
+    client_max_body_size 50M;
+    
+    # Compression
+    gzip on;
+    gzip_vary on;
+    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
+    
+    upstream fastapi_backend {
+        server 127.0.0.1:8000;
+    }
+    
+    server {
+        listen 7860;
+        server_name _;
+        
+        # Force HTTPS - HSTS header tells browsers to ALWAYS use HTTPS
+        add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+        
+        # Additional security headers
+        add_header X-Content-Type-Options "nosniff" always;
+        add_header X-Frame-Options "SAMEORIGIN" always;
+        add_header X-XSS-Protection "1; mode=block" always;
+        
+        # Documentation - serve static files built by Docusaurus
+        location /docs {
+            alias /app/static/docs;
+            try_files $uri $uri/ /docs/index.html;
+            
+            # Cache static assets - shorter for easier updates
+            location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
+                expires 1d;
+                add_header Cache-Control "public, max-age=86400";
+            }
+        }
+        
+        # API backend at /api/
+        location /api/ {
+            proxy_pass http://fastapi_backend/api/;
+            proxy_http_version 1.1;
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection 'upgrade';
+            proxy_set_header Host $host;
+            proxy_cache_bypass $http_upgrade;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_read_timeout 300s;
+            proxy_connect_timeout 75s;
+        }
+        
+        # API docs - route /api/docs to backend /docs
+        location = /api/docs {
+            proxy_pass http://fastapi_backend/docs;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+        
+        # API OpenAPI schema - support both /api/openapi.json and /openapi.json
+        location ~ ^/(api/)?(openapi\.json|redoc) {
+            proxy_pass http://fastapi_backend/$2;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+        
+        # Frontend assets - shorter cache for easier updates
+        location /assets/ {
+            alias /app/static/frontend/assets/;
+            expires 1d;
+            add_header Cache-Control "public, max-age=86400";
+        }
+        
+        # Main frontend app at root
+        location / {
+            root /app/static/frontend;
+            try_files $uri $uri/ /index.html;
+            
+            # NEVER cache index.html - force browser to check for new version
+            location = /index.html {
+                add_header Cache-Control "no-cache, no-store, must-revalidate";
+                add_header Pragma "no-cache";
+                add_header Expires "0";
+            }
+            
+            # Cache hashed assets (immutable) but shorter time for easier updates
+            location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
+                expires 1d;
+                add_header Cache-Control "public, max-age=86400";
+            }
+        }
+        
+        # Health check endpoint
+        location /health {
+            access_log off;
+            return 200 "OK";
+            add_header Content-Type text/plain;
+        }
+    }
+}

.huggingface/start.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+set -e
+
+echo "🚀 Starting CommunityOne on Hugging Face Spaces..."
+echo "📊 Three services architecture:"
+echo "  1. Documentation (Docusaurus) - Port 3000"
+echo "  2. Main Application (React + Vite) - Port 5173"
+echo "  3. API Backend (FastAPI) - Port 8000"
+echo "  4. Nginx Reverse Proxy - Port 7860 (HF Spaces public port)"
+echo ""
+
+# DEBUG: Check environment variable
+echo "🔍 Environment Check:"
+echo "   HF_SPACES = ${HF_SPACES:-NOT SET}"
+if [ "$HF_SPACES" = "1" ]; then
+    echo "   ✅ HF_SPACES is correctly set to 1"
+else
+    echo "   ❌ WARNING: HF_SPACES is not set to 1"
+    echo "   Setting HF_SPACES=1 now..."
+    export HF_SPACES=1
+fi
+echo ""
+
+# Create required directories
+mkdir -p /app/logs /app/data /var/log/supervisor
+
+# Verify static files exist
+echo "📁 Verifying static files..."
+if [ -d "/app/static/docs" ]; then
+    echo "✅ Documentation static files found"
+    ls -lh /app/static/docs/ | head -5
+else
+    echo "❌ ERROR: Documentation static files missing at /app/static/docs"
+    exit 1
+fi
+
+if [ -d "/app/static/frontend" ]; then
+    echo "✅ Frontend static files found"
+    ls -lh /app/static/frontend/ | head -5
+else
+    echo "❌ ERROR: Frontend static files missing at /app/static/frontend"
+    exit 1
+fi
+
+# Install serve for static file hosting (if not already installed)
+if ! command -v serve &> /dev/null; then
+    echo "📦 Installing serve for static file hosting..."
+    npm install -g serve
+fi
+
+# Test nginx configuration
+echo "🔧 Testing nginx configuration..."
+nginx -t
+
+# Initialize database if needed
+echo "💾 Initializing database..."
+python -c "from api.database import init_db; init_db()" || echo "⚠️  Database init skipped"
+
+# Start all services with supervisor
+echo "🎬 Starting all services with supervisor..."
+exec /usr/bin/supervisord -c /etc/supervisor/conf.d/supervisord.conf

.huggingface/supervisord.conf

@@ -0,0 +1,28 @@
+[supervisord]
+nodaemon=true
+logfile=/dev/stdout
+logfile_maxbytes=0
+pidfile=/tmp/supervisord.pid
+user=root
+
+[program:nginx]
+command=/usr/sbin/nginx -g "daemon off;"
+autostart=true
+autorestart=true
+stdout_logfile=/dev/stdout
+stdout_logfile_maxbytes=0
+stderr_logfile=/dev/stderr
+stderr_logfile_maxbytes=0
+priority=10
+
+[program:fastapi]
+command=uvicorn api.main:app --host 0.0.0.0 --port 8000 --log-level info --proxy-headers
+directory=/app
+autostart=true
+autorestart=true
+stdout_logfile=/dev/stdout
+stdout_logfile_maxbytes=0
+stderr_logfile=/dev/stderr
+stderr_logfile_maxbytes=0
+environment=PYTHONUNBUFFERED="1",HF_SPACES="1"
+priority=20

CITATIONS.md

@@ -0,0 +1,1474 @@
+# Citations and Acknowledgments
+
+This project uses several open datasets and research contributions. Please cite the following works when using or referencing this project.
+
+## 📚 **Datasets**
+
+### **MeetingBank Dataset**
+
+We use the MeetingBank benchmark dataset for meeting summarization and analysis.
+
+**Citation:**
+```
+Yebowen Hu, Tim Ganter, Hanieh Deilamsalehy, Franck Dernoncourt, Hassan Foroosh, Fei Liu.
+"MeetingBank: A Benchmark Dataset for Meeting Summarization"
+In Proceedings of the 61st Annual Meeting of the Association for Computational Linguistics (ACL),
+July 2023, Toronto, Canada.
+```
+
+**BibTeX:**
+```bibtex
+@inproceedings{hu-etal-2023-meetingbank,
+    title = "MeetingBank: A Benchmark Dataset for Meeting Summarization",
+    author = "Yebowen Hu and Tim Ganter and Hanieh Deilamsalehy and Franck Dernoncourt and Hassan Foroosh and Fei Liu",
+    booktitle = "Proceedings of the 61st Annual Meeting of the Association for Computational Linguistics (ACL)",
+    month = July,
+    year = "2023",
+    address = "Toronto, Canada",
+    publisher = "Association for Computational Linguistics",
+}
+```
+
+**Resources:**
+- Paper: https://arxiv.org/abs/2305.17529
+- Dataset: https://huggingface.co/datasets/huuuyeah/meetingbank
+- Zenodo: https://zenodo.org/record/7989108
+
+**What we use:**
+- 1,366 city council meetings from 6 U.S. cities
+- Meeting transcripts and summaries
+- Used for: Meeting discovery, transcript analysis, summarization benchmarking
+
+---
+
+## 🗂️ **Other Data Sources**
+
+### **U.S. Census Bureau**
+- Geographic boundaries and demographic data
+- Source: https://www.census.gov/
+- License: Public Domain (U.S. Government)
+
+### **Open States / Plural Policy** ⭐
+- Comprehensive state and local legislative information
+- Organization: Plural Policy (formerly Open States Foundation)
+- Source: https://openstates.org/
+- API: https://openstates.org/api/
+- Data Downloads: https://open.pluralpolicy.com/data/
+- License: Various (check per state)
+- API Key: Required for access (free tier: 50,000 requests/month)
+
+**Coverage:**
+- All 50 states + DC + Puerto Rico
+- 7,300+ state legislators
+- Millions of bills, votes, and legislative sessions
+- Monthly PostgreSQL database dumps (9.8GB+)
+
+**What we use:**
+- Bulk legislative session downloads (CSV/JSON/PostgreSQL)
+- State legislator data with committee assignments
+- Bill tracking and voting records
+- Legislative video sources (YouTube channels, Granicus portals)
+
+**Resources:**
+- Open Data: https://open.pluralpolicy.com/data/
+- Scrapers Repository: https://github.com/openstates/openstates-scrapers
+- Local Database Setup: https://docs.openstates.org/contributing/local-database/
+- Code of Conduct: https://docs.openstates.org/code-of-conduct/
+- Schema Documentation: https://github.com/openstates/people/blob/master/schema.md
+
+**BibTeX:**
+```bibtex
+@software{openstates,
+    title = {Open States},
+    author = {{Plural Policy}},
+    year = {2024},
+    url = {https://openstates.org/},
+    note = {Comprehensive state legislative data for all 50 U.S. states}
+}
+```
+
+**Potential Contributions:**
+- Our scraper patterns could be contributed to openstates-scrapers
+- Video source discovery could enhance their data
+- We follow their Code of Conduct for all contributions
+
+### **LegiScan** ⭐
+- Comprehensive legislative tracking and bill text database
+- Organization: LegiScan LLC
+- Source: https://legiscan.com/
+- API: https://legiscan.com/legiscan
+- License: API access requires subscription (free tier available with limitations)
+- Coverage: All 50 states + U.S. Congress + Washington D.C.
+- API Key: Required for access (free tier: limited requests)
+
+**Coverage:**
+- Real-time legislative tracking for all U.S. states and Congress
+- Full bill text, amendments, and legislative documents
+- Roll call votes and voting records
+- Committee assignments and hearings
+- Bill status tracking and history
+- Sponsor and co-sponsor information
+- Bill text in PDF, HTML, and plain text formats
+
+**What we use:**
+- Bill text downloads and full-text search
+- Legislative document archives
+- Bill status and tracking data
+- Voting records and roll calls
+- Supplement to Open States data for missing jurisdictions
+- Historical legislative data back to 2011
+
+**API Features:**
+- GetBillText: Retrieve full bill text in multiple formats
+- GetBill: Detailed bill metadata and status
+- GetRollCall: Voting records with legislator positions
+- GetSponsor: Sponsor and co-sponsor information
+- Search: Full-text search across all bills
+- GetDatasetList: Bulk dataset downloads
+
+**Resources:**
+- API Documentation: https://legiscan.com/legiscan
+- Dataset Downloads: https://legiscan.com/datasets
+- Search Interface: https://legiscan.com/gaits/search
+- State Coverage: https://legiscan.com/legiscan/states
+
+**BibTeX:**
+```bibtex
+@software{legiscan,
+    title = {LegiScan},
+    author = {{LegiScan LLC}},
+    year = {2024},
+    url = {https://legiscan.com/},
+    note = {Comprehensive legislative tracking and bill text database covering all 50 U.S. states and Congress}
+}
+```
+
+**Complementary to Open States:**
+- LegiScan provides bill text in multiple formats (PDF, HTML, plain text)
+- Historical data back to 2011 for all states
+- Real-time updates and notifications
+- More comprehensive document archives
+- Paid API provides higher rate limits and bulk downloads
+- Use LegiScan for bill text analysis, Open States for structured legislative data
+
+### **Harvard Dataverse**
+- Meeting datasets and civic engagement research
+- Source: https://dataverse.harvard.edu/
+- License: Varies by dataset
+
+### **City Scrapers** ⭐
+- Open source civic tech project for scraping local government meetings
+- Organization: Documenters.org / City Bureau
+- Source: https://cityscrapers.org/
+- GitHub: https://github.com/city-scrapers
+- License: MIT License (open source)
+- Coverage: Chicago, Pittsburgh, Detroit, Cleveland, Los Angeles (250+ government agencies)
+- What we use: Validated meeting URLs, Legistar/Granicus platform endpoints, spider code for scraper patterns
+- Used for: Meeting discovery, URL extraction, platform detection, scraper validation
+
+**City Scrapers Repositories:**
+- Chicago: https://github.com/city-scrapers/city-scrapers (~100 agencies)
+- Pittsburgh: https://github.com/city-scrapers/city-scrapers-pitt (~30 agencies)
+- Detroit: https://github.com/city-scrapers/city-scrapers-detroit (~40 agencies)
+- Cleveland: https://github.com/city-scrapers/city-scrapers-cle (~30 agencies)
+- Los Angeles: https://github.com/city-scrapers/city-scrapers-la (~50 agencies)
+
+**BibTeX:**
+```bibtex
+@software{city_scrapers,
+    title = {City Scrapers},
+    author = {{Documenters.org}},
+    year = {2024},
+    url = {https://cityscrapers.org/},
+    note = {Open source civic tech project providing validated scrapers for local government meetings across major U.S. cities}
+}
+```
+
+### **Google Civic Information API** ⭐
+- Government officials, polling locations, and election data
+- Organization: Google LLC
+- API Documentation: https://developers.google.com/civic-information
+- License: Free (with quota limits)
+- Rate Limit: 25,000 requests/day (free tier)
+- Coverage: U.S. federal, state, and local government officials; polling locations; election data
+- What we use: Elected officials by address, representative contact info, voting districts
+- Used for: Contact discovery, official verification, civic engagement tools
+
+**API Endpoints Used:**
+- Representatives by Address: Get all elected officials for a given address
+- Elections: Voter information, polling locations, ballot information
+- Divisions: Geographic/political divisions (OCD-IDs)
+
+**BibTeX:**
+```bibtex
+@misc{google_civic_api,
+    title = {Google Civic Information API},
+    author = {{Google LLC}},
+    year = {2024},
+    url = {https://developers.google.com/civic-information},
+    note = {API providing government official contact information, election data, and polling locations}
+}
+```
+
+**Terms of Service:**
+- Attribution required when displaying official data
+- Caching limited to 30 days
+- Must comply with Google API Terms of Service
+
+### **YouTube Data API v3** ⭐
+- Video metadata, channel information, and search for government meetings
+- Organization: Google LLC
+- API Documentation: https://developers.google.com/youtube/v3
+- License: Free (with quota limits)
+- Rate Limit: 10,000 units/day (free tier), search costs 100 units per request
+- Coverage: Global video platform with millions of government channels
+- What we use: Government channel discovery, meeting video metadata, transcript availability
+- Used for: Video discovery, channel statistics, meeting video archival
+
+**API Features Used:**
+- Search: Find government channels by jurisdiction name
+- Channels: Get channel metadata, subscriber counts, video counts
+- Videos: Metadata including title, description, upload date, duration
+- Captions: Check for closed caption/transcript availability
+
+**BibTeX:**
+```bibtex
+@misc{youtube_data_api,
+    title = {YouTube Data API v3},
+    author = {{Google LLC}},
+    year = {2024},
+    url = {https://developers.google.com/youtube/v3},
+    note = {API for accessing YouTube video metadata, channel information, and search functionality}
+}
+```
+
+**Terms of Service:**
+- YouTube API Services Terms: https://developers.google.com/youtube/terms/api-services-terms-of-service
+- Attribution required with YouTube logo
+- Quota limits enforced (10,000 units/day free)
+- Video embeds must use official YouTube player
+
+### **Ballotpedia** ⭐
+- Ballot measures, referendums, and propositions
+- Organization: Lucy Burns Institute
+- Source: https://ballotpedia.org/
+- API: https://ballotpedia.org/API-documentation
+- License: API access is limited at scale (paid tier available)
+- Coverage: All 50 states, historical measures back to 1990s
+- Used for: Tracking fluoridation votes, school bond measures, health policy propositions
+
+### **MIT Election Data + Science Lab**
+- Presidential, Congressional, and gubernatorial election results
+- Organization: Massachusetts Institute of Technology
+- Source: https://electionlab.mit.edu/data
+- Repository: https://github.com/MEDSL/official-returns
+- License: Free for research and commercial use
+- Coverage: 1976-present, county-level results
+- Used for: Political composition analysis, jurisdiction context
+
+### **OpenElections**
+- State-by-state certified election results in standardized CSV format
+- Source: https://openelections.net/
+- GitHub: https://github.com/openelections
+- License: Open source (various by state)
+- Coverage: All 50 states (various completion levels), precinct-level data
+- Used for: Detailed election results, local race outcomes, advocacy targeting
+
+### **Open Civic Data (OCD) Standards**
+- Division identifiers and civic data standards
+- Specification: https://open-civic-data.readthedocs.io/en/latest/proposals/0002.html
+- Repository: https://github.com/opencivicdata/ocd-division-ids
+- License: Open source
+- Used for: Standardized jurisdiction identifiers, cross-platform compatibility
+
+### **Popolo Project**
+- International open government data specification for people, organizations, and elected positions
+- Specification: https://www.popoloproject.com/
+- GitHub: https://github.com/popolo-project/popolo-spec
+- Documentation: http://www.popoloproject.com/specs/
+- License: Creative Commons Attribution 4.0 International
+
+### **BillMap** ⭐
+- Tracks bill text similarity across all 50 U.S. states to identify copy-paste legislation and model bill influence
+- Organization: Sunlight Foundation / @unitedstates community
+- Repository: https://github.com/unitedstates/BillMap
+- Research: Anderson et al., "Detecting Policy Influence in Legislatures" (2019)
+- Paper: https://arxiv.org/abs/1906.03699
+- Live Demo: https://billmap.cs.princeton.edu/
+- License: Open source
+- Coverage: All 50 states, tracks legislative text diffusion across jurisdictions
+- Used for: Identifying model legislation, tracking policy influence, finding similar bills across states
+- Method: Text similarity analysis, n-gram matching, bill text alignment
+
+**What we use:**
+- Bill similarity detection algorithms
+- Model legislation tracking methodology
+- Cross-state policy diffusion analysis
+- Legislative text comparison techniques
+
+**BibTeX:**
+```bibtex
+@article{anderson2019billmap,
+    title = {Detecting Policy Influence in Legislatures},
+    author = {Anderson, Evan and Fowler, Anthony and Grossmann, Matt and Sahn, Alexander and Shiraito, Yuki},
+    journal = {arXiv preprint arXiv:1906.03699},
+    year = {2019},
+    url = {https://arxiv.org/abs/1906.03699}
+}
+```
+
+### **@unitedstates Images Repository** ⭐
+- High-resolution photos of all U.S. Congress members (past and present)
+- Organization: @unitedstates community (Sunlight Foundation legacy project)
+- Repository: https://github.com/unitedstates/images
+- CDN: https://theunitedstates.io/images/congress/
+- License: Public domain (government photos)
+- Coverage: All U.S. Senators and Representatives (1789-present), updated regularly
+- Image Format: JPEG, multiple resolutions (original, 450x550, 225x275)
+- Used for: Legislator profile photos, visual identification, representative directories
+
+**Image URL Format:**
+```
+https://theunitedstates.io/images/congress/original/[bioguide_id].jpg
+https://theunitedstates.io/images/congress/450x550/[bioguide_id].jpg
+https://theunitedstates.io/images/congress/225x275/[bioguide_id].jpg
+```
+
+**Example:**
+```
+https://theunitedstates.io/images/congress/original/P000197.jpg
+(Nancy Pelosi, bioguide_id: P000197)
+```
+
+**What we use:**
+- Legislator profile photos for federal representatives
+- Visual identification in advocacy tools
+- Representative directories and contact pages
+- Cross-referenced with Open States data using bioguide IDs
+
+**Related Projects:**
+- **congress-legislators**: https://github.com/unitedstates/congress-legislators (YAML data files)
+- **congress**: https://github.com/unitedstates/congress (scraping tools)
+- **districts**: https://github.com/unitedstates/districts (GeoJSON boundaries)
+
+---
+
+## 💰 **Nonprofit Financial Data**
+
+### **GivingTuesday 990 Data Infrastructure** ⭐
+
+We use the GivingTuesday 990 Data Lake for detailed nonprofit financial data from IRS Form 990 XML filings.
+
+**Organization:** GivingTuesday  
+**Website:** https://990data.givingtuesday.org/  
+**Data Lake:** `s3://gt990datalake-rawdata` (AWS S3, us-east-1 Virginia, Public Access)  
+**Console:** https://us-east-1.console.aws.amazon.com/s3/buckets/gt990datalake-rawdata  
+**License:** Public domain (IRS data) + Open source tools  
+**Access:** Free, no AWS credentials required (anonymous access via `--no-sign-request`)
+
+**What we use:**
+- **Raw 990 XMLs**: Individual e-filed Form 990 returns in XML format (1-2 MB each)
+- **Indices**: CSV/Parquet files listing all available 990s with metadata
+- **Coverage**: 5.4M+ e-filed Form 990s (2011-present, ~300K new filings/year)
+- **Scale**: ~10 TB of raw XML data
+- **Data extracted**: Revenue, expenses, assets, liabilities, grants, programs, officer compensation, mission statements, website URLs
+
+**Data Lake Structure:**
+```
+s3://gt990datalake-rawdata/
+├── EfileData/
+│   ├── XmlFiles/              # Individual 990 XMLs (~5.4M files, ~10 TB)
+│   │   └── [OBJECT_ID]_public.xml  (e.g., 202233259349300703_public.xml)
+│   └── XmlZips/               # ZIP archives (97 files, ~38 GB → ~95 GB uncompressed)
+│       └── YYYY_TEOS_XML_*.zip     (e.g., 2023_TEOS_XML_01A.zip ~400 MB)
+└── Indices/
+    └── 990xmls/               # CSV indices with metadata
+        └── index_all_years_efiledata_xmls_created_on_2023-10-29.csv (~925 MB)
+```
+
+**Download Strategies:**
+
+| Approach | Best For | Time | Bandwidth | Storage |
+|----------|----------|------|-----------|---------|
+| **Individual XMLs** | Single state or targeted download | ~2 hrs (22K orgs) | 32 GB | 32 GB |
+| **ZIP Archives** | All states / nationwide | ~6 hrs total | 38 GB | 95 GB |
+
+**Choose Individual XMLs when:**
+- You need data for 1-5 states only
+- You want to download only specific EINs
+- Storage space is limited
+- You want incremental caching (download as needed)
+
+**Choose ZIP Archives when:**
+- You need all 50 states
+- You're building a comprehensive nonprofit database
+- You have 100+ GB storage
+- You want offline access to all filings
+
+**S3 Access Examples:**
+
+**Individual XMLs (for single state or targeted download):**
+```bash
+# List index files (no credentials needed)
+aws s3 ls s3://gt990datalake-rawdata/Indices/990xmls/ --no-sign-request
+
+# Download index (~925 MB)
+aws s3 cp s3://gt990datalake-rawdata/Indices/990xmls/index_all_years_efiledata_xmls_created_on_2023-10-29.csv . --no-sign-request
+
+# Download specific XML
+aws s3 cp s3://gt990datalake-rawdata/EfileData/XmlFiles/202233259349300703_public.xml . --no-sign-request
+
+# Batch download for single state (using our script)
+python scripts/batch_download_990s.py --state MA --health-only --concurrent 1000
+```
+
+**ZIP Archives (for all states / nationwide):**
+```bash
+# Download all 97 ZIPs (~38 GB) to local directory
+./scripts/download_990_zips.sh
+
+# Extract all ZIPs to get ~384K XMLs (~95 GB)
+./scripts/extract_990_zips.sh
+
+# Build local index for fast lookup
+python scripts/build_990_local_index.py
+
+# Now enrich from local files (no network needed!)
+python scripts/enrich_all_states_990.py
+```
+
+**Index Schema:**
+The CSV index contains columns: `EIN`, `TaxPeriod`, `ObjectId`, `URL`, `FormType`, `OrganizationName`, `DLN`, `SubmittedOn`
+
+**Python Access:**
+```python
+import boto3
+from botocore import UNSIGNED
+from botocore.config import Config
+
+# Configure anonymous S3 client
+s3 = boto3.client('s3', config=Config(signature_version=UNSIGNED))
+
+# Download XML
+xml_obj = s3.get_object(
+    Bucket='gt990datalake-rawdata',
+    Key='EfileData/XmlFiles/202233259349300703_public.xml'
+)
+xml_content = xml_obj['Body'].read()
+```
+
+**BibTeX:**
+```bibtex
+@misc{givingtuesday990data,
+    title = {GivingTuesday 990 Data Infrastructure},
+    author = {{GivingTuesday}},
+    year = {2023},
+    url = {https://990data.givingtuesday.org/},
+    note = {Collaborative data lake of standardized IRS Form 990 XML filings}
+}
+```
+
+**Attribution:** When publishing analyses using this data, please cite both:
+1. GivingTuesday 990 Data Infrastructure: https://990data.givingtuesday.org/
+2. Our enrichment tools: https://github.com/getcommunityone/open-navigator-for-engagement
+
+---
+
+### **Google Cloud Public Datasets: IRS 990** ⭐
+
+Google hosts the complete IRS Form 990 dataset in BigQuery for fast SQL-based querying.
+
+**Platform:** Google Cloud BigQuery  
+**Dataset:** `bigquery-public-data.irs_990`  
+**Table:** `bigquery-public-data.irs_990.irs_990_xml`  
+**Documentation:** https://console.cloud.google.com/marketplace/product/internal-revenue-service/irs-990  
+**Cost:** First 1 TB of queries per month is **FREE**  
+**Coverage:** All e-filed Form 990s (2011-present, 5M+ records)
+
+**What we use:**
+- **Mission statements**: Extracted from `return_header` or `part_i_mission_desc` fields
+- **Website URLs**: Found in `website_address_txt` field
+- **Financial data**: All Form 990 fields accessible via SQL
+- **Fast bulk queries**: Extract data for 1M+ orgs in seconds (vs hours downloading XMLs)
+
+**Advantages:**
+- ✅ No local XML downloads needed
+- ✅ Single SQL query to bulk-extract fields
+- ✅ Serverless (no infrastructure to manage)
+- ✅ Fast (queries complete in seconds)
+- ✅ Free tier covers most research use cases
+
+**Example Query:**
+```sql
+SELECT 
+  ein,
+  org_name,
+  website_address_txt,
+  part_i_mission_desc,
+  total_revenue_current_year,
+  total_expenses_current_year
+FROM `bigquery-public-data.irs_990.irs_990_2023`
+WHERE state = 'AL'
+  AND ntee_code LIKE 'E%'
+LIMIT 1000;
+```
+
+**BibTeX:**
+```bibtex
+@misc{googlecloud_irs990,
+    title = {IRS 990 Public Dataset},
+    author = {{Google Cloud Public Datasets}},
+    year = {2024},
+    publisher = {Google Cloud Platform},
+    url = {https://console.cloud.google.com/marketplace/product/internal-revenue-service/irs-990},
+    note = {BigQuery public dataset of IRS Form 990 e-file data}
+}
+```
+
+**Attribution:** When using BigQuery 990 data, cite:
+1. IRS 990 Public Dataset (Google Cloud)
+2. Internal Revenue Service (original data source)
+
+---
+
+### **National Center for Charitable Statistics (NCCS) Unified BMF** ⭐
+
+The NCCS Unified BMF is a longitudinal nonprofit dataset specifically designed for AI and "Lakehouse" projects with pre-geocoded locations and Census integration.
+
+**Organization:** National Center for Charitable Statistics (NCCS), Urban Institute  
+**Website:** https://nccs.urban.org/  
+**Dataset:** Unified BMF (Business Master File)  
+**Documentation:** https://nccs.urban.org/project/irs-exempt-organizations-business-master-file  
+**License:** Public domain (IRS data) + Urban Institute terms  
+**Released:** Late 2025/Early 2026  
+**Coverage:** 1989 through mid-2025 (update pending)
+
+**What we use:**
+- **Longitudinal tracking**: Single file with one row per organization that has ever held tax-exempt status
+- **Pre-geocoded addresses**: Most recent address geocoded to Census block level
+- **Geographic codes**: FIPS codes at block, tract, county, and state levels
+- **Metropolitan area codes**: Current CBSA (Core Based Statistical Area) definitions
+- **Temporal tracking**: `ORG_YEAR_FIRST` and `ORG_YEAR_LAST` variables for organization lifecycle
+- **Census integration**: Ready for merging with Census demographic and economic data
+
+**Key Features:**
+- ✅ **Eliminates annual file merging**: Consolidates all historical BMF releases into single file
+- ✅ **AI/Lakehouse optimized**: Designed for modern data infrastructure
+- ✅ **Census-ready**: FIPS codes enable direct joins with Census data
+- ✅ **Metropolitan vs Rural**: CBSA codes identify urban/rural areas
+- ✅ **Historical analysis**: Track organizations over time without complex ETL
+- ✅ **Geographic analysis**: Pre-geocoded to Census block granularity
+
+**Use Cases:**
+- Longitudinal analysis of nonprofit sector
+- Building historical sampling frames
+- Linking nonprofit data to Census demographics
+- Metropolitan vs rural nonprofit analysis
+- Policy research requiring geographic precision
+- Time-series analysis of organizational entry/exit
+
+**Geographic Levels Available:**
+- Census Block (finest granularity)
+- Census Tract
+- County (FIPS codes)
+- State (FIPS codes)
+- CBSA (Core Based Statistical Area)
+
+**Related Resources:**
+- NCCS Census Crosswalk: For aggregating to additional geographic levels
+- BMF Overview: https://nccs.urban.org/project/irs-exempt-organizations-business-master-file
+- NCCS Data Archive: https://nccs.urban.org/nccs-data-archive
+
+**BibTeX:**
+```bibtex
+@dataset{nccs_unified_bmf,
+    title = {Unified Business Master File (BMF)},
+    author = {{National Center for Charitable Statistics}},
+    year = {2026},
+    publisher = {Urban Institute},
+    url = {https://nccs.urban.org/},
+    note = {Longitudinal nonprofit dataset with pre-geocoded Census integration, 1989-2025}
+}
+```
+
+**Attribution:** When using NCCS Unified BMF data, cite:
+1. National Center for Charitable Statistics, Urban Institute
+2. IRS Business Master File (original data source)
+3. Specify the data vintage/update date used
+
+---
+
+### **Charity Navigator** ⭐
+
+**Powered by Charity Navigator**
+
+We use the Charity Navigator GraphQL API to enrich nonprofit profiles with star ratings, mission statements, and organizational metrics.
+
+**Organization:** Charity Navigator, Inc.  
+**Website:** https://www.charitynavigator.org  
+**API Documentation:** https://www.charitynavigator.org/partner/api  
+**Principal Office:** 299 Market Street, Suite 250, Saddle Brook, NJ 07663  
+**License:** API Terms of Use (Last updated March 2025)  
+**Rate Limit:** 1,000 API calls per day  
+
+**What we use:**
+- **Charity Ratings**: Encompass Star Rating (0-4 stars)
+- **Mission Statements**: Organization mission and purpose
+- **Website URLs**: Official organization websites
+- **Organizational Data**: EIN, name, address, category, cause
+- **Active Advisories**: Alerts about organization status
+- **Encompass Score**: Overall rating score
+- **Rating Publication Date**: When the rating was last updated
+
+**Data Fields Accessed:**
+```
+- Employer Identification Number (EIN)
+- Charity Name
+- Mission
+- Organization Website URL
+- Charity Navigator URL
+- Category & Cause
+- Street Address, City, State, Zip, Country
+- Active Advisories
+- Encompass Score & Star Rating
+- Encompass Rating Publication Date & ID
+```
+
+**Attribution Requirements:**
+- **Text Credit:** "Powered by Charity Navigator" (displayed on pages using their data)
+- **Source Citation:** Charity Navigator cited as source on all pages displaying their data
+- **Linkbacks:** All charity data links back to corresponding Charity Navigator profile pages
+- **Trademark Notice:** CHARITY NAVIGATOR and the CHARITY NAVIGATOR logo are registered trademarks of Charity Navigator. All rights reserved. Used with permission.
+
+**BibTeX:**
+```bibtex
+@misc{charitynavigator_api,
+    title = {Charity Navigator API},
+    author = {{Charity Navigator, Inc.}},
+    year = {2025},
+    url = {https://www.charitynavigator.org},
+    note = {GraphQL API providing nonprofit ratings, mission statements, and organizational data}
+}
+```
+
+**Compliance:**
+This project complies with Charity Navigator's API Terms of Use, including:
+- Rate limit compliance (max 1,000 calls/day)
+- Proper attribution and branding
+- Linkbacks to Charity Navigator profile pages
+- Trademark acknowledgment
+- Data caching for performance only (not for redistribution)
+
+**Example Profile Link Format:**
+```html
+<a href="https://www.charitynavigator.org/ein/134141945">
+  Michael J. Fox Foundation for Parkinson's Research
+</a>
+```
+
+**Related Tools:**
+- [Nonprofit enrichment script](scripts/enrich_nonprofits_charitynavigator.py) (if created)
+- [API integration documentation](website/docs/data-sources/charity-navigator.md) (if created)
+
+---
+
+### **OpenSecrets.org (Center for Responsive Politics)** ⭐
+
+**Organization:** OpenSecrets, a nonpartisan research organization tracking money in U.S. politics  
+**Website:** https://www.opensecrets.org  
+**Bulk Data:** https://www.opensecrets.org/open-data/bulk-data  
+**API Documentation:** https://www.opensecrets.org/open-data/api  
+**Status:** Bulk data access pending approval
+
+**What they offer:**
+- **Campaign Finance Data**: Federal campaign contributions, expenditures, and fundraising
+- **Lobbying Data**: Federal lobbying spending by organizations and industries
+- **Political Action Committees (PACs)**: PAC contributions and expenditures
+- **Personal Finance Disclosures**: Wealth and financial interests of federal lawmakers
+- **501(c) Organizations**: Political spending by nonprofits and dark money groups
+- **Foreign Lobby Influence**: Foreign agents registered under FARA
+
+**Data Access:**
+- **Bulk Data Downloads**: Available to nonprofits upon approval (application pending)
+- **Public API**: Available with rate limits for smaller queries
+- **Data Format**: CSV files with detailed transaction-level records
+- **Update Frequency**: Regular updates as new filings are processed
+- **Coverage**: Federal-level political finance data (1990-present)
+
+**What we plan to use:**
+- Nonprofit political spending and advocacy activity
+- Lobbying expenditures by healthcare and oral health organizations
+- Campaign contributions from dental associations and health policy groups
+- 501(c)(4) "dark money" spending on ballot measures
+- Cross-reference EINs with IRS nonprofit data for comprehensive profiles
+
+**BibTeX:**
+```bibtex
+@misc{opensecrets,
+    title = {OpenSecrets.org: Money in Politics Database},
+    author = {{Center for Responsive Politics}},
+    year = {2024},
+    url = {https://www.opensecrets.org},
+    note = {Comprehensive database of campaign finance, lobbying, and political spending in U.S. politics}
+}
+```
+
+**License & Attribution:**
+- Data collected from Federal Election Commission (FEC) and other public sources
+- Attribution required: "Data from OpenSecrets.org, a project of the Center for Responsive Politics"
+- Nonprofit bulk data access subject to approval and terms of use
+
+**Application Status:**
+- ⏳ Bulk data access application pending approval
+- Will enable comprehensive analysis of nonprofit political activity
+- Integration planned upon approval
+
+---
+
+### **IRS Exempt Organizations Business Master File (EO-BMF)**
+
+Basic nonprofit registration data (name, EIN, address, NTEE code).
+
+### **IRS Exempt Organizations Business Master File (EO-BMF)**
+- Complete database of 1.9M+ U.S. tax-exempt organizations
+- Organization: Internal Revenue Service (IRS)
+- Source: https://www.irs.gov/charities-non-profits/exempt-organizations-business-master-file-extract-eo-bmf
+- Download: https://www.irs.gov/pub/irs-soi/ (4 regional CSV files)
+- Format: CSV (basic organizational data: name, EIN, address, NTEE code, etc.)
+- Update frequency: Monthly
+- License: Public Domain (U.S. Government data)
+- Coverage: All registered tax-exempt organizations under sections 501(c)(3), 501(c)(4), etc.
+- Used for: Nonprofit discovery, organization matching, NTEE categorization
+
+**Note:** This is the **Business Master File** (basic info). For detailed financial data, see IRS Form 990 XML below.
+
+### **IRS Form 990 XML Filings** ⭐
+- Detailed financial filings from nonprofit tax returns
+- Organization: Internal Revenue Service (IRS)
+- Source: https://www.irs.gov/charities-non-profits/form-990-series-downloads
+- Format: XML (highly detailed financial and operational data)
+- Parser Tools: **Giving Tuesday** open source libraries
+  - XML Parser: https://github.com/Giving-Tuesday/form-990-xml-parser
+  - XML Mapper: https://github.com/Giving-Tuesday/form-990-xml-mapper
+- AWS S3 Index: https://registry.opendata.aws/irs990/
+- License: Public Domain (U.S. Government data)
+- Coverage: Annual filings from organizations with >$50K revenue
+- Data includes: Detailed revenue, expenses, program services, officer compensation, grants, donors
+- Used for: Financial analysis, transparency, grant research, program evaluation
+
+**Giving Tuesday Attribution:**
+The Giving Tuesday Data Commons provides essential tools for parsing IRS Form 990 XML data:
+```bibtex
+@software{giving_tuesday_form990_parser,
+  title = {Form 990 XML Parser},
+  author = {{Giving Tuesday}},
+  year = {2024},
+  url = {https://github.com/Giving-Tuesday/form-990-xml-parser},
+  note = {Open source Python library for parsing IRS Form 990 XML filings}
+}
+
+@software{giving_tuesday_form990_mapper,
+  title = {Form 990 XML Mapper},
+  author = {{Giving Tuesday}},
+  year = {2024},
+  url = {https://github.com/Giving-Tuesday/form-990-xml-mapper},
+  note = {Maps Form 990 XML to standardized data structures}
+}
+```
+
+**More Giving Tuesday Resources:**
+- GitHub Organization: https://github.com/Giving-Tuesday
+- Data Commons: https://www.givingtuesday.org/data-commons
+- Research & Insights: https://www.givingtuesday.org/research
+- Coverage: Standardized schemas for Person, Organization, Membership, Post, Area, Motion, VoteEvent, Count
+- Used for: Leader/official data modeling, organization structure, membership tracking, voting records
+- Adoption: Used by Civic Commons, OpenNorth, mySociety, Sunlight Foundation, and 30+ civic tech organizations worldwide
+- Citation: "Popolo Project. Open government data specifications. https://www.popoloproject.com/"
+- **Key Features:**
+  - **Person**: Names, contact details, identifiers, links to images/sources
+  - **Organization**: Names, classification, founding/dissolution dates, contact information
+  - **Membership**: Relationship between persons and organizations (with roles and time periods)
+  - **Post**: Positions within organizations (e.g., "Mayor", "City Council Member District 3")
+  - **VoteEvent**: Votes on motions/bills with individual voter positions
+- **Our Implementation**: LEADER and ORGANIZATION entities follow Popolo schema for maximum interoperability with civic tech platforms
+
+**Popolo Dependencies & Standards:**
+The Popolo specification builds upon and references the following W3C, IETF, and open data standards:
+
+| Publisher | Specification | Prefix | Use in Popolo | URL |
+|-----------|---------------|--------|---------------|-----|
+| Bibliographic Framework Initiative | BIBFRAME Vocabulary | `bf` | Bibliographic references | https://www.loc.gov/bibframe/ |
+| Ian Davis | BIO: Biographical Information | `bio` | Life events, relationships | http://purl.org/vocab/bio/0.1/ |
+| W3C | Contact: Utility concepts | `con` | Contact information | http://www.w3.org/2000/10/swap/pim/contact# |
+| DCMI | DCMI Metadata Terms | `dcterms` | Metadata, provenance | https://www.dublincore.org/specifications/dublin-core/dcmi-terms/ |
+| FOAF Project | FOAF Vocabulary | `foaf` | People, social networks | http://xmlns.com/foaf/0.1/ |
+| GeoNames | GeoNames Ontology | `gn` | Geographic names | http://www.geonames.org/ontology/ |
+| ISA Programme | Location Core Vocabulary | `locn` | Addresses, locations | https://www.w3.org/ns/locn |
+| OSCA Foundation | NEPOMUK Calendar Ontology | `ncal` | Events, meetings | http://www.semanticdesktop.org/ontologies/ncal/ |
+| Open Data Institute | Open Data Rights Statement | `odrs` | Data licensing | http://schema.theodi.org/odrs |
+| W3C | The Organization Ontology | `org` | Organizational structures | https://www.w3.org/TR/vocab-org/ |
+| ISA Programme | Person Core Vocabulary | `person` | Person attributes | http://www.w3.org/ns/person |
+| W3C | RDF Schema | `rdfs` | Semantic web foundation | https://www.w3.org/TR/rdf-schema/ |
+| W3C | Schema.org | `schema` | Structured data | https://schema.org/ |
+| W3C | SKOS | `skos` | Taxonomies, classification | https://www.w3.org/2004/02/skos/ |
+| IETF | vCard Format | `vcard` | Contact information | https://www.rfc-editor.org/rfc/rfc6350.html |
+
+**Popolo Classes Implemented:**
+- ✅ **Person** → LEADER entity (elected officials, appointees)
+- ✅ **Organization** → ORGANIZATION entity (nonprofits, government agencies)
+- ✅ **Membership** → Implicit through leader_id/organization relationships
+- ✅ **Post** → position_type, office fields in LEADER
+- ✅ **Contact Detail** → email, phone, website fields
+- ✅ **Motion** → AGENDA items, LEGISLATION entities
+- ✅ **Vote Event** → VOTE entity
+- ✅ **Count** → vote_yes, vote_no in VOTE and LEGISLATION
+- ✅ **Area** → JURISDICTION entity (geographic/political boundaries)
+- ✅ **Event** → MEETING entity
+- ✅ **Speech** → Extracted from MINUTES, VIDEO transcripts
+
+### **Roper Center for Public Opinion Research**
+- Scientifically validated survey questions and public opinion data
+- Organization: Cornell University
+- Source: https://ropercenter.cornell.edu/
+- iPoll Database: https://ropercenter.cornell.edu/ipoll/
+- License: Free public search (metadata and question wording), full data requires institutional membership
+- Coverage: 500,000+ survey questions from 1930s-present, all major polling organizations
+- Used for: Topic definitions, validated question wording, national opinion baselines, messaging optimization
+- Citation: "Roper Center for Public Opinion Research, Cornell University. iPoll Databank. https://ropercenter.cornell.edu/ipoll/"
+
+### **Google Fact Check Tools API**
+- Aggregated fact-checking data with ClaimReview structured data
+- Organization: Google LLC
+- Source: https://toolbox.google.com/factcheck/explorer
+- API: https://developers.google.com/fact-check/tools/api
+- Schema: https://developers.google.com/search/docs/appearance/structured-data/factcheck
+- License: Free API with quota (10,000 queries/day)
+- Coverage: 100+ fact-checking organizations worldwide, all claim types
+- Used for: Verifying claims from meetings/legislation, tracking misinformation, accountability scoring
+- Citation: "Google Fact Check Tools API. Google LLC. https://developers.google.com/fact-check/tools/api"
+
+### **FactCheck.org**
+- Nonpartisan fact-checking of political claims and viral misinformation
+- Organization: Annenberg Public Policy Center, University of Pennsylvania
+- Source: https://www.factcheck.org/
+- License: Free (web scraping allowed with rate limiting)
+- Coverage: National politics, health claims, science, viral content (2003-present)
+- Used for: Verifying political claims, health policy fact-checking, scientific claim verification
+- Citation: "FactCheck.org. Annenberg Public Policy Center, University of Pennsylvania. https://www.factcheck.org/"
+
+### **PolitiFact**
+- Pulitzer Prize-winning fact-checking with Truth-O-Meter ratings
+- Organization: Poynter Institute
+- Source: https://www.politifact.com/
+- License: Free (web scraping allowed with rate limiting)
+- Coverage: All 50 states, federal politics, ballot measures (2007-present)
+- Rating Scale: 6-point (True, Mostly True, Half True, Mostly False, False, Pants on Fire)
+- Used for: State-level fact-checking, tracking politician claims, ballot measure verification
+- Citation: "PolitiFact. Poynter Institute. https://www.politifact.com/"
+
+### **Schema.org**
+- Structured data vocabulary for semantic web markup
+- Organization: W3C Community Group (sponsors: Google, Microsoft, Yahoo, Yandex)
+- Source: https://schema.org/
+- Documentation: https://schema.org/docs/schemas.html
+- License: Creative Commons Attribution-ShareAlike License (CC BY-SA 3.0)
+- Coverage: 800+ types, 1,400+ properties for describing web content
+- Used for: SEO-optimized structured data, JSON-LD exports, API documentation, search engine compatibility
+- Citation: "Schema.org. W3C Community Group. https://schema.org/"
+
+**Our Schema.org Type Mappings:**
+
+| Our Entity | Schema.org Type | Properties Used | Use Case |
+|------------|----------------|-----------------|----------|
+| JURISDICTION | [AdministrativeArea](https://schema.org/AdministrativeArea) | name, address, geo, telephone, url | City/county geographic data |
+| MEETING | [Event](https://schema.org/Event) + [GovernmentService](https://schema.org/GovernmentService) | name, startDate, location, organizer, description | Public meetings, hearings |
+| LEADER | [Person](https://schema.org/Person) + [GovernmentOfficial](https://schema.org/GovernmentOfficial) | name, email, telephone, jobTitle, worksFor | Elected officials |
+| ORGANIZATION | [Organization](https://schema.org/Organization) + [NGO](https://schema.org/NGO) | name, address, telephone, url, foundingDate | Nonprofits, agencies |
+| LEGISLATION | [Legislation](https://schema.org/Legislation) | name, legislationDate, legislationPassedBy, legislationType | Bills, ordinances |
+| BALLOT_MEASURE | [Legislation](https://schema.org/Legislation) + referendumProposal | name, datePosted, legislationChanges | Referendums, propositions |
+| VOTE | [VoteAction](https://schema.org/VoteAction) | agent (Person), candidate (Legislation), actionOption | Roll call votes |
+| FACT_CHECK | [ClaimReview](https://schema.org/ClaimReview) | claimReviewed, reviewRating, author, datePublished | Verified fact-checks |
+| SCHOOL_DISTRICT | [EducationalOrganization](https://schema.org/EducationalOrganization) | name, address, telephone, numberOfStudents | K-12 school districts |
+| NONPROFIT_FINANCES | [MonetaryGrant](https://schema.org/MonetaryGrant) | funder, amount, fundedItem | IRS Form 990 data |
+| VIDEO | [VideoObject](https://schema.org/VideoObject) | name, description, uploadDate, duration, thumbnailUrl | Meeting recordings |
+| DOCUMENT | [DigitalDocument](https://schema.org/DigitalDocument) | name, fileFormat, datePublished, url | PDFs, agendas, minutes |
+
+**Benefits:**
+- ✅ **SEO Enhancement**: Google Search rich results for meetings, officials, organizations
+- ✅ **Voice Assistant Ready**: Alexa, Google Assistant can parse our structured data
+- ✅ **Knowledge Graph**: Data appears in Google Knowledge Panels
+- ✅ **API Discoverability**: Standards-compliant REST/GraphQL responses
+- ✅ **Cross-platform**: Compatible with Apple Podcasts, Microsoft Bing, Yandex
+
+### **Common Education Data Standards (CEDS)**
+- Comprehensive education data standards for K-12, postsecondary, and workforce
+- Organization: U.S. Department of Education, National Center for Education Statistics (NCES)
+- Source: https://ceds.ed.gov/
+- GitHub: https://github.com/CEDStandards
+- Specification Repository: https://github.com/CEDStandards/CEDS-Elements
+- License: Public Domain (U.S. Government)
+- Coverage: 2,300+ data elements, 500+ option sets, alignment with NCES surveys
+- Used for: School district data modeling, NCES interoperability, education finance tracking
+- Citation: "Common Education Data Standards (CEDS). National Center for Education Statistics. https://ceds.ed.gov/"
+
+**CEDS Alignment for School Districts:**
+
+| Our Field | CEDS Element ID | CEDS Element Name | Description |
+|-----------|----------------|-------------------|-------------|
+| `nces_id` | 000827 | LEA Identifier (NCES) | National Center for Education Statistics LEA ID |
+| `district_name` | 000168 | Name of Institution | Legal name of the school district |
+| `district_type` | 000108 | LEA Type | Local, State, Federal, or Other |
+| `total_students` | 001475 | Student Count | Total number of students enrolled |
+| `total_schools` | 000856 | Number of Schools | Count of schools in district |
+| `total_revenue` | 000612 | Total Revenue | Sum of all revenue sources |
+| `total_expenditures` | 000611 | Total Expenditures | Sum of all spending categories |
+| `per_pupil_spending` | 000613 | Expenditure per Student | Total expenditures / student count |
+| `federal_revenue` | 000614 | Federal Revenue | Revenue from federal government |
+| `state_revenue` | 000615 | State Revenue | Revenue from state sources |
+| `local_revenue` | 000616 | Local Revenue | Revenue from property taxes, bonds |
+| `superintendent` | 000240 | Chief Administrator Name | District superintendent name |
+| `school_year` | 000243 | School Year | Academic year (e.g., 2023-2024) |
+
+**CEDS Option Sets Used:**
+- **LEA Type** (CEDS 000108): Regular, Specialized, Supervisory Union, Service Agency, State Agency, Federal Agency
+- **Grade Level** (CEDS 000100): PK, KG, 01-12, UG (ungraded)
+- **Operational Status** (CEDS 000533): Open, Closed, New, Added, Changed Agency, Temporarily Closed
+- **Locale Type** (CEDS 001315): City, Suburb, Town, Rural (NCES Urban-centric locale codes)
+
+**Benefits of CEDS Compliance:**
+- ✅ **NCES Compatibility**: Direct mapping to Common Core of Data (CCD) and F-33 Finance Survey
+- ✅ **State Reporting**: Aligns with state education department data systems
+- ✅ **Federal Grants**: Standardized reporting for ESSA, Title I, IDEA compliance
+- ✅ **Longitudinal Tracking**: Consistent identifiers for multi-year analysis
+- ✅ **Interoperability**: Works with Ed-Fi Alliance, IMS Global, SIF Association standards
+
+### **Microsoft Common Data Model for Nonprofits**
+- Industry-standard data model for nonprofit organizations built on Microsoft Dataverse
+- Organization: Microsoft Corporation
+- Repository: https://github.com/microsoft/Nonprofits/tree/master/CommonDataModelforNonprofits
+- ERD Documentation: https://github.com/microsoft/Nonprofits/blob/master/CommonDataModelforNonprofits/Documents/common-data-model-for-nonprofits-erds.pdf
+- License: MIT License
+- Coverage: Donor management, fundraising, program delivery, volunteer management, impact measurement, award/grant tracking
+- Used for: Nonprofit data standardization, Dynamics 365 integration, constituent relationship management, outcome tracking
+- Citation: "Microsoft Common Data Model for Nonprofits. Microsoft Corporation. https://github.com/microsoft/Nonprofits/"
+
+**Microsoft CDM Nonprofit Core Entities:**
+
+| Entity | Description | Our Implementation |
+|--------|-------------|--------------------|
+| **Constituent** | Individuals who interact with nonprofit (donors, volunteers, members, beneficiaries) | CONSTITUENT entity |
+| **Donation** | Financial contributions and in-kind gifts | DONATION entity |
+| **Designation** | How donations are allocated (programs, funds, campaigns) | designation_id in DONATION |
+| **Campaign** | Fundraising campaigns and appeals | CAMPAIGN entity |
+| **Membership** | Member enrollment and renewal tracking | MEMBERSHIP entity |
+| **Volunteer** | Volunteer activities, hours, and preferences | VOLUNTEER_ACTIVITY entity |
+| **Award** | Grants received by the nonprofit | Awards captured in NONPROFIT_FINANCES |
+| **Disbursement** | Spending of grant/award funds | Expenditures in GOVERNMENT_BUDGET |
+| **Objective** | Measurable program outcomes and impact | PROGRAM_OUTCOME entity |
+| **DeliveryFramework** | Programs and services delivered | PROGRAM_DELIVERY entity |
+| **Budget** | Organizational budgets and allocations | GOVERNMENT_BUDGET, SCHOOL_DISTRICT budgets |
+| **Indicator** | Key performance indicators for impact | Metrics in PROGRAM_OUTCOME |
+
+**Key Entity Relationships (Microsoft CDM Pattern):**
+- Constituent → Donation (one-to-many): A constituent makes many donations
+- Donation → Designation (many-to-one): Multiple donations to one fund/program
+- Campaign → Donation (one-to-many): A campaign receives many donations
+- Constituent → Membership (one-to-many): A constituent can have multiple memberships over time
+- Constituent → Volunteer (one-to-many): A constituent volunteers for multiple activities
+- Organization → DeliveryFramework (one-to-many): An organization delivers multiple programs
+- DeliveryFramework → Objective (one-to-many): A program has multiple outcome objectives
+
+**Benefits of Microsoft CDM Alignment:**
+- ✅ **Dynamics 365 Integration**: Native compatibility with Microsoft Cloud for Nonprofits
+- ✅ **Power Platform**: Direct use in Power BI, Power Apps, Power Automate
+- ✅ **Azure Synapse**: Seamless analytics with Azure data services
+- ✅ **Industry Standard**: Adopted by large nonprofits using Microsoft ecosystem
+- ✅ **Grant Compliance**: Built-in support for grant reporting and outcome measurement
+- ✅ **Constituent 360**: Unified view of donor, volunteer, member activities
+
+---
+
+## 🎯 **Grant Research and Fundraising Platforms**
+
+These platforms are built on open-source principles or community-funded models to keep grant and fundraising data accessible.
+
+### **Grantmakers.io** ⭐
+
+**"Free as in Freedom" Grant Research**
+
+Grantmakers.io is the gold standard for open, community-supported foundation research. It provides lightning-fast search through IRS 990-PF data with no login required.
+
+**Organization:** Community-supported open-source project  
+**Website:** https://www.grantmakers.io/  
+**Data Source:** IRS Form 990-PF (Private Foundation tax returns)  
+**License:** Open source, community-funded  
+**Access:** 100% free, no account or API key required  
+**Coverage:** All U.S. private foundations filing Form 990-PF (75,000+ grantmaking foundations)
+
+**What we use:**
+- **Foundation Giving Histories**: Search foundations by who they've funded in the past
+- **Grantee Databases**: Find all grants made to specific organizations
+- **Geographic Targeting**: Search by state, city, or region
+- **Funding Amounts**: Filter by grant size ranges
+- **NTEE Categories**: Search by nonprofit sector (health, education, environment, etc.)
+- **Year-over-Year Trends**: Track foundation giving patterns over time
+
+**Key Features:**
+- ⚡ **Lightning-Fast Search**: Instant results across millions of grant records
+- 🔓 **No Login Required**: Completely open access, no barriers
+- 📊 **Detailed 990-PF Data**: Full foundation financials, officers, assets
+- 🎯 **Relationship Mapping**: Discover foundation-grantee connections
+- 📈 **Trend Analysis**: Multi-year giving patterns and focus areas
+- 🆓 **Always Free**: Community-funded to remain accessible
+
+**Use Cases:**
+- **Grant Prospecting**: Find foundations that fund similar organizations in your area
+- **Relationship Research**: Identify foundations that have supported oral health, public health, or civic engagement
+- **Competitive Analysis**: See which organizations are receiving grants in your field
+- **Foundation Vetting**: Review foundation assets, giving patterns, and leadership before applying
+
+**Example Searches:**
+- Foundations that funded "fluoridation" or "oral health" projects
+- Grantmakers in Massachusetts supporting health policy advocacy
+- Foundations with >$10M assets funding civic engagement
+- All grants made by Robert Wood Johnson Foundation to nonprofits in Alabama
+
+**BibTeX:**
+```bibtex
+@misc{grantmakersio,
+    title = {Grantmakers.io: Open Foundation Research Platform},
+    year = {2026},
+    url = {https://www.grantmakers.io/},
+    note = {Community-supported open-source platform for searching IRS 990-PF private foundation data}
+}
+```
+
+**Citation:** "Grantmakers.io. Community-supported open foundation research. https://www.grantmakers.io/"
+
+---
+
+### **Zeffy** ⭐
+
+**100% Free Fundraising with AI-Powered Grant Matching**
+
+Zeffy is unique for being a completely free fundraising platform that also offers an AI-powered grant search tool to help match nonprofit missions with potential grant opportunities.
+
+**Organization:** Zeffy, Inc.  
+**Website:** https://www.zeffy.com/  
+**Platform:** Fundraising + Grant Discovery  
+**Cost:** 100% free for nonprofits (donor-covered fees model)  
+**Grant Tool:** AI-powered grant opportunity matching  
+**Coverage:** U.S. and Canadian grant opportunities
+
+**What we use:**
+- **AI Grant Matching**: Automated matching of nonprofit missions to relevant grant opportunities
+- **Fundraising Infrastructure**: Donation processing, event ticketing, membership management
+- **Donor Management**: CRM for tracking constituent relationships
+- **Grant Alerts**: Notifications when new matching opportunities are posted
+
+**Key Features:**
+- 💰 **100% Free**: No platform fees, monthly charges, or hidden costs
+- 🤖 **AI-Powered Matching**: Machine learning matches your mission to grant opportunities
+- 📧 **Grant Alerts**: Email notifications for new matching grants
+- 🎟️ **All-in-One Platform**: Donations, events, memberships, grants in one system
+- 🇺🇸 🇨🇦 **North America Coverage**: U.S. and Canadian grant databases
+- 📊 **Impact Reporting**: Built-in analytics for grant reporting requirements
+
+**Grant Discovery Capabilities:**
+- **Mission-Based Matching**: Upload your mission statement, get matched grants
+- **Federal Grants**: Monitors Grants.gov for federal opportunities
+- **Foundation Grants**: Tracks private foundation RFPs and announcements
+- **Corporate Giving**: Alerts for corporate philanthropy programs
+- **Local Grants**: Community foundation and regional funder opportunities
+
+**Use Cases for This Project:**
+- **Nonprofit Fundraising**: Organizations can use Zeffy for zero-cost donation processing
+- **Grant Prospecting**: AI helps match oral health nonprofits to relevant grant opportunities
+- **Event Fundraising**: Free ticketing for fundraising galas, community events
+- **Membership Management**: Track supporters, volunteers, members at no cost
+- **Sustainability**: Recommend to small nonprofits to reduce overhead costs
+
+**Why It's Important:**
+Traditional fundraising platforms charge 3-5% fees on donations, which drains resources from small nonprofits. Zeffy's donor-covered model means 100% of donations go to the organization, making it especially valuable for grassroots oral health advocacy groups.
+
+**BibTeX:**
+```bibtex
+@misc{zeffy_platform,
+    title = {Zeffy: 100% Free Fundraising Platform with AI Grant Matching},
+    author = {{Zeffy, Inc.}},
+    year = {2026},
+    url = {https://www.zeffy.com/},
+    note = {Free fundraising platform with AI-powered grant discovery for U.S. and Canadian nonprofits}
+}
+```
+
+**Citation:** "Zeffy. 100% Free Fundraising Platform with AI Grant Matching. https://www.zeffy.com/"
+
+---
+
+### **Community Foundations** ⭐
+
+**Local Grant Opportunities Often Overlooked**
+
+Community foundations are often the most accessible grant sources for local nonprofits, yet they're frequently overlooked because they don't appear in major federal databases. Most maintain their own open listings for regional grants.
+
+**What Community Foundations Are:**
+Community foundations are public charities that pool donations from individuals, families, and businesses to support local nonprofits through competitive grants, scholarship programs, and donor-advised funds.
+
+**Why They Matter:**
+- 🏘️ **Local Focus**: Prioritize organizations serving their specific geographic region
+- 💵 **Smaller, Accessible Grants**: $500-$50,000 range, ideal for grassroots groups
+- 🤝 **Relationship-Based**: Local foundations know local issues and local leaders
+- 📋 **Simpler Applications**: Less bureaucratic than federal or national foundations
+- ⚡ **Faster Decisions**: Many have quarterly or rolling deadlines
+- 🎯 **Mission Alignment**: Support for community health, civic engagement, education
+
+**Examples of Community Foundations:**
+
+| Foundation | Region | Website | Grant Focus Areas |
+|------------|--------|---------|-------------------|
+| **Central Alabama Community Foundation** | Birmingham, AL metro | https://www.cacfbirmingham.org/ | Health, education, civic engagement, arts |
+| **Community Foundation for Greater Atlanta** | Atlanta, GA metro | https://cfgreateratlanta.org/ | Health equity, education, economic mobility |
+| **Boston Foundation** | Boston, MA metro | https://www.tbf.org/ | Health, housing, education, civic participation |
+| **Community Foundation of Greater Memphis** | Memphis, TN metro | https://cfgm.org/ | Health, youth development, community engagement |
+| **Silicon Valley Community Foundation** | San Francisco Bay Area | https://www.siliconvalleycf.org/ | Health, education, immigration, environment |
+| **Greater Kansas City Community Foundation** | Kansas City, MO/KS | https://www.growyourgiving.org/ | Health, education, civic infrastructure |
+| **Seattle Foundation** | Seattle, WA metro | https://www.seattlefoundation.org/ | Racial equity, community health, economic opportunity |
+
+**How to Find Your Local Community Foundation:**
+1. **Council on Foundations Directory**: https://www.cof.org/community-foundation-locator
+2. **Candid (formerly Foundation Center)**: https://candid.org/find-us/foundation-finder
+3. **State Associations**: Most states have a community foundation association
+4. **Google Search**: "[Your City] Community Foundation" or "[Your County] Community Foundation"
+
+**Grant Opportunities:**
+- **Competitive Grants**: Open RFPs for nonprofits in specific focus areas
+- **Capacity Building Grants**: Support for operations, staffing, strategic planning
+- **Donor-Advised Funds**: Individuals/families make grants through the foundation
+- **Fiscal Sponsorship**: Some foundations sponsor projects for groups without 501(c)(3) status
+- **Scholarship Programs**: Education grants for students (often administered by community foundations)
+
+**For Oral Health Advocacy:**
+Many community foundations have health equity or preventive health focus areas that align perfectly with fluoridation advocacy, dental access programs, and oral health education. They're often the best first step for local grassroots campaigns.
+
+**How We Use Community Foundation Data:**
+- **Local Grant Mapping**: Identify which community foundations serve each jurisdiction
+- **Nonprofit Funding Sources**: Link organizations to local foundation grants received
+- **Geographic Targeting**: Recommend local funders when users search by city/county
+- **Grant Prospecting**: Alert nonprofits to community foundation RFPs in their area
+
+**BibTeX:**
+```bibtex
+@misc{community_foundations,
+    title = {Community Foundations: Local Grant Opportunities},
+    author = {{Council on Foundations}},
+    year = {2026},
+    url = {https://www.cof.org/community-foundation-locator},
+    note = {Network of 700+ community foundations providing local grants across the United States}
+}
+```
+
+**Citation:** "Community Foundations. Council on Foundations. https://www.cof.org/community-foundation-locator"
+
+---
+
+## 🏛️ **Civic Tech Organizations & Resources**
+
+### **Code for America** ⭐
+
+The flagship U.S. civic technology nonprofit organization, convening government leaders and technologists to transform public services.
+
+**Organization:** Code for America  
+**Website:** https://codeforamerica.org/  
+**About:** National nonprofit working with government to build digital services that are simple, effective, and accessible to all  
+**Founded:** 2009  
+**Coverage:** National (50 states), with focus on state-level government transformation  
+
+**What we use:**
+- **Summit Insights**: Annual Summit (most recently Summit 2026) where state-level AI leads and municipal CIOs set the civic tech agenda for the year
+- **Brigade Network**: Community chapters across the U.S. working on local civic tech projects
+- **Best Practices**: Government service design patterns, digital service standards
+- **Technology Landscape**: Trends in state and local government digital transformation
+
+**Key Programs:**
+- **Code for America Summit**: Annual conference bringing together 1,500+ government leaders, technologists, and advocates
+- **Brigade Network**: 80+ volunteer chapters in cities across America building civic tech solutions
+- **Get CalFresh**: Flagship product helping millions access food benefits through simplified digital applications
+- **Clear My Record**: Automated criminal record clearance to help people move forward
+- **Government Services Portfolio**: Digital tools for social safety net programs
+
+**Resources:**
+- Summit: https://codeforamerica.org/summit/
+- Brigade Network: https://brigade.codeforamerica.org/
+- Blog: https://codeforamerica.org/news/
+- GitHub: https://github.com/codeforamerica
+- Annual Reports: https://codeforamerica.org/news/category/annual-reports/
+
+**Why Code for America:**
+- **Agenda Setting**: The Summit is where state-level AI leads and municipal CIOs define priorities for the year
+- **Network Effect**: Connects civic technologists across the country
+- **Proven Impact**: Products serving millions of Americans annually
+- **Open Source**: Many tools available as open source for other governments to adopt
+
+**BibTeX:**
+```bibtex
+@misc{code_for_america,
+    title = {Code for America},
+    author = {{Code for America}},
+    year = {2026},
+    url = {https://codeforamerica.org/},
+    note = {National nonprofit transforming government digital services and convening state and local government technology leaders}
+}
+```
+
+**Citation:** "Code for America. https://codeforamerica.org/"
+
+---
+
+### **GovTech.com (Government Technology)** ⭐
+
+The primary news and ranking source for the government technology industry, providing market intelligence and trend analysis.
+
+**Organization:** Government Technology (e.Republic)  
+**Website:** https://www.govtech.com/  
+**About:** Leading publication covering technology trends, policy, and innovation in state and local government  
+**Founded:** 1987  
+**Coverage:** State and local government across all 50 states  
+
+**What we use:**
+- **GovTech 100**: Annual definitive directory of the top 100 trending companies in the U.S. public sector technology market
+- **Industry Trends**: Analysis of emerging technologies, procurement trends, and digital transformation initiatives
+- **Vendor Landscape**: Tracking government technology companies, products, and solutions
+- **Policy Coverage**: Legislative and regulatory developments affecting civic technology
+
+**Key Resources:**
+- **GovTech 100 List**: https://www.govtech.com/100/ - The definitive annual ranking of companies shaping the future of state and local government
+- **Navigator Awards**: https://www.govtech.com/navigator - Recognition of state and local government IT leaders
+- **Digital Cities Survey**: Annual ranking of America's most digitally advanced cities and counties
+- **Research Center**: https://www.govtech.com/research/ - White papers, surveys, and industry reports
+- **Webinars & Events**: https://www.govtech.com/events/
+
+**GovTech 100 Categories:**
+- Cloud & Infrastructure
+- Cybersecurity
+- Data & Analytics
+- Digital Government Services
+- Education Technology
+- Emergency Management
+- Financial Management
+- GIS & Mapping
+- Health & Human Services
+- Public Safety
+- Transportation
+
+**Why GovTech.com:**
+- **Market Intelligence**: The GovTech 100 is the authoritative list of trending companies in government technology
+- **Vendor Discovery**: Comprehensive directory of solutions available to state and local government
+- **Industry Standards**: Defines what's considered "trending" and "emerging" in the civic tech marketplace
+- **Procurement Insights**: Helps identify which technologies governments are actively adopting
+
+**Resources:**
+- Main Site: https://www.govtech.com/
+- GovTech 100: https://www.govtech.com/100/
+- Newsletter: https://www.govtech.com/newsletters/
+- Podcasts: https://www.govtech.com/podcasts/
+- Magazine Archive: https://www.govtech.com/magazines/
+
+**BibTeX:**
+```bibtex
+@misc{govtech_magazine,
+    title = {Government Technology Magazine},
+    author = {{e.Republic Inc.}},
+    year = {2026},
+    url = {https://www.govtech.com/},
+    note = {Leading publication and market intelligence source for state and local government technology, publisher of the annual GovTech 100 list}
+}
+```
+
+**GovTech 100 BibTeX:**
+```bibtex
+@misc{govtech_100,
+    title = {GovTech 100: Companies Trending in State and Local Government},
+    author = {{Government Technology}},
+    year = {2026},
+    url = {https://www.govtech.com/100/},
+    note = {Annual directory of the top 100 trending companies serving the U.S. public sector}
+}
+```
+
+**Citation:** "Government Technology. e.Republic Inc. https://www.govtech.com/"
+
+---
+
+### **Civic Tech Guide** ⭐
+
+Comprehensive, curated directory of civic technology projects, organizations, and tools worldwide, maintained by the civic tech community.
+
+**Organization:** Civic Tech Field Guide (Community-maintained)  
+**Website:** https://app.civictech.guide/  
+**About:** Open directory and knowledge base of civic tech projects, tools, and organizations with detailed project profiles and categorization  
+**Founded:** 2018  
+**Coverage:** Global civic technology ecosystem (1,000+ projects)  
+
+**What we use:**
+- **Project Directory**: Discovery of related civic tech tools and platforms
+- **Categorization**: Understanding how civic tech projects are classified and tagged
+- **Community Connections**: Network of civic technologists and organizations
+- **Best Practices**: Learning from similar projects and their approaches
+
+**CommunityOne Profile:**
+- **Listed as**: https://app.civictech.guide/p/communityone/r/recN0BG4gvjXT7WLf
+- **Categories**: Open Government, Civic Engagement, AI/Machine Learning
+- **Description**: AI-powered civic engagement platform tracking local government meetings, legislation, and advocacy opportunities
+
+**Key Features:**
+- **Search & Filter**: Discover projects by topic, geography, technology, and impact area
+- **Project Profiles**: Detailed information about civic tech initiatives including status, team, and technology
+- **Tagging System**: Categorization by civic tech domains (transparency, participation, accountability, etc.)
+- **API Access**: Programmatic access to the project database
+- **Community Contributions**: Open for civic tech projects to self-list and update profiles
+
+**Categories in Civic Tech Guide:**
+- Open Government & Transparency
+- Civic Participation & Engagement
+- Community Organizing
+- Democracy & Voting
+- Public Service Delivery
+- Data & Research
+- Advocacy & Policy
+- Urban Planning & Development
+
+**Resources:**
+- Main Site: https://app.civictech.guide/
+- About: https://civictech.guide/
+- Submit Project: https://app.civictech.guide/submit
+- GitHub: https://github.com/compilerla/civic-tech-taxonomy
+
+**Why Civic Tech Guide:**
+- **Discovery**: Find related projects and potential collaborators
+- **Context**: Understand where your project fits in the broader civic tech ecosystem
+- **Community**: Connect with civic technologists working on similar problems
+- **Legitimacy**: Being listed establishes credibility in the civic tech community
+
+**BibTeX:**
+```bibtex
+@misc{civic_tech_guide,
+    title = {Civic Tech Field Guide},
+    author = {{Civic Tech Field Guide Community}},
+    year = {2026},
+    url = {https://civictech.guide/},
+    note = {Community-maintained directory of civic technology projects and organizations worldwide}
+}
+```
+
+**Citation:** "Civic Tech Field Guide. https://civictech.guide/"
+
+---
+
+## �️ **Technology Platforms & Support Programs**
+
+### **Databricks for Good Program** ⭐
+
+A philanthropic initiative providing cloud data platform credits and technical support to nonprofits, academic institutions, and social impact organizations.
+
+**Organization:** Databricks, Inc.  
+**Website:** https://www.databricks.com/product/databricks-for-good  
+**Application:** https://www.databricks.com/product/databricks-for-good  
+
+**Eligibility:**
+- ✅ **Nonprofits** - 501(c)(3) status required
+- ✅ **Academic institutions** - Universities, colleges, research organizations
+- ✅ **Social impact organizations** - Civic engagement, public good projects
+- ✅ **Government agencies** - Case-by-case evaluation for civic data initiatives
+
+**CommunityOne/Open Navigator Alignment:**
+This project appears well-suited for the program as a civic engagement and social good initiative. Eligibility would depend on establishing formal nonprofit status or academic partnership.
+
+**Program Benefits:**
+- **$10,000-50,000** in annual Databricks credits
+- Access to **Unity Catalog** (normally $0.20 per million metadata operations)
+- Access to **Databricks Marketplace** for data sharing and distribution
+- **Standard tier** platform features included
+- **Technical support** from Databricks team
+- **Delta Sharing** protocol for secure data distribution
+- **MLflow** for AI/ML experiment tracking
+- **Databricks SQL** for analytics and dashboards
+
+**What This Enables for Open Navigator:**
+- **Data Publishing**: Share 1.8M nonprofit profiles, 4.5M+ legislative documents via Databricks Marketplace
+- **Unity Catalog**: Organize data assets with enterprise-grade governance
+- **Delta Sharing**: Distribute datasets to enterprise/research consumers without data copying
+- **Lakehouse Architecture**: Unified analytics on legislative, nonprofit, and civic data
+- **Collaborative Notebooks**: Reproducible research and analysis
+- **Scheduled Pipelines**: Automated data updates and quality checks
+
+**Alternative Path (Hybrid Approach):**
+- **HuggingFace Hub**: Continue using for open-source community distribution (free)
+- **Databricks Marketplace**: Add enterprise/research distribution channel (if approved)
+- **Data stays in one place**: External tables in Unity Catalog point to existing Parquet files
+- **No data duplication**: Delta Sharing streams data from your storage on-demand
+
+**BibTeX:**
+```bibtex
+@misc{databricks_for_good,
+    title = {Databricks for Good Program},
+    author = {{Databricks, Inc.}},
+    year = {2024},
+    url = {https://www.databricks.com/product/databricks-for-good},
+    note = {Cloud data platform credits and support for nonprofits, academic institutions, and social impact organizations}
+}
+```
+
+**Application Process:**
+1. Visit https://www.databricks.com/product/databricks-for-good
+2. Submit organization details and project description
+3. Describe social impact and data use case
+4. Provide 501(c)(3) documentation (for nonprofits) or academic affiliation
+5. Review process typically takes 2-4 weeks
+6. Upon approval, receive credits and onboarding support
+
+**Compliance:**
+Credits must be used for the approved social impact project and cannot be resold or transferred. Annual renewal required with impact reporting.
+
+---
+
+## �🙏 **Acknowledgments**
+
+We are grateful to the authors of MeetingBank for making their dataset publicly available for research purposes. Their work on meeting summarization has been instrumental in developing civic engagement tools.
+
+Special thanks to:
+- The Association for Computational Linguistics (ACL)
+- HuggingFace for hosting datasets
+- Open States for legislative data
+- All municipal governments providing open access to meeting records
+
+---
+
+## 📖 **How to Cite This Project**
+
+If you use Open Navigator in your research, please cite:
+
+```
+Open Navigator
+GitHub: https://github.com/getcommunityone/open-navigator-for-engagement
+License: MIT
+```
+
+**BibTeX:**
+```bibtex
+@software{open-navigator-2026,
+    title = {Open Navigator},
+    author = {Community One},
+    year = {2026},
+    url = {https://github.com/getcommunityone/open-navigator-for-engagement},
+    license = {MIT}
+}
+```
+
+---
+
+## 📝 **License Compliance**
+
+This project respects all dataset licenses and terms of use. See [LICENSE](LICENSE) for this project's MIT license.
+
+For dataset-specific licenses, please refer to the original sources listed above.

CONTRIBUTING.md

@@ -0,0 +1,99 @@
+# Contributing to Oral Health Policy Pulse
+
+Thank you for your interest in contributing to the Oral Health Policy Pulse project!
+
+## How to Contribute
+
+### Reporting Bugs
+
+If you find a bug, please open an issue with:
+- A clear description of the problem
+- Steps to reproduce
+- Expected vs actual behavior
+- Your environment (OS, Python version, etc.)
+
+### Suggesting Features
+
+Feature requests are welcome! Please:
+- Check if the feature has already been requested
+- Clearly describe the feature and its use case
+- Explain how it would benefit advocacy groups
+
+### Code Contributions
+
+1. **Fork the repository**
+2. **Create a feature branch**
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+3. **Make your changes**
+   - Follow the existing code style
+   - Add tests for new functionality
+   - Update documentation as needed
+
+4. **Run tests**
+   ```bash
+   pytest
+   black .
+   ruff check .
+   ```
+
+5. **Commit your changes**
+   ```bash
+   git commit -m "Add feature: description"
+   ```
+
+6. **Push and create a pull request**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+## Code Style
+
+- Follow PEP 8 guidelines
+- Use type hints
+- Write docstrings for all public functions
+- Keep functions focused and single-purpose
+- Use meaningful variable names
+
+## Code of Conduct
+
+This project values respectful, inclusive collaboration. We align with the principles of:
+- **Open States Code of Conduct**: https://docs.openstates.org/code-of-conduct/
+- Be respectful and professional
+- Welcome diverse perspectives
+- Focus on what's best for the community
+- Show empathy towards other contributors
+
+## Contributing to Upstream Projects
+
+We use data and patterns from several open source civic tech projects. When contributing scraper patterns or improvements back to upstream projects like **OpenStates**, please:
+
+1. **Follow their standards**: https://github.com/openstates/openstates-scrapers
+2. **Reference their documentation**: https://docs.openstates.org/contributing/local-database/
+3. **Respect their Code of Conduct**: https://docs.openstates.org/code-of-conduct/
+4. **Test locally** before submitting pull requests
+5. **Document data sources** used in scraper development
+
+## Testing
+
+All new features should include tests. Run the test suite with:
+
+```bash
+pytest tests/ -v
+```
+
+## Documentation
+
+Update relevant documentation when:
+- Adding new features
+- Changing API endpoints
+- Modifying configuration options
+- Adding new dependencies
+
+## Questions?
+
+Open an issue or reach out to the maintainers.
+
+Thank you for helping improve oral health advocacy! 🦷

Dockerfile

@@ -0,0 +1,90 @@
+# Multi-stage build for Hugging Face Spaces
+# Runs all three apps: Docusaurus docs, React frontend, FastAPI backend
+
+FROM node:20-slim AS docs-builder
+WORKDIR /build
+
+# Set baseUrl to /docs/ for HuggingFace deployment  # Docs are served at nginx /docs/ location
+# routeBasePath: '/' in docusaurus.config.ts prevents /docs/docs/ nesting
+ENV DOCUSAURUS_BASE_URL=/docs/
+
+COPY website/package*.json ./
+RUN npm config set fetch-retry-mintimeout 20000 && \
+    npm config set fetch-retry-maxtimeout 120000 && \
+    npm ci --prefer-offline --no-audit || npm install --prefer-offline --no-audit
+
+# Add cache-busting argument to force rebuild when needed
+ARG CACHE_BUST=2026-04-27-12-00-fix-double-docs-prefix
+
+COPY website/ ./
+
+# Verify environment variable is set and build
+RUN echo "Building Docusaurus with DOCUSAURUS_BASE_URL=$DOCUSAURUS_BASE_URL" && \
+    echo "Cache bust: 2026-04-27-12-00-fix-double-docs-prefix" && \
+    npm run build && \
+    echo "Verifying baseUrl in build output..." && \
+    grep -r "baseUrl" build/ | head -5 || true
+
+FROM python:3.11-slim
+
+# Install system dependencies, nginx, and Node.js for frontend build
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    curl \
+    git \
+    tesseract-ocr \
+    nginx \
+    supervisor \
+    && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
+    && apt-get install -y nodejs \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Copy Python requirements and install
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# OPTIMIZATION: Copy frontend package files first for better caching
+COPY frontend/package*.json /app/frontend/
+RUN cd /app/frontend && npm ci
+
+# Copy application code (now npm ci layer is cached)
+COPY . .
+
+# Copy built static files from docs stage
+COPY --from=docs-builder /build/build /app/static/docs
+
+# Build frontend (npm_modules already cached from above)
+# Set production environment variables for Vite
+ENV VITE_CANONICAL_DOMAIN=www.communityone.com
+ENV VITE_API_URL=/api
+# Cache bust: 2026-04-29-remove-axios
+ARG CACHE_BUST_FRONTEND=2026-04-29-remove-axios
+RUN cd /app/frontend && echo "Frontend build cache bust: $CACHE_BUST_FRONTEND" && npm run build
+
+# Frontend is already built to /app/api/static/ via vite.config.ts
+# Create frontend directory in /app/static for nginx
+RUN mkdir -p /app/static/frontend && \
+    ls -la /app/api/static/ && \
+    cp -r /app/api/static/* /app/static/frontend/
+
+# Create necessary directories
+RUN mkdir -p /app/logs /app/data /var/log/supervisor
+
+# Copy Hugging Face specific configs
+COPY .huggingface/nginx.conf /etc/nginx/nginx.conf
+COPY .huggingface/supervisord.conf /etc/supervisor/conf.d/supervisord.conf
+COPY .huggingface/start.sh /app/start.sh
+RUN chmod +x /app/start.sh
+
+# Expose port 7860 (Hugging Face Spaces default)
+EXPOSE 7860
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1
+ENV LOG_LEVEL=INFO
+ENV HF_SPACES=1
+
+# Use supervisor to run all services
+CMD ["/app/start.sh"]

INTEL_ARC_QUICKSTART.md

@@ -0,0 +1,281 @@
+# 🚀 Intel Arc + DuckDB Quick Reference
+
+**Get started with local AI legislative analysis in 5 minutes**
+
+## ⚡ Performance at a Glance
+
+| Task | Standard (Postgres + CPU) | Optimized (DuckDB + Arc GPU) | Speedup |
+|------|--------------------------|------------------------------|---------|
+| Context injection (100 bills) | 500ms | 20ms | **25x** |
+| Vector search (10K records) | 800ms | 18ms | **44x** |
+| LLM inference (3B model) | 350 tok/s | 1,200 tok/s | **3.4x** |
+| Full testimony analysis | 2,000ms | 80ms | **25x** |
+
+## 🎯 Three-Step Setup
+
+### 1. Install (5 minutes)
+
+```bash
+cd /path/to/open-navigator
+./scripts/intel_llm_setup.sh
+source .venv-intel/bin/activate
+```
+
+### 2. Test DuckDB VSS (30 seconds)
+
+```bash
+python scripts/duckdb_vss_demo.py
+```
+
+Expected output:
+```
+📊 Creating demo DuckDB database with VSS...
+✅ Demo database created!
+📈 Results (searching 1,000 bills):
+   Average: 18.45ms
+🎯 Top 3 most similar bills: ...
+```
+
+### 3. Run Analysis (1 minute)
+
+```bash
+python scripts/legislative_analysis_intel.py
+```
+
+## 🧠 Code Examples
+
+### Example 1: Fast Bill Search
+
+```python
+from scripts.legislative_analysis_intel import DuckDBLegislativeAnalyzer
+
+with DuckDBLegislativeAnalyzer() as analyzer:
+    # Get bill context in < 50ms
+    bill = analyzer.get_bill_context("HB1234")
+    testimony = analyzer.get_all_testimony_for_bill("HB1234")
+    
+    print(f"Bill: {bill['title']}")
+    print(f"Testimony records: {len(testimony)}")
+```
+
+### Example 2: Vector Similarity Search
+
+```python
+import numpy as np
+
+# Your query embedding (384 dimensions from sentence-transformers)
+query_embedding = model.encode("water fluoridation policy")
+
+# Fast vector search (< 20ms for 10K bills)
+similar_bills = analyzer.search_similar_testimony(
+    query_embedding.tolist(),
+    limit=10
+)
+
+for bill in similar_bills:
+    print(f"{bill['bill_id']}: {bill['text'][:100]}... (similarity: {bill['similarity']:.2f})")
+```
+
+### Example 3: Extract Interest Groups
+
+```python
+from scripts.legislative_analysis_intel import IntelOptimizedLLM, InterestGroup
+
+# Initialize Intel-optimized LLM (uses Arc GPU)
+llm = IntelOptimizedLLM(model_name="meta-llama/Llama-3.2-3B-Instruct")
+llm.load_model(use_openvino=True)  # OpenVINO = best Arc GPU performance
+
+# Extract structured data
+groups = llm.extract_interest_groups(bill_context, testimony)
+
+# Results
+for group in groups:
+    print(f"""
+    Group: {group.group_name}
+    Lobbyist: {group.lobbyist}
+    Stance: {group.stance} (score: {group.stance_score})
+    Tradeoffs: {group.tradeoff_notes}
+    Confidence: {group.confidence}
+    """)
+```
+
+### Example 4: Query Hugging Face Datasets Directly
+
+```python
+import duckdb
+
+conn = duckdb.connect()
+
+# No download needed - streams from HF!
+df = conn.execute("""
+    SELECT * 
+    FROM read_parquet(
+        'hf://datasets/CommunityOne/states-al-nonprofits-locations/data/train-*.parquet'
+    )
+    WHERE city = 'Birmingham'
+    LIMIT 100
+""").fetchdf()
+
+print(f"Found {len(df)} organizations in Birmingham, AL")
+```
+
+## 🎨 Output Schema
+
+**Interest Group Extraction:**
+
+```json
+{
+  "groups": [
+    {
+      "group_name": "Alabama Dental Association",
+      "lobbyist": "John Smith, DDS",
+      "stance": "conditional",
+      "stance_score": 0.6,
+      "tradeoff_notes": "Support if Section 4 amended to include rural exemption and phased implementation timeline",
+      "testimony_excerpt": "While we have concerns about Section 4's implementation timeline, we support the overall goals if rural communities receive proper resources...",
+      "bill_id": "HB1234",
+      "confidence": 0.85
+    },
+    {
+      "group_name": "Sierra Club Alabama Chapter",
+      "lobbyist": null,
+      "stance": "oppose",
+      "stance_score": -0.9,
+      "tradeoff_notes": null,
+      "testimony_excerpt": "We strongly oppose this bill due to environmental concerns...",
+      "bill_id": "HB1234",
+      "confidence": 0.92
+    }
+  ]
+}
+```
+
+## 🔧 Environment Variables
+
+```bash
+# Enable Intel GPU
+export ZES_ENABLE_SYSMAN=1
+
+# Ollama GPU usage (if using Ollama)
+export OLLAMA_NUM_GPU=999
+
+# IPEX-LLM optimizations
+export IPEX_LLM_NUM_GPU=1
+export ONEAPI_DEVICE_SELECTOR=level_zero:0
+```
+
+## 💡 Best Practices
+
+### 1. Cache Embeddings
+
+**DON'T** recompute every time:
+```python
+# Slow - recomputes embeddings every run
+for bill in bills:
+    embedding = model.encode(bill['text'])
+    analyze(embedding)
+```
+
+**DO** cache in DuckDB:
+```python
+# Fast - compute once, reuse forever
+conn.execute("""
+    CREATE TABLE bill_embeddings AS
+    SELECT bill_id, embedding
+    FROM ... -- computed once
+""")
+
+# Then just query
+similar = conn.execute("""
+    SELECT * FROM bill_embeddings
+    ORDER BY array_distance(embedding, ?) 
+    LIMIT 10
+""", [query]).fetchall()
+```
+
+### 2. Batch Processing
+
+**DON'T** process one at a time:
+```python
+for bill_id in bill_ids:  # Slow!
+    result = analyze_single_bill(bill_id)
+```
+
+**DO** batch efficiently:
+```python
+# Fast - processes 100 bills in parallel
+results = llm.extract_interest_groups_batch(
+    bill_contexts=bills,
+    testimony_batches=all_testimony,
+    batch_size=32  # Fits in Arc GPU memory
+)
+```
+
+### 3. Monitor GPU Usage
+
+```bash
+# Linux: intel_gpu_top
+sudo apt install intel-gpu-tools
+intel_gpu_top
+
+# Windows: Task Manager → Performance → GPU
+# Look for "GPU 0 - Intel Arc Graphics"
+```
+
+## 🐛 Troubleshooting
+
+### Issue: "ModuleNotFoundError: optimum"
+
+```bash
+pip install optimum[openvino]
+```
+
+### Issue: Slow inference (still using CPU)
+
+Check device:
+```python
+import torch
+print(f"Device: {torch.cuda.get_device_name(0)}")  # Should show Arc GPU
+
+# Force GPU
+model = OVModelForCausalLM.from_pretrained(
+    model_name,
+    device="GPU"  # Explicitly set
+)
+```
+
+### Issue: Out of memory
+
+Use smaller model or reduce batch size:
+```python
+# Use 3B instead of 8B
+model_name = "meta-llama/Llama-3.2-3B-Instruct"
+
+# Reduce context
+testimony = testimony[:10]  # Top 10 only
+```
+
+## 📚 Resources
+
+- **Full Guide**: [website/docs/guides/intel-arc-optimization.md](../website/docs/guides/intel-arc-optimization.md)
+- **DuckDB Docs**: https://duckdb.org/docs/
+- **Intel IPEX**: https://github.com/intel/intel-extension-for-pytorch
+- **OpenVINO**: https://docs.openvino.ai/
+
+## 🎯 Next Steps
+
+1. ✅ Run the demo: `python scripts/duckdb_vss_demo.py`
+2. ✅ Test analysis: `python scripts/legislative_analysis_intel.py`
+3. 📚 Read full guide: [Intel Arc Optimization Guide](../website/docs/guides/intel-arc-optimization.md)
+4. 🚀 Build your own: Use the `DuckDBLegislativeAnalyzer` class
+5. 🤝 Share results: Open an issue with your findings!
+
+## 💬 Questions?
+
+- **GitHub Issues**: https://github.com/getcommunityone/open-navigator/issues
+- **Documentation**: https://www.communityone.com/docs
+- **Intel AI Forums**: https://community.intel.com/t5/Intel-AI-Analytics-and/bd-p/software-ai
+
+---
+
+**Built with ❤️ for Data Engineering Managers who want local, private, fast legislative intelligence.**

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Support. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Community One
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

Makefile

@@ -0,0 +1,169 @@
+.PHONY: help install install-frontend install-docs build-frontend build-docs clean test run dev dev-frontend dev-docs start-all stop-all dev-full docker-up docker-down deploy-databricks
+
+help:
+	@echo "🦷 Open Navigator - Makefile Commands"
+	@echo "===================================================="
+	@echo ""
+	@echo "🚀 Quick Start:"
+	@echo "  make start-all         - Start ALL services (API + Dashboard + Docs) with tmux"
+	@echo "  make stop-all          - Stop all running services"
+	@echo ""
+	@echo "🐍 Python Backend:"
+	@echo "  make install           - Install Python dependencies in venv"
+	@echo "  make dev               - Start backend with auto-reload"
+	@echo "  make run               - Start backend (production)"
+	@echo ""
+	@echo "⚛️  React Dashboard:"
+	@echo "  make install-frontend  - Install dashboard npm dependencies"
+	@echo "  make build-frontend    - Build React dashboard for production"
+	@echo "  make dev-frontend      - Start dashboard dev server"
+	@echo ""
+	@echo "📚 Documentation Site:"
+	@echo "  make install-docs      - Install Docusaurus dependencies"
+	@echo "  make build-docs        - Build documentation for production"
+	@echo "  make dev-docs          - Start documentation dev server"
+	@echo ""
+	@echo "☁️  Deployment:"
+	@echo "  make deploy-databricks - Deploy to Databricks Apps"
+	@echo ""
+	@echo "🐳 Docker:"
+	@echo "  make docker-up         - Start Docker containers"
+	@echo "  make docker-down       - Stop Docker containers"
+	@echo ""
+	@echo "🧪 Testing:"
+	@echo "  make test              - Run test suite"
+	@echo "  make clean             - Remove build artifacts"
+	@echo ""
+
+install:
+	@echo "📦 Creating virtual environment and installing dependencies..."
+	@chmod +x install.sh
+	@./install.sh
+
+install-frontend:
+	@echo "📦 Installing dashboard dependencies..."
+	@cd frontend && npm install
+	@echo "✅ Dashboard dependencies installed!"
+
+install-docs:
+	@echo "📦 Installing documentation dependencies..."
+	@cd website && npm install
+	@echo "✅ Documentation dependencies installed!"
+
+build-frontend:
+	@echo "🔨 Building React dashboard..."
+	@cd frontend && npm run build
+	@echo "✅ Dashboard built to api/static/"
+
+build-docs:
+	@echo "🔨 Building documentation site..."
+	@cd website && npm run build
+	@echo "✅ Documentation built to website/build/"
+
+clean:
+	@echo "🧹 Cleaning up..."
+	@rm -rf .venv venv
+	@rm -rf frontend/node_modules frontend/dist
+	@rm -rf website/node_modules website/build website/.docusaurus
+	@rm -rf api/static
+	@rm -rf __pycache__
+	@find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
+	@find . -type f -name "*.pyc" -delete
+	@find . -type f -name "*.pyo" -delete
+	@rm -rf .pytest_cache
+	@rm -rf .coverage
+	@rm -rf htmlcov
+	@rm -rf dist
+	@rm -rf build
+	@rm -rf *.egg-info
+	@rm -rf logs/*.pid logs/*.log
+	@echo "✅ Cleanup complete"
+
+test:
+	@echo "🧪 Running tests..."
+	@. venv/bin/activate && pytest tests/ -v
+
+run: build-frontend
+	@echo "🚀 Starting application (production mode)..."
+	@. venv/bin/activate && uvicorn api.app:app --host 0.0.0.0 --port 8000
+
+dev:
+	@echo "🔧 Starting backend with auto-reload..."
+	@echo "📡 Backend running at http://localhost:8000"
+	@. venv/bin/activate && uvicorn api.app:app --reload
+
+dev-frontend:
+	@echo "⚛️  Starting dashboard dev server..."
+	@echo "📡 Dashboard running at http://localhost:5173"
+	@cd frontend && npm run dev
+
+dev-docs:
+	@echo "📚 Starting documentation dev server..."
+	@echo "📡 Documentation running at http://localhost:3000"
+	@cd website && npm start
+
+start-all:
+	@echo "🚀 Starting all services with tmux..."
+	@chmod +x start-all.sh
+	@./start-all.sh
+
+stop-all:
+	@echo "🛑 Stopping all services..."
+	@chmod +x stop-all.sh
+	@./stop-all.sh
+
+dev-full:
+	@echo "🚀 Use 'make start-all' for better experience with tmux!"
+	@echo ""
+	@echo "Starting backend and frontend (manual)..."
+	@echo "📡 Backend:   http://localhost:8000"
+	@echo "📡 Dashboard: http://localhost:5173"
+	@echo "📡 Docs:      http://localhost:3000 (run 'make dev-docs' in another terminal)"
+	@echo ""
+	@. venv/bin/activate && uvicorn api.app:app --reload & \
+	cd frontend && npm run dev
+
+deploy-databricks:
+	@echo "☁️  Deploying to Databricks Apps..."
+	@chmod +x scripts/deploy-databricks-app.sh
+	@./scripts/deploy-databricks-app.sh
+
+docker-up:
+	@echo "Starting Docker containers..."
+	@docker-compose up -d
+	@echo "✓ Containers started"
+	@echo "  API: http://localhost:8000"
+	@echo "  Docs: http://localhost:8000/docs"
+
+docker-down:
+	@echo "Stopping Docker containers..."
+	@docker-compose down
+	@echo "✓ Containers stopped"
+
+example:
+	@echo "Running example workflow..."
+	@. venv/bin/activate && python examples/example_workflow.py
+
+heatmap:
+	@echo "Generating example heatmap..."
+	@. venv/bin/activate && python main.py generate-heatmap --output example_heatmap.html
+	@echo "✓ Heatmap saved to example_heatmap.html"
+
+init:
+	@echo "Initializing system..."
+	@. venv/bin/activate && python main.py init
+
+status:
+	@echo "Checking system status..."
+	@. venv/bin/activate && python main.py status
+
+format:
+	@echo "Formatting code..."
+	@. venv/bin/activate && black .
+	@. venv/bin/activate && ruff check . --fix
+	@echo "✓ Code formatted"
+
+lint:
+	@echo "Linting code..."
+	@. venv/bin/activate && ruff check .
+	@. venv/bin/activate && mypy agents/ pipeline/ visualization/ api/

README.md

@@ -0,0 +1,534 @@
+---
+title: Open Navigator
+emoji: 🏛️
+colorFrom: blue
+colorTo: green
+sdk: docker
+app_port: 7860
+pinned: false
+license: apache-2.0
+---
+
+# 🏛️ Open Navigator
+
+> **CommunityOne: The open path to everything local**
+>
+> AI-powered civic engagement platform with React + FastAPI web interface
+
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![React](https://img.shields.io/badge/React-18.2-61DAFB.svg)](https://reactjs.org)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.109.0-009688.svg)](https://fastapi.tiangolo.com)
+
+## � Quick Links
+
+**[⚛️ Open Navigator →](https://www.communityone.com)** - **LIVE APPLICATION** (search, filters, heatmap, data exploration)
+
+**[📖 Documentation →](https://www.communityone.com/docs)** - Complete guides, architecture, and feature details
+
+The documentation site includes:
+- Features and capabilities
+- Data sources and integrations
+- Architecture and deployment options
+- Policy topics and advocacy tools
+- API reference and examples
+
+---
+
+## Quick Start
+
+### Three Services
+
+This project runs three separate services:
+
+| Service | Port (Local) | Live URL | Description |
+|---------|------|----------|-------------|
+| **⚛️ Open Navigator** 🚀 | 5173 | [www.communityone.com](https://www.communityone.com) | **MAIN APPLICATION** - Search, filters, heatmap, data exploration |
+| **📚 Documentation** | 3000 | [www.communityone.com/docs](https://www.communityone.com/docs) | Docusaurus site with complete guides and tutorials |
+| **🔥 API Backend** | 8000 | [www.communityone.com/api](https://www.communityone.com/api) | FastAPI server with AI agents |
+
+> **💡 LIVE DEMO:** Visit **[www.communityone.com](https://www.communityone.com)** to use the application!
+> 
+> **💻 LOCAL DEV:** After running `./start-all.sh`, visit **http://localhost:5173**
+
+## 🚀 Deployment
+
+**Deploy to Hugging Face Spaces** in 3 commands:
+
+```bash
+echo "HF_USERNAME=your_username" >> .env
+./deploy-huggingface.sh
+# Configure hardware and secrets at https://huggingface.co/spaces/YOUR_USERNAME/www.communityone.com
+```
+
+**Full deployment guides:**
+- **[Hugging Face Spaces](website/docs/deployment/huggingface-spaces.md)** - Docker deployment (~$22/month)
+- **[Databricks Apps](website/docs/deployment/databricks-apps.md)** - Enterprise deployment
+- **[Local Development](website/docs/deployment/)** - Complete deployment documentation
+
+The `deploy-huggingface.sh` script automatically:
+- ✅ Tests builds locally (catches errors before pushing)
+- ✅ Creates the Space on Hugging Face  
+- ✅ Pushes code and triggers automatic build (~10-15 min)
+
+
+### Prerequisites
+
+- Python 3.11+
+- Node.js 18+
+- Docker (optional)
+- OpenAI API key
+
+### Installation
+
+**Option 1: Start Everything at Once (Recommended)**
+
+```bash
+# Clone repository
+git clone https://github.com/getcommunityone/open-navigator.git
+cd open-navigator
+
+# Install dependencies
+./install.sh                          # Python backend
+cd frontend && npm install && cd ..   # React app
+cd website && npm install && cd ..    # Documentation
+
+# Setup git hooks for build protection (one-time)
+./setup-git-hooks.sh
+
+# Start all services in tmux
+./start-all.sh
+```
+
+**Option 2: Using Makefile**
+
+```bash
+# Install
+make install
+make install-frontend
+make install-docs
+
+# Start all services
+make start-all
+
+# Or individually:
+make dev           # API only
+make dev-frontend  # React app only
+make dev-docs      # Docs only
+```
+
+**Option 3: Manual Setup**
+
+```bash
+# Python backend
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+
+# React app
+cd frontend && npm install && cd ..
+
+# Documentation
+cd website && npm install && cd ..
+
+# Configure environment
+cp .env.example .env
+# Edit .env with your API keys
+
+# Start services (separate terminals)
+source .venv/bin/activate && python main.py serve  # Terminal 1
+cd frontend && npm run dev                          # Terminal 2
+cd website && npm start                             # Terminal 3
+```
+
+### Access Points
+
+**🌐 LIVE APPLICATION:**
+- **🚀 Open Navigator:** https://www.communityone.com - Main application
+- 📚 **Documentation:** https://www.communityone.com/docs - Guides and API reference
+- 🔥 **API Docs:** https://www.communityone.com/api/docs - FastAPI interactive documentation
+
+**💻 LOCAL DEVELOPMENT:**
+- **🚀 Main App:** http://localhost:5173
+- 📚 **Documentation:** http://localhost:3000
+- 🔥 **API Docs:** http://localhost:8000/docs
+
+### Stop Services
+
+```bash
+./stop-all.sh
+# or
+make stop-all
+```
+
+---
+
+## Usage
+
+### Command Line Interface
+
+Always activate the virtual environment first:
+
+```bash
+source .venv/bin/activate
+```
+
+**API Server**
+
+```bash
+python main.py serve --host 0.0.0.0 --port 8000
+```
+
+**Jurisdiction Discovery**
+
+```bash
+# Test run
+python main.py discover-jurisdictions --limit 100
+
+# Single state
+python main.py discover-jurisdictions --state CA
+
+# Full discovery (~30k jurisdictions)
+python main.py discover-jurisdictions
+
+# View statistics
+python main.py discovery-stats
+```
+
+**Data Ingestion**
+
+```bash
+# Census data (90,000+ jurisdictions)
+python -m discovery.census_ingestion
+
+# NCES school districts (13,000+)
+python -m discovery.nces_ingestion
+
+# Pre-built meeting datasets
+python discovery/meetingbank_ingestion.py
+python discovery/city_scrapers_urls.py
+python discovery/openstates_sources.py
+
+# LocalView (requires Dataverse API key)
+python discovery/localview_ingestion.py
+```
+
+**Scraping & Analysis**
+
+```bash
+# Scrape batch from discovered sites
+python main.py scrape-batch --source discovered --limit 50
+
+# Scrape single source
+python main.py scrape --url "https://city.legistar.com" \
+                      --state "CA" \
+                      --municipality "San Francisco"
+
+# Run analysis pipeline
+python main.py analyze --targets-file examples/targets.json
+
+# Generate heatmap
+python main.py generate-heatmap --output heatmap.html
+```
+
+**Publishing Datasets**
+
+```bash
+# Publish to HuggingFace (requires HUGGINGFACE_TOKEN in .env)
+python main.py publish-to-hf --dataset all
+python main.py publish-to-hf --dataset discovered-urls
+python main.py publish-to-hf --dataset census --sample
+```
+
+### API Usage
+
+**Start a workflow:**
+
+```bash
+curl -X POST "http://localhost:8000/workflow/start" \
+     -H "Content-Type: application/json" \
+     -d '{
+       "scrape_targets": [
+         {
+           "url": "https://example-city.legistar.com",
+           "municipality": "Example City",
+           "state": "CA",
+           "platform": "legistar"
+         }
+       ]
+     }'
+```
+
+**Query opportunities:**
+
+```bash
+curl "http://localhost:8000/opportunities?state=CA&urgency=critical"
+```
+
+**Get heatmap:**
+
+```bash
+curl "http://localhost:8000/heatmap" > heatmap.html
+```
+
+### Python API
+
+```python
+import asyncio
+from agents.orchestrator import OrchestratorAgent
+from agents.scraper import ScraperAgent
+from agents.parser import ParserAgent
+from agents.classifier import ClassifierAgent
+
+# Initialize orchestrator
+orchestrator = OrchestratorAgent()
+
+# Register agents
+orchestrator.register_agent(ScraperAgent())
+orchestrator.register_agent(ParserAgent())
+orchestrator.register_agent(ClassifierAgent())
+
+# Execute pipeline
+targets = [
+    {
+        "url": "https://city.legistar.com",
+        "municipality": "Example City",
+        "state": "CA",
+        "platform": "legistar"
+    }
+]
+
+results = await orchestrator.execute_pipeline(targets)
+```
+
+---
+
+## Project Structure
+
+```
+open-navigator/
+├── agents/                 # Multi-agent AI system
+├── api/                   # FastAPI application
+├── frontend/             # React application (Open Navigator)
+├── website/              # Docusaurus documentation
+├── discovery/            # Data discovery modules
+├── extraction/           # Document extraction
+├── pipeline/             # Data pipeline components
+├── visualization/        # Heatmap and charts
+├── config/               # Configuration
+├── tests/                # Test suite
+├── main.py              # CLI entry point
+└── requirements.txt     # Python dependencies
+```
+
+---
+
+## Deployment Options
+
+### 1. Databricks Apps (Production)
+
+```bash
+export DATABRICKS_HOST=https://your-workspace.cloud.databricks.com
+export DATABRICKS_TOKEN=dapi...
+export OPENAI_API_KEY=sk-...
+
+./scripts/deploy-databricks-app.sh
+```
+
+See [DATABRICKS_APP_GUIDE.md](DATABRICKS_APP_GUIDE.md) for details.
+
+### 2. Docker
+
+```bash
+docker-compose up -d
+```
+
+Starts:
+- API server (port 8000)
+- Qdrant vector database (port 6333)
+- Jupyter notebook (port 8888)
+
+### 3. Local Development
+
+See [Quick Start](#quick-start) above.
+
+---
+
+## ⚡ Intel Arc GPU Optimization
+
+**Run Llama 4 at NVIDIA-like speeds on Intel Arc integrated graphics!**
+
+If you have **Intel Core Ultra 7** (or similar) with Arc Graphics + NPU, you can use **DuckDB + VSS** for 10-50x faster legislative analysis:
+
+```bash
+# Setup Intel-optimized environment
+./scripts/intel_llm_setup.sh
+source .venv-intel/bin/activate
+
+# Run DuckDB vector search demo
+python scripts/duckdb_vss_demo.py
+
+# Run legislative analysis with LLM
+python scripts/legislative_analysis_intel.py
+```
+
+**Why DuckDB for Local AI?**
+- ⚡ **10-50x faster** than Postgres for context injection
+- 🎯 **< 20ms** vector similarity search across 10K bills
+- 🧠 **Embedded** - no server needed, runs locally
+- 🤗 **Hugging Face Integration** - query HF datasets directly
+
+**Performance:**
+- **Context Injection**: 20ms vs 500ms (Postgres) = **25x faster**
+- **LLM Inference**: 1,200 tok/s (Arc GPU) vs 350 tok/s (CPU) = **3.4x faster**
+- **Vector Search**: 18ms vs 800ms = **44x faster**
+
+**Features:**
+- Extract interest groups from legislative testimony
+- Identify lobbyists and their positions
+- Analyze support/oppose scores with confidence
+- Detect tradeoffs and compromises
+
+**See full guide:** [Intel Arc Optimization Guide](website/docs/guides/intel-arc-optimization.md)
+
+---
+
+## 🤖 AI Integration (MCP Server)
+
+**Connect your civic data to Claude and other AI assistants!**
+
+Open Navigator includes a **Model Context Protocol (MCP)** server that lets AI assistants directly access your data:
+
+```bash
+# Install MCP dependencies
+pip install mcp anthropic-mcp-sdk
+
+# Run the server
+python scripts/mcp/open_navigator_server.py
+```
+
+**What AI assistants can do:**
+- 🏛️ Search 90,000+ jurisdictions by name or location
+- 🏢 Query 1.8M nonprofits with Form 990 data
+- 📜 Semantic search across 4.5M+ legislative documents
+- 📊 Get real-time statistics and analytics
+- 🔍 Vector search meetings and bills with natural language
+
+**Example queries to Claude:**
+> "Find all cities named Springfield in the database"
+
+> "Show me 501c3 nonprofits in San Francisco focused on education"
+
+> "What bills related to oral health were introduced in California?"
+
+**Configure Claude Desktop:**
+
+Add to `~/.config/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "open-navigator": {
+      "command": "python",
+      "args": ["/path/to/open-navigator/scripts/mcp/open_navigator_server.py"],
+      "env": {
+        "DATABASE_URL": "postgresql://postgres:password@localhost:5433/open_navigator"
+      }
+    }
+  }
+}
+```
+
+**See full guide:** [MCP Server Documentation](website/docs/integrations/mcp-server.md)
+
+---
+
+## Testing
+
+```bash
+# Run all tests
+pytest
+
+# With coverage
+pytest --cov=agents --cov=pipeline --cov=visualization
+
+# Specific test file
+pytest tests/test_agents.py
+```
+
+---
+
+## Configuration
+
+Create `.env` file:
+
+```bash
+# OpenAI
+OPENAI_API_KEY=sk-...
+
+# Databricks (optional)
+DATABRICKS_HOST=https://your-workspace.cloud.databricks.com
+DATABRICKS_TOKEN=dapi...
+
+# HuggingFace (optional)
+HUGGINGFACE_TOKEN=hf_...
+
+# Dataverse (optional)
+DATAVERSE_API_KEY=...
+```
+
+---
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Submit a pull request
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+---
+
+## Documentation
+
+- **[Full Documentation](http://localhost:3000)** - Complete guides and API reference
+- **[Architecture](http://localhost:3000/docs/architecture)** - System architecture overview
+- **[Quick Start](http://localhost:3000/docs/quickstart)** - Detailed setup instructions
+- **[Quick Reference](http://localhost:3000/docs/quick-reference)** - Command reference card
+- **[MCP Server](http://localhost:3000/docs/integrations/mcp-server)** - AI assistant integration guide
+- **[Deployment](http://localhost:3000/docs/deployment/databricks-apps)** - Production deployment guides
+- **[Case Studies](http://localhost:3000/docs/case-studies/tuscaloosa-complete)** - Real-world examples
+- [CONTRIBUTING.md](CONTRIBUTING.md) - How to contribute
+
+---
+
+## Citations
+
+This project uses several open datasets and research contributions. **Please see [CITATIONS.md](CITATIONS.md) for complete citation information.**
+
+**Key Dataset:**
+- **MeetingBank**: Hu et al., "MeetingBank: A Benchmark Dataset for Meeting Summarization", ACL 2023
+  - Used for meeting discovery and analysis
+  - 1,366 city council meetings from 6 U.S. cities
+  - See [CITATIONS.md](CITATIONS.md) for full citation and BibTeX
+
+---
+
+## License
+
+Apache License 2.0 - see [LICENSE](LICENSE) file for details.
+
+---
+
+## Support
+
+- GitHub Issues: [github.com/getcommunityone/open-navigator-for-engagement/issues](https://github.com/getcommunityone/open-navigator-for-engagement/issues)
+- Email: johnbowyer@communityone.com
+
+---
+
+**Note**: This system is designed to support advocacy efforts. All generated content should be reviewed by humans before use.

README_HF.md

@@ -0,0 +1,101 @@
+---
+title: CommunityOne - Open Navigator
+emoji: 🏛️
+colorFrom: blue
+colorTo: green
+sdk: docker
+app_port: 7860
+pinned: false
+license: apache-2.0
+tags:
+  - civic-engagement
+  - policy-tracking
+  - government-transparency
+  - nonprofit-discovery
+  - open-data
+---
+
+# 🏛️ CommunityOne - Open Navigator
+
+**Track 90,000+ jurisdictions. Monitor 1.8M nonprofits. Amplify your voice.**
+
+CommunityOne is a civic engagement platform that helps you discover advocacy opportunities, track policy changes, and connect with organizations working on the causes you care about.
+
+## ✨ Features
+
+- **🔍 Unified Search**: Find contacts, meetings, organizations, and causes across the entire United States
+- **📊 Real-time Stats**: Track policy activity across 90,000+ cities, counties, and states
+- **🏢 Nonprofit Discovery**: Explore 1.8M organizations from IRS data enriched with Every.org
+- **📅 Meeting Minutes**: Search 250,000+ government meeting transcripts and agendas
+- **🎯 Geographic Filtering**: Browse by state, county, or city to find local opportunities
+- **🔐 OAuth Login**: Sign in with HuggingFace, GitHub, or Google to save your preferences
+
+## 🚀 Three Services Architecture
+
+This deployment runs three integrated services:
+
+1. **📚 Documentation** (Docusaurus) - `/docs/`
+2. **🖥️ Main Application** (React + Vite) - `/`
+3. **⚡ API Backend** (FastAPI) - `/api/`
+
+All services are reverse-proxied through nginx on port 7860.
+
+## 📖 Quick Start
+
+### Browse Without Login
+- Click "Browse All" to explore data by state
+- Use the search bar to find organizations, contacts, or causes
+- Filter by location using the state/county/city selectors
+
+### Sign In for Personalization
+- Click "Login" in the top right
+- Choose your OAuth provider (HuggingFace, GitHub, or Google)
+- Follow organizations, leaders, and causes you care about
+- Get personalized recommendations
+
+### Explore the API
+- Visit `/redoc` for interactive API documentation
+- Try the search endpoints with state filters
+- Export data in JSON format for your own projects
+
+## 🛠️ Technology Stack
+
+- **Frontend**: React 18 + TypeScript + Vite + TailwindCSS + shadcn/ui
+- **Backend**: Python 3.11 + FastAPI + Pydantic
+- **Data**: Delta Lake + Parquet (90GB+ of civic data)
+- **Docs**: Docusaurus v3
+- **Infrastructure**: nginx + supervisor + Docker
+
+## 📊 Data Sources
+
+- **IRS BMF**: 1.8M tax-exempt organizations
+- **Every.org**: Nonprofit enrichment (logos, causes, revenue)
+- **Open States**: State legislators and bills (7,300+ officials)
+- **Census**: Jurisdictions and boundaries (90,000+)
+- **CityScrapers**: Local government meetings
+- **OpenCivicData**: Standardized government data
+
+## 🔗 Links
+
+- **Repository**: [github.com/getcommunityone/open-navigator](https://github.com/getcommunityone/open-navigator)
+- **Documentation**: Click "📚 Browse Documentation" on the homepage
+- **API Docs**: `/redoc` endpoint
+- **Website**: [www.communityone.com](https://www.communityone.com)
+
+## 📝 License
+
+Apache License 2.0 - Free for commercial and non-commercial use
+
+## 🤝 Contributing
+
+We welcome contributions! See CONTRIBUTING.md in the repository for guidelines.
+
+## 💬 Support
+
+- **Issues**: [GitHub Issues](https://github.com/getcommunityone/open-navigator/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/getcommunityone/open-navigator/discussions)
+- **Email**: hello@communityone.com
+
+---
+
+Built with ❤️ for civic engagement and government transparency.

agents/__init__.py

@@ -0,0 +1,16 @@
+"""Agents module for the Oral Health Policy Pulse system."""
+from agents.base import BaseAgent, AgentRole, AgentMessage, MessageType, AgentStatus
+from agents.orchestrator import OrchestratorAgent
+from agents.debate_grader import DebateGraderAgent, DebateDimension, DebateScore
+
+__all__ = [
+    "BaseAgent",
+    "AgentRole",
+    "AgentMessage",
+    "MessageType",
+    "AgentStatus",
+    "OrchestratorAgent",
+    "DebateGraderAgent",
+    "DebateDimension",
+    "DebateScore"
+]

agents/advocacy.py

@@ -0,0 +1,408 @@
+"""
+Advocacy Writer Agent for generating personalized outreach materials.
+"""
+import asyncio
+from typing import List, Dict, Any, Optional
+from datetime import datetime
+from loguru import logger
+
+from agents.base import BaseAgent, AgentRole, AgentMessage, MessageType, AgentStatus
+
+
+class AdvocacyWriterAgent(BaseAgent):
+    """
+    Agent responsible for generating advocacy materials.
+    
+    Creates:
+    - Personalized emails to local officials
+    - Talking points for public testimony
+    - Social media content
+    - Policy briefs
+    - Community outreach materials
+    """
+    
+    def __init__(self, agent_id: str = "advocacy-001"):
+        """Initialize the advocacy writer agent."""
+        super().__init__(agent_id, AgentRole.ADVOCACY_WRITER)
+        self._initialize_templates()
+    
+    def _initialize_templates(self):
+        """Initialize email and content templates."""
+        self.email_templates = {
+            "critical_vote": {
+                "subject": "Urgent: Support Oral Health Policy - Vote Upcoming in {municipality}",
+                "opening": (
+                    "I am writing to urge your support for the upcoming vote on "
+                    "{policy_topic} in {municipality}."
+                ),
+                "urgency": "This matter requires immediate attention as a vote is scheduled for {meeting_date}."
+            },
+            "introduce_topic": {
+                "subject": "Opportunity to Improve Community Oral Health in {municipality}",
+                "opening": (
+                    "I am writing to bring to your attention an important opportunity "
+                    "to enhance oral health services in {municipality}."
+                ),
+                "urgency": None
+            },
+            "address_opposition": {
+                "subject": "Addressing Concerns About {policy_topic} in {municipality}",
+                "opening": (
+                    "I understand there are concerns about {policy_topic}. "
+                    "I would like to share evidence-based information that may help inform the discussion."
+                ),
+                "urgency": None
+            },
+            "support_existing": {
+                "subject": "Thank You for Supporting Oral Health in {municipality}",
+                "opening": (
+                    "Thank you for your support of {policy_topic}. "
+                    "I am writing to express my appreciation and offer additional support."
+                ),
+                "urgency": None
+            }
+        }
+        
+        self.policy_benefits = {
+            "water_fluoridation": [
+                "Reduces tooth decay by 25% in children and adults",
+                "Costs approximately $1 per person per year",
+                "Recognized by CDC as one of 10 great public health achievements",
+                "Reduces dental treatment costs by $38 per $1 invested",
+                "Particularly benefits low-income families with limited access to dental care"
+            ],
+            "school_dental_screening": [
+                "Early detection prevents costly emergency dental procedures",
+                "Identifies children who need care before problems become severe",
+                "Reduces school absences due to dental pain",
+                "Connects families to dental resources and services",
+                "Supported by American Academy of Pediatrics"
+            ],
+            "medicaid_dental": [
+                "Improves health outcomes for vulnerable populations",
+                "Reduces emergency room visits for dental problems",
+                "Prevents progression of oral disease to systemic health issues",
+                "Supports working families and children",
+                "Generates economic returns through improved productivity"
+            ],
+            "dental_clinic_funding": [
+                "Provides essential services to underserved communities",
+                "Reduces health disparities",
+                "Creates local jobs and economic activity",
+                "Prevents costly emergency care",
+                "Serves as safety net for uninsured and underinsured residents"
+            ]
+        }
+    
+    async def process(self, message: AgentMessage) -> List[AgentMessage]:
+        """
+        Process advocacy generation commands.
+        
+        Args:
+            message: Message containing analyzed documents and opportunities
+            
+        Returns:
+            List of messages with generated advocacy materials
+        """
+        self.update_status(AgentStatus.PROCESSING, "Generating advocacy materials")
+        
+        try:
+            documents = message.payload.get("documents", [])
+            opportunities = message.payload.get("opportunities", [])
+            
+            # Generate advocacy materials for each opportunity
+            advocacy_materials = []
+            
+            for opp in opportunities:
+                materials = await self._generate_advocacy_materials(opp, documents)
+                advocacy_materials.append(materials)
+            
+            # Send results back to orchestrator
+            response = await self.send_message(
+                AgentRole.ORCHESTRATOR,
+                MessageType.RESPONSE,
+                {
+                    "workflow_id": message.payload.get("workflow_id"),
+                    "advocacy_materials": advocacy_materials,
+                    "opportunities_count": len(opportunities),
+                    "materials_generated": len(advocacy_materials)
+                }
+            )
+            
+            self.log_success()
+            logger.info(f"Generated advocacy materials for {len(opportunities)} opportunities")
+            
+            return [response]
+            
+        except Exception as e:
+            self.log_failure(str(e))
+            error_msg = await self.send_message(
+                AgentRole.ORCHESTRATOR,
+                MessageType.ERROR,
+                {"error": str(e), "agent": self.agent_id}
+            )
+            return [error_msg]
+    
+    async def _generate_advocacy_materials(
+        self,
+        opportunity: Dict[str, Any],
+        all_documents: List[Dict[str, Any]]
+    ) -> Dict[str, Any]:
+        """
+        Generate complete advocacy materials for an opportunity.
+        
+        Args:
+            opportunity: Advocacy opportunity details
+            all_documents: All analyzed documents for context
+            
+        Returns:
+            Dictionary containing all generated materials
+        """
+        # Find the source document
+        doc = next(
+            (d for d in all_documents if d["document_id"] == opportunity["document_id"]),
+            None
+        )
+        
+        if not doc:
+            logger.error(f"Document not found: {opportunity['document_id']}")
+            return {}
+        
+        # Determine template based on situation
+        template_type = self._select_template(opportunity)
+        
+        # Generate email
+        email = await self._generate_email(opportunity, doc, template_type)
+        
+        # Generate talking points
+        talking_points = self._generate_talking_points(opportunity, doc)
+        
+        # Generate social media content
+        social_media = self._generate_social_media(opportunity)
+        
+        # Generate policy brief
+        policy_brief = self._generate_policy_brief(opportunity, doc)
+        
+        materials = {
+            "opportunity_id": opportunity["document_id"],
+            "municipality": opportunity["municipality"],
+            "state": opportunity["state"],
+            "topic": opportunity["topic"],
+            "urgency": opportunity["urgency"],
+            "materials": {
+                "email": email,
+                "talking_points": talking_points,
+                "social_media": social_media,
+                "policy_brief": policy_brief
+            },
+            "generated_at": datetime.utcnow().isoformat(),
+            "metadata": {
+                "source_url": opportunity["source_url"],
+                "meeting_date": opportunity["meeting_date"]
+            }
+        }
+        
+        return materials
+    
+    def _select_template(self, opportunity: Dict[str, Any]) -> str:
+        """Select appropriate email template based on situation."""
+        urgency = opportunity.get("urgency")
+        stance = opportunity.get("stance")
+        
+        if urgency == "critical":
+            return "critical_vote"
+        elif stance in ["opposed", "strongly_opposed"]:
+            return "address_opposition"
+        elif stance in ["supportive", "strongly_supportive"]:
+            return "support_existing"
+        else:
+            return "introduce_topic"
+    
+    async def _generate_email(
+        self,
+        opportunity: Dict[str, Any],
+        doc: Dict[str, Any],
+        template_type: str
+    ) -> Dict[str, Any]:
+        """Generate personalized email content."""
+        template = self.email_templates[template_type]
+        
+        # Format template variables
+        variables = {
+            "municipality": opportunity["municipality"],
+            "policy_topic": self._format_topic_name(opportunity["topic"]),
+            "meeting_date": opportunity["meeting_date"]
+        }
+        
+        subject = template["subject"].format(**variables)
+        opening = template["opening"].format(**variables)
+        
+        # Build email body
+        body_parts = [opening]
+        
+        # Add urgency if applicable
+        if template["urgency"]:
+            body_parts.append("\n\n" + template["urgency"].format(**variables))
+        
+        # Add policy benefits
+        body_parts.append("\n\n**Key Benefits:**")
+        benefits = self.policy_benefits.get(
+            opportunity["topic"],
+            ["Improves community health outcomes"]
+        )
+        for benefit in benefits[:3]:  # Top 3 benefits
+            body_parts.append(f"• {benefit}")
+        
+        # Add call to action
+        body_parts.append(self._generate_call_to_action(opportunity))
+        
+        # Add closing
+        body_parts.append(
+            "\n\nThank you for your time and consideration. "
+            "I would welcome the opportunity to discuss this further."
+        )
+        body_parts.append("\n\nSincerely,")
+        body_parts.append("[Your Name]")
+        body_parts.append("[Your Organization]")
+        
+        email = {
+            "subject": subject,
+            "body": "\n".join(body_parts),
+            "template_type": template_type,
+            "personalization_variables": variables
+        }
+        
+        return email
+    
+    def _generate_call_to_action(self, opportunity: Dict[str, Any]) -> str:
+        """Generate appropriate call to action based on urgency."""
+        urgency = opportunity.get("urgency")
+        stance = opportunity.get("stance")
+        
+        if urgency == "critical":
+            return (
+                "\n\n**Action Needed:**\n"
+                f"Please vote in favor of this important measure at the upcoming meeting. "
+                f"Your constituents' oral health depends on this decision."
+            )
+        elif stance in ["opposed", "strongly_opposed"]:
+            return (
+                "\n\n**Requested Action:**\n"
+                "I respectfully request a meeting to discuss the evidence supporting this policy "
+                "and address any concerns you may have."
+            )
+        else:
+            return (
+                "\n\n**Requested Action:**\n"
+                "I encourage you to support this initiative and would be happy to provide "
+                "additional information or connect you with subject matter experts."
+            )
+    
+    def _generate_talking_points(
+        self,
+        opportunity: Dict[str, Any],
+        doc: Dict[str, Any]
+    ) -> List[str]:
+        """Generate talking points for public testimony or meetings."""
+        topic = opportunity["topic"]
+        
+        talking_points = [
+            f"Introduction: Community member concerned about oral health in {opportunity['municipality']}"
+        ]
+        
+        # Add topic-specific points
+        benefits = self.policy_benefits.get(topic, [])
+        for i, benefit in enumerate(benefits[:5], 1):
+            talking_points.append(f"Point {i}: {benefit}")
+        
+        # Add local context
+        talking_points.append(
+            f"Local relevance: This policy addresses needs identified in "
+            f"recent community discussions"
+        )
+        
+        # Add closing point
+        talking_points.append(
+            "Closing: Urge decision-makers to prioritize community oral health"
+        )
+        
+        return talking_points
+    
+    def _generate_social_media(
+        self,
+        opportunity: Dict[str, Any]
+    ) -> Dict[str, str]:
+        """Generate social media content."""
+        municipality = opportunity["municipality"]
+        topic = self._format_topic_name(opportunity["topic"])
+        
+        twitter = (
+            f"🦷 {municipality} is considering {topic}! "
+            f"This could improve oral health for thousands. "
+            f"Contact your local officials to show support. "
+            f"#OralHealth #PublicHealth"
+        )
+        
+        facebook = (
+            f"Important news for {municipality} residents!\n\n"
+            f"Our local government is discussing {topic}. "
+            f"This policy could significantly improve access to dental care "
+            f"for families in our community.\n\n"
+            f"Learn more and contact your representatives to voice your support: "
+            f"{opportunity.get('source_url', '')}"
+        )
+        
+        return {
+            "twitter": twitter,
+            "facebook": facebook,
+            "instagram": twitter,  # Similar to Twitter
+            "hashtags": ["OralHealth", "PublicHealth", municipality.replace(" ", "")]
+        }
+    
+    def _generate_policy_brief(
+        self,
+        opportunity: Dict[str, Any],
+        doc: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Generate a concise policy brief."""
+        topic = opportunity["topic"]
+        
+        brief = {
+            "title": f"Policy Brief: {self._format_topic_name(topic)} in {opportunity['municipality']}",
+            "summary": (
+                f"This brief outlines the benefits and implementation considerations "
+                f"for {self._format_topic_name(topic)}."
+            ),
+            "background": (
+                f"Current discussion in {opportunity['municipality']} presents "
+                f"an opportunity to improve community oral health."
+            ),
+            "key_benefits": self.policy_benefits.get(topic, []),
+            "recommendations": [
+                "Approve the proposed policy",
+                "Allocate necessary funding",
+                "Establish implementation timeline",
+                "Monitor outcomes and adjust as needed"
+            ],
+            "evidence_sources": [
+                "Centers for Disease Control and Prevention",
+                "American Dental Association",
+                "Community Preventive Services Task Force"
+            ]
+        }
+        
+        return brief
+    
+    def _format_topic_name(self, topic: str) -> str:
+        """Format topic identifier into readable name."""
+        topic_names = {
+            "water_fluoridation": "community water fluoridation",
+            "school_dental_screening": "school-based dental screening",
+            "medicaid_dental": "Medicaid dental coverage expansion",
+            "dental_clinic_funding": "community dental clinic funding",
+            "community_dental_program": "community dental programs",
+            "children_dental_health": "children's dental health initiatives",
+            "dental_care_access": "dental care access improvements"
+        }
+        
+        return topic_names.get(topic, topic.replace("_", " "))

agents/base.py

@@ -0,0 +1,171 @@
+"""
+Core agent base classes and protocols for the multi-agent system.
+"""
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional, Union
+from datetime import datetime
+from enum import Enum
+from pydantic import BaseModel, Field
+from loguru import logger
+
+
+class AgentRole(str, Enum):
+    """Enumeration of agent roles in the system."""
+    SCRAPER = "scraper"
+    PARSER = "parser"
+    CLASSIFIER = "classifier"
+    SENTIMENT_ANALYZER = "sentiment_analyzer"
+    DEBATE_GRADER = "debate_grader"
+    ADVOCACY_WRITER = "advocacy_writer"
+    ORCHESTRATOR = "orchestrator"
+
+
+class MessageType(str, Enum):
+    """Types of messages exchanged between agents."""
+    DATA = "data"
+    COMMAND = "command"
+    QUERY = "query"
+    RESPONSE = "response"
+    ERROR = "error"
+    STATUS = "status"
+
+
+class AgentMessage(BaseModel):
+    """Message structure for inter-agent communication."""
+    message_id: str = Field(..., description="Unique message identifier")
+    sender: AgentRole = Field(..., description="Sending agent role")
+    recipient: AgentRole = Field(..., description="Receiving agent role")
+    message_type: MessageType = Field(..., description="Type of message")
+    timestamp: datetime = Field(default_factory=datetime.utcnow)
+    payload: Dict[str, Any] = Field(default_factory=dict, description="Message payload")
+    metadata: Dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
+    
+    class Config:
+        json_encoders = {
+            datetime: lambda v: v.isoformat()
+        }
+
+
+class AgentStatus(str, Enum):
+    """Agent operational status."""
+    IDLE = "idle"
+    PROCESSING = "processing"
+    WAITING = "waiting"
+    ERROR = "error"
+    COMPLETED = "completed"
+
+
+class AgentState(BaseModel):
+    """Current state of an agent."""
+    agent_id: str
+    role: AgentRole
+    status: AgentStatus = AgentStatus.IDLE
+    current_task: Optional[str] = None
+    tasks_completed: int = 0
+    tasks_failed: int = 0
+    last_activity: datetime = Field(default_factory=datetime.utcnow)
+    error_message: Optional[str] = None
+
+
+class BaseAgent(ABC):
+    """
+    Abstract base class for all agents in the system.
+    
+    Each agent must implement the process method to handle incoming messages
+    and perform its specific role in the pipeline.
+    """
+    
+    def __init__(self, agent_id: str, role: AgentRole):
+        """
+        Initialize the base agent.
+        
+        Args:
+            agent_id: Unique identifier for this agent instance
+            role: The role this agent plays in the system
+        """
+        self.agent_id = agent_id
+        self.role = role
+        self.state = AgentState(agent_id=agent_id, role=role)
+        self.message_queue: List[AgentMessage] = []
+        logger.info(f"Initialized {role.value} agent: {agent_id}")
+    
+    @abstractmethod
+    async def process(self, message: AgentMessage) -> Union[AgentMessage, List[AgentMessage]]:
+        """
+        Process an incoming message and return response(s).
+        
+        Args:
+            message: The message to process
+            
+        Returns:
+            One or more response messages
+        """
+        pass
+    
+    def update_status(self, status: AgentStatus, task: Optional[str] = None):
+        """Update the agent's current status."""
+        self.state.status = status
+        self.state.current_task = task
+        self.state.last_activity = datetime.utcnow()
+        logger.debug(f"{self.role.value} agent {self.agent_id} status: {status.value}")
+    
+    def log_success(self):
+        """Log a successful task completion."""
+        self.state.tasks_completed += 1
+        self.update_status(AgentStatus.IDLE)
+    
+    def log_failure(self, error: str):
+        """Log a task failure."""
+        self.state.tasks_failed += 1
+        self.state.error_message = error
+        self.update_status(AgentStatus.ERROR)
+        logger.error(f"{self.role.value} agent {self.agent_id} error: {error}")
+    
+    async def send_message(
+        self,
+        recipient: AgentRole,
+        message_type: MessageType,
+        payload: Dict[str, Any],
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> AgentMessage:
+        """
+        Create and send a message to another agent.
+        
+        Args:
+            recipient: The receiving agent's role
+            message_type: Type of message to send
+            payload: Message content
+            metadata: Optional metadata
+            
+        Returns:
+            The created message
+        """
+        import uuid
+        
+        message = AgentMessage(
+            message_id=str(uuid.uuid4()),
+            sender=self.role,
+            recipient=recipient,
+            message_type=message_type,
+            payload=payload,
+            metadata=metadata or {}
+        )
+        
+        return message
+    
+    def get_state(self) -> AgentState:
+        """Get the current state of the agent."""
+        return self.state
+
+
+class AgentMetrics(BaseModel):
+    """Metrics for monitoring agent performance."""
+    agent_id: str
+    role: AgentRole
+    total_messages_processed: int = 0
+    total_processing_time_seconds: float = 0.0
+    average_processing_time_seconds: float = 0.0
+    success_rate: float = 0.0
+    error_count: int = 0
+    last_error: Optional[str] = None
+    uptime_seconds: float = 0.0

agents/classifier.py

@@ -0,0 +1,295 @@
+"""
+Classifier Agent for identifying oral health policy topics in meeting minutes.
+"""
+import asyncio
+from typing import List, Dict, Any, Optional, Set
+from datetime import datetime
+from loguru import logger
+
+from agents.base import BaseAgent, AgentRole, AgentMessage, MessageType, AgentStatus
+from config import settings
+
+
+class PolicyTopic:
+    """Enumeration of oral health policy topics."""
+    WATER_FLUORIDATION = "water_fluoridation"
+    SCHOOL_DENTAL_SCREENING = "school_dental_screening"
+    MEDICAID_DENTAL = "medicaid_dental"
+    DENTAL_CLINIC_FUNDING = "dental_clinic_funding"
+    COMMUNITY_DENTAL_PROGRAM = "community_dental_program"
+    CHILDREN_DENTAL_HEALTH = "children_dental_health"
+    DENTAL_CARE_ACCESS = "dental_care_access"
+    OTHER_ORAL_HEALTH = "other_oral_health"
+    NOT_RELEVANT = "not_relevant"
+
+
+class ClassifierAgent(BaseAgent):
+    """
+    Agent responsible for classifying documents by oral health policy topics.
+    
+    Uses a combination of:
+    - Keyword matching for high-precision identification
+    - LLM-based classification for nuanced topics
+    - Topic modeling for discovering new themes
+    """
+    
+    def __init__(self, agent_id: str = "classifier-001"):
+        """Initialize the classifier agent."""
+        super().__init__(agent_id, AgentRole.CLASSIFIER)
+        self._initialize_keywords()
+        self.llm_client = None  # Will be initialized when needed
+    
+    def _initialize_keywords(self):
+        """Initialize keyword patterns for each topic."""
+        self.topic_keywords = {
+            PolicyTopic.WATER_FLUORIDATION: [
+                "fluoridation", "fluoride", "water fluoridation",
+                "fluoridated water", "fluoride level", "fluoride treatment",
+                "community water fluoridation"
+            ],
+            PolicyTopic.SCHOOL_DENTAL_SCREENING: [
+                "school dental", "dental screening", "school screening",
+                "school health screening", "dental exam", "school nurse",
+                "student dental"
+            ],
+            PolicyTopic.MEDICAID_DENTAL: [
+                "medicaid dental", "medicaid", "medicare dental",
+                "public assistance dental", "low-income dental",
+                "dental benefits", "dental coverage"
+            ],
+            PolicyTopic.DENTAL_CLINIC_FUNDING: [
+                "dental clinic", "community dental clinic",
+                "dental center", "dental facility", "clinic funding",
+                "dental services funding"
+            ],
+            PolicyTopic.COMMUNITY_DENTAL_PROGRAM: [
+                "community dental", "dental program", "oral health program",
+                "dental outreach", "mobile dental", "dental van"
+            ],
+            PolicyTopic.CHILDREN_DENTAL_HEALTH: [
+                "children's dental", "pediatric dental", "child dental",
+                "kids dental", "youth dental", "infant oral health"
+            ],
+            PolicyTopic.DENTAL_CARE_ACCESS: [
+                "dental access", "access to dental", "dental care",
+                "oral health access", "dental services", "dental disparities"
+            ]
+        }
+    
+    async def process(self, message: AgentMessage) -> List[AgentMessage]:
+        """
+        Process classification commands.
+        
+        Args:
+            message: Message containing parsed documents to classify
+            
+        Returns:
+            List of messages with classification results
+        """
+        self.update_status(AgentStatus.PROCESSING, "Classifying policy documents")
+        
+        try:
+            documents = message.payload.get("documents", [])
+            
+            # Classify documents in batches
+            batch_size = settings.classifier_batch_size
+            classified_documents = []
+            
+            for i in range(0, len(documents), batch_size):
+                batch = documents[i:i + batch_size]
+                batch_results = await self._classify_batch(batch)
+                classified_documents.extend(batch_results)
+            
+            # Filter to only relevant documents
+            relevant_documents = [
+                doc for doc in classified_documents
+                if doc["classification"]["primary_topic"] != PolicyTopic.NOT_RELEVANT
+            ]
+            
+            # Send classified documents to sentiment analyzer
+            response = await self.send_message(
+                AgentRole.SENTIMENT_ANALYZER,
+                MessageType.DATA,
+                {
+                    "workflow_id": message.payload.get("workflow_id"),
+                    "documents": relevant_documents,
+                    "count": len(relevant_documents),
+                    "filtered_count": len(documents) - len(relevant_documents)
+                }
+            )
+            
+            self.log_success()
+            logger.info(
+                f"Classified {len(documents)} documents, "
+                f"{len(relevant_documents)} relevant to oral health policy"
+            )
+            
+            return [response]
+            
+        except Exception as e:
+            self.log_failure(str(e))
+            error_msg = await self.send_message(
+                AgentRole.ORCHESTRATOR,
+                MessageType.ERROR,
+                {"error": str(e), "agent": self.agent_id}
+            )
+            return [error_msg]
+    
+    async def _classify_batch(
+        self,
+        documents: List[Dict[str, Any]]
+    ) -> List[Dict[str, Any]]:
+        """
+        Classify a batch of documents.
+        
+        Args:
+            documents: Batch of documents to classify
+            
+        Returns:
+            Documents with classification results
+        """
+        tasks = [self._classify_document(doc) for doc in documents]
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+        
+        classified = []
+        for doc, result in zip(documents, results):
+            if isinstance(result, Exception):
+                logger.error(f"Classification error for {doc['document_id']}: {result}")
+                doc["classification"] = {
+                    "primary_topic": PolicyTopic.NOT_RELEVANT,
+                    "error": str(result)
+                }
+            else:
+                doc["classification"] = result
+            
+            classified.append(doc)
+        
+        return classified
+    
+    async def _classify_document(
+        self,
+        doc: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Classify a single document.
+        
+        Args:
+            doc: Document to classify
+            
+        Returns:
+            Classification results
+        """
+        text = self._get_searchable_text(doc)
+        text_lower = text.lower()
+        
+        # Keyword-based classification
+        topic_scores = {}
+        for topic, keywords in self.topic_keywords.items():
+            score = sum(1 for keyword in keywords if keyword in text_lower)
+            if score > 0:
+                topic_scores[topic] = score
+        
+        # Determine primary topic
+        if topic_scores:
+            primary_topic = max(topic_scores, key=topic_scores.get)
+            confidence = "high" if topic_scores[primary_topic] >= 3 else "medium"
+            
+            # Get all topics mentioned
+            all_topics = list(topic_scores.keys())
+        else:
+            primary_topic = PolicyTopic.NOT_RELEVANT
+            confidence = "high"
+            all_topics = []
+        
+        # Extract relevant excerpts
+        excerpts = self._extract_relevant_excerpts(doc, primary_topic)
+        
+        classification = {
+            "primary_topic": primary_topic,
+            "all_topics": all_topics,
+            "topic_scores": topic_scores,
+            "confidence": confidence,
+            "relevant_excerpts": excerpts,
+            "classified_at": datetime.utcnow().isoformat()
+        }
+        
+        return classification
+    
+    def _get_searchable_text(self, doc: Dict[str, Any]) -> str:
+        """Extract searchable text from document."""
+        parts = [
+            doc.get("raw_title", ""),
+            doc.get("full_text", "")
+        ]
+        
+        # Add agenda items
+        for item in doc.get("agenda_items", []):
+            parts.append(item.get("description", ""))
+        
+        # Add discussion sections
+        for section in doc.get("discussion_sections", []):
+            parts.append(section.get("text", ""))
+        
+        return " ".join(parts)
+    
+    def _extract_relevant_excerpts(
+        self,
+        doc: Dict[str, Any],
+        topic: str
+    ) -> List[Dict[str, str]]:
+        """Extract text excerpts relevant to the topic."""
+        if topic == PolicyTopic.NOT_RELEVANT:
+            return []
+        
+        keywords = self.topic_keywords.get(topic, [])
+        excerpts = []
+        
+        # Check discussion sections
+        for section in doc.get("discussion_sections", []):
+            text = section.get("text", "")
+            text_lower = text.lower()
+            
+            # Check if any keywords present
+            if any(keyword in text_lower for keyword in keywords):
+                excerpts.append({
+                    "source": "discussion",
+                    "text": text[:500],  # First 500 chars
+                    "section_id": section.get("section_id")
+                })
+        
+        # Check agenda items
+        for item in doc.get("agenda_items", []):
+            desc = item.get("description", "")
+            desc_lower = desc.lower()
+            
+            if any(keyword in desc_lower for keyword in keywords):
+                excerpts.append({
+                    "source": "agenda",
+                    "text": desc,
+                    "item_number": item.get("number")
+                })
+        
+        return excerpts[:5]  # Return top 5 excerpts
+    
+    async def _llm_classify(
+        self,
+        text: str,
+        preliminary_topics: List[str]
+    ) -> Dict[str, Any]:
+        """
+        Use LLM for nuanced classification when keywords are ambiguous.
+        
+        Args:
+            text: Text to classify
+            preliminary_topics: Topics identified by keyword matching
+            
+        Returns:
+            LLM classification results
+        """
+        # This would use OpenAI API or similar
+        # Placeholder for now
+        return {
+            "llm_topic": preliminary_topics[0] if preliminary_topics else PolicyTopic.NOT_RELEVANT,
+            "llm_confidence": 0.8,
+            "llm_reasoning": "Based on keyword analysis"
+        }

agents/debate_grader.py

@@ -0,0 +1,424 @@
+"""
+Debate Grader Agent for evaluating government decisions using debate framework.
+
+Evaluates decisions across three dimensions:
+- Harms: The problem/crisis identified
+- Solvency: How the proposed solution addresses the problem
+- Topicality: Whether the solution fits within jurisdiction's authority
+"""
+import asyncio
+from typing import List, Dict, Any, Optional
+from datetime import datetime
+from loguru import logger
+
+from agents.base import BaseAgent, AgentRole, AgentMessage, MessageType, AgentStatus
+
+
+class DebateDimension:
+    """Enumeration of debate evaluation dimensions."""
+    HARMS = "harms"  # The problem
+    SOLVENCY = "solvency"  # The fix
+    TOPICALITY = "topicality"  # The scope
+
+
+class DebateScore:
+    """Score levels for each debate dimension."""
+    EXCELLENT = "excellent"  # 4-5/5
+    GOOD = "good"  # 3-4/5
+    FAIR = "fair"  # 2-3/5
+    WEAK = "weak"  # 1-2/5
+    MISSING = "missing"  # 0-1/5
+
+
+class DebateGraderAgent(BaseAgent):
+    """
+    Agent responsible for grading government decisions using debate framework.
+    
+    Translates debate concepts for laypeople:
+    - Harms → "The Problem": Why is this a crisis in our community?
+    - Solvency → "The Fix": How does this solution actually work?
+    - Topicality → "The Scope": Does the government have authority to do this?
+    """
+    
+    def __init__(self, agent_id: str = "debate-grader-001"):
+        """Initialize the debate grader agent."""
+        super().__init__(agent_id, AgentRole.SENTIMENT_ANALYZER)
+        self._initialize_criteria()
+    
+    def _initialize_criteria(self):
+        """Initialize evaluation criteria for each dimension."""
+        
+        # Harms evaluation keywords
+        self.harms_indicators = {
+            "problem_identification": [
+                "crisis", "emergency", "critical", "urgent need",
+                "widespread problem", "affecting", "impacting",
+                "suffering", "lack of", "shortage", "gap in services"
+            ],
+            "data_evidence": [
+                "statistics", "data shows", "research indicates",
+                "study found", "percent", "%", "number of people",
+                "cases", "instances", "reports"
+            ],
+            "affected_population": [
+                "children", "families", "residents", "citizens",
+                "low-income", "vulnerable", "underserved",
+                "community members", "students", "seniors"
+            ]
+        }
+        
+        # Solvency evaluation keywords
+        self.solvency_indicators = {
+            "solution_clarity": [
+                "will", "would", "proposes to", "plans to",
+                "implement", "establish", "create", "provide",
+                "offer", "deliver", "fund", "allocate"
+            ],
+            "mechanism": [
+                "through", "by", "using", "via", "process",
+                "program", "initiative", "partnership",
+                "collaboration", "service", "system"
+            ],
+            "evidence_of_effectiveness": [
+                "proven", "successful in", "works in",
+                "demonstrated", "track record", "best practice",
+                "evidence-based", "research-backed"
+            ],
+            "implementation_plan": [
+                "timeline", "budget", "staff", "resources",
+                "phase", "rollout", "launch", "start date",
+                "completion", "milestones"
+            ]
+        }
+        
+        # Topicality evaluation keywords
+        self.topicality_indicators = {
+            "legal_authority": [
+                "authority", "jurisdiction", "mandate",
+                "chartered to", "empowered to", "authorized",
+                "within our purview", "responsibility"
+            ],
+            "precedent": [
+                "previously", "historically", "past practice",
+                "similar actions", "other cities", "state law",
+                "federal law", "code", "ordinance"
+            ],
+            "scope_appropriateness": [
+                "city council", "county commission", "board",
+                "department", "local government", "municipal",
+                "within scope", "appropriate for"
+            ]
+        }
+    
+    async def process(self, message: AgentMessage) -> List[AgentMessage]:
+        """
+        Process debate grading commands.
+        
+        Args:
+            message: Message containing decisions/documents to grade
+            
+        Returns:
+            List of messages with debate grades
+        """
+        self.update_status(AgentStatus.PROCESSING, "Grading decisions with debate framework")
+        
+        try:
+            documents = message.payload.get("documents", [])
+            
+            graded_documents = []
+            
+            for doc in documents:
+                grade = await self._grade_document(doc)
+                doc["debate_grade"] = grade
+                graded_documents.append(doc)
+            
+            # Calculate aggregate insights
+            insights = self._generate_insights(graded_documents)
+            
+            # Send results
+            response = await self.send_message(
+                recipient=AgentRole.ORCHESTRATOR,
+                message_type=MessageType.RESPONSE,
+                payload={
+                    "documents": graded_documents,
+                    "insights": insights,
+                    "graded_count": len(graded_documents)
+                }
+            )
+            
+            self.update_status(AgentStatus.COMPLETED, f"Graded {len(graded_documents)} decisions")
+            return [response]
+            
+        except Exception as e:
+            logger.error(f"Debate grading failed: {e}")
+            self.update_status(AgentStatus.ERROR, str(e))
+            raise
+    
+    async def _grade_document(self, document: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Grade a single document across all debate dimensions.
+        
+        Args:
+            document: Document to grade
+            
+        Returns:
+            Dictionary with grades for each dimension
+        """
+        text = document.get("content", "").lower()
+        title = document.get("title", "").lower()
+        combined_text = f"{title} {text}"
+        
+        # Grade each dimension
+        harms_score = self._grade_harms(combined_text)
+        solvency_score = self._grade_solvency(combined_text)
+        topicality_score = self._grade_topicality(combined_text)
+        
+        # Calculate overall score
+        overall_score = self._calculate_overall_score(
+            harms_score, solvency_score, topicality_score
+        )
+        
+        return {
+            "dimensions": {
+                "harms": {
+                    "score": harms_score["score"],
+                    "grade": harms_score["grade"],
+                    "explanation": harms_score["explanation"],
+                    "layperson_label": "The Problem",
+                    "layperson_question": "Why is this a crisis in our community?"
+                },
+                "solvency": {
+                    "score": solvency_score["score"],
+                    "grade": solvency_score["grade"],
+                    "explanation": solvency_score["explanation"],
+                    "layperson_label": "The Fix",
+                    "layperson_question": "How does this solution actually work?"
+                },
+                "topicality": {
+                    "score": topicality_score["score"],
+                    "grade": topicality_score["grade"],
+                    "explanation": topicality_score["explanation"],
+                    "layperson_label": "The Scope",
+                    "layperson_question": "Does the government have authority to do this?"
+                }
+            },
+            "overall": {
+                "score": overall_score,
+                "grade": self._score_to_grade(overall_score),
+                "summary": self._generate_summary(harms_score, solvency_score, topicality_score)
+            },
+            "timestamp": datetime.utcnow().isoformat()
+        }
+    
+    def _grade_harms(self, text: str) -> Dict[str, Any]:
+        """Grade the 'harms' dimension - problem identification."""
+        score = 0
+        max_score = 5
+        details = []
+        
+        # Check for problem identification (0-2 points)
+        problem_count = sum(1 for keyword in self.harms_indicators["problem_identification"] if keyword in text)
+        if problem_count >= 3:
+            score += 2
+            details.append("Strong problem identification")
+        elif problem_count >= 1:
+            score += 1
+            details.append("Problem mentioned but not detailed")
+        
+        # Check for data/evidence (0-2 points)
+        data_count = sum(1 for keyword in self.harms_indicators["data_evidence"] if keyword in text)
+        if data_count >= 2:
+            score += 2
+            details.append("Data-driven evidence provided")
+        elif data_count >= 1:
+            score += 1
+            details.append("Some evidence mentioned")
+        
+        # Check for affected population (0-1 point)
+        population_count = sum(1 for keyword in self.harms_indicators["affected_population"] if keyword in text)
+        if population_count >= 1:
+            score += 1
+            details.append("Affected population identified")
+        
+        return {
+            "score": score,
+            "max_score": max_score,
+            "grade": self._score_to_grade(score / max_score * 5),
+            "explanation": "; ".join(details) if details else "No clear problem statement"
+        }
+    
+    def _grade_solvency(self, text: str) -> Dict[str, Any]:
+        """Grade the 'solvency' dimension - solution effectiveness."""
+        score = 0
+        max_score = 5
+        details = []
+        
+        # Check for solution clarity (0-1 point)
+        solution_count = sum(1 for keyword in self.solvency_indicators["solution_clarity"] if keyword in text)
+        if solution_count >= 2:
+            score += 1
+            details.append("Clear solution proposed")
+        
+        # Check for mechanism (0-2 points)
+        mechanism_count = sum(1 for keyword in self.solvency_indicators["mechanism"] if keyword in text)
+        if mechanism_count >= 3:
+            score += 2
+            details.append("Implementation mechanism described")
+        elif mechanism_count >= 1:
+            score += 1
+            details.append("Basic approach outlined")
+        
+        # Check for evidence of effectiveness (0-1 point)
+        evidence_count = sum(1 for keyword in self.solvency_indicators["evidence_of_effectiveness"] if keyword in text)
+        if evidence_count >= 1:
+            score += 1
+            details.append("Evidence-based approach")
+        
+        # Check for implementation plan (0-1 point)
+        plan_count = sum(1 for keyword in self.solvency_indicators["implementation_plan"] if keyword in text)
+        if plan_count >= 2:
+            score += 1
+            details.append("Implementation plan included")
+        
+        return {
+            "score": score,
+            "max_score": max_score,
+            "grade": self._score_to_grade(score / max_score * 5),
+            "explanation": "; ".join(details) if details else "No clear solution mechanism"
+        }
+    
+    def _grade_topicality(self, text: str) -> Dict[str, Any]:
+        """Grade the 'topicality' dimension - scope appropriateness."""
+        score = 0
+        max_score = 5
+        details = []
+        
+        # Check for legal authority (0-2 points)
+        authority_count = sum(1 for keyword in self.topicality_indicators["legal_authority"] if keyword in text)
+        if authority_count >= 2:
+            score += 2
+            details.append("Legal authority cited")
+        elif authority_count >= 1:
+            score += 1
+            details.append("Authority mentioned")
+        
+        # Check for precedent (0-2 points)
+        precedent_count = sum(1 for keyword in self.topicality_indicators["precedent"] if keyword in text)
+        if precedent_count >= 2:
+            score += 2
+            details.append("Precedent established")
+        elif precedent_count >= 1:
+            score += 1
+            details.append("Some precedent referenced")
+        
+        # Check for scope appropriateness (0-1 point)
+        scope_count = sum(1 for keyword in self.topicality_indicators["scope_appropriateness"] if keyword in text)
+        if scope_count >= 1:
+            score += 1
+            details.append("Within appropriate scope")
+        
+        return {
+            "score": score,
+            "max_score": max_score,
+            "grade": self._score_to_grade(score / max_score * 5),
+            "explanation": "; ".join(details) if details else "Unclear jurisdictional authority"
+        }
+    
+    def _score_to_grade(self, normalized_score: float) -> str:
+        """Convert numerical score to grade."""
+        if normalized_score >= 4.0:
+            return DebateScore.EXCELLENT
+        elif normalized_score >= 3.0:
+            return DebateScore.GOOD
+        elif normalized_score >= 2.0:
+            return DebateScore.FAIR
+        elif normalized_score >= 1.0:
+            return DebateScore.WEAK
+        else:
+            return DebateScore.MISSING
+    
+    def _calculate_overall_score(
+        self,
+        harms: Dict[str, Any],
+        solvency: Dict[str, Any],
+        topicality: Dict[str, Any]
+    ) -> float:
+        """Calculate weighted overall score."""
+        # Weight: Harms 40%, Solvency 40%, Topicality 20%
+        harms_normalized = (harms["score"] / harms["max_score"]) * 5
+        solvency_normalized = (solvency["score"] / solvency["max_score"]) * 5
+        topicality_normalized = (topicality["score"] / topicality["max_score"]) * 5
+        
+        overall = (harms_normalized * 0.4) + (solvency_normalized * 0.4) + (topicality_normalized * 0.2)
+        return round(overall, 2)
+    
+    def _generate_summary(
+        self,
+        harms: Dict[str, Any],
+        solvency: Dict[str, Any],
+        topicality: Dict[str, Any]
+    ) -> str:
+        """Generate human-readable summary."""
+        parts = []
+        
+        if harms["grade"] in [DebateScore.EXCELLENT, DebateScore.GOOD]:
+            parts.append("Strong problem identification")
+        else:
+            parts.append("Weak problem statement")
+        
+        if solvency["grade"] in [DebateScore.EXCELLENT, DebateScore.GOOD]:
+            parts.append("clear solution")
+        else:
+            parts.append("unclear fix")
+        
+        if topicality["grade"] in [DebateScore.EXCELLENT, DebateScore.GOOD]:
+            parts.append("within authority")
+        else:
+            parts.append("questionable scope")
+        
+        return "; ".join(parts).capitalize()
+    
+    def _generate_insights(self, documents: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """Generate aggregate insights from all graded documents."""
+        if not documents:
+            return {}
+        
+        total = len(documents)
+        dimension_scores = {
+            "harms": [],
+            "solvency": [],
+            "topicality": []
+        }
+        overall_scores = []
+        
+        for doc in documents:
+            grade = doc.get("debate_grade", {})
+            dimensions = grade.get("dimensions", {})
+            
+            for dim in ["harms", "solvency", "topicality"]:
+                if dim in dimensions:
+                    dimension_scores[dim].append(dimensions[dim]["score"])
+            
+            if "overall" in grade:
+                overall_scores.append(grade["overall"]["score"])
+        
+        # Calculate averages
+        insights = {
+            "total_documents": total,
+            "average_scores": {
+                "harms": round(sum(dimension_scores["harms"]) / len(dimension_scores["harms"]), 2) if dimension_scores["harms"] else 0,
+                "solvency": round(sum(dimension_scores["solvency"]) / len(dimension_scores["solvency"]), 2) if dimension_scores["solvency"] else 0,
+                "topicality": round(sum(dimension_scores["topicality"]) / len(dimension_scores["topicality"]), 2) if dimension_scores["topicality"] else 0,
+                "overall": round(sum(overall_scores) / len(overall_scores), 2) if overall_scores else 0
+            },
+            "strongest_dimension": max(
+                dimension_scores.items(),
+                key=lambda x: sum(x[1]) / len(x[1]) if x[1] else 0
+            )[0] if any(dimension_scores.values()) else None,
+            "weakest_dimension": min(
+                dimension_scores.items(),
+                key=lambda x: sum(x[1]) / len(x[1]) if x[1] else 0
+            )[0] if any(dimension_scores.values()) else None
+        }
+        
+        return insights

agents/mlflow_base.py

@@ -0,0 +1,307 @@
+"""
+MLflow-based agent foundation for Databricks Agent Bricks.
+
+Provides:
+- MLflow Pyfunc model wrappers for agents
+- Unity Catalog integration
+- Automatic tracing and observability
+- Model serving compatibility
+"""
+from typing import Any, Dict, List, Optional, Union
+from abc import ABC, abstractmethod
+import mlflow
+from mlflow.pyfunc import PythonModel
+from mlflow.models import infer_signature
+from mlflow.tracking import MlflowClient
+import pandas as pd
+from datetime import datetime
+from loguru import logger
+
+from agents.base import AgentRole, AgentMessage, AgentStatus
+from config import settings
+
+
+class MLflowAgentBase(PythonModel, ABC):
+    """
+    Base class for agents that can be deployed via MLflow Model Serving.
+    
+    Integrates with:
+    - Unity Catalog for governance
+    - MLflow Tracking for experimentation
+    - Databricks Model Serving for deployment
+    - Mosaic AI Agent Framework for evaluation
+    """
+    
+    def __init__(self, agent_id: str, role: AgentRole):
+        """
+        Initialize MLflow agent.
+        
+        Args:
+            agent_id: Unique identifier for this agent
+            role: Agent role in the pipeline
+        """
+        super().__init__()
+        self.agent_id = agent_id
+        self.role = role
+        self.status = AgentStatus.IDLE
+        self.client = MlflowClient()
+        
+    def load_context(self, context):
+        """
+        Load agent context from MLflow (called during model loading).
+        
+        Args:
+            context: MLflow context with model artifacts
+        """
+        logger.info(f"Loading {self.role.value} agent from MLflow context")
+        # Load any model artifacts, configs, etc.
+        pass
+    
+    @abstractmethod
+    def _process_request(self, request: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Process a single agent request.
+        
+        Args:
+            request: Input request dictionary
+            
+        Returns:
+            Response dictionary
+        """
+        pass
+    
+    def predict(
+        self, 
+        context, 
+        model_input: Union[pd.DataFrame, Dict[str, Any], List[Dict[str, Any]]]
+    ) -> Union[pd.DataFrame, List[Dict[str, Any]]]:
+        """
+        MLflow Pyfunc predict interface.
+        
+        This is the main entry point when the agent is deployed as a Model Serving endpoint.
+        
+        Args:
+            context: MLflow context
+            model_input: Input data (DataFrame, dict, or list of dicts)
+            
+        Returns:
+            Predictions in same format as input
+        """
+        # Enable MLflow tracing for observability
+        with mlflow.start_span(name=f"{self.role.value}_agent") as span:
+            span.set_attribute("agent_id", self.agent_id)
+            span.set_attribute("agent_role", self.role.value)
+            
+            try:
+                # Convert input to standard format
+                if isinstance(model_input, pd.DataFrame):
+                    requests = model_input.to_dict('records')
+                    return_df = True
+                elif isinstance(model_input, dict):
+                    requests = [model_input]
+                    return_df = False
+                else:
+                    requests = model_input
+                    return_df = False
+                
+                # Process each request with tracing
+                results = []
+                for idx, request in enumerate(requests):
+                    with mlflow.start_span(name=f"process_request_{idx}") as req_span:
+                        req_span.set_attribute("request_id", request.get("request_id", f"req_{idx}"))
+                        
+                        try:
+                            result = self._process_request(request)
+                            result["status"] = "success"
+                            result["agent_id"] = self.agent_id
+                            result["timestamp"] = datetime.utcnow().isoformat()
+                            results.append(result)
+                            
+                            req_span.set_attribute("status", "success")
+                            
+                        except Exception as e:
+                            error_result = {
+                                "status": "error",
+                                "error": str(e),
+                                "agent_id": self.agent_id,
+                                "timestamp": datetime.utcnow().isoformat()
+                            }
+                            results.append(error_result)
+                            
+                            req_span.set_attribute("status", "error")
+                            req_span.set_attribute("error", str(e))
+                            logger.error(f"Error processing request {idx}: {e}")
+                
+                # Return in requested format
+                if return_df:
+                    return pd.DataFrame(results)
+                elif len(results) == 1 and not isinstance(model_input, list):
+                    return results[0]
+                else:
+                    return results
+                    
+            except Exception as e:
+                span.set_attribute("status", "error")
+                span.set_attribute("error", str(e))
+                logger.error(f"Error in {self.role.value} agent: {e}")
+                raise
+    
+    def log_to_mlflow(
+        self, 
+        model_name: str,
+        artifact_path: str = "agent",
+        registered_model_name: Optional[str] = None,
+        **kwargs
+    ):
+        """
+        Log this agent to MLflow.
+        
+        Args:
+            model_name: Name for the MLflow run
+            artifact_path: Path within the run to store the model
+            registered_model_name: Unity Catalog model name (e.g., "main.agents.scraper")
+            **kwargs: Additional MLflow logging parameters
+        """
+        with mlflow.start_run(run_name=model_name) as run:
+            # Log agent metadata
+            mlflow.log_param("agent_id", self.agent_id)
+            mlflow.log_param("agent_role", self.role.value)
+            mlflow.log_param("framework", "databricks-agent-bricks")
+            
+            # Create example input/output for signature
+            example_input = self._get_example_input()
+            example_output = self.predict(None, example_input)
+            signature = infer_signature(example_input, example_output)
+            
+            # Log the model
+            mlflow.pyfunc.log_model(
+                artifact_path=artifact_path,
+                python_model=self,
+                signature=signature,
+                registered_model_name=registered_model_name,
+                **kwargs
+            )
+            
+            logger.info(f"Logged {self.role.value} agent to MLflow run {run.info.run_id}")
+            
+            if registered_model_name:
+                logger.info(f"Registered model as {registered_model_name}")
+                
+            return run.info.run_id
+    
+    @abstractmethod
+    def _get_example_input(self) -> Union[pd.DataFrame, Dict[str, Any]]:
+        """
+        Get example input for MLflow signature inference.
+        
+        Returns:
+            Example input data
+        """
+        pass
+    
+    def deploy_to_model_serving(
+        self,
+        model_name: str,
+        endpoint_name: str,
+        workload_size: str = "Small",
+        scale_to_zero: bool = True
+    ) -> str:
+        """
+        Deploy this agent to Databricks Model Serving.
+        
+        Args:
+            model_name: Registered model name in Unity Catalog
+            endpoint_name: Name for the serving endpoint
+            workload_size: Endpoint size (Small, Medium, Large)
+            scale_to_zero: Whether to scale to zero when idle
+            
+        Returns:
+            Endpoint URL
+        """
+        from databricks.sdk import WorkspaceClient
+        from databricks.sdk.service.serving import ServedEntityInput, EndpointCoreConfigInput
+        
+        w = WorkspaceClient(
+            host=settings.databricks_host,
+            token=settings.databricks_token
+        )
+        
+        # Get latest model version
+        latest_version = self.client.get_latest_versions(model_name, stages=["None"])[0].version
+        
+        # Create or update endpoint
+        endpoint_config = EndpointCoreConfigInput(
+            name=endpoint_name,
+            served_entities=[
+                ServedEntityInput(
+                    entity_name=model_name,
+                    entity_version=latest_version,
+                    workload_size=workload_size,
+                    scale_to_zero_enabled=scale_to_zero
+                )
+            ]
+        )
+        
+        try:
+            endpoint = w.serving_endpoints.create_and_wait(
+                name=endpoint_name,
+                config=endpoint_config
+            )
+            logger.info(f"Created endpoint: {endpoint_name}")
+        except Exception as e:
+            if "already exists" in str(e):
+                endpoint = w.serving_endpoints.update_config_and_wait(
+                    name=endpoint_name,
+                    served_entities=endpoint_config.served_entities
+                )
+                logger.info(f"Updated endpoint: {endpoint_name}")
+            else:
+                raise
+        
+        endpoint_url = f"{settings.databricks_host}/serving-endpoints/{endpoint_name}/invocations"
+        return endpoint_url
+
+
+class MLflowChainAgent(MLflowAgentBase):
+    """
+    Agent that uses LangChain with MLflow tracing.
+    
+    Provides integration with:
+    - LangChain agents and chains
+    - Automatic prompt logging
+    - LLM call tracing
+    - Tool usage tracking
+    """
+    
+    def __init__(self, agent_id: str, role: AgentRole):
+        """Initialize LangChain-based agent."""
+        super().__init__(agent_id, role)
+        self.chain = None
+        
+    def _setup_langchain_tracing(self):
+        """Enable MLflow tracing for LangChain."""
+        mlflow.langchain.autolog()
+        
+    @abstractmethod
+    def _build_chain(self):
+        """
+        Build the LangChain chain for this agent.
+        
+        Returns:
+            LangChain chain or agent
+        """
+        pass
+    
+    def _process_request(self, request: Dict[str, Any]) -> Dict[str, Any]:
+        """Process request through LangChain."""
+        if self.chain is None:
+            self.chain = self._build_chain()
+            
+        with mlflow.start_span(name="langchain_invoke") as span:
+            result = self.chain.invoke(request)
+            
+            # Log relevant metrics
+            if hasattr(result, "llm_output"):
+                span.set_attribute("tokens_used", result.llm_output.get("token_usage", {}).get("total_tokens", 0))
+            
+            return result

agents/mlflow_classifier.py

@@ -0,0 +1,308 @@
+"""
+Policy Classifier Agent - MLflow version for Databricks Agent Bricks.
+
+Classifies meeting documents for oral health policy topics using:
+- Keyword matching and NLP
+- LLM-based classification for ambiguous cases
+- Unity Catalog for model governance
+- MLflow tracing for observability
+"""
+from typing import Any, Dict, List, Optional
+import pandas as pd
+from enum import Enum
+import mlflow
+from langchain.chat_models import ChatOpenAI
+from langchain.prompts import ChatPromptTemplate
+from langchain.output_parsers import PydanticOutputParser
+from pydantic import BaseModel, Field
+
+from agents.mlflow_base import MLflowChainAgent
+from agents.base import AgentRole
+from config import settings
+
+
+class PolicyTopic(str, Enum):
+    """Oral health policy topics to classify."""
+    WATER_FLUORIDATION = "water_fluoridation"
+    SCHOOL_DENTAL_SCREENING = "school_dental_screening"
+    MEDICAID_DENTAL = "medicaid_dental_expansion"
+    LOW_INCOME_DENTAL_FUNDING = "low_income_dental_funding"
+    DENTAL_INSURANCE_MANDATE = "dental_insurance_mandate"
+    DENTAL_WORKFORCE = "dental_workforce_development"
+    COMMUNITY_HEALTH_CENTER = "community_health_center_dental"
+    OTHER_ORAL_HEALTH = "other_oral_health"
+    NOT_ORAL_HEALTH = "not_oral_health_related"
+
+
+class ClassificationResult(BaseModel):
+    """Structured classification output."""
+    primary_topic: PolicyTopic = Field(description="Primary policy topic")
+    secondary_topics: List[PolicyTopic] = Field(default_factory=list, description="Additional relevant topics")
+    confidence: float = Field(ge=0.0, le=1.0, description="Classification confidence")
+    relevant_excerpts: List[str] = Field(default_factory=list, description="Key text excerpts")
+    reasoning: str = Field(description="Brief explanation of classification")
+
+
+class PolicyClassifierAgent(MLflowChainAgent):
+    """
+    Agent that classifies documents for oral health policy topics.
+    
+    Can be deployed to Databricks Model Serving and integrated with
+    Unity Catalog for governance.
+    """
+    
+    # Keywords for each topic (fallback classification)
+    TOPIC_KEYWORDS = {
+        PolicyTopic.WATER_FLUORIDATION: {
+            "fluoride", "fluoridation", "water supply", "dental fluorosis",
+            "community water", "fluoride levels", "fluoridated water"
+        },
+        PolicyTopic.SCHOOL_DENTAL_SCREENING: {
+            "school dental", "screening program", "student dental", "school health",
+            "dental exam", "school nurse", "oral health screening"
+        },
+        PolicyTopic.MEDICAID_DENTAL: {
+            "medicaid dental", "adult dental coverage", "medicaid expansion",
+            "dental benefits", "state medicaid", "covered dental services"
+        },
+        PolicyTopic.LOW_INCOME_DENTAL_FUNDING: {
+            "low-income dental", "dental safety net", "free dental clinic",
+            "dental voucher", "sliding scale dental", "charity care"
+        },
+        PolicyTopic.DENTAL_INSURANCE_MANDATE: {
+            "dental insurance", "insurance mandate", "coverage requirement",
+            "pediatric dental", "essential health benefits"
+        },
+        PolicyTopic.DENTAL_WORKFORCE: {
+            "dental hygienist", "dental therapist", "scope of practice",
+            "workforce shortage", "dental provider", "loan repayment"
+        },
+        PolicyTopic.COMMUNITY_HEALTH_CENTER: {
+            "community health center", "FQHC", "health center dental",
+            "federally qualified", "CHC dental"
+        }
+    }
+    
+    def __init__(self, agent_id: str = "classifier-mlflow-001"):
+        """Initialize classifier agent."""
+        super().__init__(agent_id, AgentRole.CLASSIFIER)
+        self._setup_langchain_tracing()
+        
+    def _build_chain(self):
+        """Build LangChain classification chain."""
+        # Initialize LLM (will use AI Gateway if configured)
+        llm = ChatOpenAI(
+            model=settings.classifier_model,
+            temperature=0.1,
+            openai_api_key=settings.openai_api_key
+        )
+        
+        # Create output parser
+        parser = PydanticOutputParser(pydantic_object=ClassificationResult)
+        
+        # Create prompt template
+        prompt = ChatPromptTemplate.from_messages([
+            ("system", """You are an expert policy analyst specializing in oral health policy.
+            
+Classify the following government meeting document for oral health policy topics.
+
+Available topics:
+- water_fluoridation: Fluoride in public water systems
+- school_dental_screening: School-based dental programs
+- medicaid_dental_expansion: Medicaid dental coverage
+- low_income_dental_funding: Funding for low-income dental care
+- dental_insurance_mandate: Insurance coverage requirements
+- dental_workforce_development: Training, scope of practice
+- community_health_center_dental: CHC/FQHC dental services
+- other_oral_health: Other oral health topics
+- not_oral_health_related: Not related to oral health
+
+{format_instructions}"""),
+            ("user", """Document Title: {title}
+            
+Document Content:
+{content}
+
+Classify this document and provide relevant excerpts.""")
+        ])
+        
+        # Build chain
+        chain = prompt | llm | parser
+        return chain
+    
+    def _process_request(self, request: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Classify a document for oral health policy topics.
+        
+        Args:
+            request: Dict with 'document_id', 'title', 'content'
+            
+        Returns:
+            Classification results with topics and confidence
+        """
+        document_id = request.get("document_id")
+        title = request.get("title", "")
+        content = request.get("content", "")
+        
+        with mlflow.start_span(name="classify_document") as span:
+            span.set_attribute("document_id", document_id)
+            
+            # Try keyword-based classification first (faster, cheaper)
+            keyword_result = self._classify_by_keywords(title + " " + content)
+            
+            if keyword_result["confidence"] >= 0.8:
+                # High confidence from keywords, no LLM needed
+                span.set_attribute("classification_method", "keywords")
+                result = keyword_result
+            else:
+                # Use LLM for ambiguous cases
+                span.set_attribute("classification_method", "llm")
+                
+                try:
+                    llm_result = super()._process_request({
+                        "title": title,
+                        "content": content[:4000],  # Limit context length
+                        "format_instructions": self._get_format_instructions()
+                    })
+                    
+                    result = {
+                        "document_id": document_id,
+                        "primary_topic": llm_result.primary_topic.value,
+                        "secondary_topics": [t.value for t in llm_result.secondary_topics],
+                        "confidence": llm_result.confidence,
+                        "relevant_excerpts": llm_result.relevant_excerpts,
+                        "reasoning": llm_result.reasoning,
+                        "method": "llm"
+                    }
+                    
+                except Exception as e:
+                    # Fallback to keywords if LLM fails
+                    span.set_attribute("llm_error", str(e))
+                    result = keyword_result
+                    result["method"] = "keywords_fallback"
+            
+            return result
+    
+    def _classify_by_keywords(self, text: str) -> Dict[str, Any]:
+        """
+        Fast keyword-based classification.
+        
+        Args:
+            text: Document text
+            
+        Returns:
+            Classification result
+        """
+        text_lower = text.lower()
+        scores = {}
+        
+        # Score each topic
+        for topic, keywords in self.TOPIC_KEYWORDS.items():
+            score = sum(1 for keyword in keywords if keyword in text_lower)
+            if score > 0:
+                scores[topic] = score
+        
+        if not scores:
+            return {
+                "primary_topic": PolicyTopic.NOT_ORAL_HEALTH.value,
+                "secondary_topics": [],
+                "confidence": 0.9,
+                "relevant_excerpts": [],
+                "reasoning": "No oral health keywords found",
+                "method": "keywords"
+            }
+        
+        # Get top topics
+        sorted_topics = sorted(scores.items(), key=lambda x: x[1], reverse=True)
+        primary_topic = sorted_topics[0][0]
+        secondary_topics = [t for t, s in sorted_topics[1:3] if s >= 2]
+        
+        # Calculate confidence based on score gap
+        max_score = sorted_topics[0][1]
+        confidence = min(0.95, 0.5 + (max_score / 10))
+        
+        # Extract relevant excerpts
+        excerpts = self._extract_excerpts(text, primary_topic)
+        
+        return {
+            "primary_topic": primary_topic.value,
+            "secondary_topics": [t.value for t in secondary_topics],
+            "confidence": confidence,
+            "relevant_excerpts": excerpts,
+            "reasoning": f"Found {max_score} keyword matches for {primary_topic.value}",
+            "method": "keywords"
+        }
+    
+    def _extract_excerpts(self, text: str, topic: PolicyTopic, max_excerpts: int = 3) -> List[str]:
+        """Extract relevant text excerpts for a topic."""
+        keywords = self.TOPIC_KEYWORDS.get(topic, set())
+        sentences = text.split('. ')
+        
+        relevant = []
+        for sentence in sentences:
+            sentence_lower = sentence.lower()
+            if any(keyword in sentence_lower for keyword in keywords):
+                relevant.append(sentence.strip())
+                if len(relevant) >= max_excerpts:
+                    break
+        
+        return relevant
+    
+    def _get_format_instructions(self) -> str:
+        """Get format instructions for LLM output parsing."""
+        parser = PydanticOutputParser(pydantic_object=ClassificationResult)
+        return parser.get_format_instructions()
+    
+    def _get_example_input(self) -> Dict[str, Any]:
+        """Get example input for MLflow signature."""
+        return {
+            "document_id": "doc_12345",
+            "title": "City Council Meeting - Water Quality Discussion",
+            "content": "The council discussed adding fluoride to the municipal water supply..."
+        }
+
+
+def register_classifier_to_unity_catalog():
+    """
+    Register the classifier agent to Unity Catalog.
+    
+    Usage:
+        python -c "from agents.mlflow_classifier import register_classifier_to_unity_catalog; register_classifier_to_unity_catalog()"
+    """
+    agent = PolicyClassifierAgent()
+    
+    # Log and register to Unity Catalog
+    run_id = agent.log_to_mlflow(
+        model_name="policy_classifier_agent",
+        registered_model_name=f"{settings.catalog_name}.{settings.schema_name}.policy_classifier",
+        pip_requirements=[
+            "mlflow>=2.10.0",
+            "langchain>=0.1.0",
+            "openai>=1.6.0",
+            "pydantic>=2.5.0"
+        ]
+    )
+    
+    print(f"✅ Registered policy classifier agent to Unity Catalog")
+    print(f"   Model: {settings.catalog_name}.{settings.schema_name}.policy_classifier")
+    print(f"   Run ID: {run_id}")
+    
+    return run_id
+
+
+if __name__ == "__main__":
+    # Test the agent locally
+    agent = PolicyClassifierAgent()
+    
+    test_input = {
+        "document_id": "test_001",
+        "title": "School Board Meeting Minutes",
+        "content": """
+        The school board discussed implementing a new dental screening program
+        for elementary students. The program would provide free dental exams
+        and referrals to local dentists for students in need.
+        """
+    }
+    
+    result = agent.predict(None, test_input)
+    print("Classification Result:", result)

agents/orchestrator.py

@@ -0,0 +1,269 @@
+"""
+Multi-Agent Orchestrator for coordinating the policy analysis pipeline.
+"""
+import asyncio
+from typing import Dict, List, Optional, Any
+from datetime import datetime
+from collections import defaultdict
+from loguru import logger
+
+from agents.base import (
+    BaseAgent,
+    AgentRole,
+    AgentMessage,
+    MessageType,
+    AgentStatus
+)
+
+
+class WorkflowStage(str):
+    """Workflow stage identifiers."""
+    SCRAPE = "scrape"
+    PARSE = "parse"
+    CLASSIFY = "classify"
+    ANALYZE = "analyze"
+    GENERATE = "generate"
+
+
+class OrchestratorAgent(BaseAgent):
+    """
+    Orchestrator agent that coordinates the multi-agent workflow.
+    
+    The orchestrator manages the flow of data through the pipeline:
+    1. Scraper Agent -> Collects meeting minutes
+    2. Parser Agent -> Extracts structured data
+    3. Classifier Agent -> Identifies oral health topics
+    4. Sentiment Agent -> Analyzes policy positions
+    5. Advocacy Agent -> Generates outreach materials
+    """
+    
+    def __init__(self, agent_id: str = "orchestrator-001"):
+        """Initialize the orchestrator agent."""
+        super().__init__(agent_id, AgentRole.ORCHESTRATOR)
+        self.agents: Dict[AgentRole, BaseAgent] = {}
+        self.workflow_state: Dict[str, Any] = defaultdict(dict)
+        self.active_workflows: Dict[str, Dict[str, Any]] = {}
+        
+    def register_agent(self, agent: BaseAgent):
+        """
+        Register an agent with the orchestrator.
+        
+        Args:
+            agent: The agent to register
+        """
+        self.agents[agent.role] = agent
+        logger.info(f"Registered {agent.role.value} agent: {agent.agent_id}")
+    
+    async def process(self, message: AgentMessage) -> List[AgentMessage]:
+        """
+        Process orchestrator commands and route messages.
+        
+        Args:
+            message: The incoming message
+            
+        Returns:
+            List of response messages
+        """
+        self.update_status(AgentStatus.PROCESSING, "Processing orchestrator command")
+        
+        try:
+            if message.message_type == MessageType.COMMAND:
+                command = message.payload.get("command")
+                
+                if command == "start_workflow":
+                    return await self._start_workflow(message.payload)
+                elif command == "check_status":
+                    return await self._check_workflow_status(message.payload)
+                elif command == "stop_workflow":
+                    return await self._stop_workflow(message.payload)
+            
+            self.log_success()
+            return []
+            
+        except Exception as e:
+            self.log_failure(str(e))
+            return [await self.send_message(
+                message.sender,
+                MessageType.ERROR,
+                {"error": str(e)}
+            )]
+    
+    async def _start_workflow(self, payload: Dict[str, Any]) -> List[AgentMessage]:
+        """
+        Start a new policy analysis workflow.
+        
+        Args:
+            payload: Workflow configuration
+            
+        Returns:
+            List of messages to initiate the workflow
+        """
+        import uuid
+        
+        workflow_id = str(uuid.uuid4())
+        workflow_config = payload.get("config", {})
+        
+        # Initialize workflow state
+        self.active_workflows[workflow_id] = {
+            "id": workflow_id,
+            "started_at": datetime.utcnow(),
+            "stage": WorkflowStage.SCRAPE,
+            "config": workflow_config,
+            "status": "running"
+        }
+        
+        logger.info(f"Starting workflow {workflow_id}")
+        
+        # Create initial scraping task
+        scraper_message = await self.send_message(
+            AgentRole.SCRAPER,
+            MessageType.COMMAND,
+            {
+                "workflow_id": workflow_id,
+                "command": "scrape",
+                "targets": workflow_config.get("scrape_targets", []),
+                "date_range": workflow_config.get("date_range", {})
+            }
+        )
+        
+        return [scraper_message]
+    
+    async def _check_workflow_status(self, payload: Dict[str, Any]) -> List[AgentMessage]:
+        """
+        Check the status of active workflows.
+        
+        Args:
+            payload: Status check request
+            
+        Returns:
+            List containing status response
+        """
+        workflow_id = payload.get("workflow_id")
+        
+        if workflow_id and workflow_id in self.active_workflows:
+            workflow = self.active_workflows[workflow_id]
+            status_payload = {
+                "workflow_id": workflow_id,
+                "status": workflow.get("status"),
+                "stage": workflow.get("stage"),
+                "started_at": workflow.get("started_at").isoformat()
+            }
+        else:
+            # Return status of all workflows
+            status_payload = {
+                "active_workflows": len(self.active_workflows),
+                "workflows": [
+                    {
+                        "id": wf_id,
+                        "status": wf["status"],
+                        "stage": wf["stage"]
+                    }
+                    for wf_id, wf in self.active_workflows.items()
+                ]
+            }
+        
+        response = await self.send_message(
+            AgentRole.ORCHESTRATOR,
+            MessageType.RESPONSE,
+            status_payload
+        )
+        
+        return [response]
+    
+    async def _stop_workflow(self, payload: Dict[str, Any]) -> List[AgentMessage]:
+        """
+        Stop a running workflow.
+        
+        Args:
+            payload: Stop request with workflow_id
+            
+        Returns:
+            List containing confirmation message
+        """
+        workflow_id = payload.get("workflow_id")
+        
+        if workflow_id in self.active_workflows:
+            self.active_workflows[workflow_id]["status"] = "stopped"
+            logger.info(f"Stopped workflow {workflow_id}")
+            
+            response = await self.send_message(
+                AgentRole.ORCHESTRATOR,
+                MessageType.RESPONSE,
+                {"workflow_id": workflow_id, "status": "stopped"}
+            )
+        else:
+            response = await self.send_message(
+                AgentRole.ORCHESTRATOR,
+                MessageType.ERROR,
+                {"error": f"Workflow {workflow_id} not found"}
+            )
+        
+        return [response]
+    
+    async def route_message(self, message: AgentMessage) -> Optional[AgentMessage]:
+        """
+        Route a message to the appropriate agent.
+        
+        Args:
+            message: The message to route
+            
+        Returns:
+            Response from the target agent
+        """
+        target_agent = self.agents.get(message.recipient)
+        
+        if not target_agent:
+            logger.error(f"No agent found for role: {message.recipient}")
+            return None
+        
+        try:
+            response = await target_agent.process(message)
+            return response
+        except Exception as e:
+            logger.error(f"Error routing message to {message.recipient}: {e}")
+            return None
+    
+    async def execute_pipeline(
+        self,
+        scrape_targets: List[Dict[str, Any]],
+        date_range: Optional[Dict[str, str]] = None
+    ) -> Dict[str, Any]:
+        """
+        Execute the complete policy analysis pipeline.
+        
+        Args:
+            scrape_targets: List of government entities to scrape
+            date_range: Optional date range for historical data
+            
+        Returns:
+            Dictionary containing pipeline results
+        """
+        workflow_config = {
+            "scrape_targets": scrape_targets,
+            "date_range": date_range or {}
+        }
+        
+        # Start the workflow
+        start_message = await self.send_message(
+            AgentRole.ORCHESTRATOR,
+            MessageType.COMMAND,
+            {
+                "command": "start_workflow",
+                "config": workflow_config
+            }
+        )
+        
+        results = await self.process(start_message)
+        
+        return {
+            "success": True,
+            "workflow_initiated": True,
+            "messages": [msg.dict() for msg in results]
+        }
+    
+    def get_all_agent_states(self) -> Dict[str, Any]:
+        """Get the current state of all registered agents."""
+        return {
+            role.value: agent.get_state().dict()
+            for role, agent in self.agents.items()
+        }

agents/parser.py

@@ -0,0 +1,199 @@
+"""
+Parser Agent for extracting and structuring data from raw meeting minutes.
+"""
+import re
+from typing import List, Dict, Any, Optional
+from datetime import datetime
+from loguru import logger
+
+from agents.base import BaseAgent, AgentRole, AgentMessage, MessageType, AgentStatus
+
+
+class ParserAgent(BaseAgent):
+    """
+    Agent responsible for parsing raw meeting documents into structured data.
+    
+    Extracts:
+    - Meeting metadata (date, type, location)
+    - Attendees and participants
+    - Agenda items
+    - Discussion topics
+    - Votes and decisions
+    - Action items
+    """
+    
+    def __init__(self, agent_id: str = "parser-001"):
+        """Initialize the parser agent."""
+        super().__init__(agent_id, AgentRole.PARSER)
+        self._compile_patterns()
+    
+    def _compile_patterns(self):
+        """Compile regex patterns for parsing."""
+        self.patterns = {
+            "date": re.compile(
+                r"(?:January|February|March|April|May|June|July|August|September|October|November|December)\s+\d{1,2},?\s+\d{4}",
+                re.IGNORECASE
+            ),
+            "time": re.compile(r"\d{1,2}:\d{2}\s*(?:AM|PM|am|pm)?"),
+            "attendees": re.compile(r"(?:Present|Attending|Members Present):(.+?)(?:\n\n|\Z)", re.DOTALL | re.IGNORECASE),
+            "motion": re.compile(r"(?:MOTION|Motion|MOVED)(.+?)(?:CARRIED|PASSED|FAILED|$)", re.DOTALL | re.IGNORECASE),
+            "vote": re.compile(r"(?:Vote|VOTE):\s*(.+)", re.IGNORECASE),
+            "agenda_item": re.compile(r"(?:Item|ITEM)\s+#?(\d+|[A-Z])[\.:]\s*(.+?)(?=\n(?:Item|ITEM)|$)", re.DOTALL | re.IGNORECASE)
+        }
+    
+    async def process(self, message: AgentMessage) -> List[AgentMessage]:
+        """
+        Process parsing commands.
+        
+        Args:
+            message: Message containing raw documents to parse
+            
+        Returns:
+            List of messages with parsed data
+        """
+        self.update_status(AgentStatus.PROCESSING, "Parsing meeting documents")
+        
+        try:
+            documents = message.payload.get("documents", [])
+            
+            parsed_documents = []
+            
+            for doc in documents:
+                parsed = await self._parse_document(doc)
+                if parsed:
+                    parsed_documents.append(parsed)
+            
+            # Send parsed documents to classifier
+            response = await self.send_message(
+                AgentRole.CLASSIFIER,
+                MessageType.DATA,
+                {
+                    "workflow_id": message.payload.get("workflow_id"),
+                    "documents": parsed_documents,
+                    "count": len(parsed_documents)
+                }
+            )
+            
+            self.log_success()
+            logger.info(f"Parsed {len(parsed_documents)} documents")
+            
+            return [response]
+            
+        except Exception as e:
+            self.log_failure(str(e))
+            error_msg = await self.send_message(
+                AgentRole.ORCHESTRATOR,
+                MessageType.ERROR,
+                {"error": str(e), "agent": self.agent_id}
+            )
+            return [error_msg]
+    
+    async def _parse_document(self, doc: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        """
+        Parse a single meeting document.
+        
+        Args:
+            doc: Raw document data
+            
+        Returns:
+            Parsed document with structured fields
+        """
+        try:
+            content = doc.get("content", "")
+            
+            parsed = {
+                "document_id": doc["document_id"],
+                "source_url": doc["source_url"],
+                "municipality": doc["municipality"],
+                "state": doc["state"],
+                "raw_title": doc["title"],
+                "parsed_at": datetime.utcnow().isoformat(),
+                
+                # Extracted structured data
+                "meeting_date": self._extract_date(content, doc.get("meeting_date")),
+                "meeting_time": self._extract_time(content),
+                "meeting_type": doc.get("meeting_type", "Unknown"),
+                "attendees": self._extract_attendees(content),
+                "agenda_items": self._extract_agenda_items(content),
+                "motions": self._extract_motions(content),
+                "votes": self._extract_votes(content),
+                "discussion_sections": self._extract_discussion_sections(content),
+                
+                # Full text for semantic search
+                "full_text": content,
+                
+                # Metadata
+                "metadata": doc.get("metadata", {})
+            }
+            
+            return parsed
+            
+        except Exception as e:
+            logger.error(f"Error parsing document {doc.get('document_id')}: {e}")
+            return None
+    
+    def _extract_date(self, content: str, fallback_date: Optional[str]) -> str:
+        """Extract meeting date from content."""
+        match = self.patterns["date"].search(content)
+        if match:
+            return match.group(0)
+        return fallback_date or datetime.utcnow().isoformat()
+    
+    def _extract_time(self, content: str) -> Optional[str]:
+        """Extract meeting time from content."""
+        match = self.patterns["time"].search(content)
+        return match.group(0) if match else None
+    
+    def _extract_attendees(self, content: str) -> List[str]:
+        """Extract list of meeting attendees."""
+        match = self.patterns["attendees"].search(content)
+        if match:
+            attendees_text = match.group(1)
+            # Split by comma or newline
+            attendees = re.split(r'[,\n]', attendees_text)
+            return [a.strip() for a in attendees if a.strip()]
+        return []
+    
+    def _extract_agenda_items(self, content: str) -> List[Dict[str, str]]:
+        """Extract agenda items from content."""
+        items = []
+        for match in self.patterns["agenda_item"].finditer(content):
+            items.append({
+                "number": match.group(1).strip(),
+                "description": match.group(2).strip()
+            })
+        return items
+    
+    def _extract_motions(self, content: str) -> List[Dict[str, str]]:
+        """Extract motions from content."""
+        motions = []
+        for match in self.patterns["motion"].finditer(content):
+            motions.append({
+                "text": match.group(1).strip(),
+                "full_match": match.group(0).strip()
+            })
+        return motions
+    
+    def _extract_votes(self, content: str) -> List[Dict[str, str]]:
+        """Extract voting records from content."""
+        votes = []
+        for match in self.patterns["vote"].finditer(content):
+            votes.append({
+                "result": match.group(1).strip()
+            })
+        return votes
+    
+    def _extract_discussion_sections(self, content: str) -> List[Dict[str, str]]:
+        """Extract discussion sections from content."""
+        # Split content into paragraphs
+        paragraphs = [p.strip() for p in content.split("\n\n") if p.strip()]
+        
+        sections = []
+        for i, para in enumerate(paragraphs):
+            if len(para) > 100:  # Only substantial paragraphs
+                sections.append({
+                    "section_id": i,
+                    "text": para
+                })
+        
+        return sections

agents/scraper.py

@@ -0,0 +1,2113 @@
+"""
+Scraper Agent for collecting government meeting minutes from various sources.
+"""
+import asyncio
+import hashlib
+import io
+import json
+import re
+from typing import List, Dict, Any, Optional
+from datetime import datetime, timedelta
+from urllib.parse import urljoin, urlparse
+import httpx
+from bs4 import BeautifulSoup
+from loguru import logger
+
+try:
+    from PyPDF2 import PdfReader
+except Exception:
+    PdfReader = None
+
+try:
+    import pdfplumber
+except Exception:
+    pdfplumber = None
+
+try:
+    import pytesseract
+    from pytesseract import TesseractNotFoundError
+except Exception:
+    pytesseract = None
+    TesseractNotFoundError = Exception
+
+try:
+    from PIL import Image
+except Exception:
+    Image = None
+
+try:
+    from youtube_transcript_api import YouTubeTranscriptApi
+except Exception:
+    YouTubeTranscriptApi = None
+
+from agents.base import BaseAgent, AgentRole, AgentMessage, MessageType, AgentStatus
+
+
+class MeetingDocument(dict):
+    """Structured representation of a meeting document."""
+    
+    def __init__(
+        self,
+        document_id: str,
+        source_url: str,
+        municipality: str,
+        state: str,
+        meeting_date: datetime,
+        meeting_type: str,
+        title: str,
+        content: str,
+        metadata: Optional[Dict[str, Any]] = None
+    ):
+        super().__init__(
+            document_id=document_id,
+            source_url=source_url,
+            municipality=municipality,
+            state=state,
+            meeting_date=meeting_date.isoformat() if isinstance(meeting_date, datetime) else meeting_date,
+            meeting_type=meeting_type,
+            title=title,
+            content=content,
+            scraped_at=datetime.utcnow().isoformat(),
+            metadata=metadata or {}
+        )
+
+
+class ScraperAgent(BaseAgent):
+    """
+    Agent responsible for scraping government meeting minutes from various sources.
+    
+    Supports multiple platforms:
+    - Legistar (widely used by city councils)
+    - Granicus (meeting management platform)
+    - Generic municipal websites
+    - PDF documents
+    """
+    
+    def __init__(self, agent_id: str = "scraper-001"):
+        """Initialize the scraper agent."""
+        super().__init__(agent_id, AgentRole.SCRAPER)
+        self.http_client: Optional[httpx.AsyncClient] = None
+        self.scraped_urls: set = set()
+        self.document_extensions = (".pdf", ".doc", ".docx", ".ppt", ".pptx", ".xls", ".xlsx")
+        self.meeting_keywords = ("minutes", "agenda", "meeting", "council", "commission", "board")
+        self.document_route_keywords = (
+            "getagendafile",
+            "getminutesfile",
+            "download",
+            "agendafile",
+            "minutesfile",
+        )
+        self.ocr_max_pages = 10
+        self._ocr_missing_tesseract_warned = False
+        self.social_source_limit = 8
+        
+        # Policy and meeting-focused keywords for social media filtering
+        self.policy_meeting_keywords = (
+            # Meetings
+            "council meeting", "city council", "town council", "board meeting",
+            "commission meeting", "public meeting", "town hall", "session",
+            "special meeting", "regular meeting", "work session", "workshop",
+            # Documents
+            "agenda", "minutes", "ordinance", "resolution", "public hearing",
+            "hearing", "vote", "voting", "motion", "legislation",
+            # Policy topics
+            "policy", "budget", "zoning", "planning", "development",
+            "public comment", "community meeting", "civic", "government",
+            # Video/meeting specific
+            "live stream", "livestream", "recorded meeting", "meeting video",
+            "council session", "board session", "official meeting"
+        )
+        
+    async def __aenter__(self):
+        """Async context manager entry."""
+        self.http_client = httpx.AsyncClient(
+            timeout=30.0,
+            follow_redirects=True,
+            headers={
+                "User-Agent": "OpenNavigator/1.0 (+https://github.com/getcommunityone/open-navigator)"
+            }
+        )
+        return self
+    
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit."""
+        if self.http_client:
+            await self.http_client.aclose()
+    
+    async def process(self, message: AgentMessage) -> List[AgentMessage]:
+        """
+        Process scraping commands.
+        
+        Args:
+            message: Command message with scraping targets
+            
+        Returns:
+            List of messages containing scraped data
+        """
+        self.update_status(AgentStatus.PROCESSING, "Scraping government meeting minutes")
+        
+        try:
+            command = message.payload.get("command")
+            
+            if command == "scrape":
+                targets = message.payload.get("targets", [])
+                date_range = message.payload.get("date_range", {})
+                
+                # Initialize HTTP client if not already done
+                if not self.http_client:
+                    async with self:
+                        documents = await self._scrape_targets(targets, date_range)
+                else:
+                    documents = await self._scrape_targets(targets, date_range)
+                
+                # Send scraped documents to parser
+                response = await self.send_message(
+                    AgentRole.PARSER,
+                    MessageType.DATA,
+                    {
+                        "workflow_id": message.payload.get("workflow_id"),
+                        "documents": documents,
+                        "count": len(documents)
+                    }
+                )
+                
+                self.log_success()
+                logger.info(f"Scraped {len(documents)} documents")
+                
+                return [response]
+            
+            return []
+            
+        except Exception as e:
+            self.log_failure(str(e))
+            error_msg = await self.send_message(
+                AgentRole.ORCHESTRATOR,
+                MessageType.ERROR,
+                {"error": str(e), "agent": self.agent_id}
+            )
+            return [error_msg]
+    
+    async def _scrape_targets(
+        self,
+        targets: List[Dict[str, Any]],
+        date_range: Dict[str, str]
+    ) -> List[Dict[str, Any]]:
+        """
+        Scrape multiple targets concurrently.
+        
+        Args:
+            targets: List of scraping targets
+            date_range: Date range for filtering meetings
+            
+        Returns:
+            List of scraped documents
+        """
+        tasks = []
+        
+        for target in targets:
+            platform = target.get("platform", "generic")
+            url = target.get("url", "")
+            
+            if platform == "legistar":
+                tasks.append(self._scrape_legistar(target, date_range))
+            elif platform == "granicus":
+                tasks.append(self._scrape_granicus(target, date_range))
+            elif platform == "suiteonemedia" or "suiteonemedia" in url.lower():
+                tasks.append(self._scrape_suiteonemedia(target, date_range))
+            elif platform == "eboard" or "eboardsolutions.com" in url.lower() or "simbli.eboardsolutions" in url.lower():
+                tasks.append(self._scrape_eboard(target, date_range))
+            elif platform == "youtube":
+                tasks.append(self._scrape_youtube_source(target))
+            elif platform == "facebook":
+                tasks.append(self._scrape_facebook_source(target))
+            else:
+                tasks.append(self._scrape_generic(target, date_range))
+        
+        # Execute all scraping tasks concurrently
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+        
+        # Flatten results and filter out errors
+        documents = []
+        for result in results:
+            if isinstance(result, Exception):
+                logger.error(f"Scraping error: {result}")
+            elif isinstance(result, list):
+                documents.extend(result)
+        
+        return documents
+
+    async def scrape_social_sources(
+        self,
+        municipality: str,
+        state: str,
+        seed_url: str,
+        max_sources: int = 8
+    ) -> List[Dict[str, Any]]:
+        """Discover and scrape YouTube/Facebook sources for a jurisdiction."""
+        social_documents: List[Dict[str, Any]] = []
+
+        homepage_url = await self._resolve_homepage_url(municipality, state, seed_url)
+        if not homepage_url:
+            logger.warning(f"Could not resolve homepage URL for social scraping: {municipality}, {state}")
+            return social_documents
+
+        logger.info(f"Discovering social sources from homepage: {homepage_url}")
+        social_urls = await self._discover_social_urls(homepage_url, municipality, state)
+
+        youtube_urls = list(dict.fromkeys(social_urls.get("youtube", [])))[:max_sources]
+        facebook_urls = list(dict.fromkeys(social_urls.get("facebook", [])))[:max_sources]
+
+        logger.info(
+            f"Social discovery for {municipality}: "
+            f"{len(youtube_urls)} YouTube, {len(facebook_urls)} Facebook"
+        )
+
+        tasks = []
+        for y_url in youtube_urls:
+            tasks.append(self._scrape_youtube_source({
+                "url": y_url,
+                "municipality": municipality,
+                "state": state,
+            }))
+        for f_url in facebook_urls:
+            tasks.append(self._scrape_facebook_source({
+                "url": f_url,
+                "municipality": municipality,
+                "state": state,
+            }))
+
+        if not tasks:
+            return social_documents
+
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+        for result in results:
+            if isinstance(result, Exception):
+                logger.warning(f"Social scraping error: {result}")
+                continue
+            if isinstance(result, list):
+                social_documents.extend(result)
+
+        return social_documents
+
+    async def _resolve_homepage_url(self, municipality: str, state: str, seed_url: str) -> str:
+        """Resolve an official website homepage used for social discovery."""
+        if seed_url and "suiteonemedia" not in seed_url.lower():
+            parsed = urlparse(seed_url)
+            return f"{parsed.scheme}://{parsed.netloc}" if parsed.scheme and parsed.netloc else seed_url
+
+        city = (municipality or "").lower().replace(" ", "").replace("'", "")
+        st = (state or "").lower()
+        candidates = [
+            f"https://www.{city}{st}.gov",
+            f"https://{city}{st}.gov",
+            f"https://www.cityof{city}.com",
+            f"https://www.{city}.gov",
+            f"https://www.{city}.com",
+            f"https://{city}.com",
+        ]
+
+        for candidate in candidates:
+            try:
+                resp = await self.http_client.get(candidate, timeout=8)
+                if resp.status_code < 400:
+                    parsed = urlparse(str(resp.url))
+                    return f"{parsed.scheme}://{parsed.netloc}"
+            except Exception:
+                continue
+
+        return ""
+
+    async def _discover_social_urls(self, homepage_url: str, municipality: str, state: str) -> Dict[str, List[str]]:
+        """Discover social media URLs from homepage and YouTube pattern matching."""
+        discovered = {"youtube": [], "facebook": []}
+
+        try:
+            from discovery.social_media_discovery import SocialMediaDiscovery
+
+            async with SocialMediaDiscovery() as discovery:
+                social = await discovery.discover_from_website(
+                    homepage_url=homepage_url,
+                    jurisdiction_name=municipality,
+                    state=state,
+                )
+                discovered["youtube"] = social.get("youtube", [])
+                discovered["facebook"] = social.get("facebook", [])
+        except Exception as err:
+            logger.debug(f"SocialMediaDiscovery unavailable/failed: {err}")
+
+        # Augment YouTube discovery using handle pattern search for better recall.
+        try:
+            from discovery.youtube_channel_discovery import YouTubeChannelDiscovery
+
+            async with YouTubeChannelDiscovery() as ydisc:
+                channels = await ydisc.discover_channels(
+                    city_name=municipality,
+                    state_code=state,
+                    homepage_url=homepage_url,
+                )
+                for channel in channels:
+                    url = channel.get("channel_url")
+                    if url:
+                        discovered["youtube"].append(url)
+        except Exception as err:
+            logger.debug(f"YouTubeChannelDiscovery unavailable/failed: {err}")
+
+        discovered["youtube"] = list(dict.fromkeys(discovered["youtube"]))
+        discovered["facebook"] = list(dict.fromkeys(discovered["facebook"]))
+        return discovered
+
+    def _is_policy_meeting_content(self, text: str) -> bool:
+        """Check if text content is related to policy or meetings."""
+        if not text:
+            return False
+        text_lower = text.lower()
+        return any(keyword in text_lower for keyword in self.policy_meeting_keywords)
+    
+    def _extract_youtube_video_metadata(self, html: str, video_id: str) -> Dict[str, str]:
+        """Extract title and description from YouTube video page HTML."""
+        metadata = {"title": "", "description": ""}
+        
+        try:
+            # Extract title from various possible patterns
+            title_match = re.search(r'"title":"([^"]+)"', html)
+            if title_match:
+                metadata["title"] = title_match.group(1)
+            else:
+                # Fallback to meta tags
+                title_match = re.search(r'<title>([^<]+)</title>', html)
+                if title_match:
+                    metadata["title"] = title_match.group(1).replace(" - YouTube", "")
+            
+            # Extract description
+            desc_match = re.search(r'"description":"([^"]+)"', html)
+            if desc_match:
+                # Unescape and limit description length
+                metadata["description"] = desc_match.group(1)[:500]
+        
+        except Exception as err:
+            logger.debug(f"Error extracting metadata for video {video_id}: {err}")
+        
+        return metadata
+
+    async def _scrape_youtube_source(self, target: Dict[str, Any]) -> List[Dict[str, Any]]:
+        """Scrape recent YouTube videos and transcripts from a channel URL, focusing on policy and meeting content."""
+        url = target.get("url", "")
+        municipality = target.get("municipality", "")
+        state = target.get("state", "")
+
+        documents: List[Dict[str, Any]] = []
+        if not url:
+            return documents
+
+        videos_url = url.rstrip("/") + "/videos"
+        try:
+            resp = await self.http_client.get(videos_url)
+            if resp.status_code >= 400:
+                resp = await self.http_client.get(url)
+            text = resp.text
+        except Exception as err:
+            logger.debug(f"Could not fetch YouTube page {url}: {err}")
+            return documents
+
+        video_ids = []
+        for vid in re.findall(r'watch\?v=([A-Za-z0-9_-]{11})', text):
+            if vid not in video_ids:
+                video_ids.append(vid)
+        
+        # Process more videos initially to filter for relevant content
+        video_ids = video_ids[: self.social_source_limit * 3]
+        
+        policy_videos = []
+        
+        for vid in video_ids:
+            video_url = f"https://www.youtube.com/watch?v={vid}"
+            
+            # Fetch video page to extract metadata
+            try:
+                video_resp = await self.http_client.get(video_url)
+                video_metadata = self._extract_youtube_video_metadata(video_resp.text, vid)
+                
+                # Filter: Only keep videos with policy/meeting-related titles or descriptions
+                if not self._is_policy_meeting_content(video_metadata["title"]) and \
+                   not self._is_policy_meeting_content(video_metadata["description"]):
+                    logger.debug(f"Skipping non-policy video: {video_metadata['title']}")
+                    continue
+                
+                logger.info(f"Found policy/meeting video: {video_metadata['title']}")
+                
+            except Exception as err:
+                logger.debug(f"Could not fetch metadata for video {vid}: {err}")
+                video_metadata = {"title": f"Video {vid}", "description": ""}
+            
+            # Fetch transcript
+            transcript_text = self._fetch_youtube_transcript(vid)
+            if not transcript_text:
+                logger.debug(f"No transcript available for video {vid}")
+                continue
+            
+            # Double-check transcript content for policy/meeting keywords
+            if not self._is_policy_meeting_content(transcript_text):
+                logger.debug(f"Transcript doesn't contain policy/meeting content: {vid}")
+                continue
+
+            doc_id = hashlib.md5(f"youtube-{municipality}-{vid}".encode()).hexdigest()
+            policy_videos.append(MeetingDocument(
+                document_id=doc_id,
+                source_url=video_url,
+                municipality=municipality,
+                state=state,
+                meeting_date=datetime.utcnow().isoformat(),
+                meeting_type="YouTube Video - Policy/Meeting",
+                title=video_metadata["title"] or f"YouTube Video {vid}",
+                content=transcript_text,
+                metadata={
+                    "platform": "youtube",
+                    "channel_url": url,
+                    "video_id": vid,
+                    "has_transcript": True,
+                    "description": video_metadata["description"],
+                    "filtered_for_policy": True,
+                }
+            ))
+            
+            # Limit to configured number of policy videos
+            if len(policy_videos) >= self.social_source_limit:
+                break
+            
+            # Rate limiting
+            await asyncio.sleep(0.5)
+
+        logger.info(f"Found {len(policy_videos)} policy/meeting videos from {url}")
+        return policy_videos
+
+    async def _scrape_facebook_source(self, target: Dict[str, Any]) -> List[Dict[str, Any]]:
+        """Scrape publicly accessible Facebook page/post text snippets, focusing on policy and meeting content."""
+        url = target.get("url", "")
+        municipality = target.get("municipality", "")
+        state = target.get("state", "")
+
+        documents: List[Dict[str, Any]] = []
+        if not url:
+            return documents
+
+        normalized = url.replace("www.facebook.com", "m.facebook.com")
+        try:
+            resp = await self.http_client.get(normalized)
+            if resp.status_code >= 400:
+                return documents
+            soup = BeautifulSoup(resp.content, "html.parser")
+        except Exception as err:
+            logger.debug(f"Could not fetch Facebook page {url}: {err}")
+            return documents
+
+        # Try to extract links to individual post pages first.
+        post_links: List[str] = []
+        for a in soup.find_all("a", href=True):
+            href = a["href"]
+            if "/posts/" in href or "/videos/" in href:
+                full = urljoin(normalized, href)
+                if full not in post_links:
+                    post_links.append(full)
+        post_links = post_links[: self.social_source_limit * 2]  # Check more posts to filter
+
+        # If direct post links are unavailable, use page text as fallback content.
+        if not post_links:
+            page_text = soup.get_text(" ", strip=True)
+            # Filter: Only use page content if it contains policy/meeting keywords
+            if len(page_text) > 200 and self._is_policy_meeting_content(page_text):
+                doc_id = hashlib.md5(f"facebook-page-{municipality}-{url}".encode()).hexdigest()
+                documents.append(MeetingDocument(
+                    document_id=doc_id,
+                    source_url=url,
+                    municipality=municipality,
+                    state=state,
+                    meeting_date=datetime.utcnow().isoformat(),
+                    meeting_type="Facebook Page - Policy/Meeting",
+                    title="Facebook Page Content (Policy-Related)",
+                    content=page_text[:8000],
+                    metadata={
+                        "platform": "facebook",
+                        "content_source": "page_fallback",
+                        "filtered_for_policy": True,
+                    }
+                ))
+            else:
+                logger.debug(f"Facebook page content doesn't contain policy/meeting keywords: {url}")
+            return documents
+
+        policy_posts = []
+        for post_url in post_links:
+            try:
+                p_resp = await self.http_client.get(post_url)
+                if p_resp.status_code >= 400:
+                    continue
+                p_soup = BeautifulSoup(p_resp.content, "html.parser")
+                post_text = p_soup.get_text(" ", strip=True)
+                if len(post_text) < 120:
+                    continue
+                
+                # Filter: Only keep posts that mention policy/meeting keywords
+                if not self._is_policy_meeting_content(post_text):
+                    logger.debug(f"Skipping non-policy Facebook post: {post_url[:80]}...")
+                    continue
+                
+                logger.info(f"Found policy/meeting Facebook post: {post_url[:80]}...")
+
+                doc_id = hashlib.md5(f"facebook-post-{municipality}-{post_url}".encode()).hexdigest()
+                policy_posts.append(MeetingDocument(
+                    document_id=doc_id,
+                    source_url=post_url,
+                    municipality=municipality,
+                    state=state,
+                    meeting_date=datetime.utcnow().isoformat(),
+                    meeting_type="Facebook Post - Policy/Meeting",
+                    title="Facebook Post (Policy-Related)",
+                    content=post_text[:8000],
+                    metadata={
+                        "platform": "facebook",
+                        "content_source": "post",
+                        "filtered_for_policy": True,
+                    }
+                ))
+                
+                # Limit to configured number of policy posts
+                if len(policy_posts) >= self.social_source_limit:
+                    break
+                    
+                # Rate limiting
+                await asyncio.sleep(0.5)
+                
+            except Exception as err:
+                logger.debug(f"Could not parse Facebook post {post_url}: {err}")
+
+        logger.info(f"Found {len(policy_posts)} policy/meeting Facebook posts from {url}")
+        return policy_posts
+
+    def _fetch_youtube_transcript(self, video_id: str) -> str:
+        """Return concatenated YouTube transcript text when available."""
+        if YouTubeTranscriptApi is None:
+            return ""
+
+        try:
+            transcript = YouTubeTranscriptApi.get_transcript(video_id, languages=["en"])
+            return " ".join(chunk.get("text", "") for chunk in transcript if chunk.get("text")).strip()
+        except Exception:
+            return ""
+    
+    async def _scrape_legistar(
+        self,
+        target: Dict[str, Any],
+        date_range: Dict[str, str]
+    ) -> List[Dict[str, Any]]:
+        """
+        Scrape meeting minutes from Legistar platform using the official API.
+        
+        Legistar provides a REST API at https://webapi.legistar.com/v1/{city}/
+        This is much more reliable than HTML scraping.
+        
+        Args:
+            target: Target configuration with 'url' and 'municipality'
+            date_range: Date range for filtering (optional)
+            
+        Returns:
+            List of meeting documents
+        """
+        base_url = target["url"]
+        municipality = target["municipality"]
+        state = target["state"]
+        
+        # Extract city slug from URL (e.g., "chicago" from "chicago.legistar.com")
+        parsed = urlparse(base_url)
+        hostname = parsed.hostname or ""
+        city_slug = hostname.split('.')[0] if '.' in hostname else municipality.lower().replace(' ', '')
+        
+        # Use the official Legistar API
+        api_base = f"https://webapi.legistar.com/v1/{city_slug}"
+        
+        documents = []
+        
+        try:
+            # Build OData filter for date range
+            params = {
+                "$top": 100,  # Limit to 100 most recent meetings
+                "$orderby": "EventDate desc"
+            }
+            
+            if date_range and "start" in date_range:
+                params["$filter"] = f"EventDate ge datetime'{date_range['start']}'"
+            
+            # Get events (meetings)
+            events_url = f"{api_base}/events"
+            logger.info(f"Fetching Legistar events from {events_url}")
+            
+            response = await self.http_client.get(events_url, params=params)
+            response.raise_for_status()
+            events = response.json()
+            
+            logger.info(f"Found {len(events)} events for {municipality}")
+            
+            # Process each event
+            for event in events[:50]:  # Limit to 50 meetings
+                event_id = event.get("EventId")
+                event_guid = event.get("EventGuid")
+                
+                if not event_id:
+                    continue
+                
+                # Get agenda items for this event
+                try:
+                    items_url = f"{api_base}/events/{event_id}/EventItems"
+                    items_response = await self.http_client.get(items_url, timeout=10)
+                    
+                    if items_response.status_code == 200:
+                        items = items_response.json()
+                        
+                        # Create document from event and items
+                        doc = self._create_legistar_document(
+                            event,
+                            items,
+                            municipality,
+                            state,
+                            base_url
+                        )
+                        
+                        if doc:
+                            documents.append(doc)
+                    
+                    # Rate limiting - be respectful
+                    await asyncio.sleep(0.3)
+                    
+                except Exception as item_error:
+                    logger.warning(f"Error fetching items for event {event_id}: {item_error}")
+                    continue
+        
+        except Exception as e:
+            logger.error(f"Error scraping Legistar API for {municipality}: {e}")
+        
+        return documents
+    
+    def _create_legistar_document(
+        self,
+        event: Dict[str, Any],
+        items: List[Dict[str, Any]],
+        municipality: str,
+        state: str,
+        base_url: str
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Create a meeting document from Legistar API data.
+        
+        Args:
+            event: Event data from API
+            items: Agenda items from API
+            municipality: Municipality name
+            state: State code
+            base_url: Base URL for constructing links
+            
+        Returns:
+            Meeting document dict or None
+        """
+        try:
+            event_id = event.get("EventId")
+            event_date = event.get("EventDate", "")
+            event_body = event.get("EventBodyName", "Unknown Body")
+            
+            # Combine agenda items into content
+            content_parts = [f"Meeting: {event_body}", f"Date: {event_date}", "\n=== AGENDA ===\n"]
+            
+            for item in items:
+                agenda_num = item.get("EventItemAgendaNumber", "")
+                title = item.get("EventItemTitle", "")
+                matter_file = item.get("EventItemMatterFile", "")
+                
+                if title:
+                    item_text = f"\n{agenda_num}. {title}"
+                    if matter_file:
+                        item_text += f" (File: {matter_file})"
+                    content_parts.append(item_text)
+            
+            content = "\n".join(content_parts)
+            
+            # Generate document ID
+            doc_id = hashlib.md5(
+                f"{municipality}-{state}-{event_id}".encode()
+            ).hexdigest()
+            
+            # Create meeting detail URL
+            parsed = urlparse(base_url)
+            hostname = parsed.hostname or base_url
+            meeting_url = f"https://{hostname}/MeetingDetail.aspx?ID={event_id}"
+            
+            return MeetingDocument(
+                document_id=doc_id,
+                source_url=meeting_url,
+                municipality=municipality,
+                state=state,
+                meeting_date=event_date,
+                meeting_type=event_body,
+                title=f"{event_body} - {event_date}",
+                content=content,
+                metadata={
+                    "event_id": event_id,
+                    "event_guid": event.get("EventGuid"),
+                    "event_time": event.get("EventTime"),
+                    "event_location": event.get("EventLocation"),
+                    "video_status": event.get("EventVideoStatus"),
+                    "agenda_status": event.get("EventAgendaStatusName"),
+                    "minutes_status": event.get("EventMinutesStatusName"),
+                    "item_count": len(items),
+                    "platform": "legistar_api"
+                }
+            )
+        
+        except Exception as e:
+            logger.error(f"Error creating document from Legistar data: {e}")
+            return None
+    
+    async def _scrape_granicus(
+        self,
+        target: Dict[str, Any],
+        date_range: Dict[str, str]
+    ) -> List[Dict[str, Any]]:
+        """
+        Scrape meeting minutes from Granicus platform.
+        
+        Args:
+            target: Target configuration
+            date_range: Date range for filtering
+            
+        Returns:
+            List of meeting documents
+        """
+        base_url = target["url"]
+        municipality = target["municipality"]
+        state = target["state"]
+        
+        documents = []
+        
+        try:
+            # Granicus often has an API endpoint
+            api_url = urljoin(base_url, "api/v1/meetings")
+            
+            response = await self.http_client.get(api_url)
+            response.raise_for_status()
+            
+            meetings_data = response.json()
+            
+            for meeting in meetings_data.get("meetings", [])[:50]:
+                meeting_id = meeting.get("id")
+                meeting_url = urljoin(base_url, f"meeting/{meeting_id}")
+                
+                if meeting_url in self.scraped_urls:
+                    continue
+                
+                doc = await self._scrape_meeting_page(
+                    meeting_url,
+                    municipality,
+                    state,
+                    meeting_data=meeting
+                )
+                
+                if doc:
+                    documents.append(doc)
+                    self.scraped_urls.add(meeting_url)
+                
+                await asyncio.sleep(0.5)
+        
+        except Exception as e:
+            logger.error(f"Error scraping Granicus {base_url}: {e}")
+        
+        return documents
+
+    async def _scrape_suiteonemedia(
+        self,
+        target: Dict[str, Any],
+        date_range: Dict[str, str]
+    ) -> List[Dict[str, Any]]:
+        """
+        Scrape meeting events from a SuiteOne Media portal.
+
+        Strategy:
+        1. Fetch the portal homepage — it renders ALL current-year events as
+           /event/?id=XXXX anchor links.
+          2. Parse each <tr> in the eventTable to get: event ID, title, date,
+              agenda/minutes PDF links, and whether a media recording exists.
+          3. For events with media (or missing title/date), fetch the event page
+              to extract the S3 MP4 video recording URL from jwplayer setup.
+          4. Download PDFs for text extraction.
+          5. Extend backwards through historical event IDs when max_events > homepage count.
+
+        Parameters via target dict:
+          max_events  - maximum events to process (default 500, 0 = unlimited)
+          start_year  - only include events on/after this year (0 = all)
+                  fetch_videos - whether to fetch event pages for S3 video URLs (default True)
+        """
+        url = target["url"]
+        municipality = target.get("municipality", "")
+        state = target.get("state", "")
+        max_events: int = int(target.get("max_events", 500))
+        start_year: int = int(target.get("start_year", 0))
+        fetch_videos: bool = bool(target.get("fetch_videos", True))
+
+        parsed = urlparse(url)
+        base_url = f"{parsed.scheme}://{parsed.netloc}"
+
+        documents: List[Dict[str, Any]] = []
+
+        try:
+            # ---- Step 1: fetch homepage and parse event table rows ----
+            logger.info(f"Fetching SuiteOne homepage: {base_url}/Web/Home.aspx")
+            home_resp = await self.http_client.get(f"{base_url}/Web/Home.aspx")
+            home_resp.raise_for_status()
+            home_soup = BeautifulSoup(home_resp.content, "html.parser")
+
+            # Each <tr> in an eventTable contains: event link, agenda/minutes PDF links, date text
+            events: list[dict] = []
+            seen_event_ids: set[int] = set()
+
+            for table in home_soup.find_all("table", class_=re.compile("eventTable", re.I)):
+                for tr in table.find_all("tr"):
+                    row_links = [(a["href"], a.get_text(" ", strip=True)) for a in tr.find_all("a", href=True)]
+                    row_text = tr.get_text(" ", strip=True)
+
+                    event_id = None
+                    event_title = ""
+                    agenda_url = ""
+                    minutes_url = ""
+                    has_media = False
+
+                    for href, text in row_links:
+                        m = re.match(r'/event/\?id=(\d+)', href)
+                        if m:
+                            eid = int(m.group(1))
+                            if event_id is None:
+                                event_id = eid
+                                event_title = re.sub(r'\(opens in new window\)', '', text).strip()
+                        elif "getagendafile" in href.lower():
+                            agenda_url = self._normalize_document_url(urljoin(base_url, href))
+                        elif "getminutesfile" in href.lower():
+                            minutes_url = self._normalize_document_url(urljoin(base_url, href))
+                        if "media" in text.lower():
+                            has_media = True
+
+                    if event_id is None or event_id in seen_event_ids:
+                        continue
+                    seen_event_ids.add(event_id)
+
+                    date_m = re.search(
+                        r'((?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\w*'
+                        r'\s+\d{1,2},?\s*\d{4}(?:\s*\|\s*\d{2}:\d{2}\s*[AP]M)?)',
+                        row_text, re.I
+                    )
+                    meeting_date = date_m.group(1).strip() if date_m else ""
+
+                    year_m = re.search(r'\b(20\d{2})\b', meeting_date)
+                    if start_year and year_m and int(year_m.group(1)) < start_year:
+                        continue
+
+                    events.append({
+                        "id": event_id,
+                        "title": event_title,
+                        "date": meeting_date,
+                        "agenda_url": agenda_url,
+                        "minutes_url": minutes_url,
+                        "has_media": has_media,
+                    })
+
+            logger.info(
+                f"Parsed {len(events)} events from SuiteOne homepage table "
+                f"({len([e for e in events if e['agenda_url']])} with agenda, "
+                f"{len([e for e in events if e['minutes_url']])} with minutes, "
+                f"{len([e for e in events if e['has_media']])} with media)"
+            )
+
+            # ---- Step 2: extend with historical events if needed ----
+            if events and (max_events == 0 or max_events > len(events)):
+                lowest_id = min(e["id"] for e in events)
+                logger.info(f"Probing historical events below ID {lowest_id}")
+                for eid in range(lowest_id - 1, max(1, lowest_id - 5000), -1):
+                    if eid not in seen_event_ids:
+                        seen_event_ids.add(eid)
+                        events.append({
+                            "id": eid, "title": "", "date": "", "agenda_url": "",
+                            "minutes_url": "", "has_media": True,
+                        })
+                logger.info(f"Expanded to {len(events)} total events (including historical)")
+
+            events.sort(key=lambda e: e["id"], reverse=True)
+            if max_events > 0:
+                events = events[:max_events]
+
+            logger.info(f"Processing {len(events)} SuiteOne events for {municipality}")
+
+            # ---- Step 3 & 4: for each event, fetch video URL + download PDFs ----
+            for i, ev in enumerate(events):
+                eid = ev["id"]
+                event_url = f"{base_url}/event/?id={eid}"
+
+                meeting_date = ev["date"]
+                meeting_title = ev["title"]
+                meeting_type = re.sub(r'^\d+:\d+\s*[ap]\.m\.\s*', '', meeting_title, flags=re.I).strip() or "Meeting"
+                video_url = ""
+
+                # Fetch event page when: has media flag, or missing title/date
+                if ev["has_media"] or not meeting_title or not meeting_date:
+                    try:
+                        ev_resp = await self.http_client.get(event_url)
+                        if ev_resp.status_code == 404:
+                            continue
+                        ev_resp.raise_for_status()
+                        ev_text = ev_resp.text
+                        ev_soup = BeautifulSoup(ev_resp.content, "html.parser")
+
+                        title_tag = ev_soup.find("title")
+                        if title_tag:
+                            page_title = title_tag.get_text(strip=True).replace("Meeting:", "").strip()
+                            if "upcoming meetings" in page_title.lower():
+                                continue
+                            if not meeting_title:
+                                meeting_title = page_title
+                                meeting_type = re.sub(r'^\d+:\d+\s*[ap]\.m\.\s*', '', meeting_title, flags=re.I).strip() or "Meeting"
+
+                        if not meeting_date:
+                            dm = re.search(
+                                r'((?:January|February|March|April|May|June|July|August|'
+                                r'September|October|November|December)\s+\d{1,2},?\s*\d{4})',
+                                ev_text
+                            )
+                            meeting_date = dm.group(1) if dm else ""
+
+                        year_m = re.search(r'\b(20\d{2})\b', meeting_date)
+                        if start_year and year_m and int(year_m.group(1)) < start_year:
+                            continue
+
+                        if fetch_videos:
+                            src_m = re.search(r"var src\s*=\s*'([^']+)';", ev_text)
+                            if src_m and src_m.group(1):
+                                video_url = src_m.group(1)
+
+                        for a in ev_soup.find_all("a", href=True):
+                            href = a["href"]
+                            full = self._normalize_document_url(urljoin(base_url, href))
+                            if "getagendafile" in full.lower() and not ev["agenda_url"]:
+                                ev["agenda_url"] = full
+                            elif "getminutesfile" in full.lower() and not ev["minutes_url"]:
+                                ev["minutes_url"] = full
+
+                        await asyncio.sleep(0.2)
+
+                    except Exception as fetch_err:
+                        logger.debug(f"Could not fetch event page {eid}: {fetch_err}")
+
+                doc_urls = [(ev["agenda_url"], "Agenda"), (ev["minutes_url"], "Minutes")]
+                produced = 0
+                for doc_url, doc_type in doc_urls:
+                    if not doc_url or doc_url in self.scraped_urls:
+                        continue
+                    doc = await self._scrape_document(
+                        url=doc_url,
+                        municipality=municipality,
+                        state=state,
+                        title=f"{meeting_title} — {doc_type}",
+                    )
+                    if doc:
+                        doc["meeting_date"] = meeting_date
+                        doc["meeting_type"] = meeting_type
+                        meta = doc.setdefault("metadata", {})
+                        meta["platform"] = "suiteonemedia"
+                        meta["event_id"] = eid
+                        meta["doc_type"] = doc_type.lower()
+                        if video_url:
+                            meta["video_url"] = video_url
+                        documents.append(doc)
+                        self.scraped_urls.add(doc_url)
+                        produced += 1
+
+                if produced == 0 and meeting_title and "upcoming meetings" not in meeting_title.lower():
+                    doc_id = hashlib.md5(event_url.encode()).hexdigest()
+                    documents.append(MeetingDocument(
+                        document_id=doc_id,
+                        source_url=event_url,
+                        municipality=municipality,
+                        state=state,
+                        meeting_date=meeting_date or datetime.utcnow().isoformat(),
+                        meeting_type=meeting_type,
+                        title=meeting_title,
+                        content="",
+                        metadata={
+                            "platform": "suiteonemedia",
+                            "event_id": eid,
+                            "video_url": video_url,
+                            "has_pdf": False,
+                        }
+                    ))
+
+                if (i + 1) % 50 == 0:
+                    logger.info(
+                        f"  SuiteOne: {i+1}/{len(events)} events processed, "
+                        f"{len(documents)} docs so far"
+                    )
+
+                await asyncio.sleep(0.3)
+
+        except Exception as e:
+            logger.error(f"Error scraping SuiteOne portal {url}: {e}")
+
+        logger.info(f"SuiteOne scrape complete: {len(documents)} documents from {municipality}")
+        return documents
+
+    async def _scrape_eboard_undetected(
+        self,
+        target: Dict[str, Any],
+        date_range: Dict[str, str]
+    ) -> List[Dict[str, Any]]:
+        """
+        Scrape eBoard using undetected-chromedriver to bypass Incapsula automatically.
+        
+        This method uses undetected-chromedriver which patches Selenium to avoid detection:
+        - Removes navigator.webdriver flag
+        - Uses real Chrome binary
+        - Randomizes browser fingerprints
+        
+        Args:
+            target: Scraping target with URL, municipality, state
+            date_range: Date range for filtering meetings
+            
+        Returns:
+            List of meeting documents
+        """
+        url = target.get("url", "")
+        municipality = target.get("municipality", "Unknown")
+        state = target.get("state", "")
+        
+        import undetected_chromedriver as uc
+        from selenium.webdriver.common.by import By
+        from selenium.webdriver.support.ui import WebDriverWait
+        from selenium.webdriver.support import expected_conditions as EC
+        import time
+        import random
+        import re
+        from pathlib import Path
+        
+        # Extract school ID from URL
+        school_id_match = re.search(r'[?&]s=(\d+)', url, re.IGNORECASE)
+        school_id = school_id_match.group(1) if school_id_match else None
+        
+        if not school_id:
+            logger.error(f"Could not extract school ID from URL: {url}")
+            return []
+        
+        base_url = "https://simbli.eboardsolutions.com"
+        meetings_url = f"{base_url}/SB_Meetings/SB_MeetingListing.aspx?S={school_id}"
+        
+        logger.info(f"Using undetected-chromedriver for: {meetings_url}")
+        
+        documents = []
+        driver = None
+        
+        try:
+            # Create undetected Chrome instance
+            options = uc.ChromeOptions()
+            # Try headless mode (may work better with newer Chrome)
+            options.add_argument('--headless=new')  # New headless mode
+            options.add_argument('--no-sandbox')
+            options.add_argument('--disable-dev-shm-usage')
+            options.add_argument('--disable-blink-features=AutomationControlled')
+            options.add_argument('--window-size=1920,1080')
+            
+            logger.info("Launching Chrome with anti-detection patches...")
+            
+            # Let undetected-chromedriver auto-download matching ChromeDriver
+            # Specify version_main to match system Chrome (147)
+            try:
+                driver = uc.Chrome(
+                    options=options,
+                    version_main=147,  # Match Chromium version
+                    use_subprocess=True
+                )
+            except Exception as e:
+                logger.warning(f"Headless mode failed: {e}, trying with visible browser...")
+                # Try without headless as fallback
+                options = uc.ChromeOptions()
+                options.add_argument('--no-sandbox')
+                options.add_argument('--disable-dev-shm-usage')
+                driver = uc.Chrome(options=options, version_main=147, use_subprocess=True)
+            
+            # Navigate to meetings page
+            logger.info("Loading meeting listing page...")
+            driver.get(meetings_url)
+            
+            # Wait for Incapsula challenge to complete
+            wait_time = random.uniform(6.0, 9.0)
+            logger.info(f"Waiting {wait_time:.1f}s for Incapsula challenge...")
+            time.sleep(wait_time)
+            
+            # Check if we bypassed Incapsula
+            page_source = driver.page_source
+            
+            if 'Incapsula incident ID' in page_source or ('Incapsula' in page_source and len(page_source) < 10000):
+                logger.error(f"Still blocked by Incapsula ({len(page_source)} bytes)")
+                logger.error("Incapsula detection triggered despite undetected-chromedriver")
+                raise Exception("Incapsula block detected")
+            
+            logger.success(f"✓ Bypassed Incapsula! Page size: {len(page_source)} bytes")
+            
+            # Parse the page
+            soup = BeautifulSoup(page_source, 'html.parser')
+            
+            # Extract meeting links
+            meeting_links = []
+            
+            # Look for links with MID parameter or PDFs
+            for link in soup.find_all('a', href=True):
+                href = link.get('href', '')
+                text = link.get_text().strip()
+                
+                if 'MID=' in href.upper() or 'meetingdetail' in href.lower():
+                    full_url = urljoin(base_url, href)
+                    meeting_links.append({
+                        'url': full_url,
+                        'text': text,
+                        'type': 'meeting'
+                    })
+                elif href.lower().endswith('.pdf') and any(word in text.lower() for word in ['agenda', 'minutes', 'packet', 'meeting']):
+                    full_url = urljoin(base_url, href)
+                    meeting_links.append({
+                        'url': full_url,
+                        'text': text,
+                        'type': 'pdf'
+                    })
+            
+            logger.info(f"Found {len(meeting_links)} meeting/document links")
+            
+            # If no links found, try waiting for JavaScript-rendered content
+            if len(meeting_links) == 0:
+                logger.warning("No links found initially, waiting for JavaScript...")
+                try:
+                    WebDriverWait(driver, 10).until(
+                        EC.presence_of_element_located((By.TAG_NAME, "a"))
+                    )
+                    time.sleep(3)
+                    
+                    # Re-parse
+                    page_source = driver.page_source
+                    soup = BeautifulSoup(page_source, 'html.parser')
+                    
+                    for link in soup.find_all('a', href=True):
+                        href = link.get('href', '')
+                        text = link.get_text().strip()
+                        
+                        if 'MID=' in href.upper() or href.lower().endswith('.pdf'):
+                            full_url = urljoin(base_url, href)
+                            meeting_links.append({
+                                'url': full_url,
+                                'text': text,
+                                'type': 'pdf' if href.lower().endswith('.pdf') else 'meeting'
+                            })
+                    
+                    logger.info(f"After JS wait: {len(meeting_links)} links")
+                except Exception as e:
+                    logger.warning(f"JS content wait failed: {e}")
+            
+            # Save page HTML for debugging
+            debug_file = Path("/tmp/eboard_meeting_list_undetected.html")
+            with open(debug_file, 'w', encoding='utf-8') as f:
+                f.write(page_source)
+            logger.info(f"Saved page HTML to {debug_file} for debugging")
+            
+            # Process meeting links (limit to prevent overwhelming)
+            for idx, meeting_info in enumerate(meeting_links[:50]):
+                if idx > 0 and idx % 10 == 0:
+                    logger.info(f"Progress: {idx}/{min(50, len(meeting_links))}")
+                
+                # Human-like delay
+                time.sleep(random.uniform(2.0, 4.0))
+                
+                try:
+                    meeting_url = meeting_info['url']
+                    meeting_title = meeting_info['text']
+                    
+                    if meeting_info['type'] == 'pdf':
+                        # Record PDF link for later download
+                        logger.debug(f"  Found PDF: {meeting_title[:50]}")
+                        
+                        # Try to extract date from title
+                        meeting_date = datetime.now()
+                        try:
+                            from dateutil import parser as date_parser
+                            date_match = re.search(r'(\d{1,2}[-/]\d{1,2}[-/]\d{2,4})', meeting_title)
+                            if date_match:
+                                meeting_date = date_parser.parse(date_match.group(0))
+                        except:
+                            pass
+                        
+                        # Download and extract PDF content
+                        try:
+                            pdf_content = await self._scrape_pdf_document(meeting_url)
+                            if pdf_content and len(pdf_content.strip()) > 100:
+                                doc = MeetingDocument(
+                                    document_id=hashlib.md5(f"{meeting_url}{municipality}".encode()).hexdigest(),
+                                    source_url=meeting_url,
+                                    municipality=municipality,
+                                    state=state,
+                                    meeting_date=meeting_date,
+                                    meeting_type='Board Meeting',
+                                    title=meeting_title,
+                                    content=pdf_content[:50000],
+                                    metadata={
+                                        'platform': 'eboard',
+                                        'school_id': school_id,
+                                        'scraped_with': 'undetected_chromedriver'
+                                    }
+                                )
+                                documents.append(doc)
+                                logger.success(f"    ✓ Scraped PDF: {meeting_title[:50]}")
+                        except Exception as e:
+                            logger.error(f"    Error downloading PDF: {e}")
+                    
+                    else:
+                        # Navigate to meeting detail page
+                        logger.debug(f"  Loading meeting: {meeting_title[:50]}")
+                        driver.get(meeting_url)
+                        time.sleep(random.uniform(2.0, 4.0))
+                        
+                        meeting_soup = BeautifulSoup(driver.page_source, 'html.parser')
+                        
+                        # Extract meeting date
+                        meeting_date = datetime.now()
+                        try:
+                            from dateutil import parser as date_parser
+                            for elem in meeting_soup.find_all(['h1', 'h2', 'h3', 'div', 'span']):
+                                text = elem.get_text().strip()
+                                date_match = re.search(r'(\d{1,2}[-/]\d{1,2}[-/]\d{2,4})', text)
+                                if date_match:
+                                    meeting_date = date_parser.parse(date_match.group(0))
+                                    break
+                        except:
+                            pass
+                        
+                        # Find document links (PDFs)
+                        doc_links = []
+                        for link in meeting_soup.find_all('a', href=True):
+                            href = link.get('href', '')
+                            link_text = link.get_text().strip()
+                            
+                            if href.lower().endswith('.pdf') or any(word in link_text.lower() for word in ['agenda', 'minutes', 'packet']):
+                                doc_url = urljoin(base_url, href)
+                                doc_links.append({
+                                    'url': doc_url,
+                                    'text': link_text
+                                })
+                        
+                        logger.info(f"    Found {len(doc_links)} documents")
+                        
+                        # Download each document
+                        for doc_info in doc_links[:5]:
+                            try:
+                                doc_url = doc_info['url']
+                                doc_title = doc_info['text']
+                                
+                                if doc_url.lower().endswith('.pdf'):
+                                    doc_content = await self._scrape_pdf_document(doc_url)
+                                    
+                                    if doc_content and len(doc_content.strip()) > 100:
+                                        doc = MeetingDocument(
+                                            document_id=hashlib.md5(f"{doc_url}{municipality}".encode()).hexdigest(),
+                                            source_url=doc_url,
+                                            municipality=municipality,
+                                            state=state,
+                                            meeting_date=meeting_date,
+                                            meeting_type='Board Meeting',
+                                            title=doc_title or meeting_title,
+                                            content=doc_content[:50000],
+                                            metadata={
+                                                'platform': 'eboard',
+                                                'meeting_page': meeting_url,
+                                                'school_id': school_id,
+                                                'scraped_with': 'undetected_chromedriver'
+                                            }
+                                        )
+                                        documents.append(doc)
+                                        logger.success(f"      ✓ Scraped: {doc_title[:50]}")
+                            
+                            except Exception as e:
+                                logger.error(f"      Error scraping document: {e}")
+                
+                except Exception as e:
+                    logger.error(f"Error processing {meeting_info.get('text', 'unknown')}: {e}")
+                    continue
+            
+        except Exception as e:
+            logger.error(f"Error in undetected scraper: {e}")
+            import traceback
+            logger.error(traceback.format_exc())
+            raise  # Re-raise to trigger fallback
+        
+        finally:
+            if driver:
+                try:
+                    driver.quit()
+                except:
+                    pass
+        
+        logger.success(f"Undetected scraper complete: {len(documents)} documents")
+        return documents
+
+    async def _scrape_eboard(
+        self,
+        target: Dict[str, Any],
+        date_range: Dict[str, str]
+    ) -> List[Dict[str, Any]]:
+        """
+        Scrape eBoard Solutions platform (used by many school districts).
+        
+        eBoard uses ASP.NET with JavaScript and Incapsula bot protection.
+        This implementation uses undetected-chromedriver for automatic bypass.
+        
+        Bypass methods (in order):
+        1. Undetected ChromeDriver - automatic bot detection evasion
+        2. Playwright with manual cookies (fallback)
+        
+        Args:
+            target: Scraping target with URL, municipality, state
+            date_range: Date range for filtering meetings
+            
+        Returns:
+            List of meeting documents
+        """
+        url = target.get("url", "")
+        municipality = target.get("municipality", "Unknown")
+        state = target.get("state", "")
+        
+        logger.info(f"Scraping eBoard platform: {url} for {municipality}")
+        
+        # Try undetected-chromedriver first (automatic bypass)
+        try:
+            import undetected_chromedriver as uc
+            logger.info("Attempting with undetected-chromedriver (automatic bot evasion)")
+            return await self._scrape_eboard_undetected(target, date_range)
+        except ImportError:
+            logger.warning("undetected-chromedriver not available, falling back to Playwright")
+        except Exception as e:
+            logger.warning(f"Undetected ChromeDriver failed: {e}, falling back to Playwright")
+        
+        # Fallback to Playwright with cookies
+        logger.info("Using Playwright with manual cookies (if available)")
+        
+        documents = []
+        
+        try:
+            from playwright.async_api import async_playwright
+            from playwright_stealth import Stealth
+            import random
+            from pathlib import Path
+            
+            # Extract school ID from URL (S=xxxx parameter)
+            import re
+            school_id_match = re.search(r'[?&]s=(\d+)', url, re.IGNORECASE)
+            school_id = school_id_match.group(1) if school_id_match else None
+            
+            if not school_id:
+                logger.error(f"Could not extract school ID from URL: {url}")
+                return []
+            
+            # Target the Meeting Listing page directly (bypasses some Incapsula triggers)
+            base_url = "https://simbli.eboardsolutions.com"
+            meetings_url = f"{base_url}/SB_Meetings/SB_MeetingListing.aspx?S={school_id}"
+            
+            # Check for manual cookies file
+            cookie_file = Path("eboard_cookies.json")
+            cookies = None
+            if cookie_file.exists():
+                try:
+                    import json
+                    with open(cookie_file, 'r') as f:
+                        cookies = json.load(f)
+                    logger.success(f"✓ Loaded {len(cookies)} cookies from eboard_cookies.json")
+                    logger.info("Using manual session cookies to bypass Incapsula")
+                except Exception as e:
+                    logger.warning(f"Could not load cookies: {e}")
+            else:
+                logger.info("No cookie file found. Will attempt without cookies (may be blocked)")
+                logger.info(f"To bypass Incapsula: Create {cookie_file.absolute()}")
+                logger.info("See docs/EBOARD_MANUAL_DOWNLOAD.md for instructions")
+            
+            logger.info(f"Targeting Meeting Listing: {meetings_url}")
+            
+            async with async_playwright() as p:
+                # Launch browser with anti-detection settings
+                logger.info("Launching browser with stealth settings to bypass Incapsula")
+                browser = await p.chromium.launch(
+                    headless=True,  # Stealth makes headless work
+                    args=[
+                        '--disable-blink-features=AutomationControlled',
+                        '--disable-dev-shm-usage',
+                        '--no-sandbox'
+                    ]
+                )
+                
+                # CRITICAL: User-Agent must match the browser used to generate cookies
+                # If cookies were from Chrome 123, use Chrome 123 UA
+                user_agent = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36'
+                
+                context = await browser.new_context(
+                    viewport={'width': 1920, 'height': 1080},
+                    user_agent=user_agent,
+                    locale='en-US',
+                    timezone_id='America/Chicago',
+                    # Additional fingerprinting evasion
+                    geolocation={'latitude': 33.2098, 'longitude': -87.5692},  # Tuscaloosa, AL
+                    permissions=['geolocation']
+                )
+                
+                page = await context.new_page()
+                
+                # Apply stealth to bypass Incapsula fingerprinting
+                stealth = Stealth()
+                await stealth.apply_stealth_async(page)
+                logger.info("Stealth mode activated")
+                
+                # Inject cookies if available (CRITICAL for bypassing Incapsula)
+                if cookies:
+                    await context.add_cookies(cookies)
+                    logger.success("✓ Cookies injected into browser session")
+                
+                # Navigate to Meeting Listing
+                logger.info(f"Loading Meeting Listing page...")
+                try:
+                    # Simulate human behavior - move mouse before navigation
+                    await page.mouse.move(random.randint(100, 500), random.randint(100, 500))
+                    
+                    response = await page.goto(meetings_url, wait_until='networkidle', timeout=60000)
+                    logger.info(f"Response status: {response.status if response else 'No response'}")
+                except Exception as e:
+                    logger.warning(f"Navigation timeout/error: {e}, continuing anyway...")
+                
+                # Wait for Incapsula JavaScript challenge to complete
+                # CRITICAL: Use randomized delay (not flat sleep) to avoid pattern detection
+                wait_time = random.uniform(5.0, 7.0)
+                logger.info(f"Waiting {wait_time:.1f}s for Incapsula JavaScript challenge...")
+                await page.wait_for_timeout(int(wait_time * 1000))
+                
+                # Check if we got through
+                content = await page.content()
+                
+                # More sophisticated Incapsula detection
+                is_blocked = False
+                if len(content) < 5000:
+                    is_blocked = True
+                    logger.error(f"Still blocked by Incapsula (page too small: {len(content)} bytes)")
+                elif 'Incapsula incident ID' in content:
+                    is_blocked = True  
+                    logger.error(f"Still blocked by Incapsula (incident ID found)")
+                elif 'Request unsuccessful. Incapsula' in content:
+                    is_blocked = True
+                    logger.error(f"Still blocked by Incapsula (request unsuccessful message)")
+                elif '<title>Access Denied</title>' in content or '<title>Blocked</title>' in content:
+                    is_blocked = True
+                    logger.error(f"Still blocked by Incapsula (access denied title)")
+                
+                if is_blocked:
+                    logger.warning(f"Try running with headless=False or use manual session cookies")
+                    logger.info(f"See docs/EBOARD_MANUAL_DOWNLOAD.md for manual download guide")
+                    await browser.close()
+                    return []
+                
+                logger.success(f"✓ Bypassed Incapsula! Got {len(content)} bytes")
+                
+                # Save HTML for debugging
+                debug_file = Path("/tmp/eboard_success.html")
+                with open(debug_file, 'w', encoding='utf-8') as f:
+                    f.write(content)
+                logger.info(f"Saved successful page to {debug_file}")
+                
+                # Parse the page
+                soup = BeautifulSoup(content, 'html.parser')
+                
+                # Debug: Log all links found on page
+                all_links = soup.find_all('a', href=True)
+                logger.info(f"Total <a> tags with href found: {len(all_links)}")
+                if len(all_links) > 0:
+                    logger.info(f"Sample links (first 10):")
+                    for i, link in enumerate(all_links[:10]):
+                        href = link.get('href', '')[:100]
+                        text = link.get_text().strip()[:50]
+                        logger.info(f"  {i+1}. {text} -> {href}")
+                
+                # Extract meeting links - eBoard uses MID parameter
+                # Look for links containing "MID=" (Meeting ID)
+                meeting_links = []
+                
+                for link in soup.find_all('a', href=True):
+                    href = link.get('href', '')
+                    text = link.get_text().strip()
+                    
+                    # eBoard meeting detail links contain MID parameter
+                    if 'MID=' in href.upper() or 'meetingdetail' in href.lower():
+                        full_url = urljoin(base_url, href)
+                        meeting_links.append({
+                            'url': full_url,
+                            'text': text,
+                            'mid': re.search(r'MID=(\d+)', href, re.IGNORECASE).group(1) if re.search(r'MID=(\d+)', href, re.IGNORECASE) else None
+                        })
+                
+                # Also look for direct PDF links (agendas/minutes)
+                for link in soup.find_all('a', href=True):
+                    href = link.get('href', '')
+                    text = link.get_text().strip()
+                    
+                    if href.lower().endswith('.pdf') and any(word in text.lower() for word in ['agenda', 'minutes', 'packet']):
+                        full_url = urljoin(base_url, href)
+                        meeting_links.append({
+                            'url': full_url,
+                            'text': text,
+                            'type': 'pdf'
+                        })
+                
+                logger.info(f"Found {len(meeting_links)} meeting/document links")
+                
+                # Process each meeting (limit to prevent overwhelming)
+                for idx, meeting_info in enumerate(meeting_links[:50]):
+                    try:
+                        meeting_url = meeting_info['url']
+                        meeting_title = meeting_info['text']
+                        
+                        if idx > 0 and idx % 10 == 0:
+                            logger.info(f"  Progress: {idx}/{min(50, len(meeting_links))} meetings processed")
+                        
+                        # CRITICAL: Randomized rate limiting to prevent Advanced Mode trigger
+                        # Never use flat sleep - Incapsula detects patterns
+                        wait_time = random.uniform(3.0, 7.0)
+                        await asyncio.sleep(wait_time)
+                        
+                        # Simulate human mouse movement before each action
+                        await page.mouse.move(random.randint(200, 800), random.randint(200, 600))
+                        
+                        # Handle PDF links directly
+                        if meeting_info.get('type') == 'pdf':
+                            try:
+                                # Download PDF
+                                pdf_content = await self._scrape_pdf_document(meeting_url)
+                                
+                                if pdf_content and len(pdf_content.strip()) > 100:
+                                    # Extract date from title/text
+                                    meeting_date = None
+                                    try:
+                                        from dateutil import parser as date_parser
+                                        date_match = re.search(r'(\d{1,2}[-/]\d{1,2}[-/]\d{2,4})', meeting_title)
+                                        if not date_match:
+                                            date_match = re.search(r'(January|February|March|April|May|June|July|August|September|October|November|December)\s+\d{1,2},?\s+\d{4}', meeting_title, re.IGNORECASE)
+                                        
+                                        if date_match:
+                                            meeting_date = date_parser.parse(date_match.group(0))
+                                    except:
+                                        meeting_date = datetime.now()
+                                    
+                                    if not meeting_date:
+                                        meeting_date = datetime.now()
+                                    
+                                    document_id = hashlib.md5(f"{meeting_url}{municipality}".encode()).hexdigest()
+                                    
+                                    doc = MeetingDocument(
+                                        document_id=document_id,
+                                        source_url=meeting_url,
+                                        municipality=municipality,
+                                        state=state,
+                                        meeting_date=meeting_date,
+                                        meeting_type='Board Meeting',
+                                        title=meeting_title,
+                                        content=pdf_content[:50000],
+                                        metadata={
+                                            'platform': 'eboard',
+                                            'school_id': school_id,
+                                            'scraped_with': 'playwright_stealth'
+                                        }
+                                    )
+                                    
+                                    documents.append(doc)
+                                    logger.success(f"    ✓ Scraped PDF: {meeting_title[:50]}")
+                            
+                            except Exception as e:
+                                logger.error(f"    Error downloading PDF: {e}")
+                                continue
+                        
+                        # Handle meeting detail pages
+                        else:
+                            logger.debug(f"  Loading meeting detail: {meeting_title[:50]}")
+                            
+                            try:
+                                # Simulate clicking on link (human-like behavior)
+                                await page.mouse.move(random.randint(300, 700), random.randint(200, 500))
+                                await page.goto(meeting_url, wait_until='domcontentloaded', timeout=30000)
+                                
+                                # Random wait to appear human
+                                await page.wait_for_timeout(random.randint(1500, 3000))
+                                
+                                meeting_content = await page.content()
+                                meeting_soup = BeautifulSoup(meeting_content, 'html.parser')
+                                
+                                # Extract meeting date
+                                meeting_date = None
+                                for elem in meeting_soup.find_all(['h1', 'h2', 'h3', 'div', 'span']):
+                                    text = elem.get_text().strip()
+                                    date_match = re.search(r'(\d{1,2}[-/]\d{1,2}[-/]\d{2,4})', text)
+                                    if not date_match:
+                                        date_match = re.search(r'(January|February|March|April|May|June|July|August|September|October|November|December)\s+\d{1,2},?\s+\d{4}', text, re.IGNORECASE)
+                                    
+                                    if date_match:
+                                        try:
+                                            from dateutil import parser as date_parser
+                                            meeting_date = date_parser.parse(date_match.group(0))
+                                            break
+                                        except:
+                                            pass
+                                
+                                if not meeting_date:
+                                    meeting_date = datetime.now()
+                                
+                                # Find document links (PDFs)
+                                doc_links = []
+                                for link in meeting_soup.find_all('a', href=True):
+                                    href = link.get('href', '')
+                                    link_text = link.get_text().strip()
+                                    
+                                    if (href.lower().endswith('.pdf') or 
+                                        'agenda' in link_text.lower() or 
+                                        'minutes' in link_text.lower() or
+                                        'packet' in link_text.lower()):
+                                        
+                                        doc_url = urljoin(base_url, href)
+                                        doc_links.append({
+                                            'url': doc_url,
+                                            'text': link_text
+                                        })
+                                
+                                logger.info(f"    Found {len(doc_links)} documents for {meeting_title[:40]}")
+                                
+                                # Download each document
+                                for doc_info in doc_links[:5]:  # Limit per meeting
+                                    try:
+                                        doc_url = doc_info['url']
+                                        doc_title = doc_info['text']
+                                        
+                                        if doc_url.lower().endswith('.pdf'):
+                                            doc_content = await self._scrape_pdf_document(doc_url)
+                                            
+                                            if doc_content and len(doc_content.strip()) > 100:
+                                                document_id = hashlib.md5(f"{doc_url}{municipality}".encode()).hexdigest()
+                                                
+                                                doc = MeetingDocument(
+                                                    document_id=document_id,
+                                                    source_url=doc_url,
+                                                    municipality=municipality,
+                                                    state=state,
+                                                    meeting_date=meeting_date,
+                                                    meeting_type='Board Meeting',
+                                                    title=doc_title or meeting_title,
+                                                    content=doc_content[:50000],
+                                                    metadata={
+                                                        'platform': 'eboard',
+                                                        'meeting_page': meeting_url,
+                                                        'school_id': school_id,
+                                                        'meeting_id': meeting_info.get('mid'),
+                                                        'scraped_with': 'playwright_stealth'
+                                                    }
+                                                )
+                                                
+                                                documents.append(doc)
+                                                logger.success(f"      ✓ Scraped: {doc_title[:50]}")
+                                    
+                                    except Exception as e:
+                                        logger.error(f"      Error scraping document: {e}")
+                                        continue
+                            
+                            except Exception as e:
+                                logger.error(f"  Error processing meeting {meeting_title[:40]}: {e}")
+                                continue
+                    
+                    except Exception as e:
+                        logger.error(f"Error processing meeting link: {e}")
+                        continue
+                
+                # Close browser
+                await browser.close()
+        
+        except ImportError as e:
+            logger.error(f"Missing dependency: {e}")
+            logger.error("Install with: pip install playwright-stealth && playwright install chromium")
+            return []
+        except Exception as e:
+            logger.error(f"Error scraping eBoard {url}: {e}")
+            import traceback
+            logger.error(traceback.format_exc())
+        
+        logger.success(f"eBoard scrape complete: {len(documents)} documents from {municipality}")
+        return documents
+
+    async def _scrape_generic(
+        self,
+        target: Dict[str, Any],
+        date_range: Dict[str, str]
+    ) -> List[Dict[str, Any]]:
+        """
+        Scrape meeting minutes from generic municipal websites.
+        
+        Args:
+            target: Target configuration
+            date_range: Date range for filtering
+            
+        Returns:
+            List of meeting documents
+        """
+        url = target["url"]
+        municipality = target["municipality"]
+        state = target["state"]
+        
+        documents = []
+        
+        try:
+            response = await self.http_client.get(url)
+            response.raise_for_status()
+            
+            soup = BeautifulSoup(response.content, "html.parser")
+
+            candidate_documents = self._extract_document_candidates(
+                page_url=url,
+                html=response.text,
+                soup=soup
+            )
+
+            # Crawl a few likely meeting pages because many sites (including JS-heavy portals)
+            # keep document links off the landing page.
+            meeting_pages = self._extract_meeting_pages(page_url=url, soup=soup)
+            for meeting_page in meeting_pages[:8]:
+                try:
+                    page_response = await self.http_client.get(meeting_page)
+                    if page_response.status_code >= 400:
+                        continue
+
+                    page_soup = BeautifulSoup(page_response.content, "html.parser")
+                    page_candidates = self._extract_document_candidates(
+                        page_url=meeting_page,
+                        html=page_response.text,
+                        soup=page_soup
+                    )
+                    candidate_documents.extend(page_candidates)
+                    await asyncio.sleep(0.2)
+                except Exception as page_err:
+                    logger.debug(f"Could not scrape meeting page {meeting_page}: {page_err}")
+
+            # De-duplicate while preserving order
+            seen_urls = set()
+            deduped_candidates = []
+            for doc_url, doc_label in candidate_documents:
+                if doc_url not in seen_urls:
+                    seen_urls.add(doc_url)
+                    deduped_candidates.append((doc_url, doc_label))
+
+            for doc_url, doc_label in deduped_candidates[:50]:
+                if doc_url in self.scraped_urls:
+                    continue
+
+                # Prioritize meeting-related labels but still allow document URL heuristics.
+                label = (doc_label or "").lower()
+                if label and not any(keyword in label for keyword in self.meeting_keywords):
+                    if not any(keyword in doc_url.lower() for keyword in self.meeting_keywords):
+                        continue
+
+                doc = await self._scrape_document(
+                    url=doc_url,
+                    municipality=municipality,
+                    state=state,
+                    title=doc_label or "meeting document"
+                )
+
+                if doc:
+                    documents.append(doc)
+                    self.scraped_urls.add(doc_url)
+
+                await asyncio.sleep(0.2)
+        
+        except Exception as e:
+            logger.error(f"Error scraping generic site {url}: {e}")
+        
+        return documents
+
+    def _extract_document_candidates(
+        self,
+        page_url: str,
+        html: str,
+        soup: BeautifulSoup
+    ) -> List[tuple[str, str]]:
+        """Extract document URLs from anchors and script text."""
+        candidates: List[tuple[str, str]] = []
+
+        # Anchor/link extraction
+        for anchor in soup.find_all("a", href=True):
+            href = anchor.get("href", "")
+            if not href:
+                continue
+            full_url = urljoin(page_url, href)
+            full_url = self._normalize_document_url(full_url)
+            lowered = full_url.lower()
+            if any(ext in lowered for ext in self.document_extensions) or any(k in lowered for k in self.document_route_keywords):
+                text = anchor.get_text(" ", strip=True) or anchor.get("title", "") or "document"
+                candidates.append((full_url, text))
+
+        # Script extraction for JS-driven portals that embed links in JSON blobs.
+        url_pattern = r'(https?://[^"\'\s)]+\.(?:pdf|docx?|pptx?|xlsx?)(?:\?[^"\'\s)]*)?)'
+        rel_pattern = r'([\w/\-.]+\.(?:pdf|docx?|pptx?|xlsx?)(?:\?[^"\'\s)]*)?)'
+
+        for raw in re.findall(url_pattern, html, flags=re.IGNORECASE):
+            candidates.append((self._normalize_document_url(raw), "document"))
+
+        route_pattern = r'(["\'](?:/event/Get(?:Agenda|Minutes)File/[^"\']+)["\'])'
+        for raw in re.findall(route_pattern, html, flags=re.IGNORECASE):
+            cleaned = raw.strip("\"'")
+            candidates.append((self._normalize_document_url(urljoin(page_url, cleaned)), "document"))
+
+        for raw in re.findall(rel_pattern, html, flags=re.IGNORECASE):
+            if raw.startswith("http"):
+                continue
+            if raw.startswith("/") or "/" in raw:
+                candidates.append((self._normalize_document_url(urljoin(page_url, raw)), "document"))
+
+        return candidates
+
+    def _normalize_document_url(self, url: str) -> str:
+        """Clean common malformed URL artifacts found in embedded portal markup."""
+        normalized = url.strip()
+        normalized = normalized.replace(" %20?", "?")
+        normalized = normalized.replace("%20?", "?")
+        normalized = normalized.replace(" ?", "?")
+        return normalized
+
+    def _extract_meeting_pages(self, page_url: str, soup: BeautifulSoup) -> List[str]:
+        """Find likely meeting-related subpages to expand document discovery."""
+        pages = []
+        for anchor in soup.find_all("a", href=True):
+            href = anchor.get("href", "")
+            text = anchor.get_text(" ", strip=True).lower()
+            if not href:
+                continue
+
+            full_url = urljoin(page_url, href)
+            combined = f"{text} {full_url.lower()}"
+            if "/event/?id=" in full_url.lower() or any(keyword in combined for keyword in self.meeting_keywords):
+                pages.append(full_url)
+
+        seen = set()
+        deduped = []
+        for p in pages:
+            if p not in seen:
+                seen.add(p)
+                deduped.append(p)
+        return deduped
+    
+    async def _scrape_meeting_page(
+        self,
+        url: str,
+        municipality: str,
+        state: str,
+        meeting_data: Optional[Dict[str, Any]] = None
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Scrape a single meeting page.
+        
+        Args:
+            url: Meeting page URL
+            municipality: Municipality name
+            state: State code
+            meeting_data: Optional pre-fetched meeting data
+            
+        Returns:
+            Meeting document or None
+        """
+        try:
+            response = await self.http_client.get(url)
+            response.raise_for_status()
+            
+            soup = BeautifulSoup(response.content, "html.parser")
+            
+            # Extract meeting details (simplified - actual implementation would be more robust)
+            title = soup.find("h1") or soup.find("title")
+            title_text = title.get_text().strip() if title else "Untitled Meeting"
+            
+            # Extract main content
+            content_div = soup.find("div", class_="meeting-content") or soup.find("main")
+            content = content_div.get_text(separator="\n").strip() if content_div else ""
+            
+            # Generate document ID
+            doc_id = hashlib.md5(f"{url}{municipality}".encode()).hexdigest()
+            
+            document = MeetingDocument(
+                document_id=doc_id,
+                source_url=url,
+                municipality=municipality,
+                state=state,
+                meeting_date=datetime.utcnow(),  # Would parse from content
+                meeting_type="City Council",  # Would determine from content
+                title=title_text,
+                content=content,
+                metadata={"platform": "web", "raw_data": meeting_data}
+            )
+            
+            return document
+        
+        except Exception as e:
+            logger.error(f"Error scraping meeting page {url}: {e}")
+            return None
+    
+    async def _scrape_document(
+        self,
+        url: str,
+        municipality: str,
+        state: str,
+        title: str
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Download and extract text from a document URL.
+        
+        Args:
+            url: PDF URL
+            municipality: Municipality name
+            state: State code
+            title: Document title
+            
+        Returns:
+            Meeting document or None
+        """
+        try:
+            response = await self.http_client.get(url)
+            response.raise_for_status()
+            
+            content_type = (response.headers.get("content-type") or "").lower()
+            url_lower = url.lower()
+            is_pdf = ".pdf" in url_lower or "application/pdf" in content_type
+            is_image = any(ext in url_lower for ext in [".png", ".jpg", ".jpeg", ".tif", ".tiff"]) or content_type.startswith("image/")
+
+            content = "[Document content extraction unavailable]"
+            ocr_used = False
+            ocr_pages = 0
+
+            if is_pdf and PdfReader is not None:
+                try:
+                    reader = PdfReader(io.BytesIO(response.content))
+                    pages = []
+                    for page in reader.pages[:30]:
+                        pages.append(page.extract_text() or "")
+                    extracted = "\n".join(pages).strip()
+                    if extracted:
+                        content = extracted
+                    else:
+                        content = "[PDF has no extractable text]"
+                except Exception as parse_error:
+                    logger.debug(f"PDF parse failed for {url}: {parse_error}")
+                    content = "[PDF parsing failed]"
+
+            # OCR fallback for scanned/image-based PDFs.
+            if is_pdf and content in ["[PDF has no extractable text]", "[PDF parsing failed]"]:
+                ocr_text, ocr_pages = self._ocr_pdf_bytes(response.content)
+                if ocr_text:
+                    content = ocr_text
+                    ocr_used = True
+
+            # OCR for image documents.
+            if is_image and content == "[Document content extraction unavailable]":
+                image_text = self._ocr_image_bytes(response.content)
+                if image_text:
+                    content = image_text
+                    ocr_used = True
+                    ocr_pages = 1
+            
+            doc_id = hashlib.md5(f"{url}{municipality}".encode()).hexdigest()
+            
+            document = MeetingDocument(
+                document_id=doc_id,
+                source_url=url,
+                municipality=municipality,
+                state=state,
+                meeting_date=datetime.utcnow(),
+                meeting_type="Unknown",
+                title=title,
+                content=content,
+                metadata={
+                    "platform": "document",
+                    "file_size": len(response.content),
+                    "content_type": response.headers.get("content-type"),
+                    "is_pdf": is_pdf,
+                    "is_image": is_image,
+                    "ocr_used": ocr_used,
+                    "ocr_pages": ocr_pages,
+                    "text_extracted": content not in [
+                        "[Document content extraction unavailable]",
+                        "[PDF has no extractable text]",
+                        "[PDF parsing failed]"
+                    ]
+                }
+            )
+            
+            return document
+        
+        except Exception as e:
+            if isinstance(e, httpx.HTTPStatusError) and e.response.status_code == 404:
+                logger.debug(f"Document not found (404): {url}")
+            else:
+                logger.error(f"Error downloading document {url}: {e}")
+            return None
+
+    def _ocr_pdf_bytes(self, pdf_bytes: bytes) -> tuple[str, int]:
+        """OCR PDF pages when direct PDF text extraction fails."""
+        if pdfplumber is None or pytesseract is None:
+            return "", 0
+
+        try:
+            extracted_pages = []
+            with pdfplumber.open(io.BytesIO(pdf_bytes)) as pdf:
+                for page in pdf.pages[:self.ocr_max_pages]:
+                    try:
+                        image = page.to_image(resolution=200).original
+                        text = pytesseract.image_to_string(image).strip()
+                        if text:
+                            extracted_pages.append(text)
+                    except TesseractNotFoundError:
+                        if not self._ocr_missing_tesseract_warned:
+                            logger.warning("Tesseract binary not found. Install 'tesseract-ocr' to enable OCR.")
+                            self._ocr_missing_tesseract_warned = True
+                        return "", 0
+                    except Exception as page_err:
+                        logger.debug(f"OCR page failed: {page_err}")
+
+            if not extracted_pages:
+                return "", 0
+            return "\n\n".join(extracted_pages), len(extracted_pages)
+        except Exception as err:
+            logger.debug(f"OCR PDF fallback failed: {err}")
+            return "", 0
+
+    def _ocr_image_bytes(self, image_bytes: bytes) -> str:
+        """OCR text from image-based documents."""
+        if pytesseract is None or Image is None:
+            return ""
+
+        try:
+            image = Image.open(io.BytesIO(image_bytes))
+            return pytesseract.image_to_string(image).strip()
+        except TesseractNotFoundError:
+            if not self._ocr_missing_tesseract_warned:
+                logger.warning("Tesseract binary not found. Install 'tesseract-ocr' to enable OCR.")
+                self._ocr_missing_tesseract_warned = True
+            return ""
+        except Exception as err:
+            logger.debug(f"Image OCR failed: {err}")
+            return ""
+
+    async def _scrape_pdf_document(
+        self,
+        url: str,
+        municipality: str,
+        state: str,
+        title: str
+    ) -> Optional[Dict[str, Any]]:
+        """Backward-compatible wrapper for existing call sites."""
+        return await self._scrape_document(url, municipality, state, title)

agents/scraper_undetected.py

@@ -0,0 +1,261 @@
+"""
+Alternative eBoard scraper using undetected-chromedriver
+This bypasses Incapsula without manual cookies
+"""
+import asyncio
+import re
+from typing import Dict, Any, List
+from pathlib import Path
+from bs4 import BeautifulSoup
+from urllib.parse import urljoin
+from datetime import datetime
+import hashlib
+
+from loguru import logger
+
+
+class UndetectedEboardScraper:
+    """
+    Scrape eBoard using undetected-chromedriver to bypass Incapsula.
+    
+    This library patches Selenium ChromeDriver to avoid detection by:
+    - Removing Selenium markers from navigator.webdriver
+    - Randomizing browser fingerprints
+    - Using real Chrome instead of ChromeDriver
+    """
+    
+    async def scrape_eboard(
+        self,
+        url: str,
+        municipality: str,
+        state: str,
+        school_id: str = None
+    ) -> List[Dict[str, Any]]:
+        """
+        Scrape eBoard platform without manual cookies.
+        
+        Args:
+            url: eBoard URL
+            municipality: School district name
+            state: State code
+            school_id: Optional school ID (extracted from URL if not provided)
+        
+        Returns:
+            List of meeting documents
+        """
+        try:
+            import undetected_chromedriver as uc
+            from selenium.webdriver.common.by import By
+            from selenium.webdriver.support.ui import WebDriverWait
+            from selenium.webdriver.support import expected_conditions as EC
+            import time
+            import random
+        except ImportError:
+            logger.error("Missing undetected-chromedriver. Install: pip install undetected-chromedriver")
+            return []
+        
+        # Extract school ID
+        if not school_id:
+            match = re.search(r'[?&]s=(\d+)', url, re.IGNORECASE)
+            school_id = match.group(1) if match else None
+        
+        if not school_id:
+            logger.error(f"Could not extract school ID from URL: {url}")
+            return []
+        
+        base_url = "https://simbli.eboardsolutions.com"
+        meetings_url = f"{base_url}/SB_Meetings/SB_MeetingListing.aspx?S={school_id}"
+        
+        logger.info(f"Using undetected-chromedriver to bypass Incapsula")
+        logger.info(f"Target: {meetings_url}")
+        
+        documents = []
+        
+        try:
+            # Create undetected Chrome instance
+            options = uc.ChromeOptions()
+            # options.add_argument('--headless')  # Headless may still be detected
+            options.add_argument('--no-sandbox')
+            options.add_argument('--disable-dev-shm-usage')
+            options.add_argument('--disable-blink-features=AutomationControlled')
+            
+            # Create driver with version management
+            driver = uc.Chrome(options=options, version_main=None)
+            
+            logger.info("Chrome launched with anti-detection patches")
+            
+            # Navigate to meetings page
+            driver.get(meetings_url)
+            logger.info(f"Loaded page: {driver.title[:100]}")
+            
+            # Wait for Incapsula challenge to complete
+            # The challenge usually takes 3-5 seconds
+            wait_time = random.uniform(5.0, 8.0)
+            logger.info(f"Waiting {wait_time:.1f}s for Incapsula challenge...")
+            time.sleep(wait_time)
+            
+            # Check if we bypassed Incapsula
+            page_source = driver.page_source
+            
+            if 'Incapsula' in page_source and len(page_source) < 10000:
+                logger.error("Still blocked by Incapsula")
+                logger.warning("Try running with headless=False or use Option 2 (Residential Proxies)")
+                driver.quit()
+                return []
+            
+            logger.success(f"✓ Bypassed Incapsula! Page size: {len(page_source)} bytes")
+            
+            # Parse the page
+            soup = BeautifulSoup(page_source, 'html.parser')
+            
+            # Extract meeting links
+            meeting_links = []
+            
+            # Method 1: Look for MID parameter
+            for link in soup.find_all('a', href=True):
+                href = link.get('href', '')
+                text = link.get_text().strip()
+                
+                if 'MID=' in href.upper() or 'meetingdetail' in href.lower():
+                    full_url = urljoin(base_url, href)
+                    meeting_links.append({
+                        'url': full_url,
+                        'text': text,
+                        'type': 'meeting'
+                    })
+                elif href.lower().endswith('.pdf'):
+                    full_url = urljoin(base_url, href)
+                    meeting_links.append({
+                        'url': full_url,
+                        'text': text,
+                        'type': 'pdf'
+                    })
+            
+            logger.info(f"Found {len(meeting_links)} meeting/document links")
+            
+            # If no links found, try JavaScript execution
+            if len(meeting_links) == 0:
+                logger.warning("No links found in HTML, checking for JavaScript-rendered content...")
+                
+                # Wait for dynamic content
+                try:
+                    WebDriverWait(driver, 10).until(
+                        EC.presence_of_element_located((By.TAG_NAME, "a"))
+                    )
+                    time.sleep(3)  # Additional wait for JS
+                    
+                    # Re-parse
+                    page_source = driver.page_source
+                    soup = BeautifulSoup(page_source, 'html.parser')
+                    
+                    for link in soup.find_all('a', href=True):
+                        href = link.get('href', '')
+                        text = link.get_text().strip()
+                        
+                        if 'MID=' in href.upper() or href.lower().endswith('.pdf'):
+                            full_url = urljoin(base_url, href)
+                            meeting_links.append({
+                                'url': full_url,
+                                'text': text,
+                                'type': 'pdf' if href.lower().endswith('.pdf') else 'meeting'
+                            })
+                    
+                    logger.info(f"After JS wait: Found {len(meeting_links)} links")
+                except Exception as e:
+                    logger.warning(f"JS content wait failed: {e}")
+            
+            # Process meeting links (limit to prevent overwhelming)
+            for idx, meeting_info in enumerate(meeting_links[:50]):
+                if idx > 0 and idx % 10 == 0:
+                    logger.info(f"Progress: {idx}/{min(50, len(meeting_links))}")
+                
+                # Human-like delay
+                time.sleep(random.uniform(2.0, 5.0))
+                
+                try:
+                    meeting_url = meeting_info['url']
+                    meeting_title = meeting_info['text']
+                    
+                    if meeting_info['type'] == 'pdf':
+                        # Download PDF directly
+                        logger.debug(f"  Downloading PDF: {meeting_title[:50]}")
+                        # TODO: Implement PDF download
+                        # For now, just record the URL
+                        doc = {
+                            'document_id': hashlib.md5(f"{meeting_url}{municipality}".encode()).hexdigest(),
+                            'source_url': meeting_url,
+                            'municipality': municipality,
+                            'state': state,
+                            'meeting_date': datetime.now(),
+                            'meeting_type': 'Board Meeting',
+                            'title': meeting_title,
+                            'content': '',  # Would need PDF extraction
+                            'metadata': {
+                                'platform': 'eboard',
+                                'school_id': school_id,
+                                'scraped_with': 'undetected_chromedriver'
+                            }
+                        }
+                        documents.append(doc)
+                    else:
+                        # Navigate to meeting detail page
+                        logger.debug(f"  Loading meeting: {meeting_title[:50]}")
+                        driver.get(meeting_url)
+                        time.sleep(random.uniform(2.0, 4.0))
+                        
+                        meeting_soup = BeautifulSoup(driver.page_source, 'html.parser')
+                        
+                        # Extract PDFs from meeting page
+                        for link in meeting_soup.find_all('a', href=True):
+                            href = link.get('href', '')
+                            if href.lower().endswith('.pdf'):
+                                doc_url = urljoin(base_url, href)
+                                doc_title = link.get_text().strip()
+                                
+                                doc = {
+                                    'document_id': hashlib.md5(f"{doc_url}{municipality}".encode()).hexdigest(),
+                                    'source_url': doc_url,
+                                    'municipality': municipality,
+                                    'state': state,
+                                    'meeting_date': datetime.now(),
+                                    'meeting_type': 'Board Meeting',
+                                    'title': doc_title or meeting_title,
+                                    'content': '',
+                                    'metadata': {
+                                        'platform': 'eboard',
+                                        'meeting_page': meeting_url,
+                                        'school_id': school_id,
+                                        'scraped_with': 'undetected_chromedriver'
+                                    }
+                                }
+                                documents.append(doc)
+                                logger.success(f"    ✓ Found: {doc_title[:50]}")
+                
+                except Exception as e:
+                    logger.error(f"Error processing {meeting_info.get('text', 'unknown')}: {e}")
+                    continue
+            
+            driver.quit()
+            logger.success(f"Scraping complete: {len(documents)} documents")
+            return documents
+            
+        except Exception as e:
+            logger.error(f"Error in undetected scraper: {e}")
+            import traceback
+            logger.error(traceback.format_exc())
+            return []
+
+
+# Example usage
+async def main():
+    scraper = UndetectedEboardScraper()
+    docs = await scraper.scrape_eboard(
+        url="http://simbli.eboardsolutions.com/index.aspx?s=2088",
+        municipality="Tuscaloosa City Schools",
+        state="AL"
+    )
+    print(f"Scraped {len(docs)} documents")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

agents/sentiment.py

@@ -0,0 +1,381 @@
+"""
+Sentiment Analyzer Agent for determining policy stance and debate intensity.
+"""
+import asyncio
+from typing import List, Dict, Any, Optional
+from datetime import datetime
+from loguru import logger
+
+from agents.base import BaseAgent, AgentRole, AgentMessage, MessageType, AgentStatus
+
+
+class PolicyStance:
+    """Enumeration of policy stances."""
+    STRONGLY_SUPPORTIVE = "strongly_supportive"
+    SUPPORTIVE = "supportive"
+    NEUTRAL = "neutral"
+    OPPOSED = "opposed"
+    STRONGLY_OPPOSED = "strongly_opposed"
+    DEBATED = "debated"  # When there's active debate
+
+
+class DebateIntensity:
+    """Enumeration of debate intensity levels."""
+    NONE = "none"  # Passing mention
+    LOW = "low"  # Brief discussion
+    MODERATE = "moderate"  # Extended discussion
+    HIGH = "high"  # Heated debate with multiple viewpoints
+    CRITICAL = "critical"  # Vote imminent or major decision pending
+
+
+class SentimentAnalyzerAgent(BaseAgent):
+    """
+    Agent responsible for analyzing sentiment and policy stance.
+    
+    Determines:
+    - Overall stance toward oral health policies
+    - Intensity of debate/discussion
+    - Key arguments for and against
+    - Likelihood of policy action
+    - Advocacy opportunities
+    """
+    
+    def __init__(self, agent_id: str = "sentiment-001"):
+        """Initialize the sentiment analyzer agent."""
+        super().__init__(agent_id, AgentRole.SENTIMENT_ANALYZER)
+        self._initialize_indicators()
+    
+    def _initialize_indicators(self):
+        """Initialize sentiment and debate indicators."""
+        self.supportive_indicators = [
+            "approve", "support", "favor", "endorse", "recommend",
+            "beneficial", "important", "necessary", "implement",
+            "move forward", "proceed with"
+        ]
+        
+        self.opposition_indicators = [
+            "oppose", "against", "reject", "deny", "concerns about",
+            "problems with", "issues with", "delay", "postpone",
+            "table the motion", "reconsider"
+        ]
+        
+        self.debate_indicators = [
+            "discussion", "debate", "motion", "vote", "amendment",
+            "public comment", "testimony", "hearing", "concerns",
+            "questions about", "divided"
+        ]
+        
+        self.urgency_indicators = [
+            "urgent", "immediate", "deadline", "vote", "decision",
+            "approval needed", "time-sensitive", "pressing",
+            "second reading", "final vote"
+        ]
+    
+    async def process(self, message: AgentMessage) -> List[AgentMessage]:
+        """
+        Process sentiment analysis commands.
+        
+        Args:
+            message: Message containing classified documents
+            
+        Returns:
+            List of messages with sentiment analysis results
+        """
+        self.update_status(AgentStatus.PROCESSING, "Analyzing policy sentiment and debate")
+        
+        try:
+            documents = message.payload.get("documents", [])
+            
+            analyzed_documents = []
+            
+            for doc in documents:
+                analysis = await self._analyze_document(doc)
+                doc["sentiment_analysis"] = analysis
+                analyzed_documents.append(doc)
+            
+            # Identify advocacy opportunities
+            opportunities = self._identify_advocacy_opportunities(analyzed_documents)
+            
+            # Send to advocacy writer agent
+            response = await self.send_message(
+                AgentRole.ADVOCACY_WRITER,
+                MessageType.DATA,
+                {
+                    "workflow_id": message.payload.get("workflow_id"),
+                    "documents": analyzed_documents,
+                    "opportunities": opportunities,
+                    "count": len(analyzed_documents)
+                }
+            )
+            
+            self.log_success()
+            logger.info(
+                f"Analyzed sentiment for {len(analyzed_documents)} documents, "
+                f"found {len(opportunities)} advocacy opportunities"
+            )
+            
+            return [response]
+            
+        except Exception as e:
+            self.log_failure(str(e))
+            error_msg = await self.send_message(
+                AgentRole.ORCHESTRATOR,
+                MessageType.ERROR,
+                {"error": str(e), "agent": self.agent_id}
+            )
+            return [error_msg]
+    
+    async def _analyze_document(
+        self,
+        doc: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Analyze sentiment and policy stance for a document.
+        
+        Args:
+            doc: Document to analyze
+            
+        Returns:
+            Sentiment analysis results
+        """
+        text = self._get_analyzable_text(doc)
+        text_lower = text.lower()
+        
+        # Count sentiment indicators
+        support_score = sum(
+            1 for indicator in self.supportive_indicators
+            if indicator in text_lower
+        )
+        
+        opposition_score = sum(
+            1 for indicator in self.opposition_indicators
+            if indicator in text_lower
+        )
+        
+        debate_score = sum(
+            1 for indicator in self.debate_indicators
+            if indicator in text_lower
+        )
+        
+        urgency_score = sum(
+            1 for indicator in self.urgency_indicators
+            if indicator in text_lower
+        )
+        
+        # Determine policy stance
+        stance = self._determine_stance(support_score, opposition_score, debate_score)
+        
+        # Determine debate intensity
+        intensity = self._determine_intensity(debate_score, urgency_score, doc)
+        
+        # Extract key arguments
+        arguments = self._extract_arguments(doc, text_lower)
+        
+        # Calculate advocacy urgency
+        advocacy_urgency = self._calculate_advocacy_urgency(
+            stance, intensity, urgency_score
+        )
+        
+        analysis = {
+            "stance": stance,
+            "debate_intensity": intensity,
+            "support_score": support_score,
+            "opposition_score": opposition_score,
+            "debate_score": debate_score,
+            "urgency_score": urgency_score,
+            "advocacy_urgency": advocacy_urgency,
+            "key_arguments": arguments,
+            "analyzed_at": datetime.utcnow().isoformat()
+        }
+        
+        return analysis
+    
+    def _get_analyzable_text(self, doc: Dict[str, Any]) -> str:
+        """Extract text for sentiment analysis."""
+        parts = []
+        
+        # Prioritize excerpts from classification
+        for excerpt in doc.get("classification", {}).get("relevant_excerpts", []):
+            parts.append(excerpt.get("text", ""))
+        
+        # Add motions (highly relevant)
+        for motion in doc.get("motions", []):
+            parts.append(motion.get("text", ""))
+        
+        # Add votes
+        for vote in doc.get("votes", []):
+            parts.append(vote.get("result", ""))
+        
+        # Fallback to full text if needed
+        if not parts:
+            parts.append(doc.get("full_text", ""))
+        
+        return " ".join(parts)
+    
+    def _determine_stance(
+        self,
+        support_score: int,
+        opposition_score: int,
+        debate_score: int
+    ) -> str:
+        """Determine overall policy stance."""
+        if debate_score >= 3 and abs(support_score - opposition_score) <= 1:
+            return PolicyStance.DEBATED
+        
+        if support_score > opposition_score:
+            if support_score >= 3:
+                return PolicyStance.STRONGLY_SUPPORTIVE
+            else:
+                return PolicyStance.SUPPORTIVE
+        elif opposition_score > support_score:
+            if opposition_score >= 3:
+                return PolicyStance.STRONGLY_OPPOSED
+            else:
+                return PolicyStance.OPPOSED
+        else:
+            return PolicyStance.NEUTRAL
+    
+    def _determine_intensity(
+        self,
+        debate_score: int,
+        urgency_score: int,
+        doc: Dict[str, Any]
+    ) -> str:
+        """Determine debate intensity."""
+        # Check for votes or motions (indicates high intensity)
+        has_vote = len(doc.get("votes", [])) > 0
+        has_motion = len(doc.get("motions", [])) > 0
+        
+        if urgency_score >= 2 or (has_vote and has_motion):
+            return DebateIntensity.CRITICAL
+        elif debate_score >= 5 or has_vote or has_motion:
+            return DebateIntensity.HIGH
+        elif debate_score >= 3:
+            return DebateIntensity.MODERATE
+        elif debate_score >= 1:
+            return DebateIntensity.LOW
+        else:
+            return DebateIntensity.NONE
+    
+    def _extract_arguments(
+        self,
+        doc: Dict[str, Any],
+        text_lower: str
+    ) -> Dict[str, List[str]]:
+        """Extract key arguments for and against."""
+        arguments = {
+            "supporting": [],
+            "opposing": []
+        }
+        
+        # Extract from motions and discussion
+        for motion in doc.get("motions", []):
+            motion_text = motion.get("text", "").lower()
+            
+            if any(ind in motion_text for ind in self.supportive_indicators):
+                arguments["supporting"].append(motion.get("text", ""))
+            elif any(ind in motion_text for ind in self.opposition_indicators):
+                arguments["opposing"].append(motion.get("text", ""))
+        
+        return arguments
+    
+    def _calculate_advocacy_urgency(
+        self,
+        stance: str,
+        intensity: str,
+        urgency_score: int
+    ) -> str:
+        """
+        Calculate how urgent advocacy action is needed.
+        
+        Returns: "critical", "high", "medium", "low", or "none"
+        """
+        # Critical: Vote imminent and debated/opposed
+        if intensity == DebateIntensity.CRITICAL:
+            if stance in [PolicyStance.DEBATED, PolicyStance.OPPOSED, PolicyStance.STRONGLY_OPPOSED]:
+                return "critical"
+            return "high"
+        
+        # High: Active debate with opposition
+        if intensity == DebateIntensity.HIGH:
+            if stance in [PolicyStance.OPPOSED, PolicyStance.STRONGLY_OPPOSED]:
+                return "high"
+            elif stance == PolicyStance.DEBATED:
+                return "high"
+            return "medium"
+        
+        # Medium: Moderate discussion or emerging issue
+        if intensity == DebateIntensity.MODERATE:
+            return "medium"
+        
+        # Low: Early stage or general mention
+        if intensity == DebateIntensity.LOW:
+            return "low"
+        
+        return "none"
+    
+    def _identify_advocacy_opportunities(
+        self,
+        documents: List[Dict[str, Any]]
+    ) -> List[Dict[str, Any]]:
+        """
+        Identify advocacy opportunities across all analyzed documents.
+        
+        Args:
+            documents: All analyzed documents
+            
+        Returns:
+            List of advocacy opportunities
+        """
+        opportunities = []
+        
+        for doc in documents:
+            sentiment = doc.get("sentiment_analysis", {})
+            urgency = sentiment.get("advocacy_urgency")
+            
+            # Only flag high and critical urgency items
+            if urgency in ["critical", "high"]:
+                opportunity = {
+                    "document_id": doc["document_id"],
+                    "municipality": doc["municipality"],
+                    "state": doc["state"],
+                    "meeting_date": doc["meeting_date"],
+                    "source_url": doc["source_url"],
+                    "topic": doc["classification"]["primary_topic"],
+                    "stance": sentiment["stance"],
+                    "intensity": sentiment["debate_intensity"],
+                    "urgency": urgency,
+                    "key_excerpts": doc["classification"].get("relevant_excerpts", []),
+                    "recommended_action": self._recommend_action(sentiment, doc)
+                }
+                opportunities.append(opportunity)
+        
+        # Sort by urgency
+        urgency_order = {"critical": 0, "high": 1, "medium": 2, "low": 3}
+        opportunities.sort(key=lambda x: urgency_order.get(x["urgency"], 4))
+        
+        return opportunities
+    
+    def _recommend_action(
+        self,
+        sentiment: Dict[str, Any],
+        doc: Dict[str, Any]
+    ) -> str:
+        """Recommend advocacy action based on analysis."""
+        stance = sentiment.get("stance")
+        intensity = sentiment.get("debate_intensity")
+        
+        if intensity == DebateIntensity.CRITICAL:
+            if stance in [PolicyStance.OPPOSED, PolicyStance.STRONGLY_OPPOSED]:
+                return "URGENT: Contact officials immediately. Vote imminent."
+            elif stance == PolicyStance.DEBATED:
+                return "URGENT: Provide supporting testimony. Decision pending."
+        
+        if stance == PolicyStance.DEBATED:
+            return "Engage with stakeholders. Provide educational materials."
+        elif stance in [PolicyStance.OPPOSED, PolicyStance.STRONGLY_OPPOSED]:
+            return "Initiate dialogue with decision-makers. Address concerns."
+        elif stance == PolicyStance.NEUTRAL:
+            return "Introduce topic to agenda. Build awareness."
+        
+        return "Monitor situation. Prepare support materials."

api/__init__.py

@@ -0,0 +1,4 @@
+"""API module for the Oral Health Policy Pulse system."""
+from api.main import app
+
+__all__ = ["app"]

api/app.py

@@ -0,0 +1,711 @@
+"""
+FastAPI application optimized for Databricks Apps deployment.
+Serves React frontend and provides REST API for agent interactions.
+"""
+from typing import List, Dict, Any, Optional
+from datetime import datetime
+from pathlib import Path
+from fastapi import FastAPI, HTTPException, Query, BackgroundTasks
+from fastapi.responses import HTMLResponse, JSONResponse, FileResponse
+from fastapi.staticfiles import StaticFiles
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel, Field
+from loguru import logger
+import os
+
+from agents.orchestrator import OrchestratorAgent
+from pipeline.delta_lake import DeltaLakePipeline
+from config import settings
+
+# Initialize FastAPI app
+app = FastAPI(
+    title="Open Navigator",
+    description="AI-powered advocacy opportunity finder",
+    version="2.0.0",
+    docs_url="/api/docs",
+    redoc_url="/api/redoc",
+    openapi_url="/api/openapi.json"
+)
+
+# Add CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Initialize components
+orchestrator = OrchestratorAgent()
+pipeline = DeltaLakePipeline()
+
+# Pydantic models
+class WorkflowRequest(BaseModel):
+    """Request to start a new analysis workflow."""
+    targets: List[Dict[str, str]]
+    topics: Optional[List[str]] = None
+
+class OpportunityFilter(BaseModel):
+    """Filter criteria for advocacy opportunities."""
+    state: Optional[str] = None
+    topic: Optional[str] = None
+    urgency: Optional[str] = None
+    min_confidence: Optional[float] = 0.7
+
+
+# API Routes
+@app.get("/api/health")
+async def health_check():
+    """Health check endpoint."""
+    return {"status": "healthy", "timestamp": datetime.utcnow().isoformat()}
+
+
+@app.get("/api/dashboard")
+async def get_dashboard_stats():
+    """Get dashboard statistics and recent opportunities."""
+    try:
+        # Query Delta Lake for stats
+        stats = await pipeline.get_dashboard_stats()
+        return stats
+    except Exception as e:
+        logger.error(f"Dashboard stats error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/api/opportunities")
+async def get_opportunities(
+    state: Optional[str] = Query(None),
+    topic: Optional[str] = Query(None),
+    urgency: Optional[str] = Query(None),
+    limit: int = Query(100, le=1000)
+):
+    """Get advocacy opportunities with optional filters."""
+    try:
+        opportunities = await pipeline.query_opportunities(
+            state=state,
+            topic=topic,
+            urgency=urgency,
+            limit=limit
+        )
+        return {"opportunities": opportunities, "count": len(opportunities)}
+    except Exception as e:
+        logger.error(f"Query opportunities error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/api/documents")
+async def get_documents(
+    search: Optional[str] = Query(None),
+    page: int = Query(1, ge=1),
+    limit: int = Query(20, le=100)
+):
+    """Get analyzed documents with pagination."""
+    try:
+        offset = (page - 1) * limit
+        documents = await pipeline.query_documents(
+            search=search,
+            limit=limit,
+            offset=offset
+        )
+        total = await pipeline.count_documents(search=search)
+        return {
+            "documents": documents,
+            "page": page,
+            "limit": limit,
+            "total": total,
+            "total_pages": (total + limit - 1) // limit
+        }
+    except Exception as e:
+        logger.error(f"Query documents error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/api/search/")
+async def search_all(
+    q: str = Query(..., min_length=1, description="Search query"),
+    types: Optional[str] = Query("contacts,organizations,causes", description="Comma-separated types to search"),
+    state: Optional[str] = Query(None, description="Filter by state code (e.g. MA, AL)"),
+    limit: int = Query(10, ge=1, le=100),
+    page: int = Query(1, ge=1),
+    ntee_code: Optional[str] = Query(None, description="NTEE category code")
+):
+    """
+    Unified search across contacts, organizations, causes, and jurisdictions.
+    Returns results grouped by type with pagination.
+    """
+    try:
+        offset = (page - 1) * limit
+        search_types = [t.strip() for t in types.split(',') if t.strip()]
+        
+        # Initialize results structure
+        results = {
+            "contacts": [],
+            "organizations": [],
+            "causes": [],
+            "meetings": [],
+            "jurisdictions": []
+        }
+        
+        # Search logic (placeholder - implement actual search)
+        # For now, return mock results for demonstration
+        if "contacts" in search_types:
+            results["contacts"] = [
+                {
+                    "type": "contact",
+                    "title": f"Sample Contact matching '{q}'",
+                    "subtitle": "Government Official",
+                    "description": "Contact information for local official",
+                    "url": "/contact/1",
+                    "score": 0.9,
+                    "metadata": {"state": state or "MA"}
+                }
+            ]
+        
+        if "organizations" in search_types:
+            results["organizations"] = [
+                {
+                    "type": "organization",
+                    "title": f"Sample Organization matching '{q}'",
+                    "subtitle": "Nonprofit Organization",
+                    "description": "Community health organization",
+                    "url": "/org/1",
+                    "score": 0.85,
+                    "metadata": {"state": state or "MA", "ntee": ntee_code}
+                }
+            ]
+        
+        if "causes" in search_types:
+            results["causes"] = [
+                {
+                    "type": "cause",
+                    "title": f"Sample Cause matching '{q}'",
+                    "subtitle": "Health & Wellness",
+                    "description": "Advocacy for community health",
+                    "url": "/cause/1",
+                    "score": 0.8,
+                    "metadata": {}
+                }
+            ]
+        
+        # Calculate total results
+        total_results = sum(len(v) for v in results.values())
+        total_pages = max(1, (total_results + limit - 1) // limit)
+        
+        return {
+            "query": q,
+            "total_results": total_results,
+            "results": results,
+            "pagination": {
+                "page": page,
+                "limit": limit,
+                "offset": offset,
+                "total_pages": total_pages,
+                "has_next": page < total_pages,
+                "has_prev": page > 1
+            },
+            "filters": {
+                "state": state,
+                "ntee_code": ntee_code,
+                "types": search_types
+            }
+        }
+    except Exception as e:
+        logger.error(f"Search error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/api/workflow/start")
+async def start_workflow(request: WorkflowRequest, background_tasks: BackgroundTasks):
+    """Start a new analysis workflow."""
+    try:
+        workflow_id = f"workflow_{datetime.utcnow().timestamp()}"
+        
+        # Start workflow in background
+        background_tasks.add_task(
+            orchestrator.execute_pipeline,
+            workflow_id=workflow_id,
+            targets=request.targets,
+            topics=request.topics
+        )
+        
+        return {
+            "workflow_id": workflow_id,
+            "status": "started",
+            "message": "Workflow started successfully"
+        }
+    except Exception as e:
+        logger.error(f"Workflow start error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/api/workflow/{workflow_id}/status")
+async def get_workflow_status(workflow_id: str):
+    """Get status of a running workflow."""
+    try:
+        status = await orchestrator.get_workflow_status(workflow_id)
+        return status
+    except Exception as e:
+        logger.error(f"Workflow status error: {e}")
+        raise HTTPException(status_code=404, detail="Workflow not found")
+
+
+@app.post("/api/advocacy/email/{opportunity_id}")
+async def generate_advocacy_email(opportunity_id: str):
+    """Generate advocacy email for an opportunity."""
+    try:
+        opportunity = await pipeline.get_opportunity(opportunity_id)
+        if not opportunity:
+            raise HTTPException(status_code=404, detail="Opportunity not found")
+        
+        email_content = await orchestrator.generate_advocacy_email(opportunity)
+        return {"content": email_content}
+    except Exception as e:
+        logger.error(f"Generate email error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/api/settings")
+async def get_settings():
+    """Get current system settings."""
+    return {
+        "target_states": settings.target_states or [],
+        "policy_topics": settings.policy_topics,
+        "min_confidence": 0.7,
+        "email_notifications": False,
+        "notification_email": ""
+    }
+
+
+@app.put("/api/settings")
+async def update_settings(new_settings: Dict[str, Any]):
+    """Update system settings."""
+    try:
+        # In production, this would update configuration in Unity Catalog
+        logger.info(f"Settings update requested: {new_settings}")
+        return {"message": "Settings updated successfully"}
+    except Exception as e:
+        logger.error(f"Settings update error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/api/agents/status")
+async def get_agents_status():
+    """Get status of all agents."""
+    try:
+        return {
+            "agents": [
+                {"name": "Scraper", "status": "active", "uptime": "24h"},
+                {"name": "Classifier", "status": "active", "uptime": "24h"},
+                {"name": "Sentiment Analyzer", "status": "active", "uptime": "24h"},
+                {"name": "Advocacy Writer", "status": "active", "uptime": "24h"}
+            ]
+        }
+    except Exception as e:
+        logger.error(f"Agent status error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/api/nonprofits")
+async def search_nonprofits(
+    location: str = Query("Tuscaloosa, AL", description="City, State format"),
+    keyword: Optional[str] = Query(None, description="Service keyword (e.g., 'dental', 'health')"),
+    state: Optional[str] = Query(None, description="2-letter state code (e.g., 'AL')"),
+    ntee_code: Optional[str] = Query(None, description="NTEE code (e.g., 'E' for health)"),
+    source: Optional[str] = Query(None, description="Data source: 'propublica', 'everyorg', 'all'")
+):
+    """
+    Search for nonprofits using free open data APIs.
+    
+    Integrates data from:
+    - ProPublica Nonprofit Explorer (financial data, NTEE codes)
+    - Every.org (mission statements, logos)
+    - IRS TEOS (official tax-exempt status)
+    
+    Example: /api/nonprofits?location=Tuscaloosa,AL&keyword=dental&ntee_code=E
+    """
+    try:
+        from discovery.nonprofit_discovery import NonprofitDiscovery
+        
+        discovery = NonprofitDiscovery()
+        results = []
+        
+        # Parse location for state/city
+        location_parts = location.split(',')
+        city = location_parts[0].strip() if len(location_parts) > 0 else None
+        state_from_location = location_parts[1].strip() if len(location_parts) > 1 else None
+        state_code = state or state_from_location or "AL"
+        
+        # Determine which sources to query
+        sources_to_query = ['propublica', 'everyorg'] if source == 'all' or not source else [source]
+        
+        # Query ProPublica
+        if 'propublica' in sources_to_query:
+            try:
+                propublica_results = discovery.search_propublica(
+                    state=state_code,
+                    city=city,
+                    ntee_code=ntee_code
+                )
+                results.extend(propublica_results)
+                logger.info(f"ProPublica: Found {len(propublica_results)} organizations")
+            except Exception as e:
+                logger.warning(f"ProPublica search failed: {e}")
+        
+        # Query Every.org
+        if 'everyorg' in sources_to_query:
+            try:
+                causes = []
+                if keyword:
+                    # Map keywords to causes
+                    keyword_lower = keyword.lower()
+                    if 'health' in keyword_lower or 'dental' in keyword_lower or 'medical' in keyword_lower:
+                        causes.append('health')
+                    if 'education' in keyword_lower or 'school' in keyword_lower:
+                        causes.append('education')
+                
+                everyorg_results = discovery.search_everyorg(
+                    location=location,
+                    causes=causes if causes else None
+                )
+                results.extend(everyorg_results)
+                logger.info(f"Every.org: Found {len(everyorg_results)} organizations")
+            except Exception as e:
+                logger.warning(f"Every.org search failed: {e}")
+        
+        # Filter by keyword if provided
+        if keyword and results:
+            keyword_lower = keyword.lower()
+            filtered_results = []
+            for org in results:
+                # Search in name, description, mission, ntee_description
+                searchable_text = ' '.join([
+                    str(org.get('name', '')),
+                    str(org.get('description', '')),
+                    str(org.get('mission', '')),
+                    str(org.get('ntee_description', ''))
+                ]).lower()
+                
+                if keyword_lower in searchable_text:
+                    filtered_results.append(org)
+            
+            results = filtered_results
+        
+        return {
+            "location": location,
+            "keyword": keyword,
+            "state": state_code,
+            "ntee_code": ntee_code,
+            "count": len(results),
+            "nonprofits": results,
+            "data_sources": {
+                "propublica": "https://projects.propublica.org/nonprofits/api",
+                "everyorg": "https://www.every.org/nonprofit-api",
+                "irs_teos": "https://www.irs.gov/charities-non-profits/tax-exempt-organization-search-bulk-data-downloads"
+            }
+        }
+        
+    except Exception as e:
+        logger.error(f"Nonprofit search error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/api/data/status")
+async def get_data_status():
+    """
+    Get status of all reference data ingestions.
+    
+    Returns counts and last update times for:
+    - Census jurisdictions
+    - NCES school districts
+    - Nonprofit organizations
+    - Meeting datasets (MeetingBank, LocalView, etc.)
+    """
+    try:
+        from pathlib import Path
+        from datetime import datetime
+        
+        status = {
+            "census_jurisdictions": {
+                "path": "data/bronze/census_jurisdictions",
+                "status": "not_ingested",
+                "count": 0,
+                "last_updated": None
+            },
+            "nces_school_districts": {
+                "path": "data/bronze/nces_school_districts",
+                "status": "not_ingested",
+                "count": 0,
+                "last_updated": None
+            },
+            "nonprofits": {
+                "path": "data/cache/nonprofits",
+                "status": "cached",
+                "count": 0,
+                "last_updated": None
+            },
+            "meeting_datasets": {
+                "meetingbank": {"status": "available", "count": 1366},
+                "city_scrapers": {"status": "available", "count": "100-500"},
+                "open_states": {"status": "available", "count": "50+"}
+            }
+        }
+        
+        # Check each data directory
+        for key in ["census_jurisdictions", "nces_school_districts", "nonprofits"]:
+            data_path = Path(status[key]["path"])
+            if data_path.exists():
+                files = list(data_path.glob("**/*"))
+                status[key]["count"] = len(files)
+                status[key]["status"] = "ingested" if files else "empty"
+                if files:
+                    latest_file = max(files, key=lambda f: f.stat().st_mtime if f.is_file() else 0)
+                    if latest_file.is_file():
+                        status[key]["last_updated"] = datetime.fromtimestamp(
+                            latest_file.stat().st_mtime
+                        ).isoformat()
+        
+        return status
+        
+    except Exception as e:
+        logger.error(f"Data status error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/api/data/ingest/census")
+async def ingest_census_data(background_tasks: BackgroundTasks):
+    """
+    Trigger Census Bureau jurisdiction data ingestion.
+    
+    Downloads and processes:
+    - 3,144 counties
+    - 19,500+ municipalities  
+    - 36,000+ townships
+    - 13,000+ school districts
+    
+    This is a long-running operation that runs in the background.
+    """
+    try:
+        def run_census_ingestion():
+            from discovery.census_ingestion import CensusGovernmentIngestion
+            import asyncio
+            
+            logger.info("Starting Census data ingestion...")
+            ingestor = CensusGovernmentIngestion()
+            
+            # Run async ingestion
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+            result = loop.run_until_complete(ingestor.ingest_all_jurisdictions())
+            loop.close()
+            
+            logger.success(f"Census ingestion complete: {result}")
+        
+        background_tasks.add_task(run_census_ingestion)
+        
+        return {
+            "message": "Census data ingestion started",
+            "status": "processing",
+            "check_status": "/api/data/status"
+        }
+        
+    except Exception as e:
+        logger.error(f"Census ingestion error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/api/data/ingest/nces")
+async def ingest_nces_data(background_tasks: BackgroundTasks):
+    """
+    Trigger NCES school district data ingestion.
+    
+    Downloads and processes 13,000+ school districts with:
+    - District names and addresses
+    - Contact information
+    - NCES IDs
+    - Enrollment data
+    """
+    try:
+        def run_nces_ingestion():
+            from discovery.nces_ingestion import NCESSchoolDistrictIngestion
+            import asyncio
+            
+            logger.info("Starting NCES data ingestion...")
+            ingestor = NCESSchoolDistrictIngestion()
+            
+            # Run async ingestion
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+            result = loop.run_until_complete(ingestor.download_and_process())
+            loop.close()
+            
+            logger.success(f"NCES ingestion complete: {result}")
+        
+        background_tasks.add_task(run_nces_ingestion)
+        
+        return {
+            "message": "NCES data ingestion started",
+            "status": "processing",
+            "check_status": "/api/data/status"
+        }
+        
+    except Exception as e:
+        logger.error(f"NCES ingestion error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/api/data/ingest/nonprofits")
+async def ingest_nonprofits(
+    state: str = Query(..., description="2-letter state code"),
+    ntee_codes: Optional[List[str]] = Query(None, description="NTEE codes to ingest"),
+    background_tasks: BackgroundTasks = None
+):
+    """
+    Trigger nonprofit data ingestion for a specific state.
+    
+    Bulk downloads nonprofit data from ProPublica API and caches locally.
+    
+    Example: POST /api/data/ingest/nonprofits?state=AL&ntee_codes=E&ntee_codes=E20
+    """
+    try:
+        from discovery.nonprofit_discovery import NonprofitDiscovery
+        
+        discovery = NonprofitDiscovery()
+        ntee_list = ntee_codes or ["E"]  # Default to health
+        
+        total_orgs = 0
+        for ntee_code in ntee_list:
+            orgs = discovery.search_propublica(state=state, ntee_code=ntee_code)
+            total_orgs += len(orgs)
+            logger.info(f"Cached {len(orgs)} nonprofits for {state}/{ntee_code}")
+        
+        return {
+            "message": f"Nonprofit data ingestion complete for {state}",
+            "state": state,
+            "ntee_codes": ntee_list,
+            "organizations_cached": total_orgs,
+            "cache_location": "data/cache/nonprofits"
+        }
+        
+    except Exception as e:
+        logger.error(f"Nonprofit ingestion error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/api/jurisdictions")
+async def get_jurisdictions(
+    state: Optional[str] = Query(None, description="2-letter state code"),
+    type: Optional[str] = Query(None, description="Type: county, municipality, township"),
+    limit: int = Query(100, le=1000)
+):
+    """
+    Query ingested Census jurisdiction data.
+    
+    Returns government entities with FIPS codes, coordinates, and population.
+    """
+    try:
+        # This would query the Delta Lake census tables
+        # For now, return sample data
+        return {
+            "message": "Query census jurisdiction data from Delta Lake",
+            "filters": {"state": state, "type": type},
+            "limit": limit,
+            "note": "Requires Census data ingestion first (POST /api/data/ingest/census)",
+            "example_data": [
+                {
+                    "name": "Tuscaloosa County",
+                    "state": "AL",
+                    "type": "county",
+                    "fips": "01125",
+                    "population": "209355"
+                }
+            ]
+        }
+        
+    except Exception as e:
+        logger.error(f"Jurisdiction query error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/api/school-districts")
+async def get_school_districts(
+    state: Optional[str] = Query(None, description="2-letter state code"),
+    limit: int = Query(100, le=1000)
+):
+    """
+    Query ingested NCES school district data.
+    
+    Returns school districts with contact information and enrollment.
+    """
+    try:
+        # This would query the Delta Lake NCES tables
+        return {
+            "message": "Query NCES school district data from Delta Lake",
+            "filters": {"state": state},
+            "limit": limit,
+            "note": "Requires NCES data ingestion first (POST /api/data/ingest/nces)",
+            "example_data": [
+                {
+                    "name": "Tuscaloosa City Schools",
+                    "state": "AL",
+                    "nces_id": "0100123",
+                    "phone": "(205) 759-3500",
+                    "website": "https://www.tusc.k12.al.us/"
+                }
+            ]
+        }
+        
+    except Exception as e:
+        logger.error(f"School district query error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+# Serve React frontend
+static_dir = Path(__file__).parent / "static"
+if static_dir.exists():
+    # Mount static files (JS, CSS, images)
+    app.mount("/assets", StaticFiles(directory=static_dir / "assets"), name="assets")
+    
+    # Serve index.html for all non-API routes (SPA routing)
+    @app.get("/{full_path:path}")
+    async def serve_react_app(full_path: str):
+        """Serve React app for all non-API routes."""
+        if full_path.startswith("api/"):
+            raise HTTPException(status_code=404, detail="API endpoint not found")
+        
+        index_file = static_dir / "index.html"
+        if index_file.exists():
+            return FileResponse(index_file)
+        else:
+            raise HTTPException(status_code=404, detail="Frontend not built")
+
+
+@app.on_event("startup")
+async def startup_event():
+    """Initialize system on startup."""
+    logger.info("Starting Oral Health Policy Pulse application...")
+    
+    # Initialize Delta Lake if not exists
+    try:
+        await pipeline.initialize_tables()
+        logger.info("Delta Lake tables initialized")
+    except Exception as e:
+        logger.warning(f"Delta Lake initialization skipped: {e}")
+    
+    logger.info("Application started successfully")
+
+
+@app.on_event("shutdown")
+async def shutdown_event():
+    """Cleanup on shutdown."""
+    logger.info("Shutting down application...")
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(
+        "api.app:app",
+        host="0.0.0.0",
+        port=8000,
+        reload=True
+    )

api/auth.py

@@ -0,0 +1,153 @@
+"""
+Authentication utilities - JWT tokens, password hashing, OAuth helpers
+"""
+import os
+import secrets
+from datetime import datetime, timedelta
+from typing import Optional, Dict, Any
+from dotenv import load_dotenv
+
+from jose import JWTError, jwt
+from passlib.context import CryptContext
+from fastapi import HTTPException, status, Depends
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from sqlalchemy.orm import Session
+
+from api.database import get_db
+from api.models import User
+
+# Load environment variables
+load_dotenv()
+
+# Security configuration
+SECRET_KEY = os.getenv("JWT_SECRET_KEY", secrets.token_urlsafe(32))
+ALGORITHM = "HS256"
+ACCESS_TOKEN_EXPIRE_MINUTES = 60 * 24 * 7  # 7 days
+
+# Password hashing
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+# HTTP Bearer token scheme
+security = HTTPBearer(auto_error=False)
+
+
+def hash_password(password: str) -> str:
+    """Hash a password using bcrypt"""
+    return pwd_context.hash(password)
+
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    """Verify a password against its hash"""
+    return pwd_context.verify(plain_password, hashed_password)
+
+
+def create_access_token(data: Dict[str, Any], expires_delta: Optional[timedelta] = None) -> str:
+    """
+    Create a JWT access token
+    
+    Args:
+        data: Payload to encode (usually {"sub": user_id})
+        expires_delta: Optional custom expiration time
+    
+    Returns:
+        JWT token string
+    """
+    to_encode = data.copy()
+    
+    if expires_delta:
+        expire = datetime.utcnow() + expires_delta
+    else:
+        expire = datetime.utcnow() + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
+    
+    to_encode.update({"exp": expire})
+    encoded_jwt = jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
+    return encoded_jwt
+
+
+def decode_access_token(token: str) -> Dict[str, Any]:
+    """
+    Decode and validate a JWT token
+    
+    Args:
+        token: JWT token string
+    
+    Returns:
+        Decoded payload
+    
+    Raises:
+        HTTPException: If token is invalid or expired
+    """
+    try:
+        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
+        return payload
+    except JWTError:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Could not validate credentials",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+
+def get_current_user(
+    credentials: HTTPAuthorizationCredentials = Depends(security),
+    db: Session = Depends(get_db)
+) -> Optional[User]:
+    """
+    Get current authenticated user from JWT token
+    
+    Usage:
+        @app.get("/protected")
+        def protected_route(user: User = Depends(get_current_user)):
+            return {"message": f"Hello {user.email}"}
+    
+    Returns:
+        User object if authenticated, None if optional auth
+    """
+    if not credentials:
+        return None
+    
+    token = credentials.credentials
+    payload = decode_access_token(token)
+    
+    user_id: int = payload.get("sub")
+    if user_id is None:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid authentication credentials"
+        )
+    
+    user = db.query(User).filter(User.id == user_id).first()
+    if user is None:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="User not found"
+        )
+    
+    # Update last login
+    user.last_login = datetime.utcnow()
+    db.commit()
+    
+    return user
+
+
+def require_auth(user: User = Depends(get_current_user)) -> User:
+    """
+    Require authentication (raises 401 if not authenticated)
+    
+    Usage:
+        @app.get("/protected")
+        def protected_route(user: User = Depends(require_auth)):
+            return {"message": f"Hello {user.email}"}
+    """
+    if user is None:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Authentication required",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    return user
+
+
+def generate_state_token() -> str:
+    """Generate a secure random state token for OAuth CSRF protection"""
+    return secrets.token_urlsafe(32)

api/database.py

@@ -0,0 +1,62 @@
+"""
+Database connection and session management
+"""
+import os
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker, Session
+from sqlalchemy.pool import StaticPool
+from typing import Generator
+
+from api.models import Base
+
+# Database URL from environment or default to SQLite for development
+DATABASE_URL = os.getenv(
+    "DATABASE_URL",
+    "sqlite:///./data/users.db"  # Fallback to SQLite if no PostgreSQL configured
+)
+
+# Handle PostgreSQL URL format for SQLAlchemy 2.0+
+if DATABASE_URL.startswith("postgres://"):
+    DATABASE_URL = DATABASE_URL.replace("postgres://", "postgresql://", 1)
+
+# Create engine
+if "sqlite" in DATABASE_URL:
+    # SQLite needs special handling for concurrent access
+    engine = create_engine(
+        DATABASE_URL,
+        connect_args={"check_same_thread": False},
+        poolclass=StaticPool,
+    )
+else:
+    # PostgreSQL configuration
+    engine = create_engine(
+        DATABASE_URL,
+        pool_pre_ping=True,
+        pool_size=10,
+        max_overflow=20,
+    )
+
+# Create session factory
+SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+
+
+def init_db():
+    """Create all tables"""
+    Base.metadata.create_all(bind=engine)
+    print(f"✅ Database initialized at: {DATABASE_URL}")
+
+
+def get_db() -> Generator[Session, None, None]:
+    """
+    Database session dependency for FastAPI
+    
+    Usage:
+        @app.get("/users")
+        def get_users(db: Session = Depends(get_db)):
+            return db.query(User).all()
+    """
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()

api/errors.py

@@ -0,0 +1,154 @@
+"""
+Structured error models for API responses.
+
+Provides user-friendly error messages with expandable technical details.
+"""
+from pydantic import BaseModel, Field
+from typing import Optional, Dict, Any
+
+
+class ErrorDetail(BaseModel):
+    """Structured error detail with user-friendly message and technical info."""
+    
+    message: str = Field(
+        ...,
+        description="User-friendly error message"
+    )
+    
+    error_type: str = Field(
+        ...,
+        description="Type of error (e.g., 'data_not_found', 'network_error', 'validation_error')"
+    )
+    
+    technical_details: Optional[str] = Field(
+        None,
+        description="Technical error details for debugging (expandable in UI)"
+    )
+    
+    suggestions: Optional[list[str]] = Field(
+        None,
+        description="Helpful suggestions for the user"
+    )
+    
+    metadata: Optional[Dict[str, Any]] = Field(
+        None,
+        description="Additional context (state, dataset name, etc.)"
+    )
+
+
+def parse_error(exception: Exception, context: Optional[Dict[str, Any]] = None) -> ErrorDetail:
+    """
+    Parse an exception into a structured ErrorDetail with user-friendly message.
+    
+    Args:
+        exception: The exception to parse
+        context: Additional context (state, dataset, etc.)
+    
+    Returns:
+        ErrorDetail with user-friendly message and technical details
+    """
+    error_str = str(exception)
+    context = context or {}
+    
+    # Parse HuggingFace dataset not found errors
+    if "HTTP 404 Not Found" in error_str and "huggingface.co/datasets" in error_str:
+        # Extract dataset name from URL
+        import re
+        match = re.search(r'datasets/([^/]+/[^/]+)/', error_str)
+        dataset_name = match.group(1) if match else "unknown"
+        
+        # Extract state from dataset name or context
+        state = context.get('state', 'Unknown')
+        data_type = 'bills' if 'bills' in dataset_name else 'data'
+        
+        return ErrorDetail(
+            message=f"No {data_type} data available for {state.upper()}",
+            error_type="data_not_found",
+            technical_details=f"Dataset '{dataset_name}' not found on HuggingFace.\n\nFull error: {error_str}",
+            suggestions=[
+                f"Try a different state - we have data for 50+ states",
+                f"Check /api/bills/map to see which states have {data_type} data",
+                "Contact support if you believe this data should be available"
+            ],
+            metadata={
+                "dataset": dataset_name,
+                "state": state,
+                "data_type": data_type
+            }
+        )
+    
+    # Parse file not found errors (local environment)
+    elif "No such file or directory" in error_str or "FileNotFoundError" in error_str:
+        state = context.get('state', 'Unknown')
+        data_type = context.get('data_type', 'data')
+        
+        return ErrorDetail(
+            message=f"No {data_type} available for {state.upper()}",
+            error_type="data_not_found",
+            technical_details=error_str,
+            suggestions=[
+                f"This state may not have {data_type} in our database yet",
+                "Try a different state or check which states have data",
+                "Data is being continuously added - check back later"
+            ],
+            metadata={
+                "state": state,
+                "data_type": data_type
+            }
+        )
+    
+    # Parse DuckDB/SQL errors
+    elif "DuckDB" in error_str or "SYNTAX ERROR" in error_str or "LINE" in error_str:
+        return ErrorDetail(
+            message="Database query error - please check your search parameters",
+            error_type="query_error",
+            technical_details=error_str,
+            suggestions=[
+                "Try simplifying your search query",
+                "Check that all parameters are valid",
+                "Contact support if the issue persists"
+            ],
+            metadata=context
+        )
+    
+    # Parse network/timeout errors
+    elif "timeout" in error_str.lower() or "connection" in error_str.lower():
+        return ErrorDetail(
+            message="Network request timed out - please try again",
+            error_type="network_error",
+            technical_details=error_str,
+            suggestions=[
+                "Try again in a few seconds",
+                "Check your internet connection",
+                "The server may be temporarily busy"
+            ],
+            metadata=context
+        )
+    
+    # Parse validation errors
+    elif "validation" in error_str.lower() or "invalid" in error_str.lower():
+        return ErrorDetail(
+            message="Invalid request parameters",
+            error_type="validation_error",
+            technical_details=error_str,
+            suggestions=[
+                "Check that all required parameters are provided",
+                "Verify parameter formats (e.g., state codes should be 2 letters)",
+                "See API documentation for valid parameter values"
+            ],
+            metadata=context
+        )
+    
+    # Generic error fallback
+    else:
+        return ErrorDetail(
+            message="An unexpected error occurred",
+            error_type="server_error",
+            technical_details=error_str,
+            suggestions=[
+                "Try again in a few moments",
+                "Contact support if the issue persists",
+                "Check the technical details for more information"
+            ],
+            metadata=context
+        )

api/main.py

@@ -0,0 +1,1288 @@
+"""
+FastAPI application for the Oral Health Policy Pulse system.
+
+Provides REST API endpoints for:
+- Initiating policy analysis workflows
+- Querying advocacy opportunities
+- Retrieving generated materials
+- Accessing visualizations
+- System status and monitoring
+"""
+from typing import List, Dict, Any, Optional
+from datetime import datetime, date
+import sys
+import time
+from pathlib import Path
+from fastapi import FastAPI, HTTPException, Query, BackgroundTasks, Request
+from fastapi.responses import HTMLResponse, JSONResponse
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+from fastapi.openapi.docs import get_swagger_ui_html
+from pydantic import BaseModel, Field
+from loguru import logger
+import os
+
+from agents.orchestrator import OrchestratorAgent
+from agents.scraper import ScraperAgent
+from agents.parser import ParserAgent
+from agents.classifier import ClassifierAgent
+from agents.sentiment import SentimentAnalyzerAgent
+from agents.advocacy import AdvocacyWriterAgent
+from pipeline.delta_lake import DeltaLakePipeline
+from visualization.heatmap import AdvocacyHeatmap
+from config import settings
+
+# Configure logging with rotation and retention
+# Output to both file (with rotation) and stderr (for HuggingFace container logs)
+logger.remove()  # Remove default handler
+
+# Add console output (shows in HuggingFace container logs)
+logger.add(
+    sys.stderr,
+    format="<green>{time:YYYY-MM-DD HH:mm:ss}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan> - <level>{message}</level>",
+    level=settings.log_level
+)
+
+# Add file output with rotation and retention
+logger.add(
+    settings.log_file,
+    rotation="500 MB",      # Create new file when size exceeds 500MB
+    retention="10 days",    # Delete logs older than 10 days
+    level=settings.log_level,
+    format="{time:YYYY-MM-DD HH:mm:ss} | {level: <8} | {name}:{function} - {message}"
+)
+
+# Initialize FastAPI app
+app = FastAPI(
+    title="Open Navigator API",
+    description="Multi-agent system for analyzing local government oral health policy discussions",
+    version="1.0.0",
+    docs_url=None,  # Disable default docs to use custom
+    redoc_url="/redoc",  # Keep ReDoc at /redoc
+    openapi_tags=[
+        {
+            "name": "auth",
+            "description": "Authentication and user management"
+        },
+        {
+            "name": "social",
+            "description": "Social features - follow users, leaders, organizations, and causes"
+        },
+        {
+            "name": "workflows",
+            "description": "Policy analysis workflows"
+        },
+        {
+            "name": "opportunities",
+            "description": "Advocacy opportunities"
+        }
+    ]
+)
+
+# Custom OpenAPI schema with logo
+def custom_openapi():
+    if app.openapi_schema:
+        return app.openapi_schema
+    
+    from fastapi.openapi.utils import get_openapi
+    
+    openapi_schema = get_openapi(
+        title=app.title,
+        version=app.version,
+        description=app.description,
+        routes=app.routes,
+    )
+    
+    # Add custom logo
+    openapi_schema["info"]["x-logo"] = {
+        "url": "/static/communityone_logo.svg",
+        "altText": "CommunityOne Logo"
+    }
+    
+    app.openapi_schema = openapi_schema
+    return app.openapi_schema
+
+app.openapi = custom_openapi
+
+# Add CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Request logging middleware
+@app.middleware("http")
+async def log_requests(request: Request, call_next):
+    """Log all API requests with timing and response info"""
+    start_time = time.time()
+    
+    # Get client info
+    client_host = request.client.host if request.client else "unknown"
+    
+    # Log incoming request
+    logger.info(f"➡️  {request.method} {request.url.path} - Client: {client_host}")
+    
+    # Process request
+    try:
+        response = await call_next(request)
+        
+        # Calculate duration
+        duration_ms = (time.time() - start_time) * 1000
+        
+        # Get response size if available
+        response_size = response.headers.get("content-length", "unknown")
+        
+        # Log response with appropriate emoji based on status
+        if response.status_code < 400:
+            logger.info(
+                f"✅ {request.method} {request.url.path} - "
+                f"Status: {response.status_code} - "
+                f"Duration: {duration_ms:.2f}ms - "
+                f"Size: {response_size} bytes"
+            )
+        elif response.status_code < 500:
+            logger.warning(
+                f"⚠️  {request.method} {request.url.path} - "
+                f"Status: {response.status_code} - "
+                f"Duration: {duration_ms:.2f}ms"
+            )
+        else:
+            logger.error(
+                f"❌ {request.method} {request.url.path} - "
+                f"Status: {response.status_code} - "
+                f"Duration: {duration_ms:.2f}ms"
+            )
+        
+        return response
+        
+    except Exception as e:
+        duration_ms = (time.time() - start_time) * 1000
+        logger.error(
+            f"💥 {request.method} {request.url.path} - "
+            f"Error: {str(e)} - "
+            f"Duration: {duration_ms:.2f}ms"
+        )
+        raise
+
+# Mount static files for logo
+static_dir = os.path.join(os.path.dirname(os.path.dirname(__file__)), "frontend", "public")
+if os.path.exists(static_dir):
+    app.mount("/static", StaticFiles(directory=static_dir), name="static")
+else:
+    logger.warning(f"Static directory not found: {static_dir}")
+
+# Include authentication routes
+from api.routes import auth as auth_routes
+from api.routes import social as social_routes
+from api.routes import search as search_routes
+# Use Neon database for fast stats queries (500x faster than parquet)
+from api.routes import stats_neon as stats_routes  # Was: stats
+from api.routes import contact as contact_routes
+# Use hybrid approach for bills: Neon for map, parquet for drill-down (saves space)
+from api.routes import bills_neon as bills_routes  # Was: bills
+from api.database import init_db
+
+app.include_router(auth_routes.router)
+app.include_router(social_routes.router)
+app.include_router(search_routes.router)
+app.include_router(stats_routes.router, prefix="/api", tags=["stats"])
+app.include_router(contact_routes.router)
+app.include_router(bills_routes.router)
+
+# Custom Swagger UI with logo
+@app.get("/docs", include_in_schema=False)
+async def custom_swagger_ui_html():
+    """Custom Swagger UI with CommunityOne logo"""
+    return get_swagger_ui_html(
+        openapi_url=app.openapi_url,
+        title=f"{app.title} - API Documentation",
+        swagger_favicon_url="/static/communityone_logo_64.png",
+        swagger_ui_parameters={
+            "defaultModelsExpandDepth": -1,
+            "docExpansion": "list",
+            "filter": True,
+            "syntaxHighlight.theme": "monokai"
+        }
+    )
+
+# Initialize database on startup
+@app.on_event("startup")
+async def init_database():
+    """Initialize authentication database"""
+    try:
+        init_db()
+        logger.info("✅ Authentication database initialized")
+    except Exception as e:
+        logger.warning(f"⚠️  Database initialization skipped: {e}")
+
+# Initialize components
+orchestrator = OrchestratorAgent()
+pipeline = DeltaLakePipeline()
+heatmap_generator = AdvocacyHeatmap()
+
+
+# Pydantic models for API
+class ScrapeTarget(BaseModel):
+    """Configuration for a scraping target."""
+    url: str
+    municipality: str
+    state: str
+    platform: str = "generic"
+
+
+class WorkflowRequest(BaseModel):
+    """Request to start a new analysis workflow."""
+    scrape_targets: List[ScrapeTarget]
+    date_range: Optional[Dict[str, str]] = None
+    description: Optional[str] = None
+
+
+class WorkflowResponse(BaseModel):
+    """Response for workflow operations."""
+    workflow_id: str
+    status: str
+    message: str
+
+
+class OpportunityFilter(BaseModel):
+    """Filters for querying opportunities."""
+    state: Optional[str] = None
+    municipality: Optional[str] = None
+    topic: Optional[str] = None
+    urgency: Optional[str] = None
+    min_date: Optional[date] = None
+    max_date: Optional[date] = None
+
+
+class OpportunityResponse(BaseModel):
+    """Response containing advocacy opportunities."""
+    opportunities: List[Dict[str, Any]]
+    total_count: int
+    filters_applied: Dict[str, Any]
+
+
+class SystemStatus(BaseModel):
+    """System status information."""
+    status: str
+    active_workflows: int
+    agent_status: Dict[str, Any]
+    last_update: datetime
+
+
+# API Endpoints
+
+@app.get("/", response_class=HTMLResponse)
+async def root():
+    """Root endpoint with API information."""
+    html_content = """
+    <!DOCTYPE html>
+    <html>
+        <head>
+            <title>Open Navigator API</title>
+            <style>
+                body { 
+                    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+                    max-width: 900px; 
+                    margin: 50px auto; 
+                    padding: 20px;
+                    line-height: 1.6;
+                }
+                .header {
+                    display: flex;
+                    align-items: center;
+                    gap: 20px;
+                    margin-bottom: 30px;
+                    border-bottom: 2px solid #1976d2;
+                    padding-bottom: 20px;
+                }
+                .logo {
+                    width: 80px;
+                    height: 80px;
+                }
+                h1 { 
+                    color: #1976d2;
+                    margin: 0;
+                }
+                .tagline {
+                    color: #666;
+                    font-size: 1.1em;
+                }
+                .endpoint { 
+                    background: linear-gradient(135deg, #f5f5f5 0%, #e8f4f8 100%);
+                    padding: 15px;
+                    margin: 10px 0;
+                    border-radius: 8px;
+                    border-left: 4px solid #1976d2;
+                }
+                .endpoint strong {
+                    color: #1976d2;
+                }
+                code { 
+                    background: #e0e0e0;
+                    padding: 3px 8px;
+                    border-radius: 4px;
+                    font-family: 'Courier New', monospace;
+                }
+                .docs-link {
+                    display: inline-block;
+                    background: #1976d2;
+                    color: white;
+                    padding: 12px 24px;
+                    text-decoration: none;
+                    border-radius: 6px;
+                    margin-top: 20px;
+                    transition: background 0.3s;
+                }
+                .docs-link:hover {
+                    background: #1565c0;
+                }
+            </style>
+        </head>
+        <body>
+            <div class="header">
+                <img src="/static/communityone_logo.svg" alt="CommunityOne Logo" class="logo">
+                <div>
+                    <h1>Open Navigator API</h1>
+                    <p class="tagline">CommunityOne: The open path to everything local</p>
+                </div>
+            </div>
+            
+            <h2>🔑 Key Endpoints:</h2>
+            <div class="endpoint">
+                <strong>POST /workflow/start</strong> - Start a new analysis workflow
+            </div>
+            <div class="endpoint">
+                <strong>GET /opportunities</strong> - Query advocacy opportunities
+            </div>
+            <div class="endpoint">
+                <strong>GET /heatmap</strong> - Get advocacy heatmap visualization
+            </div>
+            <div class="endpoint">
+                <strong>GET /status</strong> - System status and health
+            </div>
+            <div class="endpoint">
+                <strong>POST /auth/login/{provider}</strong> - OAuth login (HuggingFace, Google, Facebook, GitHub)
+            </div>
+            
+            <a href="/docs" class="docs-link">📚 View Full API Documentation</a>
+        </body>
+    </html>
+    """
+    return HTMLResponse(content=html_content)
+
+
+@app.post("/workflow/start", response_model=WorkflowResponse)
+async def start_workflow(
+    request: WorkflowRequest,
+    background_tasks: BackgroundTasks
+):
+    """
+    Start a new policy analysis workflow.
+    
+    This initiates the full multi-agent pipeline:
+    1. Scrape meeting minutes from specified sources
+    2. Parse and structure the data
+    3. Classify by oral health topics
+    4. Analyze sentiment and policy stance
+    5. Generate advocacy materials
+    """
+    try:
+        # Register agents with orchestrator
+        orchestrator.register_agent(ScraperAgent())
+        orchestrator.register_agent(ParserAgent())
+        orchestrator.register_agent(ClassifierAgent())
+        orchestrator.register_agent(SentimentAnalyzerAgent())
+        orchestrator.register_agent(AdvocacyWriterAgent())
+        
+        # Convert targets to dict format
+        targets = [target.dict() for target in request.scrape_targets]
+        
+        # Start workflow in background
+        background_tasks.add_task(
+            orchestrator.execute_pipeline,
+            targets,
+            request.date_range
+        )
+        
+        return WorkflowResponse(
+            workflow_id="wf-" + datetime.utcnow().strftime("%Y%m%d-%H%M%S"),
+            status="started",
+            message=f"Workflow started with {len(targets)} targets"
+        )
+        
+    except Exception as e:
+        logger.error(f"Error starting workflow: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/workflow/{workflow_id}/status")
+async def get_workflow_status(workflow_id: str):
+    """Get the status of a specific workflow."""
+    # Query workflow status from orchestrator
+    # This is a placeholder - would query actual workflow state
+    return {
+        "workflow_id": workflow_id,
+        "status": "running",
+        "stage": "classification",
+        "progress": 0.6
+    }
+
+
+@app.get("/opportunities", response_model=OpportunityResponse)
+async def get_opportunities(
+    state: Optional[str] = Query(None, description="Filter by state code"),
+    municipality: Optional[str] = Query(None, description="Filter by municipality"),
+    topic: Optional[str] = Query(None, description="Filter by policy topic"),
+    urgency: Optional[str] = Query(None, description="Filter by urgency level"),
+    limit: int = Query(100, ge=1, le=1000, description="Maximum results to return")
+):
+    """
+    Query advocacy opportunities.
+    
+    Returns a list of identified opportunities for advocacy action
+    based on the specified filters.
+    """
+    try:
+        # Query from Delta Lake
+        opportunities = pipeline.query_opportunities_by_state(state, urgency)
+        
+        # Apply additional filters
+        if municipality:
+            opportunities = [
+                opp for opp in opportunities
+                if opp.get("municipality", "").lower() == municipality.lower()
+            ]
+        
+        if topic:
+            opportunities = [
+                opp for opp in opportunities
+                if opp.get("topic") == topic
+            ]
+        
+        # Limit results
+        opportunities = opportunities[:limit]
+        
+        return OpportunityResponse(
+            opportunities=opportunities,
+            total_count=len(opportunities),
+            filters_applied={
+                "state": state,
+                "municipality": municipality,
+                "topic": topic,
+                "urgency": urgency
+            }
+        )
+        
+    except Exception as e:
+        logger.error(f"Error querying opportunities: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+# React frontend endpoints with /api/ prefix
+@app.get("/api/opportunities")
+async def get_api_opportunities(
+    state: Optional[str] = Query(None),
+    topic: Optional[str] = Query(None),
+    urgency: Optional[str] = Query(None),
+    limit: int = Query(100)
+):
+    """API endpoint for React frontend opportunities page - returns fluoridation bills as advocacy opportunities."""
+    try:
+        import duckdb
+        from pathlib import Path
+        import random
+        
+        # State center coordinates for mapping
+        STATE_COORDS = {
+            'AL': (32.806671, -86.791130),
+            'GA': (33.040619, -83.643074),
+            'IN': (39.849426, -86.258278),
+            'MA': (42.230171, -71.530106),
+            'WA': (47.400902, -121.490494),
+            'WI': (44.268543, -89.616508)
+        }
+        
+        # Build query for fluoridation-related bills
+        states = [state] if state else list(STATE_COORDS.keys())
+        opportunities = []
+        
+        for st in states:
+            parquet_path = Path(f"data/gold/states/{st}/bills_bills.parquet")
+            if not parquet_path.exists():
+                continue
+            
+            # Query for fluoridation-related bills
+            query = f"""
+                SELECT 
+                    '{st}' as state,
+                    title,
+                    identifier,
+                    session,
+                    latest_action,
+                    created_at,
+                    updated_at
+                FROM read_parquet('{parquet_path}')
+                WHERE LOWER(title) LIKE '%fluorid%' 
+                   OR LOWER(title) LIKE '%dental%'
+                   OR LOWER(title) LIKE '%oral health%'
+                   OR LOWER(title) LIKE '%water treat%'
+                LIMIT {limit}
+            """
+            
+            result = duckdb.query(query).fetchall()
+            
+            # Convert to opportunities format
+            for row in result:
+                state_code, title, identifier, session, latest_action, created_at, updated_at = row
+                
+                # Determine urgency based on keywords
+                title_lower = title.lower() if title else ""
+                # Check for fluoride topics (both pro and anti fluoride are critical)
+                if 'fluoride' in title_lower or 'fluorin' in title_lower or 'water' in title_lower:
+                    urgency_level = 'critical'
+                    confidence = 0.9
+                    topic_type = 'water_fluoridation'
+                elif 'dental' in title_lower:
+                    urgency_level = 'high'
+                    confidence = 0.75
+                    topic_type = 'school_dental_screening'
+                else:
+                    urgency_level = 'medium'
+                    confidence = 0.6
+                    topic_type = 'medicaid_dental_expansion'
+                
+                # Filter by topic if specified
+                if topic and topic_type != topic:
+                    continue
+                
+                # Filter by urgency if specified
+                if urgency and urgency_level != urgency:
+                    continue
+                
+                # Get state coordinates with slight random offset for multiple bills
+                base_lat, base_lon = STATE_COORDS[state_code]
+                lat_offset = random.uniform(-0.5, 0.5)
+                lon_offset = random.uniform(-0.5, 0.5)
+                
+                opportunities.append({
+                    'state': state_code,
+                    'municipality': f'{state_code} Legislature',
+                    'latitude': base_lat + lat_offset,
+                    'longitude': base_lon + lon_offset,
+                    'topic': topic_type,
+                    'urgency': urgency_level,
+                    'confidence': confidence,
+                    'meeting_date': updated_at.isoformat() if updated_at else created_at.isoformat(),
+                    'title': title,
+                    'bill_id': identifier,
+                    'session': session,
+                    'latest_action': latest_action
+                })
+        
+        return {"opportunities": opportunities[:limit]}
+    except Exception as e:
+        logger.error(f"Error: {e}")
+        return {"opportunities": []}
+
+
+@app.get("/api/documents")
+async def get_api_documents(
+    search: Optional[str] = Query(None),
+    page: int = Query(1),
+    limit: int = Query(20)
+):
+    """API endpoint for React frontend documents page."""
+    try:
+        # Get all opportunities (documents)
+        documents = pipeline.query_opportunities_by_state(None, None)
+        
+        # Apply search filter
+        if search:
+            search_lower = search.lower()
+            documents = [
+                d for d in documents
+                if search_lower in d.get("title", "").lower() or
+                   search_lower in d.get("municipality", "").lower() or
+                   search_lower in d.get("content", "").lower()
+            ]
+        
+        # Paginate
+        start = (page - 1) * limit
+        end = start + limit
+        
+        return {
+            "documents": documents[start:end],
+            "total": len(documents),
+            "page": page,
+            "limit": limit
+        }
+    except Exception as e:
+        logger.error(f"Error: {e}")
+        return {"documents": [], "total": 0}
+
+
+@app.get("/opportunities/{opportunity_id}")
+async def get_opportunity_detail(opportunity_id: str):
+    """Get detailed information about a specific opportunity."""
+    # Query specific opportunity
+    document = pipeline.get_document_by_id(opportunity_id)
+    
+    if not document:
+        raise HTTPException(status_code=404, detail="Opportunity not found")
+    
+    return document
+
+
+@app.get("/opportunities/{opportunity_id}/materials")
+async def get_advocacy_materials(opportunity_id: str):
+    """Get generated advocacy materials for an opportunity."""
+    # Query materials from Delta Lake
+    # This is a placeholder
+    return {
+        "opportunity_id": opportunity_id,
+        "materials": {
+            "email": {
+                "subject": "Support Oral Health Policy",
+                "body": "..."
+            },
+            "talking_points": [],
+            "social_media": {}
+        }
+    }
+
+
+@app.get("/heatmap", response_class=HTMLResponse)
+async def get_heatmap(
+    urgency: Optional[str] = Query(None, description="Filter by urgency level")
+):
+    """
+    Get interactive heatmap visualization.
+    
+    Returns an HTML page with an interactive map showing
+    advocacy opportunities across the country.
+    """
+    try:
+        # Query opportunities
+        opportunities = pipeline.query_opportunities_by_state(None, urgency)
+        
+        # Generate map
+        m = heatmap_generator.create_folium_map(
+            opportunities,
+            title="Open Navigator - Advocacy Heatmap"
+        )
+        
+        # Return HTML
+        return HTMLResponse(content=m._repr_html_())
+        
+    except Exception as e:
+        logger.error(f"Error generating heatmap: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/dashboard")
+async def get_dashboard():
+    """
+    Get complete dashboard data including statistics and visualizations.
+    """
+    try:
+        # Query all opportunities
+        opportunities = pipeline.query_opportunities_by_state(None, None)
+        
+        # Generate dashboard
+        dashboard = heatmap_generator.create_dashboard(opportunities)
+        
+        # Convert visualizations to JSON-serializable format
+        return {
+            "statistics": dashboard["statistics"],
+            "topic_distribution": dashboard["topic_distribution"].to_json(),
+            "timeline": dashboard["timeline"].to_json()
+        }
+        
+    except Exception as e:
+        logger.error(f"Error generating dashboard: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/api/dashboard")
+async def get_api_dashboard():
+    """
+    Get dashboard statistics for React frontend.
+    Returns data in format expected by frontend Dashboard component.
+    """
+    try:
+        # Query all opportunities
+        opportunities = pipeline.query_opportunities_by_state(None, None)
+        
+        # Count topics
+        topics_count = {}
+        for opp in opportunities:
+            topic = opp.get("topic", "unknown")
+            topics_count[topic] = topics_count.get(topic, 0) + 1
+        
+        # Get unique states
+        states = set(opp.get("state") for opp in opportunities if opp.get("state"))
+        
+        # Get recent opportunities (last 10)
+        recent = sorted(
+            opportunities,
+            key=lambda x: x.get("meeting_date", ""),
+            reverse=True
+        )[:10]
+        
+        return {
+            "total_documents": len(opportunities),
+            "total_opportunities": len(opportunities),
+            "states_monitored": len(states),
+            "topics": topics_count,
+            "recent_opportunities": recent
+        }
+        
+    except Exception as e:
+        logger.error(f"Error generating API dashboard: {e}")
+        # Return mock data if there's an error
+        return {
+            "total_documents": 0,
+            "total_opportunities": 0,
+            "states_monitored": 0,
+            "topics": {},
+            "recent_opportunities": []
+        }
+
+
+@app.get("/topics")
+async def get_topics():
+    """Get list of all policy topics being tracked."""
+    return {
+        "topics": settings.policy_topics,
+        "count": len(settings.policy_topics)
+    }
+
+
+@app.get("/states")
+async def get_states():
+    """Get list of all states with active opportunities."""
+    # Query distinct states from database
+    states = ["CA", "NY", "TX", "FL", "IL"]  # Placeholder
+    
+    return {
+        "states": states,
+        "count": len(states)
+    }
+
+
+@app.get("/status", response_model=SystemStatus)
+async def get_system_status():
+    """Get current system status and health."""
+    try:
+        agent_status = orchestrator.get_all_agent_states()
+        
+        return SystemStatus(
+            status="operational",
+            active_workflows=len(orchestrator.active_workflows),
+            agent_status=agent_status,
+            last_update=datetime.utcnow()
+        )
+        
+    except Exception as e:
+        logger.error(f"Error getting system status: {e}")
+        return SystemStatus(
+            status="error",
+            active_workflows=0,
+            agent_status={},
+            last_update=datetime.utcnow()
+        )
+
+
+@app.get("/nonprofits")
+async def search_nonprofits(
+    location: str = Query("Tuscaloosa, AL", description="City, State format"),
+    keyword: Optional[str] = Query(None, description="Service keyword (e.g., 'dental', 'health')"),
+    state: Optional[str] = Query(None, description="2-letter state code (e.g., 'AL')"),
+    ntee_code: Optional[str] = Query(None, description="NTEE code (e.g., 'E' for health)"),
+    source: Optional[str] = Query(None, description="Data source: 'propublica', 'everyorg', 'all'")
+):
+    """
+    Search for nonprofits using free open data APIs.
+    
+    Integrates data from:
+    - ProPublica Nonprofit Explorer (financial data, NTEE codes)
+    - Every.org (mission statements, logos)
+    - IRS TEOS (official tax-exempt status)
+    
+    Example: /nonprofits?location=Tuscaloosa,AL&keyword=dental&ntee_code=E
+    """
+    try:
+        from discovery.nonprofit_discovery import NonprofitDiscovery
+        
+        discovery = NonprofitDiscovery()
+        results = []
+        
+        # Parse location for state/city
+        location_parts = location.split(',')
+        city = location_parts[0].strip() if len(location_parts) > 0 else None
+        state_from_location = location_parts[1].strip() if len(location_parts) > 1 else None
+        state_code = state or state_from_location or "AL"
+        
+        # Determine which sources to query
+        sources_to_query = ['propublica', 'everyorg'] if source == 'all' or not source else [source]
+        
+        # Query ProPublica
+        if 'propublica' in sources_to_query:
+            try:
+                propublica_results = discovery.search_propublica(
+                    state=state_code,
+                    city=city,
+                    ntee_code=ntee_code
+                )
+                results.extend(propublica_results)
+                logger.info(f"ProPublica: Found {len(propublica_results)} organizations")
+            except Exception as e:
+                logger.warning(f"ProPublica search failed: {e}")
+        
+        # Query Every.org
+        if 'everyorg' in sources_to_query:
+            try:
+                causes = []
+                if keyword:
+                    # Map keywords to causes
+                    keyword_lower = keyword.lower()
+                    if 'health' in keyword_lower or 'dental' in keyword_lower or 'medical' in keyword_lower:
+                        causes.append('health')
+                    if 'education' in keyword_lower or 'school' in keyword_lower:
+                        causes.append('education')
+                
+                everyorg_results = discovery.search_everyorg(
+                    location=location,
+                    causes=causes if causes else None
+                )
+                results.extend(everyorg_results)
+                logger.info(f"Every.org: Found {len(everyorg_results)} organizations")
+            except Exception as e:
+                logger.warning(f"Every.org search failed: {e}")
+        
+        # Filter by keyword if provided
+        if keyword and results:
+            keyword_lower = keyword.lower()
+            filtered_results = []
+            for org in results:
+                # Search in name, description, mission, ntee_description
+                searchable_text = ' '.join([
+                    str(org.get('name', '')),
+                    str(org.get('description', '')),
+                    str(org.get('mission', '')),
+                    str(org.get('ntee_description', ''))
+                ]).lower()
+                
+                if keyword_lower in searchable_text:
+                    filtered_results.append(org)
+            
+            results = filtered_results
+        
+        return {
+            "location": location,
+            "keyword": keyword,
+            "state": state_code,
+            "ntee_code": ntee_code,
+            "count": len(results),
+            "nonprofits": results,
+            "data_sources": {
+                "propublica": "https://projects.propublica.org/nonprofits/api",
+                "everyorg": "https://www.every.org/nonprofit-api",
+                "irs_teos": "https://www.irs.gov/charities-non-profits/tax-exempt-organization-search-bulk-data-downloads"
+            }
+        }
+        
+    except Exception as e:
+        logger.error(f"Nonprofit search error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/api/nonprofits")
+async def search_nonprofits_api(
+    location: str = Query("Tuscaloosa, AL", description="City, State format"),
+    keyword: Optional[str] = Query(None, description="Service keyword (e.g., 'dental', 'health')"),
+    state: Optional[str] = Query(None, description="2-letter state code (e.g., 'AL')"),
+    ntee_code: Optional[str] = Query(None, description="NTEE code (e.g., 'E' for health)"),
+    source: Optional[str] = Query(None, description="Data source: 'propublica', 'everyorg', 'all'")
+):
+    """
+    Search for nonprofits using free open data APIs (API-prefixed endpoint for frontend).
+    
+    This is a duplicate of /nonprofits with /api prefix for frontend routing.
+    """
+    return await search_nonprofits(location, keyword, state, ntee_code, source)
+
+
+@app.get("/data/status")
+async def get_data_ingestion_status():
+    """
+    Get status of reference data ingestions.
+    
+    Shows Census jurisdictions, NCES school districts, and nonprofit cache status.
+    """
+    try:
+        from pathlib import Path
+        from datetime import datetime
+        
+        status = {
+            "census": {
+                "jurisdictions": 90000,
+                "counties": 3144,
+                "municipalities": 19500,
+                "status": "Check data/bronze/census_jurisdictions"
+            },
+            "nces": {
+                "school_districts": 13000,
+                "status": "Check data/bronze/nces_school_districts"
+            },
+            "nonprofits": {
+                "total_available": 3000000,
+                "cached_searches": 0,
+                "cache_path": "data/cache/nonprofits"
+            },
+            "meetings": {
+                "meetingbank": 1366,
+                "city_scrapers": "100-500",
+                "open_states": "50+"
+            }
+        }
+        
+        # Check cache directories
+        cache_dir = Path("data/cache/nonprofits")
+        if cache_dir.exists():
+            cached_files = list(cache_dir.glob("*.json"))
+            status["nonprofits"]["cached_searches"] = len(cached_files)
+        
+        return status
+        
+    except Exception as e:
+        logger.error(f"Data status error: {e}")
+        return {"error": str(e)}
+
+
+@app.post("/data/ingest/nonprofits")
+async def bulk_ingest_nonprofits(
+    state: str = Query(..., description="State code (e.g., AL)"),
+    ntee_code: Optional[str] = Query("E", description="NTEE code (default: E for Health)")
+):
+    """
+    Bulk ingest nonprofit data for a state.
+    
+    Caches ProPublica API results for offline use.
+    """
+    try:
+        from discovery.nonprofit_discovery import NonprofitDiscovery
+        
+        discovery = NonprofitDiscovery()
+        orgs = discovery.search_propublica(state=state, ntee_code=ntee_code)
+        
+        return {
+            "message": f"Ingested {len(orgs)} nonprofits for {state}",
+            "state": state,
+            "ntee_code": ntee_code,
+            "count": len(orgs),
+            "cache_location": "data/cache/nonprofits"
+        }
+        
+    except Exception as e:
+        logger.error(f"Nonprofit ingestion error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/health")
+async def health_check():
+    """Health check endpoint for monitoring."""
+    return {
+        "status": "healthy",
+        "timestamp": datetime.utcnow().isoformat(),
+        "version": "1.0.0"
+    }
+
+
+@app.get("/api/health")
+async def api_health_check():
+    """Health check endpoint for monitoring (API path)."""
+    return {
+        "status": "healthy",
+        "timestamp": datetime.utcnow().isoformat(),
+        "version": "1.0.0"
+    }
+
+
+@app.post("/admin/initialize")
+async def initialize_system():
+    """Initialize Delta Lake tables and system components."""
+    try:
+        pipeline.initialize_tables()
+        
+        return {
+            "status": "success",
+            "message": "System initialized successfully"
+        }
+        
+    except Exception as e:
+        logger.error(f"Error initializing system: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+# Startup event
+@app.post("/api/debate-grade")
+async def grade_decision_with_debate_framework(
+    document_id: Optional[str] = Query(None, description="Document ID to grade"),
+    text: Optional[str] = Query(None, description="Text to grade directly"),
+    title: Optional[str] = Query("", description="Document title")
+):
+    """
+    Grade a government decision using debate framework (Harms/Solvency/Topicality).
+    
+    Translates debate concepts for laypeople:
+    - Harms → "The Problem": Why is this a crisis?
+    - Solvency → "The Fix": How does this solution work?
+    - Topicality → "The Scope": Does the government have authority?
+    
+    Example: /api/debate-grade?text=The city council approved funding for dental screening...
+    """
+    try:
+        from agents.debate_grader import DebateGraderAgent
+        
+        grader = DebateGraderAgent()
+        
+        # Get document content
+        if document_id:
+            document = pipeline.get_document_by_id(document_id)
+            if not document:
+                raise HTTPException(status_code=404, detail="Document not found")
+        elif text:
+            document = {
+                "content": text,
+                "title": title,
+                "id": "custom_text"
+            }
+        else:
+            raise HTTPException(status_code=400, detail="Provide either document_id or text")
+        
+        # Grade the document
+        grade = await grader._grade_document(document)
+        
+        return {
+            "document_id": document.get("id"),
+            "title": document.get("title", ""),
+            "debate_grade": grade,
+            "explanation": {
+                "harms": "This measures how well the decision identifies and documents the problem using data and evidence",
+                "solvency": "This measures how clearly the solution is defined and whether it will actually fix the problem",
+                "topicality": "This measures whether the government body has the legal authority to take this action"
+            }
+        }
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Debate grading error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.post("/api/debate-grade/batch")
+async def grade_decisions_batch(
+    state: Optional[str] = Query(None, description="Filter by state"),
+    topic: Optional[str] = Query(None, description="Filter by topic"),
+    limit: int = Query(50, description="Number of documents to grade")
+):
+    """
+    Grade multiple government decisions using debate framework.
+    
+    Returns aggregate insights about decision quality across dimensions.
+    """
+    try:
+        from agents.debate_grader import DebateGraderAgent
+        from agents.base import AgentMessage, MessageType, AgentRole
+        
+        grader = DebateGraderAgent()
+        
+        # Get documents to grade
+        documents = pipeline.query_opportunities_by_state(state, None)
+        
+        if topic:
+            documents = [d for d in documents if d.get("topic") == topic]
+        
+        documents = documents[:limit]
+        
+        # Create message and process
+        message = AgentMessage(
+            message_id=f"batch_grade_{datetime.utcnow().timestamp()}",
+            sender=AgentRole.ORCHESTRATOR,
+            recipient=AgentRole.DEBATE_GRADER,
+            message_type=MessageType.COMMAND,
+            payload={"documents": documents}
+        )
+        
+        result = await grader.process(message)
+        graded_documents = result[0].payload.get("documents", [])
+        insights = result[0].payload.get("insights", {})
+        
+        return {
+            "graded_count": len(graded_documents),
+            "documents": graded_documents,
+            "insights": insights,
+            "explanation": {
+                "average_scores": "Average scores across all three debate dimensions (out of 5)",
+                "strongest_dimension": "Which dimension governments perform best on",
+                "weakest_dimension": "Which dimension needs the most improvement"
+            }
+        }
+        
+    except Exception as e:
+        logger.error(f"Batch debate grading error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.on_event("startup")
+async def startup_event():
+    """Initialize system on startup with data validation."""
+    logger.info("="*80)
+    logger.info("🚀 STARTING Open Navigator API")
+    logger.info("="*80)
+    logger.info(f"Configuration: {settings.catalog_name}.{settings.schema_name}")
+    logger.info(f"Log Level: {settings.log_level}")
+    logger.info(f"Log File: {settings.log_file}")
+    
+    # Check if running on HuggingFace Spaces
+    IS_HF_SPACES = os.getenv("HF_SPACES") == "1"
+    if IS_HF_SPACES:
+        logger.info(f"🤗 Running on HuggingFace Spaces")
+    else:
+        logger.info(f"💻 Running in local/standard environment")
+    
+    # Validate critical data files
+    logger.info("")
+    logger.info("📊 VALIDATING DATA AVAILABILITY...")
+    logger.info("-" * 80)
+    
+    data_dir = Path("data/gold")
+    critical_files = []
+    optional_files = []
+    
+    # Check reference data (critical)
+    reference_checks = [
+        "reference/jurisdictions_cities.parquet",
+        "reference/jurisdictions_counties.parquet",
+        "reference/causes_ntee_codes.parquet",
+    ]
+    
+    for file_pattern in reference_checks:
+        file_path = data_dir / file_pattern
+        if file_path.exists():
+            size_mb = file_path.stat().st_size / (1024 * 1024)
+            try:
+                import pandas as pd
+                df = pd.read_parquet(file_path)
+                logger.info(f"  ✅ {file_pattern}: {len(df):,} records ({size_mb:.2f} MB)")
+                critical_files.append(file_pattern)
+            except Exception as e:
+                logger.error(f"  ❌ {file_pattern}: ERROR - {e}")
+        else:
+            logger.warning(f"  ⚠️  {file_pattern}: NOT FOUND")
+    
+    # Check state data (optional - shows what's available)
+    logger.info("")
+    logger.info("📍 STATE DATA AVAILABILITY:")
+    
+    states_dir = data_dir / "states"
+    if states_dir.exists():
+        state_dirs = sorted([d for d in states_dir.iterdir() if d.is_dir()])
+        states_with_data = []
+        
+        for state_dir in state_dirs[:10]:  # Show first 10 states
+            state = state_dir.name
+            files_found = []
+            
+            # Check for key files
+            key_files = [
+                "nonprofits_organizations.parquet",
+                "contacts_officials.parquet",
+                "events.parquet",
+            ]
+            
+            for filename in key_files:
+                file_path = state_dir / filename
+                if file_path.exists():
+                    files_found.append(filename.split('.')[0].split('_')[-1])
+            
+            if files_found:
+                logger.info(f"  ✅ {state}: {', '.join(files_found)}")
+                states_with_data.append(state)
+        
+        total_states = len(state_dirs)
+        if total_states > 10:
+            logger.info(f"  ... and {total_states - 10} more states")
+        
+        logger.info(f"")
+        logger.info(f"  📊 Total states with data: {total_states}")
+    else:
+        logger.warning("  ⚠️  No state data directory found")
+    
+    # Validate HuggingFace datasets if running on HF Spaces
+    if IS_HF_SPACES:
+        logger.info("")
+        logger.info("🤗 VALIDATING HUGGINGFACE DATASETS...")
+        logger.info("-" * 80)
+        
+        # Check a sample of critical datasets
+        import requests
+        from api.routes.bills import get_hf_dataset_url
+        
+        test_datasets = [
+            ("states-ma-bills-bills", "Massachusetts Bills"),
+            ("states-al-bills-bills", "Alabama Bills"),
+            ("states-ma-contacts-local-officials", "Massachusetts Local Officials"),
+        ]
+        
+        hf_datasets_ok = 0
+        for dataset_name, display_name in test_datasets:
+            url = get_hf_dataset_url(dataset_name)
+            try:
+                response = requests.head(url, timeout=10, allow_redirects=True)
+                if response.status_code == 200:
+                    logger.info(f"  ✅ {display_name}: Accessible")
+                    hf_datasets_ok += 1
+                else:
+                    logger.error(f"  ❌ {display_name}: HTTP {response.status_code}")
+                    logger.error(f"     URL: {url}")
+            except Exception as e:
+                logger.error(f"  ❌ {display_name}: {type(e).__name__} - {e}")
+                logger.error(f"     URL: {url}")
+        
+        logger.info("")
+        logger.info(f"  📊 HuggingFace datasets validated: {hf_datasets_ok}/{len(test_datasets)}")
+        
+        if hf_datasets_ok < len(test_datasets):
+            logger.warning("  ⚠️  Some datasets are not accessible - API may have limited functionality")
+    
+    logger.info("")
+    logger.info("="*80)
+    logger.info(f"✅ API READY - {len(critical_files)}/{len(reference_checks)} critical files available")
+    if IS_HF_SPACES:
+        logger.info(f"✅ HuggingFace datasets validated")
+    logger.info("="*80)
+    logger.info("")
+
+
+# Shutdown event
+@app.on_event("shutdown")
+async def shutdown_event():
+    """Cleanup on shutdown."""
+    logger.info("Shutting down Oral Health Policy Pulse API")
+
+
+if __name__ == "__main__":
+    import uvicorn
+    
+    uvicorn.run(
+        app,
+        host=settings.api_host,
+        port=settings.api_port,
+        workers=settings.api_workers
+    )

api/models.py

@@ -0,0 +1,268 @@
+"""
+Database models for authentication, user management, and social features
+"""
+from datetime import datetime
+from sqlalchemy import Column, Integer, String, DateTime, Boolean, Text, ForeignKey, UniqueConstraint, Float
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.orm import relationship
+
+Base = declarative_base()
+
+
+class User(Base):
+    """User account model"""
+    __tablename__ = "users"
+
+    id = Column(Integer, primary_key=True, index=True)
+    email = Column(String(255), unique=True, index=True, nullable=False)
+    username = Column(String(100), unique=True, index=True, nullable=True)
+    full_name = Column(String(255), nullable=True)
+    avatar_url = Column(String(500), nullable=True)
+    
+    # OAuth provider info
+    oauth_provider = Column(String(50), nullable=True)  # 'huggingface', 'google', 'facebook', 'github'
+    oauth_id = Column(String(255), nullable=True)  # Provider-specific user ID
+    
+    # Authentication
+    hashed_password = Column(String(255), nullable=True)  # For email/password (optional)
+    is_active = Column(Boolean, default=True)
+    is_verified = Column(Boolean, default=False)
+    
+    # Location preferences
+    state = Column(String(100), nullable=True)  # US State
+    county = Column(String(100), nullable=True)  # County
+    city = Column(String(100), nullable=True)  # City
+    school_board = Column(String(255), nullable=True)  # School board/district
+    
+    # Profile completion
+    profile_completed = Column(Boolean, default=False)
+    
+    # Timestamps
+    created_at = Column(DateTime, default=datetime.utcnow)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+    last_login = Column(DateTime, nullable=True)
+    
+    # User preferences (JSON stored as text)
+    preferences = Column(Text, nullable=True)
+    
+    def __repr__(self):
+        return f"<User {self.email}>"
+
+
+class OAuthState(Base):
+    """Temporary storage for OAuth state tokens (CSRF protection)"""
+    __tablename__ = "oauth_states"
+    
+    id = Column(Integer, primary_key=True, index=True)
+    state_token = Column(String(255), unique=True, index=True, nullable=False)
+    provider = Column(String(50), nullable=False)
+    redirect_uri = Column(String(500), nullable=True)
+    created_at = Column(DateTime, default=datetime.utcnow)
+    expires_at = Column(DateTime, nullable=False)
+    
+    def __repr__(self):
+        return f"<OAuthState {self.provider} - {self.state_token[:8]}...>"
+
+
+# ============================================================================
+# SOCIAL FEATURES MODELS
+# ============================================================================
+
+class Organization(Base):
+    """Organizations (nonprofits, charities, government agencies, advocacy groups)"""
+    __tablename__ = "organizations"
+    
+    id = Column(Integer, primary_key=True, index=True)
+    name = Column(String(255), nullable=False, index=True)
+    slug = Column(String(255), unique=True, index=True, nullable=False)  # URL-friendly identifier
+    description = Column(Text, nullable=True)
+    logo_url = Column(String(500), nullable=True)
+    website = Column(String(500), nullable=True)
+    
+    # Organization type
+    org_type = Column(String(50), nullable=True)  # 'nonprofit', 'government', 'advocacy', 'charity'
+    
+    # Location
+    state = Column(String(100), nullable=True)
+    county = Column(String(100), nullable=True)
+    city = Column(String(100), nullable=True)
+    address = Column(Text, nullable=True)
+    
+    # Contact
+    email = Column(String(255), nullable=True)
+    phone = Column(String(50), nullable=True)
+    
+    # Nonprofit-specific (from IRS/ProPublica)
+    ein = Column(String(20), nullable=True, index=True)  # Employer Identification Number
+    ntee_code = Column(String(10), nullable=True)  # National Taxonomy of Exempt Entities
+    revenue = Column(Float, nullable=True)
+    
+    # Social stats
+    follower_count = Column(Integer, default=0)
+    
+    # Verification
+    is_verified = Column(Boolean, default=False)
+    verified_at = Column(DateTime, nullable=True)
+    
+    # Timestamps
+    created_at = Column(DateTime, default=datetime.utcnow)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+    
+    def __repr__(self):
+        return f"<Organization {self.name}>"
+
+
+class Cause(Base):
+    """Causes/Topics/Issues (oral health, housing, education, climate, etc.)"""
+    __tablename__ = "causes"
+    
+    id = Column(Integer, primary_key=True, index=True)
+    name = Column(String(255), nullable=False, index=True)
+    slug = Column(String(255), unique=True, index=True, nullable=False)
+    description = Column(Text, nullable=True)
+    icon_url = Column(String(500), nullable=True)
+    color = Column(String(7), nullable=True)  # Hex color code
+    
+    # Category
+    category = Column(String(100), nullable=True)  # 'health', 'education', 'housing', 'environment', etc.
+    
+    # Social stats
+    follower_count = Column(Integer, default=0)
+    
+    # Timestamps
+    created_at = Column(DateTime, default=datetime.utcnow)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+    
+    def __repr__(self):
+        return f"<Cause {self.name}>"
+
+
+class Official(Base):
+    """Public officials (elected, appointed) - renamed from Leader to match OpenStates"""
+    __tablename__ = "officials"
+    
+    id = Column(Integer, primary_key=True, index=True)
+    ocd_person_id = Column(String(255), unique=True, index=True, nullable=True)  # OpenCivicData ID
+    name = Column(String(255), nullable=False, index=True)
+    slug = Column(String(255), unique=True, index=True, nullable=False)
+    family_name = Column(String(100), nullable=True)
+    given_name = Column(String(100), nullable=True)
+    sort_name = Column(String(255), nullable=True)
+    
+    # Bio and presentation
+    title = Column(String(255), nullable=True)  # 'Mayor', 'State Senator', 'City Council Member'
+    bio = Column(Text, nullable=True)
+    photo_url = Column(String(500), nullable=True)
+    gender = Column(String(20), nullable=True)
+    birth_date = Column(DateTime, nullable=True)
+    
+    # Current role (primary position)
+    position_type = Column(String(100), nullable=True)  # 'elected', 'appointed'
+    office = Column(String(255), nullable=True)  # 'Office of the Mayor', 'State Senate District 12'
+    party = Column(String(100), nullable=True)  # 'Democratic', 'Republican', 'Independent'
+    chamber = Column(String(50), nullable=True)  # 'upper', 'lower', 'executive'
+    district = Column(String(50), nullable=True)  # District number or name
+    
+    # Location/Jurisdiction
+    state = Column(String(100), nullable=True)
+    county = Column(String(100), nullable=True)
+    city = Column(String(100), nullable=True)
+    jurisdiction = Column(String(255), nullable=True)
+    
+    # Contact
+    email = Column(String(255), nullable=True)
+    phone = Column(String(50), nullable=True)
+    website = Column(String(500), nullable=True)
+    
+    # Social media
+    twitter = Column(String(255), nullable=True)
+    linkedin = Column(String(255), nullable=True)
+    facebook = Column(String(255), nullable=True)
+    
+    # Social stats
+    follower_count = Column(Integer, default=0)
+    
+    # Verification
+    is_verified = Column(Boolean, default=False)
+    verified_at = Column(DateTime, nullable=True)
+    
+    # Term dates
+    term_start_date = Column(DateTime, nullable=True)
+    term_end_date = Column(DateTime, nullable=True)
+    is_current = Column(Boolean, default=True)
+    
+    # Timestamps
+    created_at = Column(DateTime, default=datetime.utcnow)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+    
+    def __repr__(self):
+        return f"<Official {self.name}>"
+
+
+# ============================================================================
+# FOLLOW RELATIONSHIPS (Many-to-Many)
+# ============================================================================
+
+class UserFollow(Base):
+    """User following another user"""
+    __tablename__ = "user_follows"
+    __table_args__ = (
+        UniqueConstraint('follower_id', 'following_id', name='unique_user_follow'),
+    )
+    
+    id = Column(Integer, primary_key=True, index=True)
+    follower_id = Column(Integer, ForeignKey('users.id', ondelete='CASCADE'), nullable=False, index=True)
+    following_id = Column(Integer, ForeignKey('users.id', ondelete='CASCADE'), nullable=False, index=True)
+    created_at = Column(DateTime, default=datetime.utcnow)
+    
+    def __repr__(self):
+        return f"<UserFollow {self.follower_id} -> {self.following_id}>"
+
+
+class OfficialFollow(Base):
+    """User following an official (renamed from LeaderFollow)"""
+    __tablename__ = "official_follows"
+    __table_args__ = (
+        UniqueConstraint('user_id', 'official_id', name='unique_official_follow'),
+    )
+    
+    id = Column(Integer, primary_key=True, index=True)
+    user_id = Column(Integer, ForeignKey('users.id', ondelete='CASCADE'), nullable=False, index=True)
+    official_id = Column(Integer, ForeignKey('officials.id', ondelete='CASCADE'), nullable=False, index=True)
+    created_at = Column(DateTime, default=datetime.utcnow)
+    
+    def __repr__(self):
+        return f"<OfficialFollow user:{self.user_id} -> official:{self.official_id}>"
+
+
+class OrganizationFollow(Base):
+    """User following an organization"""
+    __tablename__ = "organization_follows"
+    __table_args__ = (
+        UniqueConstraint('user_id', 'organization_id', name='unique_org_follow'),
+    )
+    
+    id = Column(Integer, primary_key=True, index=True)
+    user_id = Column(Integer, ForeignKey('users.id', ondelete='CASCADE'), nullable=False, index=True)
+    organization_id = Column(Integer, ForeignKey('organizations.id', ondelete='CASCADE'), nullable=False, index=True)
+    created_at = Column(DateTime, default=datetime.utcnow)
+    
+    def __repr__(self):
+        return f"<OrganizationFollow user:{self.user_id} -> org:{self.organization_id}>"
+
+
+class CauseFollow(Base):
+    """User following a cause/topic"""
+    __tablename__ = "cause_follows"
+    __table_args__ = (
+        UniqueConstraint('user_id', 'cause_id', name='unique_cause_follow'),
+    )
+    
+    id = Column(Integer, primary_key=True, index=True)
+    user_id = Column(Integer, ForeignKey('users.id', ondelete='CASCADE'), nullable=False, index=True)
+    cause_id = Column(Integer, ForeignKey('causes.id', ondelete='CASCADE'), nullable=False, index=True)
+    created_at = Column(DateTime, default=datetime.utcnow)
+    
+    def __repr__(self):
+        return f"<CauseFollow user:{self.user_id} -> cause:{self.cause_id}>"
+

api/routes/__init__.py

@@ -0,0 +1,3 @@
+"""
+API routes package
+"""

api/routes/auth.py

@@ -0,0 +1,436 @@
+"""
+OAuth authentication routes - HuggingFace, Google, Facebook, GitHub
+"""
+import os
+import httpx
+from datetime import datetime, timedelta
+from typing import Optional
+from urllib.parse import urlencode
+from dotenv import load_dotenv
+
+from fastapi import APIRouter, Depends, HTTPException, Request, status
+from fastapi.responses import RedirectResponse
+from sqlalchemy.orm import Session
+from pydantic import BaseModel
+
+from api.database import get_db
+from api.models import User, OAuthState
+from api.auth import create_access_token, generate_state_token
+
+# Load environment variables from .env file
+load_dotenv()
+
+router = APIRouter(prefix="/auth", tags=["authentication"])
+
+# OAuth provider configurations
+OAUTH_PROVIDERS = {
+    'huggingface': {
+        'authorize_url': 'https://huggingface.co/oauth/authorize',
+        'token_url': 'https://huggingface.co/oauth/token',
+        'userinfo_url': 'https://huggingface.co/api/whoami-v2',
+        'scope': 'openid profile email',
+        'client_id_env': 'HUGGINGFACE_CLIENT_ID',
+        'client_secret_env': 'HUGGINGFACE_CLIENT_SECRET',
+    },
+    'google': {
+        'authorize_url': 'https://accounts.google.com/o/oauth2/v2/auth',
+        'token_url': 'https://oauth2.googleapis.com/token',
+        'userinfo_url': 'https://www.googleapis.com/oauth2/v2/userinfo',
+        'scope': 'openid email profile',
+        'client_id_env': 'GOOGLE_CLIENT_ID',
+        'client_secret_env': 'GOOGLE_CLIENT_SECRET',
+    },
+    'facebook': {
+        'authorize_url': 'https://www.facebook.com/v18.0/dialog/oauth',
+        'token_url': 'https://graph.facebook.com/v18.0/oauth/access_token',
+        'userinfo_url': 'https://graph.facebook.com/me?fields=id,name,email,picture',
+        'scope': 'email public_profile',
+        'client_id_env': 'FACEBOOK_APP_ID',
+        'client_secret_env': 'FACEBOOK_APP_SECRET',
+    },
+    'github': {
+        'authorize_url': 'https://github.com/login/oauth/authorize',
+        'token_url': 'https://github.com/login/oauth/access_token',
+        'userinfo_url': 'https://api.github.com/user',
+        'scope': 'user:email',
+        'client_id_env': 'GITHUB_CLIENT_ID',
+        'client_secret_env': 'GITHUB_CLIENT_SECRET',
+    },
+}
+
+
+# Response models
+class TokenResponse(BaseModel):
+    access_token: str
+    token_type: str = "bearer"
+    user: dict
+
+
+class UserResponse(BaseModel):
+    id: int
+    email: str
+    username: Optional[str]
+    full_name: Optional[str]
+    avatar_url: Optional[str]
+    oauth_provider: Optional[str]
+    state: Optional[str]
+    county: Optional[str]
+    city: Optional[str]
+    school_board: Optional[str]
+    profile_completed: Optional[bool]
+
+
+# Helper functions
+def get_or_create_user(
+    db: Session,
+    email: str,
+    provider: str,
+    oauth_id: str,
+    full_name: Optional[str] = None,
+    avatar_url: Optional[str] = None,
+    username: Optional[str] = None,
+) -> User:
+    """Get existing user or create new one from OAuth data"""
+    
+    # Try to find existing user by OAuth ID first
+    user = db.query(User).filter(
+        User.oauth_provider == provider,
+        User.oauth_id == oauth_id
+    ).first()
+    
+    if user:
+        # Update user info if changed
+        user.full_name = full_name or user.full_name
+        user.avatar_url = avatar_url or user.avatar_url
+        user.username = username or user.username
+        user.last_login = datetime.utcnow()
+        db.commit()
+        return user
+    
+    # Try to find by email
+    user = db.query(User).filter(User.email == email).first()
+    
+    if user:
+        # Link OAuth account to existing user
+        user.oauth_provider = provider
+        user.oauth_id = oauth_id
+        user.full_name = full_name or user.full_name
+        user.avatar_url = avatar_url or user.avatar_url
+        user.username = username or user.username
+        user.last_login = datetime.utcnow()
+        user.is_verified = True  # OAuth emails are verified
+        db.commit()
+        return user
+    
+    # Create new user
+    user = User(
+        email=email,
+        username=username,
+        full_name=full_name,
+        avatar_url=avatar_url,
+        oauth_provider=provider,
+        oauth_id=oauth_id,
+        is_verified=True,
+        is_active=True,
+        last_login=datetime.utcnow(),
+    )
+    db.add(user)
+    db.commit()
+    db.refresh(user)
+    return user
+
+
+# OAuth routes
+@router.get("/login/{provider}")
+async def oauth_login(
+    provider: str,
+    request: Request,
+    db: Session = Depends(get_db),
+    redirect_uri: Optional[str] = None
+):
+    """
+    Initiate OAuth login flow
+    
+    Supported providers: huggingface, google, facebook, github
+    """
+    if provider not in OAUTH_PROVIDERS:
+        raise HTTPException(status_code=400, detail=f"Unsupported provider: {provider}")
+    
+    config = OAUTH_PROVIDERS[provider]
+    client_id = os.getenv(config['client_id_env'])
+    
+    if not client_id:
+        raise HTTPException(
+            status_code=500, 
+            detail=f"OAuth not configured for {provider}. Missing {config['client_id_env']}"
+        )
+    
+    # Generate state token for CSRF protection
+    state = generate_state_token()
+    
+    # Store state in database
+    oauth_state = OAuthState(
+        state_token=state,
+        provider=provider,
+        redirect_uri=redirect_uri,
+        expires_at=datetime.utcnow() + timedelta(minutes=10),
+    )
+    db.add(oauth_state)
+    db.commit()
+    
+    # Build callback URL using API_BASE_URL to ensure correct protocol (http vs https)
+    base_url = os.getenv('API_BASE_URL', 'http://localhost:8000')
+    callback_url = f"{base_url}/auth/callback/{provider}"
+    
+    # Build authorization URL
+    params = {
+        'client_id': client_id,
+        'redirect_uri': callback_url,
+        'scope': config['scope'],
+        'state': state,
+        'response_type': 'code',
+    }
+    
+    auth_url = f"{config['authorize_url']}?{urlencode(params)}"
+    return RedirectResponse(url=auth_url)
+
+
+@router.get("/callback/{provider}", name="oauth_callback")
+async def oauth_callback(
+    provider: str,
+    code: Optional[str] = None,
+    state: Optional[str] = None,
+    error: Optional[str] = None,
+    db: Session = Depends(get_db)
+):
+    """OAuth callback handler"""
+    
+    if error:
+        raise HTTPException(status_code=400, detail=f"OAuth error: {error}")
+    
+    if not code or not state:
+        raise HTTPException(status_code=400, detail="Missing code or state parameter")
+    
+    if provider not in OAUTH_PROVIDERS:
+        raise HTTPException(status_code=400, detail=f"Unsupported provider: {provider}")
+    
+    # Verify state token
+    oauth_state = db.query(OAuthState).filter(
+        OAuthState.state_token == state,
+        OAuthState.provider == provider
+    ).first()
+    
+    if not oauth_state or oauth_state.expires_at < datetime.utcnow():
+        raise HTTPException(status_code=400, detail="Invalid or expired state token")
+    
+    config = OAUTH_PROVIDERS[provider]
+    client_id = os.getenv(config['client_id_env'])
+    client_secret = os.getenv(config['client_secret_env'])
+    
+    # Build callback URL (must match the one sent to authorize)
+    from fastapi import Request
+    # We need to reconstruct the callback URL - for now use a simple approach
+    base_url = os.getenv('API_BASE_URL', 'http://localhost:8000')
+    callback_url = f"{base_url}/auth/callback/{provider}"
+    
+    # Exchange code for access token
+    async with httpx.AsyncClient() as client:
+        token_response = await client.post(
+            config['token_url'],
+            data={
+                'client_id': client_id,
+                'client_secret': client_secret,
+                'code': code,
+                'redirect_uri': callback_url,
+                'grant_type': 'authorization_code',
+            },
+            headers={'Accept': 'application/json'}
+        )
+        
+        if token_response.status_code != 200:
+            raise HTTPException(
+                status_code=400, 
+                detail=f"Token exchange failed: {token_response.text}"
+            )
+        
+        token_data = token_response.json()
+        access_token = token_data.get('access_token')
+        
+        if not access_token:
+            raise HTTPException(status_code=400, detail="No access token received")
+        
+        # Get user info from provider
+        user_info = await get_user_info(provider, access_token, config)
+    
+    if not user_info or not user_info.get('email'):
+        raise HTTPException(status_code=400, detail="Could not retrieve user email from provider")
+    
+    # Get or create user
+    user = get_or_create_user(
+        db=db,
+        email=user_info['email'],
+        provider=provider,
+        oauth_id=user_info['oauth_id'],
+        full_name=user_info.get('full_name'),
+        avatar_url=user_info.get('avatar_url'),
+        username=user_info.get('username'),
+    )
+    
+    # Clean up state token
+    db.delete(oauth_state)
+    db.commit()
+    
+    # Create JWT token (sub must be string, not int)
+    jwt_token = create_access_token(data={"sub": str(user.id)})
+    
+    # Redirect to frontend with token
+    # On HuggingFace/production, frontend and backend are same domain - use relative path
+    # On local dev, frontend is separate server - use FRONTEND_URL
+    frontend_url = os.getenv('FRONTEND_URL', '')
+    
+    # If FRONTEND_URL is localhost or not set, assume same-domain deployment (HuggingFace)
+    if not frontend_url or 'localhost' in frontend_url:
+        # Use relative redirect (works on HuggingFace where both are same domain)
+        redirect_url = oauth_state.redirect_uri or '/'
+    else:
+        # Use absolute URL for separate frontend server
+        redirect_url = oauth_state.redirect_uri or frontend_url
+    
+    # Append token as URL parameter
+    params = urlencode({'token': jwt_token})
+    full_redirect_url = f"{redirect_url}?{params}" if '?' not in redirect_url else f"{redirect_url}&{params}"
+    
+    return RedirectResponse(url=full_redirect_url)
+
+
+async def get_user_info(provider: str, access_token: str, config: dict) -> dict:
+    """Get user information from OAuth provider"""
+    
+    async with httpx.AsyncClient() as client:
+        headers = {'Authorization': f'Bearer {access_token}'}
+        
+        user_info = {}
+        
+        if provider == 'huggingface':
+            resp = await client.get(config['userinfo_url'], headers=headers)
+            data = resp.json()
+            user_info = {
+                'email': data.get('email'),
+                'oauth_id': str(data.get('id')),
+                'full_name': data.get('fullname') or data.get('name'),
+                'avatar_url': data.get('avatarUrl'),
+                'username': data.get('name'),
+            }
+        
+        elif provider == 'google':
+            resp = await client.get(config['userinfo_url'], headers=headers)
+            data = resp.json()
+            user_info = {
+                'email': data.get('email'),
+                'oauth_id': data.get('id'),
+                'full_name': data.get('name'),
+                'avatar_url': data.get('picture'),
+                'username': data.get('email', '').split('@')[0],
+            }
+        
+        elif provider == 'facebook':
+            resp = await client.get(config['userinfo_url'], headers={'Authorization': f'Bearer {access_token}'})
+            data = resp.json()
+            user_info = {
+                'email': data.get('email'),
+                'oauth_id': str(data.get('id')),
+                'full_name': data.get('name'),
+                'avatar_url': data.get('picture', {}).get('data', {}).get('url') if isinstance(data.get('picture'), dict) else None,
+                'username': data.get('name', '').replace(' ', '_').lower(),
+            }
+        
+        elif provider == 'github':
+            # Get user profile
+            resp = await client.get(config['userinfo_url'], headers=headers)
+            data = resp.json()
+            
+            # Get user email if not public
+            email = data.get('email')
+            if not email:
+                resp_emails = await client.get('https://api.github.com/user/emails', headers=headers)
+                emails = resp_emails.json()
+                email = next((e['email'] for e in emails if e.get('primary')), emails[0]['email'] if emails else None)
+            
+            user_info = {
+                'email': email,
+                'oauth_id': str(data.get('id')),
+                'full_name': data.get('name'),
+                'avatar_url': data.get('avatar_url'),
+                'username': data.get('login'),
+            }
+        
+        return user_info
+
+
+@router.get("/me", response_model=UserResponse)
+def get_current_user_info(
+    request: Request,
+    db: Session = Depends(get_db)
+):
+    """Get current authenticated user info"""
+    
+    # Get token from Authorization header
+    auth_header = request.headers.get('Authorization')
+    if not auth_header or not auth_header.startswith('Bearer '):
+        raise HTTPException(status_code=401, detail="Not authenticated")
+    
+    token = auth_header.split(' ')[1]
+    
+    # Decode token and get user
+    from api.auth import decode_access_token
+    payload = decode_access_token(token)
+    user_id = int(payload.get('sub'))  # Convert back to int for DB query
+    
+    user = db.query(User).filter(User.id == user_id).first()
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+    
+    return user
+
+
+@router.patch("/profile", response_model=UserResponse)
+def update_user_profile(
+    profile_data: dict,
+    request: Request,
+    db: Session = Depends(get_db)
+):
+    """Update user profile (location preferences)"""
+    
+    # Get token from Authorization header
+    auth_header = request.headers.get('Authorization')
+    if not auth_header or not auth_header.startswith('Bearer '):
+        raise HTTPException(status_code=401, detail="Not authenticated")
+    
+    token = auth_header.split(' ')[1]
+    
+    # Decode token and get user
+    from api.auth import decode_access_token
+    payload = decode_access_token(token)
+    user_id = int(payload.get('sub'))
+    
+    user = db.query(User).filter(User.id == user_id).first()
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+    
+    # Update allowed fields
+    allowed_fields = ['state', 'county', 'city', 'school_board', 'profile_completed']
+    for field, value in profile_data.items():
+        if field in allowed_fields and hasattr(user, field):
+            setattr(user, field, value)
+    
+    user.updated_at = datetime.utcnow()
+    db.commit()
+    db.refresh(user)
+    
+    return user
+
+
+@router.post("/logout")
+def logout():
+    """Logout endpoint (client-side token removal)"""
+    return {"message": "Logged out successfully. Please remove the token from client."}

api/routes/bills.py

@@ -0,0 +1,841 @@
+"""
+Bills API Routes - Legislative bill data from OpenStates
+"""
+from fastapi import APIRouter, Query, HTTPException
+from fastapi.responses import JSONResponse
+from typing import Optional, List, Dict
+import duckdb
+import pandas as pd
+from pathlib import Path
+from loguru import logger
+import re
+import os
+import sys
+import traceback
+
+from api.errors import ErrorDetail, parse_error
+from api.routes.search import load_parquet_cached
+
+router = APIRouter(prefix="/api/bills", tags=["bills"])
+
+GOLD_DIR = Path("data/gold")
+IS_HF_SPACES = os.getenv("HF_SPACES") == "1"
+HF_ORGANIZATION = "CommunityOne"
+
+def get_hf_dataset_url(dataset_name: str) -> str:
+    """
+    Convert dataset name to HuggingFace parquet URL.
+    
+    HuggingFace Datasets library stores parquet files in the standard format:
+    data/train-00000-of-00001.parquet
+    
+    Args:
+        dataset_name: Dataset name (e.g., 'states-ma-bills-bills')
+    
+    Returns:
+        Full URL to the parquet file
+    """
+    return f"https://huggingface.co/datasets/{HF_ORGANIZATION}/{dataset_name}/resolve/main/data/train-00000-of-00001.parquet"
+
+def get_data_source(file_path: Path, use_remote: bool = False) -> str:
+    """Get data source (local path or remote URL) based on environment."""
+    if not IS_HF_SPACES and not use_remote:
+        return str(file_path)
+    
+    # Convert local path to HuggingFace dataset name
+    parts = file_path.parts
+    
+    if 'states' in parts:
+        state_idx = parts.index('states')
+        state = parts[state_idx + 1].lower()
+        filename = parts[-1].replace('.parquet', '').replace('_', '-')
+        dataset_name = f"states-{state}-{filename}"
+        return get_hf_dataset_url(dataset_name)
+    
+    # Fallback to local
+    return str(file_path)
+
+
+def classify_bill_type(title: str, classification: list, topic: Optional[str] = None) -> str:
+    """
+    Classify bill based on topic-specific categories.
+    
+    Different topics use different classification schemes:
+    - Fluoridation: mandate, removal, funding, study
+    - Dental/Oral Health: coverage_expansion, screening, provider_access, funding
+    - Medicaid: expansion, coverage, reimbursement, eligibility
+    - Health (general): protection, restriction, funding, reform
+    - Education: requirement, funding, curriculum, reform
+    - Default: support, oppose, regulate, other
+    """
+    title_lower = title.lower()
+    topic_lower = topic.lower() if topic else ""
+    
+    # EXCEPTION: Fluoride varnish/dental coverage bills (not water fluoridation)
+    # Check this BEFORE water fluoridation classification
+    if any(word in title_lower for word in ['varnish', 'sealant', 'dental', 'medicaid', 'medical assistance']) and 'fluoride' in title_lower:
+        if any(word in title_lower for word in ['coverage', 'expand', 'expansion', 'benefit']):
+            return 'coverage_expansion'
+        elif any(word in title_lower for word in ['screening', 'examination', 'check']):
+            return 'screening'
+        # If it mentions dental/varnish but unclear type, it's dental "other" not fluoridation
+        return 'other'
+    
+    # Fluoridation-specific classifications (WATER fluoridation only)
+    if 'fluoride' in topic_lower or 'fluoride' in title_lower:
+        # FIRST: Check for REMOVAL/BAN/PROHIBITION (negative sentiment)
+        # CRITICAL: Must check these BEFORE "mandate"/"require" to avoid misclassification
+        # e.g., "prohibit fluoride" should be "removal", not "mandate"
+        if any(word in title_lower for word in [
+            'prohibit', 'prohibition', 'prohibited', 'prohibiting',
+            'ban', 'banning', 'banned',
+            'discontinue', 'discontinuation',
+            'cease', 'ceasing',
+            'eliminate', 'elimination',
+            'removal', 'remove', 'removing',
+            'prevent', 'preventing',
+            'repeal', 'repealing', 'repealed',
+            'optional', 'opt-out', 'opt out',
+            'fluoride-free', 'fluoride free'
+        ]):
+            # But check if it's "prohibit removal" (double negative = pro-fluoride)
+            if any(phrase in title_lower for phrase in ['prohibit removal', 'prevent removal', 'ban removal']):
+                return 'mandate'  # Prohibiting removal = mandate to keep
+            return 'removal'
+        
+        # SECOND: Check for notification/monitoring (before "require" check)
+        # Bills like "notification required" are about monitoring, not mandating fluoridation
+        elif any(phrase in title_lower for phrase in [
+            'notification', 'notify', 'notifying',
+            'report to', 'reporting', 'report when',
+            'monitor', 'monitoring'
+        ]):
+            return 'study'
+        
+        # THIRD: Check for MANDATE/REQUIRE (positive sentiment)
+        # Be specific - just "require" alone isn't enough, need context
+        elif any(phrase in title_lower for phrase in [
+            'mandate', 'mandating', 'shall fluoridate', 'shall add fluoride',
+            'must fluoridate', 'must add fluoride',
+            'require fluoridation', 'require water system to fluoridate',
+            'require addition of fluoride'
+        ]):
+            return 'mandate'
+        
+        # FOURTH: Check for funding
+        elif any(word in title_lower for word in ['fund', 'funding', 'appropriation', 'grant', 'reimburse', 'subsidy']):
+            return 'funding'
+        elif any(word in title_lower for word in ['study', 'research', 'analysis', 'assess', 'evaluate']):
+            return 'study'
+        else:
+            return 'other'
+    
+    # Dental/Oral Health-specific classifications
+    elif 'dental' in topic_lower or 'oral health' in topic_lower or 'dental' in title_lower:
+        if any(word in title_lower for word in ['expand', 'increase coverage', 'extend coverage', 'add coverage']):
+            return 'coverage_expansion'
+        elif any(word in title_lower for word in ['screen', 'examination', 'checkup', 'assessment']):
+            return 'screening'
+        elif any(word in title_lower for word in ['provider', 'dentist', 'hygienist', 'workforce', 'professional']):
+            return 'provider_access'
+        elif any(word in title_lower for word in ['fund', 'appropriation', 'grant', 'budget', 'reimburse']):
+            return 'funding'
+        else:
+            return 'other'
+    
+    # Medicaid-specific classifications
+    elif 'medicaid' in topic_lower or 'medicaid' in title_lower:
+        if any(word in title_lower for word in ['expand', 'expansion', 'extend', 'broaden']):
+            return 'expansion'
+        elif any(word in title_lower for word in ['coverage', 'benefit', 'service']):
+            return 'coverage'
+        elif any(word in title_lower for word in ['reimburse', 'payment', 'rate', 'compensation']):
+            return 'reimbursement'
+        elif any(word in title_lower for word in ['eligib', 'qualify', 'enroll']):
+            return 'eligibility'
+        else:
+            return 'other'
+    
+    # Education-specific classifications
+    elif 'education' in topic_lower or 'school' in topic_lower:
+        if any(word in title_lower for word in ['require', 'mandate', 'shall provide', 'must offer']):
+            return 'requirement'
+        elif any(word in title_lower for word in ['fund', 'appropriation', 'grant', 'budget']):
+            return 'funding'
+        elif any(word in title_lower for word in ['curriculum', 'course', 'instruction', 'program']):
+            return 'curriculum'
+        elif any(word in title_lower for word in ['reform', 'restructure', 'modernize', 'improve']):
+            return 'reform'
+        else:
+            return 'other'
+    
+    # General health classifications
+    elif 'health' in topic_lower or 'health' in title_lower:
+        if any(word in title_lower for word in ['protect', 'preserve', 'safeguard', 'ensure', 'guarantee', 'expand', 'increase', 'enhance', 'support']):
+            return 'protection'
+        elif any(word in title_lower for word in ['restrict', 'limit', 'regulate', 'control', 'impose', 'prohibit', 'ban']):
+            return 'restriction'
+        elif any(word in title_lower for word in ['fund', 'appropriation', 'grant', 'budget']):
+            return 'funding'
+        elif any(word in title_lower for word in ['reform', 'restructure', 'modernize', 'improve']):
+            return 'reform'
+        else:
+            return 'other'
+    
+    # Default general classifications
+    else:
+        if any(word in title_lower for word in ['support', 'promote', 'encourage', 'expand', 'increase', 'enhance', 'fund']):
+            return 'support'
+        elif any(word in title_lower for word in ['oppose', 'prohibit', 'ban', 'restrict', 'limit', 'prevent']):
+            return 'oppose'
+        elif any(word in title_lower for word in ['regulate', 'oversee', 'control', 'require', 'mandate']):
+            return 'regulate'
+        else:
+            return 'other'
+
+
+def get_legend_for_topic(topic: Optional[str]) -> dict:
+    """
+    Get appropriate legend labels based on topic.
+    """
+    topic_lower = topic.lower() if topic else ""
+    
+    if 'fluoride' in topic_lower:
+        return {
+            "mandate": "Mandate Fluoridation",
+            "removal": "Remove Fluoridation",
+            "funding": "Funding/Grants",
+            "study": "Study/Research",
+            "other": "Other"
+        }
+    elif 'dental' in topic_lower or 'oral health' in topic_lower:
+        return {
+            "coverage_expansion": "Coverage Expansion",
+            "screening": "Screening Programs",
+            "provider_access": "Provider Access",
+            "funding": "Funding/Grants",
+            "other": "Other"
+        }
+    elif 'medicaid' in topic_lower:
+        return {
+            "expansion": "Program Expansion",
+            "coverage": "Coverage/Benefits",
+            "reimbursement": "Reimbursement",
+            "eligibility": "Eligibility",
+            "other": "Other"
+        }
+    elif 'education' in topic_lower or 'school' in topic_lower:
+        return {
+            "requirement": "Requirements",
+            "funding": "Funding",
+            "curriculum": "Curriculum",
+            "reform": "Reform",
+            "other": "Other"
+        }
+    elif 'health' in topic_lower:
+        return {
+            "protection": "Protection/Expansion",
+            "restriction": "Restriction",
+            "funding": "Funding",
+            "reform": "Reform",
+            "other": "Other"
+        }
+    else:
+        return {
+            "support": "Support/Promote",
+            "oppose": "Oppose/Restrict",
+            "regulate": "Regulate",
+            "other": "Other"
+        }
+
+
+def determine_bill_status(latest_action: str, latest_date: str) -> str:
+    """
+    Determine if bill was enacted, failed, or is pending.
+    """
+    if not latest_action:
+        return 'pending'
+    
+    action_lower = latest_action.lower()
+    
+    # Enacted/Passed
+    if any(word in action_lower for word in ['signed', 'enacted', 'approved', 'passed both', 'became law']):
+        return 'enacted'
+    
+    # Failed
+    if any(word in action_lower for word in ['failed', 'defeated', 'rejected', 'died', 'withdrawn', 'vetoed']):
+        return 'failed'
+    
+    # Pending (default)
+    return 'pending'
+
+
+@router.get("")
+async def search_bills(
+    q: Optional[str] = Query(None, description="Search query for bill title or number"),
+    state: Optional[str] = Query("AL", description="State code (e.g., AL, GA, MA)"),
+    session: Optional[str] = Query(None, description="Legislative session (e.g., 2024rs)"),
+    limit: int = Query(20, ge=1, le=100, description="Maximum results"),
+    offset: int = Query(0, ge=0, description="Number of results to skip")
+):
+    """
+    Search legislative bills from OpenStates data.
+    
+    **Examples:**
+    - `/api/bills?state=AL&q=dental` - Search Alabama bills for "dental"
+    - `/api/bills?state=AL&session=2024rs` - Get all 2024 regular session bills
+    - `/api/bills?state=AL&limit=50` - Browse recent Alabama bills
+    """
+    try:
+        # Build file path
+        bills_file = GOLD_DIR / "states" / state / "bills_bills.parquet"
+        
+        # Get data source (local or remote HuggingFace URL)
+        data_source = get_data_source(bills_file, use_remote=IS_HF_SPACES)
+        
+        # Connect to DuckDB
+        conn = duckdb.connect()
+        
+        # Build SQL query
+        where_clauses = []
+        params = []
+        
+        if q:
+            where_clauses.append("(LOWER(title) LIKE LOWER(?) OR LOWER(bill_number) LIKE LOWER(?))")
+            pattern = f'%{q}%'
+            params.extend([pattern, pattern])
+        
+        if session:
+            where_clauses.append("session = ?")
+            params.append(session)
+        
+        where_clause = " AND ".join(where_clauses) if where_clauses else "1=1"
+        
+        # Count total
+        count_sql = f"""
+            SELECT COUNT(*) as total
+            FROM read_parquet(?)
+            WHERE {where_clause}
+        """
+        count_params = [data_source] + params
+        total = conn.execute(count_sql, count_params).fetchone()[0]
+        
+        # Fetch bills
+        sql = f"""
+            SELECT 
+                bill_id,
+                bill_number,
+                title,
+                classification,
+                session,
+                session_name,
+                first_action_date,
+                latest_action_date,
+                latest_action_description,
+                jurisdiction_name
+            FROM read_parquet(?)
+            WHERE {where_clause}
+            ORDER BY latest_action_date DESC NULLS LAST, bill_number DESC
+            LIMIT ? OFFSET ?
+        """
+        
+        query_params = [data_source] + params + [limit, offset]
+        rows = conn.execute(sql, query_params).fetchall()
+        
+        bills = []
+        for row in rows:
+            bills.append({
+                "bill_id": row[0],
+                "bill_number": row[1],
+                "title": row[2],
+                "classification": row[3],
+                "session": row[4],
+                "session_name": row[5],
+                "first_action_date": row[6],
+                "latest_action_date": row[7],
+                "latest_action": row[8],
+                "jurisdiction": row[9]
+            })
+        
+        conn.close()
+        
+        return {
+            "total": total,
+            "bills": bills,
+            "pagination": {
+                "limit": limit,
+                "offset": offset,
+                "has_more": offset + len(bills) < total
+            },
+            "filters": {
+                "state": state,
+                "query": q,
+                "session": session
+            }
+        }
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Bills search error for state={state}: {e}")
+        
+        # Parse error into structured response
+        error_detail = parse_error(e, context={
+            "state": state,
+            "data_type": "bills",
+            "query": q,
+            "session": session
+        })
+        
+        # Return structured error response
+        return JSONResponse(
+            status_code=500,
+            content=error_detail.model_dump()
+        )
+
+
+@router.get("/sessions")
+async def get_sessions(
+    state: str = Query("AL", description="State code")
+):
+    """Get available legislative sessions for a state."""
+    try:
+        bills_file = GOLD_DIR / "states" / state / "bills_bills.parquet"
+        
+        if not bills_file.exists():
+            raise HTTPException(
+                status_code=404,
+                detail=f"No bills data found for state: {state}"
+            )
+        
+        conn = duckdb.connect()
+        
+        sql = """
+            SELECT DISTINCT 
+                session,
+                session_name,
+                MIN(first_action_date) as start_date,
+                MAX(latest_action_date) as end_date,
+                COUNT(*) as bill_count
+            FROM read_parquet(?)
+            GROUP BY session, session_name
+            ORDER BY session DESC
+        """
+        
+        rows = conn.execute(sql, [str(bills_file)]).fetchall()
+        
+        sessions = []
+        for row in rows:
+            sessions.append({
+                "session": row[0],
+                "session_name": row[1],
+                "start_date": row[2],
+                "end_date": row[3],
+                "bill_count": row[4]
+            })
+        
+        conn.close()
+        
+        return {
+            "state": state,
+            "sessions": sessions,
+            "total_sessions": len(sessions)
+        }
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Sessions query error for state={state}: {e}")
+        
+        # Parse error into structured response
+        error_detail = parse_error(e, context={
+            "state": state,
+            "data_type": "sessions"
+        })
+        
+        return JSONResponse(
+            status_code=500,
+            content=error_detail.model_dump()
+        )
+
+
+@router.get("/map")
+async def get_bill_map_data(
+    topic: Optional[str] = Query(None, description="Topic to filter (e.g., dental, health, education)"),
+    session: Optional[str] = Query(None, description="Legislative session")
+):
+    """
+    Get aggregated bill data for choropleth map visualization.
+    
+    Uses pre-computed national aggregates for instant loading.
+    Returns counts of bills by type and status for each state.
+    
+    **Examples:**
+    - `/api/bills/map?topic=fluorid` - Map fluoridation legislation
+    - `/api/bills/map?topic=dental` - Map dental legislation  
+    """
+    try:
+        # Use pre-aggregated national dataset
+        agg_file = GOLD_DIR / "national" / "bills_map_aggregates.parquet"
+        
+        # Fallback to on-demand aggregation if pre-computed file doesn't exist
+        if not agg_file.exists():
+            logger.warning("Pre-aggregated bill data not found, using on-demand aggregation (slower)")
+            return await get_bill_map_data_on_demand(topic, session)
+        
+        # Load from cached aggregates (fast!)
+        df = load_parquet_cached(str(agg_file))
+        
+        # Filter by topic
+        if topic:
+            df = df[df['topic'] == topic.lower()]
+        
+        # Convert to state_data dict
+        state_data = {}
+        
+        for _, row in df.iterrows():
+            state_code = row['state']
+            
+            # Reconstruct nested dicts (exclude type_status_counts which is already a dict)
+            type_cols = [c for c in df.columns if c.startswith('type_') and c != 'type_status_counts']
+            status_cols = [c for c in df.columns if c.startswith('status_')]
+            
+            # Handle NaN values - convert to 0
+            type_counts = {c.replace('type_', ''): int(row[c]) if not pd.isna(row[c]) else 0 for c in type_cols}
+            status_counts = {c.replace('status_', ''): int(row[c]) if not pd.isna(row[c]) else 0 for c in status_cols}
+            
+            # Extract sample_bills (stored as numpy array in parquet)
+            sample_bills = []
+            if 'sample_bills' in row.index:
+                bills_data = row['sample_bills']
+                # Pandas stores list columns as numpy arrays
+                if hasattr(bills_data, '__iter__') and not isinstance(bills_data, str):
+                    try:
+                        # Convert numpy array or list to Python list
+                        sample_bills = [dict(bill) for bill in bills_data if bill]
+                    except:
+                        sample_bills = []
+                elif isinstance(bills_data, str):
+                    import json
+                    try:
+                        sample_bills = json.loads(bills_data)
+                    except:
+                        sample_bills = []
+            
+            state_data[state_code] = {
+                "state": state_code,
+                "total_bills": int(row['total_bills']),
+                "type_counts": type_counts,
+                "status_counts": status_counts,
+                "primary_type": row['primary_type'],
+                "primary_status": row['primary_status'],
+                "map_category": row['map_category'],
+                "sample_bills": sample_bills,
+                "last_updated": str(row['last_updated']) if 'last_updated' in row.index else ''
+            }
+        
+        return {
+            "topic": topic,
+            "session": session,
+            "states": state_data,
+            "total_states": len(state_data),
+            "legend": {
+                "types": get_legend_for_topic(topic),
+                "statuses": {
+                    "enacted": "Enacted",
+                    "failed": "Failed",
+                    "pending": "Pending"
+                }
+            },
+            "cached": True
+        }
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Map data error: {e}")
+        
+        error_detail = parse_error(e, context={
+            "data_type": "bill map",
+            "topic": topic,
+            "session": session
+        })
+        
+        return JSONResponse(
+            status_code=500,
+            content=error_detail.model_dump()
+        )
+
+
+async def get_bill_map_data_on_demand(
+    topic: Optional[str] = None,
+    session: Optional[str] = None
+):
+    """
+    LEGACY: On-demand aggregation (slow - loads 50 state files).
+    Only used as fallback if pre-aggregated data doesn't exist.
+    """
+    try:
+        # List of all US state codes to check
+        ALL_STATES = [
+            "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "FL", "GA",
+            "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD",
+            "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ",
+            "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC",
+            "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY"
+        ]
+        
+        # In local environment, check available directories
+        # In HF Spaces, try all states (will skip missing datasets)
+        states_to_check = ALL_STATES
+        if not IS_HF_SPACES:
+            states_dir = GOLD_DIR / "states"
+            if states_dir.exists():
+                states_to_check = [d.name for d in states_dir.iterdir() if d.is_dir()]
+        
+        state_data = {}
+        
+        # Iterate through states
+        for state_code in states_to_check:
+            try:
+                bills_file = GOLD_DIR / "states" / state_code / "bills_bills.parquet"
+                
+                # Get data source (local or remote HuggingFace URL)
+                data_source = get_data_source(bills_file, use_remote=IS_HF_SPACES)
+                
+                # Connect to DuckDB
+                conn = duckdb.connect()
+                
+                # Build query
+                where_clauses = ["1=1"]
+                params = [data_source]
+                
+                if topic:
+                    where_clauses.append("LOWER(title) LIKE LOWER(?)")
+                    params.append(f'%{topic}%')
+                
+                if session:
+                    where_clauses.append("session = ?")
+                    params.append(session)
+                
+                where_clause = " AND ".join(where_clauses)
+                
+                sql = f"""
+                    SELECT 
+                        title,
+                        classification,
+                        latest_action_description
+                    FROM read_parquet(?)
+                    WHERE {where_clause}
+                """
+                
+                rows = conn.execute(sql, params).fetchall()
+                conn.close()
+                
+                if not rows:
+                    continue
+                
+                # Get topic-aware categories
+                legend_categories = get_legend_for_topic(topic)
+                
+                # Initialize type_counts with all possible categories for this topic
+                type_counts = {cat: 0 for cat in legend_categories.keys()}
+                status_counts = {'enacted': 0, 'failed': 0, 'pending': 0}
+                type_status_counts = {}
+                
+                for row in rows:
+                    title = row[0]
+                    classification = row[1] if row[1] else []
+                    latest_action = row[2] if row[2] else ''
+                    
+                    bill_type = classify_bill_type(title, classification, topic)
+                    bill_status = determine_bill_status(latest_action, '')
+                    
+                    # Ensure bill_type exists in type_counts (fallback to 'other')
+                    if bill_type not in type_counts:
+                        bill_type = 'other'
+                    
+                    type_counts[bill_type] += 1
+                    status_counts[bill_status] += 1
+                    
+                    # Track type+status combinations
+                    key = f"{bill_type}_{bill_status}"
+                    type_status_counts[key] = type_status_counts.get(key, 0) + 1
+                
+                # Determine primary legislation type and status for map visualization
+                primary_type = max(type_counts, key=type_counts.get)
+                primary_status = max(status_counts, key=status_counts.get)
+                
+                state_data[state_code] = {
+                    "state": state_code,
+                    "total_bills": len(rows),
+                    "type_counts": type_counts,
+                    "status_counts": status_counts,
+                    "type_status_counts": type_status_counts,
+                    "primary_type": primary_type,
+                    "primary_status": primary_status,
+                    # For map visualization
+                    "map_category": f"{primary_type}_{primary_status}" if type_counts[primary_type] > 0 else "none"
+                }
+                
+            except Exception as e:
+                # Skip states with missing or inaccessible data
+                logger.debug(f"Skipping state {state_code}: {str(e)}")
+                continue
+        
+        return {
+            "topic": topic,
+            "session": session,
+            "states": state_data,
+            "total_states": len(state_data),
+            "legend": {
+                "types": get_legend_for_topic(topic),
+                "statuses": {
+                    "enacted": "Enacted",
+                    "failed": "Failed",
+                    "pending": "Pending"
+                }
+            }
+        }
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Map data error: {e}")
+        
+        # Parse error into structured response
+        error_detail = parse_error(e, context={
+            "data_type": "bill map",
+            "topic": topic,
+            "session": session
+        })
+        
+        return JSONResponse(
+            status_code=500,
+            content=error_detail.model_dump()
+        )
+
+
+@router.get("/{bill_id}")
+async def get_bill_details(bill_id: str):
+    """
+    Get detailed information about a specific bill from gold parquet files.
+    
+    Args:
+        bill_id: Bill identifier in format {state}-{bill_number} (e.g., "LA-SB 4")
+    
+    Returns:
+        Detailed bill information including actions, sponsors, sources
+    """
+    try:
+        # Parse bill_id to extract state and bill number
+        if '-' not in bill_id:
+            raise HTTPException(status_code=400, detail="Invalid bill ID format. Expected: STATE-BILLNUMBER")
+        
+        parts = bill_id.split('-', 1)
+        state = parts[0].upper()
+        bill_number = parts[1]
+        
+        # Build file paths for bills data from gold layer
+        bills_file = GOLD_DIR / "states" / state / "bills_bills.parquet"
+        actions_file = GOLD_DIR / "states" / state / "bills_bill_actions.parquet"
+        sponsors_file = GOLD_DIR / "states" / state / "bills_bill_sponsorships.parquet"
+        
+        # Get data sources (local or remote HuggingFace URL)
+        bills_source = get_data_source(bills_file, use_remote=IS_HF_SPACES)
+        actions_source = get_data_source(actions_file, use_remote=IS_HF_SPACES)
+        sponsors_source = get_data_source(sponsors_file, use_remote=IS_HF_SPACES)
+        
+        # Connect to DuckDB for querying parquet files
+        conn = duckdb.connect()
+        
+        try:
+            # Query for the specific bill
+            bill_query = """
+                SELECT 
+                    bill_id,
+                    bill_number,
+                    title,
+                    classification,
+                    latest_action_description,
+                    latest_action_date,
+                    first_action_date,
+                    session,
+                    session_name,
+                    jurisdiction_name
+                FROM read_parquet(?)
+                WHERE bill_number = ?
+                LIMIT 1
+            """
+            
+            result = conn.execute(bill_query, [bills_source, bill_number]).fetchone()
+            
+            if not result:
+                conn.close()
+                raise HTTPException(status_code=404, detail=f"Bill {bill_number} not found in {state}")
+            
+            # Parse bill data
+            bill_data = {
+                "bill_id": result[0] if result[0] else bill_id,
+                "bill_number": result[1],
+                "title": result[2],
+                "classification": result[3] if result[3] else [],
+                "latest_action": result[4],
+                "latest_action_date": result[5],
+                "first_action_date": result[6],
+                "session": result[7],
+                "session_name": result[8],
+                "jurisdiction": result[9],
+                "state": state,
+            }
+            
+            # Get sponsors if available
+            try:
+                sponsor_query = """
+                    SELECT name, primary_sponsor, classification
+                    FROM read_parquet(?)
+                    WHERE bill_id = ?
+                    ORDER BY primary_sponsor DESC
+                """
+                sponsor_rows = conn.execute(sponsor_query, [sponsors_source, bill_data["bill_id"]]).fetchall()
+                
+                bill_data["sponsors"] = [
+                    {"name": s[0], "primary": bool(s[1]), "classification": s[2]}
+                    for s in sponsor_rows
+                ]
+            except Exception as e:
+                logger.warning(f"Could not load sponsors for {bill_id}: {e}")
+                bill_data["sponsors"] = []
+            
+            # Get actions if available
+            try:
+                actions_query = """
+                    SELECT description, date, classification
+                    FROM read_parquet(?)
+                    WHERE bill_id = ?
+                    ORDER BY date DESC
+                    LIMIT 10
+                """
+                action_rows = conn.execute(actions_query, [actions_source, bill_data["bill_id"]]).fetchall()
+                
+                bill_data["actions"] = [
+                    {"description": a[0], "date": a[1], "classification": a[2]}
+                    for a in action_rows
+                ]
+            except Exception as e:
+                logger.warning(f"Could not load actions for {bill_id}: {e}")
+                bill_data["actions"] = []
+            
+            conn.close()
+            return bill_data
+            
+        except Exception as e:
+            conn.close()
+            raise
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Bill details error: {e}")
+        logger.error(traceback.format_exc())
+        raise HTTPException(status_code=500, detail=str(e))

api/routes/bills_neon.py

@@ -0,0 +1,481 @@
+"""
+Bills API Routes - Hybrid approach using Neon + Parquet
+- Map aggregates: Neon PostgreSQL (fast, lightweight)
+- Detailed bills & sessions: Parquet files (saves Neon space)
+"""
+from fastapi import APIRouter, Query, HTTPException
+from fastapi.responses import JSONResponse
+from typing import Optional, List, Dict, Any
+import asyncpg
+import duckdb
+import pandas as pd
+from pathlib import Path
+from loguru import logger
+import os
+from datetime import datetime, timedelta
+
+from api.errors import ErrorDetail, parse_error
+
+router = APIRouter(prefix="/api/bills", tags=["bills"])
+
+# Database configuration (for map aggregates only)
+NEON_DATABASE_URL_DEV = os.getenv("NEON_DATABASE_URL_DEV")
+NEON_DATABASE_URL = os.getenv("NEON_DATABASE_URL")
+DATABASE_URL = NEON_DATABASE_URL_DEV or NEON_DATABASE_URL
+
+# Parquet configuration (for detailed bills)
+GOLD_DIR = Path("data/gold")
+IS_HF_SPACES = os.getenv("HF_SPACES") == "1"
+HF_ORGANIZATION = os.getenv('HF_ORGANIZATION', 'CommunityOne')
+
+if DATABASE_URL:
+    logger.info(f"🗄️  Bills map using: {'DEV' if NEON_DATABASE_URL_DEV else 'PROD'} database")
+    logger.info(f"📁 Bills details using: {'HuggingFace' if IS_HF_SPACES else 'local'} parquet")
+else:
+    logger.warning("⚠️  No database URL configured. Map endpoint will not work.")
+
+# Connection pool
+_pool = None
+
+# Cache for map data (TTL: 5 minutes)
+_map_cache = {}
+_map_cache_time = None
+MAP_CACHE_DURATION = timedelta(minutes=5)
+
+
+def get_hf_dataset_url(dataset_name: str) -> str:
+    """Convert dataset name to HuggingFace parquet URL."""
+    return f"https://huggingface.co/datasets/{HF_ORGANIZATION}/{dataset_name}/resolve/main/data/train-00000-of-00001.parquet"
+
+def get_data_source(file_path: Path, use_remote: bool = False) -> str:
+    """Get data source (local path or remote URL) based on environment."""
+    if not IS_HF_SPACES and not use_remote:
+        return str(file_path)
+    
+    # Convert local path to HuggingFace dataset name
+    parts = file_path.parts
+    
+    if 'states' in parts:
+        state_idx = parts.index('states')
+        state = parts[state_idx + 1].lower()
+        filename = parts[-1].replace('.parquet', '').replace('_', '-')
+        dataset_name = f"states-{state}-{filename}"
+        return get_hf_dataset_url(dataset_name)
+    
+    return str(file_path)
+
+
+async def get_pool():
+    """Get or create asyncpg connection pool."""
+    global _pool
+    if _pool is None and DATABASE_URL:
+        _pool = await asyncpg.create_pool(
+            DATABASE_URL,
+            min_size=1,
+            max_size=10,
+            command_timeout=60
+        )
+    return _pool
+
+
+async def fetch_bills_from_parquet(
+    state: str,
+    q: Optional[str] = None,
+    session: Optional[str] = None,
+    limit: int = 50,
+    offset: int = 0
+) -> Dict[str, Any]:
+    """Fetch bills from parquet files using DuckDB (detailed drill-down)."""
+    try:
+        # Build file path
+        bills_file = GOLD_DIR / "states" / state / "bills_bills.parquet"
+        
+        # Get data source (local or remote HuggingFace URL)
+        data_source = get_data_source(bills_file, use_remote=IS_HF_SPACES)
+        
+        # Connect to DuckDB
+        conn = duckdb.connect()
+        
+        # Build SQL query
+        where_clauses = []
+        params = []
+        
+        if q:
+            where_clauses.append("(LOWER(title) LIKE LOWER(?) OR LOWER(bill_number) LIKE LOWER(?))")
+            pattern = f'%{q}%'
+            params.extend([pattern, pattern])
+        
+        if session:
+            where_clauses.append("session = ?")
+            params.append(session)
+        
+        where_clause = " AND ".join(where_clauses) if where_clauses else "1=1"
+        
+        # Count total
+        count_sql = f"""
+            SELECT COUNT(*) as total
+            FROM read_parquet(?)
+            WHERE {where_clause}
+        """
+        count_params = [data_source] + params
+        total = conn.execute(count_sql, count_params).fetchone()[0]
+        
+        # Fetch bills
+        sql = f"""
+            SELECT 
+                bill_id,
+                bill_number,
+                title,
+                classification,
+                session,
+                session_name,
+                first_action_date,
+                latest_action_date,
+                latest_action_description,
+                jurisdiction_name
+            FROM read_parquet(?)
+            WHERE {where_clause}
+            ORDER BY latest_action_date DESC NULLS LAST, bill_number DESC
+            LIMIT ? OFFSET ?
+        """
+        
+        query_params = [data_source] + params + [limit, offset]
+        rows = conn.execute(sql, query_params).fetchall()
+        
+        bills = []
+        for row in rows:
+            bills.append({
+                "bill_id": row[0],
+                "bill_number": row[1],
+                "title": row[2],
+                "classification": list(row[3]) if row[3] else [],
+                "session": row[4],
+                "session_name": row[5],
+                "first_action_date": str(row[6]) if row[6] else None,
+                "latest_action_date": str(row[7]) if row[7] else None,
+                "latest_action_description": row[8],
+                "jurisdiction_name": row[9]
+            })
+        
+        conn.close()
+        
+        return {
+            "state": state,
+            "query": q,
+            "session": session,
+            "bills": bills,
+            "total": total,
+            "limit": limit,
+            "offset": offset,
+            "source": "parquet"
+        }
+        
+    except Exception as e:
+        logger.error(f"Error fetching bills from parquet: {e}")
+        raise
+
+
+async def fetch_sessions_from_parquet(state: str) -> Dict[str, Any]:
+    """Fetch sessions from parquet files using DuckDB."""
+    try:
+        # Build file path
+        bills_file = GOLD_DIR / "states" / state / "bills_bills.parquet"
+        
+        # Get data source
+        data_source = get_data_source(bills_file, use_remote=IS_HF_SPACES)
+        
+        # Connect to DuckDB
+        conn = duckdb.connect()
+        
+        # Aggregate sessions
+        sql = """
+            SELECT 
+                session,
+                MAX(session_name) as session_name,
+                MIN(first_action_date) as start_date,
+                MAX(latest_action_date) as end_date,
+                COUNT(*) as bill_count
+            FROM read_parquet(?)
+            GROUP BY session, session_name
+            ORDER BY session DESC
+        """
+        
+        rows = conn.execute(sql, [data_source]).fetchall()
+        
+        sessions = []
+        for row in rows:
+            sessions.append({
+                "session": row[0],
+                "session_name": row[1],
+                "start_date": str(row[2]) if row[2] else None,
+                "end_date": str(row[3]) if row[3] else None,
+                "bill_count": row[4]
+            })
+        
+        conn.close()
+        
+        return {
+            "state": state,
+            "sessions": sessions,
+            "total_sessions": len(sessions),
+            "source": "parquet"
+        }
+        
+    except Exception as e:
+        logger.error(f"Error fetching sessions from parquet: {e}")
+        raise
+
+
+async def fetch_map_data_from_neon(
+    topic: Optional[str] = None,
+    session: Optional[str] = None
+) -> Dict[str, Any]:
+    """Fetch map aggregates from Neon PostgreSQL."""
+    pool = await get_pool()
+    
+    # Use cache if available
+    global _map_cache, _map_cache_time
+    cache_key = f"{topic or 'all'}_{session or 'all'}"
+    
+    now = datetime.now()
+    if _map_cache_time and (now - _map_cache_time) < MAP_CACHE_DURATION:
+        if cache_key in _map_cache:
+            logger.debug(f"🚀 Map cache hit for {cache_key}")
+            return _map_cache[cache_key]
+    
+    async with pool.acquire() as conn:
+        # For now, we only support topic='all' (no topic filtering yet)
+        # Session filtering would require aggregating bills on-the-fly
+        
+        sql = """
+            SELECT 
+                state_code,
+                topic,
+                total_bills,
+                type_bill,
+                type_resolution,
+                type_concurrent_resolution,
+                type_joint_resolution,
+                type_constitutional_amendment,
+                status_enacted,
+                status_failed,
+                status_pending,
+                primary_type,
+                primary_status,
+                map_category,
+                sample_bills,
+                last_updated
+            FROM bills_map_aggregates
+            WHERE topic = $1
+        """
+        
+        requested_topic = topic.lower() if topic else 'all'
+        rows = await conn.fetch(sql, requested_topic)
+        
+        # If topic-specific data not found, return empty (don't fallback)
+        if not rows:
+            logger.warning(f"📊 No pre-computed data for topic '{requested_topic}'")
+            return {
+                "topic": requested_topic,
+                "session": session,
+                "states": {},
+                "total_states": 0,
+                "message": f"No data available for topic '{requested_topic}'. Try 'all' or pre-compute aggregates for this topic.",
+                "source": "neon"
+            }
+        
+        state_data = {}
+        for row in rows:
+            state_code = row['state_code']
+            
+            # Parse sample bills JSON
+            sample_bills = row['sample_bills'] or []
+            if isinstance(sample_bills, str):
+                import json
+                sample_bills = json.loads(sample_bills)
+            
+            state_data[state_code] = {
+                "state": state_code,
+                "total_bills": row['total_bills'],
+                "type_counts": {
+                    "bill": row['type_bill'],
+                    "resolution": row['type_resolution'],
+                    "concurrent_resolution": row['type_concurrent_resolution'],
+                    "joint_resolution": row['type_joint_resolution'],
+                    "constitutional_amendment": row['type_constitutional_amendment']
+                },
+                "status_counts": {
+                    "enacted": row['status_enacted'] or 0,
+                    "failed": row['status_failed'] or 0,
+                    "pending": row['status_pending'] or 0
+                },
+                "primary_type": row['primary_type'],
+                "primary_status": row['primary_status'],
+                "map_category": row['map_category'],
+                "sample_bills": sample_bills,
+                "last_updated": row['last_updated'].isoformat() if row['last_updated'] else None
+            }
+        
+        # Build dynamic legend based on actual data
+        unique_types = set()
+        for state in state_data.values():
+            if state['primary_type']:
+                unique_types.add(state['primary_type'])
+        
+        # Map types to user-friendly names
+        type_labels = {
+            'mandate': 'Mandate',
+            'removal': 'Removal',
+            'study': 'Study',
+            'funding': 'Funding',
+            'coverage_expansion': 'Coverage Expansion',
+            'screening': 'Screening',
+            'provider_access': 'Provider Access',
+            'expansion': 'Expansion',
+            'coverage': 'Coverage',
+            'reimbursement': 'Reimbursement',
+            'eligibility': 'Eligibility',
+            'requirement': 'Requirement',
+            'curriculum': 'Curriculum',
+            'reform': 'Reform',
+            'protection': 'Protection',
+            'restriction': 'Restriction',
+            'other': 'Other'
+        }
+        
+        legend_types = {t: type_labels.get(t, t.replace('_', ' ').title()) for t in unique_types}
+        
+        result = {
+            "topic": requested_topic,
+            "session": session,
+            "states": state_data,
+            "total_states": len(state_data),
+            "legend": {
+                "types": legend_types,
+                "statuses": {
+                    "enacted": "Enacted",
+                    "failed": "Failed",
+                    "pending": "Pending"
+                }
+            },
+            "cached": True,
+            "source": "neon"
+        }
+        
+        # Update cache
+        _map_cache[cache_key] = result
+        _map_cache_time = now
+        
+        return result
+
+
+@router.get("")
+async def get_bills(
+    state: str = Query(..., description="State abbreviation (e.g., MA, AL)"),
+    q: Optional[str] = Query(None, description="Search query (bill number or title)"),
+    session: Optional[str] = Query(None, description="Legislative session"),
+    limit: int = Query(50, ge=1, le=500),
+    offset: int = Query(0, ge=0)
+):
+    """
+    Search legislative bills using parquet files (detailed drill-down).
+    
+    **Examples:**
+    - `/api/bills?state=AL&q=dental` - Search Alabama bills for "dental"
+    - `/api/bills?state=AL&session=2024rs` - Get all 2024 regular session bills
+    - `/api/bills?state=AL&limit=50` - Browse recent Alabama bills
+    """
+    try:
+        result = await fetch_bills_from_parquet(
+            state=state.upper(),
+            q=q,
+            session=session,
+            limit=limit,
+            offset=offset
+        )
+        
+        return result
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Bills query error for state={state}: {e}")
+        
+        error_detail = parse_error(e, context={
+            "state": state,
+            "query": q,
+            "session": session
+        })
+        
+        return JSONResponse(
+            status_code=500,
+            content=error_detail.model_dump()
+        )
+
+
+@router.get("/sessions")
+async def get_sessions(
+    state: str = Query(..., description="State abbreviation (e.g., MA, AL)")
+):
+    """
+    Get legislative sessions for a state using parquet files.
+    
+    **Examples:**
+    - `/api/bills/sessions?state=MA` - Get all Massachusetts sessions
+    """
+    try:
+        result = await fetch_sessions_from_parquet(state=state.upper())
+        
+        return result
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Sessions query error for state={state}: {e}")
+        
+        error_detail = parse_error(e, context={
+            "state": state
+        })
+        
+        return JSONResponse(
+            status_code=500,
+            content=error_detail.model_dump()
+        )
+
+
+@router.get("/map")
+async def get_bill_map_data(
+    topic: Optional[str] = Query(None, description="Topic to filter (e.g., dental, health, education)"),
+    session: Optional[str] = Query(None, description="Legislative session")
+):
+    """
+    Get aggregated bill data for choropleth map using Neon PostgreSQL.
+    
+    Returns pre-computed state-level aggregates for instant visualization.
+    
+    **Examples:**
+    - `/api/bills/map` - Get national bill map data
+    - `/api/bills/map?topic=dental` - Map dental legislation (not yet implemented)
+    """
+    try:
+        if not DATABASE_URL:
+            raise HTTPException(status_code=503, detail="Database not configured")
+        
+        result = await fetch_map_data_from_neon(topic=topic, session=session)
+        
+        return result
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Map data query error: {e}")
+        
+        error_detail = parse_error(e, context={
+            "topic": topic,
+            "session": session
+        })
+        
+        return JSONResponse(
+            status_code=500,
+            content=error_detail.model_dump()
+        )

api/routes/contact.py

@@ -0,0 +1,118 @@
+"""
+Contact routes for submitting feedback and issues via GitHub.
+"""
+from fastapi import APIRouter, HTTPException, status
+from pydantic import BaseModel, EmailStr, Field
+from typing import Optional
+import httpx
+import os
+from loguru import logger
+
+router = APIRouter(prefix="/api/contact", tags=["contact"])
+
+
+class ContactRequest(BaseModel):
+    """Contact form submission"""
+    name: str = Field(..., min_length=1, max_length=100, description="Name of the person contacting")
+    email: EmailStr = Field(..., description="Email address for follow-up")
+    subject: str = Field(..., min_length=1, max_length=200, description="Subject of the message")
+    message: str = Field(..., min_length=10, max_length=5000, description="Detailed message")
+    category: Optional[str] = Field(default="feedback", description="Type of contact: feedback, bug, feature, question")
+
+
+class ContactResponse(BaseModel):
+    """Response after submitting contact form"""
+    success: bool
+    message: str
+    issue_url: Optional[str] = None
+
+
+@router.post("/submit", response_model=ContactResponse, status_code=status.HTTP_201_CREATED)
+async def submit_contact(request: ContactRequest):
+    """
+    Submit a contact form message as a GitHub issue.
+    
+    Creates an issue in the GitHub repository with the contact information.
+    Requires GITHUB_TOKEN and GITHUB_REPO environment variables.
+    """
+    github_token = os.getenv("GITHUB_TOKEN")
+    github_repo = os.getenv("GITHUB_REPO", "getcommunityone/open-navigator")
+    
+    if not github_token:
+        logger.warning("GitHub token not configured - contact form submission failed")
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Contact form is not configured. Please email us directly or submit an issue on GitHub."
+        )
+    
+    # Determine label based on category
+    category_labels = {
+        "bug": "bug",
+        "feature": "enhancement",
+        "question": "question",
+        "feedback": "feedback"
+    }
+    label = category_labels.get(request.category, "feedback")
+    
+    # Create issue title and body
+    issue_title = f"[Contact Form] {request.subject}"
+    issue_body = f"""**From:** {request.name} ({request.email})
+**Category:** {request.category}
+
+---
+
+{request.message}
+
+---
+*This issue was automatically created from the contact form.*
+"""
+    
+    # Create GitHub issue
+    github_api_url = f"https://api.github.com/repos/{github_repo}/issues"
+    headers = {
+        "Authorization": f"token {github_token}",
+        "Accept": "application/vnd.github.v3+json"
+    }
+    payload = {
+        "title": issue_title,
+        "body": issue_body,
+        "labels": [label, "contact-form"]
+    }
+    
+    try:
+        async with httpx.AsyncClient() as client:
+            response = await client.post(
+                github_api_url,
+                json=payload,
+                headers=headers,
+                timeout=10.0
+            )
+            
+            if response.status_code == 201:
+                issue_data = response.json()
+                issue_url = issue_data.get("html_url")
+                logger.info(f"Contact form submitted successfully: {issue_url}")
+                return ContactResponse(
+                    success=True,
+                    message="Thank you for contacting us! We've received your message and will get back to you soon.",
+                    issue_url=issue_url
+                )
+            else:
+                logger.error(f"GitHub API error: {response.status_code} - {response.text}")
+                raise HTTPException(
+                    status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                    detail="Failed to submit contact form. Please try again later."
+                )
+    
+    except httpx.TimeoutException:
+        logger.error("GitHub API timeout")
+        raise HTTPException(
+            status_code=status.HTTP_504_GATEWAY_TIMEOUT,
+            detail="Request timed out. Please try again."
+        )
+    except httpx.RequestError as e:
+        logger.error(f"GitHub API request error: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to submit contact form. Please try again later."
+        )

api/routes/hf_search.py

@@ -0,0 +1,182 @@
+"""
+HuggingFace Datasets Search API Integration
+
+Fast server-side text search using HuggingFace's indexed datasets.
+Falls back to DuckDB if dataset not indexed or search unavailable.
+"""
+import httpx
+from typing import Optional, List, Dict, Any
+from loguru import logger
+import os
+
+HF_SEARCH_API = "https://datasets-server.huggingface.co/search"
+HF_ORGANIZATION = os.getenv('HF_ORGANIZATION', 'CommunityOne')
+REQUEST_TIMEOUT = 5  # seconds
+
+
+def is_dataset_indexed(dataset_name: str) -> bool:
+    """
+    Check if a dataset is indexed and searchable.
+    
+    Args:
+        dataset_name: Full repo ID (e.g., 'CommunityOne/states-ma-contacts-local-officials')
+    
+    Returns:
+        True if dataset supports search, False otherwise
+    """
+    try:
+        response = httpx.get(
+            "https://datasets-server.huggingface.co/is-valid",
+            params={"dataset": dataset_name},
+            timeout=REQUEST_TIMEOUT
+        )
+        if response.status_code == 200:
+            data = response.json()
+            return data.get("search", False)
+    except Exception as e:
+        logger.debug(f"Could not check if {dataset_name} is indexed: {e}")
+    
+    return False
+
+
+def search_hf_dataset(
+    dataset_name: str,
+    query: str,
+    config: str = "default",
+    split: str = "train",
+    limit: int = 100
+) -> Optional[List[Dict[str, Any]]]:
+    """
+    Search a HuggingFace dataset using server-side indexed search.
+    
+    Args:
+        dataset_name: Full repo ID (e.g., 'CommunityOne/states-ma-contacts')
+        query: Search text (searches across all string columns)
+        config: Dataset configuration name
+        split: Dataset split to search
+        limit: Maximum results to return
+    
+    Returns:
+        List of matching rows, or None if search unavailable
+    """
+    try:
+        response = httpx.get(
+            HF_SEARCH_API,
+            params={
+                "dataset": dataset_name,
+                "config": config,
+                "split": split,
+                "query": query,
+                "offset": 0,
+                "length": limit
+            },
+            timeout=REQUEST_TIMEOUT
+        )
+        
+        if response.status_code == 200:
+            data = response.json()
+            
+            # Check for errors
+            if "error" in data:
+                logger.debug(f"HF Search API error for {dataset_name}: {data['error']}")
+                return None
+            
+            # Extract rows
+            rows = data.get("rows", [])
+            logger.info(f"✅ HF Search API: Found {len(rows)} results for '{query}' in {dataset_name}")
+            
+            # Convert to list of dicts (row['row'] contains actual data)
+            results = [row.get("row", {}) for row in rows]
+            return results
+        
+        elif response.status_code == 404:
+            logger.debug(f"Dataset {dataset_name} not found on HuggingFace")
+            return None
+        
+        else:
+            logger.debug(f"HF Search API returned status {response.status_code}")
+            return None
+            
+    except httpx.TimeoutException:
+        logger.debug(f"HF Search API timeout for {dataset_name}")
+        return None
+    
+    except Exception as e:
+        logger.debug(f"HF Search API error: {e}")
+        return None
+
+
+def search_contacts_hf(query: str, state: Optional[str] = None, limit: int = 10) -> Optional[List[Dict[str, Any]]]:
+    """
+    Search contacts (local officials + nonprofit officers) using HF Search API.
+    
+    Args:
+        query: Search text (name, title, jurisdiction, etc.)
+        state: 2-letter state code (e.g., 'MA')
+        limit: Maximum results
+    
+    Returns:
+        List of contact dicts, or None if search unavailable
+    """
+    results = []
+    
+    # Search local officials
+    if state:
+        dataset = f"{HF_ORGANIZATION}/states-{state.lower()}-contacts-local-officials"
+        local_results = search_hf_dataset(dataset, query, limit=limit)
+        if local_results:
+            for row in local_results:
+                row['source'] = 'local_officials'
+                results.append(row)
+    
+    # Search nonprofit officers
+    if state and len(results) < limit:
+        dataset = f"{HF_ORGANIZATION}/states-{state.lower()}-contacts-nonprofit-officers"
+        nonprofit_results = search_hf_dataset(dataset, query, limit=limit - len(results))
+        if nonprofit_results:
+            for row in nonprofit_results:
+                row['source'] = 'nonprofit_officers'
+                results.append(row)
+    
+    return results if results else None
+
+
+def search_organizations_hf(query: str, state: Optional[str] = None, limit: int = 10) -> Optional[List[Dict[str, Any]]]:
+    """
+    Search nonprofit organizations using HF Search API.
+    
+    Args:
+        query: Search text (organization name, EIN, etc.)
+        state: 2-letter state code
+        limit: Maximum results
+    
+    Returns:
+        List of organization dicts, or None if search unavailable
+    """
+    if state:
+        dataset = f"{HF_ORGANIZATION}/states-{state.lower()}-nonprofits-organizations"
+    else:
+        dataset = f"{HF_ORGANIZATION}/national-nonprofits-organizations"
+    
+    return search_hf_dataset(dataset, query, limit=limit)
+
+
+def search_jurisdictions_hf(query: str, jurisdiction_type: Optional[str] = None, limit: int = 10) -> Optional[List[Dict[str, Any]]]:
+    """
+    Search jurisdictions (cities, counties, townships, school districts) using HF Search API.
+    
+    Args:
+        query: Search text (city name, county name, etc.)
+        jurisdiction_type: 'cities', 'counties', 'townships', 'school_districts'
+        limit: Maximum results
+    
+    Returns:
+        List of jurisdiction dicts, or None if search unavailable
+    """
+    if jurisdiction_type:
+        dataset = f"{HF_ORGANIZATION}/reference-jurisdictions-{jurisdiction_type.replace('_', '-')}"
+    else:
+        # Try cities first (most common)
+        dataset = f"{HF_ORGANIZATION}/reference-jurisdictions-cities"
+    
+    return search_hf_dataset(dataset, query, limit=limit)

api/routes/search.py

@@ -0,0 +1,1685 @@
+"""
+Unified Search API
+LinkedIn-style search across contacts, meetings, organizations, and causes
+Uses hybrid approach: PostgreSQL (primary, fast) + HuggingFace Search API + DuckDB (fallback)
+"""
+from fastapi import APIRouter, Query, HTTPException
+from fastapi.responses import JSONResponse
+from typing import Optional, List, Dict, Any
+from pathlib import Path
+import pandas as pd
+import duckdb
+from loguru import logger
+import re
+import os
+import sys
+import requests
+from functools import lru_cache
+from datetime import datetime, timedelta
+
+from api.errors import ErrorDetail, parse_error
+
+# Import PostgreSQL search functions (primary)
+from api.routes import search_postgres
+
+# Import HuggingFace Search helpers
+from api.routes.hf_search import (
+    search_contacts_hf,
+    search_organizations_hf,
+    search_jurisdictions_hf,
+    is_dataset_indexed
+)
+
+router = APIRouter(tags=["search"])
+
+# Paths to gold datasets
+GOLD_DIR = Path("data/gold")
+
+# Detect deployment environment
+IS_HF_SPACES = os.getenv("HF_SPACES") == "1"
+HF_ORGANIZATION = os.getenv('HF_ORGANIZATION', 'CommunityOne')
+
+# Cache for count queries (TTL: 1 hour)
+_count_cache = {}
+_count_cache_ttl = {}
+
+# In-memory DataFrame cache for HuggingFace datasets (TTL: 5 minutes)
+# Reduces remote HTTP requests from 2-3s to <10ms per search
+_dataframe_cache: Dict[str, pd.DataFrame] = {}
+_dataframe_cache_ttl: Dict[str, datetime] = {}
+DATAFRAME_CACHE_TTL = timedelta(minutes=5)
+
+# Every.org API config (fallback only)
+EVERYORG_API_KEY = os.getenv('EVERYORG_API_KEY', '')
+EVERYORG_API_BASE = "https://partners.every.org/v0.2"
+
+
+def load_parquet_cached(url: str) -> pd.DataFrame:
+    """
+    Load parquet file with in-memory caching to avoid repeated HTTP requests.
+    
+    Cache TTL: 5 minutes (balances speed vs freshness)
+    Reduces search latency from 2-3s to <10ms per query.
+    
+    Args:
+        url: URL to parquet file (local path or HuggingFace URL)
+    
+    Returns:
+        pandas DataFrame
+    """
+    now = datetime.now()
+    
+    # Check cache
+    if url in _dataframe_cache:
+        cache_time = _dataframe_cache_ttl.get(url)
+        if cache_time and (now - cache_time) < DATAFRAME_CACHE_TTL:
+            logger.debug(f"🚀 Cache hit for {url}")
+            return _dataframe_cache[url]
+    
+    # Cache miss - load from source
+    logger.info(f"📥 Loading parquet from {url}")
+    df = pd.read_parquet(url)
+    
+    # Store in cache
+    _dataframe_cache[url] = df
+    _dataframe_cache_ttl[url] = now
+    logger.debug(f"💾 Cached {len(df)} rows from {url}")
+    
+    return df
+
+
+def get_hf_dataset_url(dataset_name: str) -> str:
+    """
+    Convert dataset name to HuggingFace parquet URL.
+    
+    HuggingFace Datasets library stores parquet files in the standard format:
+    data/train-00000-of-00001.parquet
+    
+    Examples:
+        states-ma-contacts-local-officials -> 
+            https://huggingface.co/datasets/CommunityOne/states-ma-contacts-local-officials/resolve/main/data/train-00000-of-00001.parquet
+    """
+    return f"https://huggingface.co/datasets/{HF_ORGANIZATION}/{dataset_name}/resolve/main/data/train-00000-of-00001.parquet"
+
+
+def get_data_source(file_path: Path, use_remote: bool = False) -> str:
+    """
+    Get data source (local path or remote URL) based on environment.
+    
+    Args:
+        file_path: Local file path (e.g., data/gold/states/MA/contacts_local_officials.parquet)
+        use_remote: Force remote URL even in local environment
+    
+    Returns:
+        File path string (local) or HuggingFace URL (remote)
+    """
+    if not IS_HF_SPACES and not use_remote:
+        return str(file_path)
+    
+    # Convert local path to HuggingFace dataset name
+    # data/gold/states/MA/contacts_local_officials.parquet -> states-ma-contacts-local-officials
+    parts = file_path.parts
+    
+    if 'states' in parts:
+        state_idx = parts.index('states')
+        state = parts[state_idx + 1].lower()
+        filename = parts[-1].replace('.parquet', '').replace('_', '-')
+        dataset_name = f"states-{state}-{filename}"
+    elif 'national' in parts:
+        filename = parts[-1].replace('.parquet', '').replace('_', '-')
+        dataset_name = f"national-{filename}"
+    elif 'reference' in parts:
+        filename = parts[-1].replace('.parquet', '').replace('_', '-')
+        dataset_name = f"reference-{filename}"
+    else:
+        # Fallback to local
+        return str(file_path)
+    
+    return get_hf_dataset_url(dataset_name)
+
+
+@lru_cache(maxsize=5000)
+def fetch_form990_data(ein: str) -> Optional[Dict[str, Any]]:
+    """
+    Fetch enrichment data from ProPublica Nonprofit Explorer (FREE!)
+    Uses their API to get website and mission from Form 990 filings
+    """
+    if not ein:
+        return None
+    
+    try:
+        clean_ein = str(ein).replace('-', '').zfill(9)
+        url = f"https://projects.propublica.org/nonprofits/api/v2/organizations/{clean_ein}.json"
+        
+        response = requests.get(url, timeout=3)
+        
+        if response.status_code == 200:
+            data = response.json()
+            org = data.get('organization', {})
+            filings = data.get('filings_with_data', [])
+            
+            # Get most recent filing data
+            website = None
+            mission = None
+            
+            if filings:
+                # ProPublica provides website from most recent filing
+                latest = filings[0]
+                # Note: ProPublica API doesn't directly expose website field
+                # but we can use their organization name and data as fallback
+                pass
+            
+            return {
+                'website': website,  # ProPublica doesn't expose this in API
+                'mission': None,  # Would need to parse PDF
+                'source': 'propublica',
+                'last_updated': datetime.now().isoformat(),
+                'tax_year': filings[0].get('tax_prd_yr') if filings else None
+            }
+    except Exception as e:
+        logger.debug(f"ProPublica lookup failed for EIN {ein}: {e}")
+    
+    return None
+
+
+@lru_cache(maxsize=5000)
+def fetch_everyorg_data(ein: str) -> Optional[Dict[str, Any]]:
+    """Fetch enrichment data from Every.org API (cached) - FALLBACK ONLY"""
+    if not EVERYORG_API_KEY or not ein:
+        return None
+    
+    try:
+        # Format EIN (remove dashes, ensure 9 digits)
+        clean_ein = str(ein).replace('-', '').zfill(9)
+        
+        url = f"{EVERYORG_API_BASE}/nonprofit/{clean_ein}"
+        headers = {
+            "Authorization": f"Bearer {EVERYORG_API_KEY}",
+            "Accept": "application/json"
+        }
+        
+        response = requests.get(url, headers=headers, timeout=3)
+        
+        if response.status_code == 200:
+            data = response.json()
+            if data and 'data' in data and 'nonprofit' in data['data']:
+                nonprofit = data['data']['nonprofit']
+                tags = data['data'].get('nonprofitTags', [])
+                causes = [tag.get('tagName') for tag in tags if tag.get('tagName')]
+                
+                return {
+                    'mission': nonprofit.get('description') or nonprofit.get('descriptionLong'),
+                    'website': nonprofit.get('websiteUrl'),
+                    'logo_url': nonprofit.get('logoUrl'),
+                    'profile_url': nonprofit.get('profileUrl'),
+                    'causes': causes[:5],  # Limit to top 5 causes
+                    'source': 'everyorg',
+                    'last_updated': datetime.now().isoformat()
+                }
+    except Exception as e:
+        logger.debug(f"Every.org lookup failed for EIN {ein}: {e}")
+    
+    return None
+
+
+def get_enrichment_data(ein: str, existing_data: Optional[Dict] = None) -> Dict[str, Any]:
+    """
+    Get enrichment data with intelligent backfill strategy
+    
+    Priority:
+    1. Existing form_990_* data (if recent)
+    2. GivingTuesday 990 XML (future: direct S3 access)
+    3. ProPublica API (current fallback)
+    4. Every.org API (last resort)
+    
+    Tracks source and update time for incremental processing
+    """
+    result = {
+        'website': None,
+        'mission': None,
+        'logo_url': None,
+        'profile_url': None,
+        'causes': [],
+        'data_sources': []
+    }
+    
+    # Check existing data first (skip if older than 30 days)
+    if existing_data:
+        cutoff_date = datetime.now() - timedelta(days=30)
+        
+        # Check enrichment data (from any source: form_990, bigquery, etc.)
+        if existing_data.get('enrichment_website'):
+            last_updated = existing_data.get('enrichment_last_updated')
+            if not last_updated or (isinstance(last_updated, str) and datetime.fromisoformat(last_updated) > cutoff_date):
+                result['website'] = existing_data['enrichment_website']
+                result['data_sources'].append('cached')
+        
+        if existing_data.get('enrichment_mission'):
+            result['mission'] = existing_data['enrichment_mission']
+            if 'cached' not in result['data_sources']:
+                result['data_sources'].append('cached')
+    
+    # Try Every.org for missing fields (keeps logo and causes which 990 doesn't have)
+    if not result['website'] or not result['mission']:
+        everyorg_data = fetch_everyorg_data(ein)
+        if everyorg_data:
+            if not result['website'] and everyorg_data.get('website'):
+                result['website'] = everyorg_data['website']
+                result['data_sources'].append('everyorg')
+            
+            if not result['mission'] and everyorg_data.get('mission'):
+                result['mission'] = everyorg_data['mission']
+                result['data_sources'].append('everyorg')
+            
+            # Always get logo and causes from Every.org
+            result['logo_url'] = everyorg_data.get('logo_url')
+            result['profile_url'] = everyorg_data.get('profile_url')
+            result['causes'] = everyorg_data.get('causes', [])
+            if result['logo_url'] or result['causes']:
+                if 'everyorg' not in result['data_sources']:
+                    result['data_sources'].append('everyorg')
+    
+    return result
+
+class SearchResult:
+    """Unified search result"""
+    
+    def __init__(self, 
+                 result_type: str,
+                 title: str,
+                 subtitle: str,
+                 description: str,
+                 url: str,
+                 score: float,
+                 metadata: Dict[str, Any]):
+        self.result_type = result_type
+        self.title = title
+        self.subtitle = subtitle
+        self.description = description
+        self.url = url
+        self.score = score
+        self.metadata = metadata
+    
+    def to_dict(self):
+        return {
+            "type": self.result_type,
+            "title": self.title,
+            "subtitle": self.subtitle,
+            "description": self.description,
+            "url": self.url,
+            "score": self.score,
+            "metadata": self.metadata
+        }
+
+
+def convert_pg_result(pg_result: search_postgres.SearchResult) -> 'SearchResult':
+    """Convert PostgreSQL SearchResult dataclass to SearchResult class"""
+    return SearchResult(
+        result_type=pg_result.result_type,
+        title=pg_result.title,
+        subtitle=pg_result.subtitle,
+        description=pg_result.description,
+        url=pg_result.url,
+        score=pg_result.score,
+        metadata=pg_result.metadata
+    )
+
+
+def calculate_relevance_score(text: str, query: str) -> float:
+    """Calculate relevance score for text matching query"""
+    if not text or not query:
+        return 0.0
+    
+    text_lower = text.lower()
+    query_lower = query.lower()
+    
+    # Exact match gets highest score
+    if query_lower in text_lower:
+        score = 1.0
+        # Boost if it's at the start
+        if text_lower.startswith(query_lower):
+            score += 0.5
+        return min(score, 2.0)
+    
+    # Partial word matches
+    query_words = query_lower.split()
+    text_words = text_lower.split()
+    
+    matches = sum(1 for qw in query_words if any(qw in tw for tw in text_words))
+    return matches / len(query_words) if query_words else 0.0
+
+
+def search_contacts_duckdb(query: str, state: Optional[str] = None, limit: int = 10) -> List[SearchResult]:
+    """
+    Search contacts using DuckDB (supports local files or remote HTTP parquet).
+    This is the fallback when HF Search API is unavailable.
+    Supports browse mode when query is empty.
+    """
+    results = []
+    
+    # Determine if this is browse mode (no query) or search mode
+    is_browse_mode = not query or query.strip() == ''
+    
+    try:
+        # Initialize DuckDB connection
+        conn = duckdb.connect()
+        
+        # Search 1: State Officials (OpenStates - state legislators, mayors, etc.)
+        if state:
+            officials_file_path = GOLD_DIR / "states" / state / "contacts_officials.parquet"
+            officials_file_paths = [officials_file_path]
+        else:
+            officials_file_paths = list(GOLD_DIR.glob("states/*/contacts_officials.parquet"))[:5]
+        
+        logger.info(f"Searching {len(officials_file_paths)} state official contact files (OpenStates) - browse_mode={is_browse_mode}")
+        
+        for file_path in officials_file_paths:
+            if not file_path.exists():
+                continue
+                
+            # Get data source (local or remote URL)
+            data_source = get_data_source(file_path, use_remote=IS_HF_SPACES)
+            
+            try:
+                if is_browse_mode:
+                    # Browse mode: return all officials, prioritize mayors
+                    sql = """
+                        SELECT 
+                            full_name as name,
+                            role_type as title,
+                            city_jurisdiction as jurisdiction,
+                            state,
+                            email,
+                            phone,
+                            CASE 
+                                WHEN LOWER(role_type) = 'mayor' THEN 2.0
+                                WHEN LOWER(role_type) LIKE '%council%' THEN 1.8
+                                WHEN LOWER(role_type) LIKE '%commission%' THEN 1.7
+                                ELSE 1.5
+                            END as score
+                        FROM read_parquet(?)
+                        ORDER BY score DESC, full_name ASC
+                        LIMIT ?
+                    """
+                    
+                    rows = conn.execute(sql, [data_source, limit]).fetchall()
+                else:
+                    # Search mode: relevance scoring
+                    sql = """
+                        SELECT 
+                            full_name as name,
+                            role_type as title,
+                            city_jurisdiction as jurisdiction,
+                            state,
+                            email,
+                            phone,
+                            GREATEST(
+                                CASE 
+                                    WHEN LOWER(full_name) LIKE LOWER(?) THEN 1.5
+                                    WHEN LOWER(full_name) LIKE LOWER(?) THEN 1.0
+                                    ELSE 0.0
+                                END,
+                                CASE 
+                                    WHEN LOWER(role_type) LIKE LOWER(?) THEN 1.5
+                                    WHEN LOWER(role_type) LIKE LOWER(?) THEN 1.0
+                                    ELSE 0.0
+                                END,
+                                CASE 
+                                    WHEN LOWER(city_jurisdiction) LIKE LOWER(?) THEN 1.5
+                                    WHEN LOWER(city_jurisdiction) LIKE LOWER(?) THEN 1.0
+                                    ELSE 0.0
+                                END,
+                                CASE 
+                                    WHEN LOWER(jurisdiction_name) LIKE LOWER(?) THEN 1.5
+                                    WHEN LOWER(jurisdiction_name) LIKE LOWER(?) THEN 1.0
+                                    ELSE 0.0
+                                END
+                            ) as score
+                        FROM read_parquet(?)
+                        WHERE LOWER(full_name) LIKE LOWER(?) 
+                           OR LOWER(role_type) LIKE LOWER(?) 
+                           OR LOWER(city_jurisdiction) LIKE LOWER(?)
+                           OR LOWER(jurisdiction_name) LIKE LOWER(?)
+                        ORDER BY score DESC
+                        LIMIT ?
+                    """
+                    
+                    query_pattern = f'%{query}%'
+                    query_start = f'{query}%'
+                    
+                    rows = conn.execute(sql, [
+                        query_start, query_pattern,  # name scoring
+                        query_start, query_pattern,  # role_type scoring
+                        query_start, query_pattern,  # city_jurisdiction scoring
+                        query_start, query_pattern,  # jurisdiction_name scoring
+                        data_source,                 # file path or URL
+                        query_pattern, query_pattern, query_pattern, query_pattern,  # WHERE clause
+                        limit
+                    ]).fetchall()
+                
+                # Convert to SearchResult objects
+                for row in rows:
+                    name, title, jurisdiction, state_code, email, phone, score = row
+                    
+                    if score > 0.3:  # Relevance threshold
+                        contact_info = []
+                        if email:
+                            contact_info.append(f"📧 {email}")
+                        if phone:
+                            contact_info.append(f"📞 {phone}")
+                        
+                        description = f"State official in {jurisdiction}" if jurisdiction else f"State official in {state_code}"
+                        if contact_info:
+                            description += f" • {' • '.join(contact_info)}"
+                        
+                        results.append(SearchResult(
+                            result_type="contact",
+                            title=name if name else "Unknown",
+                            subtitle=f"{title.title() if title else 'Official'} - {jurisdiction or state_code}",
+                            description=description,
+                            url=f"/people/{name.replace(' ', '-') if name else 'unknown'}",
+                            score=score,
+                            metadata={
+                                "title": title,
+                                "jurisdiction": jurisdiction,
+                                "state": state_code,
+                                "name": name,
+                                "email": email,
+                                "phone": phone,
+                                "contact_type": "state_official",
+                                "data_source": "OpenStates"
+                            }
+                        ))
+                
+            except Exception as e:
+                logger.debug(f"Error searching state officials {file_path}: {e}")
+        
+        # Search 2: Local Officials (from meeting transcripts)
+        if state:
+            local_file_path = GOLD_DIR / "states" / state / "contacts_local_officials.parquet"
+            local_file_paths = [local_file_path]
+        else:
+            local_file_paths = list(GOLD_DIR.glob("states/*/contacts_local_officials.parquet"))[:5]
+        
+        logger.info(f"Searching {len(local_file_paths)} local official contact files (meeting transcripts)")
+        
+        for file_path in local_file_paths:
+            # Get data source (local or remote URL)
+            data_source = get_data_source(file_path, use_remote=IS_HF_SPACES)
+            
+            try:
+                # SQL query with relevance scoring across name, title, jurisdiction
+                sql = """
+                    SELECT 
+                        name,
+                        title,
+                        jurisdiction,
+                        state,
+                        GREATEST(
+                            CASE 
+                                WHEN LOWER(name) LIKE LOWER(?) THEN 1.5
+                                WHEN LOWER(name) LIKE LOWER(?) THEN 1.0
+                                ELSE 0.0
+                            END,
+                            CASE 
+                                WHEN LOWER(title) LIKE LOWER(?) THEN 1.5
+                                WHEN LOWER(title) LIKE LOWER(?) THEN 1.0
+                                ELSE 0.0
+                            END,
+                            CASE 
+                                WHEN LOWER(jurisdiction) LIKE LOWER(?) THEN 1.5
+                                WHEN LOWER(jurisdiction) LIKE LOWER(?) THEN 1.0
+                                ELSE 0.0
+                            END
+                        ) as score
+                    FROM read_parquet(?)
+                    WHERE LOWER(name) LIKE LOWER(?) 
+                       OR LOWER(title) LIKE LOWER(?) 
+                       OR LOWER(jurisdiction) LIKE LOWER(?)
+                    ORDER BY score DESC
+                    LIMIT ?
+                """
+                
+                query_pattern = f'%{query}%'
+                query_start = f'{query}%'
+                
+                rows = conn.execute(sql, [
+                    query_start, query_pattern,  # name scoring
+                    query_start, query_pattern,  # title scoring
+                    query_start, query_pattern,  # jurisdiction scoring
+                    data_source,                 # file path or URL
+                    query_pattern, query_pattern, query_pattern,  # WHERE clause
+                    limit
+                ]).fetchall()
+                
+                # Convert to SearchResult objects
+                for row in rows:
+                    name, title, jurisdiction, state_code, score = row
+                    
+                    if score > 0.3:  # Relevance threshold
+                        results.append(SearchResult(
+                            result_type="contact",
+                            title=name if name else "Unknown",
+                            subtitle=f"{title} - {jurisdiction}, {state_code}",
+                            description=f"Local official in {jurisdiction}",
+                            url=f"/people/{name.replace(' ', '-') if name else 'unknown'}",
+                            score=score,
+                            metadata={
+                                "title": title,
+                                "jurisdiction": jurisdiction,
+                                "state": state_code,
+                                "name": name
+                            }
+                        ))
+                
+            except Exception as e:
+                logger.debug(f"Error searching {file_path}: {e}")
+        
+        # Search 3: Nonprofit Officers from state directories
+        nonprofit_files = []
+        
+        # If state specified, search that state's directory
+        if state:
+            state_nonprofit_file = GOLD_DIR / "states" / state / "contacts_nonprofit_officers.parquet"
+            nonprofit_files.append(state_nonprofit_file)
+        else:
+            # Search all state directories
+            for state_dir in (GOLD_DIR / "states").glob("*/"):
+                state_file = state_dir / "contacts_nonprofit_officers.parquet"
+                nonprofit_files.append(state_file)
+        
+        for nonprofit_file in nonprofit_files:
+            # Get data source (local or remote URL)
+            nonprofit_source = get_data_source(nonprofit_file, use_remote=IS_HF_SPACES)
+            
+            try:
+                logger.info(f"Searching nonprofit officers: {nonprofit_source}")
+                
+                officer_sql = """
+                    SELECT 
+                        name,
+                        title,
+                        organization_name,
+                        city,
+                        state,
+                        compensation,
+                        GREATEST(
+                            CASE 
+                                WHEN LOWER(name) LIKE LOWER(?) THEN 1.5
+                                WHEN LOWER(name) LIKE LOWER(?) THEN 1.0
+                                ELSE 0.0
+                            END,
+                            CASE 
+                                WHEN LOWER(title) LIKE LOWER(?) THEN 1.0
+                                WHEN LOWER(title) LIKE LOWER(?) THEN 0.5
+                                ELSE 0.0
+                            END,
+                            CASE 
+                                WHEN LOWER(organization_name) LIKE LOWER(?) THEN 1.0
+                                WHEN LOWER(organization_name) LIKE LOWER(?) THEN 0.5
+                                ELSE 0.0
+                            END
+                        ) AS score
+                    FROM read_parquet(?)
+                    WHERE (LOWER(name) LIKE LOWER(?) 
+                       OR LOWER(title) LIKE LOWER(?) 
+                       OR LOWER(organization_name) LIKE LOWER(?))
+                """
+                
+                query_pattern = f'%{query}%'
+                query_start = f'{query}%'
+                params = [
+                    query_start, query_pattern,  # name scoring
+                    query_start, query_pattern,  # title scoring  
+                    query_start, query_pattern,  # organization scoring
+                    nonprofit_source,            # file path or URL
+                    query_pattern, query_pattern, query_pattern  # WHERE clause
+                ]
+                
+                if state:
+                    officer_sql += " AND LOWER(state) = LOWER(?)"
+                    params.append(state)
+                
+                officer_sql += " ORDER BY score DESC, compensation DESC NULLS LAST LIMIT ?"
+                params.append(limit)
+                
+                officer_rows = conn.execute(officer_sql, params).fetchall()
+                
+                for row in officer_rows:
+                    name, title, org_name, city, state_code, compensation, score = row
+                    
+                    if score > 0.3:
+                        comp_text = f" (${compensation:,.0f})" if compensation else ""
+                        
+                        results.append(SearchResult(
+                            result_type="contact",
+                            title=name if name else "Unknown",
+                            subtitle=f"{title} - {org_name}{comp_text}",
+                            description=f"Nonprofit officer in {city}, {state_code}",
+                            url=f"/nonprofits?name={org_name.replace(' ', '-') if org_name else 'unknown'}",
+                            score=score,
+                            metadata={
+                                "title": title,
+                                "organization": org_name,
+                                "city": city,
+                                "state": state_code,
+                                "compensation": compensation,
+                                "contact_type": "nonprofit_officer"
+                            }
+                        ))
+                
+                logger.info(f"Found {len([r for r in results if r.metadata.get('contact_type') == 'nonprofit_officer'])} nonprofit officer results")
+                
+            except Exception as e:
+                logger.debug(f"Error searching nonprofit officers: {e}")
+        
+        conn.close()
+        
+        # Sort all results by score and limit
+        results.sort(key=lambda x: x.score, reverse=True)
+        logger.info(f"DuckDB search found {len(results)} contacts for query '{query}'")
+        return results[:limit]
+    
+    except Exception as e:
+        logger.error(f"Contact search error: {e}")
+        return results
+
+
+def search_contacts(query: str, state: Optional[str] = None, limit: int = 10) -> List[SearchResult]:
+    """
+    HYBRID SEARCH: Search local officials AND nonprofit officers.
+    
+    Strategy:
+    1. Try HuggingFace Search API first (fast, server-side indexed) - HF Spaces only
+    2. Fall back to DuckDB (local files or remote HTTP parquet)
+    
+    Args:
+        query: Search text (name, title, organization, etc.)
+        state: Optional 2-letter state code filter
+        limit: Maximum results to return
+    
+    Returns:
+        List of SearchResult objects sorted by relevance
+    """
+    logger.info(f"🔎 search_contacts() called - query={query!r}, state={state!r}, limit={limit}, IS_HF_SPACES={IS_HF_SPACES}")
+    
+    # STRATEGY 1: Try HuggingFace Search API (fast text search)
+    if query and IS_HF_SPACES:
+        logger.info(f"🔍 Trying HF Search API for '{query}' (state={state})")
+        try:
+            hf_results = search_contacts_hf(query, state, limit=limit)
+            
+            if hf_results:
+                logger.info(f"✅ HF Search API returned {len(hf_results)} results")
+                # Convert HF results to SearchResult objects
+                results = []
+                for row in hf_results:
+                    source_type = row.get('source', 'contact')
+                    name = row.get('name', 'Unknown')
+                    title = row.get('title', '')
+                    jurisdiction = row.get('jurisdiction', row.get('organization_name', ''))
+                    state_code = row.get('state', state or '')
+                    
+                    results.append(SearchResult(
+                        result_type="contact",
+                        title=name,
+                        subtitle=f"{title} - {jurisdiction}, {state_code}",
+                        description=f"{'Local official' if source_type == 'local_officials' else 'Nonprofit officer'} in {jurisdiction}",
+                        url=f"/people/{name.replace(' ', '-')}",
+                        score=1.0,
+                        metadata={
+                            "title": title,
+                            "jurisdiction": jurisdiction,
+                            "state": state_code,
+                            "name": name,
+                            "source": source_type
+                        }
+                    ))
+                return results[:limit]
+        except Exception as e:
+            logger.warning(f"HF Search API failed, falling back to DuckDB: {e}")
+    
+    # STRATEGY 2: Fall back to DuckDB (works with local or remote parquet)
+    logger.info(f"🔍 Using DuckDB {'remote' if IS_HF_SPACES else 'local'} search for '{query}'")
+    return search_contacts_duckdb(query, state, limit)
+
+
+def search_meetings(query: str, state: Optional[str] = None, limit: int = 10) -> List[SearchResult]:
+    """Search meeting transcripts and agendas"""
+    results = []
+    
+    try:
+        # Search state event/meeting files (try new naming first, fallback to old)
+        if state:
+            meeting_files = list(GOLD_DIR.glob(f"states/{state}/events.parquet"))
+            if not meeting_files:
+                meeting_files = list(GOLD_DIR.glob(f"states/{state}/events_events.parquet"))
+            if not meeting_files:
+                meeting_files = list(GOLD_DIR.glob(f"states/{state}/meetings.parquet"))
+        else:
+            meeting_files = list(GOLD_DIR.glob("states/*/events.parquet"))
+            if not meeting_files:
+                meeting_files = list(GOLD_DIR.glob("states/*/events_events.parquet"))
+            if not meeting_files:
+                meeting_files = list(GOLD_DIR.glob("states/*/meetings.parquet"))
+        
+        for file_path in meeting_files[:5]:  # Limit for performance
+            try:
+                df = pd.read_parquet(file_path)
+                state_code = file_path.parent.name
+                
+                # Detect schema - different files have different column names
+                columns = set(df.columns)
+                
+                # Map column names (handle LocalView vs CityScrapers vs other formats)
+                title_col = 'vid_title' if 'vid_title' in columns else ('event_title' if 'event_title' in columns else 'title')
+                body_col = 'caption_text_clean' if 'caption_text_clean' in columns else ('caption_text' if 'caption_text' in columns else ('full_text' if 'full_text' in columns else 'body'))
+                jurisdiction_col = 'place_name' if 'place_name' in columns else ('jurisdiction_name' if 'jurisdiction_name' in columns else 'jurisdiction')
+                date_col = 'meeting_date' if 'meeting_date' in columns else 'date'
+                id_col = 'vid_id' if 'vid_id' in columns else ('meeting_id' if 'meeting_id' in columns else 'id')
+                
+                # Search in title, body, jurisdiction
+                for _, row in df.iterrows():
+                    title = str(row.get(title_col, ''))
+                    body = str(row.get(body_col, ''))[:500]  # First 500 chars
+                    jurisdiction = str(row.get(jurisdiction_col, ''))
+                    meeting_date = str(row.get(date_col, ''))
+                    meeting_id = str(row.get(id_col, ''))
+                    
+                    score = max(
+                        calculate_relevance_score(title, query),
+                        calculate_relevance_score(body, query) * 0.8,  # Body matches slightly lower
+                        calculate_relevance_score(jurisdiction, query) * 0.6
+                    )
+                    
+                    if score > 0.3:
+                        # Extract snippet around query
+                        snippet = body[:200] + "..." if len(body) > 200 else body
+                        
+                        results.append(SearchResult(
+                            result_type="meeting",
+                            title=title,
+                            subtitle=f"{jurisdiction}, {state_code} - {meeting_date}",
+                            description=snippet,
+                            url=f"/documents?meeting_id={meeting_id}",
+                            score=score,
+                            metadata={
+                                "jurisdiction": jurisdiction,
+                                "state": state_code,
+                                "date": meeting_date,
+                                "meeting_id": meeting_id
+                            }
+                        ))
+            except Exception as e:
+                logger.debug(f"Error searching {file_path}: {e}")
+    
+    except Exception as e:
+        logger.error(f"Meeting search error: {e}")
+    
+    results.sort(key=lambda x: x.score, reverse=True)
+    return results[:limit]
+
+
+def count_organizations(state: Optional[str] = None, ntee_code: Optional[str] = None, query: Optional[str] = None) -> int:
+    """Count total organizations matching criteria (for pagination) - cached"""
+    # Create cache key
+    cache_key = f"count_{state}_{ntee_code}_{query}"
+    
+    # Check cache (1 hour TTL)
+    now = datetime.now()
+    if cache_key in _count_cache:
+        cached_time = _count_cache_ttl.get(cache_key)
+        if cached_time and (now - cached_time).total_seconds() < 3600:
+            return _count_cache[cache_key]
+    
+    try:
+        # Determine file path
+        if state:
+            file_pattern = f"{GOLD_DIR}/states/{state}/nonprofits_organizations.parquet"
+        else:
+            file_pattern = f"{GOLD_DIR}/national/nonprofits_organizations.parquet"
+        
+        file_path = Path(file_pattern)
+        if not file_path.exists():
+            return 0
+        
+        conn = duckdb.connect()
+        
+        # Detect schema
+        columns_query = f"DESCRIBE SELECT * FROM '{file_path}' LIMIT 0"
+        available_columns = set([row[0] for row in conn.execute(columns_query).fetchall()])
+        name_col = 'organization_name' if 'organization_name' in available_columns else 'name'
+        ntee_col = 'ntee_code' if 'ntee_code' in available_columns else 'ntee_cd'
+        
+        # Build WHERE clause
+        where_clauses = []
+        params = []
+        
+        if query and query.strip():
+            where_clauses.append(f"LOWER({name_col}) LIKE LOWER(?)")
+            params.append(f'%{query}%')
+        
+        if ntee_code and ntee_col in available_columns:
+            where_clauses.append(f"{ntee_col} LIKE ?")
+            params.append(f'{ntee_code}%')
+        
+        where_sql = " AND ".join(where_clauses) if where_clauses else "TRUE"
+        
+        # Count query
+        count_sql = f"SELECT COUNT(*) FROM '{data_source}' WHERE {where_sql}"
+        result = conn.execute(count_sql, params).fetchone()
+        conn.close()
+        
+        count = result[0] if result else 0
+        
+        # Cache the result
+        _count_cache[cache_key] = count
+        _count_cache_ttl[cache_key] = now
+        
+        return count
+    except Exception as e:
+        logger.error(f"Count error: {e}")
+        return 0
+
+
+def search_organizations(query: str, state: Optional[str] = None, ntee_code: Optional[str] = None, limit: int = 10, offset: int = 0, enrich: bool = False, sort: str = 'relevance', ein: Optional[str] = None) -> List[SearchResult]:
+    """Search nonprofit organizations using DuckDB for fast Parquet queries
+    
+    Args:
+        enrich: If True, fetch additional data from Every.org API (slower)
+        sort: Sort order - 'relevance', 'name-asc', 'name-desc', 'revenue-asc', 'revenue-desc', 'assets-asc', 'assets-desc'
+        ein: If provided, filter to exact EIN match (for direct organization links)
+    """
+    results = []
+    
+    try:
+        # Determine file path
+        if state:
+            file_pattern = f"{GOLD_DIR}/states/{state}/nonprofits_organizations.parquet"
+        else:
+            file_pattern = f"{GOLD_DIR}/national/nonprofits_organizations.parquet"
+        
+        # Get data source (local or remote HuggingFace URL)
+        file_path = Path(file_pattern)
+        data_source = get_data_source(file_path, use_remote=IS_HF_SPACES)
+        
+        # Load parquet with caching (speeds up from 2-3s to <10ms)
+        df = load_parquet_cached(data_source)
+        
+        # Initialize DuckDB connection
+        conn = duckdb.connect()
+        
+        # Query the DataFrame directly (DuckDB can query pandas DataFrames)
+        available_columns = set(df.columns)
+        
+        # Detect column name variations (handle different schemas)
+        name_col = 'organization_name' if 'organization_name' in available_columns else 'name'
+        ntee_col = 'ntee_code' if 'ntee_code' in available_columns else 'ntee_cd'
+        revenue_col = 'form_990_total_revenue' if 'form_990_total_revenue' in available_columns else 'revenue_amt'
+        asset_col = 'form_990_total_assets' if 'form_990_total_assets' in available_columns else 'asset_amt'
+        income_col = 'form_990_net_income' if 'form_990_net_income' in available_columns else 'income_amt'
+        
+        # Build WHERE clauses using detected column names
+        where_clauses = []
+        params = []
+        
+        # EIN filter (exact match - highest priority for direct organization links)
+        if ein and ein.strip():
+            where_clauses.append("ein = ?")
+            params.append(ein.strip())
+        
+        # Search query (case-insensitive LIKE) - only if query provided and no EIN
+        if query and query.strip() and not ein:
+            where_clauses.append(f"LOWER({name_col}) LIKE LOWER(?)")
+            params.append(f'%{query}%')
+        
+        # State filter (if using national file)
+        if state and not file_pattern.startswith(f"{GOLD_DIR}/states/"):
+            where_clauses.append("state = ?")
+            params.append(state)
+        
+        # NTEE code filter
+        if ntee_code and ntee_col in available_columns:
+            where_clauses.append(f"{ntee_col} LIKE ?")
+            params.append(f'{ntee_code}%')
+        
+        # Default to TRUE if no filters (browse all)
+        where_sql = " AND ".join(where_clauses) if where_clauses else "TRUE"
+        
+        # Build column list with proper NULL handling for missing columns
+        select_columns = []
+        
+        # Add core columns (with aliases for consistency)
+        select_columns.append(f'{name_col} as name')
+        select_columns.append('city')
+        select_columns.append('state')
+        select_columns.append(f'{ntee_col} as ntee_cd' if ntee_col in available_columns else 'NULL as ntee_cd')
+        select_columns.append('ein')
+        select_columns.append(f'{revenue_col} as revenue_amt' if revenue_col in available_columns else 'NULL as revenue_amt')
+        select_columns.append(f'{asset_col} as asset_amt' if asset_col in available_columns else 'NULL as asset_amt')
+        select_columns.append(f'{income_col} as income_amt' if income_col in available_columns else 'NULL as income_amt')
+        select_columns.append('tax_period' if 'tax_period' in available_columns else 'NULL as tax_period')
+        
+        # Track enrichment columns (form_990 and bigquery)
+        enrichment_cols = []
+        enrichment_col_map = {}
+        
+        # Check for website columns (multiple possible names) - ALWAYS add if exists
+        website_col_added = False
+        for col_name in ['bigquery_website', 'form_990_website', 'website', 'everyorg_website']:
+            if col_name in available_columns:
+                select_columns.append(f'{col_name} as enrichment_website')
+                enrichment_cols.append('enrichment_website')
+                enrichment_col_map['enrichment_website'] = col_name
+                website_col_added = True
+                logger.debug(f"Added website column: {col_name}")
+                break
+        
+        # Check for mission columns
+        mission_col_added = False
+        for col_name in ['bigquery_mission', 'form_990_mission', 'mission', 'everyorg_mission']:
+            if col_name in available_columns:
+                select_columns.append(f'{col_name} as enrichment_mission')
+                enrichment_cols.append('enrichment_mission')
+                enrichment_col_map['enrichment_mission'] = col_name
+                mission_col_added = True
+                logger.debug(f"Added mission column: {col_name}")
+                break
+        
+        # Check for logo columns
+        logo_col_added = False
+        for col_name in ['logodev_logo_url', 'everyorg_logo_url', 'logo_url']:
+            if col_name in available_columns:
+                select_columns.append(f'{col_name} as enrichment_logo')
+                enrichment_cols.append('enrichment_logo')
+                enrichment_col_map['enrichment_logo'] = col_name
+                logo_col_added = True
+                logger.debug(f"Added logo column: {col_name}")
+                break
+        
+        # Last updated timestamp
+        for col_name in ['bigquery_updated_date', 'form_990_last_updated', 'everyorg_last_updated']:
+            if col_name in available_columns:
+                select_columns.append(f'{col_name} as enrichment_last_updated')
+                enrichment_cols.append('enrichment_last_updated')
+                enrichment_col_map['enrichment_last_updated'] = col_name
+                logger.debug(f"Added timestamp column: {col_name}")
+                break
+        
+        columns_sql = ', '.join(select_columns)
+        
+        # Log what we're selecting
+        logger.info(f"🔍 Enrichment columns to select: {enrichment_cols}")
+        logger.info(f"📋 Full SQL columns: {columns_sql}")
+        
+        # Build ORDER BY clause based on sort parameter
+        order_by_clauses = []
+        
+        if sort == 'name-asc':
+            order_by_clauses.append(f"{name_col} ASC")
+        elif sort == 'name-desc':
+            order_by_clauses.append(f"{name_col} DESC")
+        elif sort == 'revenue-desc':
+            order_by_clauses.append(f"COALESCE(TRY_CAST({revenue_col} AS BIGINT), 0) DESC")
+        elif sort == 'revenue-asc':
+            # Low to high: Show positive values first (smallest to largest), then zeros, then negatives
+            order_by_clauses.append(f"""
+                CASE 
+                    WHEN TRY_CAST({revenue_col} AS BIGINT) IS NULL THEN 3
+                    WHEN TRY_CAST({revenue_col} AS BIGINT) <= 0 THEN 2
+                    ELSE 1
+                END ASC,
+                ABS(COALESCE(TRY_CAST({revenue_col} AS BIGINT), 0)) ASC
+            """)
+        elif sort == 'assets-desc':
+            order_by_clauses.append(f"COALESCE(TRY_CAST({asset_col} AS BIGINT), 0) DESC")
+        elif sort == 'assets-asc':
+            # Low to high: Show positive values first (smallest to largest), then zeros, then negatives
+            order_by_clauses.append(f"""
+                CASE 
+                    WHEN TRY_CAST({asset_col} AS BIGINT) IS NULL THEN 3
+                    WHEN TRY_CAST({asset_col} AS BIGINT) <= 0 THEN 2
+                    ELSE 1
+                END ASC,
+                ABS(COALESCE(TRY_CAST({asset_col} AS BIGINT), 0)) ASC
+            """)
+        elif query and query.strip():
+            # Relevance sort (only for search mode)
+            order_by_clauses.append("score DESC")
+            order_by_clauses.append(f"COALESCE(TRY_CAST({revenue_col} AS BIGINT), 0) DESC")
+        else:
+            # Default browse mode: sort by revenue/assets
+            order_by_clauses.append(f"COALESCE(TRY_CAST({revenue_col} AS BIGINT), 0) DESC")
+            order_by_clauses.append(f"COALESCE(TRY_CAST({asset_col} AS BIGINT), 0) DESC")
+        
+        # Always add name as final sort for consistency
+        if 'name' not in sort:
+            order_by_clauses.append(f"{name_col}")
+        
+        order_by_sql = ', '.join(order_by_clauses)
+        
+        # SQL query with relevance scoring (browse mode if no query)
+        if query and query.strip():
+            # Search mode: score by text match
+            sql = f"""
+                SELECT 
+                    {columns_sql},
+                    CASE 
+                        WHEN LOWER({name_col}) LIKE LOWER(?) THEN 1.5
+                        WHEN LOWER({name_col}) LIKE LOWER(?) THEN 1.0
+                        ELSE 0.5
+                    END as score
+                FROM df
+                WHERE {where_sql}
+                ORDER BY {order_by_sql}
+                LIMIT ? OFFSET ?
+            """
+            # Execute query with scoring parameters
+            query_params = [f'{query}%', f'%{query}%'] + params + [limit, offset]
+        else:
+            # Browse mode: sort by size/activity
+            sql = f"""
+                SELECT 
+                    {columns_sql},
+                    1.0 as score
+                FROM df
+                WHERE {where_sql}
+                ORDER BY {order_by_sql}
+                LIMIT ? OFFSET ?
+            """
+            # Execute query without scoring parameters
+            query_params = params + [limit, offset]
+        
+        rows = conn.execute(sql, query_params).fetchall()
+        
+        # NTEE code descriptions for better context
+        ntee_descriptions = {
+            'E': 'Health Services',
+            'E60': 'Health Support Services',
+            'E61': 'Blood Supply',
+            'E62': 'Emergency Medical Services',
+            'E65': 'Organ & Tissue Banks',
+            'E70': 'Public Health',
+            'E80': 'Health Treatment - Primary Care',
+            'E90': 'Nursing Services',
+            'E20': 'Hospitals & Primary Medical Care',
+            'E30': 'Ambulatory & Primary Health Care',
+            'E32': 'Clinics & Community Health Centers',
+            'P': 'Human Services',
+            'B': 'Education',
+            'X': 'Religion-Related',
+            'A': 'Arts, Culture & Humanities',
+        }
+        
+        # Convert to SearchResult objects with intelligent enrichment
+        for row in rows:
+            # Unpack base columns (now includes tax_period)
+            org_name, city, state_code, ntee, ein, revenue, assets, income, tax_period = row[:9]
+            
+            # Unpack optional enrichment columns if present
+            existing_data = {}
+            idx = 9
+            
+            if 'enrichment_website' in enrichment_cols:
+                existing_data['enrichment_website'] = row[idx]
+                # Only log non-null websites to reduce spam
+                if row[idx] and str(row[idx]) != 'nan':
+                    logger.debug(f"✅ Website: {row[idx]}")
+                idx += 1
+            if 'enrichment_mission' in enrichment_cols:
+                existing_data['enrichment_mission'] = row[idx]
+                idx += 1
+            if 'enrichment_logo' in enrichment_cols:
+                existing_data['enrichment_logo'] = row[idx]
+                idx += 1
+            if 'enrichment_last_updated' in enrichment_cols:
+                existing_data['enrichment_last_updated'] = row[idx]
+                idx += 1
+            
+            score = row[-1]  # Score is always last
+            
+            # Parse tax year from tax_period (format: YYYYMM)
+            tax_year = None
+            if tax_period and str(tax_period).isdigit() and len(str(tax_period)) >= 4:
+                tax_year = int(str(tax_period)[:4])
+            
+            # Get enriched data with intelligent backfill (only if requested)
+            enrichment = get_enrichment_data(ein, existing_data) if (ein and enrich) else {}
+            
+            # Build a more informative description
+            ntee_desc = None
+            if ntee:
+                # Try exact match first, then prefix match
+                ntee_desc = ntee_descriptions.get(ntee)
+                if not ntee_desc:
+                    # Try first character (major category)
+                    ntee_desc = ntee_descriptions.get(ntee[0]) if ntee else None
+            
+            # Use enriched mission as primary description, fallback to NTEE + financial
+            description = enrichment.get('mission') if enrichment.get('mission') else None
+            
+            # Validate mission: if it contains a different org name, it's stale data
+            if description and org_name:
+                # Check if mission mentions a completely different org name
+                # (e.g., "Catalyst Institute" when org name is "CAREQUEST INSTITUTE")
+                mission_lower = description.lower()
+                name_words = set(org_name.lower().split())
+                
+                # If mission starts with an org name that's not in our actual org name, skip it
+                first_sentence = description.split('.')[0].lower()
+                if ' is a nonprofit' in first_sentence or ' is an nonprofit' in first_sentence:
+                    # Extract the subject (organization name before "is a nonprofit")
+                    subject = first_sentence.split(' is a')[0].strip()
+                    subject_words = set(subject.split())
+                    
+                    # If the subject shares NO significant words with our org name, it's stale
+                    # (e.g., "catalyst institute" vs "carequest institute")
+                    significant_words = subject_words - {'the', 'a', 'an', 'of', 'for', 'and', 'inc', 'llc'}
+                    name_significant = name_words - {'the', 'a', 'an', 'of', 'for', 'and', 'inc', 'llc', 'institute'}
+                    
+                    if significant_words and not (significant_words & name_significant):
+                        # Stale data - mission talks about a different org
+                        logger.warning(f"Stale mission data for {org_name}: '{subject}' != '{org_name}'")
+                        description = None
+            
+            if not description:
+                description_parts = []
+                if ntee_desc:
+                    description_parts.append(ntee_desc)
+                
+                # Convert financial data to numbers (handle None and string types)
+                try:
+                    revenue_num = float(revenue) if revenue else 0
+                    assets_num = float(assets) if assets else 0
+                except (ValueError, TypeError):
+                    revenue_num = 0
+                    assets_num = 0
+                
+                if revenue_num > 0:
+                    description_parts.append(f"Revenue: ${revenue_num:,.0f}")
+                elif assets_num > 0:
+                    description_parts.append(f"Assets: ${assets_num:,.0f}")
+                
+                if not description_parts:
+                    description_parts.append(f"Nonprofit serving {city}")
+                
+                description = " • ".join(description_parts)
+            
+            # Build metadata with enriched fields
+            metadata = {
+                "ein": ein,
+                "city": city,
+                "state": state_code,
+                "ntee_code": ntee,
+                "revenue": revenue,
+                "assets": assets,
+                "income": income,
+                "tax_year": tax_year,
+                "data_sources": []
+            }
+            
+            # ALWAYS add enrichment from parquet columns (existing_data) - no enrich flag needed
+            if existing_data.get('enrichment_website'):
+                metadata['website'] = existing_data['enrichment_website']
+                metadata['data_sources'].append('cached')
+            
+            if existing_data.get('enrichment_mission'):
+                metadata['mission'] = existing_data['enrichment_mission']
+                if 'cached' not in metadata['data_sources']:
+                    metadata['data_sources'].append('cached')
+            
+            if existing_data.get('enrichment_logo'):
+                metadata['logo_url'] = existing_data['enrichment_logo']
+                if 'cached' not in metadata['data_sources']:
+                    metadata['data_sources'].append('cached')
+            
+            # Add API enrichment if requested (enrich=true)
+            if enrichment:
+                if enrichment.get('website') and not metadata.get('website'):
+                    metadata['website'] = enrichment['website']
+                if enrichment.get('logo_url'):
+                    metadata['logo_url'] = enrichment['logo_url']
+                if enrichment.get('profile_url'):
+                    metadata['profile_url'] = enrichment['profile_url']
+                if enrichment.get('causes'):
+                    metadata['causes'] = enrichment['causes']
+                # Add API data sources
+                for source in enrichment.get('data_sources', []):
+                    if source not in metadata['data_sources']:
+                        metadata['data_sources'].append(source)
+            
+            results.append(SearchResult(
+                result_type="organization",
+                title=org_name if org_name else "Unknown",
+                subtitle=f"{city}, {state_code}" + (f" - NTEE: {ntee}" if ntee else ""),
+                description=description,
+                url=f"/search?types=organizations&state={state_code}&ein={ein}",
+                score=score,
+                metadata=metadata
+            ))
+        
+        conn.close()
+        logger.info(f"DuckDB search found {len(results)} organizations for query '{query}'")
+        
+    except Exception as e:
+        logger.error(f"Organization search error: {e}")
+    
+    return results
+
+
+def search_causes(query: str, limit: int = 10) -> List[SearchResult]:
+    """Search causes and NTEE categories - supports browse mode"""
+    results = []
+    
+    try:
+        # Get data source (local or remote HuggingFace URL)
+        ntee_file = GOLD_DIR / "reference" / "causes_ntee_codes.parquet"
+        data_source = get_data_source(ntee_file, use_remote=IS_HF_SPACES)
+        
+        # Load with caching
+        df = load_parquet_cached(data_source)
+        logger.debug(f"Loaded {len(df)} NTEE codes from cache")
+        
+        for _, row in df.iterrows():
+            code = str(row.get('ntee_code', ''))
+            description = str(row.get('description', ''))
+            ntee_type = str(row.get('ntee_type', ''))
+            
+            # Browse mode: return all causes
+            # Search mode: filter by relevance
+            if query and query.strip():
+                score = max(
+                    calculate_relevance_score(description, query),
+                    calculate_relevance_score(code, query)
+                )
+                if score <= 0.3:
+                    continue  # Skip low relevance results
+            else:
+                score = 1.0  # Default score for browse mode
+            
+            results.append(SearchResult(
+                result_type="cause",
+                title=description,
+                subtitle=f"NTEE Code: {code}",
+                description=f"Category type: {ntee_type}",
+                url=f"/nonprofits?ntee_code={code}",
+                score=score,
+                metadata={
+                    "ntee_code": code,
+                    "ntee_type": ntee_type
+                }
+            ))
+        
+        logger.info(f"Found {len(results)} cause results for query '{query}'")
+    
+    except Exception as e:
+        logger.error(f"Cause search error: {e}")
+    
+    results.sort(key=lambda x: x.score, reverse=True)
+    return results[:limit]
+
+
+def search_jurisdictions(query: str, state: Optional[str] = None, city: Optional[str] = None, jurisdiction_levels: Optional[List[str]] = None, limit: int = 10, offset: int = 0) -> List[SearchResult]:
+    """Search cities, counties, townships, and school districts using DuckDB"""
+    all_results = []
+    
+    try:
+        conn = duckdb.connect()
+        
+        # Map frontend level IDs to file keys
+        level_mapping = {
+            'city': 'city',
+            'county': 'county',
+            'town': 'township',
+            'village': 'township',
+            'school_district': 'school district',
+            'special_district': 'school district',  # Use school district as proxy
+            'state': None  # States handled separately if needed
+        }
+        
+        # Define jurisdiction files with priority scores
+        jurisdiction_files = {
+            'county': (f"{GOLD_DIR}/reference/jurisdictions_counties.parquet", 1.3),  # Boost counties
+            'city': (f"{GOLD_DIR}/reference/jurisdictions_cities.parquet", 1.0),
+            'school district': (f"{GOLD_DIR}/reference/jurisdictions_school_districts.parquet", 1.1),  # Boost school districts
+            'township': (f"{GOLD_DIR}/reference/jurisdictions_townships.parquet", 0.9)
+        }
+        
+        # Filter jurisdiction files based on selected levels
+        if jurisdiction_levels:
+            # Map selected levels to file keys
+            selected_file_keys = set()
+            for level in jurisdiction_levels:
+                file_key = level_mapping.get(level)
+                if file_key:
+                    selected_file_keys.add(file_key)
+            
+            # Filter to only selected types
+            if selected_file_keys:
+                jurisdiction_files = {
+                    k: v for k, v in jurisdiction_files.items() 
+                    if k in selected_file_keys
+                }
+        
+        # Fetch enough results from each type to ensure diversity
+        # Even with small limits, we want representation from each type
+        per_type_limit = max(limit, 15)
+        
+        for jtype, (file_path, type_score) in jurisdiction_files.items():
+            file_path_obj = Path(file_path)
+            if not file_path_obj.exists():
+                continue
+            
+            try:
+                # Build SQL query - use state column (lowercase)
+                where_clauses = []
+                params = []
+                
+                if state:
+                    where_clauses.append("state = ?")
+                    params.append(state)
+                
+                if city and query:
+                    # If city is specified, search for jurisdictions matching the city name
+                    where_clauses.append("LOWER(NAME) LIKE LOWER(?)")
+                    params.append(f"%{city}%")
+                elif query:
+                    # General search across jurisdiction names
+                    where_clauses.append("LOWER(NAME) LIKE LOWER(?)")
+                    params.append(f"%{query}%")
+                
+                where_clause = " AND ".join(where_clauses) if where_clauses else "1=1"
+                
+                # Calculate name match score if query provided
+                score_expr = f"{type_score}"
+                if query:
+                    score_expr = f"""CASE 
+                        WHEN LOWER(NAME) = LOWER('{query}') THEN {type_score} * 2.0
+                        WHEN LOWER(NAME) LIKE LOWER('{query}%') THEN {type_score} * 1.5
+                        ELSE {type_score}
+                    END"""
+                
+                sql = f"""
+                    SELECT 
+                        NAME as name,
+                        state,
+                        GEOID as geoid,
+                        jurisdiction_type,
+                        {score_expr} as score
+                    FROM read_parquet(?)
+                    WHERE {where_clause}
+                    ORDER BY score DESC, NAME ASC
+                    LIMIT ?
+                """
+                
+                query_params = [str(file_path_obj)] + params + [per_type_limit]
+                df = conn.execute(sql, query_params).fetchdf()
+                
+                for _, row in df.iterrows():
+                    jurisdiction_label = row['jurisdiction_type'].replace('_', ' ').title()
+                    all_results.append(SearchResult(
+                        result_type='jurisdiction',
+                        title=f"{row['name']}",
+                        subtitle=f"{jurisdiction_label}",
+                        description=f"{jurisdiction_label} in {row['state']}",
+                        url=f"/jurisdictions/{row['geoid']}",
+                        score=float(row['score']),
+                        metadata={
+                            'state': row['state'],
+                            'geoid': row['geoid'],
+                            'type': row['jurisdiction_type']
+                        }
+                    ))
+            
+            except Exception as e:
+                logger.error(f"Error searching {jtype} jurisdictions: {e}")
+                continue
+    
+    except Exception as e:
+        logger.error(f"Jurisdiction search error: {e}")
+    
+    # Sort all results by score, then apply pagination
+    all_results.sort(key=lambda x: (x.score, x.title), reverse=True)
+    return all_results[offset:offset + limit]
+
+
+@router.get("/api/search")
+@router.get("/api/search/", include_in_schema=False)
+async def unified_search(
+    q: Optional[str] = Query(None, description="Search query (optional - browse by filters if omitted)"),
+    types: Optional[str] = Query(None, description="Comma-separated result types: contacts,meetings,organizations,causes,jurisdictions"),
+    state: Optional[str] = Query(None, description="Filter by state (2-letter code)"),
+    city: Optional[str] = Query(None, description="Filter by city name"),
+    jurisdiction_levels: Optional[str] = Query(None, description="Comma-separated jurisdiction levels: city,county,town,village,school_district,special_district,state"),
+    ntee_code: Optional[str] = Query(None, description="Filter organizations by NTEE code"),
+    ein: Optional[str] = Query(None, description="Filter organizations by exact EIN (for direct organization links)"),
+    limit: int = Query(20, ge=1, le=100, description="Maximum results per type"),
+    offset: int = Query(0, ge=0, description="Number of results to skip (for pagination)"),
+    page: int = Query(1, ge=1, description="Page number (alternative to offset)"),
+    enrich: bool = Query(False, description="Enable API enrichment (slower - fetches logos, causes from Every.org)"),
+    sort: str = Query('relevance', description="Sort order: relevance, name-asc, name-desc, revenue-asc, revenue-desc, assets-asc, assets-desc")
+):
+    """
+    Unified search across all data types
+    
+    Search for contacts, meetings, organizations, and causes in one query.
+    **NEW:** Query is now optional - you can browse by state/type without searching!
+    
+    **Pagination:**
+    - Use `offset` to skip results: `offset=20` skips first 20 results
+    - Or use `page` with `limit`: `page=2&limit=20` gets results 21-40
+    - `offset` takes precedence if both are provided
+    
+    **Examples:**
+    - `/api/search?q=dental` - Search everything for "dental"
+    - `/api/search?types=organizations&state=GA` - Browse all orgs in Georgia
+    - `/api/search?q=budget&types=meetings` - Search only meetings
+    - `/api/search?q=health&state=AL` - Search in Alabama only
+    - `/api/search?q=education&types=organizations,causes` - Search orgs and causes
+    - `/api/search?q=health&state=MA&page=2&limit=20` - Page 2 of MA health results
+    """
+    # 🔍 DEBUG LOGGING - Log all incoming request parameters
+    logger.info(f"🔍 SEARCH REQUEST: q={q!r}, types={types!r}, state={state!r}, city={city!r}, jurisdiction_levels={jurisdiction_levels!r}, ntee_code={ntee_code!r}, ein={ein!r}, limit={limit}, offset={offset}, page={page}, enrich={enrich}, sort={sort!r}")
+    
+    try:
+        # Calculate offset from page if offset not explicitly provided
+        if offset == 0 and page > 1:
+            offset = (page - 1) * limit
+        
+        # Parse requested types
+        if types:
+            requested_types = [t.strip() for t in types.split(',')]
+        else:
+            requested_types = ['contacts', 'meetings', 'organizations', 'causes', 'jurisdictions']
+        
+        # Parse jurisdiction levels if provided
+        jurisdiction_levels_list = None
+        if jurisdiction_levels:
+            jurisdiction_levels_list = [level.strip() for level in jurisdiction_levels.split(',')]
+        
+        logger.info(f"📋 Requested types: {requested_types}, calculated offset: {offset}")
+        
+        all_results = []
+        
+        # Optimize for single-type browse mode (no query)
+        # Let database handle pagination for efficiency
+        use_db_pagination = not q and len(requested_types) == 1
+        
+        if use_db_pagination:
+            # Single-type browse: pass offset to DB for efficient pagination
+            search_limit = limit
+            search_offset = offset
+        else:
+            # Multi-type or search mode: fetch extra for mixing/sorting
+            search_limit = offset + limit + 100
+            search_offset = 0
+        
+        if 'contacts' in requested_types:
+            # Use PostgreSQL for fast indexed search
+            contact_results_pg = await search_postgres.search_contacts_pg(q, state, limit=search_limit)
+            contact_results = [convert_pg_result(r) for r in contact_results_pg]
+            logger.info(f"👤 Contacts search returned {len(contact_results)} results")
+            all_results.extend(contact_results)
+        
+        if 'meetings' in requested_types:
+            # Use PostgreSQL for fast indexed search
+            meeting_results_pg = await search_postgres.search_events_pg(q, state, limit=search_limit)
+            meeting_results = [convert_pg_result(r) for r in meeting_results_pg]
+            logger.info(f"📅 Meetings search returned {len(meeting_results)} results")
+            all_results.extend(meeting_results)
+        
+        if 'organizations' in requested_types:
+            # Use PostgreSQL for fast indexed search
+            org_results_pg = await search_postgres.search_organizations_pg(q, state, ntee_code, ein, limit=search_limit, offset=search_offset, sort=sort)
+            org_results = [convert_pg_result(r) for r in org_results_pg]
+            logger.info(f"🏢 Organizations search returned {len(org_results)} results")
+            all_results.extend(org_results)
+        
+        if 'causes' in requested_types:
+            cause_results = search_causes(q or "", limit=search_limit)
+            logger.info(f"🎯 Causes search returned {len(cause_results)} results")
+            all_results.extend(cause_results)
+        
+        if 'jurisdictions' in requested_types:
+            # Use PostgreSQL for fast indexed search
+            jurisdiction_results_pg = await search_postgres.search_jurisdictions_pg(q, state, city, jurisdiction_levels_list, limit=search_limit, offset=search_offset)
+            jurisdiction_results = [convert_pg_result(r) for r in jurisdiction_results_pg]
+            logger.info(f"🏛️ Jurisdictions search returned {len(jurisdiction_results)} results")
+            all_results.extend(jurisdiction_results)
+        
+        # Sort all results by score
+        all_results.sort(key=lambda x: x.score, reverse=True)
+        
+        logger.info(f"📊 Total combined results: {len(all_results)}, applying pagination (offset={offset}, limit={limit})")
+        
+        # Apply pagination
+        if use_db_pagination:
+            # DB already paginated - use all results
+            paginated_results = all_results
+        else:
+            # Paginate in-memory from combined results
+            paginated_results = all_results[offset:offset + limit]
+        
+        logger.info(f"✂️ Paginated results: {len(paginated_results)} items")
+        
+        # Group by type for response
+        grouped_results = {
+            'contacts': [r.to_dict() for r in paginated_results if r.result_type == 'contact'],
+            'meetings': [r.to_dict() for r in paginated_results if r.result_type == 'meeting'],
+            'organizations': [r.to_dict() for r in paginated_results if r.result_type == 'organization'],
+            'causes': [r.to_dict() for r in paginated_results if r.result_type == 'cause'],
+            'jurisdictions': [r.to_dict() for r in paginated_results if r.result_type == 'jurisdiction'],
+        }
+        
+        logger.info(f"📦 Grouped results - contacts:{len(grouped_results['contacts'])}, meetings:{len(grouped_results['meetings'])}, organizations:{len(grouped_results['organizations'])}, causes:{len(grouped_results['causes'])}, jurisdictions:{len(grouped_results['jurisdictions'])}")
+        
+        # Calculate total results per type (from all_results before pagination)
+        type_totals = {
+            'contacts': len([r for r in all_results if r.result_type == 'contact']),
+            'meetings': len([r for r in all_results if r.result_type == 'meeting']),
+            'organizations': len([r for r in all_results if r.result_type == 'organization']),
+            'causes': len([r for r in all_results if r.result_type == 'cause']),
+            'jurisdictions': len([r for r in all_results if r.result_type == 'jurisdiction']),
+        }
+        
+        # Calculate total results
+        # For single-type browse mode, get accurate count from database
+        if not q and len(requested_types) == 1:
+            # Browse mode: count total matching records in DB
+            if 'organizations' in requested_types:
+                total_results = count_organizations(state=state, ntee_code=ntee_code, query=q)
+                type_totals['organizations'] = total_results  # Use accurate DB count
+            else:
+                # Fallback to fetched results for other types
+                total_results = len(all_results)
+        else:
+            # Search/multi-type mode: use fetched results
+            total_results = len(all_results)
+        
+        total_pages = (total_results + limit - 1) // limit  # Ceiling division
+        
+        response_data = {
+            "query": q or "",
+            "total_results": total_results,
+            "type_totals": type_totals,  # Add per-type totals
+            "results": grouped_results,
+            "pagination": {
+                "page": page if offset == 0 or offset == (page - 1) * limit else (offset // limit) + 1,
+                "limit": limit,
+                "offset": offset,
+                "total_pages": total_pages,
+                "has_next": offset + limit < total_results,
+                "has_prev": offset > 0
+            },
+            "filters": {
+                "state": state,
+                "ntee_code": ntee_code,
+                "types": requested_types,
+                "sort": sort
+            }
+        }
+        
+        logger.info(f"✅ Search complete - returning {total_results} total results, {len(paginated_results)} on this page")
+        return response_data
+    
+    except Exception as e:
+        logger.error(f"❌ Search error: {type(e).__name__}: {e}")
+        logger.exception("Full traceback:")
+        
+        # Parse error into structured response
+        error_detail = parse_error(e, context={
+            "query": q,
+            "state": state,
+            "types": types,
+            "data_type": "search"
+        })
+        
+        return JSONResponse(
+            status_code=500,
+            content=error_detail.model_dump()
+        )
+
+
+@router.get("/api/search/suggest")
+async def search_suggestions(
+    q: str = Query(..., min_length=1, description="Partial search query"),
+    limit: int = Query(5, ge=1, le=20, description="Maximum suggestions")
+):
+    """
+    Get search suggestions/autocomplete
+    
+    Returns quick suggestions as user types
+    """
+    try:
+        suggestions = []
+        
+        # Common search terms
+        common_terms = [
+            "dental health", "oral health", "affordable housing", "public transit",
+            "school funding", "budget", "water quality", "parks", "zoning",
+            "police", "fire department", "mental health", "food assistance",
+            "senior services", "youth programs", "employment", "job training"
+        ]
+        
+        # Filter suggestions
+        q_lower = q.lower()
+        suggestions = [term for term in common_terms if q_lower in term.lower()]
+        
+        return {
+            "query": q,
+            "suggestions": suggestions[:limit]
+        }
+    
+    except Exception as e:
+        logger.error(f"Suggestion error: {e}")
+        
+        # Parse error into structured response
+        error_detail = parse_error(e, context={
+            "query": q,
+            "data_type": "suggestions"
+        })
+        
+        return JSONResponse(
+            status_code=500,
+            content=error_detail.model_dump()
+        )

api/routes/search_postgres.py

@@ -0,0 +1,535 @@
+"""
+PostgreSQL-based search functions
+Uses indexed search tables for fast queries (10-100x faster than parquet)
+"""
+from typing import Optional, List
+from loguru import logger
+import asyncpg
+import os
+from datetime import datetime
+from dataclasses import dataclass
+
+# Database configuration
+# Priority: NEON_DATABASE_URL_DEV (local) > NEON_DATABASE_URL (production)
+NEON_DATABASE_URL_DEV = os.getenv('NEON_DATABASE_URL_DEV')
+NEON_DATABASE_URL = os.getenv('NEON_DATABASE_URL')
+
+# Use dev database for local development, production database for deployed environments
+DATABASE_URL = NEON_DATABASE_URL_DEV or NEON_DATABASE_URL
+
+# Connection pool (created on first request)
+_db_pool = None
+
+
+@dataclass
+class SearchResult:
+    """Search result data class"""
+    result_type: str
+    title: str
+    subtitle: str
+    description: str
+    url: str
+    score: float
+    metadata: dict
+
+
+async def get_db_pool():
+    """Get or create database connection pool"""
+    global _db_pool
+    if _db_pool is None:
+        if not DATABASE_URL:
+            raise ValueError("DATABASE_URL not configured")
+        
+        db_type = "Development (Local PostgreSQL)" if NEON_DATABASE_URL_DEV else "Production (Neon)"
+        logger.info(f"🗄️  Creating connection pool to {db_type}")
+        
+        _db_pool = await asyncpg.create_pool(DATABASE_URL, min_size=2, max_size=20)
+    return _db_pool
+
+
+async def search_jurisdictions_pg(
+    query: Optional[str] = None,
+    state: Optional[str] = None,
+    city: Optional[str] = None,
+    jurisdiction_levels: Optional[List[str]] = None,
+    limit: int = 10,
+    offset: int = 0
+) -> List[SearchResult]:
+    """
+    Search jurisdictions using PostgreSQL full-text search
+    
+    Args:
+        query: Search text (jurisdiction name)
+        state: Filter by state code (e.g., 'MA')
+        city: Filter by city name  
+        jurisdiction_levels: Filter by types (city, county, town, school_district, etc.)
+        limit: Max results
+        offset: Pagination offset
+    
+    Returns:
+        List of SearchResult objects
+    """
+    try:
+        pool = await get_db_pool()
+        
+        # Map frontend level IDs to database types
+        level_mapping = {
+            'city': 'city',
+            'county': 'county',
+            'town': 'town',
+            'village': 'village',
+            'school_district': 'school_district',
+            'special_district': 'special_district',
+            'state': 'state'
+        }
+        
+        # Build SQL query
+        where_clauses = []
+        params = []
+        param_idx = 1
+        has_query = query and query.strip()
+        
+        # Text search filter first (if present) - must be $1 for score calculation
+        score_param_idx = None
+        if has_query:
+            where_clauses.append(f"to_tsvector('english', name) @@ plainto_tsquery('english', ${param_idx})")
+            params.append(query)
+            score_param_idx = param_idx
+            param_idx += 1
+        
+        # State filter
+        if state:
+            where_clauses.append(f"state = ${param_idx}")
+            params.append(state.upper())
+            param_idx += 1
+        
+        # City filter
+        if city:
+            where_clauses.append(f"LOWER(name) LIKE LOWER(${param_idx})")
+            params.append(f"%{city}%")
+            param_idx += 1
+        
+        # Jurisdiction level filter
+        if jurisdiction_levels:
+            db_types = [level_mapping.get(level) for level in jurisdiction_levels if level_mapping.get(level)]
+            if db_types:
+                placeholders = ','.join([f"${param_idx + i}" for i in range(len(db_types))])
+                where_clauses.append(f"type IN ({placeholders})")
+                params.extend(db_types)
+                param_idx += len(db_types)
+        
+        # Build final WHERE clause
+        where_sql = " AND ".join(where_clauses) if where_clauses else "TRUE"
+        
+        # Select clause and order by
+        if has_query:
+            select_score = f"ts_rank(to_tsvector('english', name), plainto_tsquery('english', ${score_param_idx})) as score"
+            order_by = f"score DESC, name ASC"
+        else:
+            select_score = "1.0 as score"
+            order_by = "name ASC"
+        
+        # Build complete query
+        sql = f"""
+            SELECT 
+                name,
+                type,
+                state,
+                county,
+                geoid,
+                population,
+                {select_score}
+            FROM jurisdictions_search
+            WHERE {where_sql}
+            ORDER BY {order_by}
+            LIMIT ${param_idx}
+            OFFSET ${param_idx + 1}
+        """
+        
+        # Add limit and offset
+        params.append(limit)
+        params.append(offset)
+        
+        async with pool.acquire() as conn:
+            rows = await conn.fetch(sql, *params)
+            
+            results = []
+            for row in rows:
+                jurisdiction_label = row['type'].replace('_', ' ').title()
+                
+                results.append(SearchResult(
+                    result_type='jurisdiction',
+                    title=row['name'],
+                    subtitle=f"{jurisdiction_label}",
+                    description=f"{jurisdiction_label} in {row['state']}" + (f" • Pop: {row['population']:,}" if row['population'] else ""),
+                    url=f"/jurisdictions/{row['geoid']}" if row['geoid'] else f"/jurisdictions/{row['name']}",
+                    score=float(row.get('score', 1.0)) if query else 1.0,
+                    metadata={
+                        'state': row['state'],
+                        'geoid': row['geoid'],
+                        'type': row['type'],
+                        'county': row['county'],
+                        'population': row['population']
+                    }
+                ))
+            
+            logger.info(f"🏛️  PostgreSQL jurisdictions search: {len(results)} results")
+            return results
+            
+    except Exception as e:
+        logger.error(f"PostgreSQL jurisdictions search error: {e}")
+        return []
+
+
+async def search_contacts_pg(
+    query: Optional[str] = None,
+    state: Optional[str] = None,
+    limit: int = 10
+) -> List[SearchResult]:
+    """
+    Search contacts (nonprofit officers, local officials) using PostgreSQL
+    
+    Args:
+        query: Search text (name, title, organization)
+        state: Filter by state code
+        limit: Max results
+    
+    Returns:
+        List of SearchResult objects
+    """
+    try:
+        pool = await get_db_pool()
+        
+        # Build WHERE clauses
+        where_clauses = []
+        params = []
+        param_idx = 1
+        
+        if state:
+            where_clauses.append(f"state = ${param_idx}")
+            params.append(state.upper())
+            param_idx += 1
+        
+        # Text search across name and organization
+        if query and query.strip():
+            where_clauses.append(f"""(
+                to_tsvector('english', name) @@ plainto_tsquery('english', ${param_idx})
+                OR to_tsvector('english', COALESCE(organization_name, '')) @@ plainto_tsquery('english', ${param_idx})
+                OR LOWER(title) LIKE LOWER(${param_idx + 1})
+            )""")
+            params.append(query)
+            params.append(f"%{query}%")
+            param_idx += 2
+            
+            # Rank by relevance
+            order_by = f"""
+                GREATEST(
+                    ts_rank(to_tsvector('english', name), plainto_tsquery('english', ${param_idx - 2})),
+                    ts_rank(to_tsvector('english', COALESCE(organization_name, '')), plainto_tsquery('english', ${param_idx - 2}))
+                ) DESC, name ASC
+            """
+        else:
+            order_by = "name ASC"
+        
+        where_sql = " AND ".join(where_clauses) if where_clauses else "TRUE"
+        
+        sql = f"""
+            SELECT 
+                name,
+                title,
+                organization_name,
+                organization_ein,
+                city,
+                state,
+                role_type,
+                compensation,
+                source
+            FROM contacts_search
+            WHERE {where_sql}
+            ORDER BY {order_by}
+            LIMIT ${param_idx}
+        """
+        params.append(limit)
+        
+        async with pool.acquire() as conn:
+            rows = await conn.fetch(sql, *params)
+            
+            results = []
+            for row in rows:
+                org_display = row['organization_name'] or 'Unknown Organization'
+                location = f"{row['city']}, {row['state']}" if row['city'] and row['state'] else (row['state'] or '')
+                
+                results.append(SearchResult(
+                    result_type='contact',
+                    title=row['name'],
+                    subtitle=f"{row['title'] or 'Officer'} - {org_display}",
+                    description=f"{row['role_type'] or 'Contact'} in {location}",
+                    url=f"/people/{row['name'].replace(' ', '-')}",
+                    score=1.0,
+                    metadata={
+                        'title': row['title'],
+                        'organization': org_display,
+                        'organization_ein': row['organization_ein'],
+                        'state': row['state'],
+                        'city': row['city'],
+                        'role_type': row['role_type'],
+                        'compensation': row['compensation'],
+                        'source': row['source']
+                    }
+                ))
+            
+            logger.info(f"👤 PostgreSQL contacts search: {len(results)} results")
+            return results
+            
+    except Exception as e:
+        logger.error(f"PostgreSQL contacts search error: {e}")
+        return []
+
+
+async def search_organizations_pg(
+    query: Optional[str] = None,
+    state: Optional[str] = None,
+    ntee_code: Optional[str] = None,
+    ein: Optional[str] = None,
+    limit: int = 10,
+    offset: int = 0,
+    sort: str = 'relevance'
+) -> List[SearchResult]:
+    """
+    Search nonprofit organizations using PostgreSQL
+    
+    Args:
+        query: Search text (organization name)
+        state: Filter by state code
+        ntee_code: Filter by NTEE code prefix
+        ein: Exact EIN match
+        limit: Max results
+        offset: Pagination offset
+        sort: Sort order (relevance, name-asc, name-desc, revenue-asc, revenue-desc, assets-asc, assets-desc)
+    
+    Returns:
+        List of SearchResult objects
+    """
+    try:
+        pool = await get_db_pool()
+        
+        # Build WHERE clauses
+        where_clauses = []
+        params = []
+        param_idx = 1
+        
+        # EIN exact match (highest priority)
+        if ein:
+            where_clauses.append(f"ein = ${param_idx}")
+            params.append(ein.strip())
+            param_idx += 1
+        
+        # State filter
+        if state:
+            where_clauses.append(f"state = ${param_idx}")
+            params.append(state.upper())
+            param_idx += 1
+        
+        # NTEE code filter
+        if ntee_code:
+            where_clauses.append(f"ntee_code LIKE ${param_idx}")
+            params.append(f"{ntee_code}%")
+            param_idx += 1
+        
+        # Text search (if no EIN specified)
+        if query and query.strip() and not ein:
+            where_clauses.append(f"to_tsvector('english', name) @@ plainto_tsquery('english', ${param_idx})")
+            params.append(query)
+            param_idx += 1
+        
+        where_sql = " AND ".join(where_clauses) if where_clauses else "TRUE"
+        
+        # Determine sort order
+        if sort == 'name-asc':
+            order_by = "name ASC"
+        elif sort == 'name-desc':
+            order_by = "name DESC"
+        elif sort == 'revenue-asc':
+            order_by = "revenue ASC NULLS LAST"
+        elif sort == 'revenue-desc':
+            order_by = "revenue DESC NULLS LAST"
+        elif sort == 'assets-asc':
+            order_by = "assets ASC NULLS LAST"
+        elif sort == 'assets-desc':
+            order_by = "assets DESC NULLS LAST"
+        elif query and query.strip() and not ein:
+            # Relevance ranking for text search
+            order_by = f"ts_rank(to_tsvector('english', name), plainto_tsquery('english', ${param_idx - 1})) DESC, name ASC"
+        else:
+            order_by = "name ASC"
+        
+        sql = f"""
+            SELECT 
+                ein,
+                name,
+                city,
+                state,
+                county,
+                ntee_code,
+                ntee_description,
+                revenue,
+                assets,
+                income,
+                tax_period
+            FROM nonprofits_search
+            WHERE {where_sql}
+            ORDER BY {order_by}
+            LIMIT ${param_idx}
+            OFFSET ${param_idx + 1}
+        """
+        params.append(limit)
+        params.append(offset)
+        
+        async with pool.acquire() as conn:
+            rows = await conn.fetch(sql, *params)
+            
+            results = []
+            for row in rows:
+                location = f"{row['city']}, {row['state']}" if row['city'] and row['state'] else (row['state'] or '')
+                
+                # Format financials
+                financials = []
+                if row['revenue']:
+                    financials.append(f"Revenue: ${row['revenue']:,}")
+                if row['assets']:
+                    financials.append(f"Assets: ${row['assets']:,}")
+                
+                description = f"{row['ntee_description'] or 'Nonprofit organization'}"
+                if financials:
+                    description += " • " + " • ".join(financials)
+                
+                results.append(SearchResult(
+                    result_type='organization',
+                    title=row['name'],
+                    subtitle=location,
+                    description=description,
+                    url=f"/organizations/{row['ein']}",
+                    score=1.0,
+                    metadata={
+                        'ein': row['ein'],
+                        'state': row['state'],
+                        'city': row['city'],
+                        'county': row['county'],
+                        'ntee_code': row['ntee_code'],
+                        'ntee_description': row['ntee_description'],
+                        'revenue': row['revenue'],
+                        'assets': row['assets'],
+                        'income': row['income'],
+                        'tax_period': row['tax_period']
+                    }
+                ))
+            
+            logger.info(f"🏢 PostgreSQL organizations search: {len(results)} results")
+            return results
+            
+    except Exception as e:
+        logger.error(f"PostgreSQL organizations search error: {e}")
+        return []
+
+
+async def search_events_pg(
+    query: Optional[str] = None,
+    state: Optional[str] = None,
+    limit: int = 10
+) -> List[SearchResult]:
+    """
+    Search meetings/events using PostgreSQL
+    
+    Args:
+        query: Search text (title, jurisdiction, description)
+        state: Filter by state code
+        limit: Max results
+    
+    Returns:
+        List of SearchResult objects
+    """
+    try:
+        pool = await get_db_pool()
+        
+        # Build WHERE clauses
+        where_clauses = []
+        params = []
+        param_idx = 1
+        
+        if state:
+            where_clauses.append(f"state = ${param_idx}")
+            params.append(state.upper())
+            param_idx += 1
+        
+        # Text search
+        if query and query.strip():
+            where_clauses.append(f"""(
+                to_tsvector('english', title) @@ plainto_tsquery('english', ${param_idx})
+                OR LOWER(jurisdiction_name) LIKE LOWER(${param_idx + 1})
+            )""")
+            params.append(query)
+            params.append(f"%{query}%")
+            param_idx += 2
+            
+            order_by = f"ts_rank(to_tsvector('english', title), plainto_tsquery('english', ${param_idx - 2})) DESC, event_date DESC"
+        else:
+            order_by = "event_date DESC"
+        
+        where_sql = " AND ".join(where_clauses) if where_clauses else "TRUE"
+        
+        sql = f"""
+            SELECT 
+                id,
+                title,
+                description,
+                event_date,
+                jurisdiction_name,
+                jurisdiction_type,
+                state,
+                city,
+                video_url,
+                agenda_url
+            FROM events_search
+            WHERE {where_sql}
+            ORDER BY {order_by}
+            LIMIT ${param_idx}
+        """
+        params.append(limit)
+        
+        async with pool.acquire() as conn:
+            rows = await conn.fetch(sql, *params)
+            
+            results = []
+            for row in rows:
+                location = f"{row['jurisdiction_name']}, {row['state']}" if row['jurisdiction_name'] and row['state'] else ''
+                date_str = row['event_date'].strftime('%Y-%m-%d') if row['event_date'] else ''
+                
+                description = (row['description'] or '')[:200]
+                if len(description) == 200:
+                    description += "..."
+                
+                results.append(SearchResult(
+                    result_type='meeting',
+                    title=row['title'],
+                    subtitle=f"{location} - {date_str}",
+                    description=description,
+                    url=f"/documents?meeting_id={row['id']}",
+                    score=1.0,
+                    metadata={
+                        'jurisdiction': row['jurisdiction_name'],
+                        'jurisdiction_type': row['jurisdiction_type'],
+                        'state': row['state'],
+                        'city': row['city'],
+                        'date': date_str,
+                        'meeting_id': row['id'],
+                        'video_url': row['video_url'],
+                        'agenda_url': row['agenda_url']
+                    }
+                ))
+            
+            logger.info(f"📅 PostgreSQL events search: {len(results)} results")
+            return results
+            
+    except Exception as e:
+        logger.error(f"PostgreSQL events search error: {e}")
+        return []

api/routes/social.py

@@ -0,0 +1,544 @@
+"""
+Social features API routes - following, followers, feeds
+"""
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.orm import Session
+from sqlalchemy import func, or_, and_
+from typing import List, Optional
+from pydantic import BaseModel
+from datetime import datetime
+
+from api.database import get_db
+from api.auth import get_current_user
+from api.models import (
+    User, Official, Organization, Cause,
+    UserFollow, OfficialFollow, OrganizationFollow, CauseFollow
+)
+
+router = APIRouter(prefix="/api/social", tags=["social"])
+
+
+# ============================================================================
+# PYDANTIC MODELS
+# ============================================================================
+
+class FollowResponse(BaseModel):
+    """Response after follow/unfollow action"""
+    success: bool
+    following: bool
+    follower_count: int
+    message: str
+
+
+class FollowerStats(BaseModel):
+    """Follower/following statistics"""
+    followers: int
+    following: int
+    following_users: int
+    following_officials: int
+    following_organizations: int
+    following_causes: int
+
+
+class UserSummary(BaseModel):
+    """Brief user info for lists"""
+    id: int
+    username: Optional[str]
+    full_name: Optional[str]
+    avatar_url: Optional[str]
+    created_at: datetime
+    
+    class Config:
+        from_attributes = True
+
+
+class OfficialSummary(BaseModel):
+    """Brief official info for lists"""
+    id: int
+    name: str
+    slug: str
+    title: Optional[str]
+    photo_url: Optional[str]
+    office: Optional[str]
+    city: Optional[str]
+    state: Optional[str]
+    follower_count: int
+    is_verified: bool
+    
+    class Config:
+        from_attributes = True
+
+
+class OrganizationSummary(BaseModel):
+    """Brief organization info for lists"""
+    id: int
+    name: str
+    slug: str
+    description: Optional[str]
+    logo_url: Optional[str]
+    org_type: Optional[str]
+    city: Optional[str]
+    state: Optional[str]
+    follower_count: int
+    is_verified: bool
+    
+    class Config:
+        from_attributes = True
+
+
+class CauseSummary(BaseModel):
+    """Brief cause info for lists"""
+    id: int
+    name: str
+    slug: str
+    description: Optional[str]
+    icon_url: Optional[str]
+    color: Optional[str]
+    category: Optional[str]
+    follower_count: int
+    
+    class Config:
+        from_attributes = True
+
+
+# ============================================================================
+# FOLLOW/UNFOLLOW ACTIONS
+# ============================================================================
+
+@router.post("/follow/user/{user_id}")
+async def follow_user(
+    user_id: int,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+) -> FollowResponse:
+    """Follow another user"""
+    
+    if current_user.id == user_id:
+        raise HTTPException(status_code=400, detail="Cannot follow yourself")
+    
+    # Check if target user exists
+    target_user = db.query(User).filter(User.id == user_id).first()
+    if not target_user:
+        raise HTTPException(status_code=404, detail="User not found")
+    
+    # Check if already following
+    existing = db.query(UserFollow).filter(
+        UserFollow.follower_id == current_user.id,
+        UserFollow.following_id == user_id
+    ).first()
+    
+    if existing:
+        return FollowResponse(
+            success=True,
+            following=True,
+            follower_count=db.query(UserFollow).filter(UserFollow.following_id == user_id).count(),
+            message="Already following this user"
+        )
+    
+    # Create follow
+    follow = UserFollow(follower_id=current_user.id, following_id=user_id)
+    db.add(follow)
+    db.commit()
+    
+    follower_count = db.query(UserFollow).filter(UserFollow.following_id == user_id).count()
+    
+    return FollowResponse(
+        success=True,
+        following=True,
+        follower_count=follower_count,
+        message="Successfully followed user"
+    )
+
+
+@router.delete("/follow/user/{user_id}")
+async def unfollow_user(
+    user_id: int,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+) -> FollowResponse:
+    """Unfollow a user"""
+    
+    follow = db.query(UserFollow).filter(
+        UserFollow.follower_id == current_user.id,
+        UserFollow.following_id == user_id
+    ).first()
+    
+    if not follow:
+        return FollowResponse(
+            success=True,
+            following=False,
+            follower_count=db.query(UserFollow).filter(UserFollow.following_id == user_id).count(),
+            message="Not following this user"
+        )
+    
+    db.delete(follow)
+    db.commit()
+    
+    follower_count = db.query(UserFollow).filter(UserFollow.following_id == user_id).count()
+    
+    return FollowResponse(
+        success=True,
+        following=False,
+        follower_count=follower_count,
+        message="Successfully unfollowed user"
+    )
+
+
+@router.post("/follow/official/{official_id}")
+async def follow_official(
+    official_id: int,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+) -> FollowResponse:
+    """Follow an official"""
+    
+    # Check if official exists
+    official = db.query(Official).filter(Official.id == official_id).first()
+    if not official:
+        raise HTTPException(status_code=404, detail="Official not found")
+    
+    # Check if already following
+    existing = db.query(OfficialFollow).filter(
+        OfficialFollow.user_id == current_user.id,
+        OfficialFollow.official_id == official_id
+    ).first()
+    
+    if existing:
+        return FollowResponse(
+            success=True,
+            following=True,
+            follower_count=official.follower_count,
+            message="Already following this official"
+        )
+    
+    # Create follow
+    follow = OfficialFollow(user_id=current_user.id, official_id=official_id)
+    db.add(follow)
+    
+    # Update follower count
+    official.follower_count += 1
+    db.commit()
+    
+    return FollowResponse(
+        success=True,
+        following=True,
+        follower_count=official.follower_count,
+        message="Successfully followed official"
+    )
+
+
+@router.delete("/follow/official/{official_id}")
+async def unfollow_official(
+    official_id: int,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+) -> FollowResponse:
+    """Unfollow an official"""
+    
+    official = db.query(Official).filter(Official.id == official_id).first()
+    if not official:
+        raise HTTPException(status_code=404, detail="Official not found")
+    
+    follow = db.query(OfficialFollow).filter(
+        OfficialFollow.user_id == current_user.id,
+        OfficialFollow.official_id == official_id
+    ).first()
+    
+    if not follow:
+        return FollowResponse(
+            success=True,
+            following=False,
+            follower_count=official.follower_count,
+            message="Not following this official"
+        )
+    
+    db.delete(follow)
+    official.follower_count = max(0, official.follower_count - 1)
+    db.commit()
+    
+    return FollowResponse(
+        success=True,
+        following=False,
+        follower_count=official.follower_count,
+        message="Successfully unfollowed official"
+    )
+
+
+@router.post("/follow/organization/{org_id}")
+async def follow_organization(
+    org_id: int,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+) -> FollowResponse:
+    """Follow an organization"""
+    
+    org = db.query(Organization).filter(Organization.id == org_id).first()
+    if not org:
+        raise HTTPException(status_code=404, detail="Organization not found")
+    
+    existing = db.query(OrganizationFollow).filter(
+        OrganizationFollow.user_id == current_user.id,
+        OrganizationFollow.organization_id == org_id
+    ).first()
+    
+    if existing:
+        return FollowResponse(
+            success=True,
+            following=True,
+            follower_count=org.follower_count,
+            message="Already following this organization"
+        )
+    
+    follow = OrganizationFollow(user_id=current_user.id, organization_id=org_id)
+    db.add(follow)
+    org.follower_count += 1
+    db.commit()
+    
+    return FollowResponse(
+        success=True,
+        following=True,
+        follower_count=org.follower_count,
+        message="Successfully followed organization"
+    )
+
+
+@router.delete("/follow/organization/{org_id}")
+async def unfollow_organization(
+    org_id: int,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+) -> FollowResponse:
+    """Unfollow an organization"""
+    
+    org = db.query(Organization).filter(Organization.id == org_id).first()
+    if not org:
+        raise HTTPException(status_code=404, detail="Organization not found")
+    
+    follow = db.query(OrganizationFollow).filter(
+        OrganizationFollow.user_id == current_user.id,
+        OrganizationFollow.organization_id == org_id
+    ).first()
+    
+    if not follow:
+        return FollowResponse(
+            success=True,
+            following=False,
+            follower_count=org.follower_count,
+            message="Not following this organization"
+        )
+    
+    db.delete(follow)
+    org.follower_count = max(0, org.follower_count - 1)
+    db.commit()
+    
+    return FollowResponse(
+        success=True,
+        following=False,
+        follower_count=org.follower_count,
+        message="Successfully unfollowed organization"
+    )
+
+
+@router.post("/follow/cause/{cause_id}")
+async def follow_cause(
+    cause_id: int,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+) -> FollowResponse:
+    """Follow a cause/topic"""
+    
+    cause = db.query(Cause).filter(Cause.id == cause_id).first()
+    if not cause:
+        raise HTTPException(status_code=404, detail="Cause not found")
+    
+    existing = db.query(CauseFollow).filter(
+        CauseFollow.user_id == current_user.id,
+        CauseFollow.cause_id == cause_id
+    ).first()
+    
+    if existing:
+        return FollowResponse(
+            success=True,
+            following=True,
+            follower_count=cause.follower_count,
+            message="Already following this cause"
+        )
+    
+    follow = CauseFollow(user_id=current_user.id, cause_id=cause_id)
+    db.add(follow)
+    cause.follower_count += 1
+    db.commit()
+    
+    return FollowResponse(
+        success=True,
+        following=True,
+        follower_count=cause.follower_count,
+        message="Successfully followed cause"
+    )
+
+
+@router.delete("/follow/cause/{cause_id}")
+async def unfollow_cause(
+    cause_id: int,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+) -> FollowResponse:
+    """Unfollow a cause/topic"""
+    
+    cause = db.query(Cause).filter(Cause.id == cause_id).first()
+    if not cause:
+        raise HTTPException(status_code=404, detail="Cause not found")
+    
+    follow = db.query(CauseFollow).filter(
+        CauseFollow.user_id == current_user.id,
+        CauseFollow.cause_id == cause_id
+    ).first()
+    
+    if not follow:
+        return FollowResponse(
+            success=True,
+            following=False,
+            follower_count=cause.follower_count,
+            message="Not following this cause"
+        )
+    
+    db.delete(follow)
+    cause.follower_count = max(0, cause.follower_count - 1)
+    db.commit()
+    
+    return FollowResponse(
+        success=True,
+        following=False,
+        follower_count=cause.follower_count,
+        message="Successfully unfollowed cause"
+    )
+
+
+# ============================================================================
+# CHECK FOLLOW STATUS
+# ============================================================================
+
+@router.get("/following/status")
+async def check_following_status(
+    user_id: Optional[int] = None,
+    leader_id: Optional[int] = None,
+    org_id: Optional[int] = None,
+    cause_id: Optional[int] = None,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+) -> dict:
+    """Check if current user is following various entities"""
+    
+    result = {}
+    
+    if user_id:
+        result['user'] = db.query(UserFollow).filter(
+            UserFollow.follower_id == current_user.id,
+            UserFollow.following_id == user_id
+        ).first() is not None
+    
+    if leader_id:
+        result['official'] = db.query(OfficialFollow).filter(
+            OfficialFollow.user_id == current_user.id,
+            OfficialFollow.official_id == leader_id
+        ).first() is not None
+    
+    if org_id:
+        result['organization'] = db.query(OrganizationFollow).filter(
+            OrganizationFollow.user_id == current_user.id,
+            OrganizationFollow.organization_id == org_id
+        ).first() is not None
+    
+    if cause_id:
+        result['cause'] = db.query(CauseFollow).filter(
+            CauseFollow.user_id == current_user.id,
+            CauseFollow.cause_id == cause_id
+        ).first() is not None
+    
+    return result
+
+
+# ============================================================================
+# FOLLOWER/FOLLOWING LISTS
+# ============================================================================
+
+@router.get("/stats")
+async def get_follower_stats(
+    user_id: Optional[int] = None,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+) -> FollowerStats:
+    """Get follower/following statistics for a user"""
+    
+    target_id = user_id if user_id else current_user.id
+    
+    # Count followers (people following this user)
+    followers = db.query(UserFollow).filter(UserFollow.following_id == target_id).count()
+    
+    # Count following (users this person follows)
+    following_users = db.query(UserFollow).filter(UserFollow.follower_id == target_id).count()
+    following_officials = db.query(OfficialFollow).filter(OfficialFollow.user_id == target_id).count()
+    following_orgs = db.query(OrganizationFollow).filter(OrganizationFollow.user_id == target_id).count()
+    following_causes = db.query(CauseFollow).filter(CauseFollow.user_id == target_id).count()
+    
+    total_following = following_users + following_officials + following_orgs + following_causes
+    
+    return FollowerStats(
+        followers=followers,
+        following=total_following,
+        following_users=following_users,
+        following_officials=following_officials,
+        following_organizations=following_orgs,
+        following_causes=following_causes
+    )
+
+
+@router.get("/following/officials")
+async def get_following_officials(
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+) -> List[OfficialSummary]:
+    """Get list of officials the current user is following"""
+    
+    officials = db.query(Official).join(
+        OfficialFollow,
+        OfficialFollow.official_id == Official.id
+    ).filter(
+        OfficialFollow.user_id == current_user.id
+    ).all()
+    
+    return [OfficialSummary.from_orm(official) for official in officials]
+
+
+@router.get("/following/organizations")
+async def get_following_organizations(
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+) -> List[OrganizationSummary]:
+    """Get list of organizations the current user is following"""
+    
+    orgs = db.query(Organization).join(
+        OrganizationFollow,
+        OrganizationFollow.organization_id == Organization.id
+    ).filter(
+        OrganizationFollow.user_id == current_user.id
+    ).all()
+    
+    return [OrganizationSummary.from_orm(org) for org in orgs]
+
+
+@router.get("/following/causes")
+async def get_following_causes(
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+) -> List[CauseSummary]:
+    """Get list of causes the current user is following"""
+    
+    causes = db.query(Cause).join(
+        CauseFollow,
+        CauseFollow.cause_id == Cause.id
+    ).filter(
+        CauseFollow.user_id == current_user.id
+    ).all()
+    
+    return [CauseSummary.from_orm(cause) for cause in causes]

api/routes/stats.py

@@ -0,0 +1,453 @@
+"""
+Statistics endpoint with cached metrics from real data at multiple geographic levels
+"""
+from fastapi import APIRouter, HTTPException, Query
+from pathlib import Path
+import pandas as pd
+from datetime import datetime, timedelta
+from typing import Dict, Any, Optional
+from loguru import logger
+
+router = APIRouter()
+
+# Multi-level cache: {cache_key: {stats_data, timestamp}}
+# Cache key format: "national" or "state:MA" or "county:MA:Suffolk" or "city:MA:Boston"
+STATS_CACHE: Dict[str, Dict[str, Any]] = {}
+CACHE_DURATION = timedelta(hours=1)
+
+
+def count_parquet_records(pattern: str, filter_func=None) -> int:
+    """
+    Count total records across matching parquet files
+    
+    Args:
+        pattern: Glob pattern for files
+        filter_func: Optional function to filter DataFrame rows
+    """
+    files = list(Path('data/gold').glob(pattern))
+    total = 0
+    for file in files:
+        try:
+            df = pd.read_parquet(file)
+            if filter_func:
+                df = df[filter_func(df)]
+            total += len(df)
+        except Exception as e:
+            print(f"Warning: Could not read {file}: {e}")
+    return total
+
+
+def calculate_stats(state: Optional[str] = None, 
+                   county: Optional[str] = None, 
+                   city: Optional[str] = None) -> Dict[str, Any]:
+    """
+    Calculate statistics from parquet files with optional geographic filtering
+    
+    Args:
+        state: Two-letter state code (e.g., 'MA')
+        county: County name (e.g., 'Suffolk County')
+        city: City name (e.g., 'Boston')
+    """
+    
+    # Determine geographic level
+    if city and state:
+        level = 'city'
+        if county:
+            location_display = f"{city}, {county}, {state}"
+        else:
+            location_display = f"{city}, {state}"
+    elif county and state:
+        level = 'county'
+        location_display = f"{county}, {state}"
+    elif state:
+        level = 'state'
+        location_display = state
+    else:
+        level = 'national'
+        location_display = 'United States'
+    
+    # Count jurisdictions (cities, counties, townships, school districts)
+    if state:
+        # Filter to specific state's jurisdictions
+        def filter_state(df):
+            state_col = 'state' if 'state' in df.columns else 'STATE'
+            if state_col not in df.columns:
+                return pd.Series([False] * len(df))
+            return df[state_col].str.upper() == state.upper()
+        
+        # For city level, show just that city (1 jurisdiction)
+        if city:
+            # When a city is selected, show 4 jurisdictions:
+            # 1. City, 2. County, 3. State, 4. School District
+            jurisdictions = 4  # City, County, State, School District
+        elif county:
+            # Count cities/townships in this county
+            cities_file = Path('data/gold/reference/jurisdictions_cities.parquet')
+            townships_file = Path('data/gold/reference/jurisdictions_townships.parquet')
+            count = 0
+            
+            if cities_file.exists():
+                df = pd.read_parquet(cities_file)
+                state_col = 'state' if 'state' in df.columns else 'STATE'
+                if state_col in df.columns:
+                    df = df[df[state_col].str.upper() == state.upper()]
+                    # Filter by county name (NAME column contains county info in some cases)
+                    # For now, count all in state - proper county filtering needs geocoding
+                    count += len(df)
+            
+            if townships_file.exists():
+                df = pd.read_parquet(townships_file)
+                state_col = 'state' if 'state' in df.columns else 'STATE'
+                if state_col in df.columns:
+                    df = df[df[state_col].str.upper() == state.upper()]
+                    count += len(df)
+            
+            jurisdictions = count if count > 0 else 1  # At least the county itself
+        else:
+            # State level - count all jurisdictions
+            jurisdictions = count_parquet_records('reference/jurisdictions_*.parquet', filter_state)
+        
+        school_districts = count_parquet_records('reference/jurisdictions_school_districts.parquet', filter_state)
+    else:
+        jurisdictions = count_parquet_records('reference/jurisdictions_*.parquet')
+        school_districts = count_parquet_records('reference/jurisdictions_school_districts.parquet')
+    
+    # Count nonprofits
+    if state:
+        # Read specific state's nonprofit file
+        state_file = Path(f'data/gold/states/{state}/nonprofits_organizations.parquet')
+        if state_file.exists():
+            df = pd.read_parquet(state_file)
+            
+            # Filter by county if specified
+            if county:
+                county_col = 'COUNTY' if 'COUNTY' in df.columns else 'county'
+                if county_col in df.columns:
+                    df = df[df[county_col].str.contains(county, case=False, na=False)]
+            
+            # Filter by city if specified  
+            if city:
+                city_col = 'CITY' if 'CITY' in df.columns else 'city'
+                if city_col in df.columns:
+                    df = df[df[city_col].str.contains(city, case=False, na=False)]
+            
+            nonprofits = len(df)
+        else:
+            nonprofits = 0
+    else:
+        nonprofits = count_parquet_records('states/*/nonprofits_organizations.parquet')
+    
+    # Count events/meetings (try new naming first, fallback to old)
+    if state:
+        # Try new naming first
+        event_pattern = f'states/{state}/events.parquet'
+        event_file = Path(f'data/gold/{event_pattern}')
+        
+        if not event_file.exists():
+            # Try old events_events naming
+            event_pattern = f'states/{state}/events_events.parquet'
+            event_file = Path(f'data/gold/{event_pattern}')
+        
+        if not event_file.exists():
+            # Fallback to original meetings naming
+            event_pattern = f'states/{state}/meetings.parquet'
+            event_file = Path(f'data/gold/{event_pattern}')
+        
+        if city and event_file.exists():
+            # Filter by city
+            df = pd.read_parquet(event_file)
+            place_col = 'place_name' if 'place_name' in df.columns else ('jurisdiction_name' if 'jurisdiction_name' in df.columns else 'jurisdiction')
+            if place_col in df.columns:
+                # Match city name (case-insensitive)
+                df = df[df[place_col].str.contains(city, case=False, na=False)]
+            meetings = len(df)
+        else:
+            meetings = count_parquet_records(event_pattern)
+    else:
+        # Try new naming first for all states
+        meetings = count_parquet_records('states/*/events.parquet')
+        if meetings == 0:
+            # Try old events_events naming
+            meetings = count_parquet_records('states/*/events_events.parquet')
+        if meetings == 0:
+            # Fallback to original meetings naming
+            meetings = count_parquet_records('states/*/meetings.parquet')
+    
+    # Count contacts
+    if state:
+        contact_pattern = f'states/{state}/contacts_*.parquet'
+        contact_files = list(Path('data/gold/states').glob(f'{state}/contacts_*.parquet'))
+        
+        if city and contact_files:
+            # Filter by city across all contact files
+            contacts = 0
+            for contact_file in contact_files:
+                try:
+                    df = pd.read_parquet(contact_file)
+                    jurisdiction_col = 'jurisdiction' if 'jurisdiction' in df.columns else 'city'
+                    if jurisdiction_col in df.columns:
+                        df = df[df[jurisdiction_col].str.contains(city, case=False, na=False)]
+                    contacts += len(df)
+                except Exception as e:
+                    logger.error(f"Error filtering contacts by city in {contact_file}: {e}")
+                    continue
+        else:
+            contacts = count_parquet_records(contact_pattern)
+    else:
+        contacts = count_parquet_records('states/*/contacts_*.parquet')
+    
+    # Count causes (NTEE codes - always national)
+    causes = count_parquet_records('reference/causes_ntee_codes.parquet')
+    
+    # Count states with data
+    states_with_data = len(list(Path('data/gold/states').glob('*/')))
+    
+    # Count domains
+    domains = count_parquet_records('reference/domains_*.parquet')
+    
+    # Format display values - use ACTUAL counts only, no extrapolation
+    # Don't make up numbers we don't have
+    nonprofits_display = f'{nonprofits:,}'
+    meetings_display = f'{meetings:,}'
+    contacts_display = f'{contacts:,}'
+    
+    # Build jurisdictions breakdown for city-level views
+    jurisdictions_breakdown = None
+    if city and state:
+        jurisdictions_breakdown = [
+            {'type': 'City', 'name': city},
+            {'type': 'County', 'name': county if county else 'County (TBD)'},
+            {'type': 'State', 'name': state},
+            {'type': 'School District', 'name': f'{city} School District'}
+        ]
+    
+    return {
+        'level': level,
+        'location': location_display,
+        'state': state,
+        'county': county,
+        'city': city,
+        
+        # Core counts
+        'jurisdictions': jurisdictions,
+        'jurisdictions_display': f'{jurisdictions:,}',
+        'jurisdictions_breakdown': jurisdictions_breakdown,  # List of jurisdiction types for city-level
+        'school_districts': school_districts,
+        'school_districts_display': f'{school_districts:,}',
+        
+        # Nonprofits (actual counts only)
+        'nonprofits_current': nonprofits,
+        'nonprofits_display': nonprofits_display,
+        
+        # Meetings (actual counts only)
+        'meetings_current': meetings,
+        'meetings_display': meetings_display,
+        
+        # Contacts (actual counts only)
+        'contacts_current': contacts,
+        'contacts_display': contacts_display,
+        
+        # Other metrics
+        'causes': causes,
+        'causes_display': f'{causes}',
+        'states_with_data': states_with_data,
+        'domains': domains,
+        'last_updated': datetime.now().isoformat(),
+        
+        # Calculated metrics (use N/A for unavailable data)
+        'budget_tracked': 'N/A',
+        'fact_checks': 'N/A',
+        'grant_opportunities': '1,000s',
+        'churches': f'{int(nonprofits * 0.1):,}' if nonprofits > 0 else '4,372',
+        'policy_decisions': 'N/A',
+        'states_total': states_with_data,
+    }
+
+
+def get_cached_stats(state: Optional[str] = None, 
+                    county: Optional[str] = None, 
+                    city: Optional[str] = None) -> Dict[str, Any]:
+    """Get stats with multi-level caching"""
+    global STATS_CACHE
+    
+    # Build cache key based on geographic level
+    if city and state:
+        # City level (county is optional)
+        if county:
+            cache_key = f"city:{state}:{county}:{city}"
+        else:
+            cache_key = f"city:{state}:{city}"
+    elif county and state:
+        cache_key = f"county:{state}:{county}"
+    elif state:
+        cache_key = f"state:{state}"
+    else:
+        cache_key = "national"
+    
+    now = datetime.now()
+    
+    # Check if cached stats exist and are still valid
+    if cache_key in STATS_CACHE:
+        cached_entry = STATS_CACHE[cache_key]
+        cache_timestamp = cached_entry.get('_cache_timestamp')
+        
+        if cache_timestamp and (now - cache_timestamp) < CACHE_DURATION:
+            # Return cached stats (remove internal timestamp before returning)
+            stats = cached_entry.copy()
+            stats.pop('_cache_timestamp', None)
+            return stats
+    
+    # Calculate fresh stats
+    try:
+        stats = calculate_stats(state=state, county=county, city=city)
+        
+        # Add to cache with timestamp
+        cache_entry = stats.copy()
+        cache_entry['_cache_timestamp'] = now
+        STATS_CACHE[cache_key] = cache_entry
+        
+        return stats
+    except Exception as e:
+        print(f"Error calculating stats for {cache_key}: {e}")
+        
+        # Return fallback stats if calculation fails (use real numbers only)
+        return {
+            'level': 'national' if not state else ('state' if not county else ('county' if not city else 'city')),
+            'location': state or 'United States',
+            'jurisdictions_display': '925',
+            'nonprofits_display': '43,726',
+            'meetings_display': '6,913',
+            'contacts_display': '362',
+            'school_districts_display': '306',
+            'causes_display': '196',
+            'churches': '4,372',
+            'budget_tracked': 'N/A',
+            'fact_checks': 'N/A',
+            'grant_opportunities': '1,000s',
+            'policy_decisions': 'N/A',
+            'states_with_data': 5,
+            'states_total': 5,
+            'last_updated': now.isoformat(),
+            'error': str(e)
+        }
+
+
+@router.get("/stats")
+async def get_stats(
+    state: Optional[str] = Query(None, description="Two-letter state code (e.g., 'MA')"),
+    county: Optional[str] = Query(None, description="County name (e.g., 'Suffolk County')"),
+    city: Optional[str] = Query(None, description="City name (e.g., 'Boston')")
+):
+    """
+    Get platform statistics from real data with optional geographic filtering
+    
+    **Examples:**
+    - `/api/stats` - National statistics
+    - `/api/stats?state=MA` - Massachusetts statistics  
+    - `/api/stats?state=MA&county=Suffolk` - Suffolk County, MA statistics
+    - `/api/stats?state=MA&county=Suffolk&city=Boston` - Boston, MA statistics
+    
+    **Returns:** Cached metrics calculated from parquet files:
+    - Jurisdictions tracked (cities, counties, townships, school districts)
+    - Nonprofits monitored 
+    - Meetings analyzed
+    - Officials and contacts tracked
+    - Causes and NTEE codes
+    
+    **Cache duration:** 1 hour per geographic level
+    """
+    try:
+        stats = get_cached_stats(state=state, county=county, city=city)
+        return {
+            'success': True,
+            'data': stats
+        }
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Error fetching stats: {str(e)}")
+
+
+@router.get("/stats/detailed")
+async def get_detailed_stats(
+    state: Optional[str] = Query(None, description="Two-letter state code (e.g., 'MA')")
+):
+    """
+    Get detailed statistics including breakdowns by state
+    
+    Returns:
+    - Overall totals
+    - Per-state breakdowns (if no state specified)
+    - Data quality metrics
+    """
+    try:
+        stats = get_cached_stats(state=state)
+        
+        # Add state-by-state breakdown (only for national view)
+        if not state:
+            states = {}
+            for state_dir in Path('data/gold/states').glob('*/'):
+                state_code = state_dir.name
+                state_stats = {}
+                
+                # Count each data type for this state
+                for data_type in ['nonprofits_organizations', 'meetings', 'contacts_nonprofit_officers']:
+                    file = state_dir / f'{data_type}.parquet'
+                    if file.exists():
+                        try:
+                            df = pd.read_parquet(file)
+                            state_stats[data_type] = len(df)
+                        except:
+                            pass
+                
+                if state_stats:
+                    states[state_code] = state_stats
+            
+            return {
+                'success': True,
+                'data': {
+                    **stats,
+                    'state_breakdown': states
+                }
+            }
+        else:
+            return {
+                'success': True,
+                'data': stats
+            }
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Error fetching detailed stats: {str(e)}")
+
+
+@router.post("/stats/refresh")
+async def refresh_stats(
+    state: Optional[str] = Query(None, description="State to refresh (or all if not specified)")
+):
+    """
+    Force refresh of statistics cache
+    
+    Useful after data updates or imports.
+    Can refresh a specific state or all levels.
+    """
+    global STATS_CACHE
+    
+    try:
+        if state:
+            # Clear cache for specific state and its derivatives
+            keys_to_remove = [k for k in STATS_CACHE.keys() if k.startswith(f'state:{state}') or k.startswith(f'county:{state}') or k.startswith(f'city:{state}')]
+            for key in keys_to_remove:
+                STATS_CACHE.pop(key, None)
+            message = f'Statistics cache refreshed for {state}'
+        else:
+            # Clear all cache
+            STATS_CACHE = {}
+            message = 'All statistics cache refreshed'
+        
+        # Recalculate to warm cache
+        stats = get_cached_stats(state=state)
+        
+        return {
+            'success': True,
+            'message': message,
+            'data': stats
+        }
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Error refreshing stats: {str(e)}")

api/routes/stats_neon.py

@@ -0,0 +1,322 @@
+"""
+Statistics endpoint using Neon Postgres (fast!)
+Replaces parquet file scanning with indexed database queries
+"""
+from fastapi import APIRouter, HTTPException, Query
+from typing import Dict, Any, Optional
+from loguru import logger
+import os
+import asyncpg
+from datetime import datetime, timedelta
+
+router = APIRouter()
+
+# Cache for stats (TTL: 5 minutes - data in Neon changes infrequently)
+STATS_CACHE: Dict[str, Dict[str, Any]] = {}
+CACHE_DURATION = timedelta(minutes=5)
+
+# Get database URL from environment
+# Priority: NEON_DATABASE_URL_DEV (local) > NEON_DATABASE_URL (production)
+NEON_DATABASE_URL_DEV = os.getenv('NEON_DATABASE_URL_DEV')
+NEON_DATABASE_URL = os.getenv('NEON_DATABASE_URL')
+
+# Use dev database for local development, production database for deployed environments
+DATABASE_URL = NEON_DATABASE_URL_DEV or NEON_DATABASE_URL
+
+# Connection pool (created on first request)
+_db_pool = None
+
+
+async def get_db_pool():
+    """Get or create database connection pool"""
+    global _db_pool
+    if _db_pool is None:
+        if not DATABASE_URL:
+            raise ValueError("DATABASE_URL not configured (set NEON_DATABASE_URL_DEV or NEON_DATABASE_URL)")
+        
+        # Log which database we're using
+        db_type = "Development (Local PostgreSQL)" if NEON_DATABASE_URL_DEV else "Production (Neon)"
+        logger.info(f"🗄️  [Stats] Connecting to {db_type}: {DATABASE_URL[:50]}...")
+        
+        _db_pool = await asyncpg.create_pool(DATABASE_URL, min_size=1, max_size=10)
+    return _db_pool
+
+
+@router.get("/stats")
+async def get_stats(
+    state: Optional[str] = Query(None, description="Two-letter state code (e.g., MA)"),
+    county: Optional[str] = Query(None, description="County name (e.g., Suffolk County)"),
+    city: Optional[str] = Query(None, description="City name (e.g., Boston)")
+):
+    """
+    Get statistics from Neon Postgres database
+    
+    **Performance**: ~10-50ms (vs 3-10 seconds with parquet files)
+    
+    - **National**: GET /api/stats
+    - **State**: GET /api/stats?state=MA
+    - **County**: GET /api/stats?state=MA&county=Suffolk%20County
+    - **City**: GET /api/stats?state=MA&city=Boston
+    
+    Returns comprehensive statistics including:
+    - Jurisdiction counts (cities, counties, school districts)
+    - Nonprofit counts and financials
+    - Event/meeting counts
+    - Contact/officer counts
+    """
+    
+    try:
+        # Determine cache key and query parameters
+        if city and state:
+            cache_key = f"city:{state}:{city}"
+            level = 'city'
+            location_display = f"{city}, {state}"
+        elif county and state:
+            cache_key = f"county:{state}:{county}"
+            level = 'county'
+            location_display = f"{county}, {state}"
+        elif state:
+            cache_key = f"state:{state}"
+            level = 'state'
+            location_display = state
+        else:
+            cache_key = "national"
+            level = 'national'
+            location_display = 'United States'
+        
+        # Check cache
+        if cache_key in STATS_CACHE:
+            cached = STATS_CACHE[cache_key]
+            if datetime.now() - cached['timestamp'] < CACHE_DURATION:
+                logger.debug(f"🚀 Cache hit for {cache_key}")
+                return cached['stats']
+        
+        # Query Neon database
+        logger.info(f"📊 Fetching stats from Neon: {cache_key}")
+        stats = await fetch_stats_from_neon(level, state, county, city)
+        
+        if not stats:
+            # No data found - return empty stats
+            stats = {
+                'location': location_display,
+                'level': level,
+                'state': state,
+                'county': county,
+                'city': city,
+                'jurisdictions': 0,
+                'school_districts': 0,
+                'nonprofits': 0,
+                'events': 0,
+                'bills': 0,
+                'contacts': 0,
+                'total_revenue': 0,
+                'total_assets': 0,
+                'last_updated': None,
+                'source': 'neon',
+                'note': 'No data available for this location'
+            }
+        else:
+            # Format response
+            stats = {
+                'location': location_display,
+                'level': level,
+                'state': state,
+                'county': county,
+                'city': city,
+                'jurisdictions': stats.get('jurisdictions_count', 0),
+                'school_districts': stats.get('school_districts_count', 0),
+                'nonprofits': stats.get('nonprofits_count', 0),
+                'events': stats.get('events_count', 0),
+                'bills': stats.get('bills_count', 0),
+                'contacts': stats.get('contacts_count', 0),
+                'total_revenue': stats.get('total_revenue', 0),
+                'total_assets': stats.get('total_assets', 0),
+                'last_updated': stats.get('last_updated'),
+                'source': 'neon'
+            }
+        
+        # Cache result
+        STATS_CACHE[cache_key] = {
+            'stats': stats,
+            'timestamp': datetime.now()
+        }
+        
+        return stats
+        
+    except Exception as e:
+        logger.error(f"❌ Error fetching stats: {e}")
+        raise HTTPException(status_code=500, detail=f"Database error: {str(e)}")
+
+
+async def fetch_stats_from_neon(
+    level: str,
+    state: Optional[str] = None,
+    county: Optional[str] = None,
+    city: Optional[str] = None
+) -> Optional[Dict[str, Any]]:
+    """
+    Fetch statistics from Neon database
+    
+    Args:
+        level: 'national', 'state', 'county', or 'city'
+        state: State code (if applicable)
+        county: County name (if applicable)
+        city: City name (if applicable)
+    
+    Returns:
+        Dictionary with stats or None if not found
+    """
+    try:
+        pool = await get_db_pool()
+        
+        async with pool.acquire() as conn:
+            # Build query based on level
+            if level == 'national':
+                query = """
+                    SELECT * FROM stats_aggregates 
+                    WHERE level = 'national'
+                    LIMIT 1
+                """
+                result = await conn.fetchrow(query)
+                
+            elif level == 'state':
+                query = """
+                    SELECT * FROM stats_aggregates 
+                    WHERE level = 'state' AND UPPER(state) = UPPER($1)
+                    LIMIT 1
+                """
+                result = await conn.fetchrow(query, state)
+                
+            elif level == 'county':
+                # Try county-level stats first
+                query = """
+                    SELECT * FROM stats_aggregates 
+                    WHERE level = 'county' 
+                      AND UPPER(state) = UPPER($1) 
+                      AND county ILIKE $2
+                    LIMIT 1
+                """
+                result = await conn.fetchrow(query, state, f"%{county}%")
+                
+                # Fall back to state-level if county not found
+                if not result and state:
+                    logger.info(f"County '{county}' not found in stats, falling back to state '{state}'")
+                    query = """
+                        SELECT * FROM stats_aggregates 
+                        WHERE level = 'state' AND UPPER(state) = UPPER($1)
+                        LIMIT 1
+                    """
+                    result = await conn.fetchrow(query, state)
+                
+            elif level == 'city':
+                # Try city-level stats first
+                query = """
+                    SELECT * FROM stats_aggregates 
+                    WHERE level = 'city' 
+                      AND UPPER(state) = UPPER($1) 
+                      AND city ILIKE $2
+                    LIMIT 1
+                """
+                result = await conn.fetchrow(query, state, f"%{city}%")
+                
+                # NEVER fall back to county stats for city requests
+                # If city stats not found, go straight to state-level
+                if not result and state:
+                    logger.info(f"City '{city}' not found in stats, falling back to state '{state}' (skipping county)")
+                    query = """
+                        SELECT * FROM stats_aggregates 
+                        WHERE level = 'state' AND UPPER(state) = UPPER($1)
+                        LIMIT 1
+                    """
+                    result = await conn.fetchrow(query, state)
+            
+            else:
+                return None
+            
+            if result:
+                return dict(result)
+            return None
+            
+    except Exception as e:
+        logger.error(f"Database query error: {e}")
+        raise
+
+
+@router.get("/stats/search")
+async def search_stats(
+    query: str = Query(..., description="Search query"),
+    limit: int = Query(10, ge=1, le=100, description="Max results")
+):
+    """
+    Search for locations (cities, counties, states) with statistics
+    
+    Example: GET /api/stats/search?query=boston&limit=5
+    
+    Returns matching locations with their statistics
+    """
+    try:
+        pool = await get_db_pool()
+        
+        async with pool.acquire() as conn:
+            # Search across all geographic levels
+            results = await conn.fetch("""
+                SELECT 
+                    level,
+                    state,
+                    county,
+                    city,
+                    jurisdictions_count,
+                    nonprofits_count,
+                    events_count,
+                    total_revenue
+                FROM stats_aggregates
+                WHERE 
+                    (city ILIKE $1 OR county ILIKE $1 OR state ILIKE $1)
+                    AND level != 'national'
+                ORDER BY 
+                    CASE level
+                        WHEN 'city' THEN 1
+                        WHEN 'county' THEN 2
+                        WHEN 'state' THEN 3
+                    END,
+                    nonprofits_count DESC
+                LIMIT $2
+            """, f"%{query}%", limit)
+            
+            return [{
+                'level': row['level'],
+                'location': format_location(row),
+                'state': row['state'],
+                'county': row['county'],
+                'city': row['city'],
+                'jurisdictions': row['jurisdictions_count'],
+                'nonprofits': row['nonprofits_count'],
+                'events': row['events_count'],
+                'total_revenue': row['total_revenue']
+            } for row in results]
+            
+    except Exception as e:
+        logger.error(f"Search error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+def format_location(row) -> str:
+    """Format location string from database row"""
+    if row['city']:
+        if row['county']:
+            return f"{row['city']}, {row['county']}, {row['state']}"
+        return f"{row['city']}, {row['state']}"
+    elif row['county']:
+        return f"{row['county']}, {row['state']}"
+    elif row['state']:
+        return row['state']
+    return 'Unknown'
+
+
+@router.on_event("shutdown")
+async def shutdown_db_pool():
+    """Close database connection pool on shutdown"""
+    global _db_pool
+    if _db_pool:
+        await _db_pool.close()
+        _db_pool = None

api/static/assets/index-BIH9Tona.css

@@ -0,0 +1 @@
+.leaflet-pane,.leaflet-tile,.leaflet-marker-icon,.leaflet-marker-shadow,.leaflet-tile-container,.leaflet-pane>svg,.leaflet-pane>canvas,.leaflet-zoom-box,.leaflet-image-layer,.leaflet-layer{position:absolute;left:0;top:0}.leaflet-container{overflow:hidden}.leaflet-tile,.leaflet-marker-icon,.leaflet-marker-shadow{-webkit-user-select:none;-moz-user-select:none;user-select:none;-webkit-user-drag:none}.leaflet-tile::-moz-selection{background:transparent}.leaflet-tile::selection{background:transparent}.leaflet-safari .leaflet-tile{image-rendering:-webkit-optimize-contrast}.leaflet-safari .leaflet-tile-container{width:1600px;height:1600px;-webkit-transform-origin:0 0}.leaflet-marker-icon,.leaflet-marker-shadow{display:block}.leaflet-container .leaflet-overlay-pane svg{max-width:none!important;max-height:none!important}.leaflet-container .leaflet-marker-pane img,.leaflet-container .leaflet-shadow-pane img,.leaflet-container .leaflet-tile-pane img,.leaflet-container img.leaflet-image-layer,.leaflet-container .leaflet-tile{max-width:none!important;max-height:none!important;width:auto;padding:0}.leaflet-container img.leaflet-tile{mix-blend-mode:plus-lighter}.leaflet-container.leaflet-touch-zoom{touch-action:pan-x pan-y}.leaflet-container.leaflet-touch-drag{touch-action:none;touch-action:pinch-zoom}.leaflet-container.leaflet-touch-drag.leaflet-touch-zoom{touch-action:none}.leaflet-container{-webkit-tap-highlight-color:transparent}.leaflet-container a{-webkit-tap-highlight-color:rgba(51,181,229,.4)}.leaflet-tile{filter:inherit;visibility:hidden}.leaflet-tile-loaded{visibility:inherit}.leaflet-zoom-box{width:0;height:0;box-sizing:border-box;z-index:800}.leaflet-overlay-pane svg{-moz-user-select:none}.leaflet-pane{z-index:400}.leaflet-tile-pane{z-index:200}.leaflet-overlay-pane{z-index:400}.leaflet-shadow-pane{z-index:500}.leaflet-marker-pane{z-index:600}.leaflet-tooltip-pane{z-index:650}.leaflet-popup-pane{z-index:700}.leaflet-map-pane canvas{z-index:100}.leaflet-map-pane svg{z-index:200}.leaflet-vml-shape{width:1px;height:1px}.lvml{behavior:url(#default#VML);display:inline-block;position:absolute}.leaflet-control{position:relative;z-index:800;pointer-events:visiblePainted;pointer-events:auto}.leaflet-top,.leaflet-bottom{position:absolute;z-index:1000;pointer-events:none}.leaflet-top{top:0}.leaflet-right{right:0}.leaflet-bottom{bottom:0}.leaflet-left{left:0}.leaflet-control{float:left;clear:both}.leaflet-right .leaflet-control{float:right}.leaflet-top .leaflet-control{margin-top:10px}.leaflet-bottom .leaflet-control{margin-bottom:10px}.leaflet-left .leaflet-control{margin-left:10px}.leaflet-right .leaflet-control{margin-right:10px}.leaflet-fade-anim .leaflet-popup{opacity:0;transition:opacity .2s linear}.leaflet-fade-anim .leaflet-map-pane .leaflet-popup{opacity:1}.leaflet-zoom-animated{transform-origin:0 0}svg.leaflet-zoom-animated{will-change:transform}.leaflet-zoom-anim .leaflet-zoom-animated{transition:transform .25s cubic-bezier(0,0,.25,1)}.leaflet-zoom-anim .leaflet-tile,.leaflet-pan-anim .leaflet-tile{transition:none}.leaflet-zoom-anim .leaflet-zoom-hide{visibility:hidden}.leaflet-interactive{cursor:pointer}.leaflet-grab{cursor:grab}.leaflet-crosshair,.leaflet-crosshair .leaflet-interactive{cursor:crosshair}.leaflet-popup-pane,.leaflet-control{cursor:auto}.leaflet-dragging .leaflet-grab,.leaflet-dragging .leaflet-grab .leaflet-interactive,.leaflet-dragging .leaflet-marker-draggable{cursor:move;cursor:grabbing}.leaflet-marker-icon,.leaflet-marker-shadow,.leaflet-image-layer,.leaflet-pane>svg path,.leaflet-tile-container{pointer-events:none}.leaflet-marker-icon.leaflet-interactive,.leaflet-image-layer.leaflet-interactive,.leaflet-pane>svg path.leaflet-interactive,svg.leaflet-image-layer.leaflet-interactive path{pointer-events:visiblePainted;pointer-events:auto}.leaflet-container{background:#ddd;outline-offset:1px}.leaflet-container a{color:#0078a8}.leaflet-zoom-box{border:2px dotted #38f;background:#ffffff80}.leaflet-container{font-family:Helvetica Neue,Arial,Helvetica,sans-serif;font-size:12px;font-size:.75rem;line-height:1.5}.leaflet-bar{box-shadow:0 1px 5px #000000a6;border-radius:4px}.leaflet-bar a{background-color:#fff;border-bottom:1px solid #ccc;width:26px;height:26px;line-height:26px;display:block;text-align:center;text-decoration:none;color:#000}.leaflet-bar a,.leaflet-control-layers-toggle{background-position:50% 50%;background-repeat:no-repeat;display:block}.leaflet-bar a:hover,.leaflet-bar a:focus{background-color:#f4f4f4}.leaflet-bar a:first-child{border-top-left-radius:4px;border-top-right-radius:4px}.leaflet-bar a:last-child{border-bottom-left-radius:4px;border-bottom-right-radius:4px;border-bottom:none}.leaflet-bar a.leaflet-disabled{cursor:default;background-color:#f4f4f4;color:#bbb}.leaflet-touch .leaflet-bar a{width:30px;height:30px;line-height:30px}.leaflet-touch .leaflet-bar a:first-child{border-top-left-radius:2px;border-top-right-radius:2px}.leaflet-touch .leaflet-bar a:last-child{border-bottom-left-radius:2px;border-bottom-right-radius:2px}.leaflet-control-zoom-in,.leaflet-control-zoom-out{font:700 18px Lucida Console,Monaco,monospace;text-indent:1px}.leaflet-touch .leaflet-control-zoom-in,.leaflet-touch .leaflet-control-zoom-out{font-size:22px}.leaflet-control-layers{box-shadow:0 1px 5px #0006;background:#fff;border-radius:5px}.leaflet-control-layers-toggle{background-image:url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABoAAAAaCAQAAAADQ4RFAAACf0lEQVR4AY1UM3gkARTePdvdoTxXKc+qTl3aU5U6b2Kbkz3Gtq3Zw6ziLGNPzrYx7946Tr6/ee/XeCQ4D3ykPtL5tHno4n0d/h3+xfuWHGLX81cn7r0iTNzjr7LrlxCqPtkbTQEHeqOrTy4Yyt3VCi/IOB0v7rVC7q45Q3Gr5K6jt+3Gl5nCoDD4MtO+j96Wu8atmhGqcNGHObuf8OM/x3AMx38+4Z2sPqzCxRFK2aF2e5Jol56XTLyggAMTL56XOMoS1W4pOyjUcGGQdZxU6qRh7B9Zp+PfpOFlqt0zyDZckPi1ttmIp03jX8gyJ8a/PG2yutpS/Vol7peZIbZcKBAEEheEIAgFbDkz5H6Zrkm2hVWGiXKiF4Ycw0RWKdtC16Q7qe3X4iOMxruonzegJzWaXFrU9utOSsLUmrc0YjeWYjCW4PDMADElpJSSQ0vQvA1Tm6/JlKnqFs1EGyZiFCqnRZTEJJJiKRYzVYzJck2Rm6P4iH+cmSY0YzimYa8l0EtTODFWhcMIMVqdsI2uiTvKmTisIDHJ3od5GILVhBCarCfVRmo4uTjkhrhzkiBV7SsaqS+TzrzM1qpGGUFt28pIySQHR6h7F6KSwGWm97ay+Z+ZqMcEjEWebE7wxCSQwpkhJqoZA5ivCdZDjJepuJ9IQjGGUmuXJdBFUygxVqVsxFsLMbDe8ZbDYVCGKxs+W080max1hFCarCfV+C1KATwcnvE9gRRuMP2prdbWGowm1KB1y+zwMMENkM755cJ2yPDtqhTI6ED1M/82yIDtC/4j4BijjeObflpO9I9MwXTCsSX8jWAFeHr05WoLTJ5G8IQVS/7vwR6ohirYM7f6HzYpogfS3R2OAAAAAElFTkSuQmCC);width:36px;height:36px}.leaflet-retina .leaflet-control-layers-toggle{background-image:url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADQAAAA0CAQAAABvcdNgAAAEsklEQVR4AWL4TydIhpZK1kpWOlg0w3ZXP6D2soBtG42jeI6ZmQTHzAxiTbSJsYLjO9HhP+WOmcuhciVnmHVQcJnp7DFvScowZorad/+V/fVzMdMT2g9Cv9guXGv/7pYOrXh2U+RRR3dSd9JRx6bIFc/ekqHI29JC6pJ5ZEh1yWkhkbcFeSjxgx3L2m1cb1C7bceyxA+CNjT/Ifff+/kDk2u/w/33/IeCMOSaWZ4glosqT3DNnNZQ7Cs58/3Ce5HL78iZH/vKVIaYlqzfdLu8Vi7dnvUbEza5Idt36tquZFldl6N5Z/POLof0XLK61mZCmJSWjVF9tEjUluu74IUXvgttuVIHE7YxSkaYhJZam7yiM9Pv82JYfl9nptxZaxMJE4YSPty+vF0+Y2up9d3wwijfjZbabqm/3bZ9ecKHsiGmRflnn1MW4pjHf9oLufyn2z3y1D6n8g8TZhxyzipLNPnAUpsOiuWimg52psrTZYnOWYNDTMuWBWa0tJb4rgq1UvmutpaYEbZlwU3CLJm/ayYjHW5/h7xWLn9Hh1vepDkyf7dE7MtT5LR4e7yYpHrkhOUpEfssBLq2pPhAqoSWKUkk7EDqkmK6RrCEzqDjhNDWNE+XSMvkJRDWlZTmCW0l0PHQGRZY5t1L83kT0Y3l2SItk5JAWHl2dCOBm+fPu3fo5/3v61RMCO9Jx2EEYYhb0rmNQMX/vm7gqOEJLcXTGw3CAuRNeyaPWwjR8PRqKQ1PDA/dpv+on9Shox52WFnx0KY8onHayrJzm87i5h9xGw/tfkev0jGsQizqezUKjk12hBMKJ4kbCqGPVNXudyyrShovGw5CgxsRICxF6aRmSjlBnHRzg7Gx8fKqEubI2rahQYdR1YgDIRQO7JvQyD52hoIQx0mxa0ODtW2Iozn1le2iIRdzwWewedyZzewidueOGqlsn1MvcnQpuVwLGG3/IR1hIKxCjelIDZ8ldqWz25jWAsnldEnK0Zxro19TGVb2ffIZEsIO89EIEDvKMPrzmBOQcKQ+rroye6NgRRxqR4U8EAkz0CL6uSGOm6KQCdWjvjRiSP1BPalCRS5iQYiEIvxuBMJEWgzSoHADcVMuN7IuqqTeyUPq22qFimFtxDyBBJEwNyt6TM88blFHao/6tWWhuuOM4SAK4EI4QmFHA+SEyWlp4EQoJ13cYGzMu7yszEIBOm2rVmHUNqwAIQabISNMRstmdhNWcFLsSm+0tjJH1MdRxO5Nx0WDMhCtgD6OKgZeljJqJKc9po8juskR9XN0Y1lZ3mWjLR9JCO1jRDMd0fpYC2VnvjBSEFg7wBENc0R9HFlb0xvF1+TBEpF68d+DHR6IOWVv2BECtxo46hOFUBd/APU57WIoEwJhIi2CdpyZX0m93BZicktMj1AS9dClteUFAUNUIEygRZCtik5zSxI9MubTBH1GOiHsiLJ3OCoSZkILa9PxiN0EbvhsAo8tdAf9Seepd36lGWHmtNANTv5Jd0z4QYyeo/UEJqxKRpg5LZx6btLPsOaEmdMyxYdlc8LMaJnikDlhclqmPiQnTEpLUIZEwkRagjYkEibQErwhkTAKCLQEbUgkzJQWc/0PstHHcfEdQ+UAAAAASUVORK5CYII=);background-size:26px 26px}.leaflet-touch .leaflet-control-layers-toggle{width:44px;height:44px}.leaflet-control-layers .leaflet-control-layers-list,.leaflet-control-layers-expanded .leaflet-control-layers-toggle{display:none}.leaflet-control-layers-expanded .leaflet-control-layers-list{display:block;position:relative}.leaflet-control-layers-expanded{padding:6px 10px 6px 6px;color:#333;background:#fff}.leaflet-control-layers-scrollbar{overflow-y:scroll;overflow-x:hidden;padding-right:5px}.leaflet-control-layers-selector{margin-top:2px;position:relative;top:1px}.leaflet-control-layers label{display:block;font-size:13px;font-size:1.08333em}.leaflet-control-layers-separator{height:0;border-top:1px solid #ddd;margin:5px -10px 5px -6px}.leaflet-default-icon-path{background-image:url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABkAAAApCAYAAADAk4LOAAAFgUlEQVR4Aa1XA5BjWRTN2oW17d3YaZtr2962HUzbDNpjszW24mRt28p47v7zq/bXZtrp/lWnXr337j3nPCe85NcypgSFdugCpW5YoDAMRaIMqRi6aKq5E3YqDQO3qAwjVWrD8Ncq/RBpykd8oZUb/kaJutow8r1aP9II0WmLKLIsJyv1w/kqw9Ch2MYdB++12Onxee/QMwvf4/Dk/Lfp/i4nxTXtOoQ4pW5Aj7wpici1A9erdAN2OH64x8OSP9j3Ft3b7aWkTg/Fm91siTra0f9on5sQr9INejH6CUUUpavjFNq1B+Oadhxmnfa8RfEmN8VNAsQhPqF55xHkMzz3jSmChWU6f7/XZKNH+9+hBLOHYozuKQPxyMPUKkrX/K0uWnfFaJGS1QPRtZsOPtr3NsW0uyh6NNCOkU3Yz+bXbT3I8G3xE5EXLXtCXbbqwCO9zPQYPRTZ5vIDXD7U+w7rFDEoUUf7ibHIR4y6bLVPXrz8JVZEql13trxwue/uDivd3fkWRbS6/IA2bID4uk0UpF1N8qLlbBlXs4Ee7HLTfV1j54APvODnSfOWBqtKVvjgLKzF5YdEk5ewRkGlK0i33Eofffc7HT56jD7/6U+qH3Cx7SBLNntH5YIPvODnyfIXZYRVDPqgHtLs5ABHD3YzLuespb7t79FY34DjMwrVrcTuwlT55YMPvOBnRrJ4VXTdNnYug5ucHLBjEpt30701A3Ts+HEa73u6dT3FNWwflY86eMHPk+Yu+i6pzUpRrW7SNDg5JHR4KapmM5Wv2E8Tfcb1HoqqHMHU+uWDD7zg54mz5/2BSnizi9T1Dg4QQXLToGNCkb6tb1NU+QAlGr1++eADrzhn/u8Q2YZhQVlZ5+CAOtqfbhmaUCS1ezNFVm2imDbPmPng5wmz+gwh+oHDce0eUtQ6OGDIyR0uUhUsoO3vfDmmgOezH0mZN59x7MBi++WDL1g/eEiU3avlidO671bkLfwbw5XV2P8Pzo0ydy4t2/0eu33xYSOMOD8hTf4CrBtGMSoXfPLchX+J0ruSePw3LZeK0juPJbYzrhkH0io7B3k164hiGvawhOKMLkrQLyVpZg8rHFW7E2uHOL888IBPlNZ1FPzstSJM694fWr6RwpvcJK60+0HCILTBzZLFNdtAzJaohze60T8qBzyh5ZuOg5e7uwQppofEmf2++DYvmySqGBuKaicF1blQjhuHdvCIMvp8whTTfZzI7RldpwtSzL+F1+wkdZ2TBOW2gIF88PBTzD/gpeREAMEbxnJcaJHNHrpzji0gQCS6hdkEeYt9DF/2qPcEC8RM28Hwmr3sdNyht00byAut2k3gufWNtgtOEOFGUwcXWNDbdNbpgBGxEvKkOQsxivJx33iow0Vw5S6SVTrpVq11ysA2Rp7gTfPfktc6zhtXBBC+adRLshf6sG2RfHPZ5EAc4sVZ83yCN00Fk/4kggu40ZTvIEm5g24qtU4KjBrx/BTTH8ifVASAG7gKrnWxJDcU7x8X6Ecczhm3o6YicvsLXWfh3Ch1W0k8x0nXF+0fFxgt4phz8QvypiwCCFKMqXCnqXExjq10beH+UUA7+nG6mdG/Pu0f3LgFcGrl2s0kNNjpmoJ9o4B29CMO8dMT4Q5ox8uitF6fqsrJOr8qnwNbRzv6hSnG5wP+64C7h9lp30hKNtKdWjtdkbuPA19nJ7Tz3zR/ibgARbhb4AlhavcBebmTHcFl2fvYEnW0ox9xMxKBS8btJ+KiEbq9zA4RthQXDhPa0T9TEe69gWupwc6uBUphquXgf+/FrIjweHQS4/pduMe5ERUMHUd9xv8ZR98CxkS4F2n3EUrUZ10EYNw7BWm9x1GiPssi3GgiGRDKWRYZfXlON+dfNbM+GgIwYdwAAAAASUVORK5CYII=)}.leaflet-container .leaflet-control-attribution{background:#fff;background:#fffc;margin:0}.leaflet-control-attribution,.leaflet-control-scale-line{padding:0 5px;color:#333;line-height:1.4}.leaflet-control-attribution a{text-decoration:none}.leaflet-control-attribution a:hover,.leaflet-control-attribution a:focus{text-decoration:underline}.leaflet-attribution-flag{display:inline!important;vertical-align:baseline!important;width:1em;height:.6669em}.leaflet-left .leaflet-control-scale{margin-left:5px}.leaflet-bottom .leaflet-control-scale{margin-bottom:5px}.leaflet-control-scale-line{border:2px solid #777;border-top:none;line-height:1.1;padding:2px 5px 1px;white-space:nowrap;box-sizing:border-box;background:#fffc;text-shadow:1px 1px #fff}.leaflet-control-scale-line:not(:first-child){border-top:2px solid #777;border-bottom:none;margin-top:-2px}.leaflet-control-scale-line:not(:first-child):not(:last-child){border-bottom:2px solid #777}.leaflet-touch .leaflet-control-attribution,.leaflet-touch .leaflet-control-layers,.leaflet-touch .leaflet-bar{box-shadow:none}.leaflet-touch .leaflet-control-layers,.leaflet-touch .leaflet-bar{border:2px solid rgba(0,0,0,.2);background-clip:padding-box}.leaflet-popup{position:absolute;text-align:center;margin-bottom:20px}.leaflet-popup-content-wrapper{padding:1px;text-align:left;border-radius:12px}.leaflet-popup-content{margin:13px 24px 13px 20px;line-height:1.3;font-size:13px;font-size:1.08333em;min-height:1px}.leaflet-popup-content p{margin:1.3em 0}.leaflet-popup-tip-container{width:40px;height:20px;position:absolute;left:50%;margin-top:-1px;margin-left:-20px;overflow:hidden;pointer-events:none}.leaflet-popup-tip{width:17px;height:17px;padding:1px;margin:-10px auto 0;pointer-events:auto;transform:rotate(45deg)}.leaflet-popup-content-wrapper,.leaflet-popup-tip{background:#fff;color:#333;box-shadow:0 3px 14px #0006}.leaflet-container a.leaflet-popup-close-button{position:absolute;top:0;right:0;border:none;text-align:center;width:24px;height:24px;font:16px/24px Tahoma,Verdana,sans-serif;color:#757575;text-decoration:none;background:transparent}.leaflet-container a.leaflet-popup-close-button:hover,.leaflet-container a.leaflet-popup-close-button:focus{color:#585858}.leaflet-popup-scrolled{overflow:auto}.leaflet-oldie .leaflet-popup-content-wrapper{-ms-zoom:1}.leaflet-oldie .leaflet-popup-tip{width:24px;margin:0 auto;-ms-filter:"progid:DXImageTransform.Microsoft.Matrix(M11=0.70710678, M12=0.70710678, M21=-0.70710678, M22=0.70710678)";filter:progid:DXImageTransform.Microsoft.Matrix(M11=.70710678,M12=.70710678,M21=-.70710678,M22=.70710678)}.leaflet-oldie .leaflet-control-zoom,.leaflet-oldie .leaflet-control-layers,.leaflet-oldie .leaflet-popup-content-wrapper,.leaflet-oldie .leaflet-popup-tip{border:1px solid #999}.leaflet-div-icon{background:#fff;border:1px solid #666}.leaflet-tooltip{position:absolute;padding:6px;background-color:#fff;border:1px solid #fff;border-radius:3px;color:#222;white-space:nowrap;-webkit-user-select:none;-moz-user-select:none;user-select:none;pointer-events:none;box-shadow:0 1px 3px #0006}.leaflet-tooltip.leaflet-interactive{cursor:pointer;pointer-events:auto}.leaflet-tooltip-top:before,.leaflet-tooltip-bottom:before,.leaflet-tooltip-left:before,.leaflet-tooltip-right:before{position:absolute;pointer-events:none;border:6px solid transparent;background:transparent;content:""}.leaflet-tooltip-bottom{margin-top:6px}.leaflet-tooltip-top{margin-top:-6px}.leaflet-tooltip-bottom:before,.leaflet-tooltip-top:before{left:50%;margin-left:-6px}.leaflet-tooltip-top:before{bottom:0;margin-bottom:-12px;border-top-color:#fff}.leaflet-tooltip-bottom:before{top:0;margin-top:-12px;margin-left:-6px;border-bottom-color:#fff}.leaflet-tooltip-left{margin-left:-6px}.leaflet-tooltip-right{margin-left:6px}.leaflet-tooltip-left:before,.leaflet-tooltip-right:before{top:50%;margin-top:-6px}.leaflet-tooltip-left:before{right:0;margin-right:-12px;border-left-color:#fff}.leaflet-tooltip-right:before{left:0;margin-left:-12px;border-right-color:#fff}@media print{.leaflet-control{-webkit-print-color-adjust:exact;print-color-adjust:exact}}*,:before,:after{--tw-border-spacing-x: 0;--tw-border-spacing-y: 0;--tw-translate-x: 0;--tw-translate-y: 0;--tw-rotate: 0;--tw-skew-x: 0;--tw-skew-y: 0;--tw-scale-x: 1;--tw-scale-y: 1;--tw-pan-x: ;--tw-pan-y: ;--tw-pinch-zoom: ;--tw-scroll-snap-strictness: proximity;--tw-gradient-from-position: ;--tw-gradient-via-position: ;--tw-gradient-to-position: ;--tw-ordinal: ;--tw-slashed-zero: ;--tw-numeric-figure: ;--tw-numeric-spacing: ;--tw-numeric-fraction: ;--tw-ring-inset: ;--tw-ring-offset-width: 0px;--tw-ring-offset-color: #fff;--tw-ring-color: rgb(59 130 246 / .5);--tw-ring-offset-shadow: 0 0 #0000;--tw-ring-shadow: 0 0 #0000;--tw-shadow: 0 0 #0000;--tw-shadow-colored: 0 0 #0000;--tw-blur: ;--tw-brightness: ;--tw-contrast: ;--tw-grayscale: ;--tw-hue-rotate: ;--tw-invert: ;--tw-saturate: ;--tw-sepia: ;--tw-drop-shadow: ;--tw-backdrop-blur: ;--tw-backdrop-brightness: ;--tw-backdrop-contrast: ;--tw-backdrop-grayscale: ;--tw-backdrop-hue-rotate: ;--tw-backdrop-invert: ;--tw-backdrop-opacity: ;--tw-backdrop-saturate: ;--tw-backdrop-sepia: ;--tw-contain-size: ;--tw-contain-layout: ;--tw-contain-paint: ;--tw-contain-style: }::backdrop{--tw-border-spacing-x: 0;--tw-border-spacing-y: 0;--tw-translate-x: 0;--tw-translate-y: 0;--tw-rotate: 0;--tw-skew-x: 0;--tw-skew-y: 0;--tw-scale-x: 1;--tw-scale-y: 1;--tw-pan-x: ;--tw-pan-y: ;--tw-pinch-zoom: ;--tw-scroll-snap-strictness: proximity;--tw-gradient-from-position: ;--tw-gradient-via-position: ;--tw-gradient-to-position: ;--tw-ordinal: ;--tw-slashed-zero: ;--tw-numeric-figure: ;--tw-numeric-spacing: ;--tw-numeric-fraction: ;--tw-ring-inset: ;--tw-ring-offset-width: 0px;--tw-ring-offset-color: #fff;--tw-ring-color: rgb(59 130 246 / .5);--tw-ring-offset-shadow: 0 0 #0000;--tw-ring-shadow: 0 0 #0000;--tw-shadow: 0 0 #0000;--tw-shadow-colored: 0 0 #0000;--tw-blur: ;--tw-brightness: ;--tw-contrast: ;--tw-grayscale: ;--tw-hue-rotate: ;--tw-invert: ;--tw-saturate: ;--tw-sepia: ;--tw-drop-shadow: ;--tw-backdrop-blur: ;--tw-backdrop-brightness: ;--tw-backdrop-contrast: ;--tw-backdrop-grayscale: ;--tw-backdrop-hue-rotate: ;--tw-backdrop-invert: ;--tw-backdrop-opacity: ;--tw-backdrop-saturate: ;--tw-backdrop-sepia: ;--tw-contain-size: ;--tw-contain-layout: ;--tw-contain-paint: ;--tw-contain-style: }*,:before,:after{box-sizing:border-box;border-width:0;border-style:solid;border-color:#e5e7eb}:before,:after{--tw-content: ""}html,:host{line-height:1.5;-webkit-text-size-adjust:100%;-moz-tab-size:4;-o-tab-size:4;tab-size:4;font-family:ui-sans-serif,system-ui,sans-serif,"Apple Color Emoji","Segoe UI Emoji",Segoe UI Symbol,"Noto Color Emoji";font-feature-settings:normal;font-variation-settings:normal;-webkit-tap-highlight-color:transparent}body{margin:0;line-height:inherit}hr{height:0;color:inherit;border-top-width:1px}abbr:where([title]){-webkit-text-decoration:underline dotted;text-decoration:underline dotted}h1,h2,h3,h4,h5,h6{font-size:inherit;font-weight:inherit}a{color:inherit;text-decoration:inherit}b,strong{font-weight:bolder}code,kbd,samp,pre{font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,monospace;font-feature-settings:normal;font-variation-settings:normal;font-size:1em}small{font-size:80%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sub{bottom:-.25em}sup{top:-.5em}table{text-indent:0;border-color:inherit;border-collapse:collapse}button,input,optgroup,select,textarea{font-family:inherit;font-feature-settings:inherit;font-variation-settings:inherit;font-size:100%;font-weight:inherit;line-height:inherit;letter-spacing:inherit;color:inherit;margin:0;padding:0}button,select{text-transform:none}button,input:where([type=button]),input:where([type=reset]),input:where([type=submit]){-webkit-appearance:button;background-color:transparent;background-image:none}:-moz-focusring{outline:auto}:-moz-ui-invalid{box-shadow:none}progress{vertical-align:baseline}::-webkit-inner-spin-button,::-webkit-outer-spin-button{height:auto}[type=search]{-webkit-appearance:textfield;outline-offset:-2px}::-webkit-search-decoration{-webkit-appearance:none}::-webkit-file-upload-button{-webkit-appearance:button;font:inherit}summary{display:list-item}blockquote,dl,dd,h1,h2,h3,h4,h5,h6,hr,figure,p,pre{margin:0}fieldset{margin:0;padding:0}legend{padding:0}ol,ul,menu{list-style:none;margin:0;padding:0}dialog{padding:0}textarea{resize:vertical}input::-moz-placeholder,textarea::-moz-placeholder{opacity:1;color:#9ca3af}input::placeholder,textarea::placeholder{opacity:1;color:#9ca3af}button,[role=button]{cursor:pointer}:disabled{cursor:default}img,svg,video,canvas,audio,iframe,embed,object{display:block;vertical-align:middle}img,video{max-width:100%;height:auto}[hidden]:where(:not([hidden=until-found])){display:none}h1{font-size:2.25rem;line-height:2.5rem;font-weight:700}h2{font-size:1.875rem;line-height:2.25rem;font-weight:600}h3{font-size:1.5rem;line-height:2rem;font-weight:600}.container{width:100%}@media (min-width: 640px){.container{max-width:640px}}@media (min-width: 768px){.container{max-width:768px}}@media (min-width: 1024px){.container{max-width:1024px}}@media (min-width: 1280px){.container{max-width:1280px}}@media (min-width: 1536px){.container{max-width:1536px}}.card{border-radius:.5rem;--tw-bg-opacity: 1;background-color:rgb(255 255 255 / var(--tw-bg-opacity, 1));padding:1.5rem;--tw-shadow: 0 4px 6px -1px rgb(0 0 0 / .1), 0 2px 4px -2px rgb(0 0 0 / .1);--tw-shadow-colored: 0 4px 6px -1px var(--tw-shadow-color), 0 2px 4px -2px var(--tw-shadow-color);box-shadow:var(--tw-ring-offset-shadow, 0 0 #0000),var(--tw-ring-shadow, 0 0 #0000),var(--tw-shadow)}.btn-primary{border-radius:.5rem;--tw-bg-opacity: 1;background-color:rgb(53 79 82 / var(--tw-bg-opacity, 1));padding:.5rem 1rem;font-weight:500;--tw-text-opacity: 1;color:rgb(255 255 255 / var(--tw-text-opacity, 1));transition-property:color,background-color,border-color,text-decoration-color,fill,stroke;transition-timing-function:cubic-bezier(.4,0,.2,1);transition-duration:.15s}.btn-primary:hover{--tw-bg-opacity: 1;background-color:rgb(46 67 70 / var(--tw-bg-opacity, 1))}.btn-secondary{border-radius:.5rem;--tw-bg-opacity: 1;background-color:rgb(229 231 235 / var(--tw-bg-opacity, 1));padding:.5rem 1rem;font-weight:500;--tw-text-opacity: 1;color:rgb(31 41 55 / var(--tw-text-opacity, 1));transition-property:color,background-color,border-color,text-decoration-color,fill,stroke;transition-timing-function:cubic-bezier(.4,0,.2,1);transition-duration:.15s}.btn-secondary:hover{--tw-bg-opacity: 1;background-color:rgb(209 213 219 / var(--tw-bg-opacity, 1))}.pointer-events-auto{pointer-events:auto}.visible{visibility:visible}.invisible{visibility:hidden}.fixed{position:fixed}.absolute{position:absolute}.relative{position:relative}.sticky{position:sticky}.inset-0{top:0;right:0;bottom:0;left:0}.inset-y-0{top:0;bottom:0}.-bottom-6{bottom:-1.5rem}.bottom-0{bottom:0}.bottom-4{bottom:1rem}.left-0{left:0}.left-1\/2{left:50%}.left-3{left:.75rem}.left-4{left:1rem}.right-0{right:0}.right-2{right:.5rem}.right-4{right:1rem}.top-0{top:0}.top-1\.5{top:.375rem}.top-1\/2{top:50%}.top-16{top:4rem}.top-2{top:.5rem}.top-2\.5{top:.625rem}.top-3\.5{top:.875rem}.z-10{z-index:10}.z-20{z-index:20}.z-30{z-index:30}.z-40{z-index:40}.z-50{z-index:50}.z-\[1\]{z-index:1}.mx-8{margin-left:2rem;margin-right:2rem}.mx-auto{margin-left:auto;margin-right:auto}.my-1{margin-top:.25rem;margin-bottom:.25rem}.my-4{margin-top:1rem;margin-bottom:1rem}.mb-1{margin-bottom:.25rem}.mb-1\.5{margin-bottom:.375rem}.mb-12{margin-bottom:3rem}.mb-16{margin-bottom:4rem}.mb-2{margin-bottom:.5rem}.mb-3{margin-bottom:.75rem}.mb-4{margin-bottom:1rem}.mb-6{margin-bottom:1.5rem}.mb-8{margin-bottom:2rem}.ml-1{margin-left:.25rem}.ml-2{margin-left:.5rem}.ml-4{margin-left:1rem}.mr-2{margin-right:.5rem}.mt-0\.5{margin-top:.125rem}.mt-1{margin-top:.25rem}.mt-12{margin-top:3rem}.mt-16{margin-top:4rem}.mt-2{margin-top:.5rem}.mt-3{margin-top:.75rem}.mt-4{margin-top:1rem}.mt-6{margin-top:1.5rem}.mt-8{margin-top:2rem}.line-clamp-2{overflow:hidden;display:-webkit-box;-webkit-box-orient:vertical;-webkit-line-clamp:2}.block{display:block}.inline-block{display:inline-block}.flex{display:flex}.inline-flex{display:inline-flex}.table{display:table}.grid{display:grid}.hidden{display:none}.h-1{height:.25rem}.h-10{height:2.5rem}.h-12{height:3rem}.h-14{height:3.5rem}.h-16{height:4rem}.h-2{height:.5rem}.h-20{height:5rem}.h-24{height:6rem}.h-3{height:.75rem}.h-4{height:1rem}.h-5{height:1.25rem}.h-6{height:1.5rem}.h-64{height:16rem}.h-7{height:1.75rem}.h-8{height:2rem}.h-9{height:2.25rem}.h-96{height:24rem}.h-\[600px\]{height:600px}.h-\[calc\(100vh-10rem\)\]{height:calc(100vh - 10rem)}.h-auto{height:auto}.h-screen{height:100vh}.max-h-48{max-height:12rem}.max-h-60{max-height:15rem}.max-h-96{max-height:24rem}.min-h-full{min-height:100%}.min-h-screen{min-height:100vh}.w-10{width:2.5rem}.w-12{width:3rem}.w-14{width:3.5rem}.w-16{width:4rem}.w-2{width:.5rem}.w-20{width:5rem}.w-24{width:6rem}.w-3{width:.75rem}.w-32{width:8rem}.w-4{width:1rem}.w-5{width:1.25rem}.w-6{width:1.5rem}.w-64{width:16rem}.w-7{width:1.75rem}.w-8{width:2rem}.w-9{width:2.25rem}.w-full{width:100%}.min-w-0{min-width:0px}.min-w-\[150px\]{min-width:150px}.min-w-\[200px\]{min-width:200px}.min-w-\[250px\]{min-width:250px}.min-w-full{min-width:100%}.max-w-2xl{max-width:42rem}.max-w-3xl{max-width:48rem}.max-w-4xl{max-width:56rem}.max-w-5xl{max-width:64rem}.max-w-6xl{max-width:72rem}.max-w-7xl{max-width:80rem}.max-w-md{max-width:28rem}.max-w-sm{max-width:24rem}.max-w-xs{max-width:20rem}.flex-1{flex:1 1 0%}.flex-shrink-0{flex-shrink:0}.grow{flex-grow:1}.origin-left{transform-origin:left}.-translate-x-1\/2{--tw-translate-x: -50%;transform:translate(var(--tw-translate-x),var(--tw-translate-y)) rotate(var(--tw-rotate)) skew(var(--tw-skew-x)) skewY(var(--tw-skew-y)) scaleX(var(--tw-scale-x)) scaleY(var(--tw-scale-y))}.-translate-x-full{--tw-translate-x: -100%;transform:translate(var(--tw-translate-x),var(--tw-translate-y)) rotate(var(--tw-rotate)) skew(var(--tw-skew-x)) skewY(var(--tw-skew-y)) scaleX(var(--tw-scale-x)) scaleY(var(--tw-scale-y))}.-translate-y-1\/2{--tw-translate-y: -50%;transform:translate(var(--tw-translate-x),var(--tw-translate-y)) rotate(var(--tw-rotate)) skew(var(--tw-skew-x)) skewY(var(--tw-skew-y)) scaleX(var(--tw-scale-x)) scaleY(var(--tw-scale-y))}.translate-x-0{--tw-translate-x: 0px;transform:translate(var(--tw-translate-x),var(--tw-translate-y)) rotate(var(--tw-rotate)) skew(var(--tw-skew-x)) skewY(var(--tw-skew-y)) scaleX(var(--tw-scale-x)) scaleY(var(--tw-scale-y))}.translate-y-full{--tw-translate-y: 100%;transform:translate(var(--tw-translate-x),var(--tw-translate-y)) rotate(var(--tw-rotate)) skew(var(--tw-skew-x)) skewY(var(--tw-skew-y)) scaleX(var(--tw-scale-x)) scaleY(var(--tw-scale-y))}.scale-100{--tw-scale-x: 1;--tw-scale-y: 1;transform:translate(var(--tw-translate-x),var(--tw-translate-y)) rotate(var(--tw-rotate)) skew(var(--tw-skew-x)) skewY(var(--tw-skew-y)) scaleX(var(--tw-scale-x)) scaleY(var(--tw-scale-y))}.scale-95{--tw-scale-x: .95;--tw-scale-y: .95;transform:translate(var(--tw-translate-x),var(--tw-translate-y)) rotate(var(--tw-rotate)) skew(var(--tw-skew-x)) skewY(var(--tw-skew-y)) scaleX(var(--tw-scale-x)) scaleY(var(--tw-scale-y))}.scale-x-0{--tw-scale-x: 0;transform:translate(var(--tw-translate-x),var(--tw-translate-y)) rotate(var(--tw-rotate)) skew(var(--tw-skew-x)) skewY(var(--tw-skew-y)) scaleX(var(--tw-scale-x)) scaleY(var(--tw-scale-y))}.transform{transform:translate(var(--tw-translate-x),var(--tw-translate-y)) rotate(var(--tw-rotate)) skew(var(--tw-skew-x)) skewY(var(--tw-skew-y)) scaleX(var(--tw-scale-x)) scaleY(var(--tw-scale-y))}.animate-\[slideUp_0\.6s_ease-out\]{animation:slideUp .6s ease-out}.animate-\[slideUp_0\.8s_ease-out_0\.2s_both\]{animation:slideUp .8s ease-out .2s both}.animate-\[slideUp_0\.8s_ease-out_0\.4s_both\]{animation:slideUp .8s ease-out .4s both}.animate-\[slideUp_0\.8s_ease-out_0\.6s_both\]{animation:slideUp .8s ease-out .6s both}.animate-\[slideUp_0\.8s_ease-out_0\.8s_both\]{animation:slideUp .8s ease-out .8s both}@keyframes pulse{50%{opacity:.5}}.animate-pulse{animation:pulse 2s cubic-bezier(.4,0,.6,1) infinite}@keyframes spin{to{transform:rotate(360deg)}}.animate-spin{animation:spin 1s linear infinite}.cursor-not-allowed{cursor:not-allowed}.cursor-pointer{cursor:pointer}.list-inside{list-style-position:inside}.list-decimal{list-style-type:decimal}.list-disc{list-style-type:disc}.grid-cols-1{grid-template-columns:repeat(1,minmax(0,1fr))}.grid-cols-2{grid-template-columns:repeat(2,minmax(0,1fr))}.grid-cols-3{grid-template-columns:repeat(3,minmax(0,1fr))}.flex-col{flex-direction:column}.flex-wrap{flex-wrap:wrap}.items-start{align-items:flex-start}.items-end{align-items:flex-end}.items-center{align-items:center}.justify-center{justify-content:center}.justify-between{justify-content:space-between}.gap-1{gap:.25rem}.gap-1\.5{gap:.375rem}.gap-12{gap:3rem}.gap-2{gap:.5rem}.gap-3{gap:.75rem}.gap-4{gap:1rem}.gap-6{gap:1.5rem}.gap-8{gap:2rem}.space-x-2>:not([hidden])~:not([hidden]){--tw-space-x-reverse: 0;margin-right:calc(.5rem * var(--tw-space-x-reverse));margin-left:calc(.5rem * calc(1 - var(--tw-space-x-reverse)))}.space-y-1>:not([hidden])~:not([hidden]){--tw-space-y-reverse: 0;margin-top:calc(.25rem * calc(1 - var(--tw-space-y-reverse)));margin-bottom:calc(.25rem * var(--tw-space-y-reverse))}.space-y-2>:not([hidden])~:not([hidden]){--tw-space-y-reverse: 0;margin-top:calc(.5rem * calc(1 - var(--tw-space-y-reverse)));margin-bottom:calc(.5rem * var(--tw-space-y-reverse))}.space-y-3>:not([hidden])~:not([hidden]){--tw-space-y-reverse: 0;margin-top:calc(.75rem * calc(1 - var(--tw-space-y-reverse)));margin-bottom:calc(.75rem * var(--tw-space-y-reverse))}.space-y-4>:not([hidden])~:not([hidden]){--tw-space-y-reverse: 0;margin-top:calc(1rem * calc(1 - var(--tw-space-y-reverse)));margin-bottom:calc(1rem * var(--tw-space-y-reverse))}.space-y-6>:not([hidden])~:not([hidden]){--tw-space-y-reverse: 0;margin-top:calc(1.5rem * calc(1 - var(--tw-space-y-reverse)));margin-bottom:calc(1.5rem * var(--tw-space-y-reverse))}.space-y-8>:not([hidden])~:not([hidden]){--tw-space-y-reverse: 0;margin-top:calc(2rem * calc(1 - var(--tw-space-y-reverse)));margin-bottom:calc(2rem * var(--tw-space-y-reverse))}.divide-y>:not([hidden])~:not([hidden]){--tw-divide-y-reverse: 0;border-top-width:calc(1px * calc(1 - var(--tw-divide-y-reverse)));border-bottom-width:calc(1px * var(--tw-divide-y-reverse))}.divide-gray-200>:not([hidden])~:not([hidden]){--tw-divide-opacity: 1;border-color:rgb(229 231 235 / var(--tw-divide-opacity, 1))}.overflow-hidden{overflow:hidden}.overflow-x-auto{overflow-x:auto}.overflow-y-auto{overflow-y:auto}.truncate{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.whitespace-nowrap{white-space:nowrap}.rounded{border-radius:.25rem}.rounded-2xl{border-radius:1rem}.rounded-full{border-radius:9999px}.rounded-lg{border-radius:.5rem}.rounded-md{border-radius:.375rem}.rounded-xl{border-radius:.75rem}.border{border-width:1px}.border-2{border-width:2px}.border-4{border-width:4px}.border-b{border-bottom-width:1px}.border-b-2{border-bottom-width:2px}.border-l-2{border-left-width:2px}.border-l-4{border-left-width:4px}.border-r{border-right-width:1px}.border-t{border-top-width:1px}.border-dashed{border-style:dashed}.border-\[\#354F52\]{--tw-border-opacity: 1;border-color:rgb(53 79 82 / var(--tw-border-opacity, 1))}.border-amber-200{--tw-border-opacity: 1;border-color:rgb(253 230 138 / var(--tw-border-opacity, 1))}.border-amber-500{--tw-border-opacity: 1;border-color:rgb(245 158 11 / var(--tw-border-opacity, 1))}.border-blue-200{--tw-border-opacity: 1;border-color:rgb(191 219 254 / var(--tw-border-opacity, 1))}.border-blue-400{--tw-border-opacity: 1;border-color:rgb(96 165 250 / var(--tw-border-opacity, 1))}.border-blue-500{--tw-border-opacity: 1;border-color:rgb(59 130 246 / var(--tw-border-opacity, 1))}.border-blue-600{--tw-border-opacity: 1;border-color:rgb(37 99 235 / var(--tw-border-opacity, 1))}.border-current{border-color:currentColor}.border-emerald-500{--tw-border-opacity: 1;border-color:rgb(16 185 129 / var(--tw-border-opacity, 1))}.border-gray-100{--tw-border-opacity: 1;border-color:rgb(243 244 246 / var(--tw-border-opacity, 1))}.border-gray-200{--tw-border-opacity: 1;border-color:rgb(229 231 235 / var(--tw-border-opacity, 1))}.border-gray-300{--tw-border-opacity: 1;border-color:rgb(209 213 219 / var(--tw-border-opacity, 1))}.border-gray-700{--tw-border-opacity: 1;border-color:rgb(55 65 81 / var(--tw-border-opacity, 1))}.border-gray-900{--tw-border-opacity: 1;border-color:rgb(17 24 39 / var(--tw-border-opacity, 1))}.border-green-200{--tw-border-opacity: 1;border-color:rgb(187 247 208 / var(--tw-border-opacity, 1))}.border-green-500{--tw-border-opacity: 1;border-color:rgb(34 197 94 / var(--tw-border-opacity, 1))}.border-green-500\/30{border-color:#22c55e4d}.border-green-500\/50{border-color:#22c55e80}.border-orange-200{--tw-border-opacity: 1;border-color:rgb(254 215 170 / var(--tw-border-opacity, 1))}.border-pink-200{--tw-border-opacity: 1;border-color:rgb(251 207 232 / var(--tw-border-opacity, 1))}.border-primary-500{--tw-border-opacity: 1;border-color:rgb(53 79 82 / var(--tw-border-opacity, 1))}.border-primary-600{--tw-border-opacity: 1;border-color:rgb(46 67 70 / var(--tw-border-opacity, 1))}.border-purple-200{--tw-border-opacity: 1;border-color:rgb(233 213 255 / var(--tw-border-opacity, 1))}.border-purple-500{--tw-border-opacity: 1;border-color:rgb(168 85 247 / var(--tw-border-opacity, 1))}.border-red-200{--tw-border-opacity: 1;border-color:rgb(254 202 202 / var(--tw-border-opacity, 1))}.border-red-300{--tw-border-opacity: 1;border-color:rgb(252 165 165 / var(--tw-border-opacity, 1))}.border-red-400{--tw-border-opacity: 1;border-color:rgb(248 113 113 / var(--tw-border-opacity, 1))}.border-red-500{--tw-border-opacity: 1;border-color:rgb(239 68 68 / var(--tw-border-opacity, 1))}.border-red-500\/30{border-color:#ef44444d}.border-red-500\/50{border-color:#ef444480}.border-teal-200{--tw-border-opacity: 1;border-color:rgb(153 246 228 / var(--tw-border-opacity, 1))}.border-transparent{border-color:transparent}.border-white{--tw-border-opacity: 1;border-color:rgb(255 255 255 / var(--tw-border-opacity, 1))}.border-yellow-200{--tw-border-opacity: 1;border-color:rgb(254 240 138 / var(--tw-border-opacity, 1))}.border-yellow-500\/30{border-color:#eab3084d}.border-yellow-500\/50{border-color:#eab30880}.border-t-primary-600{--tw-border-opacity: 1;border-top-color:rgb(46 67 70 / var(--tw-border-opacity, 1))}.border-t-transparent{border-top-color:transparent}.bg-\[\#354F52\]{--tw-bg-opacity: 1;background-color:rgb(53 79 82 / var(--tw-bg-opacity, 1))}.bg-\[\#E8EFEA\]{--tw-bg-opacity: 1;background-color:rgb(232 239 234 / var(--tw-bg-opacity, 1))}.bg-amber-100{--tw-bg-opacity: 1;background-color:rgb(254 243 199 / var(--tw-bg-opacity, 1))}.bg-amber-50{--tw-bg-opacity: 1;background-color:rgb(255 251 235 / var(--tw-bg-opacity, 1))}.bg-amber-600{--tw-bg-opacity: 1;background-color:rgb(217 119 6 / var(--tw-bg-opacity, 1))}.bg-black{--tw-bg-opacity: 1;background-color:rgb(0 0 0 / var(--tw-bg-opacity, 1))}.bg-blue-100{--tw-bg-opacity: 1;background-color:rgb(219 234 254 / var(--tw-bg-opacity, 1))}.bg-blue-50{--tw-bg-opacity: 1;background-color:rgb(239 246 255 / var(--tw-bg-opacity, 1))}.bg-blue-500{--tw-bg-opacity: 1;background-color:rgb(59 130 246 / var(--tw-bg-opacity, 1))}.bg-blue-600{--tw-bg-opacity: 1;background-color:rgb(37 99 235 / var(--tw-bg-opacity, 1))}.bg-emerald-100{--tw-bg-opacity: 1;background-color:rgb(209 250 229 / var(--tw-bg-opacity, 1))}.bg-gray-100{--tw-bg-opacity: 1;background-color:rgb(243 244 246 / var(--tw-bg-opacity, 1))}.bg-gray-200{--tw-bg-opacity: 1;background-color:rgb(229 231 235 / var(--tw-bg-opacity, 1))}.bg-gray-50{--tw-bg-opacity: 1;background-color:rgb(249 250 251 / var(--tw-bg-opacity, 1))}.bg-gray-500{--tw-bg-opacity: 1;background-color:rgb(107 114 128 / var(--tw-bg-opacity, 1))}.bg-gray-800{--tw-bg-opacity: 1;background-color:rgb(31 41 55 / var(--tw-bg-opacity, 1))}.bg-gray-800\/50{background-color:#1f293780}.bg-gray-900{--tw-bg-opacity: 1;background-color:rgb(17 24 39 / var(--tw-bg-opacity, 1))}.bg-green-100{--tw-bg-opacity: 1;background-color:rgb(220 252 231 / var(--tw-bg-opacity, 1))}.bg-green-50{--tw-bg-opacity: 1;background-color:rgb(240 253 244 / var(--tw-bg-opacity, 1))}.bg-green-500{--tw-bg-opacity: 1;background-color:rgb(34 197 94 / var(--tw-bg-opacity, 1))}.bg-green-500\/10{background-color:#22c55e1a}.bg-green-500\/20{background-color:#22c55e33}.bg-green-500\/30{background-color:#22c55e4d}.bg-green-600{--tw-bg-opacity: 1;background-color:rgb(22 163 74 / var(--tw-bg-opacity, 1))}.bg-neutral-600{--tw-bg-opacity: 1;background-color:rgb(53 79 82 / var(--tw-bg-opacity, 1))}.bg-orange-100{--tw-bg-opacity: 1;background-color:rgb(255 237 213 / var(--tw-bg-opacity, 1))}.bg-orange-50{--tw-bg-opacity: 1;background-color:rgb(255 247 237 / var(--tw-bg-opacity, 1))}.bg-pink-100{--tw-bg-opacity: 1;background-color:rgb(252 231 243 / var(--tw-bg-opacity, 1))}.bg-primary-100{--tw-bg-opacity: 1;background-color:rgb(197 202 206 / var(--tw-bg-opacity, 1))}.bg-primary-50{--tw-bg-opacity: 1;background-color:rgb(232 234 235 / var(--tw-bg-opacity, 1))}.bg-primary-500{--tw-bg-opacity: 1;background-color:rgb(53 79 82 / var(--tw-bg-opacity, 1))}.bg-primary-600{--tw-bg-opacity: 1;background-color:rgb(46 67 70 / var(--tw-bg-opacity, 1))}.bg-purple-100{--tw-bg-opacity: 1;background-color:rgb(243 232 255 / var(--tw-bg-opacity, 1))}.bg-purple-50{--tw-bg-opacity: 1;background-color:rgb(250 245 255 / var(--tw-bg-opacity, 1))}.bg-red-100{--tw-bg-opacity: 1;background-color:rgb(254 226 226 / var(--tw-bg-opacity, 1))}.bg-red-50{--tw-bg-opacity: 1;background-color:rgb(254 242 242 / var(--tw-bg-opacity, 1))}.bg-red-500{--tw-bg-opacity: 1;background-color:rgb(239 68 68 / var(--tw-bg-opacity, 1))}.bg-red-500\/10{background-color:#ef44441a}.bg-red-500\/20{background-color:#ef444433}.bg-red-500\/30{background-color:#ef44444d}.bg-red-600{--tw-bg-opacity: 1;background-color:rgb(220 38 38 / var(--tw-bg-opacity, 1))}.bg-teal-100{--tw-bg-opacity: 1;background-color:rgb(204 251 241 / var(--tw-bg-opacity, 1))}.bg-white{--tw-bg-opacity: 1;background-color:rgb(255 255 255 / var(--tw-bg-opacity, 1))}.bg-white\/10{background-color:#ffffff1a}.bg-white\/95{background-color:#fffffff2}.bg-yellow-100{--tw-bg-opacity: 1;background-color:rgb(254 249 195 / var(--tw-bg-opacity, 1))}.bg-yellow-50{--tw-bg-opacity: 1;background-color:rgb(254 252 232 / var(--tw-bg-opacity, 1))}.bg-yellow-500{--tw-bg-opacity: 1;background-color:rgb(234 179 8 / var(--tw-bg-opacity, 1))}.bg-yellow-500\/10{background-color:#eab3081a}.bg-yellow-500\/20{background-color:#eab30833}.bg-yellow-500\/30{background-color:#eab3084d}.bg-opacity-10{--tw-bg-opacity: .1}.bg-opacity-25{--tw-bg-opacity: .25}.bg-opacity-50{--tw-bg-opacity: .5}.bg-gradient-to-br{background-image:linear-gradient(to bottom right,var(--tw-gradient-stops))}.bg-gradient-to-r{background-image:linear-gradient(to right,var(--tw-gradient-stops))}.from-\[\#52796F\]{--tw-gradient-from: #52796F var(--tw-gradient-from-position);--tw-gradient-to: rgb(82 121 111 / 0) var(--tw-gradient-to-position);--tw-gradient-stops: var(--tw-gradient-from), var(--tw-gradient-to)}.from-blue-50{--tw-gradient-from: #eff6ff var(--tw-gradient-from-position);--tw-gradient-to: rgb(239 246 255 / 0) var(--tw-gradient-to-position);--tw-gradient-stops: var(--tw-gradient-from), var(--tw-gradient-to)}.from-gray-50{--tw-gradient-from: #f9fafb var(--tw-gradient-from-position);--tw-gradient-to: rgb(249 250 251 / 0) var(--tw-gradient-to-position);--tw-gradient-stops: var(--tw-gradient-from), var(--tw-gradient-to)}.from-primary-50{--tw-gradient-from: #e8eaeb var(--tw-gradient-from-position);--tw-gradient-to: rgb(232 234 235 / 0) var(--tw-gradient-to-position);--tw-gradient-stops: var(--tw-gradient-from), var(--tw-gradient-to)}.from-primary-500{--tw-gradient-from: #354F52 var(--tw-gradient-from-position);--tw-gradient-to: rgb(53 79 82 / 0) var(--tw-gradient-to-position);--tw-gradient-stops: var(--tw-gradient-from), var(--tw-gradient-to)}.from-primary-600{--tw-gradient-from: #2e4346 var(--tw-gradient-from-position);--tw-gradient-to: rgb(46 67 70 / 0) var(--tw-gradient-to-position);--tw-gradient-stops: var(--tw-gradient-from), var(--tw-gradient-to)}.from-purple-600{--tw-gradient-from: #9333ea var(--tw-gradient-from-position);--tw-gradient-to: rgb(147 51 234 / 0) var(--tw-gradient-to-position);--tw-gradient-stops: var(--tw-gradient-from), var(--tw-gradient-to)}.from-red-500{--tw-gradient-from: #ef4444 var(--tw-gradient-from-position);--tw-gradient-to: rgb(239 68 68 / 0) var(--tw-gradient-to-position);--tw-gradient-stops: var(--tw-gradient-from), var(--tw-gradient-to)}.from-teal-50{--tw-gradient-from: #f0fdfa var(--tw-gradient-from-position);--tw-gradient-to: rgb(240 253 250 / 0) var(--tw-gradient-to-position);--tw-gradient-stops: var(--tw-gradient-from), var(--tw-gradient-to)}.to-\[\#84A98C\]{--tw-gradient-to: #84A98C var(--tw-gradient-to-position)}.to-blue-50{--tw-gradient-to: #eff6ff var(--tw-gradient-to-position)}.to-gray-100{--tw-gradient-to: #f3f4f6 var(--tw-gradient-to-position)}.to-indigo-50{--tw-gradient-to: #eef2ff var(--tw-gradient-to-position)}.to-pink-600{--tw-gradient-to: #db2777 var(--tw-gradient-to-position)}.to-primary-100{--tw-gradient-to: #c5cace var(--tw-gradient-to-position)}.to-primary-600{--tw-gradient-to: #2e4346 var(--tw-gradient-to-position)}.to-primary-700{--tw-gradient-to: #27383a var(--tw-gradient-to-position)}.to-red-600{--tw-gradient-to: #dc2626 var(--tw-gradient-to-position)}.to-white{--tw-gradient-to: #fff var(--tw-gradient-to-position)}.bg-clip-text{-webkit-background-clip:text;background-clip:text}.object-contain{-o-object-fit:contain;object-fit:contain}.object-cover{-o-object-fit:cover;object-fit:cover}.p-0\.5{padding:.125rem}.p-12{padding:3rem}.p-2{padding:.5rem}.p-3{padding:.75rem}.p-4{padding:1rem}.p-6{padding:1.5rem}.p-8{padding:2rem}.px-1\.5{padding-left:.375rem;padding-right:.375rem}.px-12{padding-left:3rem;padding-right:3rem}.px-2{padding-left:.5rem;padding-right:.5rem}.px-2\.5{padding-left:.625rem;padding-right:.625rem}.px-3{padding-left:.75rem;padding-right:.75rem}.px-4{padding-left:1rem;padding-right:1rem}.px-5{padding-left:1.25rem;padding-right:1.25rem}.px-6{padding-left:1.5rem;padding-right:1.5rem}.px-8{padding-left:2rem;padding-right:2rem}.py-0\.5{padding-top:.125rem;padding-bottom:.125rem}.py-1{padding-top:.25rem;padding-bottom:.25rem}.py-1\.5{padding-top:.375rem;padding-bottom:.375rem}.py-12{padding-top:3rem;padding-bottom:3rem}.py-16{padding-top:4rem;padding-bottom:4rem}.py-2{padding-top:.5rem;padding-bottom:.5rem}.py-2\.5{padding-top:.625rem;padding-bottom:.625rem}.py-20{padding-top:5rem;padding-bottom:5rem}.py-3{padding-top:.75rem;padding-bottom:.75rem}.py-4{padding-top:1rem;padding-bottom:1rem}.py-6{padding-top:1.5rem;padding-bottom:1.5rem}.py-8{padding-top:2rem;padding-bottom:2rem}.pb-1{padding-bottom:.25rem}.pb-12{padding-bottom:3rem}.pb-16{padding-bottom:4rem}.pb-20{padding-bottom:5rem}.pb-4{padding-bottom:1rem}.pb-6{padding-bottom:1.5rem}.pl-10{padding-left:2.5rem}.pl-12{padding-left:3rem}.pl-4{padding-left:1rem}.pt-16{padding-top:4rem}.pt-2{padding-top:.5rem}.pt-20{padding-top:5rem}.pt-3{padding-top:.75rem}.pt-32{padding-top:8rem}.pt-4{padding-top:1rem}.text-left{text-align:left}.text-center{text-align:center}.align-middle{vertical-align:middle}.font-mono{font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,monospace}.text-2xl{font-size:1.5rem;line-height:2rem}.text-3xl{font-size:1.875rem;line-height:2.25rem}.text-4xl{font-size:2.25rem;line-height:2.5rem}.text-5xl{font-size:3rem;line-height:1}.text-6xl{font-size:3.75rem;line-height:1}.text-\[10px\]{font-size:10px}.text-base{font-size:1rem;line-height:1.5rem}.text-lg{font-size:1.125rem;line-height:1.75rem}.text-sm{font-size:.875rem;line-height:1.25rem}.text-xl{font-size:1.25rem;line-height:1.75rem}.text-xs{font-size:.75rem;line-height:1rem}.font-bold{font-weight:700}.font-medium{font-weight:500}.font-normal{font-weight:400}.font-semibold{font-weight:600}.uppercase{text-transform:uppercase}.capitalize{text-transform:capitalize}.italic{font-style:italic}.leading-5{line-height:1.25rem}.leading-6{line-height:1.5rem}.leading-relaxed{line-height:1.625}.tracking-wide{letter-spacing:.025em}.tracking-wider{letter-spacing:.05em}.text-\[\#354F52\]{--tw-text-opacity: 1;color:rgb(53 79 82 / var(--tw-text-opacity, 1))}.text-\[\#52796F\]{--tw-text-opacity: 1;color:rgb(82 121 111 / var(--tw-text-opacity, 1))}.text-amber-600{--tw-text-opacity: 1;color:rgb(217 119 6 / var(--tw-text-opacity, 1))}.text-amber-700{--tw-text-opacity: 1;color:rgb(180 83 9 / var(--tw-text-opacity, 1))}.text-amber-800{--tw-text-opacity: 1;color:rgb(146 64 14 / var(--tw-text-opacity, 1))}.text-blue-300{--tw-text-opacity: 1;color:rgb(147 197 253 / var(--tw-text-opacity, 1))}.text-blue-500{--tw-text-opacity: 1;color:rgb(59 130 246 / var(--tw-text-opacity, 1))}.text-blue-600{--tw-text-opacity: 1;color:rgb(37 99 235 / var(--tw-text-opacity, 1))}.text-blue-700{--tw-text-opacity: 1;color:rgb(29 78 216 / var(--tw-text-opacity, 1))}.text-blue-800{--tw-text-opacity: 1;color:rgb(30 64 175 / var(--tw-text-opacity, 1))}.text-blue-900{--tw-text-opacity: 1;color:rgb(30 58 138 / var(--tw-text-opacity, 1))}.text-cyan-600{--tw-text-opacity: 1;color:rgb(8 145 178 / var(--tw-text-opacity, 1))}.text-emerald-600{--tw-text-opacity: 1;color:rgb(5 150 105 / var(--tw-text-opacity, 1))}.text-gray-200{--tw-text-opacity: 1;color:rgb(229 231 235 / var(--tw-text-opacity, 1))}.text-gray-300{--tw-text-opacity: 1;color:rgb(209 213 219 / var(--tw-text-opacity, 1))}.text-gray-400{--tw-text-opacity: 1;color:rgb(156 163 175 / var(--tw-text-opacity, 1))}.text-gray-500{--tw-text-opacity: 1;color:rgb(107 114 128 / var(--tw-text-opacity, 1))}.text-gray-600{--tw-text-opacity: 1;color:rgb(75 85 99 / var(--tw-text-opacity, 1))}.text-gray-700{--tw-text-opacity: 1;color:rgb(55 65 81 / var(--tw-text-opacity, 1))}.text-gray-800{--tw-text-opacity: 1;color:rgb(31 41 55 / var(--tw-text-opacity, 1))}.text-gray-900{--tw-text-opacity: 1;color:rgb(17 24 39 / var(--tw-text-opacity, 1))}.text-green-300{--tw-text-opacity: 1;color:rgb(134 239 172 / var(--tw-text-opacity, 1))}.text-green-300\/70{color:#86efacb3}.text-green-400{--tw-text-opacity: 1;color:rgb(74 222 128 / var(--tw-text-opacity, 1))}.text-green-500{--tw-text-opacity: 1;color:rgb(34 197 94 / var(--tw-text-opacity, 1))}.text-green-600{--tw-text-opacity: 1;color:rgb(22 163 74 / var(--tw-text-opacity, 1))}.text-green-700{--tw-text-opacity: 1;color:rgb(21 128 61 / var(--tw-text-opacity, 1))}.text-green-800{--tw-text-opacity: 1;color:rgb(22 101 52 / var(--tw-text-opacity, 1))}.text-green-900{--tw-text-opacity: 1;color:rgb(20 83 45 / var(--tw-text-opacity, 1))}.text-orange-600{--tw-text-opacity: 1;color:rgb(234 88 12 / var(--tw-text-opacity, 1))}.text-orange-700{--tw-text-opacity: 1;color:rgb(194 65 12 / var(--tw-text-opacity, 1))}.text-orange-800{--tw-text-opacity: 1;color:rgb(154 52 18 / var(--tw-text-opacity, 1))}.text-orange-900{--tw-text-opacity: 1;color:rgb(124 45 18 / var(--tw-text-opacity, 1))}.text-pink-600{--tw-text-opacity: 1;color:rgb(219 39 119 / var(--tw-text-opacity, 1))}.text-pink-700{--tw-text-opacity: 1;color:rgb(190 24 93 / var(--tw-text-opacity, 1))}.text-primary-50{--tw-text-opacity: 1;color:rgb(232 234 235 / var(--tw-text-opacity, 1))}.text-primary-600{--tw-text-opacity: 1;color:rgb(46 67 70 / var(--tw-text-opacity, 1))}.text-primary-700{--tw-text-opacity: 1;color:rgb(39 56 58 / var(--tw-text-opacity, 1))}.text-purple-50{--tw-text-opacity: 1;color:rgb(250 245 255 / var(--tw-text-opacity, 1))}.text-purple-600{--tw-text-opacity: 1;color:rgb(147 51 234 / var(--tw-text-opacity, 1))}.text-purple-700{--tw-text-opacity: 1;color:rgb(126 34 206 / var(--tw-text-opacity, 1))}.text-purple-800{--tw-text-opacity: 1;color:rgb(107 33 168 / var(--tw-text-opacity, 1))}.text-purple-900{--tw-text-opacity: 1;color:rgb(88 28 135 / var(--tw-text-opacity, 1))}.text-red-300{--tw-text-opacity: 1;color:rgb(252 165 165 / var(--tw-text-opacity, 1))}.text-red-300\/70{color:#fca5a5b3}.text-red-400{--tw-text-opacity: 1;color:rgb(248 113 113 / var(--tw-text-opacity, 1))}.text-red-500{--tw-text-opacity: 1;color:rgb(239 68 68 / var(--tw-text-opacity, 1))}.text-red-600{--tw-text-opacity: 1;color:rgb(220 38 38 / var(--tw-text-opacity, 1))}.text-red-700{--tw-text-opacity: 1;color:rgb(185 28 28 / var(--tw-text-opacity, 1))}.text-red-800{--tw-text-opacity: 1;color:rgb(153 27 27 / var(--tw-text-opacity, 1))}.text-red-900{--tw-text-opacity: 1;color:rgb(127 29 29 / var(--tw-text-opacity, 1))}.text-teal-600{--tw-text-opacity: 1;color:rgb(13 148 136 / var(--tw-text-opacity, 1))}.text-teal-700{--tw-text-opacity: 1;color:rgb(15 118 110 / var(--tw-text-opacity, 1))}.text-teal-800{--tw-text-opacity: 1;color:rgb(17 94 89 / var(--tw-text-opacity, 1))}.text-transparent{color:transparent}.text-white{--tw-text-opacity: 1;color:rgb(255 255 255 / var(--tw-text-opacity, 1))}.text-white\/90{color:#ffffffe6}.text-yellow-300{--tw-text-opacity: 1;color:rgb(253 224 71 / var(--tw-text-opacity, 1))}.text-yellow-300\/70{color:#fde047b3}.text-yellow-400{--tw-text-opacity: 1;color:rgb(250 204 21 / var(--tw-text-opacity, 1))}.text-yellow-600{--tw-text-opacity: 1;color:rgb(202 138 4 / var(--tw-text-opacity, 1))}.text-yellow-700{--tw-text-opacity: 1;color:rgb(161 98 7 / var(--tw-text-opacity, 1))}.text-yellow-800{--tw-text-opacity: 1;color:rgb(133 77 14 / var(--tw-text-opacity, 1))}.underline{text-decoration-line:underline}.no-underline{text-decoration-line:none}.opacity-0{opacity:0}.opacity-100{opacity:1}.opacity-60{opacity:.6}.opacity-90{opacity:.9}.shadow{--tw-shadow: 0 1px 3px 0 rgb(0 0 0 / .1), 0 1px 2px -1px rgb(0 0 0 / .1);--tw-shadow-colored: 0 1px 3px 0 var(--tw-shadow-color), 0 1px 2px -1px var(--tw-shadow-color);box-shadow:var(--tw-ring-offset-shadow, 0 0 #0000),var(--tw-ring-shadow, 0 0 #0000),var(--tw-shadow)}.shadow-2xl{--tw-shadow: 0 25px 50px -12px rgb(0 0 0 / .25);--tw-shadow-colored: 0 25px 50px -12px var(--tw-shadow-color);box-shadow:var(--tw-ring-offset-shadow, 0 0 #0000),var(--tw-ring-shadow, 0 0 #0000),var(--tw-shadow)}.shadow-lg{--tw-shadow: 0 10px 15px -3px rgb(0 0 0 / .1), 0 4px 6px -4px rgb(0 0 0 / .1);--tw-shadow-colored: 0 10px 15px -3px var(--tw-shadow-color), 0 4px 6px -4px var(--tw-shadow-color);box-shadow:var(--tw-ring-offset-shadow, 0 0 #0000),var(--tw-ring-shadow, 0 0 #0000),var(--tw-shadow)}.shadow-md{--tw-shadow: 0 4px 6px -1px rgb(0 0 0 / .1), 0 2px 4px -2px rgb(0 0 0 / .1);--tw-shadow-colored: 0 4px 6px -1px var(--tw-shadow-color), 0 2px 4px -2px var(--tw-shadow-color);box-shadow:var(--tw-ring-offset-shadow, 0 0 #0000),var(--tw-ring-shadow, 0 0 #0000),var(--tw-shadow)}.shadow-sm{--tw-shadow: 0 1px 2px 0 rgb(0 0 0 / .05);--tw-shadow-colored: 0 1px 2px 0 var(--tw-shadow-color);box-shadow:var(--tw-ring-offset-shadow, 0 0 #0000),var(--tw-ring-shadow, 0 0 #0000),var(--tw-shadow)}.shadow-xl{--tw-shadow: 0 20px 25px -5px rgb(0 0 0 / .1), 0 8px 10px -6px rgb(0 0 0 / .1);--tw-shadow-colored: 0 20px 25px -5px var(--tw-shadow-color), 0 8px 10px -6px var(--tw-shadow-color);box-shadow:var(--tw-ring-offset-shadow, 0 0 #0000),var(--tw-ring-shadow, 0 0 #0000),var(--tw-shadow)}.outline{outline-style:solid}.filter{filter:var(--tw-blur) var(--tw-brightness) var(--tw-contrast) var(--tw-grayscale) var(--tw-hue-rotate) var(--tw-invert) var(--tw-saturate) var(--tw-sepia) var(--tw-drop-shadow)}.backdrop-blur-sm{--tw-backdrop-blur: blur(4px);-webkit-backdrop-filter:var(--tw-backdrop-blur) var(--tw-backdrop-brightness) var(--tw-backdrop-contrast) var(--tw-backdrop-grayscale) var(--tw-backdrop-hue-rotate) var(--tw-backdrop-invert) var(--tw-backdrop-opacity) var(--tw-backdrop-saturate) var(--tw-backdrop-sepia);backdrop-filter:var(--tw-backdrop-blur) var(--tw-backdrop-brightness) var(--tw-backdrop-contrast) var(--tw-backdrop-grayscale) var(--tw-backdrop-hue-rotate) var(--tw-backdrop-invert) var(--tw-backdrop-opacity) var(--tw-backdrop-saturate) var(--tw-backdrop-sepia)}.transition{transition-property:color,background-color,border-color,text-decoration-color,fill,stroke,opacity,box-shadow,transform,filter,backdrop-filter;transition-timing-function:cubic-bezier(.4,0,.2,1);transition-duration:.15s}.transition-all{transition-property:all;transition-timing-function:cubic-bezier(.4,0,.2,1);transition-duration:.15s}.transition-colors{transition-property:color,background-color,border-color,text-decoration-color,fill,stroke;transition-timing-function:cubic-bezier(.4,0,.2,1);transition-duration:.15s}.transition-opacity{transition-property:opacity;transition-timing-function:cubic-bezier(.4,0,.2,1);transition-duration:.15s}.transition-shadow{transition-property:box-shadow;transition-timing-function:cubic-bezier(.4,0,.2,1);transition-duration:.15s}.transition-transform{transition-property:transform;transition-timing-function:cubic-bezier(.4,0,.2,1);transition-duration:.15s}.duration-100{transition-duration:.1s}.duration-200{transition-duration:.2s}.duration-300{transition-duration:.3s}.duration-75{transition-duration:75ms}.ease-in{transition-timing-function:cubic-bezier(.4,0,1,1)}.ease-in-out{transition-timing-function:cubic-bezier(.4,0,.2,1)}.ease-out{transition-timing-function:cubic-bezier(0,0,.2,1)}:root{font-family:Inter,system-ui,Avenir,Helvetica,Arial,sans-serif;line-height:1.5;font-weight:400;color-scheme:light dark;color:#ffffffde;background-color:#f1f5f9}html{scroll-behavior:smooth}body{margin:0;min-height:100vh}@keyframes slideUp{0%{opacity:0;transform:translateY(30px)}to{opacity:1;transform:translateY(0)}}.last\:rounded-b-lg:last-child{border-bottom-right-radius:.5rem;border-bottom-left-radius:.5rem}.last\:border-b-0:last-child{border-bottom-width:0px}.hover\:-translate-y-1:hover{--tw-translate-y: -.25rem;transform:translate(var(--tw-translate-x),var(--tw-translate-y)) rotate(var(--tw-rotate)) skew(var(--tw-skew-x)) skewY(var(--tw-skew-y)) scaleX(var(--tw-scale-x)) scaleY(var(--tw-scale-y))}.hover\:scale-105:hover{--tw-scale-x: 1.05;--tw-scale-y: 1.05;transform:translate(var(--tw-translate-x),var(--tw-translate-y)) rotate(var(--tw-rotate)) skew(var(--tw-skew-x)) skewY(var(--tw-skew-y)) scaleX(var(--tw-scale-x)) scaleY(var(--tw-scale-y))}.hover\:border-2:hover{border-width:2px}.hover\:border-\[\#354F52\]:hover{--tw-border-opacity: 1;border-color:rgb(53 79 82 / var(--tw-border-opacity, 1))}.hover\:border-amber-500:hover{--tw-border-opacity: 1;border-color:rgb(245 158 11 / var(--tw-border-opacity, 1))}.hover\:border-blue-500:hover{--tw-border-opacity: 1;border-color:rgb(59 130 246 / var(--tw-border-opacity, 1))}.hover\:border-gray-200:hover{--tw-border-opacity: 1;border-color:rgb(229 231 235 / var(--tw-border-opacity, 1))}.hover\:border-gray-300:hover{--tw-border-opacity: 1;border-color:rgb(209 213 219 / var(--tw-border-opacity, 1))}.hover\:border-gray-400:hover{--tw-border-opacity: 1;border-color:rgb(156 163 175 / var(--tw-border-opacity, 1))}.hover\:border-green-500:hover{--tw-border-opacity: 1;border-color:rgb(34 197 94 / var(--tw-border-opacity, 1))}.hover\:border-primary-500:hover{--tw-border-opacity: 1;border-color:rgb(53 79 82 / var(--tw-border-opacity, 1))}.hover\:border-purple-500:hover{--tw-border-opacity: 1;border-color:rgb(168 85 247 / var(--tw-border-opacity, 1))}.hover\:bg-\[\#d9e5db\]:hover{--tw-bg-opacity: 1;background-color:rgb(217 229 219 / var(--tw-bg-opacity, 1))}.hover\:bg-amber-200:hover{--tw-bg-opacity: 1;background-color:rgb(253 230 138 / var(--tw-bg-opacity, 1))}.hover\:bg-blue-200:hover{--tw-bg-opacity: 1;background-color:rgb(191 219 254 / var(--tw-bg-opacity, 1))}.hover\:bg-blue-700:hover{--tw-bg-opacity: 1;background-color:rgb(29 78 216 / var(--tw-bg-opacity, 1))}.hover\:bg-gray-100:hover{--tw-bg-opacity: 1;background-color:rgb(243 244 246 / var(--tw-bg-opacity, 1))}.hover\:bg-gray-200:hover{--tw-bg-opacity: 1;background-color:rgb(229 231 235 / var(--tw-bg-opacity, 1))}.hover\:bg-gray-300:hover{--tw-bg-opacity: 1;background-color:rgb(209 213 219 / var(--tw-bg-opacity, 1))}.hover\:bg-gray-50:hover{--tw-bg-opacity: 1;background-color:rgb(249 250 251 / var(--tw-bg-opacity, 1))}.hover\:bg-gray-700\/50:hover{background-color:#37415180}.hover\:bg-green-200:hover{--tw-bg-opacity: 1;background-color:rgb(187 247 208 / var(--tw-bg-opacity, 1))}.hover\:bg-green-700:hover{--tw-bg-opacity: 1;background-color:rgb(21 128 61 / var(--tw-bg-opacity, 1))}.hover\:bg-neutral-700:hover{--tw-bg-opacity: 1;background-color:rgb(46 67 70 / var(--tw-bg-opacity, 1))}.hover\:bg-primary-100:hover{--tw-bg-opacity: 1;background-color:rgb(197 202 206 / var(--tw-bg-opacity, 1))}.hover\:bg-primary-50:hover{--tw-bg-opacity: 1;background-color:rgb(232 234 235 / var(--tw-bg-opacity, 1))}.hover\:bg-primary-700:hover{--tw-bg-opacity: 1;background-color:rgb(39 56 58 / var(--tw-bg-opacity, 1))}.hover\:bg-purple-200:hover{--tw-bg-opacity: 1;background-color:rgb(233 213 255 / var(--tw-bg-opacity, 1))}.hover\:bg-red-100:hover{--tw-bg-opacity: 1;background-color:rgb(254 226 226 / var(--tw-bg-opacity, 1))}.hover\:bg-red-700:hover{--tw-bg-opacity: 1;background-color:rgb(185 28 28 / var(--tw-bg-opacity, 1))}.hover\:bg-teal-200:hover{--tw-bg-opacity: 1;background-color:rgb(153 246 228 / var(--tw-bg-opacity, 1))}.hover\:bg-white\/20:hover{background-color:#fff3}.hover\:text-\[\#354F52\]:hover{--tw-text-opacity: 1;color:rgb(53 79 82 / var(--tw-text-opacity, 1))}.hover\:text-amber-900:hover{--tw-text-opacity: 1;color:rgb(120 53 15 / var(--tw-text-opacity, 1))}.hover\:text-blue-600:hover{--tw-text-opacity: 1;color:rgb(37 99 235 / var(--tw-text-opacity, 1))}.hover\:text-blue-700:hover{--tw-text-opacity: 1;color:rgb(29 78 216 / var(--tw-text-opacity, 1))}.hover\:text-blue-800:hover{--tw-text-opacity: 1;color:rgb(30 64 175 / var(--tw-text-opacity, 1))}.hover\:text-gray-500:hover{--tw-text-opacity: 1;color:rgb(107 114 128 / var(--tw-text-opacity, 1))}.hover\:text-gray-600:hover{--tw-text-opacity: 1;color:rgb(75 85 99 / var(--tw-text-opacity, 1))}.hover\:text-gray-700:hover{--tw-text-opacity: 1;color:rgb(55 65 81 / var(--tw-text-opacity, 1))}.hover\:text-gray-900:hover{--tw-text-opacity: 1;color:rgb(17 24 39 / var(--tw-text-opacity, 1))}.hover\:text-primary-100:hover{--tw-text-opacity: 1;color:rgb(197 202 206 / var(--tw-text-opacity, 1))}.hover\:text-primary-600:hover{--tw-text-opacity: 1;color:rgb(46 67 70 / var(--tw-text-opacity, 1))}.hover\:text-primary-700:hover{--tw-text-opacity: 1;color:rgb(39 56 58 / var(--tw-text-opacity, 1))}.hover\:text-red-700:hover{--tw-text-opacity: 1;color:rgb(185 28 28 / var(--tw-text-opacity, 1))}.hover\:text-white:hover{--tw-text-opacity: 1;color:rgb(255 255 255 / var(--tw-text-opacity, 1))}.hover\:underline:hover{text-decoration-line:underline}.hover\:decoration-2:hover{text-decoration-thickness:2px}.hover\:opacity-75:hover{opacity:.75}.hover\:opacity-90:hover{opacity:.9}.hover\:shadow-2xl:hover{--tw-shadow: 0 25px 50px -12px rgb(0 0 0 / .25);--tw-shadow-colored: 0 25px 50px -12px var(--tw-shadow-color);box-shadow:var(--tw-ring-offset-shadow, 0 0 #0000),var(--tw-ring-shadow, 0 0 #0000),var(--tw-shadow)}.hover\:shadow-lg:hover{--tw-shadow: 0 10px 15px -3px rgb(0 0 0 / .1), 0 4px 6px -4px rgb(0 0 0 / .1);--tw-shadow-colored: 0 10px 15px -3px var(--tw-shadow-color), 0 4px 6px -4px var(--tw-shadow-color);box-shadow:var(--tw-ring-offset-shadow, 0 0 #0000),var(--tw-ring-shadow, 0 0 #0000),var(--tw-shadow)}.hover\:shadow-md:hover{--tw-shadow: 0 4px 6px -1px rgb(0 0 0 / .1), 0 2px 4px -2px rgb(0 0 0 / .1);--tw-shadow-colored: 0 4px 6px -1px var(--tw-shadow-color), 0 2px 4px -2px var(--tw-shadow-color);box-shadow:var(--tw-ring-offset-shadow, 0 0 #0000),var(--tw-ring-shadow, 0 0 #0000),var(--tw-shadow)}.hover\:shadow-xl:hover{--tw-shadow: 0 20px 25px -5px rgb(0 0 0 / .1), 0 8px 10px -6px rgb(0 0 0 / .1);--tw-shadow-colored: 0 20px 25px -5px var(--tw-shadow-color), 0 8px 10px -6px var(--tw-shadow-color);box-shadow:var(--tw-ring-offset-shadow, 0 0 #0000),var(--tw-ring-shadow, 0 0 #0000),var(--tw-shadow)}.focus\:border-blue-500:focus{--tw-border-opacity: 1;border-color:rgb(59 130 246 / var(--tw-border-opacity, 1))}.focus\:border-primary-500:focus{--tw-border-opacity: 1;border-color:rgb(53 79 82 / var(--tw-border-opacity, 1))}.focus\:border-transparent:focus{border-color:transparent}.focus\:outline-none:focus{outline:2px solid transparent;outline-offset:2px}.focus\:ring-2:focus{--tw-ring-offset-shadow: var(--tw-ring-inset) 0 0 0 var(--tw-ring-offset-width) var(--tw-ring-offset-color);--tw-ring-shadow: var(--tw-ring-inset) 0 0 0 calc(2px + var(--tw-ring-offset-width)) var(--tw-ring-color);box-shadow:var(--tw-ring-offset-shadow),var(--tw-ring-shadow),var(--tw-shadow, 0 0 #0000)}.focus\:ring-\[\#354F52\]:focus{--tw-ring-opacity: 1;--tw-ring-color: rgb(53 79 82 / var(--tw-ring-opacity, 1))}.focus\:ring-blue-500:focus{--tw-ring-opacity: 1;--tw-ring-color: rgb(59 130 246 / var(--tw-ring-opacity, 1))}.focus\:ring-primary-500:focus{--tw-ring-opacity: 1;--tw-ring-color: rgb(53 79 82 / var(--tw-ring-opacity, 1))}.focus\:ring-offset-2:focus{--tw-ring-offset-width: 2px}.disabled\:cursor-not-allowed:disabled{cursor:not-allowed}.disabled\:bg-gray-400:disabled{--tw-bg-opacity: 1;background-color:rgb(156 163 175 / var(--tw-bg-opacity, 1))}.disabled\:opacity-50:disabled{opacity:.5}.group:hover .group-hover\:translate-x-1{--tw-translate-x: .25rem;transform:translate(var(--tw-translate-x),var(--tw-translate-y)) rotate(var(--tw-rotate)) skew(var(--tw-skew-x)) skewY(var(--tw-skew-y)) scaleX(var(--tw-scale-x)) scaleY(var(--tw-scale-y))}.group:hover .group-hover\:scale-110{--tw-scale-x: 1.1;--tw-scale-y: 1.1;transform:translate(var(--tw-translate-x),var(--tw-translate-y)) rotate(var(--tw-rotate)) skew(var(--tw-skew-x)) skewY(var(--tw-skew-y)) scaleX(var(--tw-scale-x)) scaleY(var(--tw-scale-y))}.group:hover .group-hover\:scale-x-100{--tw-scale-x: 1;transform:translate(var(--tw-translate-x),var(--tw-translate-y)) rotate(var(--tw-rotate)) skew(var(--tw-skew-x)) skewY(var(--tw-skew-y)) scaleX(var(--tw-scale-x)) scaleY(var(--tw-scale-y))}.group:hover .group-hover\:bg-amber-200{--tw-bg-opacity: 1;background-color:rgb(253 230 138 / var(--tw-bg-opacity, 1))}.group:hover .group-hover\:bg-blue-200{--tw-bg-opacity: 1;background-color:rgb(191 219 254 / var(--tw-bg-opacity, 1))}.group:hover .group-hover\:bg-green-200{--tw-bg-opacity: 1;background-color:rgb(187 247 208 / var(--tw-bg-opacity, 1))}.group:hover .group-hover\:bg-purple-200{--tw-bg-opacity: 1;background-color:rgb(233 213 255 / var(--tw-bg-opacity, 1))}.group:hover .group-hover\:text-\[\#354F52\]{--tw-text-opacity: 1;color:rgb(53 79 82 / var(--tw-text-opacity, 1))}.group:hover .group-hover\:text-amber-600{--tw-text-opacity: 1;color:rgb(217 119 6 / var(--tw-text-opacity, 1))}.group:hover .group-hover\:text-blue-200{--tw-text-opacity: 1;color:rgb(191 219 254 / var(--tw-text-opacity, 1))}.group:hover .group-hover\:text-blue-600{--tw-text-opacity: 1;color:rgb(37 99 235 / var(--tw-text-opacity, 1))}.group:hover .group-hover\:text-gray-600{--tw-text-opacity: 1;color:rgb(75 85 99 / var(--tw-text-opacity, 1))}.group:hover .group-hover\:text-green-600{--tw-text-opacity: 1;color:rgb(22 163 74 / var(--tw-text-opacity, 1))}.group:hover .group-hover\:text-primary-600{--tw-text-opacity: 1;color:rgb(46 67 70 / var(--tw-text-opacity, 1))}.group:hover .group-hover\:text-purple-600{--tw-text-opacity: 1;color:rgb(147 51 234 / var(--tw-text-opacity, 1))}.group:hover .group-hover\:opacity-100{opacity:1}@media (min-width: 640px){.sm\:w-auto{width:auto}.sm\:flex-row{flex-direction:row}.sm\:px-6{padding-left:1.5rem;padding-right:1.5rem}}@media (min-width: 768px){.md\:block{display:block}.md\:inline{display:inline}.md\:flex{display:flex}.md\:hidden{display:none}.md\:h-12{height:3rem}.md\:translate-x-0{--tw-translate-x: 0px;transform:translate(var(--tw-translate-x),var(--tw-translate-y)) rotate(var(--tw-rotate)) skew(var(--tw-skew-x)) skewY(var(--tw-skew-y)) scaleX(var(--tw-scale-x)) scaleY(var(--tw-scale-y))}.md\:grid-cols-2{grid-template-columns:repeat(2,minmax(0,1fr))}.md\:grid-cols-3{grid-template-columns:repeat(3,minmax(0,1fr))}.md\:grid-cols-4{grid-template-columns:repeat(4,minmax(0,1fr))}.md\:gap-2{gap:.5rem}.md\:gap-3{gap:.75rem}.md\:gap-4{gap:1rem}.md\:px-4{padding-left:1rem;padding-right:1rem}.md\:px-6{padding-left:1.5rem;padding-right:1.5rem}.md\:pl-64{padding-left:16rem}.md\:text-2xl{font-size:1.5rem;line-height:2rem}.md\:text-5xl{font-size:3rem;line-height:1}.md\:text-7xl{font-size:4.5rem;line-height:1}.md\:text-base{font-size:1rem;line-height:1.5rem}}@media (min-width: 1024px){.lg\:col-span-2{grid-column:span 2 / span 2}.lg\:col-span-3{grid-column:span 3 / span 3}.lg\:col-span-7{grid-column:span 7 / span 7}.lg\:flex{display:flex}.lg\:grid-cols-12{grid-template-columns:repeat(12,minmax(0,1fr))}.lg\:grid-cols-2{grid-template-columns:repeat(2,minmax(0,1fr))}.lg\:grid-cols-3{grid-template-columns:repeat(3,minmax(0,1fr))}.lg\:grid-cols-4{grid-template-columns:repeat(4,minmax(0,1fr))}.lg\:grid-cols-5{grid-template-columns:repeat(5,minmax(0,1fr))}.lg\:px-8{padding-left:2rem;padding-right:2rem}}@media (min-width: 1280px){.xl\:grid-cols-5{grid-template-columns:repeat(5,minmax(0,1fr))}}