Skip to content

Knowledge Graph Explorer Demo

This demo walks through the FCC Knowledge Graph subsystem -- a typed graph model with 9 node types, 9 edge types, builder functions, serialization to OWL/RDF/SKOS/JSON-LD, and federated cross-namespace resolution.

Table of Contents

  1. Overview
  2. Prerequisites
  3. Step 1: Build a Persona Graph
  4. Step 2: Inspect Nodes and Edges
  5. Step 3: Query Neighbors
  6. Step 4: Extract a Subgraph
  7. Step 5: Merge Multiple Graphs
  8. Step 6: Serialize to JSON-LD
  9. Step 7: Use the Federated Knowledge Graph
  10. Screenshots
  11. Next Steps

Overview

The fcc.knowledge module provides a typed, mutable KnowledgeGraph built from FCC registries. Five builder functions create specialized subgraphs (personas, workflows, cross-references, constitutions, and a full composite). The graph supports neighbor traversal, subgraph extraction, merge operations, and export to standard knowledge representation formats.

Node Types

Type Description
PERSONA A persona in the FCC framework
WORKFLOW A workflow graph definition
ACTION A workflow action
CONCEPT An abstract concept
DELIVERABLE A produced artifact
CATEGORY A persona category
DIMENSION A persona dimension
CONSTITUTION A governance constitution
ECOSYSTEM_PROJECT An ecosystem project

Edge Types

Type Description
INTERACTS_WITH Peer interaction
DEPENDS_ON Dependency relationship
ORCHESTRATES Champion orchestration
CHAMPIONS Champion-of relationship
PRODUCES Deliverable production
BELONGS_TO Category membership
MAPS_TO Vocabulary mapping
GOVERNS Governance relationship
FEDERATION_LINK Cross-namespace link

Prerequisites

  • Python 3.10+ with FCC installed: pip install -e ".[dev]"
  • No external dependencies required -- all builders work with in-memory data

Step 1: Build a Persona Graph

The build_persona_graph builder creates a graph from the full persona registry, including persona nodes, category nodes, and relationship edges.

from fcc.personas.registry import PersonaRegistry
from fcc.knowledge import build_persona_graph

registry = PersonaRegistry.from_data_dir()
graph = build_persona_graph(registry)

stats = graph.stats()
print(f"Nodes: {stats['node_count']}")
print(f"Edges: {stats['edge_count']}")
print(f"Persona nodes: {stats['nodes_persona']}")
print(f"Category nodes: {stats['nodes_category']}")

Step 2: Inspect Nodes and Edges

Query nodes by type and examine their properties.

from fcc.knowledge.models import NodeType, EdgeType

# List all persona nodes
personas = graph.nodes_by_type(NodeType.PERSONA)
print(f"Persona nodes: {len(personas)}")
for p in personas[:5]:
    print(f"  [{p.node_id}] {p.label} (ns={p.namespace})")

# List all category nodes
categories = graph.nodes_by_type(NodeType.CATEGORY)
print(f"\nCategory nodes: {len(categories)}")
for c in categories[:5]:
    print(f"  [{c.node_id}] {c.label}")

# List orchestration edges
orch_edges = graph.edges_by_type(EdgeType.ORCHESTRATES)
print(f"\nOrchestration edges: {len(orch_edges)}")
for e in orch_edges[:5]:
    print(f"  {e.source_id} --> {e.target_id}")

Step 3: Query Neighbors

Use the adjacency-based neighbors() method to traverse the graph from any node.

# Find neighbors of the Research Coordinator persona
node = graph.get_node("RC")
if node:
    print(f"Node: {node.label}")
    neighbors = graph.neighbors("RC")
    print(f"Neighbors ({len(neighbors)}):")
    for n in neighbors:
        print(f"  [{n.node_id}] {n.label} (type={n.node_type.value})")

Step 4: Extract a Subgraph

Extract a subgraph containing only specific nodes. Edges are retained only when both source and target are included.

# Extract the core category subgraph
core_ids = {p.node_id for p in personas if p.properties.get("category") == "core"}
core_ids.add("category_core")  # Include the category node

subgraph = graph.subgraph(core_ids)
print(f"Subgraph nodes: {subgraph.node_count}")
print(f"Subgraph edges: {subgraph.edge_count}")

Step 5: Merge Multiple Graphs

Combine persona and workflow graphs into a single unified graph using the merge() operation.

from fcc.knowledge import build_persona_graph, build_workflow_graph
from fcc.workflow.actions import WorkflowActionRegistry

action_registry = WorkflowActionRegistry.from_data_dir()
workflow_graph = build_workflow_graph(action_registry)

print(f"Persona graph: {graph.node_count} nodes, {graph.edge_count} edges")
print(f"Workflow graph: {workflow_graph.node_count} nodes, {workflow_graph.edge_count} edges")

merged = graph.merge(workflow_graph)
print(f"Merged graph: {merged.node_count} nodes, {merged.edge_count} edges")

Alternatively, use build_full_fcc_graph to combine all builders at once:

from fcc.knowledge import build_full_fcc_graph

full_graph = build_full_fcc_graph(
    persona_registry=registry,
    action_registry=action_registry,
)
print(f"Full graph: {full_graph.node_count} nodes, {full_graph.edge_count} edges")

Step 6: Serialize to JSON-LD

Export the graph to standard knowledge representation formats.

from fcc.knowledge import serialize_jsonld, serialize_turtle, serialize_skos

# JSON-LD export
jsonld_doc = serialize_jsonld(graph)
print(f"JSON-LD keys: {list(jsonld_doc.keys())}")
print(f"JSON-LD nodes: {len(jsonld_doc.get('@graph', []))}")

# Export graph stats
from fcc.knowledge import export_stats

stats = export_stats(graph)
for key, value in stats.items():
    print(f"  {key}: {value}")

If rdflib is installed, you can also serialize to Turtle and SKOS:

from fcc.knowledge import rdflib_available

if rdflib_available():
    turtle_str = serialize_turtle(graph)
    print(f"Turtle output length: {len(turtle_str)} chars")

    skos_str = serialize_skos(graph)
    print(f"SKOS output length: {len(skos_str)} chars")
else:
    print("Install rdflib for RDF/Turtle/SKOS export: pip install rdflib")

Step 7: Use the Federated Knowledge Graph

The FederatedKnowledgeGraph supports cross-namespace resolution, allowing graphs from different projects to be linked.

from fcc.knowledge import FederatedKnowledgeGraph

federated = FederatedKnowledgeGraph()

# Register namespace graphs
federated.register_graph("fcc", graph)

# Query across namespaces
node = federated.get_node("fcc", "RC")
if node:
    print(f"Federated lookup: {node.label} in namespace 'fcc'")

Screenshots

Knowledge Graph

KG Explorer Streamlit app showing graph traversal

The Knowledge Graph Explorer Streamlit app provides an interactive interface for traversing the graph, filtering by node type, and visualizing relationships between personas, categories, and workflows.

Next Steps

  • Explore the RAG Pipeline Demo to see how knowledge graph data feeds into retrieval-augmented generation.
  • Try the Federation Demo to connect knowledge graphs from multiple projects.
  • See the Visualization Cookbook for D3 recipes that render knowledge graph data in the browser.
  • Browse src/fcc/knowledge/ for the full source code.
  • Review src/fcc/data/schemas/knowledge_graph.json for the JSON schema.