with_structured_output() — langchain Function Reference

Architecture documentation for the with_structured_output() function in chat_models.py from the langchain codebase.

Function python LangChainCore LanguageModelBase calls 2

Entity Profile

LangChainCore→ LanguageModelBase→ with_structured_output() — langchain Function Reference

Dependency Diagram

graph TD
  a7b3568d_42f9_a0cb_ee98_bd7da412e7e8["with_structured_output()"]
  48aa29b8_65e7_522f_a445_a441eeb6baff["BaseChatModel"]
  a7b3568d_42f9_a0cb_ee98_bd7da412e7e8 -->|defined in| 48aa29b8_65e7_522f_a445_a441eeb6baff
  f691aa13_25a5_eecf_5188_77aeb1ac77c2["bind_tools()"]
  a7b3568d_42f9_a0cb_ee98_bd7da412e7e8 -->|calls| f691aa13_25a5_eecf_5188_77aeb1ac77c2
  f961f0c9_5051_8b77_5e6c_256782a5be2a["invoke()"]
  a7b3568d_42f9_a0cb_ee98_bd7da412e7e8 -->|calls| f961f0c9_5051_8b77_5e6c_256782a5be2a
  style a7b3568d_42f9_a0cb_ee98_bd7da412e7e8 fill:#6366f1,stroke:#818cf8,color:#fff

Relationship Graph

Source Code

libs/core/langchain_core/language_models/chat_models.py lines 1540–1721

    def with_structured_output(
        self,
        schema: builtins.dict[str, Any] | type,
        *,
        include_raw: bool = False,
        **kwargs: Any,
    ) -> Runnable[LanguageModelInput, builtins.dict[str, Any] | BaseModel]:
        """Model wrapper that returns outputs formatted to match the given schema.

        Args:
            schema: The output schema. Can be passed in as:

                - An OpenAI function/tool schema,
                - A JSON Schema,
                - A `TypedDict` class,
                - Or a Pydantic class.

                If `schema` is a Pydantic class then the model output will be a
                Pydantic instance of that class, and the model-generated fields will be
                validated by the Pydantic class. Otherwise the model output will be a
                dict and will not be validated.

                See `langchain_core.utils.function_calling.convert_to_openai_tool` for
                more on how to properly specify types and descriptions of schema fields
                when specifying a Pydantic or `TypedDict` class.

            include_raw:
                If `False` then only the parsed structured output is returned.

                If an error occurs during model output parsing it will be raised.

                If `True` then both the raw model response (a `BaseMessage`) and the
                parsed model response will be returned.

                If an error occurs during output parsing it will be caught and returned
                as well.

                The final output is always a `dict` with keys `'raw'`, `'parsed'`, and
                `'parsing_error'`.

        Raises:
            ValueError: If there are any unsupported `kwargs`.
            NotImplementedError: If the model does not implement
                `with_structured_output()`.

        Returns:
            A `Runnable` that takes same inputs as a
                `langchain_core.language_models.chat.BaseChatModel`. If `include_raw` is
                `False` and `schema` is a Pydantic class, `Runnable` outputs an instance
                of `schema` (i.e., a Pydantic object). Otherwise, if `include_raw` is
                `False` then `Runnable` outputs a `dict`.

                If `include_raw` is `True`, then `Runnable` outputs a `dict` with keys:

                - `'raw'`: `BaseMessage`
                - `'parsed'`: `None` if there was a parsing error, otherwise the type
                    depends on the `schema` as described above.
                - `'parsing_error'`: `BaseException | None`

        ???+ example "Pydantic schema (`include_raw=False`)"

            ```python
            from pydantic import BaseModel


            class AnswerWithJustification(BaseModel):
                '''An answer to the user question along with justification for the answer.'''

                answer: str
                justification: str


            model = ChatModel(model="model-name", temperature=0)
            structured_model = model.with_structured_output(AnswerWithJustification)

            structured_model.invoke(
                "What weighs more a pound of bricks or a pound of feathers"
            )

            # -> AnswerWithJustification(
            #     answer='They weigh the same',