masteracademicreview 0.1.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.
- masteracademicreview-0.1.0/LICENSE +21 -0
- masteracademicreview-0.1.0/PKG-INFO +375 -0
- masteracademicreview-0.1.0/README.md +333 -0
- masteracademicreview-0.1.0/masteracademicreview.egg-info/PKG-INFO +375 -0
- masteracademicreview-0.1.0/masteracademicreview.egg-info/SOURCES.txt +37 -0
- masteracademicreview-0.1.0/masteracademicreview.egg-info/dependency_links.txt +1 -0
- masteracademicreview-0.1.0/masteracademicreview.egg-info/entry_points.txt +3 -0
- masteracademicreview-0.1.0/masteracademicreview.egg-info/requires.txt +20 -0
- masteracademicreview-0.1.0/masteracademicreview.egg-info/top_level.txt +1 -0
- masteracademicreview-0.1.0/pyproject.toml +52 -0
- masteracademicreview-0.1.0/setup.cfg +4 -0
- masteracademicreview-0.1.0/shared/scripts/__init__.py +9 -0
- masteracademicreview-0.1.0/shared/scripts/__main__.py +5 -0
- masteracademicreview-0.1.0/shared/scripts/bibliometric/__init__.py +47 -0
- masteracademicreview-0.1.0/shared/scripts/bibliometric/example.py +52 -0
- masteracademicreview-0.1.0/shared/scripts/bibliometric/mapping.py +53 -0
- masteracademicreview-0.1.0/shared/scripts/bibliometric/parsers.py +233 -0
- masteracademicreview-0.1.0/shared/scripts/bibliometric/performance.py +113 -0
- masteracademicreview-0.1.0/shared/scripts/bibliometric/plots.py +56 -0
- masteracademicreview-0.1.0/shared/scripts/bibliometric/sample.csv +7 -0
- masteracademicreview-0.1.0/shared/scripts/bibliometric/validate_export.py +163 -0
- masteracademicreview-0.1.0/shared/scripts/check_review.py +323 -0
- masteracademicreview-0.1.0/shared/scripts/cli.py +123 -0
- masteracademicreview-0.1.0/shared/scripts/dedup.py +527 -0
- masteracademicreview-0.1.0/shared/scripts/export.py +58 -0
- masteracademicreview-0.1.0/shared/scripts/journal_rank.py +504 -0
- masteracademicreview-0.1.0/shared/scripts/mdconvert.py +313 -0
- masteracademicreview-0.1.0/shared/scripts/meta/__init__.py +54 -0
- masteracademicreview-0.1.0/shared/scripts/meta/effect_sizes.py +61 -0
- masteracademicreview-0.1.0/shared/scripts/meta/example.py +47 -0
- masteracademicreview-0.1.0/shared/scripts/meta/plots.py +176 -0
- masteracademicreview-0.1.0/shared/scripts/meta/pooling.py +254 -0
- masteracademicreview-0.1.0/shared/scripts/meta/selftest.py +121 -0
- masteracademicreview-0.1.0/shared/scripts/prisma_flow.py +525 -0
- masteracademicreview-0.1.0/shared/scripts/protocol.py +242 -0
- masteracademicreview-0.1.0/shared/scripts/screening_agreement.py +522 -0
- masteracademicreview-0.1.0/shared/scripts/submission.py +487 -0
- masteracademicreview-0.1.0/shared/scripts/validate_extraction.py +335 -0
- masteracademicreview-0.1.0/shared/scripts/verify_refs.py +1035 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 masteracademicreview contributors
|
|
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.
|
|
@@ -0,0 +1,375 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: masteracademicreview
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Deterministic, auditable tools for writing academic reviews: deduplication, PRISMA flow, screening agreement, extraction checks, meta-analysis, reference integrity, review gate, protocols, journal ranking and submission letters.
|
|
5
|
+
Author: thabedtholibb
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/thabedtholibb/masteracademicreview
|
|
8
|
+
Project-URL: Documentation, https://github.com/thabedtholibb/masteracademicreview/tree/master/docs
|
|
9
|
+
Project-URL: Issues, https://github.com/thabedtholibb/masteracademicreview/issues
|
|
10
|
+
Project-URL: Changelog, https://github.com/thabedtholibb/masteracademicreview/blob/master/CHANGELOG.md
|
|
11
|
+
Keywords: systematic review,meta-analysis,PRISMA,deduplication,evidence synthesis,scoping review,bibliometrics
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Science/Research
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Topic :: Scientific/Engineering
|
|
22
|
+
Requires-Python: >=3.10
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
License-File: LICENSE
|
|
25
|
+
Provides-Extra: meta
|
|
26
|
+
Requires-Dist: numpy; extra == "meta"
|
|
27
|
+
Requires-Dist: scipy; extra == "meta"
|
|
28
|
+
Requires-Dist: matplotlib; extra == "meta"
|
|
29
|
+
Provides-Extra: bibliometric
|
|
30
|
+
Requires-Dist: numpy; extra == "bibliometric"
|
|
31
|
+
Requires-Dist: matplotlib; extra == "bibliometric"
|
|
32
|
+
Provides-Extra: export
|
|
33
|
+
Requires-Dist: python-docx; extra == "export"
|
|
34
|
+
Requires-Dist: reportlab; extra == "export"
|
|
35
|
+
Provides-Extra: all
|
|
36
|
+
Requires-Dist: numpy; extra == "all"
|
|
37
|
+
Requires-Dist: scipy; extra == "all"
|
|
38
|
+
Requires-Dist: matplotlib; extra == "all"
|
|
39
|
+
Requires-Dist: python-docx; extra == "all"
|
|
40
|
+
Requires-Dist: reportlab; extra == "all"
|
|
41
|
+
Dynamic: license-file
|
|
42
|
+
|
|
43
|
+
# Master Academic Review
|
|
44
|
+
|
|
45
|
+
<p align="center"><img src="docs/banner.webp" alt="Master Academic Review: input, process, output" width="100%"></p>
|
|
46
|
+
|
|
47
|
+

|
|
48
|
+

|
|
49
|
+

|
|
50
|
+

|
|
51
|
+

|
|
52
|
+

|
|
53
|
+

|
|
54
|
+

|
|
55
|
+
|
|
56
|
+
**English** · [Bahasa Indonesia](README.id.md)
|
|
57
|
+
|
|
58
|
+
> **Every kind of review, one toolkit.** A portable agent skill-suite specialized in *writing reviews* — from a book review to a meta-analysis to a realist review — each with the right protocol, the right reporting standard, and (where it matters) real statistics for its genre.
|
|
59
|
+
|
|
60
|
+
Most academic-AI tools treat "review" as a side-mode of a paper generator. **Master Academic Review** inverts that: **the review is the product**, and the first job of the tool is to figure out *which* review you actually need.
|
|
61
|
+
|
|
62
|
+
> **What this is — and is not.** Master Academic Review is **not** a full-paper pipeline: it does not design or run experiments, and it does not generate new findings (unlike Spark-to-Paper or AI-Scientist). It produces **one kind of deliverable — a review document** — plus the auditable artifacts that back it (a PRISMA flow diagram, pooled estimates, forest/funnel plots). It works interactively, genre by genre, with you as the author.
|
|
63
|
+
>
|
|
64
|
+
> Deeper reading: [docs/USAGE.md](docs/USAGE.md) for the working model · [docs/FLOWS.md](docs/FLOWS.md) for skill-by-skill flows · [docs/WALKTHROUGH.md](docs/WALKTHROUGH.md) for a concrete session · [docs/INSTALL.md](docs/INSTALL.md) for per-platform setup.
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## Documentation
|
|
69
|
+
|
|
70
|
+
[Decision tree (which skill?)](docs/DECISION_TREE.md) · [FAQ](docs/FAQ.md) · [Troubleshooting (Windows, Pandoc, encoding)](docs/TROUBLESHOOTING.md) · [Usage](docs/USAGE.md) · [Install](docs/INSTALL.md) · [JEV decision protocol](shared/jev.md) · [End-to-end example](examples/systematic-review-demo/) · [Changelog](CHANGELOG.md)
|
|
71
|
+
|
|
72
|
+
Bahasa Indonesia: [README](README.id.md) · [Panduan](docs/id/PANDUAN.md) · [FAQ](docs/id/FAQ.md)
|
|
73
|
+
Community: [Contributing](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md) · [Security](SECURITY.md) · [Cite](CITATION.cff)
|
|
74
|
+
|
|
75
|
+
## Install the Tools (pip: terminal or PowerShell)
|
|
76
|
+
|
|
77
|
+
The deterministic tools install as one package with one command, `mar`. No clone needed; Python 3.10–3.13 on Windows, macOS or Linux.
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
pip install "masteracademicreview @ https://github.com/thabedtholibb/masteracademicreview/archive/refs/heads/master.zip"
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
On Windows, if `pip` is not recognised, use `py -m pip install ...`. Add `[all]` after the package name for the meta-analysis, bibliometric and DOCX/PDF extras (`"masteracademicreview[all] @ https://..."`). Once the package is on PyPI this becomes `pip install masteracademicreview`.
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
mar list # every tool, grouped by review step
|
|
87
|
+
mar selftest # check the installation
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
If `mar` is not on your PATH, `python -m masteracademicreview list` does the same. The **skills** (`*/SKILL.md`) are installed by cloning the repository: see [docs/INSTALL.md](docs/INSTALL.md).
|
|
91
|
+
|
|
92
|
+
## JEV: Ranked Decisions, #1 Recommended
|
|
93
|
+
|
|
94
|
+
Every decision in the suite (which databases, which model, which journal, which reviewer comment first) is presented as **ranked options with a #1 recommendation**, one line of evidence each, and what would change the ranking. The author decides; approved choices go into a decision log. Each genre skill has a *Decision points (JEV)* section, and the tools follow the same rule: `dedup.py` removes only certain duplicates and *recommends* the rest, `check_review.py` ranks fixes integrity-first, `journal_rank.py` marks **#1 recommended**, and `submission.py` writes to the #1 clean journal and ranks reviewer comments major-first. Protocol: [shared/jev.md](shared/jev.md).
|
|
95
|
+
|
|
96
|
+
## The Flow
|
|
97
|
+
|
|
98
|
+
```
|
|
99
|
+
vague idea
|
|
100
|
+
│
|
|
101
|
+
▼
|
|
102
|
+
brainstorm ──► focused research question + keyword set (PICO / PICo / PCC / SPIDER)
|
|
103
|
+
│ │
|
|
104
|
+
│ └──► journal-match (optional) ──► verified journal shortlist (JEV)
|
|
105
|
+
│
|
|
106
|
+
▼
|
|
107
|
+
review-router ──► classify + rank the review genre (best fit first)
|
|
108
|
+
│
|
|
109
|
+
▼
|
|
110
|
+
genre skill (thirteen genres)
|
|
111
|
+
│ methodology from shared/*.md · scripts from shared/scripts/
|
|
112
|
+
▼
|
|
113
|
+
review document + artifacts (PRISMA flow, forest/funnel plots, pooled estimates)
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
The **`brainstorm` skill** sits before classification because most people get stuck choosing keywords and framing their question. It produces a ready-to-search question plus a Boolean query, then hands off to the router.
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## What You Get (the Output)
|
|
121
|
+
|
|
122
|
+
Every run ends with **one review document plus supporting artifacts** (see [shared/output_spec.md](shared/output_spec.md)):
|
|
123
|
+
|
|
124
|
+
1. **`review.md`** — the review itself: a title, a metadata block (review type, reporting standard, sources, search date, gate status), an abstract, the genre's sections, and references.
|
|
125
|
+
2. **Artifacts** (per genre) — e.g. `prisma_flow.svg`, `forest.png`, `funnel.png`, `effects.csv`, `characteristics.csv`, plus the gate reports `agreement.md`, `extraction_check.md`, and `ref_check.md`.
|
|
126
|
+
3. **`review.docx` / `review.pdf`** — optional, via `python shared/scripts/export.py review.md` (Pandoc, with an automatic no-Pandoc fallback), so the review can be submitted to Word-based journals or a supervisor.
|
|
127
|
+
4. **`journal_shortlist.md`** — optional, from `journal-match`: a ranked target-journal shortlist with verified metrics and a submission cascade.
|
|
128
|
+
|
|
129
|
+
---
|
|
130
|
+
|
|
131
|
+
## The Core Idea: A Review Is Not One Thing
|
|
132
|
+
|
|
133
|
+
A review is a *family* of genres, each with its own methodology, reporting standard, and reader. Master Academic Review encodes that taxonomy as its organizing principle — **all thirteen implemented**.
|
|
134
|
+
|
|
135
|
+
| Genre | What it does | Reporting standard |
|
|
136
|
+
|---|---|---|
|
|
137
|
+
| **Book review** | Critically assess a single book | Genre conventions |
|
|
138
|
+
| **Narrative review** | Broad expert synthesis of a field | SANRA |
|
|
139
|
+
| **Critical review** | Argue a conceptual thesis across literature | — (argument contract) |
|
|
140
|
+
| **Systematic review** | Reproducible, comprehensive synthesis | PRISMA 2020 |
|
|
141
|
+
| **Meta-analysis** | Statistically pool effect sizes | PRISMA + MOOSE, GRADE |
|
|
142
|
+
| **Scoping review** | Map the breadth of a field | PRISMA-ScR |
|
|
143
|
+
| **Umbrella review** | Synthesize existing reviews | PRIOR |
|
|
144
|
+
| **Meta-synthesis** | Qualitative evidence synthesis | ENTREQ |
|
|
145
|
+
| **Rapid review** | Streamlined systematic review | Cochrane rapid-review guidance |
|
|
146
|
+
| **Integrative review** | Combine diverse designs into a whole | Whittemore & Knafl |
|
|
147
|
+
| **Mapping review** | Visual evidence & gap map | ROSES / EGM |
|
|
148
|
+
| **Bibliometric review** | Citation & co-word analysis | PRISMA 2020 (search) |
|
|
149
|
+
| **Realist review** | Theory-driven explanation (CMO) | RAMESES |
|
|
150
|
+
|
|
151
|
+
Every standard above is backed by a Crossref-verified citation in [`shared/method_sources.md`](shared/method_sources.md), along with the method papers behind each workflow and a cross-genre **Q1-readiness checklist**. Two genres (critical review, book review) have no EQUATOR-registered checklist; the suite says so and uses an explicit internal contract instead of borrowing a standard that does not fit.
|
|
152
|
+
|
|
153
|
+
---
|
|
154
|
+
|
|
155
|
+
## Journal Targeting (Optional)
|
|
156
|
+
|
|
157
|
+
Writing the review and choosing the venue are two decisions. **`journal-match`** handles the second one — before you write (recommended, because the venue shapes scope and length) or after.
|
|
158
|
+
|
|
159
|
+
- **Ranked, not guessed.** Eight criteria — scope fit (30%), article type (15%), method acceptance (15%), indexing (10%), speed (10%), cost/APC (10%), audience (5%), legitimacy (5%) — are scored 0–5 and combined by `shared/scripts/journal_rank.py`, so the ranking is reproducible.
|
|
160
|
+
- **Evidence-first (JEV).** Every quartile, APC, and decision-time claim carries a source and a check date. Anything unverified is labelled `unverified` and lowers the confidence; it is never filled in with a plausible number.
|
|
161
|
+
- **Submission cascade.** Reach / target / safety with explicit triggers and no simultaneous submissions. The recommended **#1** is the best fit-adjusted target, not the highest quartile.
|
|
162
|
+
|
|
163
|
+
Ask *"Where should I submit this review?"* — `brainstorm` offers it after the question + keywords, and `review-router` passes the genre and object to it.
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
## Reproducibility Checks (Built In)
|
|
168
|
+
|
|
169
|
+
The suite does not ask you to trust arithmetic it cannot show. Stdlib-only tools are part of the gates (each is also `mar <tool>` after `pip install`):
|
|
170
|
+
|
|
171
|
+
| Check | Command | What it catches |
|
|
172
|
+
|---|---|---|
|
|
173
|
+
| **Deduplication** | `python shared/scripts/dedup.py --source Scopus=scopus.csv --source PubMed=pubmed.ris --source WoS=wos.bib` | duplicates across RIS/CSV/BibTeX exports by DOI, then title + year; near-matches listed for a human (`possible_duplicates.csv`); writes the PRISMA identification counts and a screening template. |
|
|
174
|
+
| **PRISMA arithmetic** | `python shared/scripts/prisma_flow.py prisma_identification.json screening_counts.json --strict` | refuses a flow diagram whose boxes do not add up; `--variant scoping/update`; `--validate` checks the SVG structure. |
|
|
175
|
+
| **Reference integrity** | `python shared/scripts/verify_refs.py review.md` | duplicate DOIs, citations with no reference, orphan references, missing year/title. Add `--online` for a Crossref DOI/title/year check. |
|
|
176
|
+
| **Screening agreement** | `python shared/scripts/screening_agreement.py screening_log.csv --long --reviewers alice,bob` | Cohen's κ, PABAK, per-stage agreement, and a `conflicts.csv` for adjudication. |
|
|
177
|
+
| **Extraction validation** | `python shared/scripts/validate_extraction.py effects.csv` | non-finite effects, variance ≤ 0, bad sample sizes/years, duplicate study–outcome rows, and k < 2 / k < 10 guards. |
|
|
178
|
+
| **Protocol** | `python shared/scripts/protocol.py protocol.json --out protocol.md` | a registration-ready protocol (PROSPERO/OSF fields) per genre, PRISMA-P based; undecided fields stay `[TO COMPLETE]` and `--strict` fails until they are filled. Start with `--template GENRE`. |
|
|
179
|
+
| **Submission** | `python shared/scripts/submission.py cover-letter review.md --shortlist shortlist.json --gate-report review_check.md` | cover letter for the #1 clean journal (refused while the gate fails); `submission.py response comments.txt` builds a ranked, point-by-point response; `--lang id` for Indonesian. |
|
|
180
|
+
| **Review gate** | `python shared/scripts/check_review.py review.md` | missing metadata fields, missing genre sections, unresolved citations, referenced/required artifacts that do not exist, leftover `TODO`/`[citation needed]`, and a gate line that says "passed" with an incomplete checklist. |
|
|
181
|
+
|
|
182
|
+
All of these are offline by default and run in CI on Linux and Windows with Python 3.10–3.13; only `verify_refs.py --online` needs the network (a monthly workflow re-verifies every DOI in `shared/method_sources.md` against Crossref). The whole chain runs end to end in [examples/systematic-review-demo](examples/systematic-review-demo/). Reports land in `review_check.md`, `ref_check.md`, `agreement.md`, and `extraction_check.md`.
|
|
183
|
+
|
|
184
|
+
---
|
|
185
|
+
|
|
186
|
+
## Invoking a Skill (Three Ways)
|
|
187
|
+
|
|
188
|
+
1. **Auto (default).** Just describe what you want — *"I want a meta-analysis of this data"* — and the skill whose `description` matches loads itself.
|
|
189
|
+
2. **`@skill-id` (OpenCode).** Type `@meta-analysis`, `@brainstorm`, `@journal-match`, `@book-review`, and so on.
|
|
190
|
+
3. **`/command` (Claude Code).** Copy `commands/*.md` into `.claude/commands/`, then use `/review`, `/brainstorm`, `/journal-match`, `/meta-analysis`, `/systematic-review`, and so on.
|
|
191
|
+
|
|
192
|
+
---
|
|
193
|
+
|
|
194
|
+
## Architecture
|
|
195
|
+
|
|
196
|
+
```
|
|
197
|
+
brainstorm ──► research question + keywords ──► review-router ──► classify + rank ──► dispatch
|
|
198
|
+
│
|
|
199
|
+
├─ journal-match/ # optional: verified target-journal shortlist (JEV)
|
|
200
|
+
│
|
|
201
|
+
├─ shared/ # reusable core (not a skill)
|
|
202
|
+
│ ├─ search_strategy.md # database query + grey literature
|
|
203
|
+
│ ├─ screening.md # title/abstract/full-text + PRISMA flow
|
|
204
|
+
│ ├─ data_extraction.md # extraction forms + effect-size data
|
|
205
|
+
│ ├─ risk_of_bias.md # RoB 2, ROBINS-I, NOS, CASP, AMSTAR-2, GRADE
|
|
206
|
+
│ ├─ reporting_standards.md # PRISMA / PRISMA-ScR / SANRA / ENTREQ / PRIOR / RAMESES / ROSES / AMSTAR-2
|
|
207
|
+
│ ├─ method_sources.md # verified citations + Q1-readiness checklist
|
|
208
|
+
│ ├─ jev.md # JEV decision protocol: ranked options, #1 recommended
|
|
209
|
+
│ └─ scripts/
|
|
210
|
+
│ ├─ cli.py # `mar <tool>`: one command for every tool (pip package entry point)
|
|
211
|
+
│ ├─ dedup.py # deduplicate RIS/CSV/BibTeX exports -> PRISMA identification (stdlib)
|
|
212
|
+
│ ├─ prisma_flow.py # deterministic PRISMA flow-diagram generator + count checks (stdlib SVG)
|
|
213
|
+
│ ├─ journal_rank.py # deterministic journal-fit scoring (stdlib)
|
|
214
|
+
│ ├─ verify_refs.py # reference integrity: offline + Crossref (stdlib)
|
|
215
|
+
│ ├─ screening_agreement.py # Cohen's κ + PABAK for dual screening (stdlib)
|
|
216
|
+
│ ├─ validate_extraction.py # effects/characteristics validation (stdlib)
|
|
217
|
+
│ ├─ protocol.py # protocol.md per genre, PROSPERO/OSF fields (stdlib)
|
|
218
|
+
│ ├─ check_review.py # the review gate, ranked next steps (stdlib)
|
|
219
|
+
│ ├─ submission.py # cover letter + response to reviewers, EN/ID (stdlib)
|
|
220
|
+
│ ├─ meta/ # real meta-analysis statistics engine (numpy/scipy/matplotlib)
|
|
221
|
+
│ └─ bibliometric/ # bibliometric engine (parse, performance, co-word mapping, plots)
|
|
222
|
+
│
|
|
223
|
+
└─ one directory per genre (each a standalone skill)
|
|
224
|
+
book-review/ narrative-review/ critical-review/
|
|
225
|
+
systematic-review/ meta-analysis/ scoping-review/
|
|
226
|
+
umbrella-review/ meta-synthesis/ rapid-review/
|
|
227
|
+
integrative-review/ mapping-review/ bibliometric-review/ realist-review/
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
One brainstorm + one orchestrator + one optional journal matcher + one shared core + one skill per genre. **Narrow and deep, not a 13-agent mega-suite.**
|
|
231
|
+
|
|
232
|
+
---
|
|
233
|
+
|
|
234
|
+
## How It Differs from the Incumbents
|
|
235
|
+
|
|
236
|
+
| Capability | Master Academic Review | Academic-Research-Skills (ARS) | AI-Scientist | Spark-to-Paper |
|
|
237
|
+
|---|---|---|---|---|
|
|
238
|
+
| Treats review as a *family of genres* (13 types) | ✅ | ⚠️ | ❌ | ❌ |
|
|
239
|
+
| Orphan genres (book / narrative / critical / umbrella / meta-synthesis / integrative / mapping / realist) | ✅ | ❌ | ❌ | ❌ |
|
|
240
|
+
| Review-type diagnostic router (ranked) | ✅ | ❌ | ❌ | ❌ |
|
|
241
|
+
| Research-question + keyword brainstorm | ✅ | ⚠️ | ❌ | ❌ |
|
|
242
|
+
| Ranked target-journal shortlist with verified metrics (JEV) | ✅ | ⚠️ | ❌ | ❌ |
|
|
243
|
+
| Real meta-analysis statistics (Python) | ✅ | ❌ | ❌ | ❌ |
|
|
244
|
+
| Deterministic reporting-standard gates | ✅ | ⚠️ | ❌ | ✅ |
|
|
245
|
+
| Focus on *reviews* (not papers) | ✅ | ❌ | ❌ | ❌ |
|
|
246
|
+
|
|
247
|
+
✅ = yes · ⚠️ = partial · ❌ = no
|
|
248
|
+
|
|
249
|
+
**Positioning:** Master Academic Review does not generate a paper and does not run your experiments. It is a **human-in-the-loop specialist for the review genre** — the author owns every claim; the tool owns the protocol, the reporting checklist, and the arithmetic.
|
|
250
|
+
|
|
251
|
+
---
|
|
252
|
+
|
|
253
|
+
## Quick Start
|
|
254
|
+
|
|
255
|
+
0. **Just the tools?** `pip install` them (see *Install the Tools* above) and run `python examples/systematic-review-demo/run_demo.py` from a clone to see the whole chain.
|
|
256
|
+
1. **[Install](docs/INSTALL.md)** — copy or register the skill directories plus `shared/` in your harness (Claude Code / OpenCode / generic). Python is needed only for `systematic-review`, `scoping-review`, `mapping-review`, `meta-analysis`, `bibliometric-review`, and the `journal-match` scorer.
|
|
257
|
+
2. **Ask for a review** — in a session, say:
|
|
258
|
+
- *"I want to write a review but I don't know the topic yet."* → `brainstorm` sharpens the question + keywords.
|
|
259
|
+
- *"Help me write a review."* → `review-router` interviews you and classifies the type.
|
|
260
|
+
- *"I want a meta-analysis of this data."* → `meta-analysis` (runs `shared/scripts/meta/`).
|
|
261
|
+
- *"Where should I submit this review?"* → `journal-match` builds a verified, ranked shortlist.
|
|
262
|
+
- Or use `@meta-analysis` / `/meta-analysis` to jump straight in.
|
|
263
|
+
3. **See it in action** — [docs/WALKTHROUGH.md](docs/WALKTHROUGH.md) shows a full annotated session.
|
|
264
|
+
|
|
265
|
+
---
|
|
266
|
+
|
|
267
|
+
## Repository Layout
|
|
268
|
+
|
|
269
|
+
```
|
|
270
|
+
masteracademicreview/
|
|
271
|
+
├── README.md
|
|
272
|
+
├── README.id.md # Bahasa Indonesia
|
|
273
|
+
├── LICENSE
|
|
274
|
+
├── pyproject.toml # pip package `masteracademicreview` (maps shared/scripts/)
|
|
275
|
+
├── CHANGELOG.md CITATION.cff CONTRIBUTING.md CODE_OF_CONDUCT.md SECURITY.md
|
|
276
|
+
├── .gitignore
|
|
277
|
+
├── .gitattributes
|
|
278
|
+
├── brainstorm/SKILL.md # pre-router: research question + keywords (+ optional journal fit)
|
|
279
|
+
├── review-router/SKILL.md # orchestrator: interview → classify + rank → dispatch
|
|
280
|
+
├── journal-match/SKILL.md # optional: verified target-journal shortlist (JEV)
|
|
281
|
+
├── book-review/SKILL.md
|
|
282
|
+
├── narrative-review/SKILL.md
|
|
283
|
+
├── critical-review/SKILL.md
|
|
284
|
+
├── systematic-review/SKILL.md
|
|
285
|
+
├── meta-analysis/SKILL.md
|
|
286
|
+
├── scoping-review/SKILL.md
|
|
287
|
+
├── umbrella-review/SKILL.md
|
|
288
|
+
├── meta-synthesis/SKILL.md
|
|
289
|
+
├── rapid-review/SKILL.md
|
|
290
|
+
├── integrative-review/SKILL.md
|
|
291
|
+
├── mapping-review/SKILL.md
|
|
292
|
+
├── bibliometric-review/SKILL.md
|
|
293
|
+
├── realist-review/SKILL.md
|
|
294
|
+
├── commands/ # slash commands (copy to .claude/commands/ for Claude Code)
|
|
295
|
+
│ ├── brainstorm.md
|
|
296
|
+
│ ├── review.md
|
|
297
|
+
│ ├── journal-match.md
|
|
298
|
+
│ └── *.md # one per genre (13)
|
|
299
|
+
├── shared/ # shared library (methodology + scripts)
|
|
300
|
+
│ ├── search_strategy.md
|
|
301
|
+
│ ├── screening.md
|
|
302
|
+
│ ├── data_extraction.md
|
|
303
|
+
│ ├── risk_of_bias.md
|
|
304
|
+
│ ├── reporting_standards.md
|
|
305
|
+
│ ├── method_sources.md # Crossref-verified method citations + Q1 checklist
|
|
306
|
+
│ ├── jev.md # JEV decision protocol
|
|
307
|
+
│ ├── output_spec.md
|
|
308
|
+
│ └── scripts/
|
|
309
|
+
│ ├── cli.py __init__.py __main__.py # `mar` command / python -m masteracademicreview
|
|
310
|
+
│ ├── dedup.py # multi-database deduplication (stdlib)
|
|
311
|
+
│ ├── prisma_flow.py # PRISMA 2020 flow (systematic / scoping / update) + checks
|
|
312
|
+
│ ├── protocol.py # protocol generator (stdlib)
|
|
313
|
+
│ ├── check_review.py # review gate (stdlib)
|
|
314
|
+
│ ├── submission.py # cover letter + response to reviewers (stdlib)
|
|
315
|
+
│ ├── journal_rank.py # deterministic journal-fit scorer (stdlib)
|
|
316
|
+
│ ├── verify_refs.py # reference consistency + Crossref verification (stdlib)
|
|
317
|
+
│ ├── screening_agreement.py # Cohen's κ + PABAK, wide or long logs (stdlib)
|
|
318
|
+
│ ├── validate_extraction.py # meta/generic extraction checks (stdlib)
|
|
319
|
+
│ ├── export.py # one-command MD → DOCX/PDF (Pandoc, fallback to mdconvert)
|
|
320
|
+
│ ├── mdconvert.py # no-Pandoc converter (python-docx + reportlab)
|
|
321
|
+
│ ├── meta/
|
|
322
|
+
│ │ ├── __init__.py
|
|
323
|
+
│ │ ├── effect_sizes.py
|
|
324
|
+
│ │ ├── pooling.py
|
|
325
|
+
│ │ ├── plots.py
|
|
326
|
+
│ │ ├── example.py
|
|
327
|
+
│ │ └── selftest.py # estimators vs independent computations
|
|
328
|
+
│ └── bibliometric/
|
|
329
|
+
│ ├── __init__.py
|
|
330
|
+
│ ├── parsers.py
|
|
331
|
+
│ ├── performance.py
|
|
332
|
+
│ ├── mapping.py
|
|
333
|
+
│ ├── plots.py
|
|
334
|
+
│ ├── example.py
|
|
335
|
+
│ ├── validate_export.py # regression checks on a real Scopus/WoS export
|
|
336
|
+
│ └── sample.csv
|
|
337
|
+
├── tests/
|
|
338
|
+
│ ├── check_docs.py # standards/gates/provenance integrity (stdlib)
|
|
339
|
+
│ ├── run_tool_tests.py # CLI regression tests for the reproducibility tools
|
|
340
|
+
│ ├── fixtures/scopus_mini.csv # cp1252 + semicolon fixture used by CI
|
|
341
|
+
│ ├── fixtures/journals_example.csv # fictional journal table for the scorer's CI check
|
|
342
|
+
│ ├── fixtures/review_refs_*.md # clean / broken / running-bibliography reference fixtures
|
|
343
|
+
│ ├── fixtures/screening_*.csv # wide and long dual-screening fixtures
|
|
344
|
+
│ └── fixtures/effects_*.csv # valid / invalid meta-analysis extraction fixtures
|
|
345
|
+
├── examples/systematic-review-demo/ # synthetic end-to-end run: exports -> dedup -> PRISMA -> gate -> letter
|
|
346
|
+
├── .github/workflows/ci.yml # tools x (Linux, Windows) x py3.10-3.13, engines, pip package
|
|
347
|
+
├── .github/workflows/verify-sources.yml # monthly Crossref check of every method DOI
|
|
348
|
+
├── .github/workflows/publish.yml # manual PyPI publish (trusted publishing)
|
|
349
|
+
└── docs/
|
|
350
|
+
├── INSTALL.md
|
|
351
|
+
├── USAGE.md
|
|
352
|
+
├── FLOWS.md
|
|
353
|
+
├── WALKTHROUGH.md
|
|
354
|
+
├── DECISION_TREE.md FAQ.md TROUBLESHOOTING.md
|
|
355
|
+
└── id/ # PANDUAN.md, FAQ.md (Bahasa Indonesia)
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
Skill directories are named in lowercase (e.g. `meta-analysis/`) because that is the skill *ID* your harness loads; "Master Academic Review" is the project name. On GitHub this repository is `masteracademicreview`; a fresh clone creates a folder of the same name.
|
|
359
|
+
|
|
360
|
+
---
|
|
361
|
+
|
|
362
|
+
## Principles
|
|
363
|
+
|
|
364
|
+
- **AI is the copilot, not the author.** Every review type stops for author confirmation at decision points; the author answers for every claim and every inclusion/exclusion.
|
|
365
|
+
- **JEV: recommendation-first.** At every decision point, the skill presents the best options in priority order with **#1 recommended**, the evidence, and what would change the ranking — never a bare open question, never a silent choice ([shared/jev.md](shared/jev.md)).
|
|
366
|
+
- **Deterministic where it matters.** Search counts, screening tallies, PRISMA flow, and meta-analysis arithmetic are computed by code, never by an LLM guessing.
|
|
367
|
+
- **Reporting standards are gates, not suggestions.** A review that skips a PRISMA item is flagged, not silently passed.
|
|
368
|
+
- **Evidence over memory.** Journal quartiles, APCs, and decision times are verified against a primary source and date-stamped; unverified values are labelled, never invented.
|
|
369
|
+
- **Portable.** Plain `SKILL.md` frontmatter (`name` + `description`) works across Claude Code, OpenCode, and other agent harnesses with minimal adjustment.
|
|
370
|
+
|
|
371
|
+
---
|
|
372
|
+
|
|
373
|
+
## License
|
|
374
|
+
|
|
375
|
+
MIT. See [LICENSE](LICENSE).
|