Skip to content

FCC for Knowledge Engineers

Welcome to the For Knowledge Engineers section of the FCC Agent Team Framework documentation. This area is written for the people who turn subject-matter expertise into machine-readable vocabulary: knowledge engineers, taxonomists, ontologists, terminology leads, and data architects who cross into semantics.

If you want to write Python code against FCC, consult For Developers. If you run FCC, go to For Operators. This section is for the person building the RDF, mapping the FHIR concepts, or authoring the DCAT-US metadata.

Who This Section Is For

Your role

This section assumes you are responsible for one or more of the following:

  • Authoring vocabulary mappings that translate external ontologies into FCC's object model
  • Registering an FCC deployment under a cross-project federation namespace
  • Integrating a standard ontology (FHIR, FIBO, ACORD, NIEM, CIM, DCAT-US) into an FCC vertical project
  • Designing a RAG / GraphRAG pipeline that respects domain semantics
  • Serving as the authority that decides whether "Customer" in our domain equals "Party" in FIBO

If any of those fit, the four guides in this section will take you from "FCC has an object model" to "our 150-concept vocabulary is federated with ten peer projects and our RAG pipeline uses it as a grounding source."

Overview of Knowledge-Engineer Content

Guide Primary Audience When to Read
Vocabulary Provider Pattern Plugin authors, data architects Authoring a VocabularyProviderPlugin
Namespace Registration Federation leads Registering a new constellation project
Ontology Integration Ontologists Mapping an external standard into FCC
RAG Pipeline Guide Search architects Building a persona-aware retrieval pipeline

Each guide assumes familiarity with RDF/OWL/SKOS at an introductory level and prior exposure to at least one standard ontology (FHIR, FIBO, or equivalent).

The FCC Semantic Stack

flowchart TB
    Ext[External Ontologies<br/>FHIR / FIBO / ACORD / NIEM / CIM / DCAT-US]
    Ext --> VP[VocabularyProviderPlugin]
    VP --> OM[FCC Object Model<br/>src/fcc/objectmodel/]
    OM --> KG[Knowledge Graph<br/>src/fcc/knowledge/]
    OM --> Fed[Federation Registry<br/>src/fcc/federation/]
    KG --> RAG[RAG / GraphRAG<br/>src/fcc/rag/]
    Fed --> RAG
    RAG --> Personas[Persona-Aware<br/>Retrieval]

    classDef ext fill:#fff9c4,stroke:#f57f17;
    classDef fcc fill:#c8e6c9,stroke:#2e7d32;
    classDef out fill:#e3f2fd,stroke:#0d47a1;
    class Ext ext;
    class VP,OM,KG,Fed,RAG fcc;
    class Personas out;

Each layer has a dedicated guide in this section.

The 175 Packaged Vocabulary Mappings

FCC ships 175 YAML vocabulary mapping files under src/fcc/data/objectmodel/. These are the authoritative source-of-truth for cross-project entity resolution. Partial catalogue:

Project Mapping file
AOME aome_vocabulary_mappings.yaml
Athenium athenium_vocabulary_mappings.yaml
Caelum caelum_vocabulary_mappings.yaml
Columba columba_vocabulary_mappings.yaml
CONSTEL constel_vocabulary_mappings.yaml
Crater crater_vocabulary_mappings.yaml
Crucible crucible_vocabulary_mappings.yaml
Distiller distiller_vocabulary_mappings.yaml
Libra libra_vocabulary_mappings.yaml
Mnemosyne mnemosyne_vocabulary_mappings.yaml
Norma norma_vocabulary_mappings.yaml
Ophiuchus ophiuchus_vocabulary_mappings.yaml
PAOM paom_vocabulary_mappings.yaml
Pyxis pyxis_vocabulary_mappings.yaml
Scutum scutum_vocabulary_mappings.yaml
Sentinel sentinel_vocabulary_mappings.yaml
Serpens serpens_vocabulary_mappings.yaml
SkyParlour skyparlour_vocabulary_mappings.yaml
Vela vela_vocabulary_mappings.yaml

Knowledge engineers working on a downstream project can add a new YAML to this directory, author the matching VocabularyProviderPlugin, and the FCC federation registry will pick it up automatically. See Vocabulary Provider Pattern.

The 10 Constellation Projects

FCC v1.3.0 introduced vertical-project scaffolding and seeded 10 constellation-codename projects. Each is a reference implementation of a specific vertical domain:

Codename Vertical Ontology anchor
Ophiuchus Healthcare FHIR R5 + SNOMED CT
Serpens Healthcare research FHIR R5 + HL7 CDA
Libra Legal LKIF + LegalRuleML
Crater Insurance ACORD + ISO 12812
Scutum Government NIEM + DCAT-US
Norma Energy CIM (IEC 61970/61968)
Pyxis Finance FIBO + ISO 20022
Vela Retail GS1 + schema.org
Columba Transport CityGML + DATEX II
Caelum Climate / Earth ENVO + DCAT-US + OGC

Each carries a vocabulary mapping file in src/fcc/data/objectmodel/. Walk through Ontology Integration to see how external standards are adapted.

Quick-Start for Knowledge Engineers

Day 1 — Survey

  • Catalogue the 175 existing YAML mappings
  • Identify the external ontologies already covered
  • Locate any gaps relative to your domain

Day 2-3 — Author

  • Draft a new VocabularyProviderPlugin
  • Author the matching YAML mapping
  • Run fcc audit vocabulary --strict

Day 4 — Federate

  • Register your namespace in the federation registry
  • Verify cross-project entity resolution with a peer

Day 5 — Integrate

  • Wire the vocabulary into a RAG pipeline
  • Run a persona-aware retrieval test
  • Publish results as an OPEN-SCI-004b dataset card

Common Knowledge-Engineer Questions

What is the smallest vocabulary I can register?

A handful of concepts (5-10) is enough to exercise the plugin protocol. The athenium and mnemosyne providers (v1.2.1) each started with 8 concepts.

Must I write OWL? RDF? SKOS?

No. The YAML mapping file is the primary artefact. FCC will emit OWL/RDF/SKOS automatically via the serializers in src/fcc/knowledge/serializers.py.

How does entity resolution work across projects?

Each project has a namespace. A concept in namespace A can declare same_as / equivalent_to / broader_than relationships to concepts in namespace B. The EntityResolver in src/fcc/federation/resolver.py walks these links at query time.

Can I version a vocabulary?

Yes. Each vocabulary mapping carries a version field; the ChangeTracker in src/fcc/federation/tracker.py records every version bump and its diff.

Does the RAG pipeline understand my vocabulary?

Only if you make it so. The SemanticRetriever accepts an optional grounding vocabulary; when provided, retrieved chunks are filtered and re-ranked against concept boundaries. See RAG Pipeline Guide.

v1.4.x What's New for Knowledge Engineers

v1.4.x introduces the Zachman 6×6 cross-cut as a canonical framework primitive (v1.4.1), owned by the new ZCA (Zachman Classifier Agent) persona, with every FCC persona classified into exactly one cell. For knowledge engineers, this means a new classifier API (fcc.zachman.classify(persona_id)), a new zachman_cell attribute on every OTel span, and a new classified_as edge type in the evidence graph. v1.4.1 also adds the VDS (Vocabulary Drift Sentinel) persona monitoring SHA-256 parity across all 13+ VocabularyProviders.

Next Steps

  1. Writing your first plugin? → Vocabulary Provider Pattern
  2. Joining the federation? → Namespace Registration
  3. Mapping a standard ontology? → Ontology Integration
  4. Building retrieval? → RAG Pipeline Guide
  5. Classifying personas into Zachman cells? → Guidebook Ch. 35