aidp-rest

aidp-rest — AIDP control-plane REST primitives

Canonical location: the Python client lives in the plugin source at scripts/oracle_ai_data_platform_fusion_autopilot/dispatch/rest_client.py. The skill's client.py is a path-resolving re-export shim — it adds the checkout's scripts/ directory to sys.path and re-exports the canonical names. Edits to the client land in the plugin first; this skill documents the contract and the empirically-confirmed gotchas.

Reusable Python client for the AIDP /aiDataPlatforms/<id>/workspaces/<key>/... REST surface. Encapsulates OCI request signing (both API-key and session-token profiles), the empirically-confirmed request shapes, and the gotchas that aren't in Oracle's swagger.

When to use

• Building a skill that dispatches a notebook to a live cluster.
• Diagnosing a job run — fetching its executed notebook, parsing output markers, finding the failed task.
• Resolving workspace / cluster display names to UUIDs.
• Starting a STOPPED cluster + waiting for ACTIVE before submitting work.

Do NOT use for:

• In-cluster code that runs inside an AIDP notebook session — spark, aidputils, oidlUtils are runtime globals; talk to the AIDP control plane via those, not via REST.
• The .aidp/cli.js CLI flows defined in the workspace CLAUDE.md — those handle agent flows, not workspace data jobs.

Prerequisites

1. OCI CLI authed — ~/.oci/config with at least a DEFAULT profile pointing at a user with AIDP read/write on the target tenancy.
2. Coordinates known:
   • region (e.g. us-ashburn-1)
   • aiDataPlatformId (OCID; the regional AIDP instance)
   • workspaceKey (UUID — discoverable via list_workspaces() + find_workspace_by_name(...))
   • clusterKey (UUID — discoverable via list_clusters(workspaceKey) + find_cluster_by_name(...))

Quickstart

from client import AidpRestClient

client = AidpRestClient(
    region="us-ashburn-1",
    aidp_id="<ocid1.datalake.oc1.{region}.{tenancy-specific}>",
    workspace_key="<workspace-uuid>",
)

# 1. Verify cluster is healthy
client.verify_cluster_active(cluster_key)

# 2. Upload a notebook (built locally as an nbformat-4 dict)
client.upload_notebook("/Workspace/Shared/my-skill/run.ipynb", notebook_dict)

# 3. Create a job + submit a run
job_key = client.create_notebook_job(
    name="my-skill-run", description="...",
    notebook_path="/Workspace/Shared/my-skill/run.ipynb",
    cluster_key=cluster_key, cluster_name="fusion_autopilot_dev",
    task_key="main",
)
run_key = client.submit_run(job_key)

# 4. Poll to terminal state — returns a RunResult dataclass with .status + .raw
result = client.poll_run(run_key, timeout_s=2700, interval_s=20)
if result.status != "SUCCESS":
    handle_failure(result.raw)

# 5. Fetch the executed notebook
task_run_key = client.resolve_task_run_key(result.raw, "main")
executed_nb_json = client.fetch_output(task_run_key)

# 6. Parse a stdout marker the notebook printed
marker = client.parse_marker(json.loads(executed_nb_json),
                             begin="AIDP_LIVE_TEST_RESULT_BEGIN",
                             end="AIDP_LIVE_TEST_RESULT_END")