feat: reports and download links

[vtnphan]

Pull Request

Summary

SBP-179 Add result APIs for report, download, snapshot access, tighten BindCraft output discovery to the DB run.id S3 layout, and refactor result-specific artifact logic into results_utils.

Changes

• Added result-view endpoints in app/routes/workflow/results.py for:
  • submitted settings
  • logs
  • HTML report/animation link
  • non-snapshot downloads
  • snapshot-only downloads
• Added/updated response models in app/schemas/workflows.py for result downloads and snapshot responses
• Implemented BindCraft artifact discovery for:
  • HTML reports
  • stats CSV outputs
  • ranked PDB files
  • snapshot PNGs
• Restricted artifact discovery to the DB workflow_runs.id-based S3 path layout
• Separated API behavior so:
  • /report returns only the HTML animation/report link
  • /downloads excludes snapshot PNGs
  • /snapshots returns snapshot PNG links only
• Moved result-specific artifact discovery/link generation from app/services/job_utils.py to app/services/results_utils.py
• Kept score-related job logic in app/services/job_utils.py, reusing shared result sync helpers where needed
• Added substantial test coverage for result routes and result artifact helpers
• Updated README.md endpoint documentation to reflect the current API

How to Test

1. Install dependencies if needed:

   uv sync --all-extras

2. Run code quality checks:

   uv run ruff check app tests
   uv run black --check app tests
   uv run mypy app --ignore-missing-imports

3. Run the test suite:

   uv run pytest -q

4. Optionally verify coverage:

   uv run pytest --cov=app --cov-report=term-missing -q

5. Manually verify result API behavior for a completed BindCraft run:
   • GET /api/results/{run_id}/report returns the HTML animation/report link only
   • GET /api/results/{run_id}/downloads returns report/CSV/PDB links and excludes snapshots
   • GET /api/results/{run_id}/snapshots returns snapshot PNG links only

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have added tests that prove my fix is effective or that my feature works
• I have added or updated documentation where necessary
• I have run linting and unit tests locally
• The code follows the project's style guidelines

[Copilot]

Pull request overview

Adds result-focused APIs and supporting utilities for discovering BindCraft artifacts in S3, persisting them to the DB, and returning pre-signed report/download/snapshot links to the frontend.

Changes:

• Added /api/results/{run_id}/report, /downloads, and /snapshots endpoints (plus expanded settings/logs behavior) with S3/Seqera error mapping.
• Implemented BindCraft artifact discovery + link generation in app/services/results_utils.py and integrated output syncing into score calculation.
• Added/updated Pydantic response models and expanded test coverage + README endpoint documentation.

Reviewed changes

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

Show a summary per file

File	Description
app/routes/workflow/results.py	Adds result download/report/snapshot routes and maps S3 errors to HTTP responses.
app/services/results_utils.py	Implements artifact classification, S3 discovery, DB persistence, and pre-signed link generation helpers.
app/services/job_utils.py	Refactors to reuse results utilities and sync outputs before score computation.
app/schemas/workflows.py	Introduces response models for downloads/snapshots/report payloads.
tests/test_routes_results.py	Adds route-level tests for new endpoints and error handling behavior.
tests/test_services_job_utils.py	Updates score tests for new sync behavior and adds tests around BindCraft output syncing + snapshot/report helpers.
README.md	Updates documented API endpoints to include the new /api/results/* routes.

---

💡 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]

@vtnphan I've opened a new pull request, #28, to work on those changes. Once the pull request is ready, I'll request review from you.

[vtnphan]

@marius-mather this PR was re-opened and ready to review now. I added the content type to the report for the front end rendering yesterday. Thank you!! ^^~

[marius-mather]

Looks good overall, it just looks like there could be a lot of expensive operations for something that might need to be called/repeated a lot. Can you think about how to store the report somewhere so it doesn't have to be synced/generated every time you need to download it?