Plugin Development Guide

CKS supports external constraint plugins via the standard Python entry_points mechanism. This allows domain‑specific constraints to be distributed as independent packages and loaded automatically when cks is imported.

Quick Start

Create a new Python package (e.g., cks-plugin-example).
Define one or more constraints by subclassing Constraint from cks.constraints.base.
Create a factory function that returns a list of your constraint instances.
Register the factory in pyproject.toml under the group cks.constraints.

Example

myplugin.py

from cks.constraints.base import Constraint

class MyCustomConstraint(Constraint):
    identity = "MY-CUSTOM-CONSTRAINT"
    description = "A custom domain constraint."
    stage = "STRUCTURAL"  # or "SEMANTIC"

    def evaluate(self, structure):
        # your validation logic here
        return []

factory.py

from .myplugin import MyCustomConstraint

def load():
    return [MyCustomConstraint()]

pyproject.toml

[project.entry-points."cks.constraints"]
myplugin = "cks_plugin_example.factory:load"

Once the plugin package is installed (pip install .), the constraint appears automatically in the global registry:

cks plugin list

Using built‑in optional constraints

CKS ships with OPTIONAL_CONSTRAINTS (e.g. EmbeddingProjectionIntegrityConstraint). They are not registered by default. To enable them process‑wide:

from cks.constraints.builtin import OPTIONAL_CONSTRAINTS
from cks.constraints.registry import registry

for constraint in OPTIONAL_CONSTRAINTS:
    registry.register(constraint)

Or scoped to one ReferenceValidator:

from cks.constraints.registry import ConstraintRegistry
from cks.validator import ReferenceValidator

reg = ConstraintRegistry()
reg.register(MyConstraint())
for constraint in OPTIONAL_CONSTRAINTS:
    reg.register(constraint)
validator = ReferenceValidator(registry=reg)

Entry-Point Group

Group: cks.constraints
Expected return type: Iterable[Constraint]

Each entry-point must reference a zero‑argument callable that returns an iterable of Constraint instances. Invalid objects or exceptions are reported to stderr without halting the import.

Testing Plugins

Plugin constraints are executed during the standard validation pipeline. You can verify them with:

cks validate my_structure.json

Or programmatically:

import cks
result = cks.validate(structure)

Distribution

Publish your plugin as a standard PyPI package. Users only need to install it (pip install cks-plugin-example) – CKS discovers the constraints automatically on the next import.