API Reference: Cross-Reference¶

Full Python API documentation for the cross-reference module at fcc.personas.cross_reference.

Module Location¶

src/fcc/personas/cross_reference.py

CrossReferenceEntry¶

A frozen dataclass representing a single interaction between two personas.

Fields¶

Field	Type	Default	Description
`source_id`	`str`	(required)	Persona ID of the sender (e.g., `"RC"`, `"RCHM"`)
`target_id`	`str`	(required)	Persona ID of the receiver (e.g., `"BC"`, `"DE"`)
`relationship_type`	`str`	(required)	One of: `"handoff"`, `"feedback"`, `"coordination"`, `"governance"`, `"champion-of"`
`interaction`	`str`	(required)	Human-readable description of what is exchanged
`strength`	`str`	`"primary"`	`"primary"` (blocking/critical) or `"secondary"` (supporting)

CrossReferenceEntry.from_dict()¶

Construct an entry from a dictionary.

from fcc.personas.cross_reference import CrossReferenceEntry

data = {
    "source_id": "RC",
    "target_id": "BC",
    "relationship_type": "handoff",
    "interaction": "Delivers research inventory; clarifies context",
    "strength": "primary",
}

entry = CrossReferenceEntry.from_dict(data)
print(entry.source_id)    # "RC"
print(entry.target_id)    # "BC"
print(entry.strength)     # "primary"

Parameters:

Parameter	Type	Description
`data`	`dict`	Dictionary with keys matching field names. `strength` is optional (defaults to `"primary"`).

Returns: CrossReferenceEntry

Raises: KeyError if source_id, target_id, relationship_type, or interaction is missing.

CrossReferenceEntry.to_dict()¶

Serialize an entry to a dictionary.

entry = CrossReferenceEntry(
    source_id="DE",
    target_id="BC",
    relationship_type="feedback",
    interaction="Returns standards and edits on blueprints",
    strength="primary",
)

d = entry.to_dict()
print(d)
# {
#     "source_id": "DE",
#     "target_id": "BC",
#     "relationship_type": "feedback",
#     "interaction": "Returns standards and edits on blueprints",
#     "strength": "primary",
# }

Returns: dict with all five fields.

Immutability¶

CrossReferenceEntry is a frozen dataclass. Attempting to modify fields after construction raises FrozenInstanceError.

entry = CrossReferenceEntry.from_dict({...})
entry.strength = "secondary"  # Raises FrozenInstanceError

CrossReferenceMatrix¶

A queryable container of CrossReferenceEntry objects. Supports construction from YAML, from a PersonaRegistry, or programmatic assembly.

Constructor¶

matrix = CrossReferenceMatrix(entries=None)

Parameter	Type	Default	Description
`entries`	`list[CrossReferenceEntry] \| None`	`None`	Initial list of entries. `None` creates an empty matrix.

Construction Methods¶

CrossReferenceMatrix.from_yaml()¶

Load cross-reference entries from a YAML file. This is the primary construction method for the authoritative matrix.

from fcc.personas.cross_reference import CrossReferenceMatrix

matrix = CrossReferenceMatrix.from_yaml("data/personas/cross_reference.yaml")
print(len(matrix))  # 106

Parameters:

Parameter	Type	Description
`path`	`str \| Path`	Path to a YAML file with a `cross_references` key containing a list of entry dicts.

Returns: CrossReferenceMatrix

YAML format:

cross_references:
  - source_id: RC
    target_id: BC
    relationship_type: handoff
    interaction: Delivers research inventory; clarifies context
    strength: primary
  # ... more entries

CrossReferenceMatrix.from_personas()¶

Auto-generate cross-reference entries from a PersonaRegistry by reading each persona's collaboration field.

from fcc.personas.registry import PersonaRegistry
from fcc.personas.cross_reference import CrossReferenceMatrix

registry = PersonaRegistry.from_yaml_directory("data/personas/")
auto_matrix = CrossReferenceMatrix.from_personas(registry)
print(len(auto_matrix))  # Varies based on collaboration fields

Parameters:

Parameter	Type	Description
`registry`	`PersonaRegistry`	A loaded persona registry.

Returns: CrossReferenceMatrix

Direction-to-type mapping:

Collaboration direction	Relationship type
`"downstream"`	`"handoff"`
`"upstream"`	`"feedback"`
`"both"`	`"coordination"`
`"peer"`	`"coordination"`

All auto-generated entries have strength="primary".

Query Methods¶

upstream()¶

Return entries where the given persona is the target (incoming interactions).

# Who sends work to BC?
incoming = matrix.upstream("BC")
for entry in incoming:
    print(f"  {entry.source_id} -> BC [{entry.relationship_type}]")

Parameters:

Parameter	Type	Description
`persona_id`	`str`	The persona ID to query.

Returns: list[CrossReferenceEntry] -- entries where target_id == persona_id.

downstream()¶

Return entries where the given persona is the source (outgoing interactions).

# Where does RC send its output?
outgoing = matrix.downstream("RC")
for entry in outgoing:
    print(f"  RC -> {entry.target_id} [{entry.relationship_type}]")

Parameters:

Parameter	Type	Description
`persona_id`	`str`	The persona ID to query.

Returns: list[CrossReferenceEntry] -- entries where source_id == persona_id.

peers()¶

Return entries involving the given persona with coordination relationship type.

# Who coordinates with UG?
coord = matrix.peers("UG")
for entry in coord:
    other = entry.target_id if entry.source_id == "UG" else entry.source_id
    print(f"  UG <-> {other}")

Parameters:

Parameter	Type	Description
`persona_id`	`str`	The persona ID to query.

Returns: list[CrossReferenceEntry] -- entries where (source_id == persona_id or target_id == persona_id) and relationship_type == "coordination".

by_type()¶

Return all entries of a given relationship type.

# All governance relationships
gov = matrix.by_type("governance")
print(f"Governance entries: {len(gov)}")

# All champion-of relationships
champs = matrix.by_type("champion-of")
print(f"Champion-of entries: {len(champs)}")  # 4

Parameters:

Parameter	Type	Description
`relationship_type`	`str`	The relationship type to filter by.

Returns: list[CrossReferenceEntry]

between()¶

Return entries between two specific personas. Directional: only returns entries from source_id to target_id.

# Direct links from BCHM to BC
entries = matrix.between("BCHM", "BC")
for entry in entries:
    print(f"  [{entry.relationship_type}] {entry.interaction}")

Output:

  [champion-of] Champions and elevates the Blueprint Crafter persona
  [handoff] Orchestrates core blueprint creation

Parameters:

Parameter	Type	Description
`source_id`	`str`	Source persona ID.
`target_id`	`str`	Target persona ID.

Returns: list[CrossReferenceEntry] -- entries where both source_id and target_id match.

Note: To find entries in both directions, call between(A, B) and between(B, A) separately.

all_persona_ids()¶

Return all unique persona IDs referenced in the matrix (as source or target).

ids = matrix.all_persona_ids()
print(f"Unique persona IDs: {len(ids)}")  # 24
print(sorted(ids))

Returns: set[str]

Mutation Methods¶

add()¶

Append a single entry to the matrix.

from fcc.personas.cross_reference import CrossReferenceEntry

new_entry = CrossReferenceEntry(
    source_id="APT",
    target_id="BV",
    relationship_type="handoff",
    interaction="Submits test results for quality validation",
    strength="primary",
)
matrix.add(new_entry)
print(len(matrix))  # 107

Parameters:

Parameter	Type	Description
`entry`	`CrossReferenceEntry`	The entry to add.

Returns: None (mutates the matrix in place).

Note: add() does not check for duplicates. Use merge_with_precedence() if deduplication is needed.

merge()¶

Create a new matrix combining entries from both matrices (simple concatenation).

matrix_a = CrossReferenceMatrix.from_yaml("data/personas/cross_reference.yaml")
matrix_b = CrossReferenceMatrix(entries=[new_entry])

combined = matrix_a.merge(matrix_b)
print(len(combined))  # len(a) + len(b)

Parameters:

Parameter	Type	Description
`other`	`CrossReferenceMatrix`	The matrix to merge with.

Returns: CrossReferenceMatrix -- a new matrix. Neither self nor other is modified.

Note: merge() does not deduplicate. Duplicate entries will appear in the result. Use merge_with_precedence() for deduplication.

merge_with_precedence()¶

Merge two matrices, preferring entries from self on key conflicts. The key is (source_id, target_id, relationship_type).

yaml_matrix = CrossReferenceMatrix.from_yaml("data/personas/cross_reference.yaml")
auto_matrix = CrossReferenceMatrix.from_personas(registry)

# YAML entries win on key conflicts
combined = yaml_matrix.merge_with_precedence(auto_matrix)

Parameters:

Parameter	Type	Description
`other`	`CrossReferenceMatrix`	The lower-precedence matrix.

Returns: CrossReferenceMatrix -- a new matrix. Neither self nor other is modified.

Conflict resolution: When both matrices have an entry with the same (source_id, target_id, relationship_type), the entry from self is kept. Entries from other are added only when the key does not already exist in self.

# Example: YAML has a curated description, auto has a generic one
# Key: ("RC", "BC", "handoff")
# YAML: "Delivers research inventory; clarifies context"
# Auto: "downstream interaction"
# Result: YAML entry is kept

Serialization¶

to_yaml()¶

Write cross-reference entries to a YAML file.

matrix.to_yaml("output/cross_reference.yaml")

Parameters:

Parameter	Type	Description
`path`	`str \| Path`	Output file path.

Returns: None

Output format: Identical to the input format expected by from_yaml().

entries (property)¶

Return a copy of the internal entries list.

all_entries = matrix.entries  # list[CrossReferenceEntry]
print(len(all_entries))

Returns: list[CrossReferenceEntry] -- a new list (modifying it does not affect the matrix).

Dunder Methods¶

len()¶

print(len(matrix))  # 106

iter()¶

for entry in matrix:
    print(f"{entry.source_id} -> {entry.target_id}")

Iterates directly over the internal entries list.

Usage Patterns¶

Pattern: Build a Complete Matrix from Multiple Sources¶

from fcc.personas.cross_reference import CrossReferenceMatrix, CrossReferenceEntry
from fcc.personas.registry import PersonaRegistry

# 1. Load authoritative YAML
yaml_matrix = CrossReferenceMatrix.from_yaml("data/personas/cross_reference.yaml")

# 2. Auto-generate from registry
registry = PersonaRegistry.from_yaml_directory("data/personas/")
auto_matrix = CrossReferenceMatrix.from_personas(registry)

# 3. Add custom entries
custom = CrossReferenceMatrix([
    CrossReferenceEntry("APT", "BV", "handoff", "Submits test results", "primary"),
])

# 4. Merge with precedence: YAML > auto > custom
combined = yaml_matrix.merge_with_precedence(auto_matrix)
combined = combined.merge_with_precedence(custom)

print(f"Final matrix: {len(combined)} entries, {len(combined.all_persona_ids())} personas")

Pattern: Filter and Analyze¶

# Find all primary handoffs
primary_handoffs = [
    e for e in matrix
    if e.relationship_type == "handoff" and e.strength == "primary"
]
print(f"Primary handoffs: {len(primary_handoffs)}")

# Find personas with the most upstream connections
from collections import Counter

upstream_counts = Counter()
for entry in matrix:
    upstream_counts[entry.target_id] += 1

most_connected = upstream_counts.most_common(5)
for pid, count in most_connected:
    print(f"  {pid}: {count} upstream entries")

Pattern: Round-Trip Serialization¶

# Load -> modify -> save
matrix = CrossReferenceMatrix.from_yaml("data/personas/cross_reference.yaml")
matrix.add(CrossReferenceEntry("NEW", "BC", "handoff", "New entry", "primary"))
matrix.to_yaml("data/personas/cross_reference.yaml")

# Verify round-trip
reloaded = CrossReferenceMatrix.from_yaml("data/personas/cross_reference.yaml")
assert len(reloaded) == len(matrix)

Performance Notes¶

O(n) queries: All query methods (upstream, downstream, peers, by_type, between) perform linear scans over the entries list. For the current 106-entry matrix this is instantaneous.
Scaling: For matrices significantly beyond 1000 entries, consider building index dicts (keyed by source_id, target_id, or relationship_type) in a subclass for O(1) lookups.
Memory: Each CrossReferenceEntry is a frozen dataclass with 5 string fields. 106 entries consume negligible memory.
merge_with_precedence: Uses a set of (source_id, target_id, relationship_type) tuples for O(1) conflict detection.

CrossReferenceMatrix Specification -- Full data model and interaction tables
Cross-Reference Quick Reference -- Compact lookup card
Contributing Cross-References -- How to add entries to the YAML file
Source code

API Reference: Cross-Reference¶

Module Location¶

CrossReferenceEntry¶

Fields¶

CrossReferenceEntry.from_dict()¶

CrossReferenceEntry.to_dict()¶

Immutability¶

CrossReferenceMatrix¶

Constructor¶

Construction Methods¶

CrossReferenceMatrix.from_yaml()¶

CrossReferenceMatrix.from_personas()¶

Query Methods¶

upstream()¶

downstream()¶

peers()¶

by_type()¶

between()¶

all_persona_ids()¶

Mutation Methods¶

add()¶

merge()¶

merge_with_precedence()¶

Serialization¶

to_yaml()¶

entries (property)¶

Dunder Methods¶

__len__()¶

__iter__()¶

Usage Patterns¶

Pattern: Build a Complete Matrix from Multiple Sources¶

Pattern: Filter and Analyze¶

Pattern: Round-Trip Serialization¶

Performance Notes¶

Related¶

len()¶

iter()¶