Skip to content

Citation graph: fill cites / cited_by from TEI references #16

Description

@deOliveira-R

With `item_artifacts` + `extract/tei.py` landed (commit e2b7342), we have structured references for every paper with a `grobid_tei` artifact. The schema already has `cites` / `cited_by` in the `item_relations` CHECK vocabulary — they've just never been written to.

Plan

  1. New CLI subcommand: `grimoire citations build [--force] [--limit N]`.
  2. For each item with a `grobid_tei` artifact:
  3. Idempotent via the `INSERT OR IGNORE` on the relations table.

Unlocks

  • MCP `list_related(item_id, kind='citations')` already has the code path for this relation; it just returns nothing today.
  • Queries like "papers in my library that cite X" and "what does paper Y cite that I have" become one SQL hop.
  • Claude Code can ask "trace the citation chain forward/backward from this paper" via repeated `list_related` calls.

Acceptance

  • `grimoire citations build` walks all items with a TEI artifact and writes `cites`/`cited_by` edges for DOI-matched references.
  • Self-citations (same item as source and target) are skipped.
  • Re-running is a no-op (`INSERT OR IGNORE`).
  • Test with a synthetic TEI → seeded `items` matching the DOI → assert the edges + inverse appear.
  • At least a terse status line: "N items scanned, M edges inserted, K unresolved DOIs."

Caveats

  • GROBID reference-section parsing quality drops on chapter-in-edited-book style references — expect some noise.
  • DOI-matching is exact; consider a normalization pass (strip `https://doi.org/\`, lowercase) to avoid missing hits.
  • Bibliography entries without DOIs are genuinely unrecoverable from TEI alone — surface them in the "suggested" queue, don't try to fuzzy-match.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions