🤝 TrustCallJS

TypeScript port of trustcall - Utilities for validated tool calling and extraction with retries using LLMs.

Built on top of @langchain/langgraph.

Installation

``bash
npm install trustcalljs @langchain/langgraph @langchain/core
`

Why TrustCallJS?

Tool calling makes it easier to compose LLM calls within reliable software systems, but LLMs today can be error prone and inefficient in two common scenarios:

1. Populating complex, nested schemas - LLMs often make validation errors on deeply nested structures
2. Updating existing schemas without information loss - Regenerating entire objects can lose important data

TrustCallJS solves these problems using JSONPatch to correct validation errors, reducing costs and improving reliability.

Quick Start

`typescript
import { z } from "zod";
import { ChatOpenAI } from "@langchain/openai";
import { createExtractor } from "trustcalljs";

// Define your schema
const UserInfo = z.object({
name: z.string().describe("User's full name"),
age: z.number().describe("User's age in years"),
}).describe("UserInfo");

// Create the extractor
const llm = new ChatOpenAI({ model: "gpt-4o-mini" });
const extractor = createExtractor(llm, {
tools: [UserInfo],
});

// Extract structured data - simplest form with a string
const result = await extractor.invoke(
"My name is Alice and I'm 30 years old"
);

console.log(result.responses[0]);
// { name: "Alice", age: 30 }
`

Input Formats

The extractor supports multiple input formats:

`typescript
// 1. Simple string (converted to HumanMessage internally)
const result = await extractor.invoke("My name is Alice and I'm 30");

// 2. Single BaseMessage
import { HumanMessage } from "@langchain/core/messages";
const result = await extractor.invoke(
new HumanMessage("My name is Alice and I'm 30")
);

// 3. Array of BaseMessage (LangGraph MessagesValue compatible)
const result = await extractor.invoke({
messages: [new HumanMessage("My name is Alice and I'm 30")],
});

// 4. OpenAI-style message dict format
const result = await extractor.invoke({
messages: [{ role: "user", content: "My name is Alice and I'm 30" }],
});

// 5. With existing data for updates
const result = await extractor.invoke({
messages: [{ role: "user", content: "Change my age to 31" }],
existing: { UserInfo: { name: "Alice", age: 30 } },
});
`

Features

$3

TrustCallJS handles complex, deeply nested schemas that often cause validation errors:

`typescript
const TelegramPreferences = z.object({
communication: z.object({
telegram: z.object({
preferredEncoding: z.enum(["morse", "standard"]),
paperType: z.string().optional(),
}),
semaphore: z.object({
flagColor: z.string(),
}),
}),
}).describe("TelegramPreferences");

const extractor = createExtractor(llm, {
tools: [TelegramPreferences],
});

// Even with complex schemas, TrustCallJS will retry and fix validation errors
const result = await extractor.invoke({
messages: Extract preferences from:
User: I'd like morse code on daredevil paper,
});
`

$3

Update existing schemas without losing information:

`typescript
const UserPreferences = z.object({
name: z.string(),
favoriteColors: z.array(z.string()),
settings: z.object({
notifications: z.boolean(),
theme: z.enum(["light", "dark"]),
}),
}).describe("UserPreferences");

const existing = {
UserPreferences: {
name: "Alice",
favoriteColors: ["blue", "green"],
settings: {
notifications: true,
theme: "light",
},
},
};

const extractor = createExtractor(llm, {
tools: [UserPreferences],
enableUpdates: true,
});

const result = await extractor.invoke({
messages: [{ role: "user", content: "I now prefer dark theme and add purple to my colors" }],
existing,
});

// Result preserves existing data while applying updates:
// {
// name: "Alice",
// favoriteColors: ["blue", "green", "purple"],
// settings: { notifications: true, theme: "dark" }
// }
`

$3

TrustCallJS automatically:
- Validates tool call outputs against your schemas
- Generates JSONPatch operations to fix validation errors
- Retries with corrections up to a configurable maximum

`typescript
const extractor = createExtractor(llm, {
tools: [MySchema],
});

// Configure max retry attempts
const result = await extractor.invoke(
{ messages: "..." },
{ configurable: { max_attempts: 5 } }
);

// Check how many attempts were needed
console.log(Extraction completed in ${result.attempts} attempts);
`

API Reference

$3

Creates an extractor runnable.

Parameters:
- llm: A LangChain chat model (e.g., ChatOpenAI, ChatAnthropic)
- options: Extractor configuration
- tools: Array of Zod schemas, structured tools, or functions
- toolChoice?: Force a specific tool to be used
- enableInserts?: Allow creating new schemas when updating (default: false)
- enableUpdates?: Allow updating existing schemas (default: true)
- enableDeletes?: Allow deleting existing schemas (default: false)
- existingSchemaPolicy?: How to handle unknown existing schemas (default: true)

Returns: An extractor with invoke() and stream() methods.

$3

`typescript
interface ExtractionOutputs {
messages: AIMessage[]; // The AI messages with tool calls
responses: unknown[]; // Validated schema instances
responseMetadata: Array<{ // Metadata about each response
id: string;
jsonDocId?: string;
}>;
attempts: number; // Number of extraction attempts
}
`

$3

A standalone validation node for use in custom graphs:

`typescript
import { ValidationNode } from "trustcalljs";

const validator = new ValidationNode([UserInfo, Preferences], {
formatError: (error, call, schema) => Custom error: ${error.message},
});

const result = await validator.invoke({ messages });
``

How It Works

1. Initial Extraction: The LLM generates tool calls based on input
2. Validation: Tool calls are validated against Zod schemas
3. Error Detection: Validation errors are detected and formatted
4. Patch Generation: The LLM generates JSONPatch operations to fix errors
5. Application: Patches are applied to the original arguments
6. Retry: The process repeats until validation passes or max attempts reached

This approach is more efficient than regenerating entire outputs because:
- Only the failing parts are regenerated
- Existing correct data is preserved
- Fewer output tokens are needed for fixes

License

MIT