i/GddlmZddlmZddlmZddlmZmZd dZ ddZ d ddZ dd Z dd Z d dd Z d dd Zy)) annotations) defaultdict)Any) JsonRefError replace_refsc syttdfd jD]\}}||d\tt d fd t  fdDS)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. FcVt|trw|jd}t|tr7|j dr&|j |j dd|jD] }|| yt|tr|D] }|| yy)N$ref#/$defs//) isinstancedictgetstr startswithaddsplitvalueslist)objsourcerefvitem _collect_refsedgess m/Users/bowang/.openclaw/workspace/ChatDev/.venv/lib/python3.12/site-packages/fastmcp/utilities/json_schema.pyrz(_defs_have_cycles.._collect_refss c4 ''&/C#s#z(Bf !!#))C."45ZZ\a(" T "dF+#)rc|<j|dD]$}|vr|k(ry|k(s|s$y|<y)NTF)r) nodeneighborDONEIN_STACK UNVISITED _has_cycledefsrstates rr)z%_defs_have_cycles.._has_cycle)s_d  $+Ht#X(*X)+ 80D ,d rc3BK|]}|k(xr|ywNr#).0namer(r)r+s r z$_defs_have_cycles..5s(NuT{i'>> 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_load) r9rresolve_root_refr_merge_ref_siblingsrrr5r)schema dereferencedr*mergedkrs rdereference_refsrD8sBGR01''($FEUK zz'2&$V\4@&$'''  l "-9-?-?-AR-ATQQ'\AqD-ALRS ( ''(s*AB BBBBB54B5Nc "| t}t|trt|trd|vr|d}|jDcic] \}}|dvs ||}}}t|trB|j dr1|j dd}||vr||vrt||||||hz}|rt|} | j|| S|Si} |jD]#\} } | |vrt|| | ||| | <| | | <%| St|trgt|trWtt|t|} t|d| |d| dDcgc]\}}t||||c}}|| dzS|Scc}}wcc}}w) 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 Nr )r r;r r r F)strict) r4rrr5rrrr?updaterminlenzip)originalrAr*visitedrrCrsiblingsdef_namerBresultkeyvaluemin_lenods rr?r?vs*%(D!jt&D X 6"C)1)9X)9AQFW=W1)9HX#s#z(B99S>"-t#(?#6X dGxj s FF!F cd|vr`d|vr\d|vrX|d}t|trC|jdr2|jdd}|d}||vrt ||}||d<|S|S)aResolve $ref at root level to meet MCP spec requirements. MCP specification requires outputSchema to have "type": "object" at the root level. When Pydantic generates schemas for self-referential models, it uses $ref at the root level pointing to $defs. This function resolves such references by inlining the referenced definition while preserving $defs for nested references. Args: schema: JSON schema dict that may have $ref at root level Returns: A new schema dict with root-level $ref resolved, or the original schema if no resolution is needed Example: >>> schema = { ... "$defs": {"Node": {"type": "object", "properties": {...}}}, ... "$ref": "#/$defs/Node" ... } >>> resolved = resolve_root_ref(schema) >>> # Result: {"type": "object", "properties": {...}, "$defs": {...}} r r;typer r r )rrrrr)r@rrNr*resolveds rr>r>s}0Gv-&2FVn c3 CNN:$>yy~b)H'?D4X/$(! Mrc|jdi}|j|d}||S||d<||jdgvr*|dj||ds|jd|S)zwReturn a new schema with *param* removed from `properties`, `required`, and (if no longer referenced) `$defs`. propertiesNrequired)rpopremove)r@parampropsremoveds r _prune_paramr`sy JJ|R (Eiit$G !F<  :r**z!!%(j! JJz " Mrc sss|St tt|jd} d d  fd  |dry|rw|j D]\}} ||d d  fd t|j D]}|r |j ||s|j 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} r;Nc|dkDryttr rnjd}t|trM|j dr<|j dd}|r |j |n j| r)dvr%tfdd Drjd r$jd d urjd jD]E\}}|r|d k(r|d vr&t|tr|D]}|||dz8|||dzGyttrD]}|||dzyy)zATraverse schema tree, collecting $ref info and applying cleanups.2Nr r r r titlec3&K|]}|v ywr-r#)r.rCr$s rr0zD_single_pass_optimize..traverse_and_clean..Os!  I s)rVrYr r5allOfoneOfanyOfrZadditionalPropertiesFr;)rfrgrhr )depth) rrrrrrappendrr7r[r5r)r$current_def_nameskip_defs_sectionrjrreferenced_defrPrQrdef_dependenciesprune_additional_properties prune_defs prune_titles root_refstraverse_and_cleans` rrtz1_single_pass_optimize..traverse_and_clean2s[ 2:  dD !hhv&c3'CNN:,F%(YYs^B%7N'(8??@PQ" n5 4    HHW%,HH34=/0#jjl U$55*UD:Q %*41AQRS!&'u.>eaiP+d #"4)9K$rT)rm)rlc|vryj|g}|r.| t}||vry||hz}|D]}||vs||syy)z.is_def_used}sv9$ 033HbA #"uHx' #xj0(8O&h6;'< $ (8 r)NFr) r$objectrlz str | Nonermr3rjr6r1r2r-)rNrrvset[str] | Noner1r3)r4rrrr5keysr[) r@rrrprqr*rN def_schemaroryrsrts ``` @@@@r_single_pass_optimizer~s d ,*E %I4? 5 ::g D(,"' @L@L$@L @L @L  @L@LFv6d$(JJL Hj zH E%1  4TYY[)Hx("*  JJw % Mrc|r t|}t|}|xsgD]}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. )r]T)rrrprq)rDr>r`r~)r@ prune_paramsrprr dereferencer]s rcompress_schemars\*!&)f %F##fE2$ #!$? F Mr)r*dict[str, Any]r1r3)r@rr1rr-) rKrrArr*rrLr{r1r)r@rr]rr1r)FFT) r@rrrr3rpr3rqr3r1r)NFFF) r@rrzlist[str] | Nonerpr3rrr3rr3r1r) __future__r collectionsrtypingrjsonrefrrr9rDr?r>r`r~rr#rrrs"#.,O^;(D $ @@@ @ @  @F$N.(- j jj"&j j  j^&*(- ( ("("&( (  (  (r