How hajinhyukson/aat works
AAT ingests point-in-time market, macro, factor, and filing data; preserves source snapshots and promotes normalized records; selects security universes and runs attribution backfills; then exposes contribution, residual, evidence, and run summaries through an API and dashboard. The engine includes factor and event evidence, return accounting, residual diagnostics, and confidence scoring. README documents major stages and backfill behavior; sampled source verifies selected adapter, ingestion, database, API, and dashboard links. Unsampled job internals and several subsystem connections are therefore represented only where documented.
Main entry points: jobs Backfill orchestration · contracts.py Attribution contracts · main.py Attribution API · models.py Canonical records
Components 22
Sources and ingestion
- FMP prices
adapters/fmp/client.py - FRED macro
adapters/fred/client.py - French factors
adapters/french/client.py - EDGAR filings
adapters/sec_edgar/client.py - Import jobs
jobs
Canonical data
- Snapshot staging
jobs - Universe and identity
db/models.py - Canonical records
db/models.py - Database sessions
db/session.py
Attribution methodology
- Backfill orchestration
jobs - Return accounting
engine/returns/accounting.py - Factor models
engine/factors - Event evidence
engine/events - Exposure decisions
engine/exposures - Attribution contracts
engine/contracts.py - Residual diagnostics
engine/attribution/diagnostics.py - Confidence scoring
engine/confidence/scoring.py
API and dashboard
- Attribution API
api/main.py - Dashboard
dashboard/app/page.tsx - Dashboard API proxy
dashboard/app/api/aat/[...path]/route.ts
Other components
- Analyst
- External sources
Connections 30
- External sources → FMP prices: provides prices
- External sources → FRED macro: provides macro data
- External sources → French factors: provides factors
- External sources → EDGAR filings: provides filings
- FMP prices → Import jobs: fetches prices
jobs/ingest_fmp_prices.py - FRED macro → Import jobs: fetches observations
jobs/ingest_fred_macro.py - French factors → Import jobs: fetches factor rows
jobs/ingest_french_factors.py - EDGAR filings → Import jobs: fetches submissions
jobs/ingest_edgar_submissions.py - Import jobs → Snapshot staging: preserves snapshots
- Import jobs → Canonical records: promotes records
jobs/ingest_fmp_prices.py - Import jobs → Universe and identity: builds membership
jobs/ingest_fmp_prices.py - Database sessions → Canonical records: commits records
jobs/ingest_fmp_prices.py - Universe and identity → Backfill orchestration: selects securities
jobs/ingest_fmp_prices.py - Canonical records → Backfill orchestration: provides attribution inputs
jobs/ingest_fmp_prices.py - Backfill orchestration → Return accounting: runs windows
- Backfill orchestration → Factor models: computes contributions
- Backfill orchestration → Event evidence: uses event evidence
- Backfill orchestration → Exposure decisions: uses mappings
- Return accounting → Attribution contracts: forms results
engine/returns/accounting.py - Factor models → Attribution contracts: emits contributions
engine/factors/hierarchical_model.py - Event evidence → Attribution contracts: supplies evidence
engine/events/taxonomy.py - Exposure decisions → Attribution contracts: gates updates
engine/exposures/gates.py - Attribution contracts → Residual diagnostics: evaluates residuals
engine/attribution/diagnostics.py - Attribution contracts → Confidence scoring: scores confidence
engine/confidence/scoring.py - Backfill orchestration → Canonical records: stores attribution
jobs/ingest_fmp_prices.py - Analyst → Attribution API: requests results
- Attribution API → Database sessions: queries records
api/main.py - Attribution API → Residual diagnostics: formats diagnostics
api/main.py - Attribution API → Dashboard API proxy: serves requests
- Dashboard API proxy → Dashboard: forwards API data
dashboard/app/api/aat/[...path]/route.ts