vnstock-ezchart 1.0.2

A production-ready, AI-agent-friendly charting toolkit for Vietnamese financial markets — built on Matplotlib, Seaborn & mplfinance with a Soft Premium styling engine, branded logo injection, and 20+ publication-quality chart types out of the box

Giới thiệu vnstock_ezchart

---

🌐 English version below

Tầm nhìn: vnstock_ezchart ra đời với sứ mệnh tạo ra ngôn ngữ trực quan hoá dữ liệu chuyên nghiệp, chuẩn hoá dành cho cộng đồng đầu tư tại Việt Nam.

Trong bối cảnh số đông nhà đầu tư đang dần tiếp cận với Python và API chứng khoán qua vnstock, việc tự viết code hoặc yêu cầu AI vẽ biểu đồ từ con số 0 thường tốn rất nhiều thời gian, tiêu tốn token, và khó duy trì được tính nhất quán về mặt thẩm mỹ.

Tại sao lại là biểu đồ tĩnh (Static Charting)? vnstock_ezchart tập trung tối đa vào việc tạo ra các biểu đồ tĩnh để giải quyết triệt để các bài toán thực tiễn:

1. Nghiên cứu & Học thuật: Kết xuất ảnh với độ nét cao, dễ dàng nhúng trực tiếp vào các báo cáo phân tích, tài liệu in ấn mà không bị vỡ nét hay phụ thuộc vào trình duyệt web.
2. Tự động hoá phân tích đầu tư: Hỗ trợ xuất ảnh để tự động gửi báo cáo danh mục, phân tích kỹ thuật hay tín hiệu giao dịch cho khách hàng/nhà đầu tư qua các nền tảng chat (Telegram, Discord, Zalo). Dễ dàng tích hợp tự động hóa qua Openclaw hoặc bất kỳ AI Agent nào.
3. Phân tích Thị giác bằng AI: Khi cung cấp biểu đồ tĩnh cho các AI Agent (ví dụ trong Google Antigravity hay các IDE khác), bản thân AI có thể "nhìn" và đọc hiểu hình ảnh biểu đồ giống hệt cách con người trải nghiệm. Điều này giúp AI đưa ra những nhận định, phân tích đáng tin cậy dựa trên mặt hình ảnh thay vì chỉ đọc các con số.

Thư viện giúp tự động hóa toàn bộ khâu xử lý thẩm mỹ và định vị thương hiệu (chèn logo), mang lại kết quả đầu ra sẵn sàng sử dụng ngay lập tức cho các báo cáo phân tích chuyên nghiệp.

---

🤖 Kiến trúc Agent-Ready

Thư viện được thiết kế tối ưu hóa 100% cho khả năng tương tác với AI Agent. Các hàm vẽ biểu đồ sử dụng Docstrings chuẩn Google-style bằng tiếng Anh, giúp các Agent hiểu rõ ngữ nghĩa và cú pháp ngay lập tức. Bạn có thể kết hợp thư viện này hoàn hảo với hệ sinh thái AI thông qua bộ tài liệu Vnstock Agent Guide.

---

⚡ Cài đặt & Khởi tạo

# Cài đặt thư viện mặc định
pip install vnstock-ezchart

# Cài đặt thêm các thành phần bổ trợ (Treemap, Wordcloud)
pip install vnstock-ezchart[all]

Khởi tạo & Tuỳ biến Giao diện (Theming & Branding)

Thay vì phải lặp lại thiết lập màu sắc hay logo cho từng đồ thị, vnstock_ezchart hỗ trợ cấu trúc Global Theme giúp bạn chỉ cần khai báo một lần duy nhất.

1. Sử dụng Theme có sẵn

Thư viện cung cấp sẵn nhiều bộ theme chuyên nghiệp: vnstock (Soft Premium), academic (Báo cáo khoa học), minimal (Tối giản hiện đại), flatui, v.v.

from vnstock_ezchart import Chart

# Cài đặt Theme, Font & Ngôn ngữ toàn cục
Chart.set_theme(theme_name='vnstock', font_name='Inter', lang='vi')

2. Tự định nghĩa Theme màu sắc (Custom Palette)

Bạn hoàn toàn có thể tự tạo bộ màu mang bản sắc riêng bằng cách đăng ký vào Utils.brand_palettes. Hãy chú ý đến tính Ngữ nghĩa (Semantic) của thứ tự màu:

• Index 0: Màu Tích cực / Tăng trưởng (VD: Xanh lá)
• Index 1: Màu Dữ liệu chính
• Index 2: Màu Phụ trợ / Cảnh báo (VD: Vàng/Cam)
• Index 3: Màu Tiêu cực / Giảm điểm (VD: Đỏ)

from vnstock_ezchart.utils import Utils

# Định nghĩa Theme mới
Utils.brand_palettes['my_theme'] = ['#10B981', '#1E293B', '#F59E0B', '#EF4444', '#64748B', '#CBD5E1']

# Kích hoạt Theme vừa tạo
Chart.set_theme(theme_name='my_theme', lang='vi')

3. Thay đổi Logo Watermark thương hiệu

Thư viện cho phép bạn tự do thay thế Watermark mặc định bằng logo của cá nhân/doanh nghiệp:

# Thay thế logo toàn cục bằng đường dẫn file hoặc URL
Chart.set_logo("https://your-domain.com/path/to/your/logo.png")

# Tắt hoàn toàn logo
Chart.set_logo(None)

---

📈 Khả năng Phân tích Đầu tư Chuyên sâu

Lấy cảm hứng từ các nền tảng phân tích định lượng học thuật, vnstock_ezchart sở hữu khả năng biến hóa đa dạng để phục vụ vô vàn ngữ cảnh trong tài chính và chứng khoán.

Phân tích Kỹ thuật Nâng cao & Tâm lý Thị trường

Khả năng "chồng lớp" (Multi-layer) nhiều chiều dữ liệu lên cùng một biểu đồ mà vẫn giữ được sự tinh tế:

Thư viện Chỉ báo Kỹ thuật Đa dạng

Hỗ trợ trực quan hóa sinh động hàng chục chỉ báo phân tích kỹ thuật phổ biến với độ tuỳ biến cao, dễ dàng tùy chỉnh màu sắc, vùng tô (fill) và các lớp thông tin (overlays). Hỗ trợ hoàn hảo ngay cả những chỉ báo phức tạp đa chiều (như Ichimoku, Bollinger Bands, MACD, Donchian Channels v.v.):

Quản trị Hiệu suất & Rủi ro

Cung cấp góc nhìn tổ chức (Institutional-grade) về danh mục đầu tư:

Phân bổ & Đánh giá Danh mục

Trực quan hóa cấu trúc danh mục và tương quan thị trường đa lớp tài sản:

Dữ liệu Thị trường & Phân tích Doanh nghiệp

Khắc họa sâu sắc bức tranh tài chính doanh nghiệp và thanh khoản thị trường:

Thẻ Tóm tắt Cổ phiếu (Stock Summary Card)

Hiển thị thông tin tóm tắt về cổ phiếu theo thiết kế giao diện UI hiện đại (Soft Premium) tương tự các website tài chính hàng đầu.

Đa Dạng Theme Thiết Kế (Multi-Theme Support)

Thư viện hỗ trợ nhiều theme phù hợp với các ngữ cảnh ứng dụng khác nhau. Ví dụ dưới đây là sự khác biệt giữa theme vnstock (Soft Premium), academic (chuẩn báo cáo khoa học), và minimal (tối giản):

Trực quan hóa Backtesting (Backtesting Visualization)

Cung cấp bộ biểu đồ đầy đủ thông tin cho chiến lược backtest: nến nhật, khối lượng, điểm vào/ra lệnh, đường cong lợi nhuận và drawdown trên cùng một trục thời gian.

---

📂 Example Gallery - Bộ Sưu Tập Kịch Bản Chuyên Nghiệp

Mã nguồn mẫu đã được chia nhỏ thành các nhóm ứng dụng riêng biệt giúp bạn dễ dàng theo dõi, bảo trì và sử dụng:

• examples/01_performance_risk.py: Quản trị Hiệu suất & Rủi ro.
• examples/02_technical_analysis.py: Phân tích Kỹ thuật.
• examples/03_portfolio_management.py: Phân bổ Danh mục.
• examples/04_market_data.py: Dữ liệu Thị trường.
• examples/05_enterprise_analysis.py: Phân tích Doanh nghiệp.
• examples/06_summary_cards.py: Thẻ Tóm tắt Cổ phiếu.
• examples/07_backtest.py: Trực quan hóa kiểm thử - Backtesting.

Bạn có thể chạy toàn bộ các kịch bản để sinh ảnh song ngữ (VI & EN):

python3 examples/run_all.py

---

English Version

Vision: vnstock_ezchart aims to provide a standardized and professional data visualization language for the Vietnamese investment community.

As more investors adopt Python and stock APIs via vnstock, writing code or asking AI to draw charts from scratch often takes significant time, consumes tokens, and struggles to maintain aesthetic consistency.

Why Static Charting? vnstock_ezchart focuses extensively on generating static charts under the "Soft Premium" design philosophy to solve real-world practical problems:

1. Academic & Research: Export high-resolution images that are easily embedded directly into analysis reports, academic papers, or printed documents without pixelation or browser dependencies.
2. Real-world Automated Investing: Export charts to automatically send portfolio reports, technical analysis, or trading signals to clients and investors via chat platforms (Telegram, Discord, Zalo) by integrating with Openclaw or any AI Agent.
3. AI Vision Analysis: When static charts are provided to AI Agents (within Antigravity or other IDEs), the AI can "see" and interpret the charts exactly as a human experiences them visually. This enables the AI to provide highly reliable, visually-grounded analysis and insights rather than just reading dry data points.

The library automates all aesthetic processing and branding (logo insertion), delivering an output that is immediately ready for professional reports!

---

🤖 Agent-Ready Architecture

Optimized for AI Agents with English Google-style Docstrings. Compatible with the Vnstock Agent Guide.

---

⚡ Installation & Initialization

pip install vnstock-ezchart
pip install vnstock-ezchart[all]

Theming & Branding Initialization

Instead of repeating color or logo configurations for each chart, vnstock_ezchart supports a Global Theme architecture so you only need to declare it once.

1. Using Built-in Themes

The library provides several professional themes out of the box: vnstock (Soft Premium), academic (Scientific Reports), minimal (Modern Slate), flatui, etc.

from vnstock_ezchart import Chart

# Setup Global Theme, Font & Language
Chart.set_theme(theme_name='vnstock', font_name='Inter', lang='en')

2. Defining Custom Color Palettes

You can create your own brand identity by registering a custom palette to Utils.brand_palettes. Please pay attention to the Semantic ordering of the colors:

• Index 0: Positive / Up Color (e.g., Green)
• Index 1: Primary Data Color
• Index 2: Secondary / Warning Color (e.g., Yellow/Orange)
• Index 3: Negative / Down Color (e.g., Red)

from vnstock_ezchart.utils import Utils

# Define new custom theme
Utils.brand_palettes['my_theme'] = ['#10B981', '#1E293B', '#F59E0B', '#EF4444', '#64748B', '#CBD5E1']

# Activate the new theme
Chart.set_theme(theme_name='my_theme', lang='en')

3. Replacing the Brand Watermark Logo

The library allows you to freely replace the default watermark with your own personal or corporate logo:

# Replace global logo using a file path or URL
Chart.set_logo("https://your-domain.com/path/to/your/logo.png")

# Completely disable the logo
Chart.set_logo(None)

---

📈 Investment Analysis Showcase

Advanced Technical Analysis & Sentiment

Comprehensive Technical Indicators Library

Supports visualizing dozens of popular technical analysis indicators with high customizability, easily adjusting colors, fill areas, and overlays. Perfectly handles complex, multi-dimensional indicators (such as Ichimoku, Bollinger Bands, MACD, Donchian Channels, etc.):

Performance & Risk Management

Portfolio Allocation & Evaluation

Market Data & Enterprise Analysis

Stock Summary Card

Multi-Theme Support

The library supports multiple themes tailored for different application contexts. Below is a comparison between the vnstock (Soft Premium) theme, the academic theme (for scientific reports), and the minimal theme:

Backtesting Visualization

Provides a comprehensive chart for backtesting strategies: candlesticks, volume, entry/exit points, equity curve, and drawdown on a unified timeline.

---

📂 Example Gallery - Professional Scenario Collection

The sample source code has been broken down into separate application groups, making it easy for you to track, maintain, and use:

• examples/01_performance_risk.py: Performance & Risk Management.
• examples/02_technical_analysis.py: Technical Analysis.
• examples/03_portfolio_management.py: Portfolio Allocation.
• examples/04_market_data.py: Market Data.
• examples/05_enterprise_analysis.py: Enterprise Analysis.
• examples/06_summary_cards.py: Stock Summary Card.
• examples/07_backtest.py: Backtesting Visualization.

You can run all the scripts above simultaneously to output the bilingual image collection:

python3 examples/run_all.py