AI-powered political discourse analysis platform for analyzing semantic evolution and narrative changes in presidential communications.
Political discourse shapes public policy, yet its evolution over time is rarely analyzed systematically. VozPública provides quantitative and qualitative tools to trace how narratives, priorities, and meanings shift across presidential communications—grounded in primary sources and semantic analysis.
- 🔄 Automatic Data Ingestion - Automated scraping and processing of presidential discourse
- 🔍 Semantic Search - Vector-based search over presidential discourse using embeddings
- 💬 Question Answering - LLM-powered Q&A with source attribution
- 📊 Narrative Evolution - Track how political concepts change over time
- 🎯 Semantic Drift Detection - Identify and explain shifts in discourse meaning
- 🌐 Bilingual Interface - Full ES/EN support without external i18n dependencies
- 📈 Analytics Dashboard - Interactive visualizations of discourse patterns
- Python 3.12+
- Node.js 18+ and npm
- PostgreSQL with pgvector extension
- Azure OpenAI account (or OpenAI API key)
-
Clone the repository
git clone https://github.com/Perruchok/vozpublica.git cd vozpublica -
Install backend dependencies
pip install -r requirements.txt
-
Install frontend dependencies
cd frontend npm install cd ..
-
Configure environment variables
Create a
.envfile in the root directory:# Database PGHOST=your-postgres-host PGDATABASE=your-database-name PGUSER=your-username PGPASSWORD=your-password PGPORT=5432 # Azure OpenAI AZURE_OPENAI_API_KEY=your-api-key AZURE_OPENAI_ENDPOINT=your-endpoint AZURE_OPENAI_EMBEDDING_DEPLOYMENT=text-embedding-3-small AZURE_OPENAI_CHAT_DEPLOYMENT=gpt-4 # Frontend NEXT_PUBLIC_API_URL=http://localhost:8000
-
Start the application
./start-dev.sh
-
Access the application
- Frontend: http://localhost:3000
- API Documentation: http://localhost:8000/docs
- Health Check: http://localhost:8000/health
📖 Detailed setup guide: See docs/QUICKSTART.md
Frontend
- Next.js 14 - React framework with App Router
- React 18 - UI library with hooks
- Custom i18n - Lightweight bilingual support via React Context
Backend
- FastAPI - Modern async Python web framework
- Pydantic v2 - Data validation and settings
- asyncpg - Async PostgreSQL driver with connection pooling
- Playwright - Web scraping for data ingestion
Database & AI
- PostgreSQL + pgvector - Vector similarity search
- Azure OpenAI - text-embedding-3-small, gpt-4
- HNSW indexing - Fast approximate nearest neighbor search
Deployment
- Docker - Multi-stage builds with non-root user
- Azure App Service - Backend hosting
- Vercel - Frontend hosting (optional)
┌─────────────┐ HTTP/REST ┌──────────────┐
│ Next.js │ ◄─────────────────► │ FastAPI │
│ Frontend │ JSON/CORS │ Backend │
│ (Port 3000)│ │ (Port 8000) │
└─────────────┘ └───────┬──────┘
│
▼
┌─────────────────┐
│ PostgreSQL │
│ + pgvector │
│ (Port 5432) │
└─────────────────┘
📖 Detailed architecture: See docs/ARCHITECTURE.md
vozpublica/
├── backend/ # FastAPI application
│ ├── app/
│ │ ├── api/ # API endpoints (routers)
│ │ ├── models/ # Pydantic models
│ │ └── services/ # Business logic
│ ├── analytics/ # Semantic drift & narrative analysis
│ ├── ingestion/ # Web scraping scripts
│ ├── utils/ # Database pool, logging, helpers
│ └── settings.py # Configuration management
├── frontend/ # Next.js application
│ ├── app/ # Pages (App Router)
│ ├── components/ # React components
│ ├── lib/ # API client & translations
│ └── styles/ # Global CSS
├── docs/ # Documentation
│ ├── ARCHITECTURE.md # System architecture
│ ├── DEPLOYMENT_READINESS.md
│ ├── QUICKSTART.md # Getting started guide
│ ├── TESTING_GUIDE.md # Testing instructions
│ └── BILINGUAL_SUPPORT.md
├── dev/ # Development tools
│ ├── notebooks/ # Jupyter notebooks for analysis
│ ├── samples/ # Test data
│ └── scripts/ # Utility scripts
├── Dockerfile # Production Docker image
├── Makefile # Common tasks (scrape, test, etc.)
├── requirements.txt # Python dependencies
└── start-dev.sh # Development server launcher
# Run backend tests
pytest backend/tests/
# Run frontend in development mode
cd frontend && npm run dev
# Test API endpoints
curl http://localhost:8000/health📖 Complete testing guide: See docs/TESTING_GUIDE.md
docker build -t vozpublica-backend .
docker run -p 8000:8000 vozpublica-backend# Configure Azure resources
./setup-azure.sh
# Pre-deployment checks
./precheck-deployment.sh📖 Deployment guide: See docs/DEPLOYMENT_READINESS.md
VozPública supports both Spanish and English without external i18n libraries. The implementation uses:
- React Context for language state management
- Custom translation objects in
frontend/lib/translations.js - Language toggle component in navigation
📖 Implementation details: See docs/BILINGUAL_SUPPORT.md
Contributions are welcome! Please reach out first before starting work:
- Open an issue or comment on an existing one to discuss your proposed changes
- Wait for feedback - I'd like to chat about implementation approach and scope
- Once we've aligned on the approach:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Run tests (
pytestfor backend,npm run devfor frontend) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Ensures your work aligns with project direction
- Avoids duplicate efforts
- Helps scope features appropriately
- Facilitates better collaboration
- Follow existing code style and structure
- Add tests for new features
- Update documentation as needed
- Keep commits focused and descriptive
This project is licensed under the MIT License - see the LICENSE file for details.
- Issues: GitHub Issues
- Repository: github.com/Perruchok/vozpublica
- Built with FastAPI
- Frontend powered by Next.js
- Vector search via pgvector
- AI capabilities from Azure OpenAI
Made with ❤️ for transparent political discourse analysis