Metadata-Version: 2.4
Name: zimankit
Version: 0.3.0
Summary: Kurdish (Central / Sorani ckb and Northern / Kurmanji kmr) NLP skills: orthography, IPA, morphology, verbs, ergativity, language ID and wordlist building
Author: Dolan H.
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://0xdolan.github.io/zimankit/
Project-URL: Documentation, https://0xdolan.github.io/zimankit/guide.html
Project-URL: Source, https://github.com/0xdolan/zimankit
Project-URL: Changelog, https://github.com/0xdolan/zimankit/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/0xdolan/zimankit/issues
Keywords: kurdish,sorani,kurmanji,nlp,ipa,morphology,transliteration,ergativity
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: data
Requires-Dist: mdict-utils>=1.3; extra == "data"
Requires-Dist: libzim>=3.4; extra == "data"
Provides-Extra: kaggle
Requires-Dist: pyarrow>=15; extra == "kaggle"
Requires-Dist: kaggle>=1.6; extra == "kaggle"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/0xdolan/zimankit/main/assets/brand/logo/png/zimankit-logo-256.png" width="160" alt="zimankit logo: the deq tree-of-life figure with the Kurdish sun at its heart">
</p>

<h1 align="center">zimankit · زمانکیت</h1>

<p align="center">
  <a href="https://0xdolan.github.io/zimankit/"><strong>Website</strong></a> ·
  <a href="https://0xdolan.github.io/zimankit/playground.html"><strong>Try it in your browser</strong></a> ·
  <a href="https://0xdolan.github.io/zimankit/guide.html">Guide</a> ·
  <a href="https://github.com/0xdolan/zimankit/releases/latest">Download</a> ·
  <a href="https://github.com/0xdolan/zimankit/blob/main/CHANGELOG.md">Changelog</a>
</p>

<p align="center">
  <a href="https://github.com/0xdolan/zimankit/actions/workflows/ci.yml"><img src="https://github.com/0xdolan/zimankit/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://github.com/0xdolan/zimankit/releases/latest"><img src="https://img.shields.io/github/v/release/0xdolan/zimankit?color=FEBD11&amp;labelColor=22332A" alt="latest release"></a>
  <a href="https://pypi.org/project/zimankit/"><img src="https://img.shields.io/pypi/v/zimankit?color=FEBD11&amp;labelColor=22332A" alt="PyPI version"></a>
  <img src="https://img.shields.io/badge/python-3.11%2B-22332A" alt="Python 3.11+">
  <a href="https://github.com/0xdolan/zimankit/blob/main/LICENSE"><img src="https://img.shields.io/badge/licence-GPL--3.0--or--later-278E43" alt="GPL-3.0-or-later"></a>
</p>

**Kurdish language skills and wordlist builder** for Central Kurdish (Sorani, `ckb`, Arabic script) and Northern Kurdish (Kurmanji, `kmr`, Hawar Latin script).

*ziman* means "language" in both varieties.

| | |
|---|---|
| Skills | orthography · IPA / G2P · syllabification · transliteration · morphology · verb paradigms · split-ergativity checking · sentence structure · language identification |
| Data readers | `.mdx` dictionaries (in-process via `mdict-utils`) · `.zim` wiki dumps (`libzim`) · plain-text corpora |
| Kaggle dataset | `output/kaggle/` — one row per word, 59 flat columns (features, IPA, syllables, both scripts, definitions, frequency) as CSV · Parquet · SQLite + data card |
| Outputs | `clean_wordlist_ckb.csv` (329 190 forms) · `clean_wordlist_kmr.csv` (506 407 forms) · lemma tables · variant maps · grammar-rule JSON |
| Quality | 120+ tests incl. the ground-truth matrix and the tutorial drift check · IPA agrees 96.5 % (ckb) / 97.8 % (kmr) with reference transcriptions in the data |
| Dependencies | standard library only for the skills; `mdict-utils`, `libzim` for data ingestion |

<p align="center"><a href="https://0xdolan.github.io/zimankit/playground.html"><img src="https://raw.githubusercontent.com/0xdolan/zimankit/main/assets/brand/screenshots/website-sentence-word.png" width="820" alt="the zimankit playground: a Kurmanji sentence drawn as coloured arrows between its words, with one word explained"></a></p>

## Install

zimankit needs Python 3.11 or newer and has no dependencies.

```bash
pip install zimankit
```

On Debian, Ubuntu or Kali, the [latest release](https://github.com/0xdolan/zimankit/releases/latest) also has a package:

```bash
sudo apt install ./python3-zimankit_*_all.deb
```

The release also has the full source as `.zip` and `.tar.gz`, and `SHA256SUMS`. Optional extras: `pip install "zimankit[data]"` reads `.mdx` and `.zim` files, and `pip install "zimankit[kaggle]"` adds the Parquet export. The [guide](https://0xdolan.github.io/zimankit/guide.html) covers every command and the Python API.

## Quick start

```bash
uv venv --python 3.13 .venv && uv pip install --python .venv/bin/python mdict-utils libzim pytest
source .venv/bin/activate

python -m zimankit analyze کتێبەکەم jinekê
python -m zimankit ipa پیاوەکە کتێبەکەم jinekê dîtin      # pjaːwækæ k(ɯ)teːbækæm ʒɪnɛkeː diːtɯn
python -m zimankit conjugate کردن
echo "Min tu dîtim." | python -m zimankit ergativity       # agreement_ok: false
python -m zimankit parse "Min pirtûka nû li dibistanê xwend."   # head and relation of each word
python -m zimankit lid "Ma yew roje şima ra vat ke ziwanê ma zaf rind o"   # zza
python -m pytest -q
```

Build the wordlists from your own data:

```bash
cp config/sources.example.toml config/sources.local.toml   # set the paths (file is git-ignored)
./scripts/build_wordlists.sh

# Kaggle-ready dataset: flat columns, CSV + Parquet + SQLite + data card -> output/kaggle/
uv pip install --python .venv/bin/python pyarrow
python run_pipeline.py --stages export
```

## Documentation

Start at the **[documentation index](https://github.com/0xdolan/zimankit/blob/main/docs/00-index.md)**.

**Learning Kurdish?** The **[tutorials](https://github.com/0xdolan/zimankit/blob/main/docs/tutorials/README.md)** are two complete courses, [Sorani](https://github.com/0xdolan/zimankit/blob/main/docs/tutorials/ckb/README.md) and [Kurmanji](https://github.com/0xdolan/zimankit/blob/main/docs/tutorials/kmr/README.md), with 23 lessons each from the alphabet to ergativity, tagged 🟢 beginner / 🟡 intermediate / 🔴 advanced. Every conjugation, declension, IPA and transliteration table in them is generated by zimankit (`python scripts/gen_tutorials.py`), and a test fails if a lesson drifts from the code.

| part | chapters |
|---|---|
| Foundations | [1 Overview](https://github.com/0xdolan/zimankit/blob/main/docs/01-overview.md) · [2 Getting started](https://github.com/0xdolan/zimankit/blob/main/docs/02-getting-started.md) · [3 Data ingestion](https://github.com/0xdolan/zimankit/blob/main/docs/03-data-ingestion.md) · [4 Unicode](https://github.com/0xdolan/zimankit/blob/main/docs/04-unicode-normalization.md) · [5 Language ID](https://github.com/0xdolan/zimankit/blob/main/docs/05-language-identification.md) · [6 Tokenization](https://github.com/0xdolan/zimankit/blob/main/docs/06-tokenization.md) |
| Central Kurdish | [7 Orthography](https://github.com/0xdolan/zimankit/blob/main/docs/07-ckb-orthography.md) · [8 Phonology & IPA](https://github.com/0xdolan/zimankit/blob/main/docs/08-ckb-phonology-ipa.md) · [9 Morphology](https://github.com/0xdolan/zimankit/blob/main/docs/09-ckb-morphology.md) · [10 Verbs](https://github.com/0xdolan/zimankit/blob/main/docs/10-ckb-verbs.md) |
| Northern Kurdish | [11 Orthography](https://github.com/0xdolan/zimankit/blob/main/docs/11-kmr-orthography.md) · [12 Phonology & IPA](https://github.com/0xdolan/zimankit/blob/main/docs/12-kmr-phonology-ipa.md) · [13 Morphology](https://github.com/0xdolan/zimankit/blob/main/docs/13-kmr-morphology.md) · [14 Verbs & ergativity](https://github.com/0xdolan/zimankit/blob/main/docs/14-kmr-verbs-ergativity.md) |
| Cross-cutting | [15 Transliteration](https://github.com/0xdolan/zimankit/blob/main/docs/15-transliteration.md) · [16 Wordlist pipeline](https://github.com/0xdolan/zimankit/blob/main/docs/16-lexicon-pipeline.md) · [17 Regex cookbook](https://github.com/0xdolan/zimankit/blob/main/docs/17-regex-cookbook.md) · [18 Multi-language examples](https://github.com/0xdolan/zimankit/blob/main/docs/18-multi-language-examples.md) · [19 Testing](https://github.com/0xdolan/zimankit/blob/main/docs/19-testing.md) |
| Reference | [20 Glossary](https://github.com/0xdolan/zimankit/blob/main/docs/20-glossary.md) · [21 References](https://github.com/0xdolan/zimankit/blob/main/docs/21-references.md) |
| Sentences | [22 Sentence structure](https://github.com/0xdolan/zimankit/blob/main/docs/22-sentence-structure.md) |
| Written standard | [23 The Central Kurdish written standard](https://github.com/0xdolan/zimankit/blob/main/docs/23-ckb-written-standard.md) |

Also: [agent skills](https://github.com/0xdolan/zimankit/blob/main/skills/README.md) · [cross-language examples](https://github.com/0xdolan/zimankit/blob/main/examples/README.md) · [engineering brief](https://github.com/0xdolan/zimankit/blob/main/PROMPT.md) · [contributing and releases](https://github.com/0xdolan/zimankit/blob/main/CONTRIBUTING.md) · [changelog](https://github.com/0xdolan/zimankit/blob/main/CHANGELOG.md) · [website source](https://github.com/0xdolan/zimankit/tree/main/site/).

## Layout

```
zimankit/
├── run_pipeline.py          lexicon → dictionaries → corpus → build → rules → export
├── config/                  pipeline.toml · sources.example.toml · sources.local.toml (ignored)
├── zimankit/
│   ├── tools/               mdx_extractor.py · zim_cleaner.py
│   ├── shared_utils/        normalizer · tokenizer · lid · phonology_core · text_helpers · unicode_tables · schema
│   ├── skills_ckb/          orthography · phonology_ipa · morphology · verbs · config.toml
│   ├── skills_kmr/          orthography · phonology_ipa · morphology · verbs · syntax · translit · config.toml
│   ├── lexicon/             wiki_lexicon · corpus · harvest · builder · export
│   ├── data/                authored reference tables (core verbs, function words)
│   ├── dependency.py        sentence structure: head and relation of each word
│   ├── rules.py             grammar_rules_<lang>.json exporter
│   └── cli.py               python -m zimankit …
├── output/{ckb,kmr}/        generated wordlists and reports
├── output/kaggle/           flat Kaggle dataset (export stage)
├── docs/                    developer chapters · tutorials/{ckb,kmr} (generated tables)
├── assets/brand/           logo, icons, social, ads, print, screenshots (scripts/make_brand.py)
├── site/                   website source (scripts/build_site.sh → _site/, deployed from main)
├── .github/workflows/      CI · release (on vX.Y.Z tags) · website
├── examples/  skills/  scripts/  tests/
```

## Output schema

`grapheme, lemma, pos, ipa, morph_meta, translit, frequency, sources, confidence` — see [chapter 16](https://github.com/0xdolan/zimankit/blob/main/docs/16-lexicon-pipeline.md#csv-schema).

```
کتێبەکەم,کتێب,NOUN,k(ɯ)teːbækæm,"{""definite"":""def"",""enclitic"":""1sg"",""number"":""sg"",""seg"":""کتێب+ەکە+م""}",kitêbekem,137,"encyclopedia,news,web",0.31
jinekê,jin,NOUN,ʒɪnɛkeː,"{""case"":""obl"",""definite"":""ind"",""gender"":""f"",""number"":""sg"",""seg"":""jin+ekê""}",ژنەکێ,530,"encyclopedia,lexicon-form,news",0.754
```

## The logo

<p align="center"><img src="https://raw.githubusercontent.com/0xdolan/zimankit/main/assets/brand/story/zimankit-logo-construction.png" width="720" alt="deq figure + the sun of the flag of Kurdistan = the zimankit logo"></p>

The logo is a sign of **deq**, the traditional hand-poked tattoo of Kurdish women: the figure read as the **tree of life**, a symbol of fertility, growth and life force. Its circle stands for the cycle of life, its line and V shapes for a sprout or a tree, and its dots for protection against the evil eye. At its heart shines **Roj**, the 21-rayed sun of the flag of Kurdistan; *roj* / *ڕۆژ* means both "sun" and "day". Together they stand for Kurdish (*ziman*, "language") as a living language.

The full story, with the history and meaning of deq, sources, colours, usage, and every logo, icon, social, ad and print file, is in **[assets/brand/](https://github.com/0xdolan/zimankit/blob/main/assets/brand/README.md)**.

## Licence

The code is licensed under the [GNU General Public License v3.0 or later](https://github.com/0xdolan/zimankit/blob/main/LICENSE).

Generated data is licensed separately. The large generated files under `output/` are git-ignored (regenerate them with the pipeline; 300-row samples are kept). Wordlists derived from openly licensed sources may carry share-alike obligations when redistributed — check the licences of the data you configure. The published Kaggle dataset and the sample CSVs in `output/` are CC BY-SA 4.0.
