zorsch 0.2.0__tar.gz

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.
zorsch-0.2.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 wheatfox
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
zorsch-0.2.0/PKG-INFO ADDED
@@ -0,0 +1,163 @@
1
+ Metadata-Version: 2.4
2
+ Name: zorsch
3
+ Version: 0.2.0
4
+ Summary: A research copilot CLI (zr) built on a local Zotero library.
5
+ Author: wheatfox
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/enkerewpo/zoresearch
8
+ Requires-Python: >=3.10
9
+ Description-Content-Type: text/markdown
10
+ License-File: LICENSE
11
+ Requires-Dist: typer>=0.12
12
+ Requires-Dist: rich>=13.7
13
+ Requires-Dist: httpx>=0.27
14
+ Requires-Dist: pymupdf>=1.24
15
+ Requires-Dist: pymupdf4llm>=0.0.17
16
+ Requires-Dist: platformdirs>=4.2
17
+ Provides-Extra: mineru
18
+ Requires-Dist: mineru-open-api>=0.1; extra == "mineru"
19
+ Provides-Extra: embed
20
+ Requires-Dist: sentence-transformers>=3.0; extra == "embed"
21
+ Requires-Dist: numpy>=1.26; extra == "embed"
22
+ Provides-Extra: web
23
+ Requires-Dist: starlette>=0.37; extra == "web"
24
+ Requires-Dist: uvicorn>=0.30; extra == "web"
25
+ Requires-Dist: markdown-it-py>=3.0; extra == "web"
26
+ Requires-Dist: mdit-py-plugins>=0.4; extra == "web"
27
+ Dynamic: license-file
28
+
29
+ <p align="center"><img src="assets/logo.svg" width="128" alt="zoresearch logo"/></p>
30
+
31
+ # zoresearch
32
+
33
+ A small research copilot built on top of a local Zotero library. It browses what you already have, finds the related work you don't, keeps workspaces around a research question, and keeps durable per-paper notes.
34
+
35
+ Zotero stays the source of truth — `zotero.sqlite` is read-only from this tool's perspective, and any new items are pushed in through Zotero's own connector API. Nothing in `~/Zotero/` gets rewritten by hand.
36
+
37
+ ## What it does
38
+
39
+ The `zr` CLI is the load-bearing layer; the skills under `.agents/skills/` are thin orchestration on top, so the same workflows run by hand or driven by any coding agent (Codex, Claude Code, and others that read `AGENTS.md` and `SKILL.md`).
40
+
41
+ - **Browse & search** your existing library by topic, author, year, or collection.
42
+ - **Parse PDFs** into multimodal Markdown transcripts (figures + tables preserved) that an LLM can actually reason over — MinerU as the default engine, `pymupdf4llm` as the zero-config fallback.
43
+ - **Find related work** via a citation graph (OpenAlex) for a seed paper or a whole workspace, deduplicated against your library, and **import** the missing items back into Zotero.
44
+ - **Analyse trends & gaps** for a topic, grounded in your own library plus OpenAlex.
45
+ - **Keep per-paper notes** that survive across sessions.
46
+ - **Read in the browser** — `zr web` serves your workspaces as a clean reader with KaTeX math, syntax highlighting, and clickable citation links, and renders any `format: slides` document as a self-contained 16:9 slide deck (print-to-PDF ready).
47
+
48
+ ## Install
49
+
50
+ ```bash
51
+ pip install zorsch # core CLI, installs the `zr` command
52
+ pip install "zorsch[web]" # + browser reader / slides (zr web)
53
+ pip install "zorsch[mineru]" # + MinerU PDF engine (zr parse)
54
+ pip install "zorsch[embed]" # + local embeddings (optional)
55
+ ```
56
+
57
+ Installed this way, `data/` and `workspace/` live in the per-user data directory (on macOS `~/Library/Application Support/zorsch`). Set `ZORESEARCH_HOME` to put them elsewhere. From a source checkout, `pip install -e .` keeps them inside the repository.
58
+
59
+ Requires Python 3.10+ and a local Zotero install. Zotero must be **running** for imports (they go through the connector API). The [Better BibTeX](https://retorque.re/zotero-better-bibtex/) plugin is recommended for stable citekeys.
60
+
61
+ ## Quick start
62
+
63
+ ```bash
64
+ zr doctor # check Zotero / BBT / MinerU wiring
65
+ zr lib stats # library overview
66
+ zr lib search "embodied" # keyword search across title/abstract/tags
67
+ zr show <key|citekey> # metadata + abstract + attachment + notes
68
+
69
+ zr ws init paper -q "How do VLAs handle mid-execution task switching?"
70
+ zr ws add paper 2506.03574 # plant a seed (Zotero key / DOI / arXiv id / url)
71
+ zr ws related paper # rebuild related.md from all seeds
72
+ zr ws parse paper --yes # parse ONLY this workspace's seeds (preview without --yes)
73
+
74
+ zr web # read everything in the browser at 127.0.0.1:8765
75
+ ```
76
+
77
+ Open the directory with a coding agent: it reads `AGENTS.md` and the skills under `.agents/skills/`. Describe a research question in natural language and the agent drives the CLI for you. Claude Code finds the same skills through the `.claude/skills` link.
78
+
79
+ ## Command reference
80
+
81
+ | Command | Purpose |
82
+ |---|---|
83
+ | `zr doctor` | environment checks (Zotero DB, BBT, MinerU token) |
84
+ | `zr lib stats` | library overview |
85
+ | `zr lib search <q> [--type ...]` | keyword search across title / abstract / tags |
86
+ | `zr lib list --collection <name>` | items in a collection |
87
+ | `zr lib collections` | list collections |
88
+ | `zr show <key\|citekey>` | metadata + abstract + attachment + notes |
89
+ | `zr parse <key> [--engine mineru\|pymupdf]` | PDF → `data/transcripts/<key>/paper.md` |
90
+ | `zr annotations <key>` | your highlights & notes from the PDF |
91
+ | `zr related <key>` | backward refs + forward citations, deduped vs library |
92
+ | `zr trends "<topic>"` | OpenAlex pull (years, venues, top-cited) |
93
+ | `zr import <doi\|arxiv\|url\|file.ris>` | add to Zotero via the connector; a `.ris` file adds hand-written records with their local PDFs (`L1`) |
94
+ | `zr notes <key> [--append "..."]` | durable per-paper notes |
95
+ | `zr ws init <name> [-q "..."]` | create a workspace for a question |
96
+ | `zr ws add <name> <seed>` | add a seed paper (Zotero key / DOI / arXiv / url) |
97
+ | `zr ws list` / `zr ws show <name>` | list / inspect workspaces |
98
+ | `zr ws related <name> [-n N]` | rebuild `related.md` from all seeds |
99
+ | `zr ws parse <name> [--yes]` | parse only this workspace's seeds (preview by default) |
100
+ | `zr web [--port P] [--host H] [--no-open]` | browser reader + slide decks |
101
+
102
+ Set `ZORESEARCH_PLAIN=1` for output without colours.
103
+
104
+ ## Reading in the browser
105
+
106
+ ```bash
107
+ zr web # serves http://127.0.0.1:8765
108
+ ```
109
+
110
+ The reader renders every Markdown file under `workspace/` with KaTeX math, highlighted code, and citation links that resolve back to Zotero / arXiv. A document whose front-matter sets `format: slides` is rendered as a presentation instead:
111
+
112
+ ```markdown
113
+ ---
114
+ format: slides
115
+ title: My talk
116
+ ---
117
+ # Title slide
118
+
119
+ ---
120
+ ## A content slide
121
+ - bullets, math $E=mc^2$, images, `<video>` all work
122
+
123
+ left column
124
+ :::
125
+ right column
126
+ ```
127
+
128
+ - `---` on its own line separates slides; `:::` splits a slide into columns.
129
+ - Decks are letterboxed to a fixed **16:9** stage, so they look identical on any screen.
130
+ - `F` toggles fullscreen, `← / →` / `Space` navigate, `⌘P` prints the deck straight to a 1280×720 PDF.
131
+ - A theme toggle (light / dark) sits in the corner and is remembered across reloads.
132
+
133
+ ## Layout
134
+
135
+ ```
136
+ zoresearch/
137
+ src/zoresearch/ # python package — the CLI and web reader live here
138
+ .agents/skills/ # agent skills (one SKILL.md per skill); .claude/skills links here
139
+ data/ # local cache (gitignored, rebuildable)
140
+ transcripts/<key>/ # parsed PDFs as markdown + extracted images
141
+ citations/ # OpenAlex response cache
142
+ notes/<key>.md # per-paper notes the agent appends to
143
+ workspace/ # research projects (gitignored)
144
+ <project>/
145
+ question.md # your framing of the question
146
+ seeds.txt # Zotero keys / DOIs / arXiv ids to start from
147
+ related.md # discovered work
148
+ notes.md # synthesis
149
+ ```
150
+
151
+ See [DEVELOPMENT.md](DEVELOPMENT.md) for the module map, data flow, and how to add a command or a skill.
152
+
153
+ ## Notes
154
+
155
+ - Developed and tested on macOS.
156
+ - The MinerU token lives at `~/.zoresearch/config.toml` (mode `600`, outside the repo).
157
+ - The citation graph uses OpenAlex — no API key required.
158
+ - This tool **never** writes to `~/Zotero/zotero.sqlite`; imports go through the connector API, which is why Zotero has to be running.
159
+ - `data/` and `workspace/` are rebuildable / personal and are gitignored.
160
+
161
+ ## License
162
+
163
+ MIT.
zorsch-0.2.0/README.md ADDED
@@ -0,0 +1,135 @@
1
+ <p align="center"><img src="assets/logo.svg" width="128" alt="zoresearch logo"/></p>
2
+
3
+ # zoresearch
4
+
5
+ A small research copilot built on top of a local Zotero library. It browses what you already have, finds the related work you don't, keeps workspaces around a research question, and keeps durable per-paper notes.
6
+
7
+ Zotero stays the source of truth — `zotero.sqlite` is read-only from this tool's perspective, and any new items are pushed in through Zotero's own connector API. Nothing in `~/Zotero/` gets rewritten by hand.
8
+
9
+ ## What it does
10
+
11
+ The `zr` CLI is the load-bearing layer; the skills under `.agents/skills/` are thin orchestration on top, so the same workflows run by hand or driven by any coding agent (Codex, Claude Code, and others that read `AGENTS.md` and `SKILL.md`).
12
+
13
+ - **Browse & search** your existing library by topic, author, year, or collection.
14
+ - **Parse PDFs** into multimodal Markdown transcripts (figures + tables preserved) that an LLM can actually reason over — MinerU as the default engine, `pymupdf4llm` as the zero-config fallback.
15
+ - **Find related work** via a citation graph (OpenAlex) for a seed paper or a whole workspace, deduplicated against your library, and **import** the missing items back into Zotero.
16
+ - **Analyse trends & gaps** for a topic, grounded in your own library plus OpenAlex.
17
+ - **Keep per-paper notes** that survive across sessions.
18
+ - **Read in the browser** — `zr web` serves your workspaces as a clean reader with KaTeX math, syntax highlighting, and clickable citation links, and renders any `format: slides` document as a self-contained 16:9 slide deck (print-to-PDF ready).
19
+
20
+ ## Install
21
+
22
+ ```bash
23
+ pip install zorsch # core CLI, installs the `zr` command
24
+ pip install "zorsch[web]" # + browser reader / slides (zr web)
25
+ pip install "zorsch[mineru]" # + MinerU PDF engine (zr parse)
26
+ pip install "zorsch[embed]" # + local embeddings (optional)
27
+ ```
28
+
29
+ Installed this way, `data/` and `workspace/` live in the per-user data directory (on macOS `~/Library/Application Support/zorsch`). Set `ZORESEARCH_HOME` to put them elsewhere. From a source checkout, `pip install -e .` keeps them inside the repository.
30
+
31
+ Requires Python 3.10+ and a local Zotero install. Zotero must be **running** for imports (they go through the connector API). The [Better BibTeX](https://retorque.re/zotero-better-bibtex/) plugin is recommended for stable citekeys.
32
+
33
+ ## Quick start
34
+
35
+ ```bash
36
+ zr doctor # check Zotero / BBT / MinerU wiring
37
+ zr lib stats # library overview
38
+ zr lib search "embodied" # keyword search across title/abstract/tags
39
+ zr show <key|citekey> # metadata + abstract + attachment + notes
40
+
41
+ zr ws init paper -q "How do VLAs handle mid-execution task switching?"
42
+ zr ws add paper 2506.03574 # plant a seed (Zotero key / DOI / arXiv id / url)
43
+ zr ws related paper # rebuild related.md from all seeds
44
+ zr ws parse paper --yes # parse ONLY this workspace's seeds (preview without --yes)
45
+
46
+ zr web # read everything in the browser at 127.0.0.1:8765
47
+ ```
48
+
49
+ Open the directory with a coding agent: it reads `AGENTS.md` and the skills under `.agents/skills/`. Describe a research question in natural language and the agent drives the CLI for you. Claude Code finds the same skills through the `.claude/skills` link.
50
+
51
+ ## Command reference
52
+
53
+ | Command | Purpose |
54
+ |---|---|
55
+ | `zr doctor` | environment checks (Zotero DB, BBT, MinerU token) |
56
+ | `zr lib stats` | library overview |
57
+ | `zr lib search <q> [--type ...]` | keyword search across title / abstract / tags |
58
+ | `zr lib list --collection <name>` | items in a collection |
59
+ | `zr lib collections` | list collections |
60
+ | `zr show <key\|citekey>` | metadata + abstract + attachment + notes |
61
+ | `zr parse <key> [--engine mineru\|pymupdf]` | PDF → `data/transcripts/<key>/paper.md` |
62
+ | `zr annotations <key>` | your highlights & notes from the PDF |
63
+ | `zr related <key>` | backward refs + forward citations, deduped vs library |
64
+ | `zr trends "<topic>"` | OpenAlex pull (years, venues, top-cited) |
65
+ | `zr import <doi\|arxiv\|url\|file.ris>` | add to Zotero via the connector; a `.ris` file adds hand-written records with their local PDFs (`L1`) |
66
+ | `zr notes <key> [--append "..."]` | durable per-paper notes |
67
+ | `zr ws init <name> [-q "..."]` | create a workspace for a question |
68
+ | `zr ws add <name> <seed>` | add a seed paper (Zotero key / DOI / arXiv / url) |
69
+ | `zr ws list` / `zr ws show <name>` | list / inspect workspaces |
70
+ | `zr ws related <name> [-n N]` | rebuild `related.md` from all seeds |
71
+ | `zr ws parse <name> [--yes]` | parse only this workspace's seeds (preview by default) |
72
+ | `zr web [--port P] [--host H] [--no-open]` | browser reader + slide decks |
73
+
74
+ Set `ZORESEARCH_PLAIN=1` for output without colours.
75
+
76
+ ## Reading in the browser
77
+
78
+ ```bash
79
+ zr web # serves http://127.0.0.1:8765
80
+ ```
81
+
82
+ The reader renders every Markdown file under `workspace/` with KaTeX math, highlighted code, and citation links that resolve back to Zotero / arXiv. A document whose front-matter sets `format: slides` is rendered as a presentation instead:
83
+
84
+ ```markdown
85
+ ---
86
+ format: slides
87
+ title: My talk
88
+ ---
89
+ # Title slide
90
+
91
+ ---
92
+ ## A content slide
93
+ - bullets, math $E=mc^2$, images, `<video>` all work
94
+
95
+ left column
96
+ :::
97
+ right column
98
+ ```
99
+
100
+ - `---` on its own line separates slides; `:::` splits a slide into columns.
101
+ - Decks are letterboxed to a fixed **16:9** stage, so they look identical on any screen.
102
+ - `F` toggles fullscreen, `← / →` / `Space` navigate, `⌘P` prints the deck straight to a 1280×720 PDF.
103
+ - A theme toggle (light / dark) sits in the corner and is remembered across reloads.
104
+
105
+ ## Layout
106
+
107
+ ```
108
+ zoresearch/
109
+ src/zoresearch/ # python package — the CLI and web reader live here
110
+ .agents/skills/ # agent skills (one SKILL.md per skill); .claude/skills links here
111
+ data/ # local cache (gitignored, rebuildable)
112
+ transcripts/<key>/ # parsed PDFs as markdown + extracted images
113
+ citations/ # OpenAlex response cache
114
+ notes/<key>.md # per-paper notes the agent appends to
115
+ workspace/ # research projects (gitignored)
116
+ <project>/
117
+ question.md # your framing of the question
118
+ seeds.txt # Zotero keys / DOIs / arXiv ids to start from
119
+ related.md # discovered work
120
+ notes.md # synthesis
121
+ ```
122
+
123
+ See [DEVELOPMENT.md](DEVELOPMENT.md) for the module map, data flow, and how to add a command or a skill.
124
+
125
+ ## Notes
126
+
127
+ - Developed and tested on macOS.
128
+ - The MinerU token lives at `~/.zoresearch/config.toml` (mode `600`, outside the repo).
129
+ - The citation graph uses OpenAlex — no API key required.
130
+ - This tool **never** writes to `~/Zotero/zotero.sqlite`; imports go through the connector API, which is why Zotero has to be running.
131
+ - `data/` and `workspace/` are rebuildable / personal and are gitignored.
132
+
133
+ ## License
134
+
135
+ MIT.
@@ -0,0 +1,46 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "zorsch"
7
+ version = "0.2.0"
8
+ description = "A research copilot CLI (zr) built on a local Zotero library."
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ authors = [{ name = "wheatfox" }]
14
+ dependencies = [
15
+ "typer>=0.12",
16
+ "rich>=13.7",
17
+ "httpx>=0.27",
18
+ "pymupdf>=1.24",
19
+ "pymupdf4llm>=0.0.17",
20
+ "platformdirs>=4.2",
21
+ ]
22
+
23
+ [project.optional-dependencies]
24
+ mineru = ["mineru-open-api>=0.1"]
25
+ embed = ["sentence-transformers>=3.0", "numpy>=1.26"]
26
+ web = [
27
+ "starlette>=0.37",
28
+ "uvicorn>=0.30",
29
+ "markdown-it-py>=3.0",
30
+ "mdit-py-plugins>=0.4",
31
+ ]
32
+
33
+ [project.scripts]
34
+ zr = "zoresearch.cli:app"
35
+
36
+ [project.urls]
37
+ Homepage = "https://github.com/enkerewpo/zoresearch"
38
+
39
+ [tool.setuptools]
40
+ package-dir = { "" = "src" }
41
+
42
+ [tool.setuptools.packages.find]
43
+ where = ["src"]
44
+
45
+ [tool.setuptools.package-data]
46
+ zoresearch = ["py.typed"]
zorsch-0.2.0/setup.cfg ADDED
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,3 @@
1
+ """zoresearch — personal research copilot over a local Zotero library."""
2
+
3
+ __version__ = "0.1.0"