---
title: German Promise Tracker DIP KB
emoji: 🗳️
colorFrom: blue
colorTo: green
sdk: streamlit
app_file: app.py
pinned: false
license: mit
---

# German Promise Tracker — Bundestag DIP Knowledge Base

This Hugging Face Space builds a project knowledge base from the German Bundestag DIP API and displays it in a Streamlit dashboard.

The dashboard is designed for a political promise tracker, but it deliberately separates two layers:

1. **DIP evidence layer**: records fetched from the official Bundestag DIP API.
2. **Reviewed promise layer**: human-reviewed promise rows that can link to DIP evidence.

It does **not** automatically label a promise as completed, broken, or in progress.  DIP records are evidence; promise status requires review.

## Deployment on Hugging Face Spaces

1. Create a new Hugging Face Space.
2. Choose **Streamlit**.
3. Upload all files from this folder.
4. Add a Space secret called `DIP_API_KEY`.
5. Restart the Space and open the **Build / Refresh DIP KB** tab.

## Local run

```bash
pip install -r requirements.txt
export DIP_API_KEY="your-dip-api-key"
streamlit run app.py
```

## Build the knowledge base from the command line

```bash
export DIP_API_KEY="your-dip-api-key"
python scripts/build_dip_knowledge_base.py \
  --resources vorgang vorgangsposition drucksache \
  --wahlperiode 21 \
  --date-start 2025-01-01 \
  --max-pages 5
```

Outputs:

- `data/dip_knowledge_base.csv` — normalized dashboard table.
- `data/dip_raw_documents.jsonl` — raw API JSON for auditability.
- `data/dip_fetch_metadata.json` — fetch parameters and counts.

## API resources supported

The direct REST client supports all documented DIP resource types used by the API:

- `vorgang`
- `vorgangsposition`
- `drucksache`
- `drucksache-text`
- `plenarprotokoll`
- `plenarprotokoll-text`
- `aktivitaet`
- `person`

## Optional BundestagsAPy wrapper

The project includes `scripts/fetch_with_bundestagsapy_example.py` to show how to use the `BundestagsAPy` wrapper.  The production dashboard uses direct REST calls for explicit cursor pagination and schema normalization.

```bash
pip install -r requirements-optional.txt
python scripts/fetch_with_bundestagsapy_example.py
```

## Knowledge-base schema

`data/dip_knowledge_base.csv` uses one row per DIP API record.  Important columns include:

- `resource_type`
- `dip_id`
- `title`
- `abstract`
- `date`
- `updated`
- `election_period`
- `document_type`
- `document_number`
- `procedure_type`
- `procedure_position`
- `consultation_status`
- `initiative`
- `subject_area`
- `descriptors`
- `pdf_url`
- `api_url`
- `related_*_ids`
- `text_excerpt`
- `retrieved_at`

## Status rule

The app shows `consultation_status` from the DIP API when available.  It does not infer political promise fulfilment.  Use `manual_promise_tracker_template.csv` for reviewed status labels.