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