conlangkit

A Python toolkit for building constructed languages. It provides a glossary format and search engine, base-form reduction for English, part-of-speech tagging integration, an orthography transliterator, and phoneme/syllable primitives — plus a clk command-line tool for working with a language on disk.

Experimental: the phonotactic features (syllable.candidates, Lang.syllables) are partially implemented. Lang.syllables currently raises NotImplementedError; call syllable.candidates() directly if you need phonotactic syllable generation.

Name note: the import package is conlangkit. It is unrelated to the langkit project on PyPI (WhyLabs' LLM-monitoring library).

Install

pip install conlangkit      # or: uv add conlangkit

This installs the library and the clk command-line tool.

Quick example

from conlangkit.glossary import Glossary

g = Glossary.load("path/to/glossary.md")
print(f"{g.lemma_count} entries loaded")

# Find entries whose definition contains "fruit"
for entry in g.find("d:*fruit", max_hits=10):
    print(entry.lemma, "—", entry.defn)

# Fuzzy search across lemma and definition
hits = g.find("apple", try_fuzzy=True)

# Searching prose? Fold case — lemma matching stays byte-exact by default
hits = g.find("d:Fruit", ignore_case=True)

Glossary files are Markdown tables with four pipe-delimited columns — lemma | tags | definition | notes — and may have arbitrary Markdown before and after the table. See ARCHITECTURE.md for the full format.

Command-line tool

clk <LANGDIR> repl      # interactive REPL over the language in <LANGDIR>
clk <LANGDIR>           # defaults to the repl
clk help                # general help

<LANGDIR> is a directory containing a language (cfg.json + glossary.md).

Public API

The supported surface (imported directly from its submodule):

The package ships a py.typed marker, so type checkers see its annotations.

Developer quickstart

Prerequisite: uv.

git clone https://github.com/dhh1128/conlangkit
cd conlangkit
uv sync                 # create .venv from uv.lock (incl. dev tools)

# One-time: fetch the NLTK corpora the tests use
uv run python -c "import nltk; [nltk.download(p, quiet=True) for p in \
  ['punkt','punkt_tab','averaged_perceptron_tagger','averaged_perceptron_tagger_eng','wordnet']]"

uv run pytest           # tests + coverage
uv run ruff check .     # lint
uv run mypy             # type-check
uv run pre-commit install   # enable pre-commit hooks (once)

See CONTRIBUTING.md for the contribution workflow and AGENTS.md for the conventions AI agents and developers follow here.

License

Apache-2.0.