id dZddlmZddlZddlZddlmZmZddlm Z ddl m Z m Z m Z mZmZddlZddlmZmZmZmZmZmZmZmZmZmZmZmZmZddlmZ dd lm!Z"dd l#m$Z$dd l%m&Z&dd l'm(Z(dd l)m*Z*ddl+m,Z,ddl-m.Z.ddl/m0Z0ddl1m2Z2ddl3m4Z4ddl5m6Z6ddl7m8Z8e6e9Z:e rddl;me Gdde e=Z?e GddZ@ d)dZAd*dZB d+dZC d, d-dZD d.d ZE d/d!ZF d0d"ZGd1d#ZHddddddd$ddd% d2d&ZIddddddddd' d3d(ZJy)4z8Sampling types and helper functions for FastMCP servers.) annotationsN)CallableSequence) dataclass) TYPE_CHECKINGAnyGenericLiteralcast) ClientCapabilitiesCreateMessageResultCreateMessageResultWithTools ModelHintModelPreferencesSamplingCapabilitySamplingMessageSamplingMessageContentBlockSamplingToolsCapability TextContent ToolChoiceToolResultContentToolUseContent)CreateMessageRequestParams)Tool)ValidationError)TypeVar)settings) ToolError) SamplingTool) FunctionTool)TransformedTool)gather)compress_schema) get_logger)get_cached_typeadapter)ContextResultTautorequirednonec0eZdZUdZded<ded<ded<y) SamplingResultaResult of a sampling operation. Attributes: text: The text representation of the result (raw text or JSON for structured). result: The typed result (str for text, parsed object for structured output). history: All messages exchanged during sampling. str | Nonetextr'resultlist[SamplingMessage]historyN)__name__ __module__ __qualname____doc____annotations__k/Users/bowang/.openclaw/workspace/ChatDev/.venv/lib/python3.12/site-packages/fastmcp/server/sampling/run.pyr-r-5s  O ""r9r-c\eZdZUdZded<ded<ed dZed dZed dZy ) SampleStepzsResult of a single sampling call. Represents what the LLM returned in this step plus the message history. 2CreateMessageResult | CreateMessageResultWithToolsresponser1r2cjt|jtr|jjdk(Sy)z-True if the LLM is requesting tool execution.toolUseF) isinstancer>r stopReason)selfs r: is_tool_usezSampleStep.is_tool_useNs+ dmm%A B==++y8 8r9c|jj}t|tr&|D] }t|ts|j cSyt|tr |j Sy)z-Extract text from the response, if available.N)r>contentrAlistrr/)rCrFblocks r:r/zSampleStep.textUsW--'' gt $ e[1 ::%!  -<< r9c|jj}t|tr!|Dcgc]}t|ts|c}St|tr|gSgScc}w)z-Get the list of tool calls from the response.)r>rFrArGr)rCrFcs r: tool_callszSampleStep.tool_callsbsX--'' gt $&Hw!*Q*GAwH H  09  Is AAN)returnbool)rLr.)rLlist[ToolUseContent]) r3r4r5r6r7propertyrDr/rKr8r9r:r<r<DsP A@ ""    r9r<c<|yt|tr|St|trtt|gSt|trAt d|Ds t dt|Dcgc]}t|c}St dcc}w)z5Convert model preferences to ModelPreferences object.N)name)hintsc3<K|]}t|tywN)rAstr).0hs r: z+_parse_model_preferences..xsA/@!:a%/@sz7All elements of model_preferences list must be strings.zLmodel_preferences must be one of: ModelPreferences, str, list[str], or None.)rArrUrrGall ValueError)model_preferencesrWs r:_parse_model_preferencesr\ms  %'7 8  %s +y6G'H&IJJ %t ,A/@AAVW WBS&TBSQya'8BS&TUU Z  'Us3Bc4|j}|j}|jtt }|jtt t }|j dk(r|j tdy|j dk(r7|xr| xs|}|s)|j|r|r |s tdtd yy |j td |j d |s td |r |s tdy ) aqDetermine whether to use fallback handler or client for sampling. Args: context: The MCP context. needs_tools: Whether the sampling request requires tool support. Returns: True if fallback handler should be used, False to use client. Raises: ValueError: If client lacks required capability and no fallback configured. )sampling) capability)toolsalwaysz?sampling_handler_behavior is 'always' but no handler configuredTfallbackzeClient does not support sampling with tools. The client must advertise the sampling.tools capability.z Client does not support samplingz#Invalid sampling_handler_behavior: z(. Must be 'always', 'fallback', or None.F) fastmcpsessioncheck_client_capabilityr rrsampling_handler_behaviorsampling_handlerrZ)context needs_toolsrcrd has_samplinghas_tools_capabilityclient_sufficients r:determine_handler_modermsZooGooG22%/A/CD3L#::%'.E.GH ; ((H4  # # +Q   * *j 8(V+o.UAU ''/<8L$S!!CDD   * * 61'2S2S1VW5 5  ;<< 1 G  r9c K|jj td|j td|jj|t ||||t ||||j}t j|r |d{}t|trtdtd|dd S|S70w) zMake LLM call using the fallback handler. Note: This function expects the caller (sample_step) to have validated that sampling_handler is set via determine_handler_mode(). The checks below are safeguards against internal misuse. Nzsampling_handler is Nonezrequest_context is None) systemPromptmessages temperature maxTokensmodelPreferencesr` toolChoice assistantr/typer/unknownendTurn)rolerFmodelrB) rcrg RuntimeErrorrequest_contextSamplingParamsr\inspect isawaitablerArUr r) rhrp system_promptrq max_tokensr[ sdk_tools tool_choicer0s r:call_sampling_handlerrs"''/566&455 __ - -&# 56GH"   F6"&#"V&9    MsBCC1Cc K||dkrtd|dfd t fd|D}||r,g}|D]#} |d{}|j|%|S|dk(r$t|Dcgc] } | c}d{St j | d fd } t|Dcgc] }| | c}d{S7cc}w7Kcc}w7w)aExecute tool calls and return results. Args: tool_calls: List of tool use requests from the LLM. tool_map: Mapping from tool name to SamplingTool. mask_error_details: If True, mask detailed error messages from tool execution. When masked, only generic error messages are returned to the LLM. Tools can explicitly raise ToolError to bypass masking when they want to provide specific error messages to the LLM. tool_concurrency: Controls parallel execution of tools: - None (default): Sequential execution (one at a time) - 0: Unlimited parallel execution - N > 0: Execute at most N tools concurrently If any tool has sequential=True, all tools execute sequentially regardless of this setting. Returns: List of tool result content blocks in the same order as tool_calls. NrzItool_concurrency must be None, 0 (unlimited), or a positive integer, got c Kj|j}|3td|jt dd|jdgdS |j |j d{}td|jt dt|g S71#t$r[}tjd |jdtd|jt dt|gdcYd}~Sd}~wt$rw}tjd |jdrd |jd}nd |jd |}td|jt d|gdcYd}~Sd}~wwxYww) z,Execute a single tool and return its result.N tool_resultr/zError: Unknown tool ''rvTrw toolUseIdrFisError)rwrrFzError calling sampling tool 'zError executing tool 'z': ) getrQridrruninputrUrlogger exception Exception)tool_usetool result_valuee error_textmask_error_detailstool_maps r:_execute_single_toolz+execute_tools.._execute_single_toolss||HMM* <$""++#4X]]O1E    !%(..!99L$""++$&s<7HIJ :     ?       F ?F F  F c3pK|]-}j|jxj/ywrT)rrQ sequential)rVrrrs r:rXz execute_tools..@s5"HLL/ /D < "s36cK4d{|d{cdddd{S7%77 #1d{7swYyxYwwrTr8)rr semaphores r:bounded_executez&execute_tools..bounded_executeVs1 y1(;;!yy;!yyysEA 0A  626 A 4A 6A A? AA )rrrLr)rZanyappendr"anyio Semaphore) rKrrtool_concurrencyrequires_sequential tool_resultsrr0tcrrrrs `` @@@r: execute_toolsrs2#(81(<#$ &  ,^"#602 "H/99F    '#1L2226LMMMOO$45  <JGJbob1JGHHH!:MMHHsNAC"C'C"7CC" C)C"7CC" C C"C"C"c t|trtt|ddgS|Dcgc],}t|trtt|ddn|.c}Scc}w)zEConvert various message formats to a list of SamplingMessage objects.r/)r/rwuser)rFrz)rArUrr)rpms r:prepare_messagesr`sy(C #?f     !S! KQV$D6 R     s1A"cl|yg}|D]}t|tr|j|%t|ttfr%|jtj |`t |r%|jtj|tdt||r|SdS)aConvert tools to SamplingTool objects. Accepts SamplingTool instances, FunctionTool instances, TransformedTool instances, or plain callable functions. FunctionTool and TransformedTool are converted using from_callable_tool(), while plain functions use from_function(). Args: tools: Sequence of tools to prepare. Can be SamplingTool, FunctionTool, TransformedTool, or plain callable functions. Returns: List of SamplingTool instances, or None if tools is None. NzGExpected SamplingTool, FunctionTool, TransformedTool, or callable, got ) rArrr r!from_callable_toolcallable from_function TypeErrorrw)r`sampling_toolsts r: prepare_toolsrss" })+N  a &  ! !! $ L/: ;  ! !,"A"A!"D E a[  ! !,"<"55r9c|j}t|tr!|Dcgc]}t|ts|c}St|tr|gSgScc}w)z#Extract tool calls from a response.)rFrArGr)r>rFrJs r:extract_tool_callsrsTG'4 "D7ajN&C7DD G^ ,y IEs AAct|}|j}t|d}|jddk7r dd|idgd}d d}t dd || S) zCreate a synthetic 'final_response' tool for structured output. This tool is used to capture structured responses from the LLM. The tool's schema is derived from the result_type. T prune_titlesrwobjectvalue)rw propertiesr*c|SrTr8)kwargss r:final_responsez2create_final_response_tool..final_responses r9rz|Call this tool to provide your final response. Use this when you have completed the task and are ready to return the result.)rQ description parametersfn)rrrLzdict[str, Any])r% json_schemar#rr) result_type type_adapterschemars r:create_final_response_toolrsw *+6L  % % 'F V$ 7Fzz&X%"F+     \  r9T) rrqrr[r`rauto_execute_toolsrrc Kt|} t|} | r| D cgc]} | jc} nd}| r| D cic]} | j| c} ni}t |t | }d}|0|dvrt d|dtttd|}||nd}|rt|| ||||||d{}n>|jj| |||t||||jd{}t|t xr|j"d k(}| j%t'd |j( |s t+|| S|s t+|| St-|}|r^| | nt.j0}t3|||| d{}|r1| j%t'dtt4t6| t+|| Scc} wcc} w7+77Sw)zImplementation of Context.sample_step(). Make a single LLM sampling call. This is a stateless function that makes exactly one LLM call and optionally executes any requested tools. Nr(zInvalid tool_choice: z(. Must be 'auto', 'required', or 'none'.modei)rrqrr[rr)rprrqrr[r`rrelated_request_idr@rurzrF)r>r2)rrr)rr _to_sdk_toolrQrmrMrZrr r rrdcreate_messager\ request_idrArrBrrrFr<rrrrrGr)rhrprrqrr[r`rrrrcurrent_messagesrrrr use_fallbackeffective_tool_choiceeffective_max_tokensr>is_tool_use_responsestep_tool_callseffective_maskrs r:sample_step_implrsU*(1#5)N6D>2>a >2$0>N+NqN+2 *'43GHL04 : :' 799 !+g89;G!  *4)?:S.  '#+/-   !77%'#+67HI-&118    89: -   9 , OhFVFVWX 85EFF 85EFF)2O"- ,,  7D  -- 7 1    # # &A!BLQ  x1A BBq 3 ,.    H1 sNG3G" G3G'A,G3G,>G3G/BG3G1AG3/G31G3)rrqrr[r`rrrcKd} t|} d} |5|tur-t|} | r t| ng} | j | d} |}t | D]}t ||||||| | ||  d{}||tur|jr|jD]}|jdk(st|}|j}t|jd}|jdd k7rt|t r d |vr|d } |j#|}t%j&|j)|d }t+|||j, ccS|jsm|!|turt9d|j:dt+|j<t?t@|j<r |j<nd|j, cS|j,}| |tusd} t9d| d7#t.$rY}|j,j t1dt3d|j4t7dd|dgdgYd}~d}~wwxYww)zImplementation of Context.sample(). Send a sampling request to the client and await the response. This method runs to completion automatically, executing a tool loop until the LLM provides a final text response. dNr*) rprrqrr[r`rrrrTrrwrrjsonr)r/r0r2rrr/zValidation error: z#. Please try again with valid data.rvrrz#Expected structured output of type zR, but the LLM returned a text response instead of calling the final_response tool.z&Sampling exceeded maximum iterations ())!rrUrrGrrangerrDrKrQr%rr#rrrAdictvalidate_pythonrdumps dump_pythonr-r2rrrrrr|r3r/r r')rhrprrqrr[r`rrrmax_iterationsrrfinal_response_toolr _iterationstep tool_callr input_dataoriginal_schemavalidated_resultr/rs r: sample_implr<s*N#5)N#K;c#98E1?n-R12! ?GN+ % %'#!/ #1-     "{#'=$BRBR!__ >>%55#9+#FL"+J&5$002'O(++F3x?&z48#z1%/%8  +7+G+G +S(#zz(445EF4S  .!%#3$(LL --h&;c+A"9+:N:N9OP// "YYG$))TYYD   <<  +"4Ko,r ??OqQ RRq  T+ +++%+$5-:2;,,,75;6HLX5X-.1*15 %&)"sLA0I-2H38I-,AI- AHBI-1I- I*AI%I-%I**I-)r[)ModelPreferences | str | list[str] | NonerLzModelPreferences | None)rhr&rirMrLrM)rhr&rpr1rr.rq float | Nonerintr[rrzlist[SDKTool] | NonerzToolChoice | NonerLr=)FN) rKrNrzdict[str, SamplingTool]rrMr int | NonerLzlist[ToolResultContent])rp%str | Sequence[str | SamplingMessage]rLr1)r`SSequence[SamplingTool | FunctionTool | TransformedTool | Callable[..., Any]] | NonerLzlist[SamplingTool] | None)r>r=rLrN)rrwrLr)rhr&rprrr.rqrrrr[rr`rrzToolChoiceOption | str | NonerrMr bool | NonerrrLr<)rhr&rprrr.rqrrrr[rr`rrztype[ResultT] | NonerrrrrLzSamplingResult[ResultT])Kr6 __future__rrrcollections.abcrr dataclassesrtypingrrr r r r mcp.typesr r rrrrrrrrrrrrr~rSDKToolpydanticrtyping_extensionsrrcrfastmcp.exceptionsr%fastmcp.server.sampling.sampling_toolrfastmcp.tools.function_toolr fastmcp.tools.tool_transformr!fastmcp.utilities.async_utilsr"fastmcp.utilities.json_schemar#fastmcp.utilities.loggingr$fastmcp.utilities.typesr%r3rfastmcp.server.contextr&r'ToolChoiceOptionr-r<r\rmrrrrrrrrr8r9r:rs>" .!== C%$%(>48090: H . ) 56  #WW% #  # %% %P @  .8v0 0#0 0  0  0A0$0#080l %#' hI$hI%hIhI! hI  hI\ 3  &!6 !6!6H @  P!% $!CG 15#&*#'rC rC3rC rC  rC  rCArC rC/rCrC$rC!rCrCr!% $!CG (,&*#'AS AS3AS AS  AS  ASAAS AS&AS$AS!ASASr9