mlspace-plugin 0.2.1__py3-none-any.whl

mlspace_mcp/skills/mlspace-diagnose-job-launch-rejection/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: mlspace-diagnose-job-launch-rejection
+description: "Diagnose a rejected job launch on Cloud.ru MLSpace. Why was my job submit refused (no job created): no quota vs no queue vs PAYG vs wrong name. Uses the mlspace_allocations, mlspace_queue_inspect, mlspace_resources, mlspace_workspaces tools."
+license: MIT
+compatibility: Requires the `mlspace` MCP server from this plugin (Cloud.ru MLSpace credentials needed).
+---
+
+# Diagnose a rejected job launch
+
+Why was my job submit refused (no job created): no quota vs no queue vs PAYG vs wrong name.
+
+This skill drives the `mlspace` MCP server shipped in the same plugin. If its
+tools are not connected, say so instead of guessing — none of these steps can be
+carried out any other way.
+
+## Arguments
+
+- `region` — Region the submit targeted.
+- `instance_type` — Instance type that was rejected.
+- `allocation_name` — Allocation named in the error, if any.
+- `target` — Connected workspace ID or unambiguous name, if scoped.
+
+## Procedure
+
+Goal: explain a rejected POST /jobs when no job was created. Read actions only.
+1. Preserve the submitted target, region, instance_type and provider error. Distinguish
+   regional type mismatch, allocation eligibility, queue configuration and visibility;
+   do not cycle through types or submit a paid probe to infer quota.
+2. workspaces allocations in that target -> observed allocation IDs and region_key.
+   workspaces allocation_queues for the relevant allocation. Empty queues are ambiguous
+   (feature disabled, wrong ID, no visible queues); they do not prove GPU unavailable.
+3. allocations get and allocations list_instance_types where accessible. Report actual
+   resources_status/instance-type observations. Zero visible nodes or a 403/405 is not
+   complete evidence about PAYG eligibility, all hardware or all workspace capacity.
+4. mlspace_resources configs (cluster_type=MT) -> compare the requested region key and
+   instance_type against the actual regional catalogue and compatible images.
+5. For a known queue, mlspace_queue_inspect(queue_id, target) -> queue membership,
+   pending demand across priorities, observable workloads and candidate node load.
+   Keep failures and incomplete cross-workspace visibility explicit.
+Output: the provider rejection, supporting observations, unresolved checks and next
+step. A missing allocation/queue association may require the workspace owner/admin;
+name the exact association to verify. Catalog presence does not prove launchability,
+and a notebook is not an established GPU-job workaround without its own eligibility
+and capacity evidence. Verify physical hardware from observed device facts, not labels.

mlspace_mcp/skills/mlspace-diagnose-unhealthy-inference/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: mlspace-diagnose-unhealthy-inference
+description: "Diagnose an unhealthy inference service on Cloud.ru MLSpace. Why is my deployed model returning 5xx / unhealthy (status-level only). Uses the mlspace_inference tools."
+license: MIT
+compatibility: Requires the `mlspace` MCP server from this plugin (Cloud.ru MLSpace credentials needed).
+---
+
+# Diagnose an unhealthy inference service
+
+Why is my deployed model returning 5xx / unhealthy (status-level only).
+
+This skill drives the `mlspace` MCP server shipped in the same plugin. If its
+tools are not connected, say so instead of guessing — none of these steps can be
+carried out any other way.
+
+## Arguments
+
+- `service_name` **(required)** — Inference service name.
+- `region` — Service region, if known.
+- `stop_billing` — If true, suggest scaling replicas to 0.
+- `target` — Connected workspace ID or unambiguous name, if scoped.
+
+## Procedure
+
+Goal: diagnose an unhealthy / 5xx inference service — to the level the API allows.
+1. Resolve service+region: if region empty, mlspace_inference list and match
+   metadata.name == service_name.
+2. mlspace_inference get (inference_name, region) -> K8S manifest.
+3. Read status.conditions[]: the Ready condition + *Ready (Predictor/Routes/Ingress/
+   LatestDeployment). Report which are False and their messages.
+4. Read spec replicas.min/max (defaults min=0, max=3); if min=0 and 0 ready, the service
+   may be scaled to zero (cold) — that explains 503s on first hit.
+5. (optional, opt-in, PAID) only if the user wants to reproduce: inference predict with a
+   minimal payload to capture the live error.
+Output: identity/placement, the failing conditions + messages, replica readiness, and the
+most likely cause at status level.
+HARD CEILING — say this plainly: inference exposes NO pod logs, NO events, NO container
+status. Crash-loop / OOM / image-pull / app-level 5xx CANNOT be seen here; hand off to the
+MLSpace console for pod logs. (Only jobs have logs/pods.)
+If stop_billing=true and min>0: suggest inference update to scale replicas to 0 (a write).

mlspace_mcp/skills/mlspace-discover-launchable-resources/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: mlspace-discover-launchable-resources
+description: "Discover what you can launch on Cloud.ru MLSpace. Valid instance types, base images and free GPUs in a region before launching. Uses the mlspace_allocations, mlspace_docker_registry, mlspace_queue_inspect, mlspace_resources, mlspace_workspaces tools."
+license: MIT
+compatibility: Requires the `mlspace` MCP server from this plugin (Cloud.ru MLSpace credentials needed).
+---
+
+# Discover what you can launch
+
+Valid instance types, base images and free GPUs in a region before launching.
+
+This skill drives the `mlspace` MCP server shipped in the same plugin. If its
+tools are not connected, say so instead of guessing — none of these steps can be
+carried out any other way.
+
+## Arguments
+
+- `region` — Target region.
+- `cluster_type` — MT (jobs/notebooks) or INF (inference).
+- `allocation_id` — Allocation id, if known; access varies by endpoint.
+- `include_custom_images` — Also list registry images.
+- `target` — Connected workspace ID or unambiguous name, if scoped.
+
+## Procedure
+
+Goal: list compatible instance types/images and observed capacity before launching.
+1. mlspace_resources configs (cluster_type=MT for jobs/notebooks; INF for inference).
+   Use the target region's actual instances_types keys, resource limits and
+   datahub_images/custom_images. Include zero-GPU cpu.* types. An empty images list
+   does not establish a compatible pairing; do not recommend an arbitrary image.
+2. mlspace_resources nodes and mlspace_resources nodes_load for observable regional
+   node/load facts. Available GPU readings are point-in-time and do not guarantee
+   scheduling or idle nodes across workspaces. Missing readings remain unknown.
+3. workspaces allocations in the selected target; if an allocation_id is available,
+   allocations get/get_nodes/list_instance_types for additional observed facts.
+   Report success/403/405/empty results per endpoint. Do not infer allocation access
+   categorically from service-account vs personal credentials.
+4. For a known queue, mlspace_queue_inspect(queue_id, target) examines candidate node
+   facts, job/notebook/pod observations and pending priorities across selected observations.
+   Keep paused notebooks visible; their configured GPUs are not active consumption.
+   Do not sum shared views or claim complete cross-workspace coverage.
+5. Optionally docker_registry current_registry -> list_repos -> list_tags for images.
+Output: catalogue compatibility, observed capacity, actual scope/time and unresolved
+eligibility or visibility. PAYG may reject a catalogue-valid type; read-only inspection
+cannot promise a successful launch.

mlspace_mcp/skills/mlspace-launch-training-job/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: mlspace-launch-training-job
+description: "Launch a training job on Cloud.ru MLSpace. Start/submit a training job (resolves instance type + base image). Write action. Uses the mlspace_jobs, mlspace_resources tools."
+license: MIT
+compatibility: Requires the `mlspace` MCP server from this plugin (Cloud.ru MLSpace credentials needed).
+---
+
+# Launch a training job
+
+Start/submit a training job (resolves instance type + base image). Write action.
+
+This skill drives the `mlspace` MCP server shipped in the same plugin. If its
+tools are not connected, say so instead of guessing — none of these steps can be
+carried out any other way.
+
+## Arguments
+
+- `script` **(required)** — Entrypoint: binary command/executable or NFS script path.
+- `region` **(required)** — Target region; required for every job type.
+- `gpus` — GPU count for the instance type; use 0 for CPU-only.
+- `image_hint` — Base image keyword, e.g. pytorch.
+- `job_type` — JobType; binary accepts a command/executable path.
+- `n_workers` — Number of worker nodes.
+- `queue_name` — Queue to schedule in.
+- `extra_body` — JSON of extra RunJobRequest fields.
+- `target` — Connected workspace ID or unambiguous name, if scoped.
+
+## Procedure
+
+Goal: submit a training job (jobs.run is a write action; refused if the server
+runs with MLSPACE_READONLY=true).
+PRECONDITION (critical, easy to miss): `region` must be explicit. Interpret `script`
+according to `type`. For type=binary it is a non-empty command or executable path
+(for example `ls -lah` or `python /home/jovyan/launch.py -f script.py`) and is forwarded
+unchanged; do not force it under /home/jovyan. Verify that the command/executable exists
+in the selected image. For other job types, `script` must already exist on that same
+region's NFS under /home/jovyan (e.g. /home/jovyan/proj/train.py). `/home/jovyan` is
+region-scoped: an SR006 notebook and an A100-MT job can see different contents at the
+same path. The Public API has no remote stat operation, so the MCP cannot prove NFS
+existence. If set, checkpoint_dir/logs_dir must use that same regional NFS.
+1. Parse: script/command, explicit region from the actual MT catalogue,
+   GPU count, image hint, job type (default
+   binary; pytorch/torchrun/etc), n_workers. `gpus=0` means a CPU-only job.
+2. mlspace_resources configs cluster_type=MT. Pick regions[].key == target region.
+3. instance_type: among that region's instances_types[], pick by GPU count — for
+   gpus>0 the one whose resource.limits['nvidia.com/gpu'] equals it; for gpus=0 a
+   `cpu.*` type, where that limit is null or absent (it is a nullable STRING, so
+   compare loosely). Use its `key`. Require a non-empty compatible `images` list;
+   catalog presence alone does not prove PAYG/allocation eligibility.
+4. base_image: filter the region's datahub_images/custom_images by the hint on .name;
+   combine name + tag into the "name:tag" string. (Do NOT read instances_types[].images
+   for this — the wrapper collapses those into pre-joined "name:tag1,tag2" reference
+   strings; use them only to check WHICH images an instance type supports.)
+5. (optional) queue_name/allocation_name are free-form strings; pass verbatim.
+   max_retry is only supported inside allocations; omit it for PAYG jobs.
+6. Build RunJobRequest: {script, base_image, instance_type, region, type, n_workers,
+   plus any extra_body}. ECHO it and the relevant entrypoint evidence (binary command
+   available in the image, or NFS script staged in that exact region) to the user for
+   confirmation before submitting.
+7. jobs run (body=...). Capture job_name.
+8. Verify: jobs get (job_name) for initial status; jobs logs (tail=50) for first output.
+Re-run shortcut: jobs restart (body={job_name}) to repeat an existing job.
+Caveat: this spends compute. Confirm the resolved body with the user first. A valid
+/home/jovyan prefix is necessary but not sufficient for NFS entrypoints: wrong-region
+NFS fails fast and still burns startup capacity. Use the returned resource_ref for subsequent reads; report command/NFS availability
+as unverified when no execution-environment evidence is available.

mlspace_mcp/skills/mlspace-list-running-jobs/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: mlspace-list-running-jobs
+description: "List running / pending jobs on Cloud.ru MLSpace. What's the status of my jobs / what's running or pending. Uses the mlspace_jobs, mlspace_jobs_overview tools."
+license: MIT
+compatibility: Requires the `mlspace` MCP server from this plugin (Cloud.ru MLSpace credentials needed).
+---
+
+# List running / pending jobs
+
+What's the status of my jobs / what's running or pending.
+
+This skill drives the `mlspace` MCP server shipped in the same plugin. If its
+tools are not connected, say so instead of guessing — none of these steps can be
+carried out any other way.
+
+## Arguments
+
+- `region` — Region to scope to (omit to sweep all).
+- `status_filter` — Comma statuses, default Running,Pending.
+- `job_author` — Author email to filter by.
+- `target` — Connected workspace ID or unambiguous name, if scoped.
+
+## Procedure
+
+Goal: show in-flight / recent jobs over the requested connected contexts.
+1. Use mlspace_jobs_overview(targets=explicit_scope_or_omitted,
+   status=["Running","Pending"], author=explicit_author_or_omitted). Parse status_filter
+   if supplied; author is a user filter, not proof of identity. The helper discovers
+   each workspace's actual MT regions and paginates them; no fixed region list.
+2. If region was requested, filter observed rows by provenance.region and label that scope.
+   The helper has no region argument. For a narrow provider-side region query use jobs
+   list with target, region, status and job_author, advancing offset through all pages.
+3. Read items as {source, data, provenance, resource_ref?}. Show workspace, region,
+   job_name, status, job_author and time when returned; retain the exact resource_ref.
+4. Sort Running before Pending. State actual checked scope, failures and truncation;
+   observed counts from a partial read are not full totals or proof of a unique name.
+5. Use jobs get/logs on a chosen object's reference for follow-up, without another sweep.
+Example tool call (omit targets for the full connected set):
+```json
+{"tool":"mlspace_jobs_overview","arguments":{"status":["Running","Pending"]}}
+```
+Output: compact observed status board with source and completeness. States are
+observations over time, not a transactional snapshot.

mlspace_mcp/skills/mlspace-resume-notebook-and-set-autoshutdown/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: mlspace-resume-notebook-and-set-autoshutdown
+description: "Resume a notebook + set autoshutdown on Cloud.ru MLSpace. Wake a paused Jupyter notebook and set idle autoshutdown to control cost. Write action. Uses the mlspace_notebooks, mlspace_notebooks_overview tools."
+license: MIT
+compatibility: Requires the `mlspace` MCP server from this plugin (Cloud.ru MLSpace credentials needed).
+---
+
+# Resume a notebook + set autoshutdown
+
+Wake a paused Jupyter notebook and set idle autoshutdown to control cost. Write action.
+
+This skill drives the `mlspace` MCP server shipped in the same plugin. If its
+tools are not connected, say so instead of guessing — none of these steps can be
+carried out any other way.
+
+## Arguments
+
+- `notebook_name` **(required)** — Notebook to resume.
+- `idle_minutes` — Idle minutes before autoshutdown.
+- `workspace_id` — Workspace for the autoshutdown rule.
+- `instance_type` — Override instance type on resume.
+- `region` — Override region on resume.
+- `target` — Connected workspace ID or unambiguous name, if scoped.
+
+## Procedure
+
+Goal: resume a paused Jupyter notebook and set workspace autoshutdown (write
+actions; refused under MLSPACE_READONLY=true).
+1. For an unlocated notebook use mlspace_notebooks_overview and match data.name;
+   retain source/resource_ref and data.uid (not id). For a known target use
+   mlspace_notebooks list with search=notebook_name and paginate; resolve ambiguity.
+2. If already running/resuming/creating -> skip resume, report state.
+3. mlspace_notebooks resume using resource_ref (or target, namespace, notebook_uuid=uid)
+   and body={region, instance_type} from the chosen notebook unless overridden.
+   Check the returned instanceType: the API may retain the previous size on resume.
+4. Use the chosen notebook's context for workspace_id (auto-filled from target).
+   If an explicit workspace_id disagrees, resolve that conflict before changing rules.
+   autoshutdown is WORKSPACE-WIDE; tell the user it affects all notebooks there.
+5. mlspace_notebooks autoshutdown_get (workspace_id) to show the current rule.
+6. mlspace_notebooks autoshutdown_set (workspace_id, body = AutoShutdownV2Config:
+   nested {by_timer:{...}, by_load:{...}, by_schedule:{...}}; for an idle timer set
+   by_timer with the timeout — read the action's body hint for the exact fields).
+Output: resume result + the autoshutdown rule set + the workspace-wide warning.
+Caveat: autoshutdown is per-workspace, not per-notebook.

mlspace_mcp/skills/mlspace-stage-s3-to-nfs/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: mlspace-stage-s3-to-nfs
+description: "Stage S3 data to NFS (one-off or nightly) on Cloud.ru MLSpace. Copy/sync S3 -> NFS for a GPU job, optionally on a schedule. Write action. Uses the mlspace_data_transfer tools."
+license: MIT
+compatibility: Requires the `mlspace` MCP server from this plugin (Cloud.ru MLSpace credentials needed).
+---
+
+# Stage S3 data to NFS (one-off or nightly)
+
+Copy/sync S3 -> NFS for a GPU job, optionally on a schedule. Write action.
+
+This skill drives the `mlspace` MCP server shipped in the same plugin. If its
+tools are not connected, say so instead of guessing — none of these steps can be
+carried out any other way.
+
+## Arguments
+
+- `source_hint` — Which S3 connector/bucket.
+- `destination_hint` — Which NFS/cluster connector.
+- `source_path` — Path within the source.
+- `destination_path` — Path within the NFS share.
+- `schedule` — Crontab for nightly runs, e.g. '0 2 * * *'.
+- `transfer_name` — Name for the transfer.
+- `cluster_name` — Target cluster name (required, not auto-derivable).
+- `target` — Connected workspace ID or unambiguous name, if scoped.
+
+## Procedure
+
+Goal: copy/sync S3 -> NFS, optionally on a nightly schedule (write actions;
+refused under MLSPACE_READONLY=true).
+1. data_transfer list_connectors. SOURCE: an object-storage connector (s3amazon/
+   s3custom/s3google). DEST: an NFS/cluster connector. Capture both connector ids.
+2. cluster_name is REQUIRED and is NOT readable from the connector — ask the user or
+   take it from context; do not guess from get_connector.
+3. (optional, S3 only) try_connector to pre-check connectivity (+ its /try/logs).
+4. Ensure source_path + destination_path are known (ask if absent). Strategy:
+   one-off=write_all; nightly incremental + a crontab schedule (e.g. "0 2 * * *").
+5. list_transfers; if one matches this source->dest and the user means "edit", capture
+   its id for update instead of create.
+6. create_transfer (body=TransferInputViewModelV5: name, connector ids, paths,
+   cluster_name, strategy, optional crontab) OR update_transfer(id_, full body).
+   To just enable/disable: switch_transfer(id_, body={"active": true|false}).
+7. Verify: list_history(transfer_id) -> latest run id + status; get_history_status.
+Output: which connectors were used, the created/updated transfer id + schedule, and the
+first run's status. Echo the body before writing. Caveat: cluster_name must be supplied.

mlspace_mcp/skills/mlspace-transfer-compute-node/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: mlspace-transfer-compute-node
+description: "Inspect and transfer a compute node between queues on Cloud.ru MLSpace. Check shared workload before recommending or moving a compute node. Write only on request. Uses the mlspace_contexts, mlspace_notebooks, mlspace_queue_inspect, mlspace_queues tools."
+license: MIT
+compatibility: Requires the `mlspace` MCP server from this plugin (Cloud.ru MLSpace credentials needed).
+---
+
+# Inspect and transfer a compute node between queues
+
+Check shared workload before recommending or moving a compute node. Write only on request.
+
+This skill drives the `mlspace` MCP server shipped in the same plugin. If its
+tools are not connected, say so instead of guessing — none of these steps can be
+carried out any other way.
+
+## Arguments
+
+- `source_queue_id` **(required)** — Source queue ID.
+- `destination_queue_id` — Destination queue ID.
+- `destination_target` — Destination connected workspace ID or unambiguous name.
+- `node_name` — Compute node name; omit to inspect source candidates.
+- `target` — Connected workspace ID or unambiguous name, if scoped.
+
+## Procedure
+
+Goal: inspect and, when requested, move a COMPUTE NODE between queues. A Jupyter
+server is a workload, not the node to move. Never substitute notebooks pause/modify.
+1. Resolve the source queue_id/target and destination_queue_id/destination_target
+   within mlspace_contexts. If placement is delegated, compare eligible destinations
+   and report the choice without another workspace question.
+2. mlspace_queue_inspect(queue_id=source_queue_id, target=target,
+   candidate_nodes=[node_name]) (omit candidate_nodes to inspect source queue nodes).
+   Leave targets omitted to inspect the fixed selected set, unless the user explicitly
+   restricts observation. Examine checked_scope/failures/complete, queue/allocation
+   association, candidate membership, allocation node facts and node loads alongside
+   jobs/notebooks/pods and all pending priorities. Pending is demand, not running load;
+   paused notebook configuration alone is not capacity that can be freed.
+3. mlspace_queues get (queue_id=destination_queue_id, target=destination_target) and
+   mlspace_queues instance_types (queue_id=destination_queue_id,
+   target=destination_target) to check the destination/allocation compatibility.
+   Match concrete identities; a friendly workspace name or request context does not
+   establish owner identity. Repeated shared views cannot be summed.
+4. Report candidates, observed competing workload, freshness, failed/unread scopes
+   and unknown cross_workspace_coverage. Even complete=true does not prove all shared
+   workload is visible. If visibility is incomplete, do not call the move impact-free;
+   explain the remaining check before recommending a candidate as idle.
+5. If the user requested execution and placement/node are resolved, use supported
+   mlspace_queues add_nodes (target=destination_target, queue_id=destination_queue_id,
+   body={"nodes":[node_name], "force_withdrawal":false}). Follow the action's existing
+   write/confirm rules; never add a new mandatory workspace confirmation. Do not
+   silently escalate force_withdrawal on refusal; explain its consequences and use it
+   only when forced withdrawal was explicitly authorized. There is no remove_nodes
+   action to invent. Provider acceptance remains subject to queue/allocation policy.
+Example calls (replace these illustrative IDs with resolved addresses):
+```json
+{"tool":"mlspace_queue_inspect","arguments":{"queue_id":"source-queue","target":"workspace-a","candidate_nodes":["node-a"]}}
+```
+```json
+{"tool":"mlspace_queues","arguments":{"action":"add_nodes","target":"workspace-b","queue_id":"destination-queue","body":{"nodes":["node-a"],"force_withdrawal":false}}}
+```
+6. Read source and destination queue membership and relevant node loads again. Report
+   actual results and unresolved impact; HTTP success alone does not prove idle load
+   or uninterrupted workloads. For an inspection-only request, stop before add_nodes.