Regulatory Events & Impacts

Relevant source files

The following files were used as context for generating this wiki page:

• src/models/financial_models.py
• src/logic/asset_graph.py
• AI_RULES.md
• AUDIT_REPORT.md
• ARCHITECTURE.md
• CHANGELOG.md
• SUMMARY.md

Regulatory Events & Impacts track changes in the financial regulatory environment and model their quantitative effect on specific assets within the network. The system uses a specialized data model to categorize events (such as interest rate hikes or new compliance standards) and assigns an impact score that the AssetRelationshipGraph utilizes to build relationships between events and impacted financial instruments.

This module ensures that external shocks to the financial system are represented with the same structural integrity as internal asset relationships, allowing users to visualize how a single regulatory change propagates across different asset classes like Equities, Bonds, and Commodities.

Sources: CHANGELOG.md:73, ARCHITECTURE.md:143-154, AI_RULES.md:25-27

Data Modeling

The system defines regulatory activities and events using Python enum and dataclass structures to ensure type safety and consistent data definitions across the backend and visualization layers.

RegulatoryActivity Enum

The RegulatoryActivity enumeration categorizes the type of regulatory action. This ensures that visualization payloads and analysis algorithms can filter or color-code events based on their nature.

RegulatoryEvent Dataclass

The RegulatoryEvent dataclass serves as the primary model for representing a specific occurrence. It includes metadata for identification and numerical fields for impact modeling.

Field	Type	Description
id	str	Unique identifier for the event.
name	str	Human-readable name of the regulatory event.
date	str	Date of occurrence in ISO 8601 format.
activity_type	RegulatoryActivity	The category of the event (e.g., Rate Change, Tax Policy).
impact_score	float	Numerical impact ranging from -1.0 to 1.0.
description	str	Detailed textual description of the event.

Sources: AI_RULES.md:25-27, AUDIT_REPORT.md:35-37, SUMMARY.md:158

Validation Logic

The system enforces strict validation constraints during the initialization of regulatory data to maintain graph integrity. Validation occurs within the __post_init__ methods of the models.

• Impact Score Range: The impact_score must be a value between -1.0 (maximum negative impact) and 1.0 (maximum positive impact). Values outside this range trigger validation errors.
• Date Format: The date field must strictly follow the ISO 8601 format to ensure chronological sorting and timeline visualization in the UI.
• Identifier Integrity: All events must possess unique IDs to prevent deduplication errors when building the relationship graph.

Sources: AUDIT_REPORT.md:35-37, SUMMARY.md:158, AUDIT_REPORT.md:307

Relationship Building and Graph Integration

The AssetRelationshipGraph logic integrates regulatory events by treating them as distinct nodes that possess directed edges to affected assets.

The diagram shows how a raw impact score from a regulatory event is processed into a relationship edge within the asset network.

Sources: src/logic/asset_graph.py, ARCHITECTURE.md:152-154, AUDIT_REPORT.md:305-307

Impact Mapping Logic

When the system discovers relationships, it maps RegulatoryEvent objects to Asset objects based on defined business rules:

1. Direct Links: Events are explicitly linked to assets through a strength value derived from the impact_score.
2. Strength Clamping: The graph logic clamps all relationship strengths to a range of 0.0 to 1.0 for visualization consistency. A negative impact score still results in a positive relationship strength in the graph structure, but the metadata preserves the impact direction.
3. Deduplication: The graph builder identifies and removes duplicate event-to-asset links to prevent visual clutter and metric skewing.

Sources: AUDIT_REPORT.md:305-309, SUMMARY.md:162-167

Visualization and Analytics

Regulatory impacts are exposed to the user through the 3D network visualization and the metrics dashboard.

3D Visualization

The visualization layer uses deterministic positioning to place regulatory event nodes within the 3D space.

• Color Coding: Events are assigned distinct colors based on their RegulatoryActivity type to distinguish them from standard asset classes.
• Edge Traces: Interactive edges connect events to the assets they impact, with the line thickness or opacity representing the magnitude of the impact.

Metric Calculation

The system calculates aggregate metrics for regulatory events, including:

• Total Events: Count of active regulatory changes in the database.
• Average Impact: The mean impact score across all registered events.
• Relationship Density: The ratio of regulatory links to total possible asset links.

Sources: ARCHITECTURE.md:156-160, AUDIT_REPORT.md:308-310, CHANGELOG.md:105-108

System Data Flow

The flow of regulatory information follows the standard architectural path from ingestion to display.

Regulatory Events & Impacts provide a critical external dimension to the Financial Asset Relationship Database. By quantifying regulatory changes and mapping them to specific instruments, the system allows for sophisticated risk analysis and visual exploration of how legal and economic policy changes influence market relationships.

Sources: CHANGELOG.md:100-110, AUDIT_REPORT.md:30-34