openpond-sdk 0.0.13 → 0.0.15

package/dist/training.js

@@ -3,6 +3,105 @@ import { z as z2 } from "zod";
 
 // src/model-projects.ts
 import { z } from "zod";
+
+// src/protocol.ts
+var OPENPOND_TRAINING_PROTOCOL_MAJOR = 2;
+var OPENPOND_TRAINING_MEDIA_TYPE = "application/vnd.openpond.training+json;version=2";
+var TRAINING_JOB_SUBMISSION_MAX_BYTES = 1048576;
+var TRAINING_INPUT_ARTIFACT_MAX_BYTES = 67108864;
+var TRAINING_API_RESPONSE_MAX_BYTES = 8388608;
+var OpenPondProtocolError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "OpenPondProtocolError";
+    this.code = code;
+  }
+};
+function canonicalJson(value) {
+  return JSON.stringify(normalizeCanonicalJson(value));
+}
+function canonicalJsonByteLength(value) {
+  return new TextEncoder().encode(canonicalJson(value)).byteLength;
+}
+async function canonicalSha256(value) {
+  const bytes = new TextEncoder().encode(canonicalJson(value));
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+  return Array.from(
+    new Uint8Array(digest),
+    (byte) => byte.toString(16).padStart(2, "0")
+  ).join("");
+}
+function assertCanonicalPayloadSize(value, maximumBytes, label) {
+  const actualBytes = canonicalJsonByteLength(value);
+  if (actualBytes > maximumBytes) {
+    throw new OpenPondProtocolError(
+      "payload_too_large",
+      `${label} is ${actualBytes} bytes; the maximum is ${maximumBytes} bytes.`
+    );
+  }
+}
+function parseBoundedJson(text, maximumBytes, label) {
+  const actualBytes = new TextEncoder().encode(text).byteLength;
+  if (actualBytes > maximumBytes) {
+    throw new OpenPondProtocolError(
+      "response_too_large",
+      `${label} is ${actualBytes} bytes; the maximum is ${maximumBytes} bytes.`
+    );
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new OpenPondProtocolError(
+      "invalid_json",
+      `${label} was not valid JSON.`
+    );
+  }
+}
+function normalizeCanonicalJson(value) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new OpenPondProtocolError(
+        "non_json_value",
+        "Canonical JSON cannot contain a non-finite number."
+      );
+    }
+    return Object.is(value, -0) ? 0 : value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => normalizeCanonicalJson(entry));
+  }
+  if (typeof value === "object") {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new OpenPondProtocolError(
+        "non_json_value",
+        "Canonical JSON accepts only plain objects."
+      );
+    }
+    const result = {};
+    for (const key of Object.keys(value).sort()) {
+      const entry = value[key];
+      if (entry === void 0 || typeof entry === "function" || typeof entry === "symbol") {
+        throw new OpenPondProtocolError(
+          "non_json_value",
+          `Canonical JSON cannot contain ${typeof entry} at ${key}.`
+        );
+      }
+      result[key] = normalizeCanonicalJson(entry);
+    }
+    return result;
+  }
+  throw new OpenPondProtocolError(
+    "non_json_value",
+    `Canonical JSON cannot contain ${typeof value}.`
+  );
+}
+
+// src/model-projects.ts
 var IdSchema = z.string().trim().min(1).max(500);
 var HashSchema = z.string().regex(/^[a-f0-9]{64}$/);
 var TimestampSchema = z.string().datetime({ offset: true });
@@ -144,11 +243,56 @@ var HostedModelProjectDetailSchema = z.object({
   jobCount: z.number().int().nonnegative(),
   latestJobIds: z.array(IdSchema).max(100)
 }).strict();
+var ModelProjectApiErrorSchema = z.object({
+  schemaVersion: z.literal("openpond.modelProjectApiError.v2"),
+  code: z.string().trim().min(1).max(200),
+  message: z.string().trim().min(1).max(5e3),
+  retryable: z.boolean().default(false),
+  requestId: z.string().trim().min(1).max(500).nullable().default(null),
+  details: z.record(z.string(), z.unknown()).default({})
+}).strict();
 
 // src/training.ts
 var IdSchema2 = z2.string().trim().min(1).max(500);
 var HashSchema2 = z2.string().regex(/^[a-f0-9]{64}$/);
 var TimestampSchema2 = z2.string().datetime({ offset: true });
+var TrainingInputArtifactUploadSchema = z2.object({
+  schemaVersion: z2.literal("openpond.trainingInputArtifactUpload.v2"),
+  kind: z2.enum(["portable_training_bundle", "reward_model_dataset"]),
+  idempotencyKey: z2.string().trim().min(1).max(500),
+  sourceManifest: ModelProjectImmutableRefSchema,
+  payload: z2.unknown(),
+  contentHash: HashSchema2
+}).strict();
+var TrainingInputArtifactSchema = z2.object({
+  schemaVersion: z2.literal("openpond.trainingInputArtifact.v2"),
+  kind: z2.enum(["portable_training_bundle", "reward_model_dataset"]),
+  sourceManifest: ModelProjectImmutableRefSchema,
+  artifactRef: z2.string().trim().min(1).max(2e3),
+  contentHash: HashSchema2,
+  sizeBytes: z2.number().int().positive(),
+  createdAt: TimestampSchema2
+}).strict();
+async function trainingInputArtifactUploadHash(upload) {
+  const { contentHash: _contentHash, ...content } = upload;
+  return canonicalSha256(content);
+}
+async function parseAndVerifyTrainingInputArtifactUpload(value) {
+  assertCanonicalPayloadSize(
+    value,
+    TRAINING_INPUT_ARTIFACT_MAX_BYTES,
+    "Training input artifact"
+  );
+  const parsed = TrainingInputArtifactUploadSchema.parse(value);
+  const expectedHash = await trainingInputArtifactUploadHash(parsed);
+  if (parsed.contentHash !== expectedHash) {
+    throw new OpenPondProtocolError(
+      "content_hash_mismatch",
+      `Training input artifact contentHash ${parsed.contentHash} does not match ${expectedHash}.`
+    );
+  }
+  return parsed;
+}
 var TrainingJobKindSchema = z2.enum([
   "reward_model_train",
   "policy_optimize"
@@ -255,6 +399,26 @@ var TrainingJobSubmissionSchema = z2.object({
     });
   }
 });
+async function trainingJobSubmissionHash(submission) {
+  const { contentHash: _contentHash, ...content } = submission;
+  return canonicalSha256(content);
+}
+async function parseAndVerifyTrainingJobSubmission(value) {
+  assertCanonicalPayloadSize(
+    value,
+    TRAINING_JOB_SUBMISSION_MAX_BYTES,
+    "Training Job submission"
+  );
+  const parsed = TrainingJobSubmissionSchema.parse(value);
+  const expectedHash = await trainingJobSubmissionHash(parsed);
+  if (parsed.contentHash !== expectedHash) {
+    throw new OpenPondProtocolError(
+      "content_hash_mismatch",
+      `Training Job contentHash ${parsed.contentHash} does not match ${expectedHash}.`
+    );
+  }
+  return parsed;
+}
 var TrainingJobSchema = z2.object({
   schemaVersion: z2.literal("openpond.trainingJob.v2"),
   id: IdSchema2,
@@ -274,6 +438,11 @@ var TrainingJobSchema = z2.object({
   updatedAt: TimestampSchema2,
   completedAt: TimestampSchema2.nullable()
 }).strict();
+var TrainingJobPageSchema = z2.object({
+  schemaVersion: z2.literal("openpond.trainingJobPage.v2"),
+  jobs: z2.array(TrainingJobSchema).max(1e3),
+  nextCursor: z2.string().trim().min(1).max(2e3).nullable()
+}).strict();
 var TrainingJobEventSchema = z2.object({
   schemaVersion: z2.literal("openpond.trainingJobEvent.v2"),
   id: IdSchema2,
@@ -293,6 +462,7 @@ var TrainingJobLogSchema = z2.object({
   message: z2.string().max(2e4),
   createdAt: TimestampSchema2
 }).strict();
+var TrainingJobControlRequestSchema = z2.object({ expectedVersion: z2.number().int().nonnegative() }).strict();
 var TrainingJobOutputSchema = z2.object({
   schemaVersion: z2.literal("openpond.trainingJobOutput.v2"),
   id: IdSchema2,
@@ -330,6 +500,69 @@ var TrainingExecutionReceiptSchema = z2.object({
   issuedAt: TimestampSchema2,
   signature: z2.string().trim().min(1).max(1e4).nullable()
 }).strict();
+async function trainingExecutionReceiptHash(receipt) {
+  return canonicalSha256(TrainingExecutionReceiptSchema.parse(receipt));
+}
+async function parseAndVerifyTrainingExecutionReceipt(value, expected) {
+  const receipt = TrainingExecutionReceiptSchema.parse(value);
+  const expectedId = IdSchema2.parse(expected.id);
+  const expectedHash = HashSchema2.parse(expected.contentHash);
+  const actualHash = await trainingExecutionReceiptHash(receipt);
+  if (receipt.id !== expectedId || actualHash !== expectedHash) {
+    throw new OpenPondProtocolError(
+      "execution_receipt_mismatch",
+      "The execution receipt identity or canonical content hash did not match."
+    );
+  }
+  if (expected.teamId !== void 0 && receipt.teamId !== IdSchema2.parse(expected.teamId)) {
+    throw new OpenPondProtocolError(
+      "execution_receipt_team_mismatch",
+      "The execution receipt belongs to a different team."
+    );
+  }
+  if (expected.jobId !== void 0 && receipt.jobId !== IdSchema2.parse(expected.jobId)) {
+    throw new OpenPondProtocolError(
+      "execution_receipt_job_mismatch",
+      "The execution receipt belongs to a different Training Job."
+    );
+  }
+  if ((expected.requireCleanup ?? true) && !receipt.cleanupComplete) {
+    throw new OpenPondProtocolError(
+      "execution_cleanup_incomplete",
+      "The execution receipt does not attest complete terminal cleanup."
+    );
+  }
+  return receipt;
+}
+var TrainingJobOutputsSchema = z2.object({
+  schemaVersion: z2.literal("openpond.trainingJobOutputs.v2"),
+  outputs: z2.array(TrainingJobOutputSchema).max(1e4),
+  receipt: TrainingExecutionReceiptSchema.nullable()
+}).strict();
+var TrainingApiErrorSchema = z2.object({
+  schemaVersion: z2.literal("openpond.trainingApiError.v2"),
+  code: z2.string().trim().min(1).max(200),
+  message: z2.string().trim().min(1).max(5e3),
+  retryable: z2.boolean().default(false),
+  requestId: z2.string().trim().min(1).max(500).nullable().default(null),
+  details: z2.record(z2.string(), z2.unknown()).default({})
+}).strict();
+var OpenPondTrainingApiError = class extends Error {
+  status;
+  code;
+  retryable;
+  requestId;
+  details;
+  constructor(status, error) {
+    super(error.message);
+    this.name = "OpenPondTrainingApiError";
+    this.status = status;
+    this.code = error.code;
+    this.retryable = error.retryable;
+    this.requestId = error.requestId;
+    this.details = error.details;
+  }
+};
 var TrainingCapabilitiesSchema = z2.object({
   schemaVersion: z2.literal("openpond.trainingCapabilities.v2"),
   capabilityHash: HashSchema2,
@@ -366,14 +599,18 @@ function createTrainingClient(input) {
     const response = await fetchImpl(`${baseUrl}${pathname}`, {
       ...init,
       headers: {
-        accept: "application/json",
-        ...init?.body ? { "content-type": "application/json" } : {},
+        accept: OPENPOND_TRAINING_MEDIA_TYPE,
+        ...init?.body ? { "content-type": OPENPOND_TRAINING_MEDIA_TYPE } : {},
         ...headersRecord(configuredHeaders),
         ...headersRecord(init?.headers)
       }
     });
-    const body = await response.json();
-    if (!response.ok) throw new Error(errorMessage(body, response.status));
+    const body = parseBoundedJson(
+      await response.text(),
+      TRAINING_API_RESPONSE_MAX_BYTES,
+      "Training API response"
+    );
+    if (!response.ok) throw trainingApiError(body, response.status);
     return body;
   }
   return {
@@ -382,8 +619,20 @@ function createTrainingClient(input) {
         unwrapObject(await request("/v1/training/capabilities"), "capabilities")
       );
     },
+    async stageArtifact(upload) {
+      const parsed = await parseAndVerifyTrainingInputArtifactUpload(upload);
+      return TrainingInputArtifactSchema.parse(
+        unwrapObject(
+          await request("/v1/training/artifacts", {
+            method: "POST",
+            body: JSON.stringify(parsed)
+          }),
+          "artifact"
+        )
+      );
+    },
     async createJob(submission) {
-      const parsed = TrainingJobSubmissionSchema.parse(submission);
+      const parsed = await parseAndVerifyTrainingJobSubmission(submission);
       return TrainingJobSchema.parse(
         unwrapObject(
           await request("/v1/training/jobs", {
@@ -394,9 +643,24 @@ function createTrainingClient(input) {
         )
       );
     },
-    async listJobs(modelProjectId) {
-      const query = modelProjectId ? `?modelProjectId=${encodeURIComponent(IdSchema2.parse(modelProjectId))}` : "";
-      return z2.array(TrainingJobSchema).parse(unwrapObject(await request(`/v1/training/jobs${query}`), "jobs"));
+    async listJobs(options = {}) {
+      const parameters = new URLSearchParams();
+      if (options.modelProjectId) {
+        parameters.set("modelProjectId", IdSchema2.parse(options.modelProjectId));
+      }
+      if (options.cursor) {
+        parameters.set("cursor", z2.string().trim().min(1).max(2e3).parse(options.cursor));
+      }
+      if (options.limit !== void 0) {
+        parameters.set(
+          "limit",
+          String(z2.number().int().min(1).max(1e3).parse(options.limit))
+        );
+      }
+      const query = parameters.size > 0 ? `?${parameters.toString()}` : "";
+      return TrainingJobPageSchema.parse(
+        await request(`/v1/training/jobs${query}`)
+      );
     },
     async getJob(jobId) {
       return TrainingJobSchema.parse(
@@ -406,12 +670,25 @@ function createTrainingClient(input) {
         )
       );
     },
-    async cancelJob(jobId) {
+    async cancelJob(jobId, expectedVersion) {
+      const control = TrainingJobControlRequestSchema.parse({ expectedVersion });
       return TrainingJobSchema.parse(
         unwrapObject(
           await request(
             `/v1/training/jobs/${encodeURIComponent(IdSchema2.parse(jobId))}/cancel`,
-            { method: "POST" }
+            { method: "POST", body: JSON.stringify(control) }
+          ),
+          "job"
+        )
+      );
+    },
+    async stopAfterGroup(jobId, expectedVersion) {
+      const control = TrainingJobControlRequestSchema.parse({ expectedVersion });
+      return TrainingJobSchema.parse(
+        unwrapObject(
+          await request(
+            `/v1/training/jobs/${encodeURIComponent(IdSchema2.parse(jobId))}/stop-after-group`,
+            { method: "POST", body: JSON.stringify(control) }
           ),
           "job"
         )
@@ -428,12 +705,19 @@ function createTrainingClient(input) {
       );
     },
     async outputs(jobId) {
-      return z2.array(TrainingJobOutputSchema).parse(
+      return TrainingJobOutputsSchema.parse(
+        await request(
+          `/v1/training/jobs/${encodeURIComponent(IdSchema2.parse(jobId))}/outputs`
+        )
+      );
+    },
+    async logs(jobId) {
+      return z2.array(TrainingJobLogSchema).max(1e5).parse(
         unwrapObject(
           await request(
-            `/v1/training/jobs/${encodeURIComponent(IdSchema2.parse(jobId))}/outputs`
+            `/v1/training/jobs/${encodeURIComponent(IdSchema2.parse(jobId))}/logs`
           ),
-          "outputs"
+          "logs"
         )
       );
     }
@@ -443,28 +727,56 @@ function unwrapObject(value, key) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return value;
   return key in value ? value[key] : value;
 }
-function errorMessage(value, status) {
-  if (value && typeof value === "object" && "error" in value) {
-    return String(value.error);
+function trainingApiError(value, status) {
+  const parsed = TrainingApiErrorSchema.safeParse(value);
+  if (parsed.success) {
+    return new OpenPondTrainingApiError(status, parsed.data);
   }
-  return `Training request failed with HTTP ${status}.`;
+  return new OpenPondProtocolError(
+    "invalid_error_response",
+    `Training request failed with HTTP ${status} and an invalid error envelope.`
+  );
 }
 export {
+  OPENPOND_TRAINING_MEDIA_TYPE,
+  OPENPOND_TRAINING_PROTOCOL_MAJOR,
+  OpenPondProtocolError,
+  OpenPondTrainingApiError,
   PolicyOptimizationRequestSchema,
   RewardModelTrainingRequestSchema,
+  TRAINING_API_RESPONSE_MAX_BYTES,
+  TRAINING_INPUT_ARTIFACT_MAX_BYTES,
+  TRAINING_JOB_SUBMISSION_MAX_BYTES,
+  TrainingApiErrorSchema,
   TrainingCapabilitiesSchema,
   TrainingCapabilityRequirementSchema,
   TrainingExecutionReceiptSchema,
+  TrainingInputArtifactSchema,
+  TrainingInputArtifactUploadSchema,
   TrainingJobApprovalSchema,
+  TrainingJobControlRequestSchema,
   TrainingJobEventSchema,
   TrainingJobKindSchema,
   TrainingJobLogSchema,
   TrainingJobOutputSchema,
+  TrainingJobOutputsSchema,
+  TrainingJobPageSchema,
   TrainingJobRequestSchema,
   TrainingJobSchema,
   TrainingJobSourceSchema,
   TrainingJobStateSchema,
   TrainingJobSubmissionSchema,
-  createTrainingClient
+  assertCanonicalPayloadSize,
+  canonicalJson,
+  canonicalJsonByteLength,
+  canonicalSha256,
+  createTrainingClient,
+  parseAndVerifyTrainingExecutionReceipt,
+  parseAndVerifyTrainingInputArtifactUpload,
+  parseAndVerifyTrainingJobSubmission,
+  parseBoundedJson,
+  trainingExecutionReceiptHash,
+  trainingInputArtifactUploadHash,
+  trainingJobSubmissionHash
 };
 //# sourceMappingURL=training.js.map