You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: ARCHITECTURE.md
+103-2Lines changed: 103 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -140,6 +140,101 @@ These seams are documented as comments in the relevant `.ttl` files.
140
140
141
141
---
142
142
143
+
## Interoperability: Flexo MMS and OpenMBEE
144
+
145
+
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.
146
+
147
+
### Why the fit is natural
148
+
149
+
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:
150
+
151
+
| KC concept | MMS equivalent | Notes |
152
+
|---|---|---|
153
+
|`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 |
154
+
|`kc:boundedBy`, `kc:hasElement`| MMS element relationships | Topological structure is expressed as standard RDF triples |
155
+
| SHACL shapes (`kc_core_shapes.ttl` + user shapes) | MMS validation profiles | Shapes can be registered in MMS to enforce KC constraints on committed models |
156
+
|`kc:uri`| MMS element cross-references | Provides traceability from KC elements to external artifacts (files, documents, URIs) |
157
+
| JSON-LD export (`dump_graph(format="json-ld")`) | MMS ingest format | JSON-LD is the primary API format for Flexo MMS |
158
+
159
+
### Integration patterns
160
+
161
+
**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.
162
+
163
+
**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.
164
+
165
+
**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).
166
+
167
+
### What KC adds beyond MMS
168
+
169
+
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.
170
+
171
+
### Reference
172
+
173
+
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).
174
+
175
+
---
176
+
177
+
## Deployment Architecture
178
+
179
+
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:
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.
217
+
218
+
### Layer 2: Concrete Complex
219
+
220
+
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.
221
+
222
+
### Layer 3: Microservice
223
+
224
+
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.
225
+
226
+
### Layer 4: MCP Server
227
+
228
+
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.
229
+
230
+
### Layer 5: LLM Tool Integration
231
+
232
+
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.
233
+
234
+
This separation is key: the LLM handles ambiguity, intent, and synthesis; the KC handles structure, correctness, and computation. Neither replaces the other.
235
+
236
+
---
237
+
143
238
## Namespace Conventions
144
239
145
240
```turtle
@@ -162,5 +257,11 @@ User namespaces are set via `SchemaBuilder(namespace="aaa")`. The URI base `http
See [`examples/`](examples/) for 10 runnable examples covering all features below.
72
+
73
+
## Topological queries
74
+
75
+
Every `KnowledgeComplex` has methods for the standard simplicial complex operations.
76
+
All return `set[str]` for natural set algebra:
77
+
78
+
```python
79
+
kc.boundary("face-1") # {e1, e2, e3} — direct boundary
80
+
kc.star("alice") # all simplices containing alice
81
+
kc.link("alice") # Cl(St) \ St — the horizon around alice
82
+
kc.closure({"e1", "e2"}) # smallest subcomplex containing these edges
83
+
kc.degree("alice") # number of incident edges
84
+
85
+
# Set algebra composes naturally
86
+
shared = kc.star("alice") & kc.star("bob")
87
+
```
88
+
89
+
All operators accept an optional `type=` filter for OWL-subclass-aware filtering.
90
+
91
+
## Clique inference
92
+
93
+
Discover higher-order structure from the edge graph:
94
+
95
+
```python
96
+
from knowledgecomplex import find_cliques, infer_faces
97
+
98
+
triangles = find_cliques(kc, k=3) # pure query — what triangles exist?
99
+
infer_faces(kc, "operation") # fill in all triangles as typed faces
100
+
infer_faces(kc, "team", edge_type="collab") # restrict to specific edge types
101
+
```
102
+
103
+
## Visualization
104
+
105
+
Two complementary views — Hasse diagrams (all elements as nodes, boundary as directed arrows) and geometric realization (vertices as 3D points, edges as lines, faces as filled triangles):
106
+
107
+
```python
108
+
from knowledgecomplex import plot_hasse, plot_geometric
SHACL enforces at-most-one `kc:uri` per element. This is useful for domain applications where each element corresponds to an actual document or record.
0 commit comments