@camstack/types 1.2.332 → 1.2.334

package/dist/training/index.d.ts

@@ -0,0 +1 @@
+export * from './trainer-contract.js';

package/dist/training/trainer-contract.d.ts

@@ -0,0 +1,468 @@
+/**
+ * The trainer contract — what the hub hands the cloud trainer and what it
+ * gets back (cloud training, D805+).
+ *
+ * The trainer (`hf/camstack-trainer`, published as the Hugging Face repo
+ * `camstack/camstack-trainer`) is a separate AGPL program the hub never
+ * imports: `job.json` goes in, files come out, and progress is `CAMSTACK_EVENT`
+ * lines on stdout. These schemas are the hub's half of that boundary; the
+ * trainer's pydantic models (and the JSON Schemas generated from them under
+ * `hf/camstack-trainer/schemas/`) are the other half. A change here is a
+ * change there, in the same piece of work.
+ *
+ * No `.default()` anywhere: defaults do not run on the addon cap path, so the
+ * orchestrator fills every field of a job spec explicitly.
+ */
+import { z } from 'zod';
+export declare const TRAINING_JOB_SCHEMA = "camstack.training/v1";
+export declare const TRAINING_RESULT_SCHEMA = "camstack.training-result/v1";
+/** The stdout prefix of a progress line. Anything else on stdout is log text. */
+export declare const CAMSTACK_EVENT_PREFIX = "CAMSTACK_EVENT ";
+/** What the trainer can export. Edge TPU is a later, separate image. */
+export declare const TrainingExportSchema: z.ZodEnum<{
+    onnx: "onnx";
+    "openvino-fp16": "openvino-fp16";
+    "openvino-int8": "openvino-int8";
+    "coreml-fp16": "coreml-fp16";
+}>;
+export type TrainingExport = z.infer<typeof TrainingExportSchema>;
+export declare const TrainingJobSpecSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"camstack.training/v1">;
+    jobKey: z.ZodString;
+    target: z.ZodObject<{
+        kind: z.ZodLiteral<"detector">;
+        step: z.ZodLiteral<"object-detection">;
+    }, z.core.$strip>;
+    base: z.ZodObject<{
+        modelId: z.ZodString;
+        weights: z.ZodString;
+        imgsz: z.ZodNumber;
+    }, z.core.$strip>;
+    baseline: z.ZodObject<{
+        modelId: z.ZodString;
+        onnxUrl: z.ZodString;
+        imgsz: z.ZodNumber;
+        floors: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    }, z.core.$strip>;
+    dataset: z.ZodObject<{
+        versionId: z.ZodString;
+        annotationHash: z.ZodString;
+        sha256: z.ZodString;
+    }, z.core.$strip>;
+    split: z.ZodObject<{
+        holdoutCameras: z.ZodArray<z.ZodNumber>;
+        holdoutLastDays: z.ZodNumber;
+        valFraction: z.ZodNumber;
+        seed: z.ZodNumber;
+    }, z.core.$strip>;
+    hyper: z.ZodObject<{
+        epochs: z.ZodNumber;
+        batch: z.ZodNumber;
+        lr0: z.ZodNumber;
+        freeze: z.ZodNumber;
+        patience: z.ZodNumber;
+        seed: z.ZodNumber;
+    }, z.core.$strip>;
+    replay: z.ZodObject<{
+        source: z.ZodLiteral<"coco2017">;
+        count: z.ZodNumber;
+    }, z.core.$strip>;
+    exports: z.ZodArray<z.ZodEnum<{
+        onnx: "onnx";
+        "openvino-fp16": "openvino-fp16";
+        "openvino-int8": "openvino-int8";
+        "coreml-fp16": "coreml-fp16";
+    }>>;
+    calibration: z.ZodObject<{
+        maxFrames: z.ZodNumber;
+    }, z.core.$strip>;
+    floors: z.ZodObject<{
+        minSupport: z.ZodNumber;
+        clamp: z.ZodNumber;
+    }, z.core.$strip>;
+    int8Gate: z.ZodObject<{
+        maxMap50Drop: z.ZodNumber;
+    }, z.core.$strip>;
+    catalog: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type TrainingJobSpec = z.infer<typeof TrainingJobSpecSchema>;
+/** One regular file of the bundle. An mlpackage contributes one row per member. */
+export declare const TrainingResultFileSchema: z.ZodObject<{
+    path: z.ZodString;
+    bytes: z.ZodNumber;
+    sha256: z.ZodString;
+    format: z.ZodEnum<{
+        onnx: "onnx";
+        coreml: "coreml";
+        openvino: "openvino";
+        pt: "pt";
+    }>;
+    variant: z.ZodEnum<{
+        int8: "int8";
+        base: "base";
+    }>;
+}, z.core.$strip>;
+export type TrainingResultFile = z.infer<typeof TrainingResultFileSchema>;
+/** The trainer's half of a catalog entry; the hub completes it (labels, licence, group). */
+export declare const TrainingCatalogDraftSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodString;
+    labels: z.ZodArray<z.ZodUnknown>;
+    inputSize: z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>;
+    preprocessMode: z.ZodLiteral<"letterbox">;
+    defaultClassFloors: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    formats: z.ZodObject<{
+        onnx: z.ZodOptional<z.ZodObject<{
+            url: z.ZodString;
+            sizeMB: z.ZodNumber;
+            isDirectory: z.ZodOptional<z.ZodBoolean>;
+            files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            runtimes: z.ZodOptional<z.ZodArray<z.ZodLiteral<"python">>>;
+            revision: z.ZodString;
+        }, z.core.$strip>>;
+        openvino: z.ZodOptional<z.ZodObject<{
+            url: z.ZodString;
+            sizeMB: z.ZodNumber;
+            isDirectory: z.ZodOptional<z.ZodBoolean>;
+            files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            runtimes: z.ZodOptional<z.ZodArray<z.ZodLiteral<"python">>>;
+            revision: z.ZodString;
+        }, z.core.$strip>>;
+        coreml: z.ZodOptional<z.ZodObject<{
+            url: z.ZodString;
+            sizeMB: z.ZodNumber;
+            isDirectory: z.ZodOptional<z.ZodBoolean>;
+            files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            runtimes: z.ZodOptional<z.ZodArray<z.ZodLiteral<"python">>>;
+            revision: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type TrainingCatalogDraft = z.infer<typeof TrainingCatalogDraftSchema>;
+/** One class of one model's holdout report (the eval harness's summary). */
+export declare const TrainingEvalClassSchema: z.ZodObject<{
+    positives: z.ZodNumber;
+    floor: z.ZodNullable<z.ZodNumber>;
+    tp: z.ZodNumber;
+    fp: z.ZodNumber;
+    fn: z.ZodNumber;
+    precision: z.ZodNullable<z.ZodNumber>;
+    recall: z.ZodNullable<z.ZodNumber>;
+    ap50: z.ZodNullable<z.ZodNumber>;
+    recallByCamera: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodNumber>>>;
+    recallByLight: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodNumber>>>;
+    fpByCamera: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    smallFound: z.ZodOptional<z.ZodNumber>;
+    smallTotal: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+export type TrainingEvalClass = z.infer<typeof TrainingEvalClassSchema>;
+export declare const TrainingEvalReportSchema: z.ZodObject<{
+    frames: z.ZodNumber;
+    classes: z.ZodRecord<z.ZodString, z.ZodObject<{
+        positives: z.ZodNumber;
+        floor: z.ZodNullable<z.ZodNumber>;
+        tp: z.ZodNumber;
+        fp: z.ZodNumber;
+        fn: z.ZodNumber;
+        precision: z.ZodNullable<z.ZodNumber>;
+        recall: z.ZodNullable<z.ZodNumber>;
+        ap50: z.ZodNullable<z.ZodNumber>;
+        recallByCamera: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodNumber>>>;
+        recallByLight: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodNumber>>>;
+        fpByCamera: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        smallFound: z.ZodOptional<z.ZodNumber>;
+        smallTotal: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export type TrainingEvalReport = z.infer<typeof TrainingEvalReportSchema>;
+/**
+ * A succeeded result carries every block; a failed one carries the error and
+ * whatever was known by then — the other blocks are ABSENT, not null. The
+ * orchestrator checks the blocks it needs before it trusts a success.
+ */
+export declare const TrainingResultSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"camstack.training-result/v1">;
+    jobKey: z.ZodString;
+    status: z.ZodEnum<{
+        failed: "failed";
+        succeeded: "succeeded";
+    }>;
+    error: z.ZodNullable<z.ZodObject<{
+        stage: z.ZodString;
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>>;
+    trainer: z.ZodObject<{
+        version: z.ZodString;
+        revision: z.ZodString;
+    }, z.core.$strip>;
+    toolchain: z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodString>>;
+    dataset: z.ZodOptional<z.ZodObject<{
+        versionId: z.ZodString;
+        annotationHash: z.ZodString;
+        sha256: z.ZodString;
+        frames: z.ZodObject<{
+            train: z.ZodNumber;
+            val: z.ZodNumber;
+            holdout: z.ZodNumber;
+        }, z.core.$strip>;
+        holdoutCameras: z.ZodArray<z.ZodNumber>;
+        replayImages: z.ZodNumber;
+    }, z.core.$strip>>;
+    training: z.ZodOptional<z.ZodObject<{
+        epochsRun: z.ZodNumber;
+        bestEpoch: z.ZodNumber;
+        bestMap50: z.ZodNumber;
+        bestMap50_95: z.ZodNumber;
+        seconds: z.ZodNumber;
+    }, z.core.$strip>>;
+    evaluation: z.ZodOptional<z.ZodObject<{
+        holdoutFrames: z.ZodNumber;
+        baseline: z.ZodNullable<z.ZodObject<{
+            frames: z.ZodNumber;
+            classes: z.ZodRecord<z.ZodString, z.ZodObject<{
+                positives: z.ZodNumber;
+                floor: z.ZodNullable<z.ZodNumber>;
+                tp: z.ZodNumber;
+                fp: z.ZodNumber;
+                fn: z.ZodNumber;
+                precision: z.ZodNullable<z.ZodNumber>;
+                recall: z.ZodNullable<z.ZodNumber>;
+                ap50: z.ZodNullable<z.ZodNumber>;
+                recallByCamera: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodNumber>>>;
+                recallByLight: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodNumber>>>;
+                fpByCamera: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+                smallFound: z.ZodOptional<z.ZodNumber>;
+                smallTotal: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$loose>>;
+        }, z.core.$loose>>;
+        candidate: z.ZodNullable<z.ZodObject<{
+            frames: z.ZodNumber;
+            classes: z.ZodRecord<z.ZodString, z.ZodObject<{
+                positives: z.ZodNumber;
+                floor: z.ZodNullable<z.ZodNumber>;
+                tp: z.ZodNumber;
+                fp: z.ZodNumber;
+                fn: z.ZodNumber;
+                precision: z.ZodNullable<z.ZodNumber>;
+                recall: z.ZodNullable<z.ZodNumber>;
+                ap50: z.ZodNullable<z.ZodNumber>;
+                recallByCamera: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodNumber>>>;
+                recallByLight: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodNumber>>>;
+                fpByCamera: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+                smallFound: z.ZodOptional<z.ZodNumber>;
+                smallTotal: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$loose>>;
+        }, z.core.$loose>>;
+        candidateInt8: z.ZodNullable<z.ZodObject<{
+            frames: z.ZodNumber;
+            classes: z.ZodRecord<z.ZodString, z.ZodObject<{
+                positives: z.ZodNumber;
+                floor: z.ZodNullable<z.ZodNumber>;
+                tp: z.ZodNumber;
+                fp: z.ZodNumber;
+                fn: z.ZodNumber;
+                precision: z.ZodNullable<z.ZodNumber>;
+                recall: z.ZodNullable<z.ZodNumber>;
+                ap50: z.ZodNullable<z.ZodNumber>;
+                recallByCamera: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodNumber>>>;
+                recallByLight: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodNumber>>>;
+                fpByCamera: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+                smallFound: z.ZodOptional<z.ZodNumber>;
+                smallTotal: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$loose>>;
+        }, z.core.$loose>>;
+        recallDeltaByCamera: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodNumber>>>;
+        map50: z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strip>>;
+    floors: z.ZodOptional<z.ZodObject<{
+        baseline: z.ZodRecord<z.ZodString, z.ZodNumber>;
+        candidate: z.ZodRecord<z.ZodString, z.ZodNumber>;
+        candidateInt8: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        notes: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    int8: z.ZodOptional<z.ZodObject<{
+        kept: z.ZodBoolean;
+        map50Fp16: z.ZodNullable<z.ZodNumber>;
+        map50Int8: z.ZodNullable<z.ZodNumber>;
+        reason: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    exportsDropped: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        export: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>>>;
+    files: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        bytes: z.ZodNumber;
+        sha256: z.ZodString;
+        format: z.ZodEnum<{
+            onnx: "onnx";
+            coreml: "coreml";
+            openvino: "openvino";
+            pt: "pt";
+        }>;
+        variant: z.ZodEnum<{
+            int8: "int8";
+            base: "base";
+        }>;
+    }, z.core.$strip>>>;
+    bundle: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        path: z.ZodLiteral<"bundle.tar">;
+        bytes: z.ZodNumber;
+        sha256: z.ZodString;
+    }, z.core.$strip>>>;
+    catalogDraft: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        base: z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            description: z.ZodString;
+            labels: z.ZodArray<z.ZodUnknown>;
+            inputSize: z.ZodObject<{
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+            }, z.core.$strip>;
+            preprocessMode: z.ZodLiteral<"letterbox">;
+            defaultClassFloors: z.ZodRecord<z.ZodString, z.ZodNumber>;
+            formats: z.ZodObject<{
+                onnx: z.ZodOptional<z.ZodObject<{
+                    url: z.ZodString;
+                    sizeMB: z.ZodNumber;
+                    isDirectory: z.ZodOptional<z.ZodBoolean>;
+                    files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    runtimes: z.ZodOptional<z.ZodArray<z.ZodLiteral<"python">>>;
+                    revision: z.ZodString;
+                }, z.core.$strip>>;
+                openvino: z.ZodOptional<z.ZodObject<{
+                    url: z.ZodString;
+                    sizeMB: z.ZodNumber;
+                    isDirectory: z.ZodOptional<z.ZodBoolean>;
+                    files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    runtimes: z.ZodOptional<z.ZodArray<z.ZodLiteral<"python">>>;
+                    revision: z.ZodString;
+                }, z.core.$strip>>;
+                coreml: z.ZodOptional<z.ZodObject<{
+                    url: z.ZodString;
+                    sizeMB: z.ZodNumber;
+                    isDirectory: z.ZodOptional<z.ZodBoolean>;
+                    files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    runtimes: z.ZodOptional<z.ZodArray<z.ZodLiteral<"python">>>;
+                    revision: z.ZodString;
+                }, z.core.$strip>>;
+            }, z.core.$strip>;
+        }, z.core.$strip>;
+        int8: z.ZodNullable<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            description: z.ZodString;
+            labels: z.ZodArray<z.ZodUnknown>;
+            inputSize: z.ZodObject<{
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+            }, z.core.$strip>;
+            preprocessMode: z.ZodLiteral<"letterbox">;
+            defaultClassFloors: z.ZodRecord<z.ZodString, z.ZodNumber>;
+            formats: z.ZodObject<{
+                onnx: z.ZodOptional<z.ZodObject<{
+                    url: z.ZodString;
+                    sizeMB: z.ZodNumber;
+                    isDirectory: z.ZodOptional<z.ZodBoolean>;
+                    files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    runtimes: z.ZodOptional<z.ZodArray<z.ZodLiteral<"python">>>;
+                    revision: z.ZodString;
+                }, z.core.$strip>>;
+                openvino: z.ZodOptional<z.ZodObject<{
+                    url: z.ZodString;
+                    sizeMB: z.ZodNumber;
+                    isDirectory: z.ZodOptional<z.ZodBoolean>;
+                    files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    runtimes: z.ZodOptional<z.ZodArray<z.ZodLiteral<"python">>>;
+                    revision: z.ZodString;
+                }, z.core.$strip>>;
+                coreml: z.ZodOptional<z.ZodObject<{
+                    url: z.ZodString;
+                    sizeMB: z.ZodNumber;
+                    isDirectory: z.ZodOptional<z.ZodBoolean>;
+                    files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                    runtimes: z.ZodOptional<z.ZodArray<z.ZodLiteral<"python">>>;
+                    revision: z.ZodString;
+                }, z.core.$strip>>;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    licence: z.ZodString;
+}, z.core.$strip>;
+export type TrainingResult = z.infer<typeof TrainingResultSchema>;
+export declare const TrainingStageSchema: z.ZodEnum<{
+    package: "package";
+    replay: "replay";
+    train: "train";
+    export: "export";
+    prepare: "prepare";
+    eval: "eval";
+}>;
+export type TrainingStage = z.infer<typeof TrainingStageSchema>;
+export declare const TrainingEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"stage">;
+    stage: z.ZodEnum<{
+        package: "package";
+        replay: "replay";
+        train: "train";
+        export: "export";
+        prepare: "prepare";
+        eval: "eval";
+    }>;
+    v: z.ZodLiteral<1>;
+    ts: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"epoch">;
+    epoch: z.ZodNumber;
+    epochs: z.ZodNumber;
+    boxLoss: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    map50: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    map50_95: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    etaSec: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    v: z.ZodLiteral<1>;
+    ts: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"metric">;
+    name: z.ZodString;
+    value: z.ZodNumber;
+    v: z.ZodLiteral<1>;
+    ts: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"artifact">;
+    path: z.ZodString;
+    bytes: z.ZodNumber;
+    sha256: z.ZodString;
+    v: z.ZodLiteral<1>;
+    ts: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"done">;
+    status: z.ZodEnum<{
+        failed: "failed";
+        succeeded: "succeeded";
+    }>;
+    resultSha256: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    v: z.ZodLiteral<1>;
+    ts: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    stage: z.ZodString;
+    code: z.ZodString;
+    message: z.ZodString;
+    v: z.ZodLiteral<1>;
+    ts: z.ZodNumber;
+}, z.core.$strip>], "type">;
+export type TrainingEvent = z.infer<typeof TrainingEventSchema>;
+/**
+ * Parse one stdout line. `null` = not an event (plain log text, or an event
+ * line this hub does not understand — a newer trainer may add types).
+ */
+export declare function parseTrainingEventLine(line: string): TrainingEvent | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/types",
-  "version": "1.2.332",
+  "version": "1.2.334",
   "description": "Shared types, interfaces, and model catalogs for the CamStack detection ecosystem",
   "keywords": [
     "camstack",