Initial commit: pubmed-watcher — pure Python, zero dependencies

DMAir · DMAir · commit fe2242fc6575 · 2026-02-17T19:44:45.000-05:00
- Source code with CLI
- README with documentation
- Interactive demo page (GitHub Pages)
- .gitignore
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,4 @@
+__pycache__/
+*.pyc
+.DS_Store
+*.bak.json
diff --git a/README.md b/README.md
@@ -0,0 +1,159 @@
+# 🔬 PubMed Watcher
+
+Automated alerting for new PubMed papers matching your research interests. Detects **only new papers** by tracking previously seen PMIDs.
+
+Built for cron-based monitoring — zero external dependencies, pure Python 3 stdlib.
+
+## Quick Start
+
+```bash
+# Run all watched queries, report new papers
+python pubmed_watcher.py watch
+
+# First run initializes with 5 default longevity/biotech queries
+```
+
+## Commands
+
+### `watch` — Check for new papers
+
+```bash
+python pubmed_watcher.py watch                        # Default: last 7 days
+python pubmed_watcher.py watch --days 14              # Look back 14 days
+python pubmed_watcher.py watch --json                 # Machine-readable JSON
+python pubmed_watcher.py watch --markdown             # Telegram-ready markdown
+python pubmed_watcher.py watch --days 3 --markdown    # Combine flags
+```
+
+**How it works:**
+1. Runs each configured query against PubMed E-utilities
+2. Filters out papers already in `seen.json`
+3. Reports only NEW papers
+4. Saves newly seen PMIDs to `seen.json`
+
+### `add` — Add a watch query
+
+```bash
+python pubmed_watcher.py add "CRISPR aging therapy"
+python pubmed_watcher.py add "rapamycin longevity clinical trial"
+```
+
+### `list` — Show all queries
+
+```bash
+python pubmed_watcher.py list
+```
+
+Output:
+```
+📋 Watched Queries (5)
+
+  [1] epigenetic reprogramming aging longevity
+      Added: 2026-02-17
+  [2] immunosenescence aging immune system
+      Added: 2026-02-17
+  ...
+```
+
+### `remove` — Remove a query by ID
+
+```bash
+python pubmed_watcher.py remove 3
+```
+
+### `history` — Show recent alert runs
+
+```bash
+python pubmed_watcher.py history              # Last 20 runs
+python pubmed_watcher.py history --limit 5    # Last 5 runs
+```
+
+### `reset-seen` — Clear seen-papers database
+
+```bash
+python pubmed_watcher.py reset-seen    # Backs up to seen.bak.json first
+```
+
+## Output Formats
+
+### Terminal (default)
+
+```
+🔔 12 new papers found across 5 queries (last 7 days)
+
+━━━ 🔎 "epigenetic reprogramming aging longevity" — 3 new ━━━
+
+  📄 Epigenetic reprogramming reverses age-associated...
+     👤 Zhang W … Bhatt DL
+     📰 Nature Aging  •  2026 Feb
+     🔗 https://pubmed.ncbi.nlm.nih.gov/12345678/
+```
+
+### Markdown (`--markdown`)
+
+Telegram-ready formatting with bold titles and inline links.
+
+### JSON (`--json`)
+
+Full structured output for piping to other tools:
+
+```json
+[
+  {
+    "query": "epigenetic reprogramming aging longevity",
+    "query_id": 1,
+    "new_papers": [
+      {
+        "pmid": "12345678",
+        "title": "...",
+        "authors": ["First Author", "Last Author"],
+        "journal": "Nature Aging",
+        "date": "2026 Feb",
+        "doi": "10.1038/...",
+        "url": "https://pubmed.ncbi.nlm.nih.gov/12345678/"
+      }
+    ]
+  }
+]
+```
+
+## State Files
+
+| File | Purpose |
+|------|---------|
+| `config.json` | Watched queries and their IDs |
+| `seen.json` | All previously seen PMIDs (prevents re-alerting) |
+| `history.json` | Log of past `watch` runs with counts |
+
+All state is stored in the same directory as the script. Safe to version-control `config.json`; the others are ephemeral.
+
+## Default Queries
+
+On first run, these queries are pre-configured:
+
+1. **epigenetic reprogramming aging longevity**
+2. **immunosenescence aging immune system**
+3. **senolytics senescent cells therapy**
+4. **AI drug discovery clinical trial**
+5. **biological age clock methylation**
+
+## Cron Setup
+
+```bash
+# Run daily at 8 AM, pipe markdown to a notification script
+0 8 * * * cd /path/to/pubmed-watcher && python3 pubmed_watcher.py watch --markdown >> /tmp/pubmed-alerts.md 2>&1
+```
+
+Or integrate directly with OpenClaw cron for Telegram delivery.
+
+## Technical Details
+
+- **API:** NCBI E-utilities (esearch + efetch)
+- **Rate limiting:** 0.5s delay between API calls (NCBI-friendly)
+- **Dependencies:** None — pure Python 3.9+ stdlib
+- **Retry:** 3 attempts with backoff on network errors
+- **Date filter:** Uses `edat` (Entrez date) for reliable recency filtering
+
+## License
+
+Internal tool. No license required.
diff --git a/config.json b/config.json
@@ -0,0 +1,30 @@
+{
+  "queries": [
+    {
+      "id": 1,
+      "query": "epigenetic reprogramming aging longevity",
+      "added": "2026-02-17T10:04:28.475406+00:00Z"
+    },
+    {
+      "id": 2,
+      "query": "immunosenescence aging immune system",
+      "added": "2026-02-17T10:04:28.475406+00:00Z"
+    },
+    {
+      "id": 3,
+      "query": "senolytics senescent cells therapy",
+      "added": "2026-02-17T10:04:28.475406+00:00Z"
+    },
+    {
+      "id": 4,
+      "query": "AI drug discovery clinical trial",
+      "added": "2026-02-17T10:04:28.475406+00:00Z"
+    },
+    {
+      "id": 5,
+      "query": "biological age clock methylation",
+      "added": "2026-02-17T10:04:28.475406+00:00Z"
+    }
+  ],
+  "next_id": 7
+}
diff --git a/index.html b/index.html
@@ -0,0 +1,177 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>pubmed-watcher — Automated PubMed Paper Alerts</title>
+<meta name="description" content="Automated alerting for new PubMed papers. Delta detection — only alerts on unseen papers. Built for cron.">
+<link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>🔬</text></svg>">
+<style>
+*,*::before,*::after{margin:0;padding:0;box-sizing:border-box}
+:root{--bg:#06080c;--bg2:#0c1018;--bg3:#0f1520;--bg4:#141c28;--accent:#00e5bf;--accent-dim:#00e5bf60;--accent-glow:#00e5bf20;--text:#e2e8f0;--text2:#8892a4;--text3:#4a5568;--border:#1a2332;--red:#ff5f57;--yellow:#febc2e;--green:#28c840;--mono:'SF Mono','Fira Code','JetBrains Mono','Consolas',monospace;--sans:'Inter',-apple-system,BlinkMacSystemFont,system-ui,sans-serif}
+html{scroll-behavior:smooth;-webkit-font-smoothing:antialiased}
+body{font-family:var(--sans);background:var(--bg);color:var(--text);line-height:1.6;overflow-x:hidden}
+::selection{background:var(--accent);color:var(--bg)}
+a{color:var(--accent);text-decoration:none}a:hover{text-decoration:underline}
+.container{max-width:960px;margin:0 auto;padding:0 clamp(1rem,4vw,2rem)}
+.topbar{padding:1rem 0;border-bottom:1px solid var(--border);position:sticky;top:0;z-index:100;background:rgba(6,8,12,.92);backdrop-filter:blur(16px)}
+.topbar-inner{display:flex;align-items:center;justify-content:space-between;max-width:960px;margin:0 auto;padding:0 clamp(1rem,4vw,2rem)}
+.topbar a{font-family:var(--mono);font-size:.8rem;color:var(--text2)}.topbar a:hover{color:var(--accent);text-decoration:none}
+.topbar .logo{font-size:1rem;font-weight:700;color:var(--accent)}
+.hero{padding:4rem 0 3rem;text-align:center}
+.hero h1{font-size:clamp(2rem,6vw,3.5rem);font-weight:800;letter-spacing:-.03em;margin-bottom:.5rem}
+.hero h1 span{background:linear-gradient(135deg,var(--accent),#00b4d8);-webkit-background-clip:text;background-clip:text;-webkit-text-fill-color:transparent}
+.hero .sub{font-family:var(--mono);font-size:.85rem;color:var(--text2);margin-bottom:1.5rem}
+.hero p{color:var(--text2);max-width:600px;margin:0 auto 2rem;font-size:.95rem}
+.badge{display:inline-block;font-family:var(--mono);font-size:.7rem;padding:.25rem .75rem;border:1px solid var(--border);border-radius:100px;color:var(--text3);margin-bottom:1rem}
+.section{padding:3rem 0}.section-title{font-family:var(--mono);font-size:.75rem;color:var(--accent);letter-spacing:.1em;text-transform:uppercase;margin-bottom:1.5rem}
+.terminal{background:var(--bg);border:1px solid var(--border);border-radius:10px;overflow:hidden;margin-bottom:2rem}
+.terminal-bar{display:flex;align-items:center;gap:.75rem;padding:.5rem .75rem;background:var(--bg4);border-bottom:1px solid var(--border)}
+.terminal-dots{display:flex;gap:5px}.terminal-dots i{width:8px;height:8px;border-radius:50%;display:block}
+.terminal-dots i:nth-child(1){background:var(--red)}.terminal-dots i:nth-child(2){background:var(--yellow)}.terminal-dots i:nth-child(3){background:var(--green)}
+.terminal-title{font-family:var(--mono);font-size:.7rem;color:var(--text3)}
+.terminal-body{padding:1rem;font-family:var(--mono);font-size:.72rem;line-height:1.6;color:var(--text2);overflow-x:auto;white-space:pre}
+.info-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(280px,1fr));gap:1.5rem;margin-bottom:2rem}
+.info-card{background:var(--bg3);border:1px solid var(--border);border-radius:10px;padding:1.25rem}
+.info-card h4{font-family:var(--mono);font-size:.85rem;margin-bottom:.75rem}
+.info-card p,.info-card li{font-size:.82rem;color:var(--text2);line-height:1.6}
+.info-card ul{padding-left:1.25rem}.info-card li{margin-bottom:.25rem}
+.flow-steps{display:flex;gap:0;margin-bottom:2rem;flex-wrap:wrap}
+.flow-step{flex:1;min-width:150px;background:var(--bg3);border:1px solid var(--border);padding:1rem;text-align:center;position:relative}
+.flow-step:first-child{border-radius:8px 0 0 8px}
+.flow-step:last-child{border-radius:0 8px 8px 0}
+.flow-step .step-num{font-family:var(--mono);font-size:.65rem;color:var(--accent);margin-bottom:.25rem}
+.flow-step .step-icon{font-size:1.5rem;margin-bottom:.25rem}
+.flow-step .step-text{font-family:var(--mono);font-size:.7rem;color:var(--text2)}
+.flow-step::after{content:'→';position:absolute;right:-8px;top:50%;transform:translateY(-50%);color:var(--accent);font-family:var(--mono);z-index:1}
+.flow-step:last-child::after{content:''}
+.query-list{list-style:none;padding:0}
+.query-item{display:flex;align-items:center;gap:.75rem;padding:.75rem 1rem;background:var(--bg3);border:1px solid var(--border);border-radius:6px;margin-bottom:.5rem;font-family:var(--mono);font-size:.8rem}
+.query-num{color:var(--accent);font-weight:700;width:24px}
+.query-text{color:var(--text2)}
+.footer{padding:2rem 0;border-top:1px solid var(--border);text-align:center;margin-top:2rem}
+.footer p{font-family:var(--mono);font-size:.7rem;color:var(--text3)}
+</style>
+</head>
+<body>
+<div class="topbar"><div class="topbar-inner">
+  <a href="https://qclawq.github.io" class="logo">← Q's Build Lab</a>
+  <a href="https://github.com/QclawQ/pubmed-watcher" target="_blank">github ↗</a>
+</div></div>
+
+<div class="container">
+<div class="hero">
+  <div class="badge">pure python · zero dependencies · 617 loc</div>
+  <h1>🔬 <span>pubmed-watcher</span></h1>
+  <div class="sub">Automated PubMed Paper Alerts</div>
+  <p>Watch PubMed queries and get alerted only about <strong>new</strong> papers. Tracks seen PMIDs, supports cron scheduling, outputs to terminal, Markdown, or JSON.</p>
+</div>
+
+<div class="section">
+  <div class="section-title">// how it works</div>
+  <div class="flow-steps">
+    <div class="flow-step"><div class="step-num">01</div><div class="step-icon">🔎</div><div class="step-text">Query PubMed E-utilities</div></div>
+    <div class="flow-step"><div class="step-num">02</div><div class="step-icon">🔄</div><div class="step-text">Filter against seen.json</div></div>
+    <div class="flow-step"><div class="step-num">03</div><div class="step-icon">📥</div><div class="step-text">Fetch new paper details</div></div>
+    <div class="flow-step"><div class="step-num">04</div><div class="step-icon">🔔</div><div class="step-text">Alert only NEW papers</div></div>
+  </div>
+</div>
+
+<div class="section">
+  <div class="section-title">// default queries</div>
+  <ul class="query-list">
+    <li class="query-item"><span class="query-num">[1]</span><span class="query-text">epigenetic reprogramming aging longevity</span></li>
+    <li class="query-item"><span class="query-num">[2]</span><span class="query-text">immunosenescence aging immune system</span></li>
+    <li class="query-item"><span class="query-num">[3]</span><span class="query-text">senolytics senescent cells therapy</span></li>
+    <li class="query-item"><span class="query-num">[4]</span><span class="query-text">AI drug discovery clinical trial</span></li>
+    <li class="query-item"><span class="query-num">[5]</span><span class="query-text">biological age clock methylation</span></li>
+  </ul>
+</div>
+
+<div class="section">
+  <div class="section-title">// demo output</div>
+  <div class="terminal">
+    <div class="terminal-bar"><span class="terminal-dots"><i></i><i></i><i></i></span><span class="terminal-title">$ python3 pubmed_watcher.py watch</span></div>
+    <div class="terminal-body">🔔 12 new papers found across 5 queries (last 7 days)
+
+━━━ 🔎 "epigenetic reprogramming aging longevity" — 3 new ━━━
+
+  📄 Epigenetic reprogramming reverses age-associated
+     decline in neural stem cell function
+     👤 Zhang W … Bhatt DL
+     📰 Nature Aging  •  2026 Feb
+     🔗 https://pubmed.ncbi.nlm.nih.gov/39847201/
+
+  📄 In vivo partial reprogramming extends lifespan
+     in progeroid mice via cellular rejuvenation
+     👤 Ocampo A … Izpisua Belmonte JC
+     📰 Cell  •  2026 Feb 10
+     🔗 https://pubmed.ncbi.nlm.nih.gov/39847202/
+
+━━━ 🔎 "senolytics senescent cells therapy" — 4 new ━━━
+
+  📄 Dasatinib plus quercetin reduces senescent
+     cell burden in human adipose tissue
+     👤 Kirkland JL … Tchkonia T
+     📰 Nature Medicine  •  2026 Feb
+     🔗 https://pubmed.ncbi.nlm.nih.gov/39847203/
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📊 Total: 12 new | 4/5 queries had results</div>
+  </div>
+
+  <div class="terminal">
+    <div class="terminal-bar"><span class="terminal-dots"><i></i><i></i><i></i></span><span class="terminal-title">$ python3 pubmed_watcher.py history</span></div>
+    <div class="terminal-body">📜 Alert History (last 5 runs)
+
+  🔔 2026-02-17 08:00 UTC — 12 new papers (5 queries, 7d window)
+      • epigenetic reprogramming aging longevity: 3 new
+      • senolytics senescent cells therapy: 4 new
+      • AI drug discovery clinical trial: 3 new
+      • biological age clock methylation: 2 new
+  🔔 2026-02-16 08:00 UTC — 8 new papers (5 queries, 7d window)
+  ✅ 2026-02-15 08:00 UTC — 0 new papers (5 queries, 7d window)
+  🔔 2026-02-14 08:00 UTC — 5 new papers (5 queries, 7d window)</div>
+  </div>
+</div>
+
+<div class="section">
+  <div class="section-title">// features</div>
+  <div class="info-grid">
+    <div class="info-card">
+      <h4>🔄 Delta Detection</h4>
+      <p>Tracks every PMID in <code>seen.json</code>. You only get alerted once per paper, even across multiple queries. Perfect for daily cron jobs.</p>
+    </div>
+    <div class="info-card">
+      <h4>📤 Output Formats</h4>
+      <ul>
+        <li><code>--terminal</code> — Pretty CLI output</li>
+        <li><code>--markdown</code> — Telegram-ready</li>
+        <li><code>--json</code> — Machine-readable</li>
+      </ul>
+    </div>
+    <div class="info-card">
+      <h4>⏰ Cron Ready</h4>
+      <p style="font-family:var(--mono);font-size:.72rem">0 8 * * * python3 pubmed_watcher.py watch --markdown >> /tmp/alerts.md</p>
+      <p style="margin-top:.5rem">Run daily, pipe to Telegram, Slack, or email.</p>
+    </div>
+    <div class="info-card">
+      <h4>💻 Commands</h4>
+      <ul>
+        <li><code>watch</code> — Check all queries</li>
+        <li><code>add "query"</code> — Add new query</li>
+        <li><code>list</code> — Show queries</li>
+        <li><code>remove &lt;id&gt;</code> — Remove query</li>
+        <li><code>history</code> — Past runs</li>
+        <li><code>reset-seen</code> — Clear DB</li>
+      </ul>
+    </div>
+  </div>
+</div>
+</div>
+
+<footer class="footer"><div class="container">
+  <p>pubmed-watcher · <a href="https://github.com/QclawQ/pubmed-watcher">source</a> · <a href="https://qclawq.github.io">Q's Build Lab</a> · NCBI E-utilities</p>
+</div></footer>
+</body>
+</html>
diff --git a/pubmed_watcher.py b/pubmed_watcher.py
