README.md

metadata

title: EBM Mentor
emoji: 🩺
colorFrom: green
colorTo: blue
sdk: gradio
app_file: app.py
pinned: false
tags:
  - track:backyard
  - achievement:offgrid

EBM Mentor

EBM Mentor is a Retrieval-Augmented Generation assistant for German EBM billing research. It helps physicians, coders, and practice staff search and understand EBM code descriptions, points, exclusions, notes, and eligibility details.

Read more about the project and its development in the blog post: Medical AI: Building an EBM Assistant.

The system is RAG-only:

• CohereLabs/tiny-aya-water is used only for answer generation.
• All EBM knowledge comes from retrieval over locally indexed EBM XML data.
• If the answer is not in the retrieved context, the app must say: Diese Information ist nicht in den bereitgestellten EBM-Daten enthalten.

Architecture

flowchart LR
    A[Official EBM XML] --> B[src/parser.py]
    B --> C[Structured records]
    C --> D[src/chunking.py]
    D --> E[Searchable documents]
    E --> F[src/embeddings.py]
    F --> G[FAISS index]
    G --> H[src/retriever.py]
    H --> I[src/prompts.py]
    I --> J[src/model.py]
    J --> K[Gradio app]

Features

• Interaktiver Chat: Fragen zur EBM in natürlicher Sprache stellen.
• Quellennachweise: Jede Antwort enthält die gefundenen EBM-Ziffern als Referenz.
• EBM Explorer: Gezielte Suche nach Codes, Titeln und Kapiteln in tabellarischer Form.
• Automatische Datenbeschaffung: Lädt beim ersten Start optional den aktuellen KBV-Datensatz herunter.
• Offline-Support: Unterstützung für den Betrieb ohne Internetverbindung (lokaler Cache).

Repository Layout

ebm-rag-trainer/
├── app.py
├── requirements.txt
├── README.md
├── Dockerfile
├── data/
│   └── ebm.xml
├── src/
│   ├── parser.py
│   ├── chunking.py
│   ├── embeddings.py
│   ├── vector_store.py
│   ├── retriever.py
│   ├── prompts.py
│   ├── rag_pipeline.py
│   └── model.py
├── scripts/
│   ├── build_database.py
│   └── ingest_ebm.py
├── tests/
└── .github/

Setup

1. Umgebung erstellen

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

Linux / macOS:

source .venv/bin/activate

Windows:

.venv\Scripts\activate

2. Install dependencies

pip install -r requirements.txt

3. Add or download the official EBM XML

Place the official XML file at:

data/ebm.xml

Or download the full KBV EBM source and extract the XML automatically:

python scripts/download_full_ebm.py

This will write the extracted XML to data/ebm.xml and keep the archive in data/SDEBM_V1.61.zip.

Die Daten stammen vom offiziellen KBV-Update unter https://update.kbv.de/ita-update/Stammdateien/SDEBM/ und werden hier lokal verarbeitet. Die App liest die XML-Datei ein, wandelt sie in strukturierte Datensätze um und erstellt daraus einen lokalen FAISS-Vektorstore. Anschließend nutzt die Anwendung diese lokal gespeicherten EBM-Daten für die Suche und Retrieval-basierte Antwortgenerierung. Weiterführende Informationen zum EBM finden Sie unter https://ebm.kbv.de/.

Hinweis: Diese Funktion ist experimentell und es besteht keine Gewährleistung für Vollständigkeit oder Richtigkeit der Ausgaben. Die Anwendung ersetzt keine offizielle Abrechnungsauskunft.

The repository includes a tiny demo XML so the codebase is runnable out of the box, but production use should replace it with the official current EBM source.

4. Build the local database

python scripts/ingest_ebm.py --xml data/ebm.xml --output data/processed
python scripts/build_database.py --xml data/ebm.xml --store data/vector_store

5. Run the app

python app.py

Hugging Face Spaces Deployment

1. Create a new Hugging Face Space.
2. Choose Gradio as the SDK.
3. Upload this repository.
4. Ensure data/ebm.xml is included or mounted in the Space.
5. Let the Space build the local FAISS index on first launch or prebuild it with the scripts above.

Space Notes

• SDK: gradio
• Hardware: CPU Basic / Zero
• No external database
• No paid APIs
• Local FAISS index and local metadata files only

Sample Questions

• Was bedeutet EBM-Code 01100?
• Welche Punkte hat die Leistung?
• Gibt es Ausschlüsse für diesen Code?
• Welche Fachgruppen sind berechtigt?
• Welche Hinweise stehen in den Anmerkungen?

Testing

Run the local test suite:

pytest

The tests cover:

• XML parsing
• document chunking
• retrieval

Safety and Scope

This project is designed as a research assistant, not a legal authority. Always verify billing decisions against the official EBM source material and current practice guidance.