Add type overloads to with_structured_output() for better type safety with Pydantic schemas

[hon-gyu]

Checked

• I searched existing ideas and did not find a similar one
• I added a very descriptive title
• I've clearly described the feature request and motivation for it

Feature request

Currently, BaseChatModel.with_structured_output() has a broad return type annotation (Union[typing.Dict, BaseModel]) that doesn't reflect the actual runtime behavior when using Pydantic schemas. This causes static type checkers to complain about accessing Pydantic model attributes.

from langchain_core.language_models.chat_models import BaseChatModel
from langchain_core.messages import HumanMessage
from pydantic import BaseModel


class DesiredOutput(BaseModel):
    name: str
    age: int


def f() -> int:
    llm = BaseChatModel()

    res = llm.with_structured_output(schema=DesiredOutput, include_raw=False).invoke(
        [HumanMessage("What is the name and age of the person?")]
    )
    return res.age

Type `dict[Unknown, Unknown] | BaseModel` has no attribute `age`ty[unresolved-attribute](https://ty.dev/rules#unresolved-attribute)`

According to the documentation, when a Pydantic class is passed as the schema, the method always returns an instance of that class, but the type checker doesn't know this, forcing developers to use typing.cast() or # type: ignore comments.

Motivation

Developers should not need to manually cast the return value.

Proposal (If applicable)

# lib/core/langchain_core/language_models/chat_models.py
from typing import Type, TypeVar, overload
class BaseChatModel
    T = TypeVar("T", bound=BaseModel)

    @overload
    def with_structured_output(
        self,
        schema: Type[T],
        *,
        include_raw: Literal[False] = False,
        **kwargs: Any,
    ) -> Runnable[LanguageModelInput, T]: ...

    @overload
    def with_structured_output(
        self,
        schema: Type[T],
        *,
        include_raw: Literal[True],
        **kwargs: Any,
    ) -> Runnable[
        LanguageModelInput, dict[str, Union[BaseMessage, T, Optional[BaseException]]]
    ]: ...

    @overload
    def with_structured_output(
        self,
        schema: typing.Dict,
        *,
        include_raw: Literal[False] = False,
        **kwargs: Any,
    ) -> Runnable[LanguageModelInput, typing.Dict]: ...

    @overload
    def with_structured_output(
        self,
        schema: typing.Dict,
        *,
        include_raw: Literal[True],
        **kwargs: Any,
    ) -> Runnable[
        LanguageModelInput, dict[str, Union[BaseMessage, dict, Optional[BaseException]]]
    ]: ...

This fixes the type check error in above example.

I'm happy to create a PR.