API Reference: Knowledge Graphs¶

This document covers the FCC knowledge graph subsystem, which provides a typed graph data structure for representing relationships between personas, workflows, actions, categories, and other FCC entities. The subsystem includes builder functions for constructing graphs from registries, serializers for OWL/RDF/SKOS/JSON-LD export, and federated graphs for cross-namespace resolution.

erDiagram
    KnowledgeGraph ||--o{ KnowledgeNode : contains
    KnowledgeGraph ||--o{ KnowledgeEdge : contains
    KnowledgeNode {
        string node_id PK
        NodeType node_type
        string label
        string namespace
        dict properties
    }
    KnowledgeEdge {
        string source_id FK
        string target_id FK
        EdgeType edge_type
        string label
    }
    KnowledgeNode ||--o{ KnowledgeEdge : "source/target"

KnowledgeGraph¶

fcc.knowledge.graph.KnowledgeGraph is a mutable graph container with O(1) node lookup, adjacency-based neighbor queries, subgraph extraction, and graph merging.

Creating a Graph¶

from fcc.knowledge.graph import KnowledgeGraph
from fcc.knowledge.models import KnowledgeNode, KnowledgeEdge, NodeType, EdgeType

graph = KnowledgeGraph()

# Add nodes
graph.add_node(KnowledgeNode(
    node_id="RC",
    node_type=NodeType.PERSONA,
    label="Research Coordinator",
    properties={"fcc_phase": "Find", "category": "core"},
))

graph.add_node(KnowledgeNode(
    node_id="cat_core",
    node_type=NodeType.CATEGORY,
    label="core",
))

# Add edges
graph.add_edge(KnowledgeEdge(
    source_id="RC",
    target_id="cat_core",
    edge_type=EdgeType.BELONGS_TO,
))

Querying¶

# Retrieve a node
node = graph.get_node("RC")

# Get all neighbors
neighbors = graph.neighbors("RC")

# Filter by type
persona_nodes = graph.nodes_by_type(NodeType.PERSONA)
belongs_edges = graph.edges_by_type(EdgeType.BELONGS_TO)

# Counts
print(graph.node_count)  # Number of nodes
print(graph.edge_count)  # Number of edges

# All nodes/edges
all_nodes = graph.all_nodes()
all_edges = graph.all_edges()

Graph Operations¶

# Extract subgraph
sub = graph.subgraph({"RC", "cat_core"})

# Merge two graphs (nodes from other overwrite same-ID nodes from self)
merged = graph.merge(other_graph)

# Statistics (per-type counts)
stats = graph.stats()
# {"node_count": 2, "edge_count": 1, "nodes_persona": 1, "nodes_category": 1, ...}

Serialization¶

# To/from dict
data = graph.to_dict()
restored = KnowledgeGraph.from_dict(data)

Node and Edge Types¶

NodeType (9 types)¶

Value	Description
`PERSONA`	FCC persona
`WORKFLOW`	Workflow graph
`ACTION`	Workflow action
`CONCEPT`	Abstract concept
`DELIVERABLE`	Work product
`CATEGORY`	Persona category
`DIMENSION`	Persona dimension
`CONSTITUTION`	Governance constitution
`ECOSYSTEM_PROJECT`	Ecosystem project

EdgeType (9 types)¶

Value	Description
`INTERACTS_WITH`	Cross-reference interaction
`DEPENDS_ON`	Dependency relationship
`ORCHESTRATES`	Champion orchestration
`CHAMPIONS`	Champion-of relationship
`PRODUCES`	Persona produces action
`BELONGS_TO`	Category membership
`MAPS_TO`	Vocabulary mapping
`GOVERNS`	Constitution governs persona
`FEDERATION_LINK`	Cross-namespace link

KnowledgeNode¶

Frozen dataclass with node_id, node_type, label, namespace (default "fcc"), uri (auto-generated), and properties dict.

KnowledgeEdge¶

Frozen dataclass with source_id, target_id, edge_type, optional namespace, label, and properties dict.

Builder Functions¶

fcc.knowledge.builders provides five functions that construct KnowledgeGraph instances from FCC registries.

build_persona_graph¶

from fcc.knowledge.builders import build_persona_graph
from fcc.personas.registry import PersonaRegistry
from fcc._resources import get_personas_dir

registry = PersonaRegistry.from_yaml_directory(get_personas_dir())
graph = build_persona_graph(registry)

Creates PERSONA nodes, CATEGORY nodes, and BELONGS_TO, ORCHESTRATES, CHAMPIONS edges.

build_crossref_graph¶

from fcc.knowledge.builders import build_crossref_graph

graph = build_crossref_graph(crossref_matrix)

Creates PERSONA nodes and INTERACTS_WITH edges from cross-reference entries, including relationship_type, interaction, and strength as edge properties.

build_workflow_graph¶

from fcc.knowledge.builders import build_workflow_graph

graph = build_workflow_graph(action_registry)

Creates ACTION nodes, PERSONA reference nodes, and PRODUCES edges linking personas to their actions.

build_constitution_graph¶

from fcc.knowledge.builders import build_constitution_graph

graph = build_constitution_graph(constitution_registry)

Creates CONSTITUTION nodes (with rule counts) and GOVERNS edges linking constitutions to personas.

build_full_fcc_graph¶

from fcc.knowledge.builders import build_full_fcc_graph

graph = build_full_fcc_graph(
    persona_registry=registry,
    crossref_matrix=matrix,
    action_registry=actions,
    constitution_registry=constitutions,
)

Merges all individual sub-graphs into a single unified graph. All arguments are optional; None arguments are skipped.

Serializers¶

fcc.knowledge.serializers provides pure-Python serializers that produce well-formed output without requiring external dependencies.

Turtle (OWL/RDF)¶

from fcc.knowledge.serializers import serialize_turtle

ttl_string = serialize_turtle(graph, ontology=None)

Outputs Turtle format with @prefix declarations, node type triples (rdf:type), rdfs:label literals, and edge triples.

JSON-LD¶

from fcc.knowledge.serializers import serialize_jsonld

jsonld_string = serialize_jsonld(graph, ontology=None)

Produces a JSON-LD document with @context, @graph array of nodes and edges. Custom node properties are prefixed with fcc:.

N-Triples¶

from fcc.knowledge.serializers import serialize_ntriples

nt_string = serialize_ntriples(graph)

Outputs one triple per line in N-Triples format: <subject> <predicate> <object> .

SKOS¶

from fcc.knowledge.serializers import serialize_skos

skos_string = serialize_skos(graph, ontology=None)

Maps categories to skos:Concept instances within a skos:ConceptScheme, with skos:broader/skos:narrower relationships for category-persona hierarchies.

rdflib Availability¶

from fcc.knowledge.serializers import rdflib_available

if rdflib_available():
    # rdflib-dependent features are accessible
    pass

FCCOntology¶

fcc.knowledge.schema.FCCOntology defines the ontology schema including base URI, prefix map, and class/property definitions used by the serializers.

FederatedKnowledgeGraph¶

fcc.knowledge.federation.FederatedKnowledgeGraph provides a federated view over multiple namespace-scoped knowledge graphs.

from fcc.knowledge.federation import FederatedKnowledgeGraph
from fcc.knowledge.models import EdgeType

fed = FederatedKnowledgeGraph(local_namespace="fcc")

# Register graphs
fed.register_local(fcc_graph)
fed.register_remote("cto", cto_graph)
fed.register_remote("aome", aome_graph)

# Add cross-namespace edges
fed.add_cross_edge("fcc", "RC", "cto", "researcher", EdgeType.MAPS_TO)

# Resolve entity across namespaces (by ID or label match)
node = fed.resolve_entity("RC", "fcc", "cto")

# Merge everything into a single graph
merged = fed.merge_federated()

# Query state
print(fed.namespaces())          # ["aome", "cto", "fcc"]
print(fed.cross_project_edges()) # List of cross-namespace edges
stats = fed.stats()
# {"fcc_nodes": 100, "fcc_edges": 200, "cto_nodes": 50, ...}

Import Paths Summary¶

Class / Function	Import Path
`KnowledgeGraph`	`fcc.knowledge.graph`
`KnowledgeNode`	`fcc.knowledge.models`
`KnowledgeEdge`	`fcc.knowledge.models`
`NodeType`	`fcc.knowledge.models`
`EdgeType`	`fcc.knowledge.models`
`build_full_fcc_graph`	`fcc.knowledge.builders`
`build_persona_graph`	`fcc.knowledge.builders`
`build_crossref_graph`	`fcc.knowledge.builders`
`build_workflow_graph`	`fcc.knowledge.builders`
`build_constitution_graph`	`fcc.knowledge.builders`
`serialize_turtle`	`fcc.knowledge.serializers`
`serialize_jsonld`	`fcc.knowledge.serializers`
`serialize_ntriples`	`fcc.knowledge.serializers`
`serialize_skos`	`fcc.knowledge.serializers`
`FederatedKnowledgeGraph`	`fcc.knowledge.federation`