Relationship Assertions & Projections
Relevant source files
The following files were used as context for generating this wiki page:
Relationship Assertions and Projections constitute the core data and logic framework for managing connections between financial instruments. Assertions represent the raw, declarative links identified between assets (e.g., sector membership or corporate ownership), while Projections represent the derived mathematical and visual state of the network used for 3D rendering and metric analysis.
The system ensures that every financial link is validated against domain-specific rules before it persists. This separation of concerns allows the project to maintain a durable record of historical assertions while dynamically regenerating projections for interactive visualizations.
Architecture and Data Flow
The system processes financial data through a pipeline that starts with raw asset ingestion and ends with persistent, visualized graph data.
The diagram shows the sequential flow from raw data ingestion to the creation of persistent projections.
Sources: ARCHITECTURE.md:120-155, AUDIT_REPORT.md:25-45
Relationship Assertion Discovery
The discovery layer identifies links between assets based on shared attributes or explicit financial dependencies. The system evaluates factors such as sector affinity, corporate structures, and commodity exposure to create these assertions.
- Sector Affinity: Identifies assets within the same industry sector.
- Corporate Links: Maps relationships between corporate bonds and their underlying equities.
- Currency/Commodity Risk: Links assets to the specific currencies or commodities that impact their valuation.
- Income Comparison: Evaluates relationships based on dividend yields versus fixed-income durations.
Sources: CHANGELOG.md:85-95, ARCHITECTURE.md:135-145
Data Models and Schemas
The project utilizes structured data models to enforce type safety and validation for all assertions. Assertions are categorized by type and assigned a "strength" score between 0 and 1.
Core Asset Models
| Asset Class | Key Metadata | Validation Rules |
|---|---|---|
| Equity | P/E Ratio, Dividend Yield, EPS | Prices must be non-negative |
| Bond | Yield, Duration, Credit Rating | ISO 4217 Currency Code (3 letters) |
| Commodity | Futures, Spot Prices | Impact score must be between -1 and 1 |
| Currency | Exchange Rates | ISO 8601 Date Formats |
Sources: AUDIT_REPORT.md:30-45, CHANGELOG.md:75-80
Relationship Schema
Relationships are modeled as directional edges in a graph. Each assertion contains a source asset, a target asset, a relationship type, and a calculated strength.
This diagram illustrates the relationship between raw assets, their assertions, and the resulting projections.
Sources: src/data/relationship_assertion_schema.py, ARCHITECTURE.md:150-165
Projection Generation and Persistence
Projections transform assertions into spatial and statistical data. This process is deterministic to ensure consistency across different user sessions.
Visualization Projections
The projection engine calculates 3D coordinates for every asset. It uses a fixed seed (seed=42) to maintain static positions in the 3D network graph, allowing users to track asset movements relative to stable benchmarks.
Sources: AUDIT_REPORT.md:50-55, ARCHITECTURE.md:45-60
Durable Persistence
Durable graph persistence is a gating dependency for system promotion. The system maintains compatibility with SQLite for local development while supporting larger-scale persistence for recovery and disaster mitigation.
- Idempotency: All projection updates must be idempotent to prevent partial failure states.
- Durable Records: Graph state must persist across restarts to support multi-instance behavior.
- Lock Management: Persistence operations utilize context managers with a maximum TTL of 300 seconds to prevent resource starvation.
Sources: GEMINI.md:20-55, src/data/relationship_projection_persistence.py
Logic and Validation
The system enforces strict invariants to maintain the integrity of assertions and projections.
- Strength Clamping: All relationship strengths are automatically clamped to a [0.0, 1.0] range.
- Deterministic Back-off: Database acquisition for assertions uses a deterministic back-off strategy with a 30-second ceiling.
- Validation Gate: The
__post_init__methods in dataclasses validate input ranges for P/E ratios and impact scores before assertions are committed to the repository.
Sources: AUDIT_REPORT.md:35-42, GEMINI.md:25-30
Key Repository Functions
_find_relationships(): Scans the asset database to discover potential assertions.build_rel(): Constructs a formal relationship object with a calculated weight.get_3d_viz(): Projects the relationship graph into a 3D coordinate space for the frontend.get_metrics(): Derives network density and average degree metrics from current projections.
Sources: ARCHITECTURE.md:40-55, src/data/relationship_assertion_repository.py
Summary
The Relationship Assertions & Projections system provides the foundation for the financial network analysis. By separating raw assertion data from derived projections, the system ensures data integrity and high-performance visualization. Durable persistence and strict validation rules maintain the reliability of the graph, supporting both non-production Gradio demos and production FastAPI/Next.js workflows.