feat: citation network analysis and multi-paper comparative table #35

Overview

Two complementary analytical features to turn the local cache into an active research intelligence tool, rather than a passive bibliography store.

Feature 1 — Citation Network & Co-citation Clustering

Motivation

Every mosaic similar run already fetches related_works edges from OpenAlex and Semantic Scholar recommendations, but those edges are discarded after display. Persisting them would let MOSAIC build an incrementally richer citation graph over time — enabling topology-based discovery (key papers, bridging papers, isolated clusters) that keyword search cannot provide.

Proposed behaviour

New cache table: citations

CREATE TABLE citations (
    source_uid  TEXT NOT NULL,   -- citing paper
    target_uid  TEXT NOT NULL,   -- cited / related paper
    relation    TEXT NOT NULL,   -- 'cites' | 'related' | 'co_citation'
    weight      REAL DEFAULT 1.0,
    PRIMARY KEY (source_uid, target_uid, relation)
);

Edges are populated automatically whenever mosaic similar or mosaic search (with --prefer-cache enrichment) runs — no extra step needed.

New CLI command: mosaic network

mosaic network [OPTIONS]

Example outputs

# Show the most-connected papers in the local cache
mosaic network --cluster --top 5

# Export a Mermaid diagram of papers related to a topic
mosaic network --query "transformer attention" --depth 2 --output graph.md

# JSON for downstream tools (D3.js, Gephi, NetworkX)
mosaic network --query "protein folding" --output network.json

Terminal output (cluster report)

Cluster 1 — Transformer Architectures (14 papers)
  Hub  Attention Is All You Need          Vaswani et al.  2017  degree=11
  Hub  BERT: Pre-training of Deep…        Devlin et al.   2019  degree=9
       Efficient Transformers: A Survey   Tay et al.      2020  degree=6
       …

Cluster 2 — Diffusion Models (8 papers)
  Hub  Denoising Diffusion Probabilistic… Ho et al.       2020  degree=7
       …

Implementation sketch

• Clustering: co-citation strength (papers cited together frequently score higher) → connected-components or Louvain community detection via networkx (already a lightweight optional dep candidate)
• networkx added as optional dep under a new [analysis] extra
• Mermaid and DOT outputs need no extra deps; JSON uses stdlib

Feature 2 — Multi-paper Comparative Table

Motivation

After collecting a set of papers on a topic, researchers often need to compare them systematically — methods used, datasets evaluated on, metrics reported, key results. Building this table by hand is tedious. An LLM that already has access to each paper's title + abstract can do a first pass automatically.

Proposed behaviour

New CLI command: mosaic compare

mosaic compare [OPTIONS] [QUERY]

Works on cached papers (no network required when --cached is implied) or on fresh search results.

Example

# Compare top-cited cached papers on diffusion models
mosaic compare "diffusion models image generation" --sort citations -n 15 --output comparison.md

# Compare papers from a BibTeX file along custom axes
mosaic compare --from refs.bib --dimensions "method,dataset,BLEU,limitations"

Output (Markdown table)

| # | Title | Year | Method | Dataset | Metric | Result |
|---|-------|------|--------|---------|--------|--------|
| 1 | DDPM | 2020 | Denoising diffusion | CIFAR-10, LSUN | FID | 3.17 |
| 2 | Stable Diffusion | 2022 | Latent diffusion | LAION-5B | FID / CLIP | 12.6 / 0.31 |
| … | … | … | … | … | … | … |

Implementation sketch

• LLM prompt: given title + abstract (up to 300 chars), extract the requested dimensions as a JSON object; fall back gracefully to "–" for unavailable fields
• Uses the same [llm] config already in place (mosaic config --llm-provider ...); when no LLM is configured, extracts year/source/DOI from cache metadata only and leaves method/result columns empty with a notice
• Batches up to 20 papers per LLM call (same pattern as --sort relevance)
• --output reuses the existing exporter infrastructure; Markdown table is the default

Relationship between the two features

These features are independent but compose naturally:

# Step 1 — collect papers
mosaic search "graph neural networks" -n 50 --prefer-cache

# Step 2 — compare methods across top results
mosaic compare "graph neural networks" --sort citations -n 20 --output comparison.md

# Step 3 — visualise the citation network of the same corpus
mosaic network --query "graph neural networks" --cluster --output network.md

Out of scope for this issue

• Full-text extraction (requires PDF parsing)
• Automated literature review writing (tracked separately)
• Hypothesis generation or research gap analysis (tracked separately)