runbios-mcp 0.2.1-dev.97 → 0.2.1-rc.118

package/dist/server.js

@@ -594,9 +594,47 @@ launchGates = resolveLaunchGates()) {
     // The registrations below are moved verbatim from the original single-file
     // entry and intentionally keep their original indentation. `server.tool(...)`
     // is a thin delegate that adds the onToolCall hook around each handler.
+    const registeredTools = new Set();
+    const datasetMixingSchema = z.object({
+        mode: z.enum(["sequential", "shuffle", "interleave", "phased"]),
+        seed: z.number().int().min(Number.MIN_SAFE_INTEGER).max(Number.MAX_SAFE_INTEGER).optional(),
+        weights: z.array(z.number().nonnegative()).min(1).max(64).optional(),
+        phases: z.array(z.object({
+            name: z.string().max(255).optional(),
+            portion: z.number().positive().max(1),
+            weights: z.array(z.number().nonnegative()).min(1).max(64).optional(),
+            shuffle: z.boolean().optional(),
+        })).min(1).optional(),
+    });
+    const trainingConfigurationSchema = {
+        dataset_sample_limits: z.record(z.string(), z.number().int().min(0)).optional().describe("Per-dataset first-N row caps; keys must be selected dataset IDs. Omit or use 0 for the full source."),
+        epochs: z.number().positive().max(1000).optional().describe("Number of training epochs. Governs the full run when max_steps is omitted (the default)."),
+        max_steps: z.number().int().min(1).max(10_000_000).optional().describe("Optional hard step cap that overrides epochs. Omit for no cap and all configured epochs; setting less than one epoch intentionally trains only part of the data."),
+        learning_rate: z.number().positive().max(1).optional().describe("Learning rate."),
+        batch_size: z.number().int().min(1).max(65536).optional().describe("Per-device train batch size."),
+        gradient_accumulation_steps: z.number().int().min(1).max(65536).optional(),
+        max_seq_length: trainingSeqLengthSchema(),
+        lora_rank: z.number().int().min(1).max(4096).optional(),
+        lora_alpha: z.number().positive().max(1_000_000).optional(),
+        warmup_ratio: z.number().min(0).max(1).optional(),
+        weight_decay: z.number().min(0).max(10).optional(),
+        scheduler: z
+            .enum(["linear", "cosine", "cosine_with_restarts", "polynomial", "constant", "constant_with_warmup"])
+            .optional()
+            .describe("Learning-rate scheduler."),
+        job_name: z.string().max(255).optional(),
+        eval_split_ratio: z.number().min(0).max(0.99).optional(),
+        eval_steps: z.number().int().positive().optional().describe("Evaluate every N optimizer steps when a validation split exists."),
+        save_steps: z.number().int().positive().optional().describe("Checkpoint interval in optimizer steps."),
+        early_stopping_patience: z.number().int().min(0).max(20).optional()
+            .describe("Stop after N evaluations without a better validation loss (0 = off; default 3 when eval_split_ratio is set). The best checkpoint is always saved."),
+        overlong_policy: z.enum(["truncate", "drop"]).optional()
+            .describe("SFT only. 'truncate' trims oldest context while preserving a trainable answer; 'drop' skips overlong samples. CPT packs raw text and does not use this policy."),
+    };
     const server = {
         tool(name, description, paramsSchema, cb) {
             mcp.tool(name, description, paramsSchema, wrapToolHandler(name, cb, hooks?.onToolCall));
+            registeredTools.add(name);
         },
     };
     /* ══════════════════════════════════════════════════════════════════════════ */
@@ -628,12 +666,10 @@ launchGates = resolveLaunchGates()) {
            a stand-in that says what launches soon and names only tools that ARE
            registered (reads/lifecycle stay live). At launch the gates open and the
            real topics return verbatim. */
-        // 42 tools with every creation tool registered; the gates hide three
-        // (create_training_job, upload_dataset, import_huggingface_dataset). The
-        // coming-soon gate test pins this claim to the wire count, so drift fails.
-        const liveToolCount = 42
-            - (launchGates.training ? 1 : 0)
-            - (launchGates.datasets ? 2 : 0);
+        // Count the actual registrations, including the conditional creation tools.
+        // This is read when the guide is called, after registration has completed.
+        // The coming-soon gate test also pins this claim to the wire count.
+        const liveToolCount = registeredTools.size;
         const comingSoonNote = `# Coming soon
 
 ${gatedSurfaces.join(" and ")} ${gatedSurfaces.length > 1 ? "are" : "is"} not available in this build yet — the creation tools are not registered, so no tool call (and no workaround) can start one today. Do not retry or search for one.
@@ -690,9 +726,9 @@ get_inference_status instead of asserting them.
 4. search_models / list_models - Find a model from the hosted catalog
 5. get_model_config - Recommended settings for a chosen model
 6. list_supported_architectures - Which architectures can be served
-7. get_gpu_pricing / get_recommended_gpu - GPU options and pricing
-8. list_integrations - Connected Hugging Face accounts
-9. list_datasets / preview_dataset / delete_dataset - Read and clean up existing datasets
+7. get_gpu_pricing / get_recommended_gpu / recommend_training_config - GPU options, pricing, and the trainer's own batch/memory/time recommendation
+8. list_integrations / search_huggingface_datasets / preview_huggingface_dataset - Discover Hub sources and inspect subsets/splits
+9. list_datasets / get_dataset_status / preview_dataset / delete_dataset - Read and clean up existing datasets
 10. get_training_capabilities - Read the authoritative training contract
 11. preflight_training_job - Validate a proposed job payload (no side effects)
 12. list_training_jobs / get_training_status - Monitor existing jobs
@@ -711,7 +747,26 @@ get_inference_status instead of asserting them.
 8. update_inference_policy - Change explicit queue consent or the maximum accepted hourly price
 9. stop_inference / resume_inference / restart_inference - Control serving lifecycle
 10. chat_with_inference - Call a serverless catalog model by id or a dedicated deployment via the unified /v1 endpoint (optional streaming)
-11. delete_inference - Permanently remove a deployment after verified infrastructure teardown`;
+11. delete_inference - Permanently remove a deployment after verified infrastructure teardown
+
+## Conscious Loop MCP Tools
+The loop turns what a deployed model actually did into what it learns next.
+NOTHING IS RECORDED until loop_set_capture turns a source on — capture is a
+consent decision, not a default, and these tools cannot bypass it.
+1. loop_set_capture - Turn recording on or off for a source and set how long conversations are kept. Start here; every other loop tool is inert until this is done.
+2. loop_capture_trace / loop_import_rows - Record one exchange as it happens (what the model was asked, what it answered, any tool calls), whoever served the model — Run BiOS, another provider, or your own servers. loop_import_rows brings in data that already exists instead: an export, a spreadsheet of past answers, preference pairs. Imported rows arrive as conversations NEEDING REVIEW, never as finished training data.
+3. loop_list_traces / loop_get_trace - Read what has been recorded. Credentials and personal details are stripped before storage, never after.
+4. loop_add_signal - Record whether an answer was right. Append-only. Verdict 'edited' with a correction is the most valuable feedback there is.
+5. loop_add_candidate / loop_list_candidates - Submit ALTERNATIVE answers to a recorded prompt. Sampling the model N times and scoring the samples produces DPO pairs without a human writing each one; a stronger model's answers do distillation the same way.
+6. loop_label_trace / loop_remove_label / loop_list_labels - Carve the corpus into slices. A bare tag with a parent makes a master group; NAMED DIMENSIONS (category, task, language, anything you like) are what let ONE captured corpus become a DIFFERENT dataset for every task, because filters on different dimensions AND together and nothing has to be re-labelled.
+7. loop_create_judge / loop_list_judges - A RUBRIC a model applies, for the question no rule can answer: was this actually helpful. The rubric doubles as a GRPO reward function, which makes prompts with no checkable answer trainable.
+8. loop_start_judge_run then loop_take_judge_work then loop_post_judge_verdicts - Run a rubric over a slice. YOU call the model: take the rendered prompt, send it, post the scores back.
+9. loop_create_grader / loop_list_graders - Deterministic rules that score answers with no person reading them, weighted so the criteria that matter count more, and aimable at one label so a rule about shipping does not mark down every billing answer.
+10. loop_grade_trace - Apply those rules to an answer AND its samples in one pass. This is what closes the loop automatically.
+11. loop_build_dataset - Curate the feedback into an sft, dpo, grpo or kto training set. Always reports why rows were left out. kto takes a bare thumbs-down, which the other three cannot use at all.
+12. loop_list_datasets - The sets built so far, each with how many rows it kept and why the rest were dropped.
+13. loop_preview_dataset - Read the actual rows before anyone trains on them; each carries the address of the conversation it came from.
+14. loop_stats - How much is recorded, how much is reviewed, and what each method could use right now.`;
         const guides = {
             overview: `# Run BiOS Fine-Tuning Platform
 
@@ -756,7 +811,7 @@ get_inference_status instead of asserting them.
 - JWT token: Use \`Authorization: Bearer <token>\` header with \`X-Org-ID\` and \`X-Workspace-ID\` headers
 - Call introspect_api_key to see your permissions, scopes, and which tools you can use
 
-## Available MCP Tools (42 in this build, listed in recommended order)
+## Available MCP Tools (${liveToolCount} in this build, listed in recommended order)
 1. get_platform_guide - You're reading this! Context for all capabilities
 2. introspect_api_key - Discover your API key's permissions, scopes, and bound workspace
 3. get_wallet_balance - Check if you have enough credits before training
@@ -765,10 +820,11 @@ get_inference_status instead of asserting them.
 6. list_supported_architectures - Check which architectures can be trained or served
 7. get_training_capabilities - Read the authoritative training contract; call this before building automated payloads
 8. get_gpu_pricing - See GPU options and pricing
-9. get_recommended_gpu - Get the best GPU for your model + adapter combo
-10. list_integrations - See the Hugging Face accounts connected to your workspace
+9. get_recommended_gpu - Read default-config sizing; use full preflight for the actual run
+9a. recommend_training_config - Ask the trainer's sizing model for batch, accumulation, LR, predicted peak memory, minimum GPU count and wall clock on the GPU you picked; check your own batch size against it
+10. list_integrations / search_huggingface_datasets / preview_huggingface_dataset - Choose the Hub account, dataset, subset and split
 11. list_datasets / upload_dataset / import_huggingface_dataset - Prepare training data
-12. preview_dataset - Verify dataset format before training
+12. get_dataset_status / preview_dataset - Verify readiness and dataset format before training
 13. delete_dataset - Remove a dataset you no longer need
 14. preflight_training_job - Validate the full job before creating it
 15. create_training_job - Launch the fine-tuning job
@@ -792,7 +848,26 @@ get_inference_status instead of asserting them.
 8. update_inference_policy - Change explicit queue consent or the maximum accepted hourly price
 9. stop_inference / resume_inference / restart_inference - Control serving lifecycle
 10. chat_with_inference - Call a serverless catalog model by id or a dedicated deployment via the unified /v1 endpoint (optional streaming)
-11. delete_inference - Permanently remove a deployment after verified infrastructure teardown`,
+11. delete_inference - Permanently remove a deployment after verified infrastructure teardown
+
+## Conscious Loop MCP Tools
+The loop turns what a deployed model actually did into what it learns next.
+NOTHING IS RECORDED until loop_set_capture turns a source on — capture is a
+consent decision, not a default, and these tools cannot bypass it.
+1. loop_set_capture - Turn recording on or off for a source and set how long conversations are kept. Start here; every other loop tool is inert until this is done.
+2. loop_capture_trace / loop_import_rows - Record one exchange as it happens (what the model was asked, what it answered, any tool calls), whoever served the model — Run BiOS, another provider, or your own servers. loop_import_rows brings in data that already exists instead: an export, a spreadsheet of past answers, preference pairs. Imported rows arrive as conversations NEEDING REVIEW, never as finished training data.
+3. loop_list_traces / loop_get_trace - Read what has been recorded. Credentials and personal details are stripped before storage, never after.
+4. loop_add_signal - Record whether an answer was right. Append-only. Verdict 'edited' with a correction is the most valuable feedback there is.
+5. loop_add_candidate / loop_list_candidates - Submit ALTERNATIVE answers to a recorded prompt. Sampling the model N times and scoring the samples produces DPO pairs without a human writing each one; a stronger model's answers do distillation the same way.
+6. loop_label_trace / loop_remove_label / loop_list_labels - Carve the corpus into slices. A bare tag with a parent makes a master group; NAMED DIMENSIONS (category, task, language, anything you like) are what let ONE captured corpus become a DIFFERENT dataset for every task, because filters on different dimensions AND together and nothing has to be re-labelled.
+7. loop_create_judge / loop_list_judges - A RUBRIC a model applies, for the question no rule can answer: was this actually helpful. The rubric doubles as a GRPO reward function, which makes prompts with no checkable answer trainable.
+8. loop_start_judge_run then loop_take_judge_work then loop_post_judge_verdicts - Run a rubric over a slice. YOU call the model: take the rendered prompt, send it, post the scores back.
+9. loop_create_grader / loop_list_graders - Deterministic rules that score answers with no person reading them, weighted so the criteria that matter count more, and aimable at one label so a rule about shipping does not mark down every billing answer.
+10. loop_grade_trace - Apply those rules to an answer AND its samples in one pass. This is what closes the loop automatically.
+11. loop_build_dataset - Curate the feedback into an sft, dpo, grpo or kto training set. Always reports why rows were left out. kto takes a bare thumbs-down, which the other three cannot use at all.
+12. loop_list_datasets - The sets built so far, each with how many rows it kept and why the rest were dropped.
+13. loop_preview_dataset - Read the actual rows before anyone trains on them; each carries the address of the conversation it came from.
+14. loop_stats - How much is recorded, how much is reviewed, and what each method could use right now.`,
             quick_start: `# Quick Start Guide
 
 ## Fastest path to a fine-tuned model:
@@ -808,12 +883,15 @@ For beginners: start with meta-llama/Llama-3.1-8B-Instruct (good balance of qual
 Option A: Upload your own file — call upload_dataset with the file path
 Option B: Import from HuggingFace — call import_huggingface_dataset with a repo ID
 
-Dataset must be JSONL: {"messages": [...]} per line for SFT, or {"text": "..."} per line for CPT. Other layouts are refused with conversion guidance.
+Dataset upload accepts one file type: JSONL. Each line is {"messages": [...]} for SFT (with a final assistant response), or {"text": "..."} for CPT. A Hugging Face split may be stored upstream as Parquet or Arrow, but its ROWS must already have the same canonical shape. Other layouts are refused with conversion guidance before the dataset can become Ready.
 
-### Step 4: Get recommended config
-Call get_model_config with your model name to see recommended GPU, adapter, and hyperparameters.
+### Step 4: Choose method, adapter, and the complete training configuration
+Call get_model_config and get_training_capabilities. Choose SFT or CPT, adapter, sequence length, per-device batch, gradient accumulation, optimizer, precision, epochs/optional max_steps, validation and checkpoint settings BEFORE asking for a GPU. Empty max_steps means no cap: all configured epochs train. Early stopping defaults on when validation exists.
 
-### Step 5: Create the training job
+### Step 5: Preflight the complete request and choose a GPU LAST
+Call preflight_training_job with the model, dataset(s), method, adapter and complete config. Its GPU choices are sized from ALL of those inputs and joined to live inventory. Choose only a returned configuration; never guess a GPU count or use a choice below min_gpus.
+
+### Step 6: Create the training job
 Call create_training_job with:
 - model: the model name from step 2
 - dataset_id: the ID from step 3
@@ -821,7 +899,7 @@ Call create_training_job with:
 - adapter: "lora" (fastest, recommended for first jobs)
 - Leave other params as defaults unless you have specific needs
 
-### Step 6: Monitor progress
+### Step 7: Monitor progress
 create_training_job books a GPU before returning (~40s). A 'booked' status means the GPU is secured (booked==secured) and training is starting; 'securing' means it is still booking — poll get_training_status until 'booked'/'running'. A booking-time capacity miss returns CAPACITY_UNAVAILABLE and no job is created.
 Call get_training_status periodically. Training typically takes 1-4 hours for small models.
 If a started job loses its pod it rests at 'interrupted' (billing already stopped, not 'failed') — call resume_training_job to continue from the last checkpoint.
@@ -891,11 +969,23 @@ Example JSONL:
 - ShareGPT conversations (from/value) -> role/content with human -> user, gpt -> assistant
 - Preference pairs (chosen/rejected) and prompt-only RL formats are not accepted for training.
 
+## Discover, preview and import
+1. Call list_integrations to choose a connected account, or use public Hub access.
+2. Call search_huggingface_datasets; use has_more and page for additional results.
+3. Call preview_huggingface_dataset. Choose from available_configs/available_splits and repeat the preview with that exact subset/split.
+4. Preserve integration_id, subset and split in import_huggingface_dataset. An explicit revision pins the import to that source; otherwise the service resolves and stores an immutable commit when importing.
+5. Poll get_dataset_status until ready. A returned dataset ID or temporarily unavailable preview does not mean validation succeeded. Preview the registered dataset before training, especially when importing an explicit older revision.
+
+## Composition and resume
+- dataset_ids is an ordered array. Sequential mode keeps that order; shuffle randomizes it with a recorded seed (default 42).
+- mixing supplies mode, seed, weights and optional phases. Weight positions match dataset_ids exactly. Use phased for an ordered curriculum and interleave for weighted draws.
+- Preflight and create receive the same plan. Source pins, plan and checksum are stored; resume rebuilds data from metadata and verifies it rather than reusing a composed-data cache.
+
 ## Best Practices
-- Minimum 100 rows recommended (1,000+ for best results)
-- Maximum 500MB file size through this tool
-- Consistent formatting across all rows; remove duplicates and low-quality examples
-- Pick max_seq_length above your longest sample: samples longer than it are dropped and reported`,
+- Keep a representative held-out validation set; quality matters more than a fixed row-count target.
+- Maximum 500MB file size through the current MCP upload tool.
+- Keep row structure consistent; remove unintended duplicates and low-quality examples.
+- SFT defaults to truncating oldest context while retaining a trainable answer; unusable samples are dropped and reported. CPT packs raw text and has no per-sample truncate/drop option.`,
             training_methods: `# Training Methods
 
 ## SFT — Supervised Fine-Tuning ⭐ Most Common
@@ -909,49 +999,30 @@ Best for: Injecting domain knowledge into the base model before fine-tuning.
 Input: Raw text documents.
 When to use: Before SFT, when your domain has specialized vocabulary/knowledge.
 
-## Recommended Pipeline
-1. CPT (if domain-specific knowledge needed) → 2. SFT
-For most users: SFT alone is sufficient.`,
+## Current limits
+- The current tools expose SFT and text-corpus CPT with full, LoRA and QLoRA; read get_training_capabilities for deployment-specific restrictions.
+- A VLM architecture does not imply support for image-only pretraining or multimodal preference objectives.
+- DPO, PPO and GRPO are not enabled by these training tools. They require separately verified training implementations; PPO/GRPO also require rollout inference and reward handling.
+- Training starts from catalog models. Do not promise a CPT-to-SFT pipeline using a customer's trained checkpoint as a new training source: that workflow is not exposed here.`,
             gpu_selection: `# GPU Selection Guide
 
-## Available GPUs
-
-| GPU | VRAM | Best For | Per-Second Cost |
-|-----|------|----------|-----------------|
-| A6000 | 48 GB | Models up to 13B with LoRA | ~$0.0007/sec |
-| A100 80GB | 80 GB | Models up to 70B with QLoRA, up to 13B full | ~$0.0007/sec |
-| H100 | 80 GB | Large models, fastest training | ~$0.0011/sec |
-
-## Model Size → GPU Recommendations
-
-### LoRA Fine-Tuning (most common)
-- 1B-3B models: A6000 (48GB) — plenty of headroom
-- 7B-13B models: A100 80GB ⭐ sweet spot
-- 30B-70B models: A100 80GB or H100 (may need multi-GPU)
-
-### QLoRA Fine-Tuning (4-bit quantized, uses less VRAM)
-- 7B-13B models: A6000 (48GB) — enough with quantization
-- 30B-70B models: A100 80GB
-- 70B+ models: H100 or multi-GPU A100
-
-### Full Fine-Tuning (no adapter, maximum quality)
-- 1B-3B models: A100 80GB
-- 7B models: 2-4x A100 80GB
-- 13B+ models: 4-8x A100 or H100
-
-## Cost Optimization Tips
-- Run BiOS bills per-SECOND, not per-hour — stop jobs early to save money
-- LoRA training is 5-10x cheaper than full fine-tune for comparable quality
-- QLoRA adds ~10% training time but halves VRAM needs
-- Start with fewer epochs (1-2) to validate, then train full if results look good
-- Use the get_recommended_gpu tool to get the optimal GPU for your specific setup
-
-## Multi-GPU
-For models that don't fit in a single GPU's VRAM, the platform automatically shards across GPUs.
-Specify gpu_count in create_training_job (default: 1).
-
-## Infrastructure and Price Caps
-The platform selects and manages the underlying infrastructure automatically. You choose only the GPU type, the GPU count, and a maximum total hourly price cap. Preflight returns ranked alternatives and the exact price that will be honored. A price above the approved cap is rejected rather than silently accepted.`,
+## Configure first, choose the GPU last
+1. Select the catalog model and revision, method, adapter and compatible datasets.
+2. Set supported configuration fields from get_training_capabilities: sequence length, batch and accumulation, validation and run-length bounds. Review effective precision/optimizer settings; leave disabled engine-managed controls such as activation checkpointing to the engine.
+3. The current preflight API requires a concrete gpu_type/gpu_count. Use get_recommended_gpu only to obtain a provisional candidate, then call preflight_training_job with that candidate and the complete configuration. Never treat default-config sizing as approval of the final run.
+4. Review the service-calculated minimum, supported counts and current quote. Choose only a qualifying available type/count. Fit is not stock, and an unknown availability result is not permission to book.
+5. Re-run preflight after changing any sizing input or GPU choice; create only after valid=true with the final selection. GPU-free preflight discovery is not currently supported by the deployed API.
+
+## Booking and recovery
+- Create rechecks capacity. Do not report a run as started while it is only securing; booked means capacity was accepted, not that the trainer has begun executing steps.
+- A capacity miss must show fresh qualifying alternatives and preserve the configuration. Ask before substituting hardware or exceeding a price cap.
+- Queueing is explicit consent and applies only when no qualifying alternative is available. Waiting is unbilled.
+- Reuse the idempotency key after timeouts instead of creating a second run.
+
+## Memory and quality
+- Memory depends on the full configuration and input shapes, not parameter count alone. Do not invent a smaller minimum or claim that quantization always halves total memory.
+- Full fine-tuning is not a guarantee of higher accuracy than adapters. Use representative validation to compare outcomes.
+- Preflight admission is not proof of universal freedom from hardware faults or OOM. Report actual tested configurations and measured headroom.`,
             inference: `# Model Inference Guide
 
 Deployments serve either a verified fine-tuning checkpoint or a base model from the catalog through an OpenAI-compatible endpoint.
@@ -1399,6 +1470,50 @@ create (1-5 choices), and the queue itself stays opt-in.`,
         return json(data);
     });
     /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOL: recommend_training_config                                         */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("recommend_training_config", "Ask the trainer's own sizing model what to run for a model on a GPU type: per-device batch size, gradient accumulation, learning rate, warmup, activation checkpointing, predicted peak GPU memory, the minimum GPU count that fits, a wall-clock estimate, and a verdict on the batch size you intend to use (with a same-global-batch alternative when it will not fit). Every number carries its basis (measured, derived, judgement). Side-effect free. When 'available' is false no advisor is deployed in this environment and no recommendation is returned -- do not treat that as 'anything fits'.", {
+        model: z.string().describe("Full model name (e.g., 'Qwen/Qwen3.6-27B')"),
+        gpu_type: z.string().describe("GPU type from get_recommended_gpu (e.g., 'B300_288GB')"),
+        gpu_count: z.number().int().min(1).max(8).optional().describe("GPUs you intend to book (default 1)."),
+        adapter: z.enum(TRAINING_ADAPTERS).optional().describe("Adapter type (default: 'lora')."),
+        method: z.enum(["sft", "pt"]).optional().describe("Canonical training method (default: 'sft')."),
+        max_length: z.number().int().min(128).max(262144).optional().describe("Training sequence length (default 2048)."),
+        num_train_epochs: z.number().positive().optional().describe("Epochs, for the wall-clock estimate."),
+        max_steps: z.number().int().positive().optional().describe("Step cap, if you set one."),
+        per_device_train_batch_size: z.number().int().min(1).optional().describe("Your intended per-device batch; judged against the model."),
+        gradient_accumulation_steps: z.number().int().min(1).optional(),
+        dataset_ids: z.array(z.string()).max(20).optional().describe("Datasets the job will train on; their measured token statistics feed the sizing."),
+        model_revision: z.string().optional(),
+    }, async (params) => {
+        const q = { model_id: params.model, gpu_type: params.gpu_type };
+        if (params.gpu_count !== undefined)
+            q.gpu_count = String(params.gpu_count);
+        if (params.adapter)
+            q.train_type = params.adapter;
+        if (params.method)
+            q.method = params.method;
+        if (params.max_length !== undefined)
+            q.max_length = String(params.max_length);
+        if (params.num_train_epochs !== undefined)
+            q.num_train_epochs = String(params.num_train_epochs);
+        if (params.max_steps !== undefined)
+            q.max_steps = String(params.max_steps);
+        if (params.per_device_train_batch_size !== undefined)
+            q.per_device_train_batch_size = String(params.per_device_train_batch_size);
+        if (params.gradient_accumulation_steps !== undefined)
+            q.gradient_accumulation_steps = String(params.gradient_accumulation_steps);
+        if (params.dataset_ids?.length) {
+            for (const id of params.dataset_ids)
+                validateId(id, "dataset_ids");
+            q.dataset_ids = params.dataset_ids.join(",");
+        }
+        if (params.model_revision)
+            q.model_revision = params.model_revision;
+        const data = await client.api("/api/training/recommend", { params: q });
+        return json(data);
+    });
+    /* ══════════════════════════════════════════════════════════════════════════ */
     /*  TOOL: get_inference_gpu_options                                         */
     /* ══════════════════════════════════════════════════════════════════════════ */
     server.tool("get_inference_gpu_options", "Get inference model-fit GPU choices joined to the authoritative deployment inventory and pricing snapshot. PREFER model-addressed sizing: pass model=<model_id> (optionally revision / hf_integration_id) and the SERVER resolves the facts (vision-aware) and returns computed min_gpus, valid_counts, and bookable_counts — the exact minimums the create gate enforces. Returns valid tensor-parallel counts, exact total hourly prices, availability as available/out_of_stock/unknown, and ranked alternatives. Never interpret unknown inventory as available, never offer a count below min_gpus or outside bookable_counts, and never substitute a SKU without user approval.", {
@@ -1760,8 +1875,14 @@ create (1-5 choices), and the queue itself stays opt-in.`,
     /* ══════════════════════════════════════════════════════════════════════════ */
     /*  TOOL: list_datasets                                                     */
     /* ══════════════════════════════════════════════════════════════════════════ */
-    server.tool("list_datasets", "List all datasets in your workspace. Returns dataset ID, name, format (JSONL/Parquet/CSV), row count, file size, column names, and creation date for each dataset.", {}, async () => {
-        const data = await client.api("/api/datasets");
+    server.tool("list_datasets", "Read one page of workspace datasets with metadata and readiness. Use offset/limit for more results; list membership does not mean the dataset is compatible with every training method.", {
+        query: z.string().max(256).optional(),
+        status: z.string().max(64).optional(),
+        dataset_type: z.string().max(64).optional(),
+        limit: z.number().int().min(1).max(200).optional(),
+        offset: z.number().int().min(0).optional(),
+    }, async ({ query, status, dataset_type, limit, offset }) => {
+        const data = await client.api("/api/datasets", { params: { q: query, status, dataset_type, limit: String(limit ?? 50), offset: String(offset ?? 0) } });
         return json(data);
     });
     /* ══════════════════════════════════════════════════════════════════════════ */
@@ -1773,7 +1894,7 @@ create (1-5 choices), and the queue itself stays opt-in.`,
     // server-side (403 DATASETS_COMING_SOON) as the authority. At launch the flag
     // opens and the registration returns verbatim.
     if (!launchGates.datasets) {
-        server.tool("upload_dataset", "Upload a dataset file for fine-tuning. Supports JSONL, Parquet, and CSV formats up to 500MB. The file is automatically validated: format detection, row counting, column identification, and schema validation. Returns the dataset ID needed for create_training_job.", {
+        server.tool("upload_dataset", "Upload one canonical JSONL dataset (maximum 500MB): one JSON object per line, with a messages array and final assistant response for SFT, or one non-empty text field for CPT. JSON arrays, CSV, Parquet, TXT, Alpaca, ShareGPT, prompt/completion, question/answer and preference-pair layouts are refused with conversion guidance. The server validates the rows before the dataset becomes Ready or selectable for training. Returns the dataset ID needed for create_training_job.", {
             file_path: z.string().describe("Absolute path to the dataset file on disk"),
             name: z.string().optional().describe("Display name for the dataset (defaults to filename)"),
         }, async ({ file_path, name }) => {
@@ -1819,7 +1940,7 @@ create (1-5 choices), and the queue itself stays opt-in.`,
     /* ══════════════════════════════════════════════════════════════════════════ */
     server.tool("preview_dataset", "Preview the first rows of a dataset to inspect its structure, column names, and content before training. Useful for verifying the dataset format is correct.", {
         dataset_id: z.string().describe("Dataset ID (e.g., 'ds_abc123')"),
-        rows: z.number().optional().describe("Number of rows to preview (default: 10, max: 50)"),
+        rows: z.number().int().min(1).max(50).optional().describe("Number of rows to preview (default: 10, max: 50)"),
     }, async ({ dataset_id, rows }) => {
         validateId(dataset_id, "dataset_id");
         const data = await client.api(`/api/datasets/${dataset_id}/preview`, {
@@ -1838,8 +1959,41 @@ create (1-5 choices), and the queue itself stays opt-in.`,
         return result(`Dataset ${dataset_id} deleted successfully.`);
     });
     /* ══════════════════════════════════════════════════════════════════════════ */
-    /*  TOOL: list_integrations                                                 */
+    /*  TOOL: dataset discovery and status                                      */
     /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("get_dataset_status", "Read dataset import/upload readiness, progress and validation failure. Do not select the dataset for training until status is ready; a dataset ID alone does not prove validation completed.", { dataset_id: z.string().min(1).max(128) }, async ({ dataset_id }) => {
+        validateId(dataset_id, "dataset_id");
+        return json(await client.api(`/api/datasets/${dataset_id}/status`));
+    });
+    server.tool("search_huggingface_datasets", "Search a bounded page of public Hub datasets, or browse with a selected connected account. Use list_integrations to choose the account; private/gated visibility depends on its permissions. Preserve integration_id for preview and import. Public search needs datasets:read; connected browsing needs integrations:read.", {
+        query: z.string().max(256).optional(),
+        integration_id: z.string().min(1).max(128).optional(),
+        page: z.number().int().min(1).max(100).optional(),
+        limit: z.number().int().min(1).max(50).optional(),
+        sort: z.enum(["downloads", "likes"]).optional(),
+    }, async ({ query, integration_id, page, limit, sort }) => {
+        if (integration_id)
+            validateId(integration_id, "integration_id");
+        return json(await client.api(integration_id ? `/api/datasets/integrations/${integration_id}/browse` : "/api/datasets/hub-search", {
+            params: {
+                [integration_id ? "search" : "q"]: query,
+                page: String(page ?? 1), limit: String(limit ?? 20), sort: sort ?? "downloads",
+            },
+        }));
+    });
+    server.tool("preview_huggingface_dataset", "Preview a Hub dataset before importing. Returns available configs/subsets and splits plus sample-format validation. If configuration selection is required, repeat with one returned subset and split. Use the same integration_id as search/import; authentication failures never fall back to public access. A preview outage is not proof of valid data.", {
+        repo_id: z.string().min(1).max(256),
+        integration_id: z.string().min(1).max(128).optional(),
+        subset: z.string().max(256).optional(),
+        split: z.string().min(1).max(128).optional(),
+        rows: z.number().int().min(1).max(20).optional(),
+    }, async ({ repo_id, integration_id, subset, split, rows }) => {
+        if (integration_id)
+            validateId(integration_id, "integration_id");
+        return json(await client.api("/api/datasets/hub-preview", {
+            params: { dataset_id: repo_id, integration_id, subset, split, limit: String(rows ?? 10), soft_errors: "true" },
+        }));
+    });
     server.tool("list_integrations", "List the integrations connected to your workspace, such as Hugging Face accounts. Returns each integration's ID, label, provider type, and status. Use an integration ID wherever a tool accepts integration_id: importing HuggingFace datasets. This is how you pick WHICH connected account an import should use when several are connected. This read is workspace-scoped: without workspace context it fails with WORKSPACE_CONTEXT_REQUIRED, which is a configuration fix (BIOS_WORKSPACE_ID or a workspace-bound API key), not something to retry.", {}, async () => {
         const data = await client.api("/api/datasets/integrations");
         return json(data);
@@ -1851,27 +2005,34 @@ create (1-5 choices), and the queue itself stays opt-in.`,
     // gated, exactly like upload_dataset above; the service's 403
     // DATASETS_COMING_SOON stays the authority.
     if (!launchGates.datasets) {
-        server.tool("import_huggingface_dataset", "Import a dataset from HuggingFace Hub into your workspace. Works with public datasets and private datasets if your HuggingFace account is connected via Integrations. The dataset is downloaded, validated, and stored in your workspace. Returns the dataset ID for use with create_training_job.", {
+        server.tool("import_huggingface_dataset", "Import the Hub dataset, subset and split selected through search/preview. Omit integration_id only for anonymous public access. The source is revision-pinned and either referenced or materialized in the background; poll get_dataset_status until ready before training. Canonical messages rows are required for SFT and text rows for CPT. This does not enable preference/RL training.", {
             repo_id: z
-                .string()
+                .string().min(1).max(256)
                 .describe("HuggingFace dataset repo whose rows already carry a messages array (SFT) or a text field (CPT)"),
             integration_id: z
-                .string()
-                .describe("HuggingFace integration ID from your connected integrations"),
-            split: z.string().optional().describe("Dataset split (default: 'train')"),
-            max_samples: z.number().optional().describe("Max rows to import (imports all if omitted)"),
-            name: z.string().optional().describe("Display name for the imported dataset"),
-        }, async ({ repo_id, integration_id, split, max_samples, name }) => {
-            const data = await client.api(`/api/datasets/integrations/${encodeURIComponent(integration_id)}/import`, {
-                method: "POST",
-                body: {
-                    dataset_id: repo_id,
-                    split: split ?? "train",
-                    max_samples,
-                    name: name ?? repo_id.split("/").pop(),
-                },
-            });
-            return json(data);
+                .string().min(1).max(128).optional()
+                .describe("Connected account ID; retain it from search/preview for private or gated datasets"),
+            subset: z.string().max(256).optional().describe("Exact subset/config selected from the preview response"),
+            split: z.string().min(1).max(128).optional().describe("Exact selected dataset split (default: 'train')"),
+            revision: z.string().min(1).max(256).optional().describe("Requested source commit/tag/branch; the service records an immutable commit for training and resume"),
+            max_samples: z.number().int().positive().optional().describe("Max rows to import (imports all if omitted)"),
+            sample_strategy: z.enum(["first", "random"]).optional(),
+            import_mode: z.enum(["auto", "reference", "materialize"]).optional(),
+            name: z.string().max(255).optional().describe("Display name for the imported dataset"),
+        }, async ({ repo_id, integration_id, subset, split, revision, max_samples, sample_strategy, import_mode, name }) => {
+            const common = { name: name ?? repo_id.split("/").pop(), max_samples, sample_strategy, import_mode };
+            if (integration_id) {
+                validateId(integration_id, "integration_id");
+                return json(await client.api(`/api/datasets/integrations/${integration_id}/import`, {
+                    method: "POST", body: { ...common, dataset_id: repo_id, subset, split: split ?? "train", revision },
+                }));
+            }
+            const workspaceId = client.workspaceId || (await client.api("/api/api-keys/introspect"))?.workspace?.id;
+            if (!workspaceId)
+                throw new Error("Workspace context is required: configure RUNBIOS_WORKSPACE_ID or use a workspace-bound API key.");
+            return json(await client.api("/api/datasets/register-hf", {
+                method: "POST", body: { ...common, workspace_id: workspaceId, hf_dataset_id: repo_id, hf_subset: subset, hf_split: split ?? "train", hf_revision: revision },
+            }));
         });
     }
     /* ══════════════════════════════════════════════════════════════════════════ */
@@ -1893,7 +2054,7 @@ create (1-5 choices), and the queue itself stays opt-in.`,
         model: z.string().describe("Base model id from the Run BiOS catalog (e.g., 'meta-llama/Llama-3.1-8B-Instruct'). Must be hosted on Run BiOS — pick from list_models/search_models. Training always starts from a catalog base model; training FROM a fine-tuned model (adapter stacking) is not supported."),
         model_revision: z.string().max(256).optional().describe("Requested model branch, tag, or commit. Copy the exact 40-hex value returned in canonical_request into create."),
         dataset_id: z.string().optional(),
-        dataset_ids: z.array(z.string()).min(1).optional(),
+        dataset_ids: z.array(z.string()).min(1).max(64).optional(),
         method: z.enum(TRAINING_METHODS),
         adapter: z.enum(TRAINING_ADAPTERS).optional(),
         gpu_type: z.string().optional(),
@@ -1915,8 +2076,9 @@ create (1-5 choices), and the queue itself stays opt-in.`,
         num_checkpoints: z.number().int().min(1).max(100).optional(),
         integration_id: z.string().optional(),
         network_volume_id: z.string().optional(),
-        cache_dataset: z.boolean().optional(),
         dataset_mixing: z.enum(["shuffle", "sequential", "interleave"]).optional(),
+        mixing: datasetMixingSchema.optional().describe("Composition plan. Dataset IDs define source order and weight positions; default seed is 42. The source pins, plan and checksum are retained for metadata-only resume."),
+        ...trainingConfigurationSchema,
         config: z.record(z.string(), z.unknown()).optional(),
     }, async (params) => {
         await assertModelHosted(params.model, "preflight_training_job");
@@ -1933,7 +2095,7 @@ create (1-5 choices), and the queue itself stays opt-in.`,
     // server-side (403 TRAINING_COMING_SOON before any billing or booking) as the
     // authority. At launch the flag opens and the registration returns verbatim.
     if (!launchGates.training) {
-        server.tool("create_training_job", "Create a fine-tuning job using the same contract as the web UI, following BOOK-BEFORE-REVEAL: the call blocks while the ranked GPU ladder is booked (~40s). A job id and the started email exist only once a real pod is secured, so status is 'booked' (booked==secured; training then provisions/downloads/runs on its own) or 'securing' (still booking at the deadline — poll get_training_status until booked/running). With explicit queue consent it may return 'queued'. A definitive booking-time miss returns the structured CAPACITY_UNAVAILABLE (409) with fresh available_gpus and NO job exists (nothing charged); never auto-substitute a GPU. Call preflight_training_job first, preserve the accepted ranked GPU choices, queue deadline, and maximum total hourly price, then reuse one idempotency key after timeouts.", {
+        server.tool("create_training_job", "Create a training job using the same BOOK-BEFORE-REVEAL contract as the web UI. Call preflight_training_job first with the complete model/method/adapter/dataset/config request, then choose one returned GPU configuration: GPU is last because its minimum depends on every earlier choice. The call does not reveal a run as started until a real pod is secured; status is booked (secured) or securing (poll get_training_status). A booking-time miss returns CAPACITY_UNAVAILABLE with fresh qualifying available_gpus and no job/no charge: choose one and retry with the same setup. The rejected GPU type is never recommended back. Queue consent is valid only when available_gpus is empty; waiting is unbilled and expires automatically. Reuse one idempotency key after timeouts.", {
             model: z.string().describe("Base model id from the Run BiOS catalog (e.g., 'meta-llama/Llama-3.1-8B-Instruct'). Must be hosted on Run BiOS — pick from list_models/search_models. Training always starts from a catalog base model; training FROM a fine-tuned model (adapter stacking) is not supported."),
             model_revision: z.string().max(256).optional().describe("Exact model_revision from preflight canonical_request; a branch or tag is accepted but resolved again before any paid mutation."),
             idempotency_key: z
@@ -1944,10 +2106,10 @@ create (1-5 choices), and the queue itself stays opt-in.`,
                 .optional()
                 .describe("Stable retry key. Reuse it after a timeout; omit to generate one for this tool call."),
             dataset_id: z.string().optional().describe("Compatibility field for one dataset ID."),
-            dataset_ids: z.array(z.string()).min(1).optional().describe("One or more dataset IDs to compose for training."),
+            dataset_ids: z.array(z.string()).min(1).max(64).optional().describe("One or more dataset IDs to compose for training."),
             method: z.enum(TRAINING_METHODS).describe("Training method: sft, or pt/cpt for continued pre-training."),
             adapter: z.enum(TRAINING_ADAPTERS).optional().describe("Any adapter supported by the Run BiOS contract."),
-            gpu_type: z.string().optional().describe("GPU type (e.g., 'A100_80GB'). Use get_recommended_gpu to find the best option. Auto-selected if omitted."),
+            gpu_type: z.string().optional().describe("GPU type returned by preflight_training_job after the complete training configuration is known. Do not guess or use a pre-configuration recommendation."),
             gpu_count: z.number().int().min(1).max(8).optional().describe("Number of GPUs for the primary choice."),
             gpu_priorities: z
                 .array(z.object({
@@ -1964,29 +2126,11 @@ create (1-5 choices), and the queue itself stays opt-in.`,
             max_price_hour_cents: priceCapSchema(true),
             storage_gb: z.number().int().min(1).max(10000).optional(),
             num_checkpoints: z.number().int().min(1).max(100).optional(),
-            epochs: z.number().positive().max(1000).optional().describe("Number of training epochs."),
-            learning_rate: z.number().positive().max(1).optional().describe("Learning rate."),
-            batch_size: z.number().int().min(1).max(65536).optional().describe("Per-device train batch size."),
-            gradient_accumulation_steps: z.number().int().min(1).max(65536).optional(),
-            max_seq_length: trainingSeqLengthSchema(),
-            lora_rank: z.number().int().min(1).max(4096).optional(),
-            lora_alpha: z.number().positive().max(1_000_000).optional(),
-            warmup_ratio: z.number().min(0).max(1).optional(),
-            weight_decay: z.number().min(0).max(10).optional(),
-            scheduler: z
-                .enum(["linear", "cosine", "cosine_with_restarts", "polynomial", "constant", "constant_with_warmup"])
-                .optional()
-                .describe("Learning-rate scheduler."),
-            job_name: z.string().max(255).optional(),
-            eval_split_ratio: z.number().min(0).max(0.99).optional(),
-            early_stopping_patience: z.number().int().min(0).max(20).optional()
-                .describe("Stop after N evaluations without a better validation loss (0 = off; default 3 when eval_split_ratio is set). The best checkpoint is always saved."),
-            overlong_policy: z.enum(["truncate", "drop"]).optional()
-                .describe("Samples longer than max_seq_length: 'truncate' keeps the last tokens so the answer is trained (default); 'drop' skips them."),
             integration_id: z.string().optional(),
             network_volume_id: z.string().optional(),
-            cache_dataset: z.boolean().optional(),
             dataset_mixing: z.enum(["shuffle", "sequential", "interleave"]).optional(),
+            mixing: datasetMixingSchema.optional().describe("Composition plan. Dataset IDs define source order and weight positions; default seed is 42. The source pins, plan and checksum are retained for metadata-only resume."),
+            ...trainingConfigurationSchema,
             config: z.record(z.string(), z.unknown()).optional().describe("Additional Run BiOS training configuration fields."),
         }, async (params) => {
             await assertModelHosted(params.model, "create_training_job");
@@ -2028,7 +2172,7 @@ create (1-5 choices), and the queue itself stays opt-in.`,
     /* ══════════════════════════════════════════════════════════════════════════ */
     /*  TOOL: get_training_metrics                                              */
     /* ══════════════════════════════════════════════════════════════════════════ */
-    server.tool("get_training_metrics", "Get training metrics history for a job: training loss over time, eval loss, learning rate schedule, and evaluation results. Use this to check if training is progressing well (loss should decrease) or if the model is overfitting (eval loss increasing while train loss decreases).", {
+    server.tool("get_training_metrics", "Get training metrics history for a job: training loss over time, eval loss, learning rate schedule, and evaluation results, plus resource_metrics (the latest worker snapshot: per-GPU memory and utilization, system RAM, CPU when the worker reports it, disk). Fields the worker did not report are null, never zero. Use this to check if training is progressing well (loss should decrease), if the model is overfitting (eval loss increasing while train loss decreases), or whether memory headroom allows a larger batch.", {
         job_id: z.string().describe("Training job ID"),
     }, async ({ job_id }) => {
         validateId(job_id, "job_id");
@@ -2234,6 +2378,303 @@ create (1-5 choices), and the queue itself stays opt-in.`,
             return json(data);
         });
     }
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    /*  TOOLS: Conscious Loop                                                    */
+    /*                                                                           */
+    /*  Capture what a model was asked and answered, record whether it was right, */
+    /*  and curate the result into training data.                                 */
+    /*                                                                           */
+    /*  Every one of these is workspace-scoped and needs an API key carrying      */
+    /*  loop:read or loop:write. Those scopes are absent from the Read Only       */
+    /*  preset on purpose: what they return is raw prompts and completions, not   */
+    /*  catalog metadata, so a key holds them only by an explicit grant.          */
+    /*                                                                           */
+    /*  NOTHING IS RECORDED until loop_set_capture turns a source on. An agent    */
+    /*  calling loop_capture_trace against a source nobody enabled gets           */
+    /*  captured:false back, not an error and not a stored conversation.          */
+    /* ══════════════════════════════════════════════════════════════════════════ */
+    server.tool("loop_set_capture", "Turn conversation capture on or off for one source, and choose how long recordings are kept. THIS IS THE CONSENT DECISION the rest of the Conscious Loop rests on: until it is made, nothing is recorded. The source is a deployment id for models served on Run BiOS, or any label you choose for traffic served elsewhere (another provider, your own servers, an agent framework). Recordings are deleted automatically once the retention window passes.", {
+        source: z.string().describe("The source to record: a Run BiOS deployment id, or a label you choose for traffic served elsewhere (e.g. 'my-support-agent')"),
+        enabled: z.boolean().describe("true starts recording new conversations from this source; false stops. Turning it off never deletes what is already stored."),
+        retention_days: z.number().int().optional().describe("How many days recordings are kept before automatic deletion (1-3650, default 30)"),
+        sample_rate: z.number().optional().describe("Record only a fraction of conversations, 0 to 1. Deterministic per conversation, so a multi-turn exchange is never split in half."),
+    }, async ({ source, enabled, retention_days, sample_rate }) => {
+        const data = await client.api(`/api/loop/configs/${encodeURIComponent(source)}`, {
+            method: "PUT",
+            body: { enabled, retention_days, sample_rate },
+        });
+        return json(data);
+    });
+    server.tool("loop_capture_trace", "Record one exchange — what the model was asked and what it answered — so it can be reviewed and later trained on. Works whoever served the model. Pass tool_calls and tools when the turn invoked a function: without them a tool-using exchange trains the model to reply in prose exactly where it should have called something. The returned trace_id is Run BiOS's own; if you pass request_id, replaying it returns the same trace instead of storing a duplicate. If the source has not been enabled with loop_set_capture this returns captured:false and stores nothing.", {
+        source: z.string().describe("The source being recorded — must already be enabled with loop_set_capture"),
+        model: z.string().describe("The model that produced the answer, e.g. 'gpt-4o' or a Run BiOS model id"),
+        messages: z.array(z.object({
+            role: z.string().describe("system | user | assistant | tool"),
+            content: z.string().optional(),
+            tool_call_id: z.string().optional().describe("On a tool result turn, the call it answers"),
+            name: z.string().optional().describe("On a tool result turn, the tool's name"),
+        })).describe("The conversation as it was sent to the model"),
+        completion: z.string().optional().describe("The assistant's answer text. Omit when the answer was purely a tool call."),
+        tool_calls: z.array(z.object({
+            id: z.string().optional(),
+            type: z.string().optional(),
+            function: z.object({
+                name: z.string(),
+                arguments: z.string().describe("JSON-encoded string, as the chat-completions wire format uses"),
+            }),
+        })).optional().describe("What the answering turn invoked, if anything"),
+        tools: z.any().optional().describe("The tool schema the model was offered. Training tool use without it teaches the model to invent function names."),
+        conversation_id: z.string().optional().describe("Ties the turns of one conversation together"),
+        request_id: z.string().optional().describe("Your own idempotency handle — replaying it will not create a second trace"),
+        latency_ms: z.number().int().optional(),
+    }, async ({ source, model, messages, completion, tool_calls, tools, conversation_id, request_id, latency_ms }) => {
+        const data = await client.api("/api/loop/traces", {
+            method: "POST",
+            body: {
+                deployment_id: source, model, messages,
+                completion: completion ?? "",
+                tool_calls, tools, conversation_id, request_id, latency_ms,
+            },
+        });
+        return json(data);
+    });
+    server.tool("loop_import_rows", "Bring data the user ALREADY HAS into the loop — an export from another provider, a spreadsheet of past answers, a set of preference pairs. This does NOT create a training set: it creates conversations, in the same place captured ones live, subject to the same review, rules, judges and labels. A row becomes trainable when something says it is good, never because it arrived in a file. Each row is read for what it is: a prompt/chosen/rejected triple becomes a preference pair; an answer plus a yes-or-no becomes a thumbs verdict; a question and an answer waits for review; a question with no answer waits for an answer; a paragraph of prose is refused, because it is not a conversation. A verdict that arrives with the file is kept, but recorded as having come from the user's earlier process rather than from a reviewer here. Read the by_shape and refused_why counts back to the user: a file that was silently the wrong shape shows up there rather than merely importing fewer rows than expected.", {
+        source: z.string().describe("Where this came from, e.g. 'zendesk-2026' or 'gpt4-history'. Required, and becomes the source every imported conversation is filed under — do not use a generic word like 'import', because that produces a corpus nobody can slice later."),
+        rows: z.array(z.record(z.string(), z.any())).describe("The rows themselves, already parsed. At most 5000 per call: the call is synchronous. Pass each row in whatever shape it already has rather than reshaping it — the shape is how the server decides whether it carries a verdict."),
+        model: z.string().optional().describe("Which model produced these answers, when the rows do not say per-row"),
+        labels: z.array(z.string()).optional().describe("Applied to every row. Importing a dump is usually the moment somebody knows what all of it is, and labels are what make a slice of it selectable later."),
+        attributes: z.record(z.string(), z.string()).optional().describe("Key/value facts applied to every row, e.g. {\"category\": \"billing\"}"),
+    }, async ({ source, rows, model, labels, attributes }) => {
+        const data = await client.api("/api/loop/import", {
+            method: "POST",
+            body: { source, rows, model, labels, attributes },
+        });
+        return json(data);
+    });
+    server.tool("loop_list_traces", "List recorded conversations for this workspace, newest first. Use signalled_only to see just the ones that already carry a verdict, which is what a training set can actually be built from.", {
+        source: z.string().optional().describe("Only conversations from this source"),
+        conversation_id: z.string().optional(),
+        label: z.string().optional().describe("Only conversations carrying this bare tag. A tag with children matches them too."),
+        attributes: z.record(z.string(), z.string()).optional().describe("Only conversations matching every one of these dimensions, e.g. {\"category\":\"billing\",\"language\":\"es\"}"),
+        unlabelled: z.boolean().optional().describe("Only the conversations nobody has described yet — the pile worth looking at before deciding what the dimensions should be"),
+        signalled_only: z.boolean().optional().describe("Only conversations that already have feedback on them"),
+        limit: z.number().int().optional().describe("Default 50, maximum 200"),
+        offset: z.number().int().optional(),
+    }, async ({ source, conversation_id, label, attributes, unlabelled, signalled_only, limit, offset }) => {
+        const attrs = Object.entries(attributes ?? {})
+            .filter(([k, v]) => k && v)
+            .map(([k, v]) => `${k}:${v}`);
+        const data = await client.api("/api/loop/traces", {
+            params: {
+                deployment_id: source,
+                conversation_id,
+                label,
+                attr: attrs.length ? attrs : undefined,
+                unlabelled: unlabelled ? "true" : undefined,
+                signalled: signalled_only ? "true" : undefined,
+                limit: limit?.toString(),
+                offset: offset?.toString(),
+            },
+        });
+        return json(data);
+    });
+    server.tool("loop_get_trace", "Read one recorded conversation in full, with every verdict anyone has recorded on it. Anything that looked like a credential or a personal detail was removed before it was stored, and redaction_report says what.", { trace_id: z.string().describe("The trace id returned by loop_capture_trace or loop_list_traces") }, async ({ trace_id }) => {
+        const data = await client.api(`/api/loop/traces/${encodeURIComponent(trace_id)}`);
+        return json(data);
+    });
+    server.tool("loop_add_signal", "Record a verdict on a conversation: was the answer right? Feedback is APPEND-ONLY — a second verdict does not replace the first, because two reviewers disagreeing is information worth keeping.\n\nWHICH VERDICT TO USE, because they train different things:\n• accepted (a thumbs up) — the answer was good. It becomes an example to learn from.\n• rejected (a thumbs down) — it was wrong and you have nothing better. This REMOVES the answer from training rather than teaching anything; prefer edited whenever you know the better answer.\n• edited — the model was WRONG and here is what it should have said. The most valuable single action: it produces both halves of a preference pair, so the model learns your answer and learns to avoid its own.\n• gold — the REFERENCE answer for this question, recorded whatever the model happened to say. Unlike edited it asserts nothing about the model, so if it matches what was said no preference is invented — but it still trains SFT, and it stands in as the GRPO reference when no separate ground_truth was given. It is the most reusable feedback there is.\n• scored — a number, with ground_truth when the answer is checkable.", {
+        trace_id: z.string(),
+        verdict: z.enum(["accepted", "rejected", "edited", "scored", "gold"]).describe("accepted = thumbs up; rejected = thumbs down with nothing better to offer; edited = the model was wrong and you wrote the better answer; gold = the reference answer for this question regardless of what the model said; scored = a number or checkable fact"),
+        source: z.enum(["human", "verifier", "judge", "behavioural"]).optional().describe("Who judged. A human outranks a verifier, a verifier outranks a judge, a judge outranks a behavioural hint. Default human."),
+        correction: z.string().optional().describe("REQUIRED when verdict is 'edited' (the answer it should have given) or 'gold' (the reference answer for this question)"),
+        score: z.number().optional().describe("REQUIRED when verdict is 'scored'"),
+        ground_truth: z.string().optional().describe("The value or fact the answer can be checked against"),
+        reason: z.string().optional().describe("Why, in your own words"),
+        author: z.string().optional(),
+    }, async ({ trace_id, verdict, source, correction, score, ground_truth, reason, author }) => {
+        const data = await client.api(`/api/loop/traces/${encodeURIComponent(trace_id)}/signals`, {
+            method: "POST",
+            body: { verdict, source: source ?? "human", correction, score, ground_truth, reason, author },
+        });
+        return json(data);
+    });
+    server.tool("loop_add_candidate", "Submit an ALTERNATIVE answer to a prompt that was already recorded, and score it. This is how preference training scales without a person writing every answer: sample the model several times for the same prompt, score each sample, and a DPO pair falls out automatically — the best-scoring sample becomes 'chosen' and the worst becomes 'rejected'. Point a stronger model at the prompt instead and the same mechanism does distillation. SCORE EVERY CANDIDATE: an unscored alternative cannot pair, because it says nothing about which answer is preferred. A human correction recorded with loop_add_signal always outranks any score you submit here.", {
+        trace_id: z.string().describe("The recorded conversation this is an alternative answer to"),
+        completion: z.string().optional().describe("The alternative answer's text"),
+        tool_calls: z.array(z.object({
+            id: z.string().optional(),
+            type: z.string().optional(),
+            function: z.object({ name: z.string(), arguments: z.string() }),
+        })).optional().describe("When the alternative was itself a tool call"),
+        model: z.string().optional().describe("Which model produced this alternative — the teacher, when distilling"),
+        score: z.number().optional().describe("How good it is. Higher is better. Required for the candidate to take part in a pair."),
+        score_source: z.enum(["human", "verifier", "judge", "behavioural"]).optional().describe("What produced the score. Required whenever a score is given."),
+        reason: z.string().optional(),
+    }, async ({ trace_id, completion, tool_calls, model, score, score_source, reason }) => {
+        const data = await client.api(`/api/loop/traces/${encodeURIComponent(trace_id)}/candidates`, {
+            method: "POST",
+            body: { completion: completion ?? "", tool_calls, model, score, score_source, reason },
+        });
+        return json(data);
+    });
+    server.tool("loop_list_candidates", "Read every alternative answer recorded for one prompt, with its score and what produced that score. Use this to see whether sampling has produced a spread worth training on — if every sample scored the same, the reward function cannot separate them and no pair will be built.", { trace_id: z.string() }, async ({ trace_id }) => {
+        const data = await client.api(`/api/loop/traces/${encodeURIComponent(trace_id)}/candidates`);
+        return json(data);
+    });
+    server.tool("loop_label_trace", "Label a recorded conversation so it can be selected later. An average over everything is the least useful thing to train on — a model weak at refunds is fixed with refund examples, and you can only select those if the conversation was labelled when it arrived. A label may name a PARENT, which makes a master group: labelling something 'refunds' with parent 'billing' makes it selectable as either, and selecting 'billing' later gathers every child without anybody maintaining a list of them. Labels are lowercased and trimmed, so 'Refunds' and 'refunds' are one label.", {
+        trace_id: z.string(),
+        labels: z.array(z.string()).optional().describe("Bare tags, e.g. ['refunds','escalated']. Lowercase letters, digits, dot, dash or underscore."),
+        attributes: z.record(z.string(), z.string()).optional().describe("NAMED DIMENSIONS, e.g. {\"category\":\"billing\",\"task\":\"refund-handling\",\"language\":\"es\"}. This is what lets one captured corpus become a different dataset for every task somebody trains for: filters on different dimensions AND together, and a dimension is matched EXACTLY within its key, so source=support never matches team=support. Setting one dimension leaves the others untouched, so correcting a mistake needs no delete first."),
+        parent: z.string().optional().describe("The master group these belong to, e.g. 'billing'"),
+    }, async ({ trace_id, labels, attributes, parent }) => {
+        const data = await client.api(`/api/loop/traces/${encodeURIComponent(trace_id)}/labels`, {
+            method: "POST", body: { labels, attributes, parent },
+        });
+        return json(data);
+    });
+    server.tool("loop_remove_label", "Remove one label from a conversation. The counterpart to loop_label_trace, which until now had none — an agent could label something and then had no way to correct it. 'key' names the dimension; leave it out for a bare tag, which is what a plain name has always been.", {
+        trace_id: z.string(),
+        label: z.string().describe("The value to remove, e.g. 'refunds' or 'billing'"),
+        key: z.string().optional().describe("The dimension it belongs to, e.g. 'category'. Omit for a bare tag."),
+    }, async ({ trace_id, label, key }) => {
+        const qs = key ? `?key=${encodeURIComponent(key)}` : "";
+        const data = await client.api(`/api/loop/traces/${encodeURIComponent(trace_id)}/labels/${encodeURIComponent(label)}${qs}`, { method: "DELETE" });
+        return json(data);
+    });
+    server.tool("loop_list_labels", "Every label in this workspace with how many conversations carry it. Use it to see where the corpus actually is before choosing a slice to train on — and to discover the master groups, since a parent may have no conversations labelled with it directly.", {}, async () => json(await client.api("/api/loop/labels")));
+    server.tool("loop_create_judge", "Write a RUBRIC a model applies to answers nobody has time to read. A grader is a rule — deterministic, cheap, and blind to anything it was not told to look for; a judge is instructions in your own words, and it is the only thing that can answer 'was this answer actually helpful'. Score several things SEPARATELY: 'helpful but wrong' is not expressible in one number, and an average that hides it is worse than no score. The rubric also becomes a REWARD FUNCTION for GRPO — a prompt with a rubric attached is trainable even though no string the answer has to equal exists, which is most real work.", {
+        name: z.string().describe("What this judge is for, e.g. 'Billing tone'"),
+        instructions: z.string().describe("What makes an answer good here, in your own words"),
+        dimensions: z.array(z.object({
+            key: z.string().describe("Lowercase name, e.g. 'accuracy'"),
+            description: z.string().optional().describe("What that dimension means"),
+        })).describe("What to score, separately. At most 12."),
+        label: z.string().optional().describe("Only judge this slice. A parent label gathers its children."),
+        deployment_id: z.string().optional().describe("Only judge conversations from this source"),
+        sample: z.number().optional().describe("At most this many conversations per run"),
+        only_unscored: z.boolean().optional().describe("Skip conversations a judge has already scored"),
+        model: z.string().optional().describe("Which model you intend to judge with, recorded so two runs are comparable"),
+        write_gold: z.boolean().optional().describe("Let the judge write the answer that SHOULD have been given. Off by default: training on a model-written reference is distillation, and that is a decision you make deliberately."),
+    }, async ({ name, instructions, dimensions, label, deployment_id, sample, only_unscored, model, write_gold }) => {
+        const data = await client.api("/api/loop/judges", {
+            method: "POST",
+            body: {
+                name, instructions, dimensions, model, write_gold,
+                selection: { label, deployment_id, sample, only_unscored },
+            },
+        });
+        return json(data);
+    });
+    server.tool("loop_list_judges", "Every rubric this workspace has written, with what it scores and which slice it covers.", {}, async () => json(await client.api("/api/loop/judges")));
+    server.tool("loop_start_judge_run", "Open a run of one judge: select the conversations NOW and freeze the rubric onto them. The selection is fixed at this moment on purpose — a run whose selection is a live query silently grows as conversations arrive, so 'we scored the refunds slice' becomes a claim about a set that no longer exists. Follow with loop_take_judge_work.", {
+        judge_id: z.string(),
+        limit: z.number().optional().describe("Cap this pass below the judge's own sample, for a cheap look first"),
+    }, async ({ judge_id, limit }) => {
+        const data = await client.api(`/api/loop/judges/${encodeURIComponent(judge_id)}/runs`, {
+            method: "POST", body: limit ? { limit } : {},
+        });
+        return json(data);
+    });
+    server.tool("loop_take_judge_work", "Take the next conversations to score. Each item arrives with a 'prompt' ALREADY RENDERED — send that text to a model as-is and reply with the JSON it asks for. Do not assemble your own: two callers that build the prompt differently are not applying one rubric. YOU run the model here on purpose; the service that stores these conversations holds no credentials to any model, which is most of the reason it is safe to store them there. Nothing is marked taken, so asking again returns the same items.", { run_id: z.string(), limit: z.number().optional() }, async ({ run_id, limit }) => {
+        const qs = limit ? `?limit=${limit}` : "";
+        return json(await client.api(`/api/loop/runs/${encodeURIComponent(run_id)}/work${qs}`));
+    });
+    server.tool("loop_post_judge_verdicts", "Hand the scores back. Each verdict carries one score per dimension the rubric asked for, each between 0 and 1, plus a reason — a score nobody can argue with is one nobody can correct. Scoring something the rubric never asked for is REFUSED rather than averaged in, and reported in 'rejected'. If you could not score an item, send it with 'error' instead of dropping it: a run that quietly shrinks is one whose coverage nobody can state.", {
+        run_id: z.string(),
+        verdicts: z.array(z.object({
+            trace_id: z.string(),
+            scores: z.record(z.string(), z.number()).optional().describe("One score per dimension, 0 to 1"),
+            overall: z.number().optional().describe("Your own combination. Left out, the plain mean is used."),
+            reason: z.string().optional().describe("Why, in a sentence or two"),
+            gold: z.string().optional().describe("The answer that should have been given. Stored only if the judge has write_gold."),
+            error: z.string().optional().describe("Mark an item you could not score"),
+        })),
+        finish: z.boolean().optional().describe("Close the run even with items still pending"),
+    }, async ({ run_id, verdicts, finish }) => {
+        const data = await client.api(`/api/loop/runs/${encodeURIComponent(run_id)}/verdicts`, {
+            method: "POST", body: { verdicts, finish: finish ?? false },
+        });
+        return json(data);
+    });
+    server.tool("loop_create_grader", "Write a rule that scores answers automatically, with no person reading them. Human review is the most trustworthy feedback and the least available; a grader is written once and applied to every answer afterwards. Every kind is DETERMINISTIC — no model call — which is why a verifier's score outranks a judge's when they disagree: it cannot be flattered and it cannot drift between runs. 'weight' is the multiplier: a criterion that matters twice as much gets twice the weight, and the combined score is the weighted mean over the rules that actually applied. CAUTION WHEN WRITING A SET: a rule made only of 'forbidden' phrases is satisfied VACUOUSLY by an answer that says nothing, so pair it with a required phrase or you are rewarding silence.", {
+        name: z.string().describe("What this rule checks, in your words"),
+        kind: z.enum(["exact_match", "contains", "regex", "json_valid", "numeric", "tool_called"]),
+        expected: z.string().optional().describe("For exact_match and numeric: the value to compare against"),
+        required: z.array(z.string()).optional().describe("For contains: every phrase that must appear"),
+        forbidden: z.array(z.string()).optional().describe("For contains: phrases that must not appear"),
+        pattern: z.string().optional().describe("For regex: the pattern the answer must match"),
+        keys: z.array(z.string()).optional().describe("For json_valid: keys the parsed answer must carry"),
+        tolerance: z.number().optional().describe("For numeric: how far from expected still counts"),
+        function_name: z.string().optional().describe("For tool_called: the function that must have been invoked"),
+        case_sensitive: z.boolean().optional().describe("Turn off the default case and whitespace normalisation"),
+        label: z.string().optional().describe("Aim the rule at one slice. A master group covers its children. Outside that slice the rule is NOT APPLIED rather than failed, so it stays out of the score entirely. Without this, a rule like 'must name the order number' marks down every billing answer for not mentioning a shipment."),
+        weight: z.number().optional().describe("The multiplier, greater than zero. Default 1."),
+        source: z.string().optional().describe("Limit the rule to one capture source. Omit to apply it everywhere."),
+    }, async (input) => {
+        const data = await client.api("/api/loop/graders", {
+            method: "POST",
+            body: {
+                name: input.name, kind: input.kind, weight: input.weight,
+                deployment_id: input.source, label: input.label,
+                config: {
+                    expected: input.expected, required: input.required, forbidden: input.forbidden,
+                    pattern: input.pattern, keys: input.keys, tolerance: input.tolerance,
+                    function: input.function_name, case_sensitive: input.case_sensitive,
+                },
+            },
+        });
+        return json(data);
+    });
+    server.tool("loop_list_graders", "Every scoring rule this workspace has written, with its weight and whether it is enabled.", {}, async () => json(await client.api("/api/loop/graders")));
+    server.tool("loop_grade_trace", "Apply this workspace's rules to one recorded answer AND to every alternative sampled for it, in one pass. That pairing is the point: scoring only the original gives a verdict, while scoring the samples too gives a preference pair — so sampling the model and then calling this produces DPO training data with nobody reading anything. A run where NO rule could apply writes nothing at all: no verdict, no scores. Recording a zero that no rule produced would poison the training data with a judgement nobody reached, so you get applied:0 back instead. Read the per-rule 'detail' to see which criterion an answer failed; a single combined number tells you nothing about what to fix.", { trace_id: z.string() }, async ({ trace_id }) => {
+        const data = await client.api(`/api/loop/traces/${encodeURIComponent(trace_id)}/grade`, {
+            method: "POST", body: {},
+        });
+        return json(data);
+    });
+    server.tool("loop_build_dataset", "Turn the recorded feedback into a training set. The three methods need genuinely different feedback, so a set built for one CANNOT be reshaped into another: 'sft' uses answers marked right and answers that were rewritten; 'dpo' needs answers that were REWRITTEN, so a better and a worse version of the same reply exist; 'grpo' needs answers with a checkable ground truth OR a judge rubric; 'kto' needs only a yes or a no on an answer, INCLUDING a bare thumbs-down that trains nothing under the other three — which is why it usually has the most rows. The result always reports rejected_counts — why rows were left out — so a small set can be explained rather than guessed at. holdout_percent holds back the most RECENT work rather than a random slice, so an evaluation measures whether the model generalised instead of memorising the same week.", {
+        name: z.string().describe("A name you will recognise later"),
+        method: z.enum(["sft", "dpo", "grpo", "kto"]),
+        attributes: z.record(z.string(), z.string()).optional().describe("Narrow to named dimensions, ANDed together: {\"category\":\"billing\",\"language\":\"es\"}. This is how ONE captured corpus becomes a DIFFERENT dataset for every task — nothing is re-labelled to do it."),
+        unlabelled: z.boolean().optional().describe("Only the conversations nobody has described yet"),
+        source: z.string().optional().describe("Only conversations from this source"),
+        label: z.string().optional().describe("Only conversations carrying this label. A label with children selects them too, so 'billing' picks up 'refunds'."),
+        from: z.string().optional().describe("RFC3339 timestamp, earliest conversation to consider"),
+        to: z.string().optional().describe("RFC3339 timestamp, latest conversation to consider"),
+        sample: z.number().int().optional().describe("Take this many at random from what the filters matched. Applied before the holdout split, so the held-back slice is still the newest of what was chosen."),
+        holdout_percent: z.number().int().optional().describe("0-50. Holds back the newest slice for evaluation."),
+    }, async ({ name, method, source, label, attributes, unlabelled, from, to, sample, holdout_percent }) => {
+        const data = await client.api("/api/loop/datasets", {
+            method: "POST",
+            body: {
+                name, method, deployment_id: source, label, attributes, unlabelled,
+                from, to, sample, holdout_percent,
+            },
+        });
+        return json(data);
+    });
+    server.tool("loop_list_datasets", "List the training sets built in this workspace, each with how many rows it kept, how many conversations were considered, and why the rest were left out.", {
+        method: z.enum(["sft", "dpo", "grpo", "kto"]).optional(),
+        limit: z.number().int().optional(),
+    }, async ({ method, limit }) => {
+        const data = await client.api("/api/loop/datasets", {
+            params: { method, limit: limit?.toString() },
+        });
+        return json(data);
+    });
+    server.tool("loop_preview_dataset", "Read the actual training rows in a set before anyone spends money training on it. Each row carries the address of the conversation it was built from, so a suspicious row can be traced back to what produced it.", {
+        dataset_id: z.string(),
+        limit: z.number().int().optional().describe("Default 50, maximum 200"),
+    }, async ({ dataset_id, limit }) => {
+        const data = await client.api(`/api/loop/datasets/${encodeURIComponent(dataset_id)}/items`, {
+            params: { limit: limit?.toString() },
+        });
+        return json(data);
+    });
+    server.tool("loop_stats", "How much has been recorded in this workspace, how much of it has been reviewed, and how many rows each training method could use right now. The 'ready' figures are upper bounds: repeated questions are folded into one row when a set is built, so the finished count can be lower.", {}, async () => {
+        const data = await client.api("/api/loop/stats");
+        return json(data);
+    });
     return mcp;
 }
 //# sourceMappingURL=server.js.map