Automated Nextstrain Clade Monitoring & Variant Definition Creation

[gordonkoehn]

This PR implements a complete automation pipeline for monitoring new Nextstrain clade designations and automatically creating variant definition files for wastewater surveillance, based in mutations found in clinical sequences found on CovSpectrum once the new variant appears.

See full description for design of this automation here on MIRO.

This setup mirrors and automates our existing procedure i.e.:

1. Get notice of new Variant --> get Github Notification for new Issue
2. Wait for new Variant definitions to appear once Nextclade / CovSpectrum finishes, ~16 h later, after - new variants are assigned in ncov.
3. Run cojac sig-generate manually open PR --> PR appears automatically fetched from CovSpectrum, assigned to us

For both the Issues and the PR, we can select to notify/assign people, i.e., to @gordonkoehn, Kyra? David?

For example, Alert see here:

• New Nextstrain Clade Designation Detected: 25C (XFG) #43
  For an Example PR, see here:
• Add automated variant definition for XFG (25C) #46

It's rather hard to test the scheduling of the GitHub actions, so it may very well be that we have to iterate on this mechanism. Trusting in AI so far. All manual triggering I do seems to work fine.

Detailed flow:

• Triggers automatically when new clades are detected in ncov , makes Issue
• Schedules to query the cov Spectrum every day for 7 days
• Queries CovSpectrum API for nucleotide signature mutations
• Generates properly formatted YAML files in voc directory
• Creates pull requests with variant definitions
• Links PRs to originating issues via "Closes #X"
• Comments on issues with status updates and error details
• Prevents duplicate PRs for the same variant

Workflow Architecture

• Monitor (voc-monitor.yaml) - Detects new clades → Creates enriched issues
• Creator (variant-creator.yaml) - Triggered by labeled issues → Creates variant definitions
• Retry (variant-retry.yaml) - Scheduled retries for failed attempts

Testing

• Tested the logic locally - validates all logic components
• CovSpectrum API integration confirmed working
• Generated files match expected YAML structure
• Issue parsing and PR creation logic verified

This automation eliminates manual variant definition creation and ensures timely updates to the wastewater monitoring system.

=======

Before merging, we still need to set "arm" the workflow, that is:

• Change the branch that merges updates to

[gordonkoehn]

Products ;)

[gordonkoehn]

Before merging:

• remove trigger on push
• Extend age of open issues to trigger alerts to up to 2 weeks. (as sometimes we may wait for more mutations to arise)
• [ ]assign alerts to @gordonkoehn + @DrYak @mcarrara-bioinfo @kirschen-k @frSinger
• assign PRs to @gordonkoehn + @DrYak @mcarrara-bioinfo @kirschen-k

[gordonkoehn]

Will merge with single review. Note: This GitHub automation will push to main. To update its ledger of known variants.