Feat/issue triggered curation agent by lwaldron · Pull Request #138 · waldronlab/curatedMetagenomicDataCuration

lwaldron · 2026-03-12T03:36:33Z

Title

feat: issue-triggered metadata curation agent + Excel prefill API

Summary

This PR adds an issue-triggered GitHub Actions curation flow with human-in-the-loop (HITL) mapping review, and refactors Excel template generation to use explicit metadata prefilling.

What changed

Replaced example_data in generate_data_entry_excel() with prefill_metadata
- Supports NULL, data.frame, or CSV/TSV path
- Defaults to package example prefill file in inst/extdata
Added package example prefill dataset (cMD_prefill_example.csv)
Added curation issue form template for BioProject + attachment + DOI intake
Added full workflow for:
- issue intake + metadata lookup
- column mapping via GitHub Models API (gpt-4o-mini) with heuristic fallback
- HITL question/response loop via issue comments
- state persistence on curation-state/issue-<N> branch
- Excel artifact generation after mapping resolution
Added agent scripts:
- agent_state.R
- agent_metadata_lookup.R
- agent_column_mapping.R
- agent_prefill_excel.R
Added robust script fallback loading when package exports are unavailable in runtime context
Updated docs and script usage to the new prefill_metadata API
Added tests for CLI agent scripts

Testing

devtools::test(filter = "excel-generation") passed
devtools::test(filter = "agent-scripts") passed (46 passed, 0 failed, 0 warnings)
Script parse checks and end-to-end smoke flow completed successfully

Notes

Workflow uses lightweight ubuntu-latest + r-lib/actions setup (no Bioconductor Docker).
LLM mapping runs only when GITHUB_TOKEN is available; otherwise heuristic mapping is used.

AI Attribution

This PR was developed with assistance from GitHub Copilot (GPT-5.3-Codex) "Planning" Agent.

These changes have NOT yet been manually tested - only the AI-generated machine tests. Many features require GitHub Actions and Issues for testing.

- Refactor generate_data_entry_excel(): replace example_data bool with prefill_metadata param (NULL | data.frame | CSV/TSV path); default loads inst/extdata/cMD_prefill_example.csv - Add load_prefill_metadata() and split_prefill_values() internal helpers - Add inst/extdata/cMD_prefill_example.csv (4 example rows) - Update man/, inst/scripts/generate_excel_template.R, README_EXCEL_GENERATION.md - Update tests: example_data=FALSE -> prefill_metadata=NULL; add data.frame prefill test - Add .github/ISSUE_TEMPLATE/cMD_sra_curation.yml (BioProject, attachment, DOI fields) - Add .github/workflows/metadata-curation-agent.yml (HITL loop: intake-and-map + process-curator-response jobs; ubuntu-latest + r-lib/actions; state on curation-state/issue-N branch; LLM via GitHub Models API gpt-4o-mini) - Add inst/scripts/agent_state.R (init/update_mapping/apply_response/status) - Add inst/scripts/agent_metadata_lookup.R (SRA/BioSample fetch + attachment join) - Add inst/scripts/agent_column_mapping.R (LLM + adist heuristic fallback) - Add inst/scripts/agent_prefill_excel.R (state -> prefill df -> Excel) - Add tests/testthat/test-agent-scripts.R (46 tests, 0 failures)

github-actions · 2026-03-12T03:38:23Z

Metadata Validation Report

Date: $(date -u +"%Y-%m-%d %H:%M:%S UTC")
Trigger: pull_request
Branch: 138/merge

Schema Information

Repository: shbrief/OmicsMLRepoCuration
Commit: 52cdc8e

Results

Total Files: 130
Status: ❌ FAIL

Copilot

Pull request overview

Adds an issue-triggered GitHub Actions “curation agent” flow (stateful HITL mapping + Excel artifact generation) and refactors Excel template generation to use explicit prefill_metadata rather than the prior example_data behavior.

Changes:

Refactor generate_data_entry_excel() to support prefill_metadata (data.frame or CSV/TSV path) and ship an example prefill dataset.
Add CLI agent scripts for state management, metadata lookup/merge, column mapping (LLM + heuristic), and Excel prefill generation.
Add an issue template + GitHub Actions workflow to drive the end-to-end issue-triggered curation loop, plus new test coverage for agent scripts.

Reviewed changes

Copilot reviewed 13 out of 14 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
`tests/testthat/test-excel-generation.R`	Updates Excel generation tests for the new `prefill_metadata` API and adds a data.frame prefill test.
`tests/testthat/test-agent-scripts.R`	Adds subprocess-based tests for CLI agent scripts (argument parsing + state transitions + heuristic mapping).
`R/generate_data_entry_excel.R`	Replaces `example_data` prefilling with file/data.frame-driven `prefill_metadata` loading + row prefill logic.
`man/generate_data_entry_excel.Rd`	Updates generated Rd docs to document `prefill_metadata` parameter and defaults.
`inst/scripts/README_EXCEL_GENERATION.md`	Updates documentation/examples to pass `prefill_metadata` (often set to `NULL` to disable).
`inst/scripts/generate_excel_template.R`	Updates script invocation to pass `prefill_metadata = NULL`.
`inst/scripts/agent_state.R`	New CLI for initializing/updating/reading state and applying curator comment decisions.
`inst/scripts/agent_prefill_excel.R`	New CLI to build a prefill CSV from mappings and generate a prefilled Excel workbook.
`inst/scripts/agent_metadata_lookup.R`	New CLI to download/merge manual attachment metadata with BioProject lookups and emit summaries.
`inst/scripts/agent_column_mapping.R`	New CLI to map input columns to dictionary columns (GitHub Models call with heuristic fallback) and emit HITL questions.
`inst/extdata/cMD_prefill_example.csv`	Adds packaged example prefill dataset used as the default `prefill_metadata`.
`inst/extdata/cMD_data_dictionary.csv`	Updates dictionary descriptions (more explicit guidance/ontology notes).
`.github/workflows/metadata-curation-agent.yml`	New workflow implementing issue-labeled intake, mapping + HITL loop, state branch persistence, and Excel artifact generation.
`.github/ISSUE_TEMPLATE/cMD_sra_curation.yml`	New issue form template for metadata curation intake (BioProject/SRA + attachment + DOI).

Files not reviewed (1)

man/generate_data_entry_excel.Rd: Generated file

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

+    if (!file.exists(script)) {
+      # Try relative from the package root
+      pkg_root <- rprojroot::find_package_root_file()
+      script <- file.path(pkg_root, "inst", "scripts", script_name)
+    }


+    overlap <- intersect(names(manual_df), names(lookup_df))
+    if (length(overlap) > 0) {
+      names(lookup_df)[names(lookup_df) %in% overlap] <- paste0(names(lookup_df)[names(lookup_df) %in% overlap], "_lookup")
+    }
+    return(cbind(manual_df, lookup_df, stringsAsFactors = FALSE))
+  }


+        id: extract
+        shell: bash
+        run: |
+          BODY="${{ github.event.issue.body }}"


+  process-curator-response:
+    if: github.event_name == 'issue_comment' && github.event.action == 'created'
+    runs-on: ubuntu-latest


+        id: apply
+        shell: bash
+        run: |
+          echo "${{ github.event.comment.body }}" > "${{ steps.branch.outputs.STATE_DIR }}/comment.txt"


-uncurated_metadata,character,non-unique,optional,TRUE,Additional information that doesn't belong to the existing fields,.+,NA,NA,NA,<;>,NA,any,1,05 Other
+disease_response_os,numeric,non-unique,optional,FALSE,Overall survival duration (time to death from any cause; NCIT:C125201).,^[1-9]\d*(\.\d+)?$,NA,NA,NA,NA,NA,numeric,42,04 Clinical / Intervention
+disease_response_os_unit,character,non-unique,optional,FALSE,Unit used to report `disease_response_os`. Static ontology IDs: NCIT:C25301; NCIT:C29844; NCIT:C29846; NCIT:C29848. Type: static.,Day|Week|Month|Year,NCIT:C25301|NCIT:C29844|NCIT:C29846|NCIT:C29848,NA,NA,NA,NA,static_enum,43,04 Clinical / Intervention
+ecog_performance_status,character,non-unique,optional,FALSE,A performance status scale designed to assess disease progression and its affect on the daily living abilities of the patient. (NCIT:C105721) Static ontology IDs: NCIT:C105722; NCIT:C105723; NCIT:C105724; NCIT:C105725; NCIT:C105726; NCIT:C105727; NCIT:C105728. Type: static.,ECOG Performance Status 0|ECOG Performance Status 1|ECOG Performance Status 2|ECOG Performance Status 2 or Higher|ECOG Performance Status 3|ECOG Performance Status 4|ECOG Performance Status 5,NCIT:C105722|NCIT:C105723|NCIT:C105724|NCIT:C105725|NCIT:C105726|NCIT:C105727|NCIT:C105728,NA,NA,NA,NA,static_enum,44,04 Clinical / Intervention


+name: Metadata Curation Agent
+
+on:
+  workflow_dispatch:


lwaldron added 6 commits March 11, 2026 18:24

docs: improve data dictionary descriptions and add dynamic ontology URLs

08bb211

Albert Einstein example

f3f5c8f

docs: standardize ontology ID metadata in dictionary descriptions

021be19

explain non-uniqueness of subject_id

5c65397

docs: prune irrelevant enum lookup text from descriptions

7c16e02

lwaldron requested a review from Copilot June 18, 2026 14:05

Copilot started reviewing on behalf of lwaldron June 18, 2026 14:06 View session

Copilot AI reviewed Jun 18, 2026

View reviewed changes

Navigation Menu

Uh oh!

Feat/issue triggered curation agent - #138

Feat/issue triggered curation agent#138
lwaldron wants to merge 6 commits into
masterfrom
feat/issue-triggered-curation-agent

lwaldron commented Mar 12, 2026

Uh oh!

github-actions Bot commented Mar 12, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

lwaldron commented Mar 12, 2026

Title

Summary

What changed

Testing

Notes

AI Attribution

Uh oh!

github-actions Bot commented Mar 12, 2026

Metadata Validation Report

Schema Information

Results

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants