$ji4ddlmZddlmZddlmZddlmZmZd*d Z d+d Z d+d Z d,dZ d-d.dZ d,dZd/dZehdZehdZehdZehdZehdZehdZ d0d1d%Z d2d3d)ZdS)4) annotations) defaultdict)Any) JsonRefError replace_refsdefsdict[str, Any]returnboolc" sdSttdfd D]\}}||d \tt d fd t  fd DS)uJCheck whether any definitions in ``$defs`` form a reference cycle. A cycle means a definition directly or transitively references itself (e.g. Node → children → Node, or A → B → A). ``jsonref.replace_refs`` silently produces Python-level object cycles for these, which Pydantic's serializer rejects. Fobjrsourcestrr Nonect|tr|d}t|trI|dr4||dd|D]}||dSt|tr|D]}||dSdS)N$ref#/$defs//) isinstancedictgetr startswithaddsplitvalueslist)r rrefvitem _collect_refsedgess e/home/rurouni/.hermes/hermes-agent/venv/lib/python3.11/site-packages/fastmcp/utilities/json_schema.pyr!z(_defs_have_cycles.._collect_refss c4  ,''&//C#s## 6z(B(B 6f !!#))C.."4555ZZ\\ ) ) a(((( ) ) T " " , , , dF++++ , , , ,)rnoder c|<|dD]0}|vr|krdS|kr|rdS1|<dS)NTF)r) r'neighborDONEIN_STACK UNVISITED _has_cyclerr"states r#r.z%_defs_have_cycles.._has_cycle)sd  $++  Ht##X(**ttX)++ 80D0D+ttd ur$c3FK|]}|ko |VdSNr)).0namer-r.r/s r# z$_defs_have_cycles..5s;NNuT{i'z&_strip_remote_refs..Es,TTTAV A)!,, r$c4i|]\}}|t|Sr)r>r@s r#rBz&_strip_remote_refs..Fs'AAATQ%a((AAAr$c,g|]}t|Sr)r>r2r s r# z&_strip_remote_refs..Hs!999T"4((999r$)rrrrrr6r)r rs r#r?r?8s#tBggfoo c3   Us(;(; UTTTTT TAASYY[[AAAA#t:99S9999 Jr$ct|tr1d|vod|vpd|vhdfd|DSt|tr d|DS|S)uoRecursively remove OpenAPI ``discriminator`` keys from a schema. Pydantic emits ``discriminator.mapping`` with values like ``#/$defs/ClassName``. After ``$defs`` are inlined and removed by ``dereference_refs``, those mapping entries dangle. The keyword is an OpenAPI extension — the ``anyOf`` variants already carry ``const`` on the discriminant field, so the mapping is redundant. Only strips ``discriminator`` when it appears alongside ``anyOf`` or ``oneOf``, which is where the OpenAPI keyword lives. A property *named* ``discriminator`` (inside ``properties``) is left alone. discriminatoranyOfoneOf>enumconstdefaultexamplescRi|]#\}}|dkr ||vr|nt|$S)rH_strip_discriminator)r2rAr _DATA_KEYSskips r#rBz(_strip_discriminator..]sN   1((T( Q*__*>q*A*A(((r$c,g|]}t|Sr)rPrEs r#rFz(_strip_discriminator..cs!;;;t$T**;;;r$)rrr6r)r rRrSs @@r#rQrQLs#t #%L7c>+KW^===           #t<;;s;;;; Jr$schemact|}t|dirt|S t |dd}|di}t |||}t |tsJ|}d|vrd|D}t|}|S#t$rt|cYSwxYw)aResolve all $ref references in a JSON schema by inlining definitions. This function resolves $ref references that point to $defs, replacing them with the actual definition content while preserving sibling keywords (like description, default, examples) that Pydantic places alongside $ref. This is necessary because some MCP clients (e.g., VS Code Copilot) don't properly handle $ref in tool input schemas. For self-referencing/circular schemas where full dereferencing is not possible, this function falls back to resolving only the root-level $ref while preserving $defs for nested references. Only local ``$ref`` values (those starting with ``#``) are resolved. Remote URIs (``http://``, ``file://``, etc.) are stripped before resolution to prevent SSRF / local-file-inclusion attacks when proxying schemas from untrusted servers. Args: schema: JSON schema dict that may contain $ref references Returns: A new schema dict with $ref resolved where possible and $defs removed when no longer needed Example: >>> schema = { ... "$defs": {"Category": {"enum": ["a", "b"], "type": "string"}}, ... "properties": {"cat": {"$ref": "#/$defs/Category", "default": "a"}} ... } >>> resolved = dereference_refs(schema) >>> # Result: {"properties": {"cat": {"enum": ["a", "b"], "type": "string", "default": "a"}}} $defsF)proxies lazy_loadc&i|]\}}|dk ||S)rWr)r@s r#rBz$dereference_refs..s#RRRTQQ'\\Aq\\\r$) r?r:rresolve_root_refr_merge_ref_siblingsrrr6rQr)rU dereferencedrmergeds r#dereference_refsr_gsF  ' 'F GR0011('''($FEUKKK zz'2&&$V\4@@&$'''''  l " "RR\-?-?-A-ARRRL,L99  ((( '''''(sBCC$#C$Noriginalr]visitedset[str] | Nonectt|trt|trd|vr|d}d|D}t|trT|dr?|dd}|vr |vrt|||hz}|r&t|}|||S|Si}|D]*\} } | |vrt|| | || <%| || <+|St|tryt|trdtt|t|} fdt|d| |d| d D|| dzS|S) aMerge sibling keywords from original $ref nodes into dereferenced schema. When jsonref resolves $ref, it replaces the entire node with the referenced definition, losing any sibling keywords like description, default, or examples. This function walks both trees in parallel and merges those siblings back. Args: original: The original schema with $ref and potential siblings dereferenced: The schema after jsonref processing defs: The $defs from the original schema, for looking up referenced definitions visited: Set of definition names already being processed (prevents cycles) Returns: The dereferenced schema with sibling keywords restored Nrc"i|] \}}|dv || S))rrWr)r@s r#rBz'_merge_ref_siblings..s)XXXAQFW=W=W1=W=W=Wr$rrrc:g|]\}}t||Sr))r\)r2odrras r#rFz'_merge_ref_siblings..s;   1 1dG 4 4   r$F)strict) r5rrr6rrrr\updaterminlenzip) r`r]rrarsiblingsdef_namer^resultkeyvaluemin_lens `` r#r\r\s*%%(D!!&#jt&D&D&# X  6"CXX)9)9XXXH#s## z(B(B 99S>>"-t##(?(?#6X dGxj>> schema = { ... "$defs": {"Node": {"type": "object", "properties": {...}}}, ... "$ref": "#/$defs/Node" ... } >>> resolved = resolve_root_ref(schema) >>> # Result: {"type": "object", "properties": {...}, "$defs": {...}} rrWtyperrr)rrrrr)rUrrnrresolveds r#r[r[s0Gv--&2F2FVn c3   CNN:$>$> yy~~b)H'?D4X//$(! Mr$paramrc|di}||d}||S||d<||dgvr8|d||ds|d|S)zwReturn a new schema with *param* removed from `properties`, `required`, and (if no longer referenced) `$defs`. propertiesNrequired)rpopremove)rUrvpropsremoveds r# _prune_paramr~s JJ|R ( (Eiit$$G !F<  :r****z!!%(((j! # JJz " " " Mr$>rtallOfrIr6rJryrxr>titlereadOnly writeOnly deprecated description>rKrLrMexamplerN>rx definitions dependenciesdependentSchemaspatternPropertiesrW> ifnotelsethenr6contains contentSchema propertyNamesadditionalItemsunevaluatedItemsadditionalPropertiesunevaluatedProperties>rrIrJ prefixItemsFT prune_titlesprune_additional_properties prune_defsc sss|St tt|d} dd fd  |ddr|r|D]\}} ||ddd fd t|D]"}|s||#|s|dd|S)aK Optimize JSON schemas in a single traversal for better performance. This function combines three schema cleanup operations that would normally require separate tree traversals: 1. **Remove unused definitions** (prune_defs): Finds and removes `$defs` entries that aren't referenced anywhere in the schema, reducing schema size. 2. **Remove titles** (prune_titles): Strips `title` fields throughout the schema to reduce verbosity while preserving functional information. 3. **Remove restrictive additionalProperties** (prune_additional_properties): Removes `"additionalProperties": false` constraints to make schemas more flexible. **Performance Benefits:** - Single tree traversal instead of multiple passes (2-3x faster) - Immutable design prevents shared reference bugs - Early termination prevents runaway recursion on deeply nested schemas **Algorithm Overview:** 1. Traverse main schema, collecting $ref references and applying cleanups 2. Traverse $defs section to map inter-definition dependencies 3. Remove unused definitions based on reference analysis Args: schema: JSON schema dict to optimize (not modified) prune_titles: Remove title fields for cleaner output prune_additional_properties: Remove "additionalProperties": false constraints prune_defs: Remove unused $defs entries to reduce size Returns: A new optimized schema dict Example: >>> schema = { ... "type": "object", ... "title": "MySchema", ... "additionalProperties": False, ... "$defs": {"UnusedDef": {"type": "string"}} ... } >>> result = _single_pass_optimize(schema, prune_titles=True, prune_defs=True) >>> # Result: {"type": "object", "additionalProperties": False} rWNFrTr'objectcurrent_def_name str | Noneskip_defs_sectionr depthr7 in_schemar rc|dkrdSttr rd}t|trc|drN|dd}|r ||n||rrmdvritdtrNtfdtDstd Dr d r,d d ur d  D]\}}|r|d kr|s|||d zd #|tvr?t|tr*|D]} | ||d zdk|tvru|t vr-t|t"r|D]} | ||d zd|t$vr|||d zd|||d zd dStt"rD]} | ||d z|dSdS)uCTraverse schema tree, collecting $ref info and applying cleanups. The `in_schema` flag tracks whether the current node is reached via a known JSON-Schema-valued position (root, `properties` value, `items`, `allOf` element, etc.). When False — e.g. we descended through a user extension key like `x-ui` whose payload is opaque to us — we still collect `$ref` references (they may point at `$defs` the user cares about) but we skip all cleanups so we don't mutate user data that happens to look metadata-shaped. 2Nrrrrrc3 K|]}|vV dSr1r))r2rAr's r#r4zD_single_pass_optimize..traverse_and_clean..s'@@!AI@@@@@@r$c3(K|] }|tvVdSr1)_METADATA_KEYS)r2rAs r#r4zD_single_pass_optimize..traverse_and_clean..s'AAqqN2AAAAAAr$rFrWr%)rrT)rrrrrrappendrr8_SCHEMA_KEYWORDSallrzr6_SUBSCHEMA_MAP_KEYSr_LITERAL_KEYWORDS_SUBSCHEMA_LIST_KEYSr_SUBSCHEMA_VALUE_KEYS)r'rrrrrreferenced_defrprq sub_schemar def_dependenciesrrr root_refstraverse_and_cleans` r#rz1_single_pass_optimize..traverse_and_cleans" 2:: F dD ! !o  6hhv&&c3''6CNN:,F,F6%(YYs^^B%7N'6(8??@PQQQQ" n555 5! &4"4=#66(@@@@/?@@@@@(AADAAAAA (HHW%%%05!788EAAHH3444#jjll= =  U$ !&&/uqyE---*UD2I2I-&+llnn **&,"'!)&*   +++...:eT3J3J. %** ,"'!)&*  ///&&(#ai"&   #"+519w= = ~d # #   ""*%!)y    r$)rr)rrrnrvisitingrbc|vrdS|g}|r4|t}||vrdS||hz}|D]}||vr||rdSdS)z.is_def_usedMs9$$t 033HbAA  $#"uuHx'' 5#xj0(8$$O&h66;;'<<6 $tt5r$)NFrT) r'rrrrr rr7rr r rr1)rnrrrbr r )r5rrrr6keysrz) rUrrrrrn def_schemarrrrs ``` @@@@r#_single_pass_optimizersd ,*E %%I4? 55 ::g  D(,"' CCCCCCCCCCCCLvFFFF%&d%&$(JJLL V V Hj  zHPT U U U U U         4TYY[[)) # #H;x(( #""" & JJw % % % Mr$ prune_paramslist[str] | None dereferencec|rt|}t|}|pgD]}t||}t|||d}|S)a Compress and optimize a JSON schema for MCP compatibility. Args: schema: The schema to compress prune_params: List of parameter names to remove from properties prune_additional_properties: Whether to remove additionalProperties: false. Defaults to False to maintain MCP client compatibility, as some clients (e.g., Claude) require additionalProperties: false for strict validation. prune_titles: Whether to remove title fields from the schema dereference: Whether to dereference $ref by inlining definitions. Defaults to False; dereferencing is typically handled by middleware at serve-time instead. )rvT)rrr)r_r[r~r)rUrrrrrvs r#compress_schemarrs{**!&))f % %F#33fE222#!$? F Mr$)rr r r )r rr r)rUr r r r1) r`rr]rrr rarbr r)rUr rvrr r )FFT) rUr rr rr rr r r )NFFF) rUr rrrr rr rr r r ) __future__r collectionsrtypingrjsonrefrrr:r?rQr_r\r[r~ frozensetrrrrrrrrr)r$r#rs""""""######........,O,O,O,O^(6J(J(J(J(b $ @@@@@F$$$$N.9      IQQQRR i  "    $!y!K!K!KLL (- mmmmmd&*(- (((((((r$