"je%SrSSKJr SSKrSSKrSSKJr SSKJr SSK J r J r SSK J r SSKJrJr SS KJrJrJr SS KJrJr S S KJrJr S S KJr S SKJrJr S SK J!r!J"r"J#r#J$r$J%r%J&r&J'r'J(r( S SK)J*r*J+r+J,r,J-r-J.r. S SK/J0r0J1r1 SSK2J3r3 SSK4J5r5 SSK6J7r7 \*r8\.Rrr:Sr;"SS\5r<\"\<5r=Sr>\R~"S5r@S,SjrAS-SjrBSrCSrDS.SjrE\0"\E5RrG\GRrIS \JS!'\GRrL\ S/S"j5rMS0S#jrNS1S$jrOS1S%jrP\ "S&S'9"S(S)\5\55rQ\ "S*S+\7\55rRg)2u*Tool search toolset and strategy types. `ToolSearchToolset` wraps another toolset to support discovery of tools marked with `defer_loading=True`. It settles the one question that doesn't depend on which model serves the request — is this tool *searchable*? — and leaves the rest to [`Model.prepare_request`][pydantic_ai.models.Model.prepare_request], which can't be decided here because the model isn't known yet (think `FallbackModel`). The two questions a deferred tool raises are kept apart: * **Hidden until revealed** — true of every deferred tool. Carried by the authored `defer_loading` value, which stays set for the whole run, with current visibility travelling separately on `ModelRequestParameters.revealed_tool_names`. * **Member of the searchable corpus** — carried by `with_native='tool_search'`, and set only on deferred tools no on-demand capability gates. A capability-gated tool becomes available by loading its capability, never by querying for it. `Model.prepare_request` then decides, per model, how each hidden tool reaches the wire: * Where the provider can declare a tool but withhold its schema, hidden tools stay in `tools` behind the provider's deferral flag (Anthropic `defer_loading`, OpenAI Responses `defer_loading`) and a reveal unlocks them in place, leaving `tools` byte-identical across the reveal. * Otherwise hidden tools are kept off the wire entirely and arrive when they're revealed — as a full declaration on providers with a mid-conversation reveal item, or simply as a new `tools` entry where there's no such item. `search_tools`, the local discovery function, carries `unless_native='tool_search'` and is dropped by the adapter when the builtin is supported. When the capability commits to a named-native strategy with no local equivalent (`'bm25'`/`'regex'`) the toolset is constructed with `enable_fallback=False` and `search_tools` is not emitted at all — that way `_resolve_request_tools` raises on providers that can't honor the builtin, and the wire stays clean (just the native tool) on those that can. ) annotationsN)Sequence)deepcopy) dataclassreplace)cache) AnnotatedAny)Field TypeAdapterValidationError) TypedDict assert_never) AgentDepsT RunContext_NO_MATCHES_MESSAGE) ModelRetry UserError) ModelMessage ModelRequest ModelResponseNativeToolSearchReturnPartToolAvailabilityDeltaPartToolReturnPartToolSearchReturnPartpost_compaction_window)TOOL_SEARCH_FUNCTION_TOOL_NAMEToolSearchFuncToolSearchMatchToolSearchReturnContentToolSearchTool)ToolToolDefinition)is_gated_by_deferred_capability) ToolsetTool)WrapperToolsetdiscovered_toolsc$\rSrSr%SrS\S'Srg)_LegacyDiscoveryMetadataPa@Pre-typed-content metadata sideband shape. Earlier versions stashed discovered tool names on `ToolReturnPart.metadata['discovered_tools']` instead of on the typed `content`. Validating against this shape via Pydantic keeps the legacy reader honest about what it accepts; new writes always go through the typed content. list[str]r*N__name__ __module__ __qualname____firstlineno____doc____annotations____static_attributes__r/^/home/mande/repo/quber/.venv/lib/python3.13/site-packages/pydantic_ai/toolsets/_tool_search.pyr,r,Ps r8r, z [a-z0-9]+cZ[[RUR555$)uLowercase + extract alphanumeric tokens for keyword matching. Used for both the query and the indexed terms (tool name + description) so matching is case-insensitive and word-bounded — `me` matches `get_me` but not the substring inside `comment`. )set_SEARCH_TOKEN_REfindalllower)texts r9 _tokenizerAcs! '' 5 66r8cv[SRU55nU(d/$/nUHan[URSUR=(d S35n[ X6-5nUS:dMEUR XuR45 Mc UR SSS9 UVV s/sHupU PM sn n$s sn nf)uSBuilt-in keyword-overlap search algorithm exposed as a [`ToolSearchFunc`][pydantic_ai.capabilities.ToolSearchFunc]. Score each tool by how many query keywords appear in its name or description, then return matching names ordered by descending score. Used both as the default algorithm when `ToolSearch` was constructed without an explicit strategy AND as the explicit `strategy='keywords'` choice — the difference is that the explicit choice routes through the same dispatch path as a user-supplied callable, which enables client-executed-native wire on supporting providers (cache benefit).  rc US$)Nrr/items r9$keywords_search_fn..sar8Tkeyreverse)rAjoinname descriptionlenappendsort) _ctxqueriestoolstermsscoredtool_def tool_termsscore_rNs r9keywords_search_fnr\ms chhw' (E  $&F(--(2F2F2L"1MNO E&' 19 MM5--0 1   KK($K7 & 'WQD '' 's#B5aDSearch first for a standalone deferred tool when current tools and catalog descriptions do not name the requested operation. A capability id used as an ordinary domain word does not request that capability. This cannot find capability-owned tools; load a listed capability by id instead. If no tools are found, do not retry.zList of search queries to match against tool names and descriptions. Use specific words likely to appear in tool names or descriptions to narrow down relevant tools. Each query is independently tokenized; matches across queries are unioned.c[e)uSource-of-truth signature for the `search_tools` function tool. Used by [`Tool`][pydantic_ai.tools.Tool] to derive the JSON schema and validator that go on the `ToolDefinition` we hand to the model. Wrapping the function in a `Tool` (rather than hand-rolling a `TypedDict` + `TypeAdapter`) keeps schema generation aligned with how every other tool in the framework is defined. Parameter is `queries: list[str]` to match the cross-provider [`ToolSearchArgs`][pydantic_ai.messages.ToolSearchArgs] shape — so the same typed [`ToolSearchCallPart`][pydantic_ai.messages.ToolSearchCallPart] represents both model-emitted local calls AND cross-provider-synthesized history (Anthropic native `bm25`/`regex` and OpenAI Responses `tool_search_call`, both normalized to `queries`). )NotImplementedError)rTs r9_search_tools_signaturer_s r8dict[str, Any]_SEARCH_TOOL_SCHEMAcpU[:Xa [[4$[[5nXSSS'U[4$)ugReuse the default schema/validator or splice in a custom `queries` description. Cached per-description: with the default description the call is a constant-time lookup that returns the module-level schema and validator (`Tool(fn).function_schema` is the source of truth for both). A custom description gets a per-description rebuild whose result is memoized — the framework only pays schema-construction cost on the first run with a given override. The custom path splices `parameter_description` into the existing JSON schema rather than rebuilding from a closure-bound signature: `from __future__ import annotations` stringifies the type expression, so a closure-captured `parameter_description` would be unresolvable when `Tool` re-evaluates the string at schema-derivation time. The validator is unaffected by description, so we can safely reuse the default one. propertiesrTrO)_DEFAULT_PARAMETER_DESCRIPTIONra_SEARCH_TOOL_VALIDATORr)parameter_descriptionschemas r9_build_search_args_schemarhsB  >>"$::: ) *F5J<#M2 ) ))r8c*[[U55$)uqScan visible message history for previously-discovered tool names. Every [`CompactionPart`][pydantic_ai.messages.CompactionPart] resets the derived state at its exact position in a response. This is deliberately provider-agnostic: over-counting can prevent rediscovery or claim a schema is visible when it is not, while under-counting once only permitted a redundant, idempotent search. Now that availability gates execution, an under-count also *refuses* the call — see [`post_compaction_window`][pydantic_ai.messages.post_compaction_window] for when that is wrong and what is tracked to fix it. Trusts that any `ToolSearchReturnPart` / `NativeToolSearchReturnPart` in the history has a validated `ToolSearchReturnContent`: Pydantic's discriminator dispatch promotes from base parts on deserialization, and direct construction goes through the typed-class `__init__` (which Pydantic validates). No defensive isinstance walks needed. Also reads the legacy `metadata['discovered_tools']` sideband (validated against a TypedDict) so histories serialized before the typed-content migration continue to surface previously-discovered tools. Only the [`post_compaction_window`][pydantic_ai.messages.post_compaction_window] is scanned — the one definition of the boundary — so locating it costs a cheap reverse `isinstance` pass rather than parsing history the boundary would reset anyway. )r<discovered_tool_names_in_ordermessagess r9parse_discovered_toolsrms2 -h7 88r8c*[[U55$)a Return discovered names in first-appearance order for byte-stable provider tool segments. Scans only the [`post_compaction_window`][pydantic_ai.messages.post_compaction_window], so both the reveal set and the wire ordering derive from what the model can actually see. )_discovered_tool_names_in_orderrrks r9rjrjs ++A(+K LLr8c0nUGHn[U[5(GaURGH n[U[5(a0UR [ R UR55 MI[U[5(a7UR [ R SUR555 M[U[5(dMUR[:XdM[RUR5nUR [ R US55 GM GM7[U["5(abURHOn[U[$5(dMUR [ R SUR555 MQ GM['U5 GM [)U5$![ a GMf=f)zAParse discovery evidence from an already-selected message window.c3*# UH oSv M g7frNNr/.0matchs r9 2_discovered_tool_names_in_order..3eOde&MOdr*c3*# UH oSv M g7frrr/rss r9rvrwrxry) isinstancerpartsrupdatedictfromkeys tools_addedrr*r tool_name_SEARCH_TOOLS_NAME_LEGACY_METADATA_TAvalidate_pythonmetadatar rrrtuple)rl discoveredmsgpart validateds r9rorosR"$J c< ( ( d$=>>%%dmmD4D4D&EF&:;;%%dmm3etOdOd3e&efn55$..L^:^ !$7$G$G $V %%dmmI>P4Q&RS"] + + d$>??%%dmm3etOdOd3e&ef"  -.  +! !s.G GGT)kw_onlyc.\rSrSr%SrS\S'S\S'Srg) _SearchTooliu)The local `search_tools` function, carrying the corpus it should search over. The real `ToolDefinition`s flow through to user-supplied search functions so callables can read whatever metadata they need (parameters schema, kind, etc.) — not just the name/description pair we'd otherwise expose. zlist[ToolDefinition]corpusset[str]discovered_tool_namesr/Nr0r/r8r9rrs ! ##r8rcB\rSrSr%SrSrS\S'\rS\S'Sr S\S 'Sr S\S 'S r S \S 'Sr S\S'SSjr SSjrSSjr\SSj5rSSjrSSjrS Sjr\S!Sj5r\S"Sj5rSrg)#ToolSearchToolsetiuA toolset that enables tool discovery for large toolsets. Wraps another toolset and exposes a `search_tools` function that lets the model discover tools with `defer_loading=True`. Tools with `defer_loading=True` are not initially presented to the model — they become available after the model discovers them via search. When the model supports the framework-managed tool-search builtin, discovery is handled by the provider and the deferred tools are sent to the API with `defer_loading=True` on the wire. Nz!ToolSearchFunc[AgentDepsT] | None search_fnint max_results str | Nonetool_descriptionrfTboolenable_fallbackz int | None max_retriesc b# URRU5IShvN n0n0nUR5H*upVURR(aXcU'M&XdU'M, U(dU$[ U;a[ S[ S35e[U5n0nUR5HKupV[XR5(aXgU'M%XhU'[U[UR[S9S9Xu'MM UR(aU(aURX5U[ 'U$GN 7f)Nz Tool name 'zC' is reserved for tool search. Rename your tool to avoid conflicts.) with_native)rX) wrapped get_toolsitemsrX defer_loadingrrr~r'r_TOOL_SEARCH_BUILTIN_IDr_build_search_tool) selfctx all_toolsdeferredvisiblerNtoolresult searchables r9rToolSearchToolset.get_toolsNs,,0055 7968#//+JD}}**!% $ ,    *011tu 6:']:< "..*JD.sMMBB#t #'4 &tgdmmYp6qr +.   J)-)@)@)QF% & m6sD/D,D D/c UR=(d [n[U5upEUR5Vs/sHofRPM nnUR c[ OSn[[UR=(d [USUS9n [UU URb URO URUU[UR5S9$s snf)Nz tool-search)rNrOparameters_json_schema tool_kind unless_native)toolsetrXrargs_validatorrr)rfrdrhvaluesrXrrr%rr_DEFAULT_TOOL_DESCRIPTIONrrr<r) rrrrfrgrrrrsearch_tool_defs r9r$ToolSearchToolset._build_search_tools !% : : \>\!:;P!Q -7,=,=,?@,?D--,?@48>>3I/t (#--J1J#)#'  $,0,<,<,H((coo)"%c&?&?"@   +AsCc# U[:Xa/[U[5(aURX#U5IShvN $URR XX45IShvN $N(N7fN)rr{r _search_toolsr call_tool)rrN tool_argsrrs r9rToolSearchToolset.call_toolsU % %*T;*G*G++IDAA A\\++DSGGGBGs!5A$A #A$A"A$"A$c[[RUR555nU(a2UR [RUR555 U$r)r<r=r>r?r})rNrO search_termss r9 _search_termsToolSearchToolset._search_termssJ+33DJJLAB     0 8 89J9J9L M Nr8c# USn[SU55(d [S5eURnUbURXTX#5IShvN $UR XC5$N7f)zFRun the configured search strategy over all searchable deferred tools.rTc3@# UHoR5v M g7fr)strip)rtqs r9rv2ToolSearchToolset._search_tools..s.g7799gs3Please provide at least one non-empty search query.N)anyrr_run_search_fn_run_keywords_search)rrr search_toolrTfns r9rToolSearchToolset._search_toolssi'y1.g...RS S ^^ >,,R#KK K((>>LsA A&A$A&c<URSRU5S5nU(d [S5e/nURHunURURUR 5n[ X6-5nUS:XaM>URURUR;USUR045 Mw U(dUR5$URSSS9 USURVV s/sHu pU PM n nn URU 5$s sn nf) uScore each tool by how many query tokens appear in its name/description. Tokenizes on alphanumeric runs for both the queries and the indexed terms, so the top hit for "github profile" is `github_get_me` (two matches) without matching substrings inside longer words like `comment` for the query `me`. Tokens from all queries are unioned — the same token-overlap score applies across the set. rCNrrrNcUSUS4$)Nrr&r/rFs r9rH8ToolSearchToolset._run_keywords_search..sd1gtAw-?r8TrJ) rrMrrrNrOrPrQr _empty_returnrRr _build_return) rrTrrVscored_matchesrXrYrZr[rumatchess r9r&ToolSearchToolset._run_keywords_searchs""388G#4d;RS SBD#**H++HMM8;O;OPJ*+Ez  ! !k&G&GGQWYaYfYfPgh  +%%' '  ?N,:;MT=M=M,NO,N[Q5,NO!!'**Ps5Dc# URVs0sHoURU_M nnU"X2UR5n[R"U5(a UIShvN n/n[ U5SUR H6n UR U 5=ncMURSUR05 M8 U(dUR5$URU5$s snfN7f)zNInvoke a user-provided strategy, validating that the returned names are known.NrN) rrNinspect isawaitablelistrgetrQrr) rrrTrrrXtool_defs_by_namerrrNs r9r ToolSearchToolset._run_search_fnsFQEWEWXEW]]H4EWXC+"4"45   v & &!\F)+L!34#3#34D-11$77D 675%%' '!!'**Y"s"C$C5C$C"3C$AC$c/[S.$)uShaped "no matches" return: empty discovered_tools list with a user-visible message. Sending only the typed [`ToolSearchReturnContent`][pydantic_ai.messages.ToolSearchReturnContent] is enough — the JSON-serialized return value carries the message to the model, so it doesn't retry searching with the same keywords; adapters that need the message on the wire (Anthropic custom-callable empty-results path) read it from there too. )r*messagerr/r8r9rToolSearchToolset._empty_returns!#*  r8c SU0$)zgShaped matches return: typed [`ToolSearchReturnContent`][pydantic_ai.messages.ToolSearchReturnContent].r*r/)rs r9rToolSearchToolset._build_returns#G,,r8r/)rRunContext[AgentDepsT]return"dict[str, ToolsetTool[AgentDepsT]])rrrrr_SearchTool[AgentDepsT]) rNstrrr`rrrzToolsetTool[AgentDepsT]rr )rNrrOrrr)rr`rrrrrr")rT Sequence[str]rrrr") rzToolSearchFunc[AgentDepsT]rTrrrrrrr")rr")rzlist[ToolSearchMatch]rr")r1r2r3r4r5rr6_MAX_SEARCH_RESULTSrrrfrrrrr staticmethodrrrrrrr7r/r8r9rrst 48I07+K*H#'j'P(,:,L OT Q#K" 7r' #' 7'  ! ' RHH$2H9OHWnH H ?' ?.D ?Sj ?  ? +$ +3J +  +D+ &++$ + - + ! +.    --r8r)r@rrr)rSzRunContext[Any]rTrrUzSequence[ToolDefinition]rr.)rTzGAnnotated[list[str], Field(description=_DEFAULT_PARAMETER_DESCRIPTION)]rr")rfrrztuple[dict[str, Any], Any])rlSequence[ModelMessage]rr)rlrrztuple[str, ...])Sr5 __future__rrrecollections.abcrcopyr dataclassesrr functoolsrtypingr r pydanticr r r typing_extensionsrr _run_contextrr _tool_searchr exceptionsrrrlrrrrrrrrnative_tools._tool_searchrr r!r"r#rUr$r%_capability_ownedr'abstractr(wrapperr)rkindr%_LEGACY_DISCOVERED_TOOLS_METADATA_KEYr,rrcompiler=rAr\rrdr_function_schema_SEARCH_TOOL_FN_SCHEMA json_schemarar6 validatorrerhrmrjrorrr/r8r9rsx!F# $*!8851..   )>!#3(--(:%  y  "":;::l+7(0,R T&56FF&<&H&H^H/99**.98M: 4+j)( z-z2z- z-r8