xpander-sdk 2.0.206__tar.gz → 2.0.207__tar.gz

{xpander_sdk-2.0.206 → xpander_sdk-2.0.207}/PKG-INFO

@@ -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 → xpander_sdk-2.0.207}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setup(
     name="xpander-sdk",
-    version="2.0.206",
+    version="2.0.207",
     author="xpanderAI",
     author_email="dev@xpander.ai",
     description="xpander.ai Backend-as-a-service for AI Agents - SDK",

{xpander_sdk-2.0.206 → xpander_sdk-2.0.207}/src/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-2.0.206 → xpander_sdk-2.0.207}/src/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 → xpander_sdk-2.0.207}/src/xpander_sdk.egg-info/PKG-INFO

@@ -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 → xpander_sdk-2.0.207}/src/xpander_sdk.egg-info/SOURCES.txt

@@ -104,6 +104,8 @@ tests/test_api_client.py
 tests/test_backend_module.py
 tests/test_boot_shutdown_handlers.py
 tests/test_configuration.py
+tests/test_final_validation.py
 tests/test_knowledge_bases_module.py
 tests/test_tasks_module.py
+tests/test_tool_schema_enhancements.py
 tests/test_tools_repository.py

xpander_sdk-2.0.207/tests/test_final_validation.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+"""
+Final validation that Option 2 + 3 enhancements are working correctly.
+"""
+
+import json
+from xpander_sdk import Configuration
+from xpander_sdk.modules.agents.agents_module import Agents
+
+def main():
+    config = Configuration(
+        api_key="A02tKVpMd58Z3gAIDsQ7C8dh7oIRBYBc8Vu6cGFJ",
+        organization_id="6f3a8d1a-00e4-4ae7-bb1f-907b8704d4e2",
+        base_url="https://inbound.stg.xpander.ai"
+    )
+    
+    print("=" * 80)
+    print("TESTING OPTION 2 + 3 ENHANCEMENTS")
+    print("=" * 80)
+    
+    agents = Agents(configuration=config)
+    agent = agents.get(agent_id="cb0fa205-96a8-4f43-ad99-881fb87f374a")
+    
+    # Access functions to trigger schema enhancements
+    functions = agent.tools.functions
+    tool = agent.tools.list[0]
+    
+    print("\n✅ OPTION 3: Schema Model Description")
+    print("-" * 80)
+    model_config_desc = tool.schema.model_config.get('description', '')
+    print(model_config_desc)
+    
+    if 'CRITICAL' in model_config_desc and 'payload' in model_config_desc.lower():
+        print("\n✓ Schema description contains CRITICAL warning")
+        print("✓ Schema description mentions 'payload' wrapper")
+    
+    print("\n✅ OPTION 3: Field Descriptions with 'payload' hints")
+    print("-" * 80)
+    schema_json = tool.schema.model_json_schema()
+    for field_name, field_def in schema_json.get('properties', {}).items():
+        desc = field_def.get('description', '')
+        has_payload_hint = 'payload' in desc.lower()
+        status = "✓" if has_payload_hint else "✗"
+        print(f"{status} {field_name}: {desc[:80]}...")
+    
+    print("\n✅ OPTION 2: Function Docstring with Examples")
+    print("-" * 80)
+    func = functions[0]
+    doc = func.__doc__
+    print(doc)
+    
+    if 'IMPORTANT' in doc and 'payload' in doc.lower():
+        print("\n✓ Function docstring has IMPORTANT section")
+        print("✓ Function docstring mentions payload structure")
+        print("✓ Function docstring includes examples")
+    
+    print("\n✅ FULL JSON SCHEMA (sent to LLM)")
+    print("-" * 80)
+    print(json.dumps(schema_json, indent=2))
+    
+    print("\n" + "=" * 80)
+    print("✅ ALL ENHANCEMENTS SUCCESSFULLY APPLIED!")
+    print("=" * 80)
+    print("\nSummary:")
+    print("1. ✓ Schema model description has CRITICAL payload wrapper warning")
+    print("2. ✓ All field descriptions mention '(must be inside payload object)'")
+    print("3. ✓ Function docstring has detailed parameter structure guidance")
+    print("4. ✓ Function docstring includes correct/incorrect usage examples")
+    print("\nThese enhancements guide the LLM to pass parameters correctly:")
+    print("  CORRECT: function_name(payload={...})")
+    print("  INCORRECT: function_name(body_params={...}, headers={...})")
+
+if __name__ == "__main__":
+    main()

xpander_sdk-2.0.207/tests/test_tool_schema_enhancements.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""
+Test script to verify that Option 2 + 3 enhancements work correctly.
+This tests that the schema and docstring improvements help guide LLMs to pass parameters correctly.
+"""
+
+import json
+import sys
+from xpander_sdk import Configuration
+from xpander_sdk.modules.agents.agents_module import Agents
+
+def test_schema_enhancements():
+    """Test that tool schemas now have enhanced descriptions and examples."""
+    
+    # Setup configuration for staging
+    config = Configuration(
+        api_key="A02tKVpMd58Z3gAIDsQ7C8dh7oIRBYBc8Vu6cGFJ",
+        organization_id="6f3a8d1a-00e4-4ae7-bb1f-907b8704d4e2",
+        base_url="https://inbound.stg.xpander.ai"
+    )
+    
+    print("🔍 Fetching agent and tools...")
+    agents = Agents(configuration=config)
+    agent = agents.get(agent_id="cb0fa205-96a8-4f43-ad99-881fb87f374a")
+    
+    print(f"✅ Agent loaded: {agent.name}")
+    print(f"📊 Number of tools: {len(agent.tools.list)}\n")
+    
+    # Test each tool's schema and function
+    for tool in agent.tools.list:
+        print("=" * 80)
+        print(f"🔧 Tool: {tool.name} (ID: {tool.id})")
+        print("=" * 80)
+        
+        # Check schema documentation
+        print("\n📝 Schema Documentation:")
+        print("-" * 80)
+        if hasattr(tool.schema, '__doc__') and tool.schema.__doc__:
+            doc_lines = tool.schema.__doc__.split('\n')
+            for line in doc_lines[:20]:  # Show first 20 lines
+                print(line)
+            if len(doc_lines) > 20:
+                print(f"... ({len(doc_lines) - 20} more lines)")
+        else:
+            print("⚠️  No schema documentation found")
+        
+        # Check if critical keywords are present in schema doc
+        if tool.schema.__doc__:
+            has_payload = 'payload' in tool.schema.__doc__.lower()
+            has_example = 'example' in tool.schema.__doc__.lower()
+            has_critical = 'critical' in tool.schema.__doc__.lower()
+            
+            print(f"\n✓ Contains 'payload' guidance: {has_payload}")
+            print(f"✓ Contains example: {has_example}")
+            print(f"✓ Has CRITICAL warning: {has_critical}")
+        
+        # Check field descriptions
+        print("\n📋 Field Descriptions:")
+        print("-" * 80)
+        schema_json = tool.schema.model_json_schema()
+        if 'properties' in schema_json:
+            for field_name, field_def in schema_json['properties'].items():
+                desc = field_def.get('description', 'No description')
+                has_wrapper_note = 'payload' in desc.lower()
+                status = "✅" if has_wrapper_note else "⚠️ "
+                print(f"{status} {field_name}: {desc[:100]}...")
+        
+        # Check function documentation
+        print("\n🔨 Function Documentation:")
+        print("-" * 80)
+        functions = agent.tools.functions
+        if functions:
+            func = functions[0]  # Get first function
+            if hasattr(func, '__doc__') and func.__doc__:
+                doc_lines = func.__doc__.split('\n')
+                for line in doc_lines[:25]:  # Show first 25 lines
+                    print(line)
+                if len(doc_lines) > 25:
+                    print(f"... ({len(doc_lines) - 25} more lines)")
+            
+            # Check function signature
+            import inspect
+            sig = inspect.signature(func)
+            print(f"\n📌 Function Signature: {func.__name__}{sig}")
+            
+            # Check if function has payload parameter
+            params = list(sig.parameters.keys())
+            if 'payload' in params:
+                print("✅ Function has 'payload' parameter")
+            else:
+                print(f"⚠️  Function parameters: {params}")
+        
+        print("\n")
+
+if __name__ == "__main__":
+    try:
+        test_schema_enhancements()
+        print("\n" + "=" * 80)
+        print("✅ Test completed successfully!")
+        print("=" * 80)
+    except Exception as e:
+        print(f"\n❌ Error: {e}", file=sys.stderr)
+        import traceback
+        traceback.print_exc()
+        sys.exit(1)