__repr__ and documentation

Author: mzargham

ARCHITECTURE.md

@@ -140,6 +140,101 @@ These seams are documented as comments in the relevant `.ttl` files.
 
 ---
 
+## Interoperability: Flexo MMS and OpenMBEE
+
+Because knowledgecomplex stores all data as RDF and enforces constraints via standard W3C technologies (OWL, SHACL, SPARQL), it is natively compatible with [Flexo MMS](https://github.com/Open-MBEE/flexo-mms-deployment) — the Model Management System developed by the [OpenMBEE](https://www.openmbee.org/) community.
+
+### Why the fit is natural
+
+Flexo MMS is a version-controlled model repository that speaks RDF natively. A KC instance graph is already a valid RDF dataset, so the integration path is direct:
+
+| KC concept | MMS equivalent | Notes |
+|---|---|---|
+| `kc:Complex` (instance graph) | MMS model/branch | A KC export is a self-contained RDF graph that can be committed as an MMS model revision |
+| `kc:boundedBy`, `kc:hasElement` | MMS element relationships | Topological structure is expressed as standard RDF triples |
+| SHACL shapes (`kc_core_shapes.ttl` + user shapes) | MMS validation profiles | Shapes can be registered in MMS to enforce KC constraints on committed models |
+| `kc:uri` | MMS element cross-references | Provides traceability from KC elements to external artifacts (files, documents, URIs) |
+| JSON-LD export (`dump_graph(format="json-ld")`) | MMS ingest format | JSON-LD is the primary API format for Flexo MMS |
+
+### Integration patterns
+
+**Push to MMS:** Export a KC instance via `kc.export()` or `dump_graph(format="json-ld")`, then commit to a Flexo MMS repository via its REST API. The OWL ontology and SHACL shapes can be committed alongside the instance data, enabling MMS-side validation.
+
+**Pull from MMS:** Retrieve a model revision as JSON-LD from Flexo MMS, then load it into a KC instance via `load_graph(kc, "model.jsonld")`. The KC's SHACL verification (`kc.verify()`) ensures the imported data satisfies all topological and ontological constraints.
+
+**Version control:** MMS provides branching, diffing, and merge capabilities at the RDF triple level. KC's `ComplexDiff` and `ComplexSequence` classes complement this by providing simplicial-complex-aware diffing (element-level adds/removes rather than triple-level changes).
+
+### What KC adds beyond MMS
+
+Flexo MMS manages RDF models generically — it stores, versions, and queries them but does not enforce simplicial complex structure. KC adds the topological layer: boundary-closure, closed-triangle constraints, typed simplicial hierarchy, and algebraic topology computations (Betti numbers, Hodge decomposition). Together, MMS provides the model management infrastructure and KC provides the mathematical structure.
+
+### Reference
+
+OpenMBEE (Open Model-Based Engineering Environment) is an open-source community developing tools for model-based systems engineering. Flexo MMS is its core model management system. See [openmbee.org](https://www.openmbee.org/) and [github.com/Open-MBEE](https://github.com/Open-MBEE).
+
+---
+
+## Deployment Architecture
+
+The internal design described above (2x2 map, component layers, static resources) is the library's foundation. In practice, a knowledge complex is deployed through a stack of five layers, each building on the one below:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  5. LLM Tool Integration                                    │
+│     Register KC operations as callable tools for a language  │
+│     model. The complex serves as a deterministic expert      │
+│     system — the LLM navigates, queries, and analyzes via    │
+│     tool calls; the KC guarantees topological correctness    │
+│     and returns structured, verifiable results.              │
+├─────────────────────────────────────────────────────────────┤
+│  4. MCP Server                                               │
+│     Model Context Protocol server exposing KC as tools for   │
+│     AI assistants (Claude, etc.). Each KC operation becomes   │
+│     a tool: add_vertex, boundary, betti_numbers, audit, etc. │
+├─────────────────────────────────────────────────────────────┤
+│  3. Microservice (REST API)                                  │
+│     Python-hosted service exposing KC operations over HTTP.   │
+│     CRUD for elements, SPARQL query execution, SHACL         │
+│     verification, algebraic topology analysis, export/import.│
+├─────────────────────────────────────────────────────────────┤
+│  2. Concrete Knowledge Complex                               │
+│     An instance using a specific ontology. Typed vertices,   │
+│     edges, and faces with attributes. SHACL-verified on      │
+│     every write. Serialized as RDF (Turtle, JSON-LD).        │
+│     Versioned via Flexo MMS or git.                          │
+├─────────────────────────────────────────────────────────────┤
+│  1. KC-Compatible Ontology                                   │
+│     OWL class hierarchy extending kc:Vertex/Edge/Face.       │
+│     SHACL shapes for attribute constraints. Publicly hosted  │
+│     at persistent URIs (w3id.org). Dereferenceable — tools   │
+│     can fetch the ontology and understand the type system.    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Layer 1: Ontology
+
+A KC-compatible ontology is an OWL ontology whose classes extend `kc:Vertex`, `kc:Edge`, and `kc:Face`, paired with SHACL shapes for instance-level constraints. Ontologies are authored via `SchemaBuilder` and exported as standard `.ttl` files. For public use, the ontology should be hosted at a persistent URI (e.g. `https://w3id.org/kc/`) so that other systems can dereference the IRI and retrieve the OWL/SHACL definitions. The `knowledgecomplex.ontologies` package ships three reference ontologies (operations, brand, research) as starting points.
+
+### Layer 2: Concrete Complex
+
+A concrete knowledge complex is an RDF instance graph conforming to a specific ontology. It contains typed elements (vertices, edges, faces) with attributes, linked by `kc:boundedBy` and collected by `kc:hasElement`. SHACL verification enforces topological and ontological constraints on every write. The complex is serializable to Turtle, JSON-LD, or N-Triples and can be versioned via Flexo MMS or committed to a git repository as `.ttl` files.
+
+### Layer 3: Microservice
+
+A Python-hosted HTTP service wraps the `KnowledgeComplex` API in a REST interface. Typical endpoints: element CRUD, named SPARQL queries, topological operations (boundary, star, closure), algebraic topology analysis (Betti numbers, Hodge decomposition, edge PageRank), SHACL verification and audit, and schema introspection. The service loads a schema at startup and manages one or more complex instances.
+
+### Layer 4: MCP Server
+
+A [Model Context Protocol](https://modelcontextprotocol.io/) server exposes KC operations as tools that AI assistants can call. Each KC method becomes an MCP tool: `add_vertex`, `boundary`, `find_cliques`, `betti_numbers`, `audit`, etc. The MCP server is a thin adapter over the microservice or the library directly, translating between MCP tool calls and KC Python API calls.
+
+### Layer 5: LLM Tool Integration
+
+The knowledge complex is registered as a set of callable tools for a language model. The LLM uses the complex as a **deterministic expert system** — it navigates the simplicial structure, retrieves typed elements and their attributes, runs topological queries, and performs algebraic topology analysis via tool calls. The KC guarantees that every result is topologically valid and SHACL-verified. The LLM provides natural language understanding and reasoning; the KC provides structured, auditable, mathematically rigorous retrieval.
+
+This separation is key: the LLM handles ambiguity, intent, and synthesis; the KC handles structure, correctness, and computation. Neither replaces the other.
+
+---
+
 ## Namespace Conventions
 
 ```turtle

docs/ontology.md

@@ -22,6 +22,10 @@ The abstract SHACL shapes graph enforces instance-level constraints that exceed
 
 These constraints use `sh:sparql` validators because they require cross-individual reasoning.
 
+## Interoperability
+
+Because KC stores all data as standard RDF and enforces constraints via W3C SHACL, instance graphs are natively compatible with RDF-based model management systems such as [Flexo MMS](https://github.com/Open-MBEE/flexo-mms-deployment) from the [OpenMBEE](https://www.openmbee.org/) community. JSON-LD export (`dump_graph(format="json-ld")`) provides the primary bridge format. See the [Interoperability section of ARCHITECTURE.md](https://github.com/blockscience/knowledgecomplex/blob/main/ARCHITECTURE.md#interoperability-flexo-mms-and-openmbee) for integration patterns.
+
 ## Design rationale
 
 See [ARCHITECTURE.md](https://github.com/blockscience/knowledgecomplex/blob/main/ARCHITECTURE.md) for the full 2x2 responsibility map and design decisions.

knowledgecomplex/analysis.py

@@ -36,6 +36,10 @@ class BoundaryMatrices:
     index_edge: dict[int, str]
     index_face: dict[int, str]
 
+    def __repr__(self) -> str:
+        return (f"BoundaryMatrices(vertices={len(self.vertex_index)}, "
+                f"edges={len(self.edge_index)}, faces={len(self.face_index)})")
+
 
 @dataclass
 class HodgeDecomposition:
@@ -63,6 +67,9 @@ class SweepCut:
     volume: int
     boundary_edges: int
 
+    def __repr__(self) -> str:
+        return f"SweepCut(vertices={len(self.vertices)}, conductance={self.conductance:.4f})"
+
 
 @dataclass
 class EdgeSweepCut:
@@ -71,6 +78,9 @@ class EdgeSweepCut:
     conductance: float
     volume: int
 
+    def __repr__(self) -> str:
+        return f"EdgeSweepCut(edges={len(self.edges)}, conductance={self.conductance:.4f})"
+
 
 @dataclass
 class HodgeAnalysisResults:
@@ -83,6 +93,10 @@ class HodgeAnalysisResults:
     decompositions: dict[str, HodgeDecomposition]
     influences: dict[str, EdgeInfluence]
 
+    def __repr__(self) -> str:
+        ne = len(self.decompositions)
+        return f"HodgeAnalysisResults(betti={self.betti}, edges={ne})"
+
 
 # ---------------------------------------------------------------------------
 # Weight matrices

knowledgecomplex/filtration.py

@@ -43,6 +43,9 @@ def __init__(self, kc: "KnowledgeComplex") -> None:
         self._kc = kc
         self._steps: list[frozenset[str]] = []
 
+    def __repr__(self) -> str:
+        return f"Filtration(steps={len(self._steps)}, complete={self.is_complete})"
+
     @property
     def complex(self) -> "KnowledgeComplex":
         """The parent KnowledgeComplex."""

knowledgecomplex/graph.py

@@ -96,6 +96,13 @@ def __init__(self, kc: "KnowledgeComplex", id: str) -> None:
         self._id = id
         self._iri = URIRef(f"{kc._schema._base_iri}{id}")
 
+    def __repr__(self) -> str:
+        try:
+            t = self.type
+        except ValueError:
+            t = "?"
+        return f"Element({self._id!r}, type={t!r})"
+
     @property
     def id(self) -> str:
         return self._id
@@ -213,6 +220,10 @@ def __init__(
         self._defer_verification = False
         self._init_graph()
 
+    def __repr__(self) -> str:
+        n = len(self.element_ids())
+        return f"KnowledgeComplex(namespace={self._schema._namespace!r}, elements={n})"
+
     def _init_graph(self) -> None:
         """
         Initialize the instance graph and create the kc:Complex individual.
@@ -851,7 +862,11 @@ def boundary(self, id: str, *, type: str | None = None) -> set[str]:
         return self._ids_from_query(sparql)
 
     def coboundary(self, id: str, *, type: str | None = None) -> set[str]:
-        """Return δ(id): all simplices whose boundary contains id.
+        """Return the cofaces of id: all simplices whose boundary contains id.
+
+        Computes {τ ∈ K : id ∈ ∂(τ)} — the set of (k+1)-simplices that
+        have id as a boundary element.  This is the combinatorial coface
+        relation, not the algebraic coboundary operator δ on cochains.
 
         Parameters
         ----------

knowledgecomplex/queries/star.sparql

@@ -3,8 +3,9 @@
 #
 #   St(sigma) = {tau in K : sigma is a face of tau}
 #
-# Uses the inverse property path ^kc:boundedBy* to walk zero-or-more
-# coboundary hops from sigma upward.
+# Uses kc:boundedBy* from ?star to {simplex}: since boundedBy points
+# downward (high-dim → low-dim), ?star can only reach {simplex} if
+# {simplex} is a face of ?star — exactly the star definition.
 #
 # Usage: substitute {simplex} with the IRI of the element.
 #        substitute {type_filter} with a type constraint or empty string.

knowledgecomplex/schema.py

@@ -202,6 +202,9 @@ def __init__(self, namespace: str) -> None:
         self._queries: dict[str, str] = {}  # name -> SPARQL template string
         self._init_graphs()
 
+    def __repr__(self) -> str:
+        return f"SchemaBuilder(namespace={self._namespace!r}, types={len(self._types)})"
+
     def _init_graphs(self) -> None:
         """Load core OWL and SHACL static resources into internal graphs."""
         self._owl_graph = Graph()