astra-plugin-sdk 0.1.0__tar.gz

astra_plugin_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: astra-plugin-sdk
+Version: 0.1.0
+Summary: Python SDK for building Astra plugins
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mihailinl/AstraPlugins
+Project-URL: Repository, https://github.com/mihailinl/AstraPlugins/tree/master/astra-plugin-sdk-python
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: grpcio>=1.60.0
+Requires-Dist: grpcio-tools>=1.60.0
+Requires-Dist: protobuf>=4.25.0
+
+# Astra Plugin SDK (Python)
+
+Build plugins for [Astra](https://github.com/astra-assistant) in Python.
+
+## Installation
+
+```bash
+pip install astra-plugin-sdk
+```
+
+## Quick Start
+
+```python
+from astra_plugin_sdk import Plugin
+
+class MyPlugin(Plugin):
+    async def list_tools(self):
+        return [{
+            "name": "hello",
+            "description": "Say hello",
+            "parameters_json": '{"type": "object", "properties": {}}',
+        }]
+
+    async def call_tool(self, name, arguments_json):
+        if name == "hello":
+            return {"success": True, "result": "Hello from the plugin!"}
+        return {"success": False, "error": f"Unknown tool: {name}"}
+
+if __name__ == "__main__":
+    MyPlugin().run()
+```
+
+## Capabilities
+
+Override the methods you need:
+
+- **Tools**: `list_tools()`, `call_tool(name, args)`
+- **TTS**: `tts_list_voices()`, `tts_synthesize(text, voice_id, speed, pitch)`
+- **STT**: `stt_get_languages()`
+- **AI Provider**: `ai_get_models()`
+- **Actions**: `get_action_types()`, `execute_action(type, params)`
+- **Triggers**: `get_trigger_types()`
+- **Lifecycle**: `on_config_changed(config)`, `on_shutdown()`, `health_check()`
+
+## Host Client
+
+Access daemon services from your plugin:
+
+```python
+class MyPlugin(Plugin):
+    async def on_config_changed(self, config):
+        # Log to daemon
+        await self.host.log("info", f"Config updated: {config}")
+
+        # Fire a trigger
+        await self.host.fire_trigger("my_trigger", '{"key": "value"}')
+
+        # Get daemon info
+        info = await self.host.get_daemon_info()
+        print(f"Daemon version: {info.version}")
+```

astra_plugin_sdk-0.1.0/README.md

@@ -0,0 +1,61 @@
+# Astra Plugin SDK (Python)
+
+Build plugins for [Astra](https://github.com/astra-assistant) in Python.
+
+## Installation
+
+```bash
+pip install astra-plugin-sdk
+```
+
+## Quick Start
+
+```python
+from astra_plugin_sdk import Plugin
+
+class MyPlugin(Plugin):
+    async def list_tools(self):
+        return [{
+            "name": "hello",
+            "description": "Say hello",
+            "parameters_json": '{"type": "object", "properties": {}}',
+        }]
+
+    async def call_tool(self, name, arguments_json):
+        if name == "hello":
+            return {"success": True, "result": "Hello from the plugin!"}
+        return {"success": False, "error": f"Unknown tool: {name}"}
+
+if __name__ == "__main__":
+    MyPlugin().run()
+```
+
+## Capabilities
+
+Override the methods you need:
+
+- **Tools**: `list_tools()`, `call_tool(name, args)`
+- **TTS**: `tts_list_voices()`, `tts_synthesize(text, voice_id, speed, pitch)`
+- **STT**: `stt_get_languages()`
+- **AI Provider**: `ai_get_models()`
+- **Actions**: `get_action_types()`, `execute_action(type, params)`
+- **Triggers**: `get_trigger_types()`
+- **Lifecycle**: `on_config_changed(config)`, `on_shutdown()`, `health_check()`
+
+## Host Client
+
+Access daemon services from your plugin:
+
+```python
+class MyPlugin(Plugin):
+    async def on_config_changed(self, config):
+        # Log to daemon
+        await self.host.log("info", f"Config updated: {config}")
+
+        # Fire a trigger
+        await self.host.fire_trigger("my_trigger", '{"key": "value"}')
+
+        # Get daemon info
+        info = await self.host.get_daemon_info()
+        print(f"Daemon version: {info.version}")
+```

astra_plugin_sdk-0.1.0/astra_plugin_sdk/__init__.py

@@ -0,0 +1,8 @@
+"""Astra Plugin SDK — build plugins for Astra in Python."""
+
+from astra_plugin_sdk.plugin import Plugin
+from astra_plugin_sdk.host_client import HostClient
+from astra_plugin_sdk.decorators import tool, action, trigger, Field
+
+__all__ = ["Plugin", "HostClient", "tool", "action", "trigger", "Field"]
+__version__ = "0.1.0"

astra_plugin_sdk-0.1.0/astra_plugin_sdk/decorators.py

@@ -0,0 +1,318 @@
+"""Decorators and helpers for declarative plugin definitions.
+
+Use ``@tool``, ``@action``, and ``@trigger`` to define capabilities with
+minimal boilerplate.  The ``Field`` class provides builder methods for
+action/trigger field definitions.
+"""
+
+import inspect
+import json
+import typing
+from typing import Any, Literal, Optional, Union, get_type_hints
+
+
+# ---------------------------------------------------------------------------
+# Type-hint -> JSON Schema mapping
+# ---------------------------------------------------------------------------
+
+_PY_TO_JSON_TYPE = {
+    str: "string",
+    int: "integer",
+    float: "number",
+    bool: "boolean",
+    list: "array",
+    dict: "object",
+}
+
+
+def _type_to_schema(hint: Any) -> dict:
+    """Convert a Python type hint to a JSON Schema fragment."""
+    # Plain types
+    if hint in _PY_TO_JSON_TYPE:
+        return {"type": _PY_TO_JSON_TYPE[hint]}
+
+    origin = typing.get_origin(hint)
+    args = typing.get_args(hint)
+
+    # Literal["a", "b"] -> enum
+    if origin is Literal:
+        return {"type": "string", "enum": list(args)}
+
+    # Optional[X] (Union[X, None])
+    if origin is Union:
+        non_none = [a for a in args if a is not type(None)]
+        if len(non_none) == 1:
+            return _type_to_schema(non_none[0])
+
+    # list[str] etc.
+    if origin is list:
+        schema: dict = {"type": "array"}
+        if args:
+            schema["items"] = _type_to_schema(args[0])
+        return schema
+
+    # Fallback
+    return {"type": "string"}
+
+
+def _build_json_schema(fn: Any) -> str:
+    """Build a JSON Schema string from a function's type hints."""
+    try:
+        hints = get_type_hints(fn)
+    except Exception:
+        hints = {}
+
+    sig = inspect.signature(fn)
+    properties: dict[str, dict] = {}
+    required: list[str] = []
+
+    for name, param in sig.parameters.items():
+        if name == "self":
+            continue
+        hint = hints.get(name, str)  # default to string
+        prop = _type_to_schema(hint)
+
+        # Use parameter name as description placeholder if no docstring parsing
+        properties[name] = prop
+
+        # Required if no default
+        if param.default is inspect.Parameter.empty:
+            origin = typing.get_origin(hint)
+            args = typing.get_args(hint)
+            is_optional = (
+                origin is Union
+                and type(None) in args
+            )
+            if not is_optional:
+                required.append(name)
+
+    schema = {"type": "object", "properties": properties}
+    if required:
+        schema["required"] = required
+    return json.dumps(schema)
+
+
+# ---------------------------------------------------------------------------
+# Decorators
+# ---------------------------------------------------------------------------
+
+def tool(description: str):
+    """Mark a method as a plugin tool.
+
+    The decorated method's type hints are used to auto-generate JSON Schema
+    for the tool parameters.  The return value is automatically wrapped in
+    ``{"success": True, "result": ...}`` by the SDK.
+
+    Example::
+
+        @tool("Count words in text")
+        async def word_count(self, text: str):
+            return {"words": len(text.split())}
+    """
+    def decorator(fn):
+        fn._astra_tool_meta = {
+            "name": fn.__name__,
+            "description": description,
+            "parameters_json": _build_json_schema(fn),
+        }
+        return fn
+    return decorator
+
+
+def action(
+    label: str,
+    *,
+    icon_svg: str = "",
+    fields: list[dict] | None = None,
+    ai_available: bool = False,
+    ai_description: str = "",
+    ai_primary_field: str = "",
+):
+    """Mark a method as a plugin action type.
+
+    Example::
+
+        @action("Transform Text", fields=[
+            Field.dropdown("op", "Operation", options=["upper", "lower"]),
+        ])
+        async def transform_text(self, op: str, input_text: str):
+            ...
+    """
+    def decorator(fn):
+        fn._astra_action_meta = {
+            "type": fn.__name__,
+            "label": label,
+            "icon_svg": icon_svg,
+            "fields": fields or [],
+            "ai_available": ai_available,
+            "ai_description": ai_description,
+            "ai_primary_field": ai_primary_field,
+        }
+        return fn
+    return decorator
+
+
+def trigger(
+    label: str,
+    *,
+    icon_svg: str = "",
+    fields: list[dict] | None = None,
+):
+    """Mark a method as a plugin trigger type definition.
+
+    The method itself is not called automatically — it just holds metadata.
+    Use ``self.fire_trigger(...)`` to fire the trigger from a background task.
+
+    Example::
+
+        @trigger("Scheduled Time", fields=[
+            Field.text("time", "Time", default="09:00", placeholder="HH:MM"),
+        ])
+        def on_time(self):
+            pass
+    """
+    def decorator(fn):
+        fn._astra_trigger_meta = {
+            "type": fn.__name__,
+            "label": label,
+            "icon_svg": icon_svg,
+            "fields": fields or [],
+        }
+        return fn
+    return decorator
+
+
+# ---------------------------------------------------------------------------
+# Field builder
+# ---------------------------------------------------------------------------
+
+class Field:
+    """Builder for action/trigger field definitions.
+
+    Each static method returns a dict matching the proto ``FieldDefinitionMsg``
+    structure, ready to pass into ``@action(fields=[...])`` or
+    ``@trigger(fields=[...])``.
+    """
+
+    @staticmethod
+    def text(
+        id: str,
+        label: str,
+        *,
+        placeholder: str = "",
+        default: str = "",
+        description: str = "",
+        conditions: list[dict] | None = None,
+    ) -> dict:
+        return {
+            "id": id, "label": label, "field_type": "text",
+            "placeholder": placeholder, "default_value": default,
+            "description": description, "conditions": conditions or [],
+        }
+
+    @staticmethod
+    def textarea(
+        id: str,
+        label: str,
+        *,
+        placeholder: str = "",
+        default: str = "",
+        description: str = "",
+        conditions: list[dict] | None = None,
+    ) -> dict:
+        return {
+            "id": id, "label": label, "field_type": "textarea",
+            "placeholder": placeholder, "default_value": default,
+            "description": description, "conditions": conditions or [],
+        }
+
+    @staticmethod
+    def textarea_with_variables(
+        id: str,
+        label: str,
+        *,
+        placeholder: str = "",
+        default: str = "",
+        description: str = "",
+        conditions: list[dict] | None = None,
+    ) -> dict:
+        return {
+            "id": id, "label": label, "field_type": "textarea_with_variables",
+            "placeholder": placeholder, "default_value": default,
+            "description": description, "conditions": conditions or [],
+        }
+
+    @staticmethod
+    def dropdown(
+        id: str,
+        label: str,
+        *,
+        options: list,
+        default: str = "",
+        description: str = "",
+        conditions: list[dict] | None = None,
+    ) -> dict:
+        """Create a dropdown field.
+
+        ``options`` accepts:
+        - ``[("value", "Label"), ...]`` — tuple pairs
+        - ``[{"value": ..., "label": ...}, ...]`` — explicit dicts
+        - ``["value1", "value2"]`` — strings (value = label)
+        """
+        normalized = []
+        for opt in options:
+            if isinstance(opt, dict):
+                normalized.append(opt)
+            elif isinstance(opt, (tuple, list)) and len(opt) == 2:
+                normalized.append({"value": opt[0], "label": opt[1]})
+            else:
+                normalized.append({"value": str(opt), "label": str(opt)})
+        return {
+            "id": id, "label": label, "field_type": "dropdown",
+            "options": normalized, "default_value": default,
+            "description": description, "conditions": conditions or [],
+        }
+
+    @staticmethod
+    def number(
+        id: str,
+        label: str,
+        *,
+        min: float | None = None,
+        max: float | None = None,
+        step: float | None = None,
+        default: str = "",
+        description: str = "",
+        conditions: list[dict] | None = None,
+    ) -> dict:
+        return {
+            "id": id, "label": label, "field_type": "number",
+            "default_value": default, "description": description,
+            "has_min": min is not None,
+            "has_max": max is not None,
+            "has_step": step is not None,
+            "min": float(min) if min is not None else 0.0,
+            "max": float(max) if max is not None else 0.0,
+            "step": float(step) if step is not None else 0.0,
+            "conditions": conditions or [],
+        }
+
+    @staticmethod
+    def toggle(
+        id: str,
+        label: str,
+        *,
+        default: bool = False,
+        description: str = "",
+        conditions: list[dict] | None = None,
+    ) -> dict:
+        return {
+            "id": id, "label": label, "field_type": "toggle",
+            "default_value": "true" if default else "false",
+            "description": description, "conditions": conditions or [],
+        }
+
+    @staticmethod
+    def condition(field_id: str, operator: str, value: str = "") -> dict:
+        """Build a field visibility condition."""
+        return {"field_id": field_id, "operator": operator, "value": value}

astra_plugin_sdk-0.1.0/astra_plugin_sdk/host_client.py

@@ -0,0 +1,93 @@
+"""HostClient — plugin-side gRPC client for calling the Astra daemon."""
+
+import grpc
+
+from astra_plugin_sdk.proto import plugin_pb2, plugin_pb2_grpc
+
+
+class HostClient:
+    """Client for calling daemon services from a plugin."""
+
+    def __init__(self, daemon_addr: str, plugin_id: str):
+        self.daemon_addr = daemon_addr
+        self.plugin_id = plugin_id
+        self._channel: grpc.aio.Channel | None = None
+        self._stub: plugin_pb2_grpc.PluginHostServiceStub | None = None
+
+    async def connect(self):
+        """Connect to the daemon's PluginHostService."""
+        self._channel = grpc.aio.insecure_channel(self.daemon_addr)
+        self._stub = plugin_pb2_grpc.PluginHostServiceStub(self._channel)
+
+    async def register(
+        self, port: int, capabilities: list[str]
+    ) -> plugin_pb2.PluginRegisterResponse:
+        """Register this plugin with the daemon."""
+        return await self._stub.Register(
+            plugin_pb2.PluginRegisterRequest(
+                plugin_id=self.plugin_id,
+                port=port,
+                capabilities=capabilities,
+            )
+        )
+
+    async def fire_trigger(self, trigger_type: str, payload_json: str = "{}"):
+        """Fire a trigger (for trigger plugins)."""
+        await self._stub.FireTrigger(
+            plugin_pb2.PluginFireTriggerRequest(
+                trigger_type=trigger_type,
+                payload_json=payload_json,
+            )
+        )
+
+    async def log(self, level: str, message: str):
+        """Log a message to the daemon's log buffer."""
+        await self._stub.PluginLog(
+            plugin_pb2.PluginLogRequest(
+                plugin_id=self.plugin_id,
+                level=level,
+                message=message,
+            )
+        )
+
+    async def get_config(self) -> str:
+        """Get this plugin's current config from the daemon."""
+        response = await self._stub.GetPluginSelfConfig(
+            plugin_pb2.PluginSelfIdRequest(plugin_id=self.plugin_id)
+        )
+        return response.config_json
+
+    async def get_daemon_info(self) -> plugin_pb2.PluginDaemonInfoResponse:
+        """Get daemon info (version, state, port)."""
+        return await self._stub.GetDaemonInfo(plugin_pb2.Empty())
+
+    async def subscribe_events(self, event_types: list[str] | None = None):
+        """Subscribe to daemon events. Returns an async iterator."""
+        return self._stub.SubscribeEvents(
+            plugin_pb2.PluginEventFilter(
+                plugin_id=self.plugin_id,
+                event_types=event_types or [],
+            )
+        )
+
+    async def set_variable(self, name: str, value: str, scope: str = "session"):
+        """Set a variable in the daemon's variable context.
+
+        Args:
+            name: Variable name.
+            value: Variable value.
+            scope: "session" (default, cleared on restart) or "persistent" (saved to disk).
+        """
+        await self._stub.SetVariable(
+            plugin_pb2.PluginSetVariableRequest(
+                plugin_id=self.plugin_id,
+                name=name,
+                value=value,
+                scope=scope,
+            )
+        )
+
+    async def close(self):
+        """Close the gRPC channel."""
+        if self._channel:
+            await self._channel.close()