knowledgecomplex 0.1.0__py3-none-any.whl

knowledgecomplex/resources/kc_core.ttl

@@ -0,0 +1,140 @@
+# knowledgecomplex/resources/kc_core.ttl
+# Abstract OWL ontology — KC topological backbone.
+# This file is a static resource; do not generate at runtime.
+#
+# DESIGN SEAMS (constraints OWL cannot express — see kc_core_shapes.ttl):
+#   - Edge boundary vertices must be distinct (open-world assumption; needs SHACL)
+#   - Closed-triangle constraint across 3 Face boundary edges (co-reference; needs sh:sparql)
+#   - Boundary-closure of a Complex (compositional validity; needs sh:sparql)
+#
+# SIMPLIFICATION (this implementation):
+#   All simplices are unoriented. The boundary operator (boundedBy) returns an
+#   unordered set, not an ordered list. For oriented simplex support see
+#   docs/issues/orientation-support.md.
+
+@prefix owl:  <http://www.w3.org/2002/07/owl#> .
+@prefix rdf:  <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .
+@prefix kc:   <https://example.org/kc#> .
+
+<https://example.org/kc>
+    a owl:Ontology ;
+    rdfs:label "Knowledge Complex Core Ontology" ;
+    rdfs:comment "Abstract topological backbone: Element, Vertex, Edge, Face, Complex." .
+
+# ---------------------------------------------------------------------------
+# Base class for all topological elements (simplices)
+# ---------------------------------------------------------------------------
+
+kc:Element a owl:Class ;
+    rdfs:label "Element" ;
+    rdfs:comment """Abstract topological element (k-simplex). All KC types are elements.
+        The simplex order k determines boundary cardinality:
+          k=0 (Vertex): empty boundary (cardinality 0)
+          k=1 (Edge):   2 boundary vertices
+          k=2 (Face):   3 boundary edges
+          k>=1 general: (k+1) boundary (k-1)-simplices
+        Higher orders can be defined by subclassing Element.""" .
+
+# ---------------------------------------------------------------------------
+# Abstract simplex classes (subclasses of Element)
+# ---------------------------------------------------------------------------
+
+kc:Vertex a owl:Class ;
+    rdfs:subClassOf kc:Element ;
+    rdfs:label "Vertex" ;
+    rdfs:comment "Abstract 0-simplex. Empty boundary (∂v = ∅). Concrete types must subclass this." .
+
+kc:Edge a owl:Class ;
+    rdfs:subClassOf kc:Element ;
+    rdfs:label "Edge" ;
+    rdfs:comment "Abstract 1-simplex. Boundary: exactly 2 vertices. Concrete types must subclass this." .
+
+kc:Face a owl:Class ;
+    rdfs:subClassOf kc:Element ;
+    rdfs:label "Face" ;
+    rdfs:comment "Abstract 2-simplex. Boundary: exactly 3 edges. Concrete types must subclass this." .
+
+# Higher-order simplices (k>=3) can be defined by subclassing kc:Element
+# and adding a boundedBy cardinality restriction. For example:
+#   kc:Tetrahedron rdfs:subClassOf kc:Element .  # 3-simplex
+#   kc:Tetrahedron rdfs:subClassOf [
+#       a owl:Restriction ; owl:onProperty kc:boundedBy ;
+#       owl:qualifiedCardinality "4"^^xsd:nonNegativeInteger ;
+#       owl:onClass kc:Face ] .
+
+# ---------------------------------------------------------------------------
+# Boundary operator (dimension-polymorphic)
+# ---------------------------------------------------------------------------
+# boundedBy maps a k-simplex to its bounding (k-1)-simplices:
+#   Vertex: no boundedBy (k=0, empty boundary)
+#   Edge  boundedBy  Vertex  (cardinality 2)
+#   Face  boundedBy  Edge    (cardinality 3)
+# Coboundary (inverse lookup) is handled by SPARQL queries, not stored triples.
+
+kc:boundedBy a owl:ObjectProperty ;
+    rdfs:domain kc:Element ;
+    rdfs:range  kc:Element ;
+    rdfs:label "boundedBy" ;
+    rdfs:comment """Boundary operator (∂). Maps a k-simplex to its bounding
+        (k-1)-simplices. Cardinality is enforced per subclass via OWL restrictions.
+        Vertices (k=0) have empty boundary. For k>=1, cardinality = k+1.
+        All elements are unoriented (boundary is an unordered set).""" .
+
+# ---------------------------------------------------------------------------
+# Source file URI (optional, superstructure-level attribute)
+# ---------------------------------------------------------------------------
+# kc:uri allows any element to point to its source file (local or remote).
+# This is particularly useful for domain applications (e.g. AAA) where each
+# element corresponds to an actual document file.
+
+kc:uri a owl:DatatypeProperty ;
+    rdfs:domain kc:Element ;
+    rdfs:range  xsd:anyURI ;
+    rdfs:label "uri" ;
+    rdfs:comment """Optional URI pointing to the source file for this element.
+        Accepts any URI scheme (file:///, https://, etc.).
+        At-most-one per element (sh:maxCount 1 enforced in kc_core_shapes.ttl).""" .
+
+# ---------------------------------------------------------------------------
+# Cardinality restrictions (topological-OWL cell of the 2x2)
+# ---------------------------------------------------------------------------
+
+# Edge: exactly 2 boundary vertices
+# DESIGN SEAM: distinctness of the 2 vertices requires SHACL (see kc_core_shapes.ttl)
+
+kc:Edge rdfs:subClassOf [
+    a owl:Restriction ;
+    owl:onProperty kc:boundedBy ;
+    owl:qualifiedCardinality "2"^^xsd:nonNegativeInteger ;
+    owl:onClass kc:Vertex
+] .
+
+# Face: exactly 3 boundary edges
+# DESIGN SEAM: closed-triangle constraint (boundary edges share vertices in a cycle)
+# cannot be expressed in OWL. See sh:sparql in kc_core_shapes.ttl.
+
+kc:Face rdfs:subClassOf [
+    a owl:Restriction ;
+    owl:onProperty kc:boundedBy ;
+    owl:qualifiedCardinality "3"^^xsd:nonNegativeInteger ;
+    owl:onClass kc:Edge
+] .
+
+# ---------------------------------------------------------------------------
+# Complex — a collection of elements (simplices)
+# ---------------------------------------------------------------------------
+
+kc:Complex a owl:Class ;
+    rdfs:label "Complex" ;
+    rdfs:comment """A simplicial complex: a collection of elements (simplices) that is
+        closed under the boundary operator. If a simplex is in the complex, all its
+        boundary elements must also be in the complex. Topological validity of the
+        composition is enforced by SHACL (see kcs:ComplexShape).""" .
+
+kc:hasElement a owl:ObjectProperty ;
+    rdfs:domain kc:Complex ;
+    rdfs:range  kc:Element ;
+    rdfs:label "hasElement" ;
+    rdfs:comment "Membership relation: an element belongs to this complex." .

knowledgecomplex/resources/kc_core_shapes.ttl

@@ -0,0 +1,191 @@
+# knowledgecomplex/resources/kc_core_shapes.ttl
+# Abstract SHACL shapes — KC topological constraints.
+# This file is a static resource; do not generate at runtime.
+#
+# This file covers the topological-SHACL cell of the 2x2 responsibility map.
+# It enforces instance-level constraints that OWL cardinality axioms cannot express:
+#
+#   1. Edge boundary vertices are distinct individuals.
+#      WHY NOT OWL: OWL operates under the open-world assumption. Two boundedBy
+#      triples pointing to different IRIs are not guaranteed to denote different
+#      individuals without an explicit owl:differentFrom assertion. SHACL operates
+#      on the graph as-is.
+#
+#   2. Closed-triangle constraint: the 3 boundary edges of a Face share vertices
+#      forming a cycle.
+#      WHY NOT OWL: This requires co-referencing across 3 separate boundedBy values —
+#      i.e. checking that the boundary edges' own boundary vertices form a specific
+#      topological pattern across multiple individuals. OWL-DL cannot express this.
+#      sh:sparql is the correct mechanism.
+#
+#   3. Boundary-closure of a Complex: if a simplex is in the complex, all its
+#      boundary elements must also be in the complex.
+#      WHY NOT OWL: This requires co-referencing across kc:hasElement and
+#      kc:boundedBy on different individuals. OWL cannot express "for every element
+#      in the complex, each of its boundary elements is also in the complex."
+#
+#   4. kc:uri is optional and at-most-one per element.
+#      WHY SHACL: OWL cardinality is inference-based; SHACL enforces this at
+#      the instance level without open-world complications.
+#
+# SIMPLIFICATION: All simplices are unoriented. boundedBy returns an unordered set.
+
+@prefix sh:   <http://www.w3.org/ns/shacl#> .
+@prefix owl:  <http://www.w3.org/2002/07/owl#> .
+@prefix rdf:  <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .
+@prefix kc:   <https://example.org/kc#> .
+@prefix kcs:  <https://example.org/kc/shape#> .
+
+# ---------------------------------------------------------------------------
+# ElementShape — superstructure constraint: kc:uri is optional, at-most-one
+# ---------------------------------------------------------------------------
+
+kcs:ElementShape
+    a sh:NodeShape ;
+    sh:targetClass kc:Element ;
+    rdfs:label "ElementShape" ;
+    rdfs:comment "Superstructure constraint: kc:uri may appear at most once per element." ;
+
+    sh:property [
+        sh:path kc:uri ;
+        sh:datatype xsd:anyURI ;
+        sh:maxCount 1 ;
+        sh:message "An element may have at most one kc:uri value."
+    ] .
+
+# ---------------------------------------------------------------------------
+# EdgeShape — topological-SHACL constraints on KC:Edge instances
+# ---------------------------------------------------------------------------
+
+kcs:EdgeShape
+    a sh:NodeShape ;
+    sh:targetClass kc:Edge ;
+    rdfs:label "EdgeShape" ;
+    rdfs:comment "Topological constraints on KC:Edge instances." ;
+
+    # boundedBy: exactly 2, each must be KC:Vertex
+    sh:property [
+        sh:path kc:boundedBy ;
+        sh:minCount 2 ;
+        sh:maxCount 2 ;
+        sh:class kc:Vertex ;
+        sh:message "Edge must have exactly two boundedBy relations of type KC:Vertex."
+    ] ;
+
+    # Distinctness constraint: the two boundary vertices must differ
+    # WHY SHACL NOT OWL: see file header note 1.
+    # NOTE: We use COUNT(DISTINCT) because SPARQL pattern matching on two
+    # boundedBy triples produces self-joins where both variables bind to the
+    # same value, even when two distinct vertices exist.
+    sh:sparql [
+        a sh:SPARQLConstraint ;
+        rdfs:comment "Edge boundary vertices must be distinct individuals." ;
+        sh:message "Edge boundary vertices must not be the same vertex." ;
+        sh:select """
+            PREFIX kc: <https://example.org/kc#>
+            SELECT $this WHERE {
+                $this kc:boundedBy ?v .
+            }
+            GROUP BY $this
+            HAVING (COUNT(DISTINCT ?v) < 2)
+        """
+    ] .
+
+# ---------------------------------------------------------------------------
+# FaceShape — topological-SHACL constraints on KC:Face instances
+# ---------------------------------------------------------------------------
+
+kcs:FaceShape
+    a sh:NodeShape ;
+    sh:targetClass kc:Face ;
+    rdfs:label "FaceShape" ;
+    rdfs:comment "Topological constraints on KC:Face instances." ;
+
+    # boundedBy: exactly 3, each must be KC:Edge
+    sh:property [
+        sh:path kc:boundedBy ;
+        sh:minCount 3 ;
+        sh:maxCount 3 ;
+        sh:class kc:Edge ;
+        sh:message "Face must have exactly three boundedBy relations, each of type KC:Edge."
+    ] ;
+
+    # Closed-triangle constraint.
+    # WHY SHACL sh:sparql NOT OWL: see file header note 2.
+    # The query finds faces where the 3 boundary edges do NOT form a closed triangle.
+    # A closed triangle requires: for edges e1, e2, e3, each with 2 boundary vertices,
+    # the union of all 6 boundary vertex slots contains exactly 3 distinct vertices
+    # and each vertex appears in exactly 2 of the 3 edges.
+    sh:sparql [
+        a sh:SPARQLConstraint ;
+        rdfs:comment """
+            Closed-triangle constraint: the 3 boundary edges of a Face must share
+            vertices forming a cycle (v1-v2, v2-v3, v3-v1). This cannot be expressed
+            in OWL because it requires co-referencing property values across 3 edge
+            individuals.
+        """ ;
+        sh:message "Face boundary edges do not form a closed triangle over shared vertices." ;
+        sh:select """
+            PREFIX kc: <https://example.org/kc#>
+            SELECT $this WHERE {
+                $this kc:boundedBy ?e1 ;
+                      kc:boundedBy ?e2 ;
+                      kc:boundedBy ?e3 .
+                FILTER (?e1 != ?e2 && ?e2 != ?e3 && ?e1 != ?e3)
+                ?e1 kc:boundedBy ?a1 ; kc:boundedBy ?b1 .
+                ?e2 kc:boundedBy ?a2 ; kc:boundedBy ?b2 .
+                ?e3 kc:boundedBy ?a3 ; kc:boundedBy ?b3 .
+                FILTER (?a1 != ?b1 && ?a2 != ?b2 && ?a3 != ?b3)
+                # For a valid triangle each endpoint of e1 must appear in at least
+                # one other edge's boundary.
+                BIND(
+                    EXISTS {
+                        { ?e2 kc:boundedBy ?a1 } UNION { ?e3 kc:boundedBy ?a1 }
+                    } AS ?a1_shared
+                )
+                BIND(
+                    EXISTS {
+                        { ?e2 kc:boundedBy ?b1 } UNION { ?e3 kc:boundedBy ?b1 }
+                    } AS ?b1_shared
+                )
+                FILTER NOT EXISTS {
+                    # Valid closed triangle: each endpoint of e1 is shared with another edge
+                    FILTER (?a1_shared && ?b1_shared)
+                }
+            }
+        """
+    ] .
+
+# ---------------------------------------------------------------------------
+# ComplexShape — boundary-closure constraint on KC:Complex instances
+# ---------------------------------------------------------------------------
+
+kcs:ComplexShape
+    a sh:NodeShape ;
+    sh:targetClass kc:Complex ;
+    rdfs:label "ComplexShape" ;
+    rdfs:comment """Boundary-closure constraint: if a simplex is in the complex,
+        all its boundary elements must also be in the complex.""" ;
+
+    # Boundary-closure: every element's boundary elements must also be members.
+    # WHY SHACL sh:sparql NOT OWL: see file header note 3.
+    # The query finds complexes where some element has a boundary element that
+    # is NOT also a member of the complex.
+    sh:sparql [
+        a sh:SPARQLConstraint ;
+        rdfs:comment """Boundary-closure: for every element in the complex,
+            each of its boundedBy targets must also be a hasElement of the complex.""" ;
+        sh:message "Complex is not closed under the boundary operator: an element's boundary element is missing from the complex." ;
+        sh:select """
+            PREFIX kc: <https://example.org/kc#>
+            SELECT $this WHERE {
+                $this kc:hasElement ?elem .
+                ?elem kc:boundedBy ?boundary .
+                FILTER NOT EXISTS {
+                    $this kc:hasElement ?boundary .
+                }
+            }
+        """
+    ] .