Updated schemas as per new spec sheet

Author: pulk17

mod_api/schemas/auth.py

@@ -1,22 +1,21 @@
-"""Request/response schemas for token endpoints."""
+"""Request/response schemas for the token endpoints."""
 
 from marshmallow import RAISE, Schema, fields, validate
 
 from mod_api.models.api_token import VALID_SCOPES
 
 
 class TokenCreateRequestSchema(Schema):
-    """Schema for POST /auth/tokens request body."""
+    """Validates POST /auth/tokens bodies."""
 
     email = fields.Email(required=True)
     password = fields.String(
         required=True,
-        validate=validate.Length(min=5, max=128),
+        validate=validate.Length(min=8, max=128),
     )
     token_name = fields.String(
         required=True,
         validate=[
-            
             validate.Length(min=1, max=50),
             validate.Regexp(
                 r'^[a-zA-Z0-9_\-]+$',
@@ -25,8 +24,8 @@ class TokenCreateRequestSchema(Schema):
         ],
     )
     expires_in_days = fields.Integer(
-        load_default=30,
-        validate=validate.Range(min=1, max=90),
+        load_default=7,
+        validate=validate.Range(min=1, max=30),
     )
     scopes = fields.List(
         fields.String(validate=validate.OneOf(VALID_SCOPES)),
@@ -35,14 +34,31 @@ class TokenCreateRequestSchema(Schema):
     )
 
     class Meta:
-        unknown = RAISE  # Reject unknown fields
+        unknown = RAISE
 
 
 class AuthTokenSchema(Schema):
-    """Schema for serializing the created token response."""
+    """The one-time response returned when a token is created."""
 
     token = fields.String(required=True)
     token_type = fields.String(dump_default='bearer')
     token_name = fields.String(required=True)
     scopes = fields.List(fields.String(), required=True)
     expires_at = fields.DateTime(required=True)
+
+
+class ApiTokenItemSchema(Schema):
+    """Token metadata for list responses — never includes the plaintext value."""
+
+    id = fields.Integer(required=True)
+    user_id = fields.Integer(required=True)
+    token_name = fields.String(required=True)
+    token_prefix = fields.String(required=True)
+    scopes = fields.Method('get_scopes')
+    created_at = fields.DateTime(required=True)
+    expires_at = fields.DateTime(required=True)
+    is_revoked = fields.Boolean(required=True)
+    revoked_at = fields.DateTime(allow_none=True)
+
+    def get_scopes(self, obj):
+        return obj.scopes

mod_api/schemas/common.py

@@ -1,10 +1,10 @@
-"""Common schemas: ErrorResponse, pagination wrappers."""
+"""Shared schemas: ErrorResponse and pagination wrappers."""
 
 from marshmallow import Schema, fields
 
 
 class ErrorResponseSchema(Schema):
-    """Standard error response body."""
+    """Standard JSON error body returned by all error responses."""
     code = fields.String(required=True)
     message = fields.String(required=True)
     details = fields.Dict(keys=fields.String(), required=True, load_default={})

mod_api/schemas/errors.py

@@ -1,10 +1,10 @@
-"""Schemas for error items, error summaries, and log lines."""
+"""Schemas for error items, error summary buckets, and log lines."""
 
 from marshmallow import Schema, fields, validate
 
 
 class ErrorItemSchema(Schema):
-    """A single error derived from run results."""
+    """A single error derived from run results or infra progress."""
     error_id = fields.String(required=True)
     run_id = fields.Integer(required=True)
     sample_id = fields.Integer(allow_none=True)

mod_api/schemas/results.py

@@ -4,10 +4,15 @@
 
 
 class OutputFileContentSchema(Schema):
-    """File content blob (expected or actual output)."""
+    """File content blob returned for expected or actual output."""
+    run_id = fields.Integer(allow_none=True)
+    sample_id = fields.Integer(required=True)
+    regression_id = fields.Integer(required=True)
+    output_id = fields.Integer(required=True)
     filename = fields.String(required=True)
-    content = fields.String(required=True)
+    content_type = fields.String(required=True)
     encoding = fields.String(required=True, validate=validate.OneOf(['utf-8', 'base64']))
+    content = fields.String(required=True)
     sha256 = fields.String(allow_none=True)
     storage_status = fields.String(
         required=True,
@@ -17,49 +22,61 @@ class OutputFileContentSchema(Schema):
 
 class DiffHunkLineSchema(Schema):
     """One line inside a diff hunk."""
-    type = fields.String(required=True, validate=validate.OneOf(['add', 'delete', 'context']))
-    content = fields.String(required=True)
+    kind = fields.String(required=True, validate=validate.OneOf(['context', 'added', 'removed']))
+    expected_line = fields.Integer(allow_none=True)
+    actual_line = fields.Integer(allow_none=True)
+    text = fields.String(required=True)
 
 
 class DiffHunkSchema(Schema):
-    """A contiguous block of changes in a diff."""
-    header = fields.String(required=True)
+    """A contiguous block of changes."""
+    expected_start = fields.Integer(required=True)
+    actual_start = fields.Integer(required=True)
     lines = fields.List(fields.Nested(DiffHunkLineSchema), required=True)
 
 
 class DiffSchema(Schema):
     """Structured diff between expected and actual output."""
+    run_id = fields.Integer(required=True)
+    sample_id = fields.Integer(required=True)
+    regression_id = fields.Integer(required=True)
+    output_id = fields.Integer(required=True)
     status = fields.String(required=True, validate=validate.OneOf([
         'identical', 'different', 'missing_actual', 'missing_expected',
     ]))
-    expected_sha256 = fields.String(allow_none=True)
-    actual_sha256 = fields.String(allow_none=True)
-    stats = fields.Dict(required=True)
+    summary = fields.Dict(required=True)
     hunks = fields.List(fields.Nested(DiffHunkSchema), required=True)
 
 
 class BaselineApprovalRequestSchema(Schema):
     """POST /runs/{id}/samples/{sid}/baseline-approval body."""
-    reason = fields.String(
+    regression_id = fields.Integer(
         required=True,
-        validate=validate.Length(min=10, max=1000),
+        validate=validate.Range(min=1),
     )
     output_id = fields.Integer(
-        load_default=None,
+        required=True,
         validate=validate.Range(min=1),
     )
-    apply_to_variants = fields.Boolean(load_default=False)
+    reason = fields.String(
+        required=True,
+        validate=validate.Length(min=10, max=500),
+    )
+    remove_variants = fields.Boolean(
+        load_default=False,
+    )
 
     class Meta:
         unknown = RAISE
 
 
 class BaselineApprovalSchema(Schema):
-    """Response after submitting a baseline approval request."""
+    """Response after a baseline approval is applied."""
     approval_id = fields.String(required=True)
-    status = fields.String(required=True, validate=validate.OneOf([
-        'pending_review', 'approved', 'rejected',
-    ]))
+    status = fields.String(required=True, validate=validate.OneOf(['approved']))
+    run_id = fields.Integer(required=True)
+    sample_id = fields.Integer(required=True)
+    regression_id = fields.Integer(required=True)
+    output_id = fields.Integer(required=True)
     requested_by = fields.String(required=True)
-    reason = fields.String(required=True)
     created_at = fields.DateTime(required=True)

mod_api/schemas/runs.py

@@ -1,4 +1,4 @@
-"""Schemas for runs, run summaries, progress events, and run actions."""
+"""Schemas for runs, summaries, progress events, and run actions."""
 
 from marshmallow import RAISE, Schema, fields, validate
 
@@ -8,41 +8,44 @@ class ProgressEventSchema(Schema):
     timestamp = fields.DateTime(required=True)
     status = fields.String(required=True)
     message = fields.String(required=True)
+    step = fields.Integer(allow_none=True)
 
 
 class RunSchema(Schema):
-    """Full run representation."""
+    """Full run details."""
     run_id = fields.Integer(required=True)
     status = fields.String(required=True, validate=validate.OneOf([
         'queued', 'running', 'pass', 'fail', 'canceled', 'error', 'incomplete',
     ]))
     platform = fields.String(required=True, validate=validate.OneOf(['linux', 'windows']))
-    test_type = fields.String(required=True, validate=validate.OneOf(['commit', 'pr']))
+    test_type = fields.String(validate=validate.OneOf(['commit', 'pr']))
     repository = fields.String(required=True)
-    branch = fields.String(required=True)
+    branch = fields.String(allow_none=True)
     commit_sha = fields.String(required=True)
     pr_number = fields.Integer(allow_none=True, load_default=None)
-    created_at = fields.DateTime(allow_none=True)
+    created_at = fields.DateTime(required=True)
     queued_at = fields.DateTime(allow_none=True)
     started_at = fields.DateTime(allow_none=True)
     completed_at = fields.DateTime(allow_none=True)
     github_link = fields.String(allow_none=True)
 
 
 class RunSummarySchema(Schema):
-    """Aggregated pass/fail counts for a run."""
+    """Pass/fail/skip aggregate counts for a run."""
     run_id = fields.Integer(required=True)
     status = fields.String(required=True)
     total_samples = fields.Integer(required=True)
     pass_count = fields.Integer(required=True)
     fail_count = fields.Integer(required=True)
-    skip_count = fields.Integer(required=True)
+    skipped_count = fields.Integer(required=True)
     missing_output_count = fields.Integer(required=True)
-    runtime_ms = fields.Integer(allow_none=True)
+    error_count = fields.Integer(load_default=0)
+    duration_ms = fields.Integer(allow_none=True)
+    triggered_by = fields.String(allow_none=True)
 
 
 class RunConfigSchema(Schema):
-    """The configuration used to launch a run."""
+    """The test matrix and configuration for a run."""
     run_id = fields.Integer(required=True)
     platform = fields.String(required=True)
     branch = fields.String(required=True)
@@ -83,6 +86,11 @@ class RunCreateRequestSchema(Schema):
             ),
         ],
     )
+    pull_request = fields.Integer(
+        load_default=None,
+        allow_none=True,
+        validate=validate.Range(min=1),
+    )
     regression_test_ids = fields.List(
         fields.Integer(validate=validate.Range(min=1)),
         load_default=None,
@@ -94,7 +102,7 @@ class Meta:
 
 
 class RunActionResultSchema(Schema):
-    """Response for cancel/retry actions."""
+    """Response for cancel and similar run actions."""
     run_id = fields.Integer(required=True)
     new_run_id = fields.Integer(allow_none=True)
     action = fields.String(required=True)

mod_api/schemas/samples.py

@@ -1,4 +1,4 @@
-"""Schemas for samples, run sample results, history entries, and regression tests."""
+"""Schemas for samples, per-run sample results, history, and regression tests."""
 
 from marshmallow import Schema, fields, validate
 
@@ -13,7 +13,7 @@ class OutputFileSchema(Schema):
 
 
 class RunSampleSchema(Schema):
-    """A sample's result within a specific run."""
+    """A regression test's result within a specific run."""
     regression_test_id = fields.Integer(required=True)
     sample_id = fields.Integer(allow_none=True)
     sample_name = fields.String(allow_none=True)
@@ -29,7 +29,7 @@ class RunSampleSchema(Schema):
 
 
 class SampleSchema(Schema):
-    """A media sample from the sample catalog."""
+    """A media sample from the catalog."""
     sample_id = fields.Integer(required=True)
     sha = fields.String(required=True)
     extension = fields.String(required=True)

mod_api/schemas/system.py

@@ -1,17 +1,17 @@
-"""System schemas for health, queue, branches, environments, and artifacts."""
+"""Schemas for health checks, queue jobs, and run artifacts."""
 
 from marshmallow import Schema, fields, validate
 
 
 class DependencyHealthSchema(Schema):
-    """Schema for a single system dependency status."""
+    """Status of a single system dependency (DB, GCS, local storage)."""
     name = fields.String(required=True)
     status = fields.String(required=True, validate=validate.OneOf(['ok', 'degraded', 'down']))
     message = fields.String(allow_none=True)
 
 
 class SystemHealthSchema(Schema):
-    """Schema for the overall system health response."""
+    """Overall system health response."""
     status = fields.String(
         required=True,
         validate=validate.OneOf(['ok', 'degraded', 'down']),
@@ -21,41 +21,25 @@ class SystemHealthSchema(Schema):
 
 
 class QueueJobSchema(Schema):
-    """Schema for a single job in the queue."""
+    """A single queued or running job."""
     run_id = fields.Integer(required=True)
     status = fields.String(required=True, validate=validate.OneOf(['queued', 'running']))
     platform = fields.String(required=True, validate=validate.OneOf(['linux', 'windows']))
-    queued_at = fields.DateTime(required=True)
+    queued_at = fields.DateTime(allow_none=True)
     started_at = fields.DateTime(allow_none=True)
     position = fields.Integer(allow_none=True)
 
 
-class BranchSchema(Schema):
-    """Schema for a tracked branch."""
-    repository = fields.String(required=True)
-    name = fields.String(required=True)
-    head_sha = fields.String(allow_none=True)
-    active = fields.Boolean(required=True)
-
-
-class EnvironmentSchema(Schema):
-    """Schema for a test environment."""
-    environment_id = fields.String(required=True)
-    platform = fields.String(required=True, validate=validate.OneOf(['linux', 'windows']))
-    active = fields.Boolean(required=True)
-    runner_label = fields.String(allow_none=True)
-    average_duration_ms = fields.Integer(allow_none=True)
-
-
 class ArtifactSchema(Schema):
-    """Schema for a run artifact."""
+    """A downloadable artifact tied to a run."""
     artifact_id = fields.String(required=True)
     run_id = fields.Integer(required=True)
     sample_id = fields.Integer(allow_none=True)
     type = fields.String(
         required=True,
         validate=validate.OneOf([
-            'build_log', 'sample_output', 'expected_output', 'diff', 'media_info', 'binary',
+            'build_log', 'sample_output', 'expected_output', 'actual_output',
+            'diff', 'media_info', 'binary', 'coredump', 'combined_stdout',
         ]),
     )
     filename = fields.String(required=True)