Throughtext inputquery macroeconomic data; after the interface returns JSON, it will automatically be converted to CSV and generate the correspondingcontent description txt file.
⚠️ Core Input Constraints
- Time dimension: supports relative time expressions (such as “this year”, “the past three years”, “last month”).
- Geographic dimension: supports macro-level region expressions (such as “China”, “United States”, “Eurozone”, “East China region”, “China’s provinces”), without needing to break them down into a specific list of provinces and cities.
1. No Ambiguous Commodities
- Prohibited input: broad category names (such as “rare earth metals”, “nonferrous metals”, “agricultural products”, “energy”, “technology stocks”).
- Requirement: must be unpacked into specifictrading instrument names or codes。
- ❌ Incorrect:
"查询稀土价格走势" - ✅ Correct:
"查询氧化镨钕、氧化镝、氧化铽的价格走势"
- ❌ Incorrect:
2. No Macro Generalizations without Metrics
- Prohibited input: broad economic concepts without specific indicators (such as “China’s economy”, “U.S. manufacturing conditions”, “global inflation situation”).
- Requirement: must specify the specificindicator name(such as GDP, CPI, PMI, unemployment rate, industrial value added, etc.).
- ❌ Incorrect:
"查询中国经济数据" - ✅ Correct:
"查询中国 GDP 同比增速、中国 CPI 同比" - ✅ Correct:
"查询美国制造业 PMI"(regions may be macro-level, but indicators must be specific)
- ❌ Incorrect:
3. Flexible Time & Region
- Time: no absolute date is required.
- ✅ Allowed:
"查询中国过去五年的M2增速"、"查询上个月美国的非农数据"、"查询黄金今日价格"。 - ✅ Allowed (default):
"查询德国失业率"。
- ✅ Allowed:
- Region: no need to break it down into a subset list.
- ✅ Allowed:
"查询华东地区GDP","查询中国各省GDP"。 - ⚠️ Note: if it involves dynamic ranking references such as “major emerging markets”, “Top 5 countries”, etc., it is still recommended that the upper-layer model unpack them into a specific country list (such as
"查询中国、印度、巴西的M2") to ensure data source consistency.
- ✅ Allowed:
🔄 Output Interface & Orchestration Protocol
This Skill is only responsible for executing a single query and generating files.To ensure data completeness, the upper-layer planning engine must perform subsequent processing on the output of this Skill according to the following protocol.
1. Output File Structure
After executing mx_macro_data , the Skill will generate one or more CSV files and one description file in the specified directory.
- CSV file：
mx_macro_data_<查询ID>_<频率>.csv- Example：
mx_macro_data_4591GG28_yearly.csv,mx_macro_data_4591GG28_quarterly.csv,mx_macro_data_4591GG28_monthly.csv - Note: the number of files and frequency depend on the availability of the queried indicators (yearly, quarterly, monthly, weekly, daily).
- Example：
- Description file：
mx_macro_data_<查询ID>_description.txt- Contains basic information such as data sources, time ranges, and indicator descriptions.
2. Mandatory Verification Logic for the Upper-Level Planning Engine (Mandatory Verification Logic for Orchestrator)
After the upper-level planning engine calls mx_macro_data , itmustexecute the following workflow to ensure the completeness of the final result:
Phase A: Task Parsing & Expectation Planning (Task Parsing & Expectation Planning)
- Parse the original user intent: Extract core elements from the user query.
- Build the Expected Universe (Expected Universe)：
- Region: Through the planning engine's built-in knowledge base, search engine, or LLM reasoning capabilities, resolve vague regional expressions into specific administrative units. For example: "all provinces in China" → 34 provincial-level administrative regions; "East China region" → Shanghai, Jiangsu, Zhejiang, Anhui, Fujian, Jiangxi, Shandong, 7 provinces and municipalities in total.
- Indicator: Break composite indicators into independent indicators. For example: "GDP, CPI" → ["GDP", "CPI"].
- Frequency: Infer the expected frequency based on the query context; data files at multiple frequencies may be generated (yearly, quarterly, monthly, etc.).
Phase B: File Reading & Gap Detection (File Reading & Gap Detection)
- Obtain the output file list: Obtain
mx_macro_dataall generated CSV file paths. - Read and analyze each file：
- Use the planning engine's built-in code execution capability (such as Python Sandbox) to read the CSV.
- Extract the actual coverage in each file of the
(地区, 指标)combinations and their counts.
- Perform gap calculation：
- Foreach frequencyof files, separately calculate
Missing_Pairs_<Frequency> = Expected_Universe - Actual_From_CSV_File。 - Identify the specific missing items (for example: "Tibet-GDP" is missing in the annual frequency data).
- Foreach frequencyof files, separately calculate
Phase C: Decision & Iterative Invocation (Decision & Iterative Invocation)
⚠️ Mandatory requirement: The upper-level planning enginemustexecute the following completion process, and must not directly deliver results when missing data exists.
-
Determine whether completion is needed：
- If for all frequencies the
Missing_Pairssets are empty:End the process, and deliver the existing files. - If there are non-empty
Missing_Pairssets:must enter the completion process, and cannot skip it.
- If for all frequencies the
-
Build completion query：
- Based on the missing items in
Missing_Pairs_<Frequency>, combined with the time dimension of the original query, construct a new natural language query. - Example：
Missing_Pairs_季 = [("西藏", "GDP"), ("宁夏", "GDP")] ↓ 补全查询 = "查询西藏自治区、宁夏回族自治区的 GDP 季度数据，时间范围同前次查询"
- Based on the missing items in
-
Call again
mx_macro_data：- Using the newly constructed completion query, call this Skill again to obtain the missing data.
-
Iterative loop：
- Repeatedly execute Phase B (Gap Detection) → Phase C (Decision Completion), until any of the following conditions is met:
- ✅ All missing items at all frequencies have been completed
- ⚠️ The maximum retry count of 5 is reached; at this point, the data items that could not be completed should be reported to the user
- Repeatedly execute Phase B (Gap Detection) → Phase C (Decision Completion), until any of the following conditions is met:
Phase D: Final Delivery
- Data merging (optional)：
- If needed, results from multiple queries at the same frequency (such as multiple
quarterly.csvfiles) can be merged into a single completequarterly.csv。
- If needed, results from multiple queries at the same frequency (such as multiple
- status report：
- The planning engine should report the final list of delivered files to upstream (such as the user interface), and may optionally report the completion process (e.g., "the system automatically completed 2 missing data items").
Functional Scope
Basic Query Capabilities
- Economic indicators: GDP, CPI, PPI, PMI, unemployment rate, industrial value added, etc. (supports specifying countries/regions and specific indicator names).
- Monetary and financial: M1/M2 money supply, social financing scale, government bond interest rates, exchange rates (supports specifying currency pairs).
- Commodity prices: gold, silver, crude oil, copper, specific rare earth oxides, etc. (mustspecify the specific variety).
- Time frequency: automatically recognizes relative time (year, quarter, month, week, day) and matches data of the corresponding frequency; if unspecified, returns the latest data.
Query Example Comparison Table
| Type | ❌ Prohibited vague queries (indicator/variety unclear) | ✅ Allowed explicit queries (time/region flexible) |
|---|---|---|
| Domestic economy | Query GDP of East China | Query GDP of East China |
| Money supply | Query money supply of major emerging markets | Query M2 money supply of China, India, and Brazil |
| Commodity prices | Query prices of rare earths and nonferrous metals | Query spot price trends of praseodymium-neodymium oxide, copper, and aluminum |
| Global macro | Query nonfarm data of the Top 3 economies | Query nonfarm payroll employment data of the United States, China, and Germany |
| Flexible time | (None) | Query the unemployment rate trend of the United States over the past ten years |
| Default time | (None) | Query the latest core CPI data of Japan |
Quick Start
1. Command-line invocation
Execute in the project root directory or the configured working directory:
python3 {baseDir}/scripts/get_data.py --query 中国GDP
Parameter description:
| Parameter | Description | Required |
|---|---|---|
--query |
Natural language query conditions | ✅ |
### 2. 代码调用
```python
import asyncio
from pathlib import Path
from scripts.get_data import query_mx_macro_data
async def main():
result = await query_mx_macro_data(
query="中国近五年GDP",
output_dir=Path("workspace/mx_macro_data"),
)
if "error" in result:
print(result["error"])
else:
print(f"CSV: {r['csv_paths']}")
print(f"描述: {r['description_path']}")
print(f"行数: {r['row_counts']}")
asyncio.run(main())
Example output:
CSV: /path/to/workspace/mx_macro_data/mx_macro_data_4591GG28_yearly.csv
CSV: /path/to/workspace/mx_macro_data/mx_macro_data_4591GG28_quarterly.csv
CSV: /path/to/workspace/mx_macro_data/mx_macro_data_4591GG28_monthly.csv
描述:/path/to/workspace/mx_macro_data/mx_macro_data_4591GG28_description.txt
行数: 年: 10行, 季: 20行, 月: 40行
Output File Description
| File | Description |
|---|---|
mx_macro_data_<查询ID>_<频率>.csv |
Macro data tables grouped by frequency, UTF-8 encoded, can be opened directly with Excel or pandas. |
mx_macro_data_<查询ID>_description.txt |
Description file, containing statistics for each frequency, data sources, units, and other information. |
Environment Variables
| Variable | Description | Default |
|---|---|---|
MX_MACRO_DATA_OUTPUT_DIR |
Output directory for CSV and description files (optional) | workspace/mx_macro_data |
Frequently Asked Questions
User FAQs
A: By setting the MX_MACRO_DATA_OUTPUT_DIR environment variable:
export MX_MACRO_DATA_OUTPUT_DIR="/path/to/output"
python3 scripts/get_data.py --query "查询内容"
Developer FAQs (Planning Engine Integration)
Q: Why is an upper-layer planning engine needed for review?
A: This Skill focuses on a single query capability and is not responsible for data integrity verification. Integrity validation (such as whether "China's provinces" truly covers all provinces) falls within the scope of business logic and is better handled by a planning engine with contextual understanding and decision-making capabilities.
Q: How do you determine when to perform a review?
A: When the original user intent contains the following characteristics, the review process should be triggered automatically:
- Collective terms: such as "all provinces", "all regions", "East China region", etc.
- Multi-indicator queries: such as "GDP and CPI", "major economic indicators", etc.
Q: How do you handle data at different frequencies? A: mustfor the CSV file of each frequencyseparatelyperform integrity auditing and completion. Missing annual-frequency data cannot be completed with monthly-frequency data, and vice versa.