{"id":4817,"library":"trustcall","title":"Trustcall","description":"Trustcall is a Python library that provides tenacious and trustworthy tool calling capabilities built on LangGraph. It addresses common challenges with Large Language Models (LLMs) in generating and updating complex, nested JSON schemas by employing a 'patch-don't-post' methodology. This approach enables faster, cheaper, and more resilient structured output generation, as well as accurate updates to existing schemas without information loss. The library is actively developed, with its current version being 0.0.39, and new minor versions are released regularly.","status":"active","version":"0.0.39","language":"en","source_language":"en","source_url":"https://github.com/hinthornw/trustcall","tags":["LLM","tool calling","LangGraph","JSON patch","data extraction","Pydantic","structured output","AI agent"],"install":[{"cmd":"pip install -U trustcall langchain-fireworks","lang":"bash","label":"Install with Fireworks LLM integration"},{"cmd":"pip install -U trustcall","lang":"bash","label":"Core library only"}],"dependencies":[{"reason":"Trustcall is built on LangGraph for orchestration and robust error handling.","package":"langgraph","optional":false},{"reason":"Commonly used for defining schemas which Trustcall can validate and extract.","package":"pydantic","optional":false},{"reason":"Works out-of-the-box with any tool-calling LLM from the LangChain ecosystem.","package":"langchain","optional":false},{"reason":"Used in official examples for integrating with Fireworks AI models.","package":"langchain-fireworks","optional":true}],"imports":[{"note":"The primary entry point for creating a Trustcall extractor.","symbol":"create_extractor","correct":"from trustcall import create_extractor"}],"quickstart":{"code":"import os\nfrom typing import List\nfrom langchain_fireworks import ChatFireworks\nfrom pydantic.v1 import BaseModel, Field, validator\nfrom trustcall import create_extractor\n\n# Ensure FIREWORKS_API_KEY is set in your environment variables\n# os.environ[\"FIREWORKS_API_KEY\"] = os.environ.get('FIREWORKS_API_KEY', 'YOUR_FIREWORKS_API_KEY')\n\nclass Preferences(BaseModel):\n    foods: List[str] = Field(description=\"Favorite foods\")\n\n    @validator(\"foods\")\n    def at_least_three_foods(cls, v):\n        # This validator serves as a demonstration of error recovery\n        if len(v) < 3:\n            raise ValueError(\"Must have at least three favorite foods\")\n        return v\n\nllm = ChatFireworks(model=\"accounts/fireworks/models/firefunction-v2\")\nextractor = create_extractor(llm, tools=[Preferences], tool_choice=\"Preferences\")\n\n# Example 1: Initial extraction with validation error, Trustcall recovers\nres = extractor.invoke({\"messages\": [(\"user\", \"I like apple pie and ice cream.\")]})\nmsg = res[\"messages\"][-1]\nprint(\"Initial extraction (recovered):\", msg.tool_calls)\n# Expected output for foods list is now >= 3 items due to recovery\n\n# Example 2: Updating an existing schema\nclass UserProfile(BaseModel):\n    name: str\n    hobbies: List[str]\n\nexisting_profile = UserProfile(name=\"Alice\", hobbies=[\"reading\", \"hiking\"])\n\nupdate_extractor = create_extractor(\n    llm, \n    tools=[UserProfile], \n    tool_choice=\"UserProfile\"\n)\n\nupdated_res = update_extractor.invoke({\n    \"messages\": [(\"user\", \"My new hobby is painting.\")], \n    \"existing\": {\"UserProfile\": existing_profile}\n})\n\nupdated_msg = updated_res[\"messages\"][-1]\nprint(\"\\nUpdated profile:\", updated_msg.tool_calls)\n","lang":"python","description":"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."},"warnings":[{"fix":"Review 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.","message":"Trustcall 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If 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.","message":"Specific 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`).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Enable 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.","message":"Under 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.","severity":"breaking","affected_versions":"All versions"},{"fix":"Keep 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.","message":"As 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.","severity":"deprecated","affected_versions":"Versions relying on older LangGraph dependencies (before v1.0.0)"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}