Relationship Graph Engine
Relevant source files
The following files were used as context for generating this wiki page:
The Relationship Graph Engine manages financial assets and their interconnected dependencies. It provides the core business logic for constructing network topologies, discovering relationships based on business rules, and calculating network analytics for various asset classes including Equities, Bonds, Commodities, and Currencies.
Sources: ARCHITECTURE.md, src/logic/asset_graph.py, src/reports/schema_report_generator.py:73-83
Core Architecture
The engine functions as the central logic layer between data ingestion and visualization. It maintains an internal graph structure where assets represent nodes and relationships represent edges.
The diagram shows the data flow from ingestion sources into the core Logic Layer for relationship construction and subsequent output generation.
Sources: ARCHITECTURE.md
Key Components
| Component | Responsibility |
|---|---|
AssetRelationshipGraph | Manages the collection of assets and provides methods for graph manipulation and metric calculation. |
Relationship Discovery | Automatically identifies links between assets based on sector affinity and corporate linkages. |
Metric Calculator | Computes network density, average relationship strength, and asset class distributions. |
3D Viz Generator | Produces deterministic coordinate data for rendering interactive network visualizations. |
Sources: src/logic/asset_graph.py, ARCHITECTURE.md, src/reports/schema_report_generator.py:108-124
Relationship Discovery Logic
The engine identifies relationships by applying specific business rules across the asset pool. Relationships are categorized as either bidirectional or directional depending on the rule type.
Business Rules for Linkage
- Sector Affinity: Assets within the same industry sector receive a bidirectional link.
- Corporate Linkage: Bonds with an
issuer_idmatching an equity asset receive a directional link from the bond to the equity. - Event Propagation: Regulatory or earnings events create directional edges to all affected assets.
- Currency Exposure: FX pairs and central bank policy changes link to relevant regional assets.
Sources: src/reports/schema_report.py:195-212, CHANGELOG.md:83-93, src/reports/schema_report_generator.py:155-170
Strength and Scoring
Relationship strengths are normalized to a range between 0 and 1. Impact scores, typically derived from regulatory events, are normalized between -1 and +1 to indicate negative or positive sentiment.
The flow demonstrates the process of identifying relationship types and applying normalization to the resulting edges.
Sources: src/reports/schema_report.py:230-238, AUDIT_REPORT.md:44-50
Network Metrics and Analytics
The engine calculates statistical data to describe the graph's overall health and connectivity. These metrics are accessible via the calculate_metrics() method.
Calculated Statistics
- Network Density: The ratio of actual relationships to the total number of possible relationships.
- Average Relationship Strength: The mean value of all edge weights in the graph.
- Asset Class Distribution: A breakdown of the total asset count by type (Equity, Bond, etc.).
- Relationship Distribution: Counts of specific relationship types (e.g.,
same_sector,corporate_bond_to_equity).
Sources: src/reports/schema_report_generator.py:108-124, src/reports/schema_report.py:118-145
Schema Optimization Recommendations
Based on the Relationship Density, the engine provides automated recommendations:
- Density > 30%: Recommends normalization due to high connectivity.
- Density 10% - 30%: Considered well-balanced and optimal for analysis.
- Density < 10%: Considered sparse; recommends enriching relationship definitions.
Sources: src/reports/schema_report.py:177-190, src/reports/schema_report_generator.py:175-201
Visualization Data Generation
The engine generates data structures specifically for 3D network visualizations. It uses a deterministic positioning algorithm to ensure that the layout remains consistent across refreshes if the underlying data does not change.
The sequence shows the interaction between the UI and the Graph Engine to produce 3D coordinates and styling for the network visualization.
Sources: ARCHITECTURE.md, AUDIT_REPORT.md:27-33
Summary
The Relationship Graph Engine provides the computational foundation for the Financial Asset Relationship Database. By automating relationship discovery and normalizing connectivity metrics, the engine enables complex financial network analysis and interactive visualization across disparate asset classes.
Sources: ARCHITECTURE.md, AUDIT_REPORT.md