| name | aidp-migrator-bootstrap |
| description | One-shot environment readiness check for the Oracle AIDP Databricks migrator. Verifies Python deps, OCI auth, AIDP cluster reachability, and the customer's env-coords file. Use the first time the user invokes the migrator on a workstation, or when any other skill fails with an auth / connectivity error. |
aidp-migrator-bootstrap — environment readiness check
Confirms everything the migrator needs is in place before any of the other skills attempt real work. Idempotent — re-runnable whenever you suspect drift.
When to use
- The user is running the migrator for the first time on this workstation.
- Any other skill fails with an OCI auth, network, or cluster-not-found error.
- The user moved to a new region / DataLake / workspace and you need to re-verify.
Required env-coords
Before any check below works, the user MUST have an env-coords.md (or any plain notes file) listing all of these. Refuse to proceed and ask for them if any are missing — never guess.
| Coordinate | Example shape (do NOT use any of these literal values — these are placeholders) |
|---|
| AIDP REST base URL | https://aidp.<region>.oci.oraclecloud.com/20240831 |
| DataLake OCID | ocid1.aidataplatform.oc1.<region>.<id> |
| Workspace UUID | <8-4-4-4-12> UUID format |
| Cluster ID | <8-4-4-4-12> UUID format |
| OCI profile name | <your-profile> (e.g. the section name in ~/.oci/config) |
| Output workspace path | Shared/aidp-migration-tool-output/ (or your team's path) |
Save these into a env-coords.md file at the project root, gitignored. Every other skill in this plugin threads these through verbatim. See references/env-coords.md for a complete scaffold.
Step-by-step
1. Python prereqs
python3 --version
python -m pip install -r ~/.aidp-migrator/engine/requirements.txt
Expected packages: oci, requests, websocket-client, openai, cryptography. If any is missing, install + retry.
2. OpenAI env vars
python3 -c "import os; print('OPENAI_API_KEY=' + ('set' if os.getenv('OPENAI_API_KEY') else 'missing'))"
python3 -c "import os; print('OPENAI_MODEL=' + os.getenv('OPENAI_MODEL', '<team-approved-default>'))"
If OPENAI_API_KEY is empty, the migrator's Pass-2 cell-by-cell loop will not run. Ask the user to set OPENAI_API_KEY in the shell. If the toolkit requires an explicit model, ask them to set OPENAI_MODEL to the team's approved OpenAI model.
3. OCI authentication
Two valid paths — confirm which the user is using:
API key (recommended for unattended runs)
oci iam region list --profile <profile-name>
Session token (interactive only, expires ~1 hr)
oci session validate --profile <profile-name>
oci session authenticate --profile <profile-name> --region <region>
If either returns 401/403 or "Security Token expired", surface the exact command the user should run — do not pretend success.
4. AIDP cluster reachability + state
curl -s -H "..." \
"<AIDP_BASE>/dataLakes/<DATALAKE_OCID>/workspaces/<WORKSPACE_UUID>/clusters/<CLUSTER_ID>" \
| python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('lifecycleState'))"
Expect Active. Acceptable transient states are Starting, Updating. If Stopped or Failed, instruct the user to start the cluster from AIDP console before any Pass-2 run.
Curl with auth=signer (the migrator's helper) is the proper way; if the user wants an exact one-liner, suggest it in Python (fill the four placeholder values from your env-coords.md):
import oci, requests
profile = "<your-profile-name>"
base = "<AIDP_BASE>"
lake = "<DATALAKE_OCID>"
ws = "<WORKSPACE_UUID>"
cl = "<CLUSTER_ID>"
cfg = oci.config.from_file(profile_name=profile)
signer = oci.signer.Signer(cfg["tenancy"], cfg["user"], cfg["fingerprint"], cfg["key_file"])
r = requests.get(f"{base}/dataLakes/{lake}/workspaces/{ws}/clusters/{cl}", auth=signer)
print(r.json().get("lifecycleState"))
5. Workspace write permission
Confirm the operator can write under the target output path:
python3 -c "
import oci, requests, urllib.parse, os
cfg = oci.config.from_file(profile_name='<profile>')
signer = oci.signer.Signer(cfg['tenancy'], cfg['user'], cfg['fingerprint'], cfg['key_file'])
base = '<AIDP_BASE>'
lake = '<DATALAKE_OCID>'
ws = '<WORKSPACE_UUID>'
path = '<output-workspace-path>'
r = requests.get(f'{base}/dataLakes/{lake}/workspaces/{ws}/objects',
params={'path': path}, auth=signer)
print(r.status_code, r.text[:200])
"
200 → good. 404 → ask the user to create the folder via AIDP console or via POST .../objects with type=FOLDER. 401/403 → the operator's OCI principal lacks workspace.write on this workspace.
6. Migrator pyc compile sanity
python3 -m py_compile \
~/.aidp-migrator/engine/scripts/build_dag.py \
~/.aidp-migrator/engine/scripts/check_data_availability.py \
~/.aidp-migrator/engine/scripts/job_migrate.py \
~/.aidp-migrator/engine/scripts/migrate_catalog.py
Should be silent. If a Python-version mismatch is reported, the user is on the wrong interpreter.
Output template
After running, report back to the user as a single table:
| Check | Status | Notes |
|---|---|---|
| Python deps | OK | 3.13.x, all 5 deps present |
| OPENAI_API_KEY | OK | set in shell env |
| OPENAI_MODEL | OK | team-approved model, if required |
| OCI auth (api_key) | OK | profile <name>, region <region> |
| Cluster state | OK | Active |
| Workspace write | OK | output base reachable |
| Migrator compile | OK | all 4 entrypoints compile |
Any FAIL row → emit the exact command the user needs to run to fix it. Do not proceed to other skills if any check failed.
Notes
- This skill never modifies anything. It is read-only.
- If the user is on a session token and it's about to expire (
oci session validate shows <10 minutes remaining), warn them and suggest refresh BEFORE invoking a long-running skill like aidp-migrate-job.
- Re-run after any change in region, DataLake, workspace, or cluster.
