使用说明

🏦 对冲基金多代理平台

一个用于对冲基金风格分析和交易的模块化、多代理Python平台。每个“代理”都是一个独立的模块，处理一个问题；中央控制器协调整个管道。

✨ 平台架构

┌─────────────────────────────────────────────────────────────────────────┐
│                         Streamlit Dashboard                             │
│  Overview │ Technical │ Strategy │ Research │ Risk │ Backtest │ Compare │
└─────────────────────────────┬───────────────────────────────────────────┘
                              │
                ┌─────────────▼──────────────┐
                │   controller_hedge_fund.py  │
                │      (Orchestrator)         │
                └─┬───┬───┬───┬───┬───┬──────┘
                  │   │   │   │   │   │
     ┌────────────┘   │   │   │   │   └─────────────┐
     ▼                ▼   ▼   ▼   ▼                  ▼
 MarketData    Strategy  Risk  Backtest  CompanyResearch
   Agent        Agent   Agent  Agent        Agent
     │            │       │      │            │
     ▼            ▼       ▼      ▼            ▼
 NewsSentiment  Execution  LLMResearch  AlternativeData
   Agent          Agent      Agent          Agent
     │                                        │
     │            ┌───────────────┐            │
     └───────────►│ utils_market  │◄───────────┘
                  │  data.py      │
                  └───────────────┘

🧩 代理

代理人	文件	责任
市场数据代理	`agents/market_data_agent.py`	通过yfinance获取OHLCV数据（股票、加密货币、外汇、指数）
战略代理	`agents/strategy_agent.py`	生成买入/卖出/持有信号（组合、动量、均值回归、趋势跟踪）
公司研究代理	`agents/company_research_agent.py`	基础知识、评分、同行比较、新闻
风险代理	`agents/risk_agent.py`	风险价值、夏普、头寸规模、交易验证
备份测试代理	`agents/backtest_agent.py`	历史模拟，包括权益曲线、胜率、回撤
执行代理人	`agents/execution_agent.py`	通过市场、限价、止损限价单进行纸面/实时交易
新闻情感代理	`agents/news_sentiment_agent.py`	FinBERT推动了金融新闻头条的情绪
LLM研究代理	`agents/llm_research_agent.py`	人工智能生成的研究总结（OpenAI/模板回退）
替代数据代理	`agents/alternative_data_agent.py`	美国证券交易委员会文件、内幕交易、机构持有人、社会情绪
投资组合优化器	`agents/portfolio_optimizer.py`	马科维茨，风险平价，布莱克·利特曼，再平衡
先进的反向测试	`agents/advanced_backtest.py`	向前走，蒙特卡洛，参数优化，多策略
搜索代理	`agents/search_agent.py`	网络抓取（原始NLP演示）
摘要代理	`agents/summarizer_agent.py`	文本摘要（原始NLP演示）
感觉代理	`agents/sentiment_agent.py`	情感分析（原始NLP演示）

🚀 快速开始

# 1. Clone & enter project
cd mcp-project

# 2. Create virtual environment
python -m venv .venv && source .venv/bin/activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Configure environment (copy and edit with your keys)
cp .env.example .env   # or edit .env directly

# 5. Launch the dashboard
streamlit run app_hedge_fund.py

# — or run the CLI pipeline —
python controller_hedge_fund.py

⚙️ 环境变量

所有配置都在 .env （忽略了）。复制 .env 并填写您的密钥：

变量	描述	默认值
`OPENAI_API_KEY`	用于LLM研究摘要的OpenAI API密钥	（无--使用免费模板）
`LLM_MAX_TOKENS`	单个LLM API调用的最大令牌数	`500`
`LLM_DAILY_TOKEN_LIMIT`	每天最大总代币数（所有通话）	`10000`
`LLM_MODEL`	要使用的OpenAI模型	`gpt-4o-mini` （最便宜）
`LLM_BASE_URL`	自定义OpenAI兼容端点	（可选）
`ALPACA_API_KEY`	羊驼经纪人密钥（仅限实时交易）	（可选）
`ALPACA_SECRET`	羊驼秘密（仅限实时交易）	（可选）
`FRED_API_KEY`	FRED API关键（宏观指标）	（可选）

💡 成本安全： 当达到每日代币限额时，LLM代理自动回退到免费模板摘要——这并不奇怪。

🗂 项目结构

mcp-project/
├── agents/
│   ├── __init__.py
│   ├── market_data_agent.py      # OHLCV data fetcher (stocks, crypto, forex)
│   ├── strategy_agent.py         # Signal generation
│   ├── company_research_agent.py # Fundamental analysis
│   ├── risk_agent.py             # Risk metrics & trade validation
│   ├── backtest_agent.py         # Historical simulation engine
│   ├── execution_agent.py        # Paper / live trading engine
│   ├── news_sentiment_agent.py   # FinBERT news sentiment
│   ├── llm_research_agent.py     # AI-powered research summaries
│   ├── alternative_data_agent.py # SEC filings, insider trades, holders
│   ├── portfolio_optimizer.py    # Markowitz, risk-parity, Black-Litterman
│   ├── advanced_backtest.py      # Walk-forward, Monte Carlo, param opt
│   ├── search_agent.py           # Web scraping agent (legacy)
│   ├── summarizer_agent.py       # NLP summariser (legacy)
│   └── sentiment_agent.py        # NLP sentiment (legacy)
├── tests/
│   ├── conftest.py               # Shared fixtures
│   ├── test_backtest_agent.py
│   ├── test_advanced_backtest.py
│   ├── test_company_research_agent.py
│   ├── test_execution_agent.py
│   ├── test_llm_research_agent.py
│   ├── test_market_data_agent.py
│   ├── test_news_sentiment_agent.py
│   ├── test_portfolio_optimizer.py
│   ├── test_risk_agent.py
│   ├── test_strategy_agent.py
│   └── test_utils_marketdata.py
├── utils_marketdata.py           # Technical indicator library
├── controller_hedge_fund.py      # Unified hedge-fund orchestrator
├── controller_strategy.py        # Strategy-only controller (legacy)
├── controller.py                 # Original NLP controller (legacy)
├── app_hedge_fund.py             # Full Streamlit dashboard
├── app_marketdata.py             # Market-data-only dashboard (legacy)
├── app.py                        # Original NLP demo app (legacy)
├── .env                          # API keys & cost limits (gitignored)
├── .github/workflows/ci.yml     # CI/CD: lint + test on Python 3.11–3.13
├── requirements.txt
├── readme.md                     # ← this file
└── docs/
    ├── plan.md                   # Implementation roadmap
    ├── arch.md                   # Architecture reference
    └── futurework.md             # Ideas for next iterations

📈 特性

技术分析

移动平均线、RSI、布林带、MACD、随机指标、ATR、ADX

战略信号

组合的 --RSI+布林+MACD（市场波动）
动量 --MACD+RSI（趋势市场）
均值回归 --布林+RSI（区间市场）
趋势跟踪 --MACD+ADX+随机指标（强劲趋势）

公司研究

关键基本面（市盈率、利润率、债务、净资产收益率、收益增长）
专有0-100评分，自动生成优势/风险
行业同行比较表
最近的新闻推送

风险管理

历史VaR和CVaR（95%）
夏普和索蒂诺比率
最大提款量
头寸规模（Kelly受到每笔交易风险限额的启发）
根据投资组合约束进行交易验证

回溯测试

包含佣金和滑点的完整历史模拟
股权曲线、月回报率、胜率、利润率
止损止盈执行
详细的交易日志

执行（纸面交易）

市价、限价和止损限价订单类型
具有投资组合状态跟踪功能的纸质交易引擎
可扩展到通过经纪人API（Alpaca）进行实时交易

新闻情绪

基于FinBERT的金融头条情绪分析
带置信度评分的看涨/看跌/中性分类
如果FinBERT不可用，则自动回退到DistilBERT

法学硕士研究综述

人工智能从结构化数据中生成股票研究报告
成本控制：每次通话代币上限、每日预算、最便宜的型号
当API密钥丢失或预算耗尽时，自动回退到可用模板

替代数据

通过EDGAR向美国证券交易委员会提交文件（10-K、10-Q、8-K）
内幕交易活动
机构持有人细分
社会情绪占位符

投资组合优化

平均方差（Markowitz） --具有最大夏普和最小波动率投资组合的蒙特卡洛有效边界
风险平价 --等额风险分担
黑利特曼 --市值均衡+投资者观点
再平衡 --具有交易成本意识的交易建议（跳过微小偏差）

高级回测

向前走分析 --用于样品外验证的滚动列车/测试窗口
蒙特卡罗模拟 --1000种未来情景，包括百分位数带和损益概率
参数优化 --在止损、止盈、头寸大小上进行网格搜索
多策略 --并行运行所有策略，比较指标，找到最佳执行者

多资产支持

股票、加密货币（BTC-USD、ETH-USD）、外汇（EURUSD=X）、指数（^GSPC）
常用名称的符号解析器→ y金融行情
日内间隔（1m、5m、1h）和每日数据

多符号比较

并排的价格图表、标准化回报、相关矩阵、比较统计数据

🧪 测试

# Run the full test suite (171 tests)
pytest

# Run with verbose output
pytest -v

# Run a specific test file
pytest tests/test_execution_agent.py

🔄 CI/CD

GitHub Actions在每次推送和PR上运行：

代码检查 和 flake8
测试和 pytest 在Python 3.11、3.12和3.13上

🛣 路线图

看 docs/plan.md 完整的实施路线图和 docs/futurework.md 对于剩余的想法：

警报（Slack/电报/电子邮件）
Docker部署和认证
持久存储（SQLite/PPostgreSQL）

作为一个学习项目构建，用于演示Python中的多代理编排。