erdo 0.1.8__py3-none-any.whl → 0.1.9__py3-none-any.whl

erdo/invoke/invoke.py

@@ -40,7 +40,7 @@ class Invoke:
         self,
         agent: Optional[Any] = None,
         parameters: Optional[Dict[str, Any]] = None,
-        dataset_ids: Optional[list] = None,
+        dataset_slugs: Optional[list] = None,
         endpoint: Optional[str] = None,
         auth_token: Optional[str] = None,
         stream: bool = False,
@@ -51,7 +51,7 @@ class Invoke:
         Args:
             agent: Optional Agent instance to invoke immediately
             parameters: Parameters to pass to the agent
-            dataset_ids: Dataset IDs to include
+            dataset_slugs: Dataset slugs to include (e.g. ["my-dataset"] or ["org.my-dataset"])
             endpoint: API endpoint URL
             auth_token: Authentication token
             stream: Whether to stream events
@@ -68,14 +68,17 @@ class Invoke:
                 raise ValueError("Agent must have a 'key' attribute for invocation")
 
             self.result = self.invoke_by_key(
-                bot_key, parameters=parameters, dataset_ids=dataset_ids, stream=stream
+                bot_key,
+                parameters=parameters,
+                dataset_slugs=dataset_slugs,
+                stream=stream,
             )
 
     def invoke_agent(
         self,
         agent: Any,
         parameters: Optional[Dict[str, Any]] = None,
-        dataset_ids: Optional[list] = None,
+        dataset_slugs: Optional[list] = None,
         stream: bool = False,
     ) -> InvokeResult:
         """Invoke an agent instance.
@@ -83,7 +86,7 @@ class Invoke:
         Args:
             agent: Agent instance with a 'key' attribute
             parameters: Parameters to pass to the agent
-            dataset_ids: Dataset IDs to include
+            dataset_slugs: Dataset slugs to include (e.g. ["my-dataset"] or ["org.my-dataset"])
             stream: Whether to stream events
 
         Returns:
@@ -93,75 +96,222 @@ class Invoke:
         if not bot_key:
             raise ValueError("Agent must have a 'key' attribute for invocation")
 
-        return self.invoke_by_key(bot_key, parameters, dataset_ids, stream)
+        return self.invoke_by_key(
+            bot_key, parameters=parameters, dataset_slugs=dataset_slugs, stream=stream
+        )
 
     def invoke_by_key(
         self,
         bot_key: str,
+        messages: Optional[List[Dict[str, str]]] = None,
         parameters: Optional[Dict[str, Any]] = None,
-        dataset_ids: Optional[list] = None,
+        dataset_slugs: Optional[list] = None,
+        mode: Optional[str] = None,
         stream: bool = False,
+        output_format: str = "events",
+        verbose: bool = False,
     ) -> InvokeResult:
         """Invoke a bot by its key.
 
         Args:
             bot_key: Bot key (e.g., "erdo.data-analyzer")
+            messages: Messages in format [{"role": "user", "content": "..."}]
             parameters: Parameters to pass to the bot
-            dataset_ids: Dataset IDs to include
+            dataset_slugs: Dataset slugs to include (e.g. ["my-dataset"] or ["org.my-dataset"])
+            mode: Invocation mode: "live" (default), "replay" (cached), or "mock" (synthetic)
             stream: Whether to stream events
+            output_format: Output format: "events" (raw), "text" (formatted), "json" (summary)
+            verbose: Show detailed steps (only for text format)
 
         Returns:
             InvokeResult with the outcome
         """
         try:
             response = self.client.invoke_bot(
-                bot_key, parameters=parameters, dataset_ids=dataset_ids, stream=stream
+                bot_key,
+                messages=messages,
+                parameters=parameters,
+                dataset_slugs=dataset_slugs,
+                mode=mode,
+                stream=stream,
             )
 
             if stream:
                 # Process SSE events
                 events = []
-                final_result = None
                 invocation_id = None
 
                 # Type guard: response should be SSEClient when stream=True
                 if not isinstance(response, dict):
-                    for event in response.events():
-                        events.append(event)
-
-                        if self.print_events:
-                            self._print_event(event)
-
-                        # Extract invocation ID from events
-                        if "invocation_id" in event:
-                            invocation_id = event["invocation_id"]
-
-                        # Check for final result
-                        if event.get("type") == "invocation_completed":
-                            final_result = event.get("result")
-                        elif event.get("type") == "result":
-                            final_result = event.get("data")
+                    # For formatted output, print as we stream
+                    if output_format in ["text", "json"] and not self.print_events:
+                        from ..formatting import parse_invocation_events
+
+                        bot_name_printed = False
+                        completed_steps = set()
+
+                        for event in response.events():
+                            events.append(event)
+
+                            # Extract invocation ID and bot name from payload
+                            payload = event.get("payload", {})
+                            if isinstance(payload, dict):
+                                if "invocation_id" in payload and not invocation_id:
+                                    invocation_id = payload["invocation_id"]
+                                if "bot_name" in payload and not bot_name_printed:
+                                    bot_name = payload["bot_name"]
+                                    if output_format == "text":
+                                        print(f"Bot: {bot_name}")
+                                        print(
+                                            f"Invocation ID: {invocation_id or 'N/A'}"
+                                        )
+                                        if verbose:
+                                            print("\nSteps:")
+                                    bot_name_printed = True
+
+                            # Print steps as they complete (verbose mode)
+                            if (
+                                verbose
+                                and output_format == "text"
+                                and payload.get("status") == "step finished"
+                            ):
+                                # Parse to get step info
+                                summary = parse_invocation_events(
+                                    events, bot_key, invocation_id
+                                )
+                                for step in summary.steps:
+                                    if step.key and step.key not in completed_steps:
+                                        print(f"  ✓ {step.key} ({step.action})")
+                                        completed_steps.add(step.key)
+
+                            # Print message content as it streams
+                            if (
+                                output_format == "text"
+                                and isinstance(payload, str)
+                                and len(payload) > 0
+                            ):
+                                # Check if this is actual content (not JSON)
+                                if not payload.startswith(
+                                    "{"
+                                ) and not payload.startswith("["):
+                                    print(payload, end="", flush=True)
+                    else:
+                        # For raw events or print_events mode, just collect
+                        for event in response.events():
+                            events.append(event)
+
+                            if self.print_events:
+                                self._print_event(event)
+
+                            # Extract invocation ID from events
+                            if "invocation_id" in event:
+                                invocation_id = event["invocation_id"]
+
+                # Format final result based on output_format
+                formatted_result = self._format_result(
+                    events, bot_key, invocation_id, output_format, verbose
+                )
 
                 return InvokeResult(
                     success=True,
                     bot_id=bot_key,
                     invocation_id=invocation_id,
-                    result=final_result,
+                    result=formatted_result,
                     events=events,
                 )
             else:
-                # Non-streaming response - response is a dict
+                # Non-streaming response - response is a dict with 'events' key
                 response_dict = response if isinstance(response, dict) else {}
+                # Extract the events list from the response
+                events = response_dict.get("events", [])
+
+                # Format result based on output_format
+                formatted_result = self._format_result(
+                    events, bot_key, None, output_format, verbose
+                )
+
                 return InvokeResult(
                     success=True,
                     bot_id=bot_key,
-                    result=response_dict,
-                    events=[response_dict],
+                    result=formatted_result,
+                    events=events,
                 )
 
         except Exception as e:
             return InvokeResult(success=False, bot_id=bot_key, error=str(e))
 
+    def _format_result(
+        self,
+        events: List[Dict[str, Any]],
+        bot_key: str,
+        invocation_id: Optional[str],
+        output_format: str,
+        verbose: bool,
+    ) -> Any:
+        """Format the result based on output_format parameter.
+
+        Args:
+            events: List of events from the invocation
+            bot_key: Bot key
+            invocation_id: Invocation ID
+            output_format: "events", "text", or "json"
+            verbose: Show detailed steps (for text format)
+
+        Returns:
+            Formatted result based on output_format
+        """
+        if output_format == "events":
+            # Return raw events (backwards compatible)
+            return {"events": events}
+
+        # Import formatting helpers
+        from ..formatting import parse_invocation_events
+
+        # Parse events into structured summary
+        summary = parse_invocation_events(events, bot_key, invocation_id)
+
+        if output_format == "text":
+            # Format as human-readable text
+            lines = []
+            lines.append(f"Bot: {summary.bot_name or summary.bot_key or 'unknown'}")
+            lines.append(f"Invocation ID: {summary.invocation_id or 'N/A'}")
+
+            if verbose and summary.steps:
+                lines.append("")
+                lines.append("Steps:")
+                for step in summary.steps:
+                    status_icon = "✓" if step.status == "completed" else "•"
+                    lines.append(f"  {status_icon} {step.key} ({step.action})")
+
+            if summary.result:
+                lines.append("")
+                lines.append("Result:")
+                try:
+                    parsed = json.loads(summary.result)
+                    lines.append(json.dumps(parsed, indent=2))
+                except (json.JSONDecodeError, TypeError):
+                    lines.append(summary.result)
+
+            return "\n".join(lines)
+
+        elif output_format == "json":
+            # Return structured summary
+            return {
+                "bot_name": summary.bot_name,
+                "bot_key": summary.bot_key,
+                "invocation_id": summary.invocation_id,
+                "steps": [
+                    {"key": s.key, "action": s.action, "status": s.status}
+                    for s in summary.steps
+                ],
+                "result": summary.result,
+                "success": summary.success,
+                "error": summary.error,
+            }
+
+        # Default: return events
+        return {"events": events}
+
     def _print_event(self, event: Dict[str, Any]):
         """Print an event in a readable format."""
         event_type = event.get("type", "unknown")
@@ -186,6 +336,71 @@ class Invoke:
 
 
 # Convenience functions
+def invoke(
+    bot_key: str,
+    messages: Optional[List[Dict[str, str]]] = None,
+    parameters: Optional[Dict[str, Any]] = None,
+    datasets: Optional[list] = None,
+    mode: Optional[str] = None,
+    stream: bool = False,
+    output_format: str = "events",
+    verbose: bool = False,
+    print_events: bool = False,
+    **kwargs,
+) -> InvokeResult:
+    """Invoke a bot with a clean API.
+
+    Args:
+        bot_key: Bot key (e.g., "erdo.data-analyzer")
+        messages: Messages in format [{"role": "user", "content": "..."}]
+        parameters: Parameters to pass to the bot
+        datasets: Dataset slugs to include (e.g. ["my-dataset"] or ["org.my-dataset"])
+        mode: Invocation mode: "live" (default), "replay" (cached), or "mock" (synthetic)
+        stream: Whether to stream events
+        output_format: Output format: "events" (raw), "text" (formatted), "json" (summary)
+        verbose: Show detailed steps (only for text format)
+        print_events: Whether to print events
+        **kwargs: Additional arguments (endpoint, auth_token)
+
+    Returns:
+        InvokeResult with formatted result in response.result
+
+    Example:
+        >>> from erdo import invoke
+        >>>
+        >>> # Default: raw events (backwards compatible)
+        >>> response = invoke("my_agent", messages=[...])
+        >>> print(response.result)  # {"events": [...]}
+        >>>
+        >>> # Formatted text output
+        >>> response = invoke("my_agent", messages=[...], output_format="text")
+        >>> print(response.result)
+        Bot: my agent
+        Invocation ID: abc-123
+        Result:
+        The answer is 4
+        >>>
+        >>> # Formatted text with verbose steps
+        >>> response = invoke("my_agent", messages=[...], output_format="text", verbose=True)
+        >>>
+        >>> # JSON summary
+        >>> response = invoke("my_agent", messages=[...], output_format="json")
+        >>> print(response.result)  # {"bot_name": ..., "steps": [...], "result": ...}
+    """
+    return invoke_by_key(
+        bot_key=bot_key,
+        messages=messages,
+        parameters=parameters,
+        dataset_slugs=datasets,
+        mode=mode,
+        stream=stream,
+        output_format=output_format,
+        verbose=verbose,
+        print_events=print_events,
+        **kwargs,
+    )
+
+
 def invoke_agent(
     agent: Any,
     parameters: Optional[Dict[str, Any]] = None,
@@ -217,9 +432,13 @@ def invoke_agent(
 
 def invoke_by_key(
     bot_key: str,
+    messages: Optional[List[Dict[str, str]]] = None,
     parameters: Optional[Dict[str, Any]] = None,
     dataset_ids: Optional[list] = None,
+    mode: Optional[str] = None,
     stream: bool = False,
+    output_format: str = "events",
+    verbose: bool = False,
     print_events: bool = False,
     **kwargs,
 ) -> InvokeResult:
@@ -227,9 +446,13 @@ def invoke_by_key(
 
     Args:
         bot_key: Bot key (e.g., "erdo.data-analyzer")
+        messages: Messages in format [{"role": "user", "content": "..."}]
         parameters: Parameters to pass to the bot
         dataset_ids: Dataset IDs to include
+        mode: Invocation mode: "live" (default), "replay" (cached), or "mock" (synthetic)
         stream: Whether to stream events
+        output_format: Output format: "events" (raw), "text" (formatted), "json" (summary)
+        verbose: Show detailed steps (only for text format)
         print_events: Whether to print events
         **kwargs: Additional arguments (endpoint, auth_token)
 
@@ -241,4 +464,6 @@ def invoke_by_key(
         auth_token=kwargs.get("auth_token"),
         print_events=print_events,
     )
-    return invoke.invoke_by_key(bot_key, parameters, dataset_ids, stream)
+    return invoke.invoke_by_key(
+        bot_key, messages, parameters, dataset_ids, mode, stream, output_format, verbose
+    )

erdo/test/__init__.py

@@ -0,0 +1,41 @@
+"""Test evaluation helpers for erdo agent testing.
+
+This module provides helper functions for writing clean assertions when testing agents.
+Use these in regular Python scripts - no pytest needed!
+
+Example:
+    >>> from erdo import invoke
+    >>> from erdo.test import text_contains, json_path_equals
+    >>>
+    >>> # Test in a regular Python script
+    >>> response = invoke("my_agent", messages=[...], mode="replay")
+    >>> assert text_contains(response.result, "expected text")
+    >>> assert json_path_equals(response.result, "status", "success")
+    >>>
+    >>> # Or use via CLI
+    >>> # ./erdo invoke my_agent --message "test" --mode replay
+"""
+
+from .evaluate import (
+    has_dataset,
+    json_path_equals,
+    json_path_exists,
+    text_contains,
+    text_equals,
+    text_matches,
+)
+from .runner import discover_tests
+from .runner import main as run_tests
+from .runner import run_tests_parallel
+
+__all__ = [
+    "text_contains",
+    "text_equals",
+    "text_matches",
+    "json_path_equals",
+    "json_path_exists",
+    "has_dataset",
+    "run_tests",
+    "run_tests_parallel",
+    "discover_tests",
+]