Repository navigation
Closing gaps with public release requirements - #134
Conversation
There was a problem hiding this comment.
This PR is not yet mark ready for review, but I wanted to capture some repo level checks to start. There are some suggested changes at the bottom. I will complete a full review once PR is marked ready
Compliance Checklist
This checklist is based on the BaseTemplate public-repository requirements and the current
repository checkout only. A checked box means the item is supported by evidence in the repo.
Unchecked boxes are items I could not confirm from the repo contents alone. Struck-through text
marks an item that does not apply to this repo's chosen tooling or structure.
Repository Basics
- Public-facing README exists and is substantive. Evidence: README.md describes the project purpose, installation, running examples, configuration, docs, deployment, contributing, support, license, code of conduct, and security.
- License file is present. Evidence: LICENSE exists, and the license is also declared in pyproject.toml and referenced in README.md.
- Contributing guide is present. Evidence: CONTRIBUTING.md documents bug reports, feature requests, pull requests, style, docs, testing, and AI/LLM-assisted contributions.
- Code of Conduct is present. Evidence: CODE_OF_CONDUCT.md is linked from README.md and CONTRIBUTING.md.
- Security policy is present. Evidence: SECURITY.md provides a private vulnerability-reporting path and supported-version guidance.
- Changelog is present. Evidence: CHANGELOG.md exists and is referenced from README.md and pyproject.toml.
- Repository support / project acknowledgment is documented. Evidence: README.md includes the Genesis Mission acknowledgment.
Package Management
- Dependency metadata is declared in a standard project file. Evidence: pyproject.toml contains project metadata, dependencies, dev dependencies, build-system configuration, and project URLs.
- Dependencies are locked for reproducibility. Evidence: poetry.lock is committed and corresponds to the Poetry workflow documented in docs/installation.md.
- Installation and development setup instructions are documented. Evidence: docs/installation.md and README.md describe
poetry install, verification steps, and dependency usage. - Development commands are documented. Evidence: Makefile exposes
install,test,lint,format,type-check,docs, andclean, and README.md summarizes them. - The package is structured as an installable Python project. Evidence: pyproject.toml declares
src/apeironas the package root, and the docs show the public import pathapeiron. uv.lockis present
Documentation
- Documentation site exists. Evidence: docs/ contains the Sphinx/MyST source, and docs/README.md explains the docs structure.
- Documentation is wired for Read the Docs. Evidence: .readthedocs.yaml configures the docs build, and docs/README.md explains local build behavior.
- A docs landing page and navigation tree exist. Evidence: docs/index.md defines the toctrees and site structure.
- API reference pages exist. Evidence: docs/api/index.md and the other files under docs/api/ are present.
- User-facing docs cover installation, quickstart, architecture, configuration, detectors, continuous learning, tracking, profiling, and deployment. Evidence: docs/installation.md, docs/quickstart.md, docs/architecture.md, docs/configurations.md, docs/drift_detectors.md, docs/continuous_learning.md, docs/tracking.md, docs/profiler.md, and docs/deployment.md.
Testing And CI
- Test files are present. Evidence: tests/ contains unit and integration coverage for drift detection, trainers, logging, evaluation, config, and profiling.
- CI workflow exists. Evidence: .github/workflows/build-test.yml runs lint, type checking, tests, and coverage upload.
- A second workflow exists for image-based validation. Evidence: .github/workflows/build-image.yml builds the Docker image and runs pytest inside it.
- Quality commands are documented and match CI intent. Evidence: Makefile and CONTRIBUTING.md both list lint, type-check, and test commands.
- CI is configured to run on pull requests. The current workflow in .github/workflows/build-test.yml is triggered by
pushandworkflow_dispatch, so I could not confirm PR-triggered checks from the repo.
Community Workflow
- Issue templates are present. Evidence: .github/ISSUE_TEMPLATE/bug_report.md and .github/ISSUE_TEMPLATE/feature_request.md.
- Pull request template is present. Evidence: .github/pull_request_template.md.
- The pull request template includes review, testing, documentation, and AI-assisted-work checklists. Evidence: .github/pull_request_template.md.
- Branch protection rules are enabled for the default branch. This cannot be confirmed from the repo checkout; it requires GitHub repository settings.
- Dependency alert / secret scanning / code scanning settings are enabled. These are GitHub settings, so they cannot be confirmed from the repo contents alone.
Notes
- The package-management requirement is satisfied in principle through Poetry: the repo has a declared project file, a committed lockfile, and documented install instructions.
- The main actionable compliance gap visible from the checkout is PR-triggered CI plus GitHub-side branch protection, because those are not verifiable or enforced from the repository files alone.
Action Items
- Add
pull_requestto .github/workflows/build-test.yml so the CI status is available on PRs. - Enable branch protection on the default branch in GitHub and require the CI checks before merge.
- Confirm GitHub repository security features are enabled: Dependabot alerts, secret scanning, and code scanning.
Suggested Cleanup
- Fix
FronitertoFrontierin src/apeiron/deployment/frontier/README.md. - Replace stale
BaseSim_Frameworkrepository references in src/apeiron/deployment/frontier/README.md and src/apeiron/deployment/perlmutter/README.md with the current repo name. - Correct
Requirestedin docs/model_harness.md. - Correct the
beecausecomment in .github/workflows/build-test.yml. - Review the public
get_optmizerspelling in src/apeiron/model/torch_model_harness.py, docs/model_harness.md, examples/README.md, and the example harnesses before deciding whether to introduce a breaking rename. - Rename tests/test_valiadation_tests.py for spelling consistency, if the test import paths and CI references permit it.
- Update the README.md acknowledgment to
This work was supported by the U.S. Department of Energy (DOE), Office of Science, Office of Advanced Scientific Computing Research in alignment with DOE's Genesis Mission.
Codex was used to facilitate this review, but I stand behind it.
- Run CI on pull_request so status checks report on PRs. The examples job stays gated to workflow_dispatch, so PRs only run the build job. - Use the DOE Office of Science / ASCR acknowledgment wording in the README and docs landing page. - Fix stale BaseSim_Framework clone URLs in the Frontier and Perlmutter deployment guides. - Fix typos: "Froniter", "Requirested", "beecause". - Rename tests/test_valiadation_tests.py to tests/test_validation_tests.py. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
BaseModelHarness.get_optmizer() was a misspelled abstract method that users override in their own harnesses, so it cannot be renamed with a simple alias: the bridge has to work in both directions. - get_optimizer() is now the abstract method the framework calls. - get_optmizer() remains as a concrete deprecated shim that delegates to get_optimizer() and warns at call time, for external callers of the old name. - __init_subclass__ detects a subclass that implements only the old spelling, aliases it onto get_optimizer() so it still satisfies the ABC, and warns at class-definition time. A harness written against either spelling keeps working. Renames the in-repo implementations (three example harnesses and the test harness) and the one caller in continuous_trainer, and updates the docs, examples README, CLAUDE.md, and the Claude/Codex skill files, two of which previously told authors to preserve the misspelling. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Puts us in sync with BaseTemplate, and also resolves a dependency issue caused by a quirk in how Poetry builds the dependency chain: with torch 2.13, Poetry locked two conflicting versions of nvidia-cublas and nvidia-cuda-nvrtc under overlapping Linux markers, which broke installs on Linux. uv resolves a single version of each. Claude helped. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
I can confirm that Branch protection rules are enabled for the default branch. |
anagainaru
left a comment
anagainaru
left a comment
There was a problem hiding this comment.
I know this is still a draft, but I had some time to look over this. It's not great that we cannot use pip install apeiron. If we want to change the name this is the time, before we submit the SoftwareX paper. Or if we keep the name can we do something like pip install modcon-apeiron?
|
|
||
| def __init_subclass__(cls, **kwargs: Any) -> None: | ||
| """ | ||
| Bridge the deprecated ``get_optmizer`` spelling onto ``get_optimizer``. | ||
|
|
||
| A harness written against the old misspelled name keeps working: its | ||
| implementation is aliased onto the new name, so the framework only ever | ||
| has to call ``get_optimizer``. | ||
| """ | ||
| super().__init_subclass__(**kwargs) |
There was a problem hiding this comment.
Not sure if we want to keep backwards compatibility.
There was a problem hiding this comment.
I think that we should for one release then drop it
|
|
||
|
|
||
| class TestGetOptimizerDeprecation: |
There was a problem hiding this comment.
This is also not needed if we don't keep the deprecation.
| @@ -0,0 +1,90 @@ | |||
| # Changelog | |||
There was a problem hiding this comment.
Is this file really needed in root? Isn't this covered in the release notes?
There was a problem hiding this comment.
Kinda. One benefit is it lives alongside the code so it's there for whoever pulls from source and not just releases. It also makes it easy to create the release notes (might be less meaningful in the world of AI).
|
We can use genesis-apeiron, modcon-apeiron, or something like that on pypi |
|
Keeping the code is fine as long as we remember to remove it for the next release (not sure what the standard in python is to mark a code deprecated). This looks good to me, but Stefan or Nathan need to approve it. |
wildsm
left a comment
wildsm
left a comment
There was a problem hiding this comment.
Thanks for all the development, this was a great leap forward toward addressing https://github.com/AI-ModCon/BaseTemplate#required-elements-for-modcon-base-public-repositories
Some comments:
-
With the move from poetry to uv, I was reviewing lingering poetry occurrences. I think all is well, but note that there are poetry references in .codex/skills/install-apeiron/SKILL.md and .claude/skills/install-apeiron/SKILL.md. If desired, you could add a brief note toward the top each skill to clearly state that
This skill can install Apeiron into projects managed by uv, Poetry, or pip. This repository itself uses uv. -
PR-triggered CI:
build-test.ymlruns onpush,pull_request, andworkflow_dispatch, and includes lint, type checking, tests, and coverage. Remove the action item to addpull_request; it is already configured. Note thatbuild-image.ymlis push-only. -
The repo tripped on the security policy since the tab mentioned in SECURITY.md was empty, but this PR should populate it (something to check after merge).
|
@anagainaru - An approving review from someone with write access is needed. Can you please formally review/complete review? |
|
@andrewfayres - I think we are good to merge, congrats |
3 participants
Summary
Brings Apeiron in line with the BaseTemplate requirements for ModCon Base public repositories so we can release it publicly. The PR adds the missing community and governance files, migrates the project from Poetry to uv, and upgrades dependencies to clear the open Dependabot alerts.
Motivation & Context
CONTRIBUTING.md,CODE_OF_CONDUCT.md,SECURITY.md,CHANGELOG.md, issue templates, or AI-contribution policy, and no acknowledgment of DOE / Genesis Mission support.main.Approach
The commits are best reviewed one at a time:
73d3ebb,b7281b2)CONTRIBUTING.md(including BaseTemplate's AI/LLM-assisted contribution policy, verbatim),CODE_OF_CONDUCT.md,SECURITY.md(GitHub private vulnerability reporting),CHANGELOG.md, and issue templates.pyproject.toml, and aMakefile.get_optmizer→get_optimizer(d73501f)__init_subclass__bridges subclasses that implement only the old name onto the new one, and warns when the class is defined.ecd5ed1) — clears 121 of 122 Dependabot alerts.8f26ba1,6c96c85)nvidia-cublasthrough two paths with differently shaped markers, and Poetry locked two conflicting versions whose markers both apply on Linux. That made the lock uninstallable on Linux, which broke CI andpoetry installfor anyone working from source.b2ad48b) — wandb 0.30 removedRun.get_url(), soWandBLogger.urlraisedAttributeError. It now usesRun.url, which exists across the whole supported range (wandb>=0.22). mypy caught this.API / CLI Changes
BaseModelHarness.get_optimizer()— new; the correctly spelled abstract hook.BaseModelHarness.get_optmizer()— deprecated; still works and emits aDeprecationWarning.maketargets:install,lock,test,test-cov,lint,format,type-check,docs,clean.Breaking Changes
No Python API breaks. Changes to the development workflow and environments:
uv syncreplacespoetry installanduv runreplacespoetry run.poetry.lockis replaced byuv.lock.>=2.13.0and torchvision0.28.x, up from 2.9 / 0.24.Security & Privacy
nltkGHSA-8mgp-746c-j5xp (high), has no published fix: 3.10.3 is the latest release and is still affected. nltk comes in transitively viaevidently, and Apeiron never calls it directly. It should be dismissed as "no fix available" once this merges.SECURITY.mdwith a private reporting path.Dependencies
torch2.9.1 → 2.13.0,torchvision0.24.1 → 0.28.0,transformers5.8.1 → 5.17.0,mlflow3.12.0 → 3.16.1,wandb0.23.0 → 0.30.0, plus transitive upgrades (aiohttp,pillow,cryptography,gitpython,starlette,nltk, …).black(unused; formatting isruff format).poetry-core→uv_build. The built wheel ships the same files as before.Testing Plan
Docker-test).uv lock --check, ruff lint and format, mypy (0 issues), andmake docswith warnings as errors all pass.examplesjob (MNIST and CIFAR training runs) only runs on manual dispatch and hasn't been run on this branch. It's the best end-to-end check of the torch 2.9 → 2.13 upgrade, so it's worth triggering before merge.Documentation
AI / LLM Assistance
Checklist
ruff format --checkruff check .mypy .