synapse-result-schemas

name	synapse-result-schemas
description	Explains result schema classes for Synapse plugin actions. Use when the user mentions "TrainResult", "InferenceResult", "ExportResult", "UploadResult", "WeightsResult", "MetricsResult", "result_model", "result schema", or needs help with action return type validation.

Result Schemas

Synapse SDK provides standardized result schema classes for common action outputs. These provide type-safe, validated return types for actions.

Available Result Schemas

from synapse_sdk.plugins.schemas import (
    TrainResult,
    InferenceResult,
    ExportResult,
    UploadResult,
    WeightsResult,
    MetricsResult,
)

Schema	Purpose
TrainResult	Training output with weights and metrics
InferenceResult	Inference predictions
ExportResult	Data export output
UploadResult	File upload results
WeightsResult	Model weights only
MetricsResult	Evaluation metrics only

Quick Usage

With Class-Based Actions

from synapse_sdk.plugins.actions.train import BaseTrainAction
from synapse_sdk.plugins.schemas import TrainResult

class MyTrainAction(BaseTrainAction[TrainParams]):
    result_model = TrainResult  # Enable result validation

    def execute(self) -> TrainResult:
        # ... training ...
        return TrainResult(
            weights_path='/models/best.pt',
            final_epoch=100,
            train_metrics={'loss': 0.05},
            val_metrics={'mAP50': 0.85},
        )

With Function-Based Actions

from synapse_sdk.plugins.decorators import action
from synapse_sdk.plugins.schemas import InferenceResult

@action(name='infer', result=InferenceResult)
def infer(params: InferParams, ctx: RuntimeContext) -> InferenceResult:
    return InferenceResult(
        predictions=[{'class': 'dog', 'confidence': 0.95}],
        processed_count=100,
    )

Schema Details

TrainResult

class TrainResult(BaseModel):
    weights_path: str            # Path to trained model
    final_epoch: int             # Last completed epoch
    best_epoch: int | None       # Best epoch by val metric
    train_metrics: dict = {}     # Final training metrics
    val_metrics: dict = {}       # Final validation metrics

InferenceResult

class InferenceResult(BaseModel):
    predictions: list[dict] = [] # Prediction results
    processed_count: int = 0     # Items processed
    output_path: str | None      # Output file path

ExportResult

class ExportResult(BaseModel):
    output_path: str             # Export path
    exported_count: int          # Items exported
    format: str                  # Export format
    file_size_bytes: int | None  # File size

UploadResult

class UploadResult(BaseModel):
    uploaded_count: int          # Items uploaded
    remote_path: str | None      # Remote URL/path
    status: str = 'completed'    # Upload status

WeightsResult

class WeightsResult(BaseModel):
    weights_path: str            # Best/final weights path
    checkpoint_paths: list = []  # Intermediate checkpoints
    format: str = 'pt'           # Weights format

MetricsResult

class MetricsResult(BaseModel):
    metrics: dict[str, float]    # Metric values
    category: str = 'default'    # Metrics category

Detailed References

• references/train-result.md - TrainResult, WeightsResult
• references/inference-result.md - InferenceResult
• references/other-results.md - ExportResult, UploadResult, MetricsResult