Permea Core is building the open execution layer for delivery engineering. Contributions should help make delivery evidence benchmarkable, reproducible, and reusable.
The project is benchmark-first and evidence-bounded. Good contributions make tasks, data, labels, metrics, outputs, provenance, and limitations easier to inspect.
Useful contributions include:
- dataset cards
- benchmark tasks
- evidence cards
- run manifests
- feature descriptors
- baseline models or baseline configurations
- reproduction reports
- documentation improvements
- source attribution improvements
- claim-boundary review
See docs/CONTRIBUTION_OBJECTS.md for the contribution object model.
Before opening an issue or PR:
- confirm the contribution can be discussed publicly
- identify the source or citation when relevant
- define the task, label, metric, or artifact boundary
- document limitations and uncertainty
- avoid uploading private or restricted row-level data
- avoid uploading secrets, credentials, tokens, or private keys
- use conservative scientific language
If release status is unclear, open a minimal issue describing the question without exposing restricted material.
Do not include:
- private or proprietary data without rights to share it
- private sequences or sensitive candidate rankings
- restricted row-level datasets or row-level predictions without release approval
- credentials, tokens, passwords, private keys, or environment values
- private workflow notes or internal execution context
- private resource or program references
Public contributions should focus on source attribution, reproducibility, benchmark structure, and claim boundaries.
Permea Core does not claim solved delivery, wet-lab validation, clinical or therapeutic effect, universal delivery prediction, state-of-the-art status, or maturity comparable to AlphaFold.
Benchmark claims must remain scoped to:
- dataset
- label policy
- split policy
- metric set
- model or baseline
- evidence level
- provenance state
- release boundary
Use "AlphaFold-for-Delivery" only as an ambition and infrastructure direction, not achieved status.
- Open an issue using the relevant template.
- Maintainers triage the issue for scope, data posture, and claim boundaries.
- Draft the contribution object or implementation.
- Reproducibility, citation, and claim-boundary review happens before acceptance.
- Open a pull request with a narrow scope.
- Maintainers review and merge when the contribution is public-safe and useful.
Use the dataset card issue template.
Include the dataset name, task family, source or citation, sequence type, label definition, positive and negative criteria, assay context, limitations, suggested metrics, and public/private data status.
Do not upload row-level data unless public release rights are clear.
Use the benchmark task issue template.
Include the task name, task family, dataset card link or source reference, input schema, label schema, split policy, baseline models, metrics, output artifacts, and non-claims.
Benchmark tasks should be reproducible and bounded. A useful task definition is clear about what the benchmark does and does not support.
Use the evidence card issue template.
Include the source paper or database, molecule or sequence reference, barrier or task, assay type, cargo context, organism or cell context, reported outcome, evidence strength, limitations, citation, extraction method, and human review status.
Do not strengthen the original source claim. Evidence cards should preserve context and uncertainty.
Use the reproduction report issue template.
Include the benchmark or task, repository commit, environment, command run, output artifacts, observed metrics, expected metrics if known, deviations, logs or excerpts, and reviewer notes.
Reproduction reports may confirm a result, surface drift, or identify missing instructions.
Good first issues should map to a real contribution object. Examples:
- draft a dataset card for a public source
- summarize a benchmark task boundary
- add a feature descriptor explanation
- create an evidence card from a source
- reproduce a documented benchmark run
- improve a guide or docs map
See docs/ISSUE_LABEL_GUIDE.md for the label taxonomy used to distinguish contribution-object scope, review posture, and beginner-safe onramps.
Pull requests should:
- stay scoped to one contribution object or document family
- list changed files
- describe claim-boundary impact
- describe any data or artifact release impact
- include reproduction notes when relevant
- avoid unrelated formatting churn
- avoid adding data unless release status is clear
Documentation should be direct, source-aware, and conservative about claims.
Code or configuration contributions should preserve reproducibility through clear inputs, outputs, versions, and provenance. Prefer simple, reviewable baselines before complex model additions.
Questions about contribution scope can be sent to a.kim@permea.us.