Chapter 21: Unified Object Model¶

The FCC object model layer provides a protocol-based abstraction that unifies access to personas, workflows, archetypes, and ontological entities across multiple ecosystem projects. This chapter covers the architecture, query patterns, and federation capabilities of the unified object model.

The class diagram below sketches the unified object-model contracts — DomainEntity, RepositoryProtocol[T], ModelFacade, VocabularyMapping, and the five-stage EvolutionStage enum.

classDiagram
    class DomainEntity {
        <<Protocol>>
        +entity_id: str
        +entity_type: str
        +namespace: str
    }
    class RepositoryProtocol~T~ {
        <<Protocol>>
        +get(entity_id) T
        +list_all() list~T~
        +search(query) list~T~
        +count() int
    }
    class ModelFacade {
        <<ABC>>
        +stats() dict
        +search(query) list
        +get_full(entity_id) T
        +by_type(type) list
    }
    class VocabularyMapping {
        +source_namespace: str
        +target_namespace: str
        +translate(term) str
    }
    class EvolutionStage {
        <<Enum>>
        NASCENT
        MAPPED
        BRIDGED
        FEDERATED
        UNIFIED
    }
    ModelFacade --> RepositoryProtocol~T~
    RepositoryProtocol~T~ --> DomainEntity
    ModelFacade --> VocabularyMapping

The enum's five ordered stages (NASCENT through UNIFIED) are what lets the framework report federation maturity as a single comparable number.

Object Model Architecture¶

The object model is built on Python Protocols, allowing any project to plug into the unified API without inheriting from base classes:

┌──────────────────────────────────────────────────────┐
│                  Unified Query API                    │
│                  (ModelFacade)                        │
├─────────────┬─────────────┬─────────────┬───────────┤
│ FCC         │ CTO         │ AOME        │ Custom    │
│ Repository  │ Repository  │ Repository  │ Repos     │
└─────────────┴─────────────┴─────────────┴───────────┘

DomainEntity Protocol¶

Every queryable entity implements the DomainEntity protocol:

class DomainEntity(Protocol):
    @property
    def entity_id(self) -> str: ...
    @property
    def entity_type(self) -> str: ...
    @property
    def namespace(self) -> str: ...

RepositoryProtocol¶

Data stores implement the RepositoryProtocol[T]:

class RepositoryProtocol(Protocol[T]):
    def get(self, entity_id: str) -> T | None: ...
    def list_all(self) -> list[T]: ...
    def search(self, query: str) -> list[T]: ...
    def count(self) -> int: ...

ModelFacade¶

The ModelFacade abstract base class provides a high-level query interface that aggregates multiple repositories:

Method	Description
`stats()`	Summary statistics (entity count, type distribution)
`search(query)`	Full-text search across all repositories
`get_full(entity_id)`	Retrieve complete entity with all details
`by_type(entity_type)`	Filter by entity type

Vocabulary Mapping¶

When integrating systems with different terminologies, the VocabularyMapping frozen dataclass provides term translation:

from fcc.objectmodel.mapping import VocabularyMapping

mapping = VocabularyMapping(
    source_namespace="fcc",
    target_namespace="cto",
    term_mappings={
        "persona": "cto:Agent",
        "workflow": "cto:Process",
        "deliverable": "cto:Artifact",
    },
)

cto_term = mapping.translate("persona")  # "cto:Agent"

Evolution Stages¶

The EvolutionStage enum tracks how mature the object model integration is across projects:

Stage	Description
NASCENT	No integration; isolated data stores
MAPPED	Vocabulary mappings defined
BRIDGED	Adapter bridges operational
FEDERATED	Cross-project queries working
UNIFIED	Single query interface for all projects

CTO Bridge¶

For projects using the CTO ontology, the CTOFacadeAdapter provides seamless integration:

from fcc.objectmodel.cto_bridge import CTOFacadeAdapter, cto_available

if cto_available():
    adapter = CTOFacadeAdapter(cto_client)
    results = adapter.search("cloud storage")

When CTO is not installed, the bridge degrades gracefully with a mock adapter.

Cross-Project Assessment¶

The assess_cross_project() function evaluates integration health:

from fcc.objectmodel.federation import assess_cross_project

report = assess_cross_project(fcc_registry, cto_adapter, aome_catalog)
print(f"Alignment: {report.alignment_score:.0%}")
print(f"Gaps: {report.coverage_gaps}")

Lab Exercise¶

Lab 21.1: Load the FCC persona registry and wrap it in a ModelFacade. Query for all "data_engineering" personas and print their entity IDs.

Lab 21.2: Create a VocabularyMapping between FCC and a custom namespace. Translate 5 FCC terms and verify the results.

Lab 21.3: Use assess_cross_project() with mock data to generate an alignment report. Identify the dimensions with the lowest scores.

Summary¶

The object model provides protocol-based abstractions for cross- project entity access.
ModelFacade and RepositoryProtocol enable unified queries across FCC, CTO, AOME, and custom data stores.
VocabularyMapping handles term translation between namespaces.
EvolutionStage tracks integration maturity.
The CTO bridge demonstrates the pattern for adapting external ontologies into the unified model.