zorsch 0.2.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.
zoresearch/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ """zoresearch — personal research copilot over a local Zotero library."""
2
+
3
+ __version__ = "0.1.0"
zoresearch/cli.py ADDED
@@ -0,0 +1,447 @@
1
+ """``zr`` CLI entrypoint."""
2
+ from __future__ import annotations
3
+
4
+ import json
5
+ import sys
6
+ from pathlib import Path
7
+
8
+ import typer
9
+ from rich.console import Console
10
+ from rich.table import Table
11
+
12
+ from . import import_, lore, notes as notes_mod, openalex, parse as parse_mod, related as related_mod, workspace as ws, zot
13
+ from .config import CONFIG, USER_CONFIG
14
+ from .paths import DATA, NOTES, ROOT, TRANSCRIPTS, WORKSPACE, ZOTERO_DB, ensure_dirs
15
+
16
+ app = typer.Typer(
17
+ no_args_is_help=True,
18
+ add_completion=False,
19
+ help="zoresearch: research tools on top of a local Zotero library.",
20
+ )
21
+ lib_app = typer.Typer(no_args_is_help=True, help="Browse and search the library.")
22
+ ws_app = typer.Typer(no_args_is_help=True, help="Research-question workspaces.")
23
+ app.add_typer(lib_app, name="lib")
24
+ app.add_typer(ws_app, name="ws")
25
+
26
+ console = Console()
27
+
28
+
29
+ # ---------- top-level commands ----------------------------------------------
30
+
31
+
32
+ @app.command()
33
+ def doctor():
34
+ """Run environment checks: Zotero, BBT, MinerU, deps."""
35
+ ensure_dirs()
36
+ rows: list[tuple[str, str, str]] = []
37
+ rows.append(("data root", "info", str(ROOT)))
38
+ rows.append(("Zotero db", "ok" if ZOTERO_DB.exists() else "missing", str(ZOTERO_DB)))
39
+ if ZOTERO_DB.exists():
40
+ st = zot.stats()
41
+ rows.append(("library size", "info", f"{sum(st['by_type'].values())} papers, {st['pdf_attachments']} PDFs"))
42
+ rows.append(("Zotero running", "ok" if zot.zotero_running() else "off", "needed for import"))
43
+ try:
44
+ zot.bbt_rpc("user.groups")
45
+ rows.append(("Better BibTeX", "ok", "JSON-RPC reachable"))
46
+ except Exception as e: # noqa: BLE001
47
+ rows.append(("Better BibTeX", "warn", f"{e}"))
48
+ rows.append(
49
+ (
50
+ "MinerU token",
51
+ "ok" if CONFIG.mineru.token else "missing",
52
+ f"config at {USER_CONFIG}",
53
+ )
54
+ )
55
+ try:
56
+ import pymupdf4llm # noqa: F401
57
+ rows.append(("pymupdf4llm", "ok", ""))
58
+ except Exception as e: # noqa: BLE001
59
+ rows.append(("pymupdf4llm", "warn", str(e)))
60
+
61
+ table = Table(
62
+ title=f"[{lore.ACCENT} bold]zr diagnostics[/{lore.ACCENT} bold]",
63
+ border_style=lore.DIM,
64
+ title_style=lore.ACCENT,
65
+ )
66
+ table.add_column("check", style=lore.ACCENT)
67
+ table.add_column("status")
68
+ table.add_column("detail", style="dim")
69
+ statuses = [s for _, s, _ in rows]
70
+ for k, s, d in rows:
71
+ table.add_row(k, lore.status_icon(s), d)
72
+ console.print(table)
73
+ all_ok = all(s in ("ok", "info") for s in statuses)
74
+ console.print(
75
+ f"[{lore.SUCCESS if all_ok else lore.HIGHLIGHT}]"
76
+ f"{lore.OK_MARK if all_ok else lore.WARN_MARK} "
77
+ f"{lore.say('doctor_ready' if all_ok else 'doctor_partial')}"
78
+ f"[/{lore.SUCCESS if all_ok else lore.HIGHLIGHT}]"
79
+ )
80
+
81
+
82
+ @app.command()
83
+ def show(key_or_citekey: str = typer.Argument(..., help="Zotero item key or BBT citekey")):
84
+ """Show metadata, abstract, attachment paths, and existing notes."""
85
+ item = zot.get_item(key_or_citekey)
86
+ if item is None:
87
+ console.print(lore.err(f"not found: {key_or_citekey}"))
88
+ raise typer.Exit(1)
89
+ cyan = lore.ACCENT
90
+ dim = lore.DIM
91
+ console.print(f"[{cyan} bold]{lore.BULLET} {item.title}[/{cyan} bold]")
92
+ console.print(f" [{dim}]type [/{dim}] {item.item_type}")
93
+ console.print(f" [{dim}]authors [/{dim}] {', '.join(item.creators) or '—'}")
94
+ console.print(f" [{dim}]year [/{dim}] {item.year or '—'}")
95
+ console.print(f" [{dim}]venue [/{dim}] {item.publication or '—'}")
96
+ console.print(f" [{dim}]doi [/{dim}] {item.doi or '—'}")
97
+ console.print(f" [{dim}]key [/{dim}] [{cyan}]{item.key}[/{cyan}]")
98
+ if item.citekey:
99
+ console.print(f" [{dim}]citekey [/{dim}] {item.citekey}")
100
+ if item.tags:
101
+ console.print(f" [{dim}]glyphs [/{dim}] {', '.join(item.tags)}")
102
+ if item.collections:
103
+ console.print(f" [{dim}]filed in [/{dim}] {', '.join(item.collections)}")
104
+ pdfs = zot.attachments(item.key)
105
+ if pdfs:
106
+ console.print(f" [{dim}]tome [/{dim}]")
107
+ for p in pdfs:
108
+ console.print(f" {p}")
109
+ transcript = TRANSCRIPTS / item.key / "paper.md"
110
+ if transcript.exists():
111
+ console.print(f" [{dim}]transcript[/{dim}] [{lore.SUCCESS}]{lore.OK_MARK}[/{lore.SUCCESS}] {transcript}")
112
+ if item.abstract:
113
+ console.print(f"\n[{cyan} bold]{lore.BULLET} {lore.say('section_abstract')}[/{cyan} bold]")
114
+ console.print(item.abstract)
115
+ n = notes_mod.read(item.key)
116
+ if n:
117
+ console.print(f"\n[{cyan} bold]{lore.BULLET} {lore.say('section_notes')}[/{cyan} bold]")
118
+ console.print(n)
119
+
120
+
121
+ @app.command()
122
+ def parse(
123
+ key: str = typer.Argument(..., help="Zotero item key or citekey"),
124
+ engine: str = typer.Option(None, "--engine", "-e", help="mineru | pymupdf"),
125
+ force: bool = typer.Option(False, "--force", "-f"),
126
+ ):
127
+ """Run the PDF -> Markdown pipeline for an item."""
128
+ ensure_dirs()
129
+ res = parse_mod.parse_item(key, engine=engine, force=force)
130
+ phrase = "parse_cached" if res.engine == "cache" else "parse_done"
131
+ console.print(lore.ok(f"{lore.say(phrase)} engine={res.engine} out={res.markdown_path}"))
132
+
133
+
134
+ @app.command()
135
+ def annotations(key: str):
136
+ """Show user highlights and notes attached to a paper's PDF."""
137
+ rows = zot.annotations(key)
138
+ if not rows:
139
+ console.print("(no annotations)")
140
+ return
141
+ for a in rows:
142
+ marker = {"highlight": "▌", "note": "✎", "underline": "_"}.get(a["type"], "•")
143
+ page = f"p.{a['page']}" if a["page"] else ""
144
+ console.print(f"[dim]{page:<6}[/dim] {marker} {a['text']}")
145
+ if a["comment"]:
146
+ console.print(f" [yellow]→ {a['comment']}[/yellow]")
147
+
148
+
149
+ @app.command(name="import")
150
+ def import_cmd(
151
+ value: str = typer.Argument(..., help="DOI, arXiv id, URL, or a .ris file whose records link local PDFs (L1)"),
152
+ collection: str = typer.Option(None, "--collection", "-c", help="Zotero collection name to file the item under"),
153
+ ):
154
+ """Fetch metadata + PDF and add to Zotero (optionally into a collection)."""
155
+ console.print(lore.say("import_pending"))
156
+ if value.lower().endswith(".ris") and Path(value).is_file():
157
+ failed = False
158
+ for res in import_.import_ris(Path(value), collection=collection):
159
+ mark = lore.ok if res.item_saved and not res.error else lore.err
160
+ pdf = "PDF ✓" if res.pdf_attached else "PDF ✗"
161
+ console.print(mark(f"{res.metadata.get('title', '?')} [{pdf}] {res.error}"))
162
+ failed |= bool(res.error) or not res.item_saved
163
+ raise typer.Exit(1 if failed else 0)
164
+ res = import_.import_one(value, collection=collection)
165
+ if res.error and not res.item_saved:
166
+ console.print(lore.err(res.error))
167
+ raise typer.Exit(1)
168
+ bits = []
169
+ if res.item_saved: bits.append("metadata ✓")
170
+ if res.pdf_attached: bits.append("PDF ✓")
171
+ elif res.target.kind == "arxiv": bits.append("PDF ✗")
172
+ else: bits.append("PDF (none — likely paywall)")
173
+ console.print(lore.ok(f"{lore.say('import_added')} {res.target.url} [{', '.join(bits)}]"))
174
+ if res.error and res.item_saved:
175
+ console.print(lore.warn(res.error))
176
+ if res.metadata.get("title"):
177
+ console.print(f" [{lore.DIM}]title:[/{lore.DIM}] {res.metadata['title']}")
178
+
179
+
180
+ @app.command()
181
+ def related(
182
+ key: str,
183
+ out: Path = typer.Option(None, "--out", "-o", help="Write Markdown ranking to this file"),
184
+ top: int = typer.Option(50, "--top", "-n"),
185
+ ):
186
+ """Pull OpenAlex backward refs + forward citations for an item, ranked."""
187
+ ensure_dirs()
188
+ works = related_mod.rank(related_mod.for_item(key))[:top]
189
+ if out:
190
+ with out.open("w", encoding="utf-8") as f:
191
+ f.write(f"# Related work for {key}\n\n")
192
+ for w in works:
193
+ f.write(f"- {w.line()}\n")
194
+ if w.doi:
195
+ f.write(f" doi: {w.doi}\n")
196
+ if w.abstract:
197
+ f.write(f" {w.abstract[:300]}\n")
198
+ console.print(lore.ok(f"{lore.say('related_done')} — {len(works)} signals → {out}"))
199
+ return
200
+ console.print(f"[dim]{lore.say('related_done')} — {len(works)} signals[/dim]")
201
+ for w in works:
202
+ console.print(w.line())
203
+
204
+
205
+ @app.command()
206
+ def trends(
207
+ topic: str = typer.Argument(..., help="Free-text topic / question"),
208
+ n: int = typer.Option(50, "--n"),
209
+ ):
210
+ """Quick OpenAlex pull for a topic — venues, years, top-cited."""
211
+ works = openalex.search(topic, per_page=min(n, 50), max_pages=max(1, n // 50))
212
+ if not works:
213
+ console.print("(no hits)")
214
+ return
215
+ by_year: dict[int, int] = {}
216
+ venues: dict[str, int] = {}
217
+ for w in works:
218
+ s = openalex.shallow(w)
219
+ if s.get("year"):
220
+ by_year[s["year"]] = by_year.get(s["year"], 0) + 1
221
+ if s.get("venue"):
222
+ venues[s["venue"]] = venues.get(s["venue"], 0) + 1
223
+ console.print(f"[bold]{lore.say('trends_done')}:[/bold] {topic} (n={len(works)})\n")
224
+ console.print("[bold]Years[/bold]")
225
+ for y in sorted(by_year):
226
+ console.print(f" {y}: {'█' * by_year[y]} {by_year[y]}")
227
+ console.print("\n[bold]Top venues[/bold]")
228
+ for v, c in sorted(venues.items(), key=lambda x: -x[1])[:8]:
229
+ console.print(f" {c:>3} {v}")
230
+ console.print("\n[bold]Top-cited[/bold]")
231
+ top_cited = sorted(works, key=lambda w: -(w.get("cited_by_count") or 0))[:10]
232
+ for w in top_cited:
233
+ s = openalex.shallow(w)
234
+ a = s["authors"][0].split()[-1] if s["authors"] else "Anon"
235
+ console.print(f" [{s['cited_by_count']:>5}cit] {a} {s['year']} — {s['title'][:90]}")
236
+
237
+
238
+ @app.command()
239
+ def notes(
240
+ key: str,
241
+ append: str = typer.Option("", "--append", "-a"),
242
+ source: str = typer.Option("agent", "--source"),
243
+ kind: str = typer.Option("analysis", "--kind"),
244
+ ):
245
+ """Read or append per-paper notes."""
246
+ if append:
247
+ p = notes_mod.append(key, append, source=source, kind=kind)
248
+ console.print(lore.ok(f"{lore.say('notes_appended')} → {p}"))
249
+ return
250
+ body = notes_mod.read(key)
251
+ if not body:
252
+ console.print(lore.say("notes_empty"))
253
+ return
254
+ console.print(body)
255
+
256
+
257
+ # ---------- lib ---------------------------------------------------------------
258
+
259
+
260
+ @lib_app.command("stats")
261
+ def lib_stats():
262
+ """Counts by type, attachment / annotation totals, collections."""
263
+ s = zot.stats()
264
+ table = Table(
265
+ title=f"[{lore.ACCENT} bold]{lore.BULLET} {lore.say('lib_overview')}[/{lore.ACCENT} bold]",
266
+ border_style=lore.DIM,
267
+ )
268
+ table.add_column("entry", style=lore.ACCENT)
269
+ table.add_column("count", justify="right", style=lore.HIGHLIGHT)
270
+ for t, n in s["by_type"].items():
271
+ table.add_row(t, str(n))
272
+ table.add_row("pdf tomes", str(s["pdf_attachments"]))
273
+ table.add_row("annotations", str(s["annotations"]))
274
+ table.add_row("collections", str(s["collections"]))
275
+ console.print(table)
276
+
277
+
278
+ @lib_app.command("search")
279
+ def lib_search(
280
+ query: str,
281
+ limit: int = typer.Option(25, "--limit", "-n"),
282
+ ):
283
+ """Substring search over title / abstract / tags."""
284
+ items = zot.search(query, limit=limit)
285
+ if not items:
286
+ console.print("(no matches)")
287
+ return
288
+ for item in items:
289
+ console.print(f"[cyan]{item.key}[/cyan] {item.short()}")
290
+
291
+
292
+ @lib_app.command("list")
293
+ def lib_list(
294
+ collection: str = typer.Option(None, "--collection", "-c"),
295
+ type_: str = typer.Option(None, "--type", "-t"),
296
+ limit: int = typer.Option(50, "--limit", "-n"),
297
+ ):
298
+ """List items, optionally filtered by collection or item type."""
299
+ types = (type_,) if type_ else zot.PAPER_TYPES
300
+ for item in zot.iter_items(types=types, collection=collection, limit=limit):
301
+ console.print(f"[cyan]{item.key}[/cyan] {item.short()}")
302
+
303
+
304
+ @lib_app.command("collections")
305
+ def lib_collections():
306
+ """List collections and their item counts."""
307
+ for name, n in zot.collections():
308
+ console.print(f" {n:>4} {name}")
309
+
310
+
311
+ # ---------- workspace --------------------------------------------------------
312
+
313
+
314
+ @ws_app.command("init")
315
+ def ws_init(name: str, question: str = typer.Option("", "--question", "-q")):
316
+ """Set up a new workspace for a research question."""
317
+ p = ws.init(name, question=question)
318
+ console.print(lore.ok(f"{lore.say('ws_created')} → {p}"))
319
+
320
+
321
+ @ws_app.command("list")
322
+ def ws_list():
323
+ for n in ws.list_workspaces():
324
+ console.print(f" {n}")
325
+
326
+
327
+ @ws_app.command("add")
328
+ def ws_add(name: str, seed: str):
329
+ """Add a seed paper (Zotero key / citekey / DOI / arXiv id) to the workspace."""
330
+ p = ws.add_seed(name, seed)
331
+ console.print(lore.ok(f"{lore.say('ws_seed_added')} → {p}"))
332
+
333
+
334
+ @ws_app.command("show")
335
+ def ws_show(name: str):
336
+ w = ws.load(name)
337
+ console.print(f"[bold]{w.name}[/bold] ({w.path})\n")
338
+ console.print(w.question)
339
+ console.print("\n[bold]Seeds[/bold]")
340
+ for s in w.seeds:
341
+ console.print(f" {s}")
342
+
343
+
344
+ @ws_app.command("parse")
345
+ def ws_parse(
346
+ name: str,
347
+ engine: str = typer.Option(None, "--engine", "-e", help="mineru | pymupdf"),
348
+ yes: bool = typer.Option(False, "--yes", "-y", help="actually run; without this, only previews"),
349
+ force: bool = typer.Option(False, "--force", "-f"),
350
+ ):
351
+ """Parse the seed papers of a workspace — and only those.
352
+
353
+ By default this previews what would be parsed and exits. Pass ``--yes`` to
354
+ actually run. We never parse the full ``related.md`` — the workspace's
355
+ seeds.txt is the deliberate "papers I want to deep-read" list; everything
356
+ else stays at metadata + abstract.
357
+ """
358
+ w = ws.load(name)
359
+ todo: list[str] = []
360
+ for seed in w.seeds:
361
+ item = zot.get_item(seed)
362
+ if item is None:
363
+ console.print(lore.warn(f"skip {seed}: not in Zotero"))
364
+ continue
365
+ transcript = TRANSCRIPTS / item.key / "paper.md"
366
+ if transcript.exists() and not force:
367
+ continue
368
+ if not [p for p in zot.attachments(item.key) if p.suffix.lower() == ".pdf"]:
369
+ console.print(lore.warn(f"skip {item.key}: no PDF attachment"))
370
+ continue
371
+ todo.append(item.key)
372
+ if not todo:
373
+ console.print(lore.ok("nothing to parse — every seed already has a transcript"))
374
+ return
375
+ chosen = (engine or CONFIG.parse_engine).lower()
376
+ console.print(
377
+ f"[{lore.ACCENT}]would parse {len(todo)} paper(s) "
378
+ f"with engine={chosen}:[/{lore.ACCENT}]"
379
+ )
380
+ for key in todo:
381
+ item = zot.get_item(key)
382
+ console.print(f" [{lore.HIGHLIGHT}]{lore.WARN_MARK}[/{lore.HIGHLIGHT}] {key} {item.short() if item else ''}")
383
+ if not yes:
384
+ console.print(lore.info("preview only — pass --yes to run"))
385
+ return
386
+ for key in todo:
387
+ try:
388
+ res = parse_mod.parse_item(key, engine=engine, force=force)
389
+ console.print(lore.ok(f"{lore.say('parse_done')} {key} ({res.engine})"))
390
+ except Exception as e: # noqa: BLE001
391
+ console.print(lore.err(f"{key}: {e}"))
392
+
393
+
394
+ @ws_app.command("related")
395
+ def ws_related(name: str, top: int = typer.Option(40, "--top", "-n")):
396
+ """Build / refresh ``related.md`` for a workspace from its seeds."""
397
+ w = ws.load(name)
398
+ all_works: list[related_mod.RelatedWork] = []
399
+ for seed in w.seeds:
400
+ try:
401
+ all_works.extend(related_mod.for_item(seed))
402
+ except ValueError as e:
403
+ console.print(f"[yellow]skip[/yellow] {seed}: {e}")
404
+ seen: set[str] = set()
405
+ deduped: list[related_mod.RelatedWork] = []
406
+ for r in all_works:
407
+ ident = r.doi.lower() or r.title.lower()
408
+ if ident in seen:
409
+ continue
410
+ seen.add(ident)
411
+ deduped.append(r)
412
+ deduped = related_mod.rank(deduped)[:top]
413
+ out = w.path / "related.md"
414
+ with out.open("w", encoding="utf-8") as f:
415
+ f.write(f"# Related work — {w.name}\n\n")
416
+ f.write(f"_n={len(deduped)} from {len(w.seeds)} seeds_\n\n")
417
+ for r in deduped:
418
+ f.write(f"- {r.line()}\n")
419
+ if r.doi:
420
+ f.write(f" doi: {r.doi}\n")
421
+ if r.abstract:
422
+ f.write(f" {r.abstract[:280]}\n")
423
+ console.print(lore.ok(f"{lore.say('ws_related_done')} — {len(deduped)} signals → {out}"))
424
+
425
+
426
+ @app.command()
427
+ def web(
428
+ port: int = typer.Option(8765, "--port", "-p", help="port to bind"),
429
+ host: str = typer.Option("127.0.0.1", "--host", help="host to bind"),
430
+ no_open: bool = typer.Option(False, "--no-open", help="do not auto-open browser"),
431
+ ):
432
+ """Open workspaces in a browser, with KaTeX and Zotero citation links."""
433
+ try:
434
+ from . import web as web_mod
435
+ except ImportError as e:
436
+ console.print(f"[red]web reader needs extra deps:[/red] {e}")
437
+ console.print("install with: [cyan]pip install starlette uvicorn markdown-it-py mdit-py-plugins[/cyan]")
438
+ raise typer.Exit(1)
439
+ console.print(f"[green]zr web running[/green] → http://{host}:{port}/")
440
+ if not no_open:
441
+ console.print("opening browser…")
442
+ web_mod.serve(host=host, port=port, open_browser=not no_open)
443
+
444
+
445
+
446
+ if __name__ == "__main__":
447
+ app()
zoresearch/config.py ADDED
@@ -0,0 +1,72 @@
1
+ """Config loader. Reads ~/.zoresearch/config.toml + a few env vars.
2
+
3
+ The user-scoped config lives **outside** the repo so secrets cannot leak through
4
+ git. Order of precedence:
5
+
6
+ env > ~/.zoresearch/config.toml > built-in defaults
7
+ """
8
+ from __future__ import annotations
9
+
10
+ import os
11
+ import sys
12
+ import tomllib
13
+ from dataclasses import dataclass, field
14
+ from pathlib import Path
15
+ from typing import Any
16
+
17
+ USER_CONFIG = Path.home() / ".zoresearch" / "config.toml"
18
+
19
+
20
+ def _load_user_config() -> dict[str, Any]:
21
+ if not USER_CONFIG.exists():
22
+ return {}
23
+ with USER_CONFIG.open("rb") as f:
24
+ return tomllib.load(f)
25
+
26
+
27
+ @dataclass
28
+ class MinerUConfig:
29
+ token: str = ""
30
+ endpoint: str = "https://mineru.net/api/v4"
31
+ enable_formula: bool = True
32
+ enable_table: bool = True
33
+ language: str = "auto"
34
+
35
+
36
+ @dataclass
37
+ class Config:
38
+ mineru: MinerUConfig = field(default_factory=MinerUConfig)
39
+ default_engine: str = "mineru"
40
+
41
+ @property
42
+ def parse_engine(self) -> str:
43
+ return os.environ.get("ZORESEARCH_ENGINE", self.default_engine)
44
+
45
+
46
+ def load() -> Config:
47
+ raw = _load_user_config()
48
+ m = raw.get("mineru", {})
49
+ p = raw.get("parse", {})
50
+ cfg = Config(
51
+ mineru=MinerUConfig(
52
+ token=os.environ.get("MINERU_TOKEN") or m.get("token", ""),
53
+ endpoint=m.get("endpoint", "https://mineru.net/api/v4"),
54
+ enable_formula=p.get("enable_formula", True),
55
+ enable_table=p.get("enable_table", True),
56
+ language=p.get("language", "auto"),
57
+ ),
58
+ default_engine=m.get("default_engine", "mineru"),
59
+ )
60
+ return cfg
61
+
62
+
63
+ CONFIG: Config = load()
64
+
65
+
66
+ def warn_no_token() -> None:
67
+ if not CONFIG.mineru.token:
68
+ print(
69
+ "warning: no MinerU token configured. "
70
+ f"Set MINERU_TOKEN in env or write [mineru].token to {USER_CONFIG}",
71
+ file=sys.stderr,
72
+ )