feat(research): close citation graph and obsidian export gaps

[jerry609]

Summary

• add CitationGraphClient with multi-hop traversal, direction controls, relevance filtering, and tests
• finish Obsidian track folder + _MOC.md exports, including tasks, milestones, scholars, and configurable track layout
• add citation/backlink sections for paper notes and a long-form Obsidian report exporter with /api/obsidian/export-report

Issues

• refs [P1] 实现 CitationGraphClient 多跳引用图遍历 #160
• refs [P0] 研究 Track → Obsidian 文件夹/MOC 映射 #170
• refs [P1] 论文引用关系 → Obsidian Graph 可视化 #171
• refs [P1] 研究报告 → Obsidian 长文笔记 #172

Validation

• PYTHONPATH=src pytest -q tests/unit/test_citation_graph_client.py tests/unit/test_obsidian_exporter.py tests/unit/test_obsidian_sync.py tests/unit/test_obsidian_cli.py tests/unit/test_obsidian_report_exporter.py tests/unit/test_obsidian_report_routes.py tests/integration/test_research_track_routes.py
• PYTHONPATH=src python -m py_compile config/settings.py src/paperbot/infrastructure/api_clients/citation_graph.py src/paperbot/infrastructure/exporters/obsidian_exporter.py src/paperbot/infrastructure/exporters/obsidian_sync.py src/paperbot/infrastructure/exporters/obsidian_report_exporter.py src/paperbot/api/routes/obsidian.py

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
paper-bot	Building	Preview, Comment	Mar 12, 2026 6:43am

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 2a7e105e-1aa0-4283-b9cf-41873eb5dfa2

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch pr/close-obsidian-citation-160-172

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly expands the research workflow capabilities by integrating advanced citation analysis and enhancing Obsidian knowledge management. It provides a robust tool for exploring academic citation networks and offers a more structured and comprehensive way to export research tracks and reports into Obsidian, improving organization and discoverability of research artifacts.

Highlights

• Citation Graph Client: Added a new CitationGraphClient with capabilities for multi-hop traversal, direction controls (references/citations), and relevance filtering, complete with comprehensive tests.
• Obsidian Track Export Enhancements: Improved Obsidian track exports to support track folders and a configurable _MOC.md filename. Exports now include detailed information on tasks, milestones, and scholars associated with a track.
• Obsidian Report Exporter & API: Introduced a new long-form Obsidian report exporter, accessible via the /api/obsidian/export-report endpoint, and added citation/backlink sections to paper notes for richer inter-note connections.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• config/config.yaml
  • Added new configuration options for Obsidian track Master of Contents (MOC) filename and track folder grouping.
• config/settings.py
  • Introduced track_moc_filename and group_tracks_in_folders fields to the ObsidianConfig model.
  • Implemented loading of PAPERBOT_OBSIDIAN_TRACK_MOC_FILENAME and PAPERBOT_OBSIDIAN_GROUP_TRACKS_IN_FOLDERS environment variables.
• src/paperbot/api/main.py
  • Included the new obsidian router in the main FastAPI application.
• src/paperbot/api/routes/init.py
  • Exported the new obsidian router module.
• src/paperbot/api/routes/obsidian.py
  • Added a new file defining FastAPI routes and Pydantic models for exporting long-form Obsidian research reports.
• src/paperbot/application/ports/vault_exporter_port.py
  • Updated the export_library_snapshot method signature to include track_moc_filename and group_tracks_in_folders parameters.
• src/paperbot/infrastructure/api_clients/init.py
  • Imported and exposed new classes for CitationGraph, CitationGraphClient, CitationGraphEdge, and CitationGraphNode.
• src/paperbot/infrastructure/api_clients/citation_graph.py
  • Added a new file implementing the CitationGraphClient for multi-hop traversal of citation networks based on Semantic Scholar data.
• src/paperbot/infrastructure/exporters/init.py
  • Imported and exposed the new ObsidianReportExporter.
• src/paperbot/infrastructure/exporters/obsidian_exporter.py
  • Modified the paper note template to include dedicated sections for 'References' and 'Cited By' links.
  • Updated export_library_snapshot to accept new configuration for track MOC filename and folder grouping.
  • Implemented _sync_paper_citation_backlinks to automatically update citation and cited-by links in related paper notes.
  • Enhanced _write_track_note to support track folder structures, configurable MOC filenames, and to include tasks, milestones, and scholars in track notes.
  • Added _track_wikilink for generating Obsidian wikilinks for tracks with new folder and MOC conventions.
  • Introduced helper methods (_paper_entry_links, _paper_reference_entries, _paper_citation_entries, _paper_related_entries, _paper_relation_entries, _normalize_paper_relation_entry) for robust handling of paper relationships.
  • Added utility methods (_read_note, _upsert_markdown_section) for programmatic reading and updating of Obsidian notes.
• src/paperbot/infrastructure/exporters/obsidian_report_exporter.py
  • Added a new file implementing ObsidianReportExporter for rendering structured long-form research reports into Obsidian markdown notes.
• src/paperbot/infrastructure/exporters/obsidian_sync.py
  • Introduced _list_track_items helper to fetch associated items like tasks and milestones for a track.
  • Modified export_track_snapshot to retrieve and include track tasks and milestones in the exported track payload, and to pass new Obsidian configuration options to the exporter.
• src/paperbot/presentation/cli/main.py
  • Updated the _run_obsidian_export CLI command to pass track_moc_filename and group_tracks_in_folders to the Obsidian exporter.
• tests/unit/test_citation_graph_client.py
  • Added new unit tests for the CitationGraphClient to verify graph traversal, deduplication, relevance filtering, and parallel fetching.
• tests/unit/test_obsidian_cli.py
  • Updated CLI tests to reflect the new track note path convention (e.g., _MOC.md within a track folder) and the passing of new configuration parameters.
• tests/unit/test_obsidian_exporter.py
  • Updated tests to assert the presence of new 'References' and 'Cited By' sections in paper notes.
  • Verified that track notes now include tasks, milestones, and scholars.
  • Confirmed the correct behavior of track folder grouping and _MOC.md filenames.
  • Added a test case to ensure backfilling of cited_by links in existing paper notes.
• tests/unit/test_obsidian_report_exporter.py
  • Added new unit tests for ObsidianReportExporter to validate the correct generation of long-form research reports.
• tests/unit/test_obsidian_report_routes.py
  • Added new unit tests for the Obsidian report API routes, verifying report export functionality and required parameters.
• tests/unit/test_obsidian_sync.py
  • Updated tests to confirm that track tasks and milestones are correctly fetched and included in the exported track payload.
  • Verified that new Obsidian configuration options are correctly passed to the exporter during sync operations.

Activity

• The pull request introduces significant new features for research workflow and Obsidian integration.
• New API endpoints and client functionalities have been added, accompanied by extensive unit tests to ensure correctness and robustness.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces significant enhancements to the research and Obsidian export functionalities. The new CitationGraphClient provides a robust way to traverse citation networks with good features like multi-hop traversal, direction control, and relevance filtering. The Obsidian export has been greatly improved, now supporting track-specific folders, MOC files, and richer content in notes, including tasks, milestones, scholars, and citation/backlink sections. The addition of a long-form report exporter via the /api/obsidian/export-report endpoint is also a valuable feature. The code is well-structured, and the inclusion of comprehensive unit tests for all new components is commendable. I have one minor suggestion regarding logging in the new citation graph client to improve debuggability. Overall, this is an excellent contribution.

[gemini-code-assist]

The broad except Exception here silently ignores any errors from the relevance_filter, which can make debugging difficult. It's better to log the exception to provide visibility into why a paper might be scored as 0.0.

Consider changing this block to something like this:

            except Exception as exc:
                logger.warning("Relevance filter failed for paper %r: %s", paper_id, exc)
                score = 0.0

You'll also need to add import logging and logger = logging.getLogger(__name__) at the top of the file.

[Copilot]

Pull request overview

Adds missing research tooling around multi-hop citation traversal and completes Obsidian export coverage (track layout/MOC, citation backlinks, and long-form report export) to close gaps referenced by issues #160/#170/#171/#172.

Changes:

• Introduces CitationGraphClient for multi-hop traversal over Semantic Scholar references/citations (with filtering, direction controls, concurrency, and tests).
• Extends Obsidian vault export to support track folders + configurable MOC filenames, plus tasks/milestones/scholars and citation/backlink sections for paper notes.
• Adds long-form Obsidian report exporter and POST /api/obsidian/export-report route with tests.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/unit/test_obsidian_sync.py	Extends sync tests to include track tasks/milestones and new track layout settings.
tests/unit/test_obsidian_report_routes.py	Validates new export-report API behavior and default settings usage.
tests/unit/test_obsidian_report_exporter.py	Verifies long-form report note rendering, callouts, links, and table output.
tests/unit/test_obsidian_exporter.py	Covers citation sections/backlink backfill, track folder/MOC linking, and track metadata sections.
tests/unit/test_obsidian_cli.py	Updates CLI export expectations for new track note path/layout settings.
tests/unit/test_citation_graph_client.py	Unit tests for traversal directionality, hop behavior, filtering, and concurrency.
src/paperbot/presentation/cli/main.py	Passes new Obsidian layout settings from config into export call.
src/paperbot/infrastructure/exporters/obsidian_sync.py	Enriches exported track payload with tasks/milestones; forwards layout settings.
src/paperbot/infrastructure/exporters/obsidian_report_exporter.py	Implements Obsidian long-form report writer (frontmatter, callouts, paper/track links).
src/paperbot/infrastructure/exporters/obsidian_exporter.py	Adds citation/reference sections, backlink syncing, and track folder + MOC filename support.
src/paperbot/infrastructure/exporters/init.py	Exports ObsidianReportExporter from the package.
src/paperbot/infrastructure/api_clients/citation_graph.py	Implements citation graph traversal client + graph data structures.
src/paperbot/infrastructure/api_clients/init.py	Re-exports citation graph types/client.
src/paperbot/application/ports/vault_exporter_port.py	Extends exporter port signature with track layout parameters.
src/paperbot/api/routes/obsidian.py	Adds /api/obsidian/export-report endpoint and request/response models.
src/paperbot/api/routes/init.py	Registers the new Obsidian routes module.
src/paperbot/api/main.py	Includes the Obsidian router in the FastAPI app.
config/settings.py	Adds Obsidian config options + env var support for track MOC filename and grouping.
config/config.yaml	Adds defaults for the new Obsidian config options.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

note_path is always truthy (even when constructed from an empty string, it becomes Path('.')), so if not note_path: will never skip invalid/missing paths. This can lead to unnecessary work and makes the guard ineffective. Consider checking the original path string before creating the Path, or explicitly skipping when paper_ref.get('path') is empty/whitespace.

Suggested change

	note_path = Path(str(paper_ref.get("path") or "")).expanduser()
	if not note_path:
	continue
	raw_note_path = str(paper_ref.get("path") or "").strip()
	if not raw_note_path:
	continue
	note_path = Path(raw_note_path).expanduser()

[Copilot]

track_moc_filename is concatenated into note_path without validation. If it contains path separators (e.g. ../something.md) it can escape the track folder and write outside the intended vault subtree. Consider validating it as a plain filename (no / or ..) and/or normalizing via Path(track_moc_filename).name, and optionally enforcing a .md extension.

[Copilot]

visited is updated with requested_id, but nodes/edges use canonical_id derived from the fetched payload. If callers traverse using non-canonical IDs (e.g. DOI/arXiv), the canonical paperId can re-enter the frontier later and be re-fetched, causing duplicate work and potentially inconsistent hop attribution. Consider marking both requested_id and canonical_id as visited and/or normalizing frontier keys to canonical IDs after the first fetch.

Suggested change

	visited.add(requested_id)
	paper = payload or {}
	if not paper:
	continue
	canonical_id = self._paper_id(paper) or requested_id
	paper = payload or {}
	if not paper:
	# Mark the requested identifier as visited even if the payload is empty
	visited.add(requested_id)
	continue
	canonical_id = self._paper_id(paper) or requested_id
	# Mark both the requested and canonical identifiers as visited to avoid re-fetching
	visited.add(requested_id)
	visited.add(canonical_id)

[Copilot]

The except Exception: here is a deliberate swallow of relevance filter failures, but the repo appears to use Ruff's BLE001 rule and typically annotates intentional broad catches with # noqa: BLE001. Adding that (and a brief reason) will avoid lint failures and clarify intent.

Suggested change

	except Exception:
	except Exception: # noqa: BLE001 - treat relevance filter failures as non-relevant