Vercel AI SDK

npm install @oguardai/sdk ai

function guardedGenerateText(
  generate: (safePrompt: string) => Promise<GenerateTextLike | string> | GenerateTextLike | string,
  client: OGuardAIClient,
  prompt: string,
  options?: GuardedGenerateOptions,
): Promise<string>;

type GenerateTextLike = { text: string };

interface GuardedGenerateOptions {
  policy?: string;
  language?: string;
  outputChannel?: OutputChannel;
  restoreMode?: RestoreMode;
}

import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
import { OGuardAIClient } from "@oguardai/sdk";
import { guardedGenerateText } from "@oguardai/sdk/integrations/vercel";

const client = new OGuardAIClient({ baseUrl: "http://localhost:3000" });
const model = openai("gpt-4o-mini");

const reply = await guardedGenerateText(
  (safePrompt) => generateText({ model, prompt: safePrompt }),
  client,
  "Antworte Herrn Max Mustermann unter max.mustermann@firma.example",
  { policy: "german-support", language: "de", outputChannel: "customer_email" },
);

Antworte Herrn {{person:p_001:...}} unter {{email:e_001:...}}

cd examples/vercel-ts
pnpm install

export GUARDAI_URL="http://localhost:3000"
export GUARDAI_API_KEY="$GUARDAI_API_KEY_1"   # the bundled stack runs api_key auth

# Offline drafter (no LLM key needed): exercises transform + generate + rehydrate + per-channel + fail-closed
pnpm dev

# Live model: add a provider key first
export OPENAI_API_KEY="sk-..."
pnpm dev

import type { OutputChannel } from "@oguardai/sdk";

export const COMPANY = {
  name: "Musterfirma GmbH",
  assistant: "Vera",
  /** German formal policy: gender-aware salutations, level-1 data masked/redacted. */
  policy: process.env.CRM_POLICY ?? "german-support",
  /** German notes; the NER detector tags person gender and formality from this. */
  language: "de",
} as const;

/**
 * Output channels the copilot restores the one tokenized draft into. Each consumer sees
 * only what the policy allows for its channel (channel_rules only tighten, never widen),
 * so the same draft yields four different visibilities.
 */
export const CHANNELS = {
  /** The follow-up sent to the customer: full name (gender-aware), order, email; IBAN masked. */
  customer: "customer_email" satisfies OutputChannel,
  /** The rep's CRM timeline: name and order visible, contact details and IBAN masked. */
  crm: "internal_summary" satisfies OutputChannel,
  /** A downstream fulfilment system: minimum data, every entity masked. */
  tool: "tool_payload" satisfies OutputChannel,
  /** The audit log line: fully redacted, safe to persist in any log store. */
  audit: "log_safe" satisfies OutputChannel,
} as const;

/**
 * The inbound CRM note a rep captured after a call. It carries several real-looking PII
 * entities (person, email, IBAN, order number, phone) that must never reach the model.
 */
export const CRM_NOTE = [
  "Kunde Herr Max Mustermann (max.mustermann@example.de, Tel. +49 89 5512094)",
  "fragt nach dem Stand seiner Bestellung ORD-2026-58120 und der zugesagten Erstattung.",
  "Erstattung soll auf IBAN DE97 9900 0000 0123 4567 89 gehen. Bitte formelle Rueckmeldung.",
].join(" ");

/**
 * Mock CRM/order system, keyed by the REAL order number. It lives in the trusted zone:
 * the copilot only ever needs it host-side, and the status strings carry no PII, so they
 * are safe to weave into a token-domain draft.
 */
export const ORDER_DB: Record<string, { status: string; item: string; refundEur: number }> = {
  "ORD-2026-58120": {
    status: "Reklamation offen, Ersatzteil versandbereit",
    item: "Aluminium-Fensterrahmen",
    refundEur: 340,
  },
};

import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
import { ORDER_DB, COMPANY } from "./scenario.js";

const OPENAI_MODEL = process.env.OPENAI_MODEL ?? "gpt-4o-mini";

/** Every OGuardAI token: {{type:id:hash}}. Used to read tokens back out of safe_text. */
const TOKEN = /\{\{([a-z_]+):[^{}]+\}\}/g;

export function llmMode(): "openai" | "offline" {
  return process.env.OPENAI_API_KEY ? "openai" : "offline";
}

/**
 * The token contract handed to the model. It is load-bearing: the model must echo every
 * placeholder verbatim and must NOT write a salutation before a person token, because
 * OGuardAI injects the correct gendered "Herr"/"Frau" on restore.
 */
export const SYSTEM_PROMPT = [
  "Du bist ein CRM-Assistent und schreibst formelle deutsche Kunden-E-Mails.",
  "Die Eingabe enthaelt Platzhalter der Form {{typ:id:hash}}. Sie stehen fuer echte Daten,",
  "die du nicht sehen darfst. Regeln:",
  "1. Uebernimm jeden Platzhalter Zeichen fuer Zeichen unveraendert. Erfinde, vervollstaendige",
  "   oder formatiere niemals einen Platzhalter und schreibe niemals selbst einen echten Namen,",
  "   eine Nummer, eine E-Mail oder eine IBAN.",
  "2. Schreibe KEIN 'Herr', 'Frau' oder 'Sehr geehrte' vor einen person-Platzhalter. Die Laufzeit",
  "   setzt die korrekte Anrede selbst ein. Eroeffne mit 'Guten Tag {{person:...}},'.",
  "3. Erwaehne nur Platzhalter, die tatsaechlich vorkommen; erfinde keine Daten.",
].join("\n");

/** First token of each type found in a tokenized text, e.g. tokensByType(safe).person. */
function tokensByType(safeText: string): Record<string, string> {
  const found: Record<string, string> = {};
  for (const m of safeText.matchAll(TOKEN)) {
    const type = m[1];
    if (!(type in found)) found[type] = m[0];
  }
  return found;
}

/**
 * Deterministic stand-in for the model. It receives the tokenized prompt, reuses the exact
 * tokens it finds, and composes a formal German reply. The internal order status is looked
 * up host-side against an order NUMBER we resolve elsewhere; here we only key on presence,
 * so no PII is introduced by the draft.
 */
export function draftOffline(safePrompt: string): string {
  const t = tokensByType(safePrompt);
  const hasOrderRecord = Object.keys(ORDER_DB).length > 0;

  const lines: string[] = [];
  lines.push(t.person ? `Guten Tag ${t.person},` : "Guten Tag,");
  lines.push("");
  lines.push(
    t.order
      ? `vielen Dank fuer Ihre Nachricht zu Bestellung ${t.order}. Wir haben den Vorgang geprueft.`
      : "vielen Dank fuer Ihre Nachricht. Wir haben den Vorgang geprueft.",
  );
  if (hasOrderRecord && t.iban) {
    lines.push(
      `Die zugesagte Erstattung veranlassen wir auf Ihr Konto ${t.iban} innerhalb von 5 Werktagen.`,
    );
  }
  if (t.email) {
    lines.push(`Die Versandbestaetigung senden wir an ${t.email}.`);
  }
  lines.push("");
  lines.push("Mit freundlichen Gruessen");
  lines.push(`${COMPANY.assistant}, Kundenservice ${COMPANY.name}`);
  return lines.join("\n");
}

/** The live Vercel AI SDK generate call. Runs on tokenized `safePrompt` only. */
export async function draftWithModel(safePrompt: string): Promise<{ text: string }> {
  return generateText({
    model: openai(OPENAI_MODEL),
    system: SYSTEM_PROMPT,
    prompt: safePrompt,
    temperature: 0,
  });
}

import { strict as assert } from "node:assert";
import { OGuardAIClient, ValidationError } from "@oguardai/sdk";
import type { OutputChannel } from "@oguardai/sdk";
import { guardedGenerateText } from "@oguardai/sdk/integrations/vercel";
import { CHANNELS, COMPANY, CRM_NOTE } from "./scenario.js";
import { draftOffline, draftWithModel, llmMode } from "./model.js";

const guardaiUrl = process.env.GUARDAI_URL ?? process.env.GUARDAI_BASE_URL ?? "http://localhost:3000";
const client = new OGuardAIClient({ baseUrl: guardaiUrl, apiKey: process.env.GUARDAI_API_KEY });

/** Values the model must never see. The name needs NER, so a raw name in an offline run is a
 *  display-only note; the structured identifiers are caught by the built-in detectors, so a
 *  structured leak is a hard failure in every mode. */
const NER_PII = ["Max Mustermann"];
const STRUCTURED_PII = [
  "max.mustermann@example.de",
  "DE97 9900 0000 0123 4567 89",
  "ORD-2026-58120",
  "+49 89 5512094",
];
const RAW_PII = [...NER_PII, ...STRUCTURED_PII];

/** Any residual `{{...}}` on a customer-facing reply means an unresolved token; withhold it. */
const RESIDUAL_TOKEN = /\{\{[^{}]+\}\}/;

/** Run the model on tokenized text, in whichever mode is active. */
async function runModel(safePrompt: string): Promise<{ text: string } | string> {
  return llmMode() === "openai" ? draftWithModel(safePrompt) : draftOffline(safePrompt);
}

/** The structured identifiers are builtin-detectable, so any of them in a string bound for the
 *  model or a channel is a hard failure on every lane. Person names need NER, so a raw name is
 *  gated separately by the caller. Returns the raw names that crossed. */
function checkBoundary(text: string): string[] {
  for (const raw of STRUCTURED_PII) {
    assert.ok(!text.includes(raw), `structured PII leaked across the boundary: ${raw}`);
  }
  return NER_PII.filter((n) => text.includes(n));
}

// The generate closure is the only code that touches the model. Capture exactly what it
// received (the tokenized prompt) and what it returned (the tokenized draft) so we can prove
// the boundary held after guardedGenerateText finishes.
const capture: { seenByModel?: string; tokenizedDraft?: string } = {};
const generate = async (safePrompt: string): Promise<{ text: string } | string> => {
  capture.seenByModel = safePrompt;
  const out = await runModel(safePrompt);
  capture.tokenizedDraft = typeof out === "string" ? out : out.text;
  return out;
};

// The adapter: transform + generate + rehydrate, all with rehydration OUTSIDE the AI SDK.
const reply = await guardedGenerateText(generate, client, CRM_NOTE, {
  policy: COMPANY.policy,
  language: COMPANY.language,
  outputChannel: CHANNELS.customer,
});

const seenByModel = capture.seenByModel;
assert.ok(seenByModel, "the model was never called");
assert.ok(seenByModel.includes("{{"), "the model input carried no tokens");
const modelNameLeaks = checkBoundary(seenByModel);
const tokenizedDraft = capture.tokenizedDraft;
assert.ok(tokenizedDraft !== undefined, "the model returned no draft");
const draftNameLeaks = checkBoundary(tokenizedDraft);
assert.ok(!RESIDUAL_TOKEN.test(reply), "the restored reply still carries a token");

async function perChannel(nerAvailable: boolean): Promise<string[]> {
  const t = await client.transform({
    input: CRM_NOTE,
    policy: COMPANY.policy,
    language: COMPANY.language,
  });
  if (!t.session_state) {
    throw new ValidationError("transform returned no session_state; refusing per-channel demo (fail closed)");
  }

  const channelNameLeaks = checkBoundary(t.safe_text);
  gateNames(nerAvailable, channelNameLeaks);

  const out = await runModel(t.safe_text);
  const draft = typeof out === "string" ? out : out.text;

  const draftNameLeaks = checkBoundary(draft);
  gateNames(nerAvailable, draftNameLeaks);

  const restore = async (channel: OutputChannel): Promise<string> => {
    const r = await client.rehydrate({
      output: draft,
      session_state: t.session_state as string,
      output_channel: channel,
    });
    return r.restored_text;
  };

  const [customer, crm, tool, audit] = await Promise.all([
    restore(CHANNELS.customer),
    restore(CHANNELS.crm),
    restore(CHANNELS.tool),
    restore(CHANNELS.audit),
  ]);

  console.log(`\n[customer_email]   -> Kunde:\n${indent(customer, 4)}`);
  console.log(`\n[internal_summary] -> CRM-Verlauf:\n${indent(crm, 4)}`);
  console.log(`\n[tool_payload]     -> Fulfilment-System:\n${indent(tool, 4)}`);
  console.log(`\n[log_safe]         -> Audit-Log:\n${indent(audit, 4)}`);

  return [...channelNameLeaks, ...draftNameLeaks];
}

async function failClosed(): Promise<void> {
  // 1) A generate() that returns neither a string nor an object with a string `text` is rejected
  //    by the adapter, never returned as an unverified value.
  let noTextAccepted = false;
  try {
    await guardedGenerateText(
      () => ({ foo: 1 }) as unknown as { text: string },
      client,
      "Guten Tag, ich brauche Hilfe.",
      { policy: COMPANY.policy, language: COMPANY.language },
    );
    noTextAccepted = true;
  } catch (err) {
    const kind =
      err instanceof TypeError
        ? "TypeError"
        : err instanceof ValidationError
          ? `ValidationError (${err.code})`
          : (err as Error).constructor.name;
    console.log(`1) generate() liefert kein {text} -> abgewiesen: ${kind} (fail closed)`);
  }
  if (noTextAccepted) {
    throw new Error("fail-closed check failed: a generate() result without text was accepted");
  }

  const probe = await client.transform({
    input: "Kunde Herr Max Mustermann meldet sich zu seiner Bestellung.",
    policy: COMPANY.policy,
    language: COMPANY.language,
  });
  const personToken = probe.entities.find((e) => e.type === "person")?.token ?? "{{person:p_001:0000}}";
  const state = probe.session_state ?? "";

  // 2) A tampered session blob must be rejected, never silently restored.
  const tampered = `${state.slice(0, -40)}${"A".repeat(40)}`;
  let tamperAccepted = false;
  try {
    await client.rehydrate({
      output: `Guten Tag ${personToken}.`,
      session_state: tampered,
      output_channel: CHANNELS.customer,
    });
    tamperAccepted = true;
  } catch (err) {
    const label = err instanceof ValidationError ? `ValidationError (${err.code})` : String(err);
    console.log(`2) Manipuliertes session_state -> abgelehnt: ${label}`);
  }
  if (tamperAccepted) {
    throw new Error("fail-closed check failed: a tampered session was accepted");
  }

  // 3) A token the model invented is left verbatim and reported, never guessed.
  const invented = "{{person:p_999:deadbeef0000}}";
  const r = await client.rehydrate({
    output: `${personToken} und ${invented} melden sich.`,
    session_state: state,
    output_channel: CHANNELS.customer,
  });
  console.log(
    `3) Erfundener Token -> aufgeloest=${r.tokens_resolved} offen=[${(r.tokens_unresolved ?? []).join(", ")}]`,
  );
  if (!r.restored_text.includes(invented)) {
    throw new Error("fail-closed check failed: a forged token was resolved instead of left unresolved");
  }
}

Policy:    german-support   Sprache: de   LLM: offline

WAS DAS MODELL SIEHT (tokenisierter Prompt, kein Rohwert)
  Kunde Herr {{person:p_001:...}} ({{email:e_001:...}}, Tel. {{phone:ph_001:...}}) fragt nach
  dem Stand seiner Bestellung {{order:o_001:...}} ... IBAN {{iban:ib_001:...}} ...

ENTWURF DES MODELLS (noch tokenisiert)
  Guten Tag {{person:p_001:...}},
  vielen Dank fuer Ihre Nachricht zu Bestellung {{order:o_001:...}} ...

WIEDERHERGESTELLTE ANTWORT (Kanal customer_email)
  Guten Tag Herr Max Mustermann, ... Konto D*** **** **** **** **** *0 ...

PRO KANAL (dieselbe Antwort, verschiedene Sichtbarkeit)
[customer_email]   -> Guten Tag Herr Max Mustermann, ...
[internal_summary] -> ... an j*******************************e.
[tool_payload]     -> Guten Tag M** *********n, ... Bestellung O************0 ...
[log_safe]         -> Guten Tag [REDACTED], ... Bestellung [REDACTED] ...

FAIL-CLOSED
1) generate() liefert kein {text} -> abgewiesen: TypeError (fail closed)
2) Manipuliertes session_state -> abgelehnt: ValidationError (GUARDAI_INVALID_INPUT)
3) Erfundener Token -> aufgeloest=1 offen=[{{person:p_999:deadbeef0000}}]