holonic.viz package

Submodules

holonic.viz.formatters module

Node label formatters for holonic visualization.

Produces structured labels for yFiles nodes. The key formatter is format_compartmented which creates UML-style multi-section labels showing type, attributes, and relationships in visually distinct compartments.

SHACL shapes get special treatment: the deeply nested blank-node property constraint structure is collapsed into a readable table of paths, datatypes, cardinalities, and severities.

holonic.viz.formatters.format_simple(node)[source]

Simple one-line label: label or local name.

Return type:

str

Parameters:

node (ProjectedNode)

holonic.viz.formatters.format_typed(node)[source]

Label with type annotation: «Type» Name.

Return type:

str

Parameters:

node (ProjectedNode)

holonic.viz.formatters.format_compartmented(node, *, max_attrs=8, max_value_len=35, show_types=True)[source]

UML-style compartmented label.

Return type:

str

Parameters:
Produces a multi-line string with sections:

«Type» ────── Name ────── attr₁: value₁ attr₂: value₂ …

For yFiles, this renders as a readable multi-line node label. The compartment dividers use unicode box-drawing characters.

holonic.viz.formatters.format_shacl_shape(node, *, max_props=10)[source]

Format a SHACL NodeShape for visualization.

SHACL shapes use deeply nested blank nodes for property constraints. After blank-node resolution (via project_to_lpg), these appear as nested dicts in node.attributes under the sh:property key.

This formatter collapses them into a readable table:

«NodeShape» TargetClassName ────────────── ✓ path₁ [string] 1..1 ⚠ path₂ [integer] 0..1 …

Return type:

str

Parameters:

holonic.viz.graph_builder module

Projection-driven graph builder for yFiles visualization.

Converts holonic structures to yFiles node/edge lists by FIRST projecting RDF through the projections module (type collapse, literal collapse, blank-node resolution, SHACL flattening) and THEN building yFiles data from the simplified ProjectedGraph.

This eliminates the edge clutter and flat-label problems of the old graph_builder by ensuring that:

  • rdf:type triples become node type annotations, not edges

  • Literal-valued triples become node attributes, not edges to literal nodes

  • Blank nodes are inlined as nested attributes, not separate nodes

  • SHACL shapes are rendered as compartmented tables, not blank-node trees

holonic.viz.graph_builder.projected_to_yfiles(lpg, *, layer='default', label_fn=<function format_compartmented>, parent_id=None)[source]

Convert a ProjectedGraph into yFiles node/edge lists.

Parameters:

  • lpg (ProjectedGraph) – The projected graph (output of project_to_lpg or similar).

  • layer (str) – Layer name for styling (interior, boundary, etc.).

  • label_fn (Callable[[ProjectedNode], str]) – Function to format node labels. Default: compartmented.

  • parent_id (str | None) – If set, all nodes are parented to this group node.

Return type:

tuple[list[dict], list[dict]]

holonic.viz.graph_builder.holon_to_yfiles(ds, holon_iri, *, layers=None, show_group=True, label_fn=<function format_compartmented>)[source]

Build yFiles data for a single holon from a HolonicDataset.

Queries the dataset for the holon’s layer graphs, projects each through project_to_lpg(), and builds the yFiles representation.

Parameters:

  • ds – A HolonicDataset instance.

  • holon_iri (str) – The holon to visualize.

  • layers (list[str] | None) – Which layer roles to include. Default: all registered.

  • show_group (bool) – If True, create a group node for the holon and layer groups.

  • label_fn (Callable[[ProjectedNode], str]) – Node label formatter. Default: compartmented.

Return type:

tuple[list[dict], list[dict]]

holonic.viz.graph_builder.holarchy_to_yfiles(ds, *, show_internals=False, layers=None, label_fn=<function format_typed>)[source]

Build yFiles data for the holarchy topology.

Parameters:

  • ds – A HolonicDataset instance.

  • show_internals (bool) – If True, expand each holon to show its layer contents. If False, show holons as single nodes with portal edges.

  • layers (list[str] | None) – When show_internals=True, which layers to display.

  • label_fn (Callable[[ProjectedNode], str]) – Node label formatter for topology mode.

Return type:

tuple[list[dict], list[dict]]

holonic.viz.graph_builder.sparql_result_to_yfiles(result_graph, *, layer='default', label_fn=<function format_compartmented>)[source]

Convert a SPARQL CONSTRUCT result graph to yFiles data.

Projects the result through project_to_lpg first, eliminating type edges, literal nodes, and blank-node clutter.

Return type:

tuple[list[dict], list[dict]]

Parameters:

holonic.viz.provenance module

Provenance visualization for holonic audit trails.

Renders the flow of information through holons as a directed graph with membrane health badges, surface reports, agent attribution, and temporal ordering. Designed for automated traversal auditing.

The visualization shows:

  • Holon nodes with membrane health status (color-coded)

  • Portal edges with agent, timestamp, and portal label

  • Surface reports (boundary contract summaries) on hover

  • Derivation chains connecting the full pipeline

Classes

ProvenanceViz

yFiles widget for interactive provenance exploration.

holonic.viz.provenance.audit_trail_to_yfiles(audit, *, show_surface=True, show_agents=True)[source]

Convert an AuditTrail into yFiles node/edge lists.

Nodes represent holons that participated in traversals. Edges represent portal traversal hops.

Return type:

tuple[list[dict], list[dict]]

Parameters:
Each node is annotated with:

  • Membrane health status (color + icon)

  • Surface report (boundary contract summary)

  • Triple count (if available)

Each edge is annotated with:

  • Portal label

  • Agent

  • Timestamp

class holonic.viz.provenance.ProvenanceViz(ds, *, layout='hierarchic', show_surface=True, show_agents=True)[source]

Bases: object

Interactive provenance audit trail visualization.

Shows the flow of information through holons as a directed graph with membrane health badges, surface reports, and temporal ordering.

Parameters:

  • ds – A HolonicDataset instance.

  • layout (str) – yFiles layout algorithm. Default: hierarchic (best for pipelines — left-to-right flow).

  • show_surface (bool) – If True, nodes display boundary contract summaries.

  • show_agents (bool) – If True, edges display agent attribution.

  • Usage:: –

    prov_viz = ProvenanceViz(ds) prov_viz.show()

    # Or with interactive controls: prov_viz.show_with_controls()

    # Access the underlying audit trail: audit = prov_viz.audit print(audit.summary())

property audit: AuditTrail

The collected audit trail (lazy-loaded).

refresh()[source]

Re-collect the audit trail from the dataset.

Return type:

None

show(**kwargs)[source]

Display the provenance graph in the notebook.

show_with_controls()[source]

Display with interactive controls.

print_report()[source]

Print a text-based audit report (no yFiles required).

Return type:

None

holonic.viz.styles module

Visual constants for holonic graph visualization.

Colour palette follows the cell-membrane metaphor:

Interior = blue (the cytoplasm) Boundary = purple (the membrane) Projection = green (the surface proteins) Context = amber (the tissue/environment) Portal = red (traversal channel) Holon = grey (group container)

holonic.viz.styles.color_for_layer(layer)[source]

Return colors for the layer (default theme).

Return type:

str

Parameters:

layer (str)

holonic.viz.styles.color_for_layer_light(layer)[source]

Return colors for the layer (light theme).

Return type:

str

Parameters:

layer (str)

holonic.viz.styles.shape_for_layer(layer)[source]

Return shapes for layer.

Return type:

str

Parameters:

layer (str)

holonic.viz.styles.shorten_uri(uri, max_len=40)[source]

Produce a readable short form of a URI.

Return type:

str

Parameters:
holonic.viz.styles.classify_edge(predicate)[source]

Classify an edge predicate into a semantic role for styling.

Return type:

str

Parameters:

predicate (str)

holonic.viz.styles.edge_color(predicate)[source]

Return colour for an edge based on its predicate.

Return type:

str

Parameters:

predicate (str)

holonic.viz.widgets module

yFiles Jupyter graph widgets for holonic visualization.

All widgets query the HolonicDataset via SPARQL and project through the projections module before rendering. No direct Python object traversal — the dataset is the source of truth.

Classes

HolonViz

Visualize a single holon’s layers with compartmented node labels, SHACL shape tables, and edge-reduced topology.

HolarchyViz

Visualize the holarchy topology — collapsed (holons as nodes) or expanded (layers visible per holon).

SPARQLExplorer

Interactive SPARQL CONSTRUCT explorer with projection presets, namespace management, and live graph rendering.

class holonic.viz.widgets.HolonViz(ds, holon_iri, *, layers=None, layout='hierarchic', label_fn=<function format_compartmented>)[source]

Bases: object

Visualize a single holon’s layers from a HolonicDataset.

Projects each layer through project_to_lpg before rendering, collapsing types, literals, and blank nodes into compartmented node labels. SHACL shapes get special tabular formatting.

Parameters:

  • ds – A HolonicDataset instance.

  • holon_iri (str) – IRI of the holon to visualize.

  • layers (list[str] | None) – Which layers to show. Default: all registered.

  • layout (str) – yFiles layout algorithm.

  • label_fn (Callable[[ProjectedNode], str]) – Node label formatter. Default: compartmented.

  • Usage:: – viz = HolonViz(ds, “urn:holon:my-data”) viz.show()

show(**kwargs)[source]

Display the holon graph in the notebook.

show_with_controls()[source]

Display with interactive layer/layout controls.

class holonic.viz.widgets.HolarchyViz(ds, *, show_internals=False, layers=None, layout='hierarchic')[source]

Bases: object

Visualize a holarchy: holons as nodes connected by portals.

Two modes:

  • Collapsed: Holons are single nodes, portals are edges. Uses project_holarchy() for clean topology view.

  • Expanded: Each holon opens to show its layer groups with projected, edge-reduced content.

Parameters:

  • ds – A HolonicDataset instance.

  • show_internals (bool) – If True, expand holons to show layers. Default: False.

  • layers (list[str] | None) – When expanded, which layers to show.

  • layout (str) – yFiles layout algorithm.

  • Usage:: – viz = HolarchyViz(ds) viz.show() # collapsed viz.show(show_internals=True) # expanded

show(**kwargs)[source]

Helper to build and render the viz.

show_with_controls()[source]

Render Holarchy with view controls.

class holonic.viz.widgets.SPARQLExplorer(ds, namespaces=None, layout='hierarchic')[source]

Bases: object

Interactive SPARQL CONSTRUCT explorer linked to graph visualization.

Executes CONSTRUCT queries against the HolonicDataset and renders results through the projections module — types collapsed, literals inlined, blank nodes resolved — before visualization.

Includes:

  • Namespace manager (auto-generates PREFIX declarations)

  • Built-in projection presets (dropdown)

  • Editable query textarea

  • Live graph update on execution

  • Label format selector

Parameters:

  • ds – A HolonicDataset instance.

  • namespaces (dict[str, str] | None) – Additional namespace prefix → IRI mappings.

  • layout (str) – Default layout algorithm.

  • Usage:: – explorer = SPARQLExplorer(ds, namespaces={“eng”: “urn:eng:”}) explorer.show()

DEFAULT_NAMESPACES = {'cga': 'urn:holonic:ontology:', 'dct': 'http://purl.org/dc/terms/', 'owl': 'http://www.w3.org/2002/07/owl#', 'prov': 'http://www.w3.org/ns/prov#', 'rdf': 'http://www.w3.org/1999/02/22-rdf-syntax-ns#', 'rdfs': 'http://www.w3.org/2000/01/rdf-schema#', 'sh': 'http://www.w3.org/ns/shacl#', 'skos': 'http://www.w3.org/2004/02/skos/core#', 'xsd': 'http://www.w3.org/2001/XMLSchema#'}
execute(query)[source]

Execute a SPARQL CONSTRUCT against the dataset.

Return type:

Graph

Parameters:

query (str)

visualize_result(result, layout=None, label_fn=<function format_compartmented>)[source]

Convert CONSTRUCT result to a yFiles widget via projections.

Parameters:
show()[source]

Display the interactive explorer.

Module contents

Visualization module for holonic RDF systems.

Provides yFiles Jupyter Graphs widgets for visualizing holons, holarchies, and SPARQL query results. All rendering is projection- driven: RDF is simplified via project_to_lpg() before building yFiles node/edge data.

Requires: yfiles-jupyter-graphs, ipywidgets

class holonic.viz.HolonViz(ds, holon_iri, *, layers=None, layout='hierarchic', label_fn=<function format_compartmented>)[source]

Bases: object

Visualize a single holon’s layers from a HolonicDataset.

Projects each layer through project_to_lpg before rendering, collapsing types, literals, and blank nodes into compartmented node labels. SHACL shapes get special tabular formatting.

Parameters:

  • ds – A HolonicDataset instance.

  • holon_iri (str) – IRI of the holon to visualize.

  • layers (list[str] | None) – Which layers to show. Default: all registered.

  • layout (str) – yFiles layout algorithm.

  • label_fn (Callable[[ProjectedNode], str]) – Node label formatter. Default: compartmented.

  • Usage:: – viz = HolonViz(ds, “urn:holon:my-data”) viz.show()

show(**kwargs)[source]

Display the holon graph in the notebook.

show_with_controls()[source]

Display with interactive layer/layout controls.

class holonic.viz.HolarchyViz(ds, *, show_internals=False, layers=None, layout='hierarchic')[source]

Bases: object

Visualize a holarchy: holons as nodes connected by portals.

Two modes:

  • Collapsed: Holons are single nodes, portals are edges. Uses project_holarchy() for clean topology view.

  • Expanded: Each holon opens to show its layer groups with projected, edge-reduced content.

Parameters:

  • ds – A HolonicDataset instance.

  • show_internals (bool) – If True, expand holons to show layers. Default: False.

  • layers (list[str] | None) – When expanded, which layers to show.

  • layout (str) – yFiles layout algorithm.

  • Usage:: – viz = HolarchyViz(ds) viz.show() # collapsed viz.show(show_internals=True) # expanded

show(**kwargs)[source]

Helper to build and render the viz.

show_with_controls()[source]

Render Holarchy with view controls.

class holonic.viz.SPARQLExplorer(ds, namespaces=None, layout='hierarchic')[source]

Bases: object

Interactive SPARQL CONSTRUCT explorer linked to graph visualization.

Executes CONSTRUCT queries against the HolonicDataset and renders results through the projections module — types collapsed, literals inlined, blank nodes resolved — before visualization.

Includes:

  • Namespace manager (auto-generates PREFIX declarations)

  • Built-in projection presets (dropdown)

  • Editable query textarea

  • Live graph update on execution

  • Label format selector

Parameters:

  • ds – A HolonicDataset instance.

  • namespaces (dict[str, str] | None) – Additional namespace prefix → IRI mappings.

  • layout (str) – Default layout algorithm.

  • Usage:: – explorer = SPARQLExplorer(ds, namespaces={“eng”: “urn:eng:”}) explorer.show()

DEFAULT_NAMESPACES = {'cga': 'urn:holonic:ontology:', 'dct': 'http://purl.org/dc/terms/', 'owl': 'http://www.w3.org/2002/07/owl#', 'prov': 'http://www.w3.org/ns/prov#', 'rdf': 'http://www.w3.org/1999/02/22-rdf-syntax-ns#', 'rdfs': 'http://www.w3.org/2000/01/rdf-schema#', 'sh': 'http://www.w3.org/ns/shacl#', 'skos': 'http://www.w3.org/2004/02/skos/core#', 'xsd': 'http://www.w3.org/2001/XMLSchema#'}
execute(query)[source]

Execute a SPARQL CONSTRUCT against the dataset.

Return type:

Graph

Parameters:

query (str)

visualize_result(result, layout=None, label_fn=<function format_compartmented>)[source]

Convert CONSTRUCT result to a yFiles widget via projections.

Parameters:
show()[source]

Display the interactive explorer.

class holonic.viz.ProvenanceViz(ds, *, layout='hierarchic', show_surface=True, show_agents=True)[source]

Bases: object

Interactive provenance audit trail visualization.

Shows the flow of information through holons as a directed graph with membrane health badges, surface reports, and temporal ordering.

Parameters:

  • ds – A HolonicDataset instance.

  • layout (str) – yFiles layout algorithm. Default: hierarchic (best for pipelines — left-to-right flow).

  • show_surface (bool) – If True, nodes display boundary contract summaries.

  • show_agents (bool) – If True, edges display agent attribution.

  • Usage:: –

    prov_viz = ProvenanceViz(ds) prov_viz.show()

    # Or with interactive controls: prov_viz.show_with_controls()

    # Access the underlying audit trail: audit = prov_viz.audit print(audit.summary())

property audit: AuditTrail

The collected audit trail (lazy-loaded).

refresh()[source]

Re-collect the audit trail from the dataset.

Return type:

None

show(**kwargs)[source]

Display the provenance graph in the notebook.

show_with_controls()[source]

Display with interactive controls.

print_report()[source]

Print a text-based audit report (no yFiles required).

Return type:

None

holonic.viz.holon_to_yfiles(ds, holon_iri, *, layers=None, show_group=True, label_fn=<function format_compartmented>)[source]

Build yFiles data for a single holon from a HolonicDataset.

Queries the dataset for the holon’s layer graphs, projects each through project_to_lpg(), and builds the yFiles representation.

Parameters:

  • ds – A HolonicDataset instance.

  • holon_iri (str) – The holon to visualize.

  • layers (list[str] | None) – Which layer roles to include. Default: all registered.

  • show_group (bool) – If True, create a group node for the holon and layer groups.

  • label_fn (Callable[[ProjectedNode], str]) – Node label formatter. Default: compartmented.

Return type:

tuple[list[dict], list[dict]]

holonic.viz.holarchy_to_yfiles(ds, *, show_internals=False, layers=None, label_fn=<function format_typed>)[source]

Build yFiles data for the holarchy topology.

Parameters:

  • ds – A HolonicDataset instance.

  • show_internals (bool) – If True, expand each holon to show its layer contents. If False, show holons as single nodes with portal edges.

  • layers (list[str] | None) – When show_internals=True, which layers to display.

  • label_fn (Callable[[ProjectedNode], str]) – Node label formatter for topology mode.

Return type:

tuple[list[dict], list[dict]]

holonic.viz.projected_to_yfiles(lpg, *, layer='default', label_fn=<function format_compartmented>, parent_id=None)[source]

Convert a ProjectedGraph into yFiles node/edge lists.

Parameters:

  • lpg (ProjectedGraph) – The projected graph (output of project_to_lpg or similar).

  • layer (str) – Layer name for styling (interior, boundary, etc.).

  • label_fn (Callable[[ProjectedNode], str]) – Function to format node labels. Default: compartmented.

  • parent_id (str | None) – If set, all nodes are parented to this group node.

Return type:

tuple[list[dict], list[dict]]

holonic.viz.sparql_result_to_yfiles(result_graph, *, layer='default', label_fn=<function format_compartmented>)[source]

Convert a SPARQL CONSTRUCT result graph to yFiles data.

Projects the result through project_to_lpg first, eliminating type edges, literal nodes, and blank-node clutter.

Return type:

tuple[list[dict], list[dict]]

Parameters:
holonic.viz.audit_trail_to_yfiles(audit, *, show_surface=True, show_agents=True)[source]

Convert an AuditTrail into yFiles node/edge lists.

Nodes represent holons that participated in traversals. Edges represent portal traversal hops.

Return type:

tuple[list[dict], list[dict]]

Parameters:
Each node is annotated with:

  • Membrane health status (color + icon)

  • Surface report (boundary contract summary)

  • Triple count (if available)

Each edge is annotated with:

  • Portal label

  • Agent

  • Timestamp

holonic.viz.format_compartmented(node, *, max_attrs=8, max_value_len=35, show_types=True)[source]

UML-style compartmented label.

Return type:

str

Parameters:
Produces a multi-line string with sections:

«Type» ────── Name ────── attr₁: value₁ attr₂: value₂ …

For yFiles, this renders as a readable multi-line node label. The compartment dividers use unicode box-drawing characters.

holonic.viz.format_shacl_shape(node, *, max_props=10)[source]

Format a SHACL NodeShape for visualization.

SHACL shapes use deeply nested blank nodes for property constraints. After blank-node resolution (via project_to_lpg), these appear as nested dicts in node.attributes under the sh:property key.

This formatter collapses them into a readable table:

«NodeShape» TargetClassName ────────────── ✓ path₁ [string] 1..1 ⚠ path₂ [integer] 0..1 …

Return type:

str

Parameters:
holonic.viz.format_simple(node)[source]

Simple one-line label: label or local name.

Return type:

str

Parameters:

node (ProjectedNode)

holonic.viz.format_typed(node)[source]

Label with type annotation: «Type» Name.

Return type:

str

Parameters:

node (ProjectedNode)