openaction 0.0.13__py3-none-any.whl

api/http_service.py

@@ -0,0 +1,61 @@
+from abc import ABC, abstractmethod
+from typing import Any
+from requests import Response
+
+
+class HttpClient(ABC):
+    """
+    The HTTP client supports local serives like Shelly devices and external
+    services. Please ensure compliance with terms of use and privacy policies
+    for external requests.
+
+    This wrapper encapsulates communication with remote servers while managing
+    the connection lifecycle internally (e.g., session handling and pooling).
+
+    Note: Client instances are typically dedicated to specific tasks and are
+    not intended to be shared across concurrent executions to ensure isolation.
+    """
+
+    @abstractmethod
+    def request(self, method: str, url: str, **kwargs: Any) -> Response:
+        """
+        Sends a generic HTTP request.
+
+        Args:
+            method (str): The HTTP method (e.g., "GET", "POST", "PUT", "DELETE").
+            url (str): The target destination URL.
+            **kwargs (Any): Arguments passed to the underlying engine, such as
+                'headers', 'params', 'json', or 'timeout'.
+
+        Returns:
+            Response: A `requests.Response` object containing the server's reply.
+        """
+        pass
+
+    @abstractmethod
+    def get(self, url: str, **kwargs: Any) -> Response:
+        """
+        Sends an HTTP GET request. A convenience wrapper for request("GET", ...).
+
+        Args:
+            url (str): The target destination URL.
+            **kwargs (Any): Optional arguments like 'params' or 'headers'.
+
+        Returns:
+            Response: The server's response.
+        """
+        pass
+
+    @abstractmethod
+    def post(self, url: str, **kwargs: Any) -> Response:
+        """
+        Sends an HTTP POST request. A convenience wrapper for request("POST", ...).
+
+        Args:
+            url (str): The target destination URL.
+            **kwargs (Any): Optional arguments like 'json', 'data', or 'headers'.
+
+        Returns:
+            Response: The server's response.
+        """
+        pass

api/mcp_service.py

@@ -0,0 +1,68 @@
+from abc import ABC, abstractmethod
+from typing import Any, Optional
+
+from mcp import ListToolsResult
+from mcp.types import CallToolResult
+
+
+class MCPClient(ABC):
+    """
+    Abstract base class providing a standardized interface for Model Context Protocol (MCP) clients.
+
+    This wrapper encapsulates communication with connected MCP servers. Connection
+    lifecycle management is handled internally.
+
+    Note: Client instances are typically dedicated to specific tasks and are not
+    intended to be shared across concurrent executions.
+    """
+
+    @abstractmethod
+    def list_tools(self) -> ListToolsResult:
+        """
+        Retrieves the manifest of available tools from the connected MCP server.
+
+        Returns:
+            ListToolsResult: An object containing the tool definitions and their
+                             respective JSON Schema specifications.
+        """
+        pass
+
+    @abstractmethod
+    def call_tool(self, name: str, arguments: dict[str, Any] | None = None) -> CallToolResult:
+        """
+        Invokes a functional tool on the remote MCP server.
+
+        Args:
+            name (str): The unique identifier of the tool to execute.
+            arguments (dict[str, Any] | None, optional): Parameters for the tool,
+                matching its defined JSON Schema. Defaults to None.
+
+        Returns:
+            CallToolResult: The structured response from the server, including
+                            content (text/images) and success status.
+        """
+        pass
+
+
+
+class MCPClientRegistry(ABC):
+    """
+    Registry service for discovery and orchestration of multiple MCP clients.
+
+    Acts as a central access point for retrieving specific client instances
+    by their configured identifiers.
+    """
+
+    @abstractmethod
+    def get(self, name: str) -> Optional[MCPClient]:
+        """
+        Resolves and returns an MCPClient instance by its registration name.
+
+        Args:
+            name (str): The unique identifier of the target MCP client.
+
+        Returns:
+            Optional[MCPClient]: The requested client instance, or None if
+                                 no client is registered under that name.
+        """
+        pass

api/store_service.py

@@ -0,0 +1,59 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+class StoreService(ABC):
+    """
+    Key-value storage service.
+    """
+
+    @abstractmethod
+    def put(self, key: str, value: str, ttl_sec: int | None = None) -> None:
+        """
+        Store a value in the storage with the specified key. The amount of stored data
+        should not exceed 4 KB. All entries must be deleted. No data should be left behind.
+        The data is stored individually for each task.
+
+        Args:
+            key (str): The unique identifier for the stored value.
+            value (Any): The data to be stored.
+            ttl_sec (int | None, optional): Time-To-Live in seconds. If provided,
+                                            the key-value pair will expire and be
+                                            removed after this duration. Defaults to None.
+        """
+        pass
+
+    @abstractmethod
+    def get(self, key: str, default_value: str = None) -> str:
+        """
+        Retrieve a value from the storage using its key.
+
+        Args:
+            key (str): The unique identifier of the value to retrieve.
+            default_value (Any, optional): The value to return if the key is not found
+                                           in the storage. Defaults to None.
+
+        Returns:
+            Any: The stored value if the key exists, otherwise the default_value.
+        """
+        pass
+
+    @abstractmethod
+    def delete(self, key: str) -> None:
+        """
+        Remove a key-value pair from the storage.
+
+        Args:
+            key (str): The unique identifier of the value to be deleted.
+        """
+        pass
+
+
+    @abstractmethod
+    def keys(self) -> list[str]:
+        """
+        Retrieve a list of all keys currently stored.
+
+        Returns:
+            list[str]: A list of keys in the storage.
+        """
+        pass

cron.py

@@ -0,0 +1,153 @@
+import logging
+from concurrent.futures.thread import ThreadPoolExecutor
+from datetime import datetime, timedelta
+from threading import Thread
+from time import sleep
+from typing import Dict
+
+from task import CronTaskAdapter, TaskFactory
+from task_repository import TaskRepository
+
+
+logger = logging.getLogger(__name__)
+
+
+class CronService:
+
+    def __init__(self, task_repository : TaskRepository):
+        self._is_running = False
+        self._task_repository = task_repository
+        self._cron_cache: Dict[str, set[int]] = {}
+        self._executor = ThreadPoolExecutor(max_workers=20, thread_name_prefix="CronWorker")
+
+    def __str__(self):
+        return f"CronService(jobs={len(self._task_repository.tasks)})\n\r" + "\n\r".join([" * " + str(task) for task in self._task_repository.tasks])
+
+    def stop(self):
+        self._is_running = False
+        return self
+
+    def start(self):
+        self._is_running = True
+        Thread(target=self.__loop, daemon=True).start()
+
+    def __loop(self):
+        while self._is_running:
+            now = datetime.now()
+            run_key = (now.year, now.month, now.day, now.hour, now.minute)
+
+            for task in list(self._task_repository.tasks.values()):
+                try:
+                    if self._should_run(task, now, run_key):
+                        self._executor.submit(self._safe_run, task)
+                except Exception:
+                    logger.exception(f"Error triggering task: {task.name}")
+
+            next_tick = (datetime.now() + timedelta(seconds=1)).replace(microsecond=0)
+            sleep_time = (next_tick - datetime.now()).total_seconds()
+            sleep(sleep_time)
+
+    def _safe_run(self, task: CronTaskAdapter):
+        """Executes the task and ensures any unhandled exceptions are logged."""
+        try:
+            task.run()
+        except Exception as e:
+            logger.error(f"Execution failed for task '{task.name}': {e}")
+
+    def _should_run(self, task: CronTaskAdapter, now: datetime, run_key: tuple[int, int, int, int, int]) -> bool:
+        # If task failed recently, wait 1 minute before retrying
+        time_since_error = task.last_failure_age()
+        if time_since_error is not None:
+            if time_since_error < timedelta(minutes=1):
+                return False
+
+        # Check if already run in this minute or if cron expression matches
+        last_run = task.last_attempt_at()
+        if last_run is not None:
+            if (last_run.year, last_run.month, last_run.day, last_run.hour, last_run.minute) == run_key:
+                return False
+        return self._matches(task.cron_expression, now)
+
+    def _validate_cron_expression(self, expression: str) -> None:
+        fields = expression.split()
+        if len(fields) != 5:
+            raise ValueError(f"Invalid cron expression '{expression}'. Expected 5 fields.")
+
+        ranges = [
+            (0, 59),
+            (0, 23),
+            (1, 31),
+            (1, 12),
+            (0, 7),
+        ]
+        for field, (minimum, maximum) in zip(fields, ranges, strict=True):
+            self._parse_field(field, minimum, maximum)
+
+    def _matches(self, expression: str, now: datetime) -> bool:
+        """Splits the cron expression and evaluates each field."""
+        try:
+            minute, hour, day, month, weekday = expression.split()
+            cron_weekday = (now.weekday() + 1) % 7 # ISO (Mon=0) to Cron (Sun=0/7)
+
+            # Pass unique cache keys for each field type
+            return (
+                    self._matches_field(minute, now.minute, 0, 59, "m")
+                    and self._matches_field(hour, now.hour, 0, 23, "h")
+                    and self._matches_field(day, now.day, 1, 31, "d")
+                    and self._matches_field(month, now.month, 1, 12, "M")
+                    and self._matches_field(weekday, cron_weekday, 0, 7, "w")
+            )
+        except ValueError:
+            logger.error(f"Invalid cron expression encountered: {expression}")
+            return False
+
+    def _matches_field(self, field: str, value: int, minimum: int, maximum: int, cache_key_part: str) -> bool:
+        """
+        Checks a specific time field (e.g., 'minute') against its cron part.
+        Uses caching to avoid re-parsing identical expressions across tasks.
+        """
+        cache_key = f"{cache_key_part}:{field}:{minimum}:{maximum}"
+        if cache_key not in self._cron_cache:
+            self._cron_cache[cache_key] = self._parse_field(field, minimum, maximum)
+
+        allowed_values = self._cron_cache[cache_key]
+
+        # Special case for Sunday: support both 0 and 7.
+        if maximum == 7 and value == 0 and 7 in allowed_values:
+            return True
+        return value in allowed_values
+
+    def _parse_field(self, field: str, minimum: int, maximum: int) -> set[int]:
+        values: set[int] = set()
+
+        for part in field.split(","):
+            part = part.strip()
+            if not part:
+                raise ValueError("Empty cron field part")
+
+            if "/" in part:
+                base, step_text = part.split("/", 1)
+                step = int(step_text)
+                if step <= 0:
+                    raise ValueError(f"Invalid cron step '{part}'")
+            else:
+                base = part
+                step = 1
+
+            if base == "*":
+                start = minimum
+                end = maximum
+            elif "-" in base:
+                start_text, end_text = base.split("-", 1)
+                start = int(start_text)
+                end = int(end_text)
+            else:
+                start = int(base)
+                end = int(base)
+
+            if start < minimum or end > maximum or start > end:
+                raise ValueError(f"Cron value '{part}' out of range {minimum}-{maximum}")
+
+            values.update(range(start, end + 1, step))
+
+        return values

http_client.py

@@ -0,0 +1,63 @@
+import logging
+import requests
+from datetime import datetime, timedelta
+from typing import Any
+from requests import Response, Session
+
+from api.http_service import HttpClient
+
+class AutoRecreateHttpClient(HttpClient):
+    def __init__(self, ttl_minutes: int = 30) -> None:
+        self.ttl: timedelta = timedelta(minutes=ttl_minutes)
+        self.last_created: datetime | None = None
+        self.session: Session = self._create_session()
+
+    def _create_session(self) -> Session:
+        """Closes the old session (if any) and opens a new one."""
+        if hasattr(self, 'session') and self.session:
+            try:
+                self.session.close()
+            except Exception:
+                pass
+
+        session = requests.Session()
+        self.last_created = datetime.now()
+        logging.info("New http session created")
+        return session
+
+    def _is_expired(self) -> bool:
+        assert self.last_created is not None
+        return datetime.now() - self.last_created > self.ttl
+
+    def request(self, method: str, url: str, **kwargs: Any) -> Response:
+        # 1. Pre-check: Has the time expired?
+        if self._is_expired():
+            logging.info("TTL reached. Renewing session before request.")
+            self.session = self._create_session()
+
+        try:
+            # Execute request
+            response = self.session.request(method, url, **kwargs)
+
+            # Optional: On 401, also recreate the session for the next call
+            if response.status_code == 401:
+                logging.warning("Status 401: Session will be renewed for the next call.")
+                self.session = self._create_session()
+
+            return response
+
+        except Exception as e:
+            # 2. Error-check: Recreate immediately on exception
+            logging.exception("Exception caught: %s", e)
+            logging.info("Session will be re-initialized for the next attempt.")
+            self.session = self._create_session()
+
+            # Pass error directly (no retry)
+            raise e
+
+    # Shortcuts
+    def get(self, url: str, **kwargs: Any) -> Response:
+        return self.request('GET', url, **kwargs)
+
+    def post(self, url: str, **kwargs: Any) -> Response:
+        return self.request('POST', url, **kwargs)

mcp_client.py

@@ -0,0 +1,114 @@
+import asyncio
+import logging
+import threading
+from contextlib import AsyncExitStack
+from typing import Dict, Optional
+from mcp import ClientSession
+from mcp.client.sse import sse_client
+
+
+from api.mcp_service import MCPClientRegistry, MCPClient
+from services import MCP_SSE, ServiceRegistry
+
+logger = logging.getLogger(__name__)
+
+
+class SyncMCPClient(MCPClient):
+    """Synchronous MCP client communicating over HTTP/SSE transport."""
+
+    def __init__(self, url: str):
+        """
+        Args:
+            url: The HTTP SSE endpoint of the MCP server, e.g. 'http://host:port/sse'.
+        """
+        self.url = url
+        self._session = None
+        self._exit_stack = None
+        self._loop = asyncio.new_event_loop()
+        self._thread = threading.Thread(target=self._start_loop, daemon=True)
+        self._thread.start()
+
+    def _start_loop(self):
+        asyncio.set_event_loop(self._loop)
+        self._loop.run_forever()
+
+    def _run_sync(self, coroutine):
+        future = asyncio.run_coroutine_threadsafe(coroutine, self._loop)
+        return future.result()
+
+    async def _connect_async(self):
+        self._exit_stack = AsyncExitStack()
+
+        # Open HTTP/SSE transport to the MCP server
+        sse_transport = await self._exit_stack.enter_async_context(sse_client(self.url))
+        read, write = sse_transport
+
+        # Wrap transport in a ClientSession and perform MCP handshake
+        self._session = await self._exit_stack.enter_async_context(ClientSession(read, write))
+        await self._session.initialize()
+
+    def __connect(self):
+        self._run_sync(self._connect_async())
+
+
+    def __close(self):
+        if self._exit_stack:
+            self._run_sync(self._exit_stack.aclose())
+        self._loop.call_soon_threadsafe(lambda: self._loop.stop())
+        self._thread.join()
+
+
+    # ==========================================
+    # Public synchronous API
+    # ==========================================
+
+    def list_tools(self):
+        if not self._session:
+            self.__connect()
+        try:
+            return self._run_sync(self._session.list_tools())
+        except Exception as e:
+            self.__close()
+            raise e
+
+
+    def call_tool(self, name: str, arguments: dict = None):
+        if not self._session:
+            self.__connect()
+        try:
+            return self._run_sync(self._session.call_tool(name, arguments or {}))
+        except Exception as e:
+            self.__close()
+            raise e
+
+    def __repr__(self) -> str:
+        return f"SyncMCPClient(url='{self.url}')"
+
+
+class McpRegistry(MCPClientRegistry):
+
+    def __init__(self, service_registry: ServiceRegistry):
+        self._mcp: Dict[str, SyncMCPClient] = {}
+        self._service_registry = service_registry
+        self._service_registry.add_listener(self._refresh)
+        self._refresh()
+
+    def __del__(self):
+        self._service_registry.remove_listener(self._refresh)
+
+    def get(self, name: str) -> Optional[MCPClient]:
+        """Return the MCP client for the given name, or None."""
+        return self._mcp.get(name)
+
+    def clone(self):
+        return McpRegistry(self._service_registry)
+
+    def _refresh(self):
+        for name, conf in dict(self._service_registry.registered_services).items():
+            if conf.type == MCP_SSE:
+                if name not in self._mcp.keys():
+                    try:
+                        self._mcp[name] = SyncMCPClient(conf.url)
+                        logger.debug(f"{'auto scanned' if conf.auto_scanned else 'manually'} configured MCP server '{name}' added")
+                    except Exception as e:
+                        logger.warning(f"Error adding MCP server '{name}': {e}")

openaction-0.0.13.dist-info/METADATA

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: openaction
+Version: 0.0.13
+Summary: AI-driven framework for smart home automation
+Author: OpenAction Contributors
+License: Apache License 2.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: License :: OSI Approved :: Apache Software License
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: appdirs>=1.4.4
+Requires-Dist: mcp>=1.27.0
+Requires-Dist: zeroconf>=0.148.0
+Dynamic: license-file
+
+# OpenAction
+
+**OpenAction** is an AI-driven framework for smart home automation. It replaces static, manually created rules with dynamic scripts generated and managed by an Artificial Intelligence (LLM) based on natural language.
+
+## Core Features
+
+* **Natural Language Automation:** Create complex smart home automations through simple chat dialogues with an LLM (such as Claude).
+* **Sensors & Actuators:** All hardware devices provide their interfaces as independent MCP services.
+* **OpenAction Interface:** The framework itself acts as an MCP server. The AI uses provided tools to create and manage automations within the system.
+* **Dynamic Scheduling:** An integrated Cron service ensures the precise execution of AI-generated scripts.
+* **Persistent State:** Tasks have access to a persistent `Store` to save states across multiple executions.
+
+---
+
+## Architecture & Workflow
+
+The system is based on a decentralized architecture connected via the Model Context Protocol (MCP):
+
+1. **The Request:** The user describes an automation in a chat with the AI (e.g., Claude Desktop).
+2. **The Translation:** The AI analyzes the prompt, writes a Python script (including a cron rule and an execute function), and uses tools of the **OpenAction MCP Server** to store the script in the system.
+3. **The Scheduling:** OpenAction's local services monitor the schedules and trigger the tasks at the specified times.
+4. **The Execution:** During execution, the script calls the corresponding endpoints of the connected hardware MCP servers (e.g., switching lights, reading temperatures) via the `McpRegistry`.
+
+---

openaction-0.0.13.dist-info/RECORD

@@ -0,0 +1,17 @@
+cron.py,sha256=YfRnYm1e-mz0r0GJD4ZD0JefFQz7-a5k2M6tBXgf3bs,5861
+http_client.py,sha256=9tRQh7VnBxPrHcSw8v9Z_AqbYZxdxjrhPwiLijVk0CI,2264
+mcp_client.py,sha256=2xCFVYFOQ7Kew6-U_etHNGs4EC7wJHvBtnIuDoNcWuk,3699
+openaction.py,sha256=5f9tLrXsX4Vu8uxtJh-6uhWWwxTGLRIGuLSyAXSG-Gs,26833
+services.py,sha256=mkYHBJr40khJ8PinNfQ1Cu2CysyQKD5JBf-4pMxrGSQ,7530
+store.py,sha256=Du-pO8N0oJ-7sVk8AYoA3YRPKfdQQgm9vkGwKc-0v9g,7306
+task.py,sha256=6A5ItLjl7zL6OTb7QDhw16vmQ-1H6Z7zDhyzzwj0jG4,7369
+task_repository.py,sha256=krBNz2ofmYOvAU6UJNKFyO9-pd1FsNCCK2wyVUI8zmI,11098
+api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+api/http_service.py,sha256=Zkjl5l6Wj31sxUkZdF5njA6LFdPaHTxZuxtHlF1YNBU,1991
+api/mcp_service.py,sha256=2qtGtCUuSDbAZ3lWvqeBBgDBvd6somYOAV0LR1k7Eo8,2198
+api/store_service.py,sha256=Q3eaPEVQj1gRjctv2FgLDxeMD_w5j8g4lYn15KYxrcc,1867
+openaction-0.0.13.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+openaction-0.0.13.dist-info/METADATA,sha256=ci9wJdQ7o4GL7hKeWGCn4o35gBZL5-ZTBSqATFXYHV4,2170
+openaction-0.0.13.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+openaction-0.0.13.dist-info/top_level.txt,sha256=xabz_jrdTyRWtuia-vBgzW2IAKuu9c0akhf8qIa_hnk,79
+openaction-0.0.13.dist-info/RECORD,,

openaction-0.0.13.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+