ms-markets 2.2.4.dev14__tar.gz → 2.2.5.dev15__tar.gz

{ms_markets-2.2.4.dev14 → ms_markets-2.2.5.dev15}/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project follows versioned releases.
 
 ## [Unreleased]
 
+## [2.2.5] - 2026-10-04
+
+### Fixed
+
+- `TabularFrameResponse` and its field, source, time-series and table-visual
+  models omit unset optional fields instead of serializing them as `null`,
+  which the `core.tabular_frame@v1` schema rejects. A plain dump of
+  `build_tabular_frame(...)` failed the schema on `error`, `meta`, `source`
+  and the field `label`, `provenance`, `derivedFrom` and `warnings`; only routes
+  declared with `response_model_exclude_none=True`, as every ms-markets frame
+  route is, returned a valid frame. `null` cell values in `rows` are kept. A
+  test fails if any optional field of the bulk-action, resource-collection or
+  tabular-frame contract models serializes as `null`, other than
+  `BulkDeletePreflightResponse.impact`, and the Command Center connection
+  contract is validated against the Adapter from API discovery schema.
+
 ## [2.2.4] - 2026-10-04
 
 ### Fixed

{ms_markets-2.2.4.dev14 → ms_markets-2.2.5.dev15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ms-markets
-Version: 2.2.4.dev14
+Version: 2.2.5.dev15
 Summary: Financial markets ORM, engines, and application management extensions for Main Sequence.
 Project-URL: Changelog, https://github.com/mainsequence-projects/MainSequenceMarkets/blob/main/CHANGELOG.md
 Project-URL: Source, https://github.com/mainsequence-projects/MainSequenceMarkets

{ms_markets-2.2.4.dev14 → ms_markets-2.2.5.dev15}/docs/fast_api/v1/provider_adapter_toolkit.md

@@ -45,6 +45,11 @@ transform consumers read. A route that returns a frame declares it with
 `openapi_extra={"x-ui-contract": CORE_TABULAR_FRAME_CONTRACT}`; Adapter from API
 discovery reads the contract from that declaration only.
 
+The contract models omit unset optional fields instead of serializing them as
+`null`, which the Command Center schemas reject, so a route does not need
+`response_model_exclude_none`. `null` cell values in `rows` are kept. The
+bulk-action and resource-collection models follow the same rule.
+
 ## Bulk actions and preflight
 
 The public package contains the Command Center execution and preflight models,

{ms_markets-2.2.4.dev14 → ms_markets-2.2.5.dev15}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ms-markets"
-version = "2.2.4.dev14"
+version = "2.2.5.dev15"
 description = "Financial markets ORM, engines, and application management extensions for Main Sequence."
 readme = "README.md"
 requires-python = ">=3.13,<3.14"

{ms_markets-2.2.4.dev14 → ms_markets-2.2.5.dev15}/src/msm/api/http/tabular.py

@@ -26,25 +26,35 @@ TabularFrameFieldType = Literal[
 TabularFrameFieldProvenance = Literal["backend", "manual", "inferred", "derived"]
 
 
+def _omit_unset(**constraints: Any) -> Any:
+    """Declare an optional field that the payload omits while it is unset.
+
+    The ``core.tabular_frame@v1`` schema rejects ``null`` for these fields, so a frame
+    stays valid without ``response_model_exclude_none``.
+    """
+
+    return Field(default=None, exclude_if=lambda value: value is None, **constraints)
+
+
 class TabularFrameFieldResponse(HttpContractModel):
     key: str
     type: TabularFrameFieldType
-    label: str | None = None
-    description: str | None = None
-    nullable: bool | None = None
-    nativeType: str | None = None
-    provenance: TabularFrameFieldProvenance | None = None
-    reason: str | None = None
-    derivedFrom: list[str] | None = None
-    warnings: list[str] | None = None
+    label: str | None = _omit_unset()
+    description: str | None = _omit_unset()
+    nullable: bool | None = _omit_unset()
+    nativeType: str | None = _omit_unset()
+    provenance: TabularFrameFieldProvenance | None = _omit_unset()
+    reason: str | None = _omit_unset()
+    derivedFrom: list[str] | None = _omit_unset()
+    warnings: list[str] | None = _omit_unset()
 
 
 class TabularFrameSourceResponse(HttpContractModel):
     kind: str
-    id: str | int | float | None = None
-    label: str | None = None
-    updatedAtMs: int | None = None
-    context: dict[str, Any] | None = None
+    id: str | int | float | None = _omit_unset()
+    label: str | None = _omit_unset()
+    updatedAtMs: int | None = _omit_unset()
+    context: dict[str, Any] | None = _omit_unset()
 
 
 class TabularTimeSeriesMetaResponse(HttpContractModel):
@@ -53,15 +63,17 @@ class TabularTimeSeriesMetaResponse(HttpContractModel):
     timeUnit: Literal["ms"] = "ms"
     timezone: Literal["UTC"] = "UTC"
     sorted: bool
-    valueField: str | None = None
-    seriesField: str | None = None
-    seriesLabelFields: list[str] | None = None
-    valueFields: list[str] | None = None
-    frequency: str | None = None
-    calendar: str | None = None
-    gapPolicy: Literal["preserve_nulls", "drop_nulls"] | None = None
-    duplicatePolicy: Literal["error", "first", "latest", "aggregate", "preserve"] | None = None
-    unitByField: dict[str, str] | None = None
+    valueField: str | None = _omit_unset()
+    seriesField: str | None = _omit_unset()
+    seriesLabelFields: list[str] | None = _omit_unset()
+    valueFields: list[str] | None = _omit_unset()
+    frequency: str | None = _omit_unset()
+    calendar: str | None = _omit_unset()
+    gapPolicy: Literal["preserve_nulls", "drop_nulls"] | None = _omit_unset()
+    duplicatePolicy: (
+        Literal["error", "first", "latest", "aggregate", "preserve"] | None
+    ) = _omit_unset()
+    unitByField: dict[str, str] | None = _omit_unset()
 
     @model_validator(mode="after")
     def validate_shape_fields(self) -> TabularTimeSeriesMetaResponse:
@@ -76,27 +88,27 @@ class TabularTimeSeriesMetaResponse(HttpContractModel):
 class TableVisualThreshold(HttpContractModel):
     operator: Literal["gt", "gte", "lt", "lte", "eq"]
     value: float
-    backgroundColor: str | None = None
-    id: str | None = None
-    textColor: str | None = None
-    tone: Literal["neutral", "primary", "success", "warning", "danger"] | None = None
+    backgroundColor: str | None = _omit_unset()
+    id: str | None = _omit_unset()
+    textColor: str | None = _omit_unset()
+    tone: Literal["neutral", "primary", "success", "warning", "danger"] | None = _omit_unset()
 
 
 class TableVisualColorScale(HttpContractModel):
-    negative: str | None = None
-    neutral: str | None = None
-    positive: str | None = None
+    negative: str | None = _omit_unset()
+    neutral: str | None = _omit_unset()
+    positive: str | None = _omit_unset()
 
 
 class TableVisualRange(HttpContractModel):
-    min: float | None = None
-    max: float | None = None
-    midpoint: float | None = None
-    clamp: bool | None = None
+    min: float | None = _omit_unset()
+    max: float | None = _omit_unset()
+    midpoint: float | None = _omit_unset()
+    clamp: bool | None = _omit_unset()
 
 
 class TableVisualColumn(HttpContractModel):
-    label: str | None = None
+    label: str | None = _omit_unset()
     format: Literal[
         "number",
         "price",
@@ -105,8 +117,8 @@ class TableVisualColumn(HttpContractModel):
         "currency",
         "datetime",
         "formula",
-    ] | None = None
-    formulaExpression: str | None = None
+    ] | None = _omit_unset()
+    formulaExpression: str | None = _omit_unset()
     formulaResultFormat: Literal[
         "text",
         "datetime",
@@ -114,17 +126,17 @@ class TableVisualColumn(HttpContractModel):
         "currency",
         "percent",
         "bps",
-    ] | None = None
-    dateTimeInputFormat: str | None = None
-    dateTimeOutputFormat: str | None = None
-    decimals: int | None = Field(default=None, ge=0, le=6)
-    visible: bool | None = None
-    colorScale: TableVisualColorScale | None = None
-    range: TableVisualRange | None = None
-    thresholds: list[TableVisualThreshold] | None = None
-    heatmap: bool | None = None
-    barMode: Literal["none", "fill"] | None = None
-    gradientMode: Literal["none", "fill"] | None = None
+    ] | None = _omit_unset()
+    dateTimeInputFormat: str | None = _omit_unset()
+    dateTimeOutputFormat: str | None = _omit_unset()
+    decimals: int | None = _omit_unset(ge=0, le=6)
+    visible: bool | None = _omit_unset()
+    colorScale: TableVisualColorScale | None = _omit_unset()
+    range: TableVisualRange | None = _omit_unset()
+    thresholds: list[TableVisualThreshold] | None = _omit_unset()
+    heatmap: bool | None = _omit_unset()
+    barMode: Literal["none", "fill"] | None = _omit_unset()
+    gradientMode: Literal["none", "fill"] | None = _omit_unset()
     heatmapPalette: Literal[
         "auto",
         "viridis",
@@ -135,36 +147,36 @@ class TableVisualColumn(HttpContractModel):
         "jet",
         "blue-white-red",
         "red-yellow-green",
-    ] | None = None
-    gaugeMode: Literal["none", "ring"] | None = None
-    visualRangeMode: Literal["auto", "fixed"] | None = None
-    visualMin: float | None = None
-    visualMax: float | None = None
-    kind: Literal["sparkline", "bar", "heatmap"] | None = None
-    encoding: Literal["csv-number", "json-number-array", "number-array"] | None = None
-    order: Literal["oldest-to-newest", "newest-to-oldest"] | None = None
-    width: float | None = Field(default=None, gt=0)
+    ] | None = _omit_unset()
+    gaugeMode: Literal["none", "ring"] | None = _omit_unset()
+    visualRangeMode: Literal["auto", "fixed"] | None = _omit_unset()
+    visualMin: float | None = _omit_unset()
+    visualMax: float | None = _omit_unset()
+    kind: Literal["sparkline", "bar", "heatmap"] | None = _omit_unset()
+    encoding: Literal["csv-number", "json-number-array", "number-array"] | None = _omit_unset()
+    order: Literal["oldest-to-newest", "newest-to-oldest"] | None = _omit_unset()
+    width: float | None = _omit_unset(gt=0)
 
 
 class TableFrameVisualsMetadata(HttpContractModel):
-    columns: dict[str, TableVisualColumn] | None = None
+    columns: dict[str, TableVisualColumn] | None = _omit_unset()
 
 
 class TabularFrameMetaResponse(HttpContractModel):
     model_config = ConfigDict(extra="allow", populate_by_name=True)
 
-    timeSeries: TabularTimeSeriesMetaResponse | None = None
-    tableVisuals: TableFrameVisualsMetadata | None = None
+    timeSeries: TabularTimeSeriesMetaResponse | None = _omit_unset()
+    tableVisuals: TableFrameVisualsMetadata | None = _omit_unset()
 
 
 class TabularFrameResponse(HttpContractModel):
     status: TabularFrameStatus
     columns: list[str]
     rows: list[dict[str, Any]]
-    error: str | None = None
-    fields: list[TabularFrameFieldResponse] | None = None
-    meta: TabularFrameMetaResponse | None = None
-    source: TabularFrameSourceResponse | None = None
+    error: str | None = _omit_unset()
+    fields: list[TabularFrameFieldResponse] | None = _omit_unset()
+    meta: TabularFrameMetaResponse | None = _omit_unset()
+    source: TabularFrameSourceResponse | None = _omit_unset()
 
     @field_validator("columns")
     @classmethod

{ms_markets-2.2.4.dev14 → ms_markets-2.2.5.dev15}/tests/msm/fastapi/v1/test_bulk_action_contracts.py

@@ -5,10 +5,12 @@ from pathlib import Path
 from typing import Any
 
 import pytest
+from fastapi.testclient import TestClient
 from jsonschema import Draft202012Validator
 from pydantic import BaseModel, ValidationError
 from referencing import Registry, Resource
 
+from apps.v1.main import app
 from msm.api.http import (
     BULK_ACTION_EXECUTION_CONTRACT,
     BULK_ACTION_PREFLIGHT_CONTRACT,
@@ -27,7 +29,13 @@ from msm.api.http import (
     ResourceListDiscovery,
     ResourceSearchControl,
     TabularFrameResponse,
+    TabularFrameSourceResponse,
+    build_tabular_field,
+    build_tabular_frame,
 )
+from msm.api.http import bulk_actions as bulk_action_models
+from msm.api.http import collections as collection_models
+from msm.api.http import tabular as tabular_models
 
 COMMAND_CENTER_SDK_TAG = "v0.1.13"
 COMMAND_CENTER_SDK_COMMIT = "f11c0ea8c5d3fc267997e476aa1522c798fdaced"
@@ -138,8 +146,17 @@ _REQUIRED_ONLY_ACTION = BulkActionDefinition(
             ),
         ),
         (BULK_ACTION_PREFLIGHT_CONTRACT, BulkActionPreflightResponse(allowed=True)),
+        (
+            CORE_TABULAR_FRAME_CONTRACT,
+            build_tabular_frame(
+                rows=[{"value": 1.5}],
+                fields=[build_tabular_field("value", field_type="number", nullable=None)],
+                meta={"tableVisuals": {"columns": {"value": {}}}},
+                source=TabularFrameSourceResponse(kind="records"),
+            ),
+        ),
     ],
-    ids=["resource-discovery", "bulk-action-preflight"],
+    ids=["resource-discovery", "bulk-action-preflight", "tabular-frame"],
 )
 def test_wire_models_omit_unset_optional_fields(contract_id: str, model: BaseModel) -> None:
     """The SDK accepts optional contract fields only when absent or valid, never null."""
@@ -148,3 +165,42 @@ def test_wire_models_omit_unset_optional_fields(contract_id: str, model: BaseMod
 
     assert _null_paths(payload) == []
     _contract_validator(contract_id).validate(payload)
+
+
+# Optional contract fields that may serialize as null.
+_NULL_ALLOWED_FIELDS = {
+    # Request body: Command Center sends it and the API never serializes it.
+    "BulkActionAllMatchingQuery.search",
+    # Documented as null when MetaTables cannot compute the impact. The preflight
+    # schema allows domain extensions and the SDK keeps the raw object.
+    "BulkDeletePreflightResponse.impact",
+}
+
+
+def test_command_center_contract_models_omit_every_unset_optional_field() -> None:
+    serialized_as_null = {
+        f"{model.__name__}.{name}"
+        for module in (bulk_action_models, collection_models, tabular_models)
+        for model in vars(module).values()
+        if isinstance(model, type)
+        and issubclass(model, BaseModel)
+        and model.__module__ == module.__name__
+        for name, field in model.model_fields.items()
+        if not field.is_required() and field.default is None and field.exclude_if is None
+    }
+
+    assert serialized_as_null == _NULL_ALLOWED_FIELDS
+
+
+def test_tabular_frame_keeps_null_cell_values() -> None:
+    payload = build_tabular_frame(rows=[{"value": None}]).model_dump(mode="json", by_alias=True)
+
+    assert payload == {"status": "ready", "columns": ["value"], "rows": [{"value": None}]}
+    _contract_validator(CORE_TABULAR_FRAME_CONTRACT).validate(payload)
+
+
+def test_connection_contract_matches_adapter_discovery_schema() -> None:
+    response = TestClient(app).get("/.well-known/command-center/connection-contract")
+
+    assert response.status_code == 200
+    _contract_validator("command-center.adapter_from_api.discovery@v1").validate(response.json())