@plantnet/planttaxomatcher 0.2.0 → 0.4.0
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.
package/package.json
CHANGED
|
@@ -1,43 +1,44 @@
|
|
|
1
1
|
{
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
"
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
"
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
}
|
|
2
|
+
"name": "@plantnet/planttaxomatcher",
|
|
3
|
+
"version": "0.4.0",
|
|
4
|
+
"description": "PlantTaxoMatcher CLI — reconcile plant names against WCVP via the PlantTaxoMatcher API.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"engines": {
|
|
7
|
+
"node": ">=24"
|
|
8
|
+
},
|
|
9
|
+
"bin": {
|
|
10
|
+
"planttaxomatcher": "./dist/index.js"
|
|
11
|
+
},
|
|
12
|
+
"files": [
|
|
13
|
+
"dist",
|
|
14
|
+
"skills"
|
|
15
|
+
],
|
|
16
|
+
"publishConfig": {
|
|
17
|
+
"access": "public"
|
|
18
|
+
},
|
|
19
|
+
"scripts": {
|
|
20
|
+
"dev": "tsx src/index.ts",
|
|
21
|
+
"build": "tsup",
|
|
22
|
+
"typecheck": "tsc -p tsconfig.json --noEmit",
|
|
23
|
+
"test": "vitest run --passWithNoTests",
|
|
24
|
+
"lint": "echo \"no lint yet\" && exit 0",
|
|
25
|
+
"prepublishOnly": "pnpm run build"
|
|
26
|
+
},
|
|
27
|
+
"dependencies": {
|
|
28
|
+
"@inquirer/prompts": "^8.5.0",
|
|
29
|
+
"commander": "^14.0.0",
|
|
30
|
+
"kleur": "^4.1.5",
|
|
31
|
+
"papaparse": "^5.5.3",
|
|
32
|
+
"undici": "^8.0.0",
|
|
33
|
+
"zod": "^4.0.0"
|
|
34
|
+
},
|
|
35
|
+
"devDependencies": {
|
|
36
|
+
"@planttaxomatcher/shared": "workspace:*",
|
|
37
|
+
"@types/node": "^24.12.4",
|
|
38
|
+
"@types/papaparse": "^5.5.2",
|
|
39
|
+
"tsup": "^8.5.1",
|
|
40
|
+
"tsx": "^4.20.0",
|
|
41
|
+
"typescript": "^6.0.0",
|
|
42
|
+
"vitest": "^4.1.7"
|
|
43
|
+
}
|
|
44
|
+
}
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: planttaxomatcher
|
|
3
|
+
description: >-
|
|
4
|
+
Reconcile plant scientific names against the World Checklist of Vascular
|
|
5
|
+
Plants (WCVP) with the PlantTaxoMatcher CLI. Use when the user wants to
|
|
6
|
+
match, clean, standardise or validate a list of plant names (CSV, XLSX or
|
|
7
|
+
JSON), find the accepted name behind a synonym, attach WCVP, IPNI or POWO
|
|
8
|
+
identifiers, see which names need taxonomic review, or check, download,
|
|
9
|
+
pause or cancel a PlantTaxoMatcher job.
|
|
10
|
+
compatibility: Needs Node.js 24+ and network access to a PlantTaxoMatcher server.
|
|
11
|
+
metadata:
|
|
12
|
+
cli-version: '{{version}}'
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
# PlantTaxoMatcher
|
|
16
|
+
|
|
17
|
+
PlantTaxoMatcher matches each plant name in a file against a WCVP snapshot
|
|
18
|
+
through a cascade of exact, fuzzy and external lookups, then grades every
|
|
19
|
+
match. Confident matches (grade A) are accepted automatically; the rest wait
|
|
20
|
+
for a human in the review queue of the web app. You drive it with the CLI.
|
|
21
|
+
|
|
22
|
+
## Running the CLI
|
|
23
|
+
|
|
24
|
+
Run `planttaxomatcher --version`. Use `planttaxomatcher` only if it prints
|
|
25
|
+
{{version}} or newer; otherwise (not installed, or an older version) use
|
|
26
|
+
`npx -y @plantnet/planttaxomatcher@{{version}}` in its place everywhere below.
|
|
27
|
+
|
|
28
|
+
- Pass `--json`: stdout then carries only JSON, and progress or hints go to stderr.
|
|
29
|
+
- Branch on the exit code:
|
|
30
|
+
|
|
31
|
+
| Exit | Meaning | What to do |
|
|
32
|
+
| ---- | ------------------------------------- | ----------------------------------------------------- |
|
|
33
|
+
| 0 | Success | Continue |
|
|
34
|
+
| 1 | API or network error | Read stderr; retry once if it names a network problem |
|
|
35
|
+
| 2 | Bad flag or argument | Check `planttaxomatcher <command> --help` |
|
|
36
|
+
| 3 | Not signed in, or token rejected | Follow **Sign-in** below |
|
|
37
|
+
| 4 | A watched job failed or was cancelled | Report it with the job link |
|
|
38
|
+
| 5 | A watched job was paused | Ask the user whether to resume it |
|
|
39
|
+
|
|
40
|
+
## 1. Sign-in
|
|
41
|
+
|
|
42
|
+
Run `planttaxomatcher whoami --json` first.
|
|
43
|
+
|
|
44
|
+
- Exit 0: signed in. Note `server` and `appUrl` for links.
|
|
45
|
+
- Exit 3: not signed in. **Do not run `planttaxomatcher login` yourself.** It
|
|
46
|
+
waits for someone to approve a code in a browser and will outlast your
|
|
47
|
+
command timeout. Tell the user to run `planttaxomatcher login` in their own
|
|
48
|
+
terminal (in Claude Code they can type `! planttaxomatcher login`), approve
|
|
49
|
+
the code in the browser page it opens, and tell you when it is done. Then
|
|
50
|
+
run `planttaxomatcher whoami --json` again.
|
|
51
|
+
|
|
52
|
+
Never ask for, print, or pass a token on the command line. CI jobs use the
|
|
53
|
+
`PLANTTAXOMATCHER_TOKEN` environment variable, set by the user.
|
|
54
|
+
|
|
55
|
+
## 2. Look at the file
|
|
56
|
+
|
|
57
|
+
Read the header row (first line of a CSV; the keys of a JSON array; the first
|
|
58
|
+
row of an XLSX sheet) and choose the columns:
|
|
59
|
+
|
|
60
|
+
- `--name-column` (required): the scientific name, with its author if the file has it.
|
|
61
|
+
- `--author-column` when authorship sits in its own column.
|
|
62
|
+
- `--family-column`, `--genus-column`, `--rank-column` when present: they help break ties.
|
|
63
|
+
- `--id-column` when rows already carry an identifier, with `--id-type wcvp` or `--id-type gbif` if you know which.
|
|
64
|
+
|
|
65
|
+
Then the reference to match against:
|
|
66
|
+
|
|
67
|
+
- **Backbone**: WCVP by default. Pass `--backbone wfo` only when the user asks for World Flora Online.
|
|
68
|
+
- **Version**: leave `--referential` out to use the server's default.
|
|
69
|
+
`planttaxomatcher versions --json` lists the versions; the one with
|
|
70
|
+
`"isDefault": true` is used when none is named. Pass `--referential <version>`
|
|
71
|
+
only when the user names one, or needs a team-edited version.
|
|
72
|
+
- **Area**: when the user says where the plants grow (a country, a regional
|
|
73
|
+
flora), pass `--area <code>` so an ambiguous name is narrowed to the taxa
|
|
74
|
+
native there. Find the WGSRPD level-3 code with
|
|
75
|
+
`planttaxomatcher areas --search <country> --json`, e.g. `FRA` for France.
|
|
76
|
+
|
|
77
|
+
Ask the user when the name column is not obvious. Keep the defaults for
|
|
78
|
+
everything else unless the user asks; `references/submit-options.md` lists
|
|
79
|
+
every option (author handling, species-level roll-up, row filter, LLM).
|
|
80
|
+
|
|
81
|
+
## 3. Submit
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
planttaxomatcher submit plants.csv --name-column scientific_name --no-watch --json
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
This prints a JSON array with one job per file: `id`, `name`, `file`,
|
|
88
|
+
`status`, `totalRows`, `uniqueQueries`, `url`. Several paths, or a quoted glob
|
|
89
|
+
such as `"data/*.csv"`, create one job each. Keep the ids.
|
|
90
|
+
|
|
91
|
+
## 4. Wait
|
|
92
|
+
|
|
93
|
+
Run `planttaxomatcher status <jobId>` (it always prints JSON) every 15 to 30
|
|
94
|
+
seconds until `status` is `completed`, `failed` or `cancelled`. If it is
|
|
95
|
+
`paused`, ask the user. Large files take minutes. The useful counts are
|
|
96
|
+
`totalRows`, `matchedRows`, `ambiguousRows`, `needsReviewRows` and `errorRows`.
|
|
97
|
+
|
|
98
|
+
`planttaxomatcher watch <jobId> --json` blocks until the job stops instead:
|
|
99
|
+
use it only when your command timeout allows.
|
|
100
|
+
|
|
101
|
+
## 5. Download
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
planttaxomatcher download <jobId> --format csv --output results.csv --json
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
The export keeps every column of the user's file and adds `planttaxomatcher_*`
|
|
108
|
+
and `wcvp_*` columns. The cleaned name to hand back is
|
|
109
|
+
**`wcvp_accepted_name_with_author`**: the accepted name with its author, ready
|
|
110
|
+
to cite (e.g. *Calicotome spinosa (L.) Link*), filled even when the input was a
|
|
111
|
+
synonym. `wcvp_accepted_name` is the same without the author, and
|
|
112
|
+
`wcvp_matched_name` is what the input matched before synonyms were resolved.
|
|
113
|
+
|
|
114
|
+
The filters of the web app's download dialog. Check what each keeps first
|
|
115
|
+
with `planttaxomatcher download <jobId> --counts --json`:
|
|
116
|
+
|
|
117
|
+
- `--confirmed-only`: only rows accepted automatically (grade A) or by a reviewer.
|
|
118
|
+
- `--resolved-only`: drop the rows with no accepted name (no match, error, rejected).
|
|
119
|
+
- `--dedupe`: one row per accepted taxon (synonyms and duplicates collapse).
|
|
120
|
+
- `--taxon-level species_below` (drop genus and family matches) or `--taxon-level species_only`.
|
|
121
|
+
|
|
122
|
+
To shape the file:
|
|
123
|
+
|
|
124
|
+
- `--columns` keeps only the listed columns. Start with the user's own name column (the one passed to `--name-column`), e.g. `--columns <name column>,wcvp_accepted_name_with_author,planttaxomatcher_grade,planttaxomatcher_review_status`.
|
|
125
|
+
- `--wcvp-extra ipni_id,powo_id` appends WCVP fields as `wcvp_<field>` columns.
|
|
126
|
+
- `--format xlsx`, or `--bundle` for a ZIP with a NOTICE.md that cites the backbone version.
|
|
127
|
+
|
|
128
|
+
`planttaxomatcher download <jobId> --list-columns --json` lists every column
|
|
129
|
+
with what it holds; `references/results.md` describes them all, with the grades
|
|
130
|
+
and review states.
|
|
131
|
+
|
|
132
|
+
## 6. Report back
|
|
133
|
+
|
|
134
|
+
Summarise from the status counts and the export:
|
|
135
|
+
|
|
136
|
+
- rows matched and accepted automatically (grade A),
|
|
137
|
+
- rows waiting for review (grade B or C, ambiguous),
|
|
138
|
+
- rows with no match or an error, with a few examples,
|
|
139
|
+
|
|
140
|
+
quoting names as input → `wcvp_accepted_name_with_author`.
|
|
141
|
+
|
|
142
|
+
Give the job's `url`: reviewing happens in the web app, not the CLI. Call a
|
|
143
|
+
name accepted only when `planttaxomatcher_review_status` is `not_required`,
|
|
144
|
+
`accepted` or `overridden`.
|
|
145
|
+
|
|
146
|
+
## Other commands
|
|
147
|
+
|
|
148
|
+
- `planttaxomatcher list --json`: recent jobs (`--status completed`, `--limit 50`).
|
|
149
|
+
- `planttaxomatcher versions --json` and `planttaxomatcher areas --json`: what `--referential` and `--area` accept.
|
|
150
|
+
- `planttaxomatcher pause <jobId>`, `planttaxomatcher resume <jobId>`, `planttaxomatcher cancel <jobId>`: control a running job; each takes `--json`. Cancelling keeps the rows already matched. Ask before cancelling.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Reading the export
|
|
2
|
+
|
|
3
|
+
Every row of the user's file comes back with its original columns, plus the
|
|
4
|
+
columns below. `planttaxomatcher download <jobId> --list-columns --json` lists
|
|
5
|
+
them for a given job (the Pl@ntNet columns only exist when the server has
|
|
6
|
+
Pl@ntNet enabled).
|
|
7
|
+
|
|
8
|
+
## The columns that matter most
|
|
9
|
+
|
|
10
|
+
- `wcvp_accepted_name_with_author`: the cleaned name to hand back, the accepted
|
|
11
|
+
name with its author (e.g. *Calicotome spinosa (L.) Link*), even when the
|
|
12
|
+
input was a synonym.
|
|
13
|
+
- `planttaxomatcher_grade` and `planttaxomatcher_review_status`: how far to
|
|
14
|
+
trust it (below).
|
|
15
|
+
- `planttaxomatcher_flags` and `planttaxomatcher_reason`: why a row needs a look.
|
|
16
|
+
- `wcvp_accepted_taxon_id`, `ipni_lsid`, `powo_url`: identifiers and links for
|
|
17
|
+
the accepted taxon (WCVP jobs; a WFO job's id is in
|
|
18
|
+
`planttaxomatcher_accepted_identifier`).
|
|
19
|
+
|
|
20
|
+
## Grades
|
|
21
|
+
|
|
22
|
+
- **A**: a confident match: exact, or a unique name whose author is confirmed.
|
|
23
|
+
Accepted automatically: review status `not_required`.
|
|
24
|
+
- **B**: plausible, but a person should look: an author that could not be
|
|
25
|
+
confirmed or that disagrees, a fuzzy spelling, an external provider's
|
|
26
|
+
answer, or one pick among several candidates. Waits for review.
|
|
27
|
+
- **C**: the weakest evidence: a language-model suggestion, or only the genus
|
|
28
|
+
could be settled. Waits for review.
|
|
29
|
+
|
|
30
|
+
## Review states
|
|
31
|
+
|
|
32
|
+
- `not_required`: grade A, accepted automatically.
|
|
33
|
+
- `pending`: waiting for a person in the web app's review queue.
|
|
34
|
+
- `accepted` / `rejected`: a reviewer confirmed or refused the proposed match.
|
|
35
|
+
- `overridden`: a reviewer picked another taxon by hand.
|
|
36
|
+
|
|
37
|
+
Only `not_required`, `accepted` and `overridden` rows carry a name the user
|
|
38
|
+
can rely on. `--confirmed-only` exports just those.
|
|
39
|
+
|
|
40
|
+
{{exportColumns}}
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
# `planttaxomatcher submit` options
|
|
2
|
+
|
|
3
|
+
Only `--name-column` is required. Keep the defaults unless the user asks for
|
|
4
|
+
something else; they are what the web app uses.
|
|
5
|
+
|
|
6
|
+
## Columns
|
|
7
|
+
|
|
8
|
+
| Option | Use |
|
|
9
|
+
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
|
10
|
+
| `--name-column <name>` | Column holding the scientific name (required) |
|
|
11
|
+
| `--author-column <name>` | Authorship, when it is not part of the name |
|
|
12
|
+
| `--family-column <name>` | Family, used to break ties between homonyms |
|
|
13
|
+
| `--genus-column <name>` | Genus |
|
|
14
|
+
| `--rank-column <name>` | Rank |
|
|
15
|
+
| `--id-column <name>` | An identifier the rows already carry |
|
|
16
|
+
| `--id-type <type>` | What `--id-column` holds: `auto` (default), `wcvp`, `gbif` |
|
|
17
|
+
| `--filter-column <name>` and `--filter-value <value>` | Only match rows whose column equals the value (trimmed, case-insensitive), e.g. `--filter-column kingdom --filter-value Plantae` |
|
|
18
|
+
|
|
19
|
+
## Backbone, version and area
|
|
20
|
+
|
|
21
|
+
| Option | Default | Effect |
|
|
22
|
+
| --- | --- | --- |
|
|
23
|
+
| `--backbone <name>` | `wcvp` | `wcvp` (World Checklist of Vascular Plants) or `wfo` (World Flora Online) |
|
|
24
|
+
| `--referential <version>` | the server's default | Backbone version, e.g. `wcvp-v14`. `planttaxomatcher versions --json` lists them and marks the default (`isDefault`); a team-edited version is listed with `kind: derived` |
|
|
25
|
+
| `--area <code>` | none | WGSRPD level-3 area (botanical country), e.g. `FRA`: an ambiguous name is narrowed to the taxa native there. `planttaxomatcher areas --search <text> --json` finds the code |
|
|
26
|
+
|
|
27
|
+
The CLI checks `--referential` and `--area` against the server before uploading, and names the valid values on a typo.
|
|
28
|
+
|
|
29
|
+
## Matching
|
|
30
|
+
|
|
31
|
+
| Option | Default | Effect |
|
|
32
|
+
| ------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
33
|
+
| `--author-mode <mode>` | `prefer` | `ignore`, `prefer` or `strict` handling of authorship |
|
|
34
|
+
| `--ignore-author` | off | Accept a unique name match whose author could not be confirmed, instead of sending it to review. A conflicting author still goes to review |
|
|
35
|
+
| `--species-level` | off | Roll varieties, subspecies and forms up to their accepted species |
|
|
36
|
+
| `--allow-llm` | off | Let a language model break ties between competing matches |
|
|
37
|
+
| `--llm-cap-cents <cents>` | `500` | Spending cap for `--allow-llm` |
|
|
38
|
+
| `--review-mode <mode>` | `recommended` | `off`, `recommended` or `strict` |
|
|
39
|
+
| `--parallel <n>` | `4` | Parallelism within the job, 1 to 10 |
|
|
40
|
+
|
|
41
|
+
## Submission
|
|
42
|
+
|
|
43
|
+
| Option | Effect |
|
|
44
|
+
| ------------------------ | -------------------------------------------------------------------------------------------- |
|
|
45
|
+
| `--name <label>` | Job name for a single file; otherwise each job is named after its file |
|
|
46
|
+
| `--no-watch` | Return as soon as the jobs exist (use this, then poll `status`) |
|
|
47
|
+
| `--json` | Print the created jobs as a JSON array |
|
|
48
|
+
| `--dry-run` with `--yes` | Print a local normalisation preview of the first rows (to stderr with `--json`), then upload |
|
|
49
|
+
| `--dry-run-rows <n>` | How many rows the preview shows |
|