libs/partners/perplexity/langchain_perplexity/chat_models.py PYTHON 1,749 lines View on github.com → Search inside
1"""Wrapper around Perplexity APIs."""23from __future__ import annotations45import json6import logging7from collections.abc import AsyncIterator, Callable, Iterator, Mapping, Sequence8from operator import itemgetter9from typing import Any, Literal, Self, TypeAlias, cast1011from langchain_core.callbacks import (12    AsyncCallbackManagerForLLMRun,13    CallbackManagerForLLMRun,14)15from langchain_core.language_models import (16    LanguageModelInput,17    ModelProfile,18    ModelProfileRegistry,19)20from langchain_core.language_models.chat_models import (21    BaseChatModel,22    agenerate_from_stream,23    generate_from_stream,24)25from langchain_core.messages import (26    AIMessage,27    AIMessageChunk,28    BaseMessage,29    BaseMessageChunk,30    ChatMessage,31    ChatMessageChunk,32    FunctionMessageChunk,33    HumanMessage,34    HumanMessageChunk,35    SystemMessage,36    SystemMessageChunk,37    ToolMessage,38    ToolMessageChunk,39)40from langchain_core.messages.ai import (41    InputTokenDetails,42    OutputTokenDetails,43    UsageMetadata,44    subtract_usage,45)46from langchain_core.messages.tool import tool_call_chunk47from langchain_core.outputs import ChatGeneration, ChatGenerationChunk, ChatResult48from langchain_core.runnables import Runnable, RunnableMap, RunnablePassthrough49from langchain_core.tools import BaseTool50from langchain_core.utils import get_pydantic_field_names, secret_from_env51from langchain_core.utils.function_calling import (52    convert_to_json_schema,53    convert_to_openai_tool,54)55from langchain_core.utils.pydantic import is_basemodel_subclass56from perplexity import AsyncPerplexity, Perplexity57from pydantic import BaseModel, ConfigDict, Field, SecretStr, model_validator5859from langchain_perplexity._version import __version__60from langchain_perplexity.data._profiles import _PROFILES61from langchain_perplexity.output_parsers import (62    ReasoningJsonOutputParser,63    ReasoningStructuredOutputParser,64)65from langchain_perplexity.types import MediaResponse, WebSearchOptions6667_DictOrPydanticClass: TypeAlias = dict[str, Any] | type[BaseModel]68_DictOrPydantic: TypeAlias = dict | BaseModel6970logger = logging.getLogger(__name__)717273_MODEL_PROFILES = cast("ModelProfileRegistry", _PROFILES)747576def _get_default_model_profile(model_name: str) -> ModelProfile:77    default = _MODEL_PROFILES.get(model_name) or {}78    return default.copy()798081def _is_pydantic_class(obj: Any) -> bool:82    return isinstance(obj, type) and is_basemodel_subclass(obj)838485def _create_usage_metadata(token_usage: dict) -> UsageMetadata:86    """Create UsageMetadata from Perplexity token usage data.8788    Args:89        token_usage: Dictionary containing token usage information from Perplexity API.9091    Returns:92        UsageMetadata with properly structured token counts and details.93    """94    input_tokens = token_usage.get("prompt_tokens", 0)95    output_tokens = token_usage.get("completion_tokens", 0)96    total_tokens = token_usage.get("total_tokens", input_tokens + output_tokens)9798    # Build output_token_details for Perplexity-specific fields99    output_token_details: OutputTokenDetails = {}100    if (reasoning := token_usage.get("reasoning_tokens")) is not None:101        output_token_details["reasoning"] = reasoning102    if (citation_tokens := token_usage.get("citation_tokens")) is not None:103        output_token_details["citation_tokens"] = citation_tokens  # type: ignore[typeddict-unknown-key]104105    return UsageMetadata(106        input_tokens=input_tokens,107        output_tokens=output_tokens,108        total_tokens=total_tokens,109        output_token_details=output_token_details,110    )111112113_RESPONSES_ONLY_ARGS = frozenset(114    {"include", "input", "instructions", "previous_response_id"}115)116"""Top-level keys that exist only on Perplexity's Agent (Responses) API.117118The presence of any of these triggers auto-routing through Responses, since119the Chat Completions endpoint would silently reject them.120"""121122_RESPONSES_PASSTHROUGH_KEYS = frozenset(123    {124        "model",125        "models",126        "tools",127        "instructions",128        "language_preference",129        "max_steps",130        "preset",131        "reasoning",132        "response_format",133        "stream",134        "extra_body",135        "extra_headers",136        "extra_query",137        "timeout",138    }139)140"""Keys the Perplexity Responses SDK accepts natively.141142Mirrors `perplexity.resources.responses.ResponsesResource.create`. Anything143outside this set (other than known renames and drops) is routed through144`extra_body` so the SDK forwards it without breaking strict typing.145"""146147_RESPONSES_DROP_KEYS = frozenset({"temperature", "top_p", "top_k", "stop", "metadata"})148"""Chat-Completions-only sampling/control knobs the Responses (Agent) API does149not accept.150151Forwarding them would raise `TypeError` from the typed SDK signature in152`perplexity.resources.responses.ResponsesResource.create`, so they are dropped153at the boundary. Every drop emits a `WARNING`-level log on each call, except154the class-default `temperature`, which is suppressed because `_default_params`155injects `self.temperature` on every call regardless of user intent. A156user-supplied `temperature` (via init, `invoke(temperature=...)`, or `.bind`)157still warns.158159`tool_choice` is *not* in this set: it is a control-flow primitive160(forced/required tool selection) and is rejected with `ValueError` rather than161silently dropped, since downstream agent loops cannot recover.162"""163164165def _is_builtin_tool(tool: dict) -> bool:166    """Return True if `tool` is a Responses-API built-in (non-`function`) tool.167168    Perplexity's Agent API ships built-in tools (e.g. `web_search`,169    `code_interpreter`) that are identified by a `type` value other than170    `"function"`. Chat Completions only accepts function tools, so any tool171    failing this check forces the Responses route.172    """173    return "type" in tool and tool["type"] != "function"174175176def _flatten_responses_tool(tool: dict) -> dict:177    """Flatten a Chat-Completions function tool (nested under `function`) to178    the Responses-API's flat shape. Built-in tools (e.g. `web_search`) pass179    through unchanged.180    """181    if tool.get("type") == "function" and isinstance(tool.get("function"), dict):182        fn = tool["function"]183        flat: dict[str, Any] = {"type": "function", "name": fn.get("name")}184        for key in ("description", "parameters", "strict"):185            if key in fn:186                flat[key] = fn[key]187        return flat188    return tool189190191def _content_to_text(content: Any) -> str:192    """Concatenate text from a string or list-of-blocks content, dropping193    non-text blocks (e.g. a `tool_call`/`tool_use` block) that the Responses API194    can't take on a tool turn.195196    Only the optional plain-text preamble of an assistant tool turn is built197    here; the calls themselves are re-materialized as `function_call` items by198    `_translate_responses_input`, so nothing actionable is lost.199    """200    if isinstance(content, str):201        return content202    if isinstance(content, list):203        parts: list[str] = []204        for block in content:205            if isinstance(block, str):206                parts.append(block)207            elif isinstance(block, dict) and block.get("type") == "text":208                parts.append(block.get("text", ""))209        return "".join(parts)210    if content is not None:211        # An unexpected content shape (not str/list/None) is dropped rather than212        # guessed at; log it so content-shape drift stays diagnosable.213        logger.debug("Dropping unexpected content type %s on tool turn.", type(content))214    return ""215216217def _translate_responses_input(message_dicts: list[dict[str, Any]]) -> list[Any]:218    """Translate Chat-Completions message dicts into Responses-API input items.219220    The Responses API has no `tool` role: an assistant turn's `tool_calls`221    become `function_call` items and a `tool` message becomes a222    `function_call_output`. Other messages pass through.223224    `name`, `id`, and `tool_call_id` are the fields that pair a call with its225    result; `_convert_message_to_dict` always populates them, so a missing one226    here signals upstream drift or a hand-built message and is logged at227    `WARNING` rather than silently coerced.228    """229    translated: list[Any] = []230    for message in message_dicts:231        if not isinstance(message, dict):232            translated.append(message)233            continue234        role = message.get("role")235        if role == "assistant" and message.get("tool_calls"):236            # Assistant text (if any) becomes a plain message; the calls follow237            # as `function_call` items.238            text = _content_to_text(message.get("content"))239            if text:240                translated.append(241                    {"type": "message", "role": "assistant", "content": text}242                )243            for tool_call in message["tool_calls"]:244                function = tool_call.get("function", {})245                call_id = tool_call.get("id")246                name = function.get("name", "")247                if not name or not call_id:248                    logger.warning(249                        "Assistant tool_call missing identity field "250                        "(name=%r, id=%r); the Responses API may reject this "251                        "turn or fail to pair the call with its output.",252                        name,253                        call_id,254                    )255                translated.append(256                    {257                        "type": "function_call",258                        "call_id": call_id,259                        "name": name,260                        "arguments": function.get("arguments", "") or "",261                    }262                )263        elif role == "tool":264            content = message.get("content", "")265            output = content if isinstance(content, str) else json.dumps(content)266            call_id = message.get("tool_call_id")267            if not call_id:268                logger.warning(269                    "Tool message missing tool_call_id; the Responses API "270                    "cannot pair this function_call_output with its call."271                )272            translated.append(273                {274                    "type": "function_call_output",275                    "call_id": call_id,276                    "output": output,277                }278            )279        elif role in {"assistant", "system", "user", "developer"}:280            translated.append({**message, "type": "message"})281        else:282            translated.append(message)283    return translated284285286def _use_responses_api(payload: dict) -> bool:287    """Determine whether to route a payload through the Responses API.288289    The Agent (Responses) API is required for built-in tools and accepts290    fields that Chat Completions would reject — so callers must be routed291    there transparently when those signals appear.292293    Returns True if the payload contains a built-in tool (any element of294    `tools` whose `type` is not `"function"`) or any Responses-only field295    (`input`, `include`, `instructions`, `previous_response_id`).296    """297    uses_builtin_tools = "tools" in payload and any(298        _is_builtin_tool(tool) for tool in payload["tools"]299    )300    matched_fields = _RESPONSES_ONLY_ARGS.intersection(payload)301    if uses_builtin_tools or matched_fields:302        reason = (303            "payload contains a built-in tool (Chat Completions accepts only "304            "function tools)"305            if uses_builtin_tools306            else (307                f"payload sets Responses-only field(s) {sorted(matched_fields)} "308                "(Chat Completions would reject these)"309            )310        )311        logger.debug(312            "Routing through Perplexity Responses API: %s. "313            "Set use_responses_api=False to force Chat Completions.",314            reason,315        )316        return True317    return False318319320def _set_model_name_alias(response_metadata: dict[str, Any]) -> None:321    """Mirror `model` into `model_name`, which langchain-core usage callbacks322    read for cost tracking (the Chat Completions path already sets it).323    """324    if "model" in response_metadata:325        response_metadata["model_name"] = response_metadata["model"]326327328def _get_attr(obj: Any, name: str, default: Any = None) -> Any:329    """Safely fetch an attribute from an SDK object or a dict.330331    Responses SDK payloads arrive either as Pydantic-like SDK objects (server332    responses) or as plain dicts (when callers pass payloads pre-serialized or333    in tests). This helper normalizes both shapes so the rest of the module334    does not have to special-case them.335    """336    if isinstance(obj, dict):337        return obj.get(name, default)338    return getattr(obj, name, default)339340341def _convert_responses_usage(usage: Any) -> UsageMetadata | None:342    """Build `UsageMetadata` from a Responses API usage payload.343344    Returns `None` if `usage` itself is missing or if either token field is345    absent — emitting zeroed `UsageMetadata` would silently undercount usage346    in downstream cost dashboards.347348    Cache hits and cache writes reported under `input_tokens_details` are mapped349    onto the standard `InputTokenDetails` slots so downstream consumers can tell350    cached input from fresh input.351    """352    if usage is None:353        return None354    input_tokens = _get_attr(usage, "input_tokens", None)355    output_tokens = _get_attr(usage, "output_tokens", None)356    if input_tokens is None or output_tokens is None:357        return None358    total_tokens = _get_attr(usage, "total_tokens", None)359    if total_tokens is None:360        total_tokens = input_tokens + output_tokens361362    input_token_details: InputTokenDetails = {}363    details = _get_attr(usage, "input_tokens_details", None)364    if details is not None:365        cache_read = _get_attr(details, "cache_read_input_tokens", None)366        if cache_read is not None:367            input_token_details["cache_read"] = cache_read368        cache_creation = _get_attr(details, "cache_creation_input_tokens", None)369        if cache_creation is not None:370            input_token_details["cache_creation"] = cache_creation371372    return UsageMetadata(373        input_tokens=input_tokens,374        output_tokens=output_tokens,375        total_tokens=total_tokens,376        input_token_details=input_token_details,377    )378379380def _extract_responses_text(response: Any) -> str:381    """Extract assistant text content from a Responses API response.382383    Prefers `response.output_text`, otherwise walks `output[*].content[*].text`.384    """385    text = _get_attr(response, "output_text", None)386    if isinstance(text, str) and text:387        return text388    output = _get_attr(response, "output", None) or []389    parts: list[str] = []390    for item in output:391        item_type = _get_attr(item, "type", None)392        if item_type and item_type != "message":393            continue394        content_blocks = _get_attr(item, "content", None) or []395        for block in content_blocks:396            block_text = _get_attr(block, "text", None)397            if isinstance(block_text, str):398                parts.append(block_text)399    return "".join(parts)400401402def _convert_responses_to_chat_result(response: Any) -> ChatResult:403    """Convert a Responses API response object to a `ChatResult`.404405    Maps `output_text`/`output[*].content[*].text` to `AIMessage.content` and406    surfaces `function_call` items as `tool_calls`. Perplexity-specific fields407    (`citations`, `images`, `related_questions`, `search_results`, `videos`,408    `reasoning_steps`) are placed on `additional_kwargs` to match the shape409    produced by the Chat Completions branch, while transport-level fields410    (`id`, `model`, `status`, `object`) land on `response_metadata`.411    """412    content = _extract_responses_text(response)413414    tool_calls: list[dict[str, Any]] = []415    additional_kwargs: dict[str, Any] = {}416    output = _get_attr(response, "output", None) or []417    for item in output:418        item_type = _get_attr(item, "type", None)419        if item_type == "search_results":420            if results := _get_attr(item, "results", None):421                additional_kwargs.setdefault("search_results", []).extend(422                    result.model_dump() if isinstance(result, BaseModel) else result423                    for result in results424                )425        elif item_type == "function_call":426            raw_args = _get_attr(item, "arguments", "") or ""427            try:428                parsed_args = json.loads(raw_args) if raw_args else {}429            except (TypeError, ValueError):430                logger.warning(431                    "Failed to parse Perplexity function_call arguments as JSON "432                    "for tool %r; preserving raw payload under __raw_arguments__.",433                    _get_attr(item, "name", ""),434                    exc_info=True,435                )436                parsed_args = {"__raw_arguments__": raw_args}437            tool_calls.append(438                {439                    "name": _get_attr(item, "name", ""),440                    "args": parsed_args,441                    "id": _get_attr(item, "call_id", None)442                    or _get_attr(item, "id", None),443                    "type": "tool_call",444                }445            )446        elif item_type and item_type != "message":447            logger.debug("Ignoring unhandled Responses output item type: %s", item_type)448449    usage_metadata = _convert_responses_usage(_get_attr(response, "usage", None))450451    for key in (452        "citations",453        "images",454        "related_questions",455        "search_results",456        "videos",457        "reasoning_steps",458    ):459        value = _get_attr(response, key, None)460        if value:461            additional_kwargs.setdefault(key, value)462463    response_metadata: dict[str, Any] = {}464    for key in ("id", "model", "status", "object"):465        value = _get_attr(response, key, None)466        if value is not None:467            response_metadata[key] = value468    _set_model_name_alias(response_metadata)469470    message = AIMessage(471        content=content,472        additional_kwargs=additional_kwargs,473        tool_calls=tool_calls,  # type: ignore[arg-type]474        usage_metadata=usage_metadata,475        response_metadata=response_metadata,476    )477    return ChatResult(generations=[ChatGeneration(message=message)])478479480class PerplexityResponsesStreamError(RuntimeError):481    """Raised when a Perplexity Responses (Agent) API stream fails mid-flight.482483    Carries the structured error fields the API surfaces (`code`, `type`,484    `param`, `request_id`) and the original event payload so observability485    pipelines can inspect them programmatically instead of regex-parsing the486    message string.487    """488489    def __init__(490        self,491        message: str,492        *,493        code: str | None = None,494        error_type: str | None = None,495        param: str | None = None,496        request_id: str | None = None,497        raw_event: Any = None,498    ) -> None:499        super().__init__(message)500        self.code = code501        self.error_type = error_type502        self.param = param503        self.request_id = request_id504        self.raw_event = raw_event505506507def _convert_responses_stream_event_to_chunk(508    event: Any,509) -> ChatGenerationChunk | None:510    """Convert a Responses API streaming event to a `ChatGenerationChunk`.511512    Handles `response.reasoning.search_results` (source metadata),513    `response.output_text.delta` (text chunk), `response.output_item.done`514    carrying a `function_call` (surfaced as a tool-call chunk), `response.completed`515    (final usage + metadata), and `response.failed` / `response.error`516    (raises `PerplexityResponsesStreamError`). Returns `None` for any other517    event type; unrecognized event types are logged at `DEBUG` so SDK drift is518    diagnosable without flooding logs.519    """520    event_type = _get_attr(event, "type", None)521    if event_type == "response.reasoning.search_results":522        if results := _get_attr(event, "results", None):523            return ChatGenerationChunk(524                message=AIMessageChunk(525                    content="",526                    additional_kwargs={527                        "search_results": [528                            result.model_dump()529                            if isinstance(result, BaseModel)530                            else result531                            for result in results532                        ]533                    },534                )535            )536        return None537    if event_type == "response.output_text.delta":538        delta = _get_attr(event, "delta", "") or ""539        return ChatGenerationChunk(message=AIMessageChunk(content=delta))540    if event_type == "response.output_item.done":541        item = _get_attr(event, "item", None)542        if item is not None and _get_attr(item, "type", None) == "function_call":543            # The Responses API delivers the whole function call in one item544            # (no argument deltas), so emit it as a single tool-call chunk.545            return ChatGenerationChunk(546                message=AIMessageChunk(547                    content="",548                    tool_call_chunks=[549                        tool_call_chunk(550                            name=_get_attr(item, "name", None),551                            args=_get_attr(item, "arguments", None),552                            id=_get_attr(item, "call_id", None)553                            or _get_attr(item, "id", None),554                            index=_get_attr(event, "output_index", 0),555                        )556                    ],557                )558            )559        return None560    if event_type == "response.completed":561        response = _get_attr(event, "response", None)562        usage_metadata = _convert_responses_usage(_get_attr(response, "usage", None))563        response_metadata: dict[str, Any] = {}564        additional_kwargs: dict[str, Any] = {}565        if response is not None:566            for key in ("id", "model", "status", "object"):567                value = _get_attr(response, key, None)568                if value is not None:569                    response_metadata[key] = value570            _set_model_name_alias(response_metadata)571            for key in (572                "citations",573                "images",574                "related_questions",575                "search_results",576                "videos",577                "reasoning_steps",578            ):579                value = _get_attr(response, key, None)580                if value:581                    additional_kwargs[key] = value582        return ChatGenerationChunk(583            message=AIMessageChunk(584                content="",585                additional_kwargs=additional_kwargs,586                usage_metadata=usage_metadata,587                response_metadata=response_metadata,588            )589        )590    if event_type in ("response.failed", "response.error"):591        # `response.failed` is the canonical SDK event name; `response.error`592        # is kept as a fallback in case the API surfaces it during transport.593        # Without this branch, a server-side failure mid-stream would yield594        # zero chunks and surface as "No generation chunks were returned"595        # from `BaseChatModel.stream`, obscuring the real error.596        error = _get_attr(event, "error", None)597        message = (598            _get_attr(error, "message", None)599            if error is not None600            else _get_attr(event, "message", None)601        ) or "Perplexity Responses API stream error"602        code = _get_attr(error, "code", None) if error is not None else None603        error_type = _get_attr(error, "type", None) if error is not None else None604        param = _get_attr(error, "param", None) if error is not None else None605        request_id = _get_attr(event, "request_id", None)606        details: list[str] = []607        for label, value in (608            ("code", code),609            ("type", error_type),610            ("param", param),611            ("request_id", request_id),612        ):613            if value is not None:614                details.append(f"{label}={value}")615        if details:616            message = f"{message} ({', '.join(details)})"617        logger.error(618            "Perplexity Responses stream failure: %s",619            message,620            extra={621                "perplexity_error_code": code,622                "perplexity_error_type": error_type,623                "perplexity_error_param": param,624                "perplexity_request_id": request_id,625            },626        )627        raise PerplexityResponsesStreamError(628            message,629            code=code,630            error_type=error_type,631            param=param,632            request_id=request_id,633            raw_event=event,634        )635    logger.debug("Ignoring unhandled Perplexity stream event type: %s", event_type)636    return None637638639class ChatPerplexity(BaseChatModel):640    """`Perplexity AI` Chat models API.641642    Setup:643        To use, you should have the environment variable `PPLX_API_KEY` set to your API key.644        Any parameters that are valid to be passed to the perplexity.create call645        can be passed in, even if not explicitly saved on this class.646647        ```bash648        export PPLX_API_KEY=your_api_key649        ```650651        Key init args - completion params:652            model:653                Name of the model to use. e.g. "sonar"654            temperature:655                Sampling temperature to use.656            max_tokens:657                Maximum number of tokens to generate.658            streaming:659                Whether to stream the results or not.660661        Key init args - client params:662            pplx_api_key:663                API key for PerplexityChat API.664            request_timeout:665                Timeout for requests to PerplexityChat completion API.666            max_retries:667                Maximum number of retries to make when generating.668669        See full list of supported init args and their descriptions in the params section.670671        Instantiate:672673        ```python674        from langchain_perplexity import ChatPerplexity675676        model = ChatPerplexity(model="sonar", temperature=0.7)677        ```678679        Invoke:680681        ```python682        messages = [("system", "You are a chatbot."), ("user", "Hello!")]683        model.invoke(messages)684        ```685686        Invoke with structured output:687688        ```python689        from pydantic import BaseModel690691692        class StructuredOutput(BaseModel):693            role: str694            content: str695696697        model.with_structured_output(StructuredOutput)698        model.invoke(messages)699        ```700701        Stream:702        ```python703        for chunk in model.stream(messages):704            print(chunk.content)705        ```706707        Token usage:708        ```python709        response = model.invoke(messages)710        response.usage_metadata711        ```712713        Response metadata:714        ```python715        response = model.invoke(messages)716        response.response_metadata717        ```718719        Agent API (Responses):720721        Set `use_responses_api=True` to route requests through Perplexity's Agent722        API (the Perplexity-flavored Responses API), or leave it unset to have it723        auto-detected when a built-in tool (e.g. `web_search`) or any724        Responses-only field (`previous_response_id`, `instructions`, `input`,725        `include`) is supplied.726727        The Agent API uses its own model catalog (see728        https://docs.perplexity.ai/docs/agent-api/models). Select routing by729        passing either an explicit `model=` such as `"openai/gpt-5.6-sol"`, or a730        Perplexity `preset` (`"fast"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`,731        or `"wide-research"`) through732        `model_kwargs`. Perplexity's built-in tools and Agent-API-only fields733        also go through `model_kwargs`:734735        ```python736        from langchain_perplexity import ChatPerplexity737738        model = ChatPerplexity(739            use_responses_api=True,740            model_kwargs={741                "preset": "medium",742                "tools": [{"type": "web_search"}],743            },744        )745        model.invoke("What did Perplexity announce most recently?")746        ```747748        Auto-detection example (routes to the Agent API because a built-in749        `web_search` tool is present):750751        ```python752        model = ChatPerplexity(model="openai/gpt-5.6-sol")753        model.invoke(754            "Find recent news about AI.",755            tools=[{"type": "web_search"}],756        )757        ```758    """  # noqa: E501759760    client: Any = Field(default=None, exclude=True)761    async_client: Any = Field(default=None, exclude=True)762763    model: str = "sonar"764    """Model name."""765766    temperature: float = 0.7767    """What sampling temperature to use."""768769    model_kwargs: dict[str, Any] = Field(default_factory=dict)770    """Holds any model parameters valid for `create` call not explicitly specified."""771772    pplx_api_key: SecretStr | None = Field(773        default_factory=secret_from_env("PPLX_API_KEY", default=None), alias="api_key"774    )775    """Perplexity API key."""776777    request_timeout: float | tuple[float, float] | None = Field(None, alias="timeout")778    """Timeout for requests to PerplexityChat completion API."""779780    max_retries: int = 6781    """Maximum number of retries to make when generating."""782783    streaming: bool = False784    """Whether to stream the results or not."""785786    max_tokens: int | None = None787    """Maximum number of tokens to generate."""788789    use_responses_api: bool | None = None790    """Whether to use the Responses (Agent) API instead of the Chat Completions API.791792    If not specified then will be inferred based on invocation params. Specifically,793    requests will be routed to the Responses API when the payload includes a built-in794    tool (any `tools[*]` whose `type` is not `"function"`) or any of the795    Responses-only fields: `previous_response_id`, `instructions`, `input`, `include`.796797    Set explicitly to `True` to always use the Responses API, or `False` to always798    use Chat Completions.799800    !!! warning "Disabled parameters on the Responses (Agent) API"801802        The Perplexity Agent API does not accept Chat-Completions-only knobs.803        When routing through Responses (whether explicitly or by inference):804805        - `temperature`, `top_p`, `top_k`, `stop`, and `metadata` are dropped806          at the boundary with a `WARNING` log so the behavior change is807          discoverable. The class default `temperature` is dropped silently808          (it would otherwise spam every call), but a user-supplied809          `temperature` (init, `invoke(temperature=...)`, or `.bind`) still810          warns.811        - `tool_choice` raises `ValueError` rather than being dropped, since812          downstream agent loops cannot recover from a silently-disabled813          forced tool call.814        - Supplying a `preset` causes `model` to be dropped because the Agent815          API rejects bare Chat-Completions model names when `model` is816          provided. If `model` was explicitly set by the user, a `WARNING` is817          logged so the override is discoverable.818819        Use `use_responses_api=False` if you need any of these parameters to820        take effect.821    """822823    search_mode: Literal["academic", "sec", "web"] | None = None824    """Search mode for specialized content: "academic", "sec", or "web"."""825826    reasoning_effort: Literal["low", "medium", "high"] | None = None827    """Reasoning effort: "low", "medium", or "high" (default)."""828829    language_preference: str | None = None830    """Language preference:"""831832    search_domain_filter: list[str] | None = None833    """Search domain filter: list of domains to filter search results (max 20)."""834835    return_images: bool = False836    """Whether to return images in the response."""837838    return_related_questions: bool = False839    """Whether to return related questions in the response."""840841    search_recency_filter: Literal["day", "week", "month", "year"] | None = None842    """Filter search results by recency: "day", "week", "month", or "year"."""843844    search_after_date_filter: str | None = None845    """Search after date filter: date in format "MM/DD/YYYY" (default)."""846847    search_before_date_filter: str | None = None848    """Only return results before this date (format: MM/DD/YYYY)."""849850    last_updated_after_filter: str | None = None851    """Only return results updated after this date (format: MM/DD/YYYY)."""852853    last_updated_before_filter: str | None = None854    """Only return results updated before this date (format: MM/DD/YYYY)."""855856    disable_search: bool = False857    """Whether to disable web search entirely."""858859    enable_search_classifier: bool = False860    """Whether to enable the search classifier."""861862    web_search_options: WebSearchOptions | None = None863    """Configuration for web search behavior including Pro Search."""864865    media_response: MediaResponse | None = None866    """Media response: "images", "videos", or "none" (default)."""867868    model_config = ConfigDict(populate_by_name=True)869870    @property871    def lc_secrets(self) -> dict[str, str]:872        return {"pplx_api_key": "PPLX_API_KEY"}873874    @model_validator(mode="before")875    @classmethod876    def build_extra(cls, values: dict[str, Any]) -> Any:877        """Build extra kwargs from additional params that were passed in."""878        all_required_field_names = get_pydantic_field_names(cls)879        extra = values.get("model_kwargs", {})880        for field_name in list(values):881            if field_name in extra:882                raise ValueError(f"Found {field_name} supplied twice.")883            if field_name not in all_required_field_names:884                logger.warning(885                    f"""WARNING! {field_name} is not a default parameter.886                    {field_name} was transferred to model_kwargs.887                    Please confirm that {field_name} is what you intended."""888                )889                extra[field_name] = values.pop(field_name)890891        invalid_model_kwargs = all_required_field_names.intersection(extra.keys())892        if invalid_model_kwargs:893            raise ValueError(894                f"Parameters {invalid_model_kwargs} should be specified explicitly. "895                f"Instead they were passed in as part of `model_kwargs` parameter."896            )897898        values["model_kwargs"] = extra899        return values900901    @model_validator(mode="after")902    def _set_perplexity_version(self) -> Self:903        """Set package version in metadata."""904        self._add_version("langchain-perplexity", __version__)905        return self906907    @model_validator(mode="after")908    def validate_environment(self) -> Self:909        """Validate that api key and python package exists in environment."""910        pplx_api_key = (911            self.pplx_api_key.get_secret_value() if self.pplx_api_key else None912        )913914        client_params: dict[str, Any] = {915            "api_key": pplx_api_key,916            "max_retries": self.max_retries,917        }918        if self.request_timeout is not None:919            client_params["timeout"] = self.request_timeout920921        if not self.client:922            self.client = Perplexity(**client_params)923924        if not self.async_client:925            self.async_client = AsyncPerplexity(**client_params)926927        return self928929    def _resolve_model_profile(self) -> ModelProfile | None:930        return _get_default_model_profile(self.model) or None931932    @property933    def _default_params(self) -> dict[str, Any]:934        """Get the default parameters for calling PerplexityChat API."""935        params: dict[str, Any] = {936            "max_tokens": self.max_tokens,937            "stream": self.streaming,938            "temperature": self.temperature,939        }940        if self.search_mode:941            params["search_mode"] = self.search_mode942        if self.reasoning_effort:943            params["reasoning_effort"] = self.reasoning_effort944        if self.language_preference:945            params["language_preference"] = self.language_preference946        if self.search_domain_filter:947            params["search_domain_filter"] = self.search_domain_filter948        if self.return_images:949            params["return_images"] = self.return_images950        if self.return_related_questions:951            params["return_related_questions"] = self.return_related_questions952        if self.search_recency_filter:953            params["search_recency_filter"] = self.search_recency_filter954        if self.search_after_date_filter:955            params["search_after_date_filter"] = self.search_after_date_filter956        if self.search_before_date_filter:957            params["search_before_date_filter"] = self.search_before_date_filter958        if self.last_updated_after_filter:959            params["last_updated_after_filter"] = self.last_updated_after_filter960        if self.last_updated_before_filter:961            params["last_updated_before_filter"] = self.last_updated_before_filter962        if self.disable_search:963            params["disable_search"] = self.disable_search964        if self.enable_search_classifier:965            params["enable_search_classifier"] = self.enable_search_classifier966        if self.web_search_options:967            params["web_search_options"] = self.web_search_options.model_dump(968                exclude_none=True969            )970        if self.media_response:971            if "extra_body" not in params:972                params["extra_body"] = {}973            params["extra_body"]["media_response"] = self.media_response.model_dump(974                exclude_none=True975            )976977        return {**params, **self.model_kwargs}978979    def _convert_message_to_dict(self, message: BaseMessage) -> dict[str, Any]:980        message_dict: dict[str, Any]981        if isinstance(message, ChatMessage):982            message_dict = {"role": message.role, "content": message.content}983        elif isinstance(message, SystemMessage):984            message_dict = {"role": "system", "content": message.content}985        elif isinstance(message, HumanMessage):986            message_dict = {"role": "user", "content": message.content}987        elif isinstance(message, AIMessage):988            message_dict = {"role": "assistant", "content": message.content}989            if message.tool_calls or message.invalid_tool_calls:990                message_dict["tool_calls"] = [991                    {992                        "id": tool_call["id"],993                        "type": "function",994                        "function": {995                            "name": tool_call["name"],996                            "arguments": json.dumps(997                                tool_call["args"], ensure_ascii=False998                            ),999                        },1000                    }1001                    for tool_call in message.tool_calls1002                ] + [1003                    {1004                        "id": tool_call["id"],1005                        "type": "function",1006                        "function": {1007                            "name": tool_call["name"],1008                            "arguments": tool_call["args"],1009                        },1010                    }1011                    for tool_call in message.invalid_tool_calls1012                ]1013                # OpenAI-compatible APIs reject empty-string content alongside1014                # tool_calls; send null instead.1015                message_dict["content"] = message_dict["content"] or None1016        elif isinstance(message, ToolMessage):1017            message_dict = {1018                "role": "tool",1019                "content": message.content,1020                "tool_call_id": message.tool_call_id,1021            }1022        else:1023            raise TypeError(f"Got unknown type {message}")1024        return message_dict10251026    def _create_message_dicts(1027        self, messages: list[BaseMessage], stop: list[str] | None1028    ) -> tuple[list[dict[str, Any]], dict[str, Any]]:1029        params = dict(self._invocation_params)1030        if stop is not None:1031            if "stop" in params:1032                raise ValueError("`stop` found in both the input and default params.")1033            params["stop"] = stop1034        message_dicts = [self._convert_message_to_dict(m) for m in messages]1035        return message_dicts, params10361037    def _use_responses_api(self, payload: dict) -> bool:1038        """Return True if `payload` should be routed through the Responses API.10391040        Honors `self.use_responses_api` when set explicitly; otherwise delegates1041        to the module-level `_use_responses_api` heuristic.1042        """1043        if isinstance(self.use_responses_api, bool):1044            return self.use_responses_api1045        return _use_responses_api(payload)10461047    def _to_responses_payload(1048        self,1049        message_dicts: list[dict[str, Any]],1050        params: dict[str, Any],1051        *,1052        user_set_keys: set[str] | None = None,1053    ) -> dict[str, Any]:1054        """Translate a Chat Completions-style payload to the Responses API shape.10551056        Renames `messages` to `input` and `max_tokens` to `max_output_tokens`.1057        `None`-valued params are dropped. Chat-Completions-only sampling/control1058        parameters that the Perplexity Responses (Agent) API does not accept1059        (`temperature`, `top_p`, `top_k`, `stop`, `metadata`) are dropped at1060        the boundary because the typed SDK signature would otherwise raise a1061        `TypeError`; every drop emits a `WARNING`-level log on each call,1062        except the class-default `temperature`, which is suppressed because1063        `_default_params` injects it on every call regardless of user intent.10641065        `tool_choice` is rejected with `ValueError` rather than dropped: it is1066        a control-flow primitive (forced/required tool selection) that agent1067        loops depend on, so silently disabling it would produce wrong1068        completions while returning HTTP 200.10691070        When a `preset` is supplied, `model` is dropped — the Agent API1071        validates `model` strictly (it expects `provider/model` format), and1072        a preset selects routing/model behavior on its own. If the user1073        explicitly set `model` (init or via `kwargs`), a `WARNING` is logged1074        so the override is discoverable.10751076        Unknown or Perplexity-specific keys (including `previous_response_id`1077        and `include`, documented Perplexity features that the typed SDK1078        signature does not currently expose) are forwarded under `extra_body`.10791080        Args:1081            message_dicts: Chat messages already serialized to the Chat1082                Completions shape; promoted to `payload["input"]`.1083            params: Merged invocation params from `_default_params` and the1084                per-call `kwargs`.1085            user_set_keys: Keys the user explicitly supplied for this call1086                (typically `set(kwargs)`). Used in combination with1087                `self.model_fields_set` to distinguish class defaults from1088                explicit user intent for `temperature` and `model`.10891090        Raises:1091            ValueError: If `tool_choice` is supplied — the Responses API1092                cannot honor it.1093            TypeError: If a caller supplied an `extra_body` that is not a1094                `dict` — silently dropping subsequent params would mask1095                user-set search/filter knobs.1096        """1097        payload: dict[str, Any] = {"input": _translate_responses_input(message_dicts)}1098        runtime_keys = user_set_keys or set()1099        user_set_temperature = (1100            "temperature" in self.model_fields_set or "temperature" in runtime_keys1101        )1102        user_set_model = "model" in self.model_fields_set or "model" in runtime_keys1103        # Collect dropped values so the warning can name them.1104        dropped_for_warning: dict[str, Any] = {}1105        for key, value in params.items():1106            if value is None:1107                continue1108            if key == "messages":1109                continue1110            if key in _RESPONSES_DROP_KEYS:1111                # Suppress the warning for the class-default `temperature`,1112                # which `_default_params` injects on every call and would1113                # otherwise spam users who never asked for it.1114                if key != "temperature" or user_set_temperature:1115                    dropped_for_warning[key] = value1116                continue1117            if key == "tool_choice":1118                msg = (1119                    "Perplexity Responses (Agent) API does not support "1120                    "`tool_choice`. Forced tool selection is unavailable on "1121                    "this route. Set `use_responses_api=False` to use Chat "1122                    "Completions, or remove `tool_choice` to let the model "1123                    "decide."1124                )1125                raise ValueError(msg)1126            if key == "max_tokens":1127                payload["max_output_tokens"] = value1128                continue1129            if key == "tools":1130                # Function tools must be flattened to the Responses-API shape;1131                # built-in tools (web_search, etc.) pass through unchanged.1132                payload["tools"] = [_flatten_responses_tool(tool) for tool in value]1133                continue1134            if key in _RESPONSES_PASSTHROUGH_KEYS:1135                payload[key] = dict(value) if isinstance(value, dict) else value1136                continue1137            # Unknown / Perplexity-specific keys: route under extra_body so the1138            # SDK forwards them to the Agent API without breaking strict typing.1139            extra_body = payload.setdefault("extra_body", {})1140            if not isinstance(extra_body, dict):1141                msg = (1142                    "`extra_body` must be a dict to forward Perplexity-specific "1143                    f"parameters to the Responses API, got "1144                    f"{type(extra_body).__name__}={extra_body!r}; cannot merge "1145                    f"user-set key {key!r}."1146                )1147                raise TypeError(msg)1148            extra_body[key] = value1149        # When the caller selected a preset, defer model selection to it: the1150        # Agent API rejects bare Chat-Completions model names like `sonar-pro`1151        # outright when `model` is set, even if a preset is also present.1152        if "preset" in payload:1153            dropped_model = payload.pop("model", None)1154            if user_set_model and dropped_model is not None:1155                logger.warning(1156                    "Perplexity Agent API rejects `model` when `preset` is "1157                    "set; dropping explicit model=%r in favor of preset=%r.",1158                    dropped_model,1159                    payload["preset"],1160                )1161        if dropped_for_warning:1162            logger.warning(1163                "Perplexity Responses (Agent) API does not accept %s; the "1164                "following values were dropped: %s. Use the Chat Completions "1165                "API (set `use_responses_api=False`) if you need them.",1166                sorted(dropped_for_warning),1167                dropped_for_warning,1168            )1169        return payload11701171    def _convert_delta_to_message_chunk(1172        self, _dict: Mapping[str, Any], default_class: type[BaseMessageChunk]1173    ) -> BaseMessageChunk:1174        role = _dict.get("role")1175        content = _dict.get("content") or ""1176        additional_kwargs: dict = {}1177        if _dict.get("function_call"):1178            function_call = dict(_dict["function_call"])1179            if "name" in function_call and function_call["name"] is None:1180                function_call["name"] = ""1181            additional_kwargs["function_call"] = function_call1182        if _dict.get("tool_calls"):1183            additional_kwargs["tool_calls"] = _dict["tool_calls"]11841185        if role == "user" or default_class == HumanMessageChunk:1186            return HumanMessageChunk(content=content)1187        elif role == "assistant" or default_class == AIMessageChunk:1188            return AIMessageChunk(content=content, additional_kwargs=additional_kwargs)1189        elif role == "system" or default_class == SystemMessageChunk:1190            return SystemMessageChunk(content=content)1191        elif role == "function" or default_class == FunctionMessageChunk:1192            return FunctionMessageChunk(content=content, name=_dict["name"])1193        elif role == "tool" or default_class == ToolMessageChunk:1194            return ToolMessageChunk(content=content, tool_call_id=_dict["tool_call_id"])1195        elif role or default_class == ChatMessageChunk:1196            return ChatMessageChunk(content=content, role=role)  # type: ignore[arg-type]1197        else:1198            return default_class(content=content)  # type: ignore[call-arg]11991200    def _stream(1201        self,1202        messages: list[BaseMessage],1203        stop: list[str] | None = None,1204        run_manager: CallbackManagerForLLMRun | None = None,1205        **kwargs: Any,1206    ) -> Iterator[ChatGenerationChunk]:1207        message_dicts, params = self._create_message_dicts(messages, stop)1208        runtime_keys = set(kwargs)1209        if stop is not None:1210            runtime_keys.add("stop")1211        params = {**params, **kwargs}1212        default_chunk_class = AIMessageChunk1213        params.pop("stream", None)1214        if self._use_responses_api({**params, "messages": message_dicts}):1215            responses_payload = self._to_responses_payload(1216                message_dicts, params, user_set_keys=runtime_keys1217            )1218            responses_payload["stream"] = True1219            stream_events = self.client.responses.create(**responses_payload)1220            # Trusts SDK SSE decoding (perplexityai>=0.34.1, upstream issue1221            # perplexityai-python#53). `_convert_responses_stream_event_to_chunk`1222            # already handles both SDK objects and dicts via `_get_attr`.1223            for event in stream_events:1224                response_chunk = _convert_responses_stream_event_to_chunk(event)1225                if response_chunk is None:1226                    continue1227                if run_manager:1228                    run_manager.on_llm_new_token(1229                        response_chunk.text, chunk=response_chunk1230                    )1231                yield response_chunk1232            return1233        if stop:1234            params["stop_sequences"] = stop1235        stream_resp = self.client.chat.completions.create(1236            messages=message_dicts, stream=True, **params1237        )1238        first_chunk = True1239        prev_total_usage: UsageMetadata | None = None12401241        added_model_name: bool = False1242        added_search_queries: bool = False1243        added_search_context_size: bool = False1244        for chunk in stream_resp:1245            if not isinstance(chunk, dict):1246                chunk = chunk.model_dump()1247            # Collect standard usage metadata (transform from aggregate to delta)1248            if total_usage := chunk.get("usage"):1249                lc_total_usage = _create_usage_metadata(total_usage)1250                if prev_total_usage:1251                    usage_metadata: UsageMetadata | None = subtract_usage(1252                        lc_total_usage, prev_total_usage1253                    )1254                else:1255                    usage_metadata = lc_total_usage1256                prev_total_usage = lc_total_usage1257            else:1258                usage_metadata = None1259            generation_info = {}1260            if (model_name := chunk.get("model")) and not added_model_name:1261                generation_info["model_name"] = model_name1262                added_model_name = True1263            if total_usage := chunk.get("usage"):1264                if num_search_queries := total_usage.get("num_search_queries"):1265                    if not added_search_queries:1266                        generation_info["num_search_queries"] = num_search_queries1267                        added_search_queries = True1268                if not added_search_context_size:1269                    if search_context_size := total_usage.get("search_context_size"):1270                        generation_info["search_context_size"] = search_context_size1271                        added_search_context_size = True12721273            choices = chunk.get("choices") or []1274            if len(choices) == 0:1275                # Usage-only or otherwise empty chunk: still yield so the stream1276                # is never empty and downstream callers receive usage metadata.1277                message = AIMessageChunk(content="", usage_metadata=usage_metadata)1278                yield ChatGenerationChunk(1279                    message=message, generation_info=generation_info or None1280                )1281                continue1282            choice = choices[0]12831284            additional_kwargs = {}1285            if first_chunk:1286                additional_kwargs["citations"] = chunk.get("citations", [])1287                for attr in ["images", "related_questions", "search_results"]:1288                    if attr in chunk:1289                        additional_kwargs[attr] = chunk[attr]12901291                if chunk.get("videos"):1292                    additional_kwargs["videos"] = chunk["videos"]12931294                if chunk.get("reasoning_steps"):1295                    additional_kwargs["reasoning_steps"] = chunk["reasoning_steps"]12961297            chunk = self._convert_delta_to_message_chunk(1298                choice["delta"], default_chunk_class1299            )13001301            if isinstance(chunk, AIMessageChunk) and usage_metadata:1302                chunk.usage_metadata = usage_metadata13031304            if first_chunk:1305                chunk.additional_kwargs |= additional_kwargs1306                first_chunk = False13071308            if finish_reason := choice.get("finish_reason"):1309                generation_info["finish_reason"] = finish_reason13101311            default_chunk_class = chunk.__class__1312            chunk = ChatGenerationChunk(message=chunk, generation_info=generation_info)1313            if run_manager:1314                run_manager.on_llm_new_token(chunk.text, chunk=chunk)1315            yield chunk13161317    async def _astream(1318        self,1319        messages: list[BaseMessage],1320        stop: list[str] | None = None,1321        run_manager: AsyncCallbackManagerForLLMRun | None = None,1322        **kwargs: Any,1323    ) -> AsyncIterator[ChatGenerationChunk]:1324        message_dicts, params = self._create_message_dicts(messages, stop)1325        runtime_keys = set(kwargs)1326        if stop is not None:1327            runtime_keys.add("stop")1328        params = {**params, **kwargs}1329        default_chunk_class = AIMessageChunk1330        params.pop("stream", None)1331        if self._use_responses_api({**params, "messages": message_dicts}):1332            responses_payload = self._to_responses_payload(1333                message_dicts, params, user_set_keys=runtime_keys1334            )1335            responses_payload["stream"] = True1336            stream_events = await self.async_client.responses.create(1337                **responses_payload1338            )1339            # See sync `_stream` for SDK trust rationale (perplexityai>=0.34.1).1340            async for event in stream_events:1341                response_chunk = _convert_responses_stream_event_to_chunk(event)1342                if response_chunk is None:1343                    continue1344                if run_manager:1345                    await run_manager.on_llm_new_token(1346                        response_chunk.text, chunk=response_chunk1347                    )1348                yield response_chunk1349            return1350        if stop:1351            params["stop_sequences"] = stop1352        stream_resp = await self.async_client.chat.completions.create(1353            messages=message_dicts, stream=True, **params1354        )1355        first_chunk = True1356        prev_total_usage: UsageMetadata | None = None13571358        added_model_name: bool = False1359        added_search_queries: bool = False1360        added_search_context_size: bool = False1361        async for chunk in stream_resp:1362            if not isinstance(chunk, dict):1363                chunk = chunk.model_dump()1364            if total_usage := chunk.get("usage"):1365                lc_total_usage = _create_usage_metadata(total_usage)1366                if prev_total_usage:1367                    usage_metadata: UsageMetadata | None = subtract_usage(1368                        lc_total_usage, prev_total_usage1369                    )1370                else:1371                    usage_metadata = lc_total_usage1372                prev_total_usage = lc_total_usage1373            else:1374                usage_metadata = None1375            generation_info = {}1376            if (model_name := chunk.get("model")) and not added_model_name:1377                generation_info["model_name"] = model_name1378                added_model_name = True1379            if total_usage := chunk.get("usage"):1380                if num_search_queries := total_usage.get("num_search_queries"):1381                    if not added_search_queries:1382                        generation_info["num_search_queries"] = num_search_queries1383                        added_search_queries = True1384                if not added_search_context_size:1385                    if search_context_size := total_usage.get("search_context_size"):1386                        generation_info["search_context_size"] = search_context_size1387                        added_search_context_size = True13881389            choices = chunk.get("choices") or []1390            if len(choices) == 0:1391                # Usage-only or otherwise empty chunk: still yield so the stream1392                # is never empty and downstream callers receive usage metadata.1393                message = AIMessageChunk(content="", usage_metadata=usage_metadata)1394                yield ChatGenerationChunk(1395                    message=message, generation_info=generation_info or None1396                )1397                continue1398            choice = choices[0]13991400            additional_kwargs = {}1401            if first_chunk:1402                additional_kwargs["citations"] = chunk.get("citations", [])1403                for attr in ["images", "related_questions", "search_results"]:1404                    if attr in chunk:1405                        additional_kwargs[attr] = chunk[attr]14061407                if chunk.get("videos"):1408                    additional_kwargs["videos"] = chunk["videos"]14091410                if chunk.get("reasoning_steps"):1411                    additional_kwargs["reasoning_steps"] = chunk["reasoning_steps"]14121413            chunk = self._convert_delta_to_message_chunk(1414                choice["delta"], default_chunk_class1415            )14161417            if isinstance(chunk, AIMessageChunk) and usage_metadata:1418                chunk.usage_metadata = usage_metadata14191420            if first_chunk:1421                chunk.additional_kwargs |= additional_kwargs1422                first_chunk = False14231424            if finish_reason := choice.get("finish_reason"):1425                generation_info["finish_reason"] = finish_reason14261427            default_chunk_class = chunk.__class__1428            chunk = ChatGenerationChunk(message=chunk, generation_info=generation_info)1429            if run_manager:1430                await run_manager.on_llm_new_token(chunk.text, chunk=chunk)1431            yield chunk14321433    def _generate(1434        self,1435        messages: list[BaseMessage],1436        stop: list[str] | None = None,1437        run_manager: CallbackManagerForLLMRun | None = None,1438        **kwargs: Any,1439    ) -> ChatResult:1440        if self.streaming:1441            stream_iter = self._stream(1442                messages, stop=stop, run_manager=run_manager, **kwargs1443            )1444            if stream_iter:1445                return generate_from_stream(stream_iter)1446        message_dicts, params = self._create_message_dicts(messages, stop)1447        runtime_keys = set(kwargs)1448        if stop is not None:1449            runtime_keys.add("stop")1450        params = {**params, **kwargs}1451        if self._use_responses_api({**params, "messages": message_dicts}):1452            responses_payload = self._to_responses_payload(1453                message_dicts, params, user_set_keys=runtime_keys1454            )1455            responses_payload.pop("stream", None)1456            response = self.client.responses.create(**responses_payload)1457            return _convert_responses_to_chat_result(response)1458        response = self.client.chat.completions.create(messages=message_dicts, **params)14591460        if hasattr(response, "usage") and response.usage:1461            usage_dict = response.usage.model_dump()1462            usage_metadata = _create_usage_metadata(usage_dict)1463        else:1464            usage_metadata = None1465            usage_dict = {}14661467        additional_kwargs = {}1468        for attr in ["citations", "images", "related_questions", "search_results"]:1469            if hasattr(response, attr) and getattr(response, attr):1470                additional_kwargs[attr] = getattr(response, attr)14711472        if hasattr(response, "videos") and response.videos:1473            additional_kwargs["videos"] = [1474                v.model_dump() if hasattr(v, "model_dump") else v1475                for v in response.videos1476            ]14771478        if hasattr(response, "reasoning_steps") and response.reasoning_steps:1479            additional_kwargs["reasoning_steps"] = [1480                r.model_dump() if hasattr(r, "model_dump") else r1481                for r in response.reasoning_steps1482            ]14831484        response_metadata: dict[str, Any] = {1485            "model_name": getattr(response, "model", self.model)1486        }1487        if num_search_queries := usage_dict.get("num_search_queries"):1488            response_metadata["num_search_queries"] = num_search_queries1489        if search_context_size := usage_dict.get("search_context_size"):1490            response_metadata["search_context_size"] = search_context_size14911492        message = AIMessage(1493            content=response.choices[0].message.content,1494            additional_kwargs=additional_kwargs,1495            usage_metadata=usage_metadata,1496            response_metadata=response_metadata,1497        )1498        return ChatResult(generations=[ChatGeneration(message=message)])14991500    async def _agenerate(1501        self,1502        messages: list[BaseMessage],1503        stop: list[str] | None = None,1504        run_manager: AsyncCallbackManagerForLLMRun | None = None,1505        **kwargs: Any,1506    ) -> ChatResult:1507        if self.streaming:1508            stream_iter = self._astream(1509                messages, stop=stop, run_manager=run_manager, **kwargs1510            )1511            if stream_iter:1512                return await agenerate_from_stream(stream_iter)1513        message_dicts, params = self._create_message_dicts(messages, stop)1514        runtime_keys = set(kwargs)1515        if stop is not None:1516            runtime_keys.add("stop")1517        params = {**params, **kwargs}1518        if self._use_responses_api({**params, "messages": message_dicts}):1519            responses_payload = self._to_responses_payload(1520                message_dicts, params, user_set_keys=runtime_keys1521            )1522            responses_payload.pop("stream", None)1523            response = await self.async_client.responses.create(**responses_payload)1524            return _convert_responses_to_chat_result(response)1525        response = await self.async_client.chat.completions.create(1526            messages=message_dicts, **params1527        )15281529        if hasattr(response, "usage") and response.usage:1530            usage_dict = response.usage.model_dump()1531            usage_metadata = _create_usage_metadata(usage_dict)1532        else:1533            usage_metadata = None1534            usage_dict = {}15351536        additional_kwargs = {}1537        for attr in ["citations", "images", "related_questions", "search_results"]:1538            if hasattr(response, attr) and getattr(response, attr):1539                additional_kwargs[attr] = getattr(response, attr)15401541        if hasattr(response, "videos") and response.videos:1542            additional_kwargs["videos"] = [1543                v.model_dump() if hasattr(v, "model_dump") else v1544                for v in response.videos1545            ]15461547        if hasattr(response, "reasoning_steps") and response.reasoning_steps:1548            additional_kwargs["reasoning_steps"] = [1549                r.model_dump() if hasattr(r, "model_dump") else r1550                for r in response.reasoning_steps1551            ]15521553        response_metadata: dict[str, Any] = {1554            "model_name": getattr(response, "model", self.model)1555        }1556        if num_search_queries := usage_dict.get("num_search_queries"):1557            response_metadata["num_search_queries"] = num_search_queries1558        if search_context_size := usage_dict.get("search_context_size"):1559            response_metadata["search_context_size"] = search_context_size15601561        message = AIMessage(1562            content=response.choices[0].message.content,1563            additional_kwargs=additional_kwargs,1564            usage_metadata=usage_metadata,1565            response_metadata=response_metadata,1566        )1567        return ChatResult(generations=[ChatGeneration(message=message)])15681569    @property1570    def _invocation_params(self) -> Mapping[str, Any]:1571        """Get the parameters used to invoke the model."""1572        pplx_creds: dict[str, Any] = {"model": self.model}1573        return {**pplx_creds, **self._default_params}15741575    @property1576    def _llm_type(self) -> str:1577        """Return type of chat model."""1578        return "perplexitychat"15791580    def bind_tools(1581        self,1582        tools: Sequence[dict[str, Any] | type | Callable | BaseTool],1583        *,1584        tool_choice: dict | str | bool | None = None,1585        strict: bool | None = None,1586        **kwargs: Any,1587    ) -> Runnable[LanguageModelInput, AIMessage]:1588        """Bind tool-like objects to this chat model.15891590        Client-side function tools require the Perplexity Responses (Agent) API:1591        construct the model with `use_responses_api=True` and a tool-capable1592        model such as `openai/gpt-5`. The `sonar` family does not support1593        client-side function tools.15941595        Args:1596            tools: A list of tool definitions to bind to this chat model.1597                Supports any tool handled by1598                [convert_to_openai_tool][langchain_core.utils.function_calling.convert_to_openai_tool]1599                (Pydantic models, `TypedDict` classes, callables, `BaseTool`,1600                or OpenAI-format dicts), as well as Perplexity built-in tools such1601                as `{"type": "web_search"}`, which are passed through unchanged.1602            tool_choice: Which tool the model should use. Normalized here for API1603                parity with `langchain-openai` (a tool name, `"auto"`, `"none"`,1604                `"any"`/`"required"`/`True`, or an OpenAI-style dict) and stored1605                on the binding, but the Perplexity Responses (Agent) API does not1606                currently honor it: a non-empty `tool_choice` makes1607                `_to_responses_payload` raise `ValueError` at invoke time on the1608                Responses route. The restriction can be relaxed if Perplexity1609                adds `tool_choice` support.1610            strict: If `True`, the tool parameter schema is sent with `strict`1611                enabled. If `None` (default), the flag is omitted.1612            kwargs: Any additional parameters are passed directly to `bind`.1613        """1614        formatted_tools = [1615            tool1616            if isinstance(tool, dict) and _is_builtin_tool(tool)1617            else convert_to_openai_tool(tool, strict=strict)1618            for tool in tools1619        ]1620        if tool_choice:1621            tool_names = [1622                t["function"]["name"] if "function" in t else t.get("name")1623                for t in formatted_tools1624            ]1625            if isinstance(tool_choice, str):1626                if tool_choice in tool_names:1627                    tool_choice = {1628                        "type": "function",1629                        "function": {"name": tool_choice},1630                    }1631                # 'any' is not native to the OpenAI schema; map it to 'required'1632                # for parity with providers that use 'any'.1633                elif tool_choice == "any":1634                    tool_choice = "required"1635            elif isinstance(tool_choice, bool):1636                tool_choice = "required"1637            elif isinstance(tool_choice, dict):1638                pass1639            else:1640                msg = (1641                    "Unrecognized tool_choice type. Expected str, bool or dict. "1642                    f"Received: {tool_choice}"1643                )1644                raise ValueError(msg)1645            kwargs["tool_choice"] = tool_choice1646        return super().bind(tools=formatted_tools, **kwargs)16471648    def with_structured_output(1649        self,1650        schema: _DictOrPydanticClass | None = None,1651        *,1652        method: Literal["json_schema"] = "json_schema",1653        include_raw: bool = False,1654        strict: bool | None = None,1655        **kwargs: Any,1656    ) -> Runnable[LanguageModelInput, _DictOrPydantic]:1657        """Model wrapper that returns outputs formatted to match the given schema for Preplexity.1658        Currently, Perplexity only supports "json_schema" method for structured output1659        as per their [official documentation](https://docs.perplexity.ai/guides/structured-outputs).16601661        Args:1662            schema: The output schema. Can be passed in as:16631664                - a JSON Schema,1665                - a `TypedDict` class,1666                - or a Pydantic class16671668            method: The method for steering model generation, currently only support:16691670                - `'json_schema'`: Use the JSON Schema to parse the model output167116721673            include_raw:1674                If `False` then only the parsed structured output is returned.16751676                If an error occurs during model output parsing it will be raised.16771678                If `True` then both the raw model response (a `BaseMessage`) and the1679                parsed model response will be returned.16801681                If an error occurs during output parsing it will be caught and returned1682                as well.16831684                The final output is always a `dict` with keys `'raw'`, `'parsed'`, and1685                `'parsing_error'`.1686            strict:1687                Unsupported: whether to enable strict schema adherence when generating1688                the output. This parameter is included for compatibility with other1689                chat models, but is currently ignored.16901691            kwargs: Additional keyword args aren't supported.16921693        Returns:1694            A `Runnable` that takes same inputs as a1695                `langchain_core.language_models.chat.BaseChatModel`. If `include_raw` is1696                `False` and `schema` is a Pydantic class, `Runnable` outputs an instance1697                of `schema` (i.e., a Pydantic object). Otherwise, if `include_raw` is1698                `False` then `Runnable` outputs a `dict`.16991700                If `include_raw` is `True`, then `Runnable` outputs a `dict` with keys:17011702                - `'raw'`: `BaseMessage`1703                - `'parsed'`: `None` if there was a parsing error, otherwise the type1704                    depends on the `schema` as described above.1705                - `'parsing_error'`: `BaseException | None`1706        """  # noqa: E5011707        if method in ("function_calling", "json_mode"):1708            method = "json_schema"1709        if method == "json_schema":1710            if schema is None:1711                raise ValueError(1712                    "schema must be specified when method is not 'json_schema'. "1713                    "Received None."1714                )1715            is_pydantic_schema = _is_pydantic_class(schema)1716            response_format = convert_to_json_schema(schema)1717            llm = self.bind(1718                response_format={1719                    "type": "json_schema",1720                    "json_schema": {"schema": response_format},1721                },1722                ls_structured_output_format={1723                    "kwargs": {"method": method},1724                    "schema": response_format,1725                },1726            )1727            output_parser = (1728                ReasoningStructuredOutputParser(pydantic_object=schema)  # type: ignore[arg-type]1729                if is_pydantic_schema1730                else ReasoningJsonOutputParser()1731            )1732        else:1733            raise ValueError(1734                f"Unrecognized method argument. Expected 'json_schema' Received:\1735                    '{method}'"1736            )17371738        if include_raw:1739            parser_assign = RunnablePassthrough.assign(1740                parsed=itemgetter("raw") | output_parser, parsing_error=lambda _: None1741            )1742            parser_none = RunnablePassthrough.assign(parsed=lambda _: None)1743            parser_with_fallback = parser_assign.with_fallbacks(1744                [parser_none], exception_key="parsing_error"1745            )1746            return RunnableMap(raw=llm) | parser_with_fallback1747        else:1748            return llm | output_parser

Code quality findings 1

Ensure functions have docstrings for documentation
info maintainability missing-docstring
def lc_secrets(self) -> dict[str, str]:

Get this view in your editor

Same data, no extra tab — call code_get_file + code_get_findings over MCP from Claude/Cursor/Copilot.

Generated by searchcode.com · powered by code_get_file + code_get_findings