xpander-sdk 2.0.206__py3-none-any.whl → 2.0.207__py3-none-any.whl

xpander_sdk/modules/tools_repository/tools_repository_module.py

@@ -159,8 +159,33 @@ class ToolsRepository(XPanderSharedModel):
 
         for tool in self.list:
             
-            # add json schema to the model doc
-            tool.schema.__doc__ = "Pay attention to the schema, dont miss. " + json.dumps(tool.schema.model_json_schema(mode="serialization"))
+            # add json schema to the model doc with enhanced guidance
+            schema_json = tool.schema.model_json_schema(mode="serialization")
+            
+            # Build example with actual schema structure
+            example_payload = {}
+            if 'properties' in schema_json:
+                for prop_name, prop_def in schema_json['properties'].items():
+                    if prop_def.get('type') == 'object':
+                        if prop_def.get('properties'):
+                            # Show one example nested field
+                            first_nested = list(prop_def['properties'].keys())[0]
+                            example_payload[prop_name] = {first_nested: "<value>"}
+                        else:
+                            example_payload[prop_name] = {}
+                    else:
+                        example_payload[prop_name] = f"<{prop_def.get('type', 'value')}>"
+            
+            tool.schema.__doc__ = f"""CRITICAL: This entire schema must be wrapped in a 'payload' parameter.
+
+Call this function as: function_name(payload={{...}})
+DO NOT call as: function_name(body_params={{...}}, headers={{...}}, ...)
+
+Example correct call:
+{json.dumps({"payload": example_payload}, indent=2)}
+
+Full schema: {json.dumps(schema_json, indent=2)}
+"""
             
             schema_cls: Type[BaseModel] = tool.schema
 
@@ -208,7 +233,44 @@ class ToolsRepository(XPanderSharedModel):
 
                 # --- Metadata ---
                 tool_function.__name__ = tool_ref.id
-                tool_function.__doc__ = tool_ref.description or tool_ref.name
+                
+                # Build comprehensive docstring with parameter structure guidance
+                base_doc = tool_ref.description or tool_ref.name
+                
+                # Extract schema properties for examples
+                schema_props = schema_ref.model_json_schema().get('properties', {})
+                param_names = list(schema_props.keys())
+                
+                # Create example structure
+                example_parts = []
+                for prop_name in param_names:
+                    prop_info = schema_props.get(prop_name, {})
+                    if prop_info.get('type') == 'object' and prop_info.get('properties'):
+                        # Show nested structure
+                        nested_props = list(prop_info['properties'].keys())
+                        if nested_props:
+                            example_parts.append(f'"{prop_name}": {{"{nested_props[0]}": ...}}')
+                        else:
+                            example_parts.append(f'"{prop_name}": {{}}')
+                    else:
+                        example_parts.append(f'"{prop_name}": ...')
+                
+                example_json = "{" + ", ".join(example_parts) + "}"
+                
+                tool_function.__doc__ = f"""{base_doc}
+
+IMPORTANT - Parameter Structure:
+All parameters must be passed as a single 'payload' object containing the required fields.
+
+Correct usage example:
+{{
+  "payload": {example_json}
+}}
+
+DO NOT pass parameters as separate top-level arguments.
+DO NOT use: {{"{param_names[0] if param_names else 'param'}": ..., "{param_names[1] if len(param_names) > 1 else 'param2'}": ...}}
+USE: {{"payload": {{"{param_names[0] if param_names else 'param'}": ..., "{param_names[1] if len(param_names) > 1 else 'param2'}": ..., ...}}}}
+"""
 
                 # --- Signature ---
                 payload_param = Parameter(

xpander_sdk/modules/tools_repository/utils/schemas.py

@@ -98,20 +98,24 @@ def build_model_from_schema(
             
             field_args = {}
             
-            # Enhance description to clarify optional vs required status
+            # Enhance description to clarify optional vs required status AND nesting
             enhanced_description = description or f"Parameter: {prop_name}"
+            
+            # Add payload wrapper reminder for top-level params
+            wrapper_note = " (must be inside payload object)"
+            
             if is_empty_param_container:
-                enhanced_description = f"[OPTIONAL - empty container] {enhanced_description} (default: empty object)"
+                enhanced_description = f"[OPTIONAL - empty container] {enhanced_description} (default: empty object){wrapper_note}"
             elif prop_name in required:
                 if default is not None:
-                    enhanced_description = f"[REQUIRED with default] {enhanced_description} (default: {default})"
+                    enhanced_description = f"[REQUIRED with default] {enhanced_description} (default: {default}){wrapper_note}"
                 else:
-                    enhanced_description = f"[REQUIRED] {enhanced_description}"
+                    enhanced_description = f"[REQUIRED] {enhanced_description}{wrapper_note}"
             else:
                 if default is not None:
-                    enhanced_description = f"[OPTIONAL with default] {enhanced_description} (default: {default})"
+                    enhanced_description = f"[OPTIONAL with default] {enhanced_description} (default: {default}){wrapper_note}"
                 else:
-                    enhanced_description = f"[OPTIONAL] {enhanced_description} - can be omitted or set to null"
+                    enhanced_description = f"[OPTIONAL] {enhanced_description} - can be omitted or set to null{wrapper_note}"
             
             field_args["description"] = enhanced_description
 
@@ -169,7 +173,16 @@ def build_model_from_schema(
         strict=False,  # Allow flexibility with types to handle AI agent inputs better
         extra="allow",
         title=model_name,
-        description="IMPORTANT: Required fields must be provided. Optional fields can be omitted entirely or set to null. All parameters with defaults will use those defaults if not provided. Check the 'required' array in the schema to see which fields are mandatory."
+        description="""CRITICAL - This schema must be wrapped in a 'payload' parameter.
+        
+CORRECT: Call function with {"payload": {<this_schema>}}
+INCORRECT: Call function with {<this_schema>} directly
+
+All fields shown below must be nested inside a 'payload' object when calling the function.
+
+Required fields must be provided. Optional fields can be omitted entirely or set to null. 
+All parameters with defaults will use those defaults if not provided. 
+Check the 'required' array in the schema to see which fields are mandatory."""
     )
     return create_model(
         model_name,

{xpander_sdk-2.0.206.dist-info → xpander_sdk-2.0.207.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xpander-sdk
-Version: 2.0.206
+Version: 2.0.207
 Summary: xpander.ai Backend-as-a-service for AI Agents - SDK
 Home-page: https://www.xpander.ai
 Author: xpanderAI

{xpander_sdk-2.0.206.dist-info → xpander_sdk-2.0.207.dist-info}/RECORD

@@ -71,7 +71,7 @@ xpander_sdk/modules/tasks/sub_modules/task.py,sha256=zRDHsE_LnYYa3OC79wVQqeRnpAo
 xpander_sdk/modules/tasks/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 xpander_sdk/modules/tasks/utils/files.py,sha256=KqqwSQSrwim2-H3XP5wOadDDfngAyEI034tA7Oon-vc,3631
 xpander_sdk/modules/tools_repository/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-xpander_sdk/modules/tools_repository/tools_repository_module.py,sha256=HpiOtsJwIeyDqb1499X4FuRUdh8v-mQZQlQ2Zlgq1lY,9557
+xpander_sdk/modules/tools_repository/tools_repository_module.py,sha256=Hck2dACK2O8BHPXfFdVY8xBMQGYSFrB-trVCJ15LKN4,12393
 xpander_sdk/modules/tools_repository/decorators/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 xpander_sdk/modules/tools_repository/decorators/register_tool.py,sha256=ep-BlJHmqvG7zcW6l-hz_V0ZJx3PGfNqdijw6VjUGek,4078
 xpander_sdk/modules/tools_repository/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -82,7 +82,7 @@ xpander_sdk/modules/tools_repository/sub_modules/tool.py,sha256=rivnznxi6CrrOWE1
 xpander_sdk/modules/tools_repository/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 xpander_sdk/modules/tools_repository/utils/generic.py,sha256=bQ31-RoAq12lpDoIWsgmqAt7NL5YdzW1j3WKqZtYb2A,1904
 xpander_sdk/modules/tools_repository/utils/local_tools.py,sha256=zp5P8hVnRUJQb-w-2jCEMV5eUB_awmvYfY_rin5qvEw,1875
-xpander_sdk/modules/tools_repository/utils/schemas.py,sha256=EUi35h7CRrOVXV-TH-lyCpOdK5pu1uODDxvGB1JGDXY,13734
+xpander_sdk/modules/tools_repository/utils/schemas.py,sha256=EAoxhkVmwtqPOm-FkXiQRDNmcrmcnEeXbw73k7PzvUk,14242
 xpander_sdk/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 xpander_sdk/utils/env.py,sha256=U_zIhqWgKs5fk2-HXjAaODj4oWMc5dRQ0fvw6fqVcFk,1522
 xpander_sdk/utils/event_loop.py,sha256=kJrN0upgBhyI86tkTdfHeajznrIZl44Rl6WDiDG3GHE,2516
@@ -90,8 +90,8 @@ xpander_sdk/utils/generic.py,sha256=XrRj2-L8c0YWpfPdDyXE-pVL-6lKF9VpyZzKHQ4wuCc,
 xpander_sdk/utils/tools.py,sha256=lyFkq2yP7DxBkyXYVlnFRwDhQCvf0fZZMDm5fBycze4,1244
 xpander_sdk/utils/agents/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 xpander_sdk/utils/agents/compactization_agent.py,sha256=S_U1dSmDC7I0JUsp_THUYjfutEI5QMBaMPJEXGp0_Sw,14389
-xpander_sdk-2.0.206.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-xpander_sdk-2.0.206.dist-info/METADATA,sha256=ATScz104ZRoYszw-HsRrYKEVKazK0FWrnwFlCT-J-u8,17952
-xpander_sdk-2.0.206.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-xpander_sdk-2.0.206.dist-info/top_level.txt,sha256=UCjnxQpsMy5Zoe7lmRuVDO6DI2V_6PgRFfm4oizRbVs,12
-xpander_sdk-2.0.206.dist-info/RECORD,,
+xpander_sdk-2.0.207.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+xpander_sdk-2.0.207.dist-info/METADATA,sha256=DD0MwqtsCcc7b2XXQReMG6y4P-4Rqkbu-sutigeeoIg,17952
+xpander_sdk-2.0.207.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+xpander_sdk-2.0.207.dist-info/top_level.txt,sha256=UCjnxQpsMy5Zoe7lmRuVDO6DI2V_6PgRFfm4oizRbVs,12
+xpander_sdk-2.0.207.dist-info/RECORD,,

{xpander_sdk-2.0.206.dist-info → xpander_sdk-2.0.207.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.1)
 Root-Is-Purelib: true
 Tag: py3-none-any