conlang

A partial-spec constructed-language generator.

You describe only what you care about — phonology, syllable shapes, a handful of words — and the generator samples the rest from typologically-plausible defaults. Same spec plus same seed always produces byte-identical output, and sampled entries can be locked so they survive re-sampling.

spec (YAML) ──▶ generate ──▶ model (canonical JSON) ──▶ render ──▶ dictionary + grammar sketch
                                   │
                                   ├── lint   (machine-checkable invariants)
                                   └── bench  (plausibility scorecard vs. Kah)

The model JSON is the single source of truth; the dictionary, grammar sketch, and every other view are rendered from it.

Install

pip install conlanggen

The distribution is conlanggen, but the import package and the command are both conlang — import conlang, conlang generate.

Quickstart

# Generate from the example spec and render a Markdown dictionary.
conlang generate --spec spec\example.yaml --render

# Happy with it? Freeze it into an explicit spec so the values stick.
conlang accept --model out\veshtari.json

Output lands in out/: a model JSON and a rendered .md. Then:

conlang lint   --model out\veshtari.json
conlang render --model out\veshtari.json --out out\veshtari.md

Documentation

• Getting started — install, first language, freeze it.
• Spec reference — every spec/*.yaml key.
• Feature guide — phonotactics, scripts, data packs, the benchmark, evolve, and syntax.
• The translation pipeline — translate the fixed story end to end.
• Migrating to 2.0 — upgrade 1.x models and Specs.
• Releasing — the Codeberg CI setup and how to cut a release.
• Cross-pollination — how conlang and the sibling muna project can share (the lexicon, the story, the grammar).
• Domain glossary and architecture decisions.
• Stability and the changelog.

Guarantees and lint rules

Reproducibility is the one hard guarantee: spec + seed ⇒ identical bytes. Everything else is reported by lint as errors or warnings, and a broken language is still generated (conlangers want to explore broken states).

Every rule above has a test in tests/test_lint.py, tests/test_lint_invariants.py, or tests/test_morphology.py.

Stability

Starting with 2.0.0, the model schema, the conlang command line, and the Spec format are stable; within 2.x we make only additive, backwards-compatible changes. 1.x files upgrade with conlang migrate. See STABILITY.md for the promise and how deprecation works.

Development

.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe -m ruff check .
.\.venv\Scripts\python.exe -m mypy src

The package layout:

src/conlang/
  model/        canonical pydantic schema (the source of truth)
  sampling/     deterministic RNG, inventory presets, concepts, defaults
  phonology/    tokenization, syllabification, legality checks
  lexicon/      seeded root generation, stable per-item seeding
  morphology/   affixes, inflection classes, and word-form assembly
  soundchange/  ordered sound changes; derive a daughter language
  syntax/       word order, alignment, clause linearisation, place structure
  script/       writing systems (glyphs)
  render/       Markdown dictionary + grammar sketch
  lint/         machine-checkable invariants
  bench/        Kah adapter + scorecard
  cli.py        thin command-line view over the library

Roadmap

Shipped so far (1.0 froze the core; 1.1–1.16 add tiers):

• Phonology — inventory, phonotactics, seeded word generation.
• IPA inventories — declare the inventory phonemic (ipa: true) and derive a romanised orthography alongside the phonemic forms.
• Morphology — affix breadth, inflection classes, and stacking.
• Diachrony — conlang evolve: ordered sound changes (with environments) derive a daughter language, recorded in lineage.
• Syntax — sampled word order and alignment, case marking with subject agreement, the predication tier, clause sequencing, and aspect.
• Translation pipeline — conlang new / grow / translate / validate-translation / extras, including a grammar-match port from a sibling.
• Writing systems — conlang script: a sampled script (alphabet / syllabary / impure abjad / featural) rendered as deterministic SVG glyphs.
• Data packs — optional, pinned PHOIBLE and WALS ground sampling (conlang data fetch), with a graceful fallback to the built-in presets.
• Feature-driven phonology — natural classes and feature-based sound-change rules.
• Place structure — an ordered list of semantic roles per predicate; role-labelled clauses.
• Semantics — negation, quantifiers, coordination, and topic/focus markers.
• Complex clauses — relative, complement, and reported clauses.
• Adverbial clauses — causal (because), temporal (when), and conditional (if) adjuncts, positioned by head direction.
• Numerals — a closed digit class that composes cardinals in base 10 (ordered by word order) and derives ordinals with an ORD affix.
• Infinitives & quotation — non-finite complements with subject control (an inf marker before a bare verb) and a quot particle for direct, verbatim quotation.
• Initial mutation — a Mutation table on the model plus triggers, so a language can lenite/eclipse a word's initial segment by grammatical context (Celtic); a ## Mutation view and a mutation.table lint rule.
• Meaning — a compositional meaning layer: a typed lambda denotation per lexeme (derived from its place structure) and composed truth conditions (predication, negation, generalized quantifiers, relatives, complements, tense), rendered in a ## Meaning view.
• Model & entailment — a spec-declared semantic model (a domain of individuals plus predicate extensions) that evaluates clauses to truth values and checks entailment by model-checking the declared model; a ## Model view.
• Bounded validity — conlang valid searches all non-empty finite models up to a domain-size bound, reporting validity, a countermodel, or an exhausted-budget unknown.
• Polysemy — a lexeme can carry added senses ({gloss, field, relation, rationale}, e.g. crane the bird → the lifting machine), authored on a lexicon entry, rendered in a ## Polysemy section, and round-tripped by accept; dictionary-only (the meaning layer still reads the primary gloss).
• Lexicon converter — conlang convert-lexicon: a Muna-style lexicon TSV → a spec lexicon (the conlang ↔ muna cross-pollination seam).
• Optional alignment — syntax.alignment: none marks no case (for a no-case language).
• Modifier order — syntax.modifier_order (prenominal/postnominal) decouples the noun phrase's modifier side from word order (so a language can be SOV and postnominal).
• Pronouns — a closed pron class (the personal set 1SG–3PL plus who/what).
• Paradigms view — conlang render emits a ## Paradigms section (agreement, class prefixes, pronouns, numerals) as Markdown tables.
• Function inventory — a dem class, 25 adposition senses, until, any, and who/what/ where/how question words.
• Subordinator edge — syntax.subordinator_edge (initial/final) lets an OV language lead its subordinators.
• Oblique relative — a relative clause whose gap is an adpositional phrase (the adposition stranded).
• Degree constructions — a deg class + DegreePhrase (comparative much … and …, equative same … and …).
• Aspect particles — a closed asp class (PROG/PRF), placed around the verb.

Planned: comparative work across related languages.

License

MIT (code). Kah dictionary and grammar content remains Kwesho's and is not part of this repository.