fraclab-sdk 0.1.0__py3-none-any.whl

fraclab_sdk/models/drs.py

@@ -0,0 +1,47 @@
+"""DRS (Data Requirement Specification) model."""
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class DRSDataset(BaseModel):
+    """A dataset requirement in a DRS."""
+
+    model_config = ConfigDict(extra="ignore", populate_by_name=True)
+
+    datasetKey: str = Field(alias="key")
+    resourceType: str | None = Field(default=None, alias="resource")
+    cardinality: Literal["one", "many", "zeroOrMany"] = "many"
+    description: str | None = None
+
+
+class DRS(BaseModel):
+    """Data Requirement Specification.
+
+    Defines what data an algorithm requires as input.
+    """
+
+    model_config = ConfigDict(extra="ignore", populate_by_name=True)
+
+    schemaVersion: str | None = None
+    datasets: list[DRSDataset] = Field(default_factory=list)
+
+    @field_validator("datasets", mode="before")
+    @classmethod
+    def _coerce_datasets(cls, v):
+        """Accept mapping form {'key': {...}} by converting to list."""
+        if isinstance(v, dict):
+            return [{"key": k, **(val or {})} for k, val in v.items()]
+        return v
+
+    def get_dataset(self, dataset_key: str) -> DRSDataset | None:
+        """Get a dataset requirement by key."""
+        for ds in self.datasets:
+            if ds.datasetKey == dataset_key:
+                return ds
+        return None
+
+    def get_dataset_keys(self) -> list[str]:
+        """Get all required dataset keys."""
+        return [ds.datasetKey for ds in self.datasets]

fraclab_sdk/models/output_contract.py

@@ -0,0 +1,111 @@
+"""OutputContract model aligned with OutputSpec documentation."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# ---------------------------------------------------------------------------
+# Schemas
+# ---------------------------------------------------------------------------
+
+
+class ScalarOutputSchema(BaseModel):
+    """Schema for scalar outputs."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    type: Literal["scalar"]
+    dtype: str | None = None
+    precision: int | None = None
+
+
+class FrameOutputSchema(BaseModel):
+    """Schema for frame (tabular) outputs."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    type: Literal["frame"]
+    index: Literal["time", "depth", "none"] | None = None
+    # allow extra fields for forward-compatibility
+
+
+class ObjectOutputSchema(BaseModel):
+    """Schema for structured object outputs."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    type: Literal["object"]
+    # keep open for schema details
+
+
+class BlobOutputSchema(BaseModel):
+    """Schema for blob outputs."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    type: Literal["blob"]
+    mime: str | None = None
+    ext: str | None = None
+
+
+OutputSchema = ScalarOutputSchema | FrameOutputSchema | ObjectOutputSchema | BlobOutputSchema
+
+# ---------------------------------------------------------------------------
+# Contracts
+# ---------------------------------------------------------------------------
+
+OwnerType = Literal["stage", "well", "platform"]
+Cardinality = Literal["one", "many"]
+DatasetKind = Literal["frame", "object", "blob", "scalar"]
+DatasetRole = Literal["primary", "supporting", "debug"]
+
+
+class OutputDatasetContract(BaseModel):
+    """Dataset-level contract (declares a named output channel)."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    key: str
+    kind: DatasetKind
+    owner: OwnerType
+    cardinality: Cardinality = "many"
+    required: bool = True
+    schema: OutputSchema | dict[str, Any]
+    role: DatasetRole | None = None
+    groupPath: list[str] | None = None
+    dimensions: list[str] = Field(default_factory=list)
+    description: str | None = None
+
+
+class OutputContract(BaseModel):
+    """Full output contract for an algorithm."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    datasets: list[OutputDatasetContract] = Field(default_factory=list)
+    invariants: list[dict[str, Any]] = Field(default_factory=list)
+    relations: list[dict[str, Any]] = Field(default_factory=list)
+
+    def get_dataset(self, key: str) -> OutputDatasetContract | None:
+        """Get dataset by key."""
+        for ds in self.datasets:
+            if ds.key == key:
+                return ds
+        return None
+
+
+__all__ = [
+    "OutputSchema",
+    "ScalarOutputSchema",
+    "FrameOutputSchema",
+    "ObjectOutputSchema",
+    "BlobOutputSchema",
+    "OutputDatasetContract",
+    "OutputContract",
+    "OwnerType",
+    "DatasetKind",
+    "Cardinality",
+    "DatasetRole",
+]

fraclab_sdk/models/run_output_manifest.py

@@ -0,0 +1,119 @@
+"""Run output manifest model aligned with OutputSpec."""
+
+from typing import Any
+
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field
+
+
+class RunInfo(BaseModel):
+    """Information about a run."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    runId: str
+    algorithmId: str
+    contractVersion: str | None = None
+    codeVersion: str | None = None
+
+
+class OwnerRef(BaseModel):
+    """Owner reference for an item."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    platformId: str | None = None
+    wellId: str | None = None
+    stageId: str | None = None
+
+
+class ArtifactInfo(BaseModel):
+    """Information about an output artifact."""
+
+    model_config = ConfigDict(extra="ignore", populate_by_name=True)
+
+    artifactKey: str
+    type: str = Field(
+        validation_alias=AliasChoices("type", "artifactType"),
+        serialization_alias="type",
+    )  # e.g., "scalar", "blob", "json", "frame", "parquet"
+    uri: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("uri", "fileUri"),
+        serialization_alias="uri",
+    )
+    mimeType: str | None = None
+    description: str | None = None
+    value: Any | None = None  # For scalar artifacts
+    inline: dict[str, Any] | None = None  # Optional embedded payload
+
+    @property
+    def artifactType(self) -> str:
+        """Backward-compatible accessor for artifact type."""
+        return self.type
+
+    @property
+    def fileUri(self) -> str | None:
+        """Backward-compatible accessor for file URI."""
+        return self.uri
+
+
+class RunOutputItem(BaseModel):
+    """Single item within a dataset."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    itemKey: str | None = Field(default=None, alias="key")
+    owner: OwnerRef | None = None
+    dims: dict[str, Any] = Field(default_factory=dict)
+    meta: dict[str, Any] = Field(default_factory=dict)
+    inline: dict[str, Any] | None = None
+    artifact: ArtifactInfo
+
+
+class RunOutputDataset(BaseModel):
+    """Output dataset in run output manifest."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    datasetKey: str
+    items: list[RunOutputItem] = Field(default_factory=list)
+
+
+class RunOutputManifest(BaseModel):
+    """Manifest for run output."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    schemaVersion: str | None = None
+    run: RunInfo
+    status: str | None = None
+    error: str | None = None
+    startedAt: str | None = None
+    completedAt: str | None = None
+    datasets: list[RunOutputDataset] = Field(default_factory=list)
+
+    def get_artifact(self, artifact_key: str) -> ArtifactInfo | None:
+        """Get an artifact by key (searches all datasets)."""
+        for dataset in self.datasets:
+            for item in dataset.items:
+                if item.artifact.artifactKey == artifact_key:
+                    return item.artifact
+        return None
+
+    def list_all_artifacts(self) -> list[ArtifactInfo]:
+        """List all artifacts from all datasets."""
+        all_artifacts: list[ArtifactInfo] = []
+        for dataset in self.datasets:
+            for item in dataset.items:
+                all_artifacts.append(item.artifact)
+        return all_artifacts
+
+
+__all__ = [
+    "RunInfo",
+    "OwnerRef",
+    "ArtifactInfo",
+    "RunOutputItem",
+    "RunOutputDataset",
+    "RunOutputManifest",
+]

fraclab_sdk/results/__init__.py

@@ -0,0 +1,25 @@
+"""Result reading and preview."""
+
+from fraclab_sdk.results.preview import (
+    get_artifact_preview_type,
+    preview_image,
+    preview_json_raw,
+    preview_json_table,
+    preview_scalar,
+)
+from fraclab_sdk.results.reader import (
+    ArtifactWithPath,
+    ResultReader,
+    file_uri_to_path,
+)
+
+__all__ = [
+    "ArtifactWithPath",
+    "ResultReader",
+    "file_uri_to_path",
+    "get_artifact_preview_type",
+    "preview_image",
+    "preview_json_raw",
+    "preview_json_table",
+    "preview_scalar",
+]

fraclab_sdk/results/preview.py

@@ -0,0 +1,150 @@
+"""Preview helpers for result artifacts."""
+
+import json
+from pathlib import Path
+from typing import Any
+
+from fraclab_sdk.models import ArtifactInfo
+from fraclab_sdk.results.reader import file_uri_to_path
+
+
+def preview_scalar(artifact: ArtifactInfo) -> Any:
+    """Preview a scalar artifact.
+
+    Args:
+        artifact: The artifact info.
+
+    Returns:
+        The scalar value or None.
+    """
+    if artifact.artifactType != "scalar":
+        return None
+    return artifact.value
+
+
+def preview_image(artifact: ArtifactInfo) -> Path | None:
+    """Get image path for preview.
+
+    Args:
+        artifact: The artifact info.
+
+    Returns:
+        Path to image file or None if not an image.
+    """
+    if artifact.artifactType != "blob":
+        return None
+
+    if artifact.mimeType and not artifact.mimeType.startswith("image/"):
+        return None
+
+    if artifact.fileUri:
+        return file_uri_to_path(artifact.fileUri)
+
+    return None
+
+
+def preview_json_table(artifact: ArtifactInfo) -> dict | None:
+    """Preview JSON artifact as table data.
+
+    For array of objects, extracts columns and rows for table display.
+    Format: {"columns": [...], "rows": [[...], ...]}
+
+    Args:
+        artifact: The artifact info.
+
+    Returns:
+        Table data dict or None if not suitable for table display.
+    """
+    if artifact.artifactType not in {"json", "object"}:
+        return None
+
+    if not artifact.fileUri:
+        return None
+
+    path = file_uri_to_path(artifact.fileUri)
+    data = json.loads(path.read_text())
+
+    # Handle array of objects
+    if isinstance(data, list) and len(data) > 0 and isinstance(data[0], dict):
+        # Extract columns from first object
+        columns = list(data[0].keys())
+
+        # Extract rows
+        rows = []
+        for item in data:
+            if isinstance(item, dict):
+                row = [item.get(col) for col in columns]
+                rows.append(row)
+
+        return {"columns": columns, "rows": rows}
+
+    # Handle single object
+    if isinstance(data, dict):
+        columns = ["key", "value"]
+        rows = [[k, v] for k, v in data.items()]
+        return {"columns": columns, "rows": rows}
+
+    return None
+
+
+def preview_json_raw(artifact: ArtifactInfo, max_lines: int = 50) -> str | None:
+    """Preview raw JSON content.
+
+    Args:
+        artifact: The artifact info.
+        max_lines: Maximum lines to return.
+
+    Returns:
+        Pretty-printed JSON string or None.
+    """
+    if artifact.artifactType != "json":
+        return None
+
+    if not artifact.fileUri:
+        return None
+
+    path = file_uri_to_path(artifact.fileUri)
+    data = json.loads(path.read_text())
+    formatted = json.dumps(data, indent=2)
+
+    lines = formatted.split("\n")
+    if len(lines) > max_lines:
+        lines = lines[:max_lines]
+        lines.append(f"... ({len(formatted.split(chr(10))) - max_lines} more lines)")
+
+    return "\n".join(lines)
+
+
+def get_artifact_preview_type(artifact: ArtifactInfo) -> str:
+    """Determine the best preview type for an artifact.
+
+    Args:
+        artifact: The artifact info.
+
+    Returns:
+        Preview type: "scalar", "image", "json_table", "json_raw", "file", or "none".
+    """
+    if artifact.artifactType == "scalar":
+        return "scalar"
+
+    if artifact.artifactType == "blob":
+        if artifact.mimeType and artifact.mimeType.startswith("image/"):
+            return "image"
+        return "file"
+
+    if artifact.artifactType in {"json", "object"}:
+        # Check if suitable for table display
+        if artifact.fileUri:
+            try:
+                path = file_uri_to_path(artifact.fileUri)
+                data = json.loads(path.read_text())
+                if isinstance(data, list) and len(data) > 0 and isinstance(data[0], dict):
+                    return "json_table"
+            except Exception:
+                pass
+        return "json_raw"
+
+    if artifact.artifactType in {"frame", "parquet"}:
+        return "file"
+
+    return "none"