# my-quant-lab

**Repository Path**: llm-lab/my-quant-lab

## Basic Information

- **Project Name**: my-quant-lab
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-14
- **Last Updated**: 2026-03-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

这是一份为你量身定制的、完整且专业的 `README.md`。它不仅涵盖了基础的项目说明，还深度融入了我们刚刚构建的 **“防止数据幻觉 + 多智能体链式辩论”** 的前沿量化架构。

你可以直接复制以下所有内容，**完全覆盖**你目前的 `README.md` 文件：

```markdown
# 🚀 A-Share ETF Quant Lab (AI 多智能体量化投研实验室)

基于 A 股核心行业 ETF 的量化研究与 **AI 多智能体 (Multi-Agent)** 投研流水线。

本项目致力于探索前沿的 **LLM + Quant** 架构：通过 Python 计算严谨的底层量化因子（动量、波动率、乖离率、RSI 等），将纯客观的数据切片喂给由大语言模型（LLM）驱动的**虚拟投研委员会**，通过“投研分析师 - 首席风控官 - 基金经理”的链式辩论，输出具备严格风控底线的实盘交易策略。

---

## 🌟 核心特性 (Features)

1. **🚫 零数据幻觉 (Zero Hallucination)**：AI 的所有推理均基于 `pandas` 计算的真实量化指标（如 20日动量、14日RSI、20日乖离率、量价异动），严禁大模型凭空捏造基本面或技术指标。
2. **🤖 链式多智能体辩论 (Multi-Agent Debate)**：
   * 🐂 **投研分析师 (Researcher)**：追踪动量突破，寻找全市场最强主线（进攻）。
   * 🐻 **首席风控官 (Risk Control)**：盯防高波动、高拥挤度与技术超买（防守）。
   * ⚖️ **基金经理 (PM)**：综合下属研报，结合账户可用资金与基金底线纪律，进行最终的仓位拍板。
3. **📊 全息市场记忆 (Memory System)**：系统每天自动生成包含多维因子的 Markdown 市场切片，作为 AI 的长期/短期记忆库，支持复盘与逻辑连贯性追踪。

---

## 📂 项目结构 (Project Structure)

```text
my-quant-lab/
├── data/                    # 本地数据中心
│   ├── raw/                 # 原始数据（同步的最新 ETF 日线行情）
│   └── processed/           # 因子计算结果（动量排名、防守因子集）
├── memory/                  # AI 智能体记忆库
│   ├── short_term/          # 每日市场切片 (含全息量化因子)
│   ├── long_term/           # 各模型角色的历史研报与推演过程
│   └── soul.md              # 基金全局不可逾越的底线纪律
├── src/                     # 核心代码库
│   ├── __init__.py
│   ├── sync_data.py         # 行情数据同步模块
│   ├── analyze.py           # 🚀 顶层调度：多智能体链式辩论流水线
│   ├── factors/             # 量化因子计算模块
│   │   ├── __init__.py
│   │   ├── momentum.py      # 进攻因子 (20日/60日动量)
│   │   └── volatility.py    # 防守因子 (波动率、RSI、BIAS、量价异动)
│   └── agent/               # 大模型多智能体核心模块
│       ├── __init__.py
│       ├── llm_client.py    # LLM API 接口调用 (支持多模型轮询)
│       ├── memory_io.py     # 记忆管家：DataFrame 与 Markdown 转换
│       ├── reasoning.py     # 智能体推理与角色扮演引擎
│       └── builder.py       # 智能体 Prompt 加载器
├── config/                  # 配置文件
│   ├── settings.yaml        # 日期区间、数据源配置等
│   ├── etf_pool.csv         # ETF 池与行业映射（覆盖宽基/周期/科技/消费等）
│   └── agents/              # 各 AI 角色的核心系统设定 (Prompt)
├── reports/                 # 自动生成的每日投研会议纪要汇总
├── logs/                    # 系统运行日志
├── doc/                     # 核心参考资源与前沿学术论文 (mlfinlab, ISL等)
├── pyproject.toml           # Python 依赖与包管理配置
└── README.md                # 项目说明文档

```

---

## 🛠️ 环境与依赖 (Installation)

* **Python**: `>= 3.12`
* **包管理工具**: [uv](https://github.com/astral-sh/uv) (极速的 Python 包管理器)

核心依赖组件：

* 数据处理：`pandas`, `numpy`
* AI 交互：`openai`
* 工程框架：`loguru`, `pyyaml`, `tqdm`

### 1. 克隆与初始化环境

```bash
# 同步并安装所有依赖
uv sync

```

### 2. 配置环境变量

在项目根目录创建 `.env` 文件，并填入你的大模型 API Key（如 OpenAI、DeepSeek 或 Claude）：

```env
OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"
OPENAI_BASE_URL="[https://api.openai.com/v1](https://api.openai.com/v1)"

```

---

## 🚀 快速开始 (Quick Start)

完整的每日运行流水线分为两步：**拉取数据** -> **召开投研会议**。

### Step 1: 下载与同步最新行情数据

每日收盘后运行，系统会根据 `config/etf_pool.csv` 获取所有标的的最新日线数据并落盘至 `data/raw/`：

```bash
PYTHONPATH=src uv run src/sync_data.py

```

### Step 2: 启动多智能体量化投研流水线

此脚本将自动计算所有的进攻与防守因子，合并全息数据，并依次唤醒投研分析师、风控官和基金经理进行链式辩论：

```bash
PYTHONPATH=src uv run src/analyze.py

```

> 💡 **提示**: 运行结束后，系统会自动在 `reports/` 目录下生成一份以时间戳命名的完整《A股 ETF 量化投研会议纪要》，您可以直接审阅 AI 的最终调仓指令。

### (可选) 探索性研究

如果您想手动调参或进行数据探索，可启动 Jupyter Lab：

```bash
uv run jupyter lab

```

---

## 📚 研究与迭代指南 (Development Workflow)

若要对本系统的策略进行升级，推荐遵循以下流程：

1. **因子升维**：在 `src/factors/` 中编写新的因子脚本（如北向资金流入、成分股财报预期等），并在 `analyze.py` 中拼接到 `df_combined` 中。
2. **人设调优**：修改 `config/agents/` 下的 Markdown 文件。例如，如果你发现风控官不够敏感，可以在 `risk_control.md` 中强制要求它“当 RSI > 75 且 20日乖离率 > 8% 时，必须拉响清仓红色警报”。
3. **底线约束**：修改 `memory/soul.md`，这是整个基金的宪法。你可以在这里规定单只 ETF 最大持仓不超过 15%，或大盘破位时必须保留 50% 现金。

---

## 📈 当前状态与路线图 (Status & Roadmap)

* [x] **基础架构**: `uv` 环境配置与多维底层 ETF 资产池构建完毕。
* [x] **数据管道**: 离线/在线历史日线行情同步通畅 (`sync_data.py`)。
* [x] **量化感知层**: 动量 (Momentum)、波动率 (Volatility)、乖离率 (BIAS)、相对强弱 (RSI)、量价异动因子已完成 Pandas 向量化计算。
* [x] **认知与决策层**: 实现了“无数据幻觉”的 Agentic Reasoning，链式辩论流水线正式上线。
* [ ] **执行层 (Next)**: 解析 PM 最终输出的 JSON 交易指令，生成具体的虚拟账户买卖账单 (Portfolio Tracking)。
* [ ] **评估层 (Next)**: 引入 `Vectorized Backtesting` 引擎，验证 AI 投研委员会的历史胜率与最大回撤。

```

```