mainsequence 4.1.6__tar.gz → 4.1.7__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 4.1.6
+Version: 4.1.7
 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.7}/agent_scaffold/skills/data_publishing/data_nodes/SKILL.md

@@ -108,6 +108,10 @@ 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.
+
 Do not put those concerns in `DataNodeConfiguration`.
 
 Minimal pattern:
@@ -128,6 +132,10 @@ class Base(DeclarativeBase):
 class PricesTable(PlatformTimeIndexMetaData, Base):
     __metatable_namespace__ = "<domain_namespace>"
     __metatable_identifier__ = "<table_identifier>"
+    __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"]
 
@@ -319,6 +327,7 @@ 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`
@@ -339,6 +348,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.7}/agent_scaffold/skills/data_publishing/meta_tables/SKILL.md

@@ -99,15 +99,28 @@ 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={...})`.
+
 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_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 +185,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 +201,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.7}/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.7}/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",