Cadia KeyEdit

Server-side SDK for connecting an AI application to Cadia KeyEdit.

KeyEdit is Cadia's governed production-improvement system. It validates candidate responses and proposed actions before release, safely intervenes under the customer's policy, turns verified failures into durable improvements at the correct authorized layer, and records every intervention and edit with evidence and rollback history.

KeyEdit does not require customers to hand over their model. The SDK runs beside the customer's existing AI endpoint and sends model behavior, evidence, tool outcomes, and runner-scoped training work to Cadia.

Install

npm install @cadia-platforms/keyedit

Requires Node.js 18 or newer.

Existing @cadia-platforms/offedit, @cadia-platforms/connect-sdk, @cadia-platforms/prix-sdk, and @cadia-platforms/florell-sdk integrations can migrate without changing Cadia routes, key prefixes, or environment variables. createOffEditClient, createConnectClient, createPrixClient, and createFlorellClient remain available as deprecated aliases.

What the SDK sends

• Model inputs and outputs that your server chooses to report.
• Candidate responses and proposed tool calls submitted for validation before release.
• Tool calls, tool failures, latency, confidence, and metadata.
• Approved evidence and source-truth snippets.
• Delivery outcomes for protected responses and proposed actions.
• Runner-scoped, authorized production work and authenticated execution receipts.
• Training-pack, replay, verification, and adapter status for tunable models.

The SDK is server-side only. Do not use KeyEdit keys in browser code.

Protect responses before release

Call protectText after the model generates a candidate response and before your application sends that response to the end user. KeyEdit returns a deterministic decision: pass, correct, regenerate, abstain, block, escalate, or observe.

import { createKeyEditClient } from "@cadia-platforms/keyedit";

const keyedit = createKeyEditClient({
  apiBase: process.env.CADIA_API_BASE,
  workspaceId: process.env.CADIA_WORKSPACE_ID!,
  ingestKey: process.env.CADIA_CONNECT_INGEST_KEY!,
});

const candidate = await callYourModel(userMessage);
const protectedResponse = await keyedit.protectText({
  idempotencyKey: crypto.randomUUID(),
  userInput: userMessage,
  candidateResponse: candidate.text,
  modelProvider: candidate.provider,
  modelId: candidate.model,
  sourceTruthIds: approvedSourceTruthIds,
  metadata: {
    route: "support-chat",
  },
});

if (protectedResponse.requiresRegeneration) {
  // Regenerate with the returned directive, then submit the new candidate
  // through protectText before release.
  const regenerated = await regenerateYourModel(
    protectedResponse.preflight.regenerationDirective
  );
}

if (protectedResponse.releasedContent !== null) {
  await sendToEndUser(protectedResponse.releasedContent);
}

if (protectedResponse.preflight.interventionId) {
  await keyedit.reportRuntimeOutcome({
    idempotencyKey: crypto.randomUUID(),
    interventionId: protectedResponse.preflight.interventionId,
    deliveryStatus:
      protectedResponse.releasedContent !== null
        ? "delivered"
        : "not_delivered",
    delivered: protectedResponse.releasedContent !== null,
    finalContent: protectedResponse.releasedContent ?? undefined,
  });
}

Never release the original candidate as a fallback after KeyEdit returns correct, regenerate, abstain, block, or escalate. protectText returns only content that the runtime policy allows the application to release.

Use protectToolCall before executing a model-proposed action:

const protectedAction = await keyedit.protectToolCall({
  idempotencyKey: crypto.randomUUID(),
  userInput: userMessage,
  proposedToolCall: {
    name: "refundOrder",
    operation: "orders.refund",
    arguments: { orderId, amount },
  },
  riskHints: {
    level: "high",
    domain: "payments",
    highImpactAction: true,
  },
});

if (protectedAction.releasedToolCall) {
  // Customer application code, not KeyEdit preflight, executes the action.
  await executeApprovedToolCall(protectedAction.releasedToolCall);
}

KeyEdit validates proposed tool calls but never executes them during preflight.

For streaming responses, send ordered chunks through runtimePreflightChunk. KeyEdit buffers content according to the workspace policy and returns only content that is ready for release:

const checked = await keyedit.runtimePreflightChunk({
  idempotencyKey: `stream-${streamId}-${sequenceNumber}`,
  userInput: userMessage,
  streamId,
  chunk,
  sequenceNumber,
  streamingState: isFinalChunk ? "final" : "partial",
});

if (checked.data.releaseAllowed && checked.data.finalContent) {
  await writeStreamChunk(checked.data.finalContent);
}

Runtime interventions are temporary release decisions. Verified failures can queue durable remediation, but permanent changes to a customer system still require evidence, Change Authority, and a registered healthy production target.

Basic usage

import { createKeyEditClient } from "@cadia-platforms/keyedit";

const keyedit = createKeyEditClient({
  apiBase: process.env.CADIA_API_BASE,
  workspaceId: process.env.CADIA_WORKSPACE_ID!,
  ingestKey: process.env.CADIA_CONNECT_INGEST_KEY!,
  runnerKey: process.env.CADIA_CONNECT_RUNNER_KEY,
  defaultProvider: "openai",
  defaultModel: "gpt-4.1-mini",
});

const modelResponse = await callYourModel(userMessage);

await keyedit.signal({
  input: userMessage,
  output: modelResponse.text,
  latencyMs: modelResponse.latencyMs,
  tools: modelResponse.tools,
  metadata: {
    route: "support-chat",
  },
});

Keys

• CADIA_CONNECT_INGEST_KEY: validates candidates before release, reports runtime outcomes, and sends model events and evidence.
• CADIA_CONNECT_RUNNER_KEY: leases authorized production work, submits receipts and measured verification, and runs customer-controlled tuning work.
• CADIA_CONNECT_ADMIN_KEY: control-plane administration. Use only in trusted admin services, never in ordinary inference code.

Environment

CADIA_API_BASE=https://api.cadiaai.com
CADIA_WORKSPACE_ID=your_workspace_id
CADIA_CONNECT_INGEST_KEY=cdi_...
CADIA_CONNECT_RUNNER_KEY=cdr_...

Direct events

await cadia.signal({
  idempotencyKey: "chat-run-123",
  input: "Does Starter include SSO?",
  output: "Yes, Starter includes SSO.",
  provider: "groq",
  model: "llama-3.3-70b-versatile",
  expected: "SSO is Enterprise-only.",
  score: 0.4,
});

KeyEdit uses reported behavior, evidence, source truth, tool results, user corrections, and evaluator results to decide the correct improvement layer: memory, retrieval/context, policy/behavior, tool workflow, evaluator logic, training pack, adapter tuning, or no change.

Batch events

Large batches are chunked automatically.

await cadia.signalBatch({
  idempotencyKey: "batch-2026-06-16",
  events: modelRuns.map((run) => ({
    input: run.input,
    output: run.output,
    latencyMs: run.latencyMs,
    tools: run.tools,
  })),
});

Evidence

await cadia.evidence({
  title: "Billing plan source truth",
  content: "SSO is only available on Enterprise plans.",
  source: "approved docs",
  sourceUrl: "https://docs.example.com/plans",
});

Register production destinations

KeyEdit needs an explicit destination for every layer it may change. Register targets from a trusted admin service. Do not embed the admin key in inference code or a customer-facing browser.

const admin = createKeyEditClient({
  workspaceId: process.env.CADIA_WORKSPACE_ID!,
  adminKey: process.env.CADIA_CONNECT_ADMIN_KEY!,
});

const target = await admin.createTarget({
  name: "Production support retrieval",
  improvementLayer: "retrieval_context",
  connectorType: "customer_runner",
  environment: "production",
  capabilities: ["upsert", "version_restore"],
  allowedOperations: ["retrieval.upsert", "retrieval.restore"],
  configuration: {
    provider: "pinecone",
    index: "support",
    namespace: "production",
  },
  currentVersion: "retrieval-v1",
});

Target configuration may contain identifiers and routing metadata, but never plaintext credentials. Use secretRef: "env:YOUR_SECRET_NAME" when the customer's runner needs a secret from its own environment.

Then define the workspace authority policy. This is the permission boundary KeyEdit evaluates before any work can be leased:

await admin.setExecutionAuthority({
  autonomyMode: "guarded",
  allowedTargetIds: [(target.data as { id: string }).id],
  allowedLayers: ["retrieval_context"],
  allowedOperations: ["retrieval.upsert", "retrieval.restore"],
  riskCeiling: "medium",
  minimumConfidence: 0.85,
  requireSourceTruth: true,
  protectedDomains: ["billing", "legal"],
  highRiskPreauthorized: false,
  requireReplay: true,
  incidentRetentionDays: 30,
  redactionFields: ["user.email", "user.phone"],
});

Customer runner

The runner lives in the customer's environment and uses only the runner key. KeyEdit authorizes and describes the work; customer code applies the versioned change to the real destination and reports what happened.

const runner = createKeyEditClient({
  workspaceId: process.env.CADIA_WORKSPACE_ID!,
  runnerKey: process.env.CADIA_CONNECT_RUNNER_KEY!,
});

await runner.heartbeatTarget({
  id: process.env.CADIA_TARGET_ID!,
  healthy: true,
  currentVersion: await readCurrentRetrievalVersion(),
});

const leased = await runner.leaseExecutions({
  targetIds: [process.env.CADIA_TARGET_ID!],
  maxItems: 1,
  leaseSeconds: 60,
});

for (const work of (leased.data as { items: Array<any> }).items) {
  const startedAt = new Date().toISOString();
  const applied = await applyAuthorizedChangeToCustomerAsset(work);

  await runner.submitExecutionReceipt({
    executionId: work.execution.id,
    leaseToken: work.leaseToken,
    receipt: {
      receiptId: crypto.randomUUID(),
      executionId: work.execution.id,
      targetId: work.target.id,
      idempotencyKey: work.changeSpec.idempotencyKey,
      previousVersion: applied.previousVersion,
      resultingVersion: applied.resultingVersion,
      appliedOperation: work.changeSpec.operation,
      appliedDiffHash: applied.diffHash,
      startedAt,
      finishedAt: new Date().toISOString(),
      status: "succeeded",
      externalAssetRefs: applied.assetRefs,
      rollbackHandle: applied.rollbackHandle,
    },
  });

  const measurement = await runCustomerCanary(work);
  await runner.submitExecutionVerification({
    executionId: work.execution.id,
    submission: measurement,
  });
}

The receipt records the actual external asset and version changed. Verification must contain measured results from replay, holdout, shadow, canary, business KPI, customer evaluator, or recurrence monitoring. Projected demo lift is not a substitute for production measurement.

Incident replay

Customer runners can reproduce captured incidents and submit baseline and candidate results:

const replayWork = await runner.leaseReplays({
  targetIds: [process.env.CADIA_TARGET_ID!],
  leaseSeconds: 60,
});

for (const replay of (replayWork.data as { work: Array<any> }).work) {
  const result = await reproduceIncident(replay);
  await runner.submitReplayResult({
    replayId: replay.replay.id,
    leaseToken: replay.leaseToken,
    phase: "candidate",
    output: result.output,
    measuredScore: result.score,
    sampleCount: result.sampleCount,
    evaluatorVersion: result.evaluatorVersion,
    exactReproduction: result.exact,
    uncertainty: result.uncertainty,
    reproducibilityLimitations: result.limitations,
    regressionResults: result.regressions,
  });
}

Training work

Training work also uses the runner key and remains separate from ordinary inference events.

await runner.runnerPing();

const packs = await runner.listTrainingPacks({ limit: 10 });
const latestAdapter = await runner.latestAdapterRun();

await runner.createAdapterRun({
  status: "succeeded",
  trainingPackId: "pack-123",
  baseModel: "llama-3.1-8b",
  adapter: {
    id: "adapter-run-123",
  },
  metrics: {
    evalLift: 0.08,
  },
});

For closed hosted models, KeyEdit cannot modify weights. It can still improve behavior through memory, retrieval, policies, tool workflows, evaluators, and monitored context updates. For tunable open or customer-controlled models, the runner can execute approved adapter/LoRA work in the customer's environment.

Retries and redaction

The SDK retries transient network, rate-limit, and server errors by default. You can tune retry behavior and redact payloads before they are sent:

const cadia = createKeyEditClient({
  workspaceId: process.env.CADIA_WORKSPACE_ID!,
  ingestKey: process.env.CADIA_CONNECT_INGEST_KEY!,
  retry: {
    retries: 2,
    baseDelayMs: 250,
    maxDelayMs: 2500,
  },
  redact(payload) {
    return redactCustomerSecrets(payload);
  },
});

Error handling

import { KeyEditApiError } from "@cadia-platforms/keyedit";

try {
  await cadia.health();
} catch (error) {
  if (error instanceof KeyEditApiError) {
    console.error(error.status, error.data, error.requestId);
  }
}

Publishing checklist

Before publishing:

1. Run npm ci.
2. Run npm test.
3. Run npm run build.
4. Run npm pack --dry-run.
5. Publish when ready with the Cadia npm organization.