Skip to content

Migrate graph.py OpenAlex reference expansion to projio biblio

Goal

(promoted from note)

Context

(see source note)

Prompt

Fix the issue described below (source: /storage2/arash/projects/projio/docs/log/issue/issue-arash-20260328-145700-791144.md). Understand the problem, then implement the proposed fix.

Migrate graph.py from labpy sutil/biblio to projio biblio

sutil/biblio/graph.py in labpy contains expand_openalex_reference_graph() — an iterative multi-hop reference graph expansion via OpenAlex, seeded from known citekeys. This is the only unique functionality in labpy's legacy biblio module that projio doesn't yet cover.

Task

  1. Read /storage2/arash/sirocampus/code/labpy/src/sutil/biblio/graph.py to understand the API
  2. Read the projio biblio package structure to find the right location (likely under the biblio package)
  3. Port the graph expansion logic into projio's biblio package, adapting it to use projio's existing OpenAlex client and citekey resolution
  4. Add an MCP tool biblio_graph_expand(citekeys, max_hops) or similar that exposes this functionality
  5. Write a basic smoke test

Context

  • labpy audit confirmed this is the only piece worth migrating before deleting legacy modules
  • paper_absent_refs() in projio handles single-paper unresolved refs but not multi-hop graph traversal
  • After this migration, labpy's entire sutil/biblio/ can be deleted

Source context: labpy

Labpy (labpy): sirota lab main python package; initiated as a translation of labbox Matlab code into python

Recent commits: 

9404ac9 Add labbox↔labpy correspondence map and audit notes
3fe54eb Fix timefrequency API inconsistencies and add smoke tests
2c0ebb2 Add labbox ↔ labpy correspondence map

Acceptance Criteria

  • [ ]

Result

Completed in 1320.3s (1 steps, model: opus)

Session: 0af5ca04-3539-4666-a34a-842e84fdcd1a Result note: /storage2/arash/worklog/workflow/captures/20260328-174953-eedfc8/note.md

Output

The task (`f21b98e6248f`) is queued as pending — there's already a running task ahead of it plus 3 other pending tasks in the scheduler. It will execute once the queue clears.

Here's a summary of what was done and what's pending:

**Analysis completed:**
- Projio's `biblio/graph.py` already contains a **more advanced** version of labpy's `expand_openalex_reference_graph()` — it supports direction (references/citing/both), multi-hop with merge mode, progress callbacks, and seed citekey filtering
- The labpy version is a subset — **no core logic migration needed**
- What's missing is the **MCP tool wiring** (3 files + test)

**Task dispatched to projio** (queue ID `f21b98e6248f`):
1. Add `graph_expand()` to `packages/biblio/src/biblio/mcp.py`
2. Add `biblio_graph_expand()` wrapper to `src/projio/mcp/biblio.py`
3. Register `@server.tool("biblio_graph_expand")` in `src/projio/mcp/server.py`
4. Create smoke test at `packages/biblio/tests/test_biblio_graph_mcp.py`

## Next Steps
1. Wait for the queued task to complete, then verify with `tail_task(queue_id="f21b98e6248f")` — once done, check the test passes and the import works.
2. After the MCP tool is wired, delete labpy's legacy `sutil/biblio/` module since all functionality now lives in projio.
3. Update the labpy CLAUDE.md and correspondence map to reflect that the biblio migration is complete.