FinAssistant — AI-Powered Financial Analysis

RAG Retrieval & Agent System for China A-Share Market

Background • Features • Data Assets • Implementation • Tools

中文 | English

1. Background

The China A-share market has diverse data dimensions and massive information volumes. Retail investors and small-to-medium institutions struggle to efficiently integrate stock quotes, sector rotation, financial statements, and market news for comprehensive analysis. This project aims to build a financial RAG retrieval and agent system based on collected A-share data assets, enabling users to perform professional financial analysis through natural language conversations.

Core Objectives

Lower Analysis Barriers: Replace manual data queries, indicator calculations, and report writing with natural language
Multi-dimensional Data Correlation: Connect stocks, sectors, financials, and news for a panoramic view
Agent Collaboration: Multiple specialized agents working together, covering the full workflow from data queries to research reports

Tech Stack

Layer	Technology
Agent Framework	AgentScope 2.0 (Multi-Agent Orchestration)
Data Storage	MySQL (Structured Query) + Milvus (Vector Retrieval)
Data Collection	Python + akshare + DrissionPage
LLM	Qwen / GPT / Claude
Embedding	text-embedding-v3 / BGE
Frontend	Streamlit / Gradio

2. Feature Modules

Six intelligent agent modules planned based on existing data assets:

2.1 Stock Analysis Agent

Data Support: Daily stock quotes + Company info + Financial statements

Core Features:

Feature	Description	Implementation
Fundamental Score	Auto-score (0-100) based on ROE, gross margin, debt ratio, cash flow	Extract key fields from 3 statements, weighted calculation
Valuation Percentile	PE/PB/PCF percentile in 1-year history, determine over/undervalued	Calculate percentile on daily PE/PB series
Technical Indicators	MA(5/10/20/60), MACD, RSI, Bollinger Bands, KDJ	Real-time calculation based on OHLCV data
Trading Signals	Golden/Dead cross, MA breakout, RSI overbought/oversold	Technical indicator crossover detection
Stock Profile Report	Comprehensive fundamental + technical + valuation + sector report	LLM aggregates analysis results into text

Example Queries:

"How is Pudong Bank's cash flow situation this quarter?"
"What is Ping An Bank's current valuation percentile?"
"Analyze Kweichow Moutai's technical trend and give trading advice"
"Generate a stock profile report for CATL"

To-Do:

tools/stock_fundamental.py — Fundamental indicator calculator (Done)
tools/stock_valuation.py — Valuation percentile analyzer (Done)
tools/stock_technical.py — Technical indicator calculator (Done)
tools/stock_analysis.py — Comprehensive stock analysis report (Done)
agents/stock_agent.py — Stock analysis agent (Done)

Agent Demo:

$ python agents/stock_agent.py

============================================================
FinAssistant — 金融智能体
============================================================
输入股票代码或问题开始分析，输入 'quit' 退出
============================================================

你: 帮我分析贵州茅台的技术面走势，给出操作建议

FinAssistant:
[调用工具: reset_tools]
[完成] 结果: The currently activated tool group(s): stock-technical.

[调用工具: calc_technical_summary]
[完成] 结果: === 600519.SH 技术指标分析 (2026-07-17) ===
收盘价: 1253.0

【移动平均线 MA】
  MA5:  1237.78
  MA10: 1217.11
  MA20: 1204.07
  MA60: 1263.65
  均线趋势: 多头排列

【MACD】
  DIF: -0.2443
  DEA: -11.3353
  MACD柱: 22.182
  信号: 金叉

【RSI】
  RSI(6):  92.76
  RSI(12): 68.8
  RSI(24): 48.73
  RSI(6)信号: 超买

【布林带 BOLL】
  上轨: 1252.21
  中轨: 1204.07
  下轨: 1155.92

【KDJ】
  K: 84.3
  D: 79.2
  J: 94.49
  信号: 金叉

【综合研判】
  当前信号: MA多头排列, MACD金叉, RSI超买, KDJ金叉

### 贵州茅台(600519.SH)技术面分析与操作建议

#### 一、核心技术指标摘要（近120天）
| 指标类型 | 关键数据 | 信号解读 |
|---------|---------|---------|
| **均线系统** | MA5:1237.78, MA10:1217.11, MA20:1204.07, MA60:1263.65 | 短期均线多头排列，股价略低于MA60（1263.65），中期趋势依然向上 |
| **MACD** | DIF:-0.24, DEA:-11.34, MACD柱:22.18 | 低位金叉形成，空头趋势减弱，短期反弹信号明确 |
| **RSI** | RSI(6):92.76, RSI(12):68.80, RSI(24):48.73 | 短期RSI严重超买（>90），警惕回调风险 |
| **布林带** | 上轨:1252.21, 中轨:1204.07, 下轨:1155.92 | 股价突破上轨，处于强势区间，但短期乖离率偏大 |
| **KDJ** | K:84.30, D:79.20, J:94.49 | 高位金叉，短期上涨动能充足，但J线接近超买区 |

#### 二、综合研判
技术面呈现**强趋势与短期超买并存**的格局：
1.  **多头趋势明确**：均线多头排列、MACD低位金叉、KDJ金叉共同构成中期上涨信号
2.  **短期回调风险**：RSI超买、股价突破布林上轨提示短期涨幅过大，存在技术性回调需求

#### 三、操作建议
1.  **持仓投资者**：
    - 继续持有为主，可将MA20（1204.07）作为止损线
    - 若股价回落至MA5-MA10区间（1217-1238）可适当加仓
    - 短期若冲高至MA60（1263.65）遇阻，可考虑部分止盈

2.  **观望投资者**：
    - 等待回调至关键支撑位（MA20:1204或布林中轨:1204）再考虑进场
    - 若股价直接突破MA60并站稳，可小仓位追涨

⚠️ **风险提示**：技术分析仅供参考，不构成投资建议。市场存在不确定性，需结合自身风险承受能力决策。

2.2 Sector Rotation Analysis Agent

Data Support: Industry/Concept sector daily quotes (90 industry + 374 concept) + Constituent stocks

Core Features:

Feature	Description	Implementation
Sector Ranking	Rank by pct_chg, volume change, capital flow	Aggregate sector daily_index
Rotation Trend	Sectors with consecutive top N-day gains marked as "hot"	Sliding window rank change analysis
Sector Comparison	Multi-sector price curves overlay	Extract multiple sector close series
Constituent Distribution	Advance/decline count, limit up/down, median change	Link constituent daily data
Capital Flow	Volume change trend, determine inflow/outflow	Volume QoQ change analysis
Sector Correlation	Constituent stock overlap between two sectors	Set intersection/union ratio

Example Queries:

"Which industry sectors had the highest gains this week?"
"How has the semiconductor sector performed this month? Is capital flowing in or out?"
"How high is the overlap between AI and robotics concept constituents?"
"Which sectors had limit-down waves today?"

To-Do:

tools/sector_ranking.py — Sector ranking tool (Done)
tools/sector_rotation.py — Rotation trend identifier (Done)
tools/sector_compare.py — Sector comparison tool (Done)
tools/sector_detail.py — Sector deep analysis tool (Done)
agents/sector_agent.py — Sector analysis agent (Done)

Agent Demo:

$ python agents/sector_agent.py

============================================================
FinAssistant — 板块轮动分析智能体
============================================================
输入板块相关问题开始分析，输入 'quit' 退出
示例：
  - 最近一周涨幅最大的行业板块有哪些？
  - 半导体板块最近一个月资金是在流入还是流出？
  - AI概念和机器人概念的成分股重叠度有多高？
  - 今天哪些板块出现了跌停潮？
============================================================

你: 最近一周涨幅最大的行业板块有哪些？

FinAssistant:
[调用工具: get_sector_ranking]
[完成] 结果: === 行业板块涨跌幅排名 (2026-07-17) ===
Top 10:
排名  板块名称    涨跌幅(%)  成交额(亿)
1    通信设备    +5.23     312.45
2    半导体      +4.87     528.91
3    消费电子    +3.65     287.33
...

[调用工具: get_sector_top_gainers]
[完成] 结果: === 连续3天上涨的行业板块 ===
板块名称      连涨天数  累计涨幅(%)
半导体        3        +8.92
通信设备      3        +7.56
...

综合来看，最近一周涨幅最大的行业板块主要集中在科技领域：
1. **通信设备** (+5.23%) — 5G建设持续推进，板块领涨
2. **半导体** (+4.87%) — 国产替代逻辑强化，资金持续流入
3. **消费电子** (+3.65%) — 新品发布预期带动板块走强

其中半导体和通信设备已连续3天上涨，短期动能较强。

⚠️ 风险提示：板块轮动较快，追高需谨慎。以上分析仅供参考，不构成投资建议。

2.3 Cross-Data Correlation Analysis Agent

Data Support: Quotes + Constituents + Financial statements + News (Full data cross-correlation)

Core Features:

Feature	Description	Implementation
Stock→Sector Mapping	Query which sectors a stock belongs to, recent performance	Reverse lookup in constituent data
Sector→Financial Aggregation	Average ROE, median PE, total revenue for sector constituents	Link constituent codes to financial statements
News→Quote Correlation	Companies/sectors mentioned in news, link to recent price trends	NER entity recognition + code matching
Industry Chain	Infer upstream/downstream relationships via concept overlap	Constituent set similarity clustering
Leader Effect	Top N stocks by market cap vs sector overall performance	Market-cap weighted vs equal-weight index

Example Queries:

"Which concept sectors does BYD belong to? How are they performing?"
"What's the average PE and ROE for the semiconductor sector?"
"Any recent news about solar power? How are related sectors trending?"
"Find the top 5 stocks most correlated with CATL"

To-Do:

tools/stock_sector_mapping.py — Stock-sector mapping tool (Done)
tools/sector_financial_agg.py — Sector financial aggregation (Done)
tools/news_stock_linker.py — News-quote correlation tool (Done)
agents/correlation_agent.py — Correlation analysis agent (Done)

2.4 Financial Q&A Agent (RAG)

Data Support: Financial statements (4,593 stocks × multi-period) + Vector database (Milvus)

Core Features:

Feature	Description	Implementation
NL Financial Query	"Which companies have gross margin > 50%" → SQL/Vector search	Vectorize financial fields + structured query
Cross-stock Comparison	Horizontal comparison of financial indicators for same-industry companies	Group by industry + indicator comparison
Multi-period Trend	Vertical comparison of same company across periods	Time series analysis + trend detection
Anomaly Alert	Cash flow plunge, receivables surge, goodwill impairment	Threshold/QoQ change detection
Financial Health Score	Comprehensive solvency, profitability, growth, operational ability	DuPont analysis system + weighted scoring

Example Queries:

"Which banks have positive operating cash flow for the past year?"
"Compare CATL and BYD's debt ratio trends"
"Which companies had gross margin drop > 10% last quarter?"
"Give me a DuPont analysis for Kweichow Moutai"
"Find companies with ROE > 20% for 3 consecutive years"

To-Do:

tools/financial_query.py — Financial data query tool (Done)
tools/financial_compare.py — Financial comparison tool (Done)
tools/financial_anomaly.py — Anomaly detection tool (Done)
tools/financial_score.py — Financial health scoring tool (Done)
agents/financial_agent.py — Financial Q&A agent (Done)
rag/financial_embedding.py — Financial statement vectorization

2.5 Daily Market Report Agent

Data Support: Full data (Quotes + Sectors + News + Financials)

Core Features:

Feature	Description	Implementation
Market Overview	Major index changes, volume, advance/decline stats	Aggregate all market stock data
Sector Rotation Summary	Top gainers/losers, capital inflow/outflow Top5	Sector ranking tool output
Anomaly Detection	Limit up/down, volume breakout, abnormal volatility	Filter conditions
News Summary	Market-related important news, linked sectors	News filtering + LLM summary
Watchlist Report	User's watched stocks daily performance, announcements	Personalized filtering
Trend Assessment	Based on recent N-day data, market sentiment judgment	Multi-indicator synthesis

Example Queries:

"Generate today's market morning briefing"
"Which stocks hit limit up today? Which sectors do they belong to?"
"How has market sentiment been this week?"
"How are my watchlist stocks performing today?"

To-Do:

tools/market_overview.py — Market overview tool (Done)
tools/abnormal_detector.py — Anomaly detection tool (Done)
tools/market_trend.py — Trend assessment tool (Done)
tools/watchlist_report.py — Watchlist report tool (Done)
tools/daily_digest.py — Daily report generator (Done, integrates all 6 modules)
agents/daily_report_agent.py — Daily report agent

2.6 Research Report Generation Agent

Data Support: Full data + LLM generation capabilities

Core Features:

Feature	Description	Implementation
Stock Deep Report	Comprehensive fundamental + technical + valuation + industry position	Call previous tools + LLM long-text generation
Industry Research	Sector trends, constituent financials, industry chain analysis	Sector tools + Financial tools + LLM
Comparative Report	2-3 same-industry companies multi-dimensional comparison	Comparison tools + LLM
Event Impact Analysis	News/policy impact on related sectors and stocks	News correlation + Historical analogy + LLM
Portfolio Suggestion	Recommend sector/stock allocation based on risk preference	Optimization algorithm + LLM

Example Queries:

"Write a deep research report on the semiconductor industry"
"Compare BYD, CATL, and LONGi Green Energy with a comparative analysis"
"Which A-share sectors are most affected by Fed rate hikes?"
"I prefer conservative investing, recommend some sector allocation plans"

To-Do:

tools/report_generator.py — Report generation tool (LLM + templates)
templates/ — Report templates (stock/industry/comparison/event)
agents/report_agent.py — Report generation agent
agents/portfolio_agent.py — Portfolio optimization agent

3. Data Assets

3.1 Data Overview

Data Type	Volume	Source	Time Range
SH Stock Daily Quotes	2,308 stocks	Sina Finance (akshare)	2026-01-01 ~ Present
SZ Stock Daily Quotes	2,895 stocks	Sina Finance (akshare)	2026-01-01 ~ Present
SH Company Info	2,308 (Main 1,699 + STAR 609)	SSE (akshare)	-
SZ Company Info	2,895	SZSE (akshare)	-
SH Financial Statements	2,308 stocks	Sina Finance (akshare)	Recent 3 years
SZ Financial Statements	2,895 stocks	Sina Finance (akshare)	Recent 3 years
Industry Sector Quotes	90 sectors	Tonghuashun (akshare)	2026-01-01 ~ Present
Concept Sector Quotes	374 sectors	Tonghuashun (akshare)	2026-01-01 ~ Present
Industry Constituents	90 sectors	Tonghuashun (DrissionPage)	-
Concept Constituents	374 sectors	Tonghuashun (DrissionPage)	-
Financial News	-	Tonghuashun 7x24	2026-01-01 ~ Present

3.2 MySQL Table Schema

Data is stored in Alibaba Cloud RDS MySQL with two databases: market_data (quotes/financials) and stock_news (news).

market_data.company_info — Company Basic Info

CREATE TABLE company_info (
    id INT AUTO_INCREMENT PRIMARY KEY COMMENT 'Auto-increment ID',
    ts_code VARCHAR(20) NOT NULL COMMENT 'Stock code with suffix, e.g., 600000.SH',
    symbol VARCHAR(10) NOT NULL COMMENT 'Stock code (numeric only)',
    stock_name VARCHAR(50) COMMENT 'Stock short name',
    full_name VARCHAR(100) COMMENT 'Company full name',
    industry VARCHAR(50) COMMENT 'Industry, e.g., J Finance',
    list_date VARCHAR(20) COMMENT 'Listing date, format YYYY-MM-DD',
    market VARCHAR(5) COMMENT 'Market, SH=Shanghai SZ=Shenzhen',
    updated_at VARCHAR(30) COMMENT 'Data update time',
    UNIQUE KEY uk_ts_code (ts_code)
)

market_data.stock_kline — Stock Daily K-line

CREATE TABLE stock_kline (
    id BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT 'Auto-increment ID',
    ts_code VARCHAR(20) NOT NULL COMMENT 'Stock code with suffix',
    symbol VARCHAR(10) NOT NULL COMMENT 'Stock code (numeric only)',
    trade_date VARCHAR(20) NOT NULL COMMENT 'Trade date, format YYYY-MM-DD',
    open DOUBLE COMMENT 'Open price (CNY)',
    close DOUBLE COMMENT 'Close price (CNY)',
    high DOUBLE COMMENT 'High price (CNY)',
    low DOUBLE COMMENT 'Low price (CNY)',
    pre_close DOUBLE COMMENT 'Previous close (CNY)',
    change_data DOUBLE COMMENT 'Price change (CNY)',
    pct_chg DOUBLE COMMENT 'Change percentage (%)',
    volume DOUBLE COMMENT 'Volume (shares)',
    amount DOUBLE COMMENT 'Turnover (CNY)',
    pe DOUBLE COMMENT 'P/E ratio',
    pb DOUBLE COMMENT 'P/B ratio',
    total_mv DOUBLE COMMENT 'Total market cap (100M CNY)',
    total_share DOUBLE COMMENT 'Total shares',
    float_share DOUBLE COMMENT 'Float shares',
    circ_mv DOUBLE COMMENT 'Circulating market cap (100M CNY)',
    ln_pctchg DOUBLE COMMENT 'Log return',
    pe_ttm DOUBLE COMMENT 'P/E ratio (TTM)',
    pe_static DOUBLE COMMENT 'Static P/E ratio',
    pcf DOUBLE COMMENT 'Price-to-Cash-Flow ratio',
    UNIQUE KEY uk_code_date (ts_code, trade_date),
    KEY idx_trade_date (trade_date),
    KEY idx_symbol (symbol)
)

market_data.stock_financial — Financial Statements

CREATE TABLE stock_financial (
    id BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT 'Auto-increment ID',
    ts_code VARCHAR(20) NOT NULL COMMENT 'Stock code with suffix',
    symbol VARCHAR(10) NOT NULL COMMENT 'Stock code (numeric only)',
    statement_type VARCHAR(20) NOT NULL COMMENT 'Statement type: income/balance/cashflow',
    report_date VARCHAR(20) NOT NULL COMMENT 'Report date, e.g., 20260331',
    report_data JSON COMMENT 'Complete statement data (JSON)',
    UNIQUE KEY uk_code_type_date (ts_code, statement_type, report_date),
    KEY idx_symbol (symbol),
    KEY idx_report_date (report_date),
    KEY idx_statement_type (statement_type)
)

Financial fields vary significantly across industries (banking vs manufacturing), hence JSON storage for complete statement data.

market_data.sector_industry_daily / sector_concept_daily — Sector Daily K-line

CREATE TABLE sector_industry_daily (
    id BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT 'Auto-increment ID',
    sector_name VARCHAR(50) NOT NULL COMMENT 'Sector name',
    sector_code VARCHAR(20) NOT NULL COMMENT 'Sector code',
    trade_date VARCHAR(20) NOT NULL COMMENT 'Trade date',
    open DOUBLE COMMENT 'Open',
    high DOUBLE COMMENT 'High',
    low DOUBLE COMMENT 'Low',
    close DOUBLE COMMENT 'Close',
    vol DOUBLE COMMENT 'Volume',
    amount DOUBLE COMMENT 'Turnover',
    pct_chg DOUBLE COMMENT 'Change (%)',
    change_data DOUBLE COMMENT 'Point change',
    pct_change DOUBLE COMMENT 'Change (backup)',
    turnover_rate DOUBLE COMMENT 'Turnover rate',
    UNIQUE KEY uk_code_date (sector_code, trade_date),
    KEY idx_trade_date (trade_date),
    KEY idx_sector_name (sector_name)
)

market_data.sector_industry_cons / sector_concept_cons — Sector Constituents

CREATE TABLE sector_industry_cons (
    id BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT 'Auto-increment ID',
    sector_name VARCHAR(50) NOT NULL COMMENT 'Sector name',
    sector_code VARCHAR(20) NOT NULL COMMENT 'Sector code',
    stock_code VARCHAR(10) NOT NULL COMMENT 'Stock code',
    stock_name VARCHAR(50) COMMENT 'Stock name',
    UNIQUE KEY uk_sector_stock (sector_code, stock_code),
    KEY idx_sector_name (sector_name),
    KEY idx_stock_code (stock_code)
)

stock_news.news_em — Eastmoney 7x24 News

CREATE TABLE news_em (
    id INT AUTO_INCREMENT PRIMARY KEY COMMENT 'Auto-increment ID',
    title VARCHAR(500) NOT NULL COMMENT 'News title',
    digest TEXT COMMENT 'News digest',
    publish_time VARCHAR(30) COMMENT 'Publish time',
    url VARCHAR(500) COMMENT 'News URL',
    crawl_time VARCHAR(30) COMMENT 'Crawl time',
    UNIQUE KEY uk_title_time (title, publish_time)
)

stock_news.news_ths — Tonghuashun Financial News

CREATE TABLE news_ths (
    id INT AUTO_INCREMENT PRIMARY KEY COMMENT 'Auto-increment ID',
    news_id VARCHAR(20) NOT NULL COMMENT 'News ID',
    title VARCHAR(500) NOT NULL COMMENT 'News title',
    digest TEXT COMMENT 'News digest',
    url VARCHAR(500) COMMENT 'News URL',
    tags VARCHAR(500) COMMENT 'Tags (comma separated)',
    ctime_str VARCHAR(30) COMMENT 'Publish time',
    source VARCHAR(100) COMMENT 'Source',
    crawl_time VARCHAR(30) COMMENT 'Crawl time',
    UNIQUE KEY uk_news_id (news_id),
    KEY idx_ctime (ctime_str)
)

3.3 Data Import Scripts

Script	Target Table	Description
`import_company_info_to_mysql.py`	`market_data.company_info`	SH/SZ company info
`import_kline_to_mysql.py`	`market_data.stock_kline`	Stock daily K-line (560K+ rows)
`import_financial_to_mysql.py`	`market_data.stock_financial`	Financial statements (170K+ rows)
`import_sector_to_mysql.py`	`market_data.sector_*_daily`	Sector daily K-line
`import_sector_cons_to_mysql.py`	`market_data.sector_*_cons`	Sector constituents
`import_news_em_to_mysql.py`	`stock_news.news_em`	Eastmoney news
`import_news_ths_to_mysql.py`	`stock_news.news_ths`	Tonghuashun news

3.4 Data Collection Scripts

Script	Purpose	Source
`crawl_sh_stock_data.py`	SH stock quotes + company info	Sina Finance / SSE
`crawl_sz_stock_data.py`	SZ stock quotes + company info	Sina Finance / SZSE
`crawl_financial_reports.py`	Financial statements	Sina Finance
`crawl_sector_data.py`	Sector daily quotes (Industry + Concept)	Tonghuashun (akshare)
`crawl_sector_cons.py`	Sector constituents	Sina Finance (akshare)
`crawl_sector_cons_ths.py`	Sector constituents (backup)	Tonghuashun (DrissionPage)
`crawl_news_ths.py`	Financial news	Tonghuashun 7x24 API
`crawl_news_em.py`	Eastmoney 7x24 news (scheduled)	Eastmoney (akshare)

3.5 Known Issues

Issue	Description
Eastmoney API Blocked	`push2his.eastmoney.com` completely unavailable
Tonghuashun IP Blocked	Frequent crawling triggers Nginx 403 block
Inconsistent Sector Sources	Quotes from THS, constituents partially from Sina, names may not match
SH Company Missing Industry	SSE API doesn't provide industry field

4. AgentScope 2.0 Implementation

4.1 Architecture

User Query → FastAPI → Agent (system_prompt + model + toolkit + middlewares)
                              ↓
                         Toolkit
                           ├── ToolGroup("Stock Analysis")   → tools/stock_query.py + skills/stock-analysis/
                           ├── ToolGroup("Sector Analysis")   → tools/sector_query.py + skills/sector-rotation/
                           ├── ToolGroup("Financial Q&A")     → tools/financial_query.py + skills/financial-qa/
                           ├── ToolGroup("Daily Report")      → tools/news_query.py + skills/daily-report/
                           └── ToolGroup("Research Report")   → tools/indicators.py + skills/research-report/

4.2 Directory Structure

FinAssistant/
├── config.py                    # Global config (paths, model, API Key)
├── main.py                      # FastAPI service entry
├── main_agent.py                # Single agent script (no server, direct chat)
├── core/
│   ├── agent_setup.py           # Agent + Toolkit initialization
│   └── middleware.py            # Financial scenario middleware
├── tools/                       # Tool functions
│   ├── __init__.py
│   ├── stock_query.py           # Stock quote/company info query
│   ├── sector_query.py          # Sector quote/constituent query
│   ├── financial_query.py       # Financial statement query & analysis
│   ├── news_query.py            # News query
│   └── indicators.py            # Technical/fundamental indicator calculation
├── skills/                      # Skill documents (SKILL.md)
│   ├── stock-analysis/SKILL.md
│   ├── sector-rotation/SKILL.md
│   ├── financial-qa/SKILL.md
│   ├── daily-report/SKILL.md
│   └── research-report/SKILL.md
├── data/                        # Existing data (don't modify)
└── data_to_mysql_and_milvus/    # Existing crawler scripts (don't modify)

4.3 Implementation Steps

Step 1: config.py

Global configuration for data paths, model config, API keys.

Step 2: tools/ Tool Functions

Each function is async def, returns ToolChunk. Docstring is the tool description — LLM decides when to call based on docstring.

Step 3: skills/SKILL.md Skill Documents

Each skill directory has a SKILL.md with trigger conditions, dependent tools, and execution flow.

Step 4: core/middleware.py Middleware

Middleware	Purpose
`InputValidationMiddleware`	Filter non-financial queries
`ToolCallAuditMiddleware`	Log tool calls to traces/
`PerformanceMonitorMiddleware`	Monitor inference rounds, latency, tokens
`ContextEnrichmentMiddleware`	Inject current date, trading day context

Step 5: core/agent_setup.py Agent Initialization

Assemble model, tools, toolkit, and agent with middleware.

Step 6: main.py Service Entry

FastAPI service with OpenAI-compatible /v1/chat/completions endpoint.

5. Implemented Tools

tools/stock_fundamental.py — Fundamental Indicator Calculator

Calculates fundamental indicators from MySQL market_data.stock_financial table.

Core Functions:

Function	Description
`calc_fundamental_indicators(ts_code, report_date=None)`	Calculate single-period indicators
`calc_fundamental_trend(ts_code, periods=4)`	Calculate recent N-period trend
`get_financial_data(ts_code, report_date=None)`	Get raw statement data
`get_report_dates(ts_code, limit=8)`	Get report date list

Calculated Indicators:

Indicator	Formula	Data Source
ROE	Net Profit / Equity × 100%	Income + Balance Sheet
Gross Margin	(Revenue - COGS) / Revenue × 100%	Income Statement
Net Margin	Net Profit / Revenue × 100%	Income Statement
Debt Ratio	Total Liabilities / Total Assets × 100%	Balance Sheet
Cash Flow / Net Profit	Operating Cash Flow / Net Profit	Cash Flow + Income
Revenue YoY Growth	(Current - Prior Year) /	Prior Year
Net Profit YoY Growth	(Current - Prior Year) /	Prior Year
Revenue QoQ Growth	(Current Q - Prior Q) /	Prior Q
Net Profit QoQ Growth	(Current Q - Prior Q) /	Prior Q

Special Handling:

Auto bank detection: Via balance sheet fields (loans, deposits)
Bank field mapping: Revenue = Net Interest Income + Fee Income; COGS = Interest Expense + Fee Expense
YoY calculation: Cumulative values vs same quarter last year (2026Q1 vs 2025Q1)
QoQ calculation: Single-quarter values (Q4 = Annual - 9-month cumulative)

Usage:

from tools.stock_fundamental import calc_fundamental_indicators, calc_fundamental_trend

# Single period
result = calc_fundamental_indicators('600519.SH')
print(result['ROE'], result['毛利率'], result['营收同比增长率'])

# Trend (recent 4 periods)
trend = calc_fundamental_trend('600519.SH', periods=4)
for t in trend['trend']:
    print(t['report_date'], t['ROE'], t['营收同比增长率'])

tools/stock_valuation.py — Valuation Percentile Analyzer

Calculates PE/PB/PCF percentile in 1-year history from market_data.stock_kline table.

Core Functions:

Function	Description
`calc_valuation_percentile(ts_code, days=365)`	Calculate valuation percentile, return structured data
`calc_valuation_summary(ts_code, days=365)`	Generate formatted valuation summary
`get_valuation_history(ts_code, days=365)`	Get N-day valuation history
`get_latest_valuation(ts_code)`	Get latest day valuation data

Valuation Indicators:

Indicator	Description	Source
PE_TTM	Price-to-Earnings (Trailing Twelve Months)	stock_kline.pe_ttm
PB	Price-to-Book	stock_kline.pb
PCF	Price-to-Cash-Flow	stock_kline.pcf

Percentile Rules:

Percentile	Level	Meaning
< 20%	Undervalued	At historical low, potentially undervalued
20% - 40%	Below Average	Below historical median
40% - 60%	Fair	At historical median range
60% - 80%	Above Average	Above historical median
> 80%	Overvalued	At historical high, potentially overvalued

Usage:

from tools.stock_valuation import calc_valuation_percentile, calc_valuation_summary

# Get structured data
result = calc_valuation_percentile('600519.SH')
print(f"PE_TTM: {result['pe_ttm']}, Percentile: {result['pe_ttm_percentile']}%, {result['pe_ttm_level']}")

# Get formatted summary
print(calc_valuation_summary('600519.SH'))

tools/stock_technical.py — Technical Indicator Calculator

Calculates MA/MACD/RSI/BOLL/KDJ indicators from MySQL market_data.stock_kline table.

Core Functions:

Function	Description
`calc_technical_indicators(ts_code, days=120)`	Calculate all technical indicators
`calc_technical_summary(ts_code, days=120)`	Generate formatted summary
`get_kline_data(ts_code, days=120)`	Get K-line data from MySQL

Technical Indicators:

Indicator	Formula	Usage
MA(5/10/20/60)	Average of last N closing prices	Trend: Price above MA = bullish; MA crossover = buy/sell signal
MACD	DIF = EMA(12) - EMA(26); DEA = EMA(DIF,9); Histogram = (DIF-DEA)×2	Golden cross (DIF>DEA) = buy; Dead cross = sell
RSI(6/12/24)	RS = Avg Gain / Avg Loss; RSI = 100 - 100/(1+RS)	>80 = overbought; <20 = oversold
BOLL(20,2)	Upper = MA+2σ; Middle = MA; Lower = MA-2σ	Touch upper = overbought; Touch lower = oversold
KDJ(9,3,3)	RSV, K = 2/3K+1/3RSV, D = 2/3D+1/3K, J = 3K-2D	K>80 = overbought; K<20 = oversold; K/D crossover

Signal Interpretation:

Signal	MA	MACD	RSI	BOLL	KDJ
Bullish	MA5>MA10>MA20 (Bull alignment)	DIF>DEA, Histogram>0	RSI<20 (Oversold)	Price bounces off lower band	K/D golden cross in oversold zone
Bearish	MA5<MA10<MA20 (Bear alignment)	DIF<DEA, Histogram<0	RSI>80 (Overbought)	Price falls from upper band	K/D dead cross in overbought zone

Multi-indicator Confirmation:

Buy signals (need 2-3):

Price above MA20, MA bullish alignment (MA5>MA10>MA20)
MACD golden cross (DIF crosses above DEA)
RSI rebounds from oversold (<20 → >20)
Price bounces off Bollinger lower band
KDJ golden cross in oversold zone

Sell signals (need 2-3):

Price below MA20, MA bearish alignment (MA5<MA10<MA20)
MACD dead cross (DIF crosses below DEA)
RSI enters overbought (>80) then falls
Price falls from Bollinger upper band
KDJ dead cross in overbought zone

Usage:

from tools.stock_technical import calc_technical_indicators, calc_technical_summary

# Get structured data
result = calc_technical_indicators('600519.SH')
print(f"Close: {result['close']}, MA5: {result['ma5']}, MACD: {result['macd_signal']}")

# Get formatted summary
print(calc_technical_summary('600519.SH'))

5.5 Sector Analysis Tools

tools/sector_ranking.py — Sector Ranking Tool

Calculates sector rankings from MySQL sector_industry_daily / sector_concept_daily tables.

Core Functions:

Function	Description
`get_sector_ranking(sector_type, trade_date, top_n, sort_by)`	Sector ranking by pct_chg/amount/volume
`get_sector_top_gainers(sector_type, days, top_n)`	Sectors with consecutive N-day gains
`get_sector_top_losers(sector_type, days, top_n)`	Sectors with consecutive N-day losses
`get_sector_summary(sector_type, trade_date)`	Market overview (advance/decline, limit up/down)

Usage:

from tools.sector_ranking import get_sector_ranking, get_sector_top_gainers, get_sector_summary

# Top 10 industry sectors by pct_chg
print(get_sector_ranking(sector_type='industry', top_n=10))

# Sectors rising for 3 consecutive days
print(get_sector_top_gainers(sector_type='industry', days=3))

# Industry sector market overview
print(get_sector_summary(sector_type='industry'))

tools/sector_rotation.py — Rotation Trend Identifier

Analyzes sector momentum and capital rotation direction through short-term vs medium-term performance comparison.

Core Functions:

Function	Description
`get_sector_momentum(sector_type, short_days, long_days, top_n)`	Momentum analysis — short vs medium term, momentum score
`get_sector_rotation(sector_type, short_days, long_days, top_n)`	Rotation identification — capital inflow/outflow sectors
`get_sector_strength(sector_type, days, top_n)`	Strength ranking — composite score of gains, up-days, volume
`get_hot_cold_sectors(sector_type, days)`	Hot/cold classification — hot/warm/flat/cold categories

Usage:

from tools.sector_rotation import get_sector_momentum, get_sector_rotation, get_hot_cold_sectors

# Industry sector momentum (3-day short vs 10-day medium)
print(get_sector_momentum(sector_type='industry', short_days=3, long_days=10))

# Sector rotation (capital inflow/outflow)
print(get_sector_rotation(sector_type='industry'))

# Hot/cold sector classification
print(get_hot_cold_sectors(sector_type='industry', days=5))

tools/sector_compare.py — Sector Comparison Tool

Multi-sector price curve overlay comparison with normalization and ASCII trend charts.

Core Functions:

Function	Description
`compare_sectors(sector_names, sector_type, days)`	Multi-sector cumulative return comparison (table + ASCII chart)
`compare_sector_trend(sector_names, sector_type, days)`	Trend strength comparison with conclusion

Usage:

from tools.sector_compare import compare_sectors, compare_sector_trend

# Compare Baijiu vs Power vs Banks over 20 days
print(compare_sectors(['白酒', '电力', '银行'], sector_type='industry', days=20))

# Trend strength comparison with conclusion
print(compare_sector_trend(['白酒', '电力', '银行', '证券'], days=20))

tools/sector_detail.py — Sector Deep Analysis Tool

Links constituent stock data to provide internal sector structure analysis.

Core Functions:

Function	Description
`get_constituent_distribution(sector_name, sector_type, trade_date)`	Constituent distribution — advance/decline, limit up/down, median change, top/bottom 5
`get_sector_money_flow(sector_name, sector_type, days)`	Capital flow analysis — volume trend, price-volume coordination, inflow/outflow
`get_sector_correlation(sector_name1, sector_name2, sector_type)`	Sector correlation — Jaccard coefficient, overlapping constituents

Usage:

from tools.sector_detail import get_constituent_distribution, get_sector_money_flow, get_sector_correlation

# Baijiu sector constituent distribution
print(get_constituent_distribution('白酒', sector_type='industry'))

# Power sector capital flow analysis
print(get_sector_money_flow('电力', sector_type='industry', days=10))

# Baijiu vs Beer sector correlation
print(get_sector_correlation('白酒', '啤酒', sector_type='industry'))

tools/news_stock_linker.py — News-Stock Linker

Links news headlines to mentioned companies/sectors and correlates with their recent price trends.

Core Functions:

Function	Description
`find_news_by_keyword(keyword, limit)`	Search news by keyword (title/digest fuzzy match)
`search_news_with_market(keyword, limit, days_before, days_after)`	Search news and auto-correlate with matched stocks/sectors price trends

Usage Example:

from tools.news_stock_linker import find_news_by_keyword, search_news_with_market

# Search news by keyword
print(find_news_by_keyword('半导体', limit=5))

# Search news and correlate with market data
print(search_news_with_market('贵州茅台', limit=3, days_before=3, days_after=3))

5.6 Sector Analysis Agent

agents/sector_agent.py — Sector Analysis Agent

Integrates sector ranking, rotation, comparison, and deep analysis tool groups for sector rotation analysis.

Tool Group Structure:

Tool Group	Tools	Description
sector-ranking	`get_sector_ranking` / `get_sector_top_gainers` / `get_sector_top_losers` / `get_sector_summary`	Sector ranking
sector-rotation	`get_sector_momentum` / `get_sector_rotation` / `get_sector_strength` / `get_hot_cold_sectors`	Rotation analysis
sector-compare	`compare_sectors` / `compare_sector_trend`	Sector comparison
sector-detail	`get_constituent_distribution` / `get_sector_money_flow` / `get_sector_correlation`	Deep analysis

Run:

python agents/sector_agent.py

5.7 Correlation Analysis Agent

agents/correlation_agent.py — Correlation Analysis Agent

Integrates stock-sector mapping, sector financial aggregation, and news-market correlation tool groups for cross-data analysis.

Tool Group Structure:

Tool Group	Tools	Description
stock-sector	`find_stock_sectors`	Stock-sector mapping
sector-finance	`get_sector_financial_agg` / `get_sector_valuation_stats`	Sector financial aggregation, valuation distribution
news-market	`find_news_by_keyword` / `search_news_with_market`	News search, news-market correlation

Run:

python agents/correlation_agent.py

5.8 Financial Health Scoring Tool

tools/financial_score.py — Financial Health Scoring Tool

Computes a four-dimension composite financial health score (0-100) with rating (Excellent/Good/Fair/Poor).

Scoring Dimensions:

Dimension	Weight	Indicators
Profitability	30%	ROE(40%) + Gross Margin(30%) + Net Margin(30%)
Growth	25%	Revenue YoY Growth(50%) + Net Profit YoY Growth(50%)
Safety	25%	Debt Ratio(40%) + Cash Flow/NP(35%) + AR Ratio(25%)
Quality	20%	Deducted NP Ratio(50%) + Cash Flow Consistency(50%)

Anomaly Deduction: HIGH -5pts, MEDIUM -2pts, max -15pts.

Core Functions:

Function	Description
`calc_financial_score(ts_code, report_date=None)`	Calculate single stock financial health score
`format_financial_score(ts_code, report_date=None)`	Generate formatted Markdown output
`score_sector(sector_name, sector_type, top_n)`	Batch score sector constituents

Run:

python tools/financial_score.py --ts_code 600519.SH
python tools/financial_score.py --sector 白酒 --top_n 10
python tools/financial_score.py --ts_codes 600519.SH,300750.SZ,601318.SH

5.9 Financial Q&A Agent

agents/financial_agent.py — Financial Q&A Agent

Integrates fundamental indicators, trend analysis, comparison, anomaly detection, financial scoring, and batch screening tool groups for complex financial Q&A.

Tool Group Structure:

Tool Group	Tools	Description
fundamental	`calc_fundamental_indicators` / `calc_fundamental_trend` / `get_financial_data` / `get_report_dates`	Financial indicator calculation
compare	`compare_companies` / `compare_periods`	Financial comparison and trends
score-anomaly	`format_financial_score` / `calc_financial_score` / `detect_anomalies`	Scoring and anomaly detection
screening	`screen_cashflow_positive_stocks` / `screen_margin_decline_stocks` / `screen_roe_stocks`	Batch screening
query	`query_financial_data`	Financial data query

Example Queries:

"Which banks have positive operating cash flow for the past year?"
"Compare CATL and BYD's debt ratio trends"
"Which companies had gross margin drop > 10% last quarter?"
"Give me a DuPont analysis for Kweichow Moutai"
"Find companies with ROE > 20% for 3 consecutive years"

Run:

python agents/financial_agent.py

5.10 Daily Market Report Tools

tools/market_overview.py — Market Overview Tool

Aggregates all market stock data to compute daily market overview (advance/decline counts, limit up/down, turnover, etc.).

Core Functions:

Function	Description
`get_market_overview(trade_date=None)`	Get market overview as structured data
`format_market_overview(trade_date=None)`	Generate formatted Markdown output

Output Metrics:

Metric	Description
Advance/Decline	Up/down/flat counts and percentages
Limit Up/Down	Main board >=9.9%, ChiNext/STAR >=19.9%
Total Turnover	Market-wide turnover (100M CNY)
Avg/Median Change	Overall market change level
Market Sentiment	Strong rally/Bullish/Neutral/Bearish/Weak decline

Run:

python tools/market_overview.py
python tools/market_overview.py --trade_date 20260801

tools/abnormal_detector.py — Anomaly Detection Tool

Detects daily market anomalies: limit up/down stocks, volume breakouts, abnormal price movements, sector anomalies.

Core Functions:

Function	Description
`detect_abnormal(trade_date=None)`	Detect anomalies, return structured data
`format_abnormal(trade_date=None)`	Generate formatted Markdown output

Detection Types:

Type	Condition
Limit Up/Down	Main board >=9.9%, ChiNext/STAR >=19.9%
Volume Breakout	Volume ratio >3 AND gain >3% (ratio = current vol / 20-day avg vol)
Price Surge
Sector Anomaly

Run:

python tools/abnormal_detector.py
python tools/abnormal_detector.py --trade_date 20260801

tools/market_trend.py — Trend Assessment Tool

Multi-dimensional market sentiment analysis based on recent N-day data.

Core Functions:

Function	Description
`analyze_market_trend(days=5)`	Analyze market trend, return structured data
`format_market_trend(days=5)`	Generate formatted Markdown output

Scoring Dimensions (20 pts each, 100 total):

Dimension	Source	Logic
Advance/Decline Ratio	stock_kline 5-day	Average advancing stock ratio
Limit Up/Down Ratio	stock_kline latest	Limit up / (up + down + 1)
Turnover Trend	stock_kline 5-day	Recent 5d vs prior 5d, volume expansion/contraction
Sector Rotation	sector_industry_daily	Advancing sector ratio
Consecutive Trend	stock_kline 5-day	Consecutive up/down days

Sentiment Mapping: >=75 Optimistic / >=60 Mildly Bullish / >=40 Neutral / >=25 Mildly Bearish / <25 Pessimistic

Run:

python tools/market_trend.py
python tools/market_trend.py --days 10

tools/watchlist_report.py — Watchlist Report Tool

Personalized daily report for user-watched stocks: daily performance, 5-day change, related news.

Core Functions:

Function	Description
`get_watchlist_report(ts_codes, trade_date=None)`	Get watchlist report as structured data
`format_watchlist_report(ts_codes, trade_date=None)`	Generate formatted Markdown output

Report Content:

Module	Description
Daily Performance	Close price, change %, turnover
5-Day Change	Cumulative change over 5 trading days
Related News	Search news by stock name (max 3 per stock)

Watchlist Config: Edit tools/watchlist_config.json to set default watchlist.

Run:

python tools/watchlist_report.py --ts_codes 600519.SH,300750.SZ
python tools/watchlist_report.py  # Use default from watchlist_config.json

tools/daily_digest.py — Daily Report Generator (Enhanced)

Generates complete daily market briefing by integrating all 6 modules.

Core Functions:

Function	Description
`generate_daily_digest(trade_date=None, watchlist=None)`	Generate complete daily report (Markdown)

Report Structure:

Section	Module	Source
1	Market Overview	market_overview.py
2	Trend Assessment	market_trend.py
3	Sector Rotation	sector_ranking.py + sector_rotation.py
4	Market Anomalies	abnormal_detector.py
5	Important News	news_stock_linker.py
6	Watchlist Report (optional)	watchlist_report.py

Run:

python tools/daily_digest.py
python tools/daily_digest.py --trade_date 20260801
python tools/daily_digest.py --watchlist 600519.SH,300750.SZ

5.11 Tool Function Mapping

Existing langgraph_getdata/	New tools/	Description
`query_market_data_day_k.py`	`stock_query.py`	Stock K-line query
`query_industry_index_market.py`	`sector_query.py`	Sector quote query
`query_industry_component_list.py`	`sector_query.py`	Sector constituents
`query_concept_dc_day.py`	`sector_query.py`	Concept sector quotes
`query_concept_dc_stock.py`	`sector_query.py`	Concept sector constituents
`query_fin_account.py`	`financial_query.py`	Financial statement query (Done)
(None)	`news_query.py`	News query (New)
(None)	`stock_fundamental.py`	Fundamental indicators (Done)
(None)	`stock_valuation.py`	Valuation percentile (Done)
(None)	`stock_technical.py`	Technical indicators (Done)
(None)	`stock_sector_mapping.py`	Stock-sector mapping (Done)
(None)	`sector_financial_agg.py`	Sector financial aggregation (Done)
(None)	`news_stock_linker.py`	News-stock correlation (Done)
(None)	`financial_score.py`	Financial health scoring (Done)
(None)	`sector_data.py`	Sector data utilities (Done)
(None)	`market_overview.py`	Market overview tool (Done)
(None)	`abnormal_detector.py`	Anomaly detection tool (Done)
(None)	`market_trend.py`	Trend assessment tool (Done)
(None)	`watchlist_report.py`	Watchlist report tool (Done)
(None)	`daily_digest.py`	Daily report generator (Done)

5.12 Dependencies

pip install agentscope>=2.0.3 fastapi uvicorn

Name		Name	Last commit message	Last commit date
Latest commit History 91 Commits
agents		agents
backend		backend
competition		competition
congfig		congfig
data		data
data_to_mysql_and_milvus		data_to_mysql_and_milvus
evaluate		evaluate
frontend		frontend
img		img
langgraph_getdata		langgraph_getdata
log		log
skills		skills
src		src
test		test
tools		tools
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
README_CN.md		README_CN.md
logo.svg		logo.svg

Folders and files

Latest commit

History

Repository files navigation

FinAssistant — AI-Powered Financial Analysis

1. Background

Core Objectives

Tech Stack

2. Feature Modules

2.1 Stock Analysis Agent

2.2 Sector Rotation Analysis Agent

2.3 Cross-Data Correlation Analysis Agent

2.4 Financial Q&A Agent (RAG)

2.5 Daily Market Report Agent

2.6 Research Report Generation Agent

3. Data Assets

3.1 Data Overview

3.2 MySQL Table Schema

market_data.company_info — Company Basic Info

market_data.stock_kline — Stock Daily K-line

market_data.stock_financial — Financial Statements

market_data.sector_industry_daily / sector_concept_daily — Sector Daily K-line

market_data.sector_industry_cons / sector_concept_cons — Sector Constituents

stock_news.news_em — Eastmoney 7x24 News

stock_news.news_ths — Tonghuashun Financial News

3.3 Data Import Scripts

3.4 Data Collection Scripts

3.5 Known Issues

4. AgentScope 2.0 Implementation

4.1 Architecture

4.2 Directory Structure

4.3 Implementation Steps

Step 1: config.py

Step 2: tools/ Tool Functions

Step 3: skills/SKILL.md Skill Documents

Step 4: core/middleware.py Middleware

Step 5: core/agent_setup.py Agent Initialization

Step 6: main.py Service Entry

5. Implemented Tools

tools/stock_fundamental.py — Fundamental Indicator Calculator

tools/stock_valuation.py — Valuation Percentile Analyzer

tools/stock_technical.py — Technical Indicator Calculator

5.5 Sector Analysis Tools

tools/sector_ranking.py — Sector Ranking Tool

tools/sector_rotation.py — Rotation Trend Identifier

tools/sector_compare.py — Sector Comparison Tool

tools/sector_detail.py — Sector Deep Analysis Tool

tools/news_stock_linker.py — News-Stock Linker

5.6 Sector Analysis Agent

agents/sector_agent.py — Sector Analysis Agent

5.7 Correlation Analysis Agent

agents/correlation_agent.py — Correlation Analysis Agent

5.8 Financial Health Scoring Tool

tools/financial_score.py — Financial Health Scoring Tool

5.9 Financial Q&A Agent

agents/financial_agent.py — Financial Q&A Agent

5.10 Daily Market Report Tools

tools/market_overview.py — Market Overview Tool

tools/abnormal_detector.py — Anomaly Detection Tool

tools/market_trend.py — Trend Assessment Tool

tools/watchlist_report.py — Watchlist Report Tool

tools/daily_digest.py — Daily Report Generator (Enhanced)

5.11 Tool Function Mapping

5.12 Dependencies

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages