tushare

tushare

Converts natural language financial data requests into executable Tushare data workflows.

This is a natural language financial data research skill.

What this skill is for

Typical use cases:

• Check recent performance of a stock, index, or ETF
• Look up company fundamentals, valuation, financial trends
• Cross-compare multiple instruments
• Analyze money flows, northbound funds, top list, sector strength
• Review announcements, news, research reports, policy clues
• View macro data like CPI/PPI/PMI/social financing/interest rates
• Export CSV/parquet for further analysis or backtesting
• Generate concise research summaries instead of raw field tables

Understand the user's problem first, then select interfaces, fetch data, organize, explain, and deliver.

---

When to use

Use this skill when the user expresses the following intents:

Market / Trend

• How's XX doing lately?
• How much has XX risen over this period?
• How has it performed this year?
• Has volume picked up recently?
• Is this stock strong lately?

Financials / Valuation / Company Quality

• Check XX's financial reports
• Profit trend over recent quarters
• How's the financial quality?
• How's the cash flow?
• Is the valuation high now?
• Show me PE/PB/ROE/gross margin

Comparison / Ranking / Screening

• Which is stronger, XX or YY?
• Do a horizontal comparison for me
• Which companies have faster profit growth?
• Screen for high ROE and low debt
• Give me a top 10

Sector / Index / Theme

• Which sector is strongest lately?
• How's the semiconductor sector doing?
• Why is robotics up?
• What are the index constituents?
• Which themes are hottest?

Money Flow / Sentiment

• What are funds buying lately?
• Where are northbound funds flowing?
• Which sector is attracting the most capital?
• Who has the largest main capital inflow?
• Any highlights on the top list?

Announcements / News / Research / Policy

• Any recent announcements?
• Summarize XX's announcements for me
• Any catalysts recently?
• How's the news landscape?
• Any important policy changes?

Macro / Cross-Market

• How's the macro environment lately?
• How do CPI/PMI look?
• What's the current market style?
• Is the overall market bullish or bearish?
• How are Hong Kong/US stocks/Treasuries doing?

Data Export / Research Prep

• Export market data for me
• Pull daily data for the last two years into CSV
• Generate a backtest-ready data table
• Pull a research table for further analysis

---

What this skill is NOT for

This skill is not suitable for:

• Giving direct buy/sell advice or acting as an investment advisor
• Automated order placement or trade execution
• Millisecond-level real-time trading decisions
• Implementing complex backtesting engines or portfolio optimization systems (that's another engineering task)
• Fabricating data without proper Tushare permissions/credits

If data permissions are insufficient, interfaces are unavailable, or time ranges are unreasonable, clearly state the limitations—do not fabricate.

---

Natural-language trigger guide

Even if the user never says tushare, financials, or macro, trigger this skill as long as the intent matches the meanings below.

Common spoken triggers

• How's this stock doing lately?
• Give me a quick research on XX
• What's the status of that stock we talked about?
• Check the financial reports
• Which sector is strongest lately?
• What are northbound funds buying recently?
• Any catalyst news?
• Is this company worth a closer look?
• Pull some data for me
• Export to CSV
• Screen a batch of stocks for me
• Compare these companies

Chinese natural language priority

When the user speaks naturally, understand the task first—don't jump to interface names and field names.
Prioritize interpreting:

• "recently" as a reasonable time window
• "financial reports" as the last 8 quarters / latest fiscal year
• "strong" as price trend + relative strength + activity
• "fund attention" as net inflow, active trading, top list/northbound flows where available

If the task has multiple reasonable interpretations, ask for minimal clarification.

---

Environment check

Before actually requesting data, perform prerequisite checks:

1. Check Python availability (3.7+)
2. Check if tushare package is installed
3. Check if TUSHARE_TOKEN exists
4. Optionally run a lightweight smoke test (e.g., trade calendar / basic interface)
5. If the user requests a high-permission interface, warn about potential credit/permission limits

If the token is missing, directly suggest the shortest fix, e.g.:

export TUSHARE_TOKEN=your_token

Don't wait until the main query fails to reveal environment issues.

---

Intent taxonomy

Identify the task type first, then decide the interface combination.

1. Market / Trend

Typical questions:

• How's the recent trend?
• How much has it risen this year?
• Is volatility high recently?
• Has volume picked up?

Common interfaces:

• daily
• pro_bar
• weekly
• monthly
• stk_mins
• rt_k / rt_min (if real-time is needed and permissions allow)
• daily_basic

2. Basic Info / Instrument Identification

Typical questions:

• What company/index/fund is this?
• Is it on ChiNext? Is it ST? When was it listed?

Common interfaces:

• stock_basic
• fund_basic
• index_basic
• stock_company
• stock_st / st

3. Financials / Company Quality

Typical questions:

• Profit trend over recent quarters
• Revenue and net profit trend over recent quarters
• How's the financial quality?
• How are ROE/gross margin/cash flow?

Common interfaces:

• income (revenue/net profit trend preferred)
• fina_indicator (ROE/gross margin/net margin etc. as supplements)
• balancesheet
• cashflow
• forecast
• express
• disclosure_date

4. Valuation / Fundamental Metrics

Typical questions:

• Is the valuation high now?
• Which is cheaper?
• How are PE/PB/dividend yield?

Common interfaces:

• daily_basic
• fina_indicator

5. Money Flow / Market Behavior

Typical questions:

• What are northbound funds buying recently?
• Main capital flow direction
• Top list situation

Common interfaces:

• moneyflow
• moneyflow_hsgt
• hsgt_top10
• top_list
• top_inst
• moneyflow_ind_dc
• moneyflow_mkt_dc

6. Sector / Index / Theme

Typical questions:

• Which sector is strongest lately?
• How is sector rotation?
• What are the constituents of a certain sector?

Common interfaces:

• index_basic
• index_daily
• index_classify
• index_member_all
• sw_daily
• ths_index
• ths_member
• dc_index
• dc_member

7. Limit-up / Sentiment / Activity

Typical questions:

• Today's limit-up tier structure
• Consecutive limit-up pattern
• Limit-up break rate / sentiment strength

Common interfaces:

• limit_list_d
• limit_step
• kpl_list
• dc_hot
• ths_hot

8. Announcements / News / Research / Policy

Typical questions:

• Any recent announcements or catalysts?
• Any recent research reports?
• What's happened on the policy front?

Common interfaces:

• anns_d
• news
• major_news
• research_report
• npr
• irm_qa_sh
• irm_qa_sz

9. Macro / Cross-Market

Typical questions:

• CPI/PMI/social financing/M2
• Interest rates and yield curves
• Hong Kong/US stock/Treasury data

Common interfaces:

• cn_cpi
• cn_ppi
• cn_pmi
• cn_gdp
• cn_m
• sf_month
• shibor
• shibor_lpr
• us_tycr
• us_daily
• hk_daily
• index_global

10. Export / Research Prep

Typical questions:

• Export market data for a certain instrument over a period
• Generate a backtest data table
• Output CSV/parquet

Common interfaces:

• Depends on the upstream task; core is unified output rules and naming conventions

---

Entity resolution rules

Instrument resolution

• Prioritize identifying stock names, stock codes, index names, ETF names, fund names
• For Chinese abbreviations, first try to match standard objects
• If ambiguous or multiple matches, list candidates and ask for minimal clarification
• Standardize securities codes internally, e.g., 600519.SH, 000001.SZ

Market identification

• Default to A-shares unless the user explicitly mentions Hong Kong/US stocks, funds, bonds, or futures
• Distinguish between indices, ETFs, and individual stocks; do not mix interfaces

Time defaults

If the user does not specify a time range, use reasonable defaults:

• "Recent trend" → default last 20 trading days
• "This period / recently" → default last 3 months
• "Financial reports / earnings" → default last 8 quarters + latest fiscal year
• "How's money flow recently" → default last 5–20 trading days, adjust by task granularity
• "How's macro recently" → default last 6–12 periods

Sector classification defaults

If the user only says "sector/industry/concept" without specifying a classification system:

• For industries, prefer stable systems like Shenwan/CITIC
• For concepts, prefer Tonghuashun/East Money theme classifications
• If conclusions depend on specific classification differences, clearly state which classification was used

---

Input normalization rules

Normalize before requesting data:

• Unify dates to YYYYMMDD
• Check start_date <= end_date
• If the user inputs a future date, automatically clip to the latest available date and notify
• For bare codes like 000001, do not guess blindly; if you can complete, explain the completion rule; otherwise, clarify
• For conflicting parameters (e.g., both trade_date and start_date/end_date), resolve first—do not pass them incorrectly

---

Data retrieval rules

Documentation first

Before writing request code, confirm:

• Correct interface name
• Required parameters
• Optional parameters
• Return fields
• Credit/frequency limits

Do not hardcode field names from memory alone.

Field confirmation

For the fields parameter, prefer using a known field whitelist or confirm via interface documentation.
If the user requests a non-existent field, clearly state that—do not blindly query.

Default segmented fetching

Do not fetch all data for a long range at once.
Recommendations:

• Daily/weekly/monthly: slice by year or quarter
• Financials: slice by year/report period
• Minute data: slice by month/week
• Large batch of multiple instruments: batch by instrument + date segmentation

Retry and rate limiting

• Only retry on transient errors (network jitter, timeout, 429)
• Do not blindly retry on parameter errors, permission issues, or field errors
• Add throttling during batch fetching to avoid hitting rate limits

Merge segments

After segmented fetching:

• Merge
• Deduplicate
• Sort by primary key
• Record failed segments
• If partially successful, clearly tell the user which segments failed

---

Output contract

Unless the user explicitly wants only raw tables, prefer this structure:

1. One-sentence conclusion
2. Data range and scope
3. Key metrics / key tables
4. Anomalies / risks / limitations
5. If local output, provide file path

Delivery format

Choose based on task complexity:

• Small results: Markdown summary + short table
• Medium data table: CSV
• Large scale / further analysis: Parquet
• Reusable workflow: attach Python script
• When visualization is needed: output chart PNG or describe what can be plotted

Metadata

When generating data files, also record where possible:

• Interface name
• Request parameters
• Fetch time
• Number of rows
• Field list
• Whether any failed segments / missing data exist

---

Workflow templates

These templates are the core of this skill.
Do not start from interfaces; start from task templates.

1. Single instrument market analysis

Applicable:

• How's XX doing lately?
• Is this stock strong recently?
• How has it performed this year?

Default workflow:

1. Resolve instrument
2. Determine time range
3. Fetch market data + necessary basic metrics
4. Summarize range change, trading activity, highs/lows, volatility
5. Output one-sentence conclusion + key numbers

2. Multi-instrument horizontal comparison

Applicable:

• Which is stronger, XX or YY?
• Compare these companies

Default workflow:

1. Lock targets
2. Unify time scope
3. Select 3–5 key metrics
4. Output comparison table
5. Summarize "who is stronger in what aspect"

3. Financial quality snapshot

Applicable:

• Check XX's financial reports
• Profit trend over recent quarters
• How's the financial quality?

Default workflow:

1. Fetch core financial data for last 8 quarters + latest fiscal year
2. Distinguish revenue, profit, gross margin, ROE, cash flow
3. Highlight improvement/deterioration/volatility points
4. Explain cumulative, single-quarter, YoY scopes

4. Valuation analysis / screening

Applicable:

• Is the valuation high now?
• Which is cheaper?
• Screen for low valuation high dividend

Default workflow:

1. Clarify target pool
2. Fetch daily_basic and other valuation metrics
3. Cross-reference with financial quality if needed
4. Output ranking, extremes, scope explanation

5. Money flow tracking

Applicable:

• What are funds buying lately?
• Where are northbound funds flowing?
• Who has the largest main capital inflow?

Default workflow:

1. Clarify money flow scope (northbound/main capital/top list/sector flow)
2. Determine time window
3. Fetch net inflow / active trading / persistence
4. Cross-reference with price performance
5. Avoid calling single-day noise a trend

6. Sector/theme rotation analysis

Applicable:

• Which sector is strongest lately?
• Why is robotics strong?
• What are the constituents of a certain concept sector?

Default workflow:

1. Determine classification scope
2. Fetch sector interval performance
3. Cross-reference with constituents, money flow, limit-up tiers if needed
4. Output strong sector rankings and representative instruments

7. Announcement/news/event review

Applicable:

• Any recent announcements?
• Any catalysts?
• How's the news landscape?

Default workflow:

1. Clarify target and time window
2. Fetch announcement/news/research/policy data
3. Denoise, extract 3–5 main threads
4. Distinguish facts, announcements, media interpretations
5. If needed, provide weak causal explanation with price anomalies

8. Data export and research prep

Applicable:

• Pull a CSV
• Make a backtest data table
• Export market/financial data for a period

Default workflow:

1. Clarify data range, frequency, fields
2. Use segmented strategy to fetch
3. Clean, deduplicate, unify field types
4. Output CSV/parquet
5. Provide file path and metadata

9. Comprehensive research brief

Applicable:

• Give me a quick research on XX
• Make an investor perspective brief
• Give a panoramic view first

Default workflow:

1. One-sentence conclusion
2. Market performance
3. Financial trends
4. Valuation level
5. Money flow situation
6. Announcement/news catalysts
7. Risk points
8. Questions worth further exploration

---

Data quality rules

After fetching, at least perform these checks:

• Schema validation
• Key field existence check
• Primary key deduplication
• Fixed sorting
• Date standardization
• Numeric field type normalization

Empty result handling

An empty table is not necessarily a failure; distinguish:

• Non-trading day
• No data in range
• Stock not yet listed
• Parameter error
• Insufficient interface permissions

Do not say "interface broken" for all empty results.

---

Cache and reuse rules

To make the skill reusable long-term, prefer:

• Caching base tables (e.g., stock_basic, trade calendar, index basic info)
• Incremental updates instead of full reloads each time
• Checkpoint resume for large tasks
• Standardized result file naming

Recommended naming format:

• daily_600519.SH_20230101_20231231_20260322.csv
• fina_indicator_300750.SZ_20260322.parquet

When cache is hit, indicate which data is from cache and which is newly fetched.

---

Error handling

Prefer outputting errors in "human language + debug details" layered format.

User-visible layer

• Token not configured
• This interface may require higher credits/permissions
• Time range too large, automatically switched to segmented fetching
• Stock name not unique, please confirm which one
• Current result is empty, possibly due to non-trading day / instrument not listed / no permission

Debug layer

If needed, supplement:

• Interface name
• Parameters
• Failed segments
• Original exception

Partial success principle

If some segments fail, do not say "completed successfully."
Clearly state:

• Which parts succeeded
• Which parts failed
• Whether an incomplete result has been generated

---

Recommended minimal interface set

Do not cram hundreds of interfaces into the main skill body.
Prioritize remembering the core interface set for 80% of common tasks:

• stock_basic
• trade_cal
• daily
• pro_bar
• daily_basic
• fina_indicator
• income
• balancesheet
• cashflow
• forecast
• express
• moneyflow
• moneyflow_hsgt
• hsgt_top10
• top_list
• index_basic
• index_daily
• index_classify
• sw_daily
• ths_index
• ths_member
• limit_list_d
• limit_step
• news
• major_news
• research_report
• anns_d
• cn_cpi
• cn_pmi
• us_tycr

For all data interfaces, refer to references/数据接口.md.

---

Best practices

• Understand the task first, then select interfaces
• Fetch as little as possible—core data first, then expand
• Give conclusions first, then evidence
• Default to human language, don't pile up field names
• For vague Chinese expressions like "recently / financial reports / strong / fund attention", have reasonable default scopes
• For large tasks, give an execution plan first, then start
• For export tasks, try to keep scripts, metadata, and file paths for reusability

---

Examples

Single stock market

• Check CATL's trend over the last three months
• How much has Moutai risen this year?
• What's the maximum drawdown for CMB in the last two years?

Financials / Valuation

• Check BYD's revenue and net profit trend over the last 8 quarters
• Is Moutai's valuation high now?
• Find companies with high ROE and low debt

Comparison

• Compare the one-year returns and valuations of Moutai, Wuliangye, and Luzhou Laojiao
• Compare the performance of CSI 300, CSI 500, and ChiNext this year

Money flow / Sector

• Which stocks have the highest northbound net inflow today?
• Which sector is strongest lately?
• Has the semiconductor sector been strong in the last month?

Announcements / Events

• Summarize Cambricon's important recent announcements
• Any news catalysts for the robotics sector recently?

Macro

• Check recent changes in CPI, PPI, PMI
• Is the current market style growth or value?

Export

• Export daily data for CSI 300 constituents over the last two years to CSV
• Download CATL's adjusted market data from 2020 to now
• Pull a table of ROE, PE, PB, and revenue growth for the last 3 years

---

Quick rule

When the user says:

• Check trend
• Look up financials
• Compare companies
• Check sector
• Check money flow
• Review announcements/news
• Check macro
• Pull data for export

Don't first think "which interfaces."
First think:
What task is this? What data workflow should be used by default? How should the result be delivered to be truly useful?