goldfxgraph

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# Multi-Agent Forecast Dashboard

[English](https://github.com/michael-chow-arch/goldfxgraph/blob/HEAD/README.md) | [中文](https://github.com/michael-chow-arch/goldfxgraph/blob/HEAD/README.zh-CN.md)

![Multi-Agent forecast overview map](https://github.com/michael-chow-arch/goldfxgraph/raw/HEAD/docs/assets/readme-agent-map-sketch-en.png)

Multi-Agent Forecast Dashboard is an open-source **LangGraph** project for multi-agent XAU/USD research. It combines real-time gold prices, historical daily bars, news, macro data, alternative signals, and risk analysis into a coordinated workflow that produces structured entries, take-profit / stop-loss levels, time-window outlooks, and a final research conclusion.

It now also includes a **Two-Round Adversarial Trading Committee** layer and a **Prompt Registry / Prompt Template Management Layer** for the committee agents. The committee layer turns specialist analysis into an evidence package, runs a two-round bull vs. bear debate, and lets a chair agent arbitrate the final research posture. The prompt registry stores versioned English runtime prompts alongside Chinese maintenance translations so the committee prompts stay auditable, reviewable, and easy to evolve.

> This project is for research and decision support only. It is not investment advice and does not provide automated trading.

---

## Preview

<p align="center">
  <img src="docs/assets/readme-dashboard-overview.png" alt="Multi-Agent Forecast Dashboard overview" width="100%" />
</p>

<p align="center">
  <img src="docs/assets/readme-dashboard-details.png" alt="Multi-Agent Forecast Dashboard details" width="100%" />
</p>

<p align="center"><strong>黄金日线结构</strong></p>

<p align="center">
  <img src="docs/assets/readme-gold-daily-structure.png" alt="Golden daily structure" width="100%" />
</p>

---

## What this project does

- Provide daily entry, take-profit, and stop-loss levels, plus outlooks for the next 3 days, 3-5 days, 6-15 days, and 15+ days
- Fetch TradingView XAU/USD realtime quotes and daily snapshots
- Ingest historical daily bars as the foundation for indicator computation and evaluation
- Run specialized agents from technical, macro, news, sentiment, alternative-data, and risk perspectives
- Aggregate their outputs into a single structured forecast
- Display current price, daily direction, confidence, entry / take-profit / stop-loss, time-window outlooks, and research summaries in the frontend dashboard
- Persist research runs, forecasts, agent states, and feedback loops

---

## Multi-agent roles

| Agent | Role | Focus |
| --- | --- | --- |
| `technical` | Technical analysis | Price structure, trend, patterns, moving averages, RSI, ATR, smart-money logic |
| `macro` | Macro analysis | Dollar index, rates, inflation, liquidity, and broader macro conditions |
| `news` | News analysis | News flow, sentiment, event impact, and representative Chinese headlines |
| `market_sentiment` | Market sentiment analysis | Combined sentiment from RSI, CFTC positioning, news flow, Polymarket, and historical feedback |
| `alt_data` | Alternative data analysis | Pizza Index, macro signals, and other supplemental indicators |
| `risk` | Risk analysis | Volatility boundaries, drawdown / rebound risk, key price levels, and defensive posture |
| `forecast` | Final aggregation | Merge all agent outputs into the final direction, trade levels, and time-window outlook |
| `bull / bear` | Trading committee debate | Build evidence-backed opening, rebuttal, and final positions from the evidence package |
| `chair` | Trading committee chair | Arbitrate the final bias, actionability, and trade plan |
| `repair` | Committee repair | Apply conservative fixes when validation fails |

## Two-Round Adversarial Trading Committee

The committee layer is intentionally structured and bounded:

1. Specialist agents produce independent analysis first.
2. `node_build_evidence_package` consolidates the specialist output into a normalized evidence package.
3. Round 1 opening cases are produced by the bull and bear agents in parallel.
4. Round 2 rebuttals respond point-by-point to the opposite opening case.
5. Final positions state whether each side still stands by its view or downgrades to observe-only / no-trade.
6. The chair agent arbitrates the final bias, actionability, and trade plan.
7. A rule-based validator checks the chair decision, and a repair agent can make one or two conservative corrections if needed.

All committee reasoning must stay inside the evidence package. Committee prompts are loaded from the Prompt Registry and are not hard-coded in Python.

## Prompt Registry / Prompt Template Management Layer

The Prompt Registry stores committee prompts in the database with:

- versioned prompt keys
- English runtime prompt text for the LLM
- Chinese maintenance translations for review and auditing
- active-version lookup
- prompt metadata such as prompt type, node name, model family, and output schema reference

This makes committee prompts easier to review, safer to update, and simpler to trace back to the exact version used for a given research run.

---

## Third-party data sources and tools

| Data source / tool | Purpose |
| --- | --- |
| TradingView | Realtime XAU/USD quote, daily snapshot, and price reference |
| Reuters / NewsFlow | Mainstream news flow, sentiment, and representative headlines |
| CFTC | Positioning / COT-related inputs |
| Polymarket | Event probabilities and market expectation signals |
| Pizza Index | Alternative market sentiment indicator |
| Macro data | Treasury yields, CPI, Fed funds, and other macro inputs |
| Historical feedback | Previous forecast outcomes and evaluation feedback |
| Local daily bars | Completed daily-bar inputs for evaluation and indicator foundations |
| Technical indicator tools | SMA, EMA, RSI, ATR, and volatility-structure calculations |

---

## Workflow at a glance

```mermaid
flowchart LR
  A[TradingView / News / CFTC / Polymarket / Macro data] --> B[Load market data and latest quote]
  B --> C[Compute technical indicators]
  C --> D[Run specialist agents]
  D --> E[Build evidence package]
  P[Prompt registry / prompt versions] -.-> G
  P -.-> H1
  P -.-> I1
  P -.-> H2
  P -.-> I2
  P -.-> H3
  P -.-> I3

  subgraph S[Two-round committee debate]
    direction LR
    E --> G{Branch into bull and bear tracks}
    G --> H1[Bull opening]
    G --> I1[Bear opening]
    H1 --> H2[Bull rebuttal]
    I1 --> I2[Bear rebuttal]
    H2 --> H3[Bull final position]
    I2 --> I3[Bear final position]
    H3 --> J[Chair arbitration]
    I3 --> J
  end

  J --> K[Validate and repair if needed]
  K --> L[Persist forecast and committee trace]
  L --> M[Display in dashboard]
  L --> N[Historical feedback loop]
```

1. Load local market data and the latest quote snapshot
2. Compute technical indicators and structural signals
3. Run the specialist agents by domain
4. Consolidate specialist outputs into an evidence package
5. Branch into the committee debate after the evidence package is ready
6. Run bull and bear opening, rebuttal, and final-position tracks
7. Let the chair agent arbitrate the final research posture
8. Validate the decision and apply bounded repair if required
9. Persist the structured forecast and committee trace for later review
10. Render the latest result in the frontend dashboard
11. Feed the result into the historical feedback loop

---

## Why it is designed this way

- **LangGraph** provides explicit orchestration for the multi-agent workflow
- **Structured outputs** make each agent result safe to render in the frontend
- **Separation of tools and data sources** keeps inputs, reasoning, and outputs decoupled
- **Historical feedback loops** turn the forecast into a repeatable research process, not a one-off text output

---

## Planned enhancements

- Add historical evaluation analysis so past forecasts can be reviewed from a richer time-series perspective
- Expand the research view with longer-horizon retrospective comparisons and performance summaries
- Use historical context to compare how agent conclusions evolve across different market regimes

---

## Development stack

The project uses the following tools and workflow helpers:

- **Codex**: code authoring, debugging, refactoring, and frontend iteration
- **OpenSpec**: change definitions, design boundaries, and implementation scope
- **Superpowers**: brainstorming, planning, execution discipline, and quality checks
- **ui-ux-pro-max**: dashboard and README visual review, layout guidance, and style consistency

---

## Run and configuration

The local setup reads from `dev.env` by default. The Chinese README and this English README share the same project structure and scope.

If you prefer Chinese documentation, switch to [中文 README](https://github.com/michael-chow-arch/goldfxgraph/blob/HEAD/README.zh-CN.md).

---

## Local startup

1. Start local infrastructure with Docker Compose:

```bash
docker compose up -d
```

This uses the repository-level [`docker-compose.yml`](https://github.com/michael-chow-arch/goldfxgraph/blob/HEAD/docker-compose.yml) to start PostgreSQL for local persistence.

2. Start the backend API:

```bash
uv run uvicorn goldfxgraph.api.app:create_app --factory --host 0.0.0.0 --port 8000 --reload
```

3. Start the frontend dashboard:

```bash
cd apps/web
npm install
npm run dev
```

The frontend runs on [http://localhost:5173](http://localhost:5173) and talks to the backend through `VITE_API_BASE_URL=http://localhost:8000`.

---

## Disclaimer

Multi-Agent Forecast Dashboard is not a trading system.

This project does not provide financial advice, investment recommendations, trading signals, or automated execution. All outputs are for research, learning, and workflow exploration only.

---

## License

MIT

Multi-Agent Forecast Dashboard

English | 中文

Multi-Agent forecast overview map

Multi-Agent Forecast Dashboard is an open-source LangGraph project for multi-agent XAU/USD research. It combines real-time gold prices, historical daily bars, news, macro data, alternative signals, and risk analysis into a coordinated workflow that produces structured entries, take-profit / stop-loss levels, time-window outlooks, and a final research conclusion.

It now also includes a Two-Round Adversarial Trading Committee layer and a Prompt Registry / Prompt Template Management Layer for the committee agents. The committee layer turns specialist analysis into an evidence package, runs a two-round bull vs. bear debate, and lets a chair agent arbitrate the final research posture. The prompt registry stores versioned English runtime prompts alongside Chinese maintenance translations so the committee prompts stay auditable, reviewable, and easy to evolve.

This project is for research and decision support only. It is not investment advice and does not provide automated trading.

Preview

Multi-Agent Forecast Dashboard overview

Multi-Agent Forecast Dashboard details

黄金日线结构

Golden daily structure

What this project does

Provide daily entry, take-profit, and stop-loss levels, plus outlooks for the next 3 days, 3-5 days, 6-15 days, and 15+ days
Fetch TradingView XAU/USD realtime quotes and daily snapshots
Ingest historical daily bars as the foundation for indicator computation and evaluation
Run specialized agents from technical, macro, news, sentiment, alternative-data, and risk perspectives
Aggregate their outputs into a single structured forecast
Display current price, daily direction, confidence, entry / take-profit / stop-loss, time-window outlooks, and research summaries in the frontend dashboard
Persist research runs, forecasts, agent states, and feedback loops

Multi-agent roles

Agent	Role	Focus
`technical`	Technical analysis	Price structure, trend, patterns, moving averages, RSI, ATR, smart-money logic
`macro`	Macro analysis	Dollar index, rates, inflation, liquidity, and broader macro conditions
`news`	News analysis	News flow, sentiment, event impact, and representative Chinese headlines
`market_sentiment`	Market sentiment analysis	Combined sentiment from RSI, CFTC positioning, news flow, Polymarket, and historical feedback
`alt_data`	Alternative data analysis	Pizza Index, macro signals, and other supplemental indicators
`risk`	Risk analysis	Volatility boundaries, drawdown / rebound risk, key price levels, and defensive posture
`forecast`	Final aggregation	Merge all agent outputs into the final direction, trade levels, and time-window outlook
`bull / bear`	Trading committee debate	Build evidence-backed opening, rebuttal, and final positions from the evidence package
`chair`	Trading committee chair	Arbitrate the final bias, actionability, and trade plan
`repair`	Committee repair	Apply conservative fixes when validation fails

Two-Round Adversarial Trading Committee

The committee layer is intentionally structured and bounded:

Specialist agents produce independent analysis first.
node_build_evidence_package consolidates the specialist output into a normalized evidence package.
Round 1 opening cases are produced by the bull and bear agents in parallel.
Round 2 rebuttals respond point-by-point to the opposite opening case.
Final positions state whether each side still stands by its view or downgrades to observe-only / no-trade.
The chair agent arbitrates the final bias, actionability, and trade plan.
A rule-based validator checks the chair decision, and a repair agent can make one or two conservative corrections if needed.

All committee reasoning must stay inside the evidence package. Committee prompts are loaded from the Prompt Registry and are not hard-coded in Python.

Prompt Registry / Prompt Template Management Layer

The Prompt Registry stores committee prompts in the database with:

versioned prompt keys
English runtime prompt text for the LLM
Chinese maintenance translations for review and auditing
active-version lookup
prompt metadata such as prompt type, node name, model family, and output schema reference

This makes committee prompts easier to review, safer to update, and simpler to trace back to the exact version used for a given research run.

Third-party data sources and tools

Data source / tool	Purpose
TradingView	Realtime XAU/USD quote, daily snapshot, and price reference
Reuters / NewsFlow	Mainstream news flow, sentiment, and representative headlines
CFTC	Positioning / COT-related inputs
Polymarket	Event probabilities and market expectation signals
Pizza Index	Alternative market sentiment indicator
Macro data	Treasury yields, CPI, Fed funds, and other macro inputs
Historical feedback	Previous forecast outcomes and evaluation feedback
Local daily bars	Completed daily-bar inputs for evaluation and indicator foundations
Technical indicator tools	SMA, EMA, RSI, ATR, and volatility-structure calculations

Workflow at a glance

flowchart LR
  A[TradingView / News / CFTC / Polymarket / Macro data] --> B[Load market data and latest quote]
  B --> C[Compute technical indicators]
  C --> D[Run specialist agents]
  D --> E[Build evidence package]
  P[Prompt registry / prompt versions] -.-> G
  P -.-> H1
  P -.-> I1
  P -.-> H2
  P -.-> I2
  P -.-> H3
  P -.-> I3

  subgraph S[Two-round committee debate]
    direction LR
    E --> G{Branch into bull and bear tracks}
    G --> H1[Bull opening]
    G --> I1[Bear opening]
    H1 --> H2[Bull rebuttal]
    I1 --> I2[Bear rebuttal]
    H2 --> H3[Bull final position]
    I2 --> I3[Bear final position]
    H3 --> J[Chair arbitration]
    I3 --> J
  end

  J --> K[Validate and repair if needed]
  K --> L[Persist forecast and committee trace]
  L --> M[Display in dashboard]
  L --> N[Historical feedback loop]

Load local market data and the latest quote snapshot
Compute technical indicators and structural signals
Run the specialist agents by domain
Consolidate specialist outputs into an evidence package
Branch into the committee debate after the evidence package is ready
Run bull and bear opening, rebuttal, and final-position tracks
Let the chair agent arbitrate the final research posture
Validate the decision and apply bounded repair if required
Persist the structured forecast and committee trace for later review
Render the latest result in the frontend dashboard
Feed the result into the historical feedback loop

Why it is designed this way

LangGraph provides explicit orchestration for the multi-agent workflow
Structured outputs make each agent result safe to render in the frontend
Separation of tools and data sources keeps inputs, reasoning, and outputs decoupled
Historical feedback loops turn the forecast into a repeatable research process, not a one-off text output

Planned enhancements

Add historical evaluation analysis so past forecasts can be reviewed from a richer time-series perspective
Expand the research view with longer-horizon retrospective comparisons and performance summaries
Use historical context to compare how agent conclusions evolve across different market regimes

Development stack

The project uses the following tools and workflow helpers:

Codex: code authoring, debugging, refactoring, and frontend iteration
OpenSpec: change definitions, design boundaries, and implementation scope
Superpowers: brainstorming, planning, execution discipline, and quality checks
ui-ux-pro-max: dashboard and README visual review, layout guidance, and style consistency

Run and configuration

The local setup reads from dev.env by default. The Chinese README and this English README share the same project structure and scope.

If you prefer Chinese documentation, switch to 中文 README.

Local startup

Start local infrastructure with Docker Compose:

docker compose up -d

This uses the repository-level docker-compose.yml to start PostgreSQL for local persistence.

Start the backend API:

uv run uvicorn goldfxgraph.api.app:create_app --factory --host 0.0.0.0 --port 8000 --reload

Start the frontend dashboard:

cd apps/web
npm install
npm run dev

The frontend runs on http://localhost:5173 and talks to the backend through VITE_API_BASE_URL=http://localhost:8000.

Disclaimer

Multi-Agent Forecast Dashboard is not a trading system.

This project does not provide financial advice, investment recommendations, trading signals, or automated execution. All outputs are for research, learning, and workflow exploration only.

License

MIT