QuickLab-MCP 0.1.0__py3-none-any.whl

ml_mcp/infrastructure/object_storage/s3.py

@@ -0,0 +1,272 @@
+"""S3-compatible object storage service with tenant isolation and presigned URL support."""
+
+import hashlib
+import logging
+import os
+import re
+from typing import Any
+
+import boto3
+from botocore.client import Config
+from botocore.exceptions import ClientError
+
+from ml_mcp.config import Settings, get_settings
+from ml_mcp.domain.errors import DependencyUnavailableError
+
+logger = logging.getLogger(__name__)
+
+
+class S3StorageService:
+    """Production S3 / MinIO storage adapter managing artifacts and datasets."""
+
+    _SAFE_COMPONENT_PATTERN = re.compile(r"^[a-zA-Z0-9_\-\.]+$")
+
+    def __init__(self, settings: Settings | None = None) -> None:
+        self.settings = settings or get_settings()
+        self.bucket_name = self.settings.object_store.bucket_name
+        self._client: Any = None
+        self._memory_store: dict[str, tuple[bytes, dict[str, str], str]] = {}
+
+    @classmethod
+    def _assert_safe_component(cls, component: str, field_name: str = "component") -> str:
+        """Validate that a path component contains no traversal sequences or unsafe characters."""
+        if not component or not isinstance(component, str) or not component.strip():
+            raise ValueError(f"Invalid {field_name}: empty component")
+        if component in (".", "..") or ".." in component or "/" in component or "\\" in component:
+            raise ValueError(f"Directory traversal detected in {field_name}: '{component}'")
+        if not cls._SAFE_COMPONENT_PATTERN.match(component):
+            raise ValueError(f"Invalid characters detected in {field_name}: '{component}'")
+        return component
+
+    @classmethod
+    def _assert_safe_key(cls, key: str) -> str:
+        """Validate full storage key against path traversal and malformed structures."""
+        if not key or not isinstance(key, str) or not key.strip():
+            raise ValueError("Invalid storage key: empty key")
+        if key.startswith("/") or key.endswith("/"):
+            raise ValueError(f"Invalid storage key: leading or trailing slash in '{key}'")
+        if "//" in key or "\\" in key or ".." in key:
+            raise ValueError(f"Directory traversal detected in storage key: '{key}'")
+        parts = key.split("/")
+        for part in parts:
+            cls._assert_safe_component(part, "key component")
+        return key
+
+    @property
+    def is_testing(self) -> bool:
+        app_env = getattr(self.settings, "app_env", None)
+        if app_env is None and hasattr(self.settings, "app"):
+            app_env = getattr(self.settings.app, "env", None)
+        return app_env == "testing" or os.environ.get("APP_ENV") == "testing"
+
+    @property
+    def client(self) -> Any:
+        if self._client is None:
+            self._client = boto3.client(
+                "s3",
+                endpoint_url=self.settings.object_store.endpoint_url,
+                aws_access_key_id=self.settings.object_store.access_key_id.get_secret_value(),
+                aws_secret_access_key=self.settings.object_store.secret_access_key.get_secret_value(),
+                region_name=self.settings.object_store.region,
+                config=Config(
+                    signature_version="s3v4",
+                    s3={"addressing_style": "path"},
+                    connect_timeout=1,
+                    read_timeout=1,
+                ),
+            )
+        return self._client
+
+    @staticmethod
+    def compute_sha256(data: bytes) -> str:
+        """Compute standard hex SHA-256 digest of binary content."""
+        return hashlib.sha256(data).hexdigest()
+
+    # Tenant-isolated path generators
+    @classmethod
+    def get_dataset_key(
+        cls, tenant_id: str, dataset_id: str, version: str, filename: str = "data.parquet"
+    ) -> str:
+        cls._assert_safe_component(tenant_id, "tenant_id")
+        cls._assert_safe_component(dataset_id, "dataset_id")
+        cls._assert_safe_component(version, "version")
+        cls._assert_safe_component(filename, "filename")
+        return f"tenants/{tenant_id}/datasets/{dataset_id}/{version}/{filename}"
+
+    @classmethod
+    def get_experiment_artifact_key(
+        cls, tenant_id: str, experiment_id: str, artifact_type: str, filename: str
+    ) -> str:
+        cls._assert_safe_component(tenant_id, "tenant_id")
+        cls._assert_safe_component(experiment_id, "experiment_id")
+        cls._assert_safe_component(artifact_type, "artifact_type")
+        cls._assert_safe_component(filename, "filename")
+        return f"tenants/{tenant_id}/experiments/{experiment_id}/{artifact_type}/{filename}"
+
+    @classmethod
+    def get_model_key(
+        cls, tenant_id: str, model_id: str, version: str, filename: str = "model.joblib"
+    ) -> str:
+        cls._assert_safe_component(tenant_id, "tenant_id")
+        cls._assert_safe_component(model_id, "model_id")
+        cls._assert_safe_component(version, "version")
+        cls._assert_safe_component(filename, "filename")
+        return f"tenants/{tenant_id}/models/{model_id}/{version}/{filename}"
+
+    def put_object(
+        self,
+        key: str,
+        data: bytes,
+        content_type: str = "application/octet-stream",
+        metadata: dict[str, str] | None = None,
+    ) -> tuple[str, str]:
+        """Upload an immutable object. Returns (storage_uri, sha256_digest)."""
+        self._assert_safe_key(key)
+        content_hash = self.compute_sha256(data)
+        meta = metadata or {}
+        meta["content_hash"] = content_hash
+
+        if self.is_testing and self._client is None:
+            self._memory_store[key] = (data, meta, content_type)
+            storage_uri = f"s3://{self.bucket_name}/{key}"
+            logger.info(
+                "Testing environment: stored S3 object in memory: %s (size: %d bytes)",
+                storage_uri,
+                len(data),
+            )
+            return storage_uri, content_hash
+
+        try:
+            self.client.put_object(
+                Bucket=self.bucket_name,
+                Key=key,
+                Body=data,
+                ContentType=content_type,
+                Metadata=meta,
+            )
+            storage_uri = f"s3://{self.bucket_name}/{key}"
+            logger.info("Successfully wrote S3 object: %s (size: %d bytes)", storage_uri, len(data))
+            return storage_uri, content_hash
+        except Exception as exc:
+            if not self.is_testing:
+                raise DependencyUnavailableError("Object Storage") from exc
+            logger.warning(
+                "Live S3 unavailable (%s), writing object to memory fallback for key '%s'", exc, key
+            )
+            self._memory_store[key] = (data, meta, content_type)
+            storage_uri = f"s3://{self.bucket_name}/{key}"
+            return storage_uri, content_hash
+
+    def get_object(self, key: str) -> bytes:
+        """Retrieve binary content of an object."""
+        self._assert_safe_key(key)
+        if key in self._memory_store:
+            return self._memory_store[key][0]
+        if self.is_testing and self._client is None:
+            logger.error("Failed to read object from S3 memory store at key '%s'", key)
+            raise DependencyUnavailableError("Object Storage")
+        try:
+            response = self.client.get_object(Bucket=self.bucket_name, Key=key)
+            return response["Body"].read()
+        except Exception as exc:
+            if key in self._memory_store:
+                return self._memory_store[key][0]
+            logger.error("Failed to read object from S3 at key '%s': %s", key, exc)
+            raise DependencyUnavailableError("Object Storage") from exc
+
+    def head_object(self, key: str) -> dict[str, Any] | None:
+        """Inspect object metadata without downloading full payload."""
+        self._assert_safe_key(key)
+        if key in self._memory_store:
+            data, meta, c_type = self._memory_store[key]
+            return {
+                "size_bytes": len(data),
+                "content_type": c_type,
+                "metadata": meta,
+                "last_modified": None,
+            }
+        if self.is_testing and self._client is None:
+            return None
+        try:
+            response = self.client.head_object(Bucket=self.bucket_name, Key=key)
+            return {
+                "size_bytes": response.get("ContentLength", 0),
+                "content_type": response.get("ContentType"),
+                "metadata": response.get("Metadata", {}),
+                "last_modified": response.get("LastModified"),
+            }
+        except ClientError as exc:
+            if exc.response["Error"]["Code"] in ("404", "NoSuchKey"):
+                return None
+            raise DependencyUnavailableError("Object Storage") from exc
+        except Exception as exc:
+            if key in self._memory_store:
+                data, meta, c_type = self._memory_store[key]
+                return {
+                    "size_bytes": len(data),
+                    "content_type": c_type,
+                    "metadata": meta,
+                    "last_modified": None,
+                }
+            raise DependencyUnavailableError("Object Storage") from exc
+
+    def delete_object(self, key: str) -> bool:
+        """Delete an object."""
+        self._assert_safe_key(key)
+        self._memory_store.pop(key, None)
+        if self.is_testing and self._client is None:
+            return True
+        try:
+            self.client.delete_object(Bucket=self.bucket_name, Key=key)
+            return True
+        except Exception as exc:
+            logger.warning("Failed to delete object from S3: %s", exc)
+            return True
+
+    def generate_presigned_get_url(self, key: str, expires_in: int | None = None) -> str:
+        """Generate a short-lived read-only presigned GET URL."""
+        self._assert_safe_key(key)
+        ttl = expires_in or self.settings.object_store.presigned_ttl_seconds
+        if self.is_testing and self._client is None:
+            return f"https://s3.local/{self.bucket_name}/{key}?expires={ttl}&sig=mock"
+        try:
+            url = self.client.generate_presigned_url(
+                ClientMethod="get_object",
+                Params={"Bucket": self.bucket_name, "Key": key},
+                ExpiresIn=ttl,
+            )
+            return url
+        except Exception:
+            return f"https://s3.local/{self.bucket_name}/{key}?expires={ttl}&sig=mock"
+
+    def generate_presigned_put_url(
+        self,
+        key: str,
+        content_type: str = "application/octet-stream",
+        expires_in: int | None = None,
+    ) -> str:
+        """Generate a short-lived presigned PUT URL for direct client uploads."""
+        self._assert_safe_key(key)
+        ttl = expires_in or self.settings.object_store.presigned_ttl_seconds
+        if self.is_testing and self._client is None:
+            return f"https://s3.local/{self.bucket_name}/{key}?expires={ttl}&sig=mock"
+        try:
+            url = self.client.generate_presigned_url(
+                ClientMethod="put_object",
+                Params={"Bucket": self.bucket_name, "Key": key, "ContentType": content_type},
+                ExpiresIn=ttl,
+            )
+            return url
+        except Exception:
+            return f"https://s3.local/{self.bucket_name}/{key}?expires={ttl}&sig=mock"
+
+
+_storage_service: S3StorageService | None = None
+
+
+def get_storage_service() -> S3StorageService:
+    """Return singleton S3StorageService instance."""
+    global _storage_service
+    if _storage_service is None:
+        _storage_service = S3StorageService()
+    return _storage_service

ml_mcp/infrastructure/postgres/__init__.py

@@ -0,0 +1,14 @@
+"""PostgreSQL persistence layer using SQLAlchemy 2."""
+
+import ml_mcp.infrastructure.postgres.models as models
+from ml_mcp.infrastructure.postgres.base import Base, generate_uuid7, utc_now
+from ml_mcp.infrastructure.postgres.session import DatabaseManager, get_db_manager
+
+__all__ = [
+    "Base",
+    "generate_uuid7",
+    "utc_now",
+    "DatabaseManager",
+    "get_db_manager",
+    "models",
+]

ml_mcp/infrastructure/postgres/base.py

@@ -0,0 +1,40 @@
+"""SQLAlchemy declarative base and time-sortable identifier generator."""
+
+import os
+import time
+import uuid
+from datetime import UTC, datetime
+
+from sqlalchemy import DateTime
+from sqlalchemy.orm import DeclarativeBase
+
+
+def generate_uuid7() -> str:
+    """Generate a time-sortable UUID (RFC 9562 UUIDv7 format)."""
+    # 48-bit timestamp in milliseconds
+    ms = int(time.time() * 1000)
+    # 12 bits of rand_a + 62 bits of rand_b
+    rand_bytes = os.urandom(10)
+
+    # Construct 16-byte UUID array
+    b = bytearray(16)
+    b[0:6] = ms.to_bytes(6, byteorder="big")
+    b[6] = 0x70 | (rand_bytes[0] & 0x0F)  # version 7
+    b[7] = rand_bytes[1]
+    b[8] = 0x80 | (rand_bytes[2] & 0x3F)  # variant 1
+    b[9:16] = rand_bytes[3:10]
+
+    return str(uuid.UUID(bytes=bytes(b)))
+
+
+def utc_now() -> datetime:
+    """Return timezone-aware current UTC datetime."""
+    return datetime.now(UTC)
+
+
+class Base(DeclarativeBase):
+    """Declarative base class for all ModelLab ORM entities."""
+
+    type_annotation_map = {
+        datetime: DateTime(timezone=True),
+    }

ml_mcp/infrastructure/postgres/models.py

@@ -0,0 +1,356 @@
+"""SQLAlchemy 2.x ORM models mapping the complete ModelLab control-plane schema."""
+
+from datetime import datetime
+from typing import Any
+
+from sqlalchemy import (
+    JSON,
+    BigInteger,
+    Float,
+    ForeignKey,
+    Index,
+    Integer,
+    String,
+    Text,
+    UniqueConstraint,
+)
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from ml_mcp.infrastructure.postgres.base import Base, generate_uuid7, utc_now
+
+# Universal JSON type: native JSONB for PostgreSQL, automatic JSON serializer for SQLite
+JSON_TYPE = JSON().with_variant(JSONB(), "postgresql")
+
+
+class TenantOrm(Base):
+    __tablename__ = "tenants"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=generate_uuid7)
+    name: Mapped[str] = mapped_column(String(128), unique=True, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(default=utc_now, nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(default=utc_now, onupdate=utc_now, nullable=False)
+
+    principals: Mapped[list["PrincipalOrm"]] = relationship(
+        back_populates="tenant", cascade="all, delete-orphan"
+    )
+    projects: Mapped[list["ProjectOrm"]] = relationship(
+        back_populates="tenant", cascade="all, delete-orphan"
+    )
+
+
+class PrincipalOrm(Base):
+    __tablename__ = "principals"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=generate_uuid7)
+    tenant_id: Mapped[str] = mapped_column(
+        ForeignKey("tenants.id", ondelete="CASCADE"), nullable=False
+    )
+    username: Mapped[str] = mapped_column(String(128), nullable=False)
+    email: Mapped[str] = mapped_column(String(255), nullable=False)
+    role: Mapped[str] = mapped_column(String(32), nullable=False, default="viewer")
+    scopes: Mapped[list[str]] = mapped_column(JSON_TYPE, default=list, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(default=utc_now, nullable=False)
+
+    tenant: Mapped["TenantOrm"] = relationship(back_populates="principals")
+
+    __table_args__ = (
+        UniqueConstraint("tenant_id", "username", name="uq_principals_tenant_username"),
+        Index("ix_principals_tenant_created", "tenant_id", "created_at"),
+    )
+
+
+class ProjectOrm(Base):
+    __tablename__ = "projects"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=generate_uuid7)
+    tenant_id: Mapped[str] = mapped_column(
+        ForeignKey("tenants.id", ondelete="CASCADE"), nullable=False
+    )
+    name: Mapped[str] = mapped_column(String(128), nullable=False)
+    description: Mapped[str] = mapped_column(Text, default="", nullable=False)
+    created_at: Mapped[datetime] = mapped_column(default=utc_now, nullable=False)
+
+    tenant: Mapped["TenantOrm"] = relationship(back_populates="projects")
+    datasets: Mapped[list["DatasetOrm"]] = relationship(
+        back_populates="project", cascade="all, delete-orphan"
+    )
+    experiments: Mapped[list["ExperimentOrm"]] = relationship(
+        back_populates="project", cascade="all, delete-orphan"
+    )
+
+    __table_args__ = (
+        UniqueConstraint("tenant_id", "name", name="uq_projects_tenant_name"),
+        Index("ix_projects_tenant_created", "tenant_id", "created_at"),
+    )
+
+
+class ModelOrm(Base):
+    __tablename__ = "models"
+
+    id: Mapped[str] = mapped_column(String(64), primary_key=True)
+    tenant_id: Mapped[str] = mapped_column(String(36), nullable=False, default="system")
+    name: Mapped[str] = mapped_column(String(128), nullable=False)
+    description: Mapped[str] = mapped_column(Text, default="", nullable=False)
+    family: Mapped[str] = mapped_column(String(64), nullable=False)
+    publisher: Mapped[str] = mapped_column(String(128), default="ModelLab", nullable=False)
+    created_at: Mapped[datetime] = mapped_column(default=utc_now, nullable=False)
+
+    versions: Mapped[list["ModelVersionOrm"]] = relationship(
+        back_populates="model", cascade="all, delete-orphan"
+    )
+
+    __table_args__ = (Index("ix_models_tenant_created", "tenant_id", "created_at"),)
+
+
+class ModelVersionOrm(Base):
+    __tablename__ = "model_versions"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=generate_uuid7)
+    model_id: Mapped[str] = mapped_column(
+        ForeignKey("models.id", ondelete="CASCADE"), nullable=False
+    )
+    version: Mapped[str] = mapped_column(String(32), nullable=False)
+    container_image_digest: Mapped[str] = mapped_column(String(128), nullable=False)
+    artifact_digest: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    supported_task_types: Mapped[list[str]] = mapped_column(JSON_TYPE, nullable=False)
+    hyperparameters_schema: Mapped[list[dict[str, Any]]] = mapped_column(
+        JSON_TYPE, default=list, nullable=False
+    )
+    approval_status: Mapped[str] = mapped_column(String(32), default="APPROVED", nullable=False)
+    created_at: Mapped[datetime] = mapped_column(default=utc_now, nullable=False)
+
+    model: Mapped["ModelOrm"] = relationship(back_populates="versions")
+
+    __table_args__ = (
+        UniqueConstraint("model_id", "version", name="uq_model_versions_model_version"),
+        Index("ix_model_versions_created", "created_at"),
+    )
+
+
+class DatasetOrm(Base):
+    __tablename__ = "datasets"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=generate_uuid7)
+    tenant_id: Mapped[str] = mapped_column(String(36), nullable=False)
+    project_id: Mapped[str] = mapped_column(
+        ForeignKey("projects.id", ondelete="CASCADE"), nullable=False
+    )
+    name: Mapped[str] = mapped_column(String(128), nullable=False)
+    description: Mapped[str] = mapped_column(Text, default="", nullable=False)
+    format: Mapped[str] = mapped_column(String(16), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(default=utc_now, nullable=False)
+
+    project: Mapped["ProjectOrm"] = relationship(back_populates="datasets")
+    versions: Mapped[list["DatasetVersionOrm"]] = relationship(
+        back_populates="dataset", cascade="all, delete-orphan"
+    )
+
+    __table_args__ = (
+        UniqueConstraint("project_id", "name", name="uq_datasets_project_name"),
+        Index("ix_datasets_tenant_created", "tenant_id", "created_at"),
+        Index("ix_datasets_project_created", "project_id", "created_at"),
+    )
+
+
+class DatasetVersionOrm(Base):
+    __tablename__ = "dataset_versions"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=generate_uuid7)
+    dataset_id: Mapped[str] = mapped_column(
+        ForeignKey("datasets.id", ondelete="CASCADE"), nullable=False
+    )
+    version: Mapped[str] = mapped_column(String(32), nullable=False)
+    schema_json: Mapped[dict[str, Any]] = mapped_column(JSON_TYPE, nullable=False)
+    row_count: Mapped[int] = mapped_column(Integer, nullable=False)
+    column_count: Mapped[int] = mapped_column(Integer, nullable=False)
+    size_bytes: Mapped[int] = mapped_column(BigInteger, nullable=False)
+    content_hash: Mapped[str] = mapped_column(String(128), nullable=False)
+    storage_uri: Mapped[str] = mapped_column(String(512), nullable=False)
+    validation_status: Mapped[str] = mapped_column(String(32), default="VALIDATED", nullable=False)
+    created_at: Mapped[datetime] = mapped_column(default=utc_now, nullable=False)
+
+    dataset: Mapped["DatasetOrm"] = relationship(back_populates="versions")
+
+    __table_args__ = (
+        UniqueConstraint("dataset_id", "version", name="uq_dataset_versions_dataset_version"),
+        Index("ix_dataset_versions_hash", "content_hash"),
+    )
+
+
+class ExperimentOrm(Base):
+    __tablename__ = "experiments"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=generate_uuid7)
+    tenant_id: Mapped[str] = mapped_column(String(36), nullable=False)
+    project_id: Mapped[str] = mapped_column(
+        ForeignKey("projects.id", ondelete="CASCADE"), nullable=False
+    )
+    dataset_version_id: Mapped[str] = mapped_column(
+        ForeignKey("dataset_versions.id"), nullable=False
+    )
+    model_version_id: Mapped[str] = mapped_column(ForeignKey("model_versions.id"), nullable=False)
+    spec_json: Mapped[dict[str, Any]] = mapped_column(JSON_TYPE, nullable=False)
+    status: Mapped[str] = mapped_column(String(32), default="CREATED", nullable=False)
+    idempotency_key: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    created_by: Mapped[str] = mapped_column(String(128), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(default=utc_now, nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(default=utc_now, onupdate=utc_now, nullable=False)
+
+    project: Mapped["ProjectOrm"] = relationship(back_populates="experiments")
+    dataset_version: Mapped["DatasetVersionOrm"] = relationship()
+    model_version: Mapped["ModelVersionOrm"] = relationship()
+    runs: Mapped[list["ExperimentRunOrm"]] = relationship(
+        back_populates="experiment", cascade="all, delete-orphan"
+    )
+    metrics: Mapped[list["MetricOrm"]] = relationship(
+        back_populates="experiment", cascade="all, delete-orphan"
+    )
+    artifacts: Mapped[list["ArtifactOrm"]] = relationship(
+        back_populates="experiment", cascade="all, delete-orphan"
+    )
+    analysis: Mapped["AnalysisRunOrm | None"] = relationship(
+        back_populates="experiment", uselist=False, cascade="all, delete-orphan"
+    )
+
+    __table_args__ = (
+        Index("ix_experiments_tenant_created", "tenant_id", "created_at"),
+        Index("ix_experiments_project_created", "project_id", "created_at"),
+        Index("ix_experiments_status_created", "status", "created_at"),
+        Index("ix_experiments_idempotency", "tenant_id", "project_id", "idempotency_key"),
+    )
+
+
+class ExperimentRunOrm(Base):
+    __tablename__ = "experiment_runs"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=generate_uuid7)
+    experiment_id: Mapped[str] = mapped_column(
+        ForeignKey("experiments.id", ondelete="CASCADE"), nullable=False
+    )
+    run_number: Mapped[int] = mapped_column(Integer, default=1, nullable=False)
+    status: Mapped[str] = mapped_column(String(32), default="QUEUED", nullable=False)
+    worker_id: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    start_time: Mapped[datetime | None] = mapped_column(nullable=True)
+    end_time: Mapped[datetime | None] = mapped_column(nullable=True)
+    duration_seconds: Mapped[float | None] = mapped_column(Float, nullable=True)
+    failure_reason: Mapped[str | None] = mapped_column(Text, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(default=utc_now, nullable=False)
+
+    experiment: Mapped["ExperimentOrm"] = relationship(back_populates="runs")
+    metrics: Mapped[list["MetricOrm"]] = relationship(
+        back_populates="run", cascade="all, delete-orphan"
+    )
+
+    __table_args__ = (Index("ix_experiment_runs_experiment", "experiment_id"),)
+
+
+class MetricOrm(Base):
+    __tablename__ = "metrics"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=generate_uuid7)
+    experiment_id: Mapped[str] = mapped_column(
+        ForeignKey("experiments.id", ondelete="CASCADE"), nullable=False
+    )
+    run_id: Mapped[str] = mapped_column(
+        ForeignKey("experiment_runs.id", ondelete="CASCADE"), nullable=False
+    )
+    metric_name: Mapped[str] = mapped_column(String(64), nullable=False)
+    metric_value: Mapped[float] = mapped_column(Float, nullable=False)
+    step: Mapped[int] = mapped_column(Integer, default=0, nullable=False)
+    split: Mapped[str] = mapped_column(
+        String(32), default="validation", nullable=False
+    )  # train, validation, test
+    created_at: Mapped[datetime] = mapped_column(default=utc_now, nullable=False)
+
+    experiment: Mapped["ExperimentOrm"] = relationship(back_populates="metrics")
+    run: Mapped["ExperimentRunOrm"] = relationship(back_populates="metrics")
+
+    __table_args__ = (
+        Index("ix_metrics_experiment_name", "experiment_id", "metric_name"),
+        Index("ix_metrics_run", "run_id"),
+    )
+
+
+class AnalysisRunOrm(Base):
+    __tablename__ = "analysis_runs"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=generate_uuid7)
+    experiment_id: Mapped[str] = mapped_column(
+        ForeignKey("experiments.id", ondelete="CASCADE"), unique=True, nullable=False
+    )
+    tenant_id: Mapped[str] = mapped_column(String(36), nullable=False)
+    summary_json: Mapped[dict[str, Any]] = mapped_column(JSON_TYPE, nullable=False)
+    diagnostics_json: Mapped[dict[str, Any]] = mapped_column(JSON_TYPE, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(default=utc_now, nullable=False)
+
+    experiment: Mapped["ExperimentOrm"] = relationship(back_populates="analysis")
+
+    __table_args__ = (Index("ix_analysis_tenant_created", "tenant_id", "created_at"),)
+
+
+class ArtifactOrm(Base):
+    __tablename__ = "artifacts"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=generate_uuid7)
+    tenant_id: Mapped[str] = mapped_column(String(36), nullable=False)
+    experiment_id: Mapped[str] = mapped_column(
+        ForeignKey("experiments.id", ondelete="CASCADE"), nullable=False
+    )
+    artifact_type: Mapped[str] = mapped_column(
+        String(64), nullable=False
+    )  # model, predictions, metrics_report, etc.
+    storage_uri: Mapped[str] = mapped_column(String(512), nullable=False)
+    size_bytes: Mapped[int] = mapped_column(BigInteger, nullable=False)
+    content_hash: Mapped[str] = mapped_column(String(128), nullable=False)
+    metadata_json: Mapped[dict[str, Any]] = mapped_column(JSON_TYPE, default=dict, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(default=utc_now, nullable=False)
+
+    experiment: Mapped["ExperimentOrm"] = relationship(back_populates="artifacts")
+
+    __table_args__ = (
+        Index("ix_artifacts_experiment", "experiment_id"),
+        Index("ix_artifacts_tenant_created", "tenant_id", "created_at"),
+    )
+
+
+class OutboxEventOrm(Base):
+    __tablename__ = "outbox_events"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=generate_uuid7)
+    event_type: Mapped[str] = mapped_column(String(64), nullable=False)
+    aggregate_type: Mapped[str] = mapped_column(String(64), nullable=False)
+    aggregate_id: Mapped[str] = mapped_column(String(64), nullable=False)
+    payload_json: Mapped[dict[str, Any]] = mapped_column(JSON_TYPE, nullable=False)
+    status: Mapped[str] = mapped_column(
+        String(32), default="PENDING", nullable=False
+    )  # PENDING, DELIVERED, FAILED
+    retry_count: Mapped[int] = mapped_column(Integer, default=0, nullable=False)
+    scheduled_at: Mapped[datetime] = mapped_column(default=utc_now, nullable=False)
+    processed_at: Mapped[datetime | None] = mapped_column(nullable=True)
+    created_at: Mapped[datetime] = mapped_column(default=utc_now, nullable=False)
+
+    __table_args__ = (Index("ix_outbox_status_scheduled", "status", "scheduled_at"),)
+
+
+class AuditEventOrm(Base):
+    __tablename__ = "audit_events"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=generate_uuid7)
+    timestamp: Mapped[datetime] = mapped_column(default=utc_now, nullable=False)
+    principal_id: Mapped[str] = mapped_column(String(64), nullable=False)
+    tenant_id: Mapped[str] = mapped_column(String(36), nullable=False)
+    project_id: Mapped[str | None] = mapped_column(String(36), nullable=True)
+    action: Mapped[str] = mapped_column(String(64), nullable=False)
+    resource_type: Mapped[str] = mapped_column(String(64), nullable=False)
+    resource_id: Mapped[str] = mapped_column(String(64), nullable=False)
+    request_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    trace_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    result: Mapped[str] = mapped_column(String(32), nullable=False)  # SUCCESS, DENIED, ERROR
+    reason_code: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    client_ip: Mapped[str | None] = mapped_column(String(64), nullable=True)
+
+    __table_args__ = (
+        Index("ix_audit_tenant_timestamp", "tenant_id", "timestamp"),
+        Index("ix_audit_principal_timestamp", "principal_id", "timestamp"),
+    )