mainsequence 4.1.5__tar.gz → 4.1.7__tar.gz

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

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

@@ -15,7 +15,7 @@ is defined by a registered `PlatformTimeIndexMetaData` SQLAlchemy model.
 Canonical workflow:
 
 1. Define a `PlatformTimeIndexMetaData` storage class.
-2. Register or bind that storage class before constructing the DataNode.
+2. Register that storage class before constructing the DataNode.
 3. Construct the DataNode with `config=...` and `storage_table=StorageClass`.
 4. Return a DataFrame from `update()` that matches the storage class contract.
 
@@ -91,7 +91,7 @@ For every non-trivial DataNode task, make these decisions explicitly:
 
 1. Is this a new dataset or the same dataset?
 2. Is this change storage-contract work or update-process work?
-3. Is the storage class already registered or should the MetaTable skill handle it?
+3. Is the storage class registered through its MetaTable path, or should the MetaTable skill handle it?
 4. Is the node single-index or MultiIndex?
 5. Does the first validation run happen under an explicit `hash_namespace(...)`?
 
@@ -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"]
 
@@ -139,17 +147,17 @@ class PricesTable(PlatformTimeIndexMetaData, Base):
     close: Mapped[float] = mapped_column(Float, nullable=False)
 ```
 
-Register or bind storage before constructing the DataNode:
+Register storage before constructing the DataNode:
 
 ```python
 PricesTable.register(data_source_uid=data_source_uid)
 ```
 
-or:
-
-```python
-PricesTable.bind_meta_table(existing_meta_table)
-```
+`PlatformTimeIndexMetaData.register(...)` is the storage lifecycle path. Treat it
+as an idempotent get-or-create operation: the platform returns the registered
+metadata and UID, and the SDK records that metadata on the class. Do not manually
+attach an existing UID, reconstruct a generic `MetaTable`, or use manual bind
+helpers as an authoring step.
 
 ### 2. Keep DataNode As Update Logic
 
@@ -167,7 +175,7 @@ dependency, put that dependency storage reference in the config as
 `type[PlatformTimeIndexMetaData]`. Do not add an extra constructor argument for
 dependency storage tables. Config values of this type are hashed by the bound
 `TimeIndexMetaData.uid` from `StorageClass.__time_index_metadata__`, so the class
-must be registered or bound before DataNode construction.
+must be registered before DataNode construction.
 
 Do not accept `test_node`. It has been removed. Use explicit
 `hash_namespace(...)` or `hash_namespace="..."`.
@@ -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`
@@ -338,9 +347,10 @@ When reviewing an existing DataNode, look for:
 Do not claim success until you have checked:
 
 - the relevant docs were read first
-- storage is a registered or bound `PlatformTimeIndexMetaData` class
+- 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 or bound
+- dependency storage-table references live in config and are registered
 - config fields are updater-scoped by default
 - no removed hash metadata markers remain
 - no `test_node` usage remains

{mainsequence-4.1.5 → 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.5 → mainsequence-4.1.7}/mainsequence/cli/api.py

@@ -5136,7 +5136,7 @@ def list_project_job_runs(
 
 
 def get_project_job_run_logs(
-    job_run_id: int | str,
+    job_run_uid: str,
     *,
     timeout: int | None = None,
 ) -> dict[str, Any]:
@@ -5191,20 +5191,20 @@ def get_project_job_run_logs(
         BaseObjectOrm.ROOT_URL = root_url
         ClientJobRun.ROOT_URL = root_url
 
-        job_run = ClientJobRun.get(pk=int(job_run_id), timeout=timeout)
+        job_run = ClientJobRun.get(pk=job_run_uid, timeout=timeout)
         payload = job_run.get_logs(timeout=timeout)
         if isinstance(payload, dict):
             return payload
         if hasattr(payload, "model_dump"):
             return payload.model_dump()
-        return {"job_run_id": int(job_run_id), "rows": []}
+        return {"job_run_uid": job_run_uid, "rows": []}
 
     except Exception as e:
         err_name = type(e).__name__
         if err_name in {"AuthenticationError", "PermissionDeniedError"}:
             raise NotLoggedIn(str(e) or "Not logged in.") from e
         if err_name == "NotFoundError":
-            raise ApiError(f"Job run not found: {job_run_id}") from e
+            raise ApiError(f"Job run not found: {job_run_uid}") from e
         raise ApiError(f"Project job run logs fetch failed: {e}") from e
     finally:
         if client_utils is not None:

{mainsequence-4.1.5 → mainsequence-4.1.7}/mainsequence/cli/cli.py

@@ -10196,7 +10196,7 @@ def project_jobs_run_cmd(
     if payload:
         preferred_keys = [
             ("Job ID", str(payload.get("job") or payload.get("job_id") or job_id)),
-            ("Job Run ID", str(payload.get("id") or payload.get("job_run_id") or "-")),
+            ("Job Run UID", str(payload.get("uid") or payload.get("job_run_uid") or "-")),
             ("Name", str(payload.get("name") or payload.get("job_name") or "-")),
             ("Unique Identifier", str(payload.get("unique_identifier") or "-")),
             ("Status", str(payload.get("status") or "-")),
@@ -10208,7 +10208,8 @@ def project_jobs_run_cmd(
                 "job",
                 "job_id",
                 "id",
-                "job_run_id",
+                "uid",
+                "job_run_uid",
                 "name",
                 "job_name",
                 "unique_identifier",
@@ -10254,8 +10255,8 @@ def project_job_runs_list_cmd(
 
 @project_job_runs_group.command("logs")
 def project_job_runs_logs_cmd(
-    job_run_id: int = pydantic_argument(
-        JOB_RUN_MODEL_REF, "id", ..., help="Job run ID whose logs will be shown."
+    job_run_uid: str = pydantic_argument(
+        JOB_RUN_MODEL_REF, "uid", ..., help="Job run UID whose logs will be shown."
     ),
     poll_interval: int = typer.Option(
         30,
@@ -10279,10 +10280,10 @@ def project_job_runs_logs_cmd(
     Examples
     --------
     ```bash
-    mainsequence project jobs runs logs 501
-    mainsequence project jobs runs logs 501 --poll-interval 10
-    mainsequence project jobs runs logs 501 --max-wait-seconds 900
-    mainsequence project jobs runs logs 501 --poll-interval 0
+    mainsequence project jobs runs logs 4c1d77c8-8a42-42b8-a9c1-06be9a336e5d
+    mainsequence project jobs runs logs 4c1d77c8-8a42-42b8-a9c1-06be9a336e5d --poll-interval 10
+    mainsequence project jobs runs logs 4c1d77c8-8a42-42b8-a9c1-06be9a336e5d --max-wait-seconds 900
+    mainsequence project jobs runs logs 4c1d77c8-8a42-42b8-a9c1-06be9a336e5d --poll-interval 0
     ```
     """
     _require_login()
@@ -10296,7 +10297,7 @@ def project_job_runs_logs_cmd(
 
     while True:
         try:
-            payload = get_project_job_run_logs(job_run_id=job_run_id, timeout=timeout)
+            payload = get_project_job_run_logs(job_run_uid=job_run_uid, timeout=timeout)
         except ApiError as e:
             error(f"Project job run logs fetch failed: {e}")
             raise typer.Exit(1) from e
@@ -10313,7 +10314,7 @@ def project_job_runs_logs_cmd(
             print_kv(
                 "Job Run Logs",
                 [
-                    ("Job Run ID", str(payload.get("job_run_id") or job_run_id)),
+                    ("Job Run UID", str(payload.get("job_run_uid") or payload.get("uid") or job_run_uid)),
                     ("Status", status_value),
                 ],
             )

{mainsequence-4.1.5 → 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.5 → mainsequence-4.1.7}/mainsequence/logconf.py

@@ -236,13 +236,11 @@ def _build_backend_bindings(
     if project_id is not None:
         bindings["project_id"] = project_id
         bindings["data_source_id"] = startup_state.get("data_source_id")
-        bindings["job_run_id"] = startup_state.get("job_run_id")
         bindings["job_run_uid"] = startup_state.get("job_run_uid")
         bindings["command_id"] = startup_state.get("command_id")
     else:
-        # your existing behavior: bind job_run_id to user_id in local-ish mode
         if "user_id" in startup_state:
-            bindings["job_run_id"] = startup_state.get("user_id")
+            bindings["user_id"] = startup_state.get("user_id")
         else:
             bindings["local_mode"] = "no_app"
 

{mainsequence-4.1.5 → 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",

{mainsequence-4.1.5 → mainsequence-4.1.7}/mainsequence/meta_tables/data_nodes/build_operations.py

@@ -96,7 +96,7 @@ def _(value: type[Any]) -> Any:
     uid = getattr(time_index_metadata, "uid", None)
     if uid in (None, ""):
         raise ValueError(
-            "PlatformTimeIndexMetaData config values must be registered or bound "
+            "PlatformTimeIndexMetaData config values must be registered "
             "before they can be hashed."
         )
     return {

{mainsequence-4.1.5 → mainsequence-4.1.7}/mainsequence/meta_tables/data_nodes/data_nodes.py

@@ -647,7 +647,7 @@ class DataNode(DataAccessMixin, ABC):
             )
         if value.get_time_index_metadata() is None:
             raise ValueError(
-                "DataNode storage_table must be registered or bound before construction."
+                "DataNode storage_table must be registered before construction."
             )
         if value.get_meta_table_uid() in (None, ""):
             raise ValueError("DataNode storage_table must provide a MetaTable UID.")
@@ -659,7 +659,7 @@ class DataNode(DataAccessMixin, ABC):
     def storage_metadata(self) -> Any:
         storage_metadata = self.storage_table.get_time_index_metadata()
         if storage_metadata is None:
-            raise ValueError("DataNode storage_table must be registered or bound before use.")
+            raise ValueError("DataNode storage_table must be registered before use.")
         return storage_metadata
 
     def _initialize_configuration(self, init_kwargs: dict) -> None:

{mainsequence-4.1.5 → mainsequence-4.1.7}/mainsequence/meta_tables/data_nodes/persist_managers.py

@@ -130,7 +130,7 @@ class BasePersistManager:
         storage_metadata = storage_table.get_time_index_metadata()
         if storage_metadata is None:
             raise ValueError(
-                "PersistManager storage_table must be registered or bound before "
+                "PersistManager storage_table must be registered before "
                 "constructing the DataNode."
             )
         if storage_table.get_meta_table_uid() in (None, ""):
@@ -143,7 +143,7 @@ class BasePersistManager:
     def storage_metadata(self) -> Any:
         storage_metadata = self.storage_table.get_time_index_metadata()
         if storage_metadata is None:
-            raise ValueError("PersistManager storage_table must be registered or bound before use.")
+            raise ValueError("PersistManager storage_table must be registered before use.")
         return storage_metadata
 
     @property