$j% ddlmZddlmZddlmZmZmZmZm Z m Z ddl m Z ddl mZmZddlmZmZddlmZddlmZer dd lmZdd lmZed e ZGd de dZd dZd!dZd"dZGddeZ dS)#) annotations)Sequence) TYPE_CHECKING AnnotatedAnyClassVar TypedDictcast)Icon)BeforeValidatorField)SelfTypeVar TaskConfig)FastMCPBaseModel)Docket) ExecutionT)defaultc.eZdZUded<ded<ded<dS) FastMCPMetaz list[str]tagsstrversionversionsN)__name__ __module__ __qualname____annotations__d/home/rurouni/.hermes/hermes-agent/venv/lib/python3.11/site-packages/fastmcp/utilities/components.pyrrs0OOOLLLr"rF)totalmetadict[str, Any] | Nonereturnc|siSdD]C}||}t|trtt|cSDiS)zExtract FastMCP metadata from a component's meta dict. Handles both the current `fastmcp` namespace and the legacy `_fastmcp` namespace for compatibility with older FastMCP servers. )fastmcp_fastmcp)get isinstancedictr r)r%keymetadatas r#get_fastmcp_metadatar0sc  &//88C== h % % / X.. . . . / Ir" maybe_setset[T] | Sequence[T] | Noneset[T]cn|tSt|tr|St|S)z@Convert a sequence to a set, defaulting to an empty set if None.)setr,)r1s r#_convert_set_default_noner6+s5uu )S!! y>>r"vstr | int | float | None str | Nonec8|dSt|trtd|t|ttt fs'tdt |jd|t|}d|vrtd||S)zCoerce version to string, accepting int, float, or str. Raises TypeError for non-scalar types (list, dict, set, etc.). Raises ValueError if version contains '@' (used as key delimiter). Nz3Version must be a string, int, or float, got bool: z-Version must be a string, int, or float, got z: @z;Version string cannot contain '@' (used as key delimiter): ) r,bool TypeErrorrintfloattyper ValueError)r7rs r#_coerce_versionrB4s  yt!TUSaSSTTT a#sE* + +  UDGGd*Zd?d.Zd=d/Zd@d0Zd@d1ZdAd3ZdBd6ZdCd9Zd>d:ZxZS)DFastMCPComponentzIBase class for FastMCP tools, prompts, resources, and resource templates.z ClassVar[str] KEY_PREFIXkwargsrr'Nonec tjdi||js+ddl}||jdt ddSdS)Nrzb does not define KEY_PREFIX. Component keys will not be type-prefixed, which may cause collisions.) stacklevelr!)super__init_subclass__rFwarningswarnr UserWarning)clsrGrN __class__s r#rMz"FastMCPComponent.__init_subclass__Os!!++F+++~  OOO MM<YYY        r"zThe name of the component.) descriptionrnameNzpOptional version identifier for this component. Multiple versions of the same component (same name) can coexist.)rrSz7Annotated[str | None, BeforeValidator(_coerce_version)]rz0The title of the component for display purposes.r9titlez!The description of the component.rSzHOptional list of icons for this component to display in user interfaces.zlist[Icon] | NoneiconszTags for the component.)default_factoryrSz?Annotated[set[str], BeforeValidator(_convert_set_default_none)]rz$Meta information about the componentr&r%c"tdS)N forbidden)moderr!r"r#zFastMCPComponent.zsjk&B&B&Br")rWz_Annotated[TaskConfig, Field(description='Background task execution configuration (SEP-1686).')] task_config identifierc,|jr |jd|S|S)zConstruct the lookup key for this component type. Args: identifier: The raw identifier (name for tools/prompts, uri for resources) Returns: A prefixed key like "tool:name" or "resource:uri" :)rF)rQr]s r#make_keyzFastMCPComponent.make_key|s* > 4n33z33 3r"cR||j}|d|jpdS)aThe globally unique lookup key for this component. Format: "{key_prefix}:{identifier}@{version}" or "{key_prefix}:{identifier}@" e.g. "tool:my_tool@v2", "tool:my_tool@", "resource:file://x.txt@" The @ suffix is ALWAYS present to enable unambiguous parsing of keys (URIs may contain @ characters, so we always include the delimiter). Subclasses should override this to use their specific identifier. Base implementation uses name. Prefer `.key` over ad-hoc `name or uri or uri_template` logic for any cross-component identity work (dedupe, grouping, collision detection, lookup tables). It encodes type, identifier, and version, so variants of the same component don't falsely collide with each other, and cross-type identifiers (e.g. a tool and a resource both named "foo") can't clash. r;rE)r`rTr)selfbase_keys r#r.zFastMCPComponent.keys2(==++11T\/R111r"dict[str, Any]cz|jrt|jni}dt|ji}|j |j|d<|dx}Zt |tstdd|D}tt||z}||d<|S)a8Get the meta information about the component. Returns a dict that always includes a `fastmcp` key containing: - `tags`: sorted list of component tags - `version`: component version (only if set) Internal keys (prefixed with `_`) are stripped from the fastmcp namespace. rNrr)zmeta['fastmcp'] must be a dictcDi|]\}}|d||S)_) startswith).0kr7s r# z-FastMCPComponent.get_meta..s?Aall3>O>O1r") r%r-sortedrrr+r,r=itemsr r)rbr% fastmcp_meta upstream_metapublic_upstreams r#get_metazFastMCPComponent.get_metas#')3tDI%+VDI->->$? < #&*lL #"XXi00 0M =mT22 B @AAA!.!4!4!6!6O _|-KLLL&Y r"otherobjectr<ct|t|urdSt|t|sdS||kS)NF)r@r, model_dump)rbrrs r#__eq__zFastMCPComponent.__eq__s\ ::T%[[ ( (5%d,, 5  E$4$4$6$666r"c d|jg}|jr|d|j|d|jd|jd|jg|jjdd |dS) Nzname=zversion=ztitle=z description=ztags=(z, )) rTrappendextendrUrSrrRrjoin)rbpartss r#__repr__zFastMCPComponent.__repr__s&&&' < 6 LL4DL44 5 5 5 '''3t/33# ##    .)??DIIe,<,<????r"c2td|jd)z6Removed in 3.0. Use server.enable(keys=[...]) instead.zHComponent.enable() was removed in FastMCP 3.0. Use server.enable(keys=[' ']) instead.NotImplementedErrorr.rbs r#enablezFastMCPComponent.enables-! ?(, ? ? ?   r"c2td|jd)z7Removed in 3.0. Use server.disable(keys=[...]) instead.zJComponent.disable() was removed in FastMCP 3.0. Use server.disable(keys=['rrrs r#disablezFastMCPComponent.disables1! @)- @ @ @   r"rc*|S)zCreate a copy of the component.) model_copyrs r#copyzFastMCPComponent.copys   r"docketrcdS)zRegister this component with docket for background execution. No-ops if task_config.mode is "forbidden". Subclasses override to register their callable (self.run, self.read, self.render, or self.fn). Nr!)rbrs r#register_with_docketz%FastMCPComponent.register_with_docketsr"argsrcK|js%td|jjd|jdt |jjd)aSchedule this component for background execution via docket. Subclasses override this to handle their specific calling conventions: - Tool: add_to_docket(docket, arguments: dict, **kwargs) - Resource: add_to_docket(docket, **kwargs) - ResourceTemplate: add_to_docket(docket, params: dict, **kwargs) - Prompt: add_to_docket(docket, arguments: dict | None, **kwargs) The **kwargs are passed through to docket.add() (e.g., key=task_key). z Cannot add z 'z)' to docket: task execution not supportedz# does not implement add_to_docket())r\supports_tasks RuntimeErrorrRrrTr)rbrrrGs r# add_to_docketzFastMCPComponent.add_to_dockets..00 0dn500000 "~& K K K   r"cd|jiS)z{Return span attributes for telemetry. Subclasses should call super() and merge their specific attributes. zfastmcp.component.key)r.rs r#get_span_attributesz$FastMCPComponent.get_span_attributess (22r")rGrr'rH)r]rr'r)r'r)r'rd)rrrsr'r<)r'rH)r'r)rrr'rH)rrrrrGrr'r)rrr__doc__rFr rMr rTrrUrSrVr5rr%r\ classmethodr`propertyr.rqrvr~rrrrrr __classcell__)rRs@r#rDrDJsSS "J""""      0DHMuKHHHG FE$e7K %u^   EMRE-MMMD#(%"H###D BBCCCDDDD    [ 222X2,87777 @ @ @ @        !!!!        ,33333333r"rDN)r%r&r'r)r1r2r'r3)r7r8r'r9)! __future__rcollections.abcrtypingrrrrr r mcp.typesr pydanticr r typing_extensionsrrfastmcp.server.tasks.configrfastmcp.utilities.typesrrrdocket.executionrrrr0r6rBrDr!r"r#rs""""""$$$$$$KKKKKKKKKKKKKKKK++++++++++++++++222222444444+****** GC)5 ",|3|3|3|3|3'|3|3|3|3|3r"