Function calling (OpenAI and Anthropic)

npm i @constaia/sdk openai @anthropic-ai/sdk

import { Constaia, ConstaiaError } from "@constaia/sdk";

const constaia = new Constaia(); // reads CONSTAIA_API_KEY

export const ALLOWED_TYPES = ["es_dni", "es_nie", "passport", "medical_certificate_sport", "payment_receipt"];
const ALLOWED_URL_PREFIXES = ["https://files.example.com/uploads/"];
const KEY_FIELDS = [
  "document_number", "nie_number", "first_name", "last_name", "last_name_1", "last_name_2",
  "birth_date", "expiry_date", "issue_date", "amount", "currency",
];

export const TOOL_NAME = "validate_document";
export const TOOL_DESCRIPTION =
  "Validates a document uploaded by the user (Spanish DNI, NIE, passport, sports medical certificate or " +
  "payment receipt). Returns the verdict valid, invalid or review, the reasons and the key data.";

export const TOOL_SCHEMA = {
  type: "object",
  properties: {
    file_url: { type: "string", description: "https URL of the document, exactly as the application provides it." },
    expect: {
      type: "array",
      items: { type: "string", enum: ALLOWED_TYPES },
      minItems: 1,
      description: "Acceptable document types.",
    },
    checks: {
      type: "object",
      description: "Optional rules the document must meet.",
      properties: {
        not_expired: { type: "boolean" },
        min_age_years: { type: "integer" },
        max_age_days: { type: "integer", description: "Maximum age of the issue date, in days." },
        holder: {
          type: "object",
          properties: {
            full_name: { type: "string" },
            document_number: { type: "string" },
            birth_date: { type: "string", description: "YYYY-MM-DD" },
          },
          additionalProperties: false,
        },
        expected_amount: { type: "number" },
        expected_reference: { type: "string" },
      },
      additionalProperties: false,
    },
  },
  required: ["file_url", "expect"],
  additionalProperties: false,
};

function toSdkChecks(checks = {}) {
  const { holder } = checks;
  return {
    notExpired: checks.not_expired,
    minAgeYears: checks.min_age_years,
    maxAgeDays: checks.max_age_days,
    expectedAmount: checks.expected_amount,
    expectedReference: checks.expected_reference,
    holder: holder
      ? { fullName: holder.full_name, documentNumber: holder.document_number, birthDate: holder.birth_date }
      : undefined,
  };
}

export async function runValidateDocument(input) {
  const fileUrl = input?.file_url;
  const expect = [].concat(input?.expect ?? []);
  if (typeof fileUrl !== "string" || !ALLOWED_URL_PREFIXES.some((p) => fileUrl.startsWith(p))) {
    return { error: "file_url not allowed: only documents uploaded to the application are accepted." };
  }
  if (expect.length === 0 || !expect.every((t) => ALLOWED_TYPES.includes(t))) {
    return { error: `expect may only contain: ${ALLOWED_TYPES.join(", ")}` };
  }

  try {
    const analysis = await constaia.analyze(
      { fileUrl },
      { expect, checks: toSdkChecks(input.checks ?? {}), language: "en" },
    );
    return {
      analysis_id: analysis.id,
      status: analysis.status, // "queued" or "processing" if it didn't finish within 30 s
      document_type: analysis.document?.type ?? null,
      verdict: analysis.verdict?.status ?? null,
      reasons: (analysis.verdict?.reasons ?? []).map(({ code, severity, message }) => ({ code, severity, message })),
      fields: Object.fromEntries(
        KEY_FIELDS.filter((name) => analysis.fields?.[name]).map((name) => [name, analysis.fields[name].value]),
      ),
      warnings: analysis.warnings ?? [],
    };
  } catch (error) {
    if (error instanceof ConstaiaError) {
      return { error: `${error.code ?? error.type}: ${error.message}`, request_id: error.requestId };
    }
    throw error;
  }
}

import OpenAI from "openai";
import { TOOL_DESCRIPTION, TOOL_NAME, TOOL_SCHEMA, runValidateDocument } from "./constaia-tool.js";

const openai = new OpenAI(); // reads OPENAI_API_KEY
const model = process.env.OPENAI_MODEL ?? "gpt-4.1";

const tools = [
  { type: "function", function: { name: TOOL_NAME, description: TOOL_DESCRIPTION, parameters: TOOL_SCHEMA } },
];

const messages = [
  {
    role: "system",
    content:
      "You help review registrations. Use validate_document to check documents. " +
      "If verdict is review or status is not completed, say the document is pending review.",
  },
  {
    role: "user",
    content: "Check that https://files.example.com/uploads/dni_valid.jpg is a valid DNI of an adult.",
  },
];

for (let turn = 0; turn < 5; turn++) {
  const completion = await openai.chat.completions.create({ model, messages, tools });
  const message = completion.choices[0].message;
  messages.push(message);

  if (!message.tool_calls?.length) {
    console.log(message.content);
    break;
  }

  for (const call of message.tool_calls) {
    let result;
    if (call.function.name !== TOOL_NAME) {
      result = { error: `Unknown tool: ${call.function.name}` };
    } else {
      try {
        result = await runValidateDocument(JSON.parse(call.function.arguments));
      } catch {
        result = { error: "The document could not be validated." };
      }
    }
    messages.push({ role: "tool", tool_call_id: call.id, content: JSON.stringify(result) });
  }
}

import Anthropic from "@anthropic-ai/sdk";
import { TOOL_DESCRIPTION, TOOL_NAME, TOOL_SCHEMA, runValidateDocument } from "./constaia-tool.js";

const anthropic = new Anthropic(); // reads ANTHROPIC_API_KEY

const tools = [{ name: TOOL_NAME, description: TOOL_DESCRIPTION, input_schema: TOOL_SCHEMA }];
const system =
  "You help review registrations. Use validate_document to check documents. " +
  "If verdict is review or status is not completed, say the document is pending review.";

const messages = [
  {
    role: "user",
    content: "Check that https://files.example.com/uploads/dni_valid.jpg is a valid DNI of an adult.",
  },
];

for (let turn = 0; turn < 5; turn++) {
  const response = await anthropic.messages.create({
    model: "claude-sonnet-4-5",
    max_tokens: 1024,
    system,
    tools,
    messages,
  });
  messages.push({ role: "assistant", content: response.content });

  if (response.stop_reason !== "tool_use") {
    console.log(response.content.filter((b) => b.type === "text").map((b) => b.text).join("\n"));
    break;
  }

  const results = [];
  for (const block of response.content) {
    if (block.type !== "tool_use") continue;
    let result;
    try {
      result =
        block.name === TOOL_NAME
          ? await runValidateDocument(block.input)
          : { error: `Unknown tool: ${block.name}` };
    } catch {
      result = { error: "The document could not be validated." };
    }
    results.push({
      type: "tool_result",
      tool_use_id: block.id,
      content: JSON.stringify(result),
      is_error: Boolean(result.error),
    });
  }
  messages.push({ role: "user", content: results });
}