# biyihan2005/alpha_research_agent architecture

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

- Interactive diagram: https://gitdiagram.com/biyihan2005/alpha_research_agent
- Repository: https://github.com/biyihan2005/alpha_research_agent
- Video tour (about a minute): https://gitdiagram.com/biyihan2005/alpha_research_agent/video

## Overview

Alpha Research Agent structures quantitative factor research from inspiration and hypotheses through constrained formula validation, local data evaluation, experiment memory, and reporting. The graph preserves the documented provider, DSL, evaluation-metric, and optional publishing capabilities. Relationships are based on the README workflow and shown source references; unsampled implementation details are not treated as verified call paths.

Main entry points: [`alpha_agent/llm/base.py`](https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/llm/base.py) (LLM Interface), [`alpha_agent/inspiration/retriever.py`](https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/inspiration/retriever.py) (Idea Retriever), [`alpha_agent/agents/hypothesis_agent.py`](https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/agents/hypothesis_agent.py) (Hypothesis Agent), [`alpha_agent/agents/formula_agent.py`](https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/agents/formula_agent.py) (Formula Agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_research["Research Ideation"]
  node_retriever["Idea Retriever<br/>[retriever.py]"]
  node_idea["Idea Cards<br/>[idea_card.py]"]
  node_hypothesis["Hypothesis Agent"]
  node_formula_agent["Formula Agent<br/>[formula_agent.py]"]
  node_critique["Critique Agent<br/>[critique_agent.py]"]
end

subgraph group_compute["Formula and Data"]
  node_validator["DSL Validator<br/>[validator.py]"]
  node_parser["Formula Parser<br/>[parser.py]"]
  node_catalog["Dataset Catalog<br/>[catalog.py]"]
  node_provider["Data Providers"]
  node_loader["Panel Loader<br/>[loader.py]"]
end

subgraph group_evaluate["Evaluation and Memory"]
  node_evaluator["Factor Evaluator<br/>[evaluator.py]"]
  node_quality["Quality Gate<br/>[quality_gate.py]"]
  node_memory[("Experiment Memory<br/>[factor_store.py]")]
end

subgraph group_outputs["Reporting and Integration"]
  node_report["Research Report<br/>[report_agent.py]"]
  node_feishu["Feishu CLI<br/>[feishu_cli.py]"]
end

subgraph group_models["LLM Clients"]
  node_llm_interface["LLM Interface<br/>[base.py]"]
  node_mock_llm["Mock LLM<br/>[mock_client.py]"]
  node_deepseek["DeepSeek Client<br/>[deepseek_client.py]"]
end

node_researcher(("Researcher"))
node_deepseek_api["DeepSeek API"]

node_researcher -->|"provides goal"| node_retriever
node_retriever -->|"builds cards"| node_idea
node_retriever -->|"informs"| node_hypothesis
node_hypothesis -->|"guides formulas"| node_formula_agent
node_hypothesis -->|"generates with"| node_llm_interface
node_formula_agent -->|"generates with"| node_llm_interface
node_critique -->|"generates with"| node_llm_interface
node_mock_llm -->|"implements"| node_llm_interface
node_deepseek -->|"implements"| node_llm_interface
node_deepseek -->|"requests completions"| node_deepseek_api
node_formula_agent -->|"submits formulas"| node_validator
node_validator -.->|"validates before evaluation"| node_parser
node_catalog -->|"registers providers"| node_provider
node_provider -->|"normalizes data"| node_loader
node_provider -->|"supplies panel"| node_evaluator
node_validator -->|"passes valid formulas"| node_evaluator
node_evaluator -->|"submits metrics"| node_quality
node_quality -->|"stores accepted results"| node_memory
node_memory -->|"provides experiment records"| node_report
node_report -.->|"publishes optionally"| node_feishu

click node_retriever "https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/inspiration/retriever.py"
click node_idea "https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/inspiration/idea_card.py"
click node_hypothesis "https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/agents/hypothesis_agent.py"
click node_formula_agent "https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/agents/formula_agent.py"
click node_critique "https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/agents/critique_agent.py"
click node_llm_interface "https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/llm/base.py"
click node_mock_llm "https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/llm/mock_client.py"
click node_deepseek "https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/llm/deepseek_client.py"
click node_validator "https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/dsl/validator.py"
click node_parser "https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/dsl/parser.py"
click node_catalog "https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/datasets/catalog.py"
click node_provider "https://github.com/biyihan2005/alpha_research_agent/tree/main/alpha_agent/datasets/providers"
click node_loader "https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/data/loader.py"
click node_evaluator "https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/evaluation/evaluator.py"
click node_quality "https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/evaluation/quality_gate.py"
click node_memory "https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/memory/factor_store.py"
click node_report "https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/agents/report_agent.py"
click node_feishu "https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/integrations/feishu_cli.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_retriever,node_idea,node_hypothesis,node_formula_agent,node_critique toneBlue
class node_validator,node_parser,node_catalog,node_provider,node_loader toneAmber
class node_evaluator,node_quality,node_memory,node_deepseek_api toneMint
class node_report,node_feishu toneRose
class node_llm_interface,node_mock_llm,node_deepseek,node_researcher toneIndigo
```

## Components

### Research Ideation

- [Idea Retriever](https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/inspiration/retriever.py): `alpha_agent/inspiration/retriever.py`
- [Idea Cards](https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/inspiration/idea_card.py): `alpha_agent/inspiration/idea_card.py`
- [Hypothesis Agent](https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/agents/hypothesis_agent.py): `alpha_agent/agents/hypothesis_agent.py`
- [Formula Agent](https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/agents/formula_agent.py): `alpha_agent/agents/formula_agent.py`
- [Critique Agent](https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/agents/critique_agent.py): `alpha_agent/agents/critique_agent.py`

### Formula and Data

- [DSL Validator](https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/dsl/validator.py): `alpha_agent/dsl/validator.py`
- [Formula Parser](https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/dsl/parser.py): `alpha_agent/dsl/parser.py`
- [Dataset Catalog](https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/datasets/catalog.py): `alpha_agent/datasets/catalog.py`
- [Data Providers](https://github.com/biyihan2005/alpha_research_agent/tree/main/alpha_agent/datasets/providers): `alpha_agent/datasets/providers`
- [Panel Loader](https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/data/loader.py): `alpha_agent/data/loader.py`

### Evaluation and Memory

- [Factor Evaluator](https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/evaluation/evaluator.py): `alpha_agent/evaluation/evaluator.py`
- [Quality Gate](https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/evaluation/quality_gate.py): `alpha_agent/evaluation/quality_gate.py`
- [Experiment Memory](https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/memory/factor_store.py): `alpha_agent/memory/factor_store.py`

### Reporting and Integration

- [Research Report](https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/agents/report_agent.py): `alpha_agent/agents/report_agent.py`
- [Feishu CLI](https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/integrations/feishu_cli.py): `alpha_agent/integrations/feishu_cli.py`

### LLM Clients

- [LLM Interface](https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/llm/base.py): `alpha_agent/llm/base.py`
- [Mock LLM](https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/llm/mock_client.py): `alpha_agent/llm/mock_client.py`
- [DeepSeek Client](https://github.com/biyihan2005/alpha_research_agent/blob/main/alpha_agent/llm/deepseek_client.py): `alpha_agent/llm/deepseek_client.py`

### Other components

- **Researcher**
- **DeepSeek API**

## Connections

- Researcher → Idea Retriever: provides goal (evidence: `README.md`)
- Idea Retriever → Idea Cards: builds cards (evidence: `alpha_agent/inspiration/retriever.py`)
- Idea Retriever → Hypothesis Agent: informs (evidence: `README.md`)
- Hypothesis Agent → Formula Agent: guides formulas (evidence: `README.md`)
- Hypothesis Agent → LLM Interface: generates with (evidence: `alpha_agent/agents/hypothesis_agent.py`)
- Formula Agent → LLM Interface: generates with (evidence: `alpha_agent/agents/formula_agent.py`)
- Critique Agent → LLM Interface: generates with (evidence: `alpha_agent/agents/critique_agent.py`)
- Mock LLM → LLM Interface: implements (evidence: `alpha_agent/llm/mock_client.py`)
- DeepSeek Client → LLM Interface: implements (evidence: `alpha_agent/llm/deepseek_client.py`)
- DeepSeek Client → DeepSeek API: requests completions (evidence: `alpha_agent/llm/deepseek_client.py`)
- Formula Agent → DSL Validator: submits formulas (evidence: `README.md`)
- DSL Validator → Formula Parser: validates before evaluation (evidence: `alpha_agent/dsl/parser.py`)
- Dataset Catalog → Data Providers: registers providers (evidence: `alpha_agent/datasets/catalog.py`)
- Data Providers → Panel Loader: normalizes data (evidence: `alpha_agent/datasets/providers/sample_provider.py`)
- Data Providers → Factor Evaluator: supplies panel (evidence: `README.md`)
- DSL Validator → Factor Evaluator: passes valid formulas (evidence: `README.md`)
- Factor Evaluator → Quality Gate: submits metrics (evidence: `README.md`)
- Quality Gate → Experiment Memory: stores accepted results (evidence: `README.md`)
- Experiment Memory → Research Report: provides experiment records (evidence: `README.md`)
- Research Report → Feishu CLI: publishes optionally (evidence: `README.md`)