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