[feat]: Add python agent toolkit (#18)

* feat: initial commit for python sdk

* fix: updated readme and package, and tested happy flow for send message

* feat:update schemas and fix import errors

* fix: update schema type hints and add default factory for input_data field

* fix: resolve Pydantic validation errors in CrewAI tool wrapper and add default factory for notify field

* docs: expand README documentation and improve code examples

* refactor: rename package from siren_agent_toolkit to agenttoolkit and reorganize files

* refactor: move example docs to dedicated README and remove comment headers in code

---------

Co-authored-by: joobi-keyvalue <[email protected]>
Co-authored-by: aavani-kv <[email protected]>

Author: 3 people

python/.gitignore

@@ -0,0 +1,146 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# pdm
+.pdm.toml
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+.idea/
+
+# VS Code
+.vscode/
+
+# OS
+.DS_Store
+Thumbs.db

python/README.md

@@ -0,0 +1,107 @@
+# Siren Agent Toolkit (Python)
+
+The **Siren Agent Toolkit** provides a unified Python interface and agent tools for interacting with the Siren MCP (Model Context Protocol) platform. It enables messaging, template management, user management, workflow automation, and webhook configuration, with seamless integration into popular agent frameworks like LangChain, OpenAI, and CrewAI.
+
+## Features & Capabilities
+
+### Messaging
+- Send messages via various channels (Email, SMS, WhatsApp, Slack, Teams, Discord, Line, etc.)
+- Retrieve message status and replies
+- Support for template-based and direct messaging
+
+### Templates
+- List, create, update, delete, and publish notification templates
+- Create and manage channel-specific templates
+- Support for template variables and versioning
+
+### Users
+- Add, update, and delete users
+- Manage user attributes and contact information
+
+### Workflows
+- Trigger workflows (single or bulk operations)
+- Schedule workflows for future or recurring execution
+- Pass custom data to workflow executions
+
+### Webhooks
+- Configure webhooks for status updates
+- Set up inbound message webhooks
+- Optional webhook verification with secrets
+
+## 📋 Requirements
+
+- A Siren API key (get one from [Siren Dashboard](https://app.trysiren.io/configuration))
+
+## Installation
+
+```bash
+pip install siren-agent-toolkit
+```
+
+For local development:
+
+```bash
+# From the python/ directory
+pip install -e .
+```
+
+## Usage
+
+### Basic Example
+
+```python
+from siren_agent_toolkit.api import SirenAPI
+
+# Initialize with your API key
+api = SirenAPI(api_key="YOUR_API_KEY")
+
+# Send a simple email message
+result = api.run("send_message", {
+    "recipient_value": "[email protected]",
+    "channel": "EMAIL",
+    "subject": "Important Update",
+    "body": "Hello from Siren! This is an important notification."
+})
+print(result)
+```
+
+## Examples
+
+Complete working examples are available in the `examples/` directory:
+
+- `examples/langchain/main.py` — Using Siren tools with LangChain
+- `examples/openai/main.py` — Using Siren tools with OpenAI
+- `examples/crewai/main.py` — Using Siren tools with CrewAI
+
+## Development
+
+### Configuration
+
+The toolkit supports flexible configuration options:
+
+```python
+from siren_agent_toolkit.api import SirenAPI
+
+api = SirenAPI(
+    api_key="YOUR_API_KEY",
+    context={"env": "production"}  # Optional environment configuration
+)
+```
+
+### Building Locally
+
+```bash
+# From the python/ directory
+pip install -e .
+# Install development dependencies
+pip install -r requirements.txt
+```
+
+### Running Tests
+
+```bash
+pytest tests/
+```
+## License
+
+MIT

python/agenttoolkit/__init__.py

@@ -0,0 +1,16 @@
+"""Siren Agent Toolkit for Python."""
+
+from .api import SirenAPI
+from .configuration import Configuration, Context, Actions, is_tool_allowed
+from .tools import tools
+from .schema import *
+
+__version__ = "1.0.0"
+__all__ = [
+    "SirenAPI",
+    "Configuration", 
+    "Context",
+    "Actions",
+    "is_tool_allowed",
+    "tools",
+]

python/agenttoolkit/api.py

@@ -0,0 +1,70 @@
+from typing import Any, Dict, Optional
+from siren import SirenClient
+from .configuration import Context
+
+
+class SirenAPI:
+    """API wrapper that integrates with the Siren Python SDK."""
+    
+    def __init__(self, api_key: str, context: Optional[Context] = None):
+        self.client = SirenClient(
+            api_key=api_key,
+            env=context.get("env") if context else None,
+        )
+
+    def run(self, method: str, params: Dict[str, Any]) -> Any:
+        """Execute a method on the Siren client with the given parameters."""
+        
+        if method == "send_message":
+            return self.client.message.send(**params)
+        elif method == "get_message_status":
+            return self.client.message.get_status(params["message_id"])
+        elif method == "get_message_replies":
+            return self.client.message.get_replies(params["message_id"])
+        
+        elif method == "list_templates":
+            return self.client.template.get(**params)
+        elif method == "create_template":
+            return self.client.template.create(**params)
+        elif method == "update_template":
+            template_id = params.pop("template_id")
+            return self.client.template.update(template_id, **params)
+        elif method == "delete_template":
+            return self.client.template.delete(params["template_id"])
+        elif method == "publish_template":
+            return self.client.template.publish(params["template_id"])
+        elif method == "create_channel_templates":
+            template_id = params.pop("template_id")
+            return self.client.template.create_channel_templates(template_id, **params)
+        elif method == "get_channel_templates":
+            version_id = params.pop("version_id") 
+            return self.client.template.get_channel_templates(version_id, **params)
+        
+        elif method == "add_user":
+            return self.client.user.add(**params)
+        elif method == "update_user":
+            unique_id = params.pop("unique_id")
+            return self.client.user.update(unique_id, **params)
+        elif method == "delete_user":
+            return self.client.user.delete(params["unique_id"])
+        elif method == "get_user":
+            raise NotImplementedError("get_user is not implemented")
+            #return self.client.user.get(params["unique_id"])
+        elif method == "list_users":
+            raise NotImplementedError("list_users is not implemented")
+            #return self.client.user.list(**params)
+        
+        elif method == "trigger_workflow":
+            return self.client.workflow.trigger(**params)
+        elif method == "trigger_workflow_bulk":
+            return self.client.workflow.trigger_bulk(**params)
+        elif method == "schedule_workflow":
+            return self.client.workflow.schedule(**params)
+        
+        elif method == "configure_notification_webhooks":
+            return self.client.webhook.configure_notifications(**params)
+        elif method == "configure_inbound_webhooks":
+            return self.client.webhook.configure_inbound(**params)
+        
+        else:
+            raise ValueError(f"Unknown method: {method}")

python/agenttoolkit/configuration.py

@@ -0,0 +1,46 @@
+from typing import Dict, List, Literal, Optional, TypedDict
+
+
+Object = Literal[
+    "messaging",
+    "templates", 
+    "users",
+    "workflows",
+    "webhooks",
+]
+
+Permission = Literal["create", "update", "read", "delete", "trigger", "schedule"]
+
+
+class Actions(TypedDict, total=False):
+    messaging: Optional[Dict[Permission, bool]]
+    templates: Optional[Dict[Permission, bool]]
+    users: Optional[Dict[Permission, bool]]
+    workflows: Optional[Dict[Permission, bool]]
+    webhooks: Optional[Dict[Permission, bool]]
+
+
+class Context(TypedDict, total=False):
+    env: Optional[Literal["dev", "prod"]]
+    api_key: Optional[str]
+    base_url: Optional[str]
+    timeout: Optional[int]
+
+
+class Configuration(TypedDict, total=False):
+    actions: Optional[Actions]
+    context: Optional[Context]
+
+
+def is_tool_allowed(tool: Dict, configuration: Optional[Configuration] = None) -> bool:
+    """Check if a tool is allowed based on configuration permissions."""
+    if not configuration or not configuration.get("actions"):
+        return True  # Allow all tools if no configuration is provided
+
+    for resource, permissions in tool.get("actions", {}).items():
+        if resource not in configuration["actions"]:
+            return False
+        for permission in permissions:
+            if not configuration["actions"].get(resource, {}).get(permission, False):
+                return False
+    return True