mainsequence 4.4.16__tar.gz → 4.4.19__tar.gz

{mainsequence-4.4.16/mainsequence.egg-info → mainsequence-4.4.19}/PKG-INFO

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

{mainsequence-4.4.16 → mainsequence-4.4.19}/agent_scaffold/skills/a2a_communication/SKILL.md

@@ -83,6 +83,10 @@ mainsequence agent session a2a send \
 - Parse the CLI output as the standard A2A JSON response.
 - Consume only `message.parts` from the A2A response.
 - Do not depend on reasoning, tool traces, runtime paths, or transport metadata.
+- If a send times out or disconnects and must be retried, reuse the same
+  `--message-id` value so the target can treat it as the same logical message.
+- If the CLI generated the message id and the send failed, reuse the
+  `A2A message id for exact retry` value printed with the error.
 
 ## Deterministic Execution Path
 

{mainsequence-4.4.16 → mainsequence-4.4.19}/agent_scaffold/skills/data_access/exploration/SKILL.md

@@ -92,22 +92,81 @@ For platform discovery, start with the `mainsequence` CLI.
 
 Discovery priority:
 
-- use search first when the surface supports search
-- use list and filters when the surface does not support search
+- use semantic description search first when the user describes a dataset in natural language
+- use list and filters only when the user already knows a structured field to constrain by
+- use column lookup only when the user is specifically searching for a schema or column name
 - use detail only after you have identified the candidate object you want to inspect
 
-Typical commands include:
+Semantic description discovery searches `MetaTable` metadata rows through:
+
+- `GET /orm/api/ts_manager/meta_table/description-search/?q=<text>`
+
+The same discovery surface applies to `MetaTable` metadata and to published
+`DataNode` storage tables, because `DataNode` storage is represented by
+`TimeIndexMetaTable` metadata.
+
+Typical semantic discovery commands:
 
 - `mainsequence data-node search "<keyword>"`
-- `mainsequence data-node search "<keyword>" --mode description`
-- `mainsequence data-node search "<keyword>" --mode column`
-- `mainsequence data-node search "<keyword>" --show-filters`
-- `mainsequence data-node search "<keyword>" --filter KEY=VALUE`
+
+Optional ranking knobs for description discovery:
+
+- `--trigram-k 200`
+- `--embed-k 200`
+- `--w-trgm 0.65`
+- `--w-emb 0.35`
+
+The response is paginated metadata:
+
+```json
+{
+  "count": 2,
+  "next": null,
+  "previous": null,
+  "results": [
+    {
+      "orm_class": "TimeIndexMetaTable",
+      "uid": "0b0f5733-b1ee-4d09-b51f-9e29073007fd",
+      "data_source_uid": "864e7c22-482a-464a-8758-0d3408abd77f",
+      "identifier": "ms_markets__externalpricests__mainsequence_examples",
+      "namespace": "mainsequence.examples",
+      "description": "...",
+      "physical_table_name": "ms_markets__externalpricests__mainsequence_examples",
+      "table_contract": {},
+      "columns": [],
+      "indexes_meta": [],
+      "foreign_keys": [],
+      "cadence": "1d",
+      "time_indexed_profile": {}
+    }
+  ]
+}
+```
+
+Structured filtering is a different path. Use it only when you already know the
+field to filter by:
+
 - `mainsequence data-node list`
 - `mainsequence data-node list --show-filters`
 - `mainsequence data-node list --filter KEY=VALUE`
 - `mainsequence data-node detail <DATA_NODE_STORAGE_UID>`
 
+Column lookup is also a different path. Use it only for schema-name discovery,
+not as the default dataset discovery flow:
+
+- `mainsequence data-node search "<column-name>" --mode column`
+
+Raw SQL inspection is only for targeted exploration after you have a UID:
+
+- `mainsequence meta-table run_query <META_TABLE_UID> "SELECT * FROM public.some_table LIMIT 100"`
+- `mainsequence data-node run_query <DATA_NODE_STORAGE_UID> "SELECT * FROM public.some_table LIMIT 100"`
+
+Use the MetaTable command for `MetaTable` UIDs. Use the DataNode command only
+for `DataNode` storage UIDs. Do not confuse the two surfaces.
+
+For direct SDK/backend usage, MetaTable raw SQL is sent as a JSON string body,
+not as an object. Do not send `{ "sql": "SELECT ..." }`.
+
 ### 2. Stop at discovery boundaries
 
 Use the CLI or SDK client to identify what exists and collect the relevant identifiers, object UIDs, and metadata.
@@ -117,7 +176,8 @@ Do not define code-level read patterns here.
 For `DataNode` discovery specifically:
 
 - start with `mainsequence data-node search`
-- use `mainsequence data-node list` when you need broader enumeration or structured filters
+- use `mainsequence data-node list` only when you need broader enumeration or structured filters
+- use `mainsequence data-node search "<column-name>" --mode column` only for schema-name lookup
 - use `mainsequence data-node detail` only after search or list identified the target storage
 
 ### 3. Report platform objects with evidence

{mainsequence-4.4.16 → mainsequence-4.4.19}/mainsequence/cli/api.py

@@ -24,7 +24,14 @@ from urllib.parse import urlencode
 
 import requests
 
-from .config import backend_url, get_tokens, save_tokens
+from .config import (
+    backend_url,
+    clear_runtime_access_cache,
+    get_runtime_access_cache,
+    get_tokens,
+    save_runtime_access_cache,
+    save_tokens,
+)
 
 AUTH_PATHS = {
     "authorize": "/auth/cli/authorize/",
@@ -39,7 +46,6 @@ CLI_BROWSER_CLIENT_ID = "mainsequence-cli"
 S = requests.Session()
 S.headers.update({"Content-Type": "application/json"})
 
-DEFAULT_AGENT_RUNTIME_READY_TIMEOUT_SECONDS = 900.0
 _UNSET = object()
 
 
@@ -1061,7 +1067,6 @@ def semantic_search_agents(
 def create_agent(
     *,
     name: str,
-    agent_unique_id: str,
     description: str | None = None,
     status: str | None = None,
     labels: list[str] | None = None,
@@ -1080,7 +1085,6 @@ def create_agent(
         key: value
         for key, value in {
             "name": name,
-            "agent_unique_id": agent_unique_id,
             "description": description,
             "status": status,
             "labels": labels,
@@ -1107,55 +1111,6 @@ def create_agent(
         raise ApiError(f"Agent creation failed: {e}") from e
 
 
-def get_or_create_agent(
-    *,
-    name: str,
-    agent_unique_id: str,
-    description: str | None = None,
-    status: str | None = None,
-    labels: list[str] | None = None,
-    llm_provider: str | None = None,
-    llm_model: str | None = None,
-    engine_name: str | None = None,
-    runtime_config: dict[str, Any] | None = None,
-    configuration: dict[str, Any] | None = None,
-    metadata: dict[str, Any] | None = None,
-    timeout: int | None = None,
-) -> dict[str, Any]:
-    """
-    Get or create one agent via SDK client model.
-    """
-    payload = {
-        key: value
-        for key, value in {
-            "name": name,
-            "agent_unique_id": agent_unique_id,
-            "description": description,
-            "status": status,
-            "labels": labels,
-            "llm_provider": llm_provider,
-            "llm_model": llm_model,
-            "engine_name": engine_name,
-            "runtime_config": runtime_config,
-            "configuration": configuration,
-            "metadata": metadata,
-        }.items()
-        if value is not None
-    }
-
-    try:
-        agent = _run_sdk_model_operation(
-            module_name="mainsequence.client.agent_runtime_models",
-            class_name="Agent",
-            operation=lambda ClientAgent: ClientAgent.get_or_create(timeout=timeout, **payload),
-        )
-        return _sdk_object_to_dict(agent)
-    except Exception as e:
-        if isinstance(e, (ApiError, NotLoggedIn)):
-            raise
-        raise ApiError(f"Agent get_or_create failed: {e}") from e
-
-
 def delete_agent(
     agent_uid: str,
     *,
@@ -1255,41 +1210,13 @@ def list_agent_sessions(
     timeout: int | None = None,
     filters: dict[str, Any] | None = None,
     agent_uid: str | None = None,
-    agent_unique_id: str | None = None,
 ) -> list[dict[str, Any]]:
     """
     List agent sessions via SDK client model, optionally scoped to one agent.
     """
-    if agent_uid and agent_unique_id:
-        raise ApiError("Pass either agent_uid or agent_unique_id, not both.")
-
     session_filters = dict(filters or {})
     if agent_uid:
         session_filters["agent_uid"] = str(agent_uid)
-    elif agent_unique_id:
-        try:
-            agent = _run_sdk_model_operation(
-                module_name="mainsequence.client.agent_runtime_models",
-                class_name="Agent",
-                operation=lambda ClientAgent: ClientAgent.get_by_agent_unique_id(
-                    str(agent_unique_id), timeout=timeout
-                ),
-            )
-        except Exception as e:
-            err_name = type(e).__name__
-            if err_name in {"DoesNotExist", "NotFoundError"}:
-                raise ApiError(f"Agent not found for agent_unique_id={agent_unique_id!r}") from e
-            if isinstance(e, (ApiError, NotLoggedIn)):
-                raise
-            raise ApiError(
-                f"Agent lookup failed for agent_unique_id={agent_unique_id!r}: {e}"
-            ) from e
-
-        resolved_agent = _sdk_object_to_dict(agent)
-        resolved_agent_uid = str(resolved_agent.get("uid") or "").strip()
-        if not resolved_agent_uid:
-            raise ApiError(f"Agent lookup returned no uid for agent_unique_id={agent_unique_id!r}")
-        session_filters["agent_uid"] = resolved_agent_uid
 
     try:
         payload = _run_sdk_model_operation(
@@ -1332,135 +1259,33 @@ def get_agent_session(
         raise ApiError(f"Agent session fetch failed: {e}") from e
 
 
-def resolve_agent_session_runtime_access(
-    agent_session_uid: str,
-    *,
-    wait_for_runtime: bool = False,
-    timeout: int | None = None,
-) -> dict[str, Any]:
-    """
-    Resolve runtime access for one agent session via SDK client model.
-    """
-    try:
-        runtime_access = _run_sdk_model_operation(
-            module_name="mainsequence.client.agent_runtime_models",
-            class_name="AgentSession",
-            operation=lambda ClientAgentSession: ClientAgentSession.resolve_runtime_access(
-                str(agent_session_uid),
-                wait_for_runtime=wait_for_runtime,
-                timeout=timeout,
-            ),
-        )
-        return _sdk_object_to_dict(runtime_access)
-    except Exception as e:
-        err_name = type(e).__name__
-        if err_name == "NotFoundError":
-            raise ApiError(f"Agent session not found: {agent_session_uid}") from e
-        if isinstance(e, (ApiError, NotLoggedIn)):
-            raise
-        raise ApiError(f"Agent session runtime access resolve failed: {e}") from e
-
-
-def wait_agent_session_runtime_ready(
-    agent_session_uid: str,
-    *,
-    timeout_seconds: float = DEFAULT_AGENT_RUNTIME_READY_TIMEOUT_SECONDS,
-    timeout: int | None = None,
-) -> dict[str, Any]:
-    """
-    Wait for one agent session runtime through SDK client model.
-    """
-    try:
-        ready = _run_sdk_model_operation(
-            module_name="mainsequence.client.agent_runtime_models",
-            class_name="AgentSession",
-            operation=lambda ClientAgentSession: ClientAgentSession.wait_until_runtime_ready(
-                str(agent_session_uid),
-                timeout_seconds=timeout_seconds,
-                timeout=timeout,
-            ),
-        )
-        return _sdk_object_to_dict(ready)
-    except Exception as e:
-        err_name = type(e).__name__
-        if err_name == "NotFoundError":
-            raise ApiError(f"Agent session not found: {agent_session_uid}") from e
-        if isinstance(e, (ApiError, NotLoggedIn)):
-            raise
-        raise ApiError(f"Agent session runtime readiness failed: {e}") from e
-
-
-def send_agent_session_a2a_chat(
-    agent_session_uid: str,
-    *,
-    message: str | None = None,
-    a2a_payload: dict[str, Any] | None = None,
-    wait_for_runtime: bool = True,
-    runtime_ready_timeout_seconds: float = DEFAULT_AGENT_RUNTIME_READY_TIMEOUT_SECONDS,
-    poll_task_until_stable: bool | None = None,
-    runtime_turn_timeout_seconds: float | None = None,
-    omit_reasoning: bool | None = None,
-    response_format: dict[str, Any] | None = None,
-    json_repair: dict[str, Any] | None = None,
-    timeout: int | None = None,
-) -> dict[str, Any]:
-    """
-    Send an A2A request through the legacy backend compatibility endpoint.
-    """
-    try:
-        chat = _run_sdk_model_operation(
-            module_name="mainsequence.client.agent_runtime_models",
-            class_name="AgentSession",
-            operation=lambda ClientAgentSession: ClientAgentSession.send_a2a_chat(
-                str(agent_session_uid),
-                message=message,
-                a2a_payload=a2a_payload,
-                wait_for_runtime=wait_for_runtime,
-                runtime_ready_timeout_seconds=runtime_ready_timeout_seconds,
-                poll_task_until_stable=poll_task_until_stable,
-                runtime_turn_timeout_seconds=runtime_turn_timeout_seconds,
-                omit_reasoning=omit_reasoning,
-                response_format=response_format,
-                json_repair=json_repair,
-                timeout=timeout,
-            ),
-        )
-        return _sdk_object_to_dict(chat)
-    except Exception as e:
-        err_name = type(e).__name__
-        if err_name == "NotFoundError":
-            raise ApiError(f"Agent session not found: {agent_session_uid}") from e
-        if isinstance(e, (ApiError, NotLoggedIn)):
-            raise
-        raise ApiError(f"Agent session A2A chat failed: {e}") from e
-
-
 def send_agent_session_a2a_message(
     agent_session_uid: str,
     *,
     message: str,
+    message_id: str | None = None,
     strict_dictionary: bool = False,
     json_repair_attempts: int = 3,
-    history_length: int = 0,
     return_immediately: bool = False,
-    wait_for_runtime: bool = True,
     timeout: int | None = None,
 ) -> dict[str, Any]:
     """
     Send one standard A2A message through the target session runtime.
     """
     try:
+        cached_runtime_access = get_runtime_access_cache(str(agent_session_uid))
         payload = _run_sdk_model_operation(
             module_name="mainsequence.client.agent_runtime_models",
             class_name="AgentSession",
-            operation=lambda ClientAgentSession: ClientAgentSession.send_a2a_message(
-                str(agent_session_uid),
+            operation=lambda ClientAgentSession: _send_agent_session_a2a_message_with_cache(
+                ClientAgentSession,
+                agent_session_uid=str(agent_session_uid),
                 message=message,
+                message_id=message_id,
+                cached_runtime_access=cached_runtime_access,
                 strict_dictionary=strict_dictionary,
                 json_repair_attempts=json_repair_attempts,
-                history_length=history_length,
                 return_immediately=return_immediately,
-                wait_for_runtime=wait_for_runtime,
                 timeout=timeout,
             ),
         )
@@ -1471,112 +1296,43 @@ def send_agent_session_a2a_message(
             raise ApiError(f"Agent session not found: {agent_session_uid}") from e
         if isinstance(e, (ApiError, NotLoggedIn)):
             raise
+        if "401" in str(e) or "403" in str(e) or "unauthorized" in str(e).lower():
+            clear_runtime_access_cache(str(agent_session_uid))
         raise ApiError(f"Agent session A2A message send failed: {e}") from e
 
 
-def chat_agent_session_runtime(
-    agent_session_uid: str,
+def _send_agent_session_a2a_message_with_cache(
+    ClientAgentSession,
     *,
-    message: str,
-    runtime_access: dict[str, Any] | None = None,
-    wait_for_runtime: bool = True,
-    runtime_turn_timeout_seconds: float | None = None,
-    omit_reasoning: bool | None = True,
-    response_format: dict[str, Any] | None = None,
-    json_repair: dict[str, Any] | None = None,
-    timeout: int | None = None,
-) -> dict[str, Any]:
-    """
-    Send one message through the resolved A2A runtime chat stream.
-    """
-    operation_kwargs: dict[str, Any] = {
-        "message": message,
-        "wait_for_runtime": wait_for_runtime,
-        "runtime_turn_timeout_seconds": runtime_turn_timeout_seconds,
-        "omit_reasoning": omit_reasoning,
-        "response_format": response_format,
-        "json_repair": json_repair,
-        "timeout": timeout,
-    }
-    if runtime_access is not None:
-        operation_kwargs["runtime_access"] = runtime_access
-    try:
-        payload = _run_sdk_model_operation(
-            module_name="mainsequence.client.agent_runtime_models",
-            class_name="AgentSession",
-            operation=lambda ClientAgentSession: ClientAgentSession.a2a_chat(
-                str(agent_session_uid),
-                **operation_kwargs,
-            ),
-        )
-        return _sdk_object_to_dict(payload)
-    except Exception as e:
-        err_name = type(e).__name__
-        if err_name == "NotFoundError":
-            raise ApiError(f"Agent session not found: {agent_session_uid}") from e
-        if isinstance(e, (ApiError, NotLoggedIn)):
-            raise
-        raise ApiError(f"Agent session runtime chat failed: {e}") from e
-
-
-def cancel_agent_session_runtime(
     agent_session_uid: str,
-    *,
-    reason: str = "client_requested",
-    message: str | None = None,
-    timeout: int | None = None,
-) -> dict[str, Any]:
-    """
-    Cancel the active turn on the resolved A2A runtime.
-    """
-    try:
-        payload = _run_sdk_model_operation(
-            module_name="mainsequence.client.agent_runtime_models",
-            class_name="AgentSession",
-            operation=lambda ClientAgentSession: ClientAgentSession.cancel_runtime(
-                str(agent_session_uid),
-                reason=reason,
-                message=message,
-                timeout=timeout,
-            ),
-        )
-        return _sdk_object_to_dict(payload)
-    except Exception as e:
-        err_name = type(e).__name__
-        if err_name == "NotFoundError":
-            raise ApiError(f"Agent session not found: {agent_session_uid}") from e
-        if isinstance(e, (ApiError, NotLoggedIn)):
-            raise
-        raise ApiError(f"Agent session runtime cancel failed: {e}") from e
-
+    message: str,
+    message_id: str | None,
+    cached_runtime_access: dict[str, Any] | None,
+    strict_dictionary: bool,
+    json_repair_attempts: int,
+    return_immediately: bool,
+    timeout: int | None,
+):
+    if cached_runtime_access is not None:
+        ClientAgentSession.cache_runtime_access(agent_session_uid, cached_runtime_access)
+
+    payload = ClientAgentSession.send_a2a_message(
+        agent_session_uid,
+        message=message,
+        message_id=message_id,
+        strict_dictionary=strict_dictionary,
+        json_repair_attempts=json_repair_attempts,
+        return_immediately=return_immediately,
+        timeout=timeout,
+    )
 
-def detach_agent_session_runtime(
-    agent_session_uid: str,
-    *,
-    reason: str = "client_done",
-    timeout: int | None = None,
-) -> dict[str, Any]:
-    """
-    Detach the resolved A2A runtime for one agent session.
-    """
-    try:
-        payload = _run_sdk_model_operation(
-            module_name="mainsequence.client.agent_runtime_models",
-            class_name="AgentSession",
-            operation=lambda ClientAgentSession: ClientAgentSession.detach_runtime(
-                str(agent_session_uid),
-                reason=reason,
-                timeout=timeout,
-            ),
+    resolved_access = ClientAgentSession.get_cached_runtime_access(agent_session_uid)
+    if resolved_access is not None:
+        save_runtime_access_cache(
+            agent_session_uid,
+            _sdk_object_to_dict(resolved_access),
         )
-        return _sdk_object_to_dict(payload)
-    except Exception as e:
-        err_name = type(e).__name__
-        if err_name == "NotFoundError":
-            raise ApiError(f"Agent session not found: {agent_session_uid}") from e
-        if isinstance(e, (ApiError, NotLoggedIn)):
-            raise
-        raise ApiError(f"Agent session runtime detach failed: {e}") from e
+    return payload
 
 
 def list_agent_users_can_view(
@@ -4686,6 +4442,36 @@ def run_data_node_storage_query(
         raise ApiError(f"Data node query failed: {e}") from e
 
 
+def run_meta_table_query(
+    meta_table_uid: str,
+    sql: str,
+    *,
+    timeout: int | None = None,
+) -> dict[str, Any]:
+    """
+    Run a raw SQL query against one MetaTable via SDK client model.
+    """
+    try:
+
+        def _run_query(ClientMetaTable):
+            meta_table = ClientMetaTable.get(uid=str(meta_table_uid), timeout=timeout)
+            payload = meta_table.run_query(sql, timeout=timeout)
+            return dict(payload) if isinstance(payload, dict) else {"ok": True, "results": payload}
+
+        return _run_sdk_model_operation(
+            module_name="mainsequence.client.metatables",
+            class_name="MetaTable",
+            operation=_run_query,
+        )
+    except Exception as e:
+        err_name = type(e).__name__
+        if err_name == "NotFoundError":
+            raise ApiError(f"MetaTable not found: {meta_table_uid}") from e
+        if isinstance(e, (ApiError, NotLoggedIn)):
+            raise
+        raise ApiError(f"MetaTable query failed: {e}") from e
+
+
 def delete_data_node_storage(
     storage_uid: str,
     *,