erdo 0.1.8__tar.gz → 0.1.10__tar.gz

{erdo-0.1.8 → erdo-0.1.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: erdo
-Version: 0.1.8
+Version: 0.1.10
 Summary: Python SDK for building workflow automation agents with Erdo
 Project-URL: Homepage, https://erdo.ai
 Project-URL: Documentation, https://docs.erdo.ai
@@ -19,6 +19,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.9
@@ -292,20 +293,104 @@ main_step.on(
 )
 ```
 
-## CLI Integration
+## Invoking Agents
+
+Use the `invoke()` function to execute agents programmatically:
+
+```python
+from erdo import invoke
+
+# Invoke an agent
+response = invoke(
+    "data-question-answerer",
+    messages=[{"role": "user", "content": "What were Q4 sales?"}],
+    datasets=["sales-2024"],
+    parameters={"time_period": "Q4"},
+)
+
+if response.success:
+    print(response.result)
+else:
+    print(f"Error: {response.error}")
+```
+
+### Invocation Modes
+
+- **Live Mode** (default): Runs against real backend with LLM API
+- **Replay Mode**: Uses cached responses - free after first run (perfect for testing!)
+- **Mock Mode**: Returns synthetic responses - always free
 
-Deploy your agents using the Erdo CLI:
+```python
+# Replay mode - free after first run
+response = invoke("my-agent", messages=[...], mode="replay")
+
+# Mock mode - always free
+response = invoke("my-agent", messages=[...], mode="mock")
+```
+
+## Testing Agents
+
+Write fast, parallel agent tests using `agent_test_*` functions:
+
+```python
+from erdo import invoke
+from erdo.test import text_contains
+
+def agent_test_csv_sales():
+    """Test CSV sales analysis."""
+    response = invoke(
+        "data-question-answerer",
+        messages=[{"role": "user", "content": "What were Q4 sales?"}],
+        datasets=["sales-q4-2024"],
+        mode="replay",  # Free after first run!
+    )
+
+    assert response.success
+    result_text = str(response.result)
+    assert text_contains(result_text, "sales", case_sensitive=False)
+```
+
+Run tests in parallel with the CLI:
 
 ```bash
-# Install the CLI
-pip install erdo
-erdo install-cli
+# Run all tests
+erdo agent-test tests/test_my_agent.py
+
+# Verbose output
+erdo agent-test tests/test_my_agent.py --verbose
+```
 
-# Login to your Erdo account
+### Test Helpers
+
+The `erdo.test` module provides assertion helpers:
+
+```python
+from erdo.test import (
+    text_contains,      # Check if text contains substring
+    text_equals,        # Check exact match
+    text_matches,       # Check regex pattern
+    json_path_equals,   # Check JSON path value
+    json_path_exists,   # Check if JSON path exists
+    has_dataset,        # Check if dataset is present
+)
+```
+
+## CLI Integration
+
+Deploy and manage your agents using the Erdo CLI:
+
+```bash
+# Login to your account
 erdo login
 
-# Sync your agents
-erdo sync
+# Sync your agents to the platform
+erdo sync-agent my_agent.py
+
+# Invoke an agent
+erdo invoke my-agent --message "Hello!"
+
+# Run agent tests
+erdo agent-test tests/test_my_agent.py
 ```
 
 ## Examples
@@ -314,6 +399,8 @@ See the `examples/` directory for complete examples:
 
 - `agent_centric_example.py` - Comprehensive agent with multiple steps
 - `state_example.py` - State management and templating
+- `invoke_example.py` - Agent invocation patterns
+- `agent_test_example.py` - Agent testing examples
 
 ## API Reference
 

{erdo-0.1.8 → erdo-0.1.10}/README.md

@@ -254,20 +254,104 @@ main_step.on(
 )
 ```
 
-## CLI Integration
+## Invoking Agents
+
+Use the `invoke()` function to execute agents programmatically:
+
+```python
+from erdo import invoke
+
+# Invoke an agent
+response = invoke(
+    "data-question-answerer",
+    messages=[{"role": "user", "content": "What were Q4 sales?"}],
+    datasets=["sales-2024"],
+    parameters={"time_period": "Q4"},
+)
+
+if response.success:
+    print(response.result)
+else:
+    print(f"Error: {response.error}")
+```
+
+### Invocation Modes
+
+- **Live Mode** (default): Runs against real backend with LLM API
+- **Replay Mode**: Uses cached responses - free after first run (perfect for testing!)
+- **Mock Mode**: Returns synthetic responses - always free
 
-Deploy your agents using the Erdo CLI:
+```python
+# Replay mode - free after first run
+response = invoke("my-agent", messages=[...], mode="replay")
+
+# Mock mode - always free
+response = invoke("my-agent", messages=[...], mode="mock")
+```
+
+## Testing Agents
+
+Write fast, parallel agent tests using `agent_test_*` functions:
+
+```python
+from erdo import invoke
+from erdo.test import text_contains
+
+def agent_test_csv_sales():
+    """Test CSV sales analysis."""
+    response = invoke(
+        "data-question-answerer",
+        messages=[{"role": "user", "content": "What were Q4 sales?"}],
+        datasets=["sales-q4-2024"],
+        mode="replay",  # Free after first run!
+    )
+
+    assert response.success
+    result_text = str(response.result)
+    assert text_contains(result_text, "sales", case_sensitive=False)
+```
+
+Run tests in parallel with the CLI:
 
 ```bash
-# Install the CLI
-pip install erdo
-erdo install-cli
+# Run all tests
+erdo agent-test tests/test_my_agent.py
+
+# Verbose output
+erdo agent-test tests/test_my_agent.py --verbose
+```
 
-# Login to your Erdo account
+### Test Helpers
+
+The `erdo.test` module provides assertion helpers:
+
+```python
+from erdo.test import (
+    text_contains,      # Check if text contains substring
+    text_equals,        # Check exact match
+    text_matches,       # Check regex pattern
+    json_path_equals,   # Check JSON path value
+    json_path_exists,   # Check if JSON path exists
+    has_dataset,        # Check if dataset is present
+)
+```
+
+## CLI Integration
+
+Deploy and manage your agents using the Erdo CLI:
+
+```bash
+# Login to your account
 erdo login
 
-# Sync your agents
-erdo sync
+# Sync your agents to the platform
+erdo sync-agent my_agent.py
+
+# Invoke an agent
+erdo invoke my-agent --message "Hello!"
+
+# Run agent tests
+erdo agent-test tests/test_my_agent.py
 ```
 
 ## Examples
@@ -276,6 +360,8 @@ See the `examples/` directory for complete examples:
 
 - `agent_centric_example.py` - Comprehensive agent with multiple steps
 - `state_example.py` - State management and templating
+- `invoke_example.py` - Agent invocation patterns
+- `agent_test_example.py` - Agent testing examples
 
 ## API Reference
 

{erdo-0.1.8 → erdo-0.1.10}/erdo/__init__.py

@@ -10,6 +10,9 @@ from ._generated.condition import __all__ as condition_all
 from ._generated.types import *  # noqa: F403,F401
 from ._generated.types import __all__ as generated_all
 
+# Import invoke function for production and testing
+from .invoke import invoke  # noqa: F401
+
 # Import state object for template support
 from .state import state  # noqa: F401
 
@@ -25,5 +28,6 @@ __all__.extend(handwritten_all)
 __all__.extend(generated_all)
 __all__.extend(condition_all)
 
-# Add state to __all__ for explicit import
+# Add state and invoke to __all__ for explicit import
 __all__.append("state")
+__all__.append("invoke")

erdo-0.1.10/erdo/config/__init__.py

@@ -0,0 +1,5 @@
+"""Configuration management for Erdo SDK."""
+
+from .config import Config, get_config, set_config
+
+__all__ = ["Config", "get_config", "set_config"]

erdo-0.1.10/erdo/formatting.py

@@ -0,0 +1,279 @@
+"""Output formatting helpers for bot invocations.
+
+This module provides utilities to parse and format bot invocation events
+into human-readable output. Use these for displaying invocation results
+in terminals, scripts, or other user-facing contexts.
+
+Example:
+    >>> from erdo import invoke
+    >>> from erdo.formatting import format_invocation
+    >>>
+    >>> response = invoke("my_agent", messages=[...])
+    >>> print(format_invocation(response))
+    Bot: my agent
+    Invocation ID: abc-123
+
+    Result:
+    The answer is 4
+
+    >>> # Verbose mode shows steps
+    >>> print(format_invocation(response, verbose=True))
+    Bot: my agent
+    Invocation ID: abc-123
+
+    Steps:
+      ✓ step1 (utils.echo)
+      ✓ step2 (llm.message)
+
+    Result:
+    The answer is 4
+"""
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class StepInfo:
+    """Information about a single step execution."""
+
+    key: str
+    action: str
+    status: str = "completed"
+
+
+@dataclass
+class InvocationSummary:
+    """Structured summary of a bot invocation.
+
+    This provides a clean, parsed view of the invocation events
+    with key information extracted and organized.
+    """
+
+    bot_name: Optional[str] = None
+    bot_key: Optional[str] = None
+    invocation_id: Optional[str] = None
+    steps: List[StepInfo] = field(default_factory=list)
+    result: Optional[Any] = None
+    error: Optional[str] = None
+    success: bool = True
+
+
+def parse_invocation_events(
+    events: List[Dict[str, Any]],
+    bot_key: Optional[str] = None,
+    invocation_id: Optional[str] = None,
+) -> InvocationSummary:
+    """Parse raw invocation events into a structured summary.
+
+    Args:
+        events: List of event dictionaries from the backend
+        bot_key: Bot key to use as fallback if not in events
+        invocation_id: Invocation ID to use as fallback if not in events
+
+    Returns:
+        InvocationSummary with parsed information
+
+    Example:
+        >>> summary = parse_invocation_events(response.events, bot_key="my_agent")
+        >>> print(summary.bot_name)
+        'my agent'
+        >>> print(summary.steps)
+        [StepInfo(key='step1', action='utils.echo', status='completed')]
+    """
+    summary = InvocationSummary(
+        bot_key=bot_key,
+        invocation_id=invocation_id,
+    )
+
+    steps_seen = set()
+    final_messages = []
+
+    for event in events:
+        # Events are dicts with 'payload' and 'metadata'
+        payload = event.get("payload", {})
+        metadata = event.get("metadata", {})
+
+        # Extract invocation ID if not set
+        if summary.invocation_id is None:
+            if "invocation_id" in payload:
+                summary.invocation_id = payload["invocation_id"]
+            elif "invocation_id" in metadata:
+                summary.invocation_id = metadata["invocation_id"]
+
+        # Extract bot name
+        if summary.bot_name is None and "bot_name" in payload:
+            summary.bot_name = payload["bot_name"]
+
+        # Track step execution
+        if "action_type" in payload and "key" in payload:
+            step_key = payload["key"]
+            # Only add if not already present (avoid duplicates)
+            if step_key not in steps_seen:
+                steps_seen.add(step_key)
+                summary.steps.append(
+                    StepInfo(
+                        key=step_key,
+                        action=payload["action_type"],
+                        status="completed",
+                    )
+                )
+
+        # Collect user-visible text messages (final output)
+        if isinstance(payload, str) and metadata.get("user_visibility") == "visible":
+            if metadata.get("message_content_id"):  # It's part of a message
+                final_messages.append(payload)
+
+    # Combine final messages into result
+    if final_messages:
+        summary.result = "".join(final_messages)
+
+    return summary
+
+
+def format_invocation(
+    response: Any,
+    mode: str = "text",
+    verbose: bool = False,
+) -> str:
+    """Format a bot invocation response for display.
+
+    Args:
+        response: InvokeResult from invoke()
+        mode: Output mode - 'text' or 'json'
+        verbose: Show detailed step execution (only applies to text mode)
+
+    Returns:
+        Formatted string ready to print
+
+    Example:
+        >>> from erdo import invoke
+        >>> from erdo.formatting import format_invocation
+        >>>
+        >>> response = invoke("my_agent", messages=[...])
+        >>>
+        >>> # Simple text output
+        >>> print(format_invocation(response))
+        >>>
+        >>> # Verbose text output (shows steps)
+        >>> print(format_invocation(response, verbose=True))
+        >>>
+        >>> # JSON output
+        >>> print(format_invocation(response, mode='json'))
+    """
+    if mode == "json":
+        return _format_as_json(response)
+    else:
+        return _format_as_text(response, verbose)
+
+
+def _format_as_json(response: Any) -> str:
+    """Format response as JSON."""
+    output = {
+        "success": response.success,
+        "invocation_id": response.invocation_id,
+        "result": response.result,
+        "error": response.error,
+        "events": response.events,
+    }
+    return json.dumps(output, indent=2)
+
+
+def _format_as_text(response: Any, verbose: bool = False) -> str:
+    """Format response as human-readable text."""
+    # Get bot key from response if available
+    bot_key = getattr(response, "bot_id", None)
+    invocation_id = response.invocation_id
+
+    # Parse events to extract information
+    # Handle SDK response structure: response.result may contain {'events': [...]}
+    events_to_process = response.events
+    if isinstance(response.result, dict) and "events" in response.result:
+        events_to_process = response.result["events"]
+
+    summary = parse_invocation_events(
+        events_to_process,
+        bot_key=bot_key,
+        invocation_id=invocation_id,
+    )
+
+    # Build output
+    lines = []
+
+    if not response.success:
+        lines.append(f"❌ Invocation failed: {response.error}")
+        return "\n".join(lines)
+
+    # Header
+    lines.append(f"Bot: {summary.bot_name or summary.bot_key or 'unknown'}")
+    lines.append(f"Invocation ID: {summary.invocation_id or 'N/A'}")
+
+    # Steps (verbose mode)
+    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})")
+
+    # Result
+    if summary.result:
+        lines.append("")
+        lines.append("Result:")
+
+        # Try to parse as JSON for pretty printing
+        try:
+            parsed = json.loads(summary.result)
+            lines.append(json.dumps(parsed, indent=2))
+        except (json.JSONDecodeError, TypeError):
+            # If not JSON, print as is
+            lines.append(summary.result)
+    elif response.result is not None:
+        lines.append("")
+        lines.append("Result:")
+        if isinstance(response.result, (dict, list)):
+            lines.append(json.dumps(response.result, indent=2))
+        else:
+            lines.append(str(response.result))
+
+    return "\n".join(lines)
+
+
+# Convenience method to add to InvokeResult
+def add_format_method():
+    """Add format() method to InvokeResult class.
+
+    This is called during SDK initialization to add the format()
+    method to InvokeResult instances.
+    """
+    try:
+        from .invoke.invoke import InvokeResult
+
+        def format_method(self, mode="text", verbose=False):
+            """Format this invocation result for display.
+
+            Args:
+                mode: 'text' or 'json'
+                verbose: Show step details (text mode only)
+
+            Returns:
+                Formatted string
+
+            Example:
+                >>> response = invoke("my_agent", messages=[...])
+                >>> print(response.format())
+                >>> print(response.format(verbose=True))
+            """
+            return format_invocation(self, mode=mode, verbose=verbose)
+
+        # Add method to class
+        InvokeResult.format = format_method
+
+    except ImportError:
+        # InvokeResult not available, skip
+        pass
+
+
+# Auto-add format method on import
+add_format_method()

{erdo-0.1.8 → erdo-0.1.10}/erdo/invoke/__init__.py

@@ -1,10 +1,11 @@
 """Invoke module for running agents via the Erdo orchestrator."""
 
-from .invoke import Invoke, InvokeResult, invoke_agent, invoke_by_key
+from .invoke import Invoke, InvokeResult, invoke, invoke_agent, invoke_by_key
 
 __all__ = [
     "Invoke",
     "InvokeResult",
+    "invoke",
     "invoke_agent",
     "invoke_by_key",
 ]

{erdo-0.1.8 → erdo-0.1.10}/erdo/invoke/client.py

@@ -1,7 +1,7 @@
 """API client for invoking bots via the backend orchestrator."""
 
 import json
-from typing import Any, Dict, Generator, Optional, Union
+from typing import Any, Dict, Generator, List, Optional, Union
 
 import requests
 
@@ -50,16 +50,20 @@ class InvokeClient:
     def invoke_bot(
         self,
         bot_identifier: 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,
     ) -> Union[SSEClient, Dict[str, Any]]:
         """Invoke a bot via the backend orchestrator.
 
         Args:
             bot_identifier: Bot ID or key (e.g., "erdo.data-analyzer")
+            messages: Messages in format [{"role": "user", "content": "..."}]
             parameters: Parameters to pass to the bot
-            dataset_ids: Optional dataset IDs to include
+            dataset_slugs: Optional dataset slugs to include
+            mode: Invocation mode: "live" (default), "replay" (cached), or "mock" (synthetic)
             stream: Whether to return SSE client for streaming (default: False)
 
         Returns:
@@ -76,12 +80,23 @@ class InvokeClient:
         }
 
         # Build invoke parameters
-        invoke_params: Dict[str, Any] = {
-            "parameters": parameters or {},
-        }
+        invoke_params: Dict[str, Any] = {}
+
+        # Add messages if provided
+        if messages:
+            invoke_params["messages"] = messages
+
+        # Add parameters if provided
+        if parameters:
+            invoke_params["parameters"] = parameters
+
+        # Add dataset slugs if provided
+        if dataset_slugs:
+            invoke_params["dataset_slugs"] = dataset_slugs
 
-        if dataset_ids:
-            invoke_params["dataset_ids"] = dataset_ids
+        # Add mode if provided (live/replay/mock)
+        if mode:
+            invoke_params["mode"] = mode
 
         # Make the request - always stream to handle SSE
         response = requests.post(url, json=invoke_params, headers=headers, stream=True)