erdo 0.1.4__tar.gz → 0.1.6__tar.gz

erdo-0.1.6/CLAUDE.md

@@ -0,0 +1,246 @@
+# Erdo Python SDK Development
+
+This is the Python SDK for Erdo, providing the API for defining AI agents, steps, and actions.
+
+**📚 Critical Documentation:**
+- **[../SDK_DEVELOPMENT.md](../SDK_DEVELOPMENT.md)** - **READ THIS FIRST** - Virtual environment gotchas, testing changes end-to-end, debugging data flow issues
+
+## Quick Start
+
+### After Making Changes
+
+**CRITICAL**: After modifying the SDK, you MUST update all virtual environments that use it:
+
+```bash
+# Update the SDK's own venv
+cd erdo-python-sdk
+uv pip install -e .
+
+# Update the agents venv (used by CLI)
+cd ../erdo-agents
+uv pip install -e ../erdo-python-sdk
+
+# Verify the correct version is loaded
+uv run python3 -c "import erdo; print(erdo.__file__)"
+# Should show: /Users/niall/work/erdo/erdo-python-sdk/erdo/__init__.py
+# NOT: erdo-agents/.venv/lib/python3.XX/site-packages/erdo/__init__.py
+```
+
+**Why this matters**: The CLI uses `uv run python3` which runs in the `erdo-agents/.venv` virtual environment. If you don't update the venv, the CLI will use the old published PyPI version of the SDK, not your local changes.
+
+### Testing Your Changes
+
+1. **Test Python SDK directly**:
+```bash
+cd erdo-python-sdk
+uv run python3 -c "
+from erdo import Agent
+from erdo.actions import utils
+agent = Agent(key='test.test', name='Test', description='Test')
+step = agent.step(utils.echo(data='hello'))
+print(step.to_dict())
+"
+```
+
+2. **Test CLI integration**:
+```bash
+cd ../erdo-cli
+./erdo test /path/to/test_agent.py
+./erdo sync-agent /path/to/test_agent.py --dry-run
+```
+
+3. **Test backend integration**:
+```bash
+# Sync to a running backend and check logs
+./erdo sync-agent /path/to/test_agent.py
+```
+
+## Project Structure
+
+```
+erdo-python-sdk/
+├── erdo/
+│   ├── __init__.py          # Main exports (Agent, Step, etc.)
+│   ├── types.py             # Core types (Step, Agent, StepMetadata, etc.)
+│   ├── actions/             # Action modules (utils, codeexec, llm, etc.)
+│   └── _generated/          # Generated types (DO NOT EDIT MANUALLY)
+│       └── types.py         # Run 'erdo gen-client' to regenerate
+├── tests/                   # Unit tests
+└── pyproject.toml          # Package configuration
+```
+
+## Key Files
+
+### `erdo/types.py`
+Contains the core SDK types:
+- `Agent` - Top-level agent definition
+- `Step` - Individual workflow step
+- `StepMetadata` - Base class for step configuration
+- `ResultHandler` - Result handler configuration
+- Enums: `OutputVisibility`, `OutputContentType`, `ParameterHydrationBehaviour`
+
+**Important**: When adding or modifying fields:
+1. Update the Pydantic model definition
+2. Update the `to_dict()` method if custom serialization is needed
+3. Filter out None values for optional fields with defaults
+
+### `erdo/_generated/types.py`
+Auto-generated from the OpenAPI schema. **DO NOT EDIT MANUALLY**.
+
+To regenerate:
+```bash
+cd ../erdo-cli
+./erdo gen-client
+```
+
+## Important Concepts
+
+### Using step_metadata in Result Handlers
+
+When creating steps in result handlers via `.on()`, you can configure step properties using `step_metadata`:
+
+```python
+step.on(IsSuccess(),
+    utils.parse_json(
+        json_data="{{output}}",
+        step_metadata=StepMetadata(
+            key="parse_result",
+            output_behavior={"data": OutputBehaviorType.MERGE}
+        )
+    )
+)
+```
+
+**How it works**:
+1. Action param classes (EchoParams, ParseJsonParams, etc.) have a `step_metadata` field
+2. When passed to an action, the metadata is stored on the action object
+3. `Step.on()` extracts the metadata and merges it into the Step configuration
+4. The `_extract_step_config_from_action()` helper handles the extraction
+
+**Important**: The `step_metadata` parameter is specifically for use in action calls. It allows you to configure step properties (key, output_behavior, execution_mode, visibility, etc.) when the step is created from an action.
+
+### Field Naming: American vs British Spelling
+
+The Python SDK uses American spelling (`output_behavior`) but the Go backend expects British spelling (`output_behaviour`). The `Step.to_dict()` method automatically handles this conversion during serialization:
+
+```python
+# In Step.to_dict():
+if "output_behavior" in result:
+    result["output_behaviour"] = result.pop("output_behavior")
+```
+
+This ensures agents sync correctly to the backend.
+
+## Common Development Tasks
+
+### Adding a New Field to Step
+
+Example: Adding a new optional field `my_field`:
+
+1. **Update `types.py`**:
+```python
+class StepMetadata(BaseModel):
+    # ... existing fields ...
+    my_field: Optional[str] = None
+```
+
+2. **Update `to_dict()` method** (if the field should be omitted when None):
+```python
+def to_dict(self) -> Dict[str, Any]:
+    result = self.model_dump(exclude={'agent', 'result_handler', 'action', 'depends_on'})
+
+    # Filter out None optional fields
+    if result.get("my_field") is None:
+        result.pop("my_field", None)
+
+    return result
+```
+
+3. **Update the backend**:
+   - Add to `erdo-common/types/bot.go` - `Step` struct
+   - Add to `erdo/backend/bot/db/migrations/` - Database migration
+   - Run `sqlc generate` in backend
+
+4. **Test**:
+```bash
+# Update venvs
+cd erdo-python-sdk && uv pip install -e .
+cd ../erdo-agents && uv pip install -e ../erdo-python-sdk
+
+# Test
+cd ../erdo-cli
+./erdo test /path/to/test_agent.py
+```
+
+### Changing Field Types
+
+Example: Changing from `field: SomeEnum = SomeEnum.NONE` to `field: Optional[SomeEnum] = None`:
+
+**See [../SDK_DEVELOPMENT.md](../SDK_DEVELOPMENT.md#type-changes-checklist)** for the complete checklist.
+
+Key steps:
+1. Change Python SDK type definition
+2. Update `to_dict()` to filter None values
+3. Update Go common types (value → pointer)
+4. Update Go backend code handling the field
+5. Update CLI export/sync code
+6. Update all venvs
+7. Test end-to-end
+
+## Debugging
+
+### Virtual Environment Issues
+
+**Problem**: Changes not appearing when testing
+
+```bash
+# Check which SDK is loaded
+uv run python3 -c "import erdo; print(erdo.__file__)"
+
+# If it shows .venv/lib/python3.XX/site-packages/erdo
+# Then reinstall in editable mode:
+uv pip install -e /Users/niall/work/erdo/erdo-python-sdk
+```
+
+### Field Serialization Issues
+
+**Problem**: Field showing wrong value in database
+
+```python
+# Debug the to_dict() output
+from erdo import Agent
+from erdo.actions import utils
+agent = Agent(key='test.test', name='Test', description='Test')
+step = agent.step(utils.echo(data='hello'))
+
+# Check attribute
+print(f"step.my_field: {step.my_field}")
+
+# Check model_dump
+dump = step.model_dump(exclude={'agent', 'action'})
+print(f"model_dump: {dump.get('my_field')}")
+
+# Check to_dict
+step_dict = step.to_dict()
+print(f"to_dict: {'my_field' in step_dict}")
+```
+
+## Testing
+
+```bash
+# Run unit tests
+cd erdo-python-sdk
+uv run pytest tests/
+
+# Run specific test
+uv run pytest tests/test_types.py::test_step_creation
+
+# Test import
+uv run python3 -c "from erdo import Agent; print('OK')"
+```
+
+## Related Documentation
+
+- [../SDK_DEVELOPMENT.md](../SDK_DEVELOPMENT.md) - Comprehensive guide for SDK development
+- [../erdo/CLAUDE.md](../erdo/CLAUDE.md) - Backend development guide
+- [../erdo-cli/CLAUDE.md](../erdo-cli/CLAUDE.md) - CLI development guide

{erdo-0.1.4 → erdo-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: erdo
-Version: 0.1.4
+Version: 0.1.6
 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'
@@ -31,6 +32,8 @@ Requires-Dist: isort>=5.0.0; extra == 'dev'
 Requires-Dist: mypy>=1.0.0; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
 Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
+Requires-Dist: types-requests>=2.31.0; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # Erdo Agent SDK

erdo-0.1.6/VERSION

@@ -0,0 +1 @@
+0.1.6

{erdo-0.1.4 → erdo-0.1.6}/erdo/__init__.py

@@ -4,32 +4,32 @@
 
 # Import all condition functions from generated condition module
 from ._generated.condition import *  # noqa: F403,F401
-from ._generated.condition import __all__ as condition_all
 
-# Import all generated types first
+# Import all generated types automatically
 from ._generated.types import *  # noqa: F403,F401
-from ._generated.types import __all__ as generated_all
 
 # Import state object for template support
 from .state import state  # noqa: F401
 
-# Import all handwritten SDK classes last (override generated ones)
-from .types import *  # noqa: F403,F401  # type: ignore[assignment]
-from .types import __all__ as handwritten_all
+# Import all handwritten SDK classes automatically
+from .types import *  # noqa: F403,F401
 
 __version__ = "0.1.0"
 
-# Build __all__ dynamically by combining all available types
-__all__ = []
+# Add all condition functions automatically
+from ._generated.condition import __all__ as condition_all  # noqa: E402
 
-# Add generated types first
-__all__.extend(generated_all)
+# Add all generated types automatically
+from ._generated.types import __all__ as generated_all  # noqa: E402
 
-# Add all condition functions
-__all__.extend(condition_all)
+# Add handwritten SDK classes
+from .types import __all__ as handwritten_all  # noqa: E402
 
-# Add handwritten SDK classes (may override generated ones in __all__)
+# Build __all__ dynamically by combining all available types
+__all__ = []
 __all__.extend(handwritten_all)
+__all__.extend(generated_all)
+__all__.extend(condition_all)
 
 # Add state to __all__ for explicit import
 __all__.append("state")

{erdo-0.1.4 → erdo-0.1.6}/erdo/_generated/actions/__init__.py

@@ -16,17 +16,19 @@ from . import codeexec  # noqa: F401
 from . import llm  # noqa: F401
 from . import memory  # noqa: F401
 from . import resource_definitions  # noqa: F401
+from . import sqlexec  # noqa: F401
 from . import utils  # noqa: F401
 from . import webparser  # noqa: F401
 from . import websearch  # noqa: F401
-from .analysis import *  # noqa: F403,F401
 
 # Import all functions from service modules
+from .analysis import *  # noqa: F403,F401
 from .bot import *  # noqa: F403,F401
 from .codeexec import *  # noqa: F403,F401
 from .llm import *  # noqa: F403,F401
 from .memory import *  # noqa: F403,F401
 from .resource_definitions import *  # noqa: F403,F401
+from .sqlexec import *  # noqa: F403,F401
 from .utils import *  # noqa: F403,F401
 from .webparser import *  # noqa: F403,F401
 from .websearch import *  # noqa: F403,F401

erdo-0.1.6/erdo/_generated/actions/analysis.py

@@ -0,0 +1,179 @@
+"""
+Analysis actions for creating and managing data analysis service functions.
+Auto-generated - DO NOT EDIT.
+
+Provides type-safe action definitions for analysis service.
+Actual execution happens in the Go backend after syncing.
+"""
+
+from typing import Any, List, Optional, Union
+
+from pydantic import BaseModel
+
+from erdo.template import TemplateString
+
+
+class BaseActionParams(BaseModel):
+    """Base class for all action parameter classes.
+
+    Provides common fields that all actions support:
+    - name: The action type identifier
+    - step_metadata: Optional configuration for the step created from this action
+    """
+
+    name: str
+    step_metadata: Optional[Any] = None
+
+
+class CreateAnalysisParams(BaseActionParams):
+    """Create an analysis for a dataset, resource, or dataset-resource combination parameters"""
+
+    name: str = "analysis.create_analysis"  # Action type for roundtrip compatibility
+    analysis: Optional[Any] = None  # analysis parameter
+    dataset_id: Optional[Union[str, TemplateString]] = None  # dataset_id parameter
+    resource_id: Optional[Union[str, TemplateString]] = None  # resource_id parameter
+
+
+class AnalyzeCsvParams(BaseActionParams):
+    """Analyze CSV file using Go-based CSV analyzer (fast, no Python needed) parameters"""
+
+    name: str = "analysis.analyze_csv"  # Action type for roundtrip compatibility
+    file: Optional[Any] = None  # file parameter
+    columns: Optional[Any] = None  # columns parameter
+    rows: Optional[Any] = None  # rows parameter
+    encryption_key: Optional[Union[str, TemplateString]] = (
+        None  # encryption_key parameter
+    )
+
+
+class AnalyzeExcelParams(BaseActionParams):
+    """Analyze Excel file using Go-based Excel analyzer (fast, no Python needed) parameters"""
+
+    name: str = "analysis.analyze_excel"  # Action type for roundtrip compatibility
+    file: Optional[Any] = None  # file parameter
+    encryption_key: Optional[Union[str, TemplateString]] = (
+        None  # encryption_key parameter
+    )
+
+
+class CreateAnalysisResult(BaseModel):
+    """Create an analysis for a dataset, resource, or dataset-resource combination result type
+
+    Result schema for analysis.create_analysis action.
+    """
+
+    analysis: Any
+    insights: Optional[List[str]]
+    recommendations: Optional[List[str]]
+
+
+class AnalyzeCsvResult(BaseModel):
+    """Analyze CSV file using Go-based CSV analyzer (fast, no Python needed) result type
+
+    Result schema for analysis.analyze_csv action.
+    """
+
+    summary: str
+    details: Any
+    dataset_file_name: str
+
+
+class AnalyzeExcelResult(BaseModel):
+    """Analyze Excel file using Go-based Excel analyzer (fast, no Python needed) result type
+
+    Result schema for analysis.analyze_excel action.
+    """
+
+    summary: str
+    details: Any
+    dataset_file_name: str
+
+
+def create_analysis(
+    analysis: Optional[Any] = None,
+    dataset_id: Optional[Union[str, TemplateString]] = None,
+    resource_id: Optional[Union[str, TemplateString]] = None,
+    **params: Any,
+) -> CreateAnalysisParams:
+    """Create an analysis for a dataset, resource, or dataset-resource combination
+
+    Args:
+        analysis: analysis parameter
+        dataset_id: dataset_id parameter
+        resource_id: resource_id parameter
+
+    Returns:
+        CreateAnalysisParams: Type-safe parameter object
+    """
+    param_dict = {
+        "analysis": analysis,
+        "dataset_id": dataset_id,
+        "resource_id": resource_id,
+    }
+    # Remove None values for optional parameters
+    param_dict = {k: v for k, v in param_dict.items() if v is not None}
+    param_dict.update(params)
+    params_obj = CreateAnalysisParams(**param_dict)
+    return params_obj
+
+
+def analyze_csv(
+    file: Optional[Any] = None,
+    columns: Optional[Any] = None,
+    rows: Optional[Any] = None,
+    encryption_key: Optional[Union[str, TemplateString]] = None,
+    **params: Any,
+) -> AnalyzeCsvParams:
+    """Analyze CSV file using Go-based CSV analyzer (fast, no Python needed)
+
+    Args:
+        file: file parameter
+        columns: columns parameter
+        rows: rows parameter
+        encryption_key: encryption_key parameter
+
+    Returns:
+        AnalyzeCsvParams: Type-safe parameter object
+    """
+    param_dict = {
+        "file": file,
+        "columns": columns,
+        "rows": rows,
+        "encryption_key": encryption_key,
+    }
+    # Remove None values for optional parameters
+    param_dict = {k: v for k, v in param_dict.items() if v is not None}
+    param_dict.update(params)
+    params_obj = AnalyzeCsvParams(**param_dict)
+    return params_obj
+
+
+def analyze_excel(
+    file: Optional[Any] = None,
+    encryption_key: Optional[Union[str, TemplateString]] = None,
+    **params: Any,
+) -> AnalyzeExcelParams:
+    """Analyze Excel file using Go-based Excel analyzer (fast, no Python needed)
+
+    Args:
+        file: file parameter
+        encryption_key: encryption_key parameter
+
+    Returns:
+        AnalyzeExcelParams: Type-safe parameter object
+    """
+    param_dict = {
+        "file": file,
+        "encryption_key": encryption_key,
+    }
+    # Remove None values for optional parameters
+    param_dict = {k: v for k, v in param_dict.items() if v is not None}
+    param_dict.update(params)
+    params_obj = AnalyzeExcelParams(**param_dict)
+    return params_obj
+
+
+# Associate parameter classes with their result types
+CreateAnalysisParams._result = CreateAnalysisResult
+AnalyzeCsvParams._result = AnalyzeCsvResult
+AnalyzeExcelParams._result = AnalyzeExcelResult

{erdo-0.1.4 → erdo-0.1.6}/erdo/_generated/actions/bot.py

@@ -17,10 +17,50 @@ from erdo.template import TemplateString
 from erdo.types import StepMetadata
 
 
-class InvokeParams(BaseModel):
+class InvokeResult(BaseModel):
+    """Bot invoke result type
+
+    Result schema for bot.invoke action.
+    """
+
+    result: Any  # The bot invocation result
+    messages: list  # Messages from the bot invocation
+    resources: list  # Resources created/used during invocation
+    final_state: Any  # Final state after invocation
+
+
+class AskResult(BaseModel):
+    """Bot ask result type
+
+    Result schema for bot.ask action.
+    """
+
+    success: bool  # Whether the question was successfully processed
+    response: Optional[str] = None  # The bot's response to the question
+    bot_id: Optional[str] = None  # ID of the bot that answered
+    invocation_id: Optional[str] = None  # ID of the invocation
+    error: Optional[str] = None  # Error message if ask failed
+
+
+class BaseActionParams(BaseModel):
+    """Base class for all action parameter classes.
+
+    Provides common fields that all actions support:
+    - name: The action type identifier
+    - step_metadata: Optional configuration for the step created from this action
+    """
+
+    name: str
+    step_metadata: Optional[Any] = None
+
+
+class InvokeParams(BaseActionParams):
     """Invoke a bot with specified parameters and return the result parameters"""
 
     name: str = "bot.invoke"  # Action type for roundtrip compatibility
+    bot_key: Optional[Union[str, TemplateString]] = (
+        None  # bot_key parameter (unique bot identifier like "erdo.security-checker")
+    )
     bot_name: Optional[Union[str, TemplateString]] = (
         None  # bot_name parameter (backend expects this, not bot_id)
     )
@@ -38,7 +78,7 @@ class InvokeParams(BaseModel):
     )
 
 
-class AskParams(BaseModel):
+class AskParams(BaseActionParams):
     """Ask a bot a question and get a response parameters"""
 
     name: str = "bot.ask"  # Action type for roundtrip compatibility
@@ -51,6 +91,7 @@ class AskParams(BaseModel):
 
 
 def invoke(
+    bot_key: Optional[Union[str, TemplateString]] = None,
     bot_name: Optional[Union[str, TemplateString]] = None,
     parameters: Optional[Union[Dict[str, Any], TemplateString]] = None,
     bot_output_visibility_behaviour: Optional[Union[str, TemplateString]] = None,
@@ -61,11 +102,12 @@ def invoke(
 ) -> InvokeParams:
     """Invoke a bot with specified parameters and return the result
 
-    The bot.invoke action expects bot_name (not bot_id) as the parameter.
-    The backend will look up the bot by name and convert to bot_id internally.
+    The bot.invoke action expects bot_key or bot_name as the parameter.
+    The backend will look up the bot and convert to bot_id internally.
 
     Args:
-        bot_name: Name of the bot to invoke
+        bot_key: Unique key of the bot to invoke (e.g., "erdo.security-checker")
+        bot_name: Name of the bot to invoke (alternative to bot_key)
         parameters: Parameters to pass to the bot
         bot_output_visibility_behaviour: Output visibility behaviour
         transparent: Whether the invocation is transparent
@@ -75,6 +117,7 @@ def invoke(
         InvokeParams: Type-safe parameter object
     """
     params_dict = {
+        "bot_key": bot_key,
         "bot_name": bot_name,
         "parameters": parameters,
         "bot_output_visibility_behaviour": bot_output_visibility_behaviour,
@@ -86,6 +129,10 @@ def invoke(
     params_dict = {k: v for k, v in params_dict.items() if v is not None}
     params_dict.update(params)
 
+    # Include step_metadata in params_dict since it's a field on BaseActionParams
+    if step_metadata is not None:
+        params_dict["step_metadata"] = step_metadata
+
     # Use normal constructor for proper validation
     return InvokeParams(**params_dict)
 
@@ -120,5 +167,14 @@ def ask(
     params_dict = {k: v for k, v in params_dict.items() if v is not None}
     params_dict.update(params)
 
+    # Include step_metadata in params_dict since it's a field on BaseActionParams
+    if step_metadata is not None:
+        params_dict["step_metadata"] = step_metadata
+
     # Use normal constructor for proper validation
     return AskParams(**params_dict)
+
+
+# Associate parameter classes with their result types
+InvokeParams._result = InvokeResult
+AskParams._result = AskResult