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,208 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Metacoupling — Apply telecoupling and metacoupling frameworks using LLMs.
|
|
3
|
+
|
|
4
|
+
This package helps researchers identify and analyze telecoupling,
|
|
5
|
+
pericoupling, and intracoupling processes in their studies using the
|
|
6
|
+
frameworks proposed by Jianguo Liu and colleagues.
|
|
7
|
+
|
|
8
|
+
Quick start
|
|
9
|
+
-----------
|
|
10
|
+
>>> from openai import OpenAI
|
|
11
|
+
>>> from metacouplingllm import MetacouplingAssistant, OpenAIAdapter
|
|
12
|
+
>>>
|
|
13
|
+
>>> client = OpenAI(api_key="...")
|
|
14
|
+
>>> advisor = MetacouplingAssistant(OpenAIAdapter(client, model="gpt-4o"))
|
|
15
|
+
>>>
|
|
16
|
+
>>> result = advisor.analyze("My research examines international coffee trade...")
|
|
17
|
+
>>> print(result.formatted)
|
|
18
|
+
>>>
|
|
19
|
+
>>> result2 = advisor.refine("Can you elaborate on spillover systems?")
|
|
20
|
+
>>> print(result2.formatted)
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
from metacouplingllm.core import (
|
|
24
|
+
AnalysisResult,
|
|
25
|
+
JOURNAL_ARTICLES_2025,
|
|
26
|
+
MetacouplingAssistant,
|
|
27
|
+
RAGResult,
|
|
28
|
+
)
|
|
29
|
+
from metacouplingllm.knowledge.countries import (
|
|
30
|
+
get_country_name,
|
|
31
|
+
resolve_country_code,
|
|
32
|
+
)
|
|
33
|
+
from metacouplingllm.knowledge.framework import (
|
|
34
|
+
AgentLevel,
|
|
35
|
+
CauseCategory,
|
|
36
|
+
CouplingType,
|
|
37
|
+
EffectCategory,
|
|
38
|
+
FlowCategory,
|
|
39
|
+
FrameworkComponent,
|
|
40
|
+
SystemRole,
|
|
41
|
+
)
|
|
42
|
+
from metacouplingllm.knowledge.literature import (
|
|
43
|
+
Paper,
|
|
44
|
+
format_recommendations,
|
|
45
|
+
get_database_info,
|
|
46
|
+
recommend_papers,
|
|
47
|
+
)
|
|
48
|
+
from metacouplingllm.knowledge.adm1_pericoupling import (
|
|
49
|
+
Adm1PairType,
|
|
50
|
+
Adm1PericouplingResult,
|
|
51
|
+
get_adm1_codes_for_country,
|
|
52
|
+
get_adm1_country,
|
|
53
|
+
get_adm1_info,
|
|
54
|
+
get_adm1_neighbors,
|
|
55
|
+
get_cross_border_neighbors,
|
|
56
|
+
is_adm1_pericoupled,
|
|
57
|
+
lookup_adm1_pericoupling,
|
|
58
|
+
resolve_adm1_code,
|
|
59
|
+
)
|
|
60
|
+
from metacouplingllm.knowledge.citations import (
|
|
61
|
+
extract_cited_ids,
|
|
62
|
+
sanitize_citations,
|
|
63
|
+
)
|
|
64
|
+
from metacouplingllm.knowledge.rag import (
|
|
65
|
+
RAGEngine,
|
|
66
|
+
RetrievalResult,
|
|
67
|
+
TextChunk,
|
|
68
|
+
annotate_citations,
|
|
69
|
+
format_evidence,
|
|
70
|
+
)
|
|
71
|
+
from metacouplingllm.knowledge.websearch import (
|
|
72
|
+
AnthropicWebSearchBackend,
|
|
73
|
+
GeminiWebSearchBackend,
|
|
74
|
+
GrokWebSearchBackend,
|
|
75
|
+
OpenAIWebSearchBackend,
|
|
76
|
+
annotate_web_citations,
|
|
77
|
+
extract_web_map_signals,
|
|
78
|
+
format_web_context,
|
|
79
|
+
format_web_map_signals_context,
|
|
80
|
+
search_web,
|
|
81
|
+
)
|
|
82
|
+
from metacouplingllm.knowledge.pericoupling import (
|
|
83
|
+
PairCouplingType,
|
|
84
|
+
PericouplingResult,
|
|
85
|
+
get_pericoupled_neighbors,
|
|
86
|
+
is_pericoupled,
|
|
87
|
+
lookup_pericoupling,
|
|
88
|
+
)
|
|
89
|
+
from metacouplingllm.llm.client import (
|
|
90
|
+
AnthropicAdapter,
|
|
91
|
+
GeminiAdapter,
|
|
92
|
+
GrokAdapter,
|
|
93
|
+
LLMClient,
|
|
94
|
+
LLMResponse,
|
|
95
|
+
Message,
|
|
96
|
+
OpenAIAdapter,
|
|
97
|
+
)
|
|
98
|
+
|
|
99
|
+
__version__ = "0.1.0"
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
# ---------------------------------------------------------------------------
|
|
103
|
+
# Lazy-import wrappers for visualization (requires metacoupling[viz])
|
|
104
|
+
# ---------------------------------------------------------------------------
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def plot_focal_country_map(focal_country, **kwargs):
|
|
108
|
+
"""Plot a world map by coupling type relative to a focal country.
|
|
109
|
+
|
|
110
|
+
Requires: ``pip install metacoupling[viz]``
|
|
111
|
+
"""
|
|
112
|
+
from metacouplingllm.visualization.worldmap import (
|
|
113
|
+
plot_focal_country_map as _f,
|
|
114
|
+
)
|
|
115
|
+
|
|
116
|
+
return _f(focal_country, **kwargs)
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
def plot_analysis_map(parsed_analysis, **kwargs):
|
|
120
|
+
"""Plot a world map from LLM analysis results.
|
|
121
|
+
|
|
122
|
+
Requires: ``pip install metacoupling[viz]``
|
|
123
|
+
"""
|
|
124
|
+
from metacouplingllm.visualization.worldmap import plot_analysis_map as _f
|
|
125
|
+
|
|
126
|
+
return _f(parsed_analysis, **kwargs)
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
def plot_focal_adm1_map(focal_adm1, **kwargs):
|
|
130
|
+
"""Plot a subnational (ADM1) map by coupling type relative to a focal region.
|
|
131
|
+
|
|
132
|
+
Requires: ``pip install metacoupling[viz]``
|
|
133
|
+
"""
|
|
134
|
+
from metacouplingllm.visualization.adm1_map import plot_focal_adm1_map as _f
|
|
135
|
+
|
|
136
|
+
return _f(focal_adm1, **kwargs)
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
__all__ = [
|
|
140
|
+
# Main interface
|
|
141
|
+
"MetacouplingAssistant",
|
|
142
|
+
"AnalysisResult",
|
|
143
|
+
"RAGResult",
|
|
144
|
+
"JOURNAL_ARTICLES_2025",
|
|
145
|
+
# LLM client
|
|
146
|
+
"LLMClient",
|
|
147
|
+
"Message",
|
|
148
|
+
"LLMResponse",
|
|
149
|
+
"OpenAIAdapter",
|
|
150
|
+
"AnthropicAdapter",
|
|
151
|
+
"GeminiAdapter",
|
|
152
|
+
"GrokAdapter",
|
|
153
|
+
# Enums
|
|
154
|
+
"AgentLevel",
|
|
155
|
+
"CauseCategory",
|
|
156
|
+
"EffectCategory",
|
|
157
|
+
"CouplingType",
|
|
158
|
+
"SystemRole",
|
|
159
|
+
"FlowCategory",
|
|
160
|
+
"FrameworkComponent",
|
|
161
|
+
# Country-level pericoupling
|
|
162
|
+
"PairCouplingType",
|
|
163
|
+
"PericouplingResult",
|
|
164
|
+
"lookup_pericoupling",
|
|
165
|
+
"is_pericoupled",
|
|
166
|
+
"get_pericoupled_neighbors",
|
|
167
|
+
"resolve_country_code",
|
|
168
|
+
"get_country_name",
|
|
169
|
+
# ADM1 (subnational) pericoupling
|
|
170
|
+
"Adm1PairType",
|
|
171
|
+
"Adm1PericouplingResult",
|
|
172
|
+
"lookup_adm1_pericoupling",
|
|
173
|
+
"is_adm1_pericoupled",
|
|
174
|
+
"get_adm1_neighbors",
|
|
175
|
+
"get_cross_border_neighbors",
|
|
176
|
+
"get_adm1_codes_for_country",
|
|
177
|
+
"get_adm1_info",
|
|
178
|
+
"get_adm1_country",
|
|
179
|
+
"resolve_adm1_code",
|
|
180
|
+
# Literature recommendation
|
|
181
|
+
"recommend_papers",
|
|
182
|
+
"format_recommendations",
|
|
183
|
+
"get_database_info",
|
|
184
|
+
"Paper",
|
|
185
|
+
# RAG (full-text evidence retrieval)
|
|
186
|
+
"RAGEngine",
|
|
187
|
+
"RetrievalResult",
|
|
188
|
+
"TextChunk",
|
|
189
|
+
"format_evidence",
|
|
190
|
+
"annotate_citations",
|
|
191
|
+
# Citation sanitization (pre-retrieval RAG)
|
|
192
|
+
"sanitize_citations",
|
|
193
|
+
"extract_cited_ids",
|
|
194
|
+
# Web search (requires metacoupling[search])
|
|
195
|
+
"search_web",
|
|
196
|
+
"AnthropicWebSearchBackend",
|
|
197
|
+
"GeminiWebSearchBackend",
|
|
198
|
+
"GrokWebSearchBackend",
|
|
199
|
+
"OpenAIWebSearchBackend",
|
|
200
|
+
"format_web_context",
|
|
201
|
+
"annotate_web_citations",
|
|
202
|
+
"extract_web_map_signals",
|
|
203
|
+
"format_web_map_signals_context",
|
|
204
|
+
# Visualization (requires metacoupling[viz])
|
|
205
|
+
"plot_focal_country_map",
|
|
206
|
+
"plot_analysis_map",
|
|
207
|
+
"plot_focal_adm1_map",
|
|
208
|
+
]
|