cks-core 1.1.1__py3-none-any.whl

cks/__init__.py

@@ -0,0 +1,124 @@
+"""
+Canonical Knowledge Structure (CKS).
+
+Reference implementation of the Canonical Knowledge Structure (CKS)
+specifications.
+
+The package exposes the canonical public API defined by CKS-007 together
+with the immutable canonical data model, structural evolution operators,
+and a plugin system for external constraints.
+
+Typical usage:
+
+    import cks
+
+    structure = cks.parse(source)
+    result = cks.validate(structure)
+
+Advanced users may instantiate their own ReferenceEngine or build
+custom validation pipelines using the lower-level modules.
+
+Only symbols defined here should normally be imported by user code.
+"""
+
+from __future__ import annotations
+
+from .core import (
+    CanonicalRelation,
+    KnowledgeObject,
+    KnowledgeStructure,
+    ObjectIdentity,
+)
+
+from .diagnostics import (
+    Diagnostic,
+    DiagnosticCollection,
+    DiagnosticSeverity,
+)
+
+from .engine import ReferenceEngine
+
+from .evolution import (
+    AddObject,
+    AddRelation,
+    RemoveObject,
+    RemoveRelation,
+    compose,
+)
+
+from .plugin import load_external_constraints
+
+from .result import ValidationResult
+
+from .serialization import SerializationError
+
+from .interface import (
+    compare,
+    construct,
+    diagnose,
+    evolve,
+    extract,
+    inspect,
+    parse,
+    project,
+    serialize,
+    validate,
+)
+
+# ---------------------------------------------------------------------------
+# Bootstrap external constraint plugins
+# ---------------------------------------------------------------------------
+
+_EXTERNAL_COUNT = load_external_constraints()
+
+__version__ = "1.1.1"
+
+VERSION = tuple(
+    int(part)
+    for part in __version__.split(".")
+)
+
+__all__ = [
+    # Public API
+    "construct",
+    "parse",
+    "serialize",
+    "validate",
+    "diagnose",
+    "inspect",
+    "compare",
+    "extract",
+    "project",
+    "evolve",
+
+    # Core model
+    "ObjectIdentity",
+    "KnowledgeObject",
+    "CanonicalRelation",
+    "KnowledgeStructure",
+
+    # Evolution operators
+    "AddObject",
+    "AddRelation",
+    "RemoveObject",
+    "RemoveRelation",
+    "compose",
+
+    # Diagnostics
+    "DiagnosticSeverity",
+    "Diagnostic",
+    "DiagnosticCollection",
+
+    # Validation
+    "ValidationResult",
+
+    # Engine
+    "ReferenceEngine",
+
+    # Exceptions
+    "SerializationError",
+
+    # Package metadata
+    "__version__",
+    "VERSION",
+]

cks/adapters/cks_to_jsonld.py

@@ -0,0 +1,62 @@
+"""
+CKS Adapter — CKS to JSON‑LD Converter.
+
+Converts a Canonical Knowledge Structure into a JSON‑LD document.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+from ..core import KnowledgeStructure, CanonicalRelation
+
+
+class CksToJsonLdConverter:
+    """Transform a KnowledgeStructure into a JSON‑LD document."""
+
+    def __init__(self, structure: KnowledgeStructure) -> None:
+        self._structure = structure
+
+    def convert(self) -> Dict[str, Any]:
+        """Run the conversion and return a JSON‑LD dictionary."""
+        graph: List[Dict[str, Any]] = []
+
+        # 1. Convert every KnowledgeObject to a JSON‑LD entity
+        for obj in self._structure.objects:
+            if isinstance(obj, CanonicalRelation):
+                continue  # handled separately
+            entity: Dict[str, Any] = {
+                "@id": obj.identity.id,
+                "@type": obj.identity.type,
+                "name": obj.identity.name,
+            }
+            # Add remaining structure fields
+            for key, value in obj.structure.items():
+                if key not in ("participants", "relation_type"):
+                    entity[key] = value
+            graph.append(entity)
+
+        # 2. Convert every CanonicalRelation to JSON‑LD properties
+        for rel in self._structure.relations():
+            # Find the subject entity and add the relation as a property
+            subj_id = rel.participants[0]
+            obj_id = rel.participants[1] if len(rel.participants) > 1 else None
+            if obj_id is None:
+                continue
+
+            # Locate the subject entity in the graph
+            for entity in graph:
+                if entity["@id"] == subj_id:
+                    if rel.relation_type not in entity:
+                        entity[rel.relation_type] = []
+                    entity[rel.relation_type].append({"@id": obj_id})
+                    break
+            else:
+                # Subject not found — create a minimal entity
+                graph.append({
+                    "@id": subj_id,
+                    "@type": "Entity",
+                    rel.relation_type: [{"@id": obj_id}],
+                })
+
+        return {"@graph": graph}

cks/adapters/cks_to_rdf.py

@@ -0,0 +1,69 @@
+"""
+CKS Adapter — CKS to RDF Converter.
+
+Converts a Canonical Knowledge Structure into an RDF graph
+(Turtle or RDF/XML).
+"""
+
+from __future__ import annotations
+
+
+from rdflib import RDF, RDFS, Graph, Literal, URIRef
+
+from ..core import CanonicalRelation, KnowledgeStructure
+
+# Base namespace for CKS entities that don't have an absolute URI.
+CKS_NS = "http://cks.org/"
+
+
+def _to_uri(raw: str) -> URIRef:
+    """Return *raw* as an absolute URI, prepending CKS_NS if necessary."""
+    if "://" in raw:
+        return URIRef(raw)
+    return URIRef(CKS_NS + raw)
+
+
+class CksToRdfConverter:
+    """Transform a KnowledgeStructure into an RDF graph."""
+
+    def __init__(self, structure: KnowledgeStructure) -> None:
+        self._structure = structure
+        self._graph = Graph()
+
+    def convert(self) -> Graph:
+        """Run the conversion and return an rdflib Graph."""
+        # 1. Convert every KnowledgeObject to an RDF resource
+        for obj in self._structure.objects:
+            if isinstance(obj, CanonicalRelation):
+                continue
+            subject = _to_uri(obj.identity.id)
+            # Type
+            self._graph.add((subject, RDF.type, _to_uri(obj.identity.type)))
+            # Name / label
+            self._graph.add((subject, RDFS.label, Literal(obj.identity.name)))
+            # Additional structure fields
+            for key, value in obj.structure.items():
+                if key in ("participants", "relation_type"):
+                    continue
+                if isinstance(value, (str, int, float)):
+                    self._graph.add((subject, _to_uri(key), Literal(value)))
+
+        # 2. Convert every CanonicalRelation to RDF triples
+        for rel in self._structure.relations():
+            subj_id = rel.participants[0]
+            obj_id = rel.participants[1] if len(rel.participants) > 1 else None
+            if obj_id is None:
+                continue
+            self._graph.add(
+                (_to_uri(subj_id), _to_uri(rel.relation_type), _to_uri(obj_id))
+            )
+
+        return self._graph
+
+    def to_turtle(self) -> str:
+        """Return the RDF graph serialised as Turtle."""
+        return self._graph.serialize(format="turtle")
+
+    def to_rdfxml(self) -> str:
+        """Return the RDF graph serialised as RDF/XML."""
+        return self._graph.serialize(format="xml")

cks/adapters/jsonld_to_cks.py

@@ -0,0 +1,121 @@
+"""
+CKS Adapter — JSON‑LD to CKS Converter.
+
+Converts a JSON‑LD document into a Canonical Knowledge Structure.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from ..core import (
+    CanonicalRelation,
+    KnowledgeObject,
+    KnowledgeStructure,
+    ObjectIdentity,
+)
+
+
+class JsonLdToCksConverter:
+    """Transform a JSON‑LD document into a KnowledgeStructure."""
+
+    def __init__(self, jsonld_data: Dict[str, Any]) -> None:
+        self._data = jsonld_data
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def convert(self) -> KnowledgeStructure:
+        """Run the conversion and return a KnowledgeStructure."""
+        objects: List[KnowledgeObject] = []
+
+        # 1. Merge entities with the same @id
+        merged_entities = self._merge_entities()
+
+        # 2. Convert each merged entity to a KnowledgeObject
+        for entity in merged_entities.values():
+            objects.append(self._entity_to_ko(entity))
+
+        # 3. Convert relations
+        for relation in self._iter_relations():
+            objects.append(relation)
+
+        return KnowledgeStructure(objects)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _merge_entities(self) -> Dict[str, Dict[str, Any]]:
+        """Merge all nodes that share the same @id."""
+        merged: Dict[str, Dict[str, Any]] = {}
+        for entity in self._iter_entities():
+            oid = entity.get("@id", "unknown")
+            if oid not in merged:
+                merged[oid] = dict(entity)
+            else:
+                # Merge: later properties override earlier ones
+                merged[oid].update(entity)
+        return merged
+
+    def _iter_entities(self) -> List[Dict[str, Any]]:
+        """Yield every entity described in the JSON‑LD document."""
+        graph = self._data.get("@graph")
+        if isinstance(graph, list):
+            return graph
+        if isinstance(self._data, dict):
+            return [self._data]
+        return []
+
+    def _entity_to_ko(self, entity: Dict[str, Any]) -> KnowledgeObject:
+        oid = entity.get("@id", "unknown")
+        otype = self._pick_type(entity)
+        name = entity.get("name", entity.get("rdfs:label", oid))
+
+        identity = ObjectIdentity(id=oid, type=otype, name=str(name))
+        structure = dict(entity)
+        return KnowledgeObject(identity=identity, structure=structure)
+
+    @staticmethod
+    def _pick_type(entity: Dict[str, Any]) -> str:
+        types = entity.get("@type", [])
+        if isinstance(types, list) and types:
+            return str(types[0])
+        if isinstance(types, str):
+            return types
+        return "Entity"
+
+    def _iter_relations(self) -> List[CanonicalRelation]:
+        relations: List[CanonicalRelation] = []
+        for entity in self._iter_entities():
+            subject_id = entity.get("@id")
+            if not subject_id:
+                continue
+            for predicate, objects in entity.items():
+                if predicate in ("@id", "@type", "@context", "@graph", "name", "rdfs:label"):
+                    continue
+                if not isinstance(objects, list):
+                    objects = [objects]
+                for obj in objects:
+                    obj_id = self._object_to_id(obj)
+                    if obj_id is None:
+                        continue
+                    rel_id = f"{subject_id}-{predicate}-{obj_id}"
+                    relation = CanonicalRelation(
+                        identity=ObjectIdentity(
+                            id=rel_id, type="Relation", name=predicate
+                        ),
+                        participants=[subject_id, obj_id],
+                        relation_type=predicate,
+                    )
+                    relations.append(relation)
+        return relations
+
+    @staticmethod
+    def _object_to_id(obj: Any) -> Optional[str]:
+        if isinstance(obj, str):
+            return obj
+        if isinstance(obj, dict):
+            return obj.get("@id")
+        return None

cks/adapters/rdf_to_cks.py

@@ -0,0 +1,88 @@
+"""
+CKS Adapter — RDF to CKS Converter.
+
+Converts an RDF graph (RDF/XML, Turtle, etc.) into a Canonical Knowledge Structure.
+"""
+
+from __future__ import annotations
+
+
+import rdflib
+
+from ..core import (
+    CanonicalRelation,
+    KnowledgeObject,
+    KnowledgeStructure,
+    ObjectIdentity,
+)
+
+
+class RdfToCksConverter:
+    """Transform an RDF graph into a KnowledgeStructure."""
+
+    def __init__(self, rdf_data: str, format: str = "turtle") -> None:
+        self._graph = rdflib.Graph()
+        self._graph.parse(data=rdf_data, format=format)
+
+    def convert(self) -> KnowledgeStructure:
+        """Run the conversion and return a KnowledgeStructure."""
+        objects: list[KnowledgeObject] = []
+        seen_ids: set[str] = set()
+        relations: list[CanonicalRelation] = []
+
+        # 1. Convert every subject to a KnowledgeObject
+        for subject in self._graph.subjects():
+            oid = str(subject)
+            if oid not in seen_ids:
+                seen_ids.add(oid)
+                objects.append(self._subject_to_ko(subject))
+
+        # 2. Convert triples
+        for s, p, o in self._graph:
+            if isinstance(o, rdflib.Literal):
+                # Skip literal objects – they are not KnowledgeObjects
+                continue
+
+            subj_id = str(s)
+            pred = str(p)
+            obj_id = str(o)
+
+            # Ensure participants exist
+            for pid in (subj_id, obj_id):
+                if pid not in seen_ids:
+                    seen_ids.add(pid)
+                    objects.append(
+                        KnowledgeObject(
+                            identity=ObjectIdentity(id=pid, type="Entity", name=pid),
+                            structure={},
+                        )
+                    )
+
+            rel_id = f"{subj_id}-{pred}-{obj_id}"
+            relation = CanonicalRelation(
+                identity=ObjectIdentity(id=rel_id, type="Relation", name=pred),
+                participants=[subj_id, obj_id],
+                relation_type=pred,
+            )
+            relations.append(relation)
+
+        all_objects = objects + list(relations)
+        return KnowledgeStructure(all_objects)
+
+    def _subject_to_ko(self, subject: rdflib.term.Node) -> KnowledgeObject:
+        oid = str(subject)
+        # Try to get a human-readable label
+        label = None
+        for _, _, lbl in self._graph.triples((subject, rdflib.RDFS.label, None)):
+            label = str(lbl)
+            break
+        name = label or oid
+
+        # Try to get a type
+        otype = "Entity"
+        for _, _, t in self._graph.triples((subject, rdflib.RDF.type, None)):
+            otype = str(t).split("#")[-1] if "#" in str(t) else str(t)
+            break
+
+        identity = ObjectIdentity(id=oid, type=otype, name=name)
+        return KnowledgeObject(identity=identity, structure={})

cks/cli/__init__.py

@@ -0,0 +1,75 @@
+"""
+CKS Command-Line Interface.
+
+Canonical entry point for interacting with CKS from the terminal.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Optional, Sequence
+
+from .commands import (
+    validate,
+    parse,
+    inspect,
+    evolve,
+    convert,
+    export,
+    schema,
+    plugin,
+)
+
+
+def _create_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="cks",
+        description="Canonical Knowledge Structure — CLI",
+    )
+
+    parser.add_argument("--strict", action="store_true", help="Fail on any plugin loading error")
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    validate.add_parser(sub)
+    parse.add_parser(sub)
+    inspect.add_parser(sub)
+    evolve.add_parser(sub)
+    convert.add_parser(sub)
+    export.add_parser(sub)
+    schema.add_parser(sub)
+    plugin.add_parser(sub)
+
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> None:
+    parser = _create_parser()
+    args = parser.parse_args(argv)
+
+    from cks.plugin import load_external_constraints
+    load_external_constraints(strict=args.strict)
+
+    if args.command == "validate":
+        validate.handle(args)
+    elif args.command == "parse":
+        parse.handle(args)
+    elif args.command == "inspect":
+        inspect.handle(args)
+    elif args.command == "evolve":
+        evolve.handle(args)
+    elif args.command == "convert":
+        convert.handle(args)
+    elif args.command == "export":
+        export.handle(args)
+    elif args.command == "schema":
+        schema.handle(args)
+    elif args.command == "plugin":
+        plugin.handle(args)
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

cks/cli/commands/convert.py

@@ -0,0 +1,54 @@
+"""
+CLI command: convert.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+from ...serialization import serialize as cks_serialize
+
+
+def add_parser(subparsers):
+    parser = subparsers.add_parser("convert", help="Convert JSON‑LD, Turtle, or RDF/XML to CKS")
+    parser.add_argument("input", type=Path, help="Path to input file")
+    parser.add_argument("--output", "-o", type=Path, default=None, help="Write CKS JSON to file")
+    parser.add_argument(
+        "--format", "-f",
+        choices=("json-ld", "rdf-xml", "turtle"),
+        default="json-ld",
+        help="Input format (default: json-ld)",
+    )
+    return parser
+
+
+def handle(args):
+    try:
+        raw = args.input.read_text(encoding="utf-8")
+        data = json.loads(raw) if args.format == "json-ld" else raw
+    except FileNotFoundError:
+        print(f"File not found: {args.input}", file=sys.stderr)
+        sys.exit(1)
+    except json.JSONDecodeError as exc:
+        print(f"Invalid JSON in {args.input}: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.format == "json-ld":
+        from ...adapters.jsonld_to_cks import JsonLdToCksConverter
+        converter = JsonLdToCksConverter(data)
+        structure = converter.convert()
+    elif args.format in ("rdf-xml", "turtle"):
+        from ...adapters.rdf_to_cks import RdfToCksConverter
+        rdf_format = "xml" if args.format == "rdf-xml" else args.format
+        converter = RdfToCksConverter(data, format=rdf_format)
+        structure = converter.convert()
+    else:
+        print(f"Unknown format: {args.format}", file=sys.stderr)
+        sys.exit(1)
+
+    output = cks_serialize(structure)
+    if args.output is None:
+        print(output)
+    else:
+        args.output.write_text(output, encoding="utf-8")

cks/cli/commands/evolve.py

@@ -0,0 +1,97 @@
+"""
+CLI command: evolve.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+from ...serialization import parse as cks_parse, serialize as cks_serialize, SerializationError
+from ...evolution import compose, AddObject, AddRelation, RemoveObject, RemoveRelation
+from ...core import KnowledgeObject, CanonicalRelation, ObjectIdentity
+from ...evolution import StructuralOperator
+
+
+def add_parser(subparsers):
+    parser = subparsers.add_parser("evolve", help="Apply structural evolution")
+    parser.add_argument("input", type=Path, help="Path to canonical JSON file")
+    parser.add_argument("operations", type=Path, help="JSON file describing operations")
+    parser.add_argument("--output", "-o", type=Path, default=None, help="Write result to file")
+    return parser
+
+
+def handle(args):
+    try:
+        raw = args.input.read_text(encoding="utf-8")
+        structure = cks_parse(raw)
+    except FileNotFoundError:
+        print(f"File not found: {args.input}", file=sys.stderr)
+        sys.exit(1)
+    except SerializationError as exc:
+        print(f"Serialization error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        ops_data = json.loads(args.operations.read_text(encoding="utf-8"))
+        operators = _parse_operations(ops_data)
+    except json.JSONDecodeError as exc:
+        print(f"Invalid JSON in operations file: {exc}", file=sys.stderr)
+        sys.exit(1)
+    except ValueError as exc:
+        print(f"Invalid operations: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    new_structure = compose(structure, operators)
+    result = cks_serialize(new_structure)
+
+    if args.output is None:
+        print(result)
+    else:
+        args.output.write_text(result, encoding="utf-8")
+
+
+def _parse_operations(ops_data: list[dict]) -> list:
+    operators: list[StructuralOperator] = []
+    for i, op in enumerate(ops_data):
+        op_type = op.get("type")
+        if op_type is None:
+            raise ValueError(f"Operation #{i}: missing 'type' field")
+        if op_type == "add_object":
+            identity_data = op.get("identity")
+            if identity_data is None:
+                raise ValueError(f"Operation #{i}: missing 'identity' field")
+            identity = ObjectIdentity(**identity_data)
+            obj = KnowledgeObject(identity=identity, structure=op.get("structure", {}))
+            operators.append(AddObject(obj))
+        elif op_type == "add_relation":
+            identity_data = op.get("identity")
+            if identity_data is None:
+                raise ValueError(f"Operation #{i}: missing 'identity' field")
+            identity = ObjectIdentity(**identity_data)
+            participants = op.get("participants")
+            if participants is None:
+                raise ValueError(f"Operation #{i}: missing 'participants' field")
+            relation_type = op.get("relation_type")
+            if relation_type is None:
+                raise ValueError(f"Operation #{i}: missing 'relation_type' field")
+            relation = CanonicalRelation(
+                identity=identity,
+                participants=participants,
+                relation_type=relation_type,
+                structure=op.get("structure", {}),
+            )
+            operators.append(AddRelation(relation))
+        elif op_type == "remove_object":
+            object_id = op.get("object_id")
+            if object_id is None:
+                raise ValueError(f"Operation #{i}: missing 'object_id' field")
+            operators.append(RemoveObject(object_id))
+        elif op_type == "remove_relation":
+            relation_id = op.get("relation_id")
+            if relation_id is None:
+                raise ValueError(f"Operation #{i}: missing 'relation_id' field")
+            operators.append(RemoveRelation(relation_id))
+        else:
+            raise ValueError(f"Operation #{i}: unknown operation type '{op_type}'")
+    return operators