openpond-sdk 0.5.7 → 0.5.9

package/TRAINING_PROTOCOL.md

@@ -175,3 +175,23 @@ The same entry point exports `materializeLearningBatchTaskset`. It verifies a
 sealed learning batch and its evidence, admission decisions, Reward releases,
 and verifier assets, then returns the authored Taskset, portable release, and
 generated verifier files consumed by training preparation.
+
+`prepareReviewedLearningBatch` applies the shared evidence privacy scan before
+that projection. Both clients use it to construct training-source provenance
+from the actual scan and sealed admission decisions.
+
+`prepareManagedTrainingSubmission` constructs the staged portable artifact and
+public policy-optimization Job from the approved manifest, recipe, exact file
+inventory, held-out source and synchronized Model. It verifies the selected
+bytes and budget, copies its inputs before hashing, and performs no network
+requests. A hosted iteration supplies its durable dispatch id as
+`idempotencyKey`; manual training retains its manifest-derived identity. The
+caller stages the returned `artifact` and creates the returned `submission`
+through the existing training client.
+
+Before approval, `withAuthoritativeRecipeHashes(taskset, recipe)` binds the
+selected Taskset and graders into the executable recipe. This is the same
+projection used by Desktop for GRPO, PPO and DPO, including GRPO optimizer
+semantics and bounded resource defaults. Validate the result with the applicable
+recipe contract, then retain that exact recipe through approval and submission.
+The shared `AdamwOptimizerConfigSchema` supplies the existing optimizer defaults.

package/dist/training-bundle.js

@@ -4,6 +4,7 @@ import {
   resolvePortableTasksetRewardExecution
 } from "./chunk-ARUJ3FJT.js";
 import {
+  LearningBatchDatasetSourceRefSchema,
   TasksetSchema,
   computeTasksetHash
 } from "./chunk-QFT2MCIC.js";
@@ -12,7 +13,12 @@ import "./chunk-S7I45WJQ.js";
 import {
   TRAINING_EVALUATION_SOURCE_PATH,
   TrainingEvaluationSourceSchema,
-  assertTrainingEvaluationIsolation
+  assertTrainingEvaluationIsolation,
+  parseAndVerifyTrainingInputArtifactUpload,
+  parseAndVerifyTrainingJobSubmission,
+  trainingEvaluationSourceRef,
+  trainingInputArtifactUploadHash,
+  trainingJobSubmissionHash
 } from "./chunk-F5JBFRAH.js";
 import {
   HarnessSourceSelectionSchema,
@@ -134,6 +140,42 @@ var ResolvedTrainingBundleManifestSchema = ResolvedTrainingBundleContentSchema.e
   contentHash: ReleaseHashSchema
 }).strict();
 
+// src/training-privacy.ts
+var SECRET_PATTERNS = [
+  { label: "OpenAI-style API key", pattern: /\bsk-[A-Za-z0-9_-]{16,}\b/g },
+  { label: "OpenPond API key", pattern: /\bopk_[A-Za-z0-9_-]{12,}\b/g },
+  { label: "private key", pattern: /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/g },
+  { label: "credential assignment", pattern: /\b(?:api[_-]?key|password|secret|token)\s*[:=]\s*["']?[^\s"']{8,}/gi }
+];
+var EMAIL_PATTERN = /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi;
+var PHONE_PATTERN = /\b(?:\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]\d{3}[-.\s]\d{4}\b/g;
+function scanAndRedactEvidence(text) {
+  const findings = [];
+  let redacted = text;
+  for (const item of SECRET_PATTERNS) {
+    item.pattern.lastIndex = 0;
+    if (item.pattern.test(redacted)) findings.push(item.label);
+    item.pattern.lastIndex = 0;
+    redacted = redacted.replace(item.pattern, `[REDACTED ${item.label}]`);
+  }
+  EMAIL_PATTERN.lastIndex = 0;
+  const hasEmail = EMAIL_PATTERN.test(redacted);
+  EMAIL_PATTERN.lastIndex = 0;
+  if (hasEmail) findings.push("email address");
+  redacted = redacted.replace(EMAIL_PATTERN, "[REDACTED email]");
+  PHONE_PATTERN.lastIndex = 0;
+  const hasPhone = PHONE_PATTERN.test(redacted);
+  PHONE_PATTERN.lastIndex = 0;
+  if (hasPhone) findings.push("phone number");
+  redacted = redacted.replace(PHONE_PATTERN, "[REDACTED phone]");
+  return {
+    secretStatus: findings.some((finding) => !finding.includes("email") && !finding.includes("phone")) ? "blocked" : "passed",
+    piiStatus: hasEmail || hasPhone ? "review" : "passed",
+    findings,
+    redacted
+  };
+}
+
 // src/training-learning-batch.ts
 import { compileTaskBatch, learningRef, taskBatchPackageMetadata, verifyLearningTextAsset } from "@openpond/evals";
 function materializeLearningBatchTaskset(input) {
@@ -213,6 +255,301 @@ function fixtureOutcome(grade) {
   if (outcome.status !== "scored") return null;
   return { passed: outcome.passed === true, rewardEligible: grade.training.status === "scored" };
 }
+function prepareReviewedLearningBatch(input) {
+  const scan = scanAndRedactEvidence(JSON.stringify({
+    tasks: input.evidence.map((item) => item.submission),
+    targets: input.decisions.map((item) => item.approvedTarget),
+    definition: input.definition
+  }));
+  if (scan.secretStatus !== "passed" || scan.piiStatus !== "passed") throw new Error(`Learning batch contains unresolved data findings (${scan.findings.join(", ")}). Correct the source examples and seal a revised batch before training.`);
+  const source = LearningBatchDatasetSourceRefSchema.parse({
+    schemaVersion: "openpond.learningBatchDatasetSource.v1",
+    kind: "learning_batch",
+    id: `batch-source-${input.batch.contentHash.slice(0, 40)}`,
+    profileId: input.profileId,
+    title: input.definition.name,
+    sourceHash: input.batch.contentHash,
+    occurredAt: input.batch.sealedAt,
+    batch: learningRef(input.batch),
+    taskDefinition: input.batch.taskDefinition,
+    admittedBy: input.batch.sealedBy,
+    licensingStatus: "approved",
+    secretScanStatus: scan.secretStatus,
+    piiScanStatus: scan.piiStatus,
+    metadata: { admission: input.admissionContext ?? "explicit_local_batch_review", privacyScanner: "openpond-evidence-v1", findings: scan.findings }
+  });
+  return materializeLearningBatchTaskset({ ...input, source });
+}
+
+// src/managed-training-preparation.ts
+import { z as z2 } from "zod";
+async function prepareManagedTrainingSubmission(raw) {
+  const input = structuredClone(raw);
+  const { project, recipe, taskset, approval } = input;
+  const manifest = HarnessRunManifestSchema.parse(input.manifest);
+  const bundle = ResolvedTrainingBundleManifestSchema.parse(input.bundleManifest);
+  const { contentHash: manifestHash, ...manifestContent } = manifest;
+  const { contentHash: bundleHash, ...bundleContent } = bundle;
+  if (contentHash(manifestContent) !== manifestHash || contentHash(bundleContent) !== bundleHash || manifest.resolvedBundleHash !== bundleHash || contentHash(manifest.harnessRelease) !== contentHash(bundle.harnessRelease) || contentHash(manifest.datasetRelease) !== contentHash(bundle.datasetRelease) || contentHash(manifest.evidenceSets) !== contentHash(bundle.evidenceSetRelease ? [bundle.evidenceSetRelease] : [])) {
+    throw new Error("The managed training manifest or resolved bundle changed.");
+  }
+  if (!project.hosted || project.hosted.syncedSourceRevision !== project.revision || project.hosted.portableProjectId !== project.id) throw new Error("Sync the exact Model Project revision before preparing managed training.");
+  const baseModel = project.trainingSetup.baseModel;
+  if (!baseModel || baseModel.modelId !== manifest.model.source || baseModel.revision !== manifest.model.revision || baseModel.tokenizerRevision !== manifest.model.tokenizerRevision || baseModel.chatTemplateHash !== manifest.model.chatTemplateHash) {
+    throw new Error("The synced Model Project base Model does not match the Run manifest.");
+  }
+  if (recipe.method !== "grpo" || contentHash(recipe) !== manifest.recipe.configHash || approval.approvalHash !== manifest.approval.approvalHash || approval.maximumSpendUsd !== manifest.approval.maximumSpendUsd) {
+    throw new Error("Managed training requires the exact approved GRPO recipe and spend ceiling.");
+  }
+  const limits = z2.object({ wallTimeMs: z2.number().positive() }).parse(recipe.resourceLimits);
+  if (input.idempotencyKey !== void 0) z2.string().trim().min(16).max(191).parse(input.idempotencyKey);
+  const files = verifyFiles(bundle, input.files);
+  const evaluationSource = TrainingEvaluationSourceSchema.parse(input.evaluationSource);
+  const evaluationFile = files.find((file) => file.path === TRAINING_EVALUATION_SOURCE_PATH);
+  if (!evaluationFile || contentHash(JSON.parse(Buffer.from(evaluationFile.content, "base64").toString("utf8"))) !== contentHash(evaluationSource)) {
+    throw new Error("The evaluation source differs from the immutable training bundle.");
+  }
+  const evaluation = await trainingEvaluationSourceRef(evaluationSource);
+  const payload = {
+    schemaVersion: "openpond.managedRlPortableSubmission.v1",
+    sourceRunRef: `openpond:model-run:${manifest.id}`,
+    name: `OpenPond Managed \xB7 ${project.id}`.slice(0, 191),
+    idempotencyKey: input.idempotencyKey ?? `openpond-managed:${manifestHash}`.slice(0, 191),
+    modelProject: { id: project.hosted.projectId, portableProjectId: project.hosted.portableProjectId },
+    manifest,
+    sourceTaskset: taskset,
+    modelImprovementQualification: input.modelImprovementQualification ?? null,
+    recipe,
+    resolvedBundle: { manifest: bundle, files },
+    validationTasks: evaluationSource.tasks,
+    validationAssets: evaluationSource.assets
+  };
+  const artifactContent = {
+    schemaVersion: "openpond.trainingInputArtifactUpload.v2",
+    kind: "portable_training_bundle",
+    idempotencyKey: `stage:${input.idempotencyKey ?? manifestHash}`,
+    sourceManifest: { id: manifest.id, contentHash: manifestHash },
+    payload
+  };
+  const artifact = await parseAndVerifyTrainingInputArtifactUpload({ ...artifactContent, contentHash: await trainingInputArtifactUploadHash(artifactContent) });
+  const jobContent = {
+    schemaVersion: "openpond.trainingJobSubmission.v2",
+    idempotencyKey: input.idempotencyKey ?? `openpond-training-v2:${manifestHash}`,
+    name: `OpenPond Managed \xB7 ${project.id}`.slice(0, 200),
+    source: {
+      modelProject: { id: project.hosted.projectId, portableProjectId: project.hosted.portableProjectId, revision: project.revision, contentHash: project.hosted.etag },
+      harnessRunManifest: artifactContent.sourceManifest,
+      harnessRelease: manifest.harnessRelease,
+      taskset,
+      tasksetRelease: { id: taskset.id, contentHash: taskset.contentHash },
+      dataset: bundle.datasetRelease,
+      evaluation,
+      evidenceSets: bundle.evidenceSetRelease ? [bundle.evidenceSetRelease] : []
+    },
+    job: { kind: "policy_optimize", baseModel, recipe, rewardSource: input.rewardSource, resumeFrom: input.resumeFrom },
+    requestedCapabilities: [
+      { id: "managed_rl.policy.grpo", version: "1", required: true },
+      { id: `managed_rl.rollouts.${manifest.runtimeTarget.placement}`, version: "1", required: true },
+      ...project.trainingSetup.managedGpuRequirement === "h100_hbm3" ? [{ id: "managed_rl.gpu.h100_hbm3", version: "1", required: true }] : []
+    ],
+    placementObjective: project.trainingSetup.managedGpuPlacementObjective,
+    budget: { maximumSpendUsd: approval.maximumSpendUsd, maximumWallSeconds: Math.ceil(limits.wallTimeMs / 1e3) },
+    approval: { ...approval, approvedAt: manifest.approval.approvedAt, exportApproved: true }
+  };
+  const submission = await parseAndVerifyTrainingJobSubmission({ ...jobContent, contentHash: await trainingJobSubmissionHash(jobContent) });
+  return { artifact, submission };
+}
+function verifyFiles(bundle, files) {
+  if (files.length !== bundle.files.length || new Set(files.map((file) => file.path)).size !== files.length) throw new Error("The managed bundle file inventory changed.");
+  const indexed = new Map(files.map((file) => [file.path, file]));
+  return bundle.files.map((expected) => {
+    const file = indexed.get(expected.path);
+    if (!file || file.path.includes("\\") || file.path.includes("\0") || file.path.split("/").some((part) => !part || part === "." || part === "..") || file.path === "bundle-manifest.json" || file.encoding !== "base64") throw new Error("The managed bundle contains an invalid file.");
+    const bytes2 = Buffer.from(file.content, "base64");
+    if (bytes2.toString("base64") !== file.content || file.sha256 !== expected.sha256 || file.sizeBytes !== expected.sizeBytes || bytes2.byteLength !== expected.sizeBytes || sha256(bytes2) !== expected.sha256) throw new Error(`Managed training bundle file ${file.path} changed before upload.`);
+    return file;
+  });
+}
+
+// src/training-recipe-binding.ts
+import { z as z3 } from "zod";
+var AdamwOptimizerConfigSchema = z3.object({
+  name: z3.literal("adamw").default("adamw"),
+  weightDecay: z3.number().nonnegative().max(1).default(0),
+  beta1: z3.number().positive().lt(1).default(0.9),
+  beta2: z3.number().positive().lt(1).default(0.999),
+  epsilon: z3.number().positive().max(0.01).default(1e-8)
+}).strict().default({
+  name: "adamw",
+  weightDecay: 0,
+  beta1: 0.9,
+  beta2: 0.999,
+  epsilon: 1e-8
+});
+function withAuthoritativeRecipeHashes(taskset, recipe) {
+  if (!recipe || typeof recipe !== "object" || Array.isArray(recipe)) {
+    return recipe;
+  }
+  const candidate = recipe;
+  if (candidate.method === "dpo") {
+    const policyModel = record(candidate.policyModel);
+    const referenceModel = record(candidate.referenceModel);
+    const dataset2 = record(candidate.dataset);
+    const invalidationHash = contentHash({
+      tasksetHash: taskset.contentHash,
+      preferenceSignals: taskset.learningSignals.preferences.map((signal) => ({
+        id: signal.id,
+        artifactRef: signal.artifactRef,
+        prompt: signal.prompt,
+        chosen: signal.chosen,
+        rejected: signal.rejected,
+        approved: signal.approved
+      })),
+      policyModel,
+      referenceModel,
+      dataset: dataset2
+    });
+    return {
+      ...candidate,
+      referenceLogprobs: {
+        cacheSchemaVersion: "openpond.dpoReferenceLogprobs.v1",
+        cacheKey: contentHash(["dpo-reference-logprobs", invalidationHash]),
+        invalidationHash
+      }
+    };
+  }
+  if (candidate.method === "ppo") {
+    const policyOptimization = record(candidate.policyOptimization);
+    const policyModel = record(policyOptimization.policyModel);
+    const referenceModel = record(policyOptimization.referenceModel);
+    const optimizer2 = record(policyOptimization.optimizer);
+    const valueModel = record(optimizer2.valueModel);
+    const dataset2 = record(policyOptimization.dataset);
+    const reward2 = record(policyOptimization.reward);
+    const policyHash = contentHash(policyModel);
+    const referenceHash = contentHash(referenceModel);
+    const valueModelHash = contentHash(valueModel);
+    return {
+      ...candidate,
+      policyOptimization: {
+        ...policyOptimization,
+        dataset: {
+          ...dataset2,
+          tasksetId: taskset.id,
+          tasksetHash: taskset.contentHash
+        },
+        reward: {
+          ...reward2,
+          graderHash: contentHash(taskset.graders)
+        }
+      },
+      resume: {
+        ...record(candidate.resume),
+        policyHash,
+        referenceHash,
+        valueModelHash
+      }
+    };
+  }
+  if (candidate.method !== "grpo") return recipe;
+  const reward = candidate.reward && typeof candidate.reward === "object" && !Array.isArray(candidate.reward) ? candidate.reward : {};
+  const metadataToolContractHash = taskset.environment.metadata.toolContractHash;
+  const authoritativeToolContractHash = typeof metadataToolContractHash === "string" && metadataToolContractHash.trim() ? metadataToolContractHash : reward.toolContractHash;
+  const baseModel = record(candidate.baseModel);
+  const dataset = record(candidate.dataset);
+  const rollout = record(candidate.rollout);
+  const optimizer = record(candidate.optimizer);
+  const loss = record(candidate.loss);
+  const resourceLimits = record(candidate.resourceLimits);
+  const maxExamples = positiveInteger(dataset.maxExamples, 1);
+  const groupSize = positiveInteger(rollout.groupSize, 2);
+  const maxOutputTokens = positiveInteger(rollout.maxOutputTokens, 1);
+  const maxPromptTokens = positiveInteger(dataset.maxPromptTokens, 1);
+  const maxSteps = positiveInteger(optimizer.maxSteps, 1);
+  const optimizerIterations = positiveInteger(optimizer.iterations, 2);
+  return {
+    ...candidate,
+    resourceLimits: {
+      ...resourceLimits,
+      maxGpuSeconds: resourceLimits.maxGpuSeconds ?? Math.min(
+        10800,
+        Math.ceil(positiveInteger(resourceLimits.wallTimeMs, 18e4) / 1e3)
+      )
+    },
+    reward: {
+      ...reward,
+      graderHash: contentHash(taskset.graders),
+      toolContractHash: authoritativeToolContractHash
+    },
+    policyOptimization: {
+      schemaVersion: "openpond.policyOptimization.v1",
+      policyModel: baseModel,
+      referenceModel: baseModel,
+      dataset: {
+        tasksetId: taskset.id,
+        tasksetHash: taskset.contentHash,
+        split: "train",
+        selectionStrategy: dataset.selectionStrategy,
+        selectionSeed: rollout.seed,
+        maxExamples
+      },
+      sampler: {
+        temperature: rollout.temperature,
+        topP: rollout.topP,
+        maxOutputTokens,
+        maxTurns: rollout.maxTurns,
+        concurrency: rollout.concurrency
+      },
+      environment: {
+        id: reward.environmentId,
+        version: reward.environmentVersion,
+        toolContractHash: authoritativeToolContractHash
+      },
+      reward: {
+        graderId: reward.graderId,
+        graderHash: contentHash(taskset.graders),
+        learnedPreference: reward.learnedPreference ?? null
+      },
+      kl: {
+        coefficient: loss.klBeta ?? null,
+        referenceConstraint: "fixed_reference"
+      },
+      budgets: {
+        maxRollouts: positiveInteger(resourceLimits.maxRollouts, maxExamples * groupSize),
+        maxEnvironmentExecutions: positiveInteger(resourceLimits.maxRollouts, maxExamples * groupSize),
+        maxInputTokens: maxExamples * groupSize * maxPromptTokens,
+        maxOutputTokens: maxExamples * groupSize * maxOutputTokens,
+        maxOptimizerSteps: maxSteps * optimizerIterations,
+        wallTimeMs: positiveInteger(resourceLimits.wallTimeMs, 18e4),
+        maximumCostUsd: null
+      },
+      checkpointEverySteps: 1,
+      seed: rollout.seed,
+      evaluationSplit: "frozen_eval",
+      optimizer: {
+        method: "grpo",
+        groupSize,
+        normalization: "group_standardized",
+        advantageEpsilon: typeof optimizer.advantageEpsilon === "number" ? optimizer.advantageEpsilon : 1e-8,
+        loss: loss.method ?? "grpo",
+        clipRange: typeof optimizer.clipRange === "number" ? optimizer.clipRange : 0.2,
+        iterations: optimizerIterations,
+        microbatchSize: positiveInteger(optimizer.microbatchSize, 1),
+        gradientAccumulationSteps: positiveInteger(
+          optimizer.gradientAccumulationSteps,
+          1
+        ),
+        adamw: AdamwOptimizerConfigSchema.parse(optimizer.adamw)
+      }
+    }
+  };
+}
+function record(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function positiveInteger(value, fallback) {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : fallback;
+}
 
 // src/training-bundle.ts
 function buildTasksetTrainingBundle(input) {
@@ -444,6 +781,7 @@ function bytes(value) {
   return Buffer.from(canonicalJson(value), "utf8");
 }
 export {
+  AdamwOptimizerConfigSchema,
   ComputeTargetBindingSchema,
   HarnessRunManifestContentSchema,
   HarnessRunManifestSchema,
@@ -454,6 +792,10 @@ export {
   ScopedSecretDeclarationSchema,
   TrainingEngineBindingSchema,
   buildTasksetTrainingBundle,
-  materializeLearningBatchTaskset
+  materializeLearningBatchTaskset,
+  prepareManagedTrainingSubmission,
+  prepareReviewedLearningBatch,
+  scanAndRedactEvidence,
+  withAuthoritativeRecipeHashes
 };
 //# sourceMappingURL=training-bundle.js.map