Install & Compatibility
Where this runs
tested against v0.0.39 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 2.709s · 74.6MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 10.3s · import 2.502s · 83MB
80MB installed
● package 80MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
create_extractor
✓ from trustcall import create_extractor
The primary entry point for creating a Trustcall extractor.
This quickstart demonstrates how to use `trustcall.create_extractor` to define a Pydantic schema for structured data extraction. It shows how Trustcall automatically handles validation errors by re-prompting the LLM to generate JSON patches, ensuring the output conforms to the schema. It also includes an example of updating an existing Pydantic model with new information using the `existing` parameter.
import os
from typing import List
from langchain_fireworks import ChatFireworks
from pydantic.v1 import BaseModel, Field, validator
from trustcall import create_extractor
# Ensure FIREWORKS_API_KEY is set in your environment variables
# os.environ["FIREWORKS_API_KEY"] = os.environ.get('FIREWORKS_API_KEY', 'YOUR_FIREWORKS_API_KEY')
class Preferences(BaseModel):
foods: List[str] = Field(description="Favorite foods")
@validator("foods")
def at_least_three_foods(cls, v):
# This validator serves as a demonstration of error recovery
if len(v) < 3:
raise ValueError("Must have at least three favorite foods")
return v
llm = ChatFireworks(model="accounts/fireworks/models/firefunction-v2")
extractor = create_extractor(llm, tools=[Preferences], tool_choice="Preferences")
# Example 1: Initial extraction with validation error, Trustcall recovers
res = extractor.invoke({"messages": [("user", "I like apple pie and ice cream.")]})
msg = res["messages"][-1]
print("Initial extraction (recovered):", msg.tool_calls)
# Expected output for foods list is now >= 3 items due to recovery
# Example 2: Updating an existing schema
class UserProfile(BaseModel):
name: str
hobbies: List[str]
existing_profile = UserProfile(name="Alice", hobbies=["reading", "hiking"])
update_extractor = create_extractor(
llm,
tools=[UserProfile],
tool_choice="UserProfile"
)
updated_res = update_extractor.invoke({
"messages": [("user", "My new hobby is painting.")],
"existing": {"UserProfile": existing_profile}
})
updated_msg = updated_res["messages"][-1]
print("\nUpdated profile:", updated_msg.tool_calls)
Debug
Known issues
gotchaTrustcall relies on Pydantic models for schema definition, and its examples often use `pydantic.v1` imports. While Pydantic V2 is backward compatible, users might encounter unexpected behavior if mixing V1 and V2 syntax without careful consideration, especially for complex custom validators or field definitions.fixReview Pydantic's V1 to V2 migration guide if upgrading or facing issues. Ensure consistency in Pydantic version usage within your project. Trustcall likely handles V2 internally, but user-defined schemas might need adjustment.
affects: All versions
gotchaSpecific LLM integrations within the LangChain ecosystem may not work seamlessly with Trustcall out-of-the-box, even if they generally support tool calling. Known issues have been reported with `ChatLlamaCpp` and certain Gemini models (e.g., `gemini-1.5-pro-002` via `ChatVertexAI`).fixIf encountering errors with a specific LLM, check the Trustcall GitHub issues for known incompatibilities or workarounds. Consider using an LLM that has been extensively tested with Trustcall, such as `langchain-fireworks` or `OpenAI` models, or consult community forums for alternative configurations.
affects: All versions
breakingUnder certain conditions, particularly with complex nested schemas or during iterative patching, internal errors related to 'patch application failure' or 'errors in _ExtractUpdates' might occur, and these may not propagate clearly, making debugging challenging. This could lead to an incomplete or incorrect final extracted schema.fixEnable detailed logging for Trustcall and LangGraph to gain insight into the internal state and patch operations. Simplify the schema if possible, or break down complex extraction tasks into smaller, more manageable steps. Monitor GitHub issues for fixes or improved error handling.
affects: All versions
deprecatedAs Trustcall is built on LangGraph, it can inherit deprecation warnings from LangGraph itself, such as `LangGraphDeprecatedSinceV10: Importing Send from langgraph.constants is deprecated`. While these might not directly break Trustcall's functionality, they indicate underlying library changes.fixKeep Trustcall and LangGraph updated to their latest compatible versions. Consult LangGraph's documentation for migration guides related to deprecations. These are often internal to Trustcall's implementation but can be seen in verbose logs.
affects: Versions relying on older LangGraph dependencies (before v1.0.0)
Upgrade
Version history
0.0.39latest on PyPI · released Apr 14, 2025
Audit
Dependencies
langgraphrequiredTrustcall is built on LangGraph for orchestration and robust error handling.
pydanticrequiredCommonly used for defining schemas which Trustcall can validate and extract.
langchainrequiredWorks out-of-the-box with any tool-calling LLM from the LangChain ecosystem.
langchain-fireworksoptionalUsed in official examples for integrating with Fireworks AI models.