altar-cherimoya 0.1.0__tar.gz

altar_cherimoya-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+*.pyc
+*~
+**/__pycache__/*
+*.swp
+.vscode/
+.idea/
+.DS_Store
+.env*
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+coverage.xml
+pytest.xml
+.hypothesis/
+.python-version
+.venv/
+.venv-*/
+*.egg-info/
+build/
+dist/
+site/
+*.sqlite3
+*.log
+
+# Generated variant indexes and datasets. The small canonical gene table is tracked.
+altar/altar/variants/data/ccres.dnatree
+altar/altar/variants/data/region_annotations.parquet
+altar/altar/variants/data/variants.pkl.gz
+altar/altar/variants/data/raw/
+

altar_cherimoya-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Riya Sinha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

altar_cherimoya-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.5
+Name: altar-cherimoya
+Version: 0.1.0
+Summary: Cherimoya model binding for Altar
+Project-URL: Documentation, https://kundajelab.github.io/altar/
+Project-URL: Issues, https://github.com/kundajelab/altar/issues
+Project-URL: Repository, https://github.com/kundajelab/altar
+Author: Riya Sinha
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: altar<0.2,>=0.1
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Altar Cherimoya binding
+
+`altar-cherimoya` is the lightweight control-plane binding between Altar and the Cherimoya variant-effect
+runtime. Installing it registers `CHERIMOYA` in the canonical `altar.model_plugins` discovery group.
+
+The binding owns Cherimoya's artifact schema, score schema, prioritization predicate, resource requests, and
+backend-neutral container plan. It does not import PyTorch, Cherimoya, a model registry, object-storage SDK,
+or compute-provider SDK. The heavyweight `cherimoya-score` CLI and independently locked image live under
+`runtimes/cherimoya` in this repository.
+
+```bash
+pip install altar-cherimoya
+```
+
+```python
+from altar.models import get_model_plugin
+
+plugin = get_model_plugin("CHERIMOYA")
+```
+
+`CherimoyaConfiguration.image` defaults to the immutable runtime digest tested with the installed binding.
+Callers may override it with another `name@sha256:<digest>` image reference; mutable tags remain invalid. Its
+`weights` tuple contains one generic `ResourceReference` per fold, each with a required SHA-256 digest. The
+URI may be local, HTTPS, GCS, S3, Hugging Face, or any other location understood by the selected storage
+adapter. The digest, not the location, defines scientific identity. Mutable images and unidentified weight
+bytes fail validation before a plan can be built.
+
+The binding emits one GPU scoring task per weight resource followed by one CPU summarize task. Every weight
+is staged to a stable logical path, and the runtime receives only that mounted path and expected digest. It
+does not download weights or know which provider stored them.
+
+The runtime streams large variant files in fixed outer batches and validates CATv1's single-track output
+contract. `profile_l1` is defined over softmax-normalized profile distributions.
+
+The tests compose `altar.testing.ModelResultContract` and `ContainerScorerContract` and fake only the outer
+Modal and Kubernetes clients, so they verify both result semantics and the plan/fan-in contract without an
+ML framework, cloud account, cluster, GPU, or image pull.

altar_cherimoya-0.1.0/README.md

@@ -0,0 +1,37 @@
+# Altar Cherimoya binding
+
+`altar-cherimoya` is the lightweight control-plane binding between Altar and the Cherimoya variant-effect
+runtime. Installing it registers `CHERIMOYA` in the canonical `altar.model_plugins` discovery group.
+
+The binding owns Cherimoya's artifact schema, score schema, prioritization predicate, resource requests, and
+backend-neutral container plan. It does not import PyTorch, Cherimoya, a model registry, object-storage SDK,
+or compute-provider SDK. The heavyweight `cherimoya-score` CLI and independently locked image live under
+`runtimes/cherimoya` in this repository.
+
+```bash
+pip install altar-cherimoya
+```
+
+```python
+from altar.models import get_model_plugin
+
+plugin = get_model_plugin("CHERIMOYA")
+```
+
+`CherimoyaConfiguration.image` defaults to the immutable runtime digest tested with the installed binding.
+Callers may override it with another `name@sha256:<digest>` image reference; mutable tags remain invalid. Its
+`weights` tuple contains one generic `ResourceReference` per fold, each with a required SHA-256 digest. The
+URI may be local, HTTPS, GCS, S3, Hugging Face, or any other location understood by the selected storage
+adapter. The digest, not the location, defines scientific identity. Mutable images and unidentified weight
+bytes fail validation before a plan can be built.
+
+The binding emits one GPU scoring task per weight resource followed by one CPU summarize task. Every weight
+is staged to a stable logical path, and the runtime receives only that mounted path and expected digest. It
+does not download weights or know which provider stored them.
+
+The runtime streams large variant files in fixed outer batches and validates CATv1's single-track output
+contract. `profile_l1` is defined over softmax-normalized profile distributions.
+
+The tests compose `altar.testing.ModelResultContract` and `ContainerScorerContract` and fake only the outer
+Modal and Kubernetes clients, so they verify both result semantics and the plan/fan-in contract without an
+ML framework, cloud account, cluster, GPU, or image pull.

altar_cherimoya-0.1.0/altar_cherimoya/__init__.py

@@ -0,0 +1,26 @@
+"""Cherimoya model binding for Altar."""
+
+from altar_cherimoya.plugin import (
+    DEFAULT_IMAGE,
+    DEFAULT_IN_WINDOW,
+    KIND_SCORING_FOLDS,
+    KIND_SCORING_SUMMARIZE,
+    CherimoyaArtifact,
+    CherimoyaConfiguration,
+    CherimoyaPlugin,
+    CherimoyaRunInputs,
+    CherimoyaShardKind,
+)
+
+
+__all__ = [
+    "DEFAULT_IMAGE",
+    "DEFAULT_IN_WINDOW",
+    "KIND_SCORING_FOLDS",
+    "KIND_SCORING_SUMMARIZE",
+    "CherimoyaArtifact",
+    "CherimoyaConfiguration",
+    "CherimoyaPlugin",
+    "CherimoyaRunInputs",
+    "CherimoyaShardKind",
+]

altar_cherimoya-0.1.0/altar_cherimoya/plugin.py

@@ -0,0 +1,317 @@
+"""Backend-neutral Altar binding for Cherimoya variant scoring.
+
+The plugin is deliberately a control-plane adapter. It validates typed model configuration and emits a
+``ContainerScoringPlan`` containing one GPU task per fold plus a CPU reduction task. The same plan runs
+through the local, Modal, or Kubernetes execution backend; the plugin never imports an ML framework or a
+provider SDK.
+
+The corresponding ``cherimoya-score`` runtime and image definition live under ``runtimes/cherimoya`` in
+the same repository. Keeping that data-plane implementation out of both ``altar`` and this binding lets the
+kernel and adapter remain lightweight while model images use independent Python versions and dependency
+locks.
+"""
+
+from __future__ import annotations
+import enum
+from typing import TYPE_CHECKING, Literal, cast
+
+from altar.execution import ContainerTaskSpec, GpuPool, ResourceRequest, Transfer
+from altar.models import (
+    ApiVersionRange,
+    ConfigurationModel,
+    ConfigurationVersionError,
+    ContainerImageDigest,
+    ContainerScoringPlan,
+    LegacyArtifactError,
+    LegacyScoringConversion,
+    ModelConfiguration,
+    ModelPlugin,
+    OutputSelection,
+    PluginCapability,
+    PluginKind,
+    PluginManifest,
+    PrioritizationPolicy,
+    ReferenceGenomeRunInputs,
+    ResourceReference,
+    ResultField,
+    ResultSchema,
+    RuntimeIdentityPolicy,
+    RuntimeKind,
+    RuntimeRequirement,
+    ScoringRequest,
+    require_resource_digests,
+    resource_transfer,
+)
+from altar.predicates import Abs, Col, Ge, Lit, Predicate
+from pydantic import Field, ValidationError, model_validator
+
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+
+DEFAULT_IN_WINDOW = 2114
+DEFAULT_IMAGE = "riyavsinha/altar-cherimoya@sha256:565117e3e34af57aa0f5ec851045450f7015b4b58c8b8a4a019a092c775790cc"
+
+_LOG2FC_PRIORITIZE_THRESHOLD = 0.25
+_VARIANT_BATCH_SIZE = 4096
+_MODEL_BATCH_SIZE = 64
+
+
+class CherimoyaShardKind(enum.StrEnum):
+    """Stable task kinds emitted by :class:`CherimoyaPlugin`."""
+
+    SCORING_FOLDS = "cherimoya_scoring_folds"
+    SCORING_SUMMARIZE = "cherimoya_scoring_summarize"
+
+
+KIND_SCORING_FOLDS = CherimoyaShardKind.SCORING_FOLDS
+KIND_SCORING_SUMMARIZE = CherimoyaShardKind.SCORING_SUMMARIZE
+
+_SCORE_RESOURCES = ResourceRequest(gpu=GpuPool.NORMAL_GPU, count=1, memory_gb=32)
+_SUMMARIZE_RESOURCES = ResourceRequest(memory_gb=8)
+
+
+class CherimoyaConfiguration(ModelConfiguration):
+    """Durable model resources and scientific settings for Cherimoya.
+
+    ``image`` defaults to the immutable runtime tested with this binding release. Callers may override it
+    with another digest-pinned image built from ``runtimes/cherimoya``. ``weights`` contains one
+    provider-neutral, content-addressed resource per fold; its length is the fold count. Storage adapters
+    may retrieve those bytes from any location they support.
+    """
+
+    weights: tuple[ResourceReference, ...] = Field(min_length=1)
+    in_window: int = Field(default=DEFAULT_IN_WINDOW, gt=0)
+    image: ContainerImageDigest = DEFAULT_IMAGE
+
+    @model_validator(mode="after")
+    def require_content_addressed_weights(self) -> CherimoyaConfiguration:
+        require_resource_digests(self, owner="Cherimoya")
+        return self
+
+
+class CherimoyaRunInputs(ReferenceGenomeRunInputs):
+    """Typed biological inputs restricted to CATv1's training assembly."""
+
+    @model_validator(mode="after")
+    def require_hg38(self) -> CherimoyaRunInputs:
+        if self.genome_build != "hg38":
+            msg = f"Cherimoya scoring currently requires genome_build='hg38', got {self.genome_build!r}"
+            raise ValueError(msg)
+        return self
+
+
+class CherimoyaArtifact(ConfigurationModel):
+    """Strict generic artifact mapping accepted by the legacy conversion entry point."""
+
+    mode: Literal["container"] = "container"
+    weights: tuple[ResourceReference, ...] = Field(min_length=1)
+    genome: ResourceReference
+    in_window: int = Field(default=DEFAULT_IN_WINDOW, gt=0)
+    image: ContainerImageDigest = DEFAULT_IMAGE
+
+    @model_validator(mode="after")
+    def require_content_addressed_resources(self) -> CherimoyaArtifact:
+        require_resource_digests(self, owner="Cherimoya")
+        return self
+
+
+class CherimoyaPlugin(ModelPlugin):
+    """Cherimoya results contract and backend-neutral container plan builder."""
+
+    model_type = "CHERIMOYA"
+    manifest = PluginManifest(
+        plugin_id="org.kundajelab.altar.model.cherimoya",
+        kind=PluginKind.MODEL,
+        capabilities=frozenset({PluginCapability.SCORE, PluginCapability.MATERIALIZE_RESULTS}),
+        architecture="Cherimoya",
+        plugin_version="0.0.1",
+        altar_api=ApiVersionRange("0.1.0", "0.2.0"),
+        configuration_schema_version="0.0.1",
+        result_schema=ResultSchema(
+            version="0.0.1",
+            fields=(
+                ResultField(
+                    "counts_log2fc",
+                    "float",
+                    "Counts Log2FC",
+                    "Alternate-minus-reference log2 effect on the single-track log(count + 1) head",
+                ),
+                ResultField(
+                    "profile_l1",
+                    "float",
+                    "Profile L1",
+                    "L1 distance between alternate and reference softmax-normalized profile distributions",
+                ),
+            ),
+        ),
+        prioritization=PrioritizationPolicy(name="cherimoya-counts-effect-v1", version="0.0.1"),
+        runtimes=(
+            RuntimeRequirement(
+                name="model_runtime",
+                kind=RuntimeKind.CONTAINER_IMAGE,
+                policy=RuntimeIdentityPolicy.DIGEST_REQUIRED,
+            ),
+        ),
+    )
+    configuration_schema_id = "org.kundajelab.altar.model.cherimoya.configuration"
+    configuration_model = CherimoyaConfiguration
+    run_input_model = CherimoyaRunInputs
+    default_output = OutputSelection(reducer="mean")
+
+    def _configuration(self, value: ModelConfiguration) -> CherimoyaConfiguration:
+        return cast("CherimoyaConfiguration", self.parse_configuration(value))
+
+    def migrate_configuration(
+        self,
+        from_version: str,
+        configuration: Mapping[str, object],
+    ) -> Mapping[str, object]:
+        """Accept an already generic resource set or reject provider-shaped configurations explicitly."""
+        if from_version not in {"1.0.0", "1.1.0"}:
+            return super().migrate_configuration(from_version, configuration)
+        try:
+            return CherimoyaConfiguration.model_validate(configuration).to_dict()
+        except ValidationError as error:
+            msg = (
+                f"CHERIMOYA configuration {from_version} cannot migrate automatically: replace the "
+                "provider-specific weights object and num_folds with a non-empty weights list containing "
+                "one ResourceReference(uri=..., digest='sha256:...') per fold, then resave with the current schema"
+            )
+            raise ConfigurationVersionError(msg) from error
+
+    def convert_legacy_artifact(
+        self,
+        artifact: Mapping[str, object],
+        *,
+        genome_build: str,
+    ) -> LegacyScoringConversion:
+        """Convert a strict provider-neutral artifact mapping, rejecting every unknown key."""
+        allowed = {"mode", "weights", "genome", "in_window", "image"}
+        unknown = set(artifact) - allowed
+        if unknown:
+            msg = f"unknown Cherimoya legacy artifact fields: {sorted(unknown)}"
+            raise LegacyArtifactError(msg)
+        try:
+            legacy = CherimoyaArtifact.model_validate(dict(artifact))
+        except ValidationError as exc:
+            msg = f"invalid Cherimoya legacy artifact: {exc}"
+            raise LegacyArtifactError(msg) from exc
+        return LegacyScoringConversion(
+            configuration=CherimoyaConfiguration(
+                weights=legacy.weights,
+                in_window=legacy.in_window,
+                image=legacy.image,
+            ),
+            run_inputs=CherimoyaRunInputs(genome_build=genome_build, genome=legacy.genome),
+            output=self.default_output,
+        )
+
+    def build_scoring_plan(self, request: ScoringRequest) -> ContainerScoringPlan:
+        """Build one score task per fold and a CPU task that averages their outputs."""
+        configuration = self._configuration(request.configuration)
+        run_inputs = cast("CherimoyaRunInputs", self.parse_run_inputs(request.run_inputs))
+        output = self.validate_output_selection(request.output)
+        identity = self.scoring_run_identity(
+            {"model_runtime": configuration.image},
+            configuration=configuration,
+            output=output,
+            run_inputs=run_inputs,
+        )
+        num_folds = len(configuration.weights)
+
+        resolver, layout = request.resolver, request.layout
+        job_id, model_id, genome = request.job_id, request.model_id, request.genome_label
+        scoring_batch = request.scoring_batch
+
+        genome_logical = layout.genome_fasta(genome)
+        variants_logical = layout.model_variants_file(job_id, model_id, scoring_batch)
+        batch_labels = {"scoring_batch": str(scoring_batch)} if scoring_batch is not None else {}
+
+        shards: list[ContainerTaskSpec] = []
+        for fold, weights in enumerate(configuration.weights):
+            weights_logical = layout.fold_model_file(model_id, fold, ".torch")
+            output_logical = layout.fold_score_file(job_id, model_id, fold, scoring_batch)
+            command = [
+                "cherimoya-score",
+                "score",
+                "--weights",
+                resolver.resolve(weights_logical),
+                "--weights-digest",
+                cast("str", weights.digest),
+                "--in-window",
+                str(configuration.in_window),
+                "--variant-batch-size",
+                str(_VARIANT_BATCH_SIZE),
+                "--model-batch-size",
+                str(_MODEL_BATCH_SIZE),
+                "-g",
+                resolver.resolve(genome_logical),
+                "--genome-digest",
+                cast("str", run_inputs.genome.digest),
+                "-v",
+                resolver.resolve(variants_logical),
+                "-o",
+                resolver.resolve(output_logical),
+            ]
+            shards.append(
+                ContainerTaskSpec(
+                    kind=KIND_SCORING_FOLDS,
+                    image=configuration.image,
+                    command=command,
+                    labels={
+                        "job_id": job_id,
+                        "model_id": model_id,
+                        "fold": str(fold),
+                        "num_folds": str(num_folds),
+                        "kind": KIND_SCORING_FOLDS,
+                        **batch_labels,
+                    },
+                    resources=_SCORE_RESOURCES,
+                    inputs=[
+                        resource_transfer(weights, weights_logical, locality_key=model_id),
+                        resource_transfer(run_inputs.genome, genome_logical),
+                        Transfer(uri=variants_logical, logical_path=variants_logical, locality_key=model_id),
+                    ],
+                    outputs=[Transfer(uri=output_logical, logical_path=output_logical, locality_key=model_id)],
+                    plugin_identity=identity,
+                )
+            )
+
+        fold_score_logicals = [
+            layout.fold_score_file(job_id, model_id, fold, scoring_batch) for fold in range(num_folds)
+        ]
+        result_logical = layout.scoring_result_file(job_id, model_id, scoring_batch)
+        summarize_command = ["cherimoya-score", "summarize"]
+        for fold, logical in enumerate(fold_score_logicals):
+            summarize_command += [f"-f{fold}", resolver.resolve(logical)]
+        summarize_command += ["-o", resolver.resolve(result_logical)]
+
+        summarize = ContainerTaskSpec(
+            kind=KIND_SCORING_SUMMARIZE,
+            image=configuration.image,
+            command=summarize_command,
+            labels={
+                "job_id": job_id,
+                "model_id": model_id,
+                "kind": KIND_SCORING_SUMMARIZE,
+                **batch_labels,
+            },
+            resources=_SUMMARIZE_RESOURCES,
+            inputs=[
+                Transfer(uri=logical, logical_path=logical, locality_key=model_id) for logical in fold_score_logicals
+            ],
+            outputs=[Transfer(uri=result_logical, logical_path=result_logical, locality_key=model_id)],
+            plugin_identity=identity,
+        )
+        return ContainerScoringPlan(
+            shards=shards,
+            plugin_identity=identity,
+            summarize=summarize,
+            ready_when=num_folds,
+        )
+
+    def prioritize_predicate(self) -> Predicate:
+        # Conservative placeholder, not a calibrated biological threshold.
+        return Ge(Abs(Col("counts_log2fc")), Lit(_LOG2FC_PRIORITIZE_THRESHOLD))