MetacouplingLLM 0.1.0__py3-none-any.whl

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.
Files changed (35) hide show
  1. metacouplingllm/__init__.py +208 -0
  2. metacouplingllm/core.py +4542 -0
  3. metacouplingllm/data/Papers.zip +0 -0
  4. metacouplingllm/data/PeriTelecoupling_clean.csv +49953 -0
  5. metacouplingllm/data/PeriTelecoupling_subset.csv +11 -0
  6. metacouplingllm/data/chunk_embeddings.manifest.json +11 -0
  7. metacouplingllm/data/chunk_embeddings.npy +0 -0
  8. metacouplingllm/data/pericoupled_adm1_edge_list.csv +8291 -0
  9. metacouplingllm/data/telecoupling_literature.bib +3498 -0
  10. metacouplingllm/knowledge/__init__.py +1 -0
  11. metacouplingllm/knowledge/adm1_pericoupling.py +591 -0
  12. metacouplingllm/knowledge/citations.py +109 -0
  13. metacouplingllm/knowledge/countries.py +557 -0
  14. metacouplingllm/knowledge/examples.py +713 -0
  15. metacouplingllm/knowledge/framework.py +717 -0
  16. metacouplingllm/knowledge/literature.py +518 -0
  17. metacouplingllm/knowledge/pericoupling.py +241 -0
  18. metacouplingllm/knowledge/rag.py +1791 -0
  19. metacouplingllm/knowledge/references.py +112 -0
  20. metacouplingllm/knowledge/websearch.py +1842 -0
  21. metacouplingllm/llm/__init__.py +1 -0
  22. metacouplingllm/llm/client.py +636 -0
  23. metacouplingllm/llm/parser.py +868 -0
  24. metacouplingllm/output/__init__.py +1 -0
  25. metacouplingllm/output/formatter.py +276 -0
  26. metacouplingllm/prompts/__init__.py +1 -0
  27. metacouplingllm/prompts/builder.py +477 -0
  28. metacouplingllm/prompts/templates.py +556 -0
  29. metacouplingllm/visualization/__init__.py +114 -0
  30. metacouplingllm/visualization/adm1_map.py +884 -0
  31. metacouplingllm/visualization/worldmap.py +1372 -0
  32. metacouplingllm-0.1.0.dist-info/METADATA +440 -0
  33. metacouplingllm-0.1.0.dist-info/RECORD +35 -0
  34. metacouplingllm-0.1.0.dist-info/WHEEL +4 -0
  35. metacouplingllm-0.1.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,557 @@
1
+ """
2
+ ISO 3166-1 alpha-3 country code mapping for pericoupling lookups.
3
+
4
+ Provides country name → ISO code resolution so that natural-language country
5
+ names produced by LLMs can be matched against the pericoupling database.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import re
11
+
12
+ # ---------------------------------------------------------------------------
13
+ # ISO alpha-3 code → canonical English name (covers all 224 codes in the
14
+ # pericoupling database plus common extras).
15
+ # ---------------------------------------------------------------------------
16
+
17
+ ISO_ALPHA3_NAMES: dict[str, str] = {
18
+ "ABW": "Aruba",
19
+ "AFG": "Afghanistan",
20
+ "AGO": "Angola",
21
+ "AIA": "Anguilla",
22
+ "ALB": "Albania",
23
+ "AND": "Andorra",
24
+ "ANT": "Netherlands Antilles",
25
+ "ARE": "United Arab Emirates",
26
+ "ARG": "Argentina",
27
+ "ARM": "Armenia",
28
+ "ATF": "French Southern Territories",
29
+ "ATG": "Antigua and Barbuda",
30
+ "AUS": "Australia",
31
+ "AUT": "Austria",
32
+ "AZE": "Azerbaijan",
33
+ "BDI": "Burundi",
34
+ "BEL": "Belgium",
35
+ "BEN": "Benin",
36
+ "BFA": "Burkina Faso",
37
+ "BGD": "Bangladesh",
38
+ "BGR": "Bulgaria",
39
+ "BHR": "Bahrain",
40
+ "BHS": "Bahamas",
41
+ "BIH": "Bosnia and Herzegovina",
42
+ "BLR": "Belarus",
43
+ "BLZ": "Belize",
44
+ "BMU": "Bermuda",
45
+ "BOL": "Bolivia",
46
+ "BRA": "Brazil",
47
+ "BRB": "Barbados",
48
+ "BRN": "Brunei",
49
+ "BTN": "Bhutan",
50
+ "BWA": "Botswana",
51
+ "CAF": "Central African Republic",
52
+ "CAN": "Canada",
53
+ "CHE": "Switzerland",
54
+ "CHL": "Chile",
55
+ "CHN": "China",
56
+ "CIV": "Ivory Coast",
57
+ "CMR": "Cameroon",
58
+ "COG": "Republic of the Congo",
59
+ "COL": "Colombia",
60
+ "COM": "Comoros",
61
+ "CPV": "Cape Verde",
62
+ "CRI": "Costa Rica",
63
+ "CUB": "Cuba",
64
+ "CYM": "Cayman Islands",
65
+ "CYP": "Cyprus",
66
+ "CZE": "Czech Republic",
67
+ "DEU": "Germany",
68
+ "DJI": "Djibouti",
69
+ "DMA": "Dominica",
70
+ "DNK": "Denmark",
71
+ "DOM": "Dominican Republic",
72
+ "DZA": "Algeria",
73
+ "ECU": "Ecuador",
74
+ "EGY": "Egypt",
75
+ "ERI": "Eritrea",
76
+ "ESH": "Western Sahara",
77
+ "ESP": "Spain",
78
+ "EST": "Estonia",
79
+ "ETH": "Ethiopia",
80
+ "FIN": "Finland",
81
+ "FJI": "Fiji",
82
+ "FLK": "Falkland Islands",
83
+ "FRA": "France",
84
+ "FSM": "Micronesia",
85
+ "GAB": "Gabon",
86
+ "GBR": "United Kingdom",
87
+ "GEO": "Georgia",
88
+ "GHA": "Ghana",
89
+ "GIB": "Gibraltar",
90
+ "GIN": "Guinea",
91
+ "GMB": "Gambia",
92
+ "GNB": "Guinea-Bissau",
93
+ "GNQ": "Equatorial Guinea",
94
+ "GRC": "Greece",
95
+ "GRD": "Grenada",
96
+ "GRL": "Greenland",
97
+ "GTM": "Guatemala",
98
+ "GUF": "French Guiana",
99
+ "GUY": "Guyana",
100
+ "HKG": "Hong Kong",
101
+ "HND": "Honduras",
102
+ "HRV": "Croatia",
103
+ "HTI": "Haiti",
104
+ "HUN": "Hungary",
105
+ "IDN": "Indonesia",
106
+ "IND": "India",
107
+ "IRL": "Ireland",
108
+ "IRN": "Iran",
109
+ "IRQ": "Iraq",
110
+ "ISL": "Iceland",
111
+ "ISR": "Israel",
112
+ "ITA": "Italy",
113
+ "JAM": "Jamaica",
114
+ "JOR": "Jordan",
115
+ "JPN": "Japan",
116
+ "KAZ": "Kazakhstan",
117
+ "KEN": "Kenya",
118
+ "KGZ": "Kyrgyzstan",
119
+ "KHM": "Cambodia",
120
+ "KIR": "Kiribati",
121
+ "KNA": "Saint Kitts and Nevis",
122
+ "KOR": "South Korea",
123
+ "KWT": "Kuwait",
124
+ "LAO": "Laos",
125
+ "LBN": "Lebanon",
126
+ "LBR": "Liberia",
127
+ "LBY": "Libya",
128
+ "LCA": "Saint Lucia",
129
+ "LKA": "Sri Lanka",
130
+ "LSO": "Lesotho",
131
+ "LTU": "Lithuania",
132
+ "LUX": "Luxembourg",
133
+ "LVA": "Latvia",
134
+ "MAC": "Macau",
135
+ "MAR": "Morocco",
136
+ "MDA": "Moldova",
137
+ "MDG": "Madagascar",
138
+ "MDV": "Maldives",
139
+ "MEX": "Mexico",
140
+ "MHL": "Marshall Islands",
141
+ "MKD": "North Macedonia",
142
+ "MLI": "Mali",
143
+ "MLT": "Malta",
144
+ "MMR": "Myanmar",
145
+ "MNG": "Mongolia",
146
+ "MNE": "Montenegro",
147
+ "MOZ": "Mozambique",
148
+ "MRT": "Mauritania",
149
+ "MUS": "Mauritius",
150
+ "MWI": "Malawi",
151
+ "MYS": "Malaysia",
152
+ "NAM": "Namibia",
153
+ "NCL": "New Caledonia",
154
+ "NER": "Niger",
155
+ "NGA": "Nigeria",
156
+ "NIC": "Nicaragua",
157
+ "NLD": "Netherlands",
158
+ "NOR": "Norway",
159
+ "NPL": "Nepal",
160
+ "NRU": "Nauru",
161
+ "NZL": "New Zealand",
162
+ "OMN": "Oman",
163
+ "PAK": "Pakistan",
164
+ "PAL": "Palestine",
165
+ "PAN": "Panama",
166
+ "PER": "Peru",
167
+ "PHL": "Philippines",
168
+ "PLW": "Palau",
169
+ "PNG": "Papua New Guinea",
170
+ "POL": "Poland",
171
+ "PRI": "Puerto Rico",
172
+ "PRK": "North Korea",
173
+ "PRT": "Portugal",
174
+ "PRY": "Paraguay",
175
+ "PSE": "Palestine",
176
+ "QAT": "Qatar",
177
+ "ROM": "Romania",
178
+ "RUS": "Russia",
179
+ "RWA": "Rwanda",
180
+ "SAU": "Saudi Arabia",
181
+ "SDN": "Sudan",
182
+ "SEN": "Senegal",
183
+ "SGP": "Singapore",
184
+ "SLB": "Solomon Islands",
185
+ "SLE": "Sierra Leone",
186
+ "SLV": "El Salvador",
187
+ "SMR": "San Marino",
188
+ "SOM": "Somalia",
189
+ "SSD": "South Sudan",
190
+ "STP": "Sao Tome and Principe",
191
+ "SUR": "Suriname",
192
+ "SVK": "Slovakia",
193
+ "SVN": "Slovenia",
194
+ "SWE": "Sweden",
195
+ "SWZ": "Eswatini",
196
+ "SYC": "Seychelles",
197
+ "SYR": "Syria",
198
+ "TCD": "Chad",
199
+ "TGO": "Togo",
200
+ "THA": "Thailand",
201
+ "TJK": "Tajikistan",
202
+ "TKM": "Turkmenistan",
203
+ "TMP": "East Timor",
204
+ "TON": "Tonga",
205
+ "TTO": "Trinidad and Tobago",
206
+ "TUN": "Tunisia",
207
+ "TUR": "Turkey",
208
+ "TUV": "Tuvalu",
209
+ "TWN": "Taiwan",
210
+ "TZA": "Tanzania",
211
+ "UGA": "Uganda",
212
+ "UKR": "Ukraine",
213
+ "URY": "Uruguay",
214
+ "USA": "United States",
215
+ "UZB": "Uzbekistan",
216
+ "VCT": "Saint Vincent and the Grenadines",
217
+ "VEN": "Venezuela",
218
+ "VNM": "Vietnam",
219
+ "VUT": "Vanuatu",
220
+ "WSM": "Samoa",
221
+ "YEM": "Yemen",
222
+ "YUG": "Yugoslavia",
223
+ "ZAF": "South Africa",
224
+ "ZAR": "Democratic Republic of the Congo",
225
+ "ZMB": "Zambia",
226
+ "ZWE": "Zimbabwe",
227
+ }
228
+
229
+ # ---------------------------------------------------------------------------
230
+ # Aliases — common alternative names, demonyms, and abbreviations that map
231
+ # to the canonical ISO alpha-3 code.
232
+ # ---------------------------------------------------------------------------
233
+
234
+ _ALIASES: dict[str, str] = {
235
+ # Short forms / abbreviations
236
+ "us": "USA",
237
+ "usa": "USA",
238
+ "u.s.": "USA",
239
+ "u.s.a.": "USA",
240
+ "uk": "GBR",
241
+ "u.k.": "GBR",
242
+ "uae": "ARE",
243
+ "u.a.e.": "ARE",
244
+ "drc": "ZAR",
245
+ "dr congo": "ZAR",
246
+ "rok": "KOR",
247
+ "dprk": "PRK",
248
+ "prc": "CHN",
249
+ # Common alternative names
250
+ "america": "USA",
251
+ "united states": "USA",
252
+ "united states of america": "USA",
253
+ "britain": "GBR",
254
+ "great britain": "GBR",
255
+ "united kingdom": "GBR",
256
+ "england": "GBR",
257
+ "scotland": "GBR",
258
+ "wales": "GBR",
259
+ "holland": "NLD",
260
+ "the netherlands": "NLD",
261
+ "ivory coast": "CIV",
262
+ "cote d'ivoire": "CIV",
263
+ "côte d'ivoire": "CIV",
264
+ "czech republic": "CZE",
265
+ "czechia": "CZE",
266
+ "south korea": "KOR",
267
+ "south sudan": "SSD",
268
+ "greenland": "GRL",
269
+ "montenegro": "MNE",
270
+ "puerto rico": "PRI",
271
+ "new caledonia": "NCL",
272
+ "falkland islands": "FLK",
273
+ "falklands": "FLK",
274
+ "republic of korea": "KOR",
275
+ "north korea": "PRK",
276
+ "democratic people's republic of korea": "PRK",
277
+ "burma": "MMR",
278
+ "myanmar": "MMR",
279
+ "persia": "IRN",
280
+ "swaziland": "SWZ",
281
+ "eswatini": "SWZ",
282
+ "east timor": "TMP",
283
+ "timor-leste": "TMP",
284
+ "zaire": "ZAR",
285
+ "congo-kinshasa": "ZAR",
286
+ "democratic republic of the congo": "ZAR",
287
+ "congo-brazzaville": "COG",
288
+ "republic of the congo": "COG",
289
+ "congo": "COG",
290
+ "palestine": "PSE",
291
+ "palestinian territories": "PSE",
292
+ "west bank": "PSE",
293
+ "gaza": "PSE",
294
+ "hong kong": "HKG",
295
+ "macau": "MAC",
296
+ "macao": "MAC",
297
+ "taiwan": "TWN",
298
+ "brunei darussalam": "BRN",
299
+ "cabo verde": "CPV",
300
+ "cape verde": "CPV",
301
+ "laos": "LAO",
302
+ "lao pdr": "LAO",
303
+ "russia": "RUS",
304
+ "russian federation": "RUS",
305
+ "soviet union": "RUS",
306
+ "ussr": "RUS",
307
+ "iran": "IRN",
308
+ "syria": "SYR",
309
+ "libya": "LBY",
310
+ "venezuela": "VEN",
311
+ "bolivia": "BOL",
312
+ "tanzania": "TZA",
313
+ "vietnam": "VNM",
314
+ "viet nam": "VNM",
315
+ "north macedonia": "MKD",
316
+ "macedonia": "MKD",
317
+ "bosnia": "BIH",
318
+ "bosnia and herzegovina": "BIH",
319
+ "serbia": "YUG",
320
+ "yugoslavia": "YUG",
321
+ "serbia and montenegro": "YUG",
322
+ "western sahara": "ESH",
323
+ "french guiana": "GUF",
324
+ "papua new guinea": "PNG",
325
+ "new zealand": "NZL",
326
+ "south africa": "ZAF",
327
+ "saudi arabia": "SAU",
328
+ "sri lanka": "LKA",
329
+ "trinidad and tobago": "TTO",
330
+ "el salvador": "SLV",
331
+ "costa rica": "CRI",
332
+ "puerto rico": "USA",
333
+ "central african republic": "CAF",
334
+ "equatorial guinea": "GNQ",
335
+ "guinea-bissau": "GNB",
336
+ "sierra leone": "SLE",
337
+ "burkina faso": "BFA",
338
+ "san marino": "SMR",
339
+ "turkiye": "TUR",
340
+ "türkiye": "TUR",
341
+ "turkey": "TUR",
342
+ # Common demonyms (adjective forms used by LLMs)
343
+ "american": "USA",
344
+ "mexican": "MEX",
345
+ "canadian": "CAN",
346
+ "brazilian": "BRA",
347
+ "chinese": "CHN",
348
+ "indian": "IND",
349
+ "german": "DEU",
350
+ "french": "FRA",
351
+ "british": "GBR",
352
+ "japanese": "JPN",
353
+ "korean": "KOR",
354
+ # "Korea" alone is ambiguous (KOR vs PRK) but in academic
355
+ # literature ~99% of bare "Korea" mentions refer to South Korea
356
+ # (KOR) — North Korea is almost always written out in full as
357
+ # "North Korea" or "DPRK". Default to KOR.
358
+ "korea": "KOR",
359
+ "australian": "AUS",
360
+ "russian": "RUS",
361
+ "italian": "ITA",
362
+ "spanish": "ESP",
363
+ "colombian": "COL",
364
+ "chilean": "CHL",
365
+ "peruvian": "PER",
366
+ "argentine": "ARG",
367
+ "argentinian": "ARG",
368
+ "venezuelan": "VEN",
369
+ "ecuadorian": "ECU",
370
+ "bolivian": "BOL",
371
+ "paraguayan": "PRY",
372
+ "uruguayan": "URY",
373
+ "guatemalan": "GTM",
374
+ "honduran": "HND",
375
+ "salvadoran": "SLV",
376
+ "nicaraguan": "NIC",
377
+ "costa rican": "CRI",
378
+ "panamanian": "PAN",
379
+ "cuban": "CUB",
380
+ "dominican": "DOM",
381
+ "haitian": "HTI",
382
+ "jamaican": "JAM",
383
+ "ethiopian": "ETH",
384
+ "kenyan": "KEN",
385
+ "nigerian": "NGA",
386
+ "ghanaian": "GHA",
387
+ "south african": "ZAF",
388
+ "egyptian": "EGY",
389
+ "moroccan": "MAR",
390
+ "tunisian": "TUN",
391
+ "algerian": "DZA",
392
+ "sudanese": "SDN",
393
+ "tanzanian": "TZA",
394
+ "ugandan": "UGA",
395
+ "thai": "THA",
396
+ "vietnamese": "VNM",
397
+ "indonesian": "IDN",
398
+ "malaysian": "MYS",
399
+ "philippine": "PHL",
400
+ "filipino": "PHL",
401
+ "cambodian": "KHM",
402
+ "myanmar": "MMR",
403
+ "burmese": "MMR",
404
+ "pakistani": "PAK",
405
+ "afghan": "AFG",
406
+ "iranian": "IRN",
407
+ "iraqi": "IRQ",
408
+ "saudi": "SAU",
409
+ "turkish": "TUR",
410
+ "israeli": "ISR",
411
+ "palestinian": "PSE",
412
+ "jordanian": "JOR",
413
+ "lebanese": "LBN",
414
+ "syrian": "SYR",
415
+ "polish": "POL",
416
+ "ukrainian": "UKR",
417
+ "romanian": "ROM",
418
+ "hungarian": "HUN",
419
+ "czech": "CZE",
420
+ "swedish": "SWE",
421
+ "norwegian": "NOR",
422
+ "finnish": "FIN",
423
+ "danish": "DNK",
424
+ "dutch": "NLD",
425
+ "belgian": "BEL",
426
+ "swiss": "CHE",
427
+ "austrian": "AUT",
428
+ "portuguese": "PRT",
429
+ "greek": "GRC",
430
+ "irish": "IRL",
431
+ "scottish": "GBR",
432
+ "welsh": "GBR",
433
+ "new zealand": "NZL",
434
+ }
435
+
436
+
437
+ # ---------------------------------------------------------------------------
438
+ # Internal reverse index (lazily built)
439
+ # ---------------------------------------------------------------------------
440
+
441
+ _name_to_code: dict[str, str] | None = None
442
+
443
+
444
+ def _build_reverse_index() -> dict[str, str]:
445
+ """Build a mapping from lowercase canonical name → code."""
446
+ index: dict[str, str] = {}
447
+ for code, name in ISO_ALPHA3_NAMES.items():
448
+ index[name.lower()] = code
449
+ return index
450
+
451
+
452
+ def _get_reverse_index() -> dict[str, str]:
453
+ global _name_to_code
454
+ if _name_to_code is None:
455
+ _name_to_code = _build_reverse_index()
456
+ return _name_to_code
457
+
458
+
459
+ # Cached sorted list of (lowercase_name, code) for substring matching,
460
+ # sorted by length descending so longest matches win.
461
+ _sorted_all_names: list[tuple[str, str]] | None = None
462
+
463
+
464
+ def _get_sorted_all_names() -> list[tuple[str, str]]:
465
+ """Return cached sorted (name, code) pairs for substring matching."""
466
+ global _sorted_all_names
467
+ if _sorted_all_names is None:
468
+ rev = _get_reverse_index()
469
+ pairs: list[tuple[str, str]] = []
470
+ for alias, code in _ALIASES.items():
471
+ pairs.append((alias, code))
472
+ for name_lower, code in rev.items():
473
+ pairs.append((name_lower, code))
474
+ pairs.sort(key=lambda t: len(t[0]), reverse=True)
475
+ _sorted_all_names = pairs
476
+ return _sorted_all_names
477
+
478
+
479
+ def _contains_standalone_country_term(text: str, term: str) -> bool:
480
+ """Return True when *term* appears as a standalone token/phrase.
481
+
482
+ This avoids false positives from naive substring matching such as:
483
+ - ``"Indiana"`` matching ``"ind"`` (India)
484
+ - ``"used"`` matching ``"us"`` (United States)
485
+ """
486
+ pattern = rf"(?<![a-z0-9]){re.escape(term)}(?![a-z0-9])"
487
+ return re.search(pattern, text) is not None
488
+
489
+
490
+ # ---------------------------------------------------------------------------
491
+ # Public API
492
+ # ---------------------------------------------------------------------------
493
+
494
+
495
+ def resolve_country_code(name_or_code: str) -> str | None:
496
+ """Resolve a country name or code to an ISO 3166-1 alpha-3 code.
497
+
498
+ Tries the following in order:
499
+
500
+ 1. Exact ISO code match (case-insensitive, e.g. ``"usa"`` → ``"USA"``)
501
+ 2. Alias match (e.g. ``"America"`` → ``"USA"``)
502
+ 3. Canonical name match (e.g. ``"United States"`` → ``"USA"``)
503
+ 4. Substring match — if *name_or_code* contains a known country name
504
+ (e.g. ``"Ethiopian coffee regions"`` → ``"ETH"``)
505
+
506
+ Parameters
507
+ ----------
508
+ name_or_code:
509
+ Country name, ISO code, or text containing a country name.
510
+
511
+ Returns
512
+ -------
513
+ The ISO alpha-3 code, or ``None`` if no match is found.
514
+ """
515
+ if not name_or_code or not name_or_code.strip():
516
+ return None
517
+
518
+ text = name_or_code.strip()
519
+ text_lower = text.lower()
520
+
521
+ # 1. Exact code match
522
+ text_upper = text.upper()
523
+ if text_upper in ISO_ALPHA3_NAMES:
524
+ return text_upper
525
+
526
+ # 2. Alias match
527
+ if text_lower in _ALIASES:
528
+ return _ALIASES[text_lower]
529
+
530
+ # 3. Canonical name match
531
+ rev = _get_reverse_index()
532
+ if text_lower in rev:
533
+ return rev[text_lower]
534
+
535
+ # 4. Substring match — check if any alias or canonical name appears
536
+ # in the input text. Try longest matches first to avoid partial hits.
537
+ # (e.g. "South Korea" before "Korea")
538
+ for name_lower, code in _get_sorted_all_names():
539
+ if _contains_standalone_country_term(text_lower, name_lower):
540
+ return code
541
+
542
+ return None
543
+
544
+
545
+ def get_country_name(code: str) -> str:
546
+ """Return the canonical English name for an ISO alpha-3 code.
547
+
548
+ Parameters
549
+ ----------
550
+ code:
551
+ ISO 3166-1 alpha-3 code (case-insensitive).
552
+
553
+ Returns
554
+ -------
555
+ The country name, or the code itself if not found.
556
+ """
557
+ return ISO_ALPHA3_NAMES.get(code.upper(), code)