cuvis-ai-schemas 0.1.0__py3-none-any.whl

cuvis_ai_schemas/pipeline/__init__.py

@@ -0,0 +1,17 @@
+"""Pipeline structure schemas."""
+
+from cuvis_ai_schemas.pipeline.config import (
+    ConnectionConfig,
+    NodeConfig,
+    PipelineConfig,
+    PipelineMetadata,
+)
+from cuvis_ai_schemas.pipeline.ports import PortSpec
+
+__all__ = [
+    "PipelineConfig",
+    "PipelineMetadata",
+    "NodeConfig",
+    "ConnectionConfig",
+    "PortSpec",
+]

cuvis_ai_schemas/pipeline/config.py

@@ -0,0 +1,238 @@
+"""Pipeline configuration schemas."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from cuvis_ai_schemas.grpc.v1 import cuvis_ai_pb2
+
+
+class _BaseConfig(BaseModel):
+    """Base model with strict validation."""
+
+    model_config = ConfigDict(extra="forbid", validate_assignment=True, populate_by_name=True)
+
+
+class PipelineMetadata(_BaseConfig):
+    """Pipeline metadata for documentation and discovery.
+
+    Attributes
+    ----------
+    name : str
+        Pipeline name
+    description : str
+        Human-readable description
+    created : str
+        Creation timestamp (ISO format)
+    tags : list[str]
+        Tags for categorization and search
+    author : str
+        Author name or email
+    cuvis_ai_version : str
+        Version of cuvis-ai-schemas used
+    """
+
+    name: str
+    description: str = ""
+    created: str = ""
+    tags: list[str] = Field(default_factory=list)
+    author: str = ""
+    cuvis_ai_version: str = "0.1.0"
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary."""
+        return self.model_dump()
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> PipelineMetadata:
+        """Load from dictionary."""
+        return cls.model_validate(data)
+
+    def to_proto(self) -> cuvis_ai_pb2.PipelineMetadata:
+        """Convert to proto message.
+
+        Requires cuvis-ai-schemas[proto] to be installed.
+
+        Returns
+        -------
+        cuvis_ai_pb2.PipelineMetadata
+            Proto message representation
+        """
+        try:
+            from cuvis_ai_schemas.grpc.v1 import cuvis_ai_pb2
+        except ImportError as exc:
+            msg = "Proto support not installed. Install with: pip install cuvis-ai-schemas[proto]"
+            raise ImportError(msg) from exc
+
+        return cuvis_ai_pb2.PipelineMetadata(
+            name=self.name,
+            description=self.description,
+            created=self.created,
+            tags=list(self.tags),
+            author=self.author,
+            cuvis_ai_version=self.cuvis_ai_version,
+        )
+
+
+class NodeConfig(_BaseConfig):
+    """Node configuration within a pipeline.
+
+    Attributes
+    ----------
+    id : str
+        Unique node identifier
+    class_name : str
+        Fully-qualified class name (e.g., 'my_package.MyNode')
+        Alias: 'class' for backward compatibility
+    params : dict[str, Any]
+        Node parameters/hyperparameters
+        Alias: 'hparams' for backward compatibility
+    """
+
+    id: str = Field(description="Unique node identifier")
+    class_name: str = Field(description="Fully-qualified class name", alias="class")
+    params: dict[str, Any] = Field(
+        default_factory=dict, description="Node parameters", alias="hparams"
+    )
+
+
+class ConnectionConfig(_BaseConfig):
+    """Connection between two nodes.
+
+    Attributes
+    ----------
+    from_node : str
+        Source node ID
+    from_port : str
+        Source port name
+    to_node : str
+        Target node ID
+    to_port : str
+        Target port name
+    """
+
+    from_node: str = Field(description="Source node ID")
+    from_port: str = Field(description="Source port name")
+    to_node: str = Field(description="Target node ID")
+    to_port: str = Field(description="Target port name")
+
+
+class PipelineConfig(_BaseConfig):
+    """Pipeline structure configuration.
+
+    Attributes
+    ----------
+    name : str
+        Pipeline name
+    nodes : list[NodeConfig] | list[dict[str, Any]]
+        Node definitions (can be NodeConfig or dict for flexibility)
+    connections : list[ConnectionConfig] | list[dict[str, Any]]
+        Node connections (can be ConnectionConfig or dict for flexibility)
+    frozen_nodes : list[str]
+        Node IDs to keep frozen during training
+    metadata : PipelineMetadata | None
+        Optional pipeline metadata
+    """
+
+    name: str = Field(default="", description="Pipeline name")
+    nodes: list[dict[str, Any]] = Field(description="Node definitions")
+    connections: list[dict[str, Any]] = Field(description="Node connections")
+    frozen_nodes: list[str] = Field(
+        default_factory=list, description="Node names to keep frozen during training"
+    )
+    metadata: PipelineMetadata | None = Field(
+        default=None, description="Optional pipeline metadata"
+    )
+
+    def to_proto(self) -> cuvis_ai_pb2.PipelineConfig:
+        """Convert to proto message.
+
+        Requires cuvis-ai-schemas[proto] to be installed.
+
+        Returns
+        -------
+        cuvis_ai_pb2.PipelineConfig
+            Proto message representation
+        """
+        try:
+            from cuvis_ai_schemas.grpc.v1 import cuvis_ai_pb2
+        except ImportError as exc:
+            msg = "Proto support not installed. Install with: pip install cuvis-ai-schemas[proto]"
+            raise ImportError(msg) from exc
+
+        return cuvis_ai_pb2.PipelineConfig(config_bytes=self.model_dump_json().encode("utf-8"))
+
+    @classmethod
+    def from_proto(cls, proto_config: cuvis_ai_pb2.PipelineConfig) -> PipelineConfig:
+        """Load from proto message.
+
+        Parameters
+        ----------
+        proto_config : cuvis_ai_pb2.PipelineConfig
+            Proto message to deserialize
+
+        Returns
+        -------
+        PipelineConfig
+            Loaded configuration
+        """
+        return cls.model_validate_json(proto_config.config_bytes.decode("utf-8"))
+
+    def to_json(self) -> str:
+        """Convert to JSON string."""
+        return self.model_dump_json()
+
+    @classmethod
+    def from_json(cls, payload: str) -> PipelineConfig:
+        """Load from JSON string."""
+        return cls.model_validate_json(payload)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary."""
+        return self.model_dump()
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> PipelineConfig:
+        """Load from dictionary."""
+        return cls.model_validate(data)
+
+    def save_to_file(self, path: str | Path) -> None:
+        """Save pipeline configuration to YAML file.
+
+        Parameters
+        ----------
+        path : str | Path
+            Output file path
+        """
+        from pathlib import Path
+
+        output_path = Path(path)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        with output_path.open("w", encoding="utf-8") as f:
+            yaml.safe_dump(self.model_dump(), f, sort_keys=False)
+
+    @classmethod
+    def load_from_file(cls, path: str | Path) -> PipelineConfig:
+        """Load pipeline configuration from YAML file.
+
+        Parameters
+        ----------
+        path : str | Path
+            Input file path
+
+        Returns
+        -------
+        PipelineConfig
+            Loaded configuration
+        """
+        from pathlib import Path
+
+        with Path(path).open("r", encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+        return cls.from_dict(data)

cuvis_ai_schemas/pipeline/ports.py

@@ -0,0 +1,48 @@
+"""Port specification for node inputs and outputs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class PortSpec:
+    """Specification for a node input or output port.
+
+    This is a lightweight schema definition. Full compatibility checking
+    logic is implemented in cuvis-ai-core.
+
+    Attributes
+    ----------
+    dtype : Any
+        Data type for the port (e.g., torch.Tensor, torch.float32, int, str)
+    shape : tuple[int | str, ...]
+        Expected shape with:
+        - Fixed dimensions: positive integers
+        - Flexible dimensions: -1
+        - Symbolic dimensions: strings (resolved from node attributes)
+    description : str
+        Human-readable description of the port
+    optional : bool
+        Whether the port is optional (for inputs)
+
+    Examples
+    --------
+    >>> # Fixed shape tensor port
+    >>> port = PortSpec(dtype=torch.Tensor, shape=(1, 3, 224, 224))
+
+    >>> # Flexible batch dimension
+    >>> port = PortSpec(dtype=torch.Tensor, shape=(-1, 3, 224, 224))
+
+    >>> # Symbolic dimension from node attribute
+    >>> port = PortSpec(dtype=torch.Tensor, shape=(-1, "num_channels", 224, 224))
+
+    >>> # Scalar port
+    >>> port = PortSpec(dtype=float, shape=())
+    """
+
+    dtype: Any
+    shape: tuple[int | str, ...]
+    description: str = ""
+    optional: bool = False

cuvis_ai_schemas/plugin/__init__.py

@@ -0,0 +1,6 @@
+"""Plugin system schemas."""
+
+from cuvis_ai_schemas.plugin.config import GitPluginConfig, LocalPluginConfig
+from cuvis_ai_schemas.plugin.manifest import PluginManifest
+
+__all__ = ["PluginManifest", "GitPluginConfig", "LocalPluginConfig"]

cuvis_ai_schemas/plugin/config.py

@@ -0,0 +1,118 @@
+"""Plugin configuration schemas."""
+
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class _BasePluginConfig(BaseModel):
+    """Base plugin configuration with strict validation.
+
+    All plugin types inherit from this base class to ensure
+    consistent validation and error handling.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",  # Reject unknown fields (catch typos)
+        validate_assignment=True,  # Validate on attribute assignment
+        populate_by_name=True,  # Allow field aliases
+    )
+
+    provides: list[str] = Field(
+        description="List of fully-qualified class paths this plugin provides",
+        min_length=1,  # At least one class required
+    )
+
+    @field_validator("provides")
+    @classmethod
+    def _validate_class_paths(cls, value: list[str]) -> list[str]:
+        """Ensure class paths are well-formed."""
+        for class_path in value:
+            if not class_path or "." not in class_path:
+                msg = (
+                    f"Invalid class path '{class_path}'. "
+                    "Must be fully-qualified (e.g., 'package.module.ClassName')"
+                )
+                raise ValueError(msg)
+        return value
+
+
+class GitPluginConfig(_BasePluginConfig):
+    """Git repository plugin configuration.
+
+    Supports:
+    - SSH URLs: git@gitlab.com:user/repo.git
+    - HTTPS URLs: https://github.com/user/repo.git
+    - Git tags only: v1.2.3, v0.1.0-alpha, etc.
+
+    Note: Branches and commit hashes are NOT supported for reproducibility.
+    """
+
+    repo: str = Field(
+        description="Git repository URL (SSH or HTTPS)",
+        min_length=1,
+    )
+
+    tag: str = Field(
+        description="Git tag (e.g., v1.2.3, v0.1.0-alpha). "
+        "Branches and commit hashes are not supported.",
+        min_length=1,
+    )
+
+    @field_validator("repo")
+    @classmethod
+    def _validate_repo_url(cls, value: str) -> str:
+        """Validate Git repository URL format."""
+        if not (
+            value.startswith("git@") or value.startswith("https://") or value.startswith("http://")
+        ):
+            msg = f"Invalid repo URL '{value}'. Must start with 'git@', 'https://', or 'http://'"
+            raise ValueError(msg)
+        return value
+
+    @field_validator("tag")
+    @classmethod
+    def _validate_tag(cls, value: str) -> str:
+        """Validate Git tag is not empty."""
+        if not value.strip():
+            msg = "Git tag cannot be empty"
+            raise ValueError(msg)
+        return value.strip()
+
+
+class LocalPluginConfig(_BasePluginConfig):
+    """Local filesystem plugin configuration.
+
+    Supports:
+    - Absolute paths: /home/user/my-plugin
+    - Relative paths: ../my-plugin (resolved relative to manifest file)
+    - Windows paths: C:\\Users\\user\\my-plugin
+    """
+
+    path: str = Field(
+        description="Absolute or relative path to plugin directory",
+        min_length=1,
+    )
+
+    @field_validator("path")
+    @classmethod
+    def _validate_path(cls, value: str) -> str:
+        """Validate path is not empty."""
+        if not value.strip():
+            msg = "Path cannot be empty"
+            raise ValueError(msg)
+        return value.strip()
+
+    def resolve_path(self, manifest_dir: Path) -> Path:
+        """Resolve relative paths to absolute paths.
+
+        Args:
+            manifest_dir: Directory containing the manifest file
+
+        Returns:
+            Absolute path to plugin directory
+        """
+        plugin_path = Path(self.path)
+        if not plugin_path.is_absolute():
+            plugin_path = (manifest_dir / plugin_path).resolve()
+        return plugin_path

cuvis_ai_schemas/plugin/manifest.py

@@ -0,0 +1,95 @@
+"""Plugin manifest schema."""
+
+from pathlib import Path
+from typing import Annotated
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from cuvis_ai_schemas.plugin.config import GitPluginConfig, LocalPluginConfig
+
+
+class PluginManifest(BaseModel):
+    """Complete plugin manifest containing all plugin configurations.
+
+    This is the root configuration object validated when loading
+    a plugins.yaml file or dictionary.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+        validate_assignment=True,
+    )
+
+    plugins: dict[
+        str,
+        Annotated[
+            GitPluginConfig | LocalPluginConfig,
+            Field(discriminator=None),  # Pydantic will auto-detect based on fields
+        ],
+    ] = Field(
+        description="Map of plugin names to their configurations",
+        default_factory=dict,
+    )
+
+    @field_validator("plugins")
+    @classmethod
+    def _validate_plugin_names(cls, value: dict) -> dict:
+        """Ensure plugin names are valid Python identifiers."""
+        for name in value.keys():
+            if not name.isidentifier():
+                msg = f"Invalid plugin name '{name}'. Must be a valid Python identifier"
+                raise ValueError(msg)
+        return value
+
+    @classmethod
+    def from_yaml(cls, yaml_path: Path) -> "PluginManifest":
+        """Load and validate manifest from YAML file.
+
+        Args:
+            yaml_path: Path to YAML file
+
+        Returns:
+            Validated PluginManifest instance
+
+        Raises:
+            FileNotFoundError: If yaml_path doesn't exist
+        """
+        if not yaml_path.exists():
+            msg = f"Plugin manifest not found: {yaml_path}"
+            raise FileNotFoundError(msg)
+
+        with yaml_path.open("r", encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+
+        if not data:
+            return cls(plugins={})
+
+        return cls.model_validate(data)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "PluginManifest":
+        """Load and validate manifest from dictionary.
+
+        Args:
+            data: Dictionary containing plugin configurations
+
+        Returns:
+            Validated PluginManifest instance
+        """
+        return cls.model_validate(data)
+
+    def to_yaml(self, yaml_path: Path) -> None:
+        """Save manifest to YAML file.
+
+        Args:
+            yaml_path: Path where YAML file should be saved
+        """
+        yaml_path.parent.mkdir(parents=True, exist_ok=True)
+        with yaml_path.open("w", encoding="utf-8") as f:
+            yaml.safe_dump(
+                self.model_dump(exclude_none=True),
+                f,
+                sort_keys=False,
+                default_flow_style=False,
+            )

cuvis_ai_schemas/training/__init__.py

@@ -0,0 +1,40 @@
+"""Training configuration schemas for cuvis-ai."""
+
+from cuvis_ai_schemas.training.callbacks import (
+    CallbacksConfig,
+    EarlyStoppingConfig,
+    LearningRateMonitorConfig,
+    ModelCheckpointConfig,
+)
+from cuvis_ai_schemas.training.config import TrainingConfig
+from cuvis_ai_schemas.training.data import DataConfig
+from cuvis_ai_schemas.training.optimizer import OptimizerConfig
+from cuvis_ai_schemas.training.run import (
+    PipelineConfig,
+    PipelineMetadata,
+    TrainRunConfig,
+)
+from cuvis_ai_schemas.training.scheduler import SchedulerConfig
+from cuvis_ai_schemas.training.trainer import TrainerConfig
+
+__all__ = [
+    # Callbacks
+    "CallbacksConfig",
+    "EarlyStoppingConfig",
+    "LearningRateMonitorConfig",
+    "ModelCheckpointConfig",
+    # Config
+    "TrainingConfig",
+    # Data
+    "DataConfig",
+    # Optimizer
+    "OptimizerConfig",
+    # Scheduler
+    "SchedulerConfig",
+    # Trainer
+    "TrainerConfig",
+    # Run
+    "PipelineConfig",
+    "PipelineMetadata",
+    "TrainRunConfig",
+]