wbgapi360 0.2.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- wbgapi360-0.2.1/LICENSE +21 -0
- wbgapi360-0.2.1/PKG-INFO +230 -0
- wbgapi360-0.2.1/README.md +198 -0
- wbgapi360-0.2.1/pyproject.toml +39 -0
- wbgapi360-0.2.1/setup.cfg +4 -0
- wbgapi360-0.2.1/setup.py +36 -0
- wbgapi360-0.2.1/tests/test_mcp.py +45 -0
- wbgapi360-0.2.1/wbgapi360/__init__.py +51 -0
- wbgapi360-0.2.1/wbgapi360/ai/agent.py +114 -0
- wbgapi360-0.2.1/wbgapi360/api.py +257 -0
- wbgapi360-0.2.1/wbgapi360/cli.py +83 -0
- wbgapi360-0.2.1/wbgapi360/config.py +41 -0
- wbgapi360-0.2.1/wbgapi360/core/auditor.py +107 -0
- wbgapi360-0.2.1/wbgapi360/core/client.py +163 -0
- wbgapi360-0.2.1/wbgapi360/core/models.py +24 -0
- wbgapi360-0.2.1/wbgapi360/core/transformers.py +70 -0
- wbgapi360-0.2.1/wbgapi360/core/utils.py +38 -0
- wbgapi360-0.2.1/wbgapi360/data/builder.py +192 -0
- wbgapi360-0.2.1/wbgapi360/mcp/server.py +590 -0
- wbgapi360-0.2.1/wbgapi360/metadata/builder.py +87 -0
- wbgapi360-0.2.1/wbgapi360/metadata/iso_mapping.py +228 -0
- wbgapi360-0.2.1/wbgapi360/metadata/resolver.py +136 -0
- wbgapi360-0.2.1/wbgapi360/search/engine.py +143 -0
- wbgapi360-0.2.1/wbgapi360/visual/__init__.py +1 -0
- wbgapi360-0.2.1/wbgapi360/visual/charts.py +1093 -0
- wbgapi360-0.2.1/wbgapi360.egg-info/PKG-INFO +230 -0
- wbgapi360-0.2.1/wbgapi360.egg-info/SOURCES.txt +29 -0
- wbgapi360-0.2.1/wbgapi360.egg-info/dependency_links.txt +1 -0
- wbgapi360-0.2.1/wbgapi360.egg-info/entry_points.txt +2 -0
- wbgapi360-0.2.1/wbgapi360.egg-info/requires.txt +17 -0
- wbgapi360-0.2.1/wbgapi360.egg-info/top_level.txt +1 -0
wbgapi360-0.2.1/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Maykol Medrano
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
wbgapi360-0.2.1/PKG-INFO
ADDED
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: wbgapi360
|
|
3
|
+
Version: 0.2.1
|
|
4
|
+
Summary: Enterprise-grade Async Python Client for World Bank Data360 API
|
|
5
|
+
Author: Maykol Medrano
|
|
6
|
+
Author-email: Maykol Medrano <mmedrano2@uc.cl>
|
|
7
|
+
License: MIT
|
|
8
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
9
|
+
Classifier: Intended Audience :: Science/Research
|
|
10
|
+
Classifier: Programming Language :: Python :: 3
|
|
11
|
+
Classifier: Topic :: Scientific/Engineering :: Information Analysis
|
|
12
|
+
Requires-Python: >=3.8
|
|
13
|
+
Description-Content-Type: text/markdown
|
|
14
|
+
License-File: LICENSE
|
|
15
|
+
Requires-Dist: httpx>=0.23.0
|
|
16
|
+
Requires-Dist: pandas>=1.3.0
|
|
17
|
+
Requires-Dist: pydantic>=2.0.0
|
|
18
|
+
Requires-Dist: nest_asyncio>=1.5.0
|
|
19
|
+
Requires-Dist: fastmcp>=0.1.0
|
|
20
|
+
Provides-Extra: visual
|
|
21
|
+
Requires-Dist: matplotlib>=3.4.0; extra == "visual"
|
|
22
|
+
Requires-Dist: seaborn>=0.11.0; extra == "visual"
|
|
23
|
+
Provides-Extra: map
|
|
24
|
+
Requires-Dist: geopandas>=0.9.0; extra == "map"
|
|
25
|
+
Requires-Dist: matplotlib>=3.4.0; extra == "map"
|
|
26
|
+
Provides-Extra: dev
|
|
27
|
+
Requires-Dist: pytest; extra == "dev"
|
|
28
|
+
Requires-Dist: pytest-asyncio; extra == "dev"
|
|
29
|
+
Dynamic: author
|
|
30
|
+
Dynamic: license-file
|
|
31
|
+
Dynamic: requires-python
|
|
32
|
+
|
|
33
|
+
# wbgapi360: World Bank Data Client for Humans & AI
|
|
34
|
+
|
|
35
|
+
[](https://pypi.org/project/wbgapi360/)
|
|
36
|
+
[](https://www.python.org/downloads/)
|
|
37
|
+
[](https://opensource.org/licenses/MIT)
|
|
38
|
+
[](https://github.com/mmedrano2/mcp_wbgapi360/actions)
|
|
39
|
+
[]()
|
|
40
|
+
|
|
41
|
+
**wbgapi360** is a high-performance Python client designed to interact with the World Bank's Data APIs. It bridges the gap between traditional econometric analysis and modern Artificial Intelligence workflows.
|
|
42
|
+
|
|
43
|
+
This library is engineered with a **Hybrid Architecture**: it provides a synchronous, blocking API for human analysts (similar to `pandas` or `matplotlib`) and an asynchronous Model Context Protocol (MCP) server for AI Agents (such as Claude or OpenAI).
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## Project Philosophy & Attribution
|
|
48
|
+
|
|
49
|
+
### Unofficial Client
|
|
50
|
+
This software is an independent open-source project. It is **not affiliated, associated, authorized, endorsed by, or in any way officially connected with The World Bank Group**. The official World Bank website can be found at [worldbank.org](https://www.worldbank.org).
|
|
51
|
+
|
|
52
|
+
### Inspiration & Legacy
|
|
53
|
+
This project is built upon the conceptual foundation laid by **Tim Herzog (tgherzog)** and his pioneering work with the original `wbgapi`.
|
|
54
|
+
|
|
55
|
+
While `wbgapi` set the standard for Pythonic access to World Bank data, `wbgapi360` was built from the ground up to address two new challenges in the modern era:
|
|
56
|
+
1. **AI Integration:** Native support for LLM function calling via MCP.
|
|
57
|
+
2. **Smart Search:** Heuristic ranking algorithms to disambiguate indicators (e.g., distinguishing "GDP" from "Education Expenditure as % of GDP").
|
|
58
|
+
|
|
59
|
+
We acknowledge and thank Tim for establishing the developer-friendly patterns that inspired this library's human interface.
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## Installation
|
|
64
|
+
|
|
65
|
+
The library is available on PyPI.
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
# Core installation (Lightweight)
|
|
69
|
+
pip install wbgapi360
|
|
70
|
+
|
|
71
|
+
# With Visualization support (adds Matplotlib/Seaborn)
|
|
72
|
+
pip install wbgapi360[visual]
|
|
73
|
+
|
|
74
|
+
# With Mapping support (adds GeoPandas - Heavy dependency)
|
|
75
|
+
pip install wbgapi360[map]
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## Usage Guide: For Analysts (Python)
|
|
81
|
+
|
|
82
|
+
The human interface is designed to be intuitive, synchronous, and safe for Jupyter Notebooks.
|
|
83
|
+
|
|
84
|
+
### 1. Smart Search (Semantic)
|
|
85
|
+
Finding the right indicator among 16,000+ options is difficult. `wbgapi360` uses a heuristic ranking system.
|
|
86
|
+
|
|
87
|
+
```python
|
|
88
|
+
import wbgapi360 as wb
|
|
89
|
+
|
|
90
|
+
# Search for "inflation" - automatically ranks "Consumer Price Index" above obscure sub-metrics
|
|
91
|
+
results = wb.search("inflation") # Returns top 10 matches
|
|
92
|
+
|
|
93
|
+
for r in results[:3]:
|
|
94
|
+
print(f"[{r['code']}] {r['name']}")
|
|
95
|
+
# Output:
|
|
96
|
+
# [FP.CPI.TOTL.ZG] Inflation, consumer prices (annual %)
|
|
97
|
+
# [FP.CPI.TOTL] Consumer price index (2010 = 100)
|
|
98
|
+
# [NY.GDP.DEFL.KD.ZG] Inflation, GDP deflator (annual %)
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
### 2. Robust Data Retrieval
|
|
102
|
+
Fetch data with automatic ID correction and intelligent time window handling.
|
|
103
|
+
|
|
104
|
+
```python
|
|
105
|
+
# Fetch GDP Growth for USA, China, and Peru (Last 10 years)
|
|
106
|
+
df = wb.get_data(
|
|
107
|
+
indicator="NY.GDP.MKTP.KD.ZG",
|
|
108
|
+
economies=["USA", "CHN", "PER"],
|
|
109
|
+
years=10,
|
|
110
|
+
labels=True, # Adds 'Country Name' column
|
|
111
|
+
as_frame=True # Returns pandas DataFrame instead of JSON
|
|
112
|
+
)
|
|
113
|
+
|
|
114
|
+
print(df.head())
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
### 3. Advanced Analysis: Trends & Statistics
|
|
118
|
+
Quickly assess the economic trajectory of a country without writing boilerplate pandas code.
|
|
119
|
+
|
|
120
|
+
```python
|
|
121
|
+
# Analyze the trend of Foreign Direct Investment in Chile
|
|
122
|
+
stats = wb.analyze_trend(
|
|
123
|
+
indicator="BX.KLT.DINV.CD.WD",
|
|
124
|
+
economy="CHL",
|
|
125
|
+
years=20
|
|
126
|
+
)
|
|
127
|
+
|
|
128
|
+
# Returns a rich JSON with growth rates, volatility, and direction
|
|
129
|
+
# {
|
|
130
|
+
# "statistics": {
|
|
131
|
+
# "avg_annual_growth_pct": 5.2,
|
|
132
|
+
# "volatility": 1240000000,
|
|
133
|
+
# "trend_direction": "increasing"
|
|
134
|
+
# }
|
|
135
|
+
# }
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
### 4. Professional Visualization
|
|
139
|
+
Generate Financial Times-style charts ready for publication.
|
|
140
|
+
|
|
141
|
+
```python
|
|
142
|
+
# 1. Fetch Data
|
|
143
|
+
data = wb.get_data("NY.GDP.PCAP.CD", ["CHL", "PER", "COL", "MEX"], years=15)
|
|
144
|
+
|
|
145
|
+
# 2. Plot Trend
|
|
146
|
+
wb.plot(
|
|
147
|
+
chart_type="trend",
|
|
148
|
+
data=data,
|
|
149
|
+
title="Pacific Alliance: GDP per Capita",
|
|
150
|
+
subtitle="Current US$ (2010-2025)",
|
|
151
|
+
save_path="pacific_gdp.png"
|
|
152
|
+
)
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
---
|
|
156
|
+
|
|
157
|
+
## Usage Guide: For AI Agents (MCP)
|
|
158
|
+
|
|
159
|
+
This library implements the **Model Context Protocol (MCP)**, allowing AI agents (like Claude or Custom GPTs) to autonomously interact with World Bank data using high-level tools.
|
|
160
|
+
|
|
161
|
+
### 1. Configuration (Claude Desktop)
|
|
162
|
+
Add the following to your `claude_desktop_config.json`:
|
|
163
|
+
|
|
164
|
+
```json
|
|
165
|
+
{
|
|
166
|
+
"mcpServers": {
|
|
167
|
+
"worldbank": {
|
|
168
|
+
"command": "uv",
|
|
169
|
+
"args": [
|
|
170
|
+
"--directory",
|
|
171
|
+
"C:/path/to/mcp_wbgapi360",
|
|
172
|
+
"run",
|
|
173
|
+
"wbgapi360"
|
|
174
|
+
]
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
### 2. Available Tools
|
|
181
|
+
The Agent receives a toolkit optimized for economic reasoning:
|
|
182
|
+
|
|
183
|
+
| Tool | Description | Signature |
|
|
184
|
+
| :--- | :--- | :--- |
|
|
185
|
+
| `search_indicators` | Semantic search. Finds the best matching indicator codes. | `(query: str) -> List[Indicator]` |
|
|
186
|
+
| `get_data` | Fetches time-series data for analysis. | `(indicator_code: str, economies: List[str], years: int)` |
|
|
187
|
+
| `compare_countries` | Comparison logic. Fetches and normalizes data for multiple countries. | `(economies: List[str], indicators: List[str])` |
|
|
188
|
+
| `analyze_trend` | Returns statistical descriptive metadata (growth, volatility). | `(indicator: str, economy: str)` |
|
|
189
|
+
| `rank_countries` | Returns a sorted leaderboard for a given indicator. | `(indicator: str, region: str, top_n: int)` |
|
|
190
|
+
| `plot_chart` | Generates a visualization file from data. | `(chart_type: str, data: json)` |
|
|
191
|
+
|
|
192
|
+
### 3. Example Prompts
|
|
193
|
+
Once connected, you can ask the Agent complex economic questions:
|
|
194
|
+
|
|
195
|
+
> **"Compare the GDP growth volatility between Peru and Chile over the last 20 years. Who has been more stable?"**
|
|
196
|
+
> * *Agent Action:* Calls `analyze_trend` for both countries and compares the `volatility` metric.
|
|
197
|
+
|
|
198
|
+
> **"Create a bar chart ranking the top 10 Latin American countries by Inflation."**
|
|
199
|
+
> * *Agent Action:* Calls `rank_countries(indicator="FP.CPI.TOTL.ZG", region="latam")` then `plot_chart(chart_type="bar", ...)`.
|
|
200
|
+
|
|
201
|
+
> **"Is there a correlation between Literacy Rate and GDP per Capita in Africa?"**
|
|
202
|
+
> * *Agent Action:* Calls `compare_countries` with both indicators for African nations, then `plot_chart(chart_type="scatter")`.
|
|
203
|
+
|
|
204
|
+
---
|
|
205
|
+
|
|
206
|
+
## Visualization Gallery
|
|
207
|
+
|
|
208
|
+
The library supports specific chart types optimized for economic data:
|
|
209
|
+
|
|
210
|
+
| Type | Description | Use Case |
|
|
211
|
+
| :--- | :--- | :--- |
|
|
212
|
+
| **Trend** | Multi-line time series | GDP Growth over time |
|
|
213
|
+
| **Bar** | Horizontal ranked bars | Comparing GINI index across countries |
|
|
214
|
+
| **Column** | Vertical categorical bars | Exports by region |
|
|
215
|
+
| **Scatter** | Correlation plot | Life Expectancy vs. GDP per Capita |
|
|
216
|
+
| **Map** | Choropleth map | Global population density (Requires geopandas) |
|
|
217
|
+
|
|
218
|
+
---
|
|
219
|
+
|
|
220
|
+
## Author
|
|
221
|
+
|
|
222
|
+
**Maykol Medrano**
|
|
223
|
+
*Applied Economist Policy Data Scientist*
|
|
224
|
+
Email: [mmedrano2@uc.cl](mailto:mmedrano2@uc.cl)
|
|
225
|
+
|
|
226
|
+
---
|
|
227
|
+
|
|
228
|
+
## License
|
|
229
|
+
|
|
230
|
+
This project is licensed under the MIT License - see the LICENSE file for details.
|
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
# wbgapi360: World Bank Data Client for Humans & AI
|
|
2
|
+
|
|
3
|
+
[](https://pypi.org/project/wbgapi360/)
|
|
4
|
+
[](https://www.python.org/downloads/)
|
|
5
|
+
[](https://opensource.org/licenses/MIT)
|
|
6
|
+
[](https://github.com/mmedrano2/mcp_wbgapi360/actions)
|
|
7
|
+
[]()
|
|
8
|
+
|
|
9
|
+
**wbgapi360** is a high-performance Python client designed to interact with the World Bank's Data APIs. It bridges the gap between traditional econometric analysis and modern Artificial Intelligence workflows.
|
|
10
|
+
|
|
11
|
+
This library is engineered with a **Hybrid Architecture**: it provides a synchronous, blocking API for human analysts (similar to `pandas` or `matplotlib`) and an asynchronous Model Context Protocol (MCP) server for AI Agents (such as Claude or OpenAI).
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Project Philosophy & Attribution
|
|
16
|
+
|
|
17
|
+
### Unofficial Client
|
|
18
|
+
This software is an independent open-source project. It is **not affiliated, associated, authorized, endorsed by, or in any way officially connected with The World Bank Group**. The official World Bank website can be found at [worldbank.org](https://www.worldbank.org).
|
|
19
|
+
|
|
20
|
+
### Inspiration & Legacy
|
|
21
|
+
This project is built upon the conceptual foundation laid by **Tim Herzog (tgherzog)** and his pioneering work with the original `wbgapi`.
|
|
22
|
+
|
|
23
|
+
While `wbgapi` set the standard for Pythonic access to World Bank data, `wbgapi360` was built from the ground up to address two new challenges in the modern era:
|
|
24
|
+
1. **AI Integration:** Native support for LLM function calling via MCP.
|
|
25
|
+
2. **Smart Search:** Heuristic ranking algorithms to disambiguate indicators (e.g., distinguishing "GDP" from "Education Expenditure as % of GDP").
|
|
26
|
+
|
|
27
|
+
We acknowledge and thank Tim for establishing the developer-friendly patterns that inspired this library's human interface.
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## Installation
|
|
32
|
+
|
|
33
|
+
The library is available on PyPI.
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
# Core installation (Lightweight)
|
|
37
|
+
pip install wbgapi360
|
|
38
|
+
|
|
39
|
+
# With Visualization support (adds Matplotlib/Seaborn)
|
|
40
|
+
pip install wbgapi360[visual]
|
|
41
|
+
|
|
42
|
+
# With Mapping support (adds GeoPandas - Heavy dependency)
|
|
43
|
+
pip install wbgapi360[map]
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
---
|
|
47
|
+
|
|
48
|
+
## Usage Guide: For Analysts (Python)
|
|
49
|
+
|
|
50
|
+
The human interface is designed to be intuitive, synchronous, and safe for Jupyter Notebooks.
|
|
51
|
+
|
|
52
|
+
### 1. Smart Search (Semantic)
|
|
53
|
+
Finding the right indicator among 16,000+ options is difficult. `wbgapi360` uses a heuristic ranking system.
|
|
54
|
+
|
|
55
|
+
```python
|
|
56
|
+
import wbgapi360 as wb
|
|
57
|
+
|
|
58
|
+
# Search for "inflation" - automatically ranks "Consumer Price Index" above obscure sub-metrics
|
|
59
|
+
results = wb.search("inflation") # Returns top 10 matches
|
|
60
|
+
|
|
61
|
+
for r in results[:3]:
|
|
62
|
+
print(f"[{r['code']}] {r['name']}")
|
|
63
|
+
# Output:
|
|
64
|
+
# [FP.CPI.TOTL.ZG] Inflation, consumer prices (annual %)
|
|
65
|
+
# [FP.CPI.TOTL] Consumer price index (2010 = 100)
|
|
66
|
+
# [NY.GDP.DEFL.KD.ZG] Inflation, GDP deflator (annual %)
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### 2. Robust Data Retrieval
|
|
70
|
+
Fetch data with automatic ID correction and intelligent time window handling.
|
|
71
|
+
|
|
72
|
+
```python
|
|
73
|
+
# Fetch GDP Growth for USA, China, and Peru (Last 10 years)
|
|
74
|
+
df = wb.get_data(
|
|
75
|
+
indicator="NY.GDP.MKTP.KD.ZG",
|
|
76
|
+
economies=["USA", "CHN", "PER"],
|
|
77
|
+
years=10,
|
|
78
|
+
labels=True, # Adds 'Country Name' column
|
|
79
|
+
as_frame=True # Returns pandas DataFrame instead of JSON
|
|
80
|
+
)
|
|
81
|
+
|
|
82
|
+
print(df.head())
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
### 3. Advanced Analysis: Trends & Statistics
|
|
86
|
+
Quickly assess the economic trajectory of a country without writing boilerplate pandas code.
|
|
87
|
+
|
|
88
|
+
```python
|
|
89
|
+
# Analyze the trend of Foreign Direct Investment in Chile
|
|
90
|
+
stats = wb.analyze_trend(
|
|
91
|
+
indicator="BX.KLT.DINV.CD.WD",
|
|
92
|
+
economy="CHL",
|
|
93
|
+
years=20
|
|
94
|
+
)
|
|
95
|
+
|
|
96
|
+
# Returns a rich JSON with growth rates, volatility, and direction
|
|
97
|
+
# {
|
|
98
|
+
# "statistics": {
|
|
99
|
+
# "avg_annual_growth_pct": 5.2,
|
|
100
|
+
# "volatility": 1240000000,
|
|
101
|
+
# "trend_direction": "increasing"
|
|
102
|
+
# }
|
|
103
|
+
# }
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
### 4. Professional Visualization
|
|
107
|
+
Generate Financial Times-style charts ready for publication.
|
|
108
|
+
|
|
109
|
+
```python
|
|
110
|
+
# 1. Fetch Data
|
|
111
|
+
data = wb.get_data("NY.GDP.PCAP.CD", ["CHL", "PER", "COL", "MEX"], years=15)
|
|
112
|
+
|
|
113
|
+
# 2. Plot Trend
|
|
114
|
+
wb.plot(
|
|
115
|
+
chart_type="trend",
|
|
116
|
+
data=data,
|
|
117
|
+
title="Pacific Alliance: GDP per Capita",
|
|
118
|
+
subtitle="Current US$ (2010-2025)",
|
|
119
|
+
save_path="pacific_gdp.png"
|
|
120
|
+
)
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## Usage Guide: For AI Agents (MCP)
|
|
126
|
+
|
|
127
|
+
This library implements the **Model Context Protocol (MCP)**, allowing AI agents (like Claude or Custom GPTs) to autonomously interact with World Bank data using high-level tools.
|
|
128
|
+
|
|
129
|
+
### 1. Configuration (Claude Desktop)
|
|
130
|
+
Add the following to your `claude_desktop_config.json`:
|
|
131
|
+
|
|
132
|
+
```json
|
|
133
|
+
{
|
|
134
|
+
"mcpServers": {
|
|
135
|
+
"worldbank": {
|
|
136
|
+
"command": "uv",
|
|
137
|
+
"args": [
|
|
138
|
+
"--directory",
|
|
139
|
+
"C:/path/to/mcp_wbgapi360",
|
|
140
|
+
"run",
|
|
141
|
+
"wbgapi360"
|
|
142
|
+
]
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
### 2. Available Tools
|
|
149
|
+
The Agent receives a toolkit optimized for economic reasoning:
|
|
150
|
+
|
|
151
|
+
| Tool | Description | Signature |
|
|
152
|
+
| :--- | :--- | :--- |
|
|
153
|
+
| `search_indicators` | Semantic search. Finds the best matching indicator codes. | `(query: str) -> List[Indicator]` |
|
|
154
|
+
| `get_data` | Fetches time-series data for analysis. | `(indicator_code: str, economies: List[str], years: int)` |
|
|
155
|
+
| `compare_countries` | Comparison logic. Fetches and normalizes data for multiple countries. | `(economies: List[str], indicators: List[str])` |
|
|
156
|
+
| `analyze_trend` | Returns statistical descriptive metadata (growth, volatility). | `(indicator: str, economy: str)` |
|
|
157
|
+
| `rank_countries` | Returns a sorted leaderboard for a given indicator. | `(indicator: str, region: str, top_n: int)` |
|
|
158
|
+
| `plot_chart` | Generates a visualization file from data. | `(chart_type: str, data: json)` |
|
|
159
|
+
|
|
160
|
+
### 3. Example Prompts
|
|
161
|
+
Once connected, you can ask the Agent complex economic questions:
|
|
162
|
+
|
|
163
|
+
> **"Compare the GDP growth volatility between Peru and Chile over the last 20 years. Who has been more stable?"**
|
|
164
|
+
> * *Agent Action:* Calls `analyze_trend` for both countries and compares the `volatility` metric.
|
|
165
|
+
|
|
166
|
+
> **"Create a bar chart ranking the top 10 Latin American countries by Inflation."**
|
|
167
|
+
> * *Agent Action:* Calls `rank_countries(indicator="FP.CPI.TOTL.ZG", region="latam")` then `plot_chart(chart_type="bar", ...)`.
|
|
168
|
+
|
|
169
|
+
> **"Is there a correlation between Literacy Rate and GDP per Capita in Africa?"**
|
|
170
|
+
> * *Agent Action:* Calls `compare_countries` with both indicators for African nations, then `plot_chart(chart_type="scatter")`.
|
|
171
|
+
|
|
172
|
+
---
|
|
173
|
+
|
|
174
|
+
## Visualization Gallery
|
|
175
|
+
|
|
176
|
+
The library supports specific chart types optimized for economic data:
|
|
177
|
+
|
|
178
|
+
| Type | Description | Use Case |
|
|
179
|
+
| :--- | :--- | :--- |
|
|
180
|
+
| **Trend** | Multi-line time series | GDP Growth over time |
|
|
181
|
+
| **Bar** | Horizontal ranked bars | Comparing GINI index across countries |
|
|
182
|
+
| **Column** | Vertical categorical bars | Exports by region |
|
|
183
|
+
| **Scatter** | Correlation plot | Life Expectancy vs. GDP per Capita |
|
|
184
|
+
| **Map** | Choropleth map | Global population density (Requires geopandas) |
|
|
185
|
+
|
|
186
|
+
---
|
|
187
|
+
|
|
188
|
+
## Author
|
|
189
|
+
|
|
190
|
+
**Maykol Medrano**
|
|
191
|
+
*Applied Economist Policy Data Scientist*
|
|
192
|
+
Email: [mmedrano2@uc.cl](mailto:mmedrano2@uc.cl)
|
|
193
|
+
|
|
194
|
+
---
|
|
195
|
+
|
|
196
|
+
## License
|
|
197
|
+
|
|
198
|
+
This project is licensed under the MIT License - see the LICENSE file for details.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=42", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "wbgapi360"
|
|
7
|
+
version = "0.2.1"
|
|
8
|
+
description = "Enterprise-grade Async Python Client for World Bank Data360 API"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.8"
|
|
11
|
+
license = {text = "MIT"}
|
|
12
|
+
authors = [
|
|
13
|
+
{name = "Maykol Medrano", email = "mmedrano2@uc.cl"}
|
|
14
|
+
]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Development Status :: 5 - Production/Stable",
|
|
17
|
+
"Intended Audience :: Science/Research",
|
|
18
|
+
"Programming Language :: Python :: 3",
|
|
19
|
+
"Topic :: Scientific/Engineering :: Information Analysis",
|
|
20
|
+
]
|
|
21
|
+
dependencies = [
|
|
22
|
+
"httpx>=0.23.0",
|
|
23
|
+
"pandas>=1.3.0",
|
|
24
|
+
"pydantic>=2.0.0",
|
|
25
|
+
"nest_asyncio>=1.5.0",
|
|
26
|
+
"fastmcp>=0.1.0",
|
|
27
|
+
]
|
|
28
|
+
|
|
29
|
+
[project.scripts]
|
|
30
|
+
wbgapi360 = "wbgapi360.cli:main"
|
|
31
|
+
|
|
32
|
+
[project.optional-dependencies]
|
|
33
|
+
visual = ["matplotlib>=3.4.0", "seaborn>=0.11.0"]
|
|
34
|
+
map = ["geopandas>=0.9.0", "matplotlib>=3.4.0"]
|
|
35
|
+
dev = ["pytest", "pytest-asyncio"]
|
|
36
|
+
|
|
37
|
+
[tool.setuptools.packages.find]
|
|
38
|
+
where = ["."]
|
|
39
|
+
include = ["wbgapi360*"]
|
wbgapi360-0.2.1/setup.py
ADDED
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
from setuptools import setup, find_packages
|
|
2
|
+
|
|
3
|
+
setup(
|
|
4
|
+
name="wbgapi360",
|
|
5
|
+
version="0.2.1",
|
|
6
|
+
description="Enterprise-grade Async Python Client for World Bank Data360 API",
|
|
7
|
+
long_description=open("README.md").read() if open("README.md") else "Official client for WBG Data360",
|
|
8
|
+
long_description_content_type="text/markdown",
|
|
9
|
+
author="Maykol Medrano",
|
|
10
|
+
author_email="mmedrano2@uc.cl",
|
|
11
|
+
packages=find_packages(),
|
|
12
|
+
python_requires=">=3.8",
|
|
13
|
+
install_requires=[
|
|
14
|
+
"httpx>=0.23.0",
|
|
15
|
+
"pandas>=1.3.0",
|
|
16
|
+
"pydantic>=2.0.0",
|
|
17
|
+
"nest_asyncio>=1.5.0",
|
|
18
|
+
"fastmcp>=0.1.0",
|
|
19
|
+
],
|
|
20
|
+
extras_require={
|
|
21
|
+
"visual": ["matplotlib>=3.4.0", "seaborn>=0.11.0"],
|
|
22
|
+
"map": ["geopandas>=0.9.0", "matplotlib>=3.4.0"],
|
|
23
|
+
"dev": ["pytest", "pytest-asyncio"]
|
|
24
|
+
},
|
|
25
|
+
entry_points={
|
|
26
|
+
"console_scripts": [
|
|
27
|
+
"wbgapi360=wbgapi360.cli:main",
|
|
28
|
+
],
|
|
29
|
+
},
|
|
30
|
+
classifiers=[
|
|
31
|
+
"Development Status :: 5 - Production/Stable",
|
|
32
|
+
"Intended Audience :: Science/Research",
|
|
33
|
+
"Programming Language :: Python :: 3",
|
|
34
|
+
"Topic :: Scientific/Engineering :: Information Analysis",
|
|
35
|
+
],
|
|
36
|
+
)
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
|
|
2
|
+
import pytest
|
|
3
|
+
import asyncio
|
|
4
|
+
from wbgapi360.mcp.server import _search_indicators, _get_data, _analyze_trend
|
|
5
|
+
|
|
6
|
+
import wbgapi360.mcp.server as server
|
|
7
|
+
|
|
8
|
+
async def reset_state():
|
|
9
|
+
if server._client_instance:
|
|
10
|
+
try:
|
|
11
|
+
await server._client_instance.close()
|
|
12
|
+
except:
|
|
13
|
+
pass
|
|
14
|
+
server._client_instance = None
|
|
15
|
+
server._search_engine_instance = None
|
|
16
|
+
|
|
17
|
+
@pytest.mark.asyncio
|
|
18
|
+
async def test_search_indicators():
|
|
19
|
+
await reset_state()
|
|
20
|
+
"""Test semantic search functionality."""
|
|
21
|
+
results = await _search_indicators(query="gdp growth", limit=3)
|
|
22
|
+
assert len(results) > 0
|
|
23
|
+
assert "code" in results[0]
|
|
24
|
+
assert "name" in results[0]
|
|
25
|
+
|
|
26
|
+
@pytest.mark.asyncio
|
|
27
|
+
async def test_get_data_basic():
|
|
28
|
+
await reset_state()
|
|
29
|
+
"""Test basic data retrieval."""
|
|
30
|
+
data = await _get_data(indicator_code="NY.GDP.MKTP.KD.ZG", economies=['USA'], years=5)
|
|
31
|
+
assert isinstance(data, str)
|
|
32
|
+
# Check for presence of key fields. Note: ID might be transformed (e.g. WB_WDI_...)
|
|
33
|
+
assert "REF_AREA" in data or "economy" in data
|
|
34
|
+
assert "WB_WDI_NY_GDP_MKTP_KD_ZG" in data or "NY.GDP.MKTP.KD.ZG" in data.replace("_", ".")
|
|
35
|
+
|
|
36
|
+
@pytest.mark.asyncio
|
|
37
|
+
async def test_analyze_trend():
|
|
38
|
+
await reset_state()
|
|
39
|
+
"""Test trend analysis."""
|
|
40
|
+
# Increase years to ensures we get enough data points for stats
|
|
41
|
+
trend_json = await _analyze_trend("NY.GDP.MKTP.KD.ZG", "USA", years=10)
|
|
42
|
+
assert isinstance(trend_json, str)
|
|
43
|
+
# We might not get stats if data is missing, so check for basic structure
|
|
44
|
+
assert "data" in trend_json
|
|
45
|
+
assert "meta" in trend_json
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
from .core.client import Data360Client
|
|
2
|
+
from .search.engine import SearchEngine
|
|
3
|
+
from .data.builder import DataBuilder
|
|
4
|
+
from .ai.agent import DataAgent
|
|
5
|
+
from .metadata.builder import MetadataBuilder
|
|
6
|
+
from .visual import viz
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
class API:
|
|
10
|
+
def __init__(self):
|
|
11
|
+
self._client = None
|
|
12
|
+
|
|
13
|
+
@property
|
|
14
|
+
def client(self):
|
|
15
|
+
if not self._client:
|
|
16
|
+
self._client = Data360Client()
|
|
17
|
+
return self._client
|
|
18
|
+
|
|
19
|
+
@property
|
|
20
|
+
def search(self):
|
|
21
|
+
return SearchEngine(self.client)
|
|
22
|
+
|
|
23
|
+
@property
|
|
24
|
+
def data(self):
|
|
25
|
+
return DataBuilder(self.client)
|
|
26
|
+
|
|
27
|
+
@property
|
|
28
|
+
def metadata(self):
|
|
29
|
+
return MetadataBuilder(self.client)
|
|
30
|
+
|
|
31
|
+
@property
|
|
32
|
+
def ai(self):
|
|
33
|
+
return DataAgent(self.client)
|
|
34
|
+
|
|
35
|
+
@property
|
|
36
|
+
def visual(self):
|
|
37
|
+
return viz
|
|
38
|
+
|
|
39
|
+
async def close(self):
|
|
40
|
+
if self._client:
|
|
41
|
+
await self._client.close()
|
|
42
|
+
|
|
43
|
+
__version__ = "0.2.1"
|
|
44
|
+
__author__ = "Maykol Medrano"
|
|
45
|
+
__email__ = "mmedrano2@uc.cl"
|
|
46
|
+
__credits__ = ["Applied Economist Policy Data Scientist"]
|
|
47
|
+
|
|
48
|
+
# Expose the human-friendly API at top level
|
|
49
|
+
from wbgapi360.api import search, get_data, plot
|
|
50
|
+
|
|
51
|
+
__all__ = ["search", "get_data", "plot"]
|