Update to Domino Data Lab

{
  "description": "Programmatically interact with Domino using python-domino SDK and REST APIs. Covers authentication, running jobs, managing projects, file operations, model deployment, and automation. Use when automating Domino workflows, integrating with CI/CD, or building custom tooling around Domino.",
  "included_files": [
    {
      "relative_path": "API-ADMIN.md",
      "size_in_bytes": 12598
    },
    {
      "relative_path": "API-APPS.md",
      "size_in_bytes": 8185
    },
    {
      "relative_path": "API-DATASETS.md",
      "size_in_bytes": 7264
    },
    {
      "relative_path": "API-ENVIRONMENTS.md",
      "size_in_bytes": 7418
    },
    {
      "relative_path": "API-JOBS.md",
      "size_in_bytes": 7428
    },
    {
      "relative_path": "API-MODEL-SERVING.md",
      "size_in_bytes": 3034
    },
    {
      "relative_path": "API-MODELS.md",
      "size_in_bytes": 8379
    },
    {
      "relative_path": "API-PROJECTS.md",
      "size_in_bytes": 8463
    },
    {
      "relative_path": "API-REFERENCE.md",
      "size_in_bytes": 17305
    }
  ],
  "name": "domino-python-sdk",
  "skill_md_contents": "---\nname: domino-python-sdk\ndescription: Programmatically interact with Domino using python-domino SDK and REST APIs. Covers authentication, running jobs, managing projects, file operations, model deployment, and automation. Use when automating Domino workflows, integrating with CI/CD, or building custom tooling around Domino.\n---\n\n# Domino Python SDK Skill\n\n## Description\nThis skill helps users work with the Domino Python SDK (python-domino) and REST APIs to programmatically interact with Domino.\n\n## Activation\nActivate this skill when users want to:\n- Use the Domino Python SDK\n- Make API calls to Domino\n- Automate Domino workflows\n- Integrate Domino with external systems\n- Query Domino programmatically\n\n## Overview\n\nDomino provides two main programmatic interfaces:\n- **python-domino**: Python SDK for common operations\n- **REST API**: Full HTTP API for all Domino features\n\n## Installation\n\n### python-domino\n```bash\n# Install from PyPI\npip install dominodatalab\n\n# Or install with extras\npip install \"dominodatalab[data]\"\n```\n\n### In Domino Environment\nAdd to requirements.txt:\n```\ndominodatalab>=1.4.0\n```\n\nOr Dockerfile:\n```dockerfile\nRUN pip install dominodatalab\n```\n\n## Authentication\n\nCanonical guide: https://docs.domino.ai/cloud/reference/api/domino-api-authentication\n\n**Do not use API keys** (`X-Domino-Api-Key`, `DOMINO_USER_API_KEY`, `api_key=`). Use PAT or service account tokens only when calling from **outside** a run.\n\n### In-run (workspace, job, app backend)\n\nDomino injects `DOMINO_USER_HOST` / `DOMINO_API_HOST` (same base; prefer `DOMINO_USER_HOST`). When JWT credential propagation is enabled, `DOMINO_API_PROXY` is the forwarded platform API base (not the same as `http://localhost:8899/access-token`).\n\n| Pattern | When | Code |\n|---------|------|------|\n| **API proxy (preferred)** | `DOMINO_API_PROXY` is set (Domino **5.4.0+** in runs with JWT credential propagation configured) | Call `{DOMINO_API_PROXY}{path}` with **no** `Authorization` header. The JWT sidecar adds the **starting user** access JWT on the forwarded request. |\n| **Access token + platform host** | Older deployments, or you intentionally call `DOMINO_USER_HOST` / `DOMINO_API_HOST` instead of the proxy URL | Fetch a short-lived JWT, then Bearer on the platform base. |\n\n**API proxy (preferred on 5.4.0+):**\n\n```python\nimport os\nimport requests\n\nbase_url = os.environ[\"DOMINO_API_PROXY\"].rstrip(\"/\")\nheaders = {}\n\nresponse = requests.get(f\"{base_url}/v4/users/self\")\n```\n\n```bash\ncurl \"$DOMINO_API_PROXY/v4/users/self\"\n```\n\nThe proxy is not guaranteed on every deployment or run type. If `DOMINO_API_PROXY` is missing, use the access-token pattern or PAT from outside the cluster.\n\n**Access token + `DOMINO_USER_HOST` (legacy-friendly in-run):** use the [In-run setup block](#in-run-setup-block-for-examples-in-this-skill) below; it covers both proxy and access-token paths.\n\n**Before Domino 5.4.0:** JWT file propagation (`DOMINO_TOKEN_FILE`) was used before the API proxy; legacy behavior may still exist if admins enable `EnableLegacyJwtTooling`. Prefer migrating to the proxy pattern on supported versions.\n\n### Outside a run (laptop, CI, cron outside Domino)\n\nYour code is **not** executing inside a Domino workspace, job, or app container. Domino does **not** inject `DOMINO_API_PROXY`, `DOMINO_USER_HOST`, or an access-token sidecar. You must supply both:\n\n1. **Base URL** — the deployment URL users open in the browser (HTTPS), for example `https://yourcompany.engineering.domino.tech`. Not `http://127.0.0.1:8763` and not values copied from an in-run environment.\n2. **Credential** — `Authorization: Bearer` with a token you store securely (secret manager, CI variable, not committed to git):\n   - **Personal Access Token (PAT)** when the automation acts as you. Create under Account settings or `POST /api/pat/v1/tokens` while already authenticated.\n   - **Service account token** when a pipeline or integration runs without a human user. An admin provisions the service account and token.\n\n```python\nimport requests\n\ndeployment_url = \"https://yourcompany.engineering.domino.tech\"\npat = \"...\"  # from your secret store; never hardcode in shared repos\n\nresponse = requests.get(\n    f\"{deployment_url.rstrip('/')}/v4/users/self\",\n    headers={\"Authorization\": f\"Bearer {pat}\"},\n)\n```\n\nSee https://docs.domino.ai/cloud/reference/api/domino-api-authentication .\n\n### In-run setup block (for examples in this skill)\n\nUse inside a workspace, job, or app only:\n\n```python\nimport os\nimport requests\n\nif os.environ.get(\"DOMINO_API_PROXY\"):\n    base_url = os.environ[\"DOMINO_API_PROXY\"].rstrip(\"/\")\n    headers = {}\nelse:\n    base_url = (os.environ.get(\"DOMINO_USER_HOST\") or os.environ.get(\"DOMINO_API_HOST\") or \"\").rstrip(\"/\")\n    token = requests.get(\"http://localhost:8899/access-token\").text.strip()\n    headers = {\"Authorization\": f\"Bearer {token}\"}\n```\n\n### python-domino inside Domino\n\n```python\nfrom domino import Domino\n\ndomino = Domino(\"owner/project-name\")\n```\n\nConfigure the SDK with host + Bearer token per the product auth page. Never pass `api_key=`.\n\n## Common Operations\n\n### Projects\n\n```python\nfrom domino import Domino\n\ndomino = Domino()\n\n# Create project\nproject = domino.project_create(\n    project_name=\"my-new-project\",\n    owner_name=\"username\"\n)\n\n# Get project info\ninfo = domino.project_info()\nprint(f\"Project: {info['name']}\")\nprint(f\"ID: {info['id']}\")\n```\n\n### Jobs (Runs)\n\n```python\n# Start a job\nrun = domino.runs_start(\n    command=\"python train.py --epochs 100\",\n    hardware_tier_name=\"medium\",\n    environment_id=\"env-id\"\n)\nprint(f\"Run ID: {run['runId']}\")\n\n# Start job with different commit\nrun = domino.runs_start(\n    command=\"python train.py\",\n    commit_id=\"abc123\"\n)\n\n# Check status\nstatus = domino.runs_status(run['runId'])\nprint(f\"Status: {status['status']}\")\n\n# Wait for completion\ndomino.runs_wait(run['runId'])\n\n# Get logs\nlogs = domino.runs_get_logs(run['runId'])\nprint(logs)\n\n# Stop a run\ndomino.runs_stop(run['runId'])\n```\n\n### Workspaces\n\n```python\n# Start workspace\nworkspace = domino.workspace_start(\n    hardware_tier_name=\"medium\",\n    environment_id=\"env-id\",\n    workspace_type=\"JupyterLab\"\n)\nprint(f\"Workspace ID: {workspace['workspaceId']}\")\n\n# Stop workspace\ndomino.workspace_stop(workspace['workspaceId'])\n```\n\n### Files\n\n```python\n# Upload file\ndomino.files_upload(\n    path=\"local/file.csv\",\n    dest_path=\"/mnt/code/data/\"\n)\n\n# Download file\ndomino.files_download(\n    path=\"/mnt/code/results/output.csv\",\n    dest_path=\"local/output.csv\"\n)\n\n# List files\nfiles = domino.files_list(\"/mnt/code/\")\nfor f in files:\n    print(f['path'])\n```\n\n### Datasets\n\n```python\n# Create dataset\ndataset = domino.datasets_create(\n    name=\"training-data\",\n    description=\"Training dataset\"\n)\n\n# List datasets\ndatasets = domino.datasets_list()\n\n# Create snapshot\nsnapshot = domino.datasets_snapshot(\n    dataset_name=\"training-data\",\n    tag=\"v1.0\"\n)\n```\n\n### Environments\n\n```python\n# List environments\nenvironments = domino.environments_list()\nfor env in environments:\n    print(f\"{env['name']}: {env['id']}\")\n\n# Get environment details\nenv = domino.environment_get(\"env-id\")\n```\n\n### Model APIs\n\n```python\n# Publish model\nmodel = domino.model_publish(\n    file=\"model.py\",\n    function=\"predict\",\n    environment_id=\"env-id\",\n    name=\"my-classifier\",\n    description=\"Classification model\"\n)\nprint(f\"Model ID: {model['id']}\")\n\n# List models\nmodels = domino.models_list()\n\n# Get model info\nmodel_info = domino.model_get(\"model-id\")\n```\n\n## REST API\n\nUse the [Authentication](#authentication) setup (`base_url`, `headers`) for examples below.\n\n```python\nresponse = requests.get(f\"{base_url}/api/projects/beta/projects\", headers=headers or None)\nprojects = response.json()\n```\n\n### Common Endpoints\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/v4/projects` | GET | List projects |\n| `/v4/projects/{id}/runs` | POST | Start a run |\n| `/v4/projects/{id}/runs/{runId}` | GET | Get run status |\n| `/v4/projects/{id}/files` | GET | List files |\n| `/v4/gateway/runs/{runId}/logs` | GET | Get run logs |\n| `/v4/models` | GET | List models |\n| `/v4/models/{id}/latest/model` | POST | Call model |\n\n## Domino Data API\n\nSeparate SDK for data access:\n\n```python\nfrom domino_data.data_sources import DataSourceClient\n\n# Initialize client\nclient = DataSourceClient()\n\n# List data sources\nsources = client.list_data_sources()\n\n# Query data source\ndf = client.get_datasource(\"my-datasource\").query(\n    \"SELECT * FROM customers WHERE region = 'US'\"\n)\n```\n\n## Automation Examples\n\n### CI/CD Integration\n```python\n# trigger_training.py - Call from CI/CD pipeline\nfrom domino import Domino\nimport sys\n\ndomino = Domino(\"team/ml-project\")\n\n# Start training job\nrun = domino.runs_start(\n    command=\"python train.py\",\n    hardware_tier_name=\"gpu-large\"\n)\n\n# Wait for completion\nresult = domino.runs_wait(run['runId'])\n\nif result['status'] != 'Succeeded':\n    print(f\"Training failed: {result['status']}\")\n    sys.exit(1)\n\nprint(\"Training completed successfully!\")\n```\n\n### Batch Job Scheduler\n```python\n# Run multiple experiments\nfrom domino import Domino\nimport itertools\n\ndomino = Domino(\"team/experiments\")\n\n# Parameter grid\nparams = {\n    \"learning_rate\": [0.01, 0.001, 0.0001],\n    \"batch_size\": [32, 64, 128]\n}\n\n# Generate combinations\ncombinations = list(itertools.product(*params.values()))\nparam_names = list(params.keys())\n\n# Submit all experiments\nruns = []\nfor combo in combinations:\n    param_str = \" \".join(\n        f\"--{name}={value}\"\n        for name, value in zip(param_names, combo)\n    )\n    run = domino.runs_start(\n        command=f\"python experiment.py {param_str}\",\n        hardware_tier_name=\"gpu-small\"\n    )\n    runs.append(run['runId'])\n    print(f\"Started run {run['runId']} with {param_str}\")\n\n# Wait for all to complete\nfor run_id in runs:\n    result = domino.runs_wait(run_id)\n    print(f\"Run {run_id}: {result['status']}\")\n```\n\n### Model Deployment Pipeline\n```python\nfrom domino import Domino\n\ndomino = Domino(\"team/model-deployment\")\n\n# 1. Train model\ntrain_run = domino.runs_start(command=\"python train.py\")\ndomino.runs_wait(train_run['runId'])\n\n# 2. Evaluate model\neval_run = domino.runs_start(command=\"python evaluate.py\")\ndomino.runs_wait(eval_run['runId'])\n\n# 3. Deploy if evaluation passes\n# (Check evaluation results first)\nmodel = domino.model_publish(\n    file=\"serve.py\",\n    function=\"predict\",\n    name=\"production-model\"\n)\n\nprint(f\"Model deployed: {model['id']}\")\n```\n\n## Error Handling\n\n```python\nfrom domino import Domino\nfrom domino.exceptions import DominoException\n\ntry:\n    domino = Domino(\"team/project\")\n    run = domino.runs_start(command=\"python train.py\")\nexcept DominoException as e:\n    print(f\"Domino error: {e}\")\nexcept Exception as e:\n    print(f\"Unexpected error: {e}\")\n```\n\n## Best Practices\n\n### 1. Follow [Authentication](#authentication)\nProxy without a header when `DOMINO_API_PROXY` is set; otherwise access-token + platform host; PAT/SA only outside a run.\n\n### 2. Handle Rate Limits\n```python\nimport time\nfrom domino.exceptions import DominoException\n\ndef api_call_with_retry(func, max_retries=3):\n    for attempt in range(max_retries):\n        try:\n            return func()\n        except DominoException as e:\n            if \"rate limit\" in str(e).lower():\n                time.sleep(2 ** attempt)\n            else:\n                raise\n    raise Exception(\"Max retries exceeded\")\n```\n\n### 3. Log API Calls\n```python\nimport logging\n\nlogging.basicConfig(level=logging.INFO)\nlogger = logging.getLogger(__name__)\n\ndef start_run(command):\n    logger.info(f\"Starting run: {command}\")\n    run = domino.runs_start(command=command)\n    logger.info(f\"Run ID: {run['runId']}\")\n    return run\n```\n\n## Detailed API Reference\n\nFor comprehensive REST API documentation, see these specialized guides:\n\n| Guide | Description |\n|-------|-------------|\n| [API-PROJECTS.md](API-PROJECTS.md) | Projects, collaborators, Git repos, goals |\n| [API-JOBS.md](API-JOBS.md) | Jobs, scheduled jobs, logs, tags |\n| [API-DATASETS.md](API-DATASETS.md) | Datasets, snapshots, tags, grants |\n| [API-MODELS.md](API-MODELS.md) | Model APIs, deployments, registry |\n| [API-MODEL-SERVING.md](API-MODEL-SERVING.md) | Lifecycle, v1/v2 registry split, invoke vs management |\n| [API-ENVIRONMENTS.md](API-ENVIRONMENTS.md) | Environments, revisions, Dockerfile |\n| [API-APPS.md](API-APPS.md) | Apps endpoint catalog (see [apps/API-APPS.md](../apps/API-APPS.md) for v1 automation) |\n| [API-ADMIN.md](API-ADMIN.md) | Users, orgs, hardware tiers, data sources |\n| [API-REFERENCE.md](API-REFERENCE.md) | Complete endpoint reference |\n\n## Documentation Reference\n\nOpenAPI and route discovery: [API-SPECS.md](../domino-api-intro/API-SPECS.md).\n\n**Product docs:**\n- [Domino API authentication](https://docs.domino.ai/cloud/reference/api/domino-api-authentication)\n- [python-domino Library](https://docs.domino.ai/cloud/reference/python-sdk/python-wrapper-for-domino-api)\n- [GitHub Repository](https://github.com/dominodatalab/python-domino)\n"
}