papergraph 1.0.0

package/dist/index.js

@@ -0,0 +1,2695 @@
+#!/usr/bin/env node
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/cli/index.ts
+import { Command } from "commander";
+
+// src/utils/config.ts
+import { cosmiconfig } from "cosmiconfig";
+
+// src/types/config.ts
+var DEFAULT_CONFIG = {
+  source: "openalex",
+  spine: "citation",
+  depth: 2,
+  maxPapers: 150,
+  maxRefsPerPaper: 40,
+  maxCitesPerPaper: 40,
+  noCache: false,
+  resume: false,
+  logLevel: "info",
+  jsonLogs: false,
+  similarity: {
+    enabled: true,
+    topK: 10,
+    threshold: 0.25
+  },
+  clustering: {
+    enabled: true,
+    method: "louvain"
+  },
+  ranking: {
+    pagerankWeight: 0.5,
+    relevanceWeight: 0.3,
+    recencyWeight: 0.2
+  },
+  llm: {
+    enabled: false,
+    provider: "openai",
+    model: "gpt-4.1-mini",
+    tasks: ["edges", "clusters"],
+    maxAnnotatedPapers: 120,
+    maxAnnotatedEdges: 400,
+    concurrency: 3
+  }
+};
+
+// src/utils/logger.ts
+import pino from "pino";
+var loggerInstance = null;
+function initLogger(options) {
+  const { level = "info", jsonLogs = false } = options;
+  if (jsonLogs) {
+    loggerInstance = pino({ level });
+  } else {
+    loggerInstance = pino({
+      level,
+      transport: {
+        target: "pino-pretty",
+        options: {
+          colorize: true,
+          translateTime: "HH:MM:ss",
+          ignore: "pid,hostname"
+        }
+      }
+    });
+  }
+  return loggerInstance;
+}
+function getLogger() {
+  if (!loggerInstance) {
+    loggerInstance = initLogger({ level: "info" });
+  }
+  return loggerInstance;
+}
+
+// src/utils/config.ts
+async function loadConfigFile() {
+  const explorer = cosmiconfig("papergraph", {
+    searchPlaces: ["papergraph.config.json"]
+  });
+  try {
+    const result = await explorer.search();
+    if (result && !result.isEmpty) {
+      getLogger().debug({ path: result.filepath }, "Loaded config file");
+      return result.config;
+    }
+  } catch (error) {
+    getLogger().warn({ error }, "Failed to load config file, using defaults");
+  }
+  return null;
+}
+function loadEnvVars() {
+  const env = {};
+  if (process.env["OPENAI_API_KEY"] && !process.env["LLM_DISABLE"]) {
+    getLogger().debug("OPENAI_API_KEY detected in environment");
+  }
+  return env;
+}
+async function resolveConfig(cliFlags) {
+  const fileConfig = await loadConfigFile();
+  const envConfig = loadEnvVars();
+  const merged = {
+    ...DEFAULT_CONFIG,
+    out: "./papergraph.db",
+    ...fileConfig,
+    ...envConfig,
+    ...cliFlags,
+    // Deep merge nested objects
+    similarity: {
+      ...DEFAULT_CONFIG.similarity,
+      ...fileConfig?.similarity,
+      ...cliFlags.similarity
+    },
+    clustering: {
+      ...DEFAULT_CONFIG.clustering,
+      ...fileConfig?.clustering,
+      ...cliFlags.clustering
+    },
+    ranking: {
+      ...DEFAULT_CONFIG.ranking,
+      ...fileConfig?.ranking,
+      ...cliFlags.ranking
+    },
+    llm: {
+      ...DEFAULT_CONFIG.llm,
+      ...fileConfig?.llm,
+      ...cliFlags.llm
+    }
+  };
+  return merged;
+}
+
+// src/utils/http-client.ts
+var logger = getLogger();
+var RETRYABLE_STATUS_CODES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+var RETRYABLE_ERROR_CODES = /* @__PURE__ */ new Set(["ECONNRESET", "ECONNREFUSED", "ETIMEDOUT", "UND_ERR_SOCKET", "UND_ERR_CONNECT_TIMEOUT"]);
+var TokenBucket = class {
+  constructor(tokensPerSecond, maxTokens) {
+    this.tokensPerSecond = tokensPerSecond;
+    this.maxTokens = maxTokens;
+    this.tokens = maxTokens;
+    this.lastRefill = Date.now();
+  }
+  tokens;
+  lastRefill;
+  async acquire() {
+    this.refill();
+    if (this.tokens >= 1) {
+      this.tokens -= 1;
+      return;
+    }
+    const waitMs = (1 - this.tokens) / this.tokensPerSecond * 1e3;
+    await sleep(waitMs);
+    this.refill();
+    this.tokens -= 1;
+  }
+  refill() {
+    const now = Date.now();
+    const elapsed = (now - this.lastRefill) / 1e3;
+    this.tokens = Math.min(this.maxTokens, this.tokens + elapsed * this.tokensPerSecond);
+    this.lastRefill = now;
+  }
+};
+var RATE_LIMITS = {
+  openalex: { tokensPerSecond: 10, maxBurst: 10 },
+  // 10/s with polite pool
+  s2: { tokensPerSecond: 1, maxBurst: 1 },
+  // 1/s without API key, 10/s with
+  openai: { tokensPerSecond: 5, maxBurst: 5 },
+  ollama: { tokensPerSecond: 100, maxBurst: 100 },
+  // Local — effectively unlimited
+  default: { tokensPerSecond: 5, maxBurst: 5 }
+};
+var HttpError = class extends Error {
+  constructor(message, status, retryable, response) {
+    super(message);
+    this.status = status;
+    this.retryable = retryable;
+    this.response = response;
+    this.name = "HttpError";
+  }
+};
+var HttpClient = class {
+  buckets = /* @__PURE__ */ new Map();
+  requestCounts = /* @__PURE__ */ new Map();
+  defaultTimeout;
+  userAgent;
+  constructor(options) {
+    this.defaultTimeout = options?.timeout ?? 3e4;
+    const version = options?.version ?? "1.0.0";
+    const email = options?.email ?? "papergraph@example.com";
+    this.userAgent = `PaperGraph/${version} (mailto:${email})`;
+  }
+  /**
+   * Make an HTTP request with rate limiting and retry.
+   */
+  async request(url, options = {}) {
+    const {
+      method = "GET",
+      headers = {},
+      body,
+      timeout = this.defaultTimeout,
+      source = "default"
+    } = options;
+    const bucket = this.getBucket(source);
+    await bucket.acquire();
+    this.requestCounts.set(source, (this.requestCounts.get(source) ?? 0) + 1);
+    const requestHeaders = {
+      "User-Agent": this.userAgent,
+      ...headers
+    };
+    let requestBody;
+    if (body) {
+      if (typeof body === "object") {
+        requestBody = JSON.stringify(body);
+        requestHeaders["Content-Type"] = requestHeaders["Content-Type"] ?? "application/json";
+      } else {
+        requestBody = body;
+      }
+    }
+    const maxRetries = 3;
+    const initialBackoff = 1e3;
+    const maxBackoff = 3e4;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        const response = await fetch(url, {
+          method,
+          headers: requestHeaders,
+          body: requestBody,
+          signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        const contentType = response.headers.get("content-type") ?? "";
+        let data;
+        if (contentType.includes("application/json")) {
+          data = await response.json();
+        } else {
+          data = await response.text();
+        }
+        const responseHeaders = {};
+        response.headers.forEach((value, key) => {
+          responseHeaders[key] = value;
+        });
+        if (!response.ok) {
+          const retryable = RETRYABLE_STATUS_CODES.has(response.status);
+          if (retryable && attempt < maxRetries) {
+            const retryAfter = this.parseRetryAfter(response.headers.get("retry-after"));
+            const backoff = retryAfter ?? this.calculateBackoff(attempt, initialBackoff, maxBackoff);
+            logger.warn(
+              { status: response.status, attempt: attempt + 1, backoffMs: backoff, url },
+              `Retryable HTTP error, backing off`
+            );
+            await sleep(backoff);
+            continue;
+          }
+          throw new HttpError(
+            `HTTP ${response.status}: ${response.statusText}`,
+            response.status,
+            retryable,
+            data
+          );
+        }
+        return { status: response.status, headers: responseHeaders, data, ok: true };
+      } catch (error) {
+        if (error instanceof HttpError) throw error;
+        const errorCode = error.code;
+        const retryable = errorCode ? RETRYABLE_ERROR_CODES.has(errorCode) : false;
+        if (retryable && attempt < maxRetries) {
+          const backoff = this.calculateBackoff(attempt, initialBackoff, maxBackoff);
+          logger.warn(
+            { errorCode, attempt: attempt + 1, backoffMs: backoff, url },
+            `Retryable network error, backing off`
+          );
+          await sleep(backoff);
+          continue;
+        }
+        if (error instanceof Error && error.name === "AbortError") {
+          throw new HttpError(`Request timeout after ${timeout}ms: ${url}`, 0, true);
+        }
+        throw new HttpError(
+          `Network error: ${error instanceof Error ? error.message : String(error)}`,
+          0,
+          retryable
+        );
+      }
+    }
+    throw new HttpError(`Max retries exceeded for ${url}`, 0, false);
+  }
+  /**
+   * Convenience method for GET requests.
+   */
+  async get(url, options) {
+    return this.request(url, { ...options, method: "GET" });
+  }
+  /**
+   * Convenience method for POST requests.
+   */
+  async post(url, body, options) {
+    return this.request(url, { ...options, method: "POST", body });
+  }
+  /**
+   * Get request count for a source.
+   */
+  getRequestCount(source) {
+    return this.requestCounts.get(source) ?? 0;
+  }
+  /**
+   * Get all request counts.
+   */
+  getAllRequestCounts() {
+    return Object.fromEntries(this.requestCounts.entries());
+  }
+  /**
+   * Reset request counts.
+   */
+  resetCounts() {
+    this.requestCounts.clear();
+  }
+  getBucket(source) {
+    if (!this.buckets.has(source)) {
+      const config = RATE_LIMITS[source] ?? RATE_LIMITS["default"];
+      this.buckets.set(source, new TokenBucket(config.tokensPerSecond, config.maxBurst));
+    }
+    return this.buckets.get(source);
+  }
+  parseRetryAfter(header) {
+    if (!header) return null;
+    const seconds = parseInt(header, 10);
+    if (!isNaN(seconds)) return seconds * 1e3;
+    const date = new Date(header);
+    if (!isNaN(date.getTime())) {
+      return Math.max(0, date.getTime() - Date.now());
+    }
+    return null;
+  }
+  calculateBackoff(attempt, initial, max) {
+    const exponential = initial * Math.pow(2, attempt);
+    const jitter = Math.random() * exponential * 0.5;
+    return Math.min(max, exponential + jitter);
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+var clientInstance = null;
+function getHttpClient(options) {
+  if (!clientInstance) {
+    clientInstance = new HttpClient(options);
+  }
+  return clientInstance;
+}
+
+// src/storage/database.ts
+import Database from "better-sqlite3";
+var logger2 = getLogger();
+var MIGRATION_V1 = `
+-- Runs: build session metadata
+CREATE TABLE IF NOT EXISTS runs (
+  run_id INTEGER PRIMARY KEY,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  papergraph_version TEXT NOT NULL,
+  config_json TEXT NOT NULL,
+  source TEXT NOT NULL,
+  spine TEXT NOT NULL,
+  depth INTEGER NOT NULL,
+  stats_json TEXT NOT NULL DEFAULT '{}'
+);
+
+-- Papers: core paper nodes
+CREATE TABLE IF NOT EXISTS papers (
+  paper_id INTEGER PRIMARY KEY,
+  source TEXT NOT NULL,
+  source_id TEXT NOT NULL,
+  doi TEXT,
+  arxiv_id TEXT,
+  title TEXT NOT NULL,
+  abstract TEXT,
+  year INTEGER,
+  venue TEXT,
+  url TEXT,
+  citation_count INTEGER NOT NULL DEFAULT 0,
+  influence_score REAL,
+  keywords_json TEXT,
+  concepts_json TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+-- Edges: relationships between papers
+CREATE TABLE IF NOT EXISTS edges (
+  edge_id INTEGER PRIMARY KEY,
+  src_paper_id INTEGER NOT NULL REFERENCES papers(paper_id),
+  dst_paper_id INTEGER NOT NULL REFERENCES papers(paper_id),
+  type TEXT NOT NULL,
+  weight REAL NOT NULL DEFAULT 1.0,
+  confidence REAL NOT NULL DEFAULT 1.0,
+  rationale TEXT,
+  evidence TEXT,
+  created_by TEXT NOT NULL DEFAULT 'algo',
+  provenance_json TEXT NOT NULL DEFAULT '{}',
+  created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+-- Authors
+CREATE TABLE IF NOT EXISTS authors (
+  author_id INTEGER PRIMARY KEY,
+  name TEXT NOT NULL,
+  source_id TEXT,
+  affiliation TEXT
+);
+
+-- Paper-Author junction
+CREATE TABLE IF NOT EXISTS paper_authors (
+  paper_id INTEGER NOT NULL REFERENCES papers(paper_id),
+  author_id INTEGER NOT NULL REFERENCES authors(author_id),
+  position INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (paper_id, author_id)
+);
+
+-- Clusters: community detection results
+CREATE TABLE IF NOT EXISTS clusters (
+  cluster_id INTEGER PRIMARY KEY,
+  method TEXT NOT NULL,
+  name TEXT,
+  description TEXT,
+  stats_json TEXT NOT NULL DEFAULT '{}'
+);
+
+-- Paper-Cluster junction
+CREATE TABLE IF NOT EXISTS paper_clusters (
+  paper_id INTEGER NOT NULL REFERENCES papers(paper_id),
+  cluster_id INTEGER NOT NULL REFERENCES clusters(cluster_id),
+  PRIMARY KEY (paper_id, cluster_id)
+);
+
+-- Entities: extracted datasets/methods/tasks/metrics
+CREATE TABLE IF NOT EXISTS entities (
+  entity_id INTEGER PRIMARY KEY,
+  type TEXT NOT NULL,
+  name TEXT NOT NULL,
+  aliases_json TEXT NOT NULL DEFAULT '[]'
+);
+
+-- Paper-Entity junction
+CREATE TABLE IF NOT EXISTS paper_entities (
+  paper_id INTEGER NOT NULL REFERENCES papers(paper_id),
+  entity_id INTEGER NOT NULL REFERENCES entities(entity_id),
+  role TEXT NOT NULL DEFAULT 'uses',
+  PRIMARY KEY (paper_id, entity_id)
+);
+
+-- Indexes for edges (fast lookup by src, dst, type)
+CREATE INDEX IF NOT EXISTS idx_edges_src ON edges(src_paper_id);
+CREATE INDEX IF NOT EXISTS idx_edges_dst ON edges(dst_paper_id);
+CREATE INDEX IF NOT EXISTS idx_edges_type ON edges(type);
+
+-- Indexes for papers (fast lookup by doi, arxiv, source_id, year)
+CREATE INDEX IF NOT EXISTS idx_papers_doi ON papers(doi);
+CREATE INDEX IF NOT EXISTS idx_papers_arxiv ON papers(arxiv_id);
+CREATE INDEX IF NOT EXISTS idx_papers_source_id ON papers(source_id);
+CREATE INDEX IF NOT EXISTS idx_papers_year ON papers(year);
+
+-- Unique constraint on source + source_id to prevent duplicates
+CREATE UNIQUE INDEX IF NOT EXISTS idx_papers_source_unique ON papers(source, source_id);
+`;
+var PaperGraphDatabase = class {
+  db;
+  constructor(dbPath) {
+    this.db = new Database(dbPath);
+    this.db.pragma("journal_mode = WAL");
+    this.db.pragma("foreign_keys = ON");
+    this.migrate();
+    logger2.debug({ dbPath }, "Database initialized");
+  }
+  /**
+   * Run schema migrations.
+   */
+  migrate() {
+    const currentVersion = this.db.pragma("user_version", { simple: true });
+    if (currentVersion < 1) {
+      this.db.exec(MIGRATION_V1);
+      this.db.pragma("user_version = 1");
+      logger2.info("Database migrated to v1");
+    }
+  }
+  // ─── Papers ───────────────────────────────────────────────
+  /**
+   * Insert multiple papers in a single transaction.
+   * Returns the inserted paper IDs.
+   */
+  insertPapers(papers) {
+    const stmt = this.db.prepare(`
+      INSERT OR IGNORE INTO papers (source, source_id, doi, arxiv_id, title, abstract, year, venue, url, citation_count, influence_score, keywords_json, concepts_json)
+      VALUES (@source, @source_id, @doi, @arxiv_id, @title, @abstract, @year, @venue, @url, @citation_count, @influence_score, @keywords_json, @concepts_json)
+    `);
+    const ids = [];
+    const insertAll = this.db.transaction((papers2) => {
+      for (const paper of papers2) {
+        const result = stmt.run(paper);
+        if (result.changes > 0) {
+          ids.push(Number(result.lastInsertRowid));
+        } else {
+          const existing = this.getPaperBySourceId(paper.source, paper.source_id);
+          if (existing) ids.push(existing.paper_id);
+        }
+      }
+    });
+    insertAll(papers);
+    return ids;
+  }
+  /**
+   * Upsert a single paper. If it already exists (by source+source_id), update it.
+   */
+  upsertPaper(paper) {
+    const stmt = this.db.prepare(`
+      INSERT INTO papers (source, source_id, doi, arxiv_id, title, abstract, year, venue, url, citation_count, influence_score, keywords_json, concepts_json)
+      VALUES (@source, @source_id, @doi, @arxiv_id, @title, @abstract, @year, @venue, @url, @citation_count, @influence_score, @keywords_json, @concepts_json)
+      ON CONFLICT(source, source_id) DO UPDATE SET
+        doi = COALESCE(excluded.doi, doi),
+        arxiv_id = COALESCE(excluded.arxiv_id, arxiv_id),
+        title = excluded.title,
+        abstract = COALESCE(excluded.abstract, abstract),
+        year = COALESCE(excluded.year, year),
+        venue = COALESCE(excluded.venue, venue),
+        url = COALESCE(excluded.url, url),
+        citation_count = MAX(citation_count, excluded.citation_count),
+        influence_score = COALESCE(excluded.influence_score, influence_score),
+        keywords_json = COALESCE(excluded.keywords_json, keywords_json),
+        concepts_json = COALESCE(excluded.concepts_json, concepts_json)
+    `);
+    const result = stmt.run(paper);
+    if (result.changes > 0 && result.lastInsertRowid) {
+      return Number(result.lastInsertRowid);
+    }
+    const existing = this.getPaperBySourceId(paper.source, paper.source_id);
+    return existing?.paper_id ?? -1;
+  }
+  getPaperById(id) {
+    return this.db.prepare("SELECT * FROM papers WHERE paper_id = ?").get(id);
+  }
+  getPaperByDoi(doi) {
+    return this.db.prepare("SELECT * FROM papers WHERE doi = ?").get(doi);
+  }
+  getPaperBySourceId(source, sourceId) {
+    return this.db.prepare("SELECT * FROM papers WHERE source = ? AND source_id = ?").get(source, sourceId);
+  }
+  paperExists(source, sourceId) {
+    const row = this.db.prepare("SELECT 1 FROM papers WHERE source = ? AND source_id = ?").get(source, sourceId);
+    return row !== void 0;
+  }
+  getAllPapers() {
+    return this.db.prepare("SELECT * FROM papers ORDER BY paper_id").all();
+  }
+  getPaperCount() {
+    const row = this.db.prepare("SELECT COUNT(*) as count FROM papers").get();
+    return row.count;
+  }
+  // ─── Edges ────────────────────────────────────────────────
+  /**
+   * Insert multiple edges in a single transaction.
+   */
+  insertEdges(edges) {
+    const stmt = this.db.prepare(`
+      INSERT INTO edges (src_paper_id, dst_paper_id, type, weight, confidence, rationale, evidence, created_by, provenance_json)
+      VALUES (@src_paper_id, @dst_paper_id, @type, @weight, @confidence, @rationale, @evidence, @created_by, @provenance_json)
+    `);
+    const insertAll = this.db.transaction((edges2) => {
+      for (const edge of edges2) {
+        stmt.run(edge);
+      }
+    });
+    insertAll(edges);
+  }
+  getAllEdges() {
+    return this.db.prepare("SELECT * FROM edges ORDER BY edge_id").all();
+  }
+  getEdgesByType(type) {
+    return this.db.prepare("SELECT * FROM edges WHERE type = ?").all(type);
+  }
+  getEdgeCount() {
+    const row = this.db.prepare("SELECT COUNT(*) as count FROM edges").get();
+    return row.count;
+  }
+  // ─── Authors ──────────────────────────────────────────────
+  insertAuthors(authors, paperLinks) {
+    const authorStmt = this.db.prepare(`
+      INSERT OR IGNORE INTO authors (name, source_id, affiliation)
+      VALUES (@name, @source_id, @affiliation)
+    `);
+    const linkStmt = this.db.prepare(`
+      INSERT OR IGNORE INTO paper_authors (paper_id, author_id, position)
+      VALUES (?, ?, ?)
+    `);
+    const insertAll = this.db.transaction(() => {
+      const authorIds = [];
+      for (const author of authors) {
+        const result = authorStmt.run(author);
+        authorIds.push(Number(result.lastInsertRowid));
+      }
+      for (const link of paperLinks) {
+        const authorId = authorIds[link.authorIndex];
+        if (authorId !== void 0) {
+          linkStmt.run(link.paperId, authorId, link.position);
+        }
+      }
+    });
+    insertAll();
+  }
+  // ─── Clusters ─────────────────────────────────────────────
+  insertClusters(clusters, paperMappings) {
+    const clusterStmt = this.db.prepare(`
+      INSERT INTO clusters (method, name, description, stats_json)
+      VALUES (@method, @name, @description, @stats_json)
+    `);
+    const linkStmt = this.db.prepare(`
+      INSERT OR IGNORE INTO paper_clusters (paper_id, cluster_id)
+      VALUES (?, ?)
+    `);
+    const insertAll = this.db.transaction(() => {
+      let clusterIndex = 0;
+      for (const cluster of clusters) {
+        const result = clusterStmt.run(cluster);
+        const clusterId = Number(result.lastInsertRowid);
+        const paperIds = paperMappings.get(clusterIndex) ?? [];
+        for (const paperId of paperIds) {
+          linkStmt.run(paperId, clusterId);
+        }
+        clusterIndex++;
+      }
+    });
+    insertAll();
+  }
+  getAllClusters() {
+    return this.db.prepare("SELECT * FROM clusters ORDER BY cluster_id").all();
+  }
+  getClusterCount() {
+    const row = this.db.prepare("SELECT COUNT(*) as count FROM clusters").get();
+    return row.count;
+  }
+  // ─── Entities ─────────────────────────────────────────────
+  insertEntities(entities, paperLinks) {
+    const entityStmt = this.db.prepare(`
+      INSERT OR IGNORE INTO entities (type, name, aliases_json)
+      VALUES (@type, @name, @aliases_json)
+    `);
+    const getEntityStmt = this.db.prepare(`
+      SELECT entity_id FROM entities WHERE type = ? AND name = ?
+    `);
+    const linkStmt = this.db.prepare(`
+      INSERT OR IGNORE INTO paper_entities (paper_id, entity_id, role)
+      VALUES (?, ?, ?)
+    `);
+    const insertAll = this.db.transaction(() => {
+      const entityIds = [];
+      for (const entity of entities) {
+        const result = entityStmt.run(entity);
+        if (result.changes > 0) {
+          entityIds.push(Number(result.lastInsertRowid));
+        } else {
+          const existing = getEntityStmt.get(entity.type, entity.name);
+          entityIds.push(existing?.entity_id ?? -1);
+        }
+      }
+      for (const link of paperLinks) {
+        const entityId = entityIds[link.entityIndex];
+        if (entityId !== void 0 && entityId !== -1) {
+          linkStmt.run(link.paperId, entityId, link.role);
+        }
+      }
+    });
+    insertAll();
+  }
+  getAllEntities() {
+    return this.db.prepare("SELECT * FROM entities ORDER BY entity_id").all();
+  }
+  getEntityCount() {
+    const row = this.db.prepare("SELECT COUNT(*) as count FROM entities").get();
+    return row.count;
+  }
+  // ─── Runs ─────────────────────────────────────────────────
+  insertRun(run) {
+    const stmt = this.db.prepare(`
+      INSERT INTO runs (created_at, papergraph_version, config_json, source, spine, depth, stats_json)
+      VALUES (@created_at, @papergraph_version, @config_json, @source, @spine, @depth, @stats_json)
+    `);
+    const result = stmt.run(run);
+    return Number(result.lastInsertRowid);
+  }
+  // ─── Stats ────────────────────────────────────────────────
+  getStats() {
+    const papers = this.getPaperCount();
+    const edges = this.getEdgeCount();
+    const clusters = this.getClusterCount();
+    const entities = this.getEntityCount();
+    const runs = this.db.prepare("SELECT COUNT(*) as count FROM runs").get().count;
+    const edgeTypeRows = this.db.prepare("SELECT type, COUNT(*) as count FROM edges GROUP BY type").all();
+    const edgesByType = {};
+    for (const row of edgeTypeRows) {
+      edgesByType[row.type] = row.count;
+    }
+    return { papers, edges, clusters, entities, runs, edgesByType };
+  }
+  // ─── Score Updates ────────────────────────────────────────
+  /**
+   * Update influence_score for a paper by its paper_id.
+   */
+  updatePaperScore(paperId, score) {
+    this.db.prepare("UPDATE papers SET influence_score = ? WHERE paper_id = ?").run(score, paperId);
+  }
+  // ─── Utility ──────────────────────────────────────────────
+  /**
+   * Execute a function within a transaction.
+   */
+  transaction(fn) {
+    return this.db.transaction(fn)();
+  }
+  /**
+   * Close the database connection.
+   */
+  close() {
+    this.db.close();
+    logger2.debug("Database closed");
+  }
+  /**
+   * Get the raw better-sqlite3 instance (for advanced queries).
+   */
+  getRawDb() {
+    return this.db;
+  }
+};
+
+// src/sources/utils.ts
+function invertedIndexToText(invertedIndex) {
+  if (!invertedIndex || typeof invertedIndex !== "object") {
+    return null;
+  }
+  try {
+    const words = [];
+    for (const [word, positions] of Object.entries(invertedIndex)) {
+      if (!Array.isArray(positions)) continue;
+      for (const pos of positions) {
+        if (typeof pos === "number" && pos >= 0) {
+          words.push([pos, word]);
+        }
+      }
+    }
+    if (words.length === 0) return null;
+    words.sort((a, b) => a[0] - b[0]);
+    return words.map(([, word]) => word).join(" ");
+  } catch {
+    return null;
+  }
+}
+function stripDoiPrefix(doi) {
+  if (!doi) return null;
+  return doi.replace("https://doi.org/", "").replace("http://doi.org/", "").trim() || null;
+}
+function extractArxivId(input) {
+  if (!input) return null;
+  const patterns = [
+    /arxiv\.org\/abs\/(\d{4}\.\d{4,5}(?:v\d+)?)/i,
+    /arxiv:(\d{4}\.\d{4,5}(?:v\d+)?)/i,
+    /^(\d{4}\.\d{4,5}(?:v\d+)?)$/
+  ];
+  for (const pattern of patterns) {
+    const match = input.match(pattern);
+    if (match?.[1]) return match[1];
+  }
+  return null;
+}
+
+// src/sources/openalex.ts
+var logger3 = getLogger();
+var OPENALEX_BASE = "https://api.openalex.org";
+var OpenAlexAdapter = class {
+  name = "OpenAlex";
+  sourceId = "openalex";
+  httpClient;
+  apiKey;
+  email;
+  constructor(options) {
+    this.apiKey = options?.apiKey ?? process.env["OPENALEX_API_KEY"];
+    this.email = options?.email;
+    this.httpClient = getHttpClient();
+  }
+  /**
+   * For dependency injection in tests.
+   */
+  setHttpClient(client) {
+    this.httpClient = client;
+  }
+  async searchByTopic(topic, limit = 25) {
+    const params = new URLSearchParams({
+      search: topic,
+      per_page: String(Math.min(limit, 200)),
+      sort: "cited_by_count:desc"
+    });
+    this.addAuthParams(params);
+    const url = `${OPENALEX_BASE}/works?${params.toString()}`;
+    logger3.debug({ url }, "OpenAlex topic search");
+    const response = await this.httpClient.get(url, { source: "openalex" });
+    return response.data.results.map((work) => this.normalizeWork(work));
+  }
+  async searchByTitle(title, limit = 10) {
+    const exactParams = new URLSearchParams({
+      "filter": `title.search:${title}`,
+      "per_page": String(Math.min(limit, 200)),
+      "sort": "cited_by_count:desc"
+    });
+    this.addAuthParams(exactParams);
+    const exactUrl = `${OPENALEX_BASE}/works?${exactParams.toString()}`;
+    logger3.debug({ url: exactUrl }, "OpenAlex title search (exact)");
+    const exactResponse = await this.httpClient.get(exactUrl, { source: "openalex" });
+    if (exactResponse.data.results.length > 0) {
+      return exactResponse.data.results.map((work) => this.normalizeWork(work));
+    }
+    const fallbackParams = new URLSearchParams({
+      search: title,
+      per_page: String(Math.min(limit, 200)),
+      sort: "cited_by_count:desc"
+    });
+    this.addAuthParams(fallbackParams);
+    const fallbackUrl = `${OPENALEX_BASE}/works?${fallbackParams.toString()}`;
+    logger3.debug({ url: fallbackUrl }, "OpenAlex title search (fallback)");
+    const fallbackResponse = await this.httpClient.get(fallbackUrl, { source: "openalex" });
+    return fallbackResponse.data.results.map((work) => this.normalizeWork(work));
+  }
+  async fetchPaper(id) {
+    const normalizedId = id.startsWith("https://openalex.org/") ? id : `https://openalex.org/${id}`;
+    const params = new URLSearchParams();
+    this.addAuthParams(params);
+    const url = `${OPENALEX_BASE}/works/${encodeURIComponent(normalizedId)}?${params.toString()}`;
+    logger3.debug({ url }, "OpenAlex fetch paper");
+    try {
+      const response = await this.httpClient.get(url, { source: "openalex" });
+      return this.normalizeWork(response.data);
+    } catch (error) {
+      logger3.warn({ id, error }, "Failed to fetch paper from OpenAlex");
+      return null;
+    }
+  }
+  async fetchReferences(paperId, limit = 40) {
+    const paper = await this.fetchFullWork(paperId);
+    if (!paper?.referenced_works?.length) {
+      logger3.debug({ paperId }, "No references found");
+      return [];
+    }
+    const refIds = paper.referenced_works.slice(0, limit);
+    return this.fetchWorksByIds(refIds);
+  }
+  async fetchCitations(paperId, limit = 40) {
+    const normalizedId = paperId.startsWith("https://openalex.org/") ? paperId : `https://openalex.org/${paperId}`;
+    const params = new URLSearchParams({
+      "filter": `cites:${normalizedId}`,
+      "per_page": String(Math.min(limit, 200)),
+      "sort": "cited_by_count:desc"
+    });
+    this.addAuthParams(params);
+    const url = `${OPENALEX_BASE}/works?${params.toString()}`;
+    logger3.debug({ url }, "OpenAlex fetch citations");
+    const response = await this.httpClient.get(url, { source: "openalex" });
+    return response.data.results.map((work) => this.normalizeWork(work));
+  }
+  normalize(raw) {
+    return this.normalizeWork(raw);
+  }
+  // ─── Private helpers ──────────────────────────────────────
+  async fetchFullWork(id) {
+    const normalizedId = id.startsWith("https://openalex.org/") ? id : `https://openalex.org/${id}`;
+    const params = new URLSearchParams();
+    this.addAuthParams(params);
+    const url = `${OPENALEX_BASE}/works/${encodeURIComponent(normalizedId)}?${params.toString()}`;
+    try {
+      const response = await this.httpClient.get(url, { source: "openalex" });
+      return response.data;
+    } catch {
+      return null;
+    }
+  }
+  async fetchWorksByIds(ids) {
+    if (ids.length === 0) return [];
+    const batchSize = 50;
+    const papers = [];
+    for (let i = 0; i < ids.length; i += batchSize) {
+      const batch = ids.slice(i, i + batchSize);
+      const filter = batch.map((id) => id.replace("https://openalex.org/", "")).join("|");
+      const params = new URLSearchParams({
+        "filter": `openalex:${filter}`,
+        "per_page": String(batchSize)
+      });
+      this.addAuthParams(params);
+      const url = `${OPENALEX_BASE}/works?${params.toString()}`;
+      try {
+        const response = await this.httpClient.get(url, { source: "openalex" });
+        papers.push(...response.data.results.map((work) => this.normalizeWork(work)));
+      } catch (error) {
+        logger3.warn({ error, batchIndex: i }, "Failed to fetch batch of works");
+      }
+    }
+    return papers;
+  }
+  normalizeWork(work) {
+    const openalexId = work.id?.replace("https://openalex.org/", "") ?? "";
+    const doi = stripDoiPrefix(work.doi);
+    const abstract = invertedIndexToText(work.abstract_inverted_index);
+    let arxivId = null;
+    if (doi?.includes("arxiv")) {
+      arxivId = extractArxivId(doi);
+    }
+    const keywords = work.keywords?.map((k) => k.keyword).filter((k) => !!k) ?? [];
+    const concepts = work.concepts?.filter((c) => (c.level ?? 0) <= 2).map((c) => ({ name: c.display_name ?? "", score: c.score })).filter((c) => c.name) ?? [];
+    return {
+      source: "openalex",
+      source_id: openalexId,
+      doi,
+      arxiv_id: arxivId,
+      title: work.display_name ?? work.title ?? "Untitled",
+      abstract,
+      year: work.publication_year ?? null,
+      venue: work.primary_location?.source?.display_name ?? null,
+      url: work.primary_location?.landing_page_url ?? (doi ? `https://doi.org/${doi}` : null),
+      citation_count: work.cited_by_count ?? 0,
+      influence_score: null,
+      keywords_json: keywords.length > 0 ? JSON.stringify(keywords) : null,
+      concepts_json: concepts.length > 0 ? JSON.stringify(concepts) : null
+    };
+  }
+  addAuthParams(params) {
+    if (this.apiKey) {
+      params.set("api_key", this.apiKey);
+    }
+    if (this.email) {
+      params.set("mailto", this.email);
+    }
+  }
+};
+
+// src/sources/semantic-scholar.ts
+var logger4 = getLogger();
+var S2_BASE = "https://api.semanticscholar.org/graph/v1";
+var PAPER_FIELDS = [
+  "paperId",
+  "externalIds",
+  "title",
+  "abstract",
+  "year",
+  "venue",
+  "citationCount",
+  "influentialCitationCount",
+  "isOpenAccess",
+  "fieldsOfStudy",
+  "authors",
+  "url"
+].join(",");
+var REFERENCE_FIELDS = [
+  "paperId",
+  "externalIds",
+  "title",
+  "abstract",
+  "year",
+  "venue",
+  "citationCount",
+  "influentialCitationCount",
+  "url",
+  "authors"
+].join(",");
+var SemanticScholarAdapter = class {
+  name = "Semantic Scholar";
+  sourceId = "s2";
+  httpClient;
+  apiKey;
+  constructor(options) {
+    this.apiKey = options?.apiKey ?? process.env["S2_API_KEY"];
+    this.httpClient = getHttpClient();
+  }
+  /**
+   * For dependency injection in tests.
+   */
+  setHttpClient(client) {
+    this.httpClient = client;
+  }
+  async searchByTopic(topic, limit = 25) {
+    const cleanedQuery = this.cleanSearchQuery(topic);
+    const params = new URLSearchParams({
+      query: cleanedQuery,
+      limit: String(Math.min(limit, 100)),
+      fields: PAPER_FIELDS
+    });
+    const url = `${S2_BASE}/paper/search?${params.toString()}`;
+    logger4.debug({ url }, "S2 topic search");
+    const response = await this.httpClient.get(url, {
+      source: "s2",
+      headers: this.buildHeaders()
+    });
+    return (response.data.data ?? []).map((paper) => this.normalizeS2Paper(paper));
+  }
+  async searchByTitle(title, limit = 10) {
+    const cleanedQuery = this.cleanSearchQuery(title);
+    const params = new URLSearchParams({
+      query: cleanedQuery,
+      limit: String(Math.min(limit, 100)),
+      fields: PAPER_FIELDS
+    });
+    const url = `${S2_BASE}/paper/search?${params.toString()}`;
+    logger4.debug({ url }, "S2 title search");
+    const response = await this.httpClient.get(url, {
+      source: "s2",
+      headers: this.buildHeaders()
+    });
+    return (response.data.data ?? []).map((paper) => this.normalizeS2Paper(paper));
+  }
+  async fetchPaper(id) {
+    const url = `${S2_BASE}/paper/${encodeURIComponent(id)}?fields=${PAPER_FIELDS}`;
+    logger4.debug({ url }, "S2 fetch paper");
+    try {
+      const response = await this.httpClient.get(url, {
+        source: "s2",
+        headers: this.buildHeaders()
+      });
+      return this.normalizeS2Paper(response.data);
+    } catch (error) {
+      logger4.warn({ id, error }, "Failed to fetch paper from S2");
+      return null;
+    }
+  }
+  async fetchReferences(paperId, limit = 40) {
+    const params = new URLSearchParams({
+      fields: REFERENCE_FIELDS,
+      limit: String(Math.min(limit, 1e3))
+    });
+    const url = `${S2_BASE}/paper/${encodeURIComponent(paperId)}/references?${params.toString()}`;
+    logger4.debug({ url }, "S2 fetch references");
+    try {
+      const response = await this.httpClient.get(url, {
+        source: "s2",
+        headers: this.buildHeaders()
+      });
+      return (response.data.data ?? []).map((ref) => ref.citedPaper).filter((p) => p.paperId && p.title).map((paper) => this.normalizeS2Paper(paper));
+    } catch (error) {
+      logger4.warn({ paperId, error }, "Failed to fetch references from S2");
+      return [];
+    }
+  }
+  async fetchCitations(paperId, limit = 40) {
+    const params = new URLSearchParams({
+      fields: REFERENCE_FIELDS,
+      limit: String(Math.min(limit, 1e3))
+    });
+    const url = `${S2_BASE}/paper/${encodeURIComponent(paperId)}/citations?${params.toString()}`;
+    logger4.debug({ url }, "S2 fetch citations");
+    try {
+      const response = await this.httpClient.get(url, {
+        source: "s2",
+        headers: this.buildHeaders()
+      });
+      return (response.data.data ?? []).map((cite) => cite.citingPaper).filter((p) => p.paperId && p.title).map((paper) => this.normalizeS2Paper(paper));
+    } catch (error) {
+      logger4.warn({ paperId, error }, "Failed to fetch citations from S2");
+      return [];
+    }
+  }
+  /**
+   * Batch fetch papers by IDs.
+   * S2 supports up to 500 papers per batch request.
+   */
+  async batchFetchPapers(ids) {
+    if (ids.length === 0) return [];
+    const batchSize = 500;
+    const papers = [];
+    for (let i = 0; i < ids.length; i += batchSize) {
+      const batch = ids.slice(i, i + batchSize);
+      const url = `${S2_BASE}/paper/batch?fields=${PAPER_FIELDS}`;
+      logger4.debug({ batchSize: batch.length, batchIndex: i / batchSize }, "S2 batch fetch");
+      try {
+        const response = await this.httpClient.post(
+          url,
+          { ids: batch },
+          { source: "s2", headers: this.buildHeaders() }
+        );
+        const batchPapers = (response.data ?? []).filter((p) => p && p.paperId && p.title).map((paper) => this.normalizeS2Paper(paper));
+        papers.push(...batchPapers);
+      } catch (error) {
+        logger4.warn({ error, batchIndex: i / batchSize }, "Failed batch fetch from S2");
+      }
+    }
+    return papers;
+  }
+  normalize(raw) {
+    return this.normalizeS2Paper(raw);
+  }
+  // ─── Private helpers ──────────────────────────────────────
+  normalizeS2Paper(paper) {
+    const doi = stripDoiPrefix(paper.externalIds?.DOI ?? null);
+    const arxivId = extractArxivId(paper.externalIds?.ArXiv ?? null);
+    return {
+      source: "s2",
+      source_id: paper.paperId,
+      doi,
+      arxiv_id: arxivId,
+      title: paper.title ?? "Untitled",
+      abstract: paper.abstract ?? null,
+      year: paper.year ?? null,
+      venue: paper.venue || null,
+      url: paper.url ?? (doi ? `https://doi.org/${doi}` : null),
+      citation_count: paper.citationCount ?? 0,
+      influence_score: paper.influentialCitationCount ?? null,
+      keywords_json: paper.fieldsOfStudy ? JSON.stringify(paper.fieldsOfStudy) : null,
+      concepts_json: null
+    };
+  }
+  /**
+   * Clean search query — S2 treats hyphens and plus signs as operators.
+   */
+  cleanSearchQuery(query) {
+    return query.replace(/[-+]/g, " ").replace(/\s+/g, " ").trim();
+  }
+  buildHeaders() {
+    const headers = {};
+    if (this.apiKey) {
+      headers["x-api-key"] = this.apiKey;
+    }
+    return headers;
+  }
+};
+
+// src/nlp/stopwords.ts
+var STOPWORDS = /* @__PURE__ */ new Set([
+  "a",
+  "about",
+  "above",
+  "after",
+  "again",
+  "against",
+  "all",
+  "am",
+  "an",
+  "and",
+  "any",
+  "are",
+  "aren",
+  "aren't",
+  "as",
+  "at",
+  "be",
+  "because",
+  "been",
+  "before",
+  "being",
+  "below",
+  "between",
+  "both",
+  "but",
+  "by",
+  "can",
+  "could",
+  "couldn",
+  "couldn't",
+  "d",
+  "did",
+  "didn",
+  "didn't",
+  "do",
+  "does",
+  "doesn",
+  "doesn't",
+  "doing",
+  "don",
+  "don't",
+  "down",
+  "during",
+  "each",
+  "few",
+  "for",
+  "from",
+  "further",
+  "get",
+  "got",
+  "had",
+  "hadn",
+  "hadn't",
+  "has",
+  "hasn",
+  "hasn't",
+  "have",
+  "haven",
+  "haven't",
+  "having",
+  "he",
+  "her",
+  "here",
+  "hers",
+  "herself",
+  "him",
+  "himself",
+  "his",
+  "how",
+  "i",
+  "if",
+  "in",
+  "into",
+  "is",
+  "isn",
+  "isn't",
+  "it",
+  "it's",
+  "its",
+  "itself",
+  "just",
+  "let",
+  "ll",
+  "m",
+  "ma",
+  "may",
+  "me",
+  "might",
+  "mightn",
+  "mightn't",
+  "more",
+  "most",
+  "much",
+  "must",
+  "mustn",
+  "mustn't",
+  "my",
+  "myself",
+  "need",
+  "needn",
+  "needn't",
+  "no",
+  "nor",
+  "not",
+  "now",
+  "o",
+  "of",
+  "off",
+  "on",
+  "once",
+  "only",
+  "or",
+  "other",
+  "our",
+  "ours",
+  "ourselves",
+  "out",
+  "over",
+  "own",
+  "quite",
+  "re",
+  "s",
+  "said",
+  "same",
+  "shan",
+  "shan't",
+  "she",
+  "she's",
+  "should",
+  "should've",
+  "shouldn",
+  "shouldn't",
+  "so",
+  "some",
+  "such",
+  "t",
+  "than",
+  "that",
+  "that'll",
+  "the",
+  "their",
+  "theirs",
+  "them",
+  "themselves",
+  "then",
+  "there",
+  "these",
+  "they",
+  "this",
+  "those",
+  "through",
+  "to",
+  "too",
+  "under",
+  "until",
+  "up",
+  "upon",
+  "ve",
+  "very",
+  "was",
+  "wasn",
+  "wasn't",
+  "we",
+  "were",
+  "weren",
+  "weren't",
+  "what",
+  "when",
+  "where",
+  "which",
+  "while",
+  "who",
+  "whom",
+  "why",
+  "will",
+  "with",
+  "won",
+  "won't",
+  "would",
+  "wouldn",
+  "wouldn't",
+  "y",
+  "you",
+  "you'd",
+  "you'll",
+  "you're",
+  "you've",
+  "your",
+  "yours",
+  "yourself",
+  "yourselves",
+  // Additional academic/generic stopwords
+  "also",
+  "based",
+  "et",
+  "al",
+  "using",
+  "via",
+  "vs",
+  "use",
+  "used",
+  "show",
+  "shows",
+  "shown",
+  "propose",
+  "proposed",
+  "paper",
+  "approach",
+  "method",
+  "results",
+  "model",
+  "models",
+  "work",
+  "study",
+  "new",
+  "novel",
+  "present",
+  "presented",
+  "demonstrate",
+  "demonstrated",
+  "provide",
+  "provided",
+  "however",
+  "therefore",
+  "thus",
+  "hence",
+  "although",
+  "moreover",
+  "furthermore",
+  "additionally",
+  "specifically",
+  "respectively"
+]);
+
+// src/nlp/tokenizer.ts
+function tokenize(text) {
+  if (!text) return [];
+  return text.toLowerCase().replace(/[^a-z0-9\s-]/g, " ").split(/\s+/).map((token) => token.replace(/^-+|-+$/g, "")).filter(
+    (token) => token.length > 1 && !STOPWORDS.has(token) && !/^\d+$/.test(token)
+    // Remove pure numbers
+  );
+}
+
+// src/nlp/tfidf.ts
+var logger5 = getLogger();
+function buildCorpus(papers) {
+  const df = /* @__PURE__ */ new Map();
+  const documents = /* @__PURE__ */ new Map();
+  let nullAbstractCount = 0;
+  for (const paper of papers) {
+    const id = paper.source_id || String(paper.paper_id);
+    let text = paper.title;
+    if (paper.abstract) {
+      text += " " + paper.abstract;
+    } else {
+      nullAbstractCount++;
+      if (paper.keywords_json) {
+        try {
+          const keywords = JSON.parse(paper.keywords_json);
+          text += " " + keywords.join(" ");
+        } catch {
+        }
+      }
+    }
+    const tokens = tokenize(text);
+    if (tokens.length === 0) continue;
+    const tf = /* @__PURE__ */ new Map();
+    for (const token of tokens) {
+      tf.set(token, (tf.get(token) ?? 0) + 1);
+    }
+    const maxTf = Math.max(...tf.values());
+    const normalizedTf = /* @__PURE__ */ new Map();
+    for (const [term, count] of tf) {
+      normalizedTf.set(term, count / maxTf);
+    }
+    documents.set(id, normalizedTf);
+    const seenTerms = new Set(tokens);
+    for (const term of seenTerms) {
+      df.set(term, (df.get(term) ?? 0) + 1);
+    }
+  }
+  if (papers.length > 0) {
+    const pct = (nullAbstractCount / papers.length * 100).toFixed(1);
+    if (nullAbstractCount > 0) {
+      logger5.warn(
+        { nullAbstracts: nullAbstractCount, total: papers.length, percentage: pct },
+        `${pct}% of papers have null abstracts (using title-only fallback)`
+      );
+    }
+  }
+  const N = documents.size;
+  for (const [, docTf] of documents) {
+    for (const [term, tf] of docTf) {
+      const termDf = df.get(term) ?? 1;
+      const idf = Math.log(N / termDf);
+      docTf.set(term, tf * idf);
+    }
+  }
+  return { documents, df, size: N };
+}
+function getTopTerms(corpus, docIds, topN = 5) {
+  const termScores = /* @__PURE__ */ new Map();
+  for (const docId of docIds) {
+    const vector = corpus.documents.get(docId);
+    if (!vector) continue;
+    for (const [term, weight] of vector) {
+      termScores.set(term, (termScores.get(term) ?? 0) + weight);
+    }
+  }
+  return Array.from(termScores.entries()).sort((a, b) => b[1] - a[1]).slice(0, topN).map(([term]) => term);
+}
+function computeRelevance(corpus, docId, queryTokens) {
+  const docVector = corpus.documents.get(docId);
+  if (!docVector || queryTokens.length === 0) return 0;
+  let score = 0;
+  for (const token of queryTokens) {
+    score += docVector.get(token) ?? 0;
+  }
+  return Math.min(1, score / queryTokens.length);
+}
+
+// src/nlp/similarity.ts
+function cosineSimilarity(vecA, vecB) {
+  if (vecA.size === 0 || vecB.size === 0) return 0;
+  let dotProduct = 0;
+  let normA = 0;
+  let normB = 0;
+  const [smaller, larger] = vecA.size <= vecB.size ? [vecA, vecB] : [vecB, vecA];
+  for (const [term, weightA] of smaller) {
+    const weightB = larger.get(term);
+    if (weightB !== void 0) {
+      dotProduct += weightA * weightB;
+    }
+    normA += weightA * weightA;
+  }
+  for (const [term, weight] of larger) {
+    normB += weight * weight;
+    if (!smaller.has(term)) {
+    }
+  }
+  normA = 0;
+  for (const [, w] of vecA) normA += w * w;
+  normB = 0;
+  for (const [, w] of vecB) normB += w * w;
+  const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+  if (denominator === 0) return 0;
+  return dotProduct / denominator;
+}
+function findTopKSimilar(docId, corpus, k, threshold) {
+  const docVector = corpus.documents.get(docId);
+  if (!docVector) return [];
+  const similarities = [];
+  for (const [otherId, otherVector] of corpus.documents) {
+    if (otherId === docId) continue;
+    const sim = cosineSimilarity(docVector, otherVector);
+    if (sim >= threshold) {
+      similarities.push({ id: otherId, similarity: sim });
+    }
+  }
+  similarities.sort((a, b) => b.similarity - a.similarity);
+  return similarities.slice(0, k);
+}
+function buildSimilarityEdges(paperIdMap, corpus, topK = 10, threshold = 0.25) {
+  const edges = [];
+  const seenPairs = /* @__PURE__ */ new Set();
+  for (const [sourceId, paperId] of paperIdMap) {
+    const neighbors = findTopKSimilar(sourceId, corpus, topK, threshold);
+    for (const neighbor of neighbors) {
+      const neighborPaperId = paperIdMap.get(neighbor.id);
+      if (neighborPaperId === void 0) continue;
+      const pairKey = [Math.min(paperId, neighborPaperId), Math.max(paperId, neighborPaperId)].join("-");
+      if (seenPairs.has(pairKey)) continue;
+      seenPairs.add(pairKey);
+      edges.push({
+        src_paper_id: paperId,
+        dst_paper_id: neighborPaperId,
+        type: "SIMILAR_TEXT" /* SIMILAR_TEXT */,
+        weight: neighbor.similarity,
+        confidence: neighbor.similarity,
+        rationale: null,
+        evidence: null,
+        created_by: "algo",
+        provenance_json: JSON.stringify({
+          source: "tfidf",
+          version: "1.0.0",
+          topK,
+          threshold
+        })
+      });
+    }
+  }
+  return edges;
+}
+
+// src/graph/algorithms.ts
+import GraphDefault from "graphology";
+import pagerankModule from "graphology-metrics/centrality/pagerank.js";
+import louvainModule from "graphology-communities-louvain";
+import { toUndirected } from "graphology-operators";
+var Graph = GraphDefault.default ?? GraphDefault;
+var pagerank = pagerankModule.default ?? pagerankModule;
+var louvain = louvainModule.default ?? louvainModule;
+var logger6 = getLogger();
+function computePageRank(papers, edges) {
+  const graph = new Graph({ type: "directed" });
+  for (const paper of papers) {
+    if (paper.paper_id !== void 0) {
+      graph.addNode(String(paper.paper_id));
+    }
+  }
+  const citesEdges = edges.filter((e) => e.type === "CITES" /* CITES */);
+  for (const edge of citesEdges) {
+    const src = String(edge.src_paper_id);
+    const dst = String(edge.dst_paper_id);
+    if (graph.hasNode(src) && graph.hasNode(dst) && !graph.hasEdge(src, dst)) {
+      graph.addEdge(src, dst, { weight: edge.weight });
+    }
+  }
+  const scores = pagerank(graph, { alpha: 0.85, maxIterations: 100, tolerance: 1e-6 });
+  const result = /* @__PURE__ */ new Map();
+  for (const [nodeId, score] of Object.entries(scores)) {
+    result.set(parseInt(nodeId, 10), score);
+  }
+  logger6.debug({ nodeCount: graph.order, edgeCount: graph.size }, "PageRank computed");
+  return result;
+}
+function computeLouvainClusters(papers, edges) {
+  const directedGraph = new Graph({ type: "directed", allowSelfLoops: false });
+  for (const paper of papers) {
+    if (paper.paper_id !== void 0) {
+      directedGraph.addNode(String(paper.paper_id));
+    }
+  }
+  for (const edge of edges) {
+    const src = String(edge.src_paper_id);
+    const dst = String(edge.dst_paper_id);
+    if (directedGraph.hasNode(src) && directedGraph.hasNode(dst) && !directedGraph.hasEdge(src, dst)) {
+      directedGraph.addEdge(src, dst, { weight: edge.weight });
+    }
+  }
+  const undirectedGraph = toUndirected(directedGraph);
+  if (undirectedGraph.order === 0) {
+    return /* @__PURE__ */ new Map();
+  }
+  const communities = louvain(undirectedGraph, {
+    resolution: 1
+  });
+  const clusterMap = /* @__PURE__ */ new Map();
+  for (const [nodeId, community] of Object.entries(communities)) {
+    const paperId = parseInt(nodeId, 10);
+    const communityNum = community;
+    if (!clusterMap.has(communityNum)) {
+      clusterMap.set(communityNum, []);
+    }
+    clusterMap.get(communityNum).push(paperId);
+  }
+  logger6.debug(
+    { communities: clusterMap.size, papers: papers.length },
+    "Louvain clustering computed"
+  );
+  return clusterMap;
+}
+function computeCoCitation(edges) {
+  const citesEdges = edges.filter((e) => e.type === "CITES" /* CITES */);
+  const citingToRefs = /* @__PURE__ */ new Map();
+  for (const edge of citesEdges) {
+    if (!citingToRefs.has(edge.src_paper_id)) {
+      citingToRefs.set(edge.src_paper_id, /* @__PURE__ */ new Set());
+    }
+    citingToRefs.get(edge.src_paper_id).add(edge.dst_paper_id);
+  }
+  const pairCounts = /* @__PURE__ */ new Map();
+  for (const [, refs] of citingToRefs) {
+    const refArray = Array.from(refs);
+    for (let i = 0; i < refArray.length; i++) {
+      for (let j = i + 1; j < refArray.length; j++) {
+        const a = Math.min(refArray[i], refArray[j]);
+        const b = Math.max(refArray[i], refArray[j]);
+        const key = `${a}-${b}`;
+        pairCounts.set(key, (pairCounts.get(key) ?? 0) + 1);
+      }
+    }
+  }
+  const coCitationEdges = [];
+  const maxCount = Math.max(1, ...pairCounts.values());
+  for (const [key, count] of pairCounts) {
+    const [a, b] = key.split("-").map(Number);
+    coCitationEdges.push({
+      src_paper_id: a,
+      dst_paper_id: b,
+      type: "CO_CITED" /* CO_CITED */,
+      weight: count / maxCount,
+      // Normalize to [0, 1]
+      confidence: 1,
+      rationale: null,
+      evidence: null,
+      created_by: "algo",
+      provenance_json: JSON.stringify({ source: "co-citation", count })
+    });
+  }
+  logger6.debug({ pairs: coCitationEdges.length }, "Co-citation edges computed");
+  return coCitationEdges;
+}
+function computeBibCoupling(edges) {
+  const citesEdges = edges.filter((e) => e.type === "CITES" /* CITES */);
+  const paperRefs = /* @__PURE__ */ new Map();
+  for (const edge of citesEdges) {
+    if (!paperRefs.has(edge.src_paper_id)) {
+      paperRefs.set(edge.src_paper_id, /* @__PURE__ */ new Set());
+    }
+    paperRefs.get(edge.src_paper_id).add(edge.dst_paper_id);
+  }
+  const couplingEdges = [];
+  const papers = Array.from(paperRefs.keys());
+  for (let i = 0; i < papers.length; i++) {
+    const refsA = paperRefs.get(papers[i]);
+    if (refsA.size === 0) continue;
+    for (let j = i + 1; j < papers.length; j++) {
+      const refsB = paperRefs.get(papers[j]);
+      if (refsB.size === 0) continue;
+      let overlap = 0;
+      for (const ref of refsA) {
+        if (refsB.has(ref)) overlap++;
+      }
+      if (overlap === 0) continue;
+      const weight = overlap / Math.min(refsA.size, refsB.size);
+      couplingEdges.push({
+        src_paper_id: papers[i],
+        dst_paper_id: papers[j],
+        type: "BIB_COUPLED" /* BIB_COUPLED */,
+        weight,
+        confidence: 1,
+        rationale: null,
+        evidence: null,
+        created_by: "algo",
+        provenance_json: JSON.stringify({
+          source: "bib-coupling",
+          overlap,
+          refsA: refsA.size,
+          refsB: refsB.size
+        })
+      });
+    }
+  }
+  logger6.debug({ pairs: couplingEdges.length }, "Bibliographic coupling edges computed");
+  return couplingEdges;
+}
+function buildClusterObjects(clusterMap, clusterNames) {
+  const clusters = [];
+  const paperMappings = /* @__PURE__ */ new Map();
+  let idx = 0;
+  for (const [communityId, paperIds] of clusterMap) {
+    const name = clusterNames?.get(communityId) ?? `Cluster ${communityId}`;
+    clusters.push({
+      method: "louvain_citation",
+      name,
+      description: null,
+      stats_json: JSON.stringify({
+        member_count: paperIds.length,
+        community_id: communityId
+      })
+    });
+    paperMappings.set(idx, paperIds);
+    idx++;
+  }
+  return { clusters, paperMappings };
+}
+
+// src/graph/scoring.ts
+var DEFAULT_WEIGHTS = {
+  pagerankWeight: 0.5,
+  relevanceWeight: 0.3,
+  recencyWeight: 0.2
+};
+function computeCompositeScores(papers, pagerankScores, corpus, topic, weights = DEFAULT_WEIGHTS) {
+  const scores = /* @__PURE__ */ new Map();
+  const currentYear = (/* @__PURE__ */ new Date()).getFullYear();
+  const oldestYear = Math.min(
+    ...papers.map((p) => p.year ?? currentYear).filter((y) => y > 1900)
+  );
+  const yearRange = Math.max(1, currentYear - oldestYear);
+  const queryTokens = topic ? tokenize(topic) : [];
+  const maxPagerank = Math.max(1e-3, ...pagerankScores.values());
+  for (const paper of papers) {
+    if (paper.paper_id === void 0) continue;
+    const pr = (pagerankScores.get(paper.paper_id) ?? 0) / maxPagerank;
+    const sourceId = paper.source_id || String(paper.paper_id);
+    const relevance = queryTokens.length > 0 ? computeRelevance(corpus, sourceId, queryTokens) : 0;
+    const paperYear = paper.year ?? currentYear;
+    const recency = yearRange > 0 ? (paperYear - oldestYear) / yearRange : 0.5;
+    const composite = pr * weights.pagerankWeight + relevance * weights.relevanceWeight + recency * weights.recencyWeight;
+    scores.set(paper.paper_id, Math.min(1, composite));
+  }
+  return scores;
+}
+
+// src/builder/graph-builder.ts
+var logger7 = getLogger();
+function getSourceAdapter(config) {
+  switch (config.source) {
+    case "s2":
+      return new SemanticScholarAdapter();
+    case "openalex":
+    default:
+      return new OpenAlexAdapter();
+  }
+}
+async function buildGraph(config) {
+  const db = new PaperGraphDatabase(config.out);
+  const adapter = getSourceAdapter(config);
+  logger7.info(
+    { topic: config.topic, paper: config.paper, source: config.source, spine: config.spine, depth: config.depth, maxPapers: config.maxPapers },
+    "Starting graph build"
+  );
+  const startTime = Date.now();
+  try {
+    const seedPapers = await findSeeds(adapter, config);
+    logger7.info({ seedCount: seedPapers.length }, "Seeds found");
+    if (seedPapers.length === 0) {
+      logger7.warn("No seed papers found \u2014 nothing to build");
+      db.close();
+      return config.out;
+    }
+    const seedIds = db.insertPapers(seedPapers);
+    for (let i = 0; i < seedPapers.length; i++) {
+      seedPapers[i].paper_id = seedIds[i];
+    }
+    const allEdges = [];
+    await traverseCitations(adapter, db, seedPapers, config, allEdges);
+    const allPapers = db.getAllPapers();
+    logger7.info({ paperCount: allPapers.length }, "Papers in database");
+    const corpus = buildCorpus(allPapers);
+    logger7.info({ corpusSize: corpus.size }, "TF-IDF corpus built");
+    const paperIdMap = /* @__PURE__ */ new Map();
+    for (const paper of allPapers) {
+      if (paper.paper_id !== void 0) {
+        paperIdMap.set(paper.source_id, paper.paper_id);
+      }
+    }
+    const spine = config.spine;
+    if (spine === "similarity" || spine === "hybrid") {
+      const simEdges = buildSimilarityEdges(
+        paperIdMap,
+        corpus,
+        config.similarity?.topK ?? 10,
+        config.similarity?.threshold ?? 0.25
+      );
+      db.insertEdges(simEdges);
+      logger7.info({ simEdges: simEdges.length }, "Similarity edges added");
+    }
+    const dbEdges = db.getAllEdges();
+    if (spine === "co-citation" || spine === "hybrid") {
+      const coCiteEdges = computeCoCitation(dbEdges);
+      db.insertEdges(coCiteEdges);
+      logger7.info({ coCiteEdges: coCiteEdges.length }, "Co-citation edges added");
+    }
+    if (spine === "coupling" || spine === "hybrid") {
+      const couplingEdges = computeBibCoupling(dbEdges);
+      db.insertEdges(couplingEdges);
+      logger7.info({ couplingEdges: couplingEdges.length }, "Bib coupling edges added");
+    }
+    const finalEdges = db.getAllEdges();
+    const pagerankScores = computePageRank(allPapers, finalEdges);
+    logger7.info({ nodes: pagerankScores.size }, "PageRank computed");
+    const clusterMap = computeLouvainClusters(allPapers, finalEdges);
+    const clusterNames = /* @__PURE__ */ new Map();
+    for (const [communityId, paperIds] of clusterMap) {
+      const sourceIds = paperIds.map((id) => allPapers.find((p) => p.paper_id === id)?.source_id).filter((id) => !!id);
+      const top = getTopTerms(corpus, sourceIds, 3);
+      clusterNames.set(communityId, top.join(", ") || `Cluster ${communityId}`);
+    }
+    const { clusters, paperMappings } = buildClusterObjects(clusterMap, clusterNames);
+    db.insertClusters(clusters, paperMappings);
+    logger7.info({ clusterCount: clusters.length }, "Clusters stored");
+    const topicQuery = config.topic ?? "";
+    const compositeScores = computeCompositeScores(
+      allPapers,
+      pagerankScores,
+      corpus,
+      topicQuery,
+      {
+        pagerankWeight: config.ranking?.pagerankWeight ?? 0.5,
+        relevanceWeight: config.ranking?.relevanceWeight ?? 0.3,
+        recencyWeight: config.ranking?.recencyWeight ?? 0.2
+      }
+    );
+    for (const [paperId, pr] of pagerankScores) {
+      db.updatePaperScore(paperId, pr);
+    }
+    const stats = db.getStats();
+    db.insertRun({
+      created_at: (/* @__PURE__ */ new Date()).toISOString(),
+      papergraph_version: "1.0.0",
+      config_json: JSON.stringify(config),
+      source: config.source,
+      spine: config.spine,
+      depth: config.depth,
+      stats_json: JSON.stringify(stats)
+    });
+    const elapsed = ((Date.now() - startTime) / 1e3).toFixed(1);
+    logger7.info(
+      { papers: stats.papers, edges: stats.edges, clusters: stats.clusters, elapsed: `${elapsed}s` },
+      "Graph build complete"
+    );
+    db.close();
+    return config.out;
+  } catch (error) {
+    db.close();
+    throw error;
+  }
+}
+async function findSeeds(adapter, config) {
+  const papers = [];
+  const seen = /* @__PURE__ */ new Set();
+  const addUnique = (paper) => {
+    const key = `${paper.source}:${paper.source_id}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      papers.push(paper);
+    }
+  };
+  const seedLimit = Math.max(10, Math.min(Math.floor(config.maxPapers * 0.4), 200));
+  if (config.topic) {
+    const results = await adapter.searchByTopic(config.topic, seedLimit);
+    results.forEach(addUnique);
+  }
+  if (config.paper?.length) {
+    for (const title of config.paper) {
+      const results = await adapter.searchByTitle(title, 5);
+      if (results.length > 0) {
+        addUnique(results[0]);
+      }
+    }
+  }
+  if (config.doi?.length) {
+    for (const doi of config.doi) {
+      const paper = await adapter.fetchPaper(doi);
+      if (paper) addUnique(paper);
+    }
+  }
+  return papers.slice(0, seedLimit);
+}
+async function traverseCitations(adapter, db, seedPapers, config, allEdges) {
+  const depth = config.depth;
+  const maxPapers = config.maxPapers;
+  const refsPerPaper = config.maxRefsPerPaper;
+  let frontier = [...seedPapers];
+  const visited = /* @__PURE__ */ new Set();
+  const edgeSeen = /* @__PURE__ */ new Set();
+  for (const paper of seedPapers) {
+    visited.add(`${paper.source}:${paper.source_id}`);
+  }
+  for (let d = 0; d < depth; d++) {
+    const nextFrontier = [];
+    const atCapacity = db.getPaperCount() >= maxPapers;
+    logger7.info(
+      { depth: d, frontier: frontier.length, atCapacity, totalPapers: db.getPaperCount() },
+      "Starting depth traversal"
+    );
+    for (const paper of frontier) {
+      if (paper.paper_id === void 0) continue;
+      try {
+        const refs = await adapter.fetchReferences(paper.source_id, refsPerPaper);
+        for (const ref of refs) {
+          const key = `${ref.source}:${ref.source_id}`;
+          const existingPaper = db.getPaperBySourceId(ref.source, ref.source_id);
+          if (existingPaper && existingPaper.paper_id !== void 0) {
+            const edgeKey = `${paper.paper_id}->${existingPaper.paper_id}`;
+            if (!edgeSeen.has(edgeKey)) {
+              edgeSeen.add(edgeKey);
+              const edge = {
+                src_paper_id: paper.paper_id,
+                dst_paper_id: existingPaper.paper_id,
+                type: "CITES" /* CITES */,
+                weight: 1,
+                confidence: 1,
+                rationale: null,
+                evidence: null,
+                created_by: "algo",
+                provenance_json: JSON.stringify({ source: paper.source, depth: d })
+              };
+              db.insertEdges([edge]);
+              allEdges.push(edge);
+            }
+          } else if (!visited.has(key) && !atCapacity && db.getPaperCount() < maxPapers) {
+            visited.add(key);
+            const [refId] = db.insertPapers([ref]);
+            if (refId !== void 0) {
+              const edgeKey = `${paper.paper_id}->${refId}`;
+              if (!edgeSeen.has(edgeKey)) {
+                edgeSeen.add(edgeKey);
+                const edge = {
+                  src_paper_id: paper.paper_id,
+                  dst_paper_id: refId,
+                  type: "CITES" /* CITES */,
+                  weight: 1,
+                  confidence: 1,
+                  rationale: null,
+                  evidence: null,
+                  created_by: "algo",
+                  provenance_json: JSON.stringify({ source: paper.source, depth: d })
+                };
+                db.insertEdges([edge]);
+                allEdges.push(edge);
+              }
+              nextFrontier.push({ ...ref, paper_id: refId });
+            }
+          }
+        }
+      } catch (error) {
+        logger7.warn({ paperId: paper.source_id, error }, "Failed to traverse paper");
+      }
+    }
+    logger7.info(
+      { depth: d + 1, frontier: nextFrontier.length, totalPapers: db.getPaperCount(), edgesCreated: allEdges.length },
+      "Citation depth traversed"
+    );
+    if (nextFrontier.length === 0) break;
+    frontier = nextFrontier;
+  }
+}
+
+// src/exporters/export.ts
+import { writeFileSync } from "fs";
+var logger8 = getLogger();
+function exportGraph(dbPath, outputPath, format) {
+  const db = new PaperGraphDatabase(dbPath);
+  try {
+    const data = {
+      papers: db.getAllPapers(),
+      edges: db.getAllEdges(),
+      clusters: db.getAllClusters(),
+      entities: db.getAllEntities()
+    };
+    let content;
+    switch (format) {
+      case "json":
+        content = exportJson(data);
+        break;
+      case "graphml":
+        content = exportGraphML(data);
+        break;
+      case "gexf":
+        content = exportGEXF(data);
+        break;
+      case "csv":
+        content = exportCSV(data);
+        break;
+      case "mermaid":
+        content = exportMermaid(data);
+        break;
+      default:
+        throw new Error(`Unsupported export format: ${format}`);
+    }
+    writeFileSync(outputPath, content, "utf-8");
+    logger8.info({ format, outputPath, papers: data.papers.length, edges: data.edges.length }, "Graph exported");
+  } finally {
+    db.close();
+  }
+}
+function exportJson(data) {
+  return JSON.stringify({
+    papergraph: {
+      version: "1.0.0",
+      exported_at: (/* @__PURE__ */ new Date()).toISOString()
+    },
+    papers: data.papers.map((p) => ({
+      id: p.paper_id,
+      source: p.source,
+      source_id: p.source_id,
+      doi: p.doi,
+      title: p.title,
+      abstract: p.abstract?.slice(0, 500),
+      year: p.year,
+      venue: p.venue,
+      url: p.url,
+      citation_count: p.citation_count,
+      influence_score: p.influence_score
+    })),
+    edges: data.edges.map((e) => ({
+      source: e.src_paper_id,
+      target: e.dst_paper_id,
+      type: e.type,
+      weight: e.weight,
+      confidence: e.confidence
+    })),
+    clusters: data.clusters.map((c) => ({
+      id: c.cluster_id,
+      name: c.name,
+      method: c.method
+    })),
+    entities: data.entities.map((e) => ({
+      id: e.entity_id,
+      type: e.type,
+      name: e.name
+    }))
+  }, null, 2);
+}
+function exportGraphML(data) {
+  const esc = (s) => (s ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+  let xml = `<?xml version="1.0" encoding="UTF-8"?>
+<graphml xmlns="http://graphml.graphstudio.org/xmlns/graphml"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+  <key id="title" for="node" attr.name="title" attr.type="string"/>
+  <key id="year" for="node" attr.name="year" attr.type="int"/>
+  <key id="venue" for="node" attr.name="venue" attr.type="string"/>
+  <key id="citation_count" for="node" attr.name="citation_count" attr.type="int"/>
+  <key id="doi" for="node" attr.name="doi" attr.type="string"/>
+  <key id="influence" for="node" attr.name="influence" attr.type="double"/>
+  <key id="type" for="edge" attr.name="type" attr.type="string"/>
+  <key id="weight" for="edge" attr.name="weight" attr.type="double"/>
+  <graph id="papergraph" edgedefault="directed">
+`;
+  for (const paper of data.papers) {
+    xml += `    <node id="n${paper.paper_id}">
+      <data key="title">${esc(paper.title)}</data>
+      <data key="year">${paper.year ?? ""}</data>
+      <data key="venue">${esc(paper.venue)}</data>
+      <data key="citation_count">${paper.citation_count}</data>
+      <data key="doi">${esc(paper.doi)}</data>
+      <data key="influence">${paper.influence_score ?? 0}</data>
+    </node>
+`;
+  }
+  for (const edge of data.edges) {
+    xml += `    <edge source="n${edge.src_paper_id}" target="n${edge.dst_paper_id}">
+      <data key="type">${edge.type}</data>
+      <data key="weight">${edge.weight}</data>
+    </edge>
+`;
+  }
+  xml += `  </graph>
+</graphml>`;
+  return xml;
+}
+function exportGEXF(data) {
+  const esc = (s) => (s ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+  let xml = `<?xml version="1.0" encoding="UTF-8"?>
+<gexf xmlns="http://www.gexf.net/1.3"
+      version="1.3">
+  <meta>
+    <creator>PaperGraph</creator>
+    <description>Research paper connectivity graph</description>
+  </meta>
+  <graph defaultedgetype="directed">
+    <attributes class="node">
+      <attribute id="0" title="title" type="string"/>
+      <attribute id="1" title="year" type="integer"/>
+      <attribute id="2" title="venue" type="string"/>
+      <attribute id="3" title="citations" type="integer"/>
+      <attribute id="4" title="influence" type="float"/>
+    </attributes>
+    <attributes class="edge">
+      <attribute id="0" title="type" type="string"/>
+    </attributes>
+    <nodes>
+`;
+  for (const paper of data.papers) {
+    xml += `      <node id="${paper.paper_id}" label="${esc(paper.title?.slice(0, 60))}">
+        <attvalues>
+          <attvalue for="0" value="${esc(paper.title)}"/>
+          <attvalue for="1" value="${paper.year ?? 0}"/>
+          <attvalue for="2" value="${esc(paper.venue)}"/>
+          <attvalue for="3" value="${paper.citation_count}"/>
+          <attvalue for="4" value="${paper.influence_score ?? 0}"/>
+        </attvalues>
+      </node>
+`;
+  }
+  xml += `    </nodes>
+    <edges>
+`;
+  let edgeIdx = 0;
+  for (const edge of data.edges) {
+    xml += `      <edge id="${edgeIdx++}" source="${edge.src_paper_id}" target="${edge.dst_paper_id}" weight="${edge.weight}">
+        <attvalues>
+          <attvalue for="0" value="${edge.type}"/>
+        </attvalues>
+      </edge>
+`;
+  }
+  xml += `    </edges>
+  </graph>
+</gexf>`;
+  return xml;
+}
+function exportCSV(data) {
+  let csv = "paper_id,source,source_id,doi,title,year,venue,citation_count,influence_score\n";
+  for (const paper of data.papers) {
+    csv += [
+      paper.paper_id,
+      paper.source,
+      paper.source_id,
+      `"${(paper.doi ?? "").replace(/"/g, '""')}"`,
+      `"${(paper.title ?? "").replace(/"/g, '""')}"`,
+      paper.year ?? "",
+      `"${(paper.venue ?? "").replace(/"/g, '""')}"`,
+      paper.citation_count,
+      paper.influence_score ?? ""
+    ].join(",") + "\n";
+  }
+  csv += "\n# EDGES\nsrc_paper_id,dst_paper_id,type,weight,confidence\n";
+  for (const edge of data.edges) {
+    csv += `${edge.src_paper_id},${edge.dst_paper_id},${edge.type},${edge.weight},${edge.confidence}
+`;
+  }
+  return csv;
+}
+function exportMermaid(data) {
+  let diagram = "graph TD\n";
+  for (const paper of data.papers) {
+    const label = (paper.title ?? "Untitled").slice(0, 40).replace(/"/g, "'");
+    diagram += `  P${paper.paper_id}["${label}"]
+`;
+  }
+  diagram += "\n";
+  const maxEdges = 100;
+  const edgesToRender = data.edges.slice(0, maxEdges);
+  for (const edge of edgesToRender) {
+    const style = edge.type === "CITES" ? "-->" : "-.->";
+    diagram += `  P${edge.src_paper_id} ${style} P${edge.dst_paper_id}
+`;
+  }
+  if (data.edges.length > maxEdges) {
+    diagram += `
+  %% Note: ${data.edges.length - maxEdges} additional edges omitted
+`;
+  }
+  return diagram;
+}
+
+// src/viewer/html-viewer.ts
+import { writeFileSync as writeFileSync2 } from "fs";
+var logger9 = getLogger();
+function generateViewer(dbPath, outputPath) {
+  const db = new PaperGraphDatabase(dbPath);
+  try {
+    const papers = db.getAllPapers();
+    const edges = db.getAllEdges();
+    const clusters = db.getAllClusters();
+    const rawDb = db.getRawDb();
+    const pcRows = rawDb.prepare("SELECT paper_id, cluster_id FROM paper_clusters").all();
+    const paperCluster = /* @__PURE__ */ new Map();
+    for (const row of pcRows) {
+      paperCluster.set(row.paper_id, row.cluster_id);
+    }
+    const graphData = buildCytoscapeData(papers, edges, clusters, paperCluster);
+    const html = buildHtml(graphData, papers.length, edges.length);
+    writeFileSync2(outputPath, html, "utf-8");
+    logger9.info({ outputPath, papers: papers.length, edges: edges.length }, "HTML viewer generated");
+  } finally {
+    db.close();
+  }
+}
+function buildCytoscapeData(papers, edges, clusters, paperCluster) {
+  const colors = [
+    "#6366f1",
+    "#f43f5e",
+    "#10b981",
+    "#f59e0b",
+    "#3b82f6",
+    "#8b5cf6",
+    "#ec4899",
+    "#14b8a6",
+    "#ef4444",
+    "#06b6d4",
+    "#84cc16",
+    "#a855f7",
+    "#f97316",
+    "#22d3ee",
+    "#e879f9"
+  ];
+  const clusterColor = /* @__PURE__ */ new Map();
+  let colorIdx = 0;
+  for (const c of clusters) {
+    if (c.cluster_id !== void 0) {
+      clusterColor.set(c.cluster_id, colors[colorIdx % colors.length]);
+      colorIdx++;
+    }
+  }
+  const nodes = papers.map((p) => {
+    const clusterId = paperCluster.get(p.paper_id);
+    const color = clusterId !== void 0 ? clusterColor.get(clusterId) ?? "#6366f1" : "#6366f1";
+    const size = Math.max(20, Math.min(60, 20 + (p.influence_score ?? 0) * 1e3));
+    return {
+      data: {
+        id: `p${p.paper_id}`,
+        label: (p.title ?? "Untitled").slice(0, 50),
+        title: p.title,
+        year: p.year,
+        venue: p.venue,
+        doi: p.doi,
+        url: p.url,
+        citations: p.citation_count,
+        influence: p.influence_score,
+        cluster: clusterId,
+        color,
+        size
+      }
+    };
+  });
+  const edgeTypeColors = {
+    CITES: "#64748b",
+    SIMILAR_TEXT: "#6366f1",
+    CO_CITED: "#10b981",
+    BIB_COUPLED: "#f59e0b",
+    EXTENDS: "#3b82f6",
+    CONTRADICTS: "#ef4444",
+    REVIEWS: "#8b5cf6",
+    REPLICATES: "#ec4899",
+    USES_DATA: "#14b8a6",
+    SHARES_METHOD: "#f97316",
+    SAME_VENUE: "#84cc16",
+    SAME_AUTHOR: "#a855f7",
+    LLM_SEMANTIC: "#22d3ee",
+    LLM_METHODOLOGICAL: "#e879f9",
+    LLM_BUILDS_ON: "#06b6d4",
+    LLM_DISAGREES_WITH: "#f43f5e"
+  };
+  const cyEdges = edges.map((e, i) => ({
+    data: {
+      id: `e${i}`,
+      source: `p${e.src_paper_id}`,
+      target: `p${e.dst_paper_id}`,
+      type: e.type,
+      weight: e.weight,
+      color: edgeTypeColors[e.type] ?? "#64748b"
+    }
+  }));
+  return JSON.stringify([...nodes, ...cyEdges]);
+}
+function buildHtml(graphData, paperCount, edgeCount) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>PaperGraph Viewer</title>
+<script src="https://unpkg.com/cytoscape@3.30.4/dist/cytoscape.min.js"></script>
+<script src="https://unpkg.com/elkjs@0.9.3/lib/elk.bundled.js"></script>
+<script src="https://unpkg.com/cytoscape-elk@2.2.0/dist/cytoscape-elk.js"></script>
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body {
+    font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
+    background: #0f172a;
+    color: #e2e8f0;
+    height: 100vh;
+    overflow: hidden;
+  }
+  #cy {
+    width: 100%;
+    height: 100vh;
+    position: absolute;
+    top: 0;
+    left: 0;
+  }
+  .panel {
+    position: absolute;
+    background: rgba(15, 23, 42, 0.85);
+    backdrop-filter: blur(16px);
+    border: 1px solid rgba(100, 116, 139, 0.3);
+    border-radius: 12px;
+    padding: 16px;
+    z-index: 10;
+  }
+  .header {
+    top: 16px;
+    left: 16px;
+    display: flex;
+    align-items: center;
+    gap: 12px;
+  }
+  .header h1 {
+    font-size: 18px;
+    font-weight: 700;
+    background: linear-gradient(135deg, #6366f1, #a855f7);
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+  }
+  .stats {
+    font-size: 12px;
+    color: #94a3b8;
+  }
+  .search-panel {
+    top: 16px;
+    right: 16px;
+    width: 300px;
+  }
+  .search-panel input {
+    width: 100%;
+    padding: 8px 12px;
+    background: rgba(30, 41, 59, 0.8);
+    border: 1px solid rgba(100, 116, 139, 0.3);
+    border-radius: 8px;
+    color: #e2e8f0;
+    font-size: 14px;
+    outline: none;
+  }
+  .search-panel input:focus {
+    border-color: #6366f1;
+    box-shadow: 0 0 0 3px rgba(99, 102, 241, 0.15);
+  }
+  .detail-panel {
+    bottom: 16px;
+    right: 16px;
+    width: 360px;
+    max-height: 50vh;
+    overflow-y: auto;
+    display: none;
+  }
+  .detail-panel.active { display: block; }
+  .detail-panel h3 {
+    font-size: 15px;
+    font-weight: 600;
+    margin-bottom: 8px;
+    line-height: 1.3;
+  }
+  .detail-field {
+    display: flex;
+    justify-content: space-between;
+    font-size: 12px;
+    padding: 4px 0;
+    border-bottom: 1px solid rgba(100, 116, 139, 0.15);
+  }
+  .detail-field .label { color: #94a3b8; }
+  .detail-field .value { color: #e2e8f0; font-weight: 500; }
+  .detail-field a { color: #6366f1; text-decoration: none; }
+  .detail-field a:hover { text-decoration: underline; }
+  .legend {
+    bottom: 16px;
+    left: 16px;
+    font-size: 11px;
+  }
+  .legend-item {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    margin: 3px 0;
+  }
+  .legend-dot {
+    width: 8px;
+    height: 8px;
+    border-radius: 50%;
+    flex-shrink: 0;
+  }
+  .controls {
+    top: 80px;
+    right: 16px;
+    display: flex;
+    gap: 6px;
+  }
+  .btn {
+    padding: 6px 12px;
+    background: rgba(30, 41, 59, 0.8);
+    border: 1px solid rgba(100, 116, 139, 0.3);
+    border-radius: 6px;
+    color: #e2e8f0;
+    font-size: 12px;
+    cursor: pointer;
+    transition: all 0.15s;
+  }
+  .btn:hover {
+    background: rgba(99, 102, 241, 0.2);
+    border-color: #6366f1;
+  }
+</style>
+</head>
+<body>
+  <div id="cy"></div>
+
+  <div class="panel header">
+    <h1>PaperGraph</h1>
+    <span class="stats">${paperCount} papers \xB7 ${edgeCount} edges</span>
+  </div>
+
+  <div class="panel search-panel">
+    <input type="text" id="search" placeholder="Search papers..." autocomplete="off" />
+  </div>
+
+  <div class="panel controls">
+    <button class="btn" id="fitBtn">Fit</button>
+    <button class="btn" id="layoutBtn">Re-layout</button>
+    <button class="btn" id="resetBtn">Reset</button>
+  </div>
+
+  <div class="panel detail-panel" id="detail">
+    <h3 id="detail-title"></h3>
+    <div id="detail-fields"></div>
+  </div>
+
+  <div class="panel legend">
+    <div class="legend-item"><div class="legend-dot" style="background:#64748b"></div> Cites</div>
+    <div class="legend-item"><div class="legend-dot" style="background:#6366f1"></div> Similar</div>
+    <div class="legend-item"><div class="legend-dot" style="background:#10b981"></div> Co-cited</div>
+    <div class="legend-item"><div class="legend-dot" style="background:#f59e0b"></div> Coupled</div>
+  </div>
+
+<script>
+const graphData = ${graphData};
+
+const cy = cytoscape({
+  container: document.getElementById('cy'),
+  elements: graphData,
+  style: [
+    {
+      selector: 'node',
+      style: {
+        'label': 'data(label)',
+        'background-color': 'data(color)',
+        'width': 'data(size)',
+        'height': 'data(size)',
+        'font-size': '8px',
+        'color': '#e2e8f0',
+        'text-outline-color': '#0f172a',
+        'text-outline-width': 2,
+        'text-valign': 'bottom',
+        'text-margin-y': 5,
+        'text-max-width': '100px',
+        'text-wrap': 'ellipsis',
+        'border-width': 2,
+        'border-color': 'data(color)',
+        'border-opacity': 0.6,
+      },
+    },
+    {
+      selector: 'edge',
+      style: {
+        'width': function(e) { return Math.max(1, e.data('weight') * 3); },
+        'line-color': 'data(color)',
+        'target-arrow-color': 'data(color)',
+        'target-arrow-shape': 'triangle',
+        'curve-style': 'bezier',
+        'opacity': 0.5,
+        'arrow-scale': 0.8,
+      },
+    },
+    {
+      selector: 'node:selected',
+      style: {
+        'border-width': 4,
+        'border-color': '#f59e0b',
+        'border-opacity': 1,
+      },
+    },
+    {
+      selector: '.highlighted',
+      style: {
+        'opacity': 1,
+        'border-width': 3,
+        'border-color': '#f59e0b',
+      },
+    },
+    {
+      selector: '.faded',
+      style: { 'opacity': 0.15 },
+    },
+  ],
+  layout: {
+    name: 'cose',
+    animate: false,
+    nodeRepulsion: 8000,
+    idealEdgeLength: 120,
+    nodeOverlap: 20,
+  },
+  wheelSensitivity: 0.3,
+});
+
+// Detail panel
+cy.on('tap', 'node', function(evt) {
+  const d = evt.target.data();
+  const panel = document.getElementById('detail');
+  panel.classList.add('active');
+  document.getElementById('detail-title').textContent = d.title;
+
+  const fields = [
+    ['Year', d.year],
+    ['Venue', d.venue],
+    ['Citations', d.citations],
+    ['Influence', d.influence?.toFixed(6)],
+    ['DOI', d.doi ? '<a href="https://doi.org/' + d.doi + '" target="_blank">' + d.doi + '</a>' : '\u2014'],
+    ['URL', d.url ? '<a href="' + d.url + '" target="_blank">Open</a>' : '\u2014'],
+  ];
+
+  document.getElementById('detail-fields').innerHTML = fields
+    .map(([l, v]) => '<div class="detail-field"><span class="label">' + l + '</span><span class="value">' + (v ?? '\u2014') + '</span></div>')
+    .join('');
+});
+
+cy.on('tap', function(evt) {
+  if (evt.target === cy) {
+    document.getElementById('detail').classList.remove('active');
+    cy.elements().removeClass('highlighted faded');
+  }
+});
+
+// Highlight neighbors on node click
+cy.on('select', 'node', function(evt) {
+  const node = evt.target;
+  const neighborhood = node.closedNeighborhood();
+  cy.elements().addClass('faded');
+  neighborhood.removeClass('faded').addClass('highlighted');
+});
+
+cy.on('unselect', 'node', function() {
+  cy.elements().removeClass('highlighted faded');
+});
+
+// Search
+document.getElementById('search').addEventListener('input', function(e) {
+  const q = e.target.value.toLowerCase().trim();
+  if (!q) {
+    cy.elements().removeClass('highlighted faded');
+    return;
+  }
+  cy.elements().addClass('faded');
+  cy.nodes().filter(n => {
+    const d = n.data();
+    return (d.title || '').toLowerCase().includes(q) ||
+           (d.venue || '').toLowerCase().includes(q) ||
+           (d.doi || '').toLowerCase().includes(q);
+  }).removeClass('faded').addClass('highlighted');
+});
+
+// Buttons
+document.getElementById('fitBtn').addEventListener('click', () => cy.fit(50));
+document.getElementById('layoutBtn').addEventListener('click', () => {
+  cy.layout({ name: 'cose', animate: true, animationDuration: 500, nodeRepulsion: 8000 }).run();
+});
+document.getElementById('resetBtn').addEventListener('click', () => {
+  cy.elements().removeClass('highlighted faded');
+  document.getElementById('search').value = '';
+  document.getElementById('detail').classList.remove('active');
+  cy.fit(50);
+});
+</script>
+</body>
+</html>`;
+}
+
+// src/cli/index.ts
+var VERSION = "1.0.0";
+var program = new Command();
+program.name("papergraph").description("Build research-paper connectivity graphs from topics, keywords, or paper titles.").version(VERSION);
+program.command("build").description("Build a graph database from papers").requiredOption("-t, --topic <topic>", "Search topic").option("-p, --paper <titles...>", "Paper titles to seed").option("--doi <dois...>", "DOIs to seed").option("-s, --source <source>", "Data source: openalex | s2", "openalex").option("--spine <spine>", "Graph spine: citation | similarity | co-citation | coupling | hybrid", "citation").option("-d, --depth <n>", "Citation traversal depth", "2").option("-m, --max-papers <n>", "Maximum papers to collect", "200").option("-o, --out <path>", "Output database path", "./papergraph.db").option("--max-refs <n>", "Max references per paper", "20").option("--max-cites <n>", "Max citations per paper", "20").option("--year-from <year>", "Filter papers from year").option("--year-to <year>", "Filter papers to year").option("--log-level <level>", "Log level: debug | info | warn | error", "info").option("--json-logs", "Output JSON logs", false).option("--no-cache", "Disable response caching").action(async (opts) => {
+  const cliConfig = {
+    topic: opts.topic,
+    paper: opts.paper,
+    doi: opts.doi,
+    source: opts.source,
+    spine: opts.spine,
+    depth: parseInt(opts.depth, 10),
+    maxPapers: parseInt(opts.maxPapers, 10),
+    maxRefsPerPaper: parseInt(opts.maxRefs, 10),
+    maxCitesPerPaper: parseInt(opts.maxCites, 10),
+    out: opts.out,
+    yearFrom: opts.yearFrom ? parseInt(opts.yearFrom, 10) : void 0,
+    yearTo: opts.yearTo ? parseInt(opts.yearTo, 10) : void 0,
+    logLevel: opts.logLevel,
+    jsonLogs: opts.jsonLogs,
+    noCache: !opts.cache
+  };
+  const config = await resolveConfig(cliConfig);
+  initLogger({ level: config.logLevel, jsonLogs: config.jsonLogs });
+  getHttpClient({ timeout: 3e4 });
+  const logger10 = getLogger();
+  logger10.info({ topic: config.topic, source: config.source, spine: config.spine }, "Starting build");
+  try {
+    const dbPath = await buildGraph(config);
+    logger10.info({ dbPath }, "Build complete!");
+  } catch (error) {
+    logger10.error({ error }, "Build failed");
+    process.exit(1);
+  }
+});
+program.command("export").description("Export graph to JSON, GraphML, GEXF, CSV, or Mermaid").requiredOption("-i, --input <dbPath>", "Input database path").requiredOption("-f, --format <format>", "Export format: json | graphml | gexf | csv | mermaid").option("-o, --out <path>", "Output file path").action((opts) => {
+  const format = opts.format.toLowerCase();
+  const validFormats = ["json", "graphml", "gexf", "csv", "mermaid"];
+  if (!validFormats.includes(format)) {
+    console.error(`Invalid format: ${format}. Valid: ${validFormats.join(", ")}`);
+    process.exit(1);
+  }
+  const extensions = {
+    json: ".json",
+    graphml: ".graphml",
+    gexf: ".gexf",
+    csv: ".csv",
+    mermaid: ".md"
+  };
+  const outputPath = opts.out ?? opts.input.replace(".db", extensions[format] ?? ".out");
+  try {
+    exportGraph(opts.input, outputPath, format);
+    console.log(`Exported to ${outputPath}`);
+  } catch (error) {
+    console.error("Export failed:", error);
+    process.exit(1);
+  }
+});
+program.command("view").description("Generate a self-contained HTML viewer").requiredOption("-i, --input <dbPath>", "Input database path").option("-o, --out <path>", "Output HTML file path").action((opts) => {
+  const outputPath = opts.out ?? opts.input.replace(".db", ".html");
+  try {
+    generateViewer(opts.input, outputPath);
+    console.log(`Viewer generated: ${outputPath}`);
+  } catch (error) {
+    console.error("View generation failed:", error);
+    process.exit(1);
+  }
+});
+program.command("inspect").description("Show database statistics").requiredOption("-i, --input <dbPath>", "Input database path").action((opts) => {
+  try {
+    const db = new PaperGraphDatabase(opts.input);
+    const stats = db.getStats();
+    db.close();
+    console.log("\n\u{1F4CA} PaperGraph Database Statistics\n");
+    console.log(`  Papers:   ${stats.papers}`);
+    console.log(`  Edges:    ${stats.edges}`);
+    console.log(`  Clusters: ${stats.clusters}`);
+    console.log(`  Entities: ${stats.entities}`);
+    console.log(`  Runs:     ${stats.runs}`);
+    if (Object.keys(stats.edgesByType).length > 0) {
+      console.log("\n  Edge Types:");
+      for (const [type, count] of Object.entries(stats.edgesByType)) {
+        console.log(`    ${type}: ${count}`);
+      }
+    }
+    console.log("");
+  } catch (error) {
+    console.error("Inspect failed:", error);
+    process.exit(1);
+  }
+});
+program.command("cache").description("Manage the response cache").argument("<action>", "Action: clear | stats").action((action) => {
+  switch (action) {
+    case "clear":
+      try {
+        const { rmSync } = __require("fs");
+        rmSync(".papergraph-cache", { recursive: true, force: true });
+        console.log("Cache cleared.");
+      } catch {
+        console.log("No cache to clear.");
+      }
+      break;
+    case "stats":
+      try {
+        const { readdirSync, statSync } = __require("fs");
+        const { join } = __require("path");
+        const files = readdirSync(".papergraph-cache");
+        let totalSize = 0;
+        for (const f of files) {
+          totalSize += statSync(join(".papergraph-cache", f)).size;
+        }
+        console.log(`Cache: ${files.length} entries, ${(totalSize / 1024).toFixed(1)} KB`);
+      } catch {
+        console.log("No cache found.");
+      }
+      break;
+    default:
+      console.error(`Unknown action: ${action}. Valid: clear, stats`);
+      process.exit(1);
+  }
+});
+program.parse();