nexgenpy 1.0.0__py3-none-any.whl

nexgenpy/__init__.py

@@ -0,0 +1,2 @@
+from .actuators import actuator
+from .manager import Actuator, load_actuator, run_actuator

nexgenpy/actuators.py

@@ -0,0 +1,185 @@
+"""# Actuators.
+
+It contains the decorators for the actuators.
+"""
+
+import ast
+import inspect
+import logging
+import os
+import textwrap
+from functools import wraps
+from typing import Any, Callable, Dict, List, Literal, get_type_hints
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_BASE_URL = "http://localhost:8000/api/v1"
+DEFAULT_TIMEOUT = 60
+
+
+def _function_source(func: Callable[..., Any]) -> str:
+    """# Function Source.
+
+    It returns the source code of the function without its decorators, so the
+    downloaded method.py does not need to import them.
+
+    Args:
+        func (Callable[..., Any]): The decorated function.
+
+    Returns:
+        str: The source code that starts at the `def` line.
+    """
+    source = textwrap.dedent(inspect.getsource(func))
+    node = ast.parse(source).body[0]
+    lines = source.splitlines(keepends=True)
+    return "".join(lines[node.lineno - 1 :])
+
+
+def _request_timeout() -> float:
+    """# Request Timeout.
+
+    Returns:
+        float: The value of NEXGEN_TIMEOUT, or the default if it is not valid.
+    """
+    raw_timeout = os.getenv("NEXGEN_TIMEOUT")
+    if raw_timeout is None:
+        return DEFAULT_TIMEOUT
+
+    try:
+        timeout = float(raw_timeout)
+    except ValueError:
+        timeout = 0
+
+    if timeout <= 0:
+        logger.warning(
+            "NEXGEN_TIMEOUT is invalid: %r, using %d",
+            raw_timeout,
+            DEFAULT_TIMEOUT,
+        )
+        return DEFAULT_TIMEOUT
+
+    return timeout
+
+
+def actuator(
+    name: str,
+    atype: Literal["coding", "decoding"],
+    version: str,
+    is_latest: bool,
+    requirements: List[str] | None,
+) -> Callable[[Callable[..., Any]], Callable[..., bool]]:
+    """# Actuator.
+
+    It holds the information for the actuator. A call to the decorated function
+    publishes the actuator to the Nexgen API.
+
+    Args:
+        name (str): Name of the actuator.
+        atype (Literal["coding", "decoding"]): Type of the actuator.
+        version (str): Version of the actuator.
+        is_latest (bool): If it is true, the server marks this version as latest.
+        requirements (List[str] | None): Pip requirements of the actuator.
+
+    Returns:
+        Callable[[Callable[..., Any]], Callable[..., bool]]: The decorator.
+    """
+    # Checking The Datatypes
+    if isinstance(name, str) is False:
+        logger.error("name is invalid, it has to be str")
+        raise ValueError("name is invalid, it has to be str")
+
+    if atype not in ["coding", "decoding"]:
+        logger.error("atype is invalid, it has to be either coding or decoding")
+        raise ValueError("atype is invalid, it has to be either coding or decoding")
+
+    if isinstance(version, str) is False:
+        logger.error("version is invalid, it has to be str")
+        raise ValueError("version is invalid, it has to be str")
+
+    if isinstance(is_latest, bool) is False:
+        logger.error("is_latest is invalid, it has to be bool")
+        raise ValueError("is_latest is invalid, it has to be bool")
+
+    if requirements is not None and (
+        isinstance(requirements, list) is False
+        or all(isinstance(r, str) for r in requirements) is False
+    ):
+        logger.error("requirements is invalid, it has to be List[str]")
+        raise ValueError("requirements is invalid, it has to be List[str]")
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., bool]:
+        """# Decorator Method."""
+        signature = inspect.signature(func)
+        type_hints = get_type_hints(func)
+
+        arguments: Dict[str, Dict[str, str]] = {}
+
+        # The server accepts only str values, so missing info is left out
+        for parameter_name, parameter in signature.parameters.items():
+            annotation = type_hints.get(parameter_name)
+            argument: Dict[str, str] = {}
+
+            if annotation is not None:
+                argument["type"] = str(annotation)
+
+            if parameter.default is not inspect.Parameter.empty:
+                argument["default"] = str(parameter.default)
+
+            arguments[parameter_name] = argument
+
+        sample: Dict[str, Any] = {
+            "name": name,
+            "version": version,
+            "actuator_type": atype,
+            "set_latest": is_latest,
+            "requirements": requirements if requirements is not None else [],
+            "method": _function_source(func),
+            "method_args": arguments,
+        }
+
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> bool:  # noqa: ANN401, ARG001
+            """# Wrapper Method.
+
+            Returns:
+                bool: True if the server accepted the actuator, else False.
+            """
+            base_url = os.getenv("NEXGEN_BASE_URL", DEFAULT_BASE_URL)
+
+            api_key = os.getenv("NEXGEN_API_KEY")
+            headers: Dict[str, str] = {}
+
+            if api_key is not None:
+                headers["X-API-KEY"] = api_key
+
+            try:
+                result = requests.post(
+                    f"{base_url}/actuators",
+                    headers=headers,
+                    json=sample,
+                    timeout=_request_timeout(),
+                )
+            except requests.RequestException as e:
+                logger.warning("POST /actuators failed: %s", e)
+                return False
+
+            if result.ok is True:
+                logger.info(
+                    "POST /actuators succeeded: status=%d, response=%s",
+                    result.status_code,
+                    result.text,
+                )
+                return True
+
+            logger.warning(
+                "POST /actuators failed: status=%d, response=%s",
+                result.status_code,
+                result.text,
+            )
+            return False
+
+        return wrapper
+
+    return decorator

nexgenpy/manager.py

@@ -0,0 +1,644 @@
+"""# Manager.
+
+It manages the essential works for the actuators.
+"""
+
+import asyncio
+import importlib.util
+import inspect
+import json
+import logging
+import os
+import shutil
+import subprocess
+import sys
+import threading
+from pathlib import Path
+from typing import Any, Dict
+from uuid import uuid4
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_BASE_URL = "http://localhost:8000/api/v1"
+
+
+class Actuator:
+    """# Actuator.
+
+    It runs the actuator like run_actuator. It loads the method only once, in the
+    constructor, so the next runs do not import method.py again.
+
+    Attributes:
+        name (str): Name of the actuator.
+        actuators_dir (str): Located directory for the actuators.
+        dst (str | None): It pushes the data given endpoint if they have an
+            nexgen compatible endpoint.
+        dst_timeout (int): Timeout for the sending destination endpoint.
+        dst_headers (Dict[str, Any]): Required headers for the destination
+            endpoint.
+        dst_save_original (bool): It saves the original data too with lazy upload.
+        actuator_id (str | None): The server id of the actuator. It is None if dst
+            is None.
+        method (Callable[..., Any]): The function inside method.py.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        actuators_dir: str = "nexgen_actuators",
+        dst: str | None = None,
+        dst_timeout: int = 60,
+        dst_headers: Dict[str, Any] | None = None,
+        dst_save_original: bool = True,
+        try_load_actuator: bool = True,
+    ) -> None:
+        # Checking The Datatypes
+        if isinstance(name, str) is False:
+            logger.error("name is invalid, it has to be str")
+            raise ValueError("name is invalid, it has to be str")
+
+        if isinstance(actuators_dir, str) is False:
+            logger.error("actuators_dir is invalid, it has to be str")
+            raise ValueError("actuators_dir is invalid, it has to be str")
+
+        if dst is not None and isinstance(dst, str) is False:
+            logger.error("dst is invalid, it has to be str")
+            raise ValueError("dst is invalid, it has to be str")
+
+        if isinstance(dst_timeout, int) is False:
+            logger.error("dst_timeout is invalid, it has to be int")
+            raise ValueError("dst_timeout is invalid, it has to be int")
+
+        if dst_headers is not None and isinstance(dst_headers, dict) is False:
+            logger.error("dst_headers is invalid, it has to be Dict[str, Any]")
+            raise ValueError("dst_headers is invalid, it has to be Dict[str, Any]")
+
+        if isinstance(dst_save_original, bool) is False:
+            logger.error("dst_save_original is invalid, it has to be bool")
+            raise ValueError("dst_save_original is invalid, it has to be bool")
+
+        if isinstance(try_load_actuator, bool) is False:
+            logger.error("try_load_actuator is invalid, it has to be bool")
+            raise ValueError("try_load_actuator is invalid, it has to be bool")
+
+        if Path(f"{actuators_dir}/{name}").exists() is False:
+            logger.warning(f"Actuator: {name} does not exist")
+            if try_load_actuator is False:
+                logger.error(f"Actuator {name} has to be downloaded first")
+                raise ValueError(f"Actuator {name} has to be downloaded first")
+            else:
+                load_actuator(
+                    name=name,
+                    actuators_dir=actuators_dir,
+                )
+
+        file_path = Path(f"{actuators_dir}/{name}/method.py").resolve()
+
+        spec = importlib.util.spec_from_file_location(
+            file_path.stem,
+            file_path,
+        )
+
+        if spec is None or spec.loader is None:
+            raise ImportError(f"Cannot load module: {file_path}")
+
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+
+        # Find functions defined in this file
+        methods = [
+            obj
+            for _, obj in inspect.getmembers(module, inspect.isfunction)
+            if obj.__module__ == module.__name__
+        ]
+
+        if len(methods) != 1:
+            raise ValueError(
+                f"Expected exactly one function, found {len(methods)}",
+            )
+
+        actuator_id = None
+        if dst is not None:
+            with open(f"{actuators_dir}/{name}/card.json", "r") as f:
+                actuator_id = json.load(f)["id"]
+
+        self.name = name
+        self.actuators_dir = actuators_dir
+        self.dst = dst
+        self.dst_timeout = dst_timeout
+        self.dst_headers = dst_headers if dst_headers is not None else {}
+        self.dst_save_original = dst_save_original
+        self.actuator_id = actuator_id
+        self.method = methods[0]
+
+    def run(
+        self,
+        data: Dict[str, Any],
+        data_specs: Dict[str, Any] | None = None,
+    ) -> object:
+        """# Run.
+
+        It runs the loaded method with the data. If dst is given, it also sends
+        the output to the destination endpoint.
+
+        Args:
+            data (Dict[str, Any]): Input data for the actuator.
+            data_specs (Dict[str, Any] | None, optional): Contains the extra
+                information about the data.
+
+        Returns:
+            object: The output coming from actuator.
+
+        Raises:
+            ValueError: If data or data_specs is invalid.
+        """
+        # Checking The Datatypes
+        if isinstance(data, dict) is False:
+            logger.error("data is invalid, it has to be Dict[str, Any]")
+            raise ValueError("data is invalid, it has to be Dict[str, Any]")
+
+        if data_specs is not None and isinstance(data_specs, dict) is False:
+            logger.error("data_specs is invalid, it has to be Dict[str, Any]")
+            raise ValueError("data_specs is invalid, it has to be Dict[str, Any]")
+
+        output = self.method(**data)
+
+        if self.dst is None:
+            return output
+
+        linked_resource: str | None = None
+        if self.dst_save_original is True:
+            linked_resource = str(uuid4())
+
+            # Lazy upload, so the main process does not wait for it
+            threading.Thread(
+                target=_send_content,
+                kwargs={
+                    "url": f"{self.dst}/contents",
+                    "headers": self.dst_headers,
+                    "timeout": self.dst_timeout,
+                    "identifier": linked_resource,
+                    "specs": data,
+                },
+            ).start()
+
+        result = requests.post(
+            url=f"{self.dst}/data",
+            headers=self.dst_headers,
+            json={
+                "actuator_id": self.actuator_id,
+                "metadata": output,
+                "linked_resource": linked_resource,
+                "specs": data_specs,
+            },
+            timeout=self.dst_timeout,
+        )
+
+        if result.ok is True:
+            logger.info(
+                "POST /data succeeded: status=%d, response=%s",
+                result.status_code,
+                result.text,
+            )
+        else:
+            logger.warning(
+                "POST /data failed: status=%d, response=%s",
+                result.status_code,
+                result.text,
+            )
+
+        return output
+
+    async def arun(
+        self,
+        data: Dict[str, Any],
+        data_specs: Dict[str, Any] | None = None,
+    ) -> object:
+        """# Async Run.
+
+        It is the async version of run. It runs the loaded method and the POST
+        /data request in a worker thread, so they do not block the event loop.
+
+        Args:
+            data (Dict[str, Any]): Input data for the actuator.
+            data_specs (Dict[str, Any] | None, optional): Contains the extra
+                information about the data.
+
+        Returns:
+            object: The output coming from actuator.
+
+        Raises:
+            ValueError: If data or data_specs is invalid.
+        """
+        # Checking The Datatypes
+        if isinstance(data, dict) is False:
+            logger.error("data is invalid, it has to be Dict[str, Any]")
+            raise ValueError("data is invalid, it has to be Dict[str, Any]")
+
+        if data_specs is not None and isinstance(data_specs, dict) is False:
+            logger.error("data_specs is invalid, it has to be Dict[str, Any]")
+            raise ValueError("data_specs is invalid, it has to be Dict[str, Any]")
+
+        output = await asyncio.to_thread(self.method, **data)
+
+        if self.dst is None:
+            return output
+
+        linked_resource: str | None = None
+        if self.dst_save_original is True:
+            linked_resource = str(uuid4())
+
+            # Lazy upload, so the main process does not wait for it
+            threading.Thread(
+                target=_send_content,
+                kwargs={
+                    "url": f"{self.dst}/contents",
+                    "headers": self.dst_headers,
+                    "timeout": self.dst_timeout,
+                    "identifier": linked_resource,
+                    "specs": data,
+                },
+            ).start()
+
+        result = await asyncio.to_thread(
+            requests.post,
+            url=f"{self.dst}/data",
+            headers=self.dst_headers,
+            json={
+                "actuator_id": self.actuator_id,
+                "metadata": output,
+                "linked_resource": linked_resource,
+                "specs": data_specs,
+            },
+            timeout=self.dst_timeout,
+        )
+
+        if result.ok is True:
+            logger.info(
+                "POST /data succeeded: status=%d, response=%s",
+                result.status_code,
+                result.text,
+            )
+        else:
+            logger.warning(
+                "POST /data failed: status=%d, response=%s",
+                result.status_code,
+                result.text,
+            )
+
+        return output
+
+
+def _send_content(
+    url: str,
+    headers: Dict[str, Any],
+    timeout: int,
+    identifier: str,
+    specs: Dict[str, Any],
+) -> None:
+    """# Send Content.
+
+    It sends the original data to the content endpoint. It runs in a background
+    thread, so it logs the errors and does not raise them.
+
+    Args:
+        url (str): The content endpoint.
+        headers (Dict[str, Any]): Headers for the content endpoint.
+        timeout (int): Timeout for the content endpoint.
+        identifier (str): The linked resource of the data.
+        specs (Dict[str, Any]): The original data.
+    """
+    try:
+        result = requests.post(
+            url=url,
+            headers=headers,
+            json={
+                "identifier": identifier,
+                "specs": specs,
+            },
+            timeout=timeout,
+        )
+    except requests.RequestException as e:
+        logger.warning("POST /contents failed: %s", e)
+        return
+
+    if result.ok is True:
+        logger.info(
+            "POST /contents succeeded: status=%d, response=%s",
+            result.status_code,
+            result.text,
+        )
+    else:
+        logger.warning(
+            "POST /contents failed: status=%d, response=%s",
+            result.status_code,
+            result.text,
+        )
+
+
+def run_actuator(
+    name: str,
+    data: Dict[str, Any],
+    data_specs: Dict[str, Any] | None = None,
+    actuators_dir: str = "nexgen_actuators",
+    dst: str | None = None,
+    dst_timeout: int = 60,
+    dst_headers: Dict[str, Any] | None = None,
+    dst_save_original: bool = True,
+    try_load_actuator: bool = True,
+) -> object:
+    """# Run Actuator.
+
+    It basically runs the actuator. It raises error if actuator is not seen.
+
+    Args:
+        name (str): Name of the actuator.
+        data (Dict[str, Any]): Input data for the actuator.
+        data_specs (Dict[str, Any] | None): Contains the extra information about the
+            data.
+        actuators_dir (str, optional): Located directory for the actuators.
+        dst (str | None, optional): It pushes the data given endpoint if they have an
+            nexgen compatible endpoint.
+        dst_timeout (int, optional): Timeout for the sending destination endpoint.
+        dst_headers (Dict[str, Any] | None, optional): Required headers for the
+            destination endpoint, if needed.
+        dst_save_original (bool): It saves the original data too with lazy upload.
+        try_load_actuator (bool, optional): It tries to download the actuator first
+            if it is does not exist locally.
+
+    Returns:
+        object: The output coming from actuator.
+    """
+    # Checking The Datatype
+    if isinstance(name, str) is False:
+        logger.error("name is invalid, it has to be str")
+        raise ValueError("name is invalid, it has to be str")
+
+    if isinstance(data, dict) is False:
+        logger.error("data is invalid, it has to be Dict[str, Any]")
+        raise ValueError("data is invalid, it has to be Dict[str, Any]")
+
+    if data_specs is not None and isinstance(data_specs, dict) is False:
+        logger.error("data_specs is invalid, it has to be Dict[str, Any]")
+        raise ValueError("data_specs is invalid, it has to be Dict[str, Any]")
+
+    if isinstance(actuators_dir, str) is False:
+        logger.error("actuators_dir is invalid, it has to be str")
+        raise ValueError("actuators_dir is invalid, it has to be str")
+
+    if dst is not None and isinstance(dst, str) is False:
+        logger.error("dst is invalid, it has to be str")
+        raise ValueError("dst is invalid, it has to be str")
+
+    if isinstance(dst_timeout, int) is False:
+        logger.error("dst_timeout is invalid, it has to be int")
+        raise ValueError("dst_timeout is invalid, it has to be int")
+
+    if dst_headers is not None and isinstance(dst_headers, dict) is False:
+        logger.error("dst_headers is invalid, it has to be Dict[str, Any]")
+        raise ValueError("dst_headers is invalid, it has to be Dict[str, Any]")
+
+    if isinstance(dst_save_original, bool) is False:
+        logger.error("dst_save_original is invalid, it has to be bool")
+        raise ValueError("dst_save_original is invalid, it has to be bool")
+
+    if isinstance(try_load_actuator, bool) is False:
+        logger.error("try_load_actuator is invalid, it has to be bool")
+        raise ValueError("try_load_actuator is invalid, it has to be bool")
+
+    if Path(f"{actuators_dir}/{name}").exists() is False:
+        logger.warning(f"Actuator: {name} does not exist")
+        if try_load_actuator is False:
+            logger.error(f"Actuator {name} has to be downloaded first")
+            raise ValueError(f"Actuator {name} has to be downloaded first")
+        else:
+            load_actuator(
+                name=name,
+                actuators_dir=actuators_dir,
+            )
+
+    file_path = Path(f"{actuators_dir}/{name}/method.py").resolve()
+
+    spec = importlib.util.spec_from_file_location(
+        file_path.stem,
+        file_path,
+    )
+
+    if spec is None or spec.loader is None:
+        raise ImportError(f"Cannot load module: {file_path}")
+
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+
+    # Find functions defined in this file
+    methods = [
+        obj
+        for _, obj in inspect.getmembers(module, inspect.isfunction)
+        if obj.__module__ == module.__name__
+    ]
+
+    if len(methods) != 1:
+        raise ValueError(
+            f"Expected exactly one function, found {len(methods)}",
+        )
+
+    method = methods[0]
+    output = method(**data)
+
+    if dst is None:
+        return output
+
+    if dst_headers is None:
+        dst_headers = {}
+
+    with open(f"{actuators_dir}/{name}/card.json", "r") as f:
+        actuator_id = json.load(f)["id"]
+
+    linked_resource: str | None = None
+    if dst_save_original is True:
+        linked_resource = str(uuid4())
+
+        # Lazy upload, so the main process does not wait for it
+        threading.Thread(
+            target=_send_content,
+            kwargs={
+                "url": f"{dst}/contents",
+                "headers": dst_headers,
+                "timeout": dst_timeout,
+                "identifier": linked_resource,
+                "specs": data,
+            },
+        ).start()
+
+    result = requests.post(
+        url=f"{dst}/data",
+        headers=dst_headers,
+        json={
+            "actuator_id": actuator_id,
+            "metadata": output,
+            "linked_resource": linked_resource,
+            "specs": data_specs,
+        },
+        timeout=dst_timeout,
+    )
+
+    if result.ok is True:
+        logger.info(
+            "POST /data succeeded: status=%d, response=%s",
+            result.status_code,
+            result.text,
+        )
+    else:
+        logger.warning(
+            "POST /data failed: status=%d, response=%s",
+            result.status_code,
+            result.text,
+        )
+
+    return output
+
+
+def load_actuator(
+    name: str,
+    actuators_dir: str = "nexgen_actuators",
+    load_timeout: int = 60,
+    update_actuator: bool = True,
+) -> None:
+    """# Load Actuator.
+
+    Args:
+        name (str): The name of the actuator.
+        actuators_dir (str, optional): Located directory for the actuators.
+        load_timeout (int, optional): The timeout for the loading the actuator.
+        update_actuator (bool, optional): If it is true, even though the actuator exists
+            it checks that the latest version is changed and if it is changed then
+            override the existing actuator.
+    """
+    # Checking The Datatypes
+    if isinstance(name, str) is False:
+        logger.error("name is invalid, it has to be str")
+        raise ValueError("name is invalid, it has to be str")
+
+    if isinstance(actuators_dir, str) is False:
+        logger.error("actuators_dir is invalid, it has to be str")
+        raise ValueError("actuators_dir is invalid, it has to be str")
+
+    if isinstance(load_timeout, int) is False:
+        logger.error("load_timeout is invalid, it has to be int")
+        raise ValueError("load_timeout is invalid, it has to be int")
+
+    if isinstance(update_actuator, bool) is False:
+        logger.error("update_actuator is invalid, it has to be bool")
+        raise ValueError("update_actuator is invalid, it has to be bool")
+
+    # The name has to point to a directory directly inside actuators_dir
+    actuators_path = Path(actuators_dir).resolve()
+    if (actuators_path / name).resolve().parent != actuators_path:
+        logger.error("name is invalid, it has to be a plain directory name")
+        raise ValueError("name is invalid, it has to be a plain directory name")
+
+    if update_actuator is False and Path(f"{actuators_dir}/{name}").exists() is True:
+        logger.info(f"Actuator {name} already exists")
+        return
+
+    headers = {}
+    if os.getenv("NEXGEN_API_KEY") is not None:
+        headers["X-API-KEY"] = os.getenv("NEXGEN_API_KEY")
+
+    result = requests.get(
+        f"{os.getenv('NEXGEN_BASE_URL', DEFAULT_BASE_URL)}/actuators/{name}/latest",
+        headers=headers,
+        timeout=load_timeout,
+    )
+
+    result.raise_for_status()
+
+    logger.info(
+        "GET /actuators/actuator_name/latest succeeded: status=%d, response=%s",
+        result.status_code,
+        result.text,
+    )
+
+    response = result.json()
+
+    card_path = Path(f"{actuators_dir}/{name}/card.json")
+    if card_path.exists() is True:
+        with open(card_path, "r") as f:
+            existing_card = json.load(f)
+
+        if (
+            existing_card.get("id") == response["_id"]
+            and existing_card.get("version") == response["version"]
+        ):
+            logger.info(f"Actuator {name} is already up to date")
+            return
+
+    if Path(f"{actuators_dir}/{name}").exists():
+        logger.info("Existing directory has been found")
+        shutil.rmtree(f"{actuators_dir}/{name}")
+        logger.info("Existing directory deleted")
+
+    os.makedirs(f"{actuators_dir}/{name}")
+    logger.info(f"New directory has been created: {actuators_dir}/{name}")
+
+    card = {
+        "id": response["_id"],
+        "name": response["name"],
+        "version": response["version"],
+        "actuator_type": response["actuator_type"],
+        "method_args": response["method_args"],
+        "latest": response["latest"],
+        "created_at": response["created_at"],
+        "updated_at": response["updated_at"],
+    }
+
+    requirements = "\n".join(response["requirements"])
+    method = response["method"]
+
+    with open(f"{actuators_dir}/{name}/method.py", "w") as f:
+        f.write(method)
+
+    logger.info("method.py has been created")
+
+    with open(f"{actuators_dir}/{name}/requirements.txt", "w") as f:
+        f.write(requirements)
+
+    logger.info("requirements.txt has been created")
+
+    subprocess.run(  # noqa: S603
+        [sys.executable, "-m", "venv", f"{actuators_dir}/{name}/.venv"],
+        check=True,
+    )
+
+    logger.info(".venv has been created")
+    logger.info("requirements are being downloaded...")
+
+    if sys.platform == "win32":
+        pip_path = f"{actuators_dir}/{name}/.venv/Scripts/pip.exe"
+    else:
+        pip_path = f"{actuators_dir}/{name}/.venv/bin/pip"
+
+    subprocess.run(  # noqa: S603
+        [
+            pip_path,
+            "install",
+            "-r",
+            f"{actuators_dir}/{name}/requirements.txt",
+        ],
+        check=True,
+    )
+
+    logger.info("requirements downloaded")
+
+    # card.json is written last, so a failed load is not seen as up to date
+    with open(f"{actuators_dir}/{name}/card.json", "w") as f:
+        json.dump(
+            card,
+            f,
+            indent=4,
+            ensure_ascii=True,
+        )
+
+    logger.info("card.json has been created")

nexgenpy-1.0.0.dist-info/METADATA

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: nexgenpy
+Version: 1.0.0
+Summary: Post Shannon Communication for every day systems
+Author-email: iamalreadynoob <sadikefe69@gmail.com>
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: build>=1.6.1
+Requires-Dist: pre-commit>=4.6.2
+Requires-Dist: requests>=2.34.2
+Requires-Dist: ruff>=0.16.10
+
+<div align="center">
+
+# nexgenpy
+
+**The Python client for Nexgen Server. Publish, load and run semantic communication actuators.**
+
+[![CI](https://github.com/iamalreadynoob/nexgen/actions/workflows/ci.yml/badge.svg)](https://github.com/iamalreadynoob/nexgen/actions/workflows/ci.yml)
+[![Python 3.12](https://img.shields.io/badge/python-3.12%20%7C%203.13-3776AB?logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![Version](https://img.shields.io/badge/version-1.0.0-informational)](pyproject.toml)
+[![Nexgen Server](https://img.shields.io/badge/server-nexgen--server-009688?logo=github&logoColor=white)](https://github.com/iamalreadynoob/nexgen-server)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-FAB040?logo=pre-commit&logoColor=white)](.pre-commit-config.yaml)
+
+<p>
+  <a href="#introduction">Introduction</a> •
+  <a href="#setup">Setup</a> •
+  <a href="#basic-concepts">Basic concepts</a> •
+  <a href="#documentation">Documentation</a>
+</p>
+
+</div>
+
+---
+
+## Introduction
+
+`nexgenpy` is the Python client library for [Nexgen Server](https://github.com/iamalreadynoob/nexgen-server). Nexgen Server is a registry and data store for semantic communication (SemCom) applications.
+
+SemCom is a communication paradigm. Its design objective is the correct delivery of the *meaning*, or of the *task-relevant content*, of a message. Its objective is not the bit-exact copy of the transmitted symbols. Thus the methods at each end of the link are as important as the link itself.
+
+Nexgen Server keeps these methods, called **actuators**, in one place. The server does not run actuator code. `nexgenpy` gives the applications three operations:
+
+| Operation | API | What it does |
+|---|---|---|
+| **Register** | `@actuator(...)` | Sends the source code of a Python function to the server as a new actuator version. |
+| **Load** | `load_actuator(...)` | Downloads the latest version of an actuator to a local directory and installs its requirements. |
+| **Use** | `run_actuator(...)`, `Actuator(...)` | Runs the local actuator. Optionally sends the output to the server as a data item. |
+
+```mermaid
+flowchart LR
+    subgraph DEV["Developer"]
+        F["Python function<br/>+ @actuator decorator"]
+    end
+
+    NS[("Nexgen Server<br/>actuators · data · contents")]
+
+    subgraph TX["Transmitter (nexgenpy)"]
+        S["Source s"] --> CA["coding actuator"]
+    end
+
+    subgraph RX["Receiver (nexgenpy)"]
+        DA["decoding actuator"] --> O["Output ŝ<br/>reconstruction or task decision"]
+    end
+
+    F -- "1. register<br/>POST /actuators" --> NS
+    NS -. "2. load<br/>GET /actuators/{name}/latest" .-> CA
+    NS -. "2. load" .-> DA
+    CA -- "3. use: transmitted representation" --> DA
+    CA -. "data item<br/>POST /data" .-> NS
+    S -. "content item (original)<br/>POST /contents" .-> NS
+```
+
+1. A developer writes a Python function and registers it as an actuator with a name and a version.
+2. A transmitter and a receiver each load the latest version of the actuators that they need.
+3. Each side runs its actuator on local data. The output can go to the server as a data item. The original input can go to the server as a content item.
+
+`nexgenpy` supports the two SemCom objectives of Nexgen Server:
+
+- **Semantic-level communication.** The decoding actuator recreates the source, or its meaning, from the received representation.
+- **Goal-oriented (task-oriented) communication.** The decoding actuator identifies the input or does a task with it, for example classification. It does not recreate the source.
+
+> [!TIP]
+> Do you use [Claude Code](https://claude.com/claude-code)? The [nexgenpy skill](https://github.com/iamalreadynoob/nexgenpy-skill) gives Claude Code the knowledge to use `nexgenpy` in your projects. Install it to get help when you register, load and use actuators.
+
+## Setup
+
+### Requirements
+
+- Python 3.12 or later
+- A running [Nexgen Server](https://github.com/iamalreadynoob/nexgen-server#setup)
+- The API key of the server, if the server has one
+
+### Install the library
+
+Install from GitHub with pip:
+
+```bash
+pip install "git+https://github.com/iamalreadynoob/nexgen.git"
+```
+
+Or add it to a uv project:
+
+```bash
+uv add "git+https://github.com/iamalreadynoob/nexgen.git"
+```
+
+The repository also keeps a built wheel in `dist/`. To install a local clone for development, see [Development](docs/development.md).
+
+### Connect to the server
+
+Set these environment variables:
+
+```bash
+export NEXGEN_BASE_URL="http://localhost:8000/api/v1"
+export NEXGEN_API_KEY="<your-key>"
+```
+
+If `NEXGEN_BASE_URL` is not set, the library uses `http://localhost:8000/api/v1`. See [Configuration](docs/configuration.md) for all settings.
+
+### Register a first actuator
+
+```python
+from nexgenpy import actuator
+
+
+@actuator(
+    name="text-embedder",
+    atype="coding",
+    version="1.0.0",
+    is_latest=True,
+    requirements=["numpy"],
+)
+def encode(text: str) -> list[float]:
+    import numpy as np
+
+    return np.frombuffer(text.encode(), dtype=np.uint8).astype(float).tolist()
+
+
+accepted = encode()  # sends POST /actuators, returns True or False
+```
+
+A call to the decorated function does not run `encode`. The call registers it.
+
+### Load and use the actuator
+
+```python
+from nexgenpy import load_actuator, run_actuator
+
+load_actuator("text-embedder")
+
+vector = run_actuator(
+    name="text-embedder",
+    data={"text": "hello"},
+)
+```
+
+`run_actuator` runs the function in the current Python process. Thus the current environment must also have the requirements of the actuator, `numpy` in this example. See [Architecture](docs/architecture.md#the-actuator-environment).
+
+To send the output to the server as a data item, give the server URL and the API key header:
+
+```python
+vector = run_actuator(
+    name="text-embedder",
+    data={"text": "hello"},
+    dst="http://localhost:8000/api/v1",
+    dst_headers={"X-API-Key": "<your-key>"},
+)
+```
+
+The [Quick start guide](docs/quickstart.md) gives a full transmitter and receiver example.
+
+## Basic concepts
+
+| Concept | What it is | Where it lives |
+|---|---|---|
+| **Actuator** | A versioned, named Python function that processes data. Its type is `coding` or `decoding`. | Server: `actuators` collection. Client: `nexgen_actuators/{name}/` |
+| **Data** | The output of an actuator, as the link carries or uses it. Each data item refers to the actuator that made it. | Server: `data` collection |
+| **Content** | The original input of an actuator. Applications can load it again, for example to compare it with a reconstruction. | Server: `contents` collection |
+
+### Actuators
+
+An actuator does one processing step in a SemCom pipeline. Examples are data embedding, compression and format conversion.
+
+- A **`coding`** actuator changes a source into a representation for transmission. It can be a semantic encoder, a channel encoder or a joint source–channel coding (JSCC) encoder.
+- A **`decoding`** actuator changes a received representation into an output. The output is a reconstruction of the source or a task decision.
+
+Each actuator has a `name` and a `version`. For each name, exactly one active version is the latest. `load_actuator` always gets the latest version. Thus the transmitter and the receiver can use the same version.
+
+### The actuator function
+
+The server stores only the source code of the function. The code that is outside the function does not go to the server. Thus an actuator function must obey these rules:
+
+- Put all `import` statements in the function body.
+- Do not call helper functions from the same module. Define them in the function body.
+- Use parameter names that match the keys of the input data. `run_actuator` calls the function with `**data`.
+- Return a value that JSON can encode, if you send the output to the server.
+
+[Writing actuators](docs/writing-actuators.md) explains each rule.
+
+### Local actuator directory
+
+`load_actuator` writes each actuator to `nexgen_actuators/{name}/`:
+
+```text
+nexgen_actuators/
+└── text-embedder/
+    ├── card.json          # metadata, including the server id and the version
+    ├── method.py          # the source code of the function
+    ├── requirements.txt   # the pip requirements
+    └── .venv/             # a virtual environment with the requirements
+```
+
+### Shared rules
+
+- All requests go to `NEXGEN_BASE_URL`, or to `dst` for data and content items.
+- The library sends the `X-API-KEY` header when `NEXGEN_API_KEY` is set. Data and content requests use `dst_headers` instead.
+- The server accepts a data item only from the **latest** version of an actuator. Load the actuator again after someone publishes a new version.
+
+[Concepts](docs/concepts.md) gives more detail about SemCom and about how `nexgenpy` fits a SemCom pipeline.
+
+## Documentation
+
+| Document | Contents |
+|---|---|
+| [Quick start](docs/quickstart.md) | A full example: register, load and run a coding and a decoding actuator |
+| [Concepts](docs/concepts.md) | SemCom background, the two objectives, and how actuators, data and contents fit a SemCom pipeline |
+| [Architecture](docs/architecture.md) | Modules, the request flow for each operation and the local directory layout |
+| [Writing actuators](docs/writing-actuators.md) | Rules and examples for actuator functions |
+| [Configuration](docs/configuration.md) | Environment variables, API key, timeouts and logging |
+| [API: `actuator`](docs/api/actuator.md) | The decorator that registers an actuator |
+| [API: `load_actuator`](docs/api/load-actuator.md) | The function that downloads an actuator and installs its requirements |
+| [API: `run_actuator` and `Actuator`](docs/api/run-actuator.md) | The function and the class that run an actuator and send its output |
+| [Development](docs/development.md) | Tests, lint, CI, release and code conventions |
+| [Security](docs/security.md) | Risks of downloaded actuator code, and SemCom threats |
+| [Glossary](docs/glossary.md) | SemCom and project terms |
+| [References](docs/references.md) | Surveys and papers about SemCom |

nexgenpy-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+nexgenpy/__init__.py,sha256=cQLjAlSrgGI444WYxI_cFkeoz6dvaSXTjpqfafqkdNw,91
+nexgenpy/actuators.py,sha256=vDaozWVKMXtoEmaonWISWpWYb1RbbWd47Y7UweQdl_g,5784
+nexgenpy/manager.py,sha256=WvoISC87leaPjw2-298qMGt5zDU2qArVEIndmcxPTB4,21661
+nexgenpy-1.0.0.dist-info/METADATA,sha256=HbaSjRclfa5wPc3SagKozf2gSdHGacq3BMhN_7P_-kE,10686
+nexgenpy-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+nexgenpy-1.0.0.dist-info/top_level.txt,sha256=R5Pm2g3M-7W0ZI2kxttJUkV4mAm8oMUu0EacvaEpvkA,9
+nexgenpy-1.0.0.dist-info/RECORD,,

nexgenpy-1.0.0.dist-info/WHEEL

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

nexgenpy-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+nexgenpy