KnowledgeGraph vs FederatedKnowledgeGraph¶

The FCC knowledge layer exposes two graph abstractions. KnowledgeGraph (src/fcc/knowledge/graph.py:12) is a single-namespace directed multigraph over 12 NodeType values and 11 EdgeType values, backed by dict-of-nodes, list-of-edges, and an adjacency index. FederatedKnowledgeGraph (src/fcc/knowledge/federation.py:16) wraps a local graph and an arbitrary number of remote graphs, adding cross-namespace edges and a resolve_entity method for federated lookups. The diagram below shows how federation composes the base class rather than subclassing it — the federated graph owns a local KnowledgeGraph and references remotes by namespace, which keeps single-namespace operations cleanly isolated.

The diagram below details the node and edge models alongside the two graph containers.

classDiagram
    class NodeType {
        <<enumeration>>
        PERSONA
        WORKFLOW
        ACTION
        CONCEPT
        DELIVERABLE
        CATEGORY
        DIMENSION
        CONSTITUTION
        ECOSYSTEM_PROJECT
        BUSINESS_PROCESS
        SID_ENTITY
        VOCABULARY_TERM
    }

    class EdgeType {
        <<enumeration>>
        INTERACTS_WITH
        DEPENDS_ON
        ORCHESTRATES
        CHAMPIONS
        PRODUCES
        BELONGS_TO
        MAPS_TO
        GOVERNS
        FEDERATION_LINK
        CROSS_NAMESPACE
        EQUIVALENT_TO
    }

    class KnowledgeNode {
        <<frozen dataclass>>
        +node_id : str
        +node_type : NodeType
        +label : str
        +namespace : str
        +uri : str
        +properties : dict
    }

    class KnowledgeEdge {
        <<frozen dataclass>>
        +source_id : str
        +target_id : str
        +edge_type : EdgeType
        +namespace : str
        +weight : float
        +properties : dict
    }

    class KnowledgeGraph {
        -_nodes : dict
        -_edges : list
        -_adjacency : dict
        +all_nodes() list
        +all_edges() list
        +get_node(id) KnowledgeNode
        +add_node(node)
        +add_edge(edge)
        +neighbors(id) list
        +nodes_by_type(type) list
        +edges_by_type(type) list
        +subgraph(ids) KnowledgeGraph
        +merge(other)
        +stats() dict
    }

    class FederatedKnowledgeGraph {
        -_local_namespace : str
        -_local_graph : KnowledgeGraph
        -_remote_graphs : dict
        -_cross_edges : list
        +register_local(graph)
        +register_remote(namespace, graph)
        +merge_federated() KnowledgeGraph
        +resolve_entity(id, namespace) KnowledgeNode
    }

    KnowledgeNode --> NodeType : node_type
    KnowledgeEdge --> EdgeType : edge_type
    KnowledgeGraph "1" *-- "0..*" KnowledgeNode : _nodes
    KnowledgeGraph "1" *-- "0..*" KnowledgeEdge : _edges
    FederatedKnowledgeGraph "1" *-- "1" KnowledgeGraph : _local_graph
    FederatedKnowledgeGraph "1" o-- "0..*" KnowledgeGraph : _remote_graphs
    FederatedKnowledgeGraph "1" *-- "0..*" KnowledgeEdge : _cross_edges

Reach for KnowledgeGraph whenever a single-namespace view is enough — for example, building a persona-to-action interaction map for a single ecosystem project. Reach for FederatedKnowledgeGraph when more than one namespace must coexist and cross-edges like EQUIVALENT_TO or CROSS_NAMESPACE need to be materialised. The OWL/RDF/SKOS/JSON-LD serializers (in serializers.py) operate on the base graph, which means federated exports go through merge_federated() to flatten first.

An intentional design choice is that _remote_graphs is a dict keyed by namespace and holds full KnowledgeGraph instances rather than thin proxies — this simplifies merge logic at the cost of memory, but lets federated queries fall back to local traversals without any network hop.

Key contracts¶

NodeType — enumeration of the 12 node kinds recognised by the FCC ontology.
EdgeType — enumeration of the 11 relation kinds, including three federation-specific kinds (FEDERATION_LINK, CROSS_NAMESPACE, EQUIVALENT_TO).
KnowledgeNode — frozen node record with id, type, label, namespace, URI, and free-form properties.
KnowledgeEdge — frozen directed edge record with source, target, type, namespace, weight, and properties.
KnowledgeGraph — single-namespace container with dict-backed nodes, list-backed edges, and an adjacency index; exposes traversal, typing, subgraph, and merge operations.
FederatedKnowledgeGraph — multi-namespace wrapper holding one local graph and many remote graphs plus a list of cross-namespace edges; exposes registration, federated merge, and entity resolution.

KnowledgeGraph vs FederatedKnowledgeGraph¶

Key contracts¶

See also¶