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

xpander_sdk/modules/agents/models/agent.py

@@ -475,6 +475,32 @@ class AgentOutput(BaseModel):
     use_json_mode: Optional[bool] = False
 
 class TaskLevelStrategies(XPanderSharedModel):
+    """
+    Configuration object for task-level execution strategies.
+
+    This model groups optional strategy configurations that control how a task is
+    executed and managed over time, including retries, iterative execution,
+    stopping conditions, and daily run limits.
+
+    Attributes:
+        retry_strategy:
+            Optional retry policy configuration that defines how the task should
+            behave when execution fails (e.g., max attempts, backoff rules).
+
+        iterative_strategy:
+            Optional iterative execution configuration for tasks that may run in
+            repeated cycles/steps until completion or a stop condition is met.
+
+        stop_strategy:
+            Optional stopping policy configuration that defines when the task
+            should stop running (e.g., timeout, max iterations, success criteria).
+
+        max_runs_per_day:
+            Optional limit on how many times the task is allowed to run within a
+            24-hour period. If not set, no explicit daily limit is enforced.
+    """
+
     retry_strategy: Optional[OrchestrationRetryStrategy] = None
     iterative_strategy: Optional[OrchestrationIterativeStrategy] = None
-    stop_strategy: Optional[OrchestrationStopStrategy] = None
+    stop_strategy: Optional[OrchestrationStopStrategy] = None
+    max_runs_per_day: Optional[int] = None

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.208.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xpander-sdk
-Version: 2.0.206
+Version: 2.0.208
 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.208.dist-info}/RECORD

@@ -23,7 +23,7 @@ xpander_sdk/modules/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSu
 xpander_sdk/modules/agents/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 xpander_sdk/modules/agents/agents_module.py,sha256=3EhKOIPb4c39GOrNt4zU4V6WbsGj7W_yWwRNSJBKmfc,6419
 xpander_sdk/modules/agents/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-xpander_sdk/modules/agents/models/agent.py,sha256=lHWz37a4_qB9Hq4sZhvjILjj566hJHZbDlj7JJ6iO68,15340
+xpander_sdk/modules/agents/models/agent.py,sha256=K0ZIF_JA09Vz1I2QdBvbXoByz_OzUQtNH7eE5imQ_CA,16427
 xpander_sdk/modules/agents/models/agent_list.py,sha256=byEayS2uLwDKaVT3lAHltrFocQFKpr8XEwQ6NTEEEMo,4081
 xpander_sdk/modules/agents/models/knowledge_bases.py,sha256=YimpjVJxWe8YTbGMD6oGQOA_YV8ztHQHTTBOaBB44ZM,1037
 xpander_sdk/modules/agents/sub_modules/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -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.208.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+xpander_sdk-2.0.208.dist-info/METADATA,sha256=MSaI4iPo6_l9e4BOPwlT-4FtLI70FBqwihyjxFUBu9s,17952
+xpander_sdk-2.0.208.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+xpander_sdk-2.0.208.dist-info/top_level.txt,sha256=UCjnxQpsMy5Zoe7lmRuVDO6DI2V_6PgRFfm4oizRbVs,12
+xpander_sdk-2.0.208.dist-info/RECORD,,

{xpander_sdk-2.0.206.dist-info → xpander_sdk-2.0.208.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