Skip to content
Kirak Docs

Adding a Module to Kirak

This page is for adding a built-in module to Kirak itself. To build a module in your own application, see Building Custom Modules; to add a provider to an existing module, see Adding a Provider.

Kirak describes each module once, in a spec. The catalog (kirak modules, kirak providers, kirak catalog), kirak env, kirak validate, the generated .env.example and the reference tables in these docs are all read from the specs and the JSON Schemas, so they need no edit. Tests fail when a spec disagrees with the code.

Files to change

Section titled “Files to change”
File Change
kirak/<module>/ The module code: class, router, register_module() call
kirak/catalog/specs/<module>.py A ModuleSpec: summary, pip extra and install check, kirak.json section name, operations (each gives before_/after_ hook events), other hook events, bundled models file, provider kinds, environment variables the module reads
kirak/catalog/specs/__init__.py Add the spec to MODULES
The module’s registry.py Only if it has providers: build the built-in table with builtin_table(provider_kind(...)), see Adding a Provider
kirak/schemas/manifest.schema.json The module’s kirak.json section; every key needs a description
kirak/core/manifest.py The section’s dataclass
kirak/validation/manifest.py Only if the section has rules beyond its shape; each new problem code goes in kirak/core/problem_codes.py
pyproject.toml The pip extra, and any data files under [tool.setuptools.package-data]
docs/modules/<module>.md What the module is for and how to use it. Settings and provider tables are includes of the generated files (below)
docs/reference/configuration.md The module’s section, including --8<-- "docs/reference/generated/<module>-settings.md" (and -providers.md)
README.md, docs/index.md, the Kirak docstring in kirak/kirak_instance.py The module’s one-line description
CHANGELOG.md An entry

Then regenerate the reference tables:

Terminal window
python scripts/gen_reference.py

Tests that catch a missed step

Section titled “Tests that catch a missed step”
  • tests/test_catalog/test_specs_match_code.py – every registered module has a spec; operations, hook model, bundled models file, manifest section and pip extras match the code.
  • tests/test_core/test_schema_files.py – every schema key has a description; each kirak.json section matches its dataclass.
  • tests/test_catalog/test_env.py – every environment variable Kirak reads is declared in a spec.
  • tests/test_catalog/test_generated_docs.py – the generated pages match the catalog, and every generated table is included by a page.
  • tests/test_validation/test_validate.py – every problem code is registered.
  • tests/test_core/test_package_data.py – every data file under kirak/ is in the built wheel.