mainsequence 4.3.5__tar.gz → 4.3.6__tar.gz

{mainsequence-4.3.5/mainsequence.egg-info → mainsequence-4.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 4.3.5
+Version: 4.3.6
 Summary: Main Sequence SDK 
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License: MainSequence GmbH SDK License Agreement

{mainsequence-4.3.5 → mainsequence-4.3.6}/agent_scaffold/skills/data_publishing/data_nodes/SKILL.md

@@ -159,6 +159,7 @@ class PricesTable(PlatformTimeIndexMetaTable, Base):
         "risk analytics."
     )
     __time_index_name__ = "time_index"
+    __cadence__ = "1d"
     __index_names__ = ["time_index", "unique_identifier"]
 
     time_index: Mapped[datetime.datetime] = mapped_column(
@@ -197,6 +198,12 @@ autogenerate runs. Do not manually repeat the full grain unique index in
 `__table_args__`; add ordinary SQLAlchemy `Index(...)` entries only for
 additional lookup/performance paths.
 
+When the dataset has a known stable observation interval, declare `__cadence__`
+on the `PlatformTimeIndexMetaTable` model, for example `1m`, `5m`, `1h`, `1d`,
+`1w`, `1mo`, `1q`, or `1y`. Cadence is table metadata and should be included
+whenever possible; do not make it a DataNode runtime configuration field unless
+changing it actually changes the produced dataset identity.
+
 `PlatformTimeIndexMetaTable.register()` remains SDK plumbing for the migration
 workflow. Do not manually attach an existing UID, reconstruct a generic
 `MetaTable`, or use manual bind helpers as an authoring step.

{mainsequence-4.3.5 → mainsequence-4.3.6}/agent_scaffold/skills/data_publishing/meta_tables/SKILL.md

@@ -137,6 +137,11 @@ first version, use Alembic. Keep the SDK model as a normal
 `PlatformManagedMetaTable` or `PlatformTimeIndexMetaTable` catalog contract, and
 apply physical schema changes through the Alembic migration workflow.
 
+For `PlatformTimeIndexMetaTable`, declare `__cadence__` whenever the table has a
+known stable observation interval, for example `1m`, `5m`, `1h`, `1d`, `1w`,
+`1mo`, `1q`, or `1y`. Cadence is table metadata and belongs on the storage
+model when possible.
+
 Default-schema tables must leave SQLAlchemy `Table.schema` unset; do not write
 `__table_args__ = {"schema": "public"}` for the default PostgreSQL schema. Set
 schema metadata only for non-default schemas, using `__table_args__ = {"schema":

{mainsequence-4.3.5 → mainsequence-4.3.6}/mainsequence/client/metatables/core.py

@@ -8,6 +8,7 @@ import gzip
 import json
 import math
 import os
+import re
 import time
 from collections.abc import Callable, Mapping, Sequence
 from dataclasses import dataclass
@@ -58,6 +59,24 @@ from ..utils import (
 DUCK_DB = "duck_db"
 SQLITE = "sqlite"
 LOCAL_DATA_SOURCE_CLASS_TYPES = {DUCK_DB, SQLITE}
+_TIME_INDEXED_CADENCE_RE = re.compile(
+    r"^[1-9][0-9]*(mo|s|m|h|d|w|q|y)$",
+    re.IGNORECASE,
+)
+
+
+def _normalize_time_indexed_cadence(value: Any) -> str | None:
+    if value is None:
+        return None
+    normalized = str(value).strip().lower()
+    if not normalized:
+        return None
+    if not _TIME_INDEXED_CADENCE_RE.fullmatch(normalized):
+        raise ValueError(
+            "cadence must be an interval token such as 1m, 5m, 1h, 1d, 1w, "
+            "1mo, 1q, or 1y."
+        )
+    return normalized
 
 
 def _duckdb_interface():
@@ -667,6 +686,11 @@ class ManagedMetaTableFinalizeTableResult(BasePydanticModel):
     )
     table_kind: str = Field(..., description="Backend table kind after reconciliation.")
     time_indexed: bool = Field(..., description="Whether the MetaTable is time-indexed.")
+    cadence: str | None = Field(
+        None,
+        max_length=32,
+        description="Optional declared cadence for time-indexed MetaTables.",
+    )
     finalized: bool = Field(
         ...,
         description="True when this row was reconciled and activated by this call.",
@@ -695,6 +719,11 @@ class ManagedMetaTableFinalizeTableResult(BasePydanticModel):
         description="Per-table structured error when finalization did not activate this row.",
     )
 
+    @field_validator("cadence")
+    @classmethod
+    def _normalize_cadence(cls, value: str | None) -> str | None:
+        return _normalize_time_indexed_cadence(value)
+
     model_config = ConfigDict(extra="ignore")
 
 
@@ -1923,6 +1952,14 @@ class TimeIndexMetaTableRegistrationRequest(BasePydanticModel):
         default_factory=lambda: {"create_table": True, "if_not_exists": True}
     )
     time_index_name: str = Field(..., description="Canonical timestamp column name")
+    cadence: str | None = Field(
+        None,
+        max_length=32,
+        description=(
+            "Optional time-indexed cadence token such as 1m, 5m, 1h, 1d, "
+            "1w, 1mo, 1q, or 1y."
+        ),
+    )
     partition_strategy: str = Field(
         default="backend_default",
         description="Time-indexed MetaTable physical partitioning strategy",
@@ -1973,6 +2010,11 @@ class TimeIndexMetaTableRegistrationRequest(BasePydanticModel):
         data["table_contract"] = normalized_contract
         return data
 
+    @field_validator("cadence")
+    @classmethod
+    def _normalize_cadence(cls, value: str | None) -> str | None:
+        return _normalize_time_indexed_cadence(value)
+
 
 def _payload_get(obj: Any, key: str, default: Any = None) -> Any:
     if isinstance(obj, Mapping):
@@ -2113,6 +2155,11 @@ class TimeIndexedProfile(TimeIndexedProfileBase, BasePydanticModel):
         None, description="Public uid of the related TimeIndexMetaTable"
     )
     time_index_name: str = Field(..., max_length=100, description="Time index name")
+    cadence: str | None = Field(
+        None,
+        max_length=32,
+        description="Optional declared cadence for the time-indexed table.",
+    )
     partition_strategy: str | None = None
     last_time_index_value: datetime.datetime | None = Field(
         None, description="Last time index value"
@@ -2124,6 +2171,11 @@ class TimeIndexedProfile(TimeIndexedProfileBase, BasePydanticModel):
     physical_index_plan: dict[str, Any] | None = Field(
         None, description="Server-rendered physical index plan"
     )
+
+    @field_validator("cadence")
+    @classmethod
+    def _normalize_cadence(cls, value: str | None) -> str | None:
+        return _normalize_time_indexed_cadence(value)
     multi_index_stats: dict[str, Any] | None = Field(
         None, description="Canonical multi-index progress statistics"
     )

{mainsequence-4.3.5 → mainsequence-4.3.6}/mainsequence/meta_tables/migrations.py

@@ -935,6 +935,9 @@ def _collection_create_row_from_registration_request(
     time_index_name = getattr(request, "time_index_name", None)
     if time_index_name not in (None, ""):
         row["time_index_name"] = str(time_index_name)
+    cadence = getattr(request, "cadence", None)
+    if cadence not in (None, ""):
+        row["cadence"] = str(cadence)
     partition_strategy = getattr(request, "partition_strategy", None)
     if partition_strategy not in (None, ""):
         row["partition_strategy"] = str(partition_strategy)

{mainsequence-4.3.5 → mainsequence-4.3.6}/mainsequence/meta_tables/sqlalchemy_contracts.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import contextlib
 import contextvars
 import json
+import re
 from collections.abc import Mapping, Sequence
 from dataclasses import dataclass
 from typing import Any, ClassVar
@@ -37,6 +38,10 @@ DEFAULT_PLATFORM_MANAGED_PROVISIONING = {
 }
 SERVER_GENERATED_UUID_DEFAULT = "gen_random_uuid()"
 DEFAULT_POSTGRES_SCHEMA = "public"
+_TIME_INDEXED_CADENCE_RE = re.compile(
+    r"^[1-9][0-9]*(mo|s|m|h|d|w|q|y)$",
+    re.IGNORECASE,
+)
 _PLATFORM_MANAGED_MIGRATION_REGISTRATION_CONTEXT: contextvars.ContextVar[bool] = (
     contextvars.ContextVar(
         "mainsequence_platform_managed_migration_registration_context",
@@ -292,6 +297,7 @@ class PlatformTimeIndexMetaTable(PlatformManagedMetaTable):
     """
 
     __time_index_meta_table__: ClassVar[TimeIndexMetaTable | None] = None
+    __cadence__: ClassVar[str | None] = None
 
     __mapper_args__ = _sqlalchemy_declared_attr.directive(_time_index_mapper_args)
 
@@ -505,6 +511,7 @@ def time_indexed_registration_request_from_sqlalchemy_model(
         model_or_table,
         storage_layout=storage_layout,
     )
+    resolved_cadence = _resolve_time_index_cadence(model_or_table)
     columns = _iter_columns(table)
     _validate_time_index_contract(
         columns=columns,
@@ -520,6 +527,7 @@ def time_indexed_registration_request_from_sqlalchemy_model(
             time_index_name=resolved_time_index_name,
             index_names=resolved_index_names,
             storage_layout=resolved_storage_layout,
+            cadence=resolved_cadence,
         ),
         hash_namespace=resolved_hash_namespace,
         extra_hash_components=resolved_extra_hash_components,
@@ -559,6 +567,7 @@ def time_indexed_registration_request_from_sqlalchemy_model(
         labels=_resolve_labels(model_or_table, labels=labels),
         provisioning=_resolve_provisioning(model_or_table, provisioning=provisioning),
         time_index_name=resolved_time_index_name,
+        cadence=resolved_cadence,
         table_contract={
             "version": "relational-table.v1",
             "table_kind": "time_indexed",
@@ -571,6 +580,7 @@ def time_indexed_registration_request_from_sqlalchemy_model(
                 "time_indexed": {
                     "time_index_name": resolved_time_index_name,
                     "index_names": resolved_index_names,
+                    **({"cadence": resolved_cadence} if resolved_cadence else {}),
                     **(
                         {"storage_layout": dict(resolved_storage_layout)}
                         if resolved_storage_layout
@@ -1246,6 +1256,7 @@ def _configured_table_storage_identity(model_or_table: Any, *, table: Any) -> di
         time_index_name=time_index_name,
         index_names=index_names,
         storage_layout=_resolve_time_index_storage_layout(model_or_table),
+        cadence=_resolve_time_index_cadence(model_or_table),
     )
 
 
@@ -1260,12 +1271,14 @@ def _time_index_table_storage_identity(
     time_index_name: str,
     index_names: Sequence[str],
     storage_layout: Mapping[str, Any] | None,
+    cadence: str | None,
 ) -> dict[str, Any]:
     return _time_index_storage_identity(
         table_storage_identity=_table_storage_identity(table),
         time_index_name=time_index_name,
         index_names=index_names,
         storage_layout=storage_layout,
+        cadence=cadence,
     )
 
 
@@ -1275,12 +1288,14 @@ def _time_index_table_items_storage_identity(
     time_index_name: str,
     index_names: Sequence[str],
     storage_layout: Mapping[str, Any] | None,
+    cadence: str | None,
 ) -> dict[str, Any]:
     return _time_index_storage_identity(
         table_storage_identity=_table_items_storage_identity(table_items),
         time_index_name=time_index_name,
         index_names=index_names,
         storage_layout=storage_layout,
+        cadence=cadence,
     )
 
 
@@ -1290,12 +1305,15 @@ def _time_index_storage_identity(
     time_index_name: str,
     index_names: Sequence[str],
     storage_layout: Mapping[str, Any] | None,
+    cadence: str | None,
 ) -> dict[str, Any]:
     profile: dict[str, Any] = {
         "kind": "time_indexed",
         "time_index_name": str(time_index_name),
         "index_names": [str(name) for name in index_names],
     }
+    if cadence:
+        profile["cadence"] = cadence
     if storage_layout:
         profile["storage_layout"] = dict(storage_layout)
     return {
@@ -1399,10 +1417,28 @@ def _resolve_time_index_storage_layout(
     if not isinstance(resolved, Mapping):
         raise ValueError(
             "PlatformTimeIndexMetaTable storage_layout must be a mapping when provided."
-        )
+    )
     return resolved
 
 
+def _resolve_time_index_cadence(model_or_table: Any) -> str | None:
+    resolved = (
+        getattr(model_or_table, "__cadence__", None)
+        or getattr(model_or_table, "__dynamic_table_cadence__", None)
+    )
+    if resolved in (None, ""):
+        return None
+    normalized = str(resolved).strip().lower()
+    if not normalized:
+        return None
+    if not _TIME_INDEXED_CADENCE_RE.fullmatch(normalized):
+        raise ValueError(
+            "PlatformTimeIndexMetaTable cadence must be an interval token such as "
+            "1m, 5m, 1h, 1d, 1w, 1mo, 1q, or 1y."
+        )
+    return normalized
+
+
 def _dynamic_table_info_value(model_or_table: Any, key: str) -> Any:
     dynamic_table = _table_info_value(model_or_table, "dynamic_table")
     if isinstance(dynamic_table, Mapping):

{mainsequence-4.3.5 → mainsequence-4.3.6/mainsequence.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 4.3.5
+Version: 4.3.6
 Summary: Main Sequence SDK 
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License: MainSequence GmbH SDK License Agreement

{mainsequence-4.3.5 → mainsequence-4.3.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mainsequence"
-version = "4.3.5"
+version = "4.3.6"
 description = "Main Sequence SDK "
 readme = "README.md"
 requires-python = ">=3.11"

{mainsequence-4.3.5 → mainsequence-4.3.6}/tests/test_meta_tables_sqlalchemy_contracts.py

@@ -180,6 +180,7 @@ def _time_index_model_class(
     identifier=None,
     time_index_name="time_index",
     index_names=None,
+    cadence=None,
 ):
     attrs = _model_attrs(
         name,
@@ -193,6 +194,8 @@ def _time_index_model_class(
             "__index_names__": list(index_names or [time_index_name]),
         }
     )
+    if cadence is not None:
+        attrs["__cadence__"] = cadence
     return type(
         name,
         (PlatformTimeIndexMetaTable,),
@@ -1247,6 +1250,78 @@ def test_time_index_meta_table_registration_request_uses_dynamic_contract():
     assert "physical_index_plan" not in payload
 
 
+def test_time_index_meta_table_registration_request_uses_class_cadence():
+    table = FakeTable(
+        "example_assets__prices",
+        columns=[
+            FakeColumn("time_index", DateTime(timezone=True), nullable=False),
+            FakeColumn("asset_uid", Uuid(), nullable=False),
+            FakeColumn("price", String(64), nullable=False),
+        ],
+    )
+    DailyPrices = _time_index_model_class(
+        "DailyPrices",
+        table,
+        index_names=["time_index", "asset_uid"],
+        cadence="1D",
+    )
+
+    request = DailyPrices.build_registration_request(
+        data_source_uid="dddddddd-dddd-4ddd-8ddd-dddddddddddd",
+    )
+
+    assert request.cadence == "1d"
+    assert request.table_contract["authoring"]["time_indexed"]["cadence"] == "1d"
+    payload = request.model_dump(mode="json", exclude_none=True)
+    assert payload["cadence"] == "1d"
+
+
+def test_time_index_meta_table_cadence_changes_configured_storage_hash():
+    table = FakeTable(
+        "example_assets__prices",
+        columns=[
+            FakeColumn("time_index", DateTime(timezone=True), nullable=False),
+            FakeColumn("asset_uid", Uuid(), nullable=False),
+            FakeColumn("price", String(64), nullable=False),
+        ],
+    )
+    DailyPrices = _time_index_model_class(
+        "DailyPrices",
+        table,
+        index_names=["time_index", "asset_uid"],
+        cadence="1d",
+    )
+    IntradayPrices = _time_index_model_class(
+        "IntradayPrices",
+        table,
+        index_names=["time_index", "asset_uid"],
+        cadence="5m",
+    )
+
+    assert _configured_storage_hash(DailyPrices) != _configured_storage_hash(IntradayPrices)
+
+
+def test_time_index_meta_table_rejects_invalid_class_cadence():
+    table = FakeTable(
+        "example_assets__prices",
+        columns=[
+            FakeColumn("time_index", DateTime(timezone=True), nullable=False),
+            FakeColumn("asset_uid", Uuid(), nullable=False),
+        ],
+    )
+    Prices = _time_index_model_class(
+        "Prices",
+        table,
+        index_names=["time_index", "asset_uid"],
+        cadence="daily",
+    )
+
+    with pytest.raises(ValueError, match="cadence"):
+        Prices.build_registration_request(
+            data_source_uid="dddddddd-dddd-4ddd-8ddd-dddddddddddd",
+        )
+
+
 def test_time_index_meta_table_registration_request_uses_class_metatable_description():
     table = FakeTable(
         "placeholder",