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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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