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,518 @@
1
+ """
2
+ Literature recommendation engine for telecoupling/metacoupling research.
3
+
4
+ Parses a bundled BibTeX database of telecoupling and metacoupling papers
5
+ and recommends relevant publications based on keyword matching against
6
+ a user's research topic or parsed LLM analysis.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import re
12
+ from dataclasses import dataclass, field
13
+ from importlib import resources
14
+ from pathlib import Path
15
+ from typing import TYPE_CHECKING
16
+
17
+ if TYPE_CHECKING:
18
+ from metacouplingllm.llm.parser import ParsedAnalysis
19
+
20
+
21
+ # ---------------------------------------------------------------------------
22
+ # Data structures
23
+ # ---------------------------------------------------------------------------
24
+
25
+
26
+ @dataclass
27
+ class Paper:
28
+ """A single bibliographic entry from the literature database.
29
+
30
+ Attributes
31
+ ----------
32
+ key:
33
+ BibTeX citation key (e.g., ``"liu_telecoupling_2013"``).
34
+ title:
35
+ Paper title.
36
+ authors:
37
+ Author string (e.g., ``"Liu, Jianguo and Hull, Vanessa"``).
38
+ year:
39
+ Publication year.
40
+ journal:
41
+ Journal name.
42
+ doi:
43
+ DOI string (without ``https://doi.org/`` prefix).
44
+ keywords:
45
+ Set of normalised (lowercased) keywords.
46
+ cited_by:
47
+ Citation count from Web of Science (0 if unavailable).
48
+ """
49
+
50
+ key: str = ""
51
+ title: str = ""
52
+ authors: str = ""
53
+ year: int = 0
54
+ journal: str = ""
55
+ doi: str = ""
56
+ keywords: set[str] = field(default_factory=set)
57
+ cited_by: int = 0
58
+
59
+
60
+ # ---------------------------------------------------------------------------
61
+ # Relevance filter — only keep coupling-related papers
62
+ # ---------------------------------------------------------------------------
63
+
64
+ _RELEVANCE_TERMS = {
65
+ "telecoupling", "tele-coupling", "metacoupling", "meta-coupling",
66
+ "pericoupling", "peri-coupling", "intracoupling", "intra-coupling",
67
+ "coupled human and natural", "coupled human-natural",
68
+ "chans", "coupled systems",
69
+ "sending system", "receiving system", "spillover system",
70
+ "socioeconomic-environmental", "human-nature interaction",
71
+ "land use teleconnection", "teleconnection",
72
+ }
73
+
74
+
75
+ def _is_relevant(paper: Paper) -> bool:
76
+ """Return True if the paper is related to telecoupling/metacouplingllm.
77
+
78
+ All papers in the bundled database are curated, so this filter uses
79
+ title and keywords only (no abstract dependency).
80
+ """
81
+ searchable = paper.title.lower() + " " + " ".join(paper.keywords)
82
+ return any(term in searchable for term in _RELEVANCE_TERMS)
83
+
84
+
85
+ # ---------------------------------------------------------------------------
86
+ # BibTeX parser (lightweight, no external dependency)
87
+ # ---------------------------------------------------------------------------
88
+
89
+ _ENTRY_RE = re.compile(
90
+ r"@(\w+)\{([^,]+),\s*(.*?)\n\}",
91
+ re.DOTALL,
92
+ )
93
+
94
+ _FIELD_RE = re.compile(
95
+ r"(\w+)\s*=\s*\{(.*?)\}(?:\s*,)?",
96
+ re.DOTALL,
97
+ )
98
+
99
+
100
+ def _parse_bibtex(text: str) -> list[Paper]:
101
+ """Parse a BibTeX string into a list of :class:`Paper` objects."""
102
+ papers: list[Paper] = []
103
+
104
+ for match in _ENTRY_RE.finditer(text):
105
+ entry_type = match.group(1).lower()
106
+ key = match.group(2).strip()
107
+ body = match.group(3)
108
+
109
+ if entry_type not in ("article", "incollection", "inproceedings", "book"):
110
+ continue
111
+
112
+ fields: dict[str, str] = {}
113
+ for fm in _FIELD_RE.finditer(body):
114
+ fname = fm.group(1).lower().strip()
115
+ fval = fm.group(2).strip()
116
+ # Normalise whitespace
117
+ fval = re.sub(r"\s+", " ", fval)
118
+ fields[fname] = fval
119
+
120
+ # Parse citation count from annote field
121
+ cited_by = 0
122
+ annote = fields.get("annote", "")
123
+ cite_m = re.search(r"Cited by:\s*(\d+)", annote)
124
+ if cite_m:
125
+ cited_by = int(cite_m.group(1))
126
+
127
+ # Parse keywords into a set
128
+ raw_kw = fields.get("keywords", "")
129
+ keywords: set[str] = set()
130
+ if raw_kw:
131
+ for kw in re.split(r"\s*,\s*", raw_kw):
132
+ kw = kw.strip().lower()
133
+ if kw:
134
+ keywords.add(kw)
135
+
136
+ year = 0
137
+ year_str = fields.get("year", "")
138
+ if year_str.isdigit():
139
+ year = int(year_str)
140
+
141
+ paper = Paper(
142
+ key=key,
143
+ title=fields.get("title", "").replace("{", "").replace("}", ""),
144
+ authors=fields.get("author", "").replace("{", "").replace("}", ""),
145
+ year=year,
146
+ journal=fields.get("journal", "").replace("{", "").replace("}", "").replace("\\&", "&"),
147
+ doi=fields.get("doi", ""),
148
+ keywords=keywords,
149
+ cited_by=cited_by,
150
+ )
151
+ papers.append(paper)
152
+
153
+ return papers
154
+
155
+
156
+ # ---------------------------------------------------------------------------
157
+ # Database loading (lazy, cached)
158
+ # ---------------------------------------------------------------------------
159
+
160
+ _paper_db: list[Paper] | None = None
161
+
162
+
163
+ def _locate_bib() -> Path | None:
164
+ """Find the bundled BibTeX database."""
165
+ try:
166
+ data_pkg = resources.files("metacoupling") / "data"
167
+ except (TypeError, ModuleNotFoundError):
168
+ return None
169
+
170
+ candidate = data_pkg / "telecoupling_literature.bib"
171
+ try:
172
+ path = Path(str(candidate))
173
+ if path.is_file():
174
+ return path
175
+ except Exception:
176
+ pass
177
+ return None
178
+
179
+
180
+ def _load_database() -> list[Paper]:
181
+ """Load and filter the literature database."""
182
+ bib_path = _locate_bib()
183
+ if bib_path is None:
184
+ return []
185
+
186
+ text = bib_path.read_text(encoding="utf-8-sig")
187
+ all_papers = _parse_bibtex(text)
188
+
189
+ # All papers in the bundled database are curated for
190
+ # telecoupling/metacoupling research — no filtering needed.
191
+ return all_papers
192
+
193
+
194
+ def _get_database() -> list[Paper]:
195
+ """Lazily load and cache the paper database."""
196
+ global _paper_db
197
+ if _paper_db is None:
198
+ _paper_db = _load_database()
199
+ return _paper_db
200
+
201
+
202
+ # ---------------------------------------------------------------------------
203
+ # Keyword extraction from analysis
204
+ # ---------------------------------------------------------------------------
205
+
206
+
207
+ def _extract_search_terms_from_analysis(parsed: ParsedAnalysis) -> set[str]:
208
+ """Extract search keywords from a parsed LLM analysis."""
209
+ terms: set[str] = set()
210
+
211
+ # From coupling classification
212
+ if parsed.coupling_classification:
213
+ text = parsed.coupling_classification.lower()
214
+ for word in re.findall(r"[a-z][\w-]+", text):
215
+ if len(word) > 3:
216
+ terms.add(word)
217
+
218
+ # From active coupling types
219
+ for coupling_type in parsed.active_coupling_types():
220
+ terms.add(coupling_type.lower())
221
+
222
+ # From all substantive text fragments across coupling blocks
223
+ for fragment in parsed.iter_text_fragments():
224
+ for word in re.findall(r"[a-z][\w-]+", fragment.lower()):
225
+ if len(word) > 3:
226
+ terms.add(word)
227
+
228
+ # From grouped cause/effect category labels
229
+ for kind in ("causes", "effects"):
230
+ for _coupling_type, category, _item in parsed.iter_category_items(kind):
231
+ if category:
232
+ terms.add(category.lower())
233
+
234
+ # Remove very common stopwords
235
+ stopwords = {
236
+ "this", "that", "with", "from", "have", "been", "were", "will",
237
+ "also", "more", "than", "such", "each", "which", "their", "there",
238
+ "these", "those", "about", "into", "over", "between", "through",
239
+ "during", "before", "after", "other", "some", "both", "most",
240
+ "very", "just", "only", "well", "including", "based", "using",
241
+ "system", "systems", "analysis", "study", "research", "framework",
242
+ "intracoupling", "pericoupling", "telecoupling",
243
+ }
244
+ terms -= stopwords
245
+
246
+ return terms
247
+
248
+
249
+ def _extract_search_terms_from_text(text: str) -> set[str]:
250
+ """Extract search keywords from a plain text query."""
251
+ terms: set[str] = set()
252
+ for word in re.findall(r"[a-z][\w-]+", text.lower()):
253
+ if len(word) > 3:
254
+ terms.add(word)
255
+
256
+ stopwords = {
257
+ "this", "that", "with", "from", "have", "been", "were", "will",
258
+ "also", "more", "than", "such", "each", "which", "their", "there",
259
+ "these", "those", "about", "into", "over", "between", "through",
260
+ "during", "before", "after", "other", "some", "both", "most",
261
+ "very", "just", "only", "well", "including", "based", "using",
262
+ "analyze", "analysis", "study", "research", "please", "help",
263
+ }
264
+ terms -= stopwords
265
+
266
+ return terms
267
+
268
+
269
+ # ---------------------------------------------------------------------------
270
+ # Scoring
271
+ # ---------------------------------------------------------------------------
272
+
273
+
274
+ def _score_paper(
275
+ paper: Paper,
276
+ search_terms: set[str],
277
+ fulltext_scores: dict[str, float] | None = None,
278
+ ) -> float:
279
+ """Score a paper's relevance to the search terms.
280
+
281
+ Scoring components:
282
+
283
+ - Keyword match: each matching keyword adds 3.0 points
284
+ - Title match: each matching word in title adds 2.0 points
285
+ - Full-text match: cosine similarity × 3.0 (up to 3.0 points),
286
+ sourced from the RAG TF-IDF index over bundled MD files
287
+ - Citation bonus: log-scaled citation count adds up to 2.0 points
288
+
289
+ Parameters
290
+ ----------
291
+ paper:
292
+ The paper to score.
293
+ search_terms:
294
+ Lowercased keyword tokens from the query.
295
+ fulltext_scores:
296
+ Optional mapping of ``paper_key → cosine_similarity`` from the
297
+ RAG engine. When provided, the full-text score is included.
298
+ """
299
+ import math
300
+
301
+ score = 0.0
302
+
303
+ # Keyword matches (highest weight — these are curated by authors)
304
+ for term in search_terms:
305
+ for kw in paper.keywords:
306
+ if term in kw or kw in term:
307
+ score += 3.0
308
+ break
309
+
310
+ # Title matches
311
+ title_lower = paper.title.lower()
312
+ for term in search_terms:
313
+ if term in title_lower:
314
+ score += 2.0
315
+
316
+ # Full-text relevance from RAG TF-IDF index (replaces abstract scoring)
317
+ if fulltext_scores and paper.key in fulltext_scores:
318
+ score += min(3.0, fulltext_scores[paper.key] * 3.0)
319
+
320
+ # Citation bonus (log-scaled, max ~2.0 for 100+ citations)
321
+ if paper.cited_by > 0:
322
+ score += min(2.0, math.log10(paper.cited_by + 1))
323
+
324
+ return score
325
+
326
+
327
+ # ---------------------------------------------------------------------------
328
+ # Public API
329
+ # ---------------------------------------------------------------------------
330
+
331
+
332
+ def _build_fulltext_scores(
333
+ search_terms: set[str],
334
+ top_k: int = 50,
335
+ backend: str = "auto",
336
+ ) -> dict[str, float]:
337
+ """Query the RAG index and return per-paper relevance scores.
338
+
339
+ Returns a ``{paper_key: similarity_score}`` dict. If the RAG
340
+ engine cannot be loaded, prints a warning and returns an empty dict.
341
+
342
+ Parameters
343
+ ----------
344
+ search_terms:
345
+ Lowercased query tokens.
346
+ top_k:
347
+ Maximum number of matching chunks to return.
348
+ backend:
349
+ Retrieval backend (``"auto"``, ``"embeddings"``, or
350
+ ``"tfidf"``). See :class:`~metacouplingllm.knowledge.rag.RAGEngine`.
351
+ """
352
+ try:
353
+ from metacouplingllm.knowledge.rag import RAGEngine, _extract_bundled_papers
354
+ except ImportError as exc:
355
+ print(
356
+ f"[Literature] Full-text scoring unavailable: {exc}. "
357
+ "Recommendations use title + keyword matching only."
358
+ )
359
+ return {}
360
+
361
+ try:
362
+ papers_dir = _extract_bundled_papers(verbose=False)
363
+ except Exception as exc:
364
+ print(
365
+ f"[Literature] Full-text scoring unavailable: {exc}. "
366
+ "Recommendations use title + keyword matching only."
367
+ )
368
+ return {}
369
+
370
+ engine = RAGEngine(papers_dir, backend=backend)
371
+ try:
372
+ engine.load()
373
+ except Exception as exc:
374
+ print(
375
+ f"[Literature] Full-text scoring unavailable: {exc}. "
376
+ "Recommendations use title + keyword matching only."
377
+ )
378
+ return {}
379
+
380
+ query_text = " ".join(sorted(search_terms))
381
+ # Pass None so the engine picks a backend-appropriate default.
382
+ # For TF-IDF this is 0.01; for embeddings 0.3. But since this is
383
+ # a permissive paper-scoring use case (not evidence surfacing),
384
+ # use a very low threshold to keep almost all matches.
385
+ min_score = 0.001 if engine.backend == "tfidf" else 0.0
386
+ results = engine.retrieve(query_text, top_k=top_k, min_score=min_score)
387
+ return {r.chunk.paper_key: r.score for r in results}
388
+
389
+
390
+ def recommend_papers(
391
+ query: str | ParsedAnalysis,
392
+ *,
393
+ max_results: int = 5,
394
+ ) -> list[Paper]:
395
+ """Recommend relevant papers from the telecoupling literature database.
396
+
397
+ Uses title, keywords, citation count, and **full-text TF-IDF
398
+ relevance** (from bundled MD files) to rank papers.
399
+
400
+ Parameters
401
+ ----------
402
+ query:
403
+ Either a plain-text research topic (e.g., ``"soybean trade Brazil
404
+ China deforestation"``) or a :class:`ParsedAnalysis` from an LLM
405
+ analysis result.
406
+ max_results:
407
+ Maximum number of papers to return. Default is 5.
408
+
409
+ Returns
410
+ -------
411
+ A list of :class:`Paper` objects, ranked by relevance (highest first).
412
+
413
+ Examples
414
+ --------
415
+ >>> papers = recommend_papers("avocado trade Mexico United States")
416
+ >>> for p in papers:
417
+ ... print(f"{p.year} - {p.title} (cited: {p.cited_by})")
418
+
419
+ >>> result = advisor.analyze("Coffee trade Ethiopia Europe")
420
+ >>> papers = recommend_papers(result.parsed, max_results=10)
421
+ """
422
+ # Import here to avoid circular imports
423
+ from metacouplingllm.llm.parser import ParsedAnalysis as _PA
424
+
425
+ db = _get_database()
426
+ if not db:
427
+ return []
428
+
429
+ # Extract search terms
430
+ if isinstance(query, _PA):
431
+ search_terms = _extract_search_terms_from_analysis(query)
432
+ elif isinstance(query, str):
433
+ search_terms = _extract_search_terms_from_text(query)
434
+ else:
435
+ return []
436
+
437
+ if not search_terms:
438
+ return []
439
+
440
+ # Build full-text relevance scores from RAG engine
441
+ fulltext_scores = _build_fulltext_scores(search_terms)
442
+
443
+ # Score and rank
444
+ scored: list[tuple[float, Paper]] = []
445
+ for paper in db:
446
+ s = _score_paper(paper, search_terms, fulltext_scores)
447
+ if s > 0:
448
+ scored.append((s, paper))
449
+
450
+ # Sort by score descending, then by citation count, then by year
451
+ scored.sort(key=lambda t: (t[0], t[1].cited_by, t[1].year), reverse=True)
452
+
453
+ return [paper for _, paper in scored[:max_results]]
454
+
455
+
456
+ def format_recommendations(papers: list[Paper]) -> str:
457
+ """Format a list of recommended papers as a human-readable string.
458
+
459
+ Parameters
460
+ ----------
461
+ papers:
462
+ List of :class:`Paper` objects from :func:`recommend_papers`.
463
+
464
+ Returns
465
+ -------
466
+ A formatted string ready for display.
467
+ """
468
+ if not papers:
469
+ return "No relevant papers found in the literature database."
470
+
471
+ lines: list[str] = []
472
+ lines.append("=" * 70)
473
+ lines.append(" RECOMMENDED LITERATURE")
474
+ lines.append("=" * 70)
475
+ lines.append("")
476
+
477
+ for i, p in enumerate(papers, 1):
478
+ # Shorten author list if too long
479
+ authors = p.authors
480
+ if len(authors) > 80:
481
+ # Show first two authors + "et al."
482
+ parts = authors.split(" and ")
483
+ if len(parts) > 2:
484
+ authors = parts[0] + " et al."
485
+
486
+ lines.append(f" [{i}] {p.title}")
487
+ lines.append(f" {authors} ({p.year})")
488
+ lines.append(f" {p.journal}")
489
+ if p.doi:
490
+ lines.append(f" DOI: {p.doi}")
491
+ if p.cited_by > 0:
492
+ lines.append(f" Cited by: {p.cited_by}")
493
+ lines.append("")
494
+
495
+ lines.append("=" * 70)
496
+ return "\n".join(lines)
497
+
498
+
499
+ def get_database_info() -> dict[str, int]:
500
+ """Return summary statistics about the loaded literature database.
501
+
502
+ Returns
503
+ -------
504
+ A dict with keys ``total_papers``, ``with_keywords``,
505
+ ``year_min``, ``year_max``, ``total_citations``.
506
+ """
507
+ db = _get_database()
508
+ if not db:
509
+ return {"total_papers": 0}
510
+
511
+ years = [p.year for p in db if p.year > 0]
512
+ return {
513
+ "total_papers": len(db),
514
+ "with_keywords": sum(1 for p in db if p.keywords),
515
+ "year_min": min(years) if years else 0,
516
+ "year_max": max(years) if years else 0,
517
+ "total_citations": sum(p.cited_by for p in db),
518
+ }