erdo 0.1.4__py3-none-any.whl → 0.1.5__py3-none-any.whl

erdo/types.py

@@ -10,7 +10,7 @@ from enum import Enum
 from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional, Protocol, Tuple, Union, cast
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, field_serializer
 
 from ._generated.types import (
     ExecutionModeType,
@@ -21,6 +21,14 @@ from ._generated.types import (
     ParameterHydrationBehaviour,
     Tool,
 )
+from .bot_permissions import (
+    BotPermissions,
+    check_bot_access,
+    get_bot_permissions,
+    set_bot_org_permission,
+    set_bot_public,
+    set_bot_user_permission,
+)
 from .template import TemplateString
 
 # Type aliases for complex types that are json.RawMessage in Go
@@ -99,8 +107,115 @@ class PythonFile(BaseModel):
             raise RuntimeError(f"Error reading Python file {file_path}: {e}")
 
 
+def _extract_step_config_from_action(action: Any) -> Dict[str, Any]:
+    """Extract step configuration from an action object.
+
+    Actions can include a step_metadata parameter that configures the Step properties.
+    This function extracts those properties and returns them as a dict for Step(**config).
+
+    Example:
+        utils.echo(
+            data={"result": "value"},
+            step_metadata=StepMetadata(
+                key="my_step",
+                output_behavior={"result": OutputBehaviorType.MERGE}
+            )
+        )
+
+    The step_metadata fields are extracted and used to configure the Step:
+    - key: Step identifier
+    - output_behavior: How output fields are merged into state
+    - execution_mode: Parallel/sequential/background/iterate
+    - depends_on: Step dependencies
+    - output_channels: Where output is sent
+    - visibility settings: User and bot visibility
+    - messages: Running/finished messages
+    - content types: Output/history/UI content types
+
+    Args:
+        action: Action object (from utils.echo, llm.message, etc.)
+
+    Returns:
+        Dict with 'action' and any extracted step_metadata fields
+    """
+    step_config: Dict[str, Any] = {"action": action}
+
+    # Extract step_metadata if present on the action object
+    if hasattr(action, "step_metadata") and action.step_metadata is not None:
+        metadata = action.step_metadata
+
+        # Extract each metadata field if it's set (not None)
+        if hasattr(metadata, "key") and metadata.key:
+            step_config["key"] = metadata.key
+        if hasattr(metadata, "depends_on") and metadata.depends_on:
+            step_config["depends_on"] = metadata.depends_on
+        if hasattr(metadata, "execution_mode") and metadata.execution_mode:
+            step_config["execution_mode"] = metadata.execution_mode
+        if hasattr(metadata, "output_behavior") and metadata.output_behavior:
+            step_config["output_behavior"] = metadata.output_behavior
+        if hasattr(metadata, "output_channels") and metadata.output_channels:
+            step_config["output_channels"] = metadata.output_channels
+        if hasattr(metadata, "output_content_type") and metadata.output_content_type:
+            step_config["output_content_type"] = metadata.output_content_type
+        if hasattr(metadata, "history_content_type") and metadata.history_content_type:
+            step_config["history_content_type"] = metadata.history_content_type
+        if hasattr(metadata, "ui_content_type") and metadata.ui_content_type:
+            step_config["ui_content_type"] = metadata.ui_content_type
+        if (
+            hasattr(metadata, "user_output_visibility")
+            and metadata.user_output_visibility
+        ):
+            step_config["user_output_visibility"] = metadata.user_output_visibility
+        if (
+            hasattr(metadata, "bot_output_visibility")
+            and metadata.bot_output_visibility
+        ):
+            step_config["bot_output_visibility"] = metadata.bot_output_visibility
+        if hasattr(metadata, "running_message") and metadata.running_message:
+            step_config["running_message"] = metadata.running_message
+        if hasattr(metadata, "finished_message") and metadata.finished_message:
+            step_config["finished_message"] = metadata.finished_message
+        if (
+            hasattr(metadata, "parameter_hydration_behaviour")
+            and metadata.parameter_hydration_behaviour
+        ):
+            step_config["parameter_hydration_behaviour"] = (
+                metadata.parameter_hydration_behaviour
+            )
+
+    return step_config
+
+
 class StepMetadata(BaseModel):
-    """Metadata for workflow steps, containing configuration and execution parameters."""
+    """Metadata for workflow steps, containing configuration and execution parameters.
+
+    StepMetadata is used to configure step properties when creating steps via actions.
+    It's particularly useful in result handlers where you need to configure step behavior:
+
+    Example:
+        step.on(IsSuccess(),
+            utils.parse_json(
+                json_data="{{output}}",
+                step_metadata=StepMetadata(
+                    key="parse_result",
+                    output_behavior={"data": OutputBehaviorType.MERGE}
+                )
+            )
+        )
+
+    Fields:
+        key: Step identifier (used for referencing in templates and dependencies)
+        output_behavior: Controls how output fields are merged into state
+            - STEP_ONLY: Output only available via steps.step_key.field
+            - MERGE: Output fields merged into root state
+            - OVERWRITE: Output replaces entire state
+        execution_mode: How the step executes (sequential/parallel/background/iterate)
+        depends_on: Other steps this step depends on
+        output_channels: Where step output is sent (e.g., ["user", "bot"])
+        visibility: Control who sees the output (user/bot)
+        messages: Custom running/finished messages
+        content_types: Specify output/history/UI content types
+    """
 
     model_config = {"arbitrary_types_allowed": True}
 
@@ -120,9 +235,7 @@ class StepMetadata(BaseModel):
     bot_output_visibility: OutputVisibility = OutputVisibility.HIDDEN
     running_message: Optional[str] = None
     finished_message: Optional[str] = None
-    parameter_hydration_behaviour: ParameterHydrationBehaviour = (
-        ParameterHydrationBehaviour.NONE
-    )
+    parameter_hydration_behaviour: Optional[ParameterHydrationBehaviour] = None
 
 
 class Step(StepMetadata):
@@ -260,7 +373,8 @@ class Step(StepMetadata):
         return str(type(self.action).__name__).lower()
 
     def get_depends_on_keys(self) -> Optional[List[str]]:
-        """Get dependency keys safely without circular references, preserving None vs [] distinction."""
+        """Get dependency keys safely without circular references,
+        preserving None vs [] distinction."""
         # CRITICAL: Preserve None vs [] distinction for 100% roundtrip parity
         if self.depends_on is None:
             return None  # Explicitly return None for null dependencies
@@ -341,8 +455,16 @@ class Step(StepMetadata):
                 # If it's already a Step, use step= parameter
                 step_actions.append(Step(step=action))
             else:
-                # If it's an action function, use action= parameter
-                step_actions.append(Step(action=action))
+                # Extract step_metadata from action if present and merge into Step
+                # This allows result handler steps to be configured via step_metadata parameter:
+                #   step.on(condition,
+                #       utils.echo(data=..., step_metadata=StepMetadata(
+                #           key="my_step",
+                #           output_behavior={"field": OutputBehaviorType.MERGE}
+                #       ))
+                #   )
+                step_config = _extract_step_config_from_action(action)
+                step_actions.append(Step(**step_config))
 
         # Create a result handler and add it to this step
         handler = ResultHandler(
@@ -374,6 +496,8 @@ class Step(StepMetadata):
             result.pop("ui_content_type", None)
         if result.get("history_content_type") in [None, ""]:
             result.pop("history_content_type", None)
+        if result.get("parameter_hydration_behaviour") is None:
+            result.pop("parameter_hydration_behaviour", None)
 
         # Add action information without circular references
         result["action_type"] = self.get_action_type()
@@ -461,6 +585,12 @@ class Step(StepMetadata):
         for key, value in result.items():
             result[key] = convert_conditions(value)
 
+        # Rename output_behavior to output_behaviour for Go backend compatibility
+        # Python SDK uses American spelling (output_behavior) but Go backend expects
+        # British spelling (output_behaviour). This ensures correct serialization.
+        if "output_behavior" in result:
+            result["output_behaviour"] = result.pop("output_behavior")
+
         # Recursively sort all dictionaries for deterministic serialization
         def sort_dict_recursively(obj: Any) -> Any:
             """Recursively sort all dictionaries to ensure deterministic JSON output."""
@@ -498,7 +628,8 @@ class Step(StepMetadata):
         for condition, _ in self._decorator_handlers:
             # Create a simple handler that calls the function
             # For now, we'll create a basic handler structure
-            # In a full implementation, you'd want to analyze the function and create appropriate steps
+            # In a full implementation, you'd want to analyze the function and create
+            # appropriate steps
             handler = ResultHandler(
                 type=HandlerType.FINAL,
                 if_conditions=condition,
@@ -588,9 +719,11 @@ class ResultHandler(BaseModel):
                 if hasattr(step, "to_dict"):
                     step_dict = step.to_dict()
                     # DO NOT auto-generate keys for result handler steps
-                    # Only include keys if explicitly set to preserve roundtrip parity
+                    # Only include keys if explicitly set to preserve roundtrip
+                    # parity
 
-                    # Ensure bot_output_visibility is preserved (defaults to hidden for result handler steps)
+                    # Ensure bot_output_visibility is preserved (defaults to hidden for
+                    # result handler steps)
                     if "bot_output_visibility" not in step_dict:
                         step_dict["bot_output_visibility"] = "hidden"
 
@@ -615,6 +748,8 @@ class ResultHandler(BaseModel):
             result.pop("ui_content_type", None)
         if result.get("history_content_type") in [None, ""]:
             result.pop("history_content_type", None)
+        if result.get("parameter_hydration_behaviour") is None:
+            result.pop("parameter_hydration_behaviour", None)
 
         # Convert condition objects to dictionaries if needed
         if self.if_conditions is not None and hasattr(self.if_conditions, "to_dict"):
@@ -781,9 +916,10 @@ class Agent(BaseModel):
     """Main agent class for defining AI workflows."""
 
     name: str
+    key: Optional[str] = None
     description: Optional[str] = None
     persona: Optional[str] = None
-    visibility: str = "private"
+    visibility: str = "public"
     running_message: Optional[str] = None
     finished_message: Optional[str] = None
     version: str = "1.0"
@@ -828,7 +964,6 @@ class Agent(BaseModel):
             "user_output_visibility": OutputVisibility.VISIBLE,
             "bot_output_visibility": OutputVisibility.HIDDEN,
             "output_content_type": OutputContentType.TEXT,
-            "parameter_hydration_behaviour": ParameterHydrationBehaviour.NONE,
         }
 
         # Override with any provided kwargs
@@ -850,7 +985,8 @@ class Agent(BaseModel):
 
         Args:
             step_metadata: Step configuration (key, depends_on, etc.)
-            **codeexec_params: Parameters for codeexec.execute (entrypoint, parameters, resources, etc.)
+            **codeexec_params: Parameters for codeexec.execute (entrypoint, parameters,
+                resources, etc.)
 
         Returns:
             Callable: Decorator function that creates and returns a Step
@@ -890,7 +1026,6 @@ class Agent(BaseModel):
                     "user_output_visibility": OutputVisibility.VISIBLE,
                     "bot_output_visibility": OutputVisibility.HIDDEN,
                     "output_content_type": OutputContentType.TEXT,
-                    "parameter_hydration_behaviour": ParameterHydrationBehaviour.NONE,
                 }
 
             # Remove None values and extract action separately
@@ -932,6 +1067,7 @@ class Agent(BaseModel):
         export_data = {
             "bot": {
                 "Name": self.name,
+                "Key": self.key,
                 "Description": self.description or "",
                 "Visibility": self.visibility,
                 "Persona": self.persona,  # Export as string or null, not object
@@ -1123,6 +1259,349 @@ class Prompt(BaseModel):
         return prompts
 
 
+# Test system classes for agent testing
+class ConditionDefinition(BaseModel):
+    """Condition definition for test expectations."""
+
+    type: str  # "TextContains", "IsSuccess", etc.
+    path: str  # JSONPath or template path to value
+    parameters: Dict[str, Any] = Field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dict format expected by backend."""
+        return {"type": self.type, "path": self.path, "parameters": self.parameters}
+
+
+class APIConditionDefinition(BaseModel):
+    """API condition definition that matches backend expectations."""
+
+    type: str  # "TextContains", "IsSuccess", etc.
+    conditions: List[Any] = Field(default_factory=list)  # For composite conditions
+    leaf: Dict[str, Any] = Field(default_factory=dict)  # Parameters for leaf conditions
+
+    @field_serializer("leaf")
+    def serialize_leaf(self, leaf_data: Dict[str, Any]) -> str:
+        """Serialize leaf field as JSON string to match Go backend json.RawMessage expectation."""
+        import json
+
+        if leaf_data:
+            # Convert TemplateString objects to strings
+            converted_leaf = {}
+            for key, value in leaf_data.items():
+                if hasattr(value, "template"):  # This is a TemplateString
+                    converted_leaf[key] = value.template
+                else:
+                    converted_leaf[key] = value
+            return json.dumps(converted_leaf)
+        else:
+            # Even if leaf is empty, ensure it's a JSON string
+            return "{}"
+
+
+class TestExpectation(BaseModel):
+    """Expected outcome for test validation."""
+
+    type: (
+        str  # "output_contains", "step_success", "invocation_status", "condition", etc.
+    )
+    step_key: Optional[str] = None
+    field: Optional[str] = None
+    operator: str  # "contains", "equals", "greater_than", etc.
+    value: Any
+    description: str
+    condition: Optional[Union[ConditionDefinition, APIConditionDefinition]] = None
+
+    @classmethod
+    def output_contains(
+        cls, step_key: str, text: str, description: Optional[str] = None
+    ) -> "TestExpectation":
+        """Expect step output to contain specific text."""
+        return cls(
+            type="output_contains",
+            step_key=step_key,
+            operator="contains",
+            value=text,
+            description=description
+            or f"Step '{step_key}' output should contain '{text}'",
+        )
+
+    @classmethod
+    def step_succeeds(
+        cls, step_key: str, description: Optional[str] = None
+    ) -> "TestExpectation":
+        """Expect step to complete successfully."""
+        return cls(
+            type="step_success",
+            step_key=step_key,
+            operator="equals",
+            value=True,
+            description=description or f"Step '{step_key}' should succeed",
+        )
+
+    @classmethod
+    def invocation_status(
+        cls, status: str, description: Optional[str] = None
+    ) -> "TestExpectation":
+        """Expect overall invocation to have specific status."""
+        return cls(
+            type="invocation_status",
+            operator="equals",
+            value=status,
+            description=description or f"Invocation should have status '{status}'",
+        )
+
+    @classmethod
+    def from_condition_type(
+        cls,
+        condition_type: str,
+        path: str,
+        parameters: Dict[str, Any],
+        description: Optional[str] = None,
+    ) -> "TestExpectation":
+        """Create a condition-based expectation using backend condition system."""
+        return cls(
+            type="condition",
+            operator="evaluate",
+            value="true",
+            description=description
+            or f"Condition {condition_type} should evaluate to true",
+            condition=ConditionDefinition(
+                type=condition_type, path=path, parameters=parameters
+            ),
+        )
+
+    @classmethod
+    def text_contains(
+        cls, path: str, text: str, description: Optional[str] = None
+    ) -> "TestExpectation":
+        """Expect value at path to contain specific text."""
+        return cls(
+            type="condition",
+            operator="evaluate",
+            value="true",
+            description=description or f"Value at '{path}' should contain '{text}'",
+            condition=ConditionDefinition(
+                type="TextContains", path=path, parameters={"text": text}
+            ),
+        )
+
+    @classmethod
+    def is_success(
+        cls, path: str = "$.Status", description: Optional[str] = None
+    ) -> "TestExpectation":
+        """Expect value at path to indicate success."""
+        return cls(
+            type="condition",
+            operator="evaluate",
+            value="true",
+            description=description or "Operation should succeed",
+            condition=ConditionDefinition(type="IsSuccess", path=path, parameters={}),
+        )
+
+    @classmethod
+    def from_condition(
+        cls, condition_obj: Any, description: Optional[str] = None
+    ) -> "TestExpectation":
+        """Create expectation from condition object with parameter hydration support."""
+        # Convert condition object to dict format
+        condition_dict = condition_obj.to_dict()
+        condition_type = condition_dict.get("type", "Unknown")
+
+        # Extract leaf parameters from the condition object - these support template strings
+        leaf_params = {}
+        if "leaf" in condition_dict:
+            leaf_params = condition_dict["leaf"]
+
+        # Create APIConditionDefinition object that matches backend expectations
+        api_condition = APIConditionDefinition(
+            type=condition_type,
+            conditions=[],  # Empty for leaf conditions
+            leaf=leaf_params,  # Parameters go in leaf field for backend
+        )
+
+        return cls(
+            type="condition",
+            operator="evaluate",
+            value="true",
+            description=description
+            or f"Condition {condition_type} should evaluate to true",
+            condition=api_condition,  # Use APIConditionDefinition object
+        )
+
+
+class TestMessage(BaseModel):
+    """Test message for agent input."""
+
+    role: str  # "user" or "assistant"
+    content: str
+
+    @classmethod
+    def user(cls, content: str) -> "TestMessage":
+        """Create a user message."""
+        return cls(role="user", content=content)
+
+    @classmethod
+    def assistant(cls, content: str) -> "TestMessage":
+        """Create an assistant message."""
+        return cls(role="assistant", content=content)
+
+
+class Test(BaseModel):
+    """Test definition for agent validation."""
+
+    name: str
+    description: str
+    agent: Optional[Any] = None  # Reference to agent being tested
+    messages: List[TestMessage] = Field(default_factory=list)
+    session_messages: List[TestMessage] = Field(default_factory=list)
+    dataset_ids: List[str] = Field(
+        default_factory=list
+    )  # Reference real datasets by ID
+    parameters: Dict[str, str] = Field(default_factory=dict)  # Bot parameters
+    expectations: List[TestExpectation] = Field(default_factory=list)
+    resume_from_state_id: Optional[str] = None
+    test_suite: Optional[str] = None  # Name of the test suite this test belongs to
+
+    def __init__(
+        self,
+        name: Optional[str] = None,
+        description: str = "",
+        agent: Optional[Any] = None,
+        expect: Optional[List[TestExpectation]] = None,
+        **kwargs: Any,
+    ):
+        """Initialize a Test with improved syntax support.
+
+        Args:
+            name: Test name (auto-generated from agent name if not provided)
+            description: Test description
+            agent: Agent to test
+            expect: List of expectations (alternative to using .expect() method)
+            **kwargs: Additional test configuration
+        """
+        # Auto-generate name from agent if not provided
+        if name is None and agent is not None:
+            agent_name = getattr(agent, "name", "agent")
+            name = f"{agent_name}_test"
+        elif name is None:
+            name = "test"
+
+        # Set expectations from constructor if provided
+        if expect is not None:
+            kwargs["expectations"] = expect
+
+        super().__init__(name=name, description=description, agent=agent, **kwargs)
+
+    def message(self, role: str, content: str) -> "Test":
+        """Add a message to the test conversation."""
+        self.messages.append(TestMessage(role=role, content=content))
+        return self
+
+    def user_message(self, content: str) -> "Test":
+        """Add a user message."""
+        return self.message("user", content)
+
+    def assistant_message(self, content: str) -> "Test":
+        """Add an assistant message."""
+        return self.message("assistant", content)
+
+    def dataset(self, dataset_id: str) -> "Test":
+        """Add a dataset to the test by ID."""
+        self.dataset_ids.append(dataset_id)
+        return self
+
+    def expect(self, expectation: TestExpectation) -> "Test":
+        """Add an expectation to the test."""
+        self.expectations.append(expectation)
+        return self
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dict format expected by backend."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "test_data": {
+                "messages": [msg.model_dump() for msg in self.messages],
+                "session_messages": [msg.model_dump() for msg in self.session_messages],
+                "dataset_ids": self.dataset_ids,
+                "parameters": self.parameters,
+                "resume_from_state_id": self.resume_from_state_id,
+            },
+            "expectations": [exp.model_dump() for exp in self.expectations],
+        }
+
+
+def Expect(condition: Any, description: Optional[str] = None) -> TestExpectation:
+    """Create a test expectation from a condition object with clean syntax.
+
+    Usage:
+        Expect(IsSuccess())
+        Expect(TextContains(text=TemplateString("{{output.content}}"), value="success"))
+    """
+    return TestExpectation.from_condition(condition, description)
+
+
+class TestSuite(BaseModel):
+    """Test suite for grouping related tests together."""
+
+    name: str
+    description: str
+    tests: List[Test] = Field(default_factory=list)
+    tags: List[str] = Field(default_factory=list)
+
+    def __init__(
+        self,
+        name: str,
+        description: str = "",
+        tests: Optional[List[Test]] = None,
+        tags: Optional[List[str]] = None,
+        **kwargs: Any,
+    ):
+        """Initialize a TestSuite.
+
+        Args:
+            name: Suite name
+            description: Suite description
+            tests: List of tests to include in the suite
+            tags: Tags for categorizing the test suite
+            **kwargs: Additional suite configuration
+        """
+        super().__init__(
+            name=name,
+            description=description,
+            tests=tests or [],
+            tags=tags or [],
+            **kwargs,
+        )
+
+    def add_test(self, test: Test) -> "TestSuite":
+        """Add a test to the suite."""
+        self.tests.append(test)
+        return self
+
+    def add_tests(self, *tests: Test) -> "TestSuite":
+        """Add multiple tests to the suite."""
+        for test in tests:
+            self.tests.append(test)
+        return self
+
+    def tag(self, *tags: str) -> "TestSuite":
+        """Add tags to the test suite."""
+        for tag in tags:
+            if tag not in self.tags:
+                self.tags.append(tag)
+        return self
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dict format expected by backend."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "tests": [test.to_dict() for test in self.tests],
+            "tags": self.tags,
+        }
+
+
 # Re-export commonly used types for convenience
 __all__ = [
     "Agent",
@@ -1137,6 +1616,20 @@ __all__ = [
     "PythonFile",
     "Prompt",
     "TemplateString",
+    # Test system
+    "Test",
+    "TestSuite",
+    "TestExpectation",
+    "TestMessage",
+    "Expect",
     # Complex types
     "ExecutionCondition",
+    "ConditionDefinition",
+    # Bot permissions
+    "BotPermissions",
+    "set_bot_public",
+    "set_bot_user_permission",
+    "set_bot_org_permission",
+    "get_bot_permissions",
+    "check_bot_access",
 ]

{erdo-0.1.4.dist-info → erdo-0.1.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: erdo
-Version: 0.1.4
+Version: 0.1.5
 Summary: Python SDK for building workflow automation agents with Erdo
 Project-URL: Homepage, https://erdo.ai
 Project-URL: Documentation, https://docs.erdo.ai
@@ -23,6 +23,7 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.9
 Requires-Dist: pydantic>=2.0.0
+Requires-Dist: requests>=2.31.0
 Requires-Dist: typing-extensions>=4.0.0
 Provides-Extra: dev
 Requires-Dist: black>=23.0.0; extra == 'dev'