Cross-Project Federation Demo

This demo walks through the FCC Federation subsystem -- a cross-project entity resolution, namespace management, and change tracking system that connects multiple ecosystem projects into a unified federation.

---

Table of Contents

1. Overview
2. Prerequisites
3. Step 1: Configure Namespaces
4. Step 2: Register Federated Projects
5. Step 3: Resolve Entities Across Namespaces
6. Step 4: Track Changes
7. Step 5: Run a Health Check
8. Step 6: Use the Federated Knowledge Graph
9. Namespace Registry Reference
10. Screenshots
11. Next Steps

---

Overview

The fcc.federation module coordinates cross-project integration across the FCC ecosystem. It provides four components:

Component	Module	Purpose
NamespaceRegistry	fcc.federation.namespaces	Register and look up project namespaces with URI resolution
EntityResolver	fcc.federation.entities	Resolve local identifiers across namespaces using vocabulary mappings
ChangeTracker	fcc.federation.change_tracking	Record and query federation change history
FederationRegistry	fcc.federation.registry	Top-level facade combining all three components

The federation system supports 11 ecosystem namespaces, each representing a project in the FCC ecosystem (e.g., fcc, paom, fornax, sky-parlour).

---

Prerequisites

• Python 3.10+ with FCC installed: pip install -e ".[dev]"
• No external services required -- all operations run in-memory

---

Step 1: Configure Namespaces

A NamespaceConfig defines a project's canonical namespace, URI prefix, and version. The NamespaceRegistry provides O(1) lookup and URI resolution.

from fcc.federation import NamespaceConfig, NamespaceRegistry

registry = NamespaceRegistry()

# Register the FCC namespace
fcc_ns = NamespaceConfig(
    namespace="fcc",
    prefix="fcc",
    base_uri="https://fcc.example.org/entities/",
    version="0.8.0",
    description="FCC Agent Team Framework",
)
registry.register(fcc_ns)

# Register a second project
paom_ns = NamespaceConfig(
    namespace="paom",
    prefix="paom",
    base_uri="https://paom.example.org/entities/",
    version="1.0.0",
    description="PAOM Object Model",
)
registry.register(paom_ns)

# Look up a namespace
config = registry.get("fcc")
if config:
    print(f"Namespace: {config.namespace}")
    print(f"Base URI: {config.base_uri}")
    print(f"Version: {config.version}")

# Resolve a local ID to a full URI
uri = registry.resolve_uri("fcc", "RC")
print(f"Resolved URI: {uri}")
# https://fcc.example.org/entities/RC

---

Step 2: Register Federated Projects

The FederationRegistry provides a high-level facade for managing federated projects, combining namespace registration, entity resolution, and change tracking.

from fcc.federation import FederationRegistry, NamespaceConfig

federation = FederationRegistry()

# Register projects with namespace configs
federation.add_project(
    namespace="fcc",
    namespace_config=NamespaceConfig(
        namespace="fcc",
        prefix="fcc",
        base_uri="https://fcc.example.org/entities/",
        version="0.8.0",
        description="FCC Agent Team Framework",
    ),
)

federation.add_project(
    namespace="paom",
    namespace_config=NamespaceConfig(
        namespace="paom",
        prefix="paom",
        base_uri="https://paom.example.org/entities/",
        version="1.0.0",
        description="PAOM Object Model",
    ),
)

print(f"Registered projects: {federation.project_count()}")
print(f"Project namespaces: {federation.all_projects()}")

---

Step 3: Resolve Entities Across Namespaces

The EntityResolver uses vocabulary mappings to translate identifiers from one namespace to another. Each FederatedEntity carries resolution metadata including confidence scores.

from fcc.federation import EntityResolver, FederatedEntity
from fcc.objectmodel.mapping import VocabularyMapping

# Create vocabulary mappings between namespaces
mapping = VocabularyMapping(
    source_vocabulary="fcc",
    target_vocabulary="paom",
    field_mappings={
        "RC": "research_coordinator",
        "SA": "solution_architect",
        "CR": "code_reviewer",
    },
)

resolver = EntityResolver(mappings=[mapping])

# Resolve a local ID from FCC to PAOM
entity = resolver.resolve("RC", source_namespace="fcc", target_namespace="paom")
if entity:
    print(f"Local ID: {entity.local_id}")
    print(f"Namespace: {entity.namespace}")
    print(f"Canonical ID: {entity.canonical_id}")
    print(f"Resolved: {entity.resolved}")
    print(f"Confidence: {entity.confidence}")

Using FederationRegistry for Cross-Project Resolution

# Resolve across all registered projects
results = federation.resolve_across_projects("RC", source_namespace="fcc")
print(f"Resolved to {len(results)} project(s)")
for entity in results:
    print(f"  {entity.canonical_id} (confidence={entity.confidence})")

---

Step 4: Track Changes

The ChangeTracker records mutations to federated entities, maintaining a full audit trail.

from fcc.federation import ChangeTracker, ModelChange

tracker = ChangeTracker()

# Record a change
change = ModelChange(
    entity_id="RC",
    namespace="fcc",
    field="role_title",
    old_value="Research Coordinator",
    new_value="Research Lead",
)
tracker.record(change)

# Query change history
history = tracker.history()
print(f"Changes recorded: {len(history)}")
for entry in history:
    print(f"  [{entry.timestamp}] {entry.change.entity_id}: "
          f"{entry.change.field} changed")

# Access via the federation registry
log = federation.change_log()
print(f"Federation change log entries: {len(log)}")

---

Step 5: Run a Health Check

The FederationRegistry provides a health check that reports the status of all registered projects.

health = federation.health_check()
print(f"Projects checked: {len(health.get('projects', []))}")
for project in health.get("projects", []):
    print(f"  [{project['namespace']}]")
    print(f"    Has facade: {project['has_facade']}")
    print(f"    Has namespace config: {project['has_namespace_config']}")

---

Step 6: Use the Federated Knowledge Graph

The FederatedKnowledgeGraph from fcc.knowledge supports registering knowledge graphs under different namespaces and querying across them.

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

# Build a knowledge graph from the persona registry
persona_registry = PersonaRegistry.from_data_dir()
fcc_graph = build_persona_graph(persona_registry)

# Register in the federated graph
federated_kg = FederatedKnowledgeGraph()
federated_kg.register_graph("fcc", fcc_graph)

# Query across namespaces
node = federated_kg.get_node("fcc", "RC")
if node:
    print(f"Found: {node.label} in namespace 'fcc'")
    print(f"URI: {node.uri}")

---

Namespace Registry Reference

The FCC ecosystem defines 11 namespaces for cross-project federation:

Namespace	Description
fcc	FCC Agent Team Framework (this project)
paom	PAOM Object Model
fornax	Fornax Data Engine
sky-parlour	Sky-Parlour Visualization Platform
distiller	Distiller Analytics Bridge
crucible	Crucible Development Platform
observatory	Observatory Monitoring System
nexus	Nexus Integration Hub
chronicle	Chronicle Event Store
meridian	Meridian Governance Framework
beacon	Beacon Discovery Service

---

Screenshots

The Federation Dashboard Streamlit app provides a visual overview of registered namespaces, entity resolution results, and the change history timeline across projects.

---

Next Steps

• Explore the Knowledge Graph Demo to see how graphs are built and serialized before federation.
• Try the RAG Pipeline Demo to index federated documents for retrieval.
• See the Persona Dimensions Demo to explore dimension data that feeds into federated entities.
• Browse src/fcc/federation/ for the full source code.
• Review src/fcc/data/schemas/federation.json for the JSON schema.