aditzak-cli

Basque verb conjugation lookup, full-paradigm scraper, and UD-native feature projection for the aditzak.eus public JSON API.

aditzak-cli does three things:

1. CLI lookup — give it a verb + mood + tense + argument structure + person(s), and it returns the finite verb form. Exactly like the website, including an interactive mode with dependent dropdowns.
2. Full-paradigm scraper — downloads every conjugated form across all 12 synthetic verbs and the entire agreement paradigm (Mood × Tense × Argument-structure × Person) into a single data/paradigm.json dataset, suitable for downstream use (e.g. generating synthetic GEC training data).
3. UD feature projection (v3) — maps every conjugation to Universal Dependencies verbal features (Mood, Aspect, Person[abs/erg/dat], Number[…], VerbForm) with CoNLL-U serialization, validated against UD_Basque-BDT. See docs/v3-design.md.

UD-native output (v3)

# Show UD UPOS + feats for a conjugation:
aditzak conjugate -v egon --mood indikatiboa --tense orain \
    --type nor-nork --nork nik --nor hura --ud
#   Forma  : …
#   UPOS   : VERB
#   Feats  : Aspect=Imp|Mood=Ind|Number[abs]=Sing|Number[erg]=Sing|Person[abs]=3|Person[erg]=1|VerbForm=Fin

# CoNLL-U output:
aditzak conjugate -v izan --mood indikatiboa --tense orain \
    --type nor-nork --nork nik --nor hura --conllu
#   1	dut	Aditz laguntzailea	AUX	_	Aspect=Imp|Mood=Ind|...	_	_	_	_

# Reverse lookup with UD feats:
aditzak search dut --ud

Key mappings (validated against UD_Basque-BDT): Ahalera→Pot (not Cnd — the conditional is Baldintza→Cnd); Aldia→Aspect (Basque has no Tense feature); Nork/Nori/Nor → layered Person[erg/dat/abs]+Number[…]; the Aditz laguntzailea auxiliary → UPOS=AUX. Soft-spots documented in docs/v3-design.md.

Works offline by default

The full paradigm is bundled in the repo (data/paradigm.json, 2,765 forms). conjugate, list, and search run entirely offline — no network needed. Use --online on conjugate or list to query the live aditzak.eus API instead (e.g. to check for updates).

Command	Default	--online
conjugate	offline	live API
list	offline	live API
search	offline	—
scrape	live API	—

Data source & credit

All conjugation data comes from aditzak.eus, a project by Garikoitz Knörren. This tool only re-exposes that data through a CLI and scrapes it for offline use. The conjugated forms themselves are linguistic facts (Standard Basque / batua).

⚠️ Before redistributing the scraped dataset, check with the aditzak.eus author. The code in this repository is MIT-licensed; the data is sourced from aditzak.eus and should be credited accordingly.

Install

Requires Python ≥ 3.12 and uv.

cd aditzak-cli
uv sync

Then run commands via uv run aditzak … (or activate the venv and use aditzak … directly).

Usage

Lookup a verb form

Interactive mode (offline, mimics the website's filtered dropdowns — recommended for exploration):

uv run aditzak conjugate -i
# or simply:
uv run aditzak conjugate

Direct lookup (offline, for scripting):

# Intransitive, present: "ni dago" → dago
uv run aditzak conjugate -v egon --mood indikatiboa --tense orain \
                         --type nor --nor ni

# Transitive (Nor-Nork), present: "nik dut" → dut
uv run aditzak conjugate -v izan --mood indikatiboa --tense orain \
                         --type nor-nork --nork nik --nor hura

Online mode (query the live API):

uv run aditzak conjugate --online -v egon --mood indikatiboa --tense orain \
                         --type nor --nor ni

Verb aliases: izan, edun, ukzan, aux all resolve to Aditz laguntzailea (the izan/edun auxiliary). All names match case-insensitively and accept partial matches.

List valid values

uv run aditzak list verbs     # the 12 conjugatable verbs
uv run aditzak list moods     # Indikatiboa, Ahalera, Subjuntiboa, Agintera
uv run aditzak list tenses    # Orain, Lehen, Baldintza, Ondorioa, Hipotetikoa
uv run aditzak list types     # Nor, Nor-Nori, Nor-Nork, Nor-Nori-Nork
uv run aditzak list persons   # Nork / Nori / Nor persons

Scrape the full paradigm

uv run aditzak scrape            # → data/paradigm.json
uv run aditzak scrape -w 8       # more concurrent workers
uv run aditzak scrape -o out.json

Collects all ~2,800 combinations across the 12 verbs (the auxiliary alone covers 1,516 forms spanning the full Nor / Nor-Nori / Nor-Nork / Nor-Nori-Nork paradigm). Takes under a minute with 6 workers.

Reverse lookup (search)

Find every combination that produces a given form (offline):

uv run aditzak search dut

Dataset format (data/paradigm.json)

{
  "source": "https://aditzak.eus",
  "credit": "Garikoitz Knörren (aditzak.eus) — …",
  "verb_count": 12,
  "combination_count": 2794,
  "form_count": 2765,
  "verbs": [
    {
      "id": 35, "name": "Aditz laguntzailea", "slug": "...",
      "is_default": true,
      "combination_count": 1516,
      "combinations_index": [ { "modua_id": 1, "aldia_id": 5, ... } ]
    }
  ],
  "groups":       [ { "id": 1, "name": "Modua", "slug": "modua", ... } ],
  "options":      [ { "id": 14, "group_id": 4, "name": "Nik", ... } ],
  "conjugations": [
    {
      "aditz_id": 35, "aditz_name": "Aditz laguntzailea",
      "modua_id": 1, "modua": "Indikatiboa",
      "aldia_id": 5, "aldia": "Orain",
      "mota_id": 11, "mota": "Nor-Nork",
      "nork_id": 14, "nork": "Nik",
      "nori_id": null, "nori": null,
      "nor_id": 30, "nor": "Hura",
      "forma": "dut",
      "forma_hika": "diat / dinat"
    }
  ]
}

Each conjugation row is denormalized with human-readable names (and kept IDs for joining), so it can be consumed directly without a separate lookup table. forma is the Standard Basque (batua) form; forma_hika is the informal/dialectal variant (where present) — useful as a source of "incorrect-in-formal-writing" forms.

Each verb record includes combinations_index — the full list of valid (mood, tense, type, person) combinations — which the CLI uses to drive the offline interactive dropdowns exactly like the website.

Architecture

aditzak-cli/
├── pyproject.toml          # uv-managed, hatchling build, `aditzak` console script
├── README.md
├── aditzak/
│   ├── __init__.py         # exports: AditzakClient, OfflineStore, models
│   ├── models.py           # dataclasses: Group, Option, Verb, Conjugation
│   ├── client.py           # AditzakClient — requests-based live API client
│   ├── store.py            # OfflineStore — reads paradigm.json, same interface
│   ├── scraper.py          # full-paradigm scraper (threaded) → data/paradigm.json
│   └── cli.py              # argparse CLI: conjugate / list / scrape / search
├── data/
│   └── paradigm.json       # bundled dataset (offline by default)
└── tests/
    └── test_client.py      # 12 tests: 6 online + 6 offline

OfflineStore and AditzakClient implement the same interface (get_verbs, get_groups, get_combination), so the CLI switches between them transparently. The --online flag on conjugate/list selects the live client; otherwise the local dataset is used.

API reference (aditzak.eus /public)

Method	Endpoint	Returns
GET	/public/aditzak	list of conjugatable verbs
GET	/public/groups	conjugation axes (groups) + options
POST	/public/combination	{ forma, forma_hika } for a combination

POST /public/combination body:

{ "aditz_id": 35, "modua_id": 1, "aldia_id": 5, "mota_id": 11,
  "nork_id": 14, "nori_id": null, "nor_id": 30 }

License

Code: MIT. Data: sourced from aditzak.eus (Garikoitz Knörren) — credit accordingly and verify redistribution terms with the author.