You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
77 lines
2.7 KiB
77 lines
2.7 KiB
# Stemwijzer
|
|
|
|
A Dutch parliamentary voting compass that lets you vote on real Tweede Kamer motions and see which parties match your positions.
|
|
|
|
|
|
|
|
## What is Stemwijzer?
|
|
|
|
Stemwijzer ingests motions and voting records from the Dutch House of Representatives (Tweede Kamer), stores them in DuckDB, generates AI-powered explanations with an LLM, and presents a Streamlit UI where users can vote on real motions and explore party positions through SVD visualizations, trajectory analysis, and embedding-based similarity search.
|
|
|
|
## Features
|
|
|
|
- **Voting Compass** — Vote on real parliamentary motions and see which parties align with your choices
|
|
- **Explorer** — Interactive SVD visualizations, party trajectories over time, motion browser, and semantic search
|
|
- **Analytics** — SVD decomposition of voting patterns, UMAP projections, clustering, and drift analysis
|
|
- **LLM Enrichment** — Automatic generation of layman-friendly motion explanations using QWEN via OpenRouter
|
|
|
|
## Prerequisites
|
|
|
|
- Python >= 3.13
|
|
- [uv](https://docs.astral.sh/uv/) for dependency management
|
|
- (Optional) `OPENROUTER_API_KEY` for LLM enrichment
|
|
|
|
## Quickstart
|
|
|
|
```bash
|
|
# Clone and enter the repository
|
|
git clone <your-gitea-url>/sgeboers/stemwijzer.git
|
|
cd stemwijzer
|
|
|
|
# Install dependencies
|
|
uv sync
|
|
|
|
# Run the Streamlit app
|
|
uv run streamlit run Home.py
|
|
|
|
# Run the data pipeline (fetch motions, compute embeddings, etc.)
|
|
uv run python pipeline/run_pipeline.py
|
|
|
|
# Run tests
|
|
uv run pytest tests/ -q
|
|
```
|
|
|
|
The app will be available at http://localhost:8501.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
├── app.py # Streamlit UI entrypoint
|
|
├── database.py # DuckDB schema and queries
|
|
├── api_client.py # Tweede Kamer OData API client
|
|
├── explorer.py # Explorer page with SVD visualizations
|
|
├── pipeline/ # Data ingestion and analysis pipelines
|
|
├── analysis/ # SVD, clustering, trajectory modules
|
|
├── tests/ # pytest test suite
|
|
├── docs/ # Documentation, research, and plans
|
|
└── data/motions.db # DuckDB database (~18 GB)
|
|
```
|
|
|
|
## Documentation
|
|
|
|
- **[ARCHITECTURE.md](ARCHITECTURE.md)** — Comprehensive architecture overview, tech stack, and contributor guidance
|
|
- **[CODE_STYLE.md](CODE_STYLE.md)** — Coding conventions, naming, typing, and testing standards
|
|
- **[docs/solutions/](docs/solutions/)** — Documented solutions to past bugs and best practices
|
|
|
|
## Tech Stack
|
|
|
|
- **Language:** Python 3.13+
|
|
- **Data:** DuckDB via ibis-framework
|
|
- **UI:** Streamlit + Plotly
|
|
- **ML/Analysis:** scipy, scikit-learn, umap-learn
|
|
- **LLM:** QWEN via OpenRouter (OpenAI-compatible)
|
|
- **Package Manager:** uv
|
|
|
|
## License
|
|
|
|
[Your license here]
|
|
|