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,241 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Pericoupling country-pair database.
|
|
3
|
+
|
|
4
|
+
Loads a curated CSV database of country pairs to determine which are
|
|
5
|
+
pericoupled (geographically adjacent, value=1) vs telecoupled (distant,
|
|
6
|
+
value=0). The database uses ISO 3166-1 alpha-3 codes.
|
|
7
|
+
|
|
8
|
+
At runtime the full ``PeriTelecoupling_clean.csv`` is loaded if present;
|
|
9
|
+
otherwise the small ``PeriTelecoupling_subset.csv`` is used as a fallback
|
|
10
|
+
(useful for testing).
|
|
11
|
+
|
|
12
|
+
Source
|
|
13
|
+
------
|
|
14
|
+
PeriTelecoupling_clean.csv (research dataset using ISO 3166-1 alpha-3).
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
from __future__ import annotations
|
|
18
|
+
|
|
19
|
+
import csv
|
|
20
|
+
from dataclasses import dataclass
|
|
21
|
+
from enum import Enum
|
|
22
|
+
from importlib import resources
|
|
23
|
+
from pathlib import Path
|
|
24
|
+
|
|
25
|
+
from metacouplingllm.knowledge.countries import resolve_country_code
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
# ---------------------------------------------------------------------------
|
|
29
|
+
# Public types
|
|
30
|
+
# ---------------------------------------------------------------------------
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
class PairCouplingType(str, Enum):
|
|
34
|
+
"""Result of a pericoupling database lookup."""
|
|
35
|
+
|
|
36
|
+
PERICOUPLED = "pericoupled"
|
|
37
|
+
TELECOUPLED = "telecoupled"
|
|
38
|
+
UNKNOWN = "unknown"
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
@dataclass(frozen=True)
|
|
42
|
+
class PericouplingResult:
|
|
43
|
+
"""Result of looking up a country pair in the pericoupling database.
|
|
44
|
+
|
|
45
|
+
Attributes
|
|
46
|
+
----------
|
|
47
|
+
pair_type:
|
|
48
|
+
Whether the pair is pericoupled, telecoupled, or unknown.
|
|
49
|
+
sending_code:
|
|
50
|
+
Resolved ISO alpha-3 code for the sending country, or ``None``.
|
|
51
|
+
receiving_code:
|
|
52
|
+
Resolved ISO alpha-3 code for the receiving country, or ``None``.
|
|
53
|
+
confidence:
|
|
54
|
+
``"database"`` if looked up from the database, ``"unresolved"`` if
|
|
55
|
+
one or both country codes could not be resolved, ``"same_country"``
|
|
56
|
+
if both names resolved to the same country.
|
|
57
|
+
"""
|
|
58
|
+
|
|
59
|
+
pair_type: PairCouplingType
|
|
60
|
+
sending_code: str | None
|
|
61
|
+
receiving_code: str | None
|
|
62
|
+
confidence: str = "database"
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
# ---------------------------------------------------------------------------
|
|
66
|
+
# CSV loading
|
|
67
|
+
# ---------------------------------------------------------------------------
|
|
68
|
+
|
|
69
|
+
_pericoupled_pairs: frozenset[frozenset[str]] | None = None
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def _locate_csv() -> Path | None:
|
|
73
|
+
"""Find the pericoupling CSV data file.
|
|
74
|
+
|
|
75
|
+
Tries the full dataset first, then falls back to the subset.
|
|
76
|
+
"""
|
|
77
|
+
try:
|
|
78
|
+
data_pkg = resources.files("metacoupling") / "data"
|
|
79
|
+
except (TypeError, ModuleNotFoundError):
|
|
80
|
+
return None
|
|
81
|
+
|
|
82
|
+
for name in ("PeriTelecoupling_clean.csv", "PeriTelecoupling_subset.csv"):
|
|
83
|
+
candidate = data_pkg / name
|
|
84
|
+
# resources.files may return a Traversable; convert to Path if possible
|
|
85
|
+
try:
|
|
86
|
+
path = Path(str(candidate))
|
|
87
|
+
if path.is_file():
|
|
88
|
+
return path
|
|
89
|
+
except Exception:
|
|
90
|
+
continue
|
|
91
|
+
return None
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def _load_pairs() -> frozenset[frozenset[str]]:
|
|
95
|
+
"""Load pericoupled pairs from the CSV data file.
|
|
96
|
+
|
|
97
|
+
Returns a frozenset of frozensets — each inner frozenset is a pair of
|
|
98
|
+
ISO alpha-3 codes where Intracoupling == 1 (pericoupled). Since the
|
|
99
|
+
CSV contains both directions (A→B and B→A), this naturally deduplicates
|
|
100
|
+
via frozenset.
|
|
101
|
+
"""
|
|
102
|
+
csv_path = _locate_csv()
|
|
103
|
+
if csv_path is None:
|
|
104
|
+
return frozenset()
|
|
105
|
+
|
|
106
|
+
pairs: set[frozenset[str]] = set()
|
|
107
|
+
with open(csv_path, newline="", encoding="utf-8-sig") as fh:
|
|
108
|
+
reader = csv.DictReader(fh)
|
|
109
|
+
for row in reader:
|
|
110
|
+
if row.get("Intracoupling", "").strip() == "1":
|
|
111
|
+
sending = row["Sending"].strip()
|
|
112
|
+
receiving = row["Receiving"].strip()
|
|
113
|
+
pairs.add(frozenset({sending, receiving}))
|
|
114
|
+
return frozenset(pairs)
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def _get_pairs() -> frozenset[frozenset[str]]:
|
|
118
|
+
"""Lazily load and cache the pericoupled pairs."""
|
|
119
|
+
global _pericoupled_pairs
|
|
120
|
+
if _pericoupled_pairs is None:
|
|
121
|
+
_pericoupled_pairs = _load_pairs()
|
|
122
|
+
return _pericoupled_pairs
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
# ---------------------------------------------------------------------------
|
|
126
|
+
# Lookup functions
|
|
127
|
+
# ---------------------------------------------------------------------------
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
def lookup_pericoupling(
|
|
131
|
+
country_a: str,
|
|
132
|
+
country_b: str,
|
|
133
|
+
) -> PericouplingResult:
|
|
134
|
+
"""Look up whether two countries are pericoupled or telecoupled.
|
|
135
|
+
|
|
136
|
+
Parameters
|
|
137
|
+
----------
|
|
138
|
+
country_a:
|
|
139
|
+
Name or ISO code of the first country (e.g., ``"Mexico"`` or
|
|
140
|
+
``"MEX"``).
|
|
141
|
+
country_b:
|
|
142
|
+
Name or ISO code of the second country (e.g., ``"United States"``
|
|
143
|
+
or ``"USA"``).
|
|
144
|
+
|
|
145
|
+
Returns
|
|
146
|
+
-------
|
|
147
|
+
A :class:`PericouplingResult` with the lookup outcome.
|
|
148
|
+
|
|
149
|
+
Examples
|
|
150
|
+
--------
|
|
151
|
+
>>> result = lookup_pericoupling("Mexico", "United States")
|
|
152
|
+
>>> result.pair_type
|
|
153
|
+
<PairCouplingType.PERICOUPLED: 'pericoupled'>
|
|
154
|
+
|
|
155
|
+
>>> result = lookup_pericoupling("Brazil", "China")
|
|
156
|
+
>>> result.pair_type
|
|
157
|
+
<PairCouplingType.TELECOUPLED: 'telecoupled'>
|
|
158
|
+
"""
|
|
159
|
+
code_a = resolve_country_code(country_a)
|
|
160
|
+
code_b = resolve_country_code(country_b)
|
|
161
|
+
|
|
162
|
+
if code_a is None or code_b is None:
|
|
163
|
+
return PericouplingResult(
|
|
164
|
+
pair_type=PairCouplingType.UNKNOWN,
|
|
165
|
+
sending_code=code_a,
|
|
166
|
+
receiving_code=code_b,
|
|
167
|
+
confidence="unresolved",
|
|
168
|
+
)
|
|
169
|
+
|
|
170
|
+
if code_a == code_b:
|
|
171
|
+
return PericouplingResult(
|
|
172
|
+
pair_type=PairCouplingType.UNKNOWN,
|
|
173
|
+
sending_code=code_a,
|
|
174
|
+
receiving_code=code_b,
|
|
175
|
+
confidence="same_country",
|
|
176
|
+
)
|
|
177
|
+
|
|
178
|
+
pair = frozenset({code_a, code_b})
|
|
179
|
+
pairs = _get_pairs()
|
|
180
|
+
|
|
181
|
+
if pair in pairs:
|
|
182
|
+
return PericouplingResult(
|
|
183
|
+
pair_type=PairCouplingType.PERICOUPLED,
|
|
184
|
+
sending_code=code_a,
|
|
185
|
+
receiving_code=code_b,
|
|
186
|
+
confidence="database",
|
|
187
|
+
)
|
|
188
|
+
|
|
189
|
+
return PericouplingResult(
|
|
190
|
+
pair_type=PairCouplingType.TELECOUPLED,
|
|
191
|
+
sending_code=code_a,
|
|
192
|
+
receiving_code=code_b,
|
|
193
|
+
confidence="database",
|
|
194
|
+
)
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
def get_pericoupled_neighbors(country: str) -> set[str]:
|
|
198
|
+
"""Return the set of ISO alpha-3 codes pericoupled with a country.
|
|
199
|
+
|
|
200
|
+
Parameters
|
|
201
|
+
----------
|
|
202
|
+
country:
|
|
203
|
+
Country name or ISO alpha-3 code.
|
|
204
|
+
|
|
205
|
+
Returns
|
|
206
|
+
-------
|
|
207
|
+
A set of ISO alpha-3 codes for all countries that are pericoupled
|
|
208
|
+
(geographically adjacent) with the given country. Empty set if the
|
|
209
|
+
country cannot be resolved or has no pericoupled neighbors.
|
|
210
|
+
|
|
211
|
+
Examples
|
|
212
|
+
--------
|
|
213
|
+
>>> sorted(get_pericoupled_neighbors("Mexico"))
|
|
214
|
+
['BLZ', 'GTM', 'USA']
|
|
215
|
+
"""
|
|
216
|
+
code = resolve_country_code(country)
|
|
217
|
+
if code is None:
|
|
218
|
+
return set()
|
|
219
|
+
neighbors: set[str] = set()
|
|
220
|
+
for pair in _get_pairs():
|
|
221
|
+
if code in pair:
|
|
222
|
+
others = pair - frozenset({code})
|
|
223
|
+
if others:
|
|
224
|
+
neighbors.add(next(iter(others)))
|
|
225
|
+
return neighbors
|
|
226
|
+
|
|
227
|
+
|
|
228
|
+
def is_pericoupled(country_a: str, country_b: str) -> bool | None:
|
|
229
|
+
"""Convenience function for quick pericoupling checks.
|
|
230
|
+
|
|
231
|
+
Returns
|
|
232
|
+
-------
|
|
233
|
+
``True`` if pericoupled, ``False`` if telecoupled, ``None`` if one or
|
|
234
|
+
both countries could not be resolved.
|
|
235
|
+
"""
|
|
236
|
+
result = lookup_pericoupling(country_a, country_b)
|
|
237
|
+
if result.pair_type == PairCouplingType.PERICOUPLED:
|
|
238
|
+
return True
|
|
239
|
+
if result.pair_type == PairCouplingType.TELECOUPLED:
|
|
240
|
+
return False
|
|
241
|
+
return None
|