ó
    ±"³j¾)  ã                  óô   • S r SSKJr  SSKJr  SSKJrJrJr  SSK	J
r
Jr  SSKJrJr  SSKJrJrJrJr  SS	KJrJr  SS
KJr  SSKJrJr  SSKJr  SSKJrJ r   \
(       a  SSK!J"r"  \ " S S\\   5      5       r#g)zFTool search capability: provider-adaptive discovery of deferred tools.é    )Úannotations)ÚSequence)ÚKW_ONLYÚ	dataclassÚfield)ÚTYPE_CHECKINGÚClassVaré   )Ú
AgentDepsTÚ
RunContext)ÚToolSearchFuncÚToolSearchNativeStrategyÚToolSearchStrategyÚToolSearchTool)ÚAgentNativeToolÚToolDefinition)ÚAbstractToolset)ÚToolSearchToolsetÚkeywords_search_fné   ©Úrecord_loaded_capability_tools)ÚAbstractCapabilityÚCapabilityOrdering)ÚModelRequestContextc                  óÚ   • \ rS rSr% SrSrS\S'    SrS\S'    SrS	\S
'    Sr	S	\S'    S\S'   Sr
S	\S'    \" SSSS9rS\S'   SS jrSS jrSS jrS S jr      S!S jrSrS\S'   Srg)"Ú
ToolSearché#   u 	  Capability that provides tool discovery for large toolsets.

Tools marked with `defer_loading=True` are hidden from the model until discovered.
Auto-injected into every agent â€” zero overhead when no deferred tools exist.

When the model supports native tool search (Anthropic BM25/regex, OpenAI Responses),
discovery is handled by the provider: the deferred tools are sent with `defer_loading`
on the wire and the provider exposes them once they've been discovered. Otherwise,
discovery happens locally via a `search_tools` function that the model can call.

On providers that support a native "client-executed" surface (Anthropic, OpenAI),
the discovery message is delivered append-only â€” prompt cache is preserved across
discovery turns, so growing the message history with discovered-tool results does
not invalidate the cached prefix.

```python
from collections.abc import Sequence

from pydantic_ai import Agent, RunContext, Tool
from pydantic_ai.capabilities import ToolSearch
from pydantic_ai.tools import ToolDefinition


# Tools become deferred via `defer_loading=True`. They stay hidden from the model
# until tool search discovers them.
def get_weather(city: str) -> str:
    ...


weather_tool = Tool(get_weather, defer_loading=True)

# Default: native search on supporting providers, local keyword matching elsewhere.
agent = Agent('anthropic:claude-sonnet-4-6', tools=[weather_tool], capabilities=[ToolSearch()])

# Force a specific Anthropic native strategy; errors on providers that can't honor it.
agent = Agent(
    'anthropic:claude-sonnet-4-6',
    tools=[weather_tool],
    capabilities=[ToolSearch(strategy='regex')],
)

# Always run the local keyword-overlap algorithm, regardless of provider.
agent = Agent(
    'anthropic:claude-sonnet-4-6',
    tools=[weather_tool],
    capabilities=[ToolSearch(strategy='keywords')],
)

# Custom search function â€” used locally, and by provider-native "client-executed"
# modes when supported.
def my_search(
    ctx: RunContext, queries: Sequence[str], tools: Sequence[ToolDefinition]
) -> list[str]:
    return [
        t.name
        for t in tools
        if any(q.lower() in (t.description or '').lower() for q in queries)
    ]

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    tools=[weather_tool],
    capabilities=[ToolSearch(strategy=my_search)],
)
```
Nz%ToolSearchStrategy[AgentDepsT] | NoneÚstrategyé
   ÚintÚmax_resultsz
str | NoneÚtool_descriptionÚparameter_descriptionr   Ú_Útool_searchÚidF)ÚinitÚreprÚdefaultz!ToolSearchFunc[AgentDepsT] | NoneÚ
_search_fnc                ó¢   • U R                   S:X  a  [        U l        g [        U R                   5      (       a  U R                   U l        g S U l        g )NÚkeywords)r   r   r+   Úcallable©Úselfs    Úb/home/mande/repo/quber/.venv/lib/python3.13/site-packages/pydantic_ai/capabilities/_tool_search.pyÚ__post_init__ÚToolSearch.__post_init__“   s8   € ð �=‰=˜JÓ&Ü0ˆD�OÜ�d—m‘m×$Ñ$Ø"Ÿm™mˆD�Oà"ˆD�Oó    c                ó   • [        SS9$ )NÚ	outermost)Úposition)r   r/   s    r1   Úget_orderingÚToolSearch.get_ordering¡   s   € Ü!¨;Ñ7Ð7r4   c                óÈ   • U R                   S:X  d  [        U R                   5      (       a  [        SSS9/$ U R                   c
  [        SS9/$ U R                   n[        USS9/$ )Nr-   ÚcustomT)r   Úoptional)r<   F)r   r.   r   )r0   Únameds     r1   Úget_native_toolsÚToolSearch.get_native_tools¤   sc   € ð �=‰=˜JÓ&¬(°4·=±=×*AÑ*AÜ"¨H¸tÑDÐEÐEð �]‰]Ñ"Ü"¨DÑ1Ð2Ð2ð /3¯m©mˆEÜ"¨E¸EÑBÐCÐCr4   c           	     óˆ   • [        UU R                  U R                  U R                  U R                  U R
                  S;  S9$ )N)Úbm25Úregex)ÚwrappedÚ	search_fnr"   r#   r$   Úenable_fallback)r   r+   r"   r#   r$   r   )r0   Útoolsets     r1   Úget_wrapper_toolsetÚToolSearch.get_wrapper_toolset¼   sC   € ô" !ØØ—o‘oØ×(Ñ(Ø!×2Ñ2Ø"&×"<Ñ"<Ø ŸM™MÐ1BÑBñ
ð 	
r4   c              ƒ  ó    #   • [        X5      $ 7f)z+Record tools unlocked by a capability load.r   )r0   ÚctxÚrequest_contexts      r1   Úbefore_model_requestÚToolSearch.before_model_requestÖ   s   é € ô .¨cÓCÐCùs   ‚Úsearch_toolszClassVar[str]Úfunction_tool_name)r+   )ÚreturnÚNone)rP   r   )rP   z%Sequence[AgentNativeTool[AgentDepsT]])rF   úAbstractToolset[AgentDepsT]rP   rR   )rJ   zRunContext[AgentDepsT]rK   r   rP   r   )Ú__name__Ú
__module__Ú__qualname__Ú__firstlineno__Ú__doc__r   Ú__annotations__r"   r#   r$   r'   r   r+   r2   r8   r>   rG   rL   rO   Ú__static_attributes__© r4   r1   r   r   #   s»   ‡ ñAðF 7;€HÐ3Ó:ðð$ €K�ÓØKà#'Ð�jÓ'ðð )-Ð˜:Ó,ØVàƒJà"€Bˆ
Ó"ðñ 5:¸uÈ5ÐZ^Ñ4_€JÐ1Ó_ô#ô8ôDô0
ð4DØ)ðDØ<OðDà	ôDð )7Ð˜Ó6ÚZr4   r   N)$rW   Ú
__future__r   Úcollections.abcr   Údataclassesr   r   r   Útypingr   r	   Ú_run_contextr   r   Únative_tools._tool_searchr   r   r   r   Útoolsr   r   Útoolsetsr   Útoolsets._tool_searchr   r   Ú_deferred_capabilitiesr   Úabstractr   r   Úmodelsr   r   rZ   r4   r1   Ú<module>rg      sd   ðÙ Lå "å $ß 1Ñ 1ß *ç 1÷ó ÷õ 'ß IÝ Bß <æÝ,ð ô}[Ð# JÑ/ó }[ó ñ}[r4   