content assembled for publication!

Author: mzargham

.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package and dev dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: python -m pytest tests/ -v --tb=short

.github/workflows/docs.yml

@@ -0,0 +1,24 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install -e ".[docs]"
+
+      - name: Deploy docs
+        run: mkdocs gh-deploy --force

.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install hatchling build
+
+      - name: Build distribution
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg
+MANIFEST
+htmlcov/
+.coverage

ARCHITECTURE.md

@@ -0,0 +1,166 @@
+# Architecture: knowledgecomplex
+
+## The 2×2 Responsibility Map
+
+This is the central architectural constraint. Every rule in the system belongs to exactly one cell. The Python package exists to hide this table from the user.
+
+|  | **OWL** | **SHACL** |
+|---|---|---|
+| **Topological** | `kc:Element` base class; `kc:Vertex`, `kc:Edge`, `kc:Face` as subclasses. `kc:Edge` has exactly 2 `boundedBy` (Vertex); `kc:Face` has exactly 3 `boundedBy` (Edge). `kc:Complex` as collection of elements via `kc:hasElement`. | Boundary vertices are distinct; boundary edges of a face form a closed triangle; boundary-closure of a complex (all instance-level; require `sh:sparql`) |
+| **Ontological** | Concrete subclasses and their allowed attributes; property domain/range declarations | Controlled vocabulary enforcement (e.g. `status ∈ {passing, failing, pending}`); attribute presence rules; co-occurrence constraints |
+
+### Why Both OWL and SHACL at Each Layer
+
+**Topological layer:** OWL cardinality axioms enforce structural counts at the class level (reasoning over schema). SHACL is required for the closed-triangle constraint because OWL cannot express a constraint that references the *co-values* of three different property assertions on the same individual — this is a known expressivity boundary of OWL-DL. The `sh:sparql` constraint in `kc_core_shapes.ttl` is the explicit test of this boundary.
+
+**Ontological layer:** OWL defines what attributes a concrete type *has* (property declarations, domain, range, subclass hierarchy). SHACL defines what values those attributes *must have* at the instance level (vocabulary constraints, cardinality on the concrete shape, required/optional). OWL cannot enforce controlled vocabulary on data properties at the instance level without enumerating individuals, which is inappropriate for string-valued attributes.
+
+---
+
+## Component Layers
+
+```
+┌─────────────────────────────────────────────────────┐
+│           Application / Demo  (user code)           │
+│  build_my_instance()  |  domain-specific queries    │
+│  Concrete elements: vertices, edges, faces           │
+├─────────────────────────────────────────────────────┤
+│          Domain Model  (user code)                  │
+│  build_my_schema()    |  domain SPARQL templates    │
+│  MyVertex, MyEdge, MyFace type definitions          │
+├─────────────────────────────────────────────────────┤
+│         knowledgecomplex Python Package             │
+│  SchemaBuilder DSL     |  KnowledgeComplex I/O      │
+│  (OWL + SHACL emit)   |  (rdflib graph + SPARQL)   │
+├──────────────────────┬──────────────────────────────┤
+│  kc_core.ttl         │  kc_core_shapes.ttl          │
+│  (abstract OWL)      │  (abstract SHACL)            │
+├──────────────────────┴──────────────────────────────┤
+│         rdflib  |  pyshacl  |  owlrl                │
+└─────────────────────────────────────────────────────┘
+```
+
+The **domain model** layer sits between the core framework and the application. It defines domain-specific types and queries using the core's `SchemaBuilder` DSL. The application layer then instantiates that model with concrete data.
+
+The static resources (`kc_core.ttl`, `kc_core_shapes.ttl`) are loaded once at `SchemaBuilder.__init__`. Model schema and shapes are merged into the same rdflib `Graph` objects at runtime.
+
+---
+
+## Abstraction Boundary: Core vs. Domain Models
+
+The layers above are separated by a key abstraction boundary: the **core framework** (`knowledgecomplex/`) vs. **domain models** (user code). Everything inside the package boundary (core, static resources, libraries) is framework-owned and invariant. Everything outside (model definitions, instances) is user-authored.
+
+### Core Framework (`knowledgecomplex/`, prefixes `kc:` and `kcs:`)
+
+- **Topological rule enforcement.** The Element/Vertex/Edge/Face hierarchy, cardinality axioms, distinctness, closed-triangle, and boundary-closure constraints. Static OWL and SHACL shipped with the package. Users cannot modify them.
+- **Superstructure attributes.** `kc:uri` (optional, at-most-one) allows any element to reference a source file. Enforced by `kcs:ElementShape`.
+- **Ontological rule authoring.** `SchemaBuilder` provides the DSL for declaring types, attributes, and vocabularies. It *generates* OWL classes and SHACL shapes on behalf of the domain model but does not itself define any domain types.
+- **Instance management.** `KnowledgeComplex` loads the merged schema, manages the RDF graph, validates on every write, and executes named SPARQL queries.
+- **Framework queries.** Generic SPARQL templates (`vertices`, `coboundary`) that work for any domain model.
+
+### Domain Models (user code, prefix `{namespace}:`)
+
+- **Ontological rule enforcement.** The concrete OWL types and SHACL shapes generated by calling `SchemaBuilder.add_*_type()`.
+- **Concrete complex authoring.** Instance data constructed via `KnowledgeComplex.add_*()` calls.
+- **Domain queries.** Model-specific SPARQL templates.
+
+### The Type Inheritance Chain Crosses the Boundary
+
+```
+kc:Element → kc:Vertex → aaa:spec → (instance "spec-001")
+   core          core       model        application
+```
+
+The core owns `Element → Vertex`; the model owns `Vertex → spec`; the application owns the instance `spec-001`. The boundary is at the subclass declaration — `add_vertex_type("spec")` is the model calling the core's authoring API to extend the core's type hierarchy.
+
+### Layer Ownership of the 2×2 Map
+
+|  | **OWL** | **SHACL** |
+|---|---|---|
+| **Topological** | Core owns (static `kc_core.ttl`) | Core owns (static `kc_core_shapes.ttl`) |
+| **Ontological** | Domain model authors via `SchemaBuilder` → core generates | Domain model authors via `vocab()`/attributes → core generates |
+
+Both ontological cells are *authored* by the domain model but *generated and managed* by the core. The domain model never touches OWL or SHACL directly.
+
+---
+
+## Key Design Decisions
+
+### DD1: Attributes over Subclasses (for Simple Domains)
+
+For simple domain models, a single concrete type with a controlled-vocabulary attribute (e.g. `verification` with `status ∈ {passing, failing, pending}`) is preferred over two subclasses (`PassingVerification`, `FailingVerification`). The framework supports both patterns.
+
+**Rationale:** The single-type-with-attribute pattern makes the data more inspectable before schema-level concerns are promoted. `promote_to_attribute()` supports the transition path from untyped patterns to typed attributes.
+
+### DD2: SPARQL Templates, Not Free Queries
+
+All SPARQL is encapsulated as named template files. `KnowledgeComplex.query()` accepts only registered template names.
+
+**Rationale:** Maintains API opacity, prevents arbitrary SPARQL from bypassing validation invariants, and makes the query surface explicit and testable.
+
+### DD3: Validation on Write
+
+`add_vertex()`, `add_edge()`, and `add_face()` each trigger SHACL validation immediately and raise `ValidationError` on failure. Rollback removes all added triples on failure.
+
+**Rationale:** Fail fast; keep the graph in a valid state at all times. Verification is not a batch post-processing step — it is enforced at assertion time.
+
+### DD4: Static Core Resources
+
+`kc_core.ttl` and `kc_core_shapes.ttl` are static files shipped with the package, not generated at runtime.
+
+**Rationale:** The topological rules are framework invariants, not user-configurable. Separating them from user schema makes the 2×2 boundary visible in the file system.
+
+### DD5: `dump_owl()` and `dump_shacl()` Merge Core and User Schema
+
+Both dump methods return the full merged graph (core + user-defined), serialized as Turtle.
+
+**Rationale:** The merged graph is what `pyshacl` and `owlrl` operate on. Showing the full graph makes the system inspectable and demonstrates that user types genuinely extend (not replace) the core ontology.
+
+### DD6: Shared-Domain Removal (`_set_owl_domain`)
+
+When the same property name appears on multiple types, the OWL `rdfs:domain` assertion is removed (leaving no domain) rather than adding multiple domain values. SHACL shapes still enforce per-type constraints correctly via each type's `NodeShape`.
+
+**Rationale:** Multiple `rdfs:domain` values trigger RDFS inference to classify any individual with that property as a member of *all* domain types — violating the type hierarchy. Removing domain resolves the conflict; SHACL handles the per-type enforcement.
+
+---
+
+## Known OWL Expressivity Limits (Design Seams)
+
+| Constraint | OWL can express? | Resolution |
+|---|---|---|
+| Edge has exactly 2 boundary vertices | Yes (cardinality on `boundedBy`) | OWL cardinality axiom |
+| Face has exactly 3 boundary edges | Yes (cardinality on `boundedBy`) | OWL cardinality axiom |
+| Boundary vertices are distinct individuals | No (OWL open-world; same-as/different-from is individual-level) | SHACL `sh:sparql` (COUNT DISTINCT) |
+| Boundary edges of a face form a closed triangle | No (requires co-reference across 3 property values) | SHACL `sh:sparql` constraint |
+| Boundary-closure of a complex | No (requires co-reference across `hasElement` and `boundedBy` on different individuals) | SHACL `sh:sparql` constraint |
+| Controlled vocabulary on data property | No (without `owl:oneOf` on individuals, impractical for strings) | SHACL `sh:in` |
+| At-most-one `kc:uri` per element | Not enforced practically (open-world) | SHACL `sh:maxCount 1` in `ElementShape` |
+
+These seams are documented as comments in the relevant `.ttl` files.
+
+---
+
+## Namespace Conventions
+
+```turtle
+@prefix kc:   <https://example.org/kc#> .       # core framework
+@prefix kcs:  <https://example.org/kc/shape#> . # core shapes
+@prefix aaa:  <https://example.org/aaa#> .      # user namespace (example)
+@prefix aaas: <https://example.org/aaa/shape#> .# user shapes (example)
+```
+
+User namespaces are set via `SchemaBuilder(namespace="aaa")`. The URI base `https://example.org/` is a placeholder for local development; a real deployment would use a dereferenceable IRI.
+
+---
+
+## File Inventory
+
+| File | Layer | Purpose |
+|---|---|---|
+| `knowledgecomplex/resources/kc_core.ttl` | Abstract OWL | Topological backbone: classes, properties, cardinality axioms, `kc:uri` |
+| `knowledgecomplex/resources/kc_core_shapes.ttl` | Abstract SHACL | Topological constraints: distinctness, closed-triangle, boundary-closure, `kc:uri` at-most-one |
+| `knowledgecomplex/schema.py` | Python API — schema authoring | `SchemaBuilder` DSL: `add_*_type`, `dump_owl`, `dump_shacl`, `export`, `load` |
+| `knowledgecomplex/graph.py` | Python API — instance I/O | `KnowledgeComplex`: `add_vertex`, `add_edge`, `add_face`, `query`, `dump_graph`, `export`, `load` |
+| `knowledgecomplex/exceptions.py` | Public exceptions | `ValidationError`, `SchemaError`, `UnknownQueryError` |
+| `knowledgecomplex/queries/vertices.sparql` | Framework SPARQL | Return all vertices and their types |
+| `knowledgecomplex/queries/coboundary.sparql` | Framework SPARQL | Inverse boundary operator |

README.md

@@ -0,0 +1,94 @@
+# knowledgecomplex
+
+A Python library for defining and instantiating **typed simplicial complexes** backed by OWL, SHACL, and SPARQL.
+
+## What it is
+
+A **knowledge complex** is a simplicial complex (vertices, edges, faces) where each element has a type governed by a formal ontology. The library provides:
+
+- **`SchemaBuilder`** — a DSL for declaring vertex/edge/face types, attributes, and vocabularies. Generates OWL and SHACL automatically.
+- **`KnowledgeComplex`** — an instance manager that adds elements, validates them against SHACL on every write, and executes named SPARQL queries.
+- **Core OWL + SHACL** — a static topological backbone: the `Element → Vertex/Edge/Face` hierarchy, boundary-cardinality axioms, and closed-triangle/boundary-closure constraints.
+
+All semantic web machinery (rdflib, pyshacl, owlrl) stays internal. The public API is pure Python.
+
+## Install
+
+```bash
+pip install knowledgecomplex
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/BlockScience/knowledgecomplex.git
+cd knowledgecomplex
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+```python
+from knowledgecomplex import SchemaBuilder, KnowledgeComplex, vocab, text
+
+# 1. Define a schema
+sb = SchemaBuilder(namespace="aaa")
+sb.add_vertex_type("spec",     attributes={"title": text(), "domain": text()})
+sb.add_vertex_type("guidance", attributes={"title": text(), "domain": text()})
+sb.add_edge_type("verification",
+    attributes={"status": vocab("passing", "failing", "pending")})
+sb.add_face_type("assurance")
+
+# 2. Build an instance
+kc = KnowledgeComplex(schema=sb)
+kc.add_vertex("spec-001",     type="spec",     uri="file:///docs/spec-001.md",
+              title="Spec for Verification", domain="aaa")
+kc.add_vertex("guidance-001", type="guidance", uri="file:///docs/guidance-001.md",
+              title="Guidance for Verification", domain="aaa")
+kc.add_edge("ver-001", type="verification",
+            vertices={"spec-001", "guidance-001"}, status="passing")
+
+# 3. Query
+df = kc.query("vertices")   # built-in SPARQL template
+print(df)
+
+# 4. Inspect the RDF
+print(kc.dump_graph())       # Turtle string
+```
+
+## The `kc:uri` attribute
+
+Every element (vertex, edge, or face) can carry an optional `kc:uri` property pointing to its source file:
+
+```python
+kc.add_vertex("doc-001", type="spec", uri="file:///path/to/doc-001.md")
+kc.add_edge("ver-001",   type="verification", vertices={"doc-001", "doc-002"},
+            uri="file:///edges/ver-001.md", status="passing")
+```
+
+SHACL enforces at-most-one `kc:uri` per element. This is particularly useful for domain applications like AAA where each element corresponds to an actual document file.
+
+## Architecture
+
+The library is organised around a 2×2 responsibility map. Every rule belongs to exactly one cell:
+
+|                 | **OWL**                                                   | **SHACL**                                                         |
+|-----------------|-----------------------------------------------------------|-------------------------------------------------------------------|
+| **Topological** | `kc:Element`, `kc:Vertex`, `kc:Edge`, `kc:Face` hierarchy; cardinality axioms on `kc:boundedBy`; `kc:Complex` via `kc:hasElement` | Boundary vertices are distinct; boundary edges form a closed triangle; boundary-closure of a complex (all require `sh:sparql`) |
+| **Ontological** | Concrete subclasses and their properties; domain/range declarations | Controlled vocabulary (`sh:in`); attribute presence rules; co-occurrence constraints |
+
+### Why both OWL and SHACL at each layer
+
+**Topological layer:** OWL cardinality axioms express structural counts at the schema level. SHACL is required for the closed-triangle constraint because OWL cannot express co-reference across three property assertions on different individuals — a known expressivity boundary of OWL-DL.
+
+**Ontological layer:** OWL defines what attributes a type *has* (property declarations, subclass hierarchy). SHACL defines what values those attributes *must have* at the instance level. OWL cannot enforce controlled vocabularies on string-valued data properties.
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the full design rationale.
+
+## Domain model example
+
+This package is used by [mtg-kc](https://github.com/BlockScience/mtg-kc) as a demonstration application, and by [assurances-audits-accountability](https://github.com/BlockScience/assurances-audits-accountability) as a domain-specific knowledge complex for typed document assurance.
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).

docs/api/exceptions.md

@@ -0,0 +1,3 @@
+# Exceptions
+
+::: knowledgecomplex.exceptions

docs/api/graph.md

@@ -0,0 +1,3 @@
+# Graph
+
+::: knowledgecomplex.graph

docs/api/schema.md

@@ -0,0 +1,3 @@
+# Schema
+
+::: knowledgecomplex.schema