Metadata-Version: 2.4
Name: icmd-python
Version: 3.3.0
Summary: Python client app for ICMD®
Author: QuesTek Innovations LLC
License-Expression: LicenseRef-Proprietary
Keywords: icmd,materials,alloy-design,calphad,api-client
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: cryptography>=43.0.1
Requires-Dist: jsonschema>=4.18
Requires-Dist: pandas>=2.0
Requires-Dist: pydantic<3,>=2.12
Requires-Dist: referencing>=0.30
Requires-Dist: requests>=2.32.4
Provides-Extra: dev
Requires-Dist: pyright; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-xdist; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Provides-Extra: notebooks
Requires-Dist: ipywidgets>=8.0; extra == "notebooks"
Requires-Dist: ipython>=8.10; extra == "notebooks"
Requires-Dist: jupyter>=1.1; extra == "notebooks"
Requires-Dist: matplotlib>=3.8; extra == "notebooks"
Requires-Dist: xarray>=2024.1; extra == "notebooks"
Dynamic: license-file

# icmd-python

`icmd-python` is the supported Python SDK and command-line client for licensed QuesTek customers
automating the ICMD® 2.0 API. It requires Python 3.12+ and access to an ICMD® tenant — a hostname
and an account, both supplied by QuesTek. Without them the package installs but has nothing to talk
to.

It covers sign-in and encrypted credential storage, owner-group selection, the Suite and Studio
resources (databases, models, datasets, jobs, results), model-contract retrieval and job-input
composition, and browser links back into the web app.

## Installation

Install into your environment as a library:

```bash
pip install icmd-python
```

For the standalone `icmd` CLI only:

```bash
uv tool install icmd-python
```

`uv tool install` puts the entry point on your PATH in its own isolated environment — but it does
**not** make `icmd` importable, so it does not cover the Python usage below.

## Quick Start

### Python

```python
from icmd import ICMD

client = ICMD("your-tenant.icmd.ai")

# Every list endpoint returns a pagination envelope; the rows are under "data".
jobs = client.studio.jobs.list(page_size=1)["data"]

if jobs:
    # Where to look at one in the browser. Never build this URL by hand — the app
    # lives under /app and its segments do not match the API paths.
    print(client.link_for("job", jobs[0]["uuid"]))
```

For scripts and CI/CD (no interactive prompts):

```python
client = ICMD("your-tenant.icmd.ai", developer_token="your-api-token", owner_group="my-team")
```

### CLI

```bash
icmd login --domain your-tenant.icmd.ai
icmd studio jobs list --domain your-tenant.icmd.ai --group my-team
icmd studio jobs get 8f3e6c1a-0b2d-4e5f-9a7b-1c2d3e4f5a6b --domain your-tenant.icmd.ai
# the browser link for it
icmd link build job 8f3e6c1a-0b2d-4e5f-9a7b-1c2d3e4f5a6b --domain your-tenant.icmd.ai
```

Replace `your-tenant.icmd.ai` with the hostname QuesTek gave you. Setting `ICMD_DOMAIN` and
`ICMD_GROUP` in your environment saves repeating them on every command.

Commands emit JSON except `studio jobs log --follow`, which streams raw log text; diagnostics and
errors go to stderr.

## What is in the package

- `ICMD` — the client facade. Constructing it authenticates (interactive sign-in, a developer
  token, or a stored credential) and binds the session to one tenant.
- `client.suite`, `client.studio`, `client.workspace`, `client.agent`, `client.account` — the API
  areas. Most expose resource objects with a uniform surface: `list()` and `list_all()`, `get()`,
  and, where the endpoint allows it, `add()`, `update()`, and `delete()`.
- `client.contracts` — model contracts fetched from the server, and the advisory check that reads
  a job input against them.
- `compose_input_dict()` and `check_input_dict()` — assemble a job input from models, composition,
  and design space, then check it before submitting.
- `link_for()` — web-app links for a resource, as a module function or a client method.

`help(icmd.ICMD)` and `icmd --help` document the full surface; every public function, method, and
class carries a docstring. For the written guides, the CLI reference, and the Jupyter notebook
tutorials, contact your QuesTek representative.

## License

Proprietary. Copyright © QuesTek Innovations LLC. All rights reserved. This software is
confidential, and its use is permitted solely under the terms of a valid written agreement with
QuesTek; absent such an agreement, no license or right is granted, whether express or implied. The
full license text ships with the distribution.
