quant-agent 0.3.0__tar.gz

quant_agent-0.3.0/PKG-INFO

@@ -0,0 +1,450 @@
+Metadata-Version: 2.4
+Name: quant-agent
+Version: 0.3.0
+Summary: Vietnam Quantitative Trading and Market Data Agent
+Author: quant-agent
+License-Expression: MIT
+Keywords: vietnam,stock,quant,trading,agent,finance,algorithmic-trading
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pandas>=1.5.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: beautifulsoup4>=4.11.0
+Requires-Dist: plotly>=5.10.0
+Requires-Dist: python-dateutil>=2.8.0
+
+# quant-agent: Thư viện Phân tích Dữ liệu Chứng khoán & Giao dịch Việt Nam
+
+[![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![Market Data: Free](https://img.shields.io/badge/Market%20Data-Free%20%2F%20No%20Key-brightgreen.svg)]()
+[![Smoke Test](https://img.shields.io/badge/Smoke%20Test-45%2F48%20PASS-success.svg)]()
+
+**quant-agent** (Python package: quant_agent) là thư viện Python mã nguồn mở cung cấp dữ liệu thị trường tài chính Việt Nam (cổ phiếu, chỉ số thị trường, phái sinh, quỹ mở) dưới dạng `pandas.DataFrame` đã được chuẩn hóa. 
+
+Thư viện được thiết kế theo triết lý **Zero-Friction Market Data**: toàn bộ các hàm đọc dữ liệu thị trường đều hoạt động ngay lập tức mà không cần đăng ký tài khoản hay API key trả phí. Ngoài ra, thư viện cung cấp phân hệ kết nối giao dịch tự động qua tài khoản chứng khoán DNSE.
+
+---
+
+## 📑 Mục lục
+
+1. [Tính năng nổi bật](#-tính-năng-nổi-bật)
+2. [Hiện trạng nguồn dữ liệu (Cập nhật 2026)](#-hiện-trạng-nguồn-dữ-liệu-cập-nhật-2026)
+3. [Cài đặt](#-cài-đặt)
+4. [Kiến trúc & Code Flow](#-kiến-trúc--code-flow)
+5. [Hướng dẫn sử dụng nhanh](#-hướng-dẫn-sử-dụng-nhanh)
+   - [1. Danh sách mã niêm yết](#1-danh-sách-mã-niêm-yết)
+   - [2. Dữ liệu giá lịch sử & Kỹ thuật (OHLC)](#2-dữ-liệu-giá-lịch-sử--kỹ-thuật-ohlc)
+   - [3. Dữ liệu cơ bản doanh nghiệp](#3-dữ-liệu-cơ-bản-doanh-nghiệp)
+   - [4. Báo cáo tài chính & Chỉ số định giá](#4-báo-cáo-tài-chính--chỉ-số-định-giá)
+   - [5. Bảng giá, Sổ lệnh & Dữ liệu Intraday](#5-bảng-giá-sổ-lệnh--dữ-liệu-intraday)
+   - [6. Dữ liệu Quỹ mở (Fmarket)](#6-dữ-liệu-quỹ-mở-fmarket)
+   - [7. Trực quan hóa dữ liệu (Plotly Charts)](#7-trực-quan-hóa-dữ-liệu-plotly-charts)
+   - [8. Xuất dữ liệu sang AmiBroker](#8-xuất-dữ-liệu-sang-amibroker)
+   - [9. Giao dịch tự động qua Broker (DNSE)](#9-giao-dịch-tự-động-qua-broker-dnse)
+6. [Kiểm thử sức khỏe hệ thống (Smoke Test)](#-kiểm-thử-sức-khỏe-hệ-thống-smoke-test)
+7. [Tuyên bố miễn trừ trách nhiệm](#-tuyên-bố-miễn-trừ-trách-nhiệm)
+
+---
+
+## 🚀 Tính năng nổi bật
+
+- **Dữ liệu giá OHLC toàn diện**: Hỗ trợ cổ phiếu, chứng quyền, chỉ số (VNINDEX, VN30, HNX, UPCOM) và phái sinh (VN30F1M, VN30F2M...) với các khung thời gian 1 ngày, 1 giờ, 30 phút, 15 phút, 1 phút.
+- **Dữ liệu tài chính doanh nghiệp chuyên sâu**: Báo cáo tài chính (CĐKT, KQKD, LCTT) chuẩn hóa theo quý/năm; chỉ số P/E, P/B, ROE, ROA, EPS; hồ sơ doanh nghiệp, cơ cấu cổ đông, ban lãnh đạo, giao dịch nội bộ, sự kiện và tin tức.
+- **Sổ lệnh & Intraday thời gian thực**: Xem bảng giá trực tiếp, độ sâu sổ lệnh (Top 3 mức giá Mua/Bán tốt nhất) và chi tiết từng lệnh khớp trong phiên.
+- **Quỹ mở Việt Nam**: Danh mục tài sản, ngành nắm giữ, hiệu suất sinh lời và lịch sử biến động NAV của hơn 60 quỹ mở trên Fmarket.
+- **Biểu đồ trực quan chuẩn Quant**: Tích hợp vẽ biểu đồ nến Candlestick kèm Volume, đường MA và Bollinger Bands tương tác qua Plotly.
+- **Xuất dữ liệu AmiBroker**: Định dạng CSV tương thích ngay lập tức với phần mềm phân tích kỹ thuật AmiBroker.
+- **Đặt lệnh giao dịch thật qua Broker**: Module `broker.dnse` hỗ trợ đăng nhập JWT, xác thực 2 lớp OTP/Smart OTP, kiểm tra sức mua (PPSE), đặt lệnh, tra cứu và hủy lệnh.
+
+---
+
+## 📡 Hiện trạng nguồn dữ liệu (Cập nhật 2026)
+
+Hệ thống đã được tái cấu trúc và phân lập tầng nguồn dữ liệu (`quant_agent/sources/`):
+
+| Phân hệ / Dữ liệu | Nguồn upstream | Trạng thái | Ghi chú kỹ thuật |
+|---|---|---|---|
+| **Dữ liệu OHLC ngắn hạn / Intraday** | DNSE (Entrade Gateway) | 🟢 Hoạt động tốt | Hỗ trợ nến 1D, 1h, 30m, 15m, 1m (khung < 1D giới hạn 90 ngày gần nhất) |
+| **Dữ liệu OHLC dài hạn** | VCI (VietCap Securities) | 🟢 Hoạt động tốt | Tự động phân trang, trả tối đa 1000 nến/request |
+| **Danh sách mã chứng khoán** | Wifeed API / Local CSV | 🟢 Hoạt động tốt | SSI API thường bị chặn bởi Cloudflare bot-detection |
+| **Hồ sơ & Quản trị doanh nghiệp** | VCI (VietCap Securities) | 🟢 Hoạt động tốt | Tổng quan, mô tả KD, cổ đông lớn, ban lãnh đạo, công ty con, tin tức, sự kiện |
+| **Báo cáo & Chỉ số tài chính** | VCI (VietCap Securities) | 🟢 Hoạt động tốt | BCTC, chuỗi tài chính, P/E, P/B, ROE, ROA (tự động handshake session cookie) |
+| **Sổ lệnh độ sâu (Order Book)** | VPS (banggia.vps.com.vn) | 🟢 Hoạt động tốt | Top 3 bước giá Mua / Bán, bước khối lượng, room nước ngoài |
+| **Bảng giá & Khớp lệnh Intraday** | VCI (trading.vietcap.com.vn) | 🟢 Hoạt động tốt | Bảng giá trực tiếp, từng lệnh khớp lệnh mua/bán chủ động |
+| **Dữ liệu Quỹ mở** | Fmarket (api.fmarket.vn) | 🟢 Hoạt động tốt | Toàn bộ danh sách quỹ, NAV history, top holding cổ phiếu/trái phiếu |
+| **Giao dịch Broker DNSE** | Entrade Order Service | 🟢 Hoạt động tốt | Yêu cầu tài khoản giao dịch thực tế |
+
+---
+
+## 📦 Cài đặt
+
+### Yêu cầu môi trường
+- Python >= 3.10
+- Kết nối Internet ổn định
+
+### Cài đặt thư viện
+Clone repository và cài đặt ở chế độ editable hoặc build trực tiếp:
+
+```bash
+# Clone repository
+git clone https://github.com/quant-agent/quant-agent.git
+cd quant-agent
+
+# Cài đặt các gói phụ thuộc
+pip install -r requirements.txt
+
+# Hoặc cài đặt trực tiếp dạng package
+pip install -e .
+```
+
+---
+
+## 🏗 Kiến trúc & Code Flow
+
+### 1. Sơ đồ kiến trúc phân tầng (Layered Architecture)
+
+```mermaid
+graph TD
+    User["Lập trình viên / Quant Trader / Jupyter Notebook"]
+    
+    subgraph "Tầng Public API (quant_agent/__init__.py)"
+        API["Public Functions (stock_historical_data, company_overview, price_board, ...)"]
+    end
+    
+    subgraph "Tầng Domain Logic (Core Modules)"
+        TECH["technical.py<br>(OHLC, Intraday)"]
+        FUND["fundamental.py<br>(Profiles, Financials)"]
+        TRADE["trading.py<br>(Orderbook, Price Board)"]
+        FUNDS["funds.py<br>(Mutual Funds)"]
+        CHART["chart.py<br>(Plotly Visuals)"]
+        INTEG["integration.py<br>(AmiBroker Export)"]
+        BROKER["broker/dnse.py<br>(Authenticated Trading)"]
+    end
+    
+    subgraph "Tầng HTTP Plumbing & Fail-Safe"
+        CLIENT["sources/http_client.py<br>(fetch, fetch_json)"]
+        COOKIE["sources/vci.py<br>(vci_session_cookies Handshake)"]
+    end
+    
+    subgraph "Tầng Nguồn dữ liệu ngoài (Upstream Data Providers)"
+        VCI_API["VCI VietCap API<br>(Trading / IQ Service)"]
+        DNSE_API["DNSE / Entrade API<br>(Chart / User / Order)"]
+        VPS_API["VPS Banggia API<br>(Order Book)"]
+        FM_API["Fmarket API<br>(Mutual Funds)"]
+        WF_API["Wifeed API<br>(Stock List)"]
+    end
+
+    User --> API
+    API --> TECH
+    API --> FUND
+    API --> TRADE
+    API --> FUNDS
+    API --> CHART
+    API --> INTEG
+    API --> BROKER
+    
+    TECH --> CLIENT
+    FUND --> CLIENT
+    FUND --> COOKIE
+    TRADE --> CLIENT
+    FUNDS --> CLIENT
+    BROKER --> CLIENT
+    
+    CLIENT --> VCI_API
+    CLIENT --> DNSE_API
+    CLIENT --> VPS_API
+    CLIENT --> FM_API
+    CLIENT --> WF_API
+```
+
+### 2. Nguyên lý Code Flow
+
+1. **Top-Level Re-export Hub (`quant_agent/__init__.py`)**:
+   - Tất cả các hàm nghiệp vụ được re-export ra root namespace. Người dùng chỉ cần `import quant_agent as qa` và gọi `qa.stock_historical_data()`, `qa.company_overview()`, v.v. mà không cần quan tâm cấu trúc file bên dưới.
+
+2. **Cơ chế Fail-Safe & Fallback (`sources/http_client.py`)**:
+   - Mọi request HTTP đều đi qua `fetch_json()`.
+   - Nếu xảy ra lỗi mạng, timeout hoặc mã trạng thái HTTP khác 200, hàm sẽ in thông báo cảnh báo tường minh và trả về `None` thay vì quăng Exception làm crash chương trình.
+
+3. **Cơ chế Handshake Cookie Tự động (VCI Integration)**:
+   - Các endpoint thống kê tài chính chuyên sâu của VCI yêu cầu session cookie hợp lệ từ trang bảng giá.
+   - `quant_agent` tự động thực hiện handshake nhẹ qua `vci_session_cookies()` và đính kèm vào header request mà người dùng không cần can thiệp thủ công.
+
+4. **Luồng giao dịch bảo mật 2 lớp (`broker/dnse.py`)**:
+   - Tách biệt hoàn toàn khỏi các hàm đọc dữ liệu thị trường (Read-Only).
+   - Yêu cầu quy trình 2 bước: Đăng nhập nhận JWT Token -> Xác thực OTP nhận Trading Token -> Ký lệnh gửi lên sàn.
+
+---
+
+## 📖 Hướng dẫn sử dụng nhanh
+
+```python
+import quant_agent as qa
+```
+
+### 1. Danh sách mã niêm yết
+
+```python
+# Lấy danh sách toàn bộ cổ phiếu niêm yết (nguồn Wifeed - khuyến nghị)
+df_symbols = qa.listing_companies(live=True, source='Wifeed')
+print(df_symbols.head())
+
+# Hoặc đọc từ file CSV offline do bạn tự quản lý
+df_offline = qa.listing_companies(live=False, path='path/to/my_symbols.csv')
+```
+
+### 2. Dữ liệu giá lịch sử & Kỹ thuật (OHLC)
+
+```python
+# Lấy dữ liệu OHLC hàng ngày (mặc định nguồn DNSE)
+df_daily = qa.stock_historical_data(
+    symbol='TCB', 
+    start_date='2026-01-01', 
+    end_date='2026-08-30', 
+    resolution='1D', 
+    type='stock', 
+    beautify=True, # Đổi giá sang đơn vị VNĐ
+    decor=True     # Đặt 'Time' làm Index, đổi tên cột dạng Title Case (hỗ trợ TA-Lib)
+)
+print(df_daily.head())
+
+# Lấy dữ liệu nến intraday (15 phút, 1 giờ...) - Giới hạn 90 ngày gần nhất
+df_intraday = qa.stock_historical_data(
+    symbol='FPT', 
+    start_date='2026-08-01', 
+    end_date='2026-08-30', 
+    resolution='15' # '1', '15', '30', '1H'
+)
+
+# Lấy nến chỉ số thị trường hoặc phái sinh
+df_vnindex = qa.stock_historical_data(symbol='VNINDEX', type='index')
+df_vn30f1m = qa.stock_historical_data(symbol='VN30F1M', type='derivative')
+
+# Lấy dữ liệu OHLC dài hạn (nguồn VCI - VietCap, hỗ trợ tối đa 1000 nến/lần gọi)
+df_longterm = qa.stock_historical_data(
+    symbol='TCB', 
+    start_date='2022-01-01', 
+    end_date='2026-08-30', 
+    resolution='1D', 
+    source='VCI'
+)
+
+# Hoặc gọi hàm chuyên biệt:
+# df_longterm = qa.longterm_ohlc_data('TCB', start_date='2022-01-01', end_date='2026-08-30')
+```
+
+### 3. Dữ liệu cơ bản doanh nghiệp
+
+```python
+symbol = 'TCB'
+
+# 1. Tổng quan doanh nghiệp
+df_overview = qa.company_overview(symbol)
+
+# 2. Hồ sơ mô tả hoạt động kinh doanh (đã làm sạch thẻ HTML)
+df_profile = qa.company_profile(symbol)
+
+# 3. Danh sách cổ đông lớn
+df_shareholders = qa.company_large_shareholders(symbol)
+
+# 4. Ban lãnh đạo & Cán bộ chủ chốt
+df_officers = qa.company_officers(symbol)
+
+# 5. Danh sách công ty con & liên kết
+df_subsidiaries = qa.company_subsidiaries_listing(symbol)
+
+# 6. Lịch sử giao dịch nội bộ / cổ đông lớn
+df_insiders = qa.company_insider_deals(symbol)
+
+# 7. Sự kiện doanh nghiệp (cổ tức, chia tách, ĐHCĐ, M&A)
+df_events = qa.company_events(symbol)
+
+# 8. Tin tức doanh nghiệp mới nhất
+df_news = qa.company_news(symbol)
+
+# 9. Lịch sử chi trả cổ tức
+df_div = qa.dividend_history(symbol)
+
+# 10. Biên độ giá & Room ngoại
+df_volatility = qa.ticker_price_volatility(symbol)
+```
+
+### 4. Báo cáo tài chính & Chỉ số định giá
+
+```python
+symbol = 'HPG'
+
+# Lấy Báo cáo tài chính theo năm hoặc quý (BalanceSheet, IncomeStatement, CashFlow)
+df_bs = qa.financial_report(symbol, report_type='BalanceSheet', frequency='Quarterly')
+df_is = qa.financial_report(symbol, report_type='IncomeStatement', frequency='Yearly')
+df_cf = qa.financial_report(symbol, report_type='CashFlow', frequency='Yearly')
+
+# Chuỗi thời gian chỉ tiêu tài chính
+df_flow = qa.financial_flow(symbol, report_type='incomestatement', report_range='quarterly')
+
+# Chỉ số tài chính chuyên sâu (P/E, P/B, ROE, ROA, EPS, Biên lợi nhuận...)
+df_ratios_yearly = qa.financial_ratio(symbol, report_range='yearly', is_all=True)
+df_ratios_quarterly = qa.financial_ratio(symbol, report_range='quarterly')
+
+# So sánh chỉ số tài chính nhiều cổ phiếu cùng kỳ
+df_compare = qa.financial_ratio_compare(symbol_ls=['HPG', 'NKG', 'HSG'], frequency='Quarterly')
+print(df_compare)
+
+# Lịch sử biến động P/E và P/B theo từng quý
+df_pe_pb = qa.stock_evaluation(symbol)
+```
+
+### 5. Bảng giá, Sổ lệnh & Dữ liệu Intraday
+
+```python
+# Bảng giá thời gian thực (Top 3 mức giá mua/bán, giá khớp lệnh)
+df_board = qa.price_board(['TCB', 'SSI', 'FPT'])
+
+# Sổ lệnh độ sâu (VPS Order Book)
+df_depth = qa.price_depth('TCB,SSI,VND')
+
+# Từng giao dịch khớp lệnh trong phiên (Tick-by-tick intraday trades)
+df_trades = qa.stock_intraday_data('ACB', page_size=100)
+```
+
+### 6. Dữ liệu Quỹ mở (Fmarket)
+
+```python
+import quant_agent.funds as qa_funds
+
+# Lấy danh sách các quỹ mở (Lọc theo fund_type: "", "STOCK", "BOND", "BALANCED")
+df_funds = qa_funds.funds_listing(fund_type="STOCK")
+
+# Lấy thông tin top danh mục nắm giữ của quỹ (Ví dụ mã quỹ 'VESAF' hoặc fundId=23)
+df_top_holdings = qa_funds.fund_details(symbol='VESAF', type='top_holding_list')
+
+# Lấy tỷ trọng phân bổ tài sản theo ngành
+df_industry = qa_funds.fund_industry_holding(fundId=23)
+
+# Lịch sử NAV/CCQ hàng ngày của quỹ
+df_nav = qa_funds.fund_nav_report(fundId='23')
+```
+
+### 7. Trực quan hóa dữ liệu (Plotly Charts)
+
+```python
+import quant_agent.chart as qa_chart
+
+# Lấy dữ liệu OHLC
+df = qa.stock_historical_data('TCB', start_date='2026-01-01', end_date='2026-08-30')
+
+# 1. Vẽ biểu đồ nến Candlestick + Volume + các đường MA
+fig_candle = qa_chart.candlestick_chart(
+    df, 
+    title='TCB - Candlestick Chart', 
+    ma_periods=[10, 20, 50], 
+    reference_period=90
+)
+fig_candle.show()
+
+# 2. Tính toán và vẽ Bollinger Bands
+df_bb = qa_chart.bollinger_bands(df, window=20, num_std_dev=2)
+fig_bb = qa_chart.bollinger_bands_chart(df_bb, title='TCB - Bollinger Bands')
+fig_bb.show()
+```
+
+### 8. Xuất dữ liệu sang AmiBroker
+
+```python
+# Xuất dữ liệu ra file CSV chuẩn tương thích AmiBroker
+qa.amibroker_ohlc_export(
+    path='./data_export', 
+    symbol='TCB', 
+    start_date='2026-01-01', 
+    end_date='2026-08-30', 
+    resolution='1D'
+)
+```
+
+### 9. Giao dịch tự động qua Broker (DNSE)
+
+> ⚠️ **CẢNH BÁO QUAN TRỌNG:**
+> Phân hệ `broker` thực hiện đặt lệnh thật trên tài khoản chứng khoán thực tế với tiền thật. Hãy kiểm tra kỹ tham số trước khi gọi các hàm đặt lệnh.
+
+```python
+from quant_agent.broker import DNSEClient
+
+client = DNSEClient()
+
+# 1. Đăng nhập lấy JWT Token
+client.login(user_name="064CXXXXXX", password="YOUR_PASSWORD")
+
+# 2. Xem thông tin tài khoản & danh sách tiểu khoản
+profile = client.account()
+sub_accs = client.sub_accounts()
+sub_id = "064CXXXXXX1"
+
+# 3. Tra cứu số dư và sức mua
+balance = client.account_balance(sub_id)
+capacity = client.trade_capacities(symbol="TCB", price=34000, sub_account=sub_id)
+
+# 4. Xác thực 2 bước lấy Trading Token (cần thiết trước khi đặt lệnh)
+# client.email_otp() # Nếu dùng Email OTP
+client.get_trading_token(otp="123456", smart_otp=True)
+
+# 5. Đặt lệnh mua/bán (THẬT)
+order = client.place_order(
+    sub_account=sub_id,
+    symbol="TCB",
+    side="buy",       # 'buy' hoặc 'sell'
+    quantity=100,
+    price=34000,
+    order_type="LO",
+    loan_package_id=None,
+    asset_type="stock"
+)
+
+# 6. Tra cứu sổ lệnh và hủy lệnh
+orders = client.order_list(sub_account=sub_id)
+# client.cancel_order(order_id="...", sub_account=sub_id)
+```
+
+---
+
+## 🩺 Kiểm thử sức khỏe hệ thống (Smoke Test)
+
+Do `quant_agent` kết nối trực tiếp tới các cổng API tài chính không chính thức của các bên thứ ba, bạn có thể chạy bộ kiểm thử smoke test bất cứ lúc nào để kiểm tra tính sẵn sàng của từng endpoint:
+
+```bash
+python tests/test_smoke.py
+```
+
+Kết quả kiểm thử thực tế:
+```
+Feature                                                    Status   Detail
+------------------------------------------------------------------------------------------------------------------------
+config.today                                               PASS     2026-09-06
+fundamental.listing_companies(live=True, Wifeed)           PASS     shape=(1820, 6)
+fundamental.company_overview [VCI]                         PASS     shape=(1, 8)
+fundamental.company_large_shareholders [VCI]               PASS     shape=(56, 7)
+fundamental.financial_ratio(yearly) [VCI]                  PASS     shape=(53, 5)
+fundamental.financial_report(BalanceSheet) [VCI]           PASS     shape=(8, 338)
+technical.stock_historical_data(DNSE)                      PASS     shape=(33, 7)
+technical.stock_historical_data(VCI)                       PASS     shape=(32, 7)
+technical.longterm_ohlc_data [VCI]                         PASS     shape=(151, 7)
+trading.price_board [VCI]                                  PASS     shape=(2, 16)
+trading.price_depth [VPS]                                  PASS     shape=(2, 22)
+trading.stock_intraday_data [VCI]                          PASS     shape=(20, 5)
+funds.funds_listing                                        PASS     shape=(68, 11)
+chart.candlestick_chart                                    PASS     Figure(...)
+integration.amibroker_ohlc_export [DNSE]                   PASS     wrote CSV, shape=(33, 7)
+...
+45/48 PASS, 3 EMPTY (expected: SSI Cloudflare), 0 CRASH
+```
+
+---
+
+## ⚖️ Tuyên bố miễn trừ trách nhiệm (Disclaimer)
+
+1. **quant-agent** (Python package: quant_agent) là dự án mã nguồn mở phục vụ mục đích nghiên cứu, học tập và phân tích dữ liệu cá nhân.
+2. Thư viện kết nối tới các dịch vụ API công cộng/không chính thức của các tổ chức tài chính. Tác giả không sở hữu, không đảm bảo tính sẵn sàng liên tục, tính toàn vẹn hoặc độ trễ thấp nhất của dữ liệu.
+3. Người dùng tự chịu hoàn toàn trách nhiệm pháp lý và tài chính khi sử dụng module đặt lệnh (`broker`) trên tài khoản giao dịch thực tế của mình.