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.
- metacouplingllm/__init__.py +208 -0
- metacouplingllm/core.py +4542 -0
- metacouplingllm/data/Papers.zip +0 -0
- metacouplingllm/data/PeriTelecoupling_clean.csv +49953 -0
- metacouplingllm/data/PeriTelecoupling_subset.csv +11 -0
- metacouplingllm/data/chunk_embeddings.manifest.json +11 -0
- metacouplingllm/data/chunk_embeddings.npy +0 -0
- metacouplingllm/data/pericoupled_adm1_edge_list.csv +8291 -0
- metacouplingllm/data/telecoupling_literature.bib +3498 -0
- metacouplingllm/knowledge/__init__.py +1 -0
- metacouplingllm/knowledge/adm1_pericoupling.py +591 -0
- metacouplingllm/knowledge/citations.py +109 -0
- metacouplingllm/knowledge/countries.py +557 -0
- metacouplingllm/knowledge/examples.py +713 -0
- metacouplingllm/knowledge/framework.py +717 -0
- metacouplingllm/knowledge/literature.py +518 -0
- metacouplingllm/knowledge/pericoupling.py +241 -0
- metacouplingllm/knowledge/rag.py +1791 -0
- metacouplingllm/knowledge/references.py +112 -0
- metacouplingllm/knowledge/websearch.py +1842 -0
- metacouplingllm/llm/__init__.py +1 -0
- metacouplingllm/llm/client.py +636 -0
- metacouplingllm/llm/parser.py +868 -0
- metacouplingllm/output/__init__.py +1 -0
- metacouplingllm/output/formatter.py +276 -0
- metacouplingllm/prompts/__init__.py +1 -0
- metacouplingllm/prompts/builder.py +477 -0
- metacouplingllm/prompts/templates.py +556 -0
- metacouplingllm/visualization/__init__.py +114 -0
- metacouplingllm/visualization/adm1_map.py +884 -0
- metacouplingllm/visualization/worldmap.py +1372 -0
- metacouplingllm-0.1.0.dist-info/METADATA +440 -0
- metacouplingllm-0.1.0.dist-info/RECORD +35 -0
- metacouplingllm-0.1.0.dist-info/WHEEL +4 -0
- 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)
|