@tiagojct/subsub 0.5.0

package/README.md

@@ -0,0 +1,90 @@
+# Sub-Sub
+
+A Zotero librarian and research assistant that runs in your terminal. It is built on the [pi](https://pi.dev) agent and works with your own Zotero library through Zotero's local API.
+
+> "This mere painstaking burrower and grub-worm of a poor devil of a Sub-Sub appears to have gone through the long Vaticans and street-stalls of the earth, picking up whatever random allusions to whales he could anyways find in any book whatsoever." (Moby-Dick, Extracts)
+
+Sub-Sub has two modes:
+
+- The librarian changes the library: tags from your own tag list, imports by DOI, PMID or ISBN, metadata repair, duplicates, retractions, open-access PDFs, notes and collections. It has no web access.
+- The researcher reads the library, searches PubMed and OpenAlex, and writes notes in your notes folder. It cannot change the library, except to add a short linked note to an item.
+
+Every library change is shown as a preview and runs only after you approve it. The model cannot skip this: the check is in the code, not in the prompt. Every change is journaled and can be undone with `/undo`.
+
+## Profiles
+
+A profile sets how much Sub-Sub does for you. Choose it in `subsub init` and change it with `/profile`.
+
+| Profile | What it does |
+|---|---|
+| Reader | Explains each step. Reading notes are quotes with page numbers, plus questions for you to answer. No summaries or syntheses. No bulk library changes. |
+| Scholar | Literature notes, syntheses, searches and alerts. The full librarian. |
+| Author | Scholar, plus manuscripts: citation check against the library, bibliography for Quarto or Pandoc, comments on the argument. It does not write your paragraphs. |
+| Editor | Everything, including drafting manuscript text when you ask. |
+
+A profile is your own choice, not a lock.
+
+## Requirements
+
+- Zotero 10 or later, running. In Zotero, open Settings > Advanced and turn on "Allow other applications on this computer to communicate with Zotero".
+- Node.js 22.19 or later.
+- uv (https://docs.astral.sh/uv/).
+- An account with a model provider that pi supports (for example OpenCode Go, OpenRouter, Anthropic, OpenAI, or a local Ollama).
+- macOS, Windows or Linux.
+
+## Install
+
+1. Type `npm install -g @tiagojct/subsub`. The command is `subsub`.
+2. Type `subsub init`. Answer the questions. Press Enter to keep a default.
+3. Type `subsub doctor`. Fix each line marked FIX.
+4. Type `subsub`. Then type `/login` and choose your model provider.
+
+`subsub init` creates a notes folder with Inbox/ and Systems/, a starter tag list (health sciences, health informatics, or any field) and a file with the note formats (Systems/Zotero agent.md). You can edit both files. It never replaces a file that exists.
+
+If you already use pi, you can also add Sub-Sub to plain pi: `pi install npm:@tiagojct/subsub`.
+
+The Zotero servers (zotero-local-mcp) run from PyPI through uv. To run them from a copy of the repository, add `"serverDir": "/path/to/zotero-local-mcp"` to the settings file.
+
+## Use
+
+- `subsub` starts in the researcher mode. `subsub --librarian` starts in the librarian mode. `/librarian` and `/researcher` change the mode.
+- `/profile` shows or changes the profile. `/subsub` shows the Zotero connection. `/history` lists recent library changes. `/undo` reverts one.
+- Templates: `/tag-batch`, `/clean-tags`, `/import-queue` (librarian); `/lit-note <citekey>`, `/synthesis <topic>`, `/gaps <topic>`, `/manuscript <file>`, `/alert` (researcher).
+- `subsub review preview 13-31` and `subsub review apply 13-31` preview or apply tag review notes by number.
+- `subsub -c` continues the last session. `subsub -r` selects an older one.
+
+## Settings
+
+`subsub init` writes `~/.config/subsub/config.json` (or the file in `SUBSUB_CONFIG`):
+
+| Setting | Meaning | Default |
+|---|---|---|
+| `profile` | reader, scholar, author or editor | scholar |
+| `userName` | how Sub-Sub names you | "the user" |
+| `about` | one line about you | none |
+| `language` | language of replies and notes, or `auto` | English |
+| `vault` | notes folder | `ZOTERO_VAULT` from the server settings |
+| `models` | model per mode, e.g. `{ "librarian": "opencode-go/glm-5.3-flash" }` | pi's current model |
+| `defaultMode` | librarian or researcher | researcher |
+| `serverDir` | a local copy of zotero-local-mcp | the PyPI release |
+| `look`, `quotes`, `themes` | banner, Moby-Dick line, themes per mode | on |
+
+The server settings (notes folder, tag list, contact email for Unpaywall) are in `~/.config/zotero-local-mcp/env`.
+
+## Model test
+
+`subsub-bench prepare`, `subsub-bench run` and `subsub-bench score` run the same tasks for several models against your library. Every library change is recorded and blocked, and files are written only in the run folder. The results show tag accuracy, invented references, tokens, cost and time.
+
+## Tests
+
+```sh
+npm install
+npm test
+ZLM_DIR=/path/to/zotero-local-mcp npm run test:e2e
+```
+
+The end-to-end tests run the real pi with Sub-Sub, the real Python servers, a fake Zotero and a scripted model.
+
+## Licence
+
+MIT.

package/bin/subsub-bench.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// Model test for Sub-Sub. See docs/Subsub.md.
+import { fileURLToPath } from "node:url";
+// Inside node_modules (an npm install), Node cannot strip types: use the compiled dist/.
+// From a checkout (npm link), run the TypeScript sources directly.
+const installed = fileURLToPath(import.meta.url).split(/[\\/]/).includes("node_modules");
+const entry = (name) => (installed ? `../dist/${name}.js` : `../src/${name}.ts`);
+const [major, minor] = process.versions.node.split(".").map(Number);
+if (major < 22 || (major === 22 && minor < 19)) {
+	console.error(`subsub-bench needs Node.js 22.19 or later (this is ${process.versions.node}).`);
+	process.exit(1);
+}
+const { main } = await import(entry("bench"));
+try {
+	await main();
+} catch (err) {
+	console.error(err instanceof Error ? err.message : err);
+	process.exit(1);
+}

package/bin/subsub.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// Sub-Sub: pi set up as a Zotero librarian and research assistant.
+import { fileURLToPath } from "node:url";
+// Inside node_modules (an npm install), Node cannot strip types: use the compiled dist/.
+// From a checkout (npm link), run the TypeScript sources directly.
+const installed = fileURLToPath(import.meta.url).split(/[\\/]/).includes("node_modules");
+const entry = (name) => (installed ? `../dist/${name}.js` : `../src/${name}.ts`);
+const [major, minor] = process.versions.node.split(".").map(Number);
+if (major < 22 || (major === 22 && minor < 19)) {
+	console.error(`Sub-Sub needs Node.js 22.19 or later (this is ${process.versions.node}).`);
+	process.exit(1);
+}
+const { run } = await import(entry("cli"));
+await run();

package/dist/args.js

@@ -0,0 +1,67 @@
+/**
+ * Some models send a list as a JSON string ("[\"topic/asthma\"]") or as
+ * "a, b". pi validates tool arguments against the schema before Sub-Sub sees
+ * them, so the schema also accepts a string where it wants a list of strings,
+ * and Sub-Sub turns the string back into a list before the server gets it.
+ * (Seen in the model test: three models lost several turns on this.)
+ */
+function isStringArray(s) {
+    if (!s || typeof s !== "object")
+        return false;
+    if (s.type === "array")
+        return !s.items || s.items.type === "string";
+    const alts = (s.anyOf ?? s.oneOf);
+    return Array.isArray(alts) && alts.some((a) => a?.type === "array" && (!a.items || a.items.type === "string"));
+}
+/** A copy of the input schema where top-level string lists also accept a string. */
+export function loosenArrays(schema) {
+    if (!schema || typeof schema !== "object" || !schema.properties)
+        return schema;
+    const props = {};
+    for (const [k, v] of Object.entries(schema.properties)) {
+        if (!isStringArray(v)) {
+            props[k] = v;
+            continue;
+        }
+        const s = v;
+        const alts = (s.anyOf ?? s.oneOf);
+        if (alts) {
+            props[k] = { ...s, anyOf: [...alts, { type: "string" }], oneOf: undefined };
+        }
+        else {
+            const { description, default: def, title, ...inner } = s;
+            props[k] = { anyOf: [inner, { type: "string" }], description, default: def, title };
+        }
+        for (const key of Object.keys(props[k]))
+            if (props[k][key] === undefined)
+                delete props[k][key];
+    }
+    return { ...schema, properties: props };
+}
+export function toList(value) {
+    const t = value.trim();
+    if (t.startsWith("[")) {
+        try {
+            const parsed = JSON.parse(t);
+            if (Array.isArray(parsed))
+                return parsed.map((x) => String(x));
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    return t
+        .replace(/^\[|\]$/g, "")
+        .split(/[,\n]/)
+        .map((x) => x.trim().replace(/^["'`]|["'`]$/g, ""))
+        .filter(Boolean);
+}
+/** Turn strings back into lists where the original schema wants a list of strings. Changes input in place. */
+export function coerceArgs(original, input) {
+    const props = (original?.properties ?? {});
+    for (const [k, v] of Object.entries(input)) {
+        if (typeof v === "string" && isStringArray(props[k]))
+            input[k] = toList(v);
+    }
+    return input;
+}