CBS-microdata-catalogus — agent-friendly-variant

Een toolkit om de CBS-microdata-catalogus te scrapen, indexeren en doorzoeken; voor gebruik door AI-agents (of mensen).

Gebruik

Dit project is primair bedoeld voor gebruik met AI-agents, dus open bijvoorbeeld VSCode & gebruik daar de agent-interface van GitHub Copilot. Op die manier kan je vragen stellen aan de agent over welke datasets er zijn, hoe je een bepaalde vraag kan beantwoorden met CBS-microdata, hoe je datasets aan elkaar moet koppelen en welke R-code je hiervoor zou kunnen gebruiken, et cetera. Omdat de agent via commando's zelf de database met datasets kan doorzoeken, en eventueel alle bijbehorende PDF's met omschrijvingen van de datasets kan lezen, zou je zo sneller ingewikkelde CBS-microdata-vragen moeten kunnen oplossen. Daarnaast kan je ook zelf de CLI gebruiken om handmatig te zoeken in de database.

Installatie

Dit project gebruikt 'uv' voor het beheer van Python & Python-packages; installeer dus eerst 'uv'. Dat kan op de AVD/VDI in PowerShell met:

irm https://astral.sh/uv/install.ps1 | iex

Clone het project naar een lokale locatie op jouw AVD/VDI (bijvoorbeeld C:\Users\voornaam.achternaam\GitHub (local)):

# Op lokale locatie op jouw AVD/VDI
gh repo clone KennispuntTwente/microdata_catalogus

Vervolgens kan je met 'uv' Python & packages installeren, en scripts runnen. In een terminal in de geclonede map:

# In geclonede map
# Installeer Python & dependencies met uv
uv sync

Na het clonen bouw je de lokale catalogusdatabase en PDF-cache op met de initiële scrape. Deze gegenereerde bestanden worden niet meegeleverd in de repository. De volledige update kan enige tijd duren.

# In geclonede map
# Scrapen
# Optie 1: Volledige update (scrapen + PDF's verwerken in één keer)
uv run python scripts/catalog.py update

# Optie 2: Stap voor stap
uv run python scripts/catalog.py scrape        # scrape CBS-website
uv run python scripts/catalog.py parse-pdfs    # download & verwerk PDF's

# Controleer de status van de database
uv run python scripts/catalog.py status

Agent-skills & output in investigations/

In .github/skills/ staat uitleg voor agents over hoe ze de database kunnen updaten als dat nodig is, en over hoe ze de database het beste kunnen doorzoeken. Daarin staat instructie om resultaten van een vraag over de microdata-catalogus op te slaan in een markdown-file in de investigations/-map. Dergelijke output in de investigations/-map kunnen we eventueel committen om onderzoek naar bepaalde vragen met elkaar te delen en te verbeteren.

CLI-commando's

Hieronder staan CLI-commando's voor diverse taken uitgelegd. Dit gaat dus zowel om het opbouwen van de initiële database via de scrape, als vervolgens het doorzoeken ervan.

Database bijwerken & beheren

# Volledige update: nieuwe datasets ontdekken + details scrapen + PDF's verwerken
uv run python scripts/catalog.py update

# Een specifieke dataset bijwerken
uv run python scripts/catalog.py update -d SPOLISBUS

# Alles opnieuw scrapen en verwerken
uv run python scripts/catalog.py update --force

# Alleen web scrapen (PDF-verwerking overslaan)
uv run python scripts/catalog.py update --skip-pdfs

# Controleer of er nieuwe datasets op de CBS-site staan
uv run python scripts/catalog.py discover

# Nieuwe datasets ook meteen downloaden en toevoegen aan de database
uv run python scripts/catalog.py discover --download

# Databasestatus tonen (aantallen, versheid)
uv run python scripts/catalog.py status

# Verouderde datasets tonen (30+ dagen niet bijgewerkt)
uv run python scripts/catalog.py outdated
uv run python scripts/catalog.py outdated --days 7

Database doorzoeken

# Zoek datasets op trefwoord
uv run python scripts/catalog.py search "inkomen"
uv run python scripts/catalog.py search "bevolking" --category=bevolking

# Zoek variabelen in alle datasets
uv run python scripts/catalog.py search-vars "geslacht"
uv run python scripts/catalog.py search-vars "loon" --dataset=SPOLISBUS

# Gedetailleerde informatie over een dataset
uv run python scripts/catalog.py info SPOLISBUS

# Variabelen in een dataset tonen
uv run python scripts/catalog.py variables SPOLISBUS

# Alle categorieën tonen
uv run python scripts/catalog.py categories

# Databasestatistieken
uv run python scripts/catalog.py stats

Analyse van koppelbare datasets

# Zoek datasets die gekoppeld kunnen worden aan een bepaalde dataset
uv run python scripts/catalog.py joinable SPOLISBUS

# Zoek het koppelpad tussen twee datasets
uv run python scripts/catalog.py join-path SPOLISBUS GBAPERSOONTAB

# Alle bekende koppelsleutels tonen
uv run python scripts/catalog.py join-keys

# Alle datasets met een bepaalde sleutel zoeken
uv run python scripts/catalog.py datasets-with-key RINPERSOON

# Suggesties voor onderzoeksthema's
uv run python scripts/catalog.py suggest "arbeidsmarkt inkomen"

JSON-output (voor agents)

Alle commando's ondersteunen de --json-output / -j vlag voor gestructureerde uitvoer:

uv run python scripts/catalog.py search "inkomen" -j
uv run python scripts/catalog.py info SPOLISBUS -j
uv run python scripts/catalog.py status -j