File I/O

File-based import/export utilities for KnowledgeComplex.

Functions:

Name	Description
save_graph Serialize the instance graph to a file.
load_graph Parse a file into the instance graph
dump_graph Return the instance graph as a string in a given format.

Design notes

• Turtle (.ttl) is the default format — human-readable and consistent with the ontology/shapes patterns used throughout the codebase.
• All load functions are additive: they call graph.parse() which adds triples to the existing graph. Load into a fresh KnowledgeComplex for a clean restore.
• No TriG (.trig) or N-Quads (.nq) — KnowledgeComplex uses a plain rdflib.Graph, not a ConjunctiveGraph.

Adapted from discourse_graph.io (multi-agent-dg).

save_graph(kc, path, format='turtle')

Serialize kc._instance_graph to a file.

Parameters:

Name	Type	Description	Default
kc	'KnowledgeComplex'	The KnowledgeComplex whose instance graph is serialized.	required
path	'Path | str'	Destination file path. The file is created or overwritten.	required
format	str	rdflib serialization format string. Defaults to "turtle". Other useful values: "json-ld", "ntriples", "n3", "xml" (RDF/XML).	'turtle'

Source code in knowledgecomplex/io.py

def save_graph(
    kc: "KnowledgeComplex",
    path: "Path | str",
    format: str = "turtle",
) -> None:
    """Serialize ``kc._instance_graph`` to a file.

    Parameters
    ----------
    kc :
        The ``KnowledgeComplex`` whose instance graph is serialized.
    path :
        Destination file path.  The file is created or overwritten.
    format :
        rdflib serialization format string.  Defaults to ``"turtle"``.
        Other useful values: ``"json-ld"``, ``"ntriples"``, ``"n3"``,
        ``"xml"`` (RDF/XML).
    """
    path = Path(path)
    kc._instance_graph.serialize(destination=str(path), format=format)

load_graph(kc, path, format=None, validate=False)

Parse a file into kc._instance_graph (additive).

Parameters:

Name	Type	Description	Default
kc	'KnowledgeComplex'	The KnowledgeComplex whose instance graph receives the parsed triples.	required
path	'Path | str'	Source file path.	required
format	Optional[str]	rdflib serialization format string. When None, auto-detected from the file extension using the built-in registry.	None
validate	bool	If True, run SHACL validation after parsing. On failure the newly added triples are rolled back and ValidationError is raised. Defaults to False because the data may have been exported from a validated KnowledgeComplex and re-validating is expensive.	False

Notes

This operation is additive: existing triples in the instance graph are retained. For a clean restore, load into a freshly constructed KnowledgeComplex.

The instance graph includes TBox (ontology) triples. Loading a file that was saved from a KC with the same schema is harmless — rdflib deduplicates triples. Loading data from a different schema will merge ontologies; the caller is responsible for schema compatibility.

Source code in knowledgecomplex/io.py

def load_graph(
    kc: "KnowledgeComplex",
    path: "Path | str",
    format: Optional[str] = None,
    validate: bool = False,
) -> None:
    """Parse a file into ``kc._instance_graph`` (additive).

    Parameters
    ----------
    kc :
        The ``KnowledgeComplex`` whose instance graph receives the
        parsed triples.
    path :
        Source file path.
    format :
        rdflib serialization format string.  When ``None``, auto-detected
        from the file extension using the built-in registry.
    validate :
        If ``True``, run SHACL validation after parsing.  On failure the
        newly added triples are rolled back and ``ValidationError`` is
        raised.  Defaults to ``False`` because the data may have been
        exported from a validated ``KnowledgeComplex`` and re-validating
        is expensive.

    Notes
    -----
    This operation is **additive**: existing triples in the instance graph
    are retained.  For a clean restore, load into a freshly constructed
    ``KnowledgeComplex``.

    The instance graph includes TBox (ontology) triples.  Loading a file
    that was saved from a KC with the same schema is harmless — rdflib
    deduplicates triples.  Loading data from a different schema will merge
    ontologies; the caller is responsible for schema compatibility.
    """
    path = Path(path)
    fmt = _detect_format(path, format)

    if validate:
        before = set(kc._instance_graph)

    kc._instance_graph.parse(source=str(path), format=fmt)

    if validate:
        try:
            kc._validate()
        except ValidationError:
            added = set(kc._instance_graph) - before
            for triple in added:
                kc._instance_graph.remove(triple)
            raise

dump_graph(kc, format='turtle')

Return the instance graph as a string in the requested format.

Parameters:

Name	Type	Description	Default
kc	'KnowledgeComplex'	The KnowledgeComplex whose instance graph is serialized.	required
format	str	rdflib serialization format string. Defaults to "turtle".	'turtle'

Returns:

Type	Description
str	The serialized graph.

Source code in knowledgecomplex/io.py

def dump_graph(
    kc: "KnowledgeComplex",
    format: str = "turtle",
) -> str:
    """Return the instance graph as a string in the requested format.

    Parameters
    ----------
    kc :
        The ``KnowledgeComplex`` whose instance graph is serialized.
    format :
        rdflib serialization format string.  Defaults to ``"turtle"``.

    Returns
    -------
    str
        The serialized graph.
    """
    return kc._instance_graph.serialize(format=format)