# harmonizer_template

Starter kit for the **pivot harmonizer pattern**, MIMathon Porto 2026 by
team LESL (Lea, Eliott, Sattisvar, Louis · Kereval, Dolfin, Askem).

Use this when you start a new harmonization project on a new domain. It
gives you the file layout, the portable helpers, and skeletons for the
three things you write per project: the canonical model, one adapter
per source dataset, one writer per output format.

The skill that describes the full method:
**[SKILL.md](https://askem.eu/mimathon/SKILL.md)** ·
**[sl-method.html](https://askem.eu/mimathon/sl-method.html)**.

Live reference implementations:
**[UC1 trees](https://askem.eu/mimathon/sl-uc1.html)** ·
**[UC2 POIs](https://askem.eu/mimathon/sl-uc2.html)** ·
**[UC4 traffic](https://askem.eu/mimathon/sl-uc4.html)**.

## Quick start

1.  Copy `harmonizer_template/` to `harmonize_<your_domain>/`.
    ```bash
    cp -R harmonizer_template harmonize_books
    cd harmonize_books
    grep -rn "TODO" .   # all the spots you need to customise
    ```

2.  Write your `<domain>.dolfin` file next to the package (canonical model).

3.  Mirror that model in `model.py` as `@dataclass`es.

4.  Write your first adapter from `adapters/_template.py`:
    ```bash
    cp adapters/_template.py adapters/<your_source>.py
    # implement read(path) -> Iterator[Entity]
    ```

5.  Customise `jsonld.py` `CONTEXT` to align with the standards you target
    (schema.org, Smart Data Models, INSPIRE, ...).

6.  Add other writers as needed (`datex2.py`, `csv_out.py`, ...).

7.  Run:
    ```bash
    python -m harmonize_books \
        --adapter <your_source> \
        --input data.csv \
        --output out/entities.jsonld \
        --geojson out/entities.geojson \
        --base-id "http://your-ns/entities/"
    ```

## What you do NOT customise

- `transforms.py`: ships portable helpers (`clean_text`, `extract_count`,
  `match_keywords`, `Registry`). Copy across projects unchanged.
- `__main__.py` CLI plumbing: dynamic adapter loading, optional writer
  flags. Only change it if you add a new writer flag.

## What you DO customise

- `<domain>.dolfin`: the canonical model.
- `model.py`: dataclasses mirroring the Dolfin concepts.
- `jsonld.py` `CONTEXT`: standard-specific term mappings.
- `adapters/<source>.py`: parsing logic per source dataset.
- Optional: additional writers, external resolvers (GBIF-like cached
  lookups), `category_map.json` for controlled vocabularies.

## License

Same as the reference implementations: open source, reuse encouraged.
