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,440 @@
1
+ Metadata-Version: 2.4
2
+ Name: MetacouplingLLM
3
+ Version: 0.1.0
4
+ Summary: LLM-powered toolkit for applying telecoupling and metacoupling frameworks to research
5
+ Project-URL: Homepage, https://github.com/Hanshan-XY/MetacouplingLLM
6
+ Project-URL: Documentation, https://github.com/Hanshan-XY/MetacouplingLLM/blob/main/INTRODUCTION.md
7
+ Project-URL: Manual, https://github.com/Hanshan-XY/MetacouplingLLM/blob/main/MANUAL.md
8
+ Project-URL: Issues, https://github.com/Hanshan-XY/MetacouplingLLM/issues
9
+ Project-URL: Repository, https://github.com/Hanshan-XY/MetacouplingLLM
10
+ Author: Yingjie Li, Zihan Zheng, Nan Jia, Xin Lan, Jianguo Liu
11
+ Author-email: Xiang Yu <yuxiang4@msu.edu>
12
+ Maintainer-email: Xiang Yu <yuxiang4@msu.edu>
13
+ License-Expression: MIT
14
+ License-File: LICENSE
15
+ Keywords: coupled-human-natural-systems,llm,metacoupling,research,spatial-analysis,sustainability,sustainability-science,telecoupling
16
+ Classifier: Development Status :: 3 - Alpha
17
+ Classifier: Intended Audience :: Science/Research
18
+ Classifier: License :: OSI Approved :: MIT License
19
+ Classifier: Natural Language :: English
20
+ Classifier: Operating System :: OS Independent
21
+ Classifier: Programming Language :: Python :: 3
22
+ Classifier: Programming Language :: Python :: 3 :: Only
23
+ Classifier: Programming Language :: Python :: 3.10
24
+ Classifier: Programming Language :: Python :: 3.11
25
+ Classifier: Programming Language :: Python :: 3.12
26
+ Classifier: Programming Language :: Python :: 3.13
27
+ Classifier: Topic :: Scientific/Engineering
28
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
29
+ Classifier: Topic :: Scientific/Engineering :: GIS
30
+ Classifier: Topic :: Scientific/Engineering :: Information Analysis
31
+ Requires-Python: >=3.10
32
+ Requires-Dist: fastembed>=0.8
33
+ Requires-Dist: numpy>=1.21
34
+ Provides-Extra: all
35
+ Requires-Dist: anthropic>=0.18; extra == 'all'
36
+ Requires-Dist: ddgs>=6.0; extra == 'all'
37
+ Requires-Dist: geopandas>=0.14; extra == 'all'
38
+ Requires-Dist: google-genai>=1.0; extra == 'all'
39
+ Requires-Dist: matplotlib>=3.7; extra == 'all'
40
+ Requires-Dist: openai>=1.0; extra == 'all'
41
+ Provides-Extra: anthropic
42
+ Requires-Dist: anthropic>=0.18; extra == 'anthropic'
43
+ Provides-Extra: dev
44
+ Requires-Dist: pytest-cov>=4.0; extra == 'dev'
45
+ Requires-Dist: pytest>=7.0; extra == 'dev'
46
+ Provides-Extra: gemini
47
+ Requires-Dist: google-genai>=1.0; extra == 'gemini'
48
+ Provides-Extra: grok
49
+ Requires-Dist: openai>=1.0; extra == 'grok'
50
+ Provides-Extra: openai
51
+ Requires-Dist: openai>=1.0; extra == 'openai'
52
+ Provides-Extra: search
53
+ Requires-Dist: ddgs>=6.0; extra == 'search'
54
+ Provides-Extra: viz
55
+ Requires-Dist: geopandas>=0.14; extra == 'viz'
56
+ Requires-Dist: matplotlib>=3.7; extra == 'viz'
57
+ Description-Content-Type: text/markdown
58
+
59
+ # Metacoupling: An LLM-Powered Python Package for Applying the Metacoupling Framework
60
+
61
+ ## 1. Overview
62
+
63
+ **Metacoupling** is a Python package (v0.1.0) that helps researchers apply the telecoupling and metacoupling frameworks (Liu et al., 2013; Liu, 2017) to their own research topics using Large Language Models (LLMs). Given a natural-language research description, the package produces a structured, framework-compliant analysis that identifies coupled human and natural systems, classifies coupling types, maps flows, agents, causes, and effects, and grounds the output in both a curated literature database and real-time web search results.
64
+
65
+ **Key capabilities:**
66
+
67
+ - Structured metacoupling analysis from free-text research descriptions
68
+ - Multi-turn refinement via conversational LLM interaction
69
+ - Retrieval-Augmented Generation (RAG) with 262 full-text telecoupling papers
70
+ - **RAG-only literature Q&A mode** for users already familiar with the framework (`coupling_analysis=False`)
71
+ - Literature recommendation from a curated BibTeX database
72
+ - Real-time web search grounding (DuckDuckGo, no API key required)
73
+ - Pericoupling validation against two geographic databases (country-level and subnational ADM1)
74
+ - Automated map generation at both country and subnational levels
75
+ - Support for OpenAI, Anthropic, **Google Gemini**, **xAI Grok**, or any custom LLM backend (each with native web-search auto-wiring)
76
+
77
+ **Requirements:** Python 3.10+, no hard runtime dependencies. Optional extras: `openai`, `anthropic`, `geopandas`+`matplotlib` (visualization), `ddgs` (web search).
78
+
79
+ ### Quick Install
80
+
81
+ ```bash
82
+ pip install metacoupling
83
+ pip install "metacoupling[openai]"
84
+ pip install "metacoupling[anthropic]"
85
+ pip install "metacoupling[gemini]"
86
+ pip install "metacoupling[grok]"
87
+ pip install "metacoupling[search]"
88
+ pip install "metacoupling[viz]"
89
+ pip install "metacoupling[all]"
90
+ ```
91
+
92
+ If you want to use the built-in OpenAI example below, install `metacoupling[openai]`.
93
+
94
+ ### What Users Get
95
+
96
+ - A structured metacoupling analysis from a plain-language study description
97
+ - Optional literature recommendations and supporting evidence passages
98
+ - Optional web-grounded context for current trade, policy, or event information
99
+ - Optional map generation for country-level and ADM1-level analyses
100
+
101
+ ---
102
+
103
+ ## 2. Theoretical Foundations
104
+
105
+ The package operationalizes the **metacoupling framework** (Liu, 2017), which integrates three types of human-nature interactions across geographic scales:
106
+
107
+ | Coupling Type | Definition | Example |
108
+ |---|---|---|
109
+ | **Intracoupling** | Interactions *within* a single coupled human and natural system (CHANS) | Manure management impacts on local water quality in Michigan |
110
+ | **Pericoupling** | Interactions *between adjacent* coupled systems | Feed grain trade between Michigan and neighboring Indiana |
111
+ | **Telecoupling** | Interactions *between distant* coupled systems | Pork exports from Michigan to Japan |
112
+
113
+ The framework identifies five core components in each coupling:
114
+
115
+ 1. **Systems** -- Sending, receiving, and spillover systems, each with human and natural subsystems
116
+ 2. **Flows** -- Movements of matter, capital, energy, information, people, and organisms
117
+ 3. **Agents** -- Fixed categories: individuals / households; firms / traders / corporations; governments / policymakers; organizations / NGOs; non-human agents
118
+ 4. **Causes** -- Fixed categories: economic; political / institutional; ecological / biological; technological / infrastructural; cultural / social / demographic; hydrological; climatic / atmospheric; geological / geomorphological
119
+ 5. **Effects** -- The same fixed categories used for causes, applied to outcomes across coupled systems
120
+
121
+ The package encodes 14 telecoupling categories from the literature (trade, migration, tourism, species invasion, water transfer, etc.) and the six-phase operationalization procedure from Liu (2017).
122
+
123
+ ---
124
+
125
+ ## 3. Architecture
126
+
127
+ ```
128
+ Research Description (free text)
129
+ |
130
+ +---------v----------+
131
+ | MetacouplingAssistant |
132
+ +---------+----------+
133
+ |
134
+ +-------------------+-------------------+
135
+ | | |
136
+ +-------v-------+ +-------v--------+ +-------v-------+
137
+ | PromptBuilder | | Web Search | | RAG Engine |
138
+ | (6-layer | | (DuckDuckGo) | | (262 papers, |
139
+ | system prompt)| | | | embeddings + |
140
+ | | | | | TF-IDF) |
141
+ +-------+-------+ +-------+--------+ +-------+-------+
142
+ | | |
143
+ +-------------------+-------------------+
144
+ |
145
+ +---------v----------+
146
+ | LLM Client |
147
+ | (OpenAI/Anthropic/ |
148
+ | custom backend) |
149
+ +---------+----------+
150
+ |
151
+ +---------v----------+
152
+ | Parser |
153
+ | (structured |
154
+ | ParsedAnalysis) |
155
+ +---------+----------+
156
+ |
157
+ +-------------------+-------------------+
158
+ | | |
159
+ +-------v-------+ +-------v--------+ +-------v-------+
160
+ | Pericoupling | | Literature | | Map Generator |
161
+ | Validation | | Recommendations| | (world/ADM1) |
162
+ +---------------+ +----------------+ +---------------+
163
+ |
164
+ +---------v----------+
165
+ | AnalysisResult |
166
+ | .parsed |
167
+ | .formatted |
168
+ | .map |
169
+ +--------------------+
170
+ ```
171
+
172
+ ---
173
+
174
+ ## 4. Core Functions
175
+
176
+ ### 4.1 MetacouplingAssistant
177
+
178
+ The central class that orchestrates the entire analysis pipeline.
179
+
180
+ ```python
181
+ from metacouplingllm import (
182
+ JOURNAL_ARTICLES_2025,
183
+ MetacouplingAssistant,
184
+ OpenAIAdapter,
185
+ )
186
+ from openai import OpenAI
187
+
188
+ advisor = MetacouplingAssistant(
189
+ llm_client=OpenAIAdapter(OpenAI(api_key="..."), model="gpt-5.2"),
190
+ auto_map=True, # Generate map automatically
191
+ rag_corpus=JOURNAL_ARTICLES_2025, # Use bundled 2025 journal corpus
192
+ web_search=True, # Ground analysis in web search results
193
+ web_search_max_results=5, # Number of web results to retrieve
194
+ web_structured_extraction=True, # Recommended with web_search + auto_map
195
+ rag_top_k=10, # Number of RAG evidence passages
196
+ rag_min_score=0.15, # Minimum cosine similarity for RAG
197
+ max_examples=2, # Framework examples in prompt
198
+ temperature=0.7, # LLM temperature
199
+ verbose=True, # Print progress messages
200
+ )
201
+ ```
202
+
203
+ **Key methods:**
204
+
205
+ | Method | Purpose |
206
+ |---|---|
207
+ | `analyze(research_description)` | First-turn structured analysis |
208
+ | `refine(info, focus_component=None)` | Multi-turn follow-up refinement |
209
+ | `reset()` | Clear conversation for a new topic |
210
+
211
+ ### 4.2 Prompt Engineering (6-Layer System)
212
+
213
+ The system prompt is constructed in six layers:
214
+
215
+ 1. **Role** -- Expert persona in metacoupling and sustainability science
216
+ 2. **Knowledge** -- Full framework definitions, 14 categories, coupling transformations
217
+ 3. **Methodology** -- Six-phase operationalization procedure (Liu, 2017)
218
+ 4. **Examples** -- Semantically selected real-world case studies (e.g., Brazil-China soybean trade, Beijing water system)
219
+ 5. **Output Format** -- Structured template for seven analysis sections
220
+ 6. **Interaction** -- Multi-turn refinement guidelines and citation expectations
221
+
222
+ Before calling the LLM, the system also injects:
223
+ - **Pericoupling hints** from the geographic database (e.g., "Michigan and Indiana are pericoupled")
224
+ - **Web search context** with `[W1]`, `[W2]` labels for inline citation
225
+ - **Structured web map hints** with validated countries and flows when enabled
226
+ - **ADM1 neighbor information** when subnational regions are detected
227
+
228
+ ### 4.3 Retrieval-Augmented Generation (RAG)
229
+
230
+ The RAG engine provides evidence grounding from 262 full-text telecoupling and metacoupling papers:
231
+
232
+ - **Indexing**: Papers are chunked by section and indexed by one of two backends:
233
+ - **Embeddings (default)** -- semantic retrieval via `fastembed` + the `BAAI/bge-small-en-v1.5` ONNX model. Captures synonyms, paraphrases, and related concepts (e.g., a query about "soybean trade" also matches chunks about "soya bean exports" and "Glycine max shipments"). Pre-computed corpus vectors are shipped with the package as `chunk_embeddings.npy` (~15 MB) so users never have to re-encode.
234
+ - **TF-IDF (fallback)** -- lexical retrieval using TF-IDF + cosine similarity. Activated when `fastembed` is unavailable or the pre-computed file is missing.
235
+ - **Retrieval**: Cosine similarity; top-k deduplication (at most one chunk per paper)
236
+ - **Citation**: Evidence passages are appended as `[1]`, `[2]`, ... with inline annotation
237
+ - **Lightweight**: `fastembed` + `onnxruntime` add ~20 MB to the install; no torch/GPU dependencies
238
+ - **Backend selection**: `MetacouplingAssistant(..., rag_backend="auto")` (default) picks embeddings if available and transparently falls back to TF-IDF. Explicit options: `"embeddings"`, `"tfidf"`.
239
+
240
+ ### 4.4 Web Search Grounding
241
+
242
+ Web search injects current, real-world context (trade data, policies, recent events) that may not be in the LLM's training data:
243
+
244
+ - Three fallback backends: `ddgs` -> `duckduckgo_search` -> stdlib (`urllib` + `html.parser`)
245
+ - Works on Google Colab without any extra packages (stdlib fallback)
246
+ - Results cited as `[W1]`, `[W2]`, ... -- distinct from literature `[1]`, `[2]`
247
+ - Recommended default for web-grounded maps: `web_structured_extraction=True` runs a second LLM pass over the web snippets and validates map-ready countries and flows before using them in auto-maps
248
+
249
+ ### 4.5 Pericoupling Databases
250
+
251
+ Two geographic adjacency databases validate LLM coupling classifications:
252
+
253
+ | Database | Scope | Coverage |
254
+ |---|---|---|
255
+ | Country-level | Sovereign states | Full global (ISO alpha-3) |
256
+ | ADM1 (subnational) | First-level administrative regions | 3,366 regions, 8,290 border pairs, 195 countries |
257
+
258
+ Functions: `is_pericoupled()`, `get_pericoupled_neighbors()`, `lookup_adm1_pericoupling()`, etc.
259
+
260
+ ### 4.6 Literature Recommendations
261
+
262
+ From a curated BibTeX database of 262 telecoupling/metacoupling papers, the system recommends the most relevant papers by matching keywords, coupling types, and domain overlap with the analysis.
263
+
264
+ ### 4.7 Map Visualization
265
+
266
+ Three map functions generate matplotlib figures:
267
+
268
+ | Function | Level | Data Source |
269
+ |---|---|---|
270
+ | `plot_focal_country_map(country)` | Country | Local World Bank Admin 0 `all_layers` if available; otherwise hosted `Admin 0_all_layers` mirror; fallback official World Bank Admin 0 10m |
271
+ | `plot_analysis_map(parsed_analysis)` | Country | Local World Bank Admin 0 `all_layers` if available; otherwise hosted `Admin 0_all_layers` mirror; fallback official World Bank Admin 0 10m |
272
+ | `plot_focal_adm1_map(adm1_code)` | Subnational (ADM1) | Local World Bank Admin 1 if available; otherwise hosted `Admin 1.gpkg` mirror, with World Bank `NDLSA.gpkg` for disputed-area overlay |
273
+
274
+ Map features: coupling-colored regions, flow arrows, disputed territory hatching, customizable color palettes.
275
+
276
+ ### 4.8 LLM Client Abstraction
277
+
278
+ The package uses a protocol-based design that supports any LLM backend:
279
+
280
+ ```python
281
+ # Built-in adapters
282
+ OpenAIAdapter(client, model="gpt-4o")
283
+ AnthropicAdapter(client, model="claude-sonnet-4-20250514")
284
+
285
+ # Any custom client with a chat() method also works
286
+ class MyClient:
287
+ def chat(self, messages, temperature=0.7, max_tokens=None):
288
+ return LLMResponse(content="...")
289
+ ```
290
+
291
+ ---
292
+
293
+ ## 5. Operation Procedure
294
+
295
+ ### Step 1: Install
296
+
297
+ ```bash
298
+ pip install metacoupling[all] # full installation
299
+ # or selectively:
300
+ pip install metacoupling[openai] # OpenAI support
301
+ pip install metacoupling[anthropic] # Anthropic support
302
+ pip install metacoupling[viz] # maps (geopandas + matplotlib)
303
+ pip install metacoupling[search] # web search (ddgs)
304
+ ```
305
+
306
+ ### Step 2: Initialize
307
+
308
+ ```python
309
+ from openai import OpenAI
310
+ from metacouplingllm import (
311
+ JOURNAL_ARTICLES_2025,
312
+ MetacouplingAssistant,
313
+ OpenAIAdapter,
314
+ )
315
+
316
+ client = OpenAI(api_key="your-key")
317
+ advisor = MetacouplingAssistant(
318
+ llm_client=OpenAIAdapter(client, model="gpt-5.2"),
319
+ auto_map=True,
320
+ rag_corpus=JOURNAL_ARTICLES_2025,
321
+ web_search=True,
322
+ web_search_max_results=5,
323
+ web_structured_extraction=True,
324
+ rag_top_k=10,
325
+ rag_min_score=0.15,
326
+ )
327
+ ```
328
+
329
+ ### Step 3: Analyze
330
+
331
+ ```python
332
+ result = advisor.analyze("""
333
+ My research examines what the impact of Brazil's soybeans exports is.
334
+ """)
335
+
336
+ print(result.formatted) # Full formatted report
337
+
338
+ if result.map:
339
+ result.map.savefig("metacoupling_map.png", dpi=150, bbox_inches="tight")
340
+ ```
341
+
342
+ The output includes:
343
+ - Coupling classification (intracoupling / pericoupling / telecoupling)
344
+ - Systems identification (sending, receiving, spillover with human and natural subsystems)
345
+ - Flows analysis (matter, capital, information, energy, people, organisms)
346
+ - Agents grouped by the fixed five-category agent vocabulary
347
+ - Causes grouped by the fixed cause/effect category vocabulary
348
+ - Effects grouped by the fixed cause/effect category vocabulary
349
+ - Research gaps and suggestions
350
+ - Literature evidence with `[1]`-`[N]` citations
351
+ - Web sources with `[W1]`-`[WN]` citations
352
+ - Pericoupling database validation
353
+
354
+ ### Step 4: Refine (optional)
355
+
356
+ ```python
357
+ result2 = advisor.refine(
358
+ "The main export destinations are Japan and Mexico.",
359
+ focus_component="systems",
360
+ )
361
+ print(result2.formatted)
362
+ ```
363
+
364
+ ### Step 5: Visualize (optional)
365
+
366
+ ```python
367
+ # Or generate maps independently
368
+ from metacouplingllm import plot_focal_country_map, plot_focal_adm1_map
369
+
370
+ fig = plot_focal_country_map("USA")
371
+ fig.savefig("usa_coupling_map.png", dpi=150)
372
+
373
+ fig_wb = plot_focal_country_map(
374
+ "USA",
375
+ adm0_shapefile=r"C:\path\to\World Bank Official Boundaries - Admin 0_all_layers.gpkg",
376
+ )
377
+ fig_wb.savefig("usa_coupling_map_world_bank.png", dpi=150)
378
+
379
+ fig2 = plot_focal_adm1_map("USA023") # Michigan
380
+ fig2.savefig("michigan_adm1_map.png", dpi=150)
381
+ ```
382
+
383
+ If you do not pass `adm0_shapefile`, the package first looks for a local
384
+ `World Bank Official Boundaries - Admin 0_all_layers.gpkg`. If it cannot
385
+ find one, it auto-downloads the hosted `Admin 0_all_layers` mirror into
386
+ the cache on first use, then falls back to the official World Bank Admin 0
387
+ 10m basemap if needed.
388
+
389
+ Similarly, if you do not pass `adm1_shapefile`, ADM1 maps first look for a
390
+ local Admin 1 file and then auto-download the hosted `Admin 1.gpkg` mirror.
391
+
392
+ ### Step 6: Access Structured Data
393
+
394
+ ```python
395
+ # Structured access to parsed analysis
396
+ p = result.parsed
397
+ print(p.coupling_classification)
398
+ print(p.systems) # dict of sending/receiving/spillover
399
+ print(p.flows) # list of flow dicts
400
+ print(p.agents) # list of agent dicts
401
+ print(p.causes) # dict of cause categories
402
+ print(p.effects) # dict of effect categories
403
+ print(p.suggestions) # list of research gap strings
404
+ ```
405
+
406
+ ---
407
+
408
+ ## 6. Bundled Data
409
+
410
+ | Resource | Description |
411
+ |---|---|
412
+ | 262 full-text papers (Papers.zip) | Markdown versions of telecoupling/metacoupling research papers for RAG |
413
+ | BibTeX database (telecoupling_literature.bib) | 262 curated entries with metadata for literature recommendation |
414
+ | Country pericoupling database (CSV) | Global country-pair adjacency classification |
415
+ | ADM1 edge list (CSV) | 8,290 subnational border pairs across 3,366 regions in 195 countries |
416
+ | Framework examples | Curated case studies (soybean trade, urban water) for prompt injection |
417
+
418
+ ---
419
+
420
+ ## 7. Design Principles
421
+
422
+ - **Lean dependencies** -- Core analysis works with only `numpy`, `fastembed`, and an LLM client; visualization and web search are optional extras
423
+ - **Graceful degradation** -- Each optional feature (RAG, web search, maps, literature) can be independently enabled or disabled; RAG transparently falls back from embeddings to TF-IDF when `fastembed` is unavailable
424
+ - **Protocol-based extensibility** -- Any object with a `chat()` method works as an LLM client
425
+ - **Pre-LLM knowledge injection** -- Pericoupling validation, web search, and example selection all happen before the LLM call, reducing hallucination
426
+ - **Semantic RAG** -- Pre-computed BGE-small embeddings shipped with the package; semantic matching catches synonyms and paraphrases that TF-IDF misses. TF-IDF remains available as a fallback.
427
+ - **Colab-compatible** -- Web search includes a zero-dependency stdlib fallback for restricted environments
428
+
429
+ ---
430
+
431
+ ## 8. Testing
432
+
433
+ The package includes a comprehensive test suite:
434
+
435
+ ```bash
436
+ pip install metacoupling[dev]
437
+ pytest tests/
438
+ ```
439
+
440
+ 429 tests covering all modules: core advisor logic, framework enums, prompt construction, LLM parsing, RAG retrieval, literature matching, web search (including stdlib fallback), pericoupling databases, country resolution, visualization colors, and map generation.
@@ -0,0 +1,35 @@
1
+ metacouplingllm/__init__.py,sha256=byjCqkr74qpOsEYbxbSnA4vUh6MvhYnOJSMsIo8k9e0,5417
2
+ metacouplingllm/core.py,sha256=FDjt4reSHimx_hUkJp9udJyqup-wKzrWEkzmaT5gHsU,189186
3
+ metacouplingllm/data/Papers.zip,sha256=ZMFZf51Pi39hU5dKFT2JRt2RI56mpVgyuuvIHMMMT9Q,4443486
4
+ metacouplingllm/data/PeriTelecoupling_clean.csv,sha256=1JjqkTIQ2lWKgIYrhFwC6AaY6rab7KIpkze2fXuzlOA,549508
5
+ metacouplingllm/data/PeriTelecoupling_subset.csv,sha256=haQIBaw9EaAgEo-AXyVuSE8LU8ZQT9oJjCnTns_oBK0,132
6
+ metacouplingllm/data/chunk_embeddings.manifest.json,sha256=WoRWAcAKEzdi1mqDo3lx-rmGnX014uIK3uNxlxaoDpM,381
7
+ metacouplingllm/data/chunk_embeddings.npy,sha256=rocjHcpVQos8imw-wPDlt1kaMbiDJvcsH8Qx23v5wC4,15409280
8
+ metacouplingllm/data/pericoupled_adm1_edge_list.csv,sha256=c9iMPMKqHJSvU_onmUssdINY9E5HztUoLUazYRvaEAQ,834086
9
+ metacouplingllm/data/telecoupling_literature.bib,sha256=Uk_WePCd0GEDJTXz0Hv1FEyLJX47ErOiPrUXB21iNU8,151933
10
+ metacouplingllm/knowledge/__init__.py,sha256=jl0z3wDw65ZWj65O447lsTiP_etSbIBLuo47aF8l0_8,73
11
+ metacouplingllm/knowledge/adm1_pericoupling.py,sha256=YV7rCYYEq466twJYpdQ3nLomNrWRM-LLhbcS4Mmx9jg,17138
12
+ metacouplingllm/knowledge/citations.py,sha256=DbcUzwSDIlFDqYo1YRAZM2NououeF-Jh3Ww3PaTuAkU,4027
13
+ metacouplingllm/knowledge/countries.py,sha256=6Ra2-B6mE7tSwXELnIJ-stClFiKB8g2tTsK8RX8h6YU,14764
14
+ metacouplingllm/knowledge/examples.py,sha256=gLx4jPLoFdF93WT3PJm10sM1xpr1zPQtLFuXLyk5A4g,39802
15
+ metacouplingllm/knowledge/framework.py,sha256=YbZOKfbbW2sJQq3HBTLTtUBaViBJBGmGRHRvSl0-6cQ,32527
16
+ metacouplingllm/knowledge/literature.py,sha256=uJVXiGQLofYAq4a4GvYpZ4RGtxjzhXO5tWWO1QMYIxQ,16373
17
+ metacouplingllm/knowledge/pericoupling.py,sha256=92dzi4wcul2HfgZm9M0_Yw-WFu0ceK4iAg0cvV2WvOI,7216
18
+ metacouplingllm/knowledge/rag.py,sha256=agR1tyAKZJhy91cTc_dwt6cbqSy9YOhK29eMVO7jHps,64775
19
+ metacouplingllm/knowledge/references.py,sha256=ruytkceRJjbsAN14R7obzQqV7wT4bj9xQ6BstBhJs1s,4507
20
+ metacouplingllm/knowledge/websearch.py,sha256=1a39sFrHpty8ZzWb4O3Be4ok-sfn-3SmZg2p5Efe_xk,64651
21
+ metacouplingllm/llm/__init__.py,sha256=A7epRmSePUrsSOQ9_15k06Ydh5bOy8SceposUEU3wOo,51
22
+ metacouplingllm/llm/client.py,sha256=lWZHOH365E_DHHzVLbWCteTsM-GnfyThCNN89ZvJz5Q,22890
23
+ metacouplingllm/llm/parser.py,sha256=1xfKDSY6Ncjbkz9Im6rigpu8_gTFcGXQ3VcE83s3Jbc,32083
24
+ metacouplingllm/output/__init__.py,sha256=hmAsnhxiWhcO0MOu_kGzS8V9SK3if5Xbxldtc8jjOWU,46
25
+ metacouplingllm/output/formatter.py,sha256=fI4Q3Po_6FZ6BQS4kqcpGwa1Lw9A57gfwIDHBj9O0ko,10778
26
+ metacouplingllm/prompts/__init__.py,sha256=rC3l3QkoV7vLbmtBnyB2svlde4K4OouElvEMdvhOiNI,70
27
+ metacouplingllm/prompts/builder.py,sha256=BmewR-HxtlDIFL-VAc-4f0zuvmlbGUGDqQkViDHIIJw,18243
28
+ metacouplingllm/prompts/templates.py,sha256=ftn-OzhRTg1OTk12GMFGXFfIJ_PUTAakAn5bgan4ZwU,25715
29
+ metacouplingllm/visualization/__init__.py,sha256=xFbZQLS_Mk0IFh_onYyB41-0NCMDckiZG7KmsPaWHo4,3252
30
+ metacouplingllm/visualization/adm1_map.py,sha256=w-AhpGYujTsmCBTFEvWYcf7X3G8wEX3YqJRGpE9lgOk,30871
31
+ metacouplingllm/visualization/worldmap.py,sha256=NpXyT09r4LV-paxhrJOrSOJfGtNa_JVh6wgO2q2GLwI,46127
32
+ metacouplingllm-0.1.0.dist-info/METADATA,sha256=pSSVATUJVo5s-XKerHRoO3fBBS8UD532uFLTQIFkgQo,19834
33
+ metacouplingllm-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
34
+ metacouplingllm-0.1.0.dist-info/licenses/LICENSE,sha256=hY3s7g2JUt-NV_-OOYjL8V4Eg4z5Syfoa3BtAxp3Uys,1082
35
+ metacouplingllm-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.29.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Metacoupling Contributors
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.