litloop 1.18.3__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 (176) hide show
  1. litloop/__init__.py +89 -0
  2. litloop/__main__.py +6 -0
  3. litloop/_source_hygiene.py +158 -0
  4. litloop/agents/__init__.py +13 -0
  5. litloop/agents/client.py +164 -0
  6. litloop/agents/runner.py +123 -0
  7. litloop/agents/system.py +54 -0
  8. litloop/agents/tools.py +142 -0
  9. litloop/app_server.py +8 -0
  10. litloop/browser/__init__.py +1 -0
  11. litloop/browser/backend.py +1009 -0
  12. litloop/browser/camofox_api.py +368 -0
  13. litloop/browser/chrome_copy.py +136 -0
  14. litloop/browser/cloakbrowser_compat.py +72 -0
  15. litloop/browser/cookies.py +347 -0
  16. litloop/browser/engine.py +965 -0
  17. litloop/browser/login.py +636 -0
  18. litloop/browser/pdf.py +263 -0
  19. litloop/browser/profile_health.py +167 -0
  20. litloop/browser/runtime.py +210 -0
  21. litloop/cache.py +104 -0
  22. litloop/citations/__init__.py +1 -0
  23. litloop/citations/bib_import.py +102 -0
  24. litloop/citations/bibtex_crossref.py +143 -0
  25. litloop/citations/formats.py +225 -0
  26. litloop/citations/paper_list.py +200 -0
  27. litloop/citations/session_export.py +94 -0
  28. litloop/cli/__init__.py +12 -0
  29. litloop/cli/_utils.py +267 -0
  30. litloop/cli/commands.py +1098 -0
  31. litloop/cli/doctor.py +141 -0
  32. litloop/cli/main.py +1173 -0
  33. litloop/cli/web.py +190 -0
  34. litloop/config.py +413 -0
  35. litloop/data/VARCON-LICENSE.txt +62 -0
  36. litloop/data/elements.tsv +119 -0
  37. litloop/data/institutional_identity_policy.json +165 -0
  38. litloop/data/publisher_access_catalog.json +969 -0
  39. litloop/data/publisher_carsi.json +105 -0
  40. litloop/data/spelling_search.tsv.gz +0 -0
  41. litloop/data/spelling_us.tsv.gz +0 -0
  42. litloop/data/webvpn.dat +0 -0
  43. litloop/data/webvpn.json +603 -0
  44. litloop/db.py +1922 -0
  45. litloop/deps.py +128 -0
  46. litloop/desktop/__init__.py +1 -0
  47. litloop/desktop/agent_runner.py +537 -0
  48. litloop/desktop/download_jobs.py +571 -0
  49. litloop/desktop/error_text.py +192 -0
  50. litloop/desktop/server.py +999 -0
  51. litloop/desktop/settings.py +552 -0
  52. litloop/desktop/translate.py +103 -0
  53. litloop/diagnostics.py +126 -0
  54. litloop/download/__init__.py +1 -0
  55. litloop/download/doi_check.py +44 -0
  56. litloop/download/fetcher.py +975 -0
  57. litloop/download/markdown.py +130 -0
  58. litloop/download/pdf.py +454 -0
  59. litloop/download/pipeline.py +1166 -0
  60. litloop/download/progress.py +312 -0
  61. litloop/download/rename.py +211 -0
  62. litloop/extractors/__init__.py +0 -0
  63. litloop/extractors/html_extractor.py +31 -0
  64. litloop/extractors/pdf_extractor.py +151 -0
  65. litloop/extractors/publisher_adapters/__init__.py +0 -0
  66. litloop/extractors/publisher_adapters/acs.py +167 -0
  67. litloop/extractors/publisher_adapters/elsevier.py +178 -0
  68. litloop/extractors/publisher_adapters/generic.py +191 -0
  69. litloop/extractors/publisher_adapters/nature.py +204 -0
  70. litloop/extractors/publisher_adapters/rsc.py +154 -0
  71. litloop/extractors/publisher_adapters/tandfonline.py +154 -0
  72. litloop/extractors/publisher_adapters/wiley.py +160 -0
  73. litloop/http_utils.py +57 -0
  74. litloop/identifiers.py +134 -0
  75. litloop/institutional/__init__.py +1 -0
  76. litloop/institutional/auth.py +576 -0
  77. litloop/institutional/carsi_login.py +569 -0
  78. litloop/institutional/config_adapter.py +63 -0
  79. litloop/institutional/proxy_check.py +98 -0
  80. litloop/institutional/remote_assist.py +274 -0
  81. litloop/institutional/schools.py +102 -0
  82. litloop/institutional/session_heal.py +73 -0
  83. litloop/institutional/session_store.py +105 -0
  84. litloop/log.py +47 -0
  85. litloop/models.py +269 -0
  86. litloop/network.py +417 -0
  87. litloop/optional.py +310 -0
  88. litloop/publishers/__init__.py +1 -0
  89. litloop/publishers/access.py +232 -0
  90. litloop/publishers/pdf_router.py +451 -0
  91. litloop/publishers/profiles.py +899 -0
  92. litloop/publishers/strategies/__init__.py +122 -0
  93. litloop/publishers/strategies/_core.py +2340 -0
  94. litloop/publishers/strategies/_elsevier_api.py +578 -0
  95. litloop/publishers/strategies/acm.py +27 -0
  96. litloop/publishers/strategies/acs.py +42 -0
  97. litloop/publishers/strategies/aip.py +27 -0
  98. litloop/publishers/strategies/aps.py +29 -0
  99. litloop/publishers/strategies/asce.py +28 -0
  100. litloop/publishers/strategies/base.py +108 -0
  101. litloop/publishers/strategies/copernicus.py +24 -0
  102. litloop/publishers/strategies/elsevier.py +66 -0
  103. litloop/publishers/strategies/generic.py +39 -0
  104. litloop/publishers/strategies/ieee.py +28 -0
  105. litloop/publishers/strategies/iop.py +27 -0
  106. litloop/publishers/strategies/nature.py +27 -0
  107. litloop/publishers/strategies/oxford.py +27 -0
  108. litloop/publishers/strategies/registry.py +83 -0
  109. litloop/publishers/strategies/royalsociety.py +28 -0
  110. litloop/publishers/strategies/rsc.py +27 -0
  111. litloop/publishers/strategies/sage.py +30 -0
  112. litloop/publishers/strategies/science.py +27 -0
  113. litloop/publishers/strategies/springer.py +34 -0
  114. litloop/publishers/strategies/tandfonline.py +32 -0
  115. litloop/publishers/strategies/wiley.py +32 -0
  116. litloop/publishers/supplementary.py +219 -0
  117. litloop/quota.py +202 -0
  118. litloop/search/__init__.py +1 -0
  119. litloop/search/abstracts.py +291 -0
  120. litloop/search/deep.py +1216 -0
  121. litloop/search/quick.py +1102 -0
  122. litloop/search/scansci_find.py +410 -0
  123. litloop/search/screening.py +225 -0
  124. litloop/search/title_to_doi.py +163 -0
  125. litloop/search/watches.py +124 -0
  126. litloop/server.py +1731 -0
  127. litloop/sources/__init__.py +1339 -0
  128. litloop/sources/_batch.py +529 -0
  129. litloop/sources/_index.py +221 -0
  130. litloop/sources/_routes.py +290 -0
  131. litloop/sources/altcha.py +90 -0
  132. litloop/sources/arxiv.py +45 -0
  133. litloop/sources/attempt.py +91 -0
  134. litloop/sources/carsi.py +74 -0
  135. litloop/sources/core_api.py +46 -0
  136. litloop/sources/crossref.py +162 -0
  137. litloop/sources/elsevier_api.py +620 -0
  138. litloop/sources/elsevier_check.py +274 -0
  139. litloop/sources/europepmc.py +81 -0
  140. litloop/sources/ezproxy.py +317 -0
  141. litloop/sources/instsci.py +1295 -0
  142. litloop/sources/libgen.py +116 -0
  143. litloop/sources/nature.py +39 -0
  144. litloop/sources/oa_discovery.py +135 -0
  145. litloop/sources/openaire.py +122 -0
  146. litloop/sources/openalex.py +100 -0
  147. litloop/sources/publishers.py +684 -0
  148. litloop/sources/sage_cn.py +139 -0
  149. litloop/sources/scibban.py +10 -0
  150. litloop/sources/scihub.py +1379 -0
  151. litloop/sources/scihub_domains.py +203 -0
  152. litloop/sources/scihub_speed.py +187 -0
  153. litloop/sources/scoring.py +250 -0
  154. litloop/sources/semantic_scholar.py +146 -0
  155. litloop/sources/springer_tdm.py +172 -0
  156. litloop/sources/unpaywall.py +116 -0
  157. litloop/sources/vpnsci.py +38 -0
  158. litloop/store.py +264 -0
  159. litloop/templates/index.html +347 -0
  160. litloop/terms/__init__.py +1 -0
  161. litloop/terms/glossary.py +422 -0
  162. litloop/terms/spelling.py +89 -0
  163. litloop/terms/text.py +106 -0
  164. litloop/tor/__init__.py +1 -0
  165. litloop/tor/embedded.py +371 -0
  166. litloop/tor/proxy.py +110 -0
  167. litloop/updates.py +148 -0
  168. litloop/zotero/__init__.py +1 -0
  169. litloop/zotero/bridge.py +309 -0
  170. litloop/zotero/client.py +317 -0
  171. litloop-1.18.3.dist-info/METADATA +347 -0
  172. litloop-1.18.3.dist-info/RECORD +176 -0
  173. litloop-1.18.3.dist-info/WHEEL +5 -0
  174. litloop-1.18.3.dist-info/entry_points.txt +2 -0
  175. litloop-1.18.3.dist-info/licenses/LICENSE +197 -0
  176. litloop-1.18.3.dist-info/top_level.txt +1 -0
litloop/__init__.py ADDED
@@ -0,0 +1,89 @@
1
+ """LitLoop - Academic paper downloader MCP server."""
2
+
3
+ import os as _os
4
+ import sys as _sys
5
+
6
+ # -- Auto-fix: ZCode proxy CA cert breaks SSL verification -------------------
7
+ # ZCode's traffic proxy sets HTTP_PROXY/HTTPS_PROXY to 127.0.0.1:64844 and
8
+ # SSL_CERT_FILE to its own root CA. requests' trust_env=True routes all HTTPS
9
+ # through the proxy tunnel, but the proxy's SSL context fails to verify real
10
+ # server certs. We disable proxy usage project-wide so HTTPS goes direct.
11
+
12
+ # 1. Block proxy usage (must run unconditionally, before any other import)
13
+ _os.environ["NO_PROXY"] = "*"
14
+ _os.environ["no_proxy"] = "*"
15
+
16
+ def _fix_ssl_cert_file() -> None:
17
+ _cert_file = _os.environ.get("SSL_CERT_FILE", "")
18
+ if not _cert_file or "root-ca-cert" not in _cert_file:
19
+ return
20
+ _merged = _os.path.join(_os.path.dirname(_cert_file), "..", "..", "ca-bundle-merged.pem")
21
+ _merged = _os.path.normpath(_merged)
22
+ if not _os.path.exists(_merged):
23
+ try:
24
+ import certifi
25
+ with open(_cert_file, "rb") as _f:
26
+ _zc = _f.read()
27
+ with open(certifi.where(), "rb") as _f:
28
+ _rc = _f.read()
29
+ with open(_merged, "wb") as _f:
30
+ _f.write(_zc + b"\n")
31
+ _f.write(_rc)
32
+ except Exception:
33
+ return
34
+ # 2. Set merged CA bundle (proxy CA + real CAs) for direct HTTPS
35
+ _os.environ["SSL_CERT_FILE"] = _merged
36
+ _os.environ["REQUESTS_CA_BUNDLE"] = _merged
37
+ _os.environ["CURL_CA_BUNDLE"] = _merged
38
+ # 3. Monkey-patch SSLContext.load_default_certs for urllib3 direct usage
39
+ import ssl as _ssl
40
+ _orig_load_default_certs = _ssl.SSLContext.load_default_certs
41
+ def _patched_load_default_certs(self, *args, **kwargs):
42
+ _orig_load_default_certs(self, *args, **kwargs)
43
+ self.load_verify_locations(_merged)
44
+ _ssl.SSLContext.load_default_certs = _patched_load_default_certs
45
+
46
+ _fix_ssl_cert_file()
47
+
48
+ # Components installed on demand (the layout model) live in <data dir>/packages;
49
+ # make them importable before anything tries `import pymupdf4llm`.
50
+ try:
51
+ from .optional import ensure_on_path as _ensure_on_path
52
+ _ensure_on_path()
53
+ except Exception: # a broken component folder must not stop LitLoop from starting
54
+ pass
55
+
56
+ __version__ = "1.18.3"
57
+
58
+ __all__ = [
59
+ "__version__",
60
+ "batch_download",
61
+ "search_papers",
62
+ "load_config",
63
+ "update_config",
64
+ "get_config_safe",
65
+ ]
66
+
67
+ from .config import load_config, update_config, get_config_safe
68
+
69
+ _LAZY_IMPORTS = {
70
+ "batch_download": (".sources", "batch_download"),
71
+ "search_papers": (".search.quick", "search_papers"),
72
+ }
73
+
74
+
75
+ def __getattr__(name: str):
76
+ target = _LAZY_IMPORTS.get(name)
77
+ if target is None:
78
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
79
+ module_name, attr_name = target
80
+ from importlib import import_module
81
+
82
+ module = import_module(module_name, __name__)
83
+ value = getattr(module, attr_name)
84
+ globals()[name] = value
85
+ return value
86
+
87
+
88
+ def __dir__() -> list[str]:
89
+ return sorted(set(globals()) | set(__all__))
litloop/__main__.py ADDED
@@ -0,0 +1,6 @@
1
+ """Allow running as `python -m litloop`."""
2
+
3
+ from .cli.main import main
4
+
5
+ if __name__ == "__main__":
6
+ main()
@@ -0,0 +1,158 @@
1
+ """Source code hygiene rules and scanning.
2
+
3
+ Scans source code for:
4
+ - Hard-coded absolute user / development paths (e.g. D:\\Projects, C:\\Users)
5
+ - Hard-coded User-Agent strings drifting away from litloop.network.user_agent()
6
+ - Own copies of the text rules litloop.terms.text holds (stop-word lists, dash
7
+ sets, title keys, guessed element symbols); 2026-10-25 there were 15 of them
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import re
13
+ from pathlib import Path
14
+ from typing import NamedTuple
15
+
16
+ RULE_USER_PATH = "hard-coded user path"
17
+ RULE_USER_AGENT = "hard-coded User-Agent"
18
+
19
+ USER_PATH_PATTERN = re.compile(r"[A-Za-z]:[\\/]+(?:Projects|Users)[\\/]+", re.I)
20
+ USER_AGENT_PATTERN = re.compile(r"(?:LitLoop|litloop)/\d+")
21
+
22
+ UA_EXEMPT_FILENAMES = frozenset({"network.py"})
23
+
24
+ RULE_OWN_TEXT_RULE = "own copy of a text rule (use litloop.terms.text)"
25
+ _DASH_CHAR = r"(?:[‐-―−]|\\u201[0-5]|\\u2212)"
26
+ TITLE_KEY_PATTERN = re.compile(r"""\[\^a-z0-9\]\+["']\s*,\s*["']["']""") # re.sub(r"[^a-z0-9]+", "", title)
27
+ DASH_SET_PATTERN = re.compile(rf"\[[^\]\n]*{_DASH_CHAR}[^\]\n]*{_DASH_CHAR}") # [...] with two kinds of dash
28
+ DASH_REPLACE_PATTERN = re.compile(rf"""\.replace\(\s*["']{_DASH_CHAR}""")
29
+ ELEMENT_GUESS_PATTERN = re.compile(r"\^\[A-Z\]\[a-z\]\?\$") # ^[A-Z][a-z]?$
30
+ _STOPWORD_SAMPLE = frozenset("a an and the of in on for to with by from at as or".split())
31
+ _WORDS_LITERAL = re.compile(r"""["']([a-z]+(?: [a-z]+){5,}) ?["']""")
32
+
33
+
34
+ def _is_text_rules_home(path: Path) -> bool:
35
+ """terms/text.py holds the rules; this file holds the patterns that find copies of them."""
36
+ return (path.name == "text.py" and path.parent.name == "terms") or path.name == "_source_hygiene.py"
37
+
38
+
39
+ def own_text_rule(line: str) -> str:
40
+ """Which rule of litloop.terms.text the line rebuilds, or ""."""
41
+ if TITLE_KEY_PATTERN.search(line):
42
+ return "title key: use text.title_key / text.paper_key"
43
+ if DASH_SET_PATTERN.search(line) or DASH_REPLACE_PATTERN.search(line):
44
+ return "dash set: use text.DASHES / text.ascii_dashes / text.plain"
45
+ if ELEMENT_GUESS_PATTERN.search(line):
46
+ return "element guess: use text.element_symbols / text.is_chemical_system"
47
+ for m in _WORDS_LITERAL.finditer(line):
48
+ if len(set(m.group(1).split()) & _STOPWORD_SAMPLE) >= 5:
49
+ return "stop-word list: use text.STOPWORDS"
50
+ return ""
51
+
52
+ PACKAGE_DIR = Path(__file__).resolve().parent
53
+ REPO_ROOT = PACKAGE_DIR.parent.parent
54
+ DEFAULT_SCAN_DIR = PACKAGE_DIR
55
+
56
+
57
+ class HygieneProblem(NamedTuple):
58
+ file: str
59
+ line: int
60
+ rule: str
61
+ detail: str = ""
62
+
63
+ def __str__(self) -> str:
64
+ if self.line > 0:
65
+ if self.detail:
66
+ return f"{self.file}:{self.line}: {self.rule}: {self.detail}"
67
+ return f"{self.file}:{self.line}: {self.rule}"
68
+ return f"{self.file}: {self.detail or self.rule}"
69
+
70
+
71
+ def is_test_file(path: Path) -> bool:
72
+ """Return True if path looks like a test file or lives in a tests directory."""
73
+ return path.name.startswith("test_") or "tests" in path.parts
74
+
75
+
76
+ def check_source_hygiene(
77
+ target: Path | str | None = None,
78
+ repo_root: Path | str | None = None,
79
+ ) -> list[HygieneProblem]:
80
+ """Scan Python source files for hygiene issues.
81
+
82
+ Parameters:
83
+ target: A directory to recursively scan or a specific .py file.
84
+ Defaults to src/litloop.
85
+ repo_root: Base directory used to calculate relative file paths.
86
+ Defaults to the repository root, or target if outside repo.
87
+
88
+ Returns:
89
+ A list of HygieneProblem instances.
90
+ """
91
+ if target is None:
92
+ target_path = DEFAULT_SCAN_DIR
93
+ base_dir = Path(repo_root) if repo_root is not None else REPO_ROOT
94
+ else:
95
+ target_path = Path(target)
96
+ if repo_root is not None:
97
+ base_dir = Path(repo_root)
98
+ elif target_path.is_dir():
99
+ base_dir = target_path
100
+ else:
101
+ base_dir = target_path.parent
102
+
103
+ if target_path.is_file():
104
+ py_files = [target_path]
105
+ elif target_path.is_dir():
106
+ py_files = sorted(target_path.rglob("*.py"))
107
+ else:
108
+ return []
109
+
110
+ problems: list[HygieneProblem] = []
111
+ for py_file in py_files:
112
+ if is_test_file(py_file):
113
+ continue
114
+
115
+ try:
116
+ rel = py_file.relative_to(base_dir).as_posix()
117
+ except ValueError:
118
+ rel = py_file.as_posix()
119
+
120
+ try:
121
+ lines = py_file.read_text(encoding="utf-8", errors="ignore").splitlines()
122
+ except OSError as exc:
123
+ problems.append(
124
+ HygieneProblem(
125
+ file=rel,
126
+ line=0,
127
+ rule="unreadable file",
128
+ detail=f"could not read file ({exc})",
129
+ )
130
+ )
131
+ continue
132
+
133
+ is_network = py_file.name in UA_EXEMPT_FILENAMES
134
+ is_text_home = _is_text_rules_home(py_file)
135
+ for idx, line in enumerate(lines, 1):
136
+ what = "" if is_text_home else own_text_rule(line)
137
+ if what:
138
+ problems.append(HygieneProblem(file=rel, line=idx, rule=RULE_OWN_TEXT_RULE, detail=what))
139
+ if USER_PATH_PATTERN.search(line):
140
+ problems.append(
141
+ HygieneProblem(
142
+ file=rel,
143
+ line=idx,
144
+ rule=RULE_USER_PATH,
145
+ detail=line.strip(),
146
+ )
147
+ )
148
+ if not is_network and USER_AGENT_PATTERN.search(line):
149
+ problems.append(
150
+ HygieneProblem(
151
+ file=rel,
152
+ line=idx,
153
+ rule=RULE_USER_AGENT,
154
+ detail=line.strip(),
155
+ )
156
+ )
157
+
158
+ return problems
@@ -0,0 +1,13 @@
1
+ """The model side of the desktop app's built-in agent (backend B).
2
+
3
+ The app can hand a task to an external agent (Claude Code, Codex, …) or talk to
4
+ a model API itself. This package is the second option: one call shape over both
5
+ protocols — Anthropic's own Messages API and the OpenAI-compatible one that
6
+ DeepSeek, 通义千问, Kimi, 智谱 GLM, OpenRouter, Ollama and vLLM speak.
7
+ """
8
+
9
+ from .client import PROVIDERS, chat, model_config, test_model
10
+ from .runner import ToolError, run_task
11
+ from .tools import FUNCTIONS, TOOLS
12
+
13
+ __all__ = ["FUNCTIONS", "PROVIDERS", "TOOLS", "ToolError", "chat", "model_config", "run_task", "test_model"]
@@ -0,0 +1,164 @@
1
+ """One call shape over the Anthropic Messages API and the OpenAI-compatible one.
2
+
3
+ Both give back the same dict: ``{"text", "tool_calls": [{"name", "arguments"}],
4
+ "stop", "usage"}``. Nothing here knows about tasks, prompts or the app; the
5
+ runner that drives a task is built on top of ``chat()``.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import json
11
+ import time
12
+ from typing import Any
13
+ from urllib.parse import urlparse
14
+
15
+ import requests
16
+
17
+ from ..network import proxy_dict, select_proxy_for_url, user_agent
18
+
19
+ PROVIDERS: dict[str, dict[str, str]] = {
20
+ "anthropic": {"label": "Anthropic", "base_url": "https://api.anthropic.com", "protocol": "anthropic"},
21
+ "openai": {
22
+ "label": "OpenAI 兼容",
23
+ "base_url": "https://api.openai.com/v1",
24
+ "protocol": "openai",
25
+ },
26
+ }
27
+
28
+ ANTHROPIC_VERSION = "2023-06-01"
29
+ _LOCAL_HOSTS = {"127.0.0.1", "localhost", "::1"}
30
+
31
+
32
+ def model_config(config: dict[str, Any] | None = None) -> dict[str, str]:
33
+ """The configured model, with the provider's defaults filled in."""
34
+ config = config or {}
35
+ provider = (config.get("builtin_agent_provider") or "openai").strip().lower()
36
+ if provider not in PROVIDERS:
37
+ provider = "openai"
38
+ base_url = (config.get("builtin_agent_base_url") or "").strip() or PROVIDERS[provider]["base_url"]
39
+ return {
40
+ "provider": provider,
41
+ "protocol": PROVIDERS[provider]["protocol"],
42
+ "base_url": base_url.rstrip("/"),
43
+ "api_key": (config.get("builtin_agent_api_key") or "").strip(),
44
+ "model": (config.get("builtin_agent_model") or "").strip(),
45
+ }
46
+
47
+
48
+ def _endpoint(cfg: dict[str, str]) -> str:
49
+ if cfg["protocol"] == "anthropic":
50
+ return f"{cfg['base_url']}/v1/messages"
51
+ return f"{cfg['base_url']}/chat/completions"
52
+
53
+
54
+ def _headers(cfg: dict[str, str]) -> dict[str, str]:
55
+ if cfg["protocol"] == "anthropic":
56
+ return {"x-api-key": cfg["api_key"], "anthropic-version": ANTHROPIC_VERSION,
57
+ "content-type": "application/json"}
58
+ return {"Authorization": f"Bearer {cfg['api_key']}", "content-type": "application/json"}
59
+
60
+
61
+ def _payload(cfg: dict[str, str], messages: list[dict[str, Any]], tools: list[dict[str, Any]] | None,
62
+ max_tokens: int, system: str) -> dict[str, Any]:
63
+ body: dict[str, Any] = {"model": cfg["model"], "max_tokens": max_tokens}
64
+ if cfg["protocol"] == "anthropic":
65
+ body["messages"] = [m for m in messages if m.get("role") != "system"]
66
+ if system:
67
+ body["system"] = system
68
+ if tools:
69
+ body["tools"] = [{"name": t["name"], "description": t.get("description", ""),
70
+ "input_schema": t.get("parameters") or {"type": "object", "properties": {}}}
71
+ for t in tools]
72
+ return body
73
+ body["messages"] = ([{"role": "system", "content": system}] if system else []) + messages
74
+ if tools:
75
+ body["tools"] = [{"type": "function",
76
+ "function": {"name": t["name"], "description": t.get("description", ""),
77
+ "parameters": t.get("parameters") or {"type": "object", "properties": {}}}}
78
+ for t in tools]
79
+ return body
80
+
81
+
82
+ def _parse(cfg: dict[str, str], data: dict[str, Any]) -> dict[str, Any]:
83
+ out: dict[str, Any] = {"text": "", "tool_calls": [], "stop": "", "usage": data.get("usage") or {}}
84
+ if cfg["protocol"] == "anthropic":
85
+ for block in data.get("content") or []:
86
+ if block.get("type") == "text":
87
+ out["text"] += block.get("text", "")
88
+ elif block.get("type") == "tool_use":
89
+ out["tool_calls"].append({"id": block.get("id", ""), "name": block.get("name", ""),
90
+ "arguments": block.get("input") or {}})
91
+ out["stop"] = data.get("stop_reason") or ""
92
+ return out
93
+ for choice in data.get("choices") or []:
94
+ message = choice.get("message") or {}
95
+ out["text"] += message.get("content") or ""
96
+ for call in message.get("tool_calls") or []:
97
+ fn = call.get("function") or {}
98
+ raw = fn.get("arguments") or "{}"
99
+ try:
100
+ args = json.loads(raw) if isinstance(raw, str) else dict(raw)
101
+ except ValueError:
102
+ args = {}
103
+ out["tool_calls"].append({"id": call.get("id", ""), "name": fn.get("name", ""),
104
+ "arguments": args})
105
+ out["stop"] = choice.get("finish_reason") or ""
106
+ return out
107
+
108
+
109
+ def _post(url: str, headers: dict[str, str], body: dict[str, Any], config: dict[str, Any],
110
+ timeout: float) -> dict[str, Any]:
111
+ host = (urlparse(url).hostname or "").lower()
112
+ proxies = {} if host in _LOCAL_HOSTS else proxy_dict(select_proxy_for_url(url, config))
113
+ resp = requests.post(url, headers={**headers, "User-Agent": user_agent()}, json=body,
114
+ timeout=timeout, proxies=proxies)
115
+ if resp.status_code >= 400:
116
+ detail = (resp.text or "").strip().replace("\n", " ")[:300]
117
+ raise RuntimeError(f"HTTP {resp.status_code}: {detail or resp.reason}")
118
+ return resp.json()
119
+
120
+
121
+ def chat(messages: list[dict[str, Any]], tools: list[dict[str, Any]] | None = None, *,
122
+ config: dict[str, Any] | None = None, system: str = "", max_tokens: int = 2048,
123
+ timeout: float = 120) -> dict[str, Any]:
124
+ """One round trip. ``tools`` are ``{"name", "description", "parameters"}``."""
125
+ cfg = model_config(config)
126
+ if not cfg["model"]:
127
+ raise ValueError("还没有填模型名")
128
+ if not cfg["api_key"] and cfg["protocol"] == "anthropic":
129
+ raise ValueError("还没有填 API Key")
130
+ if not system: # a system message passed in the list works too
131
+ system = "\n".join(m.get("content") or "" for m in messages
132
+ if m.get("role") == "system").strip()
133
+ body = _payload(cfg, messages, tools, max_tokens, system)
134
+ data = _post(_endpoint(cfg), _headers(cfg), body, config or {}, timeout)
135
+ return _parse(cfg, data)
136
+
137
+
138
+ _PING_TOOL = {
139
+ "name": "ping",
140
+ "description": "Answer with the given number. Call this instead of replying in text.",
141
+ "parameters": {"type": "object", "properties": {"n": {"type": "integer"}}, "required": ["n"]},
142
+ }
143
+
144
+
145
+ def test_model(config: dict[str, Any] | None = None, timeout: float = 30) -> dict[str, Any]:
146
+ """Ask the model to call a tool; that is the one thing a task runner needs."""
147
+ cfg = model_config(config)
148
+ if not cfg["model"]:
149
+ return {"ok": False, "detail": "还没有填模型名"}
150
+ if not cfg["api_key"] and cfg["protocol"] == "anthropic":
151
+ return {"ok": False, "detail": "还没有填 API Key"}
152
+ started = time.monotonic()
153
+ try:
154
+ reply = chat([{"role": "user", "content": "调用 ping,n 用 1。"}], [_PING_TOOL],
155
+ config=config, max_tokens=256, timeout=timeout)
156
+ except Exception as exc:
157
+ return {"ok": False, "detail": str(exc)[:300]}
158
+ took = time.monotonic() - started
159
+ name = f"{cfg['provider']} · {cfg['model']}"
160
+ calls = [c for c in reply["tool_calls"] if c["name"] == "ping"]
161
+ if not calls:
162
+ text = (reply["text"] or "").strip().replace("\n", " ")[:120]
163
+ return {"ok": False, "detail": f"{name} 没有发起工具调用(回了:{text or '空'}),不能用来跑任务"}
164
+ return {"ok": True, "detail": f"{name} 支持工具调用({took:.1f} 秒)"}
@@ -0,0 +1,123 @@
1
+ """Drive one task: ask the model, run the tools it calls, ask again.
2
+
3
+ The loop is protocol-agnostic; only the message shapes differ, so the runner
4
+ keeps a neutral transcript and converts it per turn. Tool functions are plain
5
+ callables that return JSON-serializable values; the schemas handed to the model
6
+ are the same ``{"name", "description", "parameters"}`` dicts ``chat()`` takes.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import json
12
+ from typing import Any, Callable
13
+
14
+ from .client import chat, model_config
15
+
16
+ Tool = Callable[..., Any]
17
+ EventHandler = Callable[[str, dict[str, Any]], None]
18
+
19
+
20
+ class ToolError(Exception):
21
+ """A tool the model asked for does not exist or could not do its job."""
22
+
23
+
24
+ def _json(value: Any) -> str:
25
+ if isinstance(value, str):
26
+ return value
27
+ try:
28
+ return json.dumps(value, ensure_ascii=False, default=str)
29
+ except (TypeError, ValueError):
30
+ return str(value)
31
+
32
+
33
+ def _call(tools: dict[str, Tool], name: str, arguments: dict[str, Any]) -> str:
34
+ fn = tools.get(name)
35
+ if fn is None:
36
+ raise ToolError(f"没有这个工具:{name}")
37
+ try:
38
+ return _json(fn(**arguments))
39
+ except TypeError as exc: # wrong or missing arguments
40
+ raise ToolError(f"{name} 的参数不对:{exc}") from exc
41
+
42
+
43
+ def _messages_for(protocol: str, transcript: list[dict[str, Any]]) -> list[dict[str, Any]]:
44
+ """Neutral turns -> the shape this protocol expects."""
45
+ out: list[dict[str, Any]] = []
46
+ for turn in transcript:
47
+ role = turn["role"]
48
+ if role in ("user", "system"):
49
+ out.append({"role": role, "content": turn.get("text", "")})
50
+ continue
51
+ calls = turn.get("calls") or []
52
+ if protocol == "anthropic":
53
+ blocks: list[dict[str, Any]] = []
54
+ if turn.get("text"):
55
+ blocks.append({"type": "text", "text": turn["text"]})
56
+ for call in calls:
57
+ blocks.append({"type": "tool_use", "id": call["id"], "name": call["name"],
58
+ "input": call["arguments"]})
59
+ if blocks:
60
+ out.append({"role": "assistant", "content": blocks})
61
+ results = [{"type": "tool_result", "tool_use_id": call["id"], "content": call["result"]}
62
+ for call in calls]
63
+ if results:
64
+ out.append({"role": "user", "content": results})
65
+ continue
66
+ out.append({"role": "assistant", "content": turn.get("text") or None,
67
+ "tool_calls": [{"id": call["id"], "type": "function",
68
+ "function": {"name": call["name"],
69
+ "arguments": _json(call["arguments"])}}
70
+ for call in calls]})
71
+ for call in calls:
72
+ out.append({"role": "tool", "tool_call_id": call["id"], "content": call["result"]})
73
+ return out
74
+
75
+
76
+ def run_task(goal: str, tools: list[dict[str, Any]], *, functions: dict[str, Tool] | None = None,
77
+ config: dict[str, Any] | None = None, system: str = "", max_steps: int = 8,
78
+ max_tokens: int = 4096, timeout: float = 180,
79
+ on_event: EventHandler | None = None) -> dict[str, Any]:
80
+ """Run until the model answers without calling a tool (or ``max_steps``)."""
81
+ protocol = model_config(config)["protocol"]
82
+ functions = functions or {}
83
+ transcript: list[dict[str, Any]] = [{"role": "user", "text": goal}]
84
+ produced: list[dict[str, Any]] = []
85
+
86
+ def emit(kind: str, **data: Any) -> None:
87
+ if on_event:
88
+ on_event(kind, data)
89
+
90
+ for step in range(1, max_steps + 1):
91
+ reply = chat(_messages_for(protocol, transcript), tools, config=config, system=system,
92
+ max_tokens=max_tokens, timeout=timeout)
93
+ text = (reply.get("text") or "").strip()
94
+ calls = reply.get("tool_calls") or []
95
+ if text:
96
+ emit("text", text=text, step=step)
97
+ if not calls:
98
+ transcript.append({"role": "assistant", "text": text})
99
+ return {"text": text, "steps": step, "tool_calls": produced,
100
+ "messages": _messages_for(protocol, transcript)}
101
+ for index, call in enumerate(calls):
102
+ name = call.get("name") or ""
103
+ # Some providers omit the id; a stable one keeps the next turn valid.
104
+ call["id"] = call.get("id") or f"call_{step}_{index}"
105
+ emit("tool", name=name, arguments=call.get("arguments") or {}, step=step)
106
+ try:
107
+ result = _call(functions, name, call.get("arguments") or {})
108
+ call["result"] = result
109
+ except ToolError as exc:
110
+ call["result"] = f"出错:{exc}"
111
+ emit("error", name=name, detail=str(exc), step=step)
112
+ except Exception as exc: # a tool blowing up must not end the task
113
+ call["result"] = f"出错:{type(exc).__name__}: {exc}"
114
+ emit("error", name=name, detail=str(exc), step=step)
115
+ emit("result", name=name, result=call["result"], step=step)
116
+ produced.append({"name": name, "arguments": call.get("arguments") or {},
117
+ "result": call["result"]})
118
+ transcript.append({"role": "assistant", "text": text, "calls": calls})
119
+
120
+ last = next((c["result"] for c in reversed(produced)), "")
121
+ return {"text": f"到 {max_steps} 步还没有给出结论。最后一步工具返回:{last[:500]}",
122
+ "steps": max_steps, "tool_calls": produced,
123
+ "messages": _messages_for(protocol, transcript)}
@@ -0,0 +1,54 @@
1
+ """The instructions a model needs before it can do what the LitLoop skill does.
2
+
3
+ An external Agent reads ``skills/`` and knows how to rate a paper and what a deep
4
+ search's batches look like. A model driven by this package does not, so the same
5
+ rules go in as a system prompt (2026-11-06: without it the built-in agent rated
6
+ papers with no rubric and stopped after one search).
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ SYSTEM = """你是 LitLoop 桌面 app 里的文献检索助手。用户不在对话里:不要提问、不要等确认,\
12
+ 需要用户决定的事写进最后的汇报。
13
+
14
+ ## 相关度
15
+
16
+ 只有四档:高 / 中 / 低 / 不相关。
17
+ - 高:研究对象、方法、关注点都符合纳入标准。
18
+ - 中:对象相同但方法或路线不同,或只覆盖问题的一部分,或与问题直接相关的综述。
19
+ - 低:方法相同但对象是相邻体系,或泛泛的综述、书章。
20
+ - 不相关:与问题无关。
21
+
22
+ 拿不准时往高评——漏掉一篇的代价比多读一篇大得多。只有标题时就凭标题判断,并在理由里注明\
23
+ 「仅凭标题」。不要编造摘要里没有的内容。每篇写一句中文理由,说明它对应哪条标准、缺了什么。
24
+
25
+ ## 快速查找
26
+
27
+ 1. 把问题拆成 2–5 条纳入标准(研究对象、关注现象、方法、文章类型、年份)。
28
+ 2. 用 `search` 检索:英文关键词,中文问题先译成英文;必要时换 2–3 组同义词分别搜。
29
+ 3. 读每篇的标题与摘要,逐篇评分。
30
+ 4. 用 `screening_save` 保存:不传 `session` 会新建一个筛选会话(这时必须传 `question` 当标题);
31
+ 每篇带上 `title`、`year`、`journal`,别只给 DOI。
32
+ 5. 用两三句中文汇报:定了哪几条标准、找到几篇、各相关度多少。
33
+
34
+ ## 深度检索
35
+
36
+ 1. 拟定 2–5 条纳入标准,以及 4–8 条英文检索词;同一个概念要照顾缩写、全称与同义词。
37
+ 2. 用 `deep_search_start` 建候选池,拿到 `session` 与第一批。
38
+ 3. **这一批每篇都要评**,优先用 `deep_search_rate` 传 `session` 与按编号 `n` 的评分(`ratings=[{n, relevance, reason}]`,无 DOI 的文献也能保存;也兼容 `screening_save`)。
39
+ 4. 用 `deep_search_next` 取下一批,重复第 3、4 步。
40
+ 5. 返回 `stop_suggested=true` 就停下来,把 `stop_reason` 写进汇报;用户给了批数上限就按上限停。
41
+ 6. **继续已有深度检索**(会话之前中断或刚补完一批):不要重新调用 `deep_search_start`。先调 `deep_search_status` 查看 `unrated` 与当前进度;有未评分文献时先用 `deep_search_rate` 评完,再调 `deep_search_next` 继续,直到 `stop_suggested=true` 或达到指定批数。
42
+ 7. 汇报:读了多少篇、各相关度数量、是否建议停、还漏什么。
43
+
44
+ ## 规则
45
+
46
+ - 不要下载 PDF,不要往 Zotero 写东西。
47
+ - 不要编造 DOI、标题、年份或摘要里没有的结论。
48
+ - 数字与单位照原文写,不要换算。
49
+ """
50
+
51
+
52
+ def system_prompt() -> str:
53
+ """The system message this package sends with every task."""
54
+ return SYSTEM