ESB Vaktin
Backend for esbvaktin.is — an independent, data-driven civic information platform for Iceland's EU membership referendum (29 August 2026).
What it does
ESB Vaktin monitors Icelandic public discourse about EU membership, extracts factual claims, and assesses them against a curated evidence database. The platform tracks claims equally regardless of whether they are pro-EU or anti-EU.
Pipeline: articles and speeches are scanned → factual claims extracted → matched against 390+ evidence entries → assessed on a five-point scale (supported, partially supported, unsupported, misleading, unverifiable) → published with full source transparency.
Transparency
All AI prompts are published. The agent definitions in .claude/agents/ contain the exact instructions given to each AI model. The context preparation code in src/esbvaktin/pipeline/prepare_context.py shows how articles, evidence, and instructions are assembled. The evidence database is committed in data/seeds/.
See METHODOLOGY.md for the full methodological description, or Aðferðafræði on the site.
Architecture
- Ground Truth database — PostgreSQL + pgvector with curated evidence (legal texts, economic data, treaty provisions, precedents)
- Analysis pipeline — Claude-powered claim extraction, assessment, and omission analysis via custom agents
- Icelandic NLP — GreynirCorrect + Málstaður API for language quality
- Site export — generates static JSON data for the 11ty frontend
Tech stack
Python 3.12+ · uv · PostgreSQL 17 + pgvector · BAAI/bge-m3 embeddings · Claude (Anthropic) · GreynirCorrect · 11ty
Setup
git clone https://github.com/bgautijonsson/esbvaktin.git
cd esbvaktin
cp .env.example .env # DATABASE_URL defaults work for local Docker
docker compose up -d # Start PostgreSQL 17 + pgvector
uv sync --extra dev # Install dependencies + dev tools
uv run python scripts/init_db.py --seed # Create schema + seed evidence
Dependency extras
| Extra | What it adds | When you need it |
|---|
| (none) | Core: trafilatura, psycopg, httpx, pydantic | Always |
dev | pytest, pytest-asyncio, ruff | Running tests and linting |
icelandic | GreynirCorrect, icegrams, islenska | Icelandic text generation/correction |
embeddings | FlagEmbedding, torch, transformers | Semantic search, evidence matching (~2GB model) |
email | requests | Mailgun email integration |
ghost | pyjwt | Ghost CMS publishing |
Optional: Alþingi speeches
The speech analysis pipeline requires althingi.db from the althingi-mcp project. Set ALTHINGI_DB_PATH=/path/to/althingi.db in .env. The core article pipeline works without it.
Optional: Site export
Export scripts generate JSON for the esbvaktin-site frontend. They default to ../esbvaktin-site as sibling directory — override with --site-dir /path/to/site.
Running tests
uv run --extra dev python -m pytest # All tests
uv run --extra dev ruff check src/ scripts/ # Lint
Contributing
See CONTRIBUTING.md for setup details, dependency guide, and contribution guidelines.
Licence
Code is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). Content and data in data/seeds/ are licensed under CC BY-SA 4.0.
