Politrack: track Austrian politicians from public sources

Initial import of Politrack, a self-hosted service that tracks Austrian
politicians from federal to municipal level - roles, votes, money flows,
statements, meetings, social media and legal proceedings - with every claim
linked to its sources.

- backend: FastAPI + Postgres/pgvector; adapter framework (fetch -> parse ->
  load -> enrich) with robots.txt/TDM-aware fetching, a raw-response archive
  for reparsing, and a claim/evidence model with corroboration
- sources: Parliament, Wikidata, EU Parliament/Commission, Council of
  Ministers, Rechnungshof party reports and donations, procurement, RTR media
  transparency, political ad libraries, WKStA, news feeds, Wikipedia edits,
  Bluesky, Mastodon, public Telegram channels, YouTube and X (official API)
- web: Next.js frontend in German and English with typed API client
- mcp: MCP server for AI agents and RAG
- docs: architecture, data model, sources, legal notes, Unraid deployment and
  contributor guides; Docker Compose setup for Unraid

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
simonandClaude Opus 5.5 committed 2026-10-28 20:02:01 +01:00
commit 583ccba31c
187 files changed
+39890

No files matched your search

View File
Whitespace-only changes.
+253
View File
@@ -0,0 +1,253 @@
"""Public read API (JSON). OpenAPI docs at /api/docs; schema at /api/openapi.json.
Conventions: every list endpoint takes limit/offset; claim-like endpoints take the source filter
(exclude_sources, min_trust) and topic/date filters; slugs identify persons, parties and organisations.
"""
from __future__ import annotations
from collections.abc import Iterator
from datetime import date
from typing import Annotated
from fastapi import Depends, FastAPI, Header, HTTPException, Query
from fastapi.middleware.cors import CORSMiddleware
from psycopg import Connection
from politrack import queries
from politrack.api import schemas as s
from politrack.config import get_settings
from politrack.db import connection
from politrack.queries import SourceFilter
app = FastAPI(
title="Politrack API",
version="0.2.0",
description="Evidence-backed information on Austrian politicians and parties. Every claim links to its sources.",
docs_url="/api/docs",
openapi_url="/api/openapi.json",
)
app.add_middleware(CORSMiddleware, allow_origins=get_settings().api_cors_origins, allow_methods=["GET", "POST"],
allow_headers=["*"])
def db() -> Iterator[Connection]:
with connection() as conn:
yield conn
def csv_list(value: str | None) -> list[str] | None:
items = [v.strip() for v in (value or "").split(",") if v.strip()]
return items or None
def source_filter(
exclude_sources: Annotated[str | None, Query(description="Comma-separated source slugs to ignore")] = None,
min_trust: Annotated[int, Query(ge=0, le=100, description="Ignore sources below this trust score")] = 0,
) -> SourceFilter:
return SourceFilter(exclude_sources=csv_list(exclude_sources) or [], min_trust=min_trust)
DB = Annotated[Connection, Depends(db)]
Sources = Annotated[SourceFilter, Depends(source_filter)]
Limit = Annotated[int, Query(ge=1, le=500)]
Offset = Annotated[int, Query(ge=0)]
def not_found(value, what: str):
if not value:
raise HTTPException(404, f"{what} not found")
return value
@app.get("/healthz", include_in_schema=False)
def healthz(conn: DB) -> dict:
conn.execute("SELECT 1")
return {"ok": True}
# -- reference data -----------------------------------------------------------------------
@app.get("/api/v1/stats", response_model=s.Stats)
def get_stats(conn: DB):
return queries.stats(conn)
@app.get("/api/v1/sources", response_model=list[s.Source])
def get_sources(conn: DB):
return queries.list_sources(conn)
@app.get("/api/v1/topics", response_model=list[s.Topic])
def get_topics(conn: DB):
return queries.list_topics(conn)
# -- parties & organisations ----------------------------------------------------------------
@app.get("/api/v1/parties", response_model=list[s.Party])
def get_parties(conn: DB):
return queries.list_parties(conn)
@app.get("/api/v1/parties/{slug}", response_model=s.PartyDetail)
def get_party(slug: str, conn: DB):
return not_found(queries.get_party(conn, slug), "party")
@app.get("/api/v1/organizations", response_model=list[s.OrganizationListItem])
def get_organizations(conn: DB, q: str | None = None, kind: str | None = None, limit: Limit = 50, offset: Offset = 0):
return queries.list_organizations(conn, q=q, kind=kind, limit=limit, offset=offset)
@app.get("/api/v1/organizations/{slug}", response_model=s.OrganizationDetail)
def get_organization(slug: str, conn: DB):
return not_found(queries.get_organization(conn, slug), "organization")
# -- persons --------------------------------------------------------------------------------
@app.get("/api/v1/persons", response_model=list[s.PersonListItem])
def get_persons(
conn: DB,
q: str | None = None,
party: str | None = None,
level: Annotated[str | None, Query(pattern="^(eu|federal|state|district|municipal|party|other)$")] = None,
status: Annotated[str, Query(pattern="^(active|former|party_member|deceased|all)$")] = "active",
limit: Limit = 50,
offset: Offset = 0,
):
return queries.list_persons(conn, q=q, party=party, level=level, status=None if status == "all" else status,
limit=limit, offset=offset)
@app.get("/api/v1/former", response_model=list[s.FormerPerson])
def get_former(conn: DB, party: str | None = None, limit: Limit = 50, offset: Offset = 0):
"""Former politicians, most recently in the news first."""
return queries.former_overview(conn, party=party, limit=limit, offset=offset)
@app.get("/api/v1/persons/{slug}", response_model=s.PersonDetail)
def get_person(slug: str, conn: DB):
return not_found(queries.get_person(conn, slug), "person")
@app.get("/api/v1/persons/{slug}/votes", response_model=list[s.PersonVote])
def get_person_votes(slug: str, conn: DB, topics: str | None = None, limit: Limit = 100, offset: Offset = 0):
return queries.person_votes(conn, slug, topics=csv_list(topics), limit=limit, offset=offset)
@app.get("/api/v1/persons/{slug}/network", response_model=s.Network)
def get_person_network(slug: str, conn: DB):
"""Organisations connected to the person (side jobs, careers, party, meetings) and their money flows."""
return queries.person_network(conn, slug)
# -- claims, timeline, calendar ----------------------------------------------------------------
@app.get("/api/v1/claims", response_model=list[s.Claim])
def get_claims(
conn: DB,
sources: Sources,
person: str | None = None,
party: str | None = None,
organization: str | None = None,
types: Annotated[str | None, Query(description="Comma-separated claim types")] = None,
topics: Annotated[str | None, Query(description="Comma-separated topic slugs")] = None,
since: date | None = None,
until: date | None = None,
q: str | None = None,
limit: Limit = 50,
offset: Offset = 0,
):
return queries.list_claims(conn, sources=sources, person=person, party=party, organization=organization,
claim_types=csv_list(types), topics=csv_list(topics), since=since, until=until, q=q,
limit=limit, offset=offset)
@app.get("/api/v1/timeline", response_model=list[s.TimelineBucket])
def get_timeline(conn: DB, sources: Sources, person: str | None = None, party: str | None = None):
return queries.timeline_histogram(conn, sources=sources, person=person, party=party)
@app.get("/api/v1/calendar", response_model=s.CalendarData)
def get_calendar(conn: DB, sources: Sources, start: date, end: date, person: str | None = None,
party: str | None = None, kinds: str | None = None):
if (end - start).days > 400:
raise HTTPException(400, "range too large (max 400 days)")
return queries.calendar(conn, sources=sources, start=start, end=end, person=person, party=party,
kinds=csv_list(kinds))
# -- money, social, wikipedia ---------------------------------------------------------------------
@app.get("/api/v1/money", response_model=list[s.MoneyFlow])
def get_money(conn: DB, sources: Sources, kinds: str | None = None, org: str | None = None, person: str | None = None,
q: str | None = None, since: date | None = None, until: date | None = None,
min_amount: float | None = None, limit: Limit = 50, offset: Offset = 0):
"""Donations, contracts, government ads, party funding, sponsoring, political ads."""
return queries.list_money(conn, sources=sources, kinds=csv_list(kinds), org=org, person=person, q=q, since=since,
until=until, min_amount=min_amount, limit=limit, offset=offset)
@app.get("/api/v1/money/summary", response_model=list[s.MoneySummaryRow])
def get_money_summary(conn: DB, kinds: str | None = None, since: date | None = None):
return queries.money_summary(conn, kinds=csv_list(kinds), since=since)
@app.get("/api/v1/social", response_model=list[s.SocialPost])
def get_social(conn: DB, sources: Sources, person: str | None = None, party: str | None = None,
platforms: str | None = None, limit: Limit = 50, offset: Offset = 0):
return queries.social_feed(conn, sources=sources, person=person, party=party, platforms=csv_list(platforms),
limit=limit, offset=offset)
@app.get("/api/v1/wiki-edits", response_model=list[s.WikiEdit])
def get_wiki_edits(conn: DB, limit: Limit = 100, offset: Offset = 0):
return queries.wiki_edits(conn, limit=limit, offset=offset)
# -- votes, search ------------------------------------------------------------------------------
@app.get("/api/v1/votes", response_model=list[s.VoteItem])
def get_votes(conn: DB, party: str | None = None, topics: str | None = None, roll_call: bool | None = None,
since: date | None = None, until: date | None = None, limit: Limit = 50, offset: Offset = 0):
return queries.list_votes(conn, party=party, topics=csv_list(topics), roll_call=roll_call, since=since,
until=until, limit=limit, offset=offset)
@app.get("/api/v1/votes/{vote_id}", response_model=s.VoteDetail)
def get_vote(vote_id: int, conn: DB):
return not_found(queries.vote_detail(conn, vote_id), "vote")
@app.get("/api/v1/search", response_model=list[s.SearchHit])
def get_search(conn: DB, sources: Sources, q: Annotated[str, Query(min_length=2)], since: date | None = None,
until: date | None = None, limit: Limit = 20):
return queries.search(conn, q, sources=sources, since=since, until=until, limit=limit)
# -- admin (POLITRACK_ADMIN_TOKEN) ------------------------------------------------------------------
def require_admin(authorization: Annotated[str | None, Header()] = None) -> str:
token = get_settings().admin_token
if not token or authorization != f"Bearer {token}":
raise HTTPException(401, "admin token required")
return "admin-api"
@app.get("/api/v1/admin/runs", response_model=list[s.Run], include_in_schema=False)
def get_runs(conn: DB, _: Annotated[str, Depends(require_admin)], limit: Limit = 50):
return queries.recent_runs(conn, limit=limit)
@app.get("/api/v1/review", response_model=list[s.PendingClaim], include_in_schema=False)
def get_review_queue(conn: DB, _: Annotated[str, Depends(require_admin)], limit: Limit = 50):
return queries.pending_claims(conn, limit=limit)
@app.post("/api/v1/review/{claim_id}", include_in_schema=False)
def post_review(claim_id: int, decision: Annotated[str, Query(pattern="^(published|rejected)$")], conn: DB,
reviewer: Annotated[str, Depends(require_admin)]) -> dict:
queries.set_review(conn, claim_id, decision, reviewer)
return {"ok": True}
+535
View File
@@ -0,0 +1,535 @@
"""Response models: the API contract. `politrack openapi --ts ../web/src/lib/api-types.ts` turns them into
TypeScript types for the web app, so frontend and backend cannot silently drift apart."""
from __future__ import annotations
from datetime import date, datetime
from typing import Any, Literal
from pydantic import BaseModel, ConfigDict
ClaimType = Literal["role", "vote", "donation", "money_flow", "statement", "appearance", "meeting", "travel",
"side_job", "legal_proceeding", "lobbying", "media_mention", "career", "parliamentary_question",
"government_decision", "wiki_edit", "declaration", "ownership", "affiliation", "party_finance",
"other"]
PersonStatus = Literal["active", "former", "party_member", "deceased"]
class Model(BaseModel):
# Fields with defaults are always present in responses, so mark them required in the (serialization)
# schema - the generated TypeScript types then have no needless optional fields.
model_config = ConfigDict(from_attributes=True, json_schema_serialization_defaults_required=True)
class Stats(Model):
persons: int
active_persons: int
parties: int
claims: int
corroborated: int
pending_review: int
documents: int
vote_events: int
roll_call_votes: int
events: int
money_flows: int
last_update: datetime | None = None
class Source(Model):
slug: str
name: str
kind: str
homepage: str | None = None
license: str | None = None
access_method: str
default_trust: int
tos_notes: str | None = None
documents: int
class Topic(Model):
slug: str
name_de: str
name_en: str
class Evidence(Model):
url: str
title: str | None = None
source: str
source_name: str | None = None
source_kind: str | None = None
published_at: datetime | None = None
quote: str | None = None
stance: Literal["supports", "contradicts", "mentions"] = "supports"
archive_url: str | None = None
class MoneyFacet(Model):
kind: str
amount: float | None = None
amount_category: str | None = None
currency: str | None = None
paid_on: date | None = None
period: str | None = None
reference: str | None = None
category: str | None = None
payer_name: str | None = None
payee_name: str | None = None
class Claim(Model):
id: int
claim_type: ClaimType
summary_de: str
summary_en: str | None = None
occurred_at: datetime | None = None
valid_from: date | None = None
valid_to: date | None = None
status: Literal["reported", "corroborated", "disputed", "retracted"]
sensitive: bool
review_status: Literal["pending", "published", "rejected"]
data: dict[str, Any] = {}
person_slug: str | None = None
person_name: str | None = None
organization_slug: str | None = None
organization_short: str | None = None
organization_name: str | None = None
counterpart_slug: str | None = None
counterpart_name: str | None = None
counterpart_kind: str | None = None
counterpart_person_slug: str | None = None
counterpart_person_name: str | None = None
legal_stage: str | None = None
legal_offense: str | None = None
legal_authority: str | None = None
money: MoneyFacet | None = None
platform: str | None = None
topics: list[Topic] | None = None
evidence: list[Evidence]
source_count: int
class PartyRef(Model):
slug: str
short_name: str | None = None
color: str | None = None
class PersonListItem(Model):
slug: str
full_name: str
photo_url: str | None = None
status: PersonStatus
status_verified: bool
last_office_end: date | None = None
current_roles: list[str] | None = None
parties: list[PartyRef] | None = None
class RoleEvidence(Model):
url: str
source: str
class Role(Model):
role: str
level: str
region: str | None = None
start_date: date | None = None
end_date: date | None = None
body: str | None = None
body_slug: str | None = None
party_slug: str | None = None
party_short: str | None = None
party_color: str | None = None
claim_status: str
evidence: list[RoleEvidence] | None = None
class SocialAccountOut(Model):
platform: str
handle: str | None = None
url: str
verified: bool
class PersonDetail(Model):
slug: str
full_name: str
given_name: str | None = None
family_name: str | None = None
birth_date: date | None = None
death_date: date | None = None
photo_url: str | None = None
wikidata_qid: str | None = None
parlament_pad: str | None = None
ep_id: str | None = None
status: PersonStatus
status_verified: bool
last_office_end: date | None = None
roles: list[Role]
social_accounts: list[SocialAccountOut]
claim_counts: dict[str, int]
class FormerPerson(Model):
slug: str
full_name: str
photo_url: str | None = None
status: PersonStatus
last_office_end: date | None = None
last_role: str | None = None
latest_news: str | None = None
latest_news_at: datetime | None = None
latest_news_url: str | None = None
latest_career: str | None = None
class NetworkOrg(Model):
id: int
slug: str
name: str
kind: str
via: list[str]
label: str | None = None
money: dict[str, Any] | None = None
class Network(Model):
organizations: list[NetworkOrg]
class Party(Model):
slug: str
name: str
short_name: str | None = None
color: str | None = None
logo_url: str | None = None
active_officials: int = 0
total_people: int = 0
class PartyMember(Model):
slug: str
full_name: str
photo_url: str | None = None
role: str
level: str
region: str | None = None
body: str | None = None
class FormerMember(Model):
slug: str
full_name: str
last_office_end: date | None = None
last_mention: datetime | None = None
class MoneyByYear(Model):
year: int
kind: str
total: float | None = None
count: int
class Finance(Model):
data: dict[str, Any]
valid_from: date | None = None
class CountByPosition(Model):
position: str
count: int
class Dissenter(Model):
slug: str
full_name: str
dissenting_votes: int
class RelatedOrg(Model):
claim_type: str
slug: str
name: str
kind: str
class PartyDetail(Model):
slug: str
name: str
short_name: str | None = None
color: str | None = None
logo_url: str | None = None
kind: str
members: list[PartyMember]
former_members: list[FormerMember]
money_by_year: list[MoneyByYear]
finance: list[Finance]
vote_stats: list[CountByPosition]
dissent: list[Dissenter]
related: list[RelatedOrg]
class OrganizationListItem(Model):
slug: str
name: str
short_name: str | None = None
kind: str
paid: float | None = None
received: float | None = None
class OrgMoney(Model):
kind: str
direction: Literal["paid", "received"]
total: float | None = None
count: int
first: str | None = None
last: str | None = None
class Counterparty(Model):
slug: str
name: str
kind: str
money_kind: str
direction: Literal["paid_to", "received_from"]
total: float | None = None
count: int
class OrgPerson(Model):
slug: str
full_name: str
via: str
summary_de: str
class OrganizationDetail(Model):
slug: str
name: str
short_name: str | None = None
kind: str
parent_slug: str | None = None
parent_name: str | None = None
identifiers: dict[str, str] | None = None
money: list[OrgMoney]
counterparties: list[Counterparty]
people: list[OrgPerson]
class MoneyFlow(Model):
id: int
summary_de: str
summary_en: str | None = None
occurred_at: datetime | None = None
status: str
data: dict[str, Any] = {}
kind: str
amount: float | None = None
amount_category: str | None = None
currency: str | None = None
paid_on: date | None = None
period: str | None = None
reference: str | None = None
category: str | None = None
payer_name: str | None = None
payee_name: str | None = None
payer_slug: str | None = None
payer_kind: str | None = None
payee_slug: str | None = None
payee_kind: str | None = None
evidence: list[Evidence]
source_count: int
class MoneySummaryRow(Model):
kind: str
slug: str
name: str
org_kind: str
side: Literal["payer", "payee"]
total: float | None = None
count: int
class SocialPost(Model):
id: int
platform: str | None = None
said_at: datetime | None = None
excerpt: str | None = None
url: str
title: str | None = None
data: dict[str, Any] = {}
person_slug: str | None = None
person_name: str | None = None
org_slug: str | None = None
org_name: str | None = None
evidence: list[Evidence]
class WikiEdit(Model):
id: int
occurred_at: datetime | None = None
summary_de: str
summary_en: str | None = None
data: dict[str, Any] = {}
org_slug: str
org_name: str
person_slug: str | None = None
person_name: str | None = None
url: str | None = None
class TimelineBucket(Model):
month: str
claim_type: str
count: int
class Participant(Model):
slug: str
name: str
class CalendarEvent(Model):
id: int
kind: str
title: str
starts_at: datetime | None = None
ends_at: datetime | None = None
location_name: str | None = None
country: str | None = None
url: str | None = None
description: str | None = None
body: str | None = None
participants: list[Participant]
class DayCount(Model):
day: date
claim_type: str
count: int
class CalendarData(Model):
events: list[CalendarEvent]
days: list[DayCount]
class PartyPosition(Model):
party: str | None = None
slug: str
color: str | None = None
position: str
class Speech(Model):
url: str
title: str | None = None
class VoteItem(Model):
id: int
item_title: str
item_ref: str | None = None
stage: str | None = None
voted_on: date | None = None
result: str | None = None
url: str | None = None
protocol_url: str | None = None
roll_call: bool
raw_text: str | None = None
chamber: str
positions: list[PartyPosition] = []
individual_votes: int = 0
class PersonVote(Model):
id: int
item_title: str
item_ref: str | None = None
stage: str | None = None
voted_on: date | None = None
result: str | None = None
url: str | None = None
protocol_url: str | None = None
roll_call: bool
position: str
faction: str | None = None
chamber: str
individual: bool
dissent: bool
spoke: Speech | None = None
topics: list[str] | None = None
class IndividualVote(Model):
slug: str
full_name: str
position: str
faction: str | None = None
dissent: bool
class VoteDetail(Model):
id: int
item_title: str
item_ref: str | None = None
stage: str | None = None
voted_on: date | None = None
result: str | None = None
url: str | None = None
protocol_url: str | None = None
roll_call: bool
raw_text: str | None = None
chamber: str
positions: list[PartyPosition]
individual: list[IndividualVote]
class SearchEvidence(Model):
url: str
title: str | None = None
source: str
class SearchHit(Model):
id: int
text: str
claim_id: int | None = None
document_id: int | None = None
summary_de: str | None = None
claim_type: str | None = None
occurred_at: datetime | None = None
person_slug: str | None = None
person_name: str | None = None
organization_slug: str | None = None
document_url: str | None = None
document_title: str | None = None
document_date: datetime | None = None
evidence: list[SearchEvidence] | None = None
score: float
class Run(Model):
adapter: str
mode: str
status: str
started_at: datetime
finished_at: datetime | None = None
stats: dict[str, Any] = {}
error: str | None = None
class PendingClaim(Model):
id: int
claim_type: str
summary_de: str
occurred_at: datetime | None = None
full_name: str | None = None
evidence: list[dict[str, Any]] | None = None