Structured Output Comparison for Compatible App Chatbot APIs and One-Key SDKs

#ai #typescript #chatbot

Short answer: an OpenAI-compatible API or native SDK passes this edtech app chatbot gate only when it repeatedly turns the same sales-call transcript into schema-valid CRM actions; cost and latency are measured per accepted result, not per request.

For this job, the least complex useful design is a small runtime adapter followed by a validator and a human-review queue. The chatbot sends a transcript and a versioned schema to whichever model runtime is under test. The application then rejects unknown action types, missing owners, malformed dates, and evidence that cannot be traced to the transcript. Only accepted actions reach the CRM. That boundary matters more than a one-key promise because syntactically valid JSON can still express the wrong work.

This is deliberately narrow. A support bot, coding assistant, or open-ended tutor needs a different scorecard. Here the output must become an auditable sales operation: create a follow-up, record an objection, or leave the record alone.

Build the schema gate before comparing runtimes

Start with the contract. The runnable TypeScript below accepts unknown model output, validates a compact action shape, and returns either a typed action or explicit issues. It uses no vendor SDK, so the same gate can sit behind a compatible chat API, separate native SDKs, or a self-hosted runtime.

type CrmAction = {
  kind: "create_follow_up" | "record_objection" | "no_action";
  summary: string;
  ownerEmail: string | null;
  dueDate: string | null;
  evidenceQuote: string;
};

type ValidationResult =
  | { ok: true; value: CrmAction }
  | { ok: false; issues: string[] };

const allowedKinds = new Set<CrmAction["kind"]>([
  "create_follow_up",
  "record_objection",
  "no_action",
]);

function validateAction(input: unknown, transcript: string): ValidationResult {
  const issues: string[] = [];
  if (typeof input !== "object" || input === null || Array.isArray(input)) {
    return { ok: false, issues: ["output must be an object"] };
  }

  const value = input as Record<string, unknown>;
  const keys = new Set(Object.keys(value));
  for (const key of ["kind", "summary", "ownerEmail", "dueDate", "evidenceQuote"]) {
    if (!keys.has(key)) issues.push(`missing field: ${key}`);
  }
  for (const key of keys) {
    if (!["kind", "summary", "ownerEmail", "dueDate", "evidenceQuote"].includes(key)) {
      issues.push(`unknown field: ${key}`);
    }
  }

  if (typeof value.kind !== "string" || !allowedKinds.has(value.kind as CrmAction["kind"])) {
    issues.push("kind is not allowed");
  }
  if (typeof value.summary !== "string" || value.summary.trim().length < 8) {
    issues.push("summary is too short");
  }
  if (value.ownerEmail !== null && typeof value.ownerEmail !== "string") {
    issues.push("ownerEmail must be a string or null");
  }
  if (value.dueDate !== null &&
      (typeof value.dueDate !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(value.dueDate))) {
    issues.push("dueDate must use YYYY-MM-DD or be null");
  }
  if (typeof value.evidenceQuote !== "string" ||
      !transcript.includes(value.evidenceQuote)) {
    issues.push("evidenceQuote must be copied from the transcript");
  }

  return issues.length > 0
    ? { ok: false, issues }
    : { ok: true, value: value as CrmAction };
}

const transcript =
  "Buyer: Please send the district security checklist by Friday.";
const candidate: unknown = {
  kind: "create_follow_up",
  summary: "Send the district security checklist",
  ownerEmail: null,
  dueDate: null,
  evidenceQuote: "Please send the district security checklist by Friday.",
};

const result = validateAction(candidate, transcript);
if (!result.ok) {
  console.error(result.issues);
  process.exitCode = 2;
} else {
  console.log(result.value);
}

The date is null on purpose. “Friday” cannot be converted safely without the call date and timezone, and a runtime should not be rewarded for inventing either. This is the kind of semantic edge that disappears in a JSON-validity chart. The evidence check is intentionally strict too: it makes unsupported actions visible before they become CRM clutter.

A production schema will probably include account IDs, action IDs, confidence policy, and transcript spans. Keep the first version smaller than feels comfortable. Every optional field multiplies the combinations in the fixture set, while every required field creates a new rejection path.

How should an in-app chatbot compare compatible API and one-key SDK options?

Use one adapter contract and test each integration as a black box. The adapter should accept messages, a schema version, a deadline, and a stable request ID; it should return raw text, parsed data, token usage when reported, timing, and provider metadata. Preserve the raw response outside the CRM write path. You need it to explain why a candidate was rejected, but it must follow the same access and retention rules as the source call.

Don't assume “OpenAI-compatible” means identical behavior beyond the portion your test proves. Compatibility can reduce client-code changes, while native SDKs may expose controls that a common surface cannot represent. A one-key service can simplify credential management, but it also creates a shared dependency for routing and usage records. Those are testable trade-offs, not reasons to pick a winner in advance.

For Claude, Gemini, an OpenAI-compatible endpoint, or any other candidate, run the same frozen fixtures through the same validator. The names are labels in the test report, never branches in business logic. If a candidate needs a different prompt, record that prompt as part of its configuration; silently tuning one candidate more than another turns the comparison into theater.

I would score the run in this order:

Accepted action rate: the response parses, matches the schema, cites transcript evidence, and passes the domain rules.
Unsafe write rate: an unsupported or wrong action would have reached the CRM without the gate. This should be treated separately from harmless rejection.
Review burden: count rejected actions and ambiguous actions sent to a person.
Tail latency: measure the user-visible path, including retries and validation, rather than quoting a provider headline.
Cost per accepted action: include retries and rejected outputs. The cheapest request can be the expensive runtime when it creates more review work.

Averages hide pain. Keep distributions by transcript length, action kind, language, and schema version. I'm not sure which runtime will lead on a particular call corpus before that test runs, and nobody can settle it from an API label. Your mileage may vary as the sales script, model version, and prompt change.

Make correctness failures observable

Separate transport failure, parse failure, schema failure, evidence failure, and policy failure. They have different owners and different retry rules. A timeout might justify one bounded retry with the same request ID. A missing required field should go to review or a controlled repair pass. An evidence mismatch should never be “fixed” by deleting the evidence requirement.

Short labels help: transport_timeout, invalid_json, schema_rejected, evidence_missing, and policy_rejected. Store the schema version, prompt version, runtime configuration, validation issues, latency, and final disposition with each evaluation record. Avoid logging an entire transcript by default — sales calls can contain names, email addresses, contract terms, and student-related context. Redacted fixture IDs are enough for dashboards.

There is a nasty false-positive case worth testing in detail. Suppose the buyer says, “We can't schedule training until legal approves the data agreement,” and later asks for the agreement. A fluent summary may create a training meeting for next week because that resembles a useful next step. The JSON can be flawless. The action is still wrong: the prerequisite has not happened, the date is absent, and the requested work is to send a document. Your fixture should include both a valid create_follow_up for the agreement and an invalid training action, then require the evidence quote to support the chosen kind. One transcript like this teaches more than fifty happy-path greetings.

Keep malformed fixtures too: truncated transcripts, two speakers assigning different owners, negated requests, relative dates without timezone context, and calls with no action. Return no_action when the evidence does not support a write. Fail closed.

Operate the comparison as a release gate

A static leaderboard goes stale as soon as a prompt, schema, or runtime configuration changes. Put a small, versioned fixture suite in continuous integration and a larger replay set in a scheduled job. The OpenAI Batch API guide is relevant to asynchronous evaluation design, but a batch mechanism should stay outside the live chatbot path; the user-facing request still needs its own deadline and fallback policy.

Promote a candidate only when it meets thresholds for every critical slice, not just the aggregate. Run a shadow phase that validates proposed actions without writing them, then canary a limited share behind an idempotent CRM command. The command should reject a duplicate action ID, so an application retry cannot create two follow-ups. Keep a kill switch that routes uncertain results to review instead of choosing another runtime blindly.

The catch is operational complexity. A multi-runtime adapter is not suitable when the team cannot maintain shared fixtures, prompt versions, credential rotation, and per-runtime observability. In that case, stick with one native SDK and put the schema gate around it. Choose a compatible API when portability is worth testing the common surface; choose separate native SDKs when runtime-specific controls materially improve accepted output. A one-key gateway fits when centralized credentials and switching are worth the extra dependency. None of these options removes validation.

Before release, read the checklist as a sentence, not a ceremony: freeze representative transcripts, remove sensitive data, version the prompt and schema, test every candidate through one validator, inspect failures by category, calculate cost per accepted action, exercise timeout and duplicate-write behavior, shadow real traffic, and define the rollback threshold. Then rerun it after any model or prompt change.

That's enough machinery.