refactor(core): add initial backend and sample contracts

Author: ErjieWu

deepks/core/contracts/__init__.py

@@ -1 +1,6 @@
-"""Scaffold package for refactor architecture."""
+"""Core contracts for ML/physics backends and sample schemas."""
+
+from .backends import ModelBackend, PhysicsBackend
+from .sample_schema import SampleSchema
+
+__all__ = ["ModelBackend", "PhysicsBackend", "SampleSchema"]

deepks/core/contracts/backends.py

@@ -0,0 +1,35 @@
+"""Abstract backend contracts used by orchestration and pipelines.
+
+These interfaces provide a stable boundary between orchestration logic and
+concrete ML/physics implementations during incremental refactoring.
+"""
+
+from abc import ABC, abstractmethod
+
+
+class ModelBackend(ABC):
+    """Contract for ML model training/inference backends."""
+
+    @abstractmethod
+    def train(self, **kwargs):
+        """Run model training with keyword-only configuration."""
+
+    @abstractmethod
+    def evaluate(self, **kwargs):
+        """Run model evaluation and return backend-specific metrics."""
+
+    @abstractmethod
+    def predict(self, **kwargs):
+        """Run model inference for a prepared input batch."""
+
+
+class PhysicsBackend(ABC):
+    """Contract for physics/SCF backends."""
+
+    @abstractmethod
+    def run_scf(self, **kwargs):
+        """Run SCF calculation and return backend-specific outputs."""
+
+    @abstractmethod
+    def collect_stats(self, **kwargs):
+        """Collect summary statistics from generated SCF results."""

deepks/core/contracts/sample_schema.py

@@ -0,0 +1,23 @@
+"""Shared sample schema metadata for cross-layer data contracts."""
+
+from dataclasses import dataclass
+from typing import Tuple
+
+
+@dataclass(frozen=True)
+class SampleSchema:
+    """Canonical key names and shape hints for model samples."""
+
+    energy_key: str = "lb_e"
+    descriptor_key: str = "eig"
+    force_key: str = "lb_f"
+    stress_key: str = "lb_s"
+    orbital_key: str = "lb_o"
+    hamiltonian_k_key: str = "lb_vd"
+    hamiltonian_r_key: str = "lb_vdr"
+
+    # Shape conventions are informational and used for schema checks.
+    energy_shape: Tuple[str, ...] = ("nframe", "1")
+    descriptor_shape: Tuple[str, ...] = ("nframe", "natom", "ndesc")
+    force_shape: Tuple[str, ...] = ("nframe", "natom", "3")
+    stress_shape: Tuple[str, ...] = ("nframe", "6")