Intelli Quant V1

IntelliTrade：自主多代理交易系统

由MCP和真实市场数据驱动的自主多代理交易大厅。

______________________________________________________________________

🎯 工程优势

模块化MCP架构：可组合服务（帐户、市场、推送、搜索）作为单独的MCP服务器，具有进程隔离和动态配置。支持即插即用功能和独立扩展。

Agent作为工具组合：研究人员代理作为工具暴露给交易者，实现多代理协作和模型灵活性。促进代码重用和复杂的工作流程。

多模型路由：跨OpenAI、DeepSeek、Grok、Gemini、OpenRouter的统一接口，具有条件初始化和智能路由功能。与供应商无关的设计，具有成本优化功能。

异步生命周期控制：AsyncExitStack管理MCP服务器清理，确保资源释放得到保证。通过并发执行 asyncio.gather() 最大化吞吐量。

并发安全：每个账户 asyncio.Lock 防止比赛条件。交易前重新加载最新状态，确保并发交易者的完整性。

Pydantic域模型：具有自动验证和JSON序列化的类型安全模型。实现准确的损益计算、完整的审计跟踪和时间序列跟踪。

实时仪表板：Gradio UI，带Plotly图表、自动刷新和实时日志流。提供操作可见性和调试支持。

______________________________________________________________________

📐 架构图

flowchart TB
    subgraph "Trading Floor Scheduler"
        Scheduler[trading_floor.py
Scheduler Loop]
    end

    subgraph "AI Traders"
        T1[Trader: Warren
Value Investor]
        T2[Trader: George
Macro Trader]
        T3[Trader: Ray
Systematic Investor]
        T4[Trader: Cathie
Crypto/Innovation]
    end

    subgraph "Researcher Agent"
        R[Researcher Agent
Web Research & Analysis]
    end

    subgraph "Trader MCP Servers"
        A[Accounts Server
Portfolio Management]
        M[Market Server
Price Lookup]
        P[Push Server
Notifications]
    end

    subgraph "Researcher MCP Servers"
        F[Fetch Server
Web Scraping]
        B[Brave Search
Web Search]
        MM1[Memory: Warren.db
Knowledge Graph]
        MM2[Memory: George.db
Knowledge Graph]
        MM3[Memory: Ray.db
Knowledge Graph]
        MM4[Memory: Cathie.db
Knowledge Graph]
    end

    subgraph "Data Layer"
        DB[(SQLite Database
accounts.db)]
        MarketAPI[Polygon.io API
Market Data]
    end

    subgraph "UI Layer"
        UI[Gradio Dashboard
Real-time Monitoring]
    end

    Scheduler -->|"Concurrent Execution"| T1
    Scheduler -->|"Concurrent Execution"| T2
    Scheduler -->|"Concurrent Execution"| T3
    Scheduler -->|"Concurrent Execution"| T4

    T1 -->|"Uses as Tool"| R
    T2 -->|"Uses as Tool"| R
    T3 -->|"Uses as Tool"| R
    T4 -->|"Uses as Tool"| R

    T1 -->|"MCP Tools"| A
    T1 -->|"MCP Tools"| M
    T1 -->|"MCP Tools"| P
    T2 -->|"MCP Tools"| A
    T2 -->|"MCP Tools"| M
    T2 -->|"MCP Tools"| P
    T3 -->|"MCP Tools"| A
    T3 -->|"MCP Tools"| M
    T3 -->|"MCP Tools"| P
    T4 -->|"MCP Tools"| A
    T4 -->|"MCP Tools"| M
    T4 -->|"MCP Tools"| P

    R -->|"MCP Tools"| F
    R -->|"MCP Tools"| B
    R -->|"MCP Tools"| MM1
    R -->|"MCP Tools"| MM2
    R -->|"MCP Tools"| MM3
    R -->|"MCP Tools"| MM4

    A |"Read/Write"| DB
    M -->|"Fetch Prices"| MarketAPI
    M -->|"Cache"| DB
    UI |"Read"| DB

查看完整的架构图 | SVG版本

______________________________________________________________________

📁 存储库结构

intellitrade/
├── trading_floor.py      # Main scheduler orchestrating trader runs
├── traders.py             # Trader agent class and model setup
├── accounts.py            # Portfolio management with concurrency control
├── market.py              # Market data integration (Polygon.io)
├── database.py            # SQLite persistence layer
├── mcp_params.py          # MCP server configuration
├── templates.py           # AI agent prompts and instructions
├── tracers.py             # Observability and logging
├── accounts_server.py      # MCP server for account operations
├── accounts_client.py     # MCP client utilities
├── market_server.py       # MCP server for market data
├── push_server.py         # MCP server for push notifications
├── app.py                 # Gradio web UI dashboard
├── reset.py               # Trader strategy initialization
├── util.py                # UI utilities (CSS/JS)
├── accounts.db            # SQLite database file
└── memory/                # Per-trader memory databases
    ├── Warren.db
    ├── George.db
    ├── Ray.db
    └── Cathie.db

______________________________________________________________________

🚀 快速入门指南

先决条件

• Python 3.12+
• 紫外线 包管理器
• （为 npx 命令）
• API密钥：OpenAI、Polygon.io

安装

# Install dependencies
uv sync

# Copy environment template
cp .env.example .env

# Edit .env with your API keys
# Required: OPENAI_API_KEY, POLYGON_API_KEY
# Optional: DEEPSEEK_API_KEY, GOOGLE_API_KEY, GROK_API_KEY, OPENROUTER_API_KEY
# Optional: PUSHOVER_USER, PUSHOVER_TOKEN, BRAVE_API_KEY

初始化交易者

# Reset all traders with their strategies
uv run reset.py

运行交易大厅

# Start the automated trading scheduler
uv run trading_floor.py

启动仪表板

# Start the Gradio web interface (separate terminal)
uv run app.py

仪表板将在您的浏览器中打开 http://127.0.0.1:7860

______________________________________________________________________

⚙️ 配置和环境

所需的环境变量

可选环境变量

功能标志

• USE_MANY_MODELS=true：为每个交易者分配不同的AI模型：

- 沃伦→ gpt-4.1-mini （OpenRouter） - 乔治→ deepseek-chat （DeepSeek） - Ray → gemini-2.5-flash-preview-04-17 谷歌 - 凯茜→ grok-3-mini-beta （Grok）

• RUN_EVEN_WHEN_MARKET_IS_CLOSED=true：允许在市场时间之外进行交易

• POLYGON_PLAN：控制市场数据访问：

- free：日终价格（默认） - paid：价格延迟15分钟 - realtime：实时市场数据

______________________________________________________________________

🔧 操作说明

并发安全

系统使用 每个账户 asyncio.Lock 为了防止比赛条件：

• 每个帐户都有一个专用锁
• buy_shares() 和 sell_shares() 修改帐户前获取锁
• 每次交易前从数据库重新加载的最新帐户状态
• 即使有并发交易者，也能确保交易的完整性

异步资源管理

• 异步堆栈：在单一上下文中管理所有MCP服务器
• 保证清理：即使出现异常，服务器也会关闭
• 超时处理：MCP服务器连接超时120秒

重试和错误处理

• 市场数据回落：根据利益相关者的要求随机调整价格
• 错误隔离：交易者失败不会阻止其他交易者
• 日志记录：所有错误都记录到数据库中进行分析

数据库模式

• accounts：帐户数据（JSON序列化）
• logs：结构化日志记录（跟踪、代理、函数、生成、响应、帐户）
• market：按日期缓存的市场数据

______________________________________________________________________

📊 架构图

• 系统架构 -高级系统概述
• 运行时间序列 -交易周期执行流程
• 组件依赖关系 -模块关系

看 建筑.md 获取详细的架构文档。

______________________________________________________________________

🧪 测试和本地开发

使用模拟外部API unittest.mock.patch.使用以下命令运行异步循环 asyncio.run()。参见 操作.md 了解详情。

🐳 部署

Dockerfile和docker组成了可用的示例。看 操作.md 获取完整的部署指南。

______________________________________________________________________

🐳 Docker设置

构建Docker镜像

# Build the Docker image
docker build -t agentic-ai-trading .

运行容器

# Run the container (with environment variables)
docker run --env-file .env -p 7860:7860 agentic-ai-trading

Docker化的好处

对IntelliTrade系统进行码头化有几个优点：

• 可移植性：在不同的环境（开发、测试、生产）中一致地运行应用程序，而不用担心Python版本冲突或依赖性问题。

• 隔离：应用程序在封闭的环境中运行，防止与系统包发生冲突，并确保干净的依赖关系管理。

• 轻松部署：以最少的配置部署到任何兼容Docker的平台（AWS ECS、Google Cloud Run、Azure容器实例、Kubernetes）。

• 可重复性：可以在任何地方重新创建完全相同的环境，使调试和协作更容易。

其他Docker命令

无缓存重建 （在依赖关系发生变化时非常有用）：

docker build --no-cache -t agentic-ai-trading .

查看容器日志:

docker logs -f 

在分离模式下运行 背景

docker run -d --env-file .env -p 7860:7860 --name intellitrade agentic-ai-trading

停止并移除容器:

docker stop 
docker rm 

本地与生产使用

本地开发:

• 使用 --env-file .env 从本地加载环境变量 .env 文件
• 如果需要持久数据库存储，请装载卷： -v $(pwd)/agents/intellitrade:/app/agents/intellitrade
• 访问仪表板 http://localhost:7860

生产部署:

• 考虑使用Docker secrets或从编排平台注入环境变量
• 使用Docker卷或外部数据库进行持久数据存储
• 为HTTPS和域路由配置反向代理（nginx、Traefik）
• 设置健康检查和自动重启策略

故障排除

端口冲突：如果端口7860已在使用中，请映射到其他端口：

docker run --env-file .env -p 8080:7860 agentic-ai-trading

环境变量未加载：确保您的 .env 文件位于项目根目录中，包含所有必需的变量(OPENAI_API_KEY, POLYGON_API_KEY等等）。

集装箱立即出口：检查日志 docker logs 以识别启动错误。常见问题包括缺少API密钥或数据库初始化问题。

权限错误：如果您遇到数据库文件的权限问题，请确保容器对已挂载的卷具有写访问权限，或使用Docker卷进行数据持久化。

______________________________________________________________________

🔍 故障排除

常见问题: POLYGON_API_KEY not found → Check .env 在 agents/ 目录。 OPENAI_API_KEY not set → 默认型号需要。 MCP server not found → 安装 uv, uvx, npx.数据库锁→ 受保护 asyncio.Lock.市场数据回退→ 有意（利益相关者要求）。看 操作.md 了解详情。

______________________________________________________________________

🗺️ 路线图

Prometheus指标、断路器、幂等性密钥、自动备份、健康检查、速率限制、结构化日志记录、优雅关机、成本跟踪、性能监控。

______________________________________________________________________

📚 文档

• 建筑.md -详细的架构文档
• 操作.md -部署和操作指南
• 安全.md -安全最佳实践

______________________________________________________________________

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件。

______________________________________________________________________

🙏 鸣谢

内置：

• OpenAI代理SDK
• 模型上下文协议
• Polygon.io -市场数据
• 格拉迪奥 -Web界面
• 派丹蒂克 -数据验证