Trading VPA Orchestrator

Đây là entrypoint duy nhất cho phân tích. File này chỉ điều phối runtime; luật
VPA/Wyckoff/action chi tiết thuộc engine, renderer và validator.

Detect Market Type

• Crypto: symbol kết thúc bằng USDT/USDC/BTC, tên coin phổ biến, hoặc prompt
  có "coin", "crypto", "binance". Dùng Crypto Workflow.
• Cổ phiếu Việt Nam: mã 3 chữ cái HOSE/HNX/UPCOM hoặc prompt có "cổ phiếu",
  "chứng khoán", "cp", "HOSE". Dùng VN Stock Workflow.
• Nếu không rõ market type, hỏi người dùng.

Crypto Defaults

• symbol: mặc định BTCUSDT; chuẩn hóa BTC thành BTCUSDT.
• market: mặc định spot; hỗ trợ spot và futures.
• trigger interval: mặc định 1d; hỗ trợ 15m, 1h, 4h, 1d.
• profile: mặc định default; chỉ dùng spot_swing khi người dùng yêu cầu
  spot swing/thăm dò rõ ràng.
• Mapping mặc định:
  • 15m: structure 4h, manage 5m.
  • 1h: structure 1d, manage 15m.
  • 4h: structure 1d, manage 1h.
  • 1d: structure 1w, manage 4h.

Crypto Workflow

1. Gọi Unified Orchestrator. Script tự reuse run hoàn chỉnh/còn fresh hoặc
   chạy pipeline mới, rồi trả về chat_response.md đã validate:

   python scripts/unified_crypto_flow.py {SYMBOL} --market {market}

   Với trigger cụ thể:

   python scripts/unified_crypto_flow.py {SYMBOL} --market {market} --interval 4h

   Với spot swing/thăm dò khi người dùng yêu cầu:

   python scripts/unified_crypto_flow.py {SYMBOL} --market spot --interval 4h --profile spot_swing

2. Orchestrator output là JSON. Lấy trường chat_response nếu
   status == "success" và gửi nguyên văn cho người dùng. Trường này được
   sinh bởi scripts/render_chat.py và đã qua validator; đây là nguồn
   user-facing duy nhất.

   Không tự suy luận câu trả lời từ decision-context.json, analysis.md,
   decision-context.summary.md, journal, log, hoặc artifact trung gian khác.
   Các file đó chỉ dùng để debug khi pipeline fail.

   Nếu status != "success", không phân tích dữ liệu cũ và không dựng chat thủ
   công. Báo lỗi ngắn gọn; thiếu field bắt buộc là bug của pipeline, cần sửa extractor/renderer/validator, hoặc orchestrator nếu lỗi nằm ở điều phối, rồi chạy lại.

3. Continuity, Decision contract, Learning loop — tất cả đều được engine
   Python xử lý tự động bên trong Orchestrator. LLM không cần can thiệp.

4. Xử lý lỗi cụ thể:

   • FileNotFoundError khi chạy script: kiểm tra lại đường dẫn script
   • timeout: Binance API có thể chậm, thử lại sau 30s
   • validation_passed: false: đọc log để biết field nào thiếu, sửa pipeline
   • Subprocess error: kiểm tra Python version và dependencies đã cài đủ

Sector Scanner

Khi người dùng hỏi về tổng quan thị trường, check market, scan nhiều coin,
top coin, bảng xếp hạng sector, hoặc muốn biết coin nào đáng chú ý (prompt
có "check market", "sector", "scan", "top coin", "thị trường", "tổng quan",
"bảng xếp hạng", "coin nào"), route sang scripts/sector_scan.py:

python scripts/sector_scan.py

Trả nguyên văn output của script. Không chạy unified_crypto_flow.py riêng lẻ
cho từng coin — script đã tự xử lý song song 23 coin đại diện theo sector.

Output gồm:

• Bảng xếp hạng HOT/WATCH/WAIT/DEAD theo composite score 0-18
• Cột Action: [Mua], [Probe], [P6], [Sớm], [Nhỏ], [Đứng ngoài]
• Bias: Long / Short / Neutral
• Spring reclaim: xác nhận (đã hồi phục trên đáy spring)
• Sector hot nhất / lạnh nhất + Top pick

VN Stock Workflow

• symbol: mã 3 chữ cái, ví dụ MBB, FPT, HPG.

• trigger interval: mặc định 1D; hỗ trợ 1D (khuyên dùng), 1W.

• Luôn multi-timeframe: khi chạy --trigger 1D sẽ tự động fetch thêm 1W
  làm structure TF (context xu hướng lớn). Hai role: structure + trigger,
  không có manage TF (Entrade API giới hạn khung).

• Với --trigger 1W: structure dùng lại 1W (cùng TF) vì Entrade không có 1M.

• Chạy full pipeline (khuyên dùng):

  python scripts/vn_stock_unified_flow.py {SYMBOL}
  python scripts/vn_stock_unified_flow.py {SYMBOL} --trigger 1D

  • Output: chat response đã validate + artifacts trong runs/vn/{symbol}/{trigger}/

• Chạy ingestion + decision engine (không render):

  python scripts/vn_stock_daily_flow.py {SYMBOL} --trigger 1D
  python scripts/vn_stock_daily_flow.py {SYMBOL} --trigger 1D --structure 1W --json-output

• Legacy single-TF (chỉ trigger, không structure — không khuyến khích):

  python scripts/vn_stock_harness.py {SYMBOL} --interval {interval} --limit 200
  python scripts/vn_stock_harness.py {SYMBOL} --interval 1D --limit 200 --write

• Đọc summary/output do script sinh ra. Nếu summary thiếu field bắt buộc, sửa
  extractor thay vì đọc raw runtime.

• Volume reliability của VN stock là cao vì volume matching tập trung trên sàn.

Position And Portfolio Commands

Khi người dùng báo lệnh spot đã khớp hoặc hỏi vị thế/danh mục, không chạy phân
tích thị trường và không sửa JSON thủ công. Route sang CLI deterministic.

Position Commands

Dùng scripts/position_cli.py cho lệnh mua/bán đã thực thi và xem vị thế:

• mua {amount}u {symbol} giá {price} khung {timeframe}
• mua thêm {amount}u {symbol} giá {price} khung {timeframe}
• bán {amount}u {symbol} giá {price} khung {timeframe}
• bán hết {symbol} giá {price} khung {timeframe}
• xem vị thế
• xem vị thế {symbol}

Chạy:

python scripts/position_cli.py "{USER_TEXT}"

Trả nguyên văn output của script. Không tự cập nhật
journal/open-positions.json.

Portfolio Commands

Dùng scripts/portfolio_cli.py cho câu hỏi phân bổ danh mục hoặc cấu hình vốn:

• xem tổng danh mục
• portfolio hiện tại
• {symbol} đang chiếm bao nhiêu %
• {symbol} còn được mua thêm bao nhiêu
• vị thế {symbol} hiện tại thế nào
• set danh mục spot {amount}u

Chạy:

python scripts/portfolio_cli.py "{USER_TEXT}"

Trả nguyên văn output của script.

Safety

• BẮT BUỘC dùng summary-first và validator/finalizer.
• Không phân tích dữ liệu cũ nếu pipeline thất bại.
• Không sửa source, cache hoặc input snapshot trong lúc phân tích.
• Không ghi action, setup grade, risk, invalidation hoặc chat verdict vượt engine
  contract.
• Nếu validator/finalizer reject, sửa pipeline output hoặc renderer; không mở rộng
  prompt runtime.