@cadia-platforms/prix-sdk

Cadia PRIX-SDK

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

PRIX stands for Production Reasoning Intelligence eXecution. It governs how production AI improves by routing verified failures to the right operational or training layer.

PRIX 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/prix-sdk

Requires Node.js 18 or newer.

Existing @cadia-platforms/connect-sdk integrations can migrate without changing Cadia routes, key prefixes, or environment variables. createConnectClient remains available as a deprecated alias in PRIX-SDK.

What the SDK sends

• Model inputs and outputs that your server chooses to report.
• Tool calls, tool failures, latency, confidence, and metadata.
• Approved evidence and source-truth snippets.
• 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 PRIX keys in browser code.

Basic usage

import { createPrixClient } from "@cadia-platforms/prix-sdk";

const cadia = createPrixClient({
  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 cadia.signal({
  input: userMessage,
  output: modelResponse.text,
  latencyMs: modelResponse.latencyMs,
  tools: modelResponse.tools,
  metadata: {
    route: "support-chat",
  },
});

Keys

• CADIA_CONNECT_INGEST_KEY: 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,
});

PRIX 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

PRIX 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 = createPrixClient({
  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 PRIX 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. PRIX authorizes and describes the work; customer code applies the versioned change to the real destination and reports what happened.

const runner = createPrixClient({
  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, PRIX 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 = createPrixClient({
  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 { PrixApiError } from "@cadia-platforms/prix-sdk";

try {
  await cadia.health();
} catch (error) {
  if (error instanceof PrixApiError) {
    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.