paper-manager 0.12.0 → 0.12.1

package/README.md

@@ -8,10 +8,11 @@ A CLI tool for managing academic papers with knowledge base and vector search su
 ## Features
 
 - **Semantic search** — FAISS vector indexing with configurable embedding models, query your papers by meaning rather than keywords
+- **Add papers by DOI** — automatically download Open Access PDFs via [Unpaywall API](https://unpaywall.org/products/api) with `--doi` ([integration guide](paper-cli/unpaywall.md))
 - **PDF metadata extraction** — automatically extracts title, author, keywords, DOI, and more from PDF files
 - **DOI deduplication** — detects duplicate papers by DOI before adding, with `--force` override
 - **Multi-format support** — import from PDF, TXT, MD, TEX, and other text-based formats
-- **PDF-to-Markdown conversion** — optional high-quality conversion via [opendataloader-pdf](https://github.com/nicobailon/opendataloader-pdf) with image extraction
+- **PDF-to-Markdown conversion** — optional high-quality conversion via [opendataloader-pdf](https://github.com/opendataloader-project/opendataloader-pdf) with image extraction ([integration guide](paper-cli/opendataloader-pdf.md))
 - **Dual-scope data model** — user-level (`~/.paper-manager/`) for global collections and project-level (`./.paper-manager/`) for project-specific papers, with automatic scope resolution
 - **DOI-to-BibTeX** — convert DOI to BibTeX citation in one command
 - **Machine-readable output** — `--json` and `--jq` flags on all read commands for scripting and automation
@@ -49,6 +50,10 @@ paper kb create my-papers -d "My research papers"
 # Add a paper (supports PDF, TXT, MD, TEX, etc.)
 paper lit add <knowledge-base-id> ./paper.pdf
 
+# Or add an Open Access paper by DOI
+paper config set email '"you@example.com"' --user  # one-time setup for Unpaywall API
+paper lit add <knowledge-base-id> --doi 10.1038/nature12373
+
 # Search across papers
 paper kb query <knowledge-base-id> "attention mechanism"
 ```
@@ -78,7 +83,8 @@ paper kb query <id> <query-text> [--json] [--jq <expr>]  # Query a knowledge bas
 ### Literature (`paper lit`)
 
 ```bash
-paper lit add <kb-id> <file-path> [-f] # Add a literature (auto-extracts PDF metadata, rejects duplicate DOI)
+paper lit add <kb-id> <file-path> [-f] # Add a literature from file (auto-extracts PDF metadata)
+paper lit add <kb-id> --doi <doi> [-f] # Add an Open Access paper by DOI via Unpaywall
 paper lit remove <kb-id> <id>         # Remove a literature
 paper lit update <kb-id> <id> [opts]  # Update literature metadata
 paper lit list <kb-id> [--json] [--jq <expr>]       # List literatures
@@ -96,6 +102,72 @@ paper util doi2bib <doi>             # Convert a DOI to BibTeX citation
 paper util pdf-meta <file> [--json] [--jq <expr>]  # Extract metadata from a PDF file
 ```
 
+## Usage Scenarios
+
+### Building a paper collection for a research project
+
+```bash
+# Initialize a project-scoped data directory (version-controllable)
+paper config init
+
+# Create a knowledge base for your topic
+paper kb create "llm-agents" -d "Papers on LLM-based autonomous agents"
+# Output: Knowledge base created: 9f3a...
+
+# Add papers — by file or by DOI
+paper lit add 9f3a ./downloaded-paper.pdf
+paper lit add 9f3a --doi 10.48550/arXiv.2305.10601
+
+# Ask questions across all your papers
+paper kb query 9f3a "how do agents handle long-term memory?"
+```
+
+### Quick-adding Open Access papers you find online
+
+```bash
+# Spot a DOI in a reference list? One command to ingest it.
+paper lit add <kb-id> --doi 10.1038/nature12373
+
+# Unpaywall checks OA status, downloads the PDF, extracts metadata,
+# and builds a vector index — all in one step.
+# If the paper is not OA, you'll get a clear error with instructions.
+```
+
+### Generating BibTeX citations for your bibliography
+
+```bash
+paper util doi2bib 10.1145/3586183.3606763
+# @inproceedings{...}
+
+# Combine with jq to batch-extract DOIs from your knowledge base
+paper lit list <kb-id> --jq '.[].doi | select(. != null)'
+```
+
+### Scripting with JSON output
+
+```bash
+# Export all papers in a knowledge base as JSON
+paper lit list <kb-id> --json > papers.json
+
+# Filter with jq expressions inline
+paper lit list <kb-id> --jq '[.[] | {title, doi, author}]'
+
+# Find papers by a specific author
+paper lit search <kb-id> -a "Vaswani" --json
+```
+
+### Annotating papers for a literature review
+
+```bash
+# Attach notes to track your reading progress
+paper lit note set <lit-id> status "read"
+paper lit note set <lit-id> relevance "high"
+paper lit note set <lit-id> summary "Proposes transformer architecture..."
+
+# Review all notes
+paper lit note list <lit-id>
+```
+
 ## Configuration
 
 See [Configuration Reference](docs/configuration.md) for all available config fields and detailed usage.

package/dist/commands/literature.js

@@ -9,6 +9,7 @@ import * as projectKb from "../db/project/knowledge-bases.js";
 import * as projectLit from "../db/project/literatures.js";
 import * as userKb from "../db/user/knowledge-bases.js";
 import * as userLit from "../db/user/literatures.js";
+import { isHybridBackendAvailable } from "../dep/index.js";
 import { extractContent, extractPdfMetadata } from "../extractor/index.js";
 import { convertPdfToMarkdown, isOpendataLoaderAvailable, removeImageDir, saveConvertResult, } from "../extractor/markdown.js";
 import { log } from "../logger.js";
@@ -217,6 +218,9 @@ export function createLiteratureCommand() {
             fs.copyFileSync(absolutePath, path.join(filesDir, `${literature.id}${ext}`));
             // Convert PDF to Markdown if opendataloader is available
             if (isPdf && (await isOpendataLoaderAvailable())) {
+                if (!(await isHybridBackendAvailable())) {
+                    log.step("Hybrid backend (localhost:5002) is not running; using basic conversion. Start the backend for better quality.");
+                }
                 const result = await convertPdfToMarkdown(absolutePath);
                 if (result) {
                     saveConvertResult(filesDir, literature.id, result);

package/dist/dep/index.js

@@ -0,0 +1,19 @@
+import { request } from "node:http";
+const HYBRID_BACKEND_URL = "http://localhost:5002";
+const HYBRID_PROBE_TIMEOUT_MS = 1500;
+/** Check if the opendataloader hybrid backend is reachable at localhost:5002. */
+export function isHybridBackendAvailable() {
+    return new Promise((resolve) => {
+        const req = request(HYBRID_BACKEND_URL, { method: "GET", timeout: HYBRID_PROBE_TIMEOUT_MS }, (res) => {
+            // Any response means the server is running
+            res.resume();
+            resolve(true);
+        });
+        req.on("error", () => resolve(false));
+        req.on("timeout", () => {
+            req.destroy();
+            resolve(false);
+        });
+        req.end();
+    });
+}

package/dist/extractor/markdown.js

@@ -1,8 +1,8 @@
 import { execFile } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { request } from "node:http";
 import { tmpdir } from "node:os";
 import * as path from "node:path";
+import { isHybridBackendAvailable } from "../dep/index.js";
 /**
  * Check whether opendataloader-pdf is available (package installed + Java runtime).
  * Result is cached after the first call.
@@ -124,24 +124,6 @@ export async function checkOpendataLoaderStatus() {
         hybridBackendAvailable,
     };
 }
-const HYBRID_BACKEND_URL = "http://localhost:5002";
-const HYBRID_PROBE_TIMEOUT_MS = 1500;
-/** Check if the opendataloader hybrid backend is reachable at localhost:5002. */
-function isHybridBackendAvailable() {
-    return new Promise((resolve) => {
-        const req = request(HYBRID_BACKEND_URL, { method: "GET", timeout: HYBRID_PROBE_TIMEOUT_MS }, (res) => {
-            // Any response means the server is running
-            res.resume();
-            resolve(true);
-        });
-        req.on("error", () => resolve(false));
-        req.on("timeout", () => {
-            req.destroy();
-            resolve(false);
-        });
-        req.end();
-    });
-}
 // execFile is safe — arguments are passed as an array, no shell interpolation.
 function getJavaVersion() {
     return new Promise((resolve) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paper-manager",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "description": "A paper management system.",
   "keywords": [],
   "homepage": "https://github.com/EurFelux/paper-manager",