Reconciliation Engine
Relevant source files
The following files were used as context for generating this wiki page:
The Reconciliation Engine manages the alignment and synchronization of financial asset data within the relationship graph. It identifies discrepancies between the internal graph state and external financial data sources, ensuring that asset relationships, strengths, and metrics reflect the most current market information. This engine is a core component of the business logic layer, operating alongside the AssetRelationshipGraph to maintain data integrity.
Within the project architecture, the Reconciliation Engine facilitates the transition from raw financial data acquisition (via yfinance) to structured relationship modeling. It utilizes a RebuildExecutor to handle the physical updates to the graph while the engine itself focuses on the logic of identifying drift and required state changes.
Sources: CHANGELOG.md, AUDIT_REPORT.md, PR_181_COMPLETION_REPORT.md
Core Architecture and Components
The reconciliation system follows a decoupled architecture where the logic for evaluation is separated from the execution of graph rebuilds. This separation allows the system to assess "drift"—the difference between current and expected states—before committing expensive computational resources to graph restructuring.
Data Flow and Logic
The engine monitors incoming market data and compares it against the existing nodes and edges in the AssetRelationshipGraph. When the RebuildDriftEvaluator detects that metrics such as relationship strength or asset prices have deviated beyond configured thresholds, it triggers a reconciliation event.
The diagram shows the flow from market data acquisition to the final graph update, highlighting the evaluation gate.
Sources: CHANGELOG.md, AUDIT_REPORT.md
Relationship Discovery and Alignment
The engine validates that every asset relationship adheres to defined business rules. It specifically reconciles five primary relationship categories to ensure the graph accurately represents market dependencies.
| Relationship Type | Discovery Logic | Metric Impact |
|---|---|---|
| Sector Affinity | Matches assets within the same industry sector. | same_sector strength (e.g., 0.7) |
| Corporate Links | Connects corporate bonds to their parent equity. | corporate_bond_to_equity |
| Commodity Exposure | Links equities to related commodities. | commodity_exposure |
| Currency Risk | Maps assets to their respective trading currencies. | currency_risk |
| Income Comparison | Compares dividend yields vs bond yields. | dividend_vs_yield |
Sources: CHANGELOG.md, AUDIT_REPORT.md
Strength Clamping and Deduplication
During reconciliation, the engine enforces a "strength clamping" policy. All relationship strengths are normalized to a range between 0 and 1. If a calculation results in a value outside this range, the engine forces the value to the nearest boundary. Additionally, the engine identifies and removes duplicate edges between the same asset pairs to prevent metric inflation.
Sources: AUDIT_REPORT.md, SUMMARY.md
Reconciliation Loop and Drift Evaluation
The ReconciliationLoop provides the execution heartbeat for the engine. It periodically invokes the RebuildDriftEvaluator to check for specific conditions that require a graph refresh.
Evaluation Criteria
The engine considers the following factors when determining if a reconciliation is necessary:
- Price Volatility: Significant changes in asset prices that impact income comparison metrics.
- Regulatory Events: New
RegulatoryEvententries with impact scores that modify relationship weights. - Temporal Drift: Scheduled intervals to ensure the graph does not become stale.
Sequence of events during a standard reconciliation check.
Sources: src/logic/asset_graph.py, CHANGELOG.md, AUDIT_REPORT.md
Configuration and Constraints
The engine uses centralized settings managed via pydantic-settings (located in src/config/settings.py). These parameters define how the engine interacts with the environment and the thresholds for reconciliation.
- Connection Strengths: Hardcoded values (e.g., 0.7 for sector affinity) have been removed in favor of parameterized configurations.
- Concurrency: Lock context managers within the engine have a maximum Time-To-Live (TTL) of 300 seconds to prevent deadlocks during graph updates.
- Persistence: The engine supports SQLite for local persistence, ensuring that the reconciled state survives application restarts.
Sources: CHANGELOG.md, GEMINI.md
Integration with Asset Models
The Reconciliation Engine relies on the validation logic embedded within the financial dataclasses. When the engine attempts to reconcile a node, the __post_init__ methods of the Asset subclasses (Equity, Bond, Commodity, Currency) validate data integrity, such as ISO currency codes or non-negative prices.
Sources: src/models/financial_models.py, AUDIT_REPORT.md
Summary
The Reconciliation Engine provides the necessary logic to keep the Financial Asset Relationship Database synchronized with real-world market dynamics. By utilizing a drift-evaluation strategy and a decoupled execution model, the engine maintains high performance while ensuring that the 3D visualizations and metric dashboards accurately reflect current asset interdependencies. Its adherence to strict validation rules and centralized configuration makes it a critical component for production-ready financial analysis.