genxai-framework 0.1.0__py3-none-any.whl

genxai/tools/templates.py

@@ -0,0 +1,435 @@
+"""Tool templates for quick tool creation."""
+
+from typing import Any, Dict, List
+import logging
+import httpx
+from genxai.tools.base import Tool, ToolMetadata, ToolParameter, ToolCategory
+
+logger = logging.getLogger(__name__)
+
+
+# Template definitions
+TEMPLATES = {
+    "api_call": {
+        "name": "API Call Tool",
+        "description": "Make HTTP requests to external APIs",
+        "parameters": ["url", "method", "headers", "body"],
+        "config_schema": {
+            "url": {"type": "string", "required": True, "description": "API endpoint URL"},
+            "method": {"type": "string", "required": True, "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"]},
+            "headers": {"type": "object", "required": False, "description": "HTTP headers"},
+            "timeout": {"type": "number", "required": False, "default": 30},
+        }
+    },
+    "text_processor": {
+        "name": "Text Processing Tool",
+        "description": "Process and transform text data",
+        "parameters": ["text", "operation"],
+        "config_schema": {
+            "operation": {
+                "type": "string", 
+                "required": True, 
+                "enum": ["uppercase", "lowercase", "reverse", "word_count", "char_count"]
+            }
+        }
+    },
+    "data_transformer": {
+        "name": "Data Transformation Tool",
+        "description": "Transform data between formats",
+        "parameters": ["data", "from_format", "to_format"],
+        "config_schema": {
+            "from_format": {"type": "string", "required": True, "enum": ["json", "csv", "xml"]},
+            "to_format": {"type": "string", "required": True, "enum": ["json", "csv", "xml"]},
+        }
+    },
+    "file_processor": {
+        "name": "File Processing Tool",
+        "description": "Read and process files",
+        "parameters": ["file_path", "operation"],
+        "config_schema": {
+            "operation": {"type": "string", "required": True, "enum": ["read", "write", "append", "delete"]},
+            "encoding": {"type": "string", "required": False, "default": "utf-8"},
+        }
+    },
+}
+
+
+class APICallTool(Tool):
+    """Template tool for making API calls."""
+
+    def __init__(
+        self,
+        name: str,
+        description: str,
+        category: ToolCategory,
+        tags: List[str],
+        config: Dict[str, Any]
+    ):
+        """Initialize API call tool."""
+        metadata = ToolMetadata(
+            name=name,
+            description=description,
+            category=category,
+            tags=tags + ["api", "http", "template"],
+        )
+
+        parameters = [
+            ToolParameter(
+                name="url",
+                type="string",
+                description="API endpoint URL (overrides default)",
+                required=False,
+            ),
+            ToolParameter(
+                name="params",
+                type="object",
+                description="Query parameters",
+                required=False,
+            ),
+            ToolParameter(
+                name="body",
+                type="object",
+                description="Request body (for POST/PUT/PATCH)",
+                required=False,
+            ),
+        ]
+
+        super().__init__(metadata, parameters)
+        self.config = config
+        self.default_url = config.get("url", "")
+        self.method = config.get("method", "GET").upper()
+        self.default_headers = config.get("headers", {})
+        self.timeout = config.get("timeout", 30)
+
+    async def _execute(self, **kwargs: Any) -> Any:
+        """Execute API call."""
+        url = kwargs.get("url", self.default_url)
+        params = kwargs.get("params", {})
+        body = kwargs.get("body", None)
+
+        if not url:
+            raise ValueError("URL is required")
+
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout) as client:
+                response = await client.request(
+                    method=self.method,
+                    url=url,
+                    params=params,
+                    json=body if body else None,
+                    headers=self.default_headers,
+                )
+                response.raise_for_status()
+
+                # Try to parse as JSON, fallback to text
+                try:
+                    data = response.json()
+                except Exception:
+                    data = response.text
+
+                return {
+                    "status_code": response.status_code,
+                    "data": data,
+                    "headers": dict(response.headers),
+                }
+
+        except httpx.HTTPError as e:
+            logger.error(f"API call failed: {e}")
+            raise RuntimeError(f"API call failed: {e}")
+
+
+class TextProcessorTool(Tool):
+    """Template tool for text processing."""
+
+    def __init__(
+        self,
+        name: str,
+        description: str,
+        category: ToolCategory,
+        tags: List[str],
+        config: Dict[str, Any]
+    ):
+        """Initialize text processor tool."""
+        metadata = ToolMetadata(
+            name=name,
+            description=description,
+            category=category,
+            tags=tags + ["text", "processing", "template"],
+        )
+
+        parameters = [
+            ToolParameter(
+                name="text",
+                type="string",
+                description="Text to process",
+                required=True,
+            ),
+            ToolParameter(
+                name="operation",
+                type="string",
+                description="Operation to perform",
+                required=False,
+                enum=["uppercase", "lowercase", "reverse", "word_count", "char_count"],
+            ),
+        ]
+
+        super().__init__(metadata, parameters)
+        self.config = config
+        self.default_operation = config.get("operation", "uppercase")
+
+    async def _execute(self, text: str, operation: str = None, **kwargs: Any) -> Any:
+        """Execute text processing."""
+        op = operation or self.default_operation
+
+        operations = {
+            "uppercase": lambda t: t.upper(),
+            "lowercase": lambda t: t.lower(),
+            "reverse": lambda t: t[::-1],
+            "word_count": lambda t: len(t.split()),
+            "char_count": lambda t: len(t),
+        }
+
+        if op not in operations:
+            raise ValueError(f"Unknown operation: {op}")
+
+        result = operations[op](text)
+
+        return {
+            "operation": op,
+            "input": text,
+            "result": result,
+        }
+
+
+class DataTransformerTool(Tool):
+    """Template tool for data transformation."""
+
+    def __init__(
+        self,
+        name: str,
+        description: str,
+        category: ToolCategory,
+        tags: List[str],
+        config: Dict[str, Any]
+    ):
+        """Initialize data transformer tool."""
+        metadata = ToolMetadata(
+            name=name,
+            description=description,
+            category=category,
+            tags=tags + ["data", "transformation", "template"],
+        )
+
+        parameters = [
+            ToolParameter(
+                name="data",
+                type="string",
+                description="Data to transform",
+                required=True,
+            ),
+            ToolParameter(
+                name="from_format",
+                type="string",
+                description="Source format",
+                required=False,
+                enum=["json", "csv", "xml"],
+            ),
+            ToolParameter(
+                name="to_format",
+                type="string",
+                description="Target format",
+                required=False,
+                enum=["json", "csv", "xml"],
+            ),
+        ]
+
+        super().__init__(metadata, parameters)
+        self.config = config
+        self.default_from = config.get("from_format", "json")
+        self.default_to = config.get("to_format", "json")
+
+    async def _execute(
+        self, 
+        data: str, 
+        from_format: str = None, 
+        to_format: str = None,
+        **kwargs: Any
+    ) -> Any:
+        """Execute data transformation."""
+        import json
+        import csv
+        import io
+
+        from_fmt = from_format or self.default_from
+        to_fmt = to_format or self.default_to
+
+        # Parse input
+        if from_fmt == "json":
+            parsed_data = json.loads(data)
+        elif from_fmt == "csv":
+            reader = csv.DictReader(io.StringIO(data))
+            parsed_data = list(reader)
+        else:
+            raise ValueError(f"Unsupported format: {from_fmt}")
+
+        # Convert output
+        if to_fmt == "json":
+            result = json.dumps(parsed_data, indent=2)
+        elif to_fmt == "csv":
+            if not isinstance(parsed_data, list):
+                parsed_data = [parsed_data]
+            
+            output = io.StringIO()
+            if parsed_data:
+                writer = csv.DictWriter(output, fieldnames=parsed_data[0].keys())
+                writer.writeheader()
+                writer.writerows(parsed_data)
+            result = output.getvalue()
+        else:
+            raise ValueError(f"Unsupported format: {to_fmt}")
+
+        return {
+            "from_format": from_fmt,
+            "to_format": to_fmt,
+            "result": result,
+        }
+
+
+class FileProcessorTool(Tool):
+    """Template tool for file processing."""
+
+    def __init__(
+        self,
+        name: str,
+        description: str,
+        category: ToolCategory,
+        tags: List[str],
+        config: Dict[str, Any]
+    ):
+        """Initialize file processor tool."""
+        metadata = ToolMetadata(
+            name=name,
+            description=description,
+            category=category,
+            tags=tags + ["file", "io", "template"],
+        )
+
+        parameters = [
+            ToolParameter(
+                name="file_path",
+                type="string",
+                description="Path to file",
+                required=True,
+            ),
+            ToolParameter(
+                name="operation",
+                type="string",
+                description="Operation to perform",
+                required=False,
+                enum=["read", "write", "append"],
+            ),
+            ToolParameter(
+                name="content",
+                type="string",
+                description="Content to write (for write/append operations)",
+                required=False,
+            ),
+        ]
+
+        super().__init__(metadata, parameters)
+        self.config = config
+        self.encoding = config.get("encoding", "utf-8")
+
+    async def _execute(
+        self,
+        file_path: str,
+        operation: str = "read",
+        content: str = None,
+        **kwargs: Any
+    ) -> Any:
+        """Execute file operation."""
+        import aiofiles
+        import os
+
+        try:
+            if operation == "read":
+                async with aiofiles.open(file_path, 'r', encoding=self.encoding) as f:
+                    data = await f.read()
+                return {"operation": "read", "file_path": file_path, "content": data}
+
+            elif operation == "write":
+                if content is None:
+                    raise ValueError("Content is required for write operation")
+                async with aiofiles.open(file_path, 'w', encoding=self.encoding) as f:
+                    await f.write(content)
+                return {"operation": "write", "file_path": file_path, "bytes_written": len(content)}
+
+            elif operation == "append":
+                if content is None:
+                    raise ValueError("Content is required for append operation")
+                async with aiofiles.open(file_path, 'a', encoding=self.encoding) as f:
+                    await f.write(content)
+                return {"operation": "append", "file_path": file_path, "bytes_written": len(content)}
+
+            else:
+                raise ValueError(f"Unknown operation: {operation}")
+
+        except Exception as e:
+            logger.error(f"File operation failed: {e}")
+            raise RuntimeError(f"File operation failed: {e}")
+
+
+def create_tool_from_template(
+    name: str,
+    description: str,
+    category: ToolCategory,
+    tags: List[str],
+    template: str,
+    config: Dict[str, Any]
+) -> Tool:
+    """Create a tool from a template.
+
+    Args:
+        name: Tool name
+        description: Tool description
+        category: Tool category
+        tags: Tool tags
+        template: Template name
+        config: Template configuration
+
+    Returns:
+        Tool instance
+
+    Raises:
+        ValueError: If template is unknown
+    """
+    template_classes = {
+        "api_call": APICallTool,
+        "text_processor": TextProcessorTool,
+        "data_transformer": DataTransformerTool,
+        "file_processor": FileProcessorTool,
+    }
+
+    if template not in template_classes:
+        raise ValueError(f"Unknown template: {template}")
+
+    tool_class = template_classes[template]
+    return tool_class(name, description, category, tags, config)
+
+
+def get_available_templates() -> List[Dict[str, Any]]:
+    """Get list of available templates.
+
+    Returns:
+        List of template definitions
+    """
+    return [
+        {
+            "id": template_id,
+            "name": template_data["name"],
+            "description": template_data["description"],
+            "parameters": template_data["parameters"],
+            "config_schema": template_data["config_schema"],
+        }
+        for template_id, template_data in TEMPLATES.items()
+    ]

genxai/triggers/__init__.py

@@ -0,0 +1,19 @@
+"""Trigger system for GenXAI workflows."""
+
+from genxai.triggers.base import BaseTrigger, TriggerEvent, TriggerStatus
+from genxai.triggers.registry import TriggerRegistry
+from genxai.triggers.webhook import WebhookTrigger
+from genxai.triggers.schedule import ScheduleTrigger
+from genxai.triggers.queue import QueueTrigger
+from genxai.triggers.file_watcher import FileWatcherTrigger
+
+__all__ = [
+    "BaseTrigger",
+    "TriggerEvent",
+    "TriggerStatus",
+    "TriggerRegistry",
+    "WebhookTrigger",
+    "ScheduleTrigger",
+    "FileWatcherTrigger",
+    "QueueTrigger",
+]

genxai/triggers/base.py

@@ -0,0 +1,104 @@
+"""Base trigger abstractions for GenXAI workflows."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any, Awaitable, Callable, Dict, Optional
+import asyncio
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class TriggerStatus(str, Enum):
+    """Lifecycle status for triggers."""
+
+    STOPPED = "stopped"
+    STARTING = "starting"
+    RUNNING = "running"
+    STOPPING = "stopping"
+    ERROR = "error"
+
+
+@dataclass
+class TriggerEvent:
+    """Event emitted by triggers to start workflows."""
+
+    trigger_id: str
+    payload: Dict[str, Any]
+    timestamp: datetime = field(default_factory=datetime.utcnow)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+class BaseTrigger(ABC):
+    """Abstract base class for workflow triggers."""
+
+    def __init__(self, trigger_id: str, name: Optional[str] = None) -> None:
+        self.trigger_id = trigger_id
+        self.name = name or trigger_id
+        self.status: TriggerStatus = TriggerStatus.STOPPED
+        self._callbacks: list[Callable[[TriggerEvent], Awaitable[None]]] = []
+        self._lock = asyncio.Lock()
+
+    def on_event(self, callback: Callable[[TriggerEvent], Awaitable[None]]) -> None:
+        """Register a callback to receive trigger events."""
+        self._callbacks.append(callback)
+
+    async def emit(self, payload: Dict[str, Any], metadata: Optional[Dict[str, Any]] = None) -> None:
+        """Emit a trigger event to registered callbacks."""
+        event = TriggerEvent(
+            trigger_id=self.trigger_id,
+            payload=payload,
+            metadata=metadata or {},
+        )
+        if not self._callbacks:
+            logger.warning("Trigger %s emitted event with no subscribers", self.trigger_id)
+            return
+
+        await asyncio.gather(*[callback(event) for callback in self._callbacks])
+
+    async def start(self) -> None:
+        """Start the trigger."""
+        async with self._lock:
+            if self.status in {TriggerStatus.RUNNING, TriggerStatus.STARTING}:
+                return
+            self.status = TriggerStatus.STARTING
+            try:
+                await self._start()
+                self.status = TriggerStatus.RUNNING
+                logger.info("Trigger started: %s", self.trigger_id)
+            except Exception as exc:
+                self.status = TriggerStatus.ERROR
+                logger.error("Failed to start trigger %s: %s", self.trigger_id, exc)
+                raise
+
+    async def stop(self) -> None:
+        """Stop the trigger."""
+        async with self._lock:
+            if self.status in {TriggerStatus.STOPPED, TriggerStatus.STOPPING}:
+                return
+            self.status = TriggerStatus.STOPPING
+            try:
+                await self._stop()
+                self.status = TriggerStatus.STOPPED
+                logger.info("Trigger stopped: %s", self.trigger_id)
+            except Exception as exc:
+                self.status = TriggerStatus.ERROR
+                logger.error("Failed to stop trigger %s: %s", self.trigger_id, exc)
+                raise
+
+    @abstractmethod
+    async def _start(self) -> None:
+        """Implement trigger-specific start logic."""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def _stop(self) -> None:
+        """Implement trigger-specific stop logic."""
+        raise NotImplementedError
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(id={self.trigger_id}, status={self.status})"

genxai/triggers/file_watcher.py

@@ -0,0 +1,75 @@
+"""File watcher trigger implementation."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, Optional
+import logging
+
+from genxai.triggers.base import BaseTrigger
+
+logger = logging.getLogger(__name__)
+
+
+class FileWatcherTrigger(BaseTrigger):
+    """Trigger that emits events on filesystem changes.
+
+    Requires `watchdog` to be installed.
+    """
+
+    def __init__(
+        self,
+        trigger_id: str,
+        watch_path: str | Path,
+        recursive: bool = True,
+        name: Optional[str] = None,
+    ) -> None:
+        super().__init__(trigger_id=trigger_id, name=name)
+        self.watch_path = Path(watch_path)
+        self.recursive = recursive
+        self._observer = None
+
+    async def _start(self) -> None:
+        try:
+            from watchdog.observers import Observer
+            from watchdog.events import FileSystemEventHandler
+        except ImportError as exc:
+            raise ImportError(
+                "watchdog is required for FileWatcherTrigger. Install with: pip install watchdog"
+            ) from exc
+
+        class _Handler(FileSystemEventHandler):
+            def __init__(self, outer: "FileWatcherTrigger") -> None:
+                self.outer = outer
+
+            def on_any_event(self, event):
+                payload: Dict[str, Any] = {
+                    "event_type": event.event_type,
+                    "src_path": event.src_path,
+                    "is_directory": event.is_directory,
+                }
+                if getattr(event, "dest_path", None):
+                    payload["dest_path"] = event.dest_path
+                try:
+                    import asyncio
+
+                    asyncio.run_coroutine_threadsafe(
+                        self.outer.emit(payload=payload),
+                        asyncio.get_event_loop(),
+                    )
+                except Exception as exc:
+                    logger.error("Failed to emit file event: %s", exc)
+
+        handler = _Handler(self)
+        observer = Observer()
+        observer.schedule(handler, str(self.watch_path), recursive=self.recursive)
+        observer.start()
+        self._observer = observer
+        logger.info("FileWatcherTrigger %s started", self.trigger_id)
+
+    async def _stop(self) -> None:
+        if self._observer:
+            self._observer.stop()
+            self._observer.join(timeout=5)
+            self._observer = None
+        logger.info("FileWatcherTrigger %s stopped", self.trigger_id)

genxai/triggers/queue.py

@@ -0,0 +1,68 @@
+"""Queue-based trigger implementation."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+import asyncio
+import logging
+
+from genxai.triggers.base import BaseTrigger
+
+logger = logging.getLogger(__name__)
+
+
+class QueueTrigger(BaseTrigger):
+    """Async queue trigger.
+
+    This trigger listens to an asyncio.Queue instance. It can be swapped
+    for custom queue backends by feeding messages into the queue.
+    """
+
+    def __init__(
+        self,
+        trigger_id: str,
+        queue: Optional[asyncio.Queue] = None,
+        name: Optional[str] = None,
+        poll_interval: float = 0.1,
+    ) -> None:
+        super().__init__(trigger_id=trigger_id, name=name)
+        self.queue = queue or asyncio.Queue()
+        self.poll_interval = poll_interval
+        self._task: Optional[asyncio.Task] = None
+
+    async def _start(self) -> None:
+        self._task = asyncio.create_task(self._listen())
+        logger.info("QueueTrigger %s started", self.trigger_id)
+
+    async def _stop(self) -> None:
+        if self._task:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+            self._task = None
+        logger.info("QueueTrigger %s stopped", self.trigger_id)
+
+    async def _listen(self) -> None:
+        while True:
+            try:
+                message = await asyncio.wait_for(self.queue.get(), timeout=self.poll_interval)
+                payload: Dict[str, Any]
+                if isinstance(message, dict):
+                    payload = message
+                else:
+                    payload = {"message": message}
+                await self.emit(payload=payload)
+                self.queue.task_done()
+            except asyncio.TimeoutError:
+                continue
+            except asyncio.CancelledError:
+                break
+            except Exception as exc:
+                logger.error("QueueTrigger %s error: %s", self.trigger_id, exc)
+                await asyncio.sleep(self.poll_interval)
+
+    async def enqueue(self, payload: Dict[str, Any]) -> None:
+        """Helper to push payloads into the trigger queue."""
+        await self.queue.put(payload)