# x512/getfactormodels architecture

> Architecture diagram of the GitHub repository x512/getfactormodels, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/x512/getfactormodels
- Repository: https://github.com/x512/getfactormodels

## Overview

getfactormodels is a Python library and CLI for retrieving financial factor-model data, portfolio sorts, and anomaly datasets. Users request a model or dataset, the API/CLI constructs the appropriate source implementation, which retrieves and parses provider data into Arrow tables for filtering, combining, and export. The graph preserves documented model families and the portfolio/anomaly branches. Some subsystem links are documented only at package level; unsampled implementations are represented by their exact tree paths, and uncertain call links are omitted.

Main entry points: [`src/getfactormodels/models/base.py`](https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/models/base.py) (Model lifecycle), [`src/getfactormodels/main.py`](https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/main.py) (Python API), [`src/getfactormodels/models/q_factors.py`](https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/models/q_factors.py) (Global-Q models), [`src/getfactormodels/models/ff_portfolios.py`](https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/models/ff_portfolios.py) (FF portfolio sorts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_api["Python API<br/>[main.py]"]
  node_cli["Command-line interface<br/>[cli.py]"]
end

subgraph group_models["Data products"]
  node_ff["Fama–French factors<br/>[fama_french.py]"]
  node_aqr["AQR factors<br/>[aqr_models.py]"]
  node_qfactors["Global-Q models<br/>[q_factors.py]"]
  node_jkp["JKP anomalies<br/>[jkp.py]"]
  node_other_models["Other factor families"]
  node_ff_sorts["FF portfolio sorts<br/>[ff_portfolios.py]"]
  node_ff_breakpoints["FF breakpoints<br/>[ff_breakpoints.py]"]
  node_industries["Industry portfolios<br/>[ff_industries.py]"]
end

subgraph group_catalog["Model catalog"]
  node_registry["Model registry<br/>[model_registry.py]"]
  node_q_registry["Q dataset catalog<br/>[_q.py]"]
  node_jkp_registry["JKP dataset catalog<br/>[_jkp.py]"]
end

subgraph group_runtime["Retrieval and processing"]
  node_base["Model lifecycle<br/>[base.py]"]
  node_http["HTTP retrieval<br/>[http_client.py]"]
  node_cache[("Download cache<br/>[cache.py]")]
  node_arrow["Arrow processing<br/>[arrow_utils.py]"]
  node_dates["Date processing<br/>[date_utils.py]"]
end

node_python(("Python user"))
node_cli_user(("CLI user"))
node_providers["Dataset providers"]
node_arrow_result["Arrow tables"]
node_output["File or dataframe"]

node_python -->|"requests data"| node_api
node_cli_user -->|"submits options"| node_cli
node_cli -->|"constructs requests"| node_api
node_api -->|"resolves models"| node_registry
node_api -->|"constructs sorts"| node_ff_sorts
node_api -->|"constructs industries"| node_industries
node_api -->|"constructs Q models"| node_qfactors
node_registry -->|"uses catalog"| node_q_registry
node_registry -->|"uses catalog"| node_jkp_registry
node_ff -->|"extends lifecycle"| node_base
node_aqr -->|"extends lifecycle"| node_base
node_qfactors -->|"extends lifecycle"| node_base
node_jkp -->|"extends lifecycle"| node_base
node_other_models -.->|"shares lifecycle"| node_base
node_ff_sorts -->|"extends portfolio base"| node_base
node_ff_sorts -->|"uses breakpoints"| node_ff_breakpoints
node_base -->|"retrieves data"| node_http
node_http -->|"reads and writes"| node_cache
node_ff -->|"downloads from"| node_providers
node_aqr -->|"downloads from"| node_providers
node_qfactors -->|"downloads from"| node_providers
node_base -->|"processes tables"| node_arrow
node_base -->|"normalizes dates"| node_dates
node_qfactors -->|"resolves dataset slugs"| node_q_registry
node_jkp -->|"uses factor catalog"| node_jkp_registry
node_api -->|"returns datasets"| node_arrow_result
node_arrow_result -->|"exports or converts"| node_output

click node_api "https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/main.py"
click node_cli "https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/utils/cli.py"
click node_base "https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/models/base.py"
click node_registry "https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/registry/model_registry.py"
click node_ff "https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/models/fama_french.py"
click node_aqr "https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/models/aqr_models.py"
click node_qfactors "https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/models/q_factors.py"
click node_jkp "https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/models/jkp.py"
click node_other_models "https://github.com/x512/getfactormodels/tree/main/src/getfactormodels/models"
click node_ff_sorts "https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/models/ff_portfolios.py"
click node_ff_breakpoints "https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/models/ff_breakpoints.py"
click node_industries "https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/models/ff_industries.py"
click node_q_registry "https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/registry/_q.py"
click node_jkp_registry "https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/registry/_jkp.py"
click node_http "https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/utils/http_client.py"
click node_cache "https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/utils/cache.py"
click node_arrow "https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/utils/arrow_utils.py"
click node_dates "https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/utils/date_utils.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_cli,node_python,node_cli_user toneBlue
class node_ff,node_aqr,node_qfactors,node_jkp,node_other_models,node_ff_sorts,node_ff_breakpoints,node_industries toneAmber
class node_registry,node_q_registry,node_jkp_registry toneMint
class node_base,node_http,node_cache,node_arrow,node_dates toneRose
class node_providers,node_arrow_result,node_output toneIndigo
```

## Components

### User entry points

- [Python API](https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/main.py): `src/getfactormodels/main.py`
- [Command-line interface](https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/utils/cli.py): `src/getfactormodels/utils/cli.py`

### Data products

- [Fama–French factors](https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/models/fama_french.py): `src/getfactormodels/models/fama_french.py`
- [AQR factors](https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/models/aqr_models.py): `src/getfactormodels/models/aqr_models.py`
- [Global-Q models](https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/models/q_factors.py): `src/getfactormodels/models/q_factors.py`
- [JKP anomalies](https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/models/jkp.py): `src/getfactormodels/models/jkp.py`
- [Other factor families](https://github.com/x512/getfactormodels/tree/main/src/getfactormodels/models): `src/getfactormodels/models`
- [FF portfolio sorts](https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/models/ff_portfolios.py): `src/getfactormodels/models/ff_portfolios.py`
- [FF breakpoints](https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/models/ff_breakpoints.py): `src/getfactormodels/models/ff_breakpoints.py`
- [Industry portfolios](https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/models/ff_industries.py): `src/getfactormodels/models/ff_industries.py`

### Model catalog

- [Model registry](https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/registry/model_registry.py): `src/getfactormodels/registry/model_registry.py`
- [Q dataset catalog](https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/registry/_q.py): `src/getfactormodels/registry/_q.py`
- [JKP dataset catalog](https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/registry/_jkp.py): `src/getfactormodels/registry/_jkp.py`

### Retrieval and processing

- [Model lifecycle](https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/models/base.py): `src/getfactormodels/models/base.py`
- [HTTP retrieval](https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/utils/http_client.py): `src/getfactormodels/utils/http_client.py`
- [Download cache](https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/utils/cache.py): `src/getfactormodels/utils/cache.py`
- [Arrow processing](https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/utils/arrow_utils.py): `src/getfactormodels/utils/arrow_utils.py`
- [Date processing](https://github.com/x512/getfactormodels/blob/main/src/getfactormodels/utils/date_utils.py): `src/getfactormodels/utils/date_utils.py`

### Other components

- **Python user**
- **CLI user**
- **Dataset providers**
- **Arrow tables**
- **File or dataframe**

## Connections

- Python user → Python API: requests data (evidence: `README.md`)
- CLI user → Command-line interface: submits options (evidence: `README.md`)
- Command-line interface → Python API: constructs requests (evidence: `src/getfactormodels/utils/cli.py`)
- Python API → Model registry: resolves models (evidence: `src/getfactormodels/main.py`)
- Python API → FF portfolio sorts: constructs sorts (evidence: `src/getfactormodels/main.py`)
- Python API → Industry portfolios: constructs industries (evidence: `src/getfactormodels/main.py`)
- Python API → Global-Q models: constructs Q models (evidence: `src/getfactormodels/main.py`)
- Model registry → Q dataset catalog: uses catalog
- Model registry → JKP dataset catalog: uses catalog
- Fama–French factors → Model lifecycle: extends lifecycle (evidence: `src/getfactormodels/models/fama_french.py`)
- AQR factors → Model lifecycle: extends lifecycle (evidence: `src/getfactormodels/models/aqr_models.py`)
- Global-Q models → Model lifecycle: extends lifecycle (evidence: `src/getfactormodels/models/q_factors.py`)
- JKP anomalies → Model lifecycle: extends lifecycle (evidence: `src/getfactormodels/models/jkp.py`)
- Other factor families → Model lifecycle: shares lifecycle (evidence: `src/getfactormodels/models/q_factors.py`)
- FF portfolio sorts → Model lifecycle: extends portfolio base (evidence: `src/getfactormodels/models/ff_portfolios.py`)
- FF portfolio sorts → FF breakpoints: uses breakpoints (evidence: `src/getfactormodels/models/ff_portfolios.py`)
- Model lifecycle → HTTP retrieval: retrieves data (evidence: `src/getfactormodels/models/base.py`)
- HTTP retrieval → Download cache: reads and writes (evidence: `src/getfactormodels/utils/http_client.py`)
- Fama–French factors → Dataset providers: downloads from (evidence: `README.md`)
- AQR factors → Dataset providers: downloads from (evidence: `README.md`)
- Global-Q models → Dataset providers: downloads from (evidence: `README.md`)
- Model lifecycle → Arrow processing: processes tables (evidence: `src/getfactormodels/models/base.py`)
- Model lifecycle → Date processing: normalizes dates (evidence: `src/getfactormodels/models/base.py`)
- Global-Q models → Q dataset catalog: resolves dataset slugs (evidence: `src/getfactormodels/models/q_factors.py`)
- JKP anomalies → JKP dataset catalog: uses factor catalog (evidence: `src/getfactormodels/models/jkp.py`)
- Python API → Arrow tables: returns datasets (evidence: `README.md`)
- Arrow tables → File or dataframe: exports or converts (evidence: `README.md`)
