mainsequence 4.0.0__tar.gz → 4.0.5__tar.gz

{mainsequence-4.0.0 → mainsequence-4.0.5}/PKG-INFO

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

{mainsequence-4.0.0 → mainsequence-4.0.5}/agent_scaffold/skills/data_publishing/meta_tables/SKILL.md

@@ -15,7 +15,8 @@ This skill is for schema-driven application tables registered through TS Manager
 
 - define SQLAlchemy/Core or ORM table models for `MetaTable` registration
 - choose `platform_managed` or `external_registered` management mode
-- build registration requests from resolved SQLAlchemy metadata
+- register platform-managed tables through the model class API
+- build registration requests from resolved SQLAlchemy metadata when inspection is useful
 - define indexes and foreign keys in the table contract
 - design governed compiled SQL read and write operations
 - review table contracts for physical-name, namespace, and identifier issues
@@ -67,7 +68,7 @@ Before changing code, collect or infer:
 - expected read patterns
 - expected mutation patterns
 - whether TS Manager should create the physical table
-- the target `DynamicTableDataSource` UID
+- for `external_registered`, the target `DynamicTableDataSource` UID
 
 If ownership of the physical table lifecycle is unclear, stop before choosing a management mode.
 
@@ -92,15 +93,67 @@ Do not hand-build contract fragments when the SQLAlchemy helper can derive them.
 
 ### 2. Use storage-hash physical names for backend-managed tables
 
-For `platform_managed`, use `metatable_tablename(...)` as the SQLAlchemy `__tablename__`.
+For `platform_managed`, inherit from `PlatformManagedMetaTable`.
 
-The backend expects that deterministic physical name to match the registration storage hash.
+The mixin derives the SQLAlchemy physical table name from storage-relevant configuration and table shape. Do not hand-write `__tablename__` for normal backend-managed tables.
+
+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.
+
+Register through the class API:
+
+```python
+account_meta_table = Account.register(
+    description="Example account table.",
+    labels=["sdk-example"],
+)
+```
+
+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.
+
+For SDK examples, use a plain namespace constant:
+
+```python
+NAMESPACE = "sdk-examples"
+```
+
+Do not add an environment variable for namespace in examples.
+
+Do not add generic labels such as `"meta-table"` or `"platform-managed"` to examples. Keep labels specific to the example or domain.
+
+Do not add a `MAINSEQUENCE_META_TABLE_REGISTER` toggle in registration examples. Registration examples should register directly.
 
 ### 3. Register parent tables before child tables
 
 Foreign-key contracts reference the target `MetaTable` UID.
 
-Register parent tables first, then pass their UIDs when building child table registration requests.
+For `PlatformManagedMetaTable`, register parent tables first and then register child tables normally. The SDK inspects SQLAlchemy foreign-key constraints and resolves each target `MetaTable` by looking up the already registered table in the same data source, schema, and physical table name.
+
+Example registration order:
+
+```python
+account_meta_table = Account.register(...)
+asset_meta_table = Asset.register(...)
+```
+
+The child registration will fail if the parent table has not already been registered, because there is no target `MetaTable.uid` for the backend FK contract.
+
+Do not pass `target_meta_tables` or `target_meta_table_uid_by_fullname` in the normal platform-managed path. Use explicit FK target mappings only for edge cases where automatic lookup is ambiguous or impossible.
+
+For `external_registered`, there is no platform-managed parent lookup through the model class. Register the parent first, then build the child registration request with the parent UID mapped by target table fullname:
+
+```python
+account_meta_table = MetaTable.register(account_request)
+asset_request = external_registered_registration_request_from_sqlalchemy_model(
+    Asset,
+    data_source_uid=data_source_uid,
+    target_meta_table_uid_by_fullname={
+        Account.__table__.fullname: account_meta_table.uid,
+    },
+)
+asset_meta_table = MetaTable.register(asset_request)
+```
 
 ### 4. Governed operations declare scope
 
@@ -119,9 +172,12 @@ Do not hardcode platform-managed physical names manually.
 When reviewing an existing MetaTable workflow, look for:
 
 - missing namespace or identifier
-- backend-managed models that do not use `metatable_tablename(...)`
+- 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
 - external tables registered with unstable physical names
-- foreign keys that do not reference target MetaTable UIDs
+- platform-managed child tables that are registered before parent tables
+- external child registrations that do not map foreign-key targets to registered parent `MetaTable.uid` values
 - compiled SQL operations without complete table scope
 - raw SQL that hardcodes stale physical names
 - a table that should really be modeled as a DataNode instead
@@ -132,7 +188,7 @@ Do not claim success until you have checked:
 
 - the table contract matches the intended row contract
 - indexes are intentional
-- foreign keys point to the correct dependency targets
+- foreign keys resolve to the correct dependency targets
 - management mode is correct
 - backend-managed physical names match the storage hash
 - registration returns a `MetaTable.uid`
@@ -141,13 +197,14 @@ Do not claim success until you have checked:
 For related tables, also check:
 
 - aliases are readable
-- parent table UIDs are passed into child contracts
+- platform-managed parent tables are registered before child tables
+- external child registration requests map FK targets to the registered parent UIDs
 - query results still match the expected response contract
 
 ## This Skill Must Stop And Escalate When
 
 - physical table lifecycle ownership is unclear
-- the target data source is unknown
+- the target data source is unknown for an `external_registered` workflow
 - the task really requires a time-series published table
 - the workflow requires direct database credentials outside TS Manager governance
 - the task is actually an API or orchestration problem

{mainsequence-4.0.0 → mainsequence-4.0.5}/mainsequence/bootstrap.py

@@ -20,7 +20,7 @@ def _read_local_env_values(env_path: pathlib.Path) -> dict[str, str]:
         return {}
 
     values: dict[str, str] = {}
-    for key in ("MAINSEQUENCE_ENDPOINT", "MAIN_SEQUENCE_PROJECT_ID"):
+    for key in ("MAINSEQUENCE_ENDPOINT", "MAIN_SEQUENCE_PROJECT_UID", "MAIN_SEQUENCE_PROJECT_ID"):
         match = re.search(rf"(?m)^{re.escape(key)}=(.+?)\s*$", content)
         if match:
             values[key] = match.group(1).strip()
@@ -35,6 +35,7 @@ def prime_runtime_env() -> None:
     local_values = _read_local_env_values(pathlib.Path.cwd() / ".env")
 
     _set_if_missing("MAINSEQUENCE_ENDPOINT", local_values.get("MAINSEQUENCE_ENDPOINT"))
+    _set_if_missing("MAIN_SEQUENCE_PROJECT_UID", local_values.get("MAIN_SEQUENCE_PROJECT_UID"))
     _set_if_missing("MAIN_SEQUENCE_PROJECT_ID", local_values.get("MAIN_SEQUENCE_PROJECT_ID"))
 
     try:

{mainsequence-4.0.0 → mainsequence-4.0.5}/mainsequence/cli/api.py

@@ -432,6 +432,7 @@ def _run_sdk_model_operation(
     class_name: str,
     operation,
     project_id_env: int | str | None = None,
+    project_uid_env: str | None = None,
 ):
     tokens = get_tokens()
     access = (tokens.get("access") or "").strip()
@@ -447,6 +448,7 @@ def _run_sdk_model_operation(
         "MAINSEQUENCE_ACCESS_TOKEN": os.environ.get("MAINSEQUENCE_ACCESS_TOKEN"),
         "MAINSEQUENCE_REFRESH_TOKEN": os.environ.get("MAINSEQUENCE_REFRESH_TOKEN"),
         "MAINSEQUENCE_ENDPOINT": os.environ.get("MAINSEQUENCE_ENDPOINT"),
+        "MAIN_SEQUENCE_PROJECT_UID": os.environ.get("MAIN_SEQUENCE_PROJECT_UID"),
         "MAIN_SEQUENCE_PROJECT_ID": os.environ.get("MAIN_SEQUENCE_PROJECT_ID"),
     }
 
@@ -464,6 +466,12 @@ def _run_sdk_model_operation(
         else:
             os.environ.pop("MAINSEQUENCE_REFRESH_TOKEN", None)
         os.environ["MAINSEQUENCE_ENDPOINT"] = endpoint
+        if project_uid_env is not None:
+            os.environ["MAIN_SEQUENCE_PROJECT_UID"] = str(project_uid_env)
+        elif project_id_env is not None and not str(project_id_env).strip().isdigit():
+            os.environ["MAIN_SEQUENCE_PROJECT_UID"] = str(project_id_env)
+        else:
+            os.environ.pop("MAIN_SEQUENCE_PROJECT_UID", None)
         if project_id_env is not None:
             os.environ["MAIN_SEQUENCE_PROJECT_ID"] = str(project_id_env)
         else:
@@ -521,20 +529,30 @@ def _run_sdk_model_operation(
 
 def get_current_user_profile() -> dict:
     """
-    Return current user profile (username + organization name) via backend endpoints.
+    Return current user profile (username + organization name) via the canonical user-details endpoint.
 
     Returns:
         dict: {"username": "...", "organization": "..."} or {}
     """
-    who = authed("GET", AUTH_PATHS["ping"])
-    d = who.json() if who.ok else {}
-    uid = d.get("id") or d.get("pk") or (d.get("user") or {}).get("id") or d.get("user_id")
-    if not uid:
-        return {}
-    full = authed("GET", f"/user/api/user/{uid}/")
-    u = full.json() if full.ok else {}
-    org_name = (u.get("organization") or {}).get("name") or u.get("organization_name") or ""
-    return {"username": u.get("username") or "", "organization": org_name}
+    details = authed("GET", "/user/api/user/get_user_details/")
+    payload = details.json() if details.ok else {}
+    user = payload.get("user") if isinstance(payload, dict) else {}
+    if not isinstance(user, dict):
+        user = {}
+    organization = user.get("organization") if isinstance(user, dict) else {}
+    if not isinstance(organization, dict):
+        organization = {}
+    payload_organization = payload.get("organization") if isinstance(payload, dict) else {}
+    if not isinstance(payload_organization, dict):
+        payload_organization = {}
+    org_name = (
+        organization.get("name")
+        or payload_organization.get("name")
+        or payload.get("organization_name")
+        or payload.get("organization")
+        or ""
+    )
+    return {"username": user.get("username") or payload.get("username") or "", "organization": org_name}
 
 
 def get_logged_user_details() -> dict[str, Any]:
@@ -676,6 +694,65 @@ def get_projects() -> list[dict]:
     return data.get("results") or []
 
 
+def _normalize_project_reference(project_ref: int | str) -> str:
+    normalized = str(project_ref).strip()
+    if not normalized:
+        raise ApiError("Project UID is required.")
+    return normalized
+
+
+def _project_matches_reference(project_payload: dict[str, Any], project_ref: str) -> bool:
+    return (
+        str(project_payload.get("uid") or "").strip() == project_ref
+        or str(project_payload.get("id") or "").strip() == project_ref
+    )
+
+
+def resolve_project(project_ref: int | str) -> dict[str, Any]:
+    normalized_ref = _normalize_project_reference(project_ref)
+
+    try:
+        payload = get_project(normalized_ref)
+        if isinstance(payload, dict) and payload:
+            return payload
+    except ApiError:
+        pass
+
+    for project_payload in get_projects():
+        if isinstance(project_payload, dict) and _project_matches_reference(project_payload, normalized_ref):
+            return project_payload
+
+    raise ApiError(f"Project not found: {normalized_ref}")
+
+
+def resolve_project_uid(project_ref: int | str) -> str:
+    normalized_ref = _normalize_project_reference(project_ref)
+    if normalized_ref.isdigit():
+        return normalized_ref
+
+    payload = resolve_project(project_ref)
+    normalized_uid = str(payload.get("uid") or "").strip()
+    if normalized_uid:
+        return normalized_uid
+    if not normalized_ref.isdigit():
+        return normalized_ref
+    raise ApiError(f"Project UID is not available for project reference: {normalized_ref}")
+
+
+def resolve_project_row_id(project_ref: int | str) -> int:
+    normalized_ref = _normalize_project_reference(project_ref)
+    if normalized_ref.isdigit():
+        return int(normalized_ref)
+
+    payload = resolve_project(project_ref)
+    row_id = payload.get("id")
+    if row_id is None:
+        if normalized_ref.isdigit():
+            return int(normalized_ref)
+        raise ApiError(f"Backend row id is not available for project reference: {normalized_ref}")
+    return int(row_id)
+
+
 def search_projects(
     q: str,
     *,
@@ -1395,7 +1472,7 @@ def get_agent_run(
 
 def get_project(project_id: int | str) -> dict:
     """
-    Fetch a single project by id.
+    Fetch a single project by public reference.
     """
     r = authed("GET", f"/orm/api/pods/projects/{project_id}/")
     if not r.ok:
@@ -1748,6 +1825,7 @@ def get_project_data_node_updates(project_id: int | str, *, timeout: int | None
         "MAINSEQUENCE_ACCESS_TOKEN": os.environ.get("MAINSEQUENCE_ACCESS_TOKEN"),
         "MAINSEQUENCE_REFRESH_TOKEN": os.environ.get("MAINSEQUENCE_REFRESH_TOKEN"),
         "MAINSEQUENCE_ENDPOINT": os.environ.get("MAINSEQUENCE_ENDPOINT"),
+        "MAIN_SEQUENCE_PROJECT_UID": os.environ.get("MAIN_SEQUENCE_PROJECT_UID"),
         "MAIN_SEQUENCE_PROJECT_ID": os.environ.get("MAIN_SEQUENCE_PROJECT_ID"),
     }
 
@@ -1765,7 +1843,10 @@ def get_project_data_node_updates(project_id: int | str, *, timeout: int | None
         else:
             os.environ.pop("MAINSEQUENCE_REFRESH_TOKEN", None)
         os.environ["MAINSEQUENCE_ENDPOINT"] = endpoint
-        os.environ["MAIN_SEQUENCE_PROJECT_ID"] = str(project_id)
+        project_uid = resolve_project_uid(project_id)
+        project_row_id = resolve_project_row_id(project_id)
+        os.environ["MAIN_SEQUENCE_PROJECT_UID"] = project_uid
+        os.environ["MAIN_SEQUENCE_PROJECT_ID"] = str(project_row_id)
 
         from mainsequence.client import utils as _client_utils
         from mainsequence.client.base import BaseObjectOrm
@@ -1782,7 +1863,7 @@ def get_project_data_node_updates(project_id: int | str, *, timeout: int | None
         BaseObjectOrm.ROOT_URL = root_url
         ClientProject.ROOT_URL = root_url
 
-        project = ClientProject.get(pk=project_id, timeout=timeout)
+        project = ClientProject.get(pk=project_uid, timeout=timeout)
         updates = project.get_data_nodes_updates(timeout=timeout)
 
         out: list[dict[str, Any]] = []
@@ -1839,14 +1920,16 @@ def sync_project_after_commit(project_id: int | str, *, timeout: int | None = No
       - delegates request behavior and payload parsing to `Project.sync_project_after_commit()`
     """
     try:
+        project_uid = resolve_project_uid(project_id)
         payload = _run_sdk_model_operation(
             module_name="mainsequence.client.models_tdag",
             class_name="Project",
             operation=lambda ClientProject: ClientProject.sync_project_after_commit(
-                int(project_id),
+                project_uid,
                 timeout=timeout,
             ),
-            project_id_env=project_id,
+            project_id_env=resolve_project_row_id(project_id),
+            project_uid_env=project_uid,
         )
         if payload is None:
             return None
@@ -1911,6 +1994,7 @@ def create_project_image(
         "MAINSEQUENCE_ACCESS_TOKEN": os.environ.get("MAINSEQUENCE_ACCESS_TOKEN"),
         "MAINSEQUENCE_REFRESH_TOKEN": os.environ.get("MAINSEQUENCE_REFRESH_TOKEN"),
         "MAINSEQUENCE_ENDPOINT": os.environ.get("MAINSEQUENCE_ENDPOINT"),
+        "MAIN_SEQUENCE_PROJECT_UID": os.environ.get("MAIN_SEQUENCE_PROJECT_UID"),
         "MAIN_SEQUENCE_PROJECT_ID": os.environ.get("MAIN_SEQUENCE_PROJECT_ID"),
     }
 
@@ -1927,7 +2011,10 @@ def create_project_image(
         else:
             os.environ.pop("MAINSEQUENCE_REFRESH_TOKEN", None)
         os.environ["MAINSEQUENCE_ENDPOINT"] = endpoint
-        os.environ["MAIN_SEQUENCE_PROJECT_ID"] = str(related_project_id)
+        project_uid = resolve_project_uid(related_project_id)
+        project_row_id = resolve_project_row_id(related_project_id)
+        os.environ["MAIN_SEQUENCE_PROJECT_UID"] = project_uid
+        os.environ["MAIN_SEQUENCE_PROJECT_ID"] = str(project_row_id)
 
         from mainsequence.client import utils as _client_utils
         from mainsequence.client.base import BaseObjectOrm
@@ -1946,7 +2033,7 @@ def create_project_image(
 
         created = ClientProjectImage.create(
             project_repo_hash=project_repo_hash,
-            related_project_id=int(related_project_id),
+            related_project_id=project_row_id,
             base_image_id=base_image_id,
             timeout=timeout,
         )
@@ -2018,6 +2105,7 @@ def list_project_images(
         "MAINSEQUENCE_ACCESS_TOKEN": os.environ.get("MAINSEQUENCE_ACCESS_TOKEN"),
         "MAINSEQUENCE_REFRESH_TOKEN": os.environ.get("MAINSEQUENCE_REFRESH_TOKEN"),
         "MAINSEQUENCE_ENDPOINT": os.environ.get("MAINSEQUENCE_ENDPOINT"),
+        "MAIN_SEQUENCE_PROJECT_UID": os.environ.get("MAIN_SEQUENCE_PROJECT_UID"),
         "MAIN_SEQUENCE_PROJECT_ID": os.environ.get("MAIN_SEQUENCE_PROJECT_ID"),
     }
 
@@ -2034,7 +2122,10 @@ def list_project_images(
         else:
             os.environ.pop("MAINSEQUENCE_REFRESH_TOKEN", None)
         os.environ["MAINSEQUENCE_ENDPOINT"] = endpoint
-        os.environ["MAIN_SEQUENCE_PROJECT_ID"] = str(related_project_id)
+        project_uid = resolve_project_uid(related_project_id)
+        project_row_id = resolve_project_row_id(related_project_id)
+        os.environ["MAIN_SEQUENCE_PROJECT_UID"] = project_uid
+        os.environ["MAIN_SEQUENCE_PROJECT_ID"] = str(project_row_id)
 
         from mainsequence.client import utils as _client_utils
         from mainsequence.client.base import BaseObjectOrm
@@ -2052,7 +2143,7 @@ def list_project_images(
         ClientProjectImage.ROOT_URL = root_url
 
         merged_filters = dict(filters or {})
-        merged_filters["related_project__id__in"] = [int(related_project_id)]
+        merged_filters["related_project__id__in"] = [project_row_id]
         images = ClientProjectImage.filter(timeout=timeout, **merged_filters)
 
         out: list[dict[str, Any]] = []
@@ -2243,6 +2334,7 @@ def list_project_jobs(
         "MAINSEQUENCE_ACCESS_TOKEN": os.environ.get("MAINSEQUENCE_ACCESS_TOKEN"),
         "MAINSEQUENCE_REFRESH_TOKEN": os.environ.get("MAINSEQUENCE_REFRESH_TOKEN"),
         "MAINSEQUENCE_ENDPOINT": os.environ.get("MAINSEQUENCE_ENDPOINT"),
+        "MAIN_SEQUENCE_PROJECT_UID": os.environ.get("MAIN_SEQUENCE_PROJECT_UID"),
         "MAIN_SEQUENCE_PROJECT_ID": os.environ.get("MAIN_SEQUENCE_PROJECT_ID"),
     }
 
@@ -2259,7 +2351,10 @@ def list_project_jobs(
         else:
             os.environ.pop("MAINSEQUENCE_REFRESH_TOKEN", None)
         os.environ["MAINSEQUENCE_ENDPOINT"] = endpoint
-        os.environ["MAIN_SEQUENCE_PROJECT_ID"] = str(project_id)
+        project_uid = resolve_project_uid(project_id)
+        project_row_id = resolve_project_row_id(project_id)
+        os.environ["MAIN_SEQUENCE_PROJECT_UID"] = project_uid
+        os.environ["MAIN_SEQUENCE_PROJECT_ID"] = str(project_row_id)
 
         from mainsequence.client import utils as _client_utils
         from mainsequence.client.base import BaseObjectOrm
@@ -2279,7 +2374,7 @@ def list_project_jobs(
         extra_filters = dict(filters or {})
         jobs = ClientJob.filter(
             timeout=timeout,
-            **{**extra_filters, "project__id": int(project_id)},
+            **{**extra_filters, "project__id": project_row_id},
         )
 
         out: list[dict[str, Any]] = []
@@ -2355,6 +2450,7 @@ def list_project_resources(
         "MAINSEQUENCE_ACCESS_TOKEN": os.environ.get("MAINSEQUENCE_ACCESS_TOKEN"),
         "MAINSEQUENCE_REFRESH_TOKEN": os.environ.get("MAINSEQUENCE_REFRESH_TOKEN"),
         "MAINSEQUENCE_ENDPOINT": os.environ.get("MAINSEQUENCE_ENDPOINT"),
+        "MAIN_SEQUENCE_PROJECT_UID": os.environ.get("MAIN_SEQUENCE_PROJECT_UID"),
         "MAIN_SEQUENCE_PROJECT_ID": os.environ.get("MAIN_SEQUENCE_PROJECT_ID"),
     }
 
@@ -2371,7 +2467,10 @@ def list_project_resources(
         else:
             os.environ.pop("MAINSEQUENCE_REFRESH_TOKEN", None)
         os.environ["MAINSEQUENCE_ENDPOINT"] = endpoint
-        os.environ["MAIN_SEQUENCE_PROJECT_ID"] = str(project_id)
+        project_uid = resolve_project_uid(project_id)
+        project_row_id = resolve_project_row_id(project_id)
+        os.environ["MAIN_SEQUENCE_PROJECT_UID"] = project_uid
+        os.environ["MAIN_SEQUENCE_PROJECT_ID"] = str(project_row_id)
 
         from mainsequence.client import utils as _client_utils
         from mainsequence.client.base import BaseObjectOrm
@@ -2391,7 +2490,7 @@ def list_project_resources(
         merged_filters: dict[str, Any] = dict(filters or {})
         merged_filters.update(
             {
-            "project__id": int(project_id),
+            "project__id": project_row_id,
             "repo_commit_sha": str(repo_commit_sha).strip(),
             }
         )
@@ -4210,6 +4309,7 @@ def create_project_job(
         "MAINSEQUENCE_ACCESS_TOKEN": os.environ.get("MAINSEQUENCE_ACCESS_TOKEN"),
         "MAINSEQUENCE_REFRESH_TOKEN": os.environ.get("MAINSEQUENCE_REFRESH_TOKEN"),
         "MAINSEQUENCE_ENDPOINT": os.environ.get("MAINSEQUENCE_ENDPOINT"),
+        "MAIN_SEQUENCE_PROJECT_UID": os.environ.get("MAIN_SEQUENCE_PROJECT_UID"),
         "MAIN_SEQUENCE_PROJECT_ID": os.environ.get("MAIN_SEQUENCE_PROJECT_ID"),
     }
 
@@ -4226,7 +4326,10 @@ def create_project_job(
         else:
             os.environ.pop("MAINSEQUENCE_REFRESH_TOKEN", None)
         os.environ["MAINSEQUENCE_ENDPOINT"] = endpoint
-        os.environ["MAIN_SEQUENCE_PROJECT_ID"] = str(project_id)
+        project_uid = resolve_project_uid(project_id)
+        project_row_id = resolve_project_row_id(project_id)
+        os.environ["MAIN_SEQUENCE_PROJECT_UID"] = project_uid
+        os.environ["MAIN_SEQUENCE_PROJECT_ID"] = str(project_row_id)
 
         from mainsequence.client import utils as _client_utils
         from mainsequence.client.base import BaseObjectOrm
@@ -4245,7 +4348,7 @@ def create_project_job(
 
         created = ClientJob.create(
             name=name,
-            project_id=int(project_id),
+            project_id=project_row_id,
             execution_path=execution_path,
             app_name=app_name,
             task_schedule=task_schedule,
@@ -4331,6 +4434,7 @@ def schedule_batch_project_jobs(
         "MAINSEQUENCE_ACCESS_TOKEN": os.environ.get("MAINSEQUENCE_ACCESS_TOKEN"),
         "MAINSEQUENCE_REFRESH_TOKEN": os.environ.get("MAINSEQUENCE_REFRESH_TOKEN"),
         "MAINSEQUENCE_ENDPOINT": os.environ.get("MAINSEQUENCE_ENDPOINT"),
+        "MAIN_SEQUENCE_PROJECT_UID": os.environ.get("MAIN_SEQUENCE_PROJECT_UID"),
         "MAIN_SEQUENCE_PROJECT_ID": os.environ.get("MAIN_SEQUENCE_PROJECT_ID"),
     }
 
@@ -4347,7 +4451,10 @@ def schedule_batch_project_jobs(
         else:
             os.environ.pop("MAINSEQUENCE_REFRESH_TOKEN", None)
         os.environ["MAINSEQUENCE_ENDPOINT"] = endpoint
-        os.environ["MAIN_SEQUENCE_PROJECT_ID"] = str(project_id)
+        project_uid = resolve_project_uid(project_id)
+        project_row_id = resolve_project_row_id(project_id)
+        os.environ["MAIN_SEQUENCE_PROJECT_UID"] = project_uid
+        os.environ["MAIN_SEQUENCE_PROJECT_ID"] = str(project_row_id)
 
         from mainsequence.client import utils as _client_utils
         from mainsequence.client.base import BaseObjectOrm
@@ -4366,7 +4473,7 @@ def schedule_batch_project_jobs(
 
         created = ClientJob.bulk_get_or_create(
             yaml_file=file_path,
-            project_id=int(project_id),
+            project_id=project_row_id,
             strict=bool(strict),
             timeout=timeout,
         )
@@ -4866,13 +4973,14 @@ def create_project(
 
 def delete_project(project_id: int | str, *, delete_repositories: bool = False) -> dict[str, Any] | None:
     """
-    Delete a project by id.
+    Delete a project by public reference.
 
     Mirrors backend behavior:
-      - DELETE /orm/api/pods/projects/{id}/
+      - DELETE /orm/api/pods/projects/{uid}/
       - optional query param delete_repositories=true
     """
-    path = f"/orm/api/pods/projects/{project_id}/"
+    project_uid = resolve_project_uid(project_id)
+    path = f"/orm/api/pods/projects/{project_uid}/"
     if delete_repositories:
         path = f"{path}?delete_repositories=true"
 
@@ -4942,7 +5050,7 @@ def add_deploy_key(project_id: int | str, key_title: str, public_key: str) -> No
     """
     r = authed(
         "POST",
-        f"/orm/api/pods/projects/{project_id}/add_deploy_key/",
+        f"/orm/api/pods/projects/{resolve_project_uid(project_id)}/add_deploy_key/",
         {"key_title": key_title, "public_key": public_key},
     )
     r.raise_for_status()