bailian-cli-core 1.4.2 → 1.5.0

package/dist/index.d.mts

@@ -625,6 +625,10 @@ declare function parseConfigFile(raw: unknown): ConfigFile;
 interface Config {
   clientName?: string;
   clientVersion?: string;
+  /** Product binary name (e.g. "bl", "rag"), injected by createCli for command-facing output. */
+  binName?: string;
+  /** npm package name for self-update (e.g. "bailian-cli", "bailian-cli-rag"), injected by createCli. */
+  npmPackage?: string;
   apiKey?: string;
   /** `DASHSCOPE_ACCESS_TOKEN` env (explicit override). */
   accessTokenEnv?: string;
@@ -906,6 +910,886 @@ declare function resolveFileUrl(input: string, apiKey: string, model: string, op
   signal?: AbortSignal;
 }): Promise<string>;
 //#endregion
+//#region src/dataset/types.d.ts
+/**
+ * Dataset API types.
+ *
+ * Maps DashScope `/api/v1/files` responses. The same endpoint backs every
+ * dataset purpose the platform supports today (fine-tune training,
+ * evaluation, etc.) — these types are deliberately purpose-agnostic so new
+ * purposes can be plugged in without schema changes.
+ */
+/** A single uploaded dataset file as returned by the platform. */
+interface DatasetFile {
+  /** File ID — the only stable handle for downstream consumers. */
+  file_id: string;
+  /** Original filename uploaded by the user. */
+  name: string;
+  /** Bytes. */
+  size?: number;
+  /** Content hash (server-computed). */
+  md5?: string;
+  /** Free-form purpose tag, e.g. "fine-tune", "evaluation". */
+  purpose?: string;
+  /** Optional internal/external URL (kept for parity with the API). */
+  url?: string;
+  /** Free-form description if the user supplied one at upload time. */
+  description?: string;
+  /** Server-side creation timestamp (string, format per platform). */
+  gmt_create?: string;
+}
+/** GET /api/v1/files response. */
+interface DatasetListResponse {
+  request_id?: string;
+  data?: {
+    files?: DatasetFile[];
+    total?: number;
+    page_no?: number;
+    page_size?: number;
+  };
+}
+/** GET /api/v1/files/{file_id} response. */
+interface DatasetGetResponse {
+  request_id?: string;
+  data?: DatasetFile;
+}
+/**
+ * POST /compatible-mode/v1/files response (OpenAI-compatible).
+ *
+ * Flat shape — there is no `data` envelope on success. `id` is the file handle
+ * to pass to fine-tune jobs; `purpose` is echoed back so callers can confirm
+ * it landed. On business-level failure (HTTP 200 + `data.failed_uploads`)
+ * `id` is absent and `data.failed_uploads[]` carries the platform's reason.
+ */
+interface DatasetUploadResponse {
+  request_id?: string;
+  /** File ID — the handle returned to callers (e.g. `file-ft-…`). */
+  id?: string;
+  /** Always `"file"` for this endpoint. */
+  object?: string;
+  /** Bytes. */
+  bytes?: number;
+  /** Original filename uploaded by the user. */
+  filename?: string;
+  /** Purpose tag, e.g. `"fine-tune"`, `"file-extract"`, `"batch"`. */
+  purpose?: string;
+  /** Platform processing state, e.g. `"processed"`. */
+  status?: string;
+  /** Creation timestamp (Unix seconds). */
+  created_at?: number;
+  /**
+   * Failure envelope: HTTP 200 + business failure. When present the upload
+   * did NOT produce a file_id; callers must treat this as an error. Common
+   * cause: server-side schema rejection (e.g. malformed JSONL slipped past
+   * the local pre-flight).
+   */
+  data?: {
+    failed_uploads?: Array<{
+      code?: string;
+      message?: string;
+      file_name?: string;
+    }>;
+  };
+}
+/** DELETE /api/v1/files/{file_id} response. */
+interface DatasetDeleteResponse {
+  request_id?: string;
+  data?: {
+    deleted?: boolean;
+    file_id?: string;
+  };
+}
+//#endregion
+//#region src/dataset/api.d.ts
+interface DatasetUploadParams {
+  filePath: string;
+  /**
+   * Purpose tag forwarded to the platform. Defaults to "fine-tune" because
+   * the API requires the field, but callers should set this explicitly when
+   * uploading evaluation or other dataset kinds.
+   */
+  purpose?: string;
+  signal?: AbortSignal;
+}
+/**
+ * POST /compatible-mode/v1/files (multipart/form-data)
+ *
+ * Streams the file from disk so we don't buffer 300MB into memory. Node's
+ * `fetch` accepts a `Blob` produced from a Readable stream via `Response`'s
+ * body shim, but the simplest portable approach (and the one used in
+ * `files/upload.ts`) is to wrap the buffer in a Blob. Here we use `Blob`
+ * with a stream-backed lazy `arrayBuffer()` for >50MB files via
+ * `Response`'s helper to avoid the buffer doubling. Fall back to readFileSync
+ * for small files where streaming overhead isn't worth it.
+ */
+declare function uploadDataset(config: Config, params: DatasetUploadParams): Promise<DatasetFile>;
+interface DatasetListParams {
+  pageNo?: number;
+  pageSize?: number;
+  purpose?: string;
+  signal?: AbortSignal;
+}
+/** GET /api/v1/files */
+declare function listDatasets(config: Config, params?: DatasetListParams): Promise<DatasetListResponse>;
+/** GET /api/v1/files/{file_id} */
+declare function getDataset(config: Config, fileId: string, signal?: AbortSignal): Promise<DatasetGetResponse>;
+/** DELETE /api/v1/files/{file_id} */
+declare function deleteDataset(config: Config, fileId: string, signal?: AbortSignal): Promise<DatasetDeleteResponse>;
+//#endregion
+//#region src/dataset/validate/types.d.ts
+/**
+ * Validator types — the registry contract that every format adheres to.
+ *
+ * Design (Plan B from the architecture review):
+ *  - A `ValidatorSpec` is a plain object, not a class. Adding a new format =
+ *    one new file exporting one constant + one line in the registry.
+ *  - Common pre-flight checks (existence, size, extension) live in `common.ts`
+ *    and are applied by `validateDataset` before the format-specific validator
+ *    runs, so individual specs only handle structural concerns.
+ */
+interface ValidateOpts {
+  /** When true, validators should do exhaustive checks (e.g. parse every line). */
+  fullValidate?: boolean;
+  /** Optional max bytes override (defaults to 300MB at the registry level). */
+  maxBytes?: number;
+  /** Optional abort signal for long-running scans. */
+  signal?: AbortSignal;
+  /**
+   * Record-schema selector for formats that carry more than one schema under
+   * the same extension. Today only the `.jsonl` ChatML family honors it:
+   *   - `"chatml"` — `{messages: [...]}` (SFT). `chosen`/`rejected` ignored.
+   *   - `"dpo"`    — `{messages: [...], chosen: {role,content}, rejected: {...}}`.
+   *                   Every record MUST carry `chosen` + `rejected`.
+   *   - `"cpt"`    — `{text: "..."}` (continual pre-training). Raw text only,
+   *                   no `messages[]`.
+   *   - `undefined` — auto-detect per record: a record with `chosen` or
+   *                   `rejected` is validated as DPO, one with `text` (and no
+   *                   `messages`) as CPT, otherwise as ChatML.
+   * `finetune create` sets this from `--training-type` (dpo* → "dpo",
+   * cpt → "cpt") so a malformed dataset fails at validate time, not on the
+   * platform ten minutes in.
+   */
+  schema?: DatasetSchema;
+}
+/** The schemas a `.jsonl` record can be validated against. */
+type DatasetSchema = "chatml" | "dpo" | "cpt";
+type ValidationSeverity = "error" | "warning";
+interface ValidationIssue {
+  severity: ValidationSeverity;
+  /** Stable machine-readable key, e.g. "EMPTY_FILE", "MALFORMED_JSON". */
+  code: string;
+  /** Human-readable message. */
+  message: string;
+  /** 1-indexed line number for line-oriented formats. */
+  line?: number;
+  /** Optional path inside the offending row, e.g. "messages[2].role". */
+  path?: string;
+}
+interface ValidationStats {
+  /** Total observed records (rows / samples / messages, depending on format). */
+  totalRecords?: number;
+  /** Records actually deep-checked (sampled). */
+  sampledRecords?: number;
+  /** Total file bytes. */
+  bytes?: number;
+  /** Wall time spent in the scan (ms). */
+  durationMs?: number;
+}
+interface ValidationResult {
+  valid: boolean;
+  format: string;
+  filePath: string;
+  errors: ValidationIssue[];
+  warnings: ValidationIssue[];
+  stats: ValidationStats;
+}
+interface ValidatorSpec {
+  /** Human-readable format identifier, e.g. "jsonl". */
+  format: string;
+  /** Lower-cased file extensions handled by this validator (include dot). */
+  extensions: string[];
+  /** Format-specific check. Pre-flight (existence/size) is applied by the registry. */
+  validate(filePath: string, opts: ValidateOpts): Promise<ValidationResult>;
+}
+//#endregion
+//#region src/dataset/validate/registry.d.ts
+/** Lookup the validator that handles a given file extension. */
+declare function pickValidator(filePath: string): ValidatorSpec;
+/** Allow tests / future plugins to inject extra validators. Idempotent. */
+declare function registerValidator(spec: ValidatorSpec): void;
+/**
+ * Top-level entry point. Applies common pre-flight (existence/size/extension)
+ * then defers to the format-specific validator.
+ */
+declare function validateDataset(filePath: string, opts?: ValidateOpts): Promise<ValidationResult>;
+/** Read-only view of the active registry — handy for tests / `--help`. */
+declare function listSupportedFormats(): {
+  format: string;
+  extensions: string[];
+}[];
+//#endregion
+//#region src/dataset/validate/common.d.ts
+/**
+ * The platform caps dataset uploads at 300MB per file. `bl dataset upload`
+ * enforces this client-side so users learn early. Update if the platform
+ * raises the cap or differentiates per-purpose limits.
+ */
+declare const MAX_DATASET_BYTES: number;
+/**
+ * Parse a `--schema` CLI value into a `DatasetSchema` (or `undefined` for
+ * auto-detect). Single source of truth for the schema vocabulary so `dataset
+ * validate`, `dataset upload`, and any future caller agree on accepted values
+ * and error wording. Throws USAGE for anything unrecognized.
+ */
+declare function parseDatasetSchemaFlag(value: string | undefined): DatasetSchema | undefined;
+//#endregion
+//#region src/dataset/validate/format.d.ts
+/**
+ * Format a single validation issue as a one-line string.
+ *
+ * Shared across every entry point that surfaces dataset validation results
+ * (`dataset validate`, `dataset upload`, `finetune create`) so the error
+ * presentation stays consistent regardless of which command ran the validator.
+ */
+declare function formatIssue(issue: ValidationIssue): string;
+//#endregion
+//#region src/finetune/types.d.ts
+/**
+ * Fine-tune job API types.
+ *
+ * Maps DashScope `/api/v1/fine-tunes` request/response shapes (snake_case
+ * preserved verbatim — callers decide how to surface fields).
+ */
+/** Hyper-parameters honored by text/thinking/vision SFT models. */
+interface FineTuneHyperParameters {
+  /** Number of training epochs. */
+  n_epochs?: number;
+  batch_size?: number;
+  /** Sent as a string to avoid JSON-number precision loss (e.g. "1.6e-5"). */
+  learning_rate?: string;
+  max_length?: number;
+  /** Train/validation split ratio when no validation file is provided. */
+  split?: number;
+  lr_scheduler_type?: string;
+  /** Future-compat: arbitrary additional fields are forwarded as-is. */
+  [k: string]: unknown;
+}
+/** POST /api/v1/fine-tunes request body. */
+interface CreateFineTuneRequest {
+  /** Base model ID, or a previously fine-tuned model ID for continued training. */
+  model: string;
+  training_file_ids: string[];
+  /**
+   * Server-supported values: `cpt | sft | efficient_sft | dpo_full | dpo_lora`.
+   *
+   * NOTE — current bailian-cli scope: `sft` (default) and `efficient_sft`.
+   * Other values are rejected by the CLI at parse time so users get an
+   * immediate error instead of a vague server-side rejection. This type
+   * stays open as `string` for forward compatibility (so adding `dpo_lora`
+   * later is a CLI-only change).
+   */
+  training_type: string;
+  validation_file_ids?: string[];
+  hyper_parameters?: FineTuneHyperParameters;
+  /** Display name for the job (optional, server generates if omitted). */
+  job_name?: string;
+  /** Output model name. Either bring your own or let the server generate one. */
+  model_name?: string;
+  /** Suffix appended by the platform; field is `finetuned_output_suffix` (NOT `suffix`). */
+  finetuned_output_suffix?: string;
+}
+/** GET /api/v1/fine-tunes/{id}/logs response. */
+interface FineTuneLogEntry {
+  /** Server-defined log line — schema varies; preserve as-is. */
+  [k: string]: unknown;
+}
+interface GetFineTuneLogsResponse {
+  request_id?: string;
+  output?: {
+    logs?: Array<FineTuneLogEntry | string>;
+    total?: number;
+    page_no?: number;
+    page_size?: number;
+    [k: string]: unknown;
+  };
+  data?: {
+    logs?: Array<FineTuneLogEntry | string>;
+    total?: number;
+    page_no?: number;
+    page_size?: number;
+    [k: string]: unknown;
+  };
+}
+/** A single checkpoint as returned by the platform. */
+interface FineTuneCheckpoint {
+  checkpoint?: string;
+  checkpoint_id?: string;
+  full_name?: string;
+  job_id?: string;
+  model_name?: string;
+  model_display_name?: string;
+  /** SUCCEEDED | PENDING | FAILED | … */
+  status?: string;
+  step?: number;
+  epoch?: number;
+  create_time?: string;
+  expire_time?: string;
+  output_model_deleted?: boolean;
+  metrics?: Record<string, unknown>;
+  [k: string]: unknown;
+}
+/**
+ * GET /api/v1/fine-tunes/{job_id}/checkpoints response.
+ *
+ * Real shape: `output` is an array of checkpoints directly (NOT wrapped in
+ * `{ checkpoints: [...] }`). The wrapped form is preserved as a fallback for
+ * older deployments.
+ */
+interface ListCheckpointsResponse {
+  request_id?: string;
+  output?: FineTuneCheckpoint[] | {
+    checkpoints?: FineTuneCheckpoint[];
+    total?: number;
+    [k: string]: unknown;
+  };
+  data?: FineTuneCheckpoint[] | {
+    checkpoints?: FineTuneCheckpoint[];
+    total?: number;
+    [k: string]: unknown;
+  };
+}
+/** GET /api/v1/fine-tunes/{job_id}/export/{checkpoint}?model_name= response. */
+interface ExportCheckpointResponse {
+  request_id?: string;
+  output?: {
+    /** Resulting deployable model name. */model_name?: string;
+    [k: string]: unknown;
+  };
+  data?: {
+    model_name?: string;
+    [k: string]: unknown;
+  };
+}
+/** POST /api/v1/fine-tunes/{id}/cancel response. */
+interface CancelFineTuneResponse {
+  request_id?: string;
+  output?: FineTuneJob;
+  data?: FineTuneJob;
+}
+/** DELETE /api/v1/fine-tunes/{id} response. */
+interface DeleteFineTuneResponse {
+  request_id?: string;
+  output?: {
+    deleted?: boolean;
+    job_id?: string;
+    [k: string]: unknown;
+  };
+  data?: {
+    deleted?: boolean;
+    job_id?: string;
+    [k: string]: unknown;
+  };
+}
+/** A single fine-tune job record as returned by the platform. */
+interface FineTuneJob {
+  job_id?: string;
+  job_name?: string;
+  model?: string;
+  base_model?: string;
+  training_type?: string;
+  /** PENDING | RUNNING | SUCCEEDED | FAILED | CANCELED */
+  status?: string;
+  finetuned_output?: string;
+  finetuned_output_suffix?: string;
+  model_name?: string;
+  training_file_ids?: string[];
+  validation_file_ids?: string[];
+  hyper_parameters?: FineTuneHyperParameters;
+  /** Server-side timestamps (DashScope uses snake_case `create_time` / `end_time`). */
+  create_time?: string;
+  end_time?: string;
+  /** Legacy field names — kept for backward compatibility with older deployments. */
+  gmt_create?: string;
+  gmt_modified?: string;
+  /** Free-form additional fields are preserved by callers. */
+  [k: string]: unknown;
+}
+/** POST /api/v1/fine-tunes response. */
+interface CreateFineTuneResponse {
+  request_id?: string;
+  /** Modern DashScope shape. */
+  output?: FineTuneJob;
+  /** Legacy shape for older platform builds. */
+  data?: FineTuneJob;
+}
+/** GET /api/v1/fine-tunes response. */
+interface ListFineTunesResponse {
+  request_id?: string;
+  output?: {
+    jobs?: FineTuneJob[];
+    total?: number;
+    page_no?: number;
+    page_size?: number;
+  };
+  data?: {
+    jobs?: FineTuneJob[];
+    total?: number;
+    page_no?: number;
+    page_size?: number;
+  };
+}
+/** GET /api/v1/fine-tunes/{job_id} response. */
+interface GetFineTuneResponse {
+  request_id?: string;
+  output?: FineTuneJob;
+  data?: FineTuneJob;
+}
+//#endregion
+//#region src/finetune/api.d.ts
+/** POST /api/v1/fine-tunes */
+declare function createFineTune(config: Config, body: CreateFineTuneRequest, signal?: AbortSignal): Promise<CreateFineTuneResponse>;
+interface ListFineTunesParams {
+  pageNo?: number;
+  pageSize?: number;
+  status?: string;
+  signal?: AbortSignal;
+}
+/** GET /api/v1/fine-tunes */
+declare function listFineTunes(config: Config, params?: ListFineTunesParams): Promise<ListFineTunesResponse>;
+/** GET /api/v1/fine-tunes/{job_id} */
+declare function getFineTune(config: Config, jobId: string, signal?: AbortSignal): Promise<GetFineTuneResponse>;
+/** POST /api/v1/fine-tunes/{job_id}/cancel */
+declare function cancelFineTune(config: Config, jobId: string, signal?: AbortSignal): Promise<CancelFineTuneResponse>;
+/** DELETE /api/v1/fine-tunes/{job_id} */
+declare function deleteFineTune(config: Config, jobId: string, signal?: AbortSignal): Promise<DeleteFineTuneResponse>;
+interface GetFineTuneLogsParams {
+  pageNo?: number;
+  pageSize?: number;
+  signal?: AbortSignal;
+}
+/** GET /api/v1/fine-tunes/{job_id}/logs */
+declare function getFineTuneLogs(config: Config, jobId: string, params?: GetFineTuneLogsParams): Promise<GetFineTuneLogsResponse>;
+/** GET /api/v1/fine-tunes/{job_id}/checkpoints */
+declare function listCheckpoints(config: Config, jobId: string, signal?: AbortSignal): Promise<ListCheckpointsResponse>;
+/**
+ * GET /api/v1/fine-tunes/{job_id}/export/{checkpoint}?model_name={name}
+ *
+ * Publishes a training checkpoint as a deployable model — required before
+ * `bl deploy create` can target it. The platform may auto-export the best
+ * checkpoint on SUCCEEDED, but explicit export is the canonical path.
+ */
+declare function exportCheckpoint(config: Config, jobId: string, checkpoint: string, modelName: string, signal?: AbortSignal): Promise<ExportCheckpointResponse>;
+//#endregion
+//#region src/finetune/capability.d.ts
+/**
+ * Training-type vocabulary exposed to users.
+ *
+ * Convention: the bare method name is **full-parameter** tuning; the `-lora`
+ * suffix is the LoRA variant. This holds for `sft` and `dpo` (both have a
+ * full + lora pair). `cpt` is the exception — the platform only supports
+ * full-parameter CPT (no `cpt-lora` exists server-side), so it has no lora
+ * sibling.
+ *
+ * Each CLI value maps 1:1 to a server `training_type`. The mapping happens at
+ * the interface boundary (request body), so the rest of the CLI never sees the
+ * raw server strings (`efficient_sft`, `dpo_full`, ...).
+ */
+declare const TRAINING_TYPE_MAP: {
+  readonly sft: {
+    readonly server: "sft";
+    readonly method: "sft";
+    readonly variant: "full";
+  };
+  readonly "sft-lora": {
+    readonly server: "efficient_sft";
+    readonly method: "sft";
+    readonly variant: "lora";
+  };
+  readonly dpo: {
+    readonly server: "dpo_full";
+    readonly method: "dpo";
+    readonly variant: "full";
+  };
+  readonly "dpo-lora": {
+    readonly server: "dpo_lora";
+    readonly method: "dpo";
+    readonly variant: "lora";
+  };
+  readonly cpt: {
+    readonly server: "cpt";
+    readonly method: "cpt";
+    readonly variant: "full";
+  };
+};
+type TrainingTypeCli = keyof typeof TRAINING_TYPE_MAP;
+/** All accepted CLI training-type values (for whitelisting / help text). */
+declare const TRAINING_TYPES_CLI: readonly TrainingTypeCli[];
+/** Default training type when `--training-type` is omitted. */
+declare const DEFAULT_TRAINING_TYPE: TrainingTypeCli;
+/** Subset of `supports` relevant to training capability. */
+interface ModelSupports {
+  sft?: boolean;
+  dpo?: boolean;
+  cpt?: boolean;
+  [key: string]: unknown;
+}
+/**
+ * A model record's training-capability fields. The full listFoundationModels
+ * item carries many more fields; only these are consulted here.
+ */
+interface ModelCapability {
+  model?: string;
+  supports?: ModelSupports;
+  trainingTypes?: Record<string, string[]>;
+  [key: string]: unknown;
+}
+/** True when `value` is one of the accepted CLI training types. */
+declare function isTrainingTypeCli(value: string): value is TrainingTypeCli;
+/** Map a CLI training type to the server `training_type` for the request body. */
+declare function toServerTrainingType(value: TrainingTypeCli): string;
+/** The (method, variant) pair a CLI training type resolves to. */
+declare function trainingTypeMethodVariant(value: TrainingTypeCli): {
+  method: string;
+  variant: string;
+};
+/**
+ * Whether a model supports the given CLI training type.
+ *
+ * A model supports `<method>[-lora]` when both:
+ *   1. `supports.<method> === true` (the high-level capability gate), and
+ *   2. `trainingTypes.<method>` includes the corresponding variant
+ *      (`full` for the bare name, `lora` for the `-lora` suffix).
+ */
+declare function modelSupportsTrainingType(model: ModelCapability | undefined | null, value: TrainingTypeCli): boolean;
+/**
+ * Every CLI training type a model supports, in canonical order
+ * (sft, sft-lora, dpo, dpo-lora, cpt). Empty when the model carries no
+ * capability metadata or supports none.
+ */
+declare function listSupportedTrainingTypes(model: ModelCapability | undefined | null): TrainingTypeCli[];
+/**
+ * Fetch a single model's foundation metadata by name (console gateway
+ * `listFoundationModels` with a `name` filter). No console login required —
+ * `listFoundationModels` is a public API, so only a DashScope API key is needed.
+ *
+ * Returns the first exact-model match, or `null` when nothing matches (the
+ * server's `name` filter is a substring match, so we additionally require an
+ * exact `model` equality to avoid e.g. `qwen3-8b` matching `qwen3-8b-v2`).
+ */
+declare function fetchModelCapability(config: Config, modelName: string): Promise<ModelCapability | null>;
+//#endregion
+//#region src/finetune/preflight.d.ts
+/** Stable issue code for "too few training samples for the batch size". */
+declare const INSUFFICIENT_SAMPLES_CODE = "INSUFFICIENT_SAMPLES";
+interface BatchSizeGateInput {
+  /**
+   * Total training-sample count across all `--datasets` files. Sourced from
+   * `validateDataset`'s `stats.totalRecords` (summed per file). The gate only
+   * fires when this is known — i.e. every dataset token was a local file that
+   * was validated; bare file-id tokens yield no count and fall through to the
+   * platform.
+   */
+  recordCount: number;
+  /**
+   * Effective batch_size the job will run with — after the CLI's clamp
+   * ([8, 1024]) and small-file auto-adjust, or the platform default (16) when
+   * neither the user nor auto-adjust set one.
+   */
+  batchSize: number;
+}
+interface BatchSizeGateResult {
+  ok: boolean;
+  /** Present when `!ok`, in the same shape `validateDataset` issues use. */
+  issue?: ValidationIssue;
+  /** Actionable guidance; callers surface it as the `BailianError` detail. */
+  hint?: string;
+}
+/**
+ * Pre-flight the platform's "training samples must exceed batch_size" rule.
+ *
+ * The platform rejects a job whose number of training samples is not greater
+ * than batch_size, but only surfaces that ~10 minutes into the run (after data
+ * processing). This gate fails fast, before upload or quota consumption.
+ *
+ * Conservative by design — never false-positives: with the platform's default
+ * 0.9 train split, training samples = 0.9 * recordCount <= recordCount, so
+ * `recordCount <= batchSize` implies training samples <= batchSize implies
+ * certain platform failure. Borderline counts (records just above batchSize)
+ * may still fail on the platform; that's an acceptable false negative for a
+ * pre-check, and the hint nudges users to leave margin for the split.
+ */
+declare function preflightBatchSizeGate(input: BatchSizeGateInput): BatchSizeGateResult;
+//#endregion
+//#region src/deploy/types.d.ts
+/**
+ * Model-deployment API types.
+ *
+ * Maps DashScope `/api/v1/deployments` request/response shapes (snake_case
+ * preserved verbatim — callers decide how to surface fields).
+ */
+/** A single deployment record as returned by the platform. */
+interface Deployment {
+  /** Unique deployed-model identifier — used as the `model` parameter when invoking the deployed model. */
+  deployed_model?: string;
+  /** Human-friendly display name set at creation time. */
+  name?: string;
+  /** Underlying model identifier (e.g. fine-tuned output or catalog model). */
+  model_name?: string;
+  /** Catalog base model. */
+  base_model?: string;
+  /** PENDING | RUNNING | STOPPED | FAILED */
+  status?: string;
+  /** Billing plan: mu | cu | ptu | lora (Token-billed). */
+  plan?: string;
+  /** Spec descriptor for MU plan, e.g. "MU1". */
+  model_unit_spec?: string;
+  /** Charge type, e.g. "post_paid". */
+  charge_type?: string;
+  /** Capacity in plan units. */
+  capacity?: number;
+  base_capacity?: number;
+  ready_capacity?: number;
+  /** Rate limits (per minute). */
+  rpm_limit?: number;
+  tpm_limit?: number;
+  /** PTU-only token-rate limits. */
+  input_tpm?: number;
+  output_tpm?: number;
+  enable_thinking?: boolean;
+  max_context_length?: number;
+  workspace_id?: string;
+  creator?: string;
+  modifier?: string;
+  gmt_create?: string;
+  gmt_modified?: string;
+  /** Free-form additional fields are preserved by callers. */
+  [k: string]: unknown;
+}
+/** A single deployable model record (GET /deployments/models). */
+interface DeployableModel {
+  model_name?: string;
+  base_model?: string;
+  /** custom | public | base | … */
+  model_source?: string;
+  /** Supported plans for `custom` (fine-tuned) models, e.g. ["mu","lora"]. */
+  supported_plans?: string[];
+  /**
+   * Nested plan info for `base` (catalog) models. Each entry describes one
+   * plan and (when applicable) its deployment templates.
+   *   - plan: "mu" | "ptu_v2" | "cu" | …
+   *   - templates: required when plan="mu" — picks deploy_spec / charge_type / role configs
+   *   - cu_specs: required when plan="cu" — light/basic etc
+   */
+  plans?: Array<{
+    plan?: string;
+    templates?: Array<DeployableTemplate>;
+    cu_specs?: string[];
+    [k: string]: unknown;
+  }>;
+  display_name?: string;
+  description?: string;
+  version?: string;
+  status?: string;
+  gmt_create?: string;
+  gmt_modified?: string;
+  [k: string]: unknown;
+}
+/** A single deployment template (only used by `plan=mu` base models). */
+interface DeployableTemplate {
+  template_id?: string;
+  template_name?: string;
+  template_desc?: string;
+  /** pre_paid | post_paid */
+  charge_type?: string;
+  /** SYSTEM | CUSTOM */
+  template_source?: string;
+  /** COUPLED | SEPERATED */
+  template_type?: string;
+  template_version?: string;
+  deploy_spec?: string;
+  /** Role-specific resource specs. Either `unified` (COUPLED) or `prefill` + `decode` (SEPERATED). */
+  roles?: {
+    unified?: {
+      model_unit_spec?: string;
+      capacity_unit_per_instance?: number;
+      capacity_unit_init?: number;
+    };
+    prefill?: {
+      model_unit_spec?: string;
+      capacity_unit_per_instance?: number;
+      capacity_unit_init?: number;
+    };
+    decode?: {
+      model_unit_spec?: string;
+      capacity_unit_per_instance?: number;
+      capacity_unit_init?: number;
+    };
+    [k: string]: unknown;
+  };
+  [k: string]: unknown;
+}
+/** POST /api/v1/deployments request body. */
+interface CreateDeploymentRequest {
+  /** Required. The catalog or fine-tuned model identifier. */
+  model_name: string;
+  /** Required. Display name shown in the console. */
+  name: string;
+  /** Required. Billing plan: mu | cu | ptu | lora. CLI defaults to "lora". */
+  plan: string;
+  /** Required by API even for token-billed (lora) plans where it is ignored — CLI injects 1. */
+  capacity?: number;
+  /** Optional template id for advanced configurations. */
+  template_id?: string;
+  /**
+   * PTU capacity (provisioned throughput limits). Only effective when
+   * `plan === "ptu"`. The doc says this defaults to 10000/1000 when omitted,
+   * but the platform currently rejects creation without it ("Miss ptu capacity
+   * info"), so the CLI treats it as required for ptu.
+   */
+  ptu_capacity?: PtuCapacity;
+  /** Future-compat: arbitrary additional fields are forwarded as-is. */
+  [k: string]: unknown;
+}
+/** PTU throughput limits — only used when `plan === "ptu"`. */
+interface PtuCapacity {
+  /** Max input tokens per minute (all models). */
+  input_tpm?: number;
+  /** Max output tokens per minute (all models). */
+  output_tpm?: number;
+  /** Max thinking-output tokens per minute (some models only). */
+  thinking_output_tpm?: number;
+}
+/** POST /api/v1/deployments response. */
+interface CreateDeploymentResponse {
+  request_id?: string;
+  output?: Deployment;
+  data?: Deployment;
+}
+/** GET /api/v1/deployments response. */
+interface ListDeploymentsResponse {
+  request_id?: string;
+  output?: {
+    deployments?: Deployment[];
+    total?: number;
+    page_no?: number;
+    page_size?: number;
+    [k: string]: unknown;
+  };
+  data?: {
+    deployments?: Deployment[];
+    total?: number;
+    page_no?: number;
+    page_size?: number;
+    [k: string]: unknown;
+  };
+}
+/** GET /api/v1/deployments/{deployed_model} response. */
+interface GetDeploymentResponse {
+  request_id?: string;
+  output?: Deployment;
+  data?: Deployment;
+}
+/** DELETE /api/v1/deployments/{deployed_model} response. */
+interface DeleteDeploymentResponse {
+  request_id?: string;
+  output?: {
+    deleted?: boolean;
+    deployed_model?: string;
+    [k: string]: unknown;
+  };
+  data?: {
+    deleted?: boolean;
+    deployed_model?: string;
+    [k: string]: unknown;
+  };
+}
+/** GET /api/v1/deployments/models response. */
+interface ListDeployableModelsResponse {
+  request_id?: string;
+  output?: {
+    models?: DeployableModel[];
+    total?: number;
+    page_no?: number;
+    page_size?: number;
+    [k: string]: unknown;
+  };
+  data?: {
+    models?: DeployableModel[];
+    total?: number;
+    page_no?: number;
+    page_size?: number;
+    [k: string]: unknown;
+  };
+}
+/** PUT /api/v1/deployments/{deployed_model}/scale request body. */
+interface ScaleDeploymentRequest {
+  /** New capacity in plan units. Server-side constraint: integer multiple of `base_capacity`, < 1000. */
+  capacity?: number;
+  /** PTU-only token-rate adjustments. */
+  input_tpm?: number;
+  output_tpm?: number;
+  [k: string]: unknown;
+}
+/** PUT /api/v1/deployments/{deployed_model}/scale response. */
+interface ScaleDeploymentResponse {
+  request_id?: string;
+  output?: Deployment;
+  data?: Deployment;
+}
+/**
+ * PUT /api/v1/deployments/{deployed_model} request body.
+ *
+ * Update rate limits — at least one of `rpm_limit` / `tpm_limit` is required.
+ *   - rpm_limit: requests per minute
+ *   - tpm_limit: tokens per minute
+ */
+interface UpdateDeploymentRequest {
+  rpm_limit?: number;
+  tpm_limit?: number;
+  [k: string]: unknown;
+}
+/** PUT /api/v1/deployments/{deployed_model} response. */
+interface UpdateDeploymentResponse {
+  request_id?: string;
+  output?: Deployment;
+  data?: Deployment;
+}
+//#endregion
+//#region src/deploy/api.d.ts
+/** POST /api/v1/deployments */
+declare function createDeployment(config: Config, body: CreateDeploymentRequest, signal?: AbortSignal): Promise<CreateDeploymentResponse>;
+interface ListDeploymentsParams {
+  pageNo?: number;
+  pageSize?: number;
+  status?: string;
+  signal?: AbortSignal;
+}
+/** GET /api/v1/deployments */
+declare function listDeployments(config: Config, params?: ListDeploymentsParams): Promise<ListDeploymentsResponse>;
+/** GET /api/v1/deployments/{deployed_model} */
+declare function getDeployment(config: Config, deployedModel: string, signal?: AbortSignal): Promise<GetDeploymentResponse>;
+/** DELETE /api/v1/deployments/{deployed_model} */
+declare function deleteDeployment(config: Config, deployedModel: string, signal?: AbortSignal): Promise<DeleteDeploymentResponse>;
+interface ListDeployableModelsParams {
+  pageNo?: number;
+  pageSize?: number;
+  /** Catalog version filter, e.g. "v1.0". */
+  version?: string;
+  /** Source filter: "custom" (fine-tuned outputs) | "public" | …. */
+  modelSource?: string;
+  signal?: AbortSignal;
+}
+/** GET /api/v1/deployments/models */
+declare function listDeployableModels(config: Config, params?: ListDeployableModelsParams): Promise<ListDeployableModelsResponse>;
+/** PUT /api/v1/deployments/{deployed_model}/scale */
+declare function scaleDeployment(config: Config, deployedModel: string, body: ScaleDeploymentRequest, signal?: AbortSignal): Promise<ScaleDeploymentResponse>;
+/**
+ * PUT /api/v1/deployments/{deployed_model}/update
+ *
+ * Update rate limits. At least one of `rpm_limit` / `tpm_limit` must be set.
+ */
+declare function updateDeployment(config: Config, deployedModel: string, body: UpdateDeploymentRequest, signal?: AbortSignal): Promise<UpdateDeploymentResponse>;
+//#endregion
 //#region src/types/command.d.ts
 interface OptionDef {
   flag: string;
@@ -914,21 +1798,32 @@ interface OptionDef {
   required?: boolean;
 }
 interface Command {
-  name: string;
   description: string;
-  usage?: string;
+  /**
+   * Argument portion of the usage line, WITHOUT the `<bin> <path>` prefix
+   * (e.g. "--index-id <id> --query <text> [flags]"). The runtime prepends the
+   * product binary name and the command's actual path when rendering help, so
+   * the same command renders correctly under any product (bl / rag / …).
+   */
+  usageArgs?: string;
   options?: OptionDef[];
-  examples?: string[];
+  /**
+   * Example argument strings, each WITHOUT the `<bin> <path>` prefix
+   * (e.g. '--index-id idx_xxx --query "..."'). The runtime prepends
+   * `<bin> <path>` per product when rendering help.
+   */
+  exampleArgs?: string[];
   skipDefaultApiKeySetup?: boolean;
   notes?: string[];
   execute: (config: Config, flags: GlobalFlags) => Promise<void>;
 }
 interface CommandSpec {
-  name: string;
   description: string;
-  usage?: string;
+  /** See {@link Command.usageArgs} — argument portion only, no `<bin> <path>` prefix. */
+  usageArgs?: string;
   options?: OptionDef[];
-  examples?: string[];
+  /** See {@link Command.exampleArgs} — argument strings only, no `<bin> <path>` prefix. */
+  exampleArgs?: string[];
   skipDefaultApiKeySetup?: boolean;
   notes?: string[];
   run: (config: Config, flags: GlobalFlags) => Promise<void>;
@@ -957,9 +1852,6 @@ declare function resolveOutputDir(config: Config, options?: {
   subDir?: string;
 }): string;
 //#endregion
-//#region src/utils/schema.d.ts
-declare function generateToolSchema(cmd: Command): Record<string, unknown>;
-//#endregion
 //#region src/utils/token.d.ts
 declare function maskToken(token: string): string;
 //#endregion
@@ -1251,4 +2143,4 @@ interface ModelSource {
   load(): Promise<ModelProfile[]>;
 }
 //#endregion
-export { AkSignConfig, type ApiErrorBody, AppCompletionRequest, AppCompletionResponse, AppStreamChunk, AuthMethod, BAILIAN_HOST, BailianError, Budget, Budgets, CHANNEL, CONSOLE_GATEWAY_NO_TOKEN_MESSAGE, Capabilities, Capability, ChatChoice, ChatMessage, ChatMessageContent, ChatRequest, ChatResponse, ChatTool, Command, CommandSpec, Complexities, Complexity, Config, ConfigFile, ConsoleGatewayRequest, ConsoleSite, ContextNeed, ContextNeeds, DOCS_HOSTS, DashScopeASRRequest, DashScopeASRTaskResult, DashScopeAsyncResponse, DashScopeImageRequest, DashScopeImageSyncResponse, DashScopeKnowledgeRetrieveRequest, DashScopeKnowledgeRetrieveResponse, DashScopeTTSRequest, DashScopeTTSResponse, DashScopeTTSStreamChunk, DashScopeTaskResponse, DashScopeVideoEditRequest, DashScopeVideoRefRequest, DashScopeVideoRequest, ExitCode, Feature, Features, GLOBAL_OPTIONS, GetModelsOptions, GlobalFlags, IntentProfile, IntentSegment, KnowledgeRetrieveRequest, KnowledgeRetrieveResponse, McpClient, McpTool, McpToolResult, MemoryAddRequest, MemoryAddResponse, MemoryMessage, MemoryNode, MemoryNodeListResponse, MemoryNodeUpdateRequest, MemorySearchRequest, MemorySearchResponse, Modalities, Modality, ModelCategories, ModelCategory, ModelListParams, ModelListResult, ModelPreference, ModelPrice, ModelProfile, ModelSource, OptionDef, OutputFormat, PipelineResult, PipelineStep, PreferenceMode, ProfileAttribute, ProfileSchemaCreateRequest, ProfileSchemaCreateResponse, QpmLimit, QualityPreference, QualityPreferences, REGIONS, RecommendOptions, RecommendResult, RecommendedModel, Region, RequestOpts, ResolvedCredential, SOURCE_CONFIG, ScoredCandidate, ServerSentEvent, SingleResult, StreamChoice, StreamChunk, TAGS, TrackingEvent, UserProfileResponse, analyzeIntent, appCompletionEndpoint, bailianMcpUrl, buildDocLink, callConsoleGateway, chatEndpoint, clearApiKey, createTrackingEvent, defineCommand, detectOutputFormat, effectiveConsoleGatewayConfig, ensureConfigDir, fetchModelList, flushTelemetry, formatErrorJson, formatJson, formatOutput, formatText, generateFilename, generateToolSchema, getConfigDir, getConfigPath, getCredentialsPath, getModels, imageEndpoint, imageSyncEndpoint, isCI, isInteractive, isLocalFile, isSemanticAvailable, knowledgeRetrieveEndpoint, loadApiKeyFromConfig, loadConfig, localSink, mapApiError, maskToken, mcpWebSearchEndpoint, memoryAddEndpoint, memoryListEndpoint, memoryNodeEndpoint, memorySearchEndpoint, parseBooleanValue, parseConfigFile, parseOptionalBooleanValue, parseSSE, profileSchemaEndpoint, rankModels, readConfigFile, recallCandidates, recallSemantic, remoteSink, request, requestJson, resolveBooleanFlag, resolveConsoleGatewayCredential, resolveCredential, resolveFileUrl, resolveOutputDir, resolveWatermark, saveApiKeyToConfig, signRequest, speechRecognizeEndpoint, speechSynthesizeEndpoint, stripUndefined, taskEndpoint, trackCommandExecution, trackingHeaders, uploadFile, userProfileEndpoint, videoGenerateEndpoint, writeConfigFile };
+export { AkSignConfig, type ApiErrorBody, AppCompletionRequest, AppCompletionResponse, AppStreamChunk, AuthMethod, BAILIAN_HOST, BailianError, BatchSizeGateInput, BatchSizeGateResult, Budget, Budgets, CHANNEL, CONSOLE_GATEWAY_NO_TOKEN_MESSAGE, CancelFineTuneResponse, Capabilities, Capability, ChatChoice, ChatMessage, ChatMessageContent, ChatRequest, ChatResponse, ChatTool, Command, CommandSpec, Complexities, Complexity, Config, ConfigFile, ConsoleGatewayRequest, ConsoleSite, ContextNeed, ContextNeeds, CreateDeploymentRequest, CreateDeploymentResponse, CreateFineTuneRequest, CreateFineTuneResponse, DEFAULT_TRAINING_TYPE, DOCS_HOSTS, DashScopeASRRequest, DashScopeASRTaskResult, DashScopeAsyncResponse, DashScopeImageRequest, DashScopeImageSyncResponse, DashScopeKnowledgeRetrieveRequest, DashScopeKnowledgeRetrieveResponse, DashScopeTTSRequest, DashScopeTTSResponse, DashScopeTTSStreamChunk, DashScopeTaskResponse, DashScopeVideoEditRequest, DashScopeVideoRefRequest, DashScopeVideoRequest, DatasetDeleteResponse, DatasetFile, DatasetGetResponse, DatasetListParams, DatasetListResponse, DatasetSchema, DatasetUploadParams, DatasetUploadResponse, DeleteDeploymentResponse, DeleteFineTuneResponse, DeployableModel, DeployableTemplate, Deployment, ExitCode, ExportCheckpointResponse, Feature, Features, FineTuneCheckpoint, FineTuneHyperParameters, FineTuneJob, FineTuneLogEntry, GLOBAL_OPTIONS, GetDeploymentResponse, GetFineTuneLogsParams, GetFineTuneLogsResponse, GetFineTuneResponse, GetModelsOptions, GlobalFlags, INSUFFICIENT_SAMPLES_CODE, IntentProfile, IntentSegment, KnowledgeRetrieveRequest, KnowledgeRetrieveResponse, ListCheckpointsResponse, ListDeployableModelsParams, ListDeployableModelsResponse, ListDeploymentsParams, ListDeploymentsResponse, ListFineTunesParams, ListFineTunesResponse, MAX_DATASET_BYTES, McpClient, McpTool, McpToolResult, MemoryAddRequest, MemoryAddResponse, MemoryMessage, MemoryNode, MemoryNodeListResponse, MemoryNodeUpdateRequest, MemorySearchRequest, MemorySearchResponse, Modalities, Modality, ModelCapability, ModelCategories, ModelCategory, ModelListParams, ModelListResult, ModelPreference, ModelPrice, ModelProfile, ModelSource, OptionDef, OutputFormat, PipelineResult, PipelineStep, PreferenceMode, ProfileAttribute, ProfileSchemaCreateRequest, ProfileSchemaCreateResponse, PtuCapacity, QpmLimit, QualityPreference, QualityPreferences, REGIONS, RecommendOptions, RecommendResult, RecommendedModel, Region, RequestOpts, ResolvedCredential, SOURCE_CONFIG, ScaleDeploymentRequest, ScaleDeploymentResponse, ScoredCandidate, ServerSentEvent, SingleResult, StreamChoice, StreamChunk, TAGS, TRAINING_TYPES_CLI, TRAINING_TYPE_MAP, TrackingEvent, TrainingTypeCli, UpdateDeploymentRequest, UpdateDeploymentResponse, UserProfileResponse, ValidateOpts, ValidationIssue, ValidationResult, ValidationSeverity, ValidationStats, ValidatorSpec, analyzeIntent, appCompletionEndpoint, bailianMcpUrl, buildDocLink, callConsoleGateway, cancelFineTune, chatEndpoint, clearApiKey, createDeployment, createFineTune, createTrackingEvent, defineCommand, deleteDataset, deleteDeployment, deleteFineTune, detectOutputFormat, effectiveConsoleGatewayConfig, ensureConfigDir, exportCheckpoint, fetchModelCapability, fetchModelList, flushTelemetry, formatErrorJson, formatIssue, formatJson, formatOutput, formatText, generateFilename, getConfigDir, getConfigPath, getCredentialsPath, getDataset, getDeployment, getFineTune, getFineTuneLogs, getModels, imageEndpoint, imageSyncEndpoint, isCI, isInteractive, isLocalFile, isSemanticAvailable, isTrainingTypeCli, knowledgeRetrieveEndpoint, listCheckpoints, listDatasets, listDeployableModels, listDeployments, listFineTunes, listSupportedFormats, listSupportedTrainingTypes, loadApiKeyFromConfig, loadConfig, localSink, mapApiError, maskToken, mcpWebSearchEndpoint, memoryAddEndpoint, memoryListEndpoint, memoryNodeEndpoint, memorySearchEndpoint, modelSupportsTrainingType, parseBooleanValue, parseConfigFile, parseDatasetSchemaFlag, parseOptionalBooleanValue, parseSSE, pickValidator, preflightBatchSizeGate, profileSchemaEndpoint, rankModels, readConfigFile, recallCandidates, recallSemantic, registerValidator, remoteSink, request, requestJson, resolveBooleanFlag, resolveConsoleGatewayCredential, resolveCredential, resolveFileUrl, resolveOutputDir, resolveWatermark, saveApiKeyToConfig, scaleDeployment, signRequest, speechRecognizeEndpoint, speechSynthesizeEndpoint, stripUndefined, taskEndpoint, toServerTrainingType, trackCommandExecution, trackingHeaders, trainingTypeMethodVariant, updateDeployment, uploadDataset, uploadFile, userProfileEndpoint, validateDataset, videoGenerateEndpoint, writeConfigFile };