QuickLab-MCP 0.1.0__py3-none-any.whl

ml_mcp/domain/policies/__init__.py

@@ -0,0 +1,16 @@
+"""Domain policies package."""
+
+from ml_mcp.domain.policies.rbac import ROLE_PERMISSIONS, Principal, Role, Scope
+from ml_mcp.domain.policies.tenant_isolation import validate_tenant_access
+from ml_mcp.domain.policies.tool_policy import TOOL_POLICIES, ToolClass, ToolPolicy
+
+__all__ = [
+    "Role",
+    "Scope",
+    "ROLE_PERMISSIONS",
+    "Principal",
+    "ToolClass",
+    "ToolPolicy",
+    "TOOL_POLICIES",
+    "validate_tenant_access",
+]

ml_mcp/domain/policies/rbac.py

@@ -0,0 +1,126 @@
+"""Role-Based Access Control (RBAC) and permission scope evaluation."""
+
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+from ml_mcp.domain.errors import AuthorizationDeniedError
+
+
+class Role(StrEnum):
+    """Supported principal roles in ModelLab."""
+
+    VIEWER = "viewer"
+    RESEARCHER = "researcher"
+    OPERATOR = "operator"
+    ADMIN = "admin"
+
+
+class Scope(StrEnum):
+    """Granular permission scopes for ML control plane operations."""
+
+    PROJECTS_READ = "ml:projects:read"
+    PROJECTS_WRITE = "ml:projects:write"
+    MODELS_READ = "ml:models:read"
+    DATASETS_READ = "ml:datasets:read"
+    DATASETS_WRITE = "ml:datasets:write"
+    EXPERIMENTS_READ = "ml:experiments:read"
+    EXPERIMENTS_CREATE = "ml:experiments:create"
+    EXPERIMENTS_CANCEL = "ml:experiments:cancel"
+    ANALYSIS_CREATE = "ml:analysis:create"
+    ARTIFACTS_READ = "ml:artifacts:read"
+    WORKER_OPERATE = "ml:worker:operate"
+    EXPERIMENT_OVERRIDE = "ml:experiment:override"
+    ADMIN = "ml:admin"
+
+
+# Standard role permissions matrix per Architecture.md section 7
+ROLE_PERMISSIONS: dict[Role, set[Scope]] = {
+    Role.VIEWER: {
+        Scope.PROJECTS_READ,
+        Scope.MODELS_READ,
+        Scope.DATASETS_READ,
+        Scope.EXPERIMENTS_READ,
+        Scope.ARTIFACTS_READ,
+    },
+    Role.RESEARCHER: {
+        Scope.PROJECTS_READ,
+        Scope.PROJECTS_WRITE,
+        Scope.MODELS_READ,
+        Scope.DATASETS_READ,
+        Scope.DATASETS_WRITE,
+        Scope.EXPERIMENTS_READ,
+        Scope.EXPERIMENTS_CREATE,
+        Scope.EXPERIMENTS_CANCEL,
+        Scope.ANALYSIS_CREATE,
+        Scope.ARTIFACTS_READ,
+    },
+    Role.OPERATOR: {
+        Scope.PROJECTS_READ,
+        Scope.PROJECTS_WRITE,
+        Scope.MODELS_READ,
+        Scope.DATASETS_READ,
+        Scope.DATASETS_WRITE,
+        Scope.EXPERIMENTS_READ,
+        Scope.EXPERIMENTS_CREATE,
+        Scope.EXPERIMENTS_CANCEL,
+        Scope.ANALYSIS_CREATE,
+        Scope.ARTIFACTS_READ,
+        Scope.WORKER_OPERATE,
+        Scope.EXPERIMENT_OVERRIDE,
+    },
+    Role.ADMIN: set(Scope),
+}
+
+
+class Principal(BaseModel):
+    """Authenticated caller identity."""
+
+    principal_id: str = Field(..., min_length=1)
+    tenant_id: str = Field(..., min_length=1)
+    project_ids: list[str] = Field(
+        default_factory=list,
+        description="List of authorized project IDs, empty allows all tenant projects",
+    )
+    role: Role = Role.VIEWER
+    scopes: set[str] = Field(
+        default_factory=set, description="Explicit scopes granted via token claims"
+    )
+
+    def has_permission(self, required_scope: Scope) -> bool:
+        """Evaluate if the principal holds the required permission via role and scope intersection.
+
+        Enforces strict OAuth 2.1 scope attenuation:
+        1. The requested scope MUST be allowed by the principal's role.
+        2. If explicit token scopes are present, the requested scope MUST also be granted
+           by the token (or covered by a wildcard '*').
+        """
+        role_allowed = ROLE_PERMISSIONS.get(self.role, set())
+        if required_scope not in role_allowed:
+            return False
+
+        # If no explicit token scopes are set, the principal has full role permissions
+        if not self.scopes:
+            return True
+
+        # If explicit scopes are set, evaluate scope intersection
+        scope_vals = {s.value if isinstance(s, Scope) else s for s in self.scopes}
+        req_val = required_scope.value
+        req_short = req_val.removeprefix("ml:")
+
+        return (
+            "*" in self.scopes
+            or "admin" in scope_vals
+            or Scope.ADMIN.value in scope_vals
+            or Scope.ADMIN in self.scopes
+            or req_val in scope_vals
+            or req_short in scope_vals
+        )
+
+    def enforce_permission(self, required_scope: Scope) -> None:
+        """Enforce permission, raising AuthorizationDeniedError if missing."""
+        if not self.has_permission(required_scope):
+            raise AuthorizationDeniedError(
+                f"Principal '{self.principal_id}' lacks required permission scope '{required_scope.value}'",
+                details={"required_scope": required_scope.value, "role": self.role.value},
+            )

ml_mcp/domain/policies/tenant_isolation.py

@@ -0,0 +1,34 @@
+"""Tenant isolation and project boundary enforcement."""
+
+from ml_mcp.domain.errors import AuthorizationDeniedError, ResourceNotFoundError
+from ml_mcp.domain.policies.rbac import Principal
+
+
+def validate_tenant_access(
+    principal: Principal,
+    resource_tenant_id: str,
+    resource_project_id: str | None = None,
+) -> None:
+    """Validate that the authenticated principal is authorized to access resources belonging to a given tenant and project.
+
+    Raises:
+        ResourceNotFoundError: if cross-tenant access is detected (anti-enumeration: 404 with 0 foreign tenant leaks).
+        AuthorizationDeniedError: if unauthorized cross-project access within the same tenant is detected.
+    """
+    # Tenant boundary enforcement: cross-tenant access returns 404 with zero foreign tenant leakage
+    if principal.tenant_id != resource_tenant_id:
+        raise ResourceNotFoundError("Resource", resource_project_id or "requested")
+
+    # Project boundary enforcement: if principal has restricted project_ids, check membership
+    if (
+        resource_project_id is not None
+        and principal.project_ids
+        and resource_project_id not in principal.project_ids
+    ):
+        raise AuthorizationDeniedError(
+            f"Principal '{principal.principal_id}' does not have access to project '{resource_project_id}'",
+            details={
+                "allowed_projects": principal.project_ids,
+                "requested_project": resource_project_id,
+            },
+        )

ml_mcp/domain/policies/tool_policy.py

@@ -0,0 +1,185 @@
+"""Tool classification and security requirements."""
+
+from enum import StrEnum
+
+from pydantic import BaseModel
+
+from ml_mcp.domain.policies.rbac import Scope
+
+
+class ToolClass(StrEnum):
+    """Policy classification for rate limiting, auditing, and access control."""
+
+    READ = "READ"
+    MUTATION = "MUTATION"
+    EXPERIMENT = "EXPERIMENT"
+    CONTROL = "CONTROL"
+    ANALYSIS = "ANALYSIS"
+    ARTIFACT = "ARTIFACT"
+
+
+class ToolPolicy(BaseModel):
+    """Security and rate-limiting policy governing an MCP tool."""
+
+    tool_name: str
+    tool_class: ToolClass
+    required_scope: Scope
+    requires_auth: bool = True
+    requires_audit: bool = True
+    rate_limit_category: str  # "read", "metadata", "experiment", "analysis"
+
+
+TOOL_POLICIES: dict[str, ToolPolicy] = {
+    # Discovery tools
+    "list_models": ToolPolicy(
+        tool_name="list_models",
+        tool_class=ToolClass.READ,
+        required_scope=Scope.MODELS_READ,
+        requires_audit=False,
+        rate_limit_category="read",
+    ),
+    "get_model": ToolPolicy(
+        tool_name="get_model",
+        tool_class=ToolClass.READ,
+        required_scope=Scope.MODELS_READ,
+        requires_audit=False,
+        rate_limit_category="read",
+    ),
+    "list_model_versions": ToolPolicy(
+        tool_name="list_model_versions",
+        tool_class=ToolClass.READ,
+        required_scope=Scope.MODELS_READ,
+        requires_audit=False,
+        rate_limit_category="read",
+    ),
+    "list_datasets": ToolPolicy(
+        tool_name="list_datasets",
+        tool_class=ToolClass.READ,
+        required_scope=Scope.DATASETS_READ,
+        requires_audit=False,
+        rate_limit_category="read",
+    ),
+    "get_dataset": ToolPolicy(
+        tool_name="get_dataset",
+        tool_class=ToolClass.READ,
+        required_scope=Scope.DATASETS_READ,
+        requires_audit=False,
+        rate_limit_category="read",
+    ),
+    "list_dataset_versions": ToolPolicy(
+        tool_name="list_dataset_versions",
+        tool_class=ToolClass.READ,
+        required_scope=Scope.DATASETS_READ,
+        requires_audit=False,
+        rate_limit_category="read",
+    ),
+    # Dataset management tools
+    "register_dataset": ToolPolicy(
+        tool_name="register_dataset",
+        tool_class=ToolClass.MUTATION,
+        required_scope=Scope.DATASETS_WRITE,
+        requires_audit=True,
+        rate_limit_category="experiment",
+    ),
+    "validate_dataset": ToolPolicy(
+        tool_name="validate_dataset",
+        tool_class=ToolClass.READ,
+        required_scope=Scope.DATASETS_READ,
+        requires_audit=True,
+        rate_limit_category="metadata",
+    ),
+    "inspect_dataset": ToolPolicy(
+        tool_name="inspect_dataset",
+        tool_class=ToolClass.READ,
+        required_scope=Scope.DATASETS_READ,
+        requires_audit=True,
+        rate_limit_category="metadata",
+    ),
+    # Experiment tools
+    "create_experiment": ToolPolicy(
+        tool_name="create_experiment",
+        tool_class=ToolClass.EXPERIMENT,
+        required_scope=Scope.EXPERIMENTS_CREATE,
+        requires_audit=True,
+        rate_limit_category="experiment",
+    ),
+    "get_experiment": ToolPolicy(
+        tool_name="get_experiment",
+        tool_class=ToolClass.READ,
+        required_scope=Scope.EXPERIMENTS_READ,
+        requires_audit=False,
+        rate_limit_category="read",
+    ),
+    "cancel_experiment": ToolPolicy(
+        tool_name="cancel_experiment",
+        tool_class=ToolClass.CONTROL,
+        required_scope=Scope.EXPERIMENTS_CANCEL,
+        requires_audit=True,
+        rate_limit_category="experiment",
+    ),
+    "list_experiments": ToolPolicy(
+        tool_name="list_experiments",
+        tool_class=ToolClass.READ,
+        required_scope=Scope.EXPERIMENTS_READ,
+        requires_audit=False,
+        rate_limit_category="read",
+    ),
+    # Result tools
+    "get_experiment_metrics": ToolPolicy(
+        tool_name="get_experiment_metrics",
+        tool_class=ToolClass.READ,
+        required_scope=Scope.EXPERIMENTS_READ,
+        requires_audit=False,
+        rate_limit_category="read",
+    ),
+    "get_experiment_predictions": ToolPolicy(
+        tool_name="get_experiment_predictions",
+        tool_class=ToolClass.ARTIFACT,
+        required_scope=Scope.ARTIFACTS_READ,
+        requires_audit=True,
+        rate_limit_category="metadata",
+    ),
+    "list_experiment_artifacts": ToolPolicy(
+        tool_name="list_experiment_artifacts",
+        tool_class=ToolClass.READ,
+        required_scope=Scope.ARTIFACTS_READ,
+        requires_audit=False,
+        rate_limit_category="read",
+    ),
+    "read_experiment_artifact": ToolPolicy(
+        tool_name="read_experiment_artifact",
+        tool_class=ToolClass.ARTIFACT,
+        required_scope=Scope.ARTIFACTS_READ,
+        requires_audit=True,
+        rate_limit_category="metadata",
+    ),
+    "compare_experiments": ToolPolicy(
+        tool_name="compare_experiments",
+        tool_class=ToolClass.READ,
+        required_scope=Scope.EXPERIMENTS_READ,
+        requires_audit=False,
+        rate_limit_category="read",
+    ),
+    # Analysis tools
+    "analyze_experiment": ToolPolicy(
+        tool_name="analyze_experiment",
+        tool_class=ToolClass.ANALYSIS,
+        required_scope=Scope.ANALYSIS_CREATE,
+        requires_audit=True,
+        rate_limit_category="analysis",
+    ),
+    "analyze_model_errors": ToolPolicy(
+        tool_name="analyze_model_errors",
+        tool_class=ToolClass.ANALYSIS,
+        required_scope=Scope.ANALYSIS_CREATE,
+        requires_audit=True,
+        rate_limit_category="analysis",
+    ),
+    "check_experiment_validity": ToolPolicy(
+        tool_name="check_experiment_validity",
+        tool_class=ToolClass.ANALYSIS,
+        required_scope=Scope.ANALYSIS_CREATE,
+        requires_audit=True,
+        rate_limit_category="analysis",
+    ),
+}

ml_mcp/domain/value_objects/__init__.py

@@ -0,0 +1,41 @@
+"""Domain value objects package."""
+
+from ml_mcp.domain.value_objects.dataset import (
+    ColumnSchema,
+    DatasetFormat,
+    DatasetSchema,
+    FeatureType,
+)
+from ml_mcp.domain.value_objects.experiment import (
+    EvaluationConfig,
+    ExperimentSpec,
+    ExperimentStatus,
+    ModelFamily,
+    ResourcePolicy,
+    SplitStrategy,
+    SplitStrategyType,
+    TaskType,
+)
+from ml_mcp.domain.value_objects.model import (
+    ApprovalStatus,
+    HyperparameterConstraint,
+    ModelMetadata,
+)
+
+__all__ = [
+    "TaskType",
+    "ModelFamily",
+    "SplitStrategyType",
+    "SplitStrategy",
+    "EvaluationConfig",
+    "ResourcePolicy",
+    "ExperimentStatus",
+    "ExperimentSpec",
+    "DatasetFormat",
+    "FeatureType",
+    "ColumnSchema",
+    "DatasetSchema",
+    "ApprovalStatus",
+    "HyperparameterConstraint",
+    "ModelMetadata",
+]

ml_mcp/domain/value_objects/dataset.py

@@ -0,0 +1,60 @@
+"""Dataset value objects and schema contracts."""
+
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class DatasetFormat(StrEnum):
+    """Allowed tabular dataset formats."""
+
+    CSV = "csv"
+    PARQUET = "parquet"
+    JSONL = "jsonl"
+
+
+class FeatureType(StrEnum):
+    """Canonical feature types inferred and used in ML preprocessing."""
+
+    NUMERIC = "numeric"
+    CATEGORICAL = "categorical"
+    BOOLEAN = "boolean"
+    DATETIME = "datetime"
+    TEXT = "text"
+
+
+class ColumnSchema(BaseModel):
+    """Schema and statistical metadata for a single dataset column."""
+
+    name: str = Field(..., min_length=1)
+    feature_type: FeatureType
+    nullable: bool = True
+    null_count: int = Field(default=0, ge=0)
+    unique_count: int = Field(default=0, ge=0)
+    sample_values: list[Any] = Field(default_factory=list)
+
+
+class DatasetSchema(BaseModel):
+    """Complete dataset schema structure with content digest and profile."""
+
+    columns: list[ColumnSchema]
+    row_count: int = Field(..., ge=0)
+    column_count: int = Field(..., ge=1)
+    size_bytes: int = Field(..., ge=0)
+    content_hash: str = Field(..., description="SHA-256 content hash of canonicalized dataset")
+
+    @field_validator("columns")
+    @classmethod
+    def validate_unique_column_names(cls, v: list[ColumnSchema]) -> list[ColumnSchema]:
+        names = [col.name.lower() for col in v]
+        if len(names) != len(set(names)):
+            raise ValueError("Dataset schema contains duplicate column names (case-insensitive)")
+        return v
+
+    def get_column(self, name: str) -> ColumnSchema | None:
+        name_lower = name.lower()
+        for col in self.columns:
+            if col.name.lower() == name_lower:
+                return col
+        return None

ml_mcp/domain/value_objects/experiment.py

@@ -0,0 +1,131 @@
+"""Experiment value objects and specification contracts."""
+
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class TaskType(StrEnum):
+    """Supported machine learning task types."""
+
+    BINARY_CLASSIFICATION = "binary_classification"
+    MULTICLASS_CLASSIFICATION = "multiclass_classification"
+    REGRESSION = "regression"
+
+
+class ModelFamily(StrEnum):
+    """Initial approved tabular model families."""
+
+    LOGISTIC_REGRESSION = "logistic_regression"
+    RANDOM_FOREST = "random_forest"
+    XGBOOST = "xgboost"
+    LIGHTGBM = "lightgbm"
+    CATBOOST = "catboost"
+    LINEAR_SVM = "linear_svm"
+    MLP = "mlp"
+
+
+class SplitStrategyType(StrEnum):
+    """Dataset splitting strategies."""
+
+    TRAIN_TEST_SPLIT = "train_test_split"
+    K_FOLD = "k_fold"
+    STRATIFIED_K_FOLD = "stratified_k_fold"
+    TIME_SERIES_SPLIT = "time_series_split"
+
+
+class SplitStrategy(BaseModel):
+    """Configuration for splitting dataset into training and evaluation partitions."""
+
+    strategy: SplitStrategyType = SplitStrategyType.TRAIN_TEST_SPLIT
+    test_size: float = Field(
+        default=0.2, ge=0.05, le=0.5, description="Fraction of data reserved for testing"
+    )
+    n_splits: int = Field(
+        default=5, ge=2, le=20, description="Folds for cross-validation strategies"
+    )
+    shuffle: bool = True
+    random_seed: int = Field(default=42, ge=0)
+
+
+class EvaluationConfig(BaseModel):
+    """Evaluation metrics configuration."""
+
+    primary_metric: str = Field(..., description="Target optimization and reporting metric")
+    additional_metrics: list[str] = Field(default_factory=list)
+
+
+class ResourcePolicy(BaseModel):
+    """Hardware quotas and execution bounds for worker isolation."""
+
+    max_runtime_seconds: int = Field(default=1800, ge=10, le=7200)
+    max_memory_mb: int = Field(default=4096, ge=256, le=32768)
+    max_cpu_cores: int = Field(default=2, ge=1, le=16)
+
+
+class ExperimentStatus(StrEnum):
+    """Lifecycle states of an ML experiment."""
+
+    CREATED = "CREATED"
+    VALIDATING = "VALIDATING"
+    REJECTED = "REJECTED"
+    QUEUED = "QUEUED"
+    RUNNING = "RUNNING"
+    SUCCEEDED = "SUCCEEDED"
+    FAILED = "FAILED"
+    CANCEL_REQUESTED = "CANCEL_REQUESTED"
+    CANCELLED = "CANCELLED"
+    ANALYZING = "ANALYZING"
+    ANALYSIS_READY = "ANALYSIS_READY"
+
+
+class ExperimentSpec(BaseModel):
+    """Complete, immutable experiment specification defining reproducible execution."""
+
+    tenant_id: str = Field(..., min_length=1)
+    project_id: str = Field(..., min_length=1)
+    dataset_version_id: str = Field(..., min_length=1)
+    model_version_id: str = Field(..., min_length=1)
+    task_type: TaskType
+    target_column: str = Field(..., min_length=1)
+    feature_columns: list[str] | None = None
+    split_strategy: SplitStrategy = Field(default_factory=SplitStrategy)
+    evaluation_config: EvaluationConfig
+    hyperparameters: dict[str, Any] = Field(default_factory=dict)
+    resource_policy: ResourcePolicy = Field(default_factory=ResourcePolicy)
+    random_seed: int = Field(default=42, ge=0)
+    idempotency_key: str | None = None
+    created_by: str = Field(..., min_length=1)
+
+    @model_validator(mode="after")
+    def validate_metrics_compatible_with_task(self) -> "ExperimentSpec":
+        classification_metrics = {
+            "accuracy",
+            "f1",
+            "f1_macro",
+            "f1_weighted",
+            "precision",
+            "recall",
+            "roc_auc",
+            "pr_auc",
+            "log_loss",
+            "brier_score",
+        }
+        regression_metrics = {"mse", "rmse", "mae", "r2", "mape", "explained_variance"}
+
+        pm = self.evaluation_config.primary_metric.lower()
+        if (
+            self.task_type in (TaskType.BINARY_CLASSIFICATION, TaskType.MULTICLASS_CLASSIFICATION)
+            and pm in regression_metrics
+            and pm not in classification_metrics
+        ):
+            raise ValueError(f"Metric '{pm}' is not compatible with classification task")
+        if (
+            self.task_type == TaskType.REGRESSION
+            and pm in classification_metrics
+            and pm not in regression_metrics
+        ):
+            raise ValueError(f"Metric '{pm}' is not compatible with regression task")
+
+        return self

ml_mcp/domain/value_objects/model.py

@@ -0,0 +1,48 @@
+"""Model registry value objects and constraints."""
+
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from ml_mcp.domain.value_objects.experiment import ModelFamily, TaskType
+
+
+class ApprovalStatus(StrEnum):
+    """Approval lifecycle of registered models."""
+
+    PENDING = "PENDING"
+    APPROVED = "APPROVED"
+    REJECTED = "REJECTED"
+    REVOKED = "REVOKED"
+
+
+class HyperparameterConstraint(BaseModel):
+    """Schema constraint definition for a model hyperparameter."""
+
+    name: str
+    type: str  # "int", "float", "str", "bool"
+    default: Any
+    min_value: float | int | None = None
+    max_value: float | int | None = None
+    allowed_values: list[Any] | None = None
+    description: str = ""
+
+
+class ModelMetadata(BaseModel):
+    """Immutable model architecture specification in the catalog."""
+
+    model_id: str = Field(..., min_length=1)
+    version: str = Field(..., min_length=1)
+    name: str = Field(..., min_length=1)
+    description: str = ""
+    family: ModelFamily
+    supported_task_types: list[TaskType]
+    approval_status: ApprovalStatus = ApprovalStatus.PENDING
+    container_image_digest: str = Field(
+        ..., description="SHA-256 digest of verified worker container image"
+    )
+    artifact_digest: str | None = None
+    supported_hyperparameters: list[HyperparameterConstraint] = Field(default_factory=list)
+    license: str = "Apache-2.0"
+    publisher: str = "ModelLab"

ml_mcp/infrastructure/__init__.py

@@ -0,0 +1 @@
+"""Infrastructure layer package."""

ml_mcp/infrastructure/object_storage/__init__.py

@@ -0,0 +1,5 @@
+"""Object storage package."""
+
+from ml_mcp.infrastructure.object_storage.s3 import S3StorageService, get_storage_service
+
+__all__ = ["S3StorageService", "get_storage_service"]