Equity-Traders

📈 股票交易员

股票交易员 是一个模块化的交易沙箱，可以连接：

• MCP（模型上下文协议）服务器 用于市场数据、帐户和推送更新
• 交易商代理 使用此数据的原因 OpenAI Python SDK
• 一个简单的 数据库 账户/头寸的后备存储
• 灯光编排，模拟“交易大厅”

目标：一个干净、可破解的基础，用于实验LLM辅助的股票交易流程，而不是一个制作经纪人或财务建议引擎。

⚠️ 这个项目是 用于研究和教育确实如此 不 现场交易和报价 没有投资建议.

______________________________________________________________________

🧱 建筑

   ┌───────────────────┐
   │   OpenAI SDK      │  (LLM calls: analysis, plans, orders)
   └─────────┬─────────┘
             │
      ┌──────▼──────┐
      │  Traders    │  traders.py
      │ (agents)    │
      └───┬─────┬───┘
          │     │
┌─────────▼─┐ ┌─▼──────────┐
│ Market    │ │ Accounts    │
│ MCP       │ │ MCP         │
│ Server    │ │ Server      │
│ (prices)  │ │ (ledger)    │
└──────┬────┘ └────┬───────┘
       │            │
 ┌─────▼────┐  ┌───▼───────┐
 │ market.py │  │ accounts.py│
 └──────────┘  └────────────┘

         ┌───────────────────────────┐
         │ Push MCP Server           │  push_server.py
         │ (stream updates/events)   │
         └───────────────────────────┘

Orchestration glue, util fns, DB helpers:

* trading\_floor.py, app.py, util.py, database.py, mcp\_params.py, tracers.py, templates.py

______________________________________________________________________

📂 项目结构（映射到实际文件）

• app.py –CLI/entry实用程序，用于启动组件或运行演示。
• trading_floor.py -协调系统：将交易者连接到MCP服务器；运行场景/循环。
• traders.py –定义交易者代理：策略支架、决策循环、LLM调用的使用方式。
• market_server.py – MCP服务器 公开市场数据工具（报价、历史数据、交易品种）。
• accounts_server.py – MCP服务器 用于账户/头寸/投资组合操作。
• push_server.py – MCP服务器 用于流媒体/推送事件（价格报价、填充、警报）。
• market.py –市场适配器/实用程序（价格检索、符号验证、转换）。
• accounts.py –账户/头寸模型和业务逻辑（余额、损益、订单检查）。
• accounts_client.py –瘦客户端从代理与帐户MCP服务器通信。
• database.py –SQLite帮助程序（模式、CRUD）。用途 accounts.db 默认情况下。
• mcp_params.py –MCP服务器注册、工具模式和参数/类型定义。
• templates.py –用于分析、订单、风险检查等的提示/LLM模板。
• tracers.py –运行日志/跟踪实用程序（LLM提示、决策、工具调用）。
• util.py –其他助手（时间、配置、格式）。
• reset.py 将SQLite数据库重置/初始化为已知状态。
• accounts.db –SQLite数据库文件。
• pyproject.toml, uv.lock –Python项目+ 紫外线 用于可重复安装的锁。
• .python-version, .gitignore –工具卫生。

上面的列表反映了repo根目录中存在的实际文件名。

______________________________________________________________________

✨ 特性

• MCP本地 数据访问：市场/投资组合是法学硕士可以调用的一流工具。
• 代理循环 在Python中使用 OpenAI SDK (≥ openai v1）：结构化提示→ 工具调用→ 决定。
• 数据库 账户/头寸的基线状态——易于重置和检查。
• 可组合：交换策略、添加工具或指向不同的市场适配器。

______________________________________________________________________

🚀 快速启动

1） 克隆并安装

git clone https://github.com/ceodaniyal/Equity-Traders.git
cd Equity-Traders

# Using uv (recommended)
uv install

2） 环境

创建 .env （或出口）至少：

export OPENAI_API_KEY=sk-...
# Optional:
# export OPENAI_BASE_URL=...   # if using an Azure/OpenAI-compatible endpoint
# export MODEL=gpt-4.1-mini    # or your preferred model

如果您使用dotenv，请确保 python-dotenv 或装入等效物 app.py/trading_floor.py.

3） 初始化数据库

uv run python reset.py

4） 启动MCP服务器（每个服务器都在自己的shell中）

# Market data
uv run python market_server.py

# Accounts & portfolio
uv run python accounts_server.py

# Push / streaming events
uv run python push_server.py

5） 运行交易大厅（代理+OpenAI SDK）

uv run python trading_floor.py

或者运行任何演示条目：

uv run python app.py

______________________________________________________________________

🧩 MCP集成

该项目公开了三个MCP服务器。如果你想在支持MCP的客户端（例如Claude Desktop或其他MCP主机）上注册它们，请使用类似于以下内容的配置：

{
  "mcpServers": {
    "equity-traders-market": {
      "command": "uv",
      "args": ["run", "python", "market_server.py"],
      "env": {}
    },
    "equity-traders-accounts": {
      "command": "uv",
      "args": ["run", "python", "accounts_server.py"],
      "env": {}
    },
    "equity-traders-push": {
      "command": "uv",
      "args": ["run", "python", "push_server.py"],
      "env": {}
    }
  }
}

每个服务器都定义了工具（请参见 mcp_params.py)使用JSON可序列化输入/输出，以便LLM可以确定地调用它们。

______________________________________________________________________

🤖 OpenAI SDK使用情况

交易员代理人使用 OpenAI Python SDK 致：

• 分析符号/市场背景，
• 决定行动（例如，“建议顺序”、“重新平衡”、“什么都不做”），
• 在采取行动之前，可以选择调用MCP工具（市场/账户）以获取权威数据。

典型呼叫模式（示意图）：

from openai import OpenAI
client = OpenAI()

resp = client.chat.completions.create(
    model=os.getenv("MODEL", "gpt-4.1-mini"),
    messages=[
        {"role": "system", "content": SYSTEM_PROMPT},
        {"role": "user", "content": user_or_loop_message},
    ],
    tools=[...],  # MCP tool schemas or function-calling bridge
)

（精确代码存在于 traders.py / templates.py.)

______________________________________________________________________

🔧 配置

• 模型：set MODEL env var或内部调整 traders.py.
• 市场适配器：扩展 market.py 指向您的首选数据源（缓存、CSV、API）。
• 风险/限制：强制执行 accounts.py （订单检查）和/或 traders.py （政策提示+工具检查）。
• 提示：调整 templates.py.
• 追踪：启用详细信息 tracers.py （例如文件日志或结构化JSON）。

______________________________________________________________________

🧪 示例工作流

• 晨间扫描：代理提取上市前快照（市场MCP）→ 对候选人进行排名→ 提出纸质订单（账户MCP）。
• 反应式交易：推送MCP流式传输事件（例如，价格突破）→ 交易员要求新报价→ 验证风险上限→ 提交模拟订单。
• 投资组合清理：agent迭代MCP帐户中的持有量→ 评估过时的职位→ 建议退出。

______________________________________________________________________

🛠️ 发展

# Lint/format/testing (suggested)
uv run ruff check .
uv run ruff format .
uv run pytest -q

如果这些工具不在 pyproject.toml 然而，请添加它们； uv 保持其快速性和可重复性。

______________________________________________________________________

🧾 故障排除

• 没有数据？ 确保 market_server.py 正在运行，并且 market.py 可以解析您的符号。
• 数据库错误？ 删除 accounts.db 然后跑 uv run python reset.py 再一次。
• LLM错误/限制？ 验证 OPENAI_API_KEY 并选择 MODEL。如果是自托管，请设置 OPENAI_BASE_URL.
• MCP客户端无法发现工具？ 确认MCP配置路径，服务器无异常启动。

______________________________________________________________________

🗺️ 路线图创意

• 实时经纪商抽象（仅限于纸面交易）
• 根据历史CSV对线束进行回溯测试
• 风险仪表板和更丰富的跟踪/遥测
• 策略注册表（动量、均值回归、配对、L/S）

______________________________________________________________________