icmd-python 1.7.1__py3-none-any.whl → 3.3.0__py3-none-any.whl

icmd/__init__.py

@@ -1,15 +1,112 @@
 """Python client for the ICMD® API."""
 
 from .client import ICMD
+from .compose import ModelInput, compose_input_dict
+from .core.advisory import AdvisoryFinding, ContractProvider, check_input_dict
+from .core.contracts import ContractClient, ContractTransport
 from .core.exceptions import (
     ICMDAuthenticationError,
     ICMDConnectionError,
+    ICMDContractUnavailableError,
+    ICMDRefreshNetworkError,
+    ICMDRefreshRateLimitedError,
+    ICMDRefreshResponseError,
+    ICMDRefreshTokenInvalidError,
+    ICMDRefreshUnavailableError,
+    ICMDRequestError,
+    ICMDTokenRefreshError,
     ICMDValidationError,
 )
+from .core.model_classes import ContractFallbackWarning
+from .links import KIND_PATHS, link_for
+from .types import (
+    CalibrationAlgorithm,
+    CalibrationOutput,
+    CalibrationSampling,
+    Component,
+    Composition,
+    CompositionalVariable,
+    Database,
+    DatasetCompositionalVariable,
+    DatasetSource,
+    DatasetVariable,
+    DesignSpace,
+    FromCalibration,
+    FromComposition,
+    FromDataset,
+    FromModel,
+    FromOptimization,
+    FromVariable,
+    GridDistribution,
+    GridSampling,
+    GridVariable,
+    LatinHypercubeSampling,
+    ModelNode,
+    MonteCarloSampling,
+    SensitivitySampling,
+    SeriesColumnMetadata,
+    SeriesDatasetSource,
+    SeriesDatasetVariable,
+    TrainedModel,
+    UniformDistribution,
+    UniformVariable,
+    UseGlobal,
+    Variable,
+)
 
 __all__ = [
     "ICMD",
+    "KIND_PATHS",
+    "AdvisoryFinding",
+    "CalibrationAlgorithm",
+    "CalibrationOutput",
+    "CalibrationSampling",
+    "Component",
+    "Composition",
+    "CompositionalVariable",
+    "ContractClient",
+    "ContractFallbackWarning",
+    "ContractProvider",
+    "ContractTransport",
+    "Database",
+    "DatasetCompositionalVariable",
+    "DatasetSource",
+    "DatasetVariable",
+    "DesignSpace",
+    "FromCalibration",
+    "FromComposition",
+    "FromDataset",
+    "FromModel",
+    "FromOptimization",
+    "FromVariable",
+    "GridDistribution",
+    "GridSampling",
+    "GridVariable",
     "ICMDAuthenticationError",
     "ICMDConnectionError",
+    "ICMDContractUnavailableError",
+    "ICMDRefreshNetworkError",
+    "ICMDRefreshRateLimitedError",
+    "ICMDRefreshResponseError",
+    "ICMDRefreshTokenInvalidError",
+    "ICMDRefreshUnavailableError",
+    "ICMDRequestError",
+    "ICMDTokenRefreshError",
     "ICMDValidationError",
+    "LatinHypercubeSampling",
+    "ModelInput",
+    "ModelNode",
+    "MonteCarloSampling",
+    "SensitivitySampling",
+    "SeriesColumnMetadata",
+    "SeriesDatasetSource",
+    "SeriesDatasetVariable",
+    "TrainedModel",
+    "UniformDistribution",
+    "UniformVariable",
+    "UseGlobal",
+    "Variable",
+    "check_input_dict",
+    "compose_input_dict",
+    "link_for",
 ]

icmd/_vendor/__init__.py

@@ -0,0 +1,23 @@
+"""Reviewed, model-agnostic code maintained inside the ICMD SDK.
+
+Purpose-built package facade; this file was not copied from qt-designer.
+Reference repository: qt-designer
+Reference commit: 9352480f33face07ff42a558c709c18c8e142f85
+Reference path: src/qt_designer/schemas/mixins/model_mixin.py
+"""
+
+from .assembler import (
+    SCENARIO_KEY,
+    SOURCE_KEYS,
+    assemble_model_inputs,
+    assemble_model_node,
+    build_design_document,
+)
+
+__all__ = [
+    "SCENARIO_KEY",
+    "SOURCE_KEYS",
+    "assemble_model_inputs",
+    "assemble_model_node",
+    "build_design_document",
+]

icmd/_vendor/assembler.py

@@ -0,0 +1,135 @@
+"""Model-agnostic helpers for assembling the ICMD job envelope.
+
+Purpose-built reference implementation; this file was not copied from qt-designer.
+
+Reference repository: qt-designer
+Reference commit: 9352480f33face07ff42a558c709c18c8e142f85
+Reference paths:
+- src/qt_designer/schemas/input_dict.py (top-level envelope shape)
+- src/qt_designer/schemas/helpers/designer_input_helpers.py (source-entry selection)
+- src/qt_designer/schemas/mixins/input_dict_builder_mixin.py (document composition)
+- src/qt_designer/schemas/mixins/model_mixin.py (model-node and input-entry shapes)
+"""
+
+from collections.abc import Mapping, Sequence
+from copy import deepcopy
+from typing import Any
+
+__all__ = [
+    "SCENARIO_KEY",
+    "SOURCE_KEYS",
+    "assemble_model_inputs",
+    "assemble_model_node",
+    "build_design_document",
+]
+
+#: The scenario discriminator this assembler emits into ``qt_model_inputs``.
+#: Exported so consumers that must recognize it -- notably the advisory check,
+#: which excludes it from contract validation -- bind to this module rather than
+#: re-spelling the literal.  Renaming it here must not leave a stale copy behind.
+SCENARIO_KEY = "__meta_scenario"
+
+REFERENCE_COMMIT = "9352480f33face07ff42a558c709c18c8e142f85"
+REFERENCE_PATHS = (
+    "src/qt_designer/schemas/input_dict.py",
+    "src/qt_designer/schemas/helpers/designer_input_helpers.py",
+    "src/qt_designer/schemas/mixins/input_dict_builder_mixin.py",
+    "src/qt_designer/schemas/mixins/model_mixin.py",
+)
+
+# This is intentionally a closed wire-shape list, not a dependency on qt-models.
+SOURCE_KEYS = frozenset(
+    {
+        "from_calibrated",
+        "from_calibration",
+        "from_composition",
+        "from_dataset",
+        "from_model",
+        "from_optimization",
+        "from_series_dataset",
+        "from_uncertainty",
+        "from_variable",
+    }
+)
+
+
+def assemble_model_inputs(inputs: Mapping[str, Any]) -> list[dict[str, Any]]:
+    """Convert a model input mapping into ``key``/``from_*`` wire entries."""
+    entries = []
+    for key, value in inputs.items():
+        source = "from_user"
+        assembled_value = deepcopy(value)
+        if isinstance(value, dict):
+            matched_sources = [candidate for candidate in value if candidate in SOURCE_KEYS]
+            if len(matched_sources) > 1:
+                raise ValueError(
+                    f"Multiple 'from_*' keys found: {matched_sources}. Only one is allowed."
+                )
+            if matched_sources and SCENARIO_KEY not in value:
+                source = matched_sources[0]
+                assembled_value = deepcopy(value[source])
+            elif matched_sources:
+                assembled_value = {
+                    SCENARIO_KEY: deepcopy(value[SCENARIO_KEY]),
+                    matched_sources[0]: deepcopy(value[matched_sources[0]]),
+                }
+            elif "use_global" in value:
+                if value["use_global"]:
+                    assembled_value = "use_global"
+                else:
+                    assembled_value.pop("use_global")
+        entries.append({"key": key, source: assembled_value})
+    return entries
+
+
+def assemble_model_node(
+    name: str,
+    model_uuid: str,
+    inputs: Mapping[str, Any],
+    scenario: str | None = None,
+    node_id: str | None = None,
+) -> dict[str, Any]:
+    """Build one model workflow node without model lookup or validation.
+
+    ``node_id`` identifies this workflow instance. The catalog ``model_uuid``
+    remains in ``qt_model.uuid`` and is used only as the default node id.
+    """
+    model_inputs = deepcopy(dict(inputs))
+    if scenario is not None:
+        model_inputs[SCENARIO_KEY] = {"title": scenario}
+    return {
+        "id": model_uuid if node_id is None else node_id,
+        "qt_model": {"name": name, "uuid": model_uuid},
+        "qt_model_inputs": assemble_model_inputs(model_inputs),
+    }
+
+
+def build_design_document(
+    composition: Mapping[str, Any],
+    variables: Mapping[str, Any] | None = None,
+    databases: Sequence[Mapping[str, Any]] | None = None,
+    engine: str | None = None,
+) -> dict[str, Any]:
+    """Build the model-independent design document skeleton.
+
+    ``databases`` and ``engine`` are the design-level values a model input
+    spelled ``use_global`` resolves against. Each is emitted only when it holds
+    a value: a consumer reads an empty list or an empty string as no value at
+    all, so an empty one is left out rather than written present-and-falsy.
+    Passing ``[]`` or ``""`` is therefore the same as passing nothing, and the
+    advisory reports the deferring model either way.
+    """
+    design_space = deepcopy(dict(variables)) if variables is not None else {}
+    design_space.setdefault("sampling_input", {"type": "grid"})
+    design_space.setdefault("compositional_variables", [])
+    design_space.setdefault("model_variables", [])
+    design_space.setdefault("dataset_variables", [])
+    design_space.setdefault("series_dataset_variables", [])
+    document: dict[str, Any] = {"composition": deepcopy(dict(composition))}
+    if databases:
+        document["databases"] = deepcopy(list(databases))
+    if engine:
+        document["engine"] = engine
+    document["design_space"] = design_space
+    document["model_workflow"] = {"models": []}
+    return document

icmd/apps/__init__.py

@@ -1,18 +1,26 @@
-"""Composition-based resource access for ICMD® API.
+"""Composition-based resource access for the ICMD® API.
 
 Provides a clean nested-attribute API::
 
-    icmd = ICMD("icmd.questek.com")
-    icmd.alloy_design.job.list(page=1, page_size=10)
+    icmd = ICMD("icmd.ai")
+    icmd.suite.databases.list()
+    icmd.studio.jobs.submit(input_dict, engine="pandat", folder="<uuid>")
     icmd.workspace.dataset.get("uuid-123")
+    icmd.agent.conversations.send_message("<uuid>", "Hi", wait=True)
 """
 
-from .design import DesignApp
-from .fatigue import FatigueApp
+from .account import AccountApp
+from .agent import AgentApp
+from .constants import ProjectKind
+from .studio import StudioApp
+from .suite import SuiteApp
 from .workspace import WorkspaceApp
 
 __all__ = [
-    "DesignApp",
-    "FatigueApp",
+    "AccountApp",
+    "AgentApp",
+    "ProjectKind",
+    "StudioApp",
+    "SuiteApp",
     "WorkspaceApp",
 ]

icmd/apps/account.py

@@ -0,0 +1,384 @@
+"""Account resources — developer tokens, the current-user profile, and workers.
+
+Wraps the user-facing slices of ``/api/v2/account/``::
+
+    icmd = ICMD("icmd.ai")
+    icmd.account.me()
+    tok = icmd.account.developer_tokens.generate(description="CI", lifetime_days=30)
+    print(tok["token"])  # shown only once — capture it now
+
+These endpoints identify the caller by bearer token, so group injection is
+skipped (they are not owner-group scoped) and never triggers interactive
+group resolution.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .base import ReadOnlyResource, _expect_dict
+
+if TYPE_CHECKING:
+    from icmd.core.session import ResourceClient
+
+
+class DeveloperTokens:
+    """Manage developer API tokens for non-interactive auth (CI, scripts, MCP).
+
+    A developer token is what :class:`~icmd.client.ICMD` accepts as
+    ``developer_token`` for headless use.  **The plaintext token is returned
+    only by :meth:`generate`** — the backend never stores it and it cannot be
+    retrieved again, so capture it then.  If lost, :meth:`revoke` it and
+    generate a new one.  Generating requires the ``has_developer_access``
+    permission and is rate-limited server-side.
+    """
+
+    _GENERATE = "account/auth/developer/generate"
+    _TOKENS = "account/auth/developer/tokens"
+
+    def __init__(self, client: ResourceClient) -> None:
+        self._client = client
+
+    def generate(
+        self,
+        *,
+        description: str | None = None,
+        lifetime_days: int | None = None,
+    ) -> dict:
+        """Mint a new developer token (``POST .../developer/generate``).
+
+        Returns the JWT ``token`` (shown only once), its ``token_id``, and
+        expiration info.
+
+        Parameters
+        ----------
+        description : str | None
+            A human label for the token (max 200 chars), e.g. ``"CI"``.
+        lifetime_days : int | None
+            Validity window in days (server default 30, bounded by the
+            tenant's configured maximum).
+        """
+        body: dict[str, Any] = {}
+        if description is not None:
+            body["description"] = description
+        if lifetime_days is not None:
+            body["lifetime_days"] = lifetime_days
+        return _expect_dict(
+            self._client.request_json(
+                "post", self._GENERATE, inject_group=False, json=body or None
+            ),
+            self._GENERATE,
+        )
+
+    def list(self) -> dict | list[dict]:
+        """List your developer tokens' metadata (``GET .../developer/tokens``).
+
+        Never includes the plaintext token — only ids, descriptions, and
+        expiry.
+        """
+        return self._client.request_json("get", self._TOKENS, inject_group=False)
+
+    def revoke(self, token_id: str) -> dict:
+        """Revoke a developer token (``POST .../developer/tokens/{token_id}/revoke``)."""
+        endpoint = f"{self._TOKENS}/{token_id}/revoke"
+        return _expect_dict(
+            self._client.request_json("post", endpoint, inject_group=False), endpoint
+        )
+
+
+class GroupUsers:
+    """Manage members of the groups you administer (``account/auth/group-users``).
+
+    Scope comes from your admin memberships server-side, not from a group
+    parameter: you see and edit only users in groups you administer.  A
+    non-admin gets an **empty list, not a 403** — an empty result does not
+    prove the group is empty.
+
+    :meth:`update` accepts exactly four writable fields:
+
+    ``is_active`` : bool
+        **A GLOBAL login flag, not a group-membership flag.**  Setting it to
+        ``False`` disables the user's login *everywhere*, not just in your
+        group; the server only checks that the target's groups are a subset of
+        the ones you administer before allowing it.  This is almost never what
+        "remove someone from my group" means — use ``remove_from_group``.
+    ``first_name`` : str
+        The target's given name.
+    ``last_name`` : str
+        The target's family name.
+    ``remove_from_group`` : str
+        Drop the user from this group.  **Takes the group NAME, not its ID** —
+        unlike the rest of the SDK, which accepts either.  Passing an ID here
+        will not match.
+
+    Known backend gaps (pre-existing and backend-owned — documented so callers
+    are not surprised, not fixed here):
+
+    * **Removal does not fully revoke access.**  The server removes the user
+      from the group's membership only; it never clears their *current group*
+      pointer, and nothing repairs it afterwards.  A removed member may retain
+      group context until something else changes it.
+    * **Removing an admin leaves their admin rights.**  A group's admin list is
+      tracked separately from its membership and is not coupled to it, so
+      removing an admin member does not revoke their admin powers.
+    * **Cross-group disclosure.**  Responses list *all* of a target's
+      memberships, not just the ones you administer — a Group A admin can see
+      that the user also belongs to B and C.
+    * **Silent no-op updates.**  The server filters the body to the four
+      writable fields *before* validating it, so a body of unknown or forbidden
+      keys (e.g. ``{"email": "x", "bogus": 1}``) validates as an *empty update*
+      and reports success.  A typo silently changes nothing — verify the
+      returned object rather than trusting the status.
+    """
+
+    _PATH = "account/auth/group-users"
+
+    def __init__(self, client: ResourceClient) -> None:
+        self._client = client
+
+    def list(self, **params: Any) -> dict | list[dict]:
+        """List members of the groups you administer (``GET .../group-users``).
+
+        Parameters
+        ----------
+        **params
+            Query parameters forwarded to the API.  The backend supports
+            ``search`` (name/email substring), ``active`` (bool, filter by the
+            global login flag), ``group`` (group name — restrict to one of your
+            administered groups), plus ``page`` / ``page_size``.
+
+        Returns
+        -------
+        dict | list[dict]
+            The paginated envelope, or a plain list on unpaginated responses.
+            **Empty for non-admins** rather than an error.
+        """
+        return self._client.request_json(
+            "get", self._PATH, inject_group=False, params=params or None
+        )
+
+    def get(self, uuid: str) -> dict:
+        """Get a single managed member (``GET .../group-users/{uuid}``).
+
+        Parameters
+        ----------
+        uuid : str
+            The target user's UUID.
+
+        Returns
+        -------
+        dict
+            The member object, including *all* of their group memberships —
+            not only the ones you administer.
+        """
+        endpoint = f"{self._PATH}/{uuid}"
+        return _expect_dict(
+            self._client.request_json("get", endpoint, inject_group=False), endpoint
+        )
+
+    def update(self, uuid: str, data: dict[str, Any]) -> dict:
+        """Update a managed member (``PATCH .../group-users/{uuid}``).
+
+        Parameters
+        ----------
+        uuid : str
+            The target user's UUID.
+        data : dict
+            Any of the four writable fields — ``is_active`` (**global** login
+            flag), ``first_name``, ``last_name``, ``remove_from_group``
+            (the group **NAME**, not its ID).  See the class docstring: other
+            keys are silently dropped and the call still reports success.
+
+        Returns
+        -------
+        dict
+            The updated member object.
+        """
+        endpoint = f"{self._PATH}/{uuid}"
+        return _expect_dict(
+            self._client.request_json("patch", endpoint, inject_group=False, json=data),
+            endpoint,
+        )
+
+
+class Invitations:
+    """Invite users to a group and manage pending invitations (``account/auth/invite``).
+
+    **An existing ICMD® user is added to the group immediately — no pending
+    invitation is created.**  Despite the name, :meth:`create` only produces an
+    invitation for an email that has no account yet; for an existing account it
+    is an instant group-add, and :meth:`resend` / :meth:`cancel` will have
+    nothing to act on.
+    """
+
+    _PATH = "account/auth/invite"
+
+    def __init__(self, client: ResourceClient) -> None:
+        self._client = client
+
+    def list(self, **params: Any) -> dict | list[dict]:
+        """List invitations (``GET account/auth/invite``).
+
+        Parameters
+        ----------
+        **params
+            Query parameters forwarded to the API.  The backend supports
+            ``group`` (group **name**) and ``status``.
+
+        Returns
+        -------
+        dict | list[dict]
+            The invitation records.
+        """
+        return self._client.request_json(
+            "get", self._PATH, inject_group=False, params=params or None
+        )
+
+    def create(self, *, email: str, group: str) -> dict:
+        """Invite a user to a group (``POST account/auth/invite/create/``).
+
+        Note the dedicated ``create/`` sub-path — this is *not* a POST to the
+        list path.
+
+        Parameters
+        ----------
+        email : str
+            The invitee's email address.
+        group : str
+            The group's **NAME, not its ID** — unlike the rest of the SDK,
+            which accepts either.  Passing an ID will not match.
+
+        Returns
+        -------
+        dict
+            The created invitation, **or** the immediate-add result when
+            *email* belongs to an existing user (see the class docstring — no
+            pending invitation exists in that case).
+        """
+        endpoint = f"{self._PATH}/create"
+        return _expect_dict(
+            self._client.request_json(
+                "post", endpoint, inject_group=False, json={"email": email, "group": group}
+            ),
+            endpoint,
+        )
+
+    def resend(self, uuid: str) -> dict:
+        """Resend a pending invitation email (``POST account/auth/invite/{uuid}/resend/``).
+
+        Parameters
+        ----------
+        uuid : str
+            The invitation's UUID.
+
+        Returns
+        -------
+        dict
+            The resend result.
+        """
+        endpoint = f"{self._PATH}/{uuid}/resend"
+        return _expect_dict(
+            self._client.request_json("post", endpoint, inject_group=False), endpoint
+        )
+
+    def cancel(self, uuid: str) -> dict:
+        """Cancel a pending invitation (``DELETE account/auth/invite/{uuid}/``).
+
+        Parameters
+        ----------
+        uuid : str
+            The invitation's UUID.
+
+        Returns
+        -------
+        dict
+            Empty on the backend's ``204 No Content``.
+        """
+        endpoint = f"{self._PATH}/{uuid}"
+        return _expect_dict(
+            self._client.request_json("delete", endpoint, inject_group=False), endpoint
+        )
+
+
+class AccountApp:
+    """Account resources — profile, developer tokens, workers, and group admin.
+
+    :attr:`developer_tokens` manages non-interactive auth tokens;
+    :attr:`workers` lists the group's workers (read-only); :attr:`group_users`
+    and :attr:`invitations` are the group-admin surface; the methods expose the
+    current-user profile and group detail.
+    """
+
+    __slots__ = ("_client", "developer_tokens", "group_users", "invitations", "workers")
+
+    def __init__(self, client: ResourceClient) -> None:
+        self._client = client
+        self.developer_tokens = DeveloperTokens(client)
+        self.group_users = GroupUsers(client)
+        self.invitations = Invitations(client)
+        self.workers = ReadOnlyResource(client, "account/workers")
+
+    def group(self, pk: int | str, *, admin: bool = False) -> dict:
+        """Get a single group by ID (``GET account/groups/{pk}``).
+
+        .. warning::
+           *pk* is the group's **integer ID — not a UUID**, unlike every other
+           getter in the SDK.  The backend looks the group up by primary key
+           and returns ``400 Invalid group ID.`` for anything non-numeric.
+           Use :meth:`~icmd.client.ICMD.get_groups` to find the ID.
+
+        .. warning::
+           ``admin=True`` **degrades silently** when you are not an admin of
+           the group.  Unlike the ``admin=true`` list-widening surface — which
+           fails closed with a ``403`` — this one checks the parameter *and*
+           real admin membership, then quietly returns the simplified payload
+           with ``capacity_info: None`` and **HTTP 200, no error**.  The only
+           way to detect it is ``result.get("capacity_info") is None`` (use
+           ``.get`` — a plain subscript would raise if a future payload omits
+           the key rather than sending it as ``None``).
+
+        Parameters
+        ----------
+        pk : int | str
+            The group's integer ID (a numeric string is accepted).
+        admin : bool
+            When ``True``, request the admin-expanded representation (full
+            member list plus ``capacity_info``).  Silently ignored if you do
+            not administer the group — see above.
+
+        Returns
+        -------
+        dict
+            The group object.  With *admin* honoured it carries the expanded
+            member roster and a populated ``capacity_info``.
+        """
+        endpoint = f"account/groups/{pk}"
+        params = {"admin": "true"} if admin else None
+        return _expect_dict(
+            self._client.request_json("get", endpoint, inject_group=False, params=params),
+            endpoint,
+        )
+
+    def me(self) -> dict:
+        """Get the current authenticated user (``GET account/user``)."""
+        return _expect_dict(
+            self._client.request_json("get", "account/user", inject_group=False), "account/user"
+        )
+
+    def update_me(self, data: dict[str, Any]) -> dict:
+        """Update the current user's profile (``PATCH account/user/patch``)."""
+        endpoint = "account/user/patch"
+        return _expect_dict(
+            self._client.request_json("patch", endpoint, inject_group=False, json=data), endpoint
+        )
+
+    def update_password(self, data: dict[str, Any]) -> dict:
+        """Change the current user's password (``PATCH account/user/update_password``).
+
+        *data* carries the password-change fields (e.g. ``old_password`` /
+        ``new_password``) as required by the backend.
+        """
+        endpoint = "account/user/update_password"
+        return _expect_dict(
+            self._client.request_json("patch", endpoint, inject_group=False, json=data), endpoint
+        )