# cetirzine/elucidator architecture

> Architecture diagram of the GitHub repository cetirzine/elucidator, 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/cetirzine/elucidator
- Repository: https://github.com/cetirzine/elucidator

## Overview

Elucidator is a minimal, auditable A-share news-factor research scaffold, not a completed trading system. Its implemented path covers point-in-time news contracts and optional LLM event extraction; the README and execution plan describe a broader research workflow whose modeling, ranking, backtesting, and paper-trading components are not present in the sampled runtime source. Edges for that broader workflow reflect documented design, not inspected implementations.

Main entry points: [`src/elucidator/llm.py`](https://github.com/cetirzine/elucidator/blob/main/src/elucidator/llm.py) (News extractor), [`docs/EXECUTION_PLAN.zh-CN.md`](https://github.com/cetirzine/elucidator/blob/main/docs/EXECUTION_PLAN.zh-CN.md) (OOF features), [`src/elucidator/contracts.py`](https://github.com/cetirzine/elucidator/blob/main/src/elucidator/contracts.py) (Event factors), [`src/elucidator/settings.py`](https://github.com/cetirzine/elucidator/blob/main/src/elucidator/settings.py) (Runtime settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs and contracts"]
  node_market_data["Market data"]
  node_news_data["News data"]
  node_timing_contract["Timing contract<br/>[contracts.py]"]
  node_research_config["Research config<br/>[research.yaml]"]
  node_settings["Runtime settings<br/>[settings.py]"]
end

subgraph group_extraction["News extraction"]
  node_news_extractor["News extractor<br/>[llm.py]"]
  node_deepseek{{"DeepSeek API"}}
  node_event_factors["Event factors<br/>[contracts.py]"]
end

subgraph group_research["Model research"]
  node_prophet_baseline["Prophet baseline"]
  node_shared_lstm["Shared LSTM"]
  node_oof_features["OOF features"]
  node_xgboost_ranker["XGBoost ranker"]
end

subgraph group_validation["Evaluation and controls"]
  node_backtest["Cost backtest"]
  node_robustness["Robustness audit"]
  node_paper_acceptance["Paper acceptance"]
  node_preflight["Environment preflight<br/>[preflight.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"configures"| node_research_config
node_market_data -.->|"checks timing"| node_timing_contract
node_news_data -.->|"checks timing"| node_timing_contract
node_news_data -.->|"provides articles"| node_news_extractor
node_settings -->|"configures"| node_news_extractor
node_news_extractor -->|"requests extraction"| node_deepseek
node_news_extractor -->|"validates output"| node_event_factors
node_market_data -.->|"informs baseline"| node_prophet_baseline
node_market_data -.->|"informs representation"| node_shared_lstm
node_prophet_baseline -.->|"contributes predictions"| node_oof_features
node_shared_lstm -.->|"contributes predictions"| node_oof_features
node_event_factors -.->|"joins features"| node_oof_features
node_oof_features -.->|"ranks factors"| node_xgboost_ranker
node_xgboost_ranker -.->|"evaluates strategy"| node_backtest
node_backtest -.->|"feeds audit"| node_robustness
node_robustness -.->|"supports acceptance"| node_paper_acceptance
node_researcher -->|"checks environment"| node_preflight

click node_market_data "https://github.com/cetirzine/elucidator/blob/main/docs/EXECUTION_PLAN.zh-CN.md"
click node_news_data "https://github.com/cetirzine/elucidator/blob/main/docs/EXECUTION_PLAN.zh-CN.md"
click node_timing_contract "https://github.com/cetirzine/elucidator/blob/main/src/elucidator/contracts.py"
click node_research_config "https://github.com/cetirzine/elucidator/blob/main/configs/research.yaml"
click node_settings "https://github.com/cetirzine/elucidator/blob/main/src/elucidator/settings.py"
click node_news_extractor "https://github.com/cetirzine/elucidator/blob/main/src/elucidator/llm.py"
click node_event_factors "https://github.com/cetirzine/elucidator/blob/main/src/elucidator/contracts.py"
click node_prophet_baseline "https://github.com/cetirzine/elucidator/blob/main/docs/EXECUTION_PLAN.zh-CN.md"
click node_shared_lstm "https://github.com/cetirzine/elucidator/blob/main/docs/EXECUTION_PLAN.zh-CN.md"
click node_oof_features "https://github.com/cetirzine/elucidator/blob/main/docs/EXECUTION_PLAN.zh-CN.md"
click node_xgboost_ranker "https://github.com/cetirzine/elucidator/blob/main/docs/EXECUTION_PLAN.zh-CN.md"
click node_backtest "https://github.com/cetirzine/elucidator/blob/main/docs/EXECUTION_PLAN.zh-CN.md"
click node_robustness "https://github.com/cetirzine/elucidator/blob/main/docs/EXECUTION_PLAN.zh-CN.md"
click node_paper_acceptance "https://github.com/cetirzine/elucidator/blob/main/docs/EXECUTION_PLAN.zh-CN.md"
click node_preflight "https://github.com/cetirzine/elucidator/blob/main/src/elucidator/preflight.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_market_data,node_news_data,node_timing_contract,node_research_config,node_settings toneBlue
class node_news_extractor,node_deepseek,node_event_factors toneAmber
class node_prophet_baseline,node_shared_lstm,node_oof_features,node_xgboost_ranker toneMint
class node_backtest,node_robustness,node_paper_acceptance,node_preflight toneRose
class node_researcher toneIndigo
```

## Components

### Inputs and contracts

- [Market data](https://github.com/cetirzine/elucidator/blob/main/docs/EXECUTION_PLAN.zh-CN.md): `docs/EXECUTION_PLAN.zh-CN.md`
- [News data](https://github.com/cetirzine/elucidator/blob/main/docs/EXECUTION_PLAN.zh-CN.md): `docs/EXECUTION_PLAN.zh-CN.md`
- [Timing contract](https://github.com/cetirzine/elucidator/blob/main/src/elucidator/contracts.py): `src/elucidator/contracts.py`
- [Research config](https://github.com/cetirzine/elucidator/blob/main/configs/research.yaml): `configs/research.yaml`
- [Runtime settings](https://github.com/cetirzine/elucidator/blob/main/src/elucidator/settings.py): `src/elucidator/settings.py`

### News extraction

- [News extractor](https://github.com/cetirzine/elucidator/blob/main/src/elucidator/llm.py): `src/elucidator/llm.py`
- **DeepSeek API**
- [Event factors](https://github.com/cetirzine/elucidator/blob/main/src/elucidator/contracts.py): `src/elucidator/contracts.py`

### Model research

- [Prophet baseline](https://github.com/cetirzine/elucidator/blob/main/docs/EXECUTION_PLAN.zh-CN.md): `docs/EXECUTION_PLAN.zh-CN.md`
- [Shared LSTM](https://github.com/cetirzine/elucidator/blob/main/docs/EXECUTION_PLAN.zh-CN.md): `docs/EXECUTION_PLAN.zh-CN.md`
- [OOF features](https://github.com/cetirzine/elucidator/blob/main/docs/EXECUTION_PLAN.zh-CN.md): `docs/EXECUTION_PLAN.zh-CN.md`
- [XGBoost ranker](https://github.com/cetirzine/elucidator/blob/main/docs/EXECUTION_PLAN.zh-CN.md): `docs/EXECUTION_PLAN.zh-CN.md`

### Evaluation and controls

- [Cost backtest](https://github.com/cetirzine/elucidator/blob/main/docs/EXECUTION_PLAN.zh-CN.md): `docs/EXECUTION_PLAN.zh-CN.md`
- [Robustness audit](https://github.com/cetirzine/elucidator/blob/main/docs/EXECUTION_PLAN.zh-CN.md): `docs/EXECUTION_PLAN.zh-CN.md`
- [Paper acceptance](https://github.com/cetirzine/elucidator/blob/main/docs/EXECUTION_PLAN.zh-CN.md): `docs/EXECUTION_PLAN.zh-CN.md`
- [Environment preflight](https://github.com/cetirzine/elucidator/blob/main/src/elucidator/preflight.py): `src/elucidator/preflight.py`

### Other components

- **Researcher**

## Connections

- Researcher → Research config: configures (evidence: `README.md`)
- Market data → Timing contract: checks timing (evidence: `README.md`)
- News data → Timing contract: checks timing (evidence: `README.md`)
- News data → News extractor: provides articles (evidence: `README.md`)
- Runtime settings → News extractor: configures (evidence: `src/elucidator/llm.py`)
- News extractor → DeepSeek API: requests extraction (evidence: `src/elucidator/llm.py`)
- News extractor → Event factors: validates output (evidence: `src/elucidator/llm.py`)
- Market data → Prophet baseline: informs baseline (evidence: `README.md`)
- Market data → Shared LSTM: informs representation (evidence: `README.md`)
- Prophet baseline → OOF features: contributes predictions (evidence: `README.md`)
- Shared LSTM → OOF features: contributes predictions (evidence: `README.md`)
- Event factors → OOF features: joins features (evidence: `README.md`)
- OOF features → XGBoost ranker: ranks factors (evidence: `README.md`)
- XGBoost ranker → Cost backtest: evaluates strategy (evidence: `README.md`)
- Cost backtest → Robustness audit: feeds audit (evidence: `README.md`)
- Robustness audit → Paper acceptance: supports acceptance (evidence: `README.md`)
- Researcher → Environment preflight: checks environment (evidence: `README.md`)