ez-reads 1.0.0

package/README.md

@@ -0,0 +1,100 @@
+# ez-reads
+
+Turn any research paper into a beautiful, interactive static website.
+
+Paste an ArXiv URL or DOI, and ez-reads will fetch the paper, distill it into structured sections using an LLM, and generate a polished React site — complete with an AI chat assistant that can answer questions about the paper.
+
+## Features
+
+- **Automatic distillation** — Extracts key contributions, methodology, results, stats, significance, limitations, glossary, and more
+- **Beautiful sites** — React + Tailwind sites with scroll animations, color themes, and responsive design
+- **AI chat assistant** — Each generated site includes a chat widget powered by Groq so visitors can ask questions about the paper
+- **Paper library** — An auto-generated index page lists all your papers with search
+- **ArXiv + DOI support** — Works with ArXiv URLs and DOIs from any publisher
+- **Figure extraction** — Automatically downloads and displays paper figures
+
+## Requirements
+
+- **Node.js 18+** (uses native `fetch()`)
+- **Groq API key** — free at [console.groq.com/keys](https://console.groq.com/keys)
+
+## Install
+
+```bash
+npm install -g ez-reads
+```
+
+Or run it directly without installing:
+
+```bash
+npx ez-reads
+```
+
+## Usage
+
+```bash
+ez-reads
+```
+
+On first run, you'll be prompted for your Groq API key. The key powers both:
+1. **Paper distillation** — extracting structured data from the paper via LLM
+2. **Chat assistant** — the interactive Q&A widget on each generated site
+
+**Model used:** `qwen/qwen3-32b` (available on Groq's free tier)
+
+### Skip the prompt
+
+Set your key in the environment to skip the interactive prompt:
+
+```bash
+export GROQ_API_KEY=gsk_your_key_here
+ez-reads
+```
+
+Or create a `.env` file in the directory where you save the key:
+
+```
+GROQ_API_KEY=gsk_your_key_here
+```
+
+## How it works
+
+```
+📄 paper → 🔬 distill → ✨ generate → 🌐 site
+```
+
+1. **Fetch** — Scrapes the paper content from ArXiv or resolves a DOI
+2. **Distill** — Sends the paper through 5-6 LLM calls to extract structured JSON (title, abstract, methodology, results, stats, glossary, etc.)
+3. **Generate** — Builds a React + Tailwind static site and serves it locally
+
+Output goes to `./ez-reads-output/` in your current directory.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `ez-reads` or `paper-site` | Start the interactive CLI |
+| `npm run rebuild` | Rebuild all existing sites (after template changes) |
+
+## Generated site structure
+
+```
+ez-reads-output/
+├── index.html          # Library page (lists all papers)
+└── <paper-slug>/
+    ├── index.html      # Paper site
+    ├── assets/         # JS/CSS bundles
+    ├── figures/        # Downloaded figures
+    ├── meta.json       # Metadata for library index
+    └── data.json       # Full distilled data (for rebuilds)
+```
+
+## Chat assistant
+
+Every generated site includes a floating chat button in the bottom-right corner. Visitors can ask questions about the paper and get answers powered by the same Groq API key used during generation.
+
+**Note:** Your Groq API key is embedded in the generated site's JavaScript bundle to power the chat assistant. This is fine for local use or private hosting. If you plan to host generated sites publicly, be aware that the key is visible in the page source.
+
+## License
+
+MIT

package/bin/paper-site.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import 'dotenv/config';
+import { run } from '../src/cli.mjs';
+
+run();

package/bin/rebuild-all.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+import 'dotenv/config';
+import path from 'path';
+import chalk from 'chalk';
+import ora from 'ora';
+import { rebuildAll } from '../src/generator.mjs';
+
+const OUTPUT_DIR = path.resolve(process.cwd(), 'ez-reads-output');
+
+console.log(chalk.blueBright('\n  Rebuilding all paper sites with updated template...\n'));
+
+const spinner = ora('Rebuilding...').start();
+
+try {
+  const results = await rebuildAll(OUTPUT_DIR);
+  spinner.succeed(`Rebuilt ${results.length} site${results.length === 1 ? '' : 's'}`);
+  for (const r of results) {
+    console.log(`  ${chalk.green('✓')} ${r.slug}`);
+  }
+  console.log('');
+} catch (err) {
+  spinner.fail(`Rebuild failed: ${err.message}`);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "ez-reads",
+  "version": "1.0.0",
+  "description": "Turn any research paper into a beautiful static website",
+  "type": "module",
+  "bin": {
+    "ez-reads": "bin/paper-site.mjs",
+    "paper-site": "bin/paper-site.mjs"
+  },
+  "scripts": {
+    "start": "node bin/paper-site.mjs",
+    "rebuild": "node bin/rebuild-all.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "template/",
+    "README.md"
+  ],
+  "keywords": [
+    "arxiv",
+    "research",
+    "paper",
+    "static-site",
+    "groq",
+    "ai",
+    "llm"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hsidiyer/ez-reads.git"
+  },
+  "homepage": "https://github.com/hsidiyer/ez-reads#readme",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "cheerio": "^1.0.0-rc.12",
+    "dotenv": "^17.2.4",
+    "fs-extra": "^11.2.0",
+    "groq-sdk": "^0.37.0",
+    "inquirer": "^9.2.12",
+    "ora": "^8.0.1"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,243 @@
+import inquirer from 'inquirer';
+import ora from 'ora';
+import chalk from 'chalk';
+import path from 'path';
+import http from 'http';
+import fs from 'fs-extra';
+import { fileURLToPath } from 'url';
+import { fetchPaper } from './fetcher.mjs';
+import { distillPaper } from './distiller.mjs';
+import { generateSite } from './generator.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const OUTPUT_DIR = path.resolve(process.cwd(), 'ez-reads-output');
+
+const gd = chalk.blueBright;
+const dm = chalk.dim;
+const wh = chalk.white;
+const cn = chalk.cyan;
+
+const BANNER = `
+${dm('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')}
+
+${gd.bold('    ███████  █████  ███████ ██    ██')}
+${gd.bold('    ██      ██   ██ ██       ██  ██ ')}
+${gd.bold('    █████   ███████ ███████   ████  ')}
+${gd.bold('    ██      ██   ██      ██    ██   ')}
+${gd.bold('    ███████ ██   ██ ███████    ██   ')}
+
+${gd.bold('    ██████  ███████  █████  ██████  ███████')}
+${gd.bold('    ██   ██ ██      ██   ██ ██   ██ ██     ')}
+${gd.bold('    ██████  █████   ███████ ██   ██ ███████')}
+${gd.bold('    ██   ██ ██      ██   ██ ██   ██      ██')}
+${gd.bold('    ██   ██ ███████ ██   ██ ██████  ███████')}
+
+${wh.bold('    Make beautiful sites from research papers.')}
+
+${dm('    📄')} ${cn('paper')} ${dm('→')} ${dm('🔬')} ${cn('distill')} ${dm('→')} ${dm('✨')} ${cn('generate')} ${dm('→')} ${dm('🌐')} ${cn('site')}
+
+${dm('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')}
+`;
+
+export async function run() {
+  console.log(BANNER);
+
+  // Resolve API key — use env/dotenv if available, otherwise prompt
+  if (!process.env.GROQ_API_KEY) {
+    console.log(
+      chalk.yellow('  ⚡ A Groq API key is required to distill papers and power the chat assistant.\n') +
+      chalk.dim('    Get one free at: ') + chalk.cyan('https://console.groq.com/keys') + '\n' +
+      chalk.dim('    Model: ') + chalk.white('qwen/qwen3-32b') + chalk.dim(' (free tier)\n') +
+      chalk.dim('    Tip: set ') + chalk.white('GROQ_API_KEY=gsk_...') + chalk.dim(' in a .env file to skip this prompt.\n')
+    );
+
+    const { apiKey } = await inquirer.prompt([
+      {
+        type: 'password',
+        name: 'apiKey',
+        message: 'Enter your Groq API key:',
+        mask: '*',
+        validate: (val) => {
+          if (!val.trim()) return 'API key is required.';
+          if (!val.trim().startsWith('gsk_')) return 'Groq API keys start with gsk_. Get one at https://console.groq.com/keys';
+          return true;
+        },
+      },
+    ]);
+
+    process.env.GROQ_API_KEY = apiKey.trim();
+  }
+
+  console.log(
+    chalk.dim('  Model: ') + chalk.cyan('qwen/qwen3-32b') + chalk.dim(' via Groq') +
+    chalk.dim('  •  API key: ') + chalk.green('✓ loaded') +
+    chalk.dim('  •  Powers: distillation + chat assistant\n')
+  );
+
+  // Start the server once — it serves the entire output/ directory
+  const { port } = await startStaticServer(OUTPUT_DIR);
+  const libraryUrl = `http://localhost:${port}/`;
+
+  console.log(`  ${chalk.bold('Library:')} ${chalk.cyan(libraryUrl)}\n`);
+
+  // Process papers in a loop
+  let paperCount = 0;
+
+  while (true) {
+    const result = await processPaper(port);
+
+    if (result) {
+      paperCount++;
+      const paperUrl = `http://localhost:${port}/${result.slug}/`;
+
+      console.log(
+        `\n  ${chalk.green('Site is live!')}\n` +
+        `\n  ${chalk.bold('This paper:')}  ${chalk.cyan(paperUrl)}` +
+        `\n  ${chalk.bold('Library:')}     ${chalk.cyan(libraryUrl)}` +
+        `\n  ${chalk.dim(`${paperCount} paper${paperCount === 1 ? '' : 's'} generated this session.`)}\n`
+      );
+    }
+
+    // Ask if the user wants to add another paper
+    const { another } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'another',
+        message: 'Add another paper?',
+        default: true,
+      },
+    ]);
+
+    if (!another) break;
+
+    console.log(''); // spacing
+  }
+
+  console.log(
+    `\n  ${chalk.dim('Server still running at')} ${chalk.cyan(libraryUrl)}` +
+    `\n  ${chalk.dim('Press Ctrl+C to stop.')}\n`
+  );
+}
+
+// ---------- process a single paper ----------
+
+async function processPaper(port) {
+  // Prompt for paper link
+  const { input } = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'input',
+      message: 'Enter an ArXiv URL or DOI:',
+      validate: (val) => {
+        val = val.trim();
+        if (!val) return 'Please enter a URL or DOI.';
+        if (/arxiv\.org\/(abs|html|pdf)\//.test(val)) return true;
+        if (/^10\.\d{4,}\//.test(val) || /doi\.org\/10\.\d{4,}\//.test(val)) return true;
+        return 'Please enter a valid ArXiv URL or DOI (e.g., https://arxiv.org/abs/2401.00001 or 10.1234/example)';
+      },
+    },
+  ]);
+
+  // Fetch
+  const fetchSpinner = ora('Fetching paper content...').start();
+  let paperData;
+  try {
+    paperData = await fetchPaper(input.trim());
+    fetchSpinner.succeed(
+      `Fetched: ${chalk.bold(paperData.title || 'paper')} (${paperData.sections.length} sections)`
+    );
+  } catch (err) {
+    fetchSpinner.fail(`Failed to fetch paper: ${err.message}`);
+    return null;
+  }
+
+  // Distill
+  const distillSpinner = ora('Distilling paper...').start();
+  let distilled;
+  try {
+    distilled = await distillPaper(paperData, (chunkName, current, total) => {
+      distillSpinner.text = `Distilling: ${chunkName} (${current}/${total})...`;
+    });
+    distilled.url = paperData.url;
+    distilled.publishedDate = paperData.publishedDate || null;
+    distillSpinner.succeed('Paper distilled into structured data (5 chunks)');
+  } catch (err) {
+    distillSpinner.fail(`Failed to distill paper: ${err.message}`);
+    return null;
+  }
+
+  // Build
+  const genSpinner = ora('Building website...').start();
+  try {
+    const result = await generateSite(distilled, OUTPUT_DIR);
+    genSpinner.succeed(`Built: ${chalk.cyan(result.slug)}`);
+    return result;
+  } catch (err) {
+    genSpinner.fail(`Failed to build site: ${err.message}`);
+    return null;
+  }
+}
+
+// ---------- static file server ----------
+
+const MIME_TYPES = {
+  '.html': 'text/html; charset=utf-8',
+  '.js':   'text/javascript; charset=utf-8',
+  '.css':  'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.png':  'image/png',
+  '.jpg':  'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif':  'image/gif',
+  '.svg':  'image/svg+xml',
+  '.ico':  'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2':'font/woff2',
+  '.ttf':  'font/ttf',
+  '.webp': 'image/webp',
+};
+
+function startStaticServer(rootDir, port = 3000) {
+  return new Promise((resolve, reject) => {
+    // Ensure the output directory exists before serving
+    fs.ensureDirSync(rootDir);
+
+    const server = http.createServer(async (req, res) => {
+      const urlPath = decodeURIComponent(req.url.split('?')[0]);
+      let filePath = path.join(rootDir, urlPath);
+
+      // If it's a directory, serve index.html
+      try {
+        const stat = await fs.stat(filePath);
+        if (stat.isDirectory()) {
+          filePath = path.join(filePath, 'index.html');
+        }
+      } catch {
+        // file doesn't exist — will 404 below
+      }
+
+      try {
+        const data = await fs.readFile(filePath);
+        const ext = path.extname(filePath).toLowerCase();
+        const contentType = MIME_TYPES[ext] || 'application/octet-stream';
+        res.writeHead(200, { 'Content-Type': contentType });
+        res.end(data);
+      } catch {
+        res.writeHead(404, { 'Content-Type': 'text/plain' });
+        res.end('Not found');
+      }
+    });
+
+    server.listen(port, () => {
+      resolve({ server, port });
+    });
+
+    server.on('error', (err) => {
+      if (err.code === 'EADDRINUSE') {
+        startStaticServer(rootDir, port + 1).then(resolve, reject);
+      } else {
+        reject(err);
+      }
+    });
+  });
+}