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,717 @@
1
+ """
2
+ Framework definitions for the metacoupling and telecoupling frameworks.
3
+
4
+ Contains enums, component definitions, and telecoupling categories derived
5
+ from Liu et al. (2013), Liu (2017), Liu (2023), and related literature.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from dataclasses import dataclass, field
11
+ from enum import Enum
12
+
13
+
14
+ # ---------------------------------------------------------------------------
15
+ # Enums
16
+ # ---------------------------------------------------------------------------
17
+
18
+ class CouplingType(str, Enum):
19
+ """Types of coupling in the metacoupling framework (Liu, 2017)."""
20
+
21
+ INTRACOUPLING = "intracoupling"
22
+ PERICOUPLING = "pericoupling"
23
+ TELECOUPLING = "telecoupling"
24
+
25
+ @property
26
+ def description(self) -> str:
27
+ return _COUPLING_DESCRIPTIONS[self]
28
+
29
+
30
+ _COUPLING_DESCRIPTIONS: dict[CouplingType, str] = {
31
+ CouplingType.INTRACOUPLING: (
32
+ "Human-nature interactions within a coupled human and natural system "
33
+ "(Liu, 2017). The intracoupling framework focuses on interactions "
34
+ "between human and nature subsystems within one focal system, through "
35
+ "flows facilitated by agents, generated by causes, and leading to "
36
+ "effects within both the focal system and any spillover systems."
37
+ ),
38
+ CouplingType.PERICOUPLING: (
39
+ "Human-nature interactions between adjacent coupled human and natural "
40
+ "systems (Liu, 2017). The pericoupling framework has the same "
41
+ "structure as the telecoupling framework (systems, flows, agents, "
42
+ "causes, effects) except that sending and receiving systems are "
43
+ "nearby rather than far away. For example, flows of labor and "
44
+ "materials between neighboring counties or nations."
45
+ ),
46
+ CouplingType.TELECOUPLING: (
47
+ "Human-nature interactions between distant coupled human and natural "
48
+ "systems (Liu et al., 2013). Telecoupling involves sending, receiving, "
49
+ "and spillover systems connected by flows of information, energy, "
50
+ "material, people, organisms, and capital across large geographic "
51
+ "distances. Research shows that in many cases, telecouplings are "
52
+ "stronger than pericouplings, challenging Tobler's First Law of "
53
+ "Geography (Liu, 2023)."
54
+ ),
55
+ }
56
+
57
+
58
+ class SystemRole(str, Enum):
59
+ """Roles that a coupled human and natural system can play."""
60
+
61
+ SENDING = "sending"
62
+ RECEIVING = "receiving"
63
+ SPILLOVER = "spillover"
64
+
65
+ @property
66
+ def description(self) -> str:
67
+ return _SYSTEM_ROLE_DESCRIPTIONS[self]
68
+
69
+
70
+ _SYSTEM_ROLE_DESCRIPTIONS: dict[SystemRole, str] = {
71
+ SystemRole.SENDING: (
72
+ "A system that sends information, energy, material, people, "
73
+ "organisms, and capital to other system(s). In intracoupling, "
74
+ "the concept of sending system is not applicable — only the "
75
+ "focal system is of interest (Liu, 2017, Table 1)."
76
+ ),
77
+ SystemRole.RECEIVING: (
78
+ "A system that receives information, energy, material, people, "
79
+ "organisms, and capital from sending system(s). In pericoupling, "
80
+ "receiving systems are adjacent to sending systems; in telecoupling, "
81
+ "they are distant (Liu, 2017, Table 1)."
82
+ ),
83
+ SystemRole.SPILLOVER: (
84
+ "A system that is affected by or affects interactions between sending "
85
+ "and receiving systems, even though it is not a direct participant. "
86
+ "Spillover effects can be much larger than effects between sending "
87
+ "and receiving systems (Liu, 2023). Spillover systems exist in all "
88
+ "three coupling types and are often traditionally overlooked."
89
+ ),
90
+ }
91
+
92
+
93
+ class FlowCategory(str, Enum):
94
+ """Categories of flows between coupled systems (Liu, 2017, Table 1)."""
95
+
96
+ CAPITAL = "capital"
97
+ ENERGY = "energy"
98
+ INFORMATION = "information"
99
+ MATTER = "matter"
100
+ ORGANISMS = "organisms"
101
+ PEOPLE = "people"
102
+
103
+ @property
104
+ def description(self) -> str:
105
+ return _FLOW_DESCRIPTIONS[self]
106
+
107
+
108
+ _FLOW_DESCRIPTIONS: dict[FlowCategory, str] = {
109
+ FlowCategory.CAPITAL: (
110
+ "Flows of money, investment, aid, financial resources, or economic "
111
+ "value between systems (e.g., foreign direct investment, conservation "
112
+ "funding, remittances, payments for ecosystem services, trade revenue)."
113
+ ),
114
+ FlowCategory.ENERGY: (
115
+ "Flows of energy resources or energy embodied in traded goods "
116
+ "between systems (e.g., electricity trade, embodied energy in "
117
+ "exports, fossil fuel transfers)."
118
+ ),
119
+ FlowCategory.INFORMATION: (
120
+ "Flows of knowledge, data, technology, ideas, and cultural "
121
+ "practices between systems (e.g., technology transfer, scientific "
122
+ "knowledge exchange, media, market signals)."
123
+ ),
124
+ FlowCategory.MATTER: (
125
+ "Flows of physical goods, commodities, natural resources, water, "
126
+ "waste, and other material substances between systems (e.g., "
127
+ "soybean trade, water transfer, e-waste shipments, dust transport)."
128
+ ),
129
+ FlowCategory.ORGANISMS: (
130
+ "Flows of living organisms between systems, including both "
131
+ "intentional transfers and natural movements (e.g., species "
132
+ "invasion, seed dispersal, animal migration, livestock trade, "
133
+ "pathogen spread)."
134
+ ),
135
+ FlowCategory.PEOPLE: (
136
+ "Flows of people between systems for economic, political, "
137
+ "environmental, or recreational reasons (e.g., migration, "
138
+ "tourism, labor movement, refugees)."
139
+ ),
140
+ }
141
+
142
+
143
+ class AgentLevel(str, Enum):
144
+ """Fixed agent categories used by MetacouplingAssistant."""
145
+
146
+ INDIVIDUALS_HOUSEHOLDS = "individuals / households"
147
+ FIRMS_TRADERS_CORPORATIONS = "firms / traders / corporations"
148
+ GOVERNMENTS_POLICYMAKERS = "governments / policymakers"
149
+ ORGANIZATIONS_NGOS = "organizations / NGOs"
150
+ NON_HUMAN_AGENTS = "non-human agents"
151
+ # Backward-compatible enum aliases; iteration still yields only the
152
+ # fixed categories above.
153
+ INDIVIDUAL = "individuals / households"
154
+ HOUSEHOLD = "individuals / households"
155
+ COMPANY = "firms / traders / corporations"
156
+ ORGANIZATION = "organizations / NGOs"
157
+ GOVERNMENT = "governments / policymakers"
158
+
159
+ @property
160
+ def description(self) -> str:
161
+ return _AGENT_LEVEL_DESCRIPTIONS[self]
162
+
163
+
164
+ _AGENT_LEVEL_DESCRIPTIONS: dict[AgentLevel, str] = {
165
+ AgentLevel.INDIVIDUALS_HOUSEHOLDS: (
166
+ "Individual people and household units that make decisions affecting "
167
+ "coupling processes, such as farmers, consumers, tourists, migrants, "
168
+ "fishers, local residents, and farming households."
169
+ ),
170
+ AgentLevel.FIRMS_TRADERS_CORPORATIONS: (
171
+ "Private-sector actors that produce, trade, finance, transport, or "
172
+ "market flows, including firms, traders, corporations, processors, "
173
+ "exporters, importers, logistics companies, and tourism operators."
174
+ ),
175
+ AgentLevel.GOVERNMENTS_POLICYMAKERS: (
176
+ "Government agencies, elected officials, regulators, and policymakers "
177
+ "that shape coupling processes through policy, planning, enforcement, "
178
+ "diplomacy, public investment, and institutional authority."
179
+ ),
180
+ AgentLevel.ORGANIZATIONS_NGOS: (
181
+ "Non-governmental, civil-society, research, nonprofit, and "
182
+ "intergovernmental organizations, including NGOs, universities, "
183
+ "certification bodies, community organizations, and international bodies."
184
+ ),
185
+ AgentLevel.NON_HUMAN_AGENTS: (
186
+ "Non-human entities that actively mediate or drive coupling dynamics, "
187
+ "such as migratory animals, invasive species, pathogens, pests, crops, "
188
+ "livestock, or other organisms when they function as agents rather "
189
+ "than only as flows or affected components."
190
+ ),
191
+ }
192
+
193
+
194
+ class CauseCategory(str, Enum):
195
+ """Fixed cause categories used by MetacouplingAssistant."""
196
+
197
+ ECONOMIC = "economic"
198
+ POLITICAL_INSTITUTIONAL = "political / institutional"
199
+ ECOLOGICAL_BIOLOGICAL = "ecological / biological"
200
+ TECHNOLOGICAL_INFRASTRUCTURAL = "technological / infrastructural"
201
+ CULTURAL_SOCIAL_DEMOGRAPHIC = "cultural / social / demographic"
202
+ HYDROLOGICAL = "hydrological"
203
+ CLIMATIC_ATMOSPHERIC = "climatic / atmospheric"
204
+ GEOLOGICAL_GEOMORPHOLOGICAL = "geological / geomorphological"
205
+ # Backward-compatible enum aliases; iteration still yields only the
206
+ # fixed categories above.
207
+ SOCIOECONOMIC = "economic"
208
+ POLITICAL = "political / institutional"
209
+ ECOLOGICAL = "ecological / biological"
210
+ CULTURAL = "cultural / social / demographic"
211
+ GEOLOGICAL = "geological / geomorphological"
212
+
213
+ @property
214
+ def description(self) -> str:
215
+ return _CAUSE_EFFECT_CATEGORY_DESCRIPTIONS[self.value]
216
+
217
+
218
+ class EffectCategory(str, Enum):
219
+ """Fixed effect categories used by MetacouplingAssistant."""
220
+
221
+ ECONOMIC = "economic"
222
+ POLITICAL_INSTITUTIONAL = "political / institutional"
223
+ ECOLOGICAL_BIOLOGICAL = "ecological / biological"
224
+ TECHNOLOGICAL_INFRASTRUCTURAL = "technological / infrastructural"
225
+ CULTURAL_SOCIAL_DEMOGRAPHIC = "cultural / social / demographic"
226
+ HYDROLOGICAL = "hydrological"
227
+ CLIMATIC_ATMOSPHERIC = "climatic / atmospheric"
228
+ GEOLOGICAL_GEOMORPHOLOGICAL = "geological / geomorphological"
229
+ # Backward-compatible enum aliases; iteration still yields only the
230
+ # fixed categories above.
231
+ SOCIOECONOMIC = "economic"
232
+ POLITICAL = "political / institutional"
233
+ ECOLOGICAL = "ecological / biological"
234
+ BIOLOGICAL = "ecological / biological"
235
+ BIOGEOCHEMICAL = "climatic / atmospheric"
236
+ CULTURAL = "cultural / social / demographic"
237
+ GEOLOGICAL = "geological / geomorphological"
238
+
239
+ @property
240
+ def description(self) -> str:
241
+ return _CAUSE_EFFECT_CATEGORY_DESCRIPTIONS[self.value]
242
+
243
+
244
+ _CAUSE_EFFECT_CATEGORY_DESCRIPTIONS: dict[str, str] = {
245
+ "economic": (
246
+ "Economic drivers or outcomes, including markets, prices, income, "
247
+ "employment, livelihoods, trade revenue, investment, costs, poverty, "
248
+ "inequality, and sectoral growth."
249
+ ),
250
+ "political / institutional": (
251
+ "Political and institutional drivers or outcomes, including policies, "
252
+ "regulations, governance, institutions, enforcement, diplomacy, "
253
+ "property rights, subsidies, agreements, and planning decisions."
254
+ ),
255
+ "ecological / biological": (
256
+ "Ecological and biological drivers or outcomes, including ecosystem "
257
+ "processes, biodiversity, habitat change, species distributions, "
258
+ "invasive species, pests, pathogens, and ecosystem services."
259
+ ),
260
+ "technological / infrastructural": (
261
+ "Technological and infrastructural drivers or outcomes, including "
262
+ "innovation, production technologies, roads, ports, dams, logistics, "
263
+ "processing facilities, monitoring systems, and technical capacity."
264
+ ),
265
+ "cultural / social / demographic": (
266
+ "Cultural, social, and demographic drivers or outcomes, including "
267
+ "values, traditions, social norms, diets, migration, population "
268
+ "change, consumption preferences, public health, and well-being."
269
+ ),
270
+ "hydrological": (
271
+ "Water-related drivers or outcomes, including water availability, "
272
+ "water quality, runoff, watershed dynamics, groundwater, drought, "
273
+ "flooding, irrigation, and river-flow alteration."
274
+ ),
275
+ "climatic / atmospheric": (
276
+ "Climate and atmosphere-related drivers or outcomes, including "
277
+ "temperature, precipitation, drought risk, greenhouse gas emissions, "
278
+ "air pollution, atmospheric transport, wind, and climate change."
279
+ ),
280
+ "geological / geomorphological": (
281
+ "Geological and geomorphological drivers or outcomes, including "
282
+ "soils, terrain, erosion, sedimentation, mineral deposits, tectonic "
283
+ "activity, landslides, and landform change."
284
+ ),
285
+ }
286
+
287
+
288
+ class FrameworkComponent(str, Enum):
289
+ """The five major components of the telecoupling framework."""
290
+
291
+ SYSTEMS = "systems"
292
+ FLOWS = "flows"
293
+ AGENTS = "agents"
294
+ CAUSES = "causes"
295
+ EFFECTS = "effects"
296
+
297
+
298
+ # ---------------------------------------------------------------------------
299
+ # Component Definitions
300
+ # ---------------------------------------------------------------------------
301
+
302
+ @dataclass(frozen=True)
303
+ class ComponentDefinition:
304
+ """Definition of a framework component with guiding questions."""
305
+
306
+ name: str
307
+ description: str
308
+ sub_elements: list[str] = field(default_factory=list)
309
+ guiding_questions: list[str] = field(default_factory=list)
310
+
311
+
312
+ COMPONENT_DEFINITIONS: dict[FrameworkComponent, ComponentDefinition] = {
313
+ FrameworkComponent.SYSTEMS: ComponentDefinition(
314
+ name="Systems",
315
+ description=(
316
+ "Coupled human and natural systems involved in the interaction. "
317
+ "Each system contains both a human (socioeconomic) subsystem and "
318
+ "a natural (environmental/ecological) subsystem that interact with "
319
+ "each other. Systems are classified by their role: sending, receiving, "
320
+ "or spillover."
321
+ ),
322
+ sub_elements=[
323
+ "Sending system(s) — origin of flows",
324
+ "Receiving system(s) — destination of flows",
325
+ "Spillover system(s) — indirectly affected systems",
326
+ "Human subsystem within each system (governance, economy, society)",
327
+ "Natural subsystem within each system (ecosystems, biodiversity, climate)",
328
+ ],
329
+ guiding_questions=[
330
+ "What are the coupled human and natural systems involved?",
331
+ "Which system(s) send flows and which receive them?",
332
+ "Are there spillover systems affected indirectly?",
333
+ "What are the human and natural subsystems within each system?",
334
+ "Can system roles change over time or be bidirectional?",
335
+ ],
336
+ ),
337
+ FrameworkComponent.FLOWS: ComponentDefinition(
338
+ name="Flows",
339
+ description=(
340
+ "Movements of matter, energy, information, capital, organisms, "
341
+ "or people between systems (Liu, 2017, Table 1). Flows are what "
342
+ "connect the coupled systems and can be unidirectional or "
343
+ "bidirectional."
344
+ ),
345
+ sub_elements=[
346
+ "Capital flows (investment, aid, payments, remittances, trade revenue)",
347
+ "Energy flows (electricity, embodied energy, fossil fuels)",
348
+ "Information flows (knowledge, technology, data, cultural practices)",
349
+ "Matter flows (goods, commodities, water, waste, natural resources)",
350
+ "Organism flows (species invasion, seed dispersal, animal migration)",
351
+ "People flows (migration, tourism, labor movement, refugees)",
352
+ ],
353
+ guiding_questions=[
354
+ "What is being transferred between systems?",
355
+ "What categories do the flows belong to (capital, energy, information, "
356
+ "matter, organisms, people)?",
357
+ "What is the direction and magnitude of each flow?",
358
+ "Are flows unidirectional or bidirectional?",
359
+ "How have flows changed over time?",
360
+ ],
361
+ ),
362
+ FrameworkComponent.AGENTS: ComponentDefinition(
363
+ name="Agents",
364
+ description=(
365
+ "Autonomous decision-making entities that directly or indirectly "
366
+ "facilitate or hinder coupling processes. Agents are grouped "
367
+ "into five fixed categories: individuals / households; firms / "
368
+ "traders / corporations; governments / policymakers; "
369
+ "organizations / NGOs; and non-human agents."
370
+ ),
371
+ sub_elements=[
372
+ "Individuals / households (farmers, consumers, tourists, migrants, fishers, local residents)",
373
+ "Firms / traders / corporations (agribusinesses, exporters, importers, logistics companies)",
374
+ "Governments / policymakers (public agencies, regulators, elected officials, planning bodies)",
375
+ "Organizations / NGOs (NGOs, universities, certification bodies, international organizations)",
376
+ "Non-human agents (migratory animals, invasive species, pathogens, pests, crops, livestock)",
377
+ "Agents in sending systems",
378
+ "Agents in receiving systems",
379
+ "Agents facilitating the coupling (brokers, intermediaries)",
380
+ ],
381
+ guiding_questions=[
382
+ "Who or what drives the interactions between systems?",
383
+ "What agents exist in the sending, receiving, and spillover systems?",
384
+ "Which fixed agent category does each agent belong to?",
385
+ "What are the agents' motivations and decision-making processes?",
386
+ "How do different agent categories interact?",
387
+ "Are there intermediary agents facilitating the telecoupling?",
388
+ "Are any non-human entities active agents rather than only flows or affected resources?",
389
+ ],
390
+ ),
391
+ FrameworkComponent.CAUSES: ComponentDefinition(
392
+ name="Causes",
393
+ description=(
394
+ "Factors that drive coupling processes, grouped into the fixed "
395
+ "MetacouplingAssistant cause/effect categories."
396
+ ),
397
+ sub_elements=[
398
+ "Economic causes (markets, prices, demand, investment, costs)",
399
+ "Political / institutional causes (policies, governance, regulation, institutions)",
400
+ "Ecological / biological causes (ecosystem processes, species, habitat, pests)",
401
+ "Technological / infrastructural causes (technology, roads, ports, logistics, dams)",
402
+ "Cultural / social / demographic causes (values, diets, migration, population change)",
403
+ "Hydrological causes (water availability, water quality, drought, flooding)",
404
+ "Climatic / atmospheric causes (climate variability, emissions, air transport)",
405
+ "Geological / geomorphological causes (soils, terrain, erosion, deposits)",
406
+ ],
407
+ guiding_questions=[
408
+ "What economic forces drive the coupling?",
409
+ "What political or institutional conditions drive the coupling?",
410
+ "What ecological or biological processes contribute to the interaction?",
411
+ "What technological or infrastructural factors enable or constrain it?",
412
+ "What cultural, social, or demographic factors are involved?",
413
+ "What hydrological conditions play a role?",
414
+ "What climatic or atmospheric conditions play a role?",
415
+ "What geological or geomorphological conditions are involved?",
416
+ "How do causes differ between sending and receiving systems?",
417
+ "Are there external/global causes (e.g., international policy, climate change)?",
418
+ ],
419
+ ),
420
+ FrameworkComponent.EFFECTS: ComponentDefinition(
421
+ name="Effects",
422
+ description=(
423
+ "Consequences and outcomes of coupling processes on coupled "
424
+ "human and natural systems, grouped into the fixed "
425
+ "MetacouplingAssistant cause/effect categories. Effects can be "
426
+ "positive, negative, or mixed for each system."
427
+ ),
428
+ sub_elements=[
429
+ "Economic effects (income, employment, costs, market shifts)",
430
+ "Political / institutional effects (governance, regulation, enforcement)",
431
+ "Ecological / biological effects (biodiversity, habitat, species, ecosystem services)",
432
+ "Technological / infrastructural effects (infrastructure, innovation, logistics)",
433
+ "Cultural / social / demographic effects (well-being, migration, equity, norms)",
434
+ "Hydrological effects (water quantity, quality, runoff, watershed change)",
435
+ "Climatic / atmospheric effects (GHG emissions, air pollution, climate feedbacks)",
436
+ "Geological / geomorphological effects (soil change, erosion, sedimentation)",
437
+ "Synergies and tradeoffs between effects",
438
+ "Feedback effects (how effects alter causes or flows)",
439
+ ],
440
+ guiding_questions=[
441
+ "Which fixed effect categories are relevant for each system?",
442
+ "Are effects positive, negative, or mixed for each system?",
443
+ "How do effects on sending vs. receiving systems compare?",
444
+ "What spillover effects occur on third-party systems?",
445
+ "Are there feedback loops where effects alter causes or flows?",
446
+ "What synergies or tradeoffs exist among the effects?",
447
+ ],
448
+ ),
449
+ }
450
+
451
+
452
+ # ---------------------------------------------------------------------------
453
+ # Telecoupling Categories
454
+ # ---------------------------------------------------------------------------
455
+
456
+ @dataclass(frozen=True)
457
+ class TelecouplingCategory:
458
+ """A recognized category of telecoupling from Liu et al. (2013)."""
459
+
460
+ name: str
461
+ description: str
462
+ example: str
463
+ keywords: list[str] = field(default_factory=list)
464
+
465
+
466
+ TELECOUPLING_CATEGORIES: list[TelecouplingCategory] = [
467
+ TelecouplingCategory(
468
+ name="Trade",
469
+ description=(
470
+ "International or long-distance exchange of goods and commodities "
471
+ "that connects distant production and consumption systems."
472
+ ),
473
+ example="Brazil-to-China soybean trade driving deforestation and land-use change",
474
+ keywords=["trade", "export", "import", "commodity", "market", "commerce"],
475
+ ),
476
+ TelecouplingCategory(
477
+ name="Development investment",
478
+ description=(
479
+ "Foreign direct investment and development projects that connect "
480
+ "investor and host country systems."
481
+ ),
482
+ example="Chinese investment in African agricultural and mining projects",
483
+ keywords=["investment", "development", "FDI", "foreign", "economic"],
484
+ ),
485
+ TelecouplingCategory(
486
+ name="Transnational land transfer",
487
+ description=(
488
+ "Large-scale acquisition or lease of land in one country by "
489
+ "entities from another country (land grabbing)."
490
+ ),
491
+ example="Saudi Arabia leasing farmland in Ethiopia for food production",
492
+ keywords=["land", "acquisition", "lease", "transnational", "grabbing"],
493
+ ),
494
+ TelecouplingCategory(
495
+ name="Conservation investment",
496
+ description=(
497
+ "Financial and institutional flows for biodiversity conservation "
498
+ "and environmental protection across distant systems."
499
+ ),
500
+ example="International funding for tropical rainforest conservation",
501
+ keywords=["conservation", "protected", "biodiversity", "funding", "PES",
502
+ "ecosystem services", "wildlife"],
503
+ ),
504
+ TelecouplingCategory(
505
+ name="Technology transfer",
506
+ description=(
507
+ "Movement of technology, equipment, and technical capacity between "
508
+ "distant systems."
509
+ ),
510
+ example="Transfer of renewable energy technology from developed to developing nations",
511
+ keywords=["technology", "innovation", "transfer", "technical", "equipment"],
512
+ ),
513
+ TelecouplingCategory(
514
+ name="Knowledge transfer",
515
+ description=(
516
+ "Exchange of scientific knowledge, educational resources, and "
517
+ "expertise between distant systems."
518
+ ),
519
+ example="International research collaborations on climate change adaptation",
520
+ keywords=["knowledge", "research", "education", "science", "academic",
521
+ "collaboration"],
522
+ ),
523
+ TelecouplingCategory(
524
+ name="Human migration",
525
+ description=(
526
+ "Movement of people between distant systems for economic, "
527
+ "political, or environmental reasons."
528
+ ),
529
+ example="Rural-to-urban migration from agricultural regions to industrial cities",
530
+ keywords=["migration", "refugee", "immigration", "emigration", "diaspora",
531
+ "labor", "displacement"],
532
+ ),
533
+ TelecouplingCategory(
534
+ name="Tourism",
535
+ description=(
536
+ "Travel of people between distant systems for recreation, "
537
+ "creating socioeconomic and environmental impacts in both "
538
+ "origin and destination systems."
539
+ ),
540
+ example="International ecotourism to panda reserves in China",
541
+ keywords=["tourism", "travel", "ecotourism", "visitor", "recreation"],
542
+ ),
543
+ TelecouplingCategory(
544
+ name="Waste transfer",
545
+ description=(
546
+ "Movement of waste, pollutants, or discarded materials between "
547
+ "distant systems."
548
+ ),
549
+ example="International e-waste shipments from developed to developing countries",
550
+ keywords=["waste", "pollution", "e-waste", "garbage", "disposal", "toxic"],
551
+ ),
552
+ TelecouplingCategory(
553
+ name="Species invasion",
554
+ description=(
555
+ "Introduction and spread of non-native species between distant "
556
+ "systems, often facilitated by trade or transport."
557
+ ),
558
+ example="Red imported fire ant invasion from USA to China via shipping containers",
559
+ keywords=["invasive", "species", "invasion", "non-native", "alien", "pest",
560
+ "biological"],
561
+ ),
562
+ TelecouplingCategory(
563
+ name="Animal migration",
564
+ description=(
565
+ "Natural seasonal or life-cycle movement of animal species "
566
+ "between distant systems."
567
+ ),
568
+ example="Migratory bird flyways connecting breeding and wintering habitats",
569
+ keywords=["migration", "migratory", "bird", "flyway", "seasonal", "wildlife"],
570
+ ),
571
+ TelecouplingCategory(
572
+ name="Water transfer",
573
+ description=(
574
+ "Engineered or natural movement of water resources between "
575
+ "distant systems, including inter-basin transfers and virtual water."
576
+ ),
577
+ example="South-to-North Water Transfer Project in China supplying Beijing",
578
+ keywords=["water", "transfer", "irrigation", "dam", "basin", "virtual water",
579
+ "hydrological"],
580
+ ),
581
+ TelecouplingCategory(
582
+ name="Species dispersal",
583
+ description=(
584
+ "Natural spread and distribution of species between distant "
585
+ "systems through ecological processes."
586
+ ),
587
+ example="Seed dispersal by migratory animals connecting forest ecosystems",
588
+ keywords=["dispersal", "spread", "seed", "propagule", "colonization",
589
+ "distribution"],
590
+ ),
591
+ TelecouplingCategory(
592
+ name="Atmospheric circulation",
593
+ description=(
594
+ "Large-scale movement of atmospheric components (dust, pollutants, "
595
+ "moisture) between distant systems."
596
+ ),
597
+ example="Saharan dust transport to the Amazon Basin fertilizing soils",
598
+ keywords=["atmospheric", "air", "dust", "pollution", "climate", "wind",
599
+ "aerosol", "carbon"],
600
+ ),
601
+ ]
602
+
603
+
604
+ # ---------------------------------------------------------------------------
605
+ # Knowledge Formatter
606
+ # ---------------------------------------------------------------------------
607
+
608
+ def get_framework_knowledge() -> str:
609
+ """Return a formatted string of all framework knowledge for prompt injection.
610
+
611
+ This produces a comprehensive text block covering:
612
+ - Metacoupling framework overview (intracoupling, pericoupling, telecoupling)
613
+ - The five components with definitions and guiding questions
614
+ - The 14 telecoupling categories with examples
615
+ """
616
+ sections: list[str] = []
617
+
618
+ # --- Metacoupling overview ---
619
+ sections.append("## METACOUPLING FRAMEWORK OVERVIEW\n")
620
+ sections.append(
621
+ "The metacoupling framework (Liu, 2017) is an integrated framework for "
622
+ "understanding human-nature interactions across all spatial scales. It "
623
+ "encompasses three types of couplings:\n"
624
+ )
625
+ for ct in CouplingType:
626
+ sections.append(f"- **{ct.value.title()}**: {ct.description}\n")
627
+ sections.append(
628
+ "\nA coupled human and natural system (CHANS) contains interconnected "
629
+ "human (socioeconomic) and natural (environmental/ecological) components "
630
+ "that interact with each other.\n"
631
+ )
632
+
633
+ # --- Five components ---
634
+ sections.append("\n## FIVE FRAMEWORK COMPONENTS\n")
635
+ sections.append(
636
+ "The telecoupling framework (Liu et al., 2013) identifies five "
637
+ "interrelated components for analyzing distant human-nature interactions:\n"
638
+ )
639
+ for comp, defn in COMPONENT_DEFINITIONS.items():
640
+ sections.append(f"\n### {defn.name}\n")
641
+ sections.append(f"{defn.description}\n")
642
+ sections.append("\nSub-elements:")
643
+ for sub in defn.sub_elements:
644
+ sections.append(f" - {sub}")
645
+ sections.append("\nGuiding questions:")
646
+ for q in defn.guiding_questions:
647
+ sections.append(f" - {q}")
648
+ sections.append("")
649
+
650
+ # --- 14 telecoupling categories ---
651
+ sections.append("\n## TELECOUPLING CATEGORIES\n")
652
+ sections.append(
653
+ "Liu et al. (2013) identified 14 major categories of telecoupling. "
654
+ "A single study may involve one or more of these categories:\n"
655
+ )
656
+ for i, cat in enumerate(TELECOUPLING_CATEGORIES, 1):
657
+ sections.append(f"{i}. **{cat.name}**: {cat.description}")
658
+ sections.append(f" Example: {cat.example}\n")
659
+
660
+ # --- Key insights from Liu (2017) and Liu (2023) ---
661
+ sections.append("\n## KEY ANALYTICAL INSIGHTS\n")
662
+
663
+ sections.append("### Operationalization Procedure (Liu, 2017)\n")
664
+ sections.append(
665
+ "Operationalizing the metacoupling framework involves six phases:\n"
666
+ " 1. Set research goals — formulate objectives, questions, hypotheses\n"
667
+ " 2. Define focal system(s) — determined by research goals and feasibility\n"
668
+ " 3. Review literature / conduct studies on flows, agents, causes, effects — "
669
+ "trace flows across space to determine system boundaries\n"
670
+ " 4. Finalize system boundaries — where flows start and end define boundaries; "
671
+ "entities affecting flows are agents; reasons for flows are causes\n"
672
+ " 5. Collect and analyze data — quantitative and qualitative\n"
673
+ " 6. Communicate results — publications, stakeholder engagement\n"
674
+ )
675
+
676
+ sections.append("### Coupling Transformations (Liu, 2023)\n")
677
+ sections.append(
678
+ "Systems can undergo four stages of transformation:\n"
679
+ " - Noncoupling: no human-nature interactions within or between systems\n"
680
+ " - Coupling: interactions emerge among components\n"
681
+ " - Decoupling: interactions weaken or dissolve (e.g., due to shocks "
682
+ "like economic recession, pandemic, or war)\n"
683
+ " - Recoupling: weakened or dissolved interactions are recovered\n"
684
+ "These stages can occur in intracoupling, pericoupling, and telecoupling "
685
+ "simultaneously or separately.\n"
686
+ )
687
+
688
+ sections.append("### Complex Interactions Among Coupling Types (Liu, 2023)\n")
689
+ sections.append(
690
+ " - Intracoupling, pericoupling, and telecoupling can have synergistic effects\n"
691
+ " - Pericoupling and telecoupling can amplify intracoupling\n"
692
+ " - Increases in one type of coupling may reduce other types\n"
693
+ " - One type of coupling may generate benefits on one scale at the cost "
694
+ "of other scales (spatial tradeoffs)\n"
695
+ " - Telecoupling, pericoupling, and intracoupling can interact indirectly\n"
696
+ " - Feedbacks (positive or negative) are common and may take time to emerge\n"
697
+ )
698
+
699
+ sections.append("### Cascading Interactions (Liu, 2023)\n")
700
+ sections.append(
701
+ "An event in one place can cascade and spread impacts on other places "
702
+ "both nearby and far away through multiple steps. For example, drought in "
703
+ "the US Midwest reduced soybean production, potentially increasing global "
704
+ "soybean prices, which could encourage deforestation in Brazil for expanded "
705
+ "soybean cultivation.\n"
706
+ )
707
+
708
+ sections.append("### Flow-Based Governance (Liu, 2023)\n")
709
+ sections.append(
710
+ "The framework supports shifting from place-based governance (focus on "
711
+ "specific places independently) to flow-based governance (focus on movements "
712
+ "of people, information, energy, matter, organisms, goods, capital among "
713
+ "places). This shift can enhance global sustainability and improve spatial "
714
+ "justice and equity.\n"
715
+ )
716
+
717
+ return "\n".join(sections)