torch-deepaudioembedding 0.1.0__py3-none-any.whl

torch_dae/__init__.py

@@ -0,0 +1,10 @@
+"""Root control-plane package for torch-dae.
+
+repository foundation exposes contracts and registry helpers without importing PyTorch.
+"""
+
+from torch_dae.core.registry import ModelCardRegistry
+
+__all__ = ["ModelCardRegistry", "__version__"]
+
+__version__ = "0.1.0"

torch_dae/cards/__init__.py

@@ -0,0 +1,59 @@
+"""Stable, model-agnostic model-card contract namespace."""
+
+from torch_dae.cards.models import (
+    BooleanCapability,
+    CapabilitiesSection,
+    DatasetRecord,
+    Datasets,
+    Description,
+    DeviceSupport,
+    EmbeddingsSection,
+    EvidenceRecord,
+    EvidenceStatus,
+    Identity,
+    IssueRecord,
+    IssueStatus,
+    MetricRecord,
+    ModelCard,
+    ModelCardLifecycle,
+    OutputComponent,
+    Outputs,
+    ProfilingSection,
+    ProfilingStatus,
+    RecommendedEnvironment,
+    ScientificReference,
+    SourceRecord,
+    Sources,
+    Tasks,
+    Usage,
+    WaveformInput,
+)
+
+__all__ = [
+    "BooleanCapability",
+    "CapabilitiesSection",
+    "DatasetRecord",
+    "Datasets",
+    "Description",
+    "DeviceSupport",
+    "EmbeddingsSection",
+    "EvidenceRecord",
+    "EvidenceStatus",
+    "Identity",
+    "IssueRecord",
+    "IssueStatus",
+    "MetricRecord",
+    "ModelCard",
+    "ModelCardLifecycle",
+    "OutputComponent",
+    "Outputs",
+    "ProfilingSection",
+    "ProfilingStatus",
+    "RecommendedEnvironment",
+    "ScientificReference",
+    "SourceRecord",
+    "Sources",
+    "Tasks",
+    "Usage",
+    "WaveformInput",
+]

torch_dae/cards/models.py

@@ -0,0 +1,471 @@
+"""Strict model-card contracts for repository foundation."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Annotated, Literal
+
+from pydantic import Field, HttpUrl, field_validator, model_validator
+
+from torch_dae.contracts import (
+    GIT_REVISION_PATTERN,
+    REPO_RELATIVE_PATTERN,
+    CanonicalId,
+    StrictBaseModel,
+    ensure_repository_relative,
+    ensure_wrapper_entry_point,
+)
+from torch_dae.core.checkpoint import CheckpointSpec
+from torch_dae.core.embeddings import EmbeddingSpec
+
+
+class ModelCardLifecycle(StrEnum):
+    """Lifecycle states defined by project_spec.md."""
+
+    DRAFT = "draft"
+    ANALYZED = "analyzed"
+    ENVIRONMENT_RESOLVED = "environment_resolved"
+    CHECKPOINT_VERIFIED = "checkpoint_verified"
+    RUNTIME_VERIFIED = "runtime_verified"
+    PROFILED = "profiled"
+
+
+class EvidenceStatus(StrEnum):
+    """Evidence provenance status."""
+
+    OFFICIALLY_REPORTED = "officially_reported"
+    OBSERVED = "observed"
+    INFERRED = "inferred"
+    UNRESOLVED = "unresolved"
+    NOT_REPORTED = "not_reported"
+    NOT_APPLICABLE = "not_applicable"
+
+
+class IssueStatus(StrEnum):
+    """Issue lifecycle state."""
+
+    OPEN = "open"
+    RESOLVED = "resolved"
+    ACCEPTED = "accepted"
+    NOT_APPLICABLE = "not_applicable"
+
+
+class ProfilingStatus(StrEnum):
+    """Profiling status reserved for later phases."""
+
+    NOT_PROFILED = "not_profiled"
+    PROFILED = "profiled"
+
+
+class EvidenceRecord(StrictBaseModel):
+    """Concise evidence record for a material claim."""
+
+    evidence_id: CanonicalId
+    kind: str
+    status: EvidenceStatus
+    url: HttpUrl | None = None
+    revision: Annotated[str | None, Field(pattern=GIT_REVISION_PATTERN)] = None
+    path: str | None = None
+    symbol: str | None = None
+    description: str
+    rationale: str | None = None
+
+    @model_validator(mode="after")
+    def inferred_requires_rationale(self) -> EvidenceRecord:
+        if self.status == EvidenceStatus.INFERRED and not self.rationale:
+            raise ValueError("inferred evidence requires rationale")
+        return self
+
+    @field_validator("path")
+    @classmethod
+    def path_repository_relative(cls, value: str | None) -> str | None:
+        return ensure_repository_relative(value)
+
+
+class IssueRecord(StrictBaseModel):
+    """Explicit issue record; lifecycle state is not used for every problem."""
+
+    issue_id: CanonicalId
+    kind: str
+    status: IssueStatus
+    description: str
+    impact: str
+
+
+class Identity(StrictBaseModel):
+    """Checkpoint-specific card identity."""
+
+    model_name: str
+    model_family: str
+    variant: str
+    checkpoint_name: str
+    framework: Literal["pytorch"]
+    wrapper_entry_point: Annotated[
+        str,
+        Field(pattern=r"^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*:[A-Z][A-Za-z0-9_]*$"),
+    ]
+
+    @field_validator("wrapper_entry_point")
+    @classmethod
+    def validate_entry_point(cls, value: str) -> str:
+        return ensure_wrapper_entry_point(value)
+
+
+class SourceRecord(StrictBaseModel):
+    """Repository, package, or asset source evidence."""
+
+    source_id: CanonicalId
+    kind: str
+    url: HttpUrl | None = None
+    package: str | None = None
+    revision: Annotated[str | None, Field(pattern=GIT_REVISION_PATTERN)] = None
+    path: Annotated[str | None, Field(pattern=REPO_RELATIVE_PATTERN)] = None
+    evidence_status: EvidenceStatus
+
+    @field_validator("path")
+    @classmethod
+    def path_repository_relative(cls, value: str | None) -> str | None:
+        return ensure_repository_relative(value)
+
+
+class Sources(StrictBaseModel):
+    """Required source roles."""
+
+    official_repository: SourceRecord
+    implementation: SourceRecord
+    checkpoint: SourceRecord
+    wrapper: SourceRecord
+
+
+class ScientificReference(StrictBaseModel):
+    """Publication metadata."""
+
+    title: str
+    doi: str | None = None
+    official_publication: HttpUrl | None = None
+    authors: tuple[str, ...]
+    year: int | None = Field(default=None, ge=1900, le=2100)
+
+
+class Description(StrictBaseModel):
+    """Separated descriptive claims."""
+
+    architecture: str
+    preprocessing: str
+    training_objective: str
+    checkpoint_behavior: str
+    implementation: str
+
+
+class Tasks(StrictBaseModel):
+    """Task roles separated by phase."""
+
+    pretraining: tuple[str, ...]
+    finetuning: tuple[str, ...]
+    official_evaluation: tuple[str, ...]
+    supported_inference: tuple[str, ...]
+
+
+class DatasetRecord(StrictBaseModel):
+    """Dataset usage record."""
+
+    name: str
+    version: str | None = None
+    subset: str | None = None
+    split: str | None = None
+    role: str
+    source_status: EvidenceStatus
+    evidence_ids: tuple[str, ...] = ()
+
+
+class Datasets(StrictBaseModel):
+    """Training, validation, and testing dataset partitions."""
+
+    training: tuple[DatasetRecord, ...]
+    validation: tuple[DatasetRecord, ...]
+    testing: tuple[DatasetRecord, ...]
+
+
+class MetricRecord(StrictBaseModel):
+    """Reported metric record."""
+
+    task: str
+    dataset: str
+    split: str
+    metric: str
+    value: float | str | None
+    unit: str | None = None
+    protocol: str
+    checkpoint_specific: bool
+    source_status: EvidenceStatus
+    evidence_ids: tuple[str, ...] = ()
+
+
+class RecommendedEnvironment(StrictBaseModel):
+    """Reference to committed environment artifacts."""
+
+    environment_id: CanonicalId
+    specification: Annotated[str, Field(pattern=REPO_RELATIVE_PATTERN)]
+    lockfile: Annotated[str, Field(pattern=REPO_RELATIVE_PATTERN)]
+    verified: bool
+
+    @field_validator("specification", "lockfile")
+    @classmethod
+    def paths_repository_relative(cls, value: str) -> str:
+        return ensure_repository_relative(value) or value
+
+
+class Usage(StrictBaseModel):
+    """Usage references and commands."""
+
+    recommended_environment: RecommendedEnvironment
+    installation_commands: tuple[str, ...]
+    checkpoint_loading: tuple[str, ...]
+    smoke_test_command: str
+
+
+class WaveformInput(StrictBaseModel):
+    """Canonical public waveform input contract."""
+
+    shape: Literal["B,C,T"]
+    sample_rate_hz: int = Field(gt=0)
+    dtype: str = "float32"
+    valid_lengths_shape: Literal["B"] | None = "B"
+    channels: str
+    resampling: str
+    padding: str
+    normalization: str
+
+
+class OutputComponent(StrictBaseModel):
+    """Stable output component description."""
+
+    name: str
+    kind: str
+    semantic_kind: str
+    rank: int = Field(ge=0)
+    layout: str
+    dimensions: tuple[str, ...]
+    dtype: str | None = None
+    granularity: str | None = None
+    task_head_relation: str | None = None
+
+    @model_validator(mode="after")
+    def rank_matches_dimensions(self) -> OutputComponent:
+        if len(self.dimensions) != self.rank:
+            raise ValueError("output component rank must match dimensions length")
+        return self
+
+
+class Outputs(StrictBaseModel):
+    """Forward and probability output declarations."""
+
+    primary: OutputComponent
+    components: tuple[OutputComponent, ...]
+    probability_output: OutputComponent | None = None
+
+
+class EmbeddingsSection(StrictBaseModel):
+    """Embedding declarations with one selected default."""
+
+    default_embedding_id: CanonicalId
+    items: tuple[EmbeddingSpec, ...]
+
+    @model_validator(mode="after")
+    def validate_default(self) -> EmbeddingsSection:
+        ids = [item.embedding_id for item in self.items]
+        if len(ids) != len(set(ids)):
+            raise ValueError("embedding IDs must be unique")
+        defaults = [item for item in self.items if item.default]
+        if len(defaults) != 1:
+            raise ValueError("exactly one embedding must be marked default")
+        if self.default_embedding_id != defaults[0].embedding_id:
+            raise ValueError("default_embedding_id must refer to the declared default embedding")
+        if self.default_embedding_id not in {item.embedding_id for item in self.items}:
+            raise ValueError("default_embedding_id must refer to a declared embedding")
+        return self
+
+
+class BooleanCapability(StrictBaseModel):
+    """Capability support plus optional reason."""
+
+    supported: bool
+    reason: str | None = None
+
+    @model_validator(mode="after")
+    def reason_for_unsupported(self) -> BooleanCapability:
+        if not self.supported and not self.reason:
+            raise ValueError("unsupported capabilities require a reason")
+        return self
+
+
+class CapabilitiesSection(StrictBaseModel):
+    """Model-independent capability declarations."""
+
+    random_initialization: BooleanCapability
+    checkpoint_loading: BooleanCapability
+    probabilities: BooleanCapability
+    embeddings: BooleanCapability
+
+
+class DeviceSupport(StrictBaseModel):
+    """Declared and observed device support."""
+
+    upstream_declared: tuple[str, ...]
+    locally_tested: tuple[str, ...]
+    known_limitations: tuple[str, ...]
+
+
+class ProfilingSection(StrictBaseModel):
+    """Profiling placeholder or completed profiling reference."""
+
+    status: ProfilingStatus
+    report: Annotated[str | None, Field(pattern=REPO_RELATIVE_PATTERN)] = None
+
+    @field_validator("report")
+    @classmethod
+    def report_repository_relative(cls, value: str | None) -> str | None:
+        return ensure_repository_relative(value)
+
+    @model_validator(mode="after")
+    def profiled_requires_report(self) -> ProfilingSection:
+        if self.status == ProfilingStatus.PROFILED and self.report is None:
+            raise ValueError("profiled sections require a report reference")
+        return self
+
+
+class ModelCard(StrictBaseModel):
+    """Validate the complete metadata for one checkpoint-specific integration.
+
+    A card represents exactly one model-family, variant, and checkpoint tuple. Validation enforces
+    lifecycle prerequisites, unique evidence identifiers, resolved evidence references, consistent
+    capabilities, repository-relative artifact paths, and the canonical waveform/output contracts.
+
+    Attributes
+    ----------
+    card_id
+        Stable canonical identifier for this exact integration tuple.
+    card_status
+        Current lifecycle state. Later states require verified environment, checkpoint, runtime,
+        and profiling evidence as applicable.
+    identity
+        Model, variant, checkpoint, framework, and public wrapper identity.
+    input
+        Canonical waveform contract using ``[B,C,T]``, sample rate in hertz, and optional ``[B]``
+        valid lengths.
+    embeddings
+        Declared embedding tensors, including exactly one default when embeddings are supported.
+    evidence
+        Provenance records supporting material scientific and technical claims.
+
+    Raises
+    ------
+    pydantic.ValidationError
+        If any field or cross-document lifecycle constraint is invalid.
+
+    Notes
+    -----
+    License fields are informational. Constructing a card never imports a model runtime, downloads
+    a checkpoint, or materializes an environment.
+    """
+
+    schema_version: Literal["1.0.0"]
+    card_id: CanonicalId
+    card_status: ModelCardLifecycle
+    identity: Identity
+    checkpoint: CheckpointSpec
+    sources: Sources
+    scientific_reference: ScientificReference
+    description: Description
+    tasks: Tasks
+    datasets: Datasets
+    reported_metrics: tuple[MetricRecord, ...]
+    usage: Usage
+    input: WaveformInput
+    outputs: Outputs
+    embeddings: EmbeddingsSection
+    capabilities: CapabilitiesSection
+    device_support: DeviceSupport
+    verification_report: Annotated[str | None, Field(pattern=REPO_RELATIVE_PATTERN)] = None
+    architectural_profiling: ProfilingSection
+    inference_profiling: ProfilingSection
+    energy_profiling: ProfilingSection
+    limitations: tuple[str, ...]
+    issues: tuple[IssueRecord, ...]
+    evidence: tuple[EvidenceRecord, ...]
+
+    @field_validator("verification_report")
+    @classmethod
+    def verification_report_repository_relative(cls, value: str | None) -> str | None:
+        return ensure_repository_relative(value)
+
+    @model_validator(mode="after")
+    def validate_lifecycle(self) -> ModelCard:
+        if (
+            self.card_status
+            in {
+                ModelCardLifecycle.ENVIRONMENT_RESOLVED,
+                ModelCardLifecycle.CHECKPOINT_VERIFIED,
+                ModelCardLifecycle.RUNTIME_VERIFIED,
+                ModelCardLifecycle.PROFILED,
+            }
+            and not self.usage.recommended_environment.verified
+        ):
+            raise ValueError("environment_resolved or later cards require verified environment")
+        if (
+            self.card_status
+            in {
+                ModelCardLifecycle.CHECKPOINT_VERIFIED,
+                ModelCardLifecycle.RUNTIME_VERIFIED,
+                ModelCardLifecycle.PROFILED,
+            }
+            and self.checkpoint.observed_sha256 is None
+        ):
+            raise ValueError(
+                "checkpoint_verified or later cards require observed checkpoint SHA-256"
+            )
+        if (
+            self.card_status
+            in {
+                ModelCardLifecycle.RUNTIME_VERIFIED,
+                ModelCardLifecycle.PROFILED,
+            }
+            and self.verification_report is None
+        ):
+            raise ValueError("runtime_verified and profiled cards require verification_report")
+        if self.card_status == ModelCardLifecycle.PROFILED:
+            for section in (
+                self.architectural_profiling,
+                self.inference_profiling,
+                self.energy_profiling,
+            ):
+                if section.status != ProfilingStatus.PROFILED:
+                    raise ValueError(
+                        "profiled cards require all profiling sections marked profiled"
+                    )
+        return self
+
+    @model_validator(mode="after")
+    def validate_capabilities_and_evidence(self) -> ModelCard:
+        if self.capabilities.probabilities.supported != (
+            self.outputs.probability_output is not None
+        ):
+            raise ValueError("probability capability must agree with probability output")
+        if self.capabilities.embeddings.supported != bool(self.embeddings.items):
+            raise ValueError("embedding capability must agree with embedding declarations")
+
+        evidence_ids = [item.evidence_id for item in self.evidence]
+        if len(evidence_ids) != len(set(evidence_ids)):
+            raise ValueError("evidence IDs must be unique")
+        declared = set(evidence_ids)
+        references: list[str] = []
+        for dataset in self.datasets.training + self.datasets.validation + self.datasets.testing:
+            references.extend(dataset.evidence_ids)
+        for metric in self.reported_metrics:
+            references.extend(metric.evidence_ids)
+        for embedding in self.embeddings.items:
+            references.extend(embedding.evidence_ids)
+        missing = sorted(set(references) - declared)
+        if missing:
+            raise ValueError(f"evidence references are unresolved: {missing}")
+        return self

torch_dae/cards/validation.py

@@ -0,0 +1,77 @@
+"""Dual Pydantic and JSON Schema validation for model cards."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from jsonschema import Draft202012Validator, FormatChecker
+from jsonschema.exceptions import ValidationError as JsonSchemaValidationError
+from pydantic import ValidationError as PydanticValidationError
+
+from torch_dae.cards.models import ModelCard
+
+
+def load_json(path: Path) -> dict[str, Any]:
+    """Load a JSON object from disk."""
+
+    value = json.loads(path.read_text())
+    if not isinstance(value, dict):
+        raise ValueError(f"{path} did not contain a JSON object")
+    return value
+
+
+def validate_model_card_pydantic(data: dict[str, Any]) -> ModelCard:
+    """Validate a card through Pydantic."""
+
+    return ModelCard.model_validate(data)
+
+
+def validate_model_card_schema(data: dict[str, Any], schema_path: Path) -> None:
+    """Validate a card through JSON Schema with format checking."""
+
+    schema = load_json(schema_path)
+    Draft202012Validator(schema, format_checker=FormatChecker()).validate(data)
+
+
+def assert_valid_pydantic(data: dict[str, Any]) -> ModelCard:
+    """Assert that Pydantic accepts a model card."""
+
+    return validate_model_card_pydantic(data)
+
+
+def assert_invalid_pydantic(data: dict[str, Any]) -> None:
+    """Assert that Pydantic rejects a model card."""
+
+    try:
+        validate_model_card_pydantic(data)
+    except PydanticValidationError:
+        return
+    raise AssertionError("expected Pydantic validation to fail")
+
+
+def assert_valid_json_schema(data: dict[str, Any], schema_path: Path) -> None:
+    """Assert that JSON Schema accepts a model card."""
+
+    validate_model_card_schema(data, schema_path)
+
+
+def assert_invalid_json_schema(data: dict[str, Any], schema_path: Path) -> None:
+    """Assert that JSON Schema rejects a model card."""
+
+    try:
+        validate_model_card_schema(data, schema_path)
+    except JsonSchemaValidationError:
+        return
+    raise AssertionError("expected JSON Schema validation to fail")
+
+
+def validate_model_card_path(path: Path, schema_path: Path | None = None) -> ModelCard:
+    """Validate a model-card file through both validators when a schema is available."""
+
+    data = load_json(path)
+    card = validate_model_card_pydantic(data)
+    if schema_path is not None:
+        validate_model_card_schema(data, schema_path)
+    return card

torch_dae/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package."""

torch_dae/cli/cards.py

@@ -0,0 +1,45 @@
+"""Model-card CLI commands."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from torch_dae.cards.validation import validate_model_card_path
+from torch_dae.core.registry import ModelCardRegistry
+from torch_dae.environment.manager import discover_repository_root
+
+app = typer.Typer(no_args_is_help=True, help="Model-card commands.")
+
+
+@app.command("list")
+def list_cards() -> None:
+    """List discovered model cards."""
+
+    registry = ModelCardRegistry(discover_repository_root())
+    for card in registry.list_cards():
+        typer.echo(card.card_id)
+
+
+@app.command("show")
+def show(card_id: str) -> None:
+    """Show a model card as normalized JSON."""
+
+    registry = ModelCardRegistry(discover_repository_root())
+    typer.echo(registry.get_card(card_id).model_dump_json(indent=2))
+
+
+@app.command("validate")
+def validate(card_id_or_path: str) -> None:
+    """Validate a card id or JSON path."""
+
+    root = discover_repository_root()
+    candidate = Path(card_id_or_path)
+    if candidate.exists():
+        path = candidate
+    else:
+        registry = ModelCardRegistry(root)
+        path = registry.get_card_path(card_id_or_path)
+    validate_model_card_path(path, root / "schemas/model-card.schema.json")
+    typer.echo(f"valid: {path}")