bios-mcp 0.1.1-dev.13 → 0.1.1-dev.17

package/README.md

@@ -41,22 +41,73 @@ not claimed without an explicit acknowledgement from the endpoint.
 ## Safe inference workflow
 
 1. `get_inference_gpu_options` returns inference-fit configurations joined to
-   authoritative deployment prices and stock. `unknown` is not treated as
-   available.
+   authoritative deployment prices and stock. Prefer the MODEL-ADDRESSED form
+   (`model=<hf_repo_id>`, optionally `revision`/`hf_integration_id`): the
+   server resolves the model facts (vision-aware) and answers with computed
+   `min_gpus`, `valid_counts`, and `bookable_counts` — the exact minimums the
+   create gate enforces, so client-supplied facts can never understate a
+   minimum. `unknown` is not treated as available; never offer a count below
+   `min_gpus` or outside `bookable_counts`.
 2. `preflight_inference` validates the exact source, model, GPU, queue, price
    cap, and wallet-hold terms without creating a deployment or mutating funds.
-3. `create_inference` uses the same request contract. Queueing is opt-in, a
-   maximum total hourly price is explicit, and a GPU alternative is never
-   selected without approval. Its inference key is shown only once.
-4. `get_inference_status` reports durable queue expiry (including
-   `status_reason=queue_expired`), provisioning/loading, endpoint readiness,
-   price cap, notification summary, and wallet authorization. An endpoint is
-   live only when the returned status is `running`.
-5. `get_inference_notifications` reports durable lifecycle-email delivery,
+3. `create_inference` uses the same request contract, self-validates the
+   selection against the model-addressed minimums before submitting, and
+   follows BOOK-BEFORE-REVEAL: a non-queued create answers `202` with a
+   booking handle while a vendor-accepted GPU is booked (30-40 s typical); the
+   tool polls the handle and returns the full payload — including the ONE-TIME
+   `inference_key` — only after the GPU is confirmed. A definitive miss
+   returns the standard `CAPACITY_UNAVAILABLE` error with fresh alternatives
+   and NO deployment exists (nothing charged). Queueing is opt-in, a maximum
+   total hourly price is explicit, and a GPU alternative is never selected
+   without approval. `gpu_priorities` backups (1-5 ranked choices) may be
+   supplied on ANY create — they form the after-start replacement ladder;
+   the queue itself stays opt-in.
+4. `get_inference_booking` polls a booking handle from a long-running
+   `create_inference` (pending → revealed payload → or the standard 409).
+5. `get_inference_status` reports durable queue state, provisioning/loading,
+   endpoint readiness, price cap, notification summary, and wallet
+   authorization. An endpoint is live only when the returned status is
+   `running`. `queued_capacity` means waiting for stock at zero charge —
+   after a deployment has ever been booked, GPU loss never ends in a
+   capacity failure; it waits and auto-resumes.
+6. `get_inference_notifications` reports durable lifecycle-email delivery,
    bounded retries, and operator-visible dead letters.
-6. `update_inference_policy`, `stop_inference`, `resume_inference`,
+7. `update_inference_policy`, `stop_inference`, `resume_inference`,
    `restart_inference`, and `delete_inference` manage the lifecycle.
 
+## Standard capacity error contract
+
+Training and inference speak ONE capacity rejection shape: HTTP `409` with
+`error.code = CAPACITY_UNAVAILABLE` (training also echoes the deprecated
+`SELECTED_GPU_UNAVAILABLE` as `legacy_code` for one release). The MCP
+transport serializes it as compact JSON in the tool-error text — even when
+zero alternatives exist — so an agent can act on it directly:
+
+```json
+{
+  "code": "CAPACITY_UNAVAILABLE",
+  "reason": "insufficient_stock | below_model_minimum | invalid_gpu_count | model_too_large",
+  "message": "H200 is out of stock",
+  "recoverable": true,
+  "instruction": "Retry with one of available_gpus (never below its min_gpus), or resubmit with allow_capacity_queue=true.",
+  "available_gpus": [
+    { "gpu_type": "H100_80GB", "gpu_count": 2, "min_gpus": 2, "valid_counts": [2, 4, 8],
+      "tier": "secure", "price_hour_cents": 598, "available_count": 6 }
+  ],
+  "minimum_requirement": {
+    "selected_gpu_min": 2, "selected_valid_counts": [2, 4, 8],
+    "per_type": [{ "gpu_type": "H200", "min_gpus": 2, "valid_counts": [2, 4, 8] }]
+  },
+  "selected": { "gpu_type": "H200", "gpu_count": 2, "availability_status": "out_of_stock" },
+  "queue_eligible": false,
+  "checked_at": "2026-07-19T00:00:00Z"
+}
+```
+
+A `503 ADMISSION_UNAVAILABLE` is a transient market outage, never a capacity
+verdict — retry shortly, never conclude out-of-stock from it. See
+`get_platform_guide` topic `capacity_errors` for the recovery playbook.
+
 Raw Hugging Face tokens are intentionally excluded from MCP tool inputs. Store
 the token in a platform Hugging Face integration and pass `hf_integration_id`.
 
@@ -65,6 +116,30 @@ the token in a platform Hugging Face integration and pass `hf_integration_id`.
 original acknowledgement instead of creating another job, wallet hold, queue
 entry, or GPU request. The MCP server generates a fresh key when it is omitted.
 
+## Training lifecycle (book-before-reveal)
+
+Like inference, `create_training_job` books a GPU before it reveals a job.
+The call blocks while the ranked ladder is booked (~40s typical); a job id and
+the "training started" email exist only once a real pod is secured. Read
+`status` on the response and from `get_training_status`:
+
+- `booked` — a GPU is secured (booked == secured); the job then provisions,
+  downloads, and runs on its own. Money is captured only after this point.
+- `securing` — still booking at the deadline; the async tail continues.
+  Poll `get_training_status` until `booked`/`running` (or a terminal state).
+  Nothing is charged while securing.
+- `queued` — returned only with explicit queue consent; waits for stock at
+  zero charge and books via the same path.
+- A booking-time capacity miss returns the standard `CAPACITY_UNAVAILABLE`
+  (409) with fresh `available_gpus` and **no job exists** (nothing charged);
+  a transient `503 ADMISSION_UNAVAILABLE` is a retry, never out-of-stock, and
+  the platform never auto-substitutes a GPU.
+
+If a started job loses its pod, it rests at `interrupted` — a self-heal state
+distinct from `failed` in which billing is already stopped. Call
+`resume_training_job` to continue from the last checkpoint; resume re-books on
+secured capacity before reporting resumed, so the same guarantees apply.
+
 Training and deployment share one authoritative GPU-capacity broker. Server
 priority is evaluated first. Within an equal-priority class, the broker rotates
 across users and preserves FIFO order within each user's own requests. This

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bios-mcp",
-  "version": "0.1.1-dev.13",
+  "version": "0.1.1-dev.17",
   "description": "BIOS MCP server — train and deploy AI models from MCP-compatible automation clients",
   "license": "MIT",
   "type": "module",