triggerware 0.1.2__tar.gz → 1.0.0__tar.gz

triggerware-1.0.0/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.3
+Name: triggerware
+Version: 1.0.0
+Summary: Async Python SDK for Triggerware
+Requires-Dist: tw2-jsonrpc
+Requires-Dist: pyyaml
+Requires-Dist: tw2-jsonrpc[websockets] ; extra == 'websockets'
+Requires-Python: >=3.11
+Provides-Extra: websockets
+Description-Content-Type: text/markdown
+
+# Triggerware Python SDK
+
+Async Python SDK for Triggerware.
+
+Install with the `websockets` extra when using cloud/WebSocket connections:
+
+```sh
+uv add "triggerware[websockets]"
+```
+
+```python
+from triggerware import TriggerwareClient
+
+client = await TriggerwareClient.connect_tcp("localhost:5221")
+
+health = await client.system.health()
+cursor = await client.cursors.open(sql="select * from my_connector")
+
+async for row in cursor:
+    print(row)
+```
+
+WebSocket connections authorize immediately with the provided API key:
+
+```python
+client = await TriggerwareClient.connect_ws("wss://example.com/rpc", "your-api-key-here")
+```

triggerware-1.0.0/README.md

@@ -0,0 +1,27 @@
+# Triggerware Python SDK
+
+Async Python SDK for Triggerware.
+
+Install with the `websockets` extra when using cloud/WebSocket connections:
+
+```sh
+uv add "triggerware[websockets]"
+```
+
+```python
+from triggerware import TriggerwareClient
+
+client = await TriggerwareClient.connect_tcp("localhost:5221")
+
+health = await client.system.health()
+cursor = await client.cursors.open(sql="select * from my_connector")
+
+async for row in cursor:
+    print(row)
+```
+
+WebSocket connections authorize immediately with the provided API key:
+
+```python
+client = await TriggerwareClient.connect_ws("wss://example.com/rpc", "your-api-key-here")
+```

triggerware-1.0.0/pyproject.toml

@@ -0,0 +1,14 @@
+[project]
+name = "triggerware"
+version = "1.0.0"
+description = "Async Python SDK for Triggerware"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = ["tw2-jsonrpc", "pyyaml"]
+
+[project.optional-dependencies]
+websockets = ["tw2-jsonrpc[websockets]"]
+
+[build-system]
+requires = ["uv_build>=0.10.0,<0.11.0"]
+build-backend = "uv_build"

triggerware-1.0.0/src/triggerware/__init__.py

@@ -0,0 +1,39 @@
+from ._client import TriggerwareClient
+from ._configuration import Configuration
+from ._connectors import (
+    ConnectorColumn,
+    ConnectorGenerator,
+    ConnectorMetadata,
+    ConnectorRuntime,
+    connector_metadata_from_string,
+)
+from ._cursors import CursorColumn
+from ._extensions import Extension, ExtensionDescription, ExtensionRuntime
+from ._logging import LogLevel
+from ._queries import QuerySignature
+from ._runtimes import Runtime
+from ._triggers import (
+    TriggerCallback,
+    TriggerDelta,
+    TriggerSignature,
+)
+
+__all__ = [
+    "Configuration",
+    "ConnectorColumn",
+    "ConnectorGenerator",
+    "ConnectorMetadata",
+    "ConnectorRuntime",
+    "connector_metadata_from_string",
+    "CursorColumn",
+    "Extension",
+    "ExtensionDescription",
+    "ExtensionRuntime",
+    "LogLevel",
+    "QuerySignature",
+    "Runtime",
+    "TriggerCallback",
+    "TriggerDelta",
+    "TriggerSignature",
+    "TriggerwareClient",
+]

triggerware-1.0.0/src/triggerware/_client.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from typing import Self
+
+import tw2_jsonrpc as rpc
+
+from ._configuration import ConfigurationService
+from ._connectors import ConnectorsService
+from ._cursors import CursorsService
+from ._extensions import ExtensionsService
+from ._logging import LoggingService
+from ._prompts import PromptsService
+from ._queries import QueriesService
+from ._runtimes import RuntimesService
+from ._system import SystemService
+from ._triggers import TriggersService
+
+
+class TriggerwareClient:
+
+    def __init__(self, peer: rpc.Peer) -> None:
+        self._peer = peer
+        self.configuration = ConfigurationService(peer)
+        self.connectors = ConnectorsService(peer)
+        self.cursors = CursorsService(peer)
+        self.extensions = ExtensionsService(peer)
+        self.logging = LoggingService(peer)
+        self.prompts = PromptsService(peer)
+        self.queries = QueriesService(peer)
+        self.runtimes = RuntimesService(peer)
+        self.system = SystemService(peer)
+        self.triggers = TriggersService(peer)
+
+    # do we need enter? exit? close?
+
+    @classmethod
+    async def connect_tcp(cls, address: str) -> Self:
+        host, port_text = address.rsplit(":", 1)
+        peer = await rpc.connect_tcp(host, int(port_text))
+        return cls(peer)
+
+    @classmethod
+    async def connect_ws(cls, url: str, api_key: str) -> Self:
+        peer = await rpc.connect_ws(url)
+        client = cls(peer)
+        await client.system.authorize(api_key)
+        return client

triggerware-1.0.0/src/triggerware/_configuration.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from typing import NotRequired, TypedDict
+
+import tw2_jsonrpc as rpc
+
+
+class Configuration(TypedDict):
+    default_timeout_ms: NotRequired[int]
+    default_batch_size: NotRequired[int]
+    default_trigger_batch_size: NotRequired[int]
+    llm_provider: NotRequired[str]
+    llm_model: NotRequired[str]
+    max_log_file_size: NotRequired[str]
+
+
+class ConfigurationService:
+    def __init__(self, peer: rpc.Peer):
+        self._peer = peer
+
+    async def get(self) -> Configuration:
+        return await self._peer.call("configuration.get")
+
+    async def set(
+        self,
+        *,
+        default_timeout_ms: int | None = None,
+        default_batch_size: int | None = None,
+        default_trigger_batch_size: int | None = None,
+        llm_provider: str | None = None,
+        llm_model: str | None = None,
+        llm_api_key: str | None = None,
+        max_log_file_size: str | None = None,
+    ) -> Configuration:
+        params = {
+            "default_timeout_ms": default_timeout_ms,
+            "default_batch_size": default_batch_size,
+            "default_trigger_batch_size": default_trigger_batch_size,
+            "llm_provider": llm_provider,
+            "llm_model": llm_model,
+            "llm_api_key": llm_api_key,
+            "max_log_file_size": max_log_file_size,
+        }
+        return await self._peer.call(
+            "configuration.set",
+            {key: value for key, value in params.items() if value is not None},
+        )
+
+    async def refresh(self) -> Configuration:
+        return await self._peer.call("configuration.refresh")

triggerware-1.0.0/src/triggerware/_connectors.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+import json
+from typing import Any, Literal, NotRequired, TypedDict
+
+import tw2_jsonrpc as rpc
+import yaml
+
+
+ConnectorRuntime = Literal["lua", "python", "node"]
+
+
+class ConnectorColumn(TypedDict):
+    name: str
+    type: str
+
+
+class ConnectorGenerator(TypedDict):
+    name: str
+    inputs: list[str]
+
+
+class ConnectorMetadata(TypedDict):
+    description: NotRequired[str]
+    columns: list[ConnectorColumn]
+    generators: list[ConnectorGenerator]
+    config_schema: NotRequired[dict[str, Any]]
+
+
+class ConnectorExtension(TypedDict):
+    name: str
+    tag: NotRequired[str]
+
+
+class Connector(TypedDict):
+    name: str
+    meta: ConnectorMetadata
+    code: str
+    runtime: NotRequired[ConnectorRuntime]
+    extension: NotRequired[ConnectorExtension]
+    configured: bool
+
+
+class ConnectorsService:
+    def __init__(self, peer: rpc.Peer):
+        self._peer = peer
+
+    async def create(
+        self,
+        name: str,
+        *,
+        prompt: str | None = None,
+        code: str | None = None,
+        meta: ConnectorMetadata | str | None = None,
+        runtime: ConnectorRuntime | None = None,
+    ) -> Connector:
+        connector = await self._peer.call(
+            "connectors.create",
+            self._definition_params(
+                name=name,
+                prompt=prompt,
+                code=code,
+                meta=meta,
+                runtime=runtime,
+            ),
+        )
+        connector["name"] = name
+        return connector
+
+    async def get(self, name: str) -> Connector:
+        connector = await self._peer.call("connectors.get", {"name": name})
+        connector["name"] = name
+        return connector
+
+    async def update(
+        self,
+        name: str,
+        *,
+        prompt: str | None = None,
+        code: str | None = None,
+        meta: ConnectorMetadata | str | None = None,
+        runtime: ConnectorRuntime | None = None,
+    ) -> Connector:
+        connector = await self._peer.call(
+            "connectors.update",
+            self._definition_params(
+                name=name,
+                prompt=prompt,
+                code=code,
+                meta=meta,
+                runtime=runtime,
+            ),
+        )
+        connector["name"] = name
+        return connector
+
+    async def list(self) -> list[str]:
+        response = await self._peer.call("connectors.list")
+        return response["connectors"]
+
+    async def delete(self, name: str) -> None:
+        await self._peer.call("connectors.delete", {"name": name})
+
+    async def sync(
+        self,
+        *,
+        connectors: list[str] | None = None,
+        extensions: list[str] | None = None,
+    ) -> None:
+        params = {
+            "connectors": connectors,
+            "extensions": extensions,
+        }
+        await self._peer.call(
+            "connectors.sync",
+            {key: value for key, value in params.items() if value is not None},
+        )
+
+    async def configure(self, connector: str | Connector, **config: Any) -> None:
+        if isinstance(connector, str):
+            name = connector
+            attached_connector = None
+        else:
+            name = connector["name"]
+            attached_connector = connector
+
+        await self._peer.call(
+            "connectors.configure",
+            {
+                "name": name,
+                "config": config,
+            },
+        )
+
+        if attached_connector is not None:
+            attached_connector["configured"] = True
+
+    def _definition_params(
+        self,
+        *,
+        name: str,
+        prompt: str | None,
+        code: str | None,
+        meta: ConnectorMetadata | str | None,
+        runtime: ConnectorRuntime | None,
+    ) -> dict[str, Any]:
+        params: dict[str, Any] = {"name": name}
+
+        if prompt is not None:
+            params["prompt"] = prompt
+        else:
+            if code is None or meta is None:
+                raise ValueError("either prompt or both code and meta must be supplied")
+            params["code"] = code
+            params["meta"] = connector_metadata_from_string(meta) if isinstance(meta, str) else meta
+
+        if runtime is not None:
+            params["runtime"] = runtime
+
+        return params
+
+
+def connector_metadata_from_string(contents: str) -> ConnectorMetadata:
+    try:
+        parsed = yaml.safe_load(contents)
+    except yaml.YAMLError:
+        parsed = json.loads(contents)
+
+    if not isinstance(parsed, dict):
+        raise ValueError("connector metadata must be an object")
+    return parsed  # type: ignore[return-value]

triggerware-1.0.0/src/triggerware/_cursors.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from typing import Any, NotRequired, TypedDict
+
+import tw2_jsonrpc as rpc
+
+
+class CursorColumn(TypedDict):
+    name: str
+    type: str
+
+
+class CursorOpen(TypedDict):
+    sql: str
+    signature: list[CursorColumn]
+    rows: list[list[Any]]
+    cursor: str
+    exhausted: bool
+
+
+class CursorFetch(TypedDict):
+    rows: list[list[Any]]
+    exhausted: bool
+
+
+class Cursor:
+    def __init__(
+        self,
+        peer: rpc.Peer,
+        *,
+        cursor: str,
+        sql: str,
+        signature: list[CursorColumn],
+        rows: list[list[Any]],
+        exhausted: bool,
+    ):
+        self._peer = peer
+        self._cursor = cursor
+        self.sql = sql
+        self.signature = signature
+        self.exhausted = exhausted
+        self._cache = rows
+        self._cache_position = 0
+
+    async def fetch(self) -> list[list[Any]]:
+        if self.exhausted:
+            return []
+
+        response: CursorFetch = await self._peer.call(
+            "cursors.fetch",
+            {"cursor": self._cursor},
+        )
+        self.exhausted = response["exhausted"]
+        self._cache.extend(response["rows"])
+        return response["rows"]
+
+    async def close(self) -> None:
+        await self._peer.call("cursors.close", {"cursor": self._cursor})
+        self.exhausted = True
+
+    def __aiter__(self) -> Cursor:
+        return self
+
+    async def __anext__(self) -> list[Any]:
+        if self._cache_position < len(self._cache):
+            row = self._cache[self._cache_position]
+            self._cache_position += 1
+            return row
+
+        if self.exhausted:
+            raise StopAsyncIteration
+
+        await self.fetch()
+
+        if self._cache_position < len(self._cache):
+            row = self._cache[self._cache_position]
+            self._cache_position += 1
+            return row
+
+        raise StopAsyncIteration
+
+
+class CursorsService:
+    def __init__(self, peer: rpc.Peer):
+        self._peer = peer
+
+    async def open(
+        self,
+        *,
+        sql: str | None = None,
+        prompt: str | None = None,
+        batch_size: int | None = None,
+        timeout_ms: int | None = None,
+    ) -> Cursor:
+        params = _run_params(
+            sql=sql,
+            prompt=prompt,
+            batch_size=batch_size,
+            timeout_ms=timeout_ms,
+        )
+        response: CursorOpen = await self._peer.call("cursors.open", params)
+        return Cursor(
+            self._peer,
+            cursor=response["cursor"],
+            sql=response["sql"],
+            signature=response["signature"],
+            rows=response["rows"],
+            exhausted=response["exhausted"],
+        )
+
+
+def _run_params(**values: Any) -> dict[str, Any]:
+    return {key: value for key, value in values.items() if value is not None}

triggerware-1.0.0/src/triggerware/_extensions.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from typing import Any, Literal, NotRequired, TypedDict
+
+import tw2_jsonrpc as rpc
+
+
+ExtensionRuntime = Literal["lua", "python", "node"]
+
+
+class Extension(TypedDict):
+    name: str
+    tag: NotRequired[str]
+    config: dict[str, Any] | None
+    connectors: list[str]
+
+
+class ExtensionDescription(TypedDict):
+    description: str
+    config_schema: dict[str, Any]
+    runtime: NotRequired[ExtensionRuntime]
+    dependencies: NotRequired[list[str]]
+    connectors: list[str]
+
+
+class ExtensionsService:
+    def __init__(self, peer: rpc.Peer):
+        self._peer = peer
+
+    async def install(
+        self,
+        *,
+        name: str | None = None,
+        url: str | None = None,
+        tag: str | None = None,
+        config: dict[str, Any] | None = None,
+    ) -> list[str]:
+        response = await self._peer.call(
+            "extensions.install",
+            _extension_params(name=name, url=url, tag=tag, config=config or {}),
+        )
+        return response["connectors"]
+
+    async def get(self, name: str, *, tag: str | None = None) -> Extension:
+        response = await self._peer.call(
+            "extensions.get",
+            _extension_params(name=name, tag=tag),
+        )
+        extension: Extension = {
+            "name": name,
+            "config": response["config"],
+            "connectors": response["connectors"],
+        }
+        if tag is not None:
+            extension["tag"] = tag
+        return extension
+
+    async def list(self) -> list[str]:
+        response = await self._peer.call("extensions.list")
+        return response["extensions"]
+
+    async def configure(
+        self,
+        name: str,
+        *,
+        tag: str | None = None,
+        config: dict[str, Any],
+    ) -> None:
+        await self._peer.call(
+            "extensions.configure",
+            _extension_params(name=name, tag=tag, config=config),
+        )
+
+    async def catalog(self) -> list[str]:
+        response = await self._peer.call("extensions.catalog")
+        return response["extensions"]
+
+    async def describe(
+        self,
+        *,
+        name: str | None = None,
+        url: str | None = None,
+    ) -> ExtensionDescription:
+        return await self._peer.call(
+            "extensions.describe",
+            _extension_params(name=name, url=url),
+        )
+
+    async def uninstall(self, name: str, *, tag: str | None = None) -> None:
+        await self._peer.call(
+            "extensions.uninstall",
+            _extension_params(name=name, tag=tag),
+        )
+
+
+def _extension_params(**values: Any) -> dict[str, Any]:
+    return {key: value for key, value in values.items() if value is not None}

triggerware-1.0.0/src/triggerware/_logging.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import Literal
+
+import tw2_jsonrpc as rpc
+
+
+LogLevel = Literal["debug", "info", "error"]
+
+
+class LoggingService:
+    def __init__(self, peer: rpc.Peer):
+        self._peer = peer
+
+    async def set(self, level: LogLevel) -> None:
+        await self._peer.call("logging.set", {"level": level})

triggerware-1.0.0/src/triggerware/_prompts.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import tw2_jsonrpc as rpc
+
+
+class PromptsService:
+    def __init__(self, peer: rpc.Peer):
+        self._peer = peer
+
+    async def get(self, name: str) -> str:
+        response = await self._peer.call("prompts.get", {"name": name})
+        return response["prompt"]
+
+    async def set(self, name: str, prompt: str) -> None:
+        await self._peer.call(
+            "prompts.set",
+            {
+                "name": name,
+                "prompt": prompt,
+            },
+        )
+
+    async def reset(self, name: str | None = None) -> None:
+        params = {} if name is None else {"name": name}
+        await self._peer.call("prompts.reset", params)