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,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