mainsequence 4.1.6__tar.gz → 4.1.8__tar.gz

{mainsequence-4.1.6 → mainsequence-4.1.8}/PKG-INFO

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

{mainsequence-4.1.6 → mainsequence-4.1.8}/agent_scaffold/skills/data_publishing/data_nodes/SKILL.md

@@ -25,7 +25,7 @@ Canonical workflow:
 - modify an existing `DataNode` update process
 - review whether a DataNode change affects update identity or table contract
 - define or refactor `DataNodeConfiguration`
-- classify config fields into update identity and hash-excluded descriptive metadata
+- classify values as hashed config fields or non-config class/runtime values
 - implement or review:
   - `dependencies()`
   - `update()`
@@ -108,6 +108,20 @@ The following are storage-contract decisions:
 - foreign keys
 - table description and labels
 
+Every storage class must include `__metatable_description__`. The description
+should explain the table's intention, row grain, and downstream use, not only
+list columns or schema mechanics.
+
+Use `__metatable_extra_hash_components__` on storage classes when distinct
+DataNode storage tables could otherwise have the same storage-relevant shape.
+For example, two one-index daily tables with one float column need a stable
+component such as `{"storage_name": "daily_random_number"}` versus
+`{"storage_name": "daily_random_addition"}`.
+
+This is storage identity. Changing it creates a different storage table. Do not
+use it for labels, descriptions, runtime options, test isolation, backend UIDs,
+data-source UIDs, or updater scope.
+
 Do not put those concerns in `DataNodeConfiguration`.
 
 Minimal pattern:
@@ -128,6 +142,11 @@ class Base(DeclarativeBase):
 class PricesTable(PlatformTimeIndexMetaData, Base):
     __metatable_namespace__ = "<domain_namespace>"
     __metatable_identifier__ = "<table_identifier>"
+    __metatable_extra_hash_components__ = {"storage_name": "<stable_storage_name>"}
+    __metatable_description__ = (
+        "Daily close prices keyed by asset unique identifier for portfolio and "
+        "risk analytics."
+    )
     __time_index_name__ = "time_index"
     __index_names__ = ["time_index", "unique_identifier"]
 
@@ -175,12 +194,21 @@ Do not accept `test_node`. It has been removed. Use explicit
 Pattern:
 
 ```python
+from typing import ClassVar
+
+from pydantic import Field
+
 from mainsequence.meta_tables import DataNode, DataNodeConfiguration
 from mainsequence.meta_tables import PlatformTimeIndexMetaData
 
 
 class PricesConfig(DataNodeConfiguration):
-    shard_id: str
+    shard_id: str = Field(
+        ...,
+        description="Stable updater partition for this price job.",
+        examples=["us_equities_daily"],
+    )
+    reference_dimension: ClassVar[str] = "unique_identifier"
 
 
 class PricesUpdate(DataNode):
@@ -208,23 +236,45 @@ class PricesUpdate(DataNode):
 ### 3. Configuration Is Update-Scoped By Default
 
 Every `DataNodeConfiguration` field participates in `update_hash` by default.
+Declare values that change output values, dependencies, source choice, or
+updater scope as normal config fields.
 
-Do not use:
+Every config field must be declared with `Field(...)`. Include a clear
+`description` and add `examples=[...]` whenever a realistic example helps. The
+description must explain what the value means for the update process, not repeat
+the Python type.
 
-- `json_schema_extra={"update_only": True}`
-- `json_schema_extra={"runtime_only": True}`
-- `json_schema_extra={"ignore_from_storage_hash": True}`
-- `_ARGS_IGNORE_IN_STORAGE_HASH`
+Values that must not affect `update_hash` should not be Pydantic config fields.
+Use `ClassVar[...]` for class-level invariants and implementation constants, or
+keep runtime controls in environment/runtime configuration outside the
+DataNode config.
 
-Those are removed. The only supported opt-out is:
+If a value genuinely must remain a Pydantic field while not affecting
+`update_hash`, the only supported field-level opt-out is
+`json_schema_extra={"hash_excluded": True}`:
 
 ```python
-Field(..., json_schema_extra={"hash_excluded": True})
+from pydantic import Field
+
+from mainsequence.meta_tables import DataNodeConfiguration
+
+
+class PricesConfig(DataNodeConfiguration):
+    shard_id: str = Field(
+        ...,
+        description="Stable updater partition for this price job.",
+        examples=["us_equities_daily"],
+    )
+    display_label: str | None = Field(
+        default=None,
+        description="Optional human-facing label for UI display only.",
+        examples=["US equities daily prices"],
+        json_schema_extra={"hash_excluded": True},
+    )
 ```
 
-Use `hash_excluded` only for descriptive metadata that must not affect update
-identity. If a field changes output values, dependencies, source choice, or
-updater scope, it must remain a normal config field.
+Do not invent other metadata-marker exceptions. Scope, dependency, source, and
+output-affecting fields must remain hashed config fields.
 
 ### 4. `hash_namespace` Is Isolation Only
 
@@ -319,13 +369,13 @@ Do not put schema or published table metadata on the DataNode configuration.
 When reviewing an existing DataNode, look for:
 
 - output storage contract hidden in `DataNodeConfiguration`
+- missing `__metatable_description__` on the storage table
 - dependency storage table passed as an ad hoc constructor argument
 - schema or published table metadata hidden in DataNode configuration
-- `update_only`, `runtime_only`, or `ignore_from_storage_hash`
 - `test_node=True`
 - missing explicit `storage_table`
 - accidental storage registration inside the DataNode
-- wrong meaning/scope/hash-excluded split
+- wrong split between hashed config fields and non-config class/runtime values
 - misuse of `hash_namespace`
 - non-incremental `update()` behavior
 - hidden dependency creation inside `update()`
@@ -339,6 +389,7 @@ Do not claim success until you have checked:
 
 - the relevant docs were read first
 - storage is a registered `PlatformTimeIndexMetaData` class
+- storage has an intention-rich `__metatable_description__`
 - the DataNode constructor requires `storage_table`
 - dependency storage-table references live in config and are registered
 - config fields are updater-scoped by default

{mainsequence-4.1.6 → mainsequence-4.1.8}/agent_scaffold/skills/data_publishing/meta_tables/SKILL.md

@@ -99,15 +99,39 @@ The mixin derives the SQLAlchemy physical table name from storage-relevant confi
 
 Schema must come from SQLAlchemy table metadata, usually `__table_args__ = {"schema": "public"}` or the tuple form ending in `{"schema": ...}`. Do not add a separate MetaTable-specific schema attribute.
 
+Always declare `__metatable_description__` on the model. The description must
+explain the table's business intention, row grain, and expected use, not only
+the schema. Column-level descriptions stay in `mapped_column(info={...})`.
+
+Use `__metatable_extra_hash_components__` when two backend-managed tables could
+otherwise produce the same storage hash because their storage-relevant shape is
+identical or intentionally generic. The value must be stable and deterministic,
+usually a small mapping such as `{"storage_name": "account_holdings"}`.
+
+This attribute is part of storage identity. Changing it defines a different
+table. Do not use it for labels, descriptions, runtime options, test isolation,
+backend UIDs, data-source UIDs, or updater scope. Use `hash_namespace` for test
+or experiment isolation.
+
 Register through the class API:
 
 ```python
-account_meta_table = Account.register(
-    description="Example account table.",
-    labels=["sdk-example"],
-)
+class Account(PlatformManagedMetaTable, Base):
+    __metatable_namespace__ = "sdk-examples"
+    __metatable_identifier__ = "Account"
+    __metatable_extra_hash_components__ = {"storage_name": "account"}
+    __metatable_description__ = (
+        "Customer account master records used to scope balances, holdings, and "
+        "account-level limits."
+    )
+
+
+account_meta_table = Account.register(labels=["sdk-example"])
 ```
 
+Pass `description=...` only when the call intentionally overrides the class
+default.
+
 For platform-managed registration, the data source is resolved from the active Main Sequence project/session, the same way DataNode does. Do not require or thread a `data_source_uid` through normal platform-managed example code.
 
 Only call `build_registration_request()` when the task explicitly needs to inspect or validate the payload before registration.
@@ -172,6 +196,7 @@ Do not hardcode platform-managed physical names manually.
 When reviewing an existing MetaTable workflow, look for:
 
 - missing namespace or identifier
+- missing `__metatable_description__`, or a description that only repeats column names instead of table intention
 - backend-managed models that do not inherit `PlatformManagedMetaTable`
 - backend-managed examples that use namespace environment variables instead of a plain `sdk-examples` namespace
 - duplicate schema sources outside SQLAlchemy table metadata
@@ -187,6 +212,7 @@ When reviewing an existing MetaTable workflow, look for:
 Do not claim success until you have checked:
 
 - the table contract matches the intended row contract
+- the table has an intention-rich `__metatable_description__`
 - indexes are intentional
 - foreign keys resolve to the correct dependency targets
 - management mode is correct

{mainsequence-4.1.6 → mainsequence-4.1.8}/mainsequence/client/models_metatables.py

@@ -220,7 +220,13 @@ class MetaTablePhysicalContract(BasePydanticModel):
         exclude=True,
         description=("Input-only schema alias. MetaTable uses the data source default schema."),
     )
-    table_name: str = Field(..., description="Physical database table name.")
+    table_name: str | None = Field(
+        default=None,
+        description=(
+            "Physical database table name. Required for external_registered tables; "
+            "omitted by platform_managed client requests because the backend owns it."
+        ),
+    )
 
     model_config = ConfigDict(populate_by_name=True)
 
@@ -1090,6 +1096,55 @@ class MetaTable(BasePydanticModel, LabelableObjectMixin, ShareableObjectMixin, B
             self.introspection_snapshot = snapshot
         return response_json
 
+    def get_schema_graph(
+        self,
+        *,
+        depth: int = 1,
+        include_incoming: bool = False,
+        timeout: int | float | tuple[float, float] | None = None,
+    ) -> dict[str, Any]:
+        """
+        Return the MetaTable foreign-key schema graph rooted at this table.
+
+        The graph is the client API for dependency analysis. Outgoing edges are
+        foreign keys declared by this table. When ``include_incoming`` is true,
+        the response also includes visible tables that depend on this table.
+
+        Args:
+            depth: Relationship traversal depth. The backend clamps this to its
+                supported range.
+            include_incoming: Include inbound relationships where another
+                visible MetaTable has a foreign key targeting this table.
+            timeout: Optional request timeout in seconds or ``requests`` timeout
+                tuple form.
+
+        Returns:
+            A dictionary with ``root_uid``, ``depth``, ``include_incoming``,
+            ``nodes``, and ``edges``. Inbound dependencies are edges where
+            ``edge["target_uid"] == self.uid``; the dependent table UID is
+            ``edge["source_uid"]``.
+        """
+        url = f"{type(self).get_object_url().rstrip('/')}/{self._public_uid()}/schema-graph/"
+        payload = {
+            "params": serialize_to_json(
+                {
+                    "depth": depth,
+                    "include_incoming": include_incoming,
+                }
+            )
+        }
+        response = make_request(
+            s=type(self).build_session(),
+            loaders=type(self).LOADERS,
+            r_type="GET",
+            url=url,
+            payload=payload,
+            time_out=timeout,
+        )
+        if response.status_code != 200:
+            raise_for_response(response, payload=payload)
+        return response.json()
+
     def refresh_table_search_index(
         self,
         *,
@@ -1335,7 +1390,11 @@ class TimeIndexMetaTableRegistrationRequest(BasePydanticModel):
     model_config = ConfigDict(extra="forbid")
 
     data_source_uid: str = Field(..., description="Public uid of the storage data source")
-    storage_hash: str = Field(..., max_length=63, description="Canonical physical table name")
+    storage_hash: str = Field(
+        ...,
+        max_length=63,
+        description="Canonical logical storage identity for the time-indexed MetaTable",
+    )
     identifier: str | None = Field(None, description="Optional published storage identifier")
     namespace: str | None = Field(None, description="Optional published storage namespace")
     description: str | None = Field(None, description="Optional storage description")

{mainsequence-4.1.6 → mainsequence-4.1.8}/mainsequence/meta_tables/__init__.py

@@ -38,10 +38,6 @@ _LAZY_IMPORTS = {
         ".sqlalchemy_contracts",
         "register_external_sqlalchemy_model",
     ),
-    "register_platform_managed_sqlalchemy_model": (
-        ".sqlalchemy_contracts",
-        "register_platform_managed_sqlalchemy_model",
-    ),
     "slugify_identifier": (".hashing", "slugify_identifier"),
     "table_contract_from_sqlalchemy_model": (
         ".sqlalchemy_contracts",

{mainsequence-4.1.6 → mainsequence-4.1.8}/mainsequence/meta_tables/data_nodes/data_nodes.py

@@ -420,13 +420,6 @@ class DataNode(DataAccessMixin, ABC):
         """
         super().__init_subclass__(**kwargs)
 
-        if "_ARGS_IGNORE_IN_STORAGE_HASH" in cls.__dict__:
-            raise TypeError(
-                f"{cls.__name__} uses removed class attribute _ARGS_IGNORE_IN_STORAGE_HASH; "
-                "move those fields into DataNodeConfiguration. Configuration fields "
-                "participate in update hashing by default."
-            )
-
         # Get the original __init__ from the new subclass
         original_init = cls.__init__
 

{mainsequence-4.1.6 → mainsequence-4.1.8}/mainsequence/meta_tables/pydantic_metadata.py

@@ -20,24 +20,6 @@ def serialize_pydantic_model(
 
     for field_name, field_info in value.__class__.model_fields.items():
         extra = field_info.json_schema_extra or {}
-        if "ignore_from_storage_hash" in extra:
-            raise ValueError(
-                f"{value.__class__.__name__}.{field_name} uses removed metadata "
-                "'ignore_from_storage_hash'. All configuration fields participate in "
-                'update hashing by default; use json_schema_extra={"hash_excluded": True} '
-                "only for fields that should not affect update identity."
-            )
-        if "update_only" in extra:
-            raise ValueError(
-                f"{value.__class__.__name__}.{field_name} uses removed metadata "
-                "'update_only'. All configuration fields are update-scoped by default."
-            )
-        if "runtime_only" in extra:
-            raise ValueError(
-                f"{value.__class__.__name__}.{field_name} uses removed metadata "
-                "'runtime_only'; use json_schema_extra={\"hash_excluded\": True} instead."
-            )
-
         is_hash_excluded = extra.get("hash_excluded", False)
         if not isinstance(is_hash_excluded, bool):
             raise ValueError(