Financial Asset Models

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
• app.py

Financial Asset Models define the core data structures used to represent financial instruments and their metadata within the relationship database. These models provide a type-safe hierarchy for assets such as Equities, Bonds, Commodities, and Currencies, ensuring data integrity through built-in validation rules.

The system uses these models to construct a complex network of relationships, enabling 3D visualizations and metrics analysis. Each model inherits from a base Asset class and includes specialized fields relevant to its specific asset class.

Sources: src/models/financial_models.py, AI_RULES.md, ARCHITECTURE.md

Core Data Structures

The project implements data models using Python dataclasses and enums. This approach ensures structured data definitions and type safety across the backend and frontend components.

Asset Class Hierarchy

All financial instruments derive from the base Asset class. This class contains universal identifiers and common market data. Specialized classes extend this base to include attributes unique to their market segment.

The diagram shows the inheritance structure where specialized assets inherit core attributes from the base Asset class.
Sources: src/models/financial_models.py:1-120, AUDIT_REPORT.md

Enumerations

The system uses the Enum module to restrict values for asset categories and regulatory activities.

Enum Name	Purpose	Values
AssetClass	Categorizes the instrument type	EQUITY, BOND, COMMODITY, CURRENCY, DERIVATIVE
RegulatoryActivity	Categorizes compliance events	INVESTIGATION, FINE, NEW_REGULATION, RATE_CHANGE

Sources: src/models/financial_models.py:10-25, AI_RULES.md

Model Validation Logic

The models include self-validation logic within the __post_init__ method. This ensures that any instance created in the AssetRelationshipGraph contains valid financial data before processing.

Validation Rules

The system enforces the following constraints during model initialization:

• Price Validation: Validates that the price field is non-negative.
• Currency Code Validation: Ensures currency codes follow the 3-letter ISO format.
• Impact Score Validation: Restricts regulatory impact scores to a range between -1 and 1.
• Date Format Validation: Checks that dates conform to ISO 8601 standards.

Sources: AUDIT_REPORT.md, src/models/financial_models.py

Integration with Asset Graph

The AssetRelationshipGraph consumes these models to identify links between instruments. The graph logic uses model attributes (like sector or asset_class) to determine relationship types and strengths.

Relationship Discovery Flow

When the system builds relationships, it iterates through asset instances and applies discovery rules based on model data.

The flow describes how asset model attributes trigger the creation of specific relationship types in the graph.
Sources: src/logic/asset_graph.py, CHANGELOG.md, ARCHITECTURE.md

Specialized Asset Attributes

Each specialized model contains fields that facilitate specific financial analyses, such as income comparison or risk mapping.

Asset Model	Key Fields	Analytical Purpose
Equity	pe_ratio, dividend_yield	Used for sector affinity and income comparison.
Bond	yield_to_maturity, duration	Enables yield curve analysis and corporate link mapping.
Commodity	spot_price, unit	Used to calculate commodity exposure for related equities.
Currency	exchange_rate, code	Facilitates currency risk mapping across the network.

Sources: src/models/financial_models.py, CHANGELOG.md

Code Example: Equity Model Implementation

@dataclass
class Equity(Asset):
    pe_ratio: float = 0.0
    dividend_yield: float = 0.0
    eps: float = 0.0

    def __post_init__(self):
        super().__post_init__()
        if self.pe_ratio < 0:
            self.pe_ratio = 0.0

Sources: src/models/financial_models.py:75-85, AUDIT_REPORT.md

Summary of Significance

Financial Asset Models serve as the foundational schema for the entire database. By defining strict structures for different asset classes, the models enable the AssetRelationshipGraph to automate the discovery of complex links. These definitions directly support the 3D visualizations in the Gradio UI and the analytical metrics displayed in the dashboard.

Sources: ARCHITECTURE.md, app.py, AI_RULES.md