Skip to content

API Reference

This document describes the public API exposed by the Canonical Knowledge Structure (CKS) Python reference implementation.

Applications should use the functions documented here instead of importing implementation modules directly.

The public API is defined by the Canonical Knowledge Interface (CKS-007).

Importing CKS

The recommended import style is:

from cks import (
    construct,
    parse,
    serialize,
    validate,
    validate_all,
    diagnose,
    inspect,
    compare,
    extract,
    project,
    evolve,
)

from cks.evolution import (
    AddObject,
    AddRelation,
    RemoveObject,
    RemoveRelation,
    compose,
)

All public operations are:

  • deterministic;
  • observationally pure;
  • implementation-independent.

Construction

construct()

Construct a canonical Knowledge Structure from an iterable of Knowledge Objects.

Signature

construct(
    objects: Iterable[KnowledgeObject],
) -> KnowledgeStructure

Example

structure = construct(
    [
        object1,
        object2,
        relation,
    ]
)

Serialization

parse()

Parse canonical JSON into a Knowledge Structure.

Signature

parse(
    source: str | dict,
) -> KnowledgeStructure

Parameters

Parameter Description
source Canonical JSON string or decoded JSON object

Example

structure = parse(json_text)

serialize()

Serialize a Knowledge Structure into canonical JSON.

Signature

serialize(
    structure: KnowledgeStructure,
) -> str

Example

json_text = serialize(structure)

The reference implementation guarantees canonical round-trip behaviour.

Validation

validate()

Execute the complete canonical validation pipeline.

Signature

validate(
    structure: KnowledgeStructure,
    *,
    min_severity: DiagnosticSeverity = DiagnosticSeverity.ERROR,
) -> ValidationResult

Validation Stages

  1. Structural Validation
  2. Semantic Validation
  3. Constraint Evaluation

Example

result = validate(structure)

print(result.is_valid)

validate_all()

Validate multiple Knowledge Structures and return individual results.

Signature

validate_all(
    structures: Iterable[KnowledgeStructure],
    *,
    min_severity: DiagnosticSeverity = DiagnosticSeverity.ERROR,
) -> list[ValidationResult]

Example

results = validate_all(
    [
        structure1,
        structure2,
    ],
    min_severity=DiagnosticSeverity.WARNING,
)

diagnose()

Return diagnostics without exposing the complete ValidationResult.

Signature

diagnose(
    structure: KnowledgeStructure,
) -> DiagnosticCollection

Example

diagnostics = diagnose(structure)

Inspection

inspect()

Return an implementation-independent summary of a Knowledge Structure.

Signature

inspect(
    structure: KnowledgeStructure,
) -> Mapping[str, object]

Example

summary = inspect(structure)

Typical summary information includes:

  • object count;
  • relation count;
  • structural metadata.

Comparison

compare()

Compare two Knowledge Structures.

Signature

compare(
    left: KnowledgeStructure,
    right: KnowledgeStructure,
) -> Mapping[str, object]

Example

comparison = compare(
    structure1,
    structure2,
)

The comparison is based on observable structure rather than implementation details.

Extraction

extract()

Extract a single Knowledge Object.

Signature

extract(
    structure: KnowledgeStructure,
    identity: str,
) -> KnowledgeObject | None

Example

obj = extract(
    structure,
    "definition-001",
)

Returns None when the requested object does not exist.

Projection

project()

Create a new Knowledge Structure containing only selected objects.

Signature

project(
    structure: KnowledgeStructure,
    identities: Iterable[str],
) -> KnowledgeStructure

Example

subset = project(
    structure,
    [
        "definition-001",
        "theorem-003",
    ],
)

Projection never modifies the original structure.

Evolution

evolve()

Apply a sequence of admissible structural operators (Genesis/Decay) to a Knowledge Structure.

Signature

evolve(
    structure: KnowledgeStructure,
    operators: Iterable[StructuralOperator],
) -> KnowledgeStructure

Operators

Operator Description
AddObject Introduce a new KnowledgeObject
AddRelation Introduce a new CanonicalRelation
RemoveObject Remove a KnowledgeObject (and related relations)
RemoveRelation Remove a CanonicalRelation

Example

from cks.evolution import AddObject, AddRelation, compose

ops = [
    AddObject(new_object),
    AddRelation(new_relation),
]

evolved = evolve(structure, ops)

All operators are observationally pure — the original structure is never modified.

Reference Engine

The public interface internally delegates every operation to the Reference Engine.

Applications normally do not need to instantiate the engine directly.

However, it remains available:

from cks import ReferenceEngine

engine = ReferenceEngine()

The engine provides the same canonical operations exposed by the module-level API.

Exceptions

SerializationError

Raised when canonical serialization cannot be parsed.

Example:

from cks import SerializationError

try:
    structure = parse(text)
except SerializationError:
    ...

ValidationResult

The validator returns an immutable ValidationResult.

Useful properties include:

Property Description
is_valid Overall validation status
diagnostics Complete diagnostic collection
error_count Number of errors
warning_count Number of warnings
information_count Number of informational diagnostics
metadata Validation metadata

Convenience methods include:

  • has_errors()
  • has_warnings()
  • has_information()
  • summary()

Public Classes

The following classes are part of the supported public API.

Class Purpose
ObjectIdentity Canonical identity
KnowledgeObject Semantic object
CanonicalRelation Semantic relation
KnowledgeStructure Immutable knowledge structure
ValidationResult Validation outcome
Diagnostic Validation diagnostic
DiagnosticCollection Immutable diagnostic collection
ReferenceEngine Reference implementation engine
SerializationError Serialization exception
StructuralOperator Abstract base for evolution operators
AddObject Genesis – add a KnowledgeObject
AddRelation Genesis – add a CanonicalRelation
RemoveObject Decay – remove a KnowledgeObject
RemoveRelation Decay – remove a CanonicalRelation

API Stability

The public API follows semantic versioning.

Within a major version:

  • public function names remain stable;
  • observable behaviour remains stable;
  • canonical semantics remain stable.

Internal implementation details may evolve without affecting user code.

Related Documentation

For additional information, see:

  • Getting Started — installation and first steps.
  • Concepts — semantic foundations.
  • Architecture — implementation design.
  • Examples — practical usage patterns.
  • Core Specifications — formal normative definitions.