langbot-plugin 0.1.0__py3-none-any.whl

langbot_plugin/cli/__init__.py

@@ -0,0 +1,35 @@
+import argparse
+from langbot_plugin.version import __version__
+from langbot_plugin.runtime import __main__ as runtime_main
+
+
+def main():
+    parser = argparse.ArgumentParser(description="LangBot Plugin CLI")
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    version_parser = subparsers.add_parser("ver", help="Show the version of the CLI")
+
+    init_parser = subparsers.add_parser("init", help="Initialize a new plugin")
+    init_parser.add_argument(
+        "--name", "-n", action="store", type=str, help="The name of the plugin"
+    )
+
+    runtime_parser = subparsers.add_parser("rt", help="Run the runtime")
+    runtime_parser.add_argument(
+        "--stdio-control", "-s", action="store_true", default=False
+    )
+    runtime_parser.add_argument("--ws-control-port", type=int, default=5400)
+    runtime_parser.add_argument("--ws-debug-port", type=int, default=5401)
+
+    args = parser.parse_args()
+
+    match args.command:
+        case "ver":
+            print(f"LangBot Plugin CLI v{__version__}")
+        case "init":
+            print(f"Initializing plugin {args.name}")
+        case "rt":
+            runtime_main.main(args)
+        case _:
+            print(f"Unknown command: {args.command}")

langbot_plugin/cli/command.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+import abc
+
+
+class CLICommand(abc.ABC):
+    @abc.abstractmethod
+    def run(self):
+        pass

langbot_plugin/entities/io/errors.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+
+class ConnectionClosedError(Exception):
+    """The connection is closed."""
+
+    def __init__(self, message: str):
+        self.message = message
+
+    def __str__(self):
+        return self.message
+
+
+class ActionCallTimeoutError(Exception):
+    """The action call timed out."""
+
+    def __init__(self, message: str):
+        self.message = message
+
+    def __str__(self):
+        return self.message
+
+
+class ActionCallError(Exception):
+    """The action call failed."""
+
+    def __init__(self, message: str):
+        self.message = message
+
+    def __str__(self):
+        return self.message

langbot_plugin/entities/io/req.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+import pydantic
+from typing import Any
+
+
+class ActionRequest(pydantic.BaseModel):
+    seq_id: int = pydantic.Field(..., description="The sequence id of the request")
+    action: str
+    data: dict[str, Any]
+
+    @classmethod
+    def make_request(
+        cls, seq_id: int, action: str, data: dict[str, Any]
+    ) -> ActionRequest:
+        return cls(seq_id=seq_id, action=action, data=data)

langbot_plugin/entities/io/resp.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import pydantic
+from typing import Any, Optional
+
+
+class ActionResponse(pydantic.BaseModel):
+    seq_id: Optional[int] = None
+    code: int = pydantic.Field(..., description="The code of the response")
+    message: str = pydantic.Field(..., description="The message of the response")
+    data: dict[str, Any] = pydantic.Field(..., description="The data of the response")
+
+    @classmethod
+    def success(cls, data: dict[str, Any]) -> ActionResponse:
+        return cls(seq_id=0, code=0, message="success", data=data)
+
+    @classmethod
+    def error(cls, message: str) -> ActionResponse:
+        return cls(code=1, message=message, data={})

langbot_plugin/runtime/__main__.py

@@ -0,0 +1,10 @@
+# handler for command
+import asyncio
+import argparse
+
+from langbot_plugin.runtime.app import Application
+
+
+def main(args: argparse.Namespace):
+    app = Application(args)
+    asyncio.run(app.run())

langbot_plugin/runtime/app.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import argparse
+from enum import Enum
+
+import asyncio
+
+from langbot_plugin.runtime.controller.stdio import server as stdio_controller_server
+from langbot_plugin.runtime.controller.ws import server as ws_controller_server
+from langbot_plugin.runtime.io import handler
+
+
+class ControlConnectionMode(Enum):
+    STDIO = "stdio"
+    WS = "ws"
+
+
+class Application:
+    """Runtime application context."""
+
+    handler_manager: handler.HandlerManager
+
+    control_connection_mode: ControlConnectionMode
+
+    stdio_server: stdio_controller_server.StdioServer | None = (
+        None  # stdio control server
+    )
+    ws_server: ws_controller_server.WebSocketServer | None = (
+        None  # ws control/debug server
+    )
+
+    def __init__(self, args: argparse.Namespace):
+        self.args = args
+        self.handler_manager = handler.HandlerManager()
+
+        if args.stdio_control:
+            self.control_connection_mode = ControlConnectionMode.STDIO
+        else:
+            self.control_connection_mode = ControlConnectionMode.WS
+
+        # build controllers layer
+        if self.control_connection_mode == ControlConnectionMode.STDIO:
+            self.stdio_server = stdio_controller_server.StdioServer(
+                self.handler_manager
+            )
+
+        self.ws_server = ws_controller_server.WebSocketServer(
+            self.args.ws_control_port, self.args.ws_debug_port, self.handler_manager
+        )
+
+    async def run(self):
+        tasks = []
+
+        if self.stdio_server:
+            tasks.append(self.stdio_server.run())
+
+        if self.ws_server:
+            tasks.append(self.ws_server.run())
+
+        await asyncio.gather(*tasks)

langbot_plugin/runtime/controller/stdio/server.py

@@ -0,0 +1,18 @@
+# Stdio server for LangBot control connection
+from __future__ import annotations
+
+from langbot_plugin.runtime.io.connections import stdio as stdio_connection
+from langbot_plugin.runtime.io.handlers import control as control_handler
+from langbot_plugin.runtime.io import handler as io_handler
+
+
+class StdioServer:
+    def __init__(self, handler_manager: io_handler.HandlerManager):
+        self.handler_manager = handler_manager
+
+    async def run(self):
+        print("Starting Stdio server")
+        connection = stdio_connection.StdioConnection()
+        handler = control_handler.ControlConnectionHandler(connection)
+        task = self.handler_manager.set_control_handler(handler)
+        await task

langbot_plugin/runtime/controller/ws/server.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import asyncio
+import websockets
+
+from langbot_plugin.runtime.io.connections import ws as ws_connection
+from langbot_plugin.runtime.io.handlers import control as control_handler
+from langbot_plugin.runtime.io import handler as io_handler
+
+
+class ControlConnectionWebSocketServer:
+    """The server for control connection WebSocket connections."""
+
+    def __init__(self, port: int, handler_manager: io_handler.HandlerManager):
+        self.port = port
+        self.handler_manager = handler_manager
+
+    async def run(self):
+        server = await websockets.serve(self.handle_connection, "0.0.0.0", self.port)
+        await server.wait_closed()
+
+    async def handle_connection(self, websocket: websockets.ServerConnection):
+        print(f"New control connection from {websocket.remote_address}")
+        connection = ws_connection.WebSocketConnection(websocket)
+        handler = control_handler.ControlConnectionHandler(connection)
+        task = self.handler_manager.set_control_handler(handler)
+        await task
+
+
+class DebugConnectionWebSocketServer:
+    """The server for debug connection WebSocket connections."""
+
+    def __init__(self, port: int, handler_manager: io_handler.HandlerManager):
+        self.port = port
+        self.handler_manager = handler_manager
+
+    async def run(self):
+        server = await websockets.serve(self.handle_connection, "0.0.0.0", self.port)
+        await server.wait_closed()
+
+    async def handle_connection(self, websocket: websockets.ServerConnection):
+        print(f"New connection from {websocket.remote_address}")
+        await websocket.send("Hello, world!")
+        await websocket.close()
+
+
+class WebSocketServer:
+    """The server for control connection WebSocket connections."""
+
+    def __init__(
+        self,
+        control_port: int,
+        debug_port: int,
+        handler_manager: io_handler.HandlerManager,
+    ):
+        self.control_port = control_port
+        self.debug_port = debug_port
+        self.handler_manager = handler_manager
+
+    async def run(self):
+        print(
+            f"Starting WebSocket server on port {self.control_port} for control connections"
+        )
+        print(
+            f"Starting WebSocket server on port {self.debug_port} for debug connections"
+        )
+        control_server = ControlConnectionWebSocketServer(
+            self.control_port, self.handler_manager
+        )
+        debug_server = DebugConnectionWebSocketServer(
+            self.debug_port, self.handler_manager
+        )
+
+        await asyncio.gather(control_server.run(), debug_server.run())

langbot_plugin/runtime/io/connection.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import abc
+
+
+class Connection(abc.ABC):
+    """The abstract base class for all connections."""
+
+    @abc.abstractmethod
+    async def send(self, message: str) -> None:
+        pass
+
+    @abc.abstractmethod
+    async def receive(self) -> str:
+        pass
+
+    @abc.abstractmethod
+    async def close(self) -> None:
+        pass

langbot_plugin/runtime/io/connections/stdio.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import asyncio
+
+from langbot_plugin.runtime.io import connection
+
+
+class StdioConnection(connection.Connection):
+    """The connection for Stdio connections."""
+
+    def __init__(self):
+        pass
+
+    async def send(self, message: str) -> None:
+        print(message)
+
+    async def receive(self) -> str:
+        while True:
+            s = await asyncio.to_thread(input)
+            if s.startswith("{") and s.endswith("}"):
+                return s
+
+    async def close(self) -> None:
+        pass

langbot_plugin/runtime/io/connections/ws.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import websockets
+
+from langbot_plugin.runtime.io import connection as io_connection
+from langbot_plugin.entities.io.errors import ConnectionClosedError
+
+
+class WebSocketConnection(io_connection.Connection):
+    """The connection for WebSocket connections."""
+
+    def __init__(self, websocket: websockets.ServerConnection):
+        self.websocket = websocket
+
+    async def send(self, message: str) -> None:
+        await self.websocket.send(message, text=True)
+
+    async def receive(self) -> str:
+        try:
+            data = await self.websocket.recv(decode=True)
+            return data
+        except websockets.exceptions.ConnectionClosed:
+            raise ConnectionClosedError("Connection closed")
+
+    async def close(self) -> None:
+        await self.websocket.close()

langbot_plugin/runtime/io/handler.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import abc
+import asyncio
+import json
+from typing import Callable, Any, Dict, Awaitable, Coroutine
+
+import pydantic
+
+from langbot_plugin.runtime.io import connection
+from langbot_plugin.entities.io.req import ActionRequest
+from langbot_plugin.entities.io.resp import ActionResponse
+from langbot_plugin.entities.io.errors import (
+    ConnectionClosedError,
+    ActionCallTimeoutError,
+    ActionCallError,
+)
+
+
+class Handler(abc.ABC):
+    """The abstract base class for all handlers."""
+
+    conn: connection.Connection
+
+    actions: dict[str, Callable[[dict[str, Any]], Coroutine[Any, Any, ActionResponse]]]
+
+    resp_waiters: dict[int, asyncio.Future[ActionResponse]] = {}
+
+    seq_id_index: int = 0
+
+    def __init__(self, connection: connection.Connection):
+        self.conn = connection
+        self.actions = {}
+
+    async def run(self) -> None:
+        while True:
+            message = None
+            try:
+                message = await self.conn.receive()
+            except ConnectionClosedError:
+                print("Connection closed")
+                break
+            if message is None:
+                continue
+
+            async def handle_message(message: str):
+                # sh*t, i dont really know how to use generic type here
+                # so just use dict[str, Any] for now
+                req_data = json.loads(message)
+                seq_id = req_data["seq_id"] if "seq_id" in req_data else -1
+
+                if "action" in req_data:  # action request from peer
+                    try:
+                        if req_data["action"] not in self.actions:
+                            raise ValueError(f"Action {req_data['action']} not found")
+
+                        response = await self.actions[req_data["action"]](
+                            req_data["data"]
+                        )
+                        response.seq_id = seq_id
+                        await self.conn.send(json.dumps(response.model_dump()))
+                    except Exception as e:
+                        error_response = ActionResponse.error(
+                            f"{e.__class__.__name__}: {str(e)}"
+                        )
+                        error_response.seq_id = seq_id
+                        await self.conn.send(json.dumps(error_response.model_dump()))
+
+                elif "code" in req_data:  # action response from peer
+                    if seq_id in self.resp_waiters:
+                        response = ActionResponse.success(req_data["data"])
+                        response.seq_id = seq_id
+                        self.resp_waiters[seq_id].set_result(response)
+                        del self.resp_waiters[seq_id]
+
+            asyncio.create_task(handle_message(message))
+
+    async def call_action(
+        self, action: str, data: dict[str, Any], timeout: float = 10.0
+    ) -> dict[str, Any]:
+        """Actively call an action provided by the peer, and wait for the response."""
+        self.seq_id_index += 1
+        request = ActionRequest.make_request(self.seq_id_index, action, data)
+        await self.conn.send(json.dumps(request.model_dump()))
+        # wait for response
+        future = asyncio.Future[ActionResponse]()
+        self.resp_waiters[self.seq_id_index] = future
+        try:
+            response = await asyncio.wait_for(future, timeout)
+            if response.code != 0:
+                raise ActionCallError(f"{response.message}")
+            return response.data
+        except asyncio.TimeoutError:
+            raise ActionCallTimeoutError(f"Action {action} call timed out")
+        except Exception as e:
+            raise ActionCallError(f"{e.__class__.__name__}: {str(e)}")
+
+    # decorator to register an action
+    def action(
+        self, name: str
+    ) -> Callable[
+        [Callable[[dict[str, Any]], Coroutine[Any, Any, ActionResponse]]],
+        Callable[[dict[str, Any]], Coroutine[Any, Any, ActionResponse]],
+    ]:
+        def decorator(
+            func: Callable[[dict[str, Any]], Coroutine[Any, Any, ActionResponse]],
+        ) -> Callable[[dict[str, Any]], Coroutine[Any, Any, ActionResponse]]:
+            self.actions[name] = func
+            return func
+
+        return decorator
+
+
+class HandlerManager:
+    """The manager for handlers."""
+
+    control_handler: Handler
+    plugin_handlers: dict[str, Handler]
+
+    def __init__(self):
+        self.langbot_handler = None
+        self.plugin_handlers = {}
+
+    def set_control_handler(self, handler: Handler) -> asyncio.Task:
+        self.control_handler = handler
+        return asyncio.create_task(handler.run())
+
+    def set_plugin_handler(self, name: str, handler: Handler) -> None:
+        self.plugin_handlers[name] = handler

langbot_plugin/runtime/io/handlers/control.py

@@ -0,0 +1,23 @@
+# handle connection from LangBot
+from __future__ import annotations
+
+from typing import Any
+
+from langbot_plugin.runtime.io import handler, connection
+
+
+class ControlConnectionHandler(handler.Handler):
+    """The handler for control connection."""
+
+    def __init__(self, connection: connection.Connection):
+        super().__init__(connection)
+
+        @self.action("ping")
+        async def ping(data: dict[str, Any]) -> handler.ActionResponse:
+            resp = await self.call_action("ping", {}, 10)
+            print("received resp: ", resp)
+            return handler.ActionResponse.success({"message": "pong"})
+
+
+# {"action": "ping", "data": {}, "seq_id": 1}
+# {"code": 0, "message": "ok", "data": {"msg": "hello"}, "seq_id": 1}

langbot_plugin/utils/importutil.py

@@ -0,0 +1,38 @@
+import importlib
+import importlib.util
+import os
+import typing
+
+
+def import_modules_in_pkg(pkg: typing.Any) -> None:
+    """
+    导入一个包内的所有模块
+    Args:
+        pkg: 要导入的包对象
+    """
+    pkg_path = os.path.dirname(pkg.__file__)
+    import_dir(pkg_path)
+
+
+def import_modules_in_pkgs(pkgs: typing.List) -> None:
+    for pkg in pkgs:
+        import_modules_in_pkg(pkg)
+
+
+def import_dot_style_dir(dot_sep_path: str):
+    sec = dot_sep_path.split(".")
+
+    return import_dir(os.path.join(*sec))
+
+
+def import_dir(path: str):
+    for file in os.listdir(path):
+        if file.endswith(".py") and file != "__init__.py":
+            full_path = os.path.join(path, file)
+            rel_path = full_path.replace(
+                os.path.dirname(os.path.dirname(os.path.dirname(__file__))), ""
+            )
+            rel_path = rel_path[1:]
+            rel_path = rel_path.replace("/", ".")[:-3]
+            rel_path = rel_path.replace("\\", ".")
+            importlib.import_module(rel_path)

langbot_plugin/version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

langbot_plugin-0.1.0.dist-info/METADATA

@@ -0,0 +1,30 @@
+Metadata-Version: 2.4
+Name: langbot-plugin
+Version: 0.1.0
+Summary: This package contains the SDK, CLI for building plugins for LangBot, plus the runtime for hosting LangBot plugins
+Author-email: Junyan Qin <rockchinq@gmail.com>
+Requires-Python: >=3.10
+Requires-Dist: mypy>=1.16.0
+Requires-Dist: pydantic>=2.11.5
+Requires-Dist: ruff>=0.11.12
+Requires-Dist: textual>=3.2.0
+Requires-Dist: websockets>=15.0.1
+Description-Content-Type: text/markdown
+
+# langbot-plugin-sdk
+
+## Connection
+
+### with LangBot
+
+- Stdio
+    - Passively
+- WebSocket
+    - Server: `:5400 /control/ws`
+
+### with Plugins
+
+- Stdio
+    - Actively
+- WebSocket (Debug)
+    - Server: `:5401 /debug/ws`

langbot_plugin-0.1.0.dist-info/RECORD

@@ -0,0 +1,34 @@
+langbot_plugin/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langbot_plugin/version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+langbot_plugin/api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langbot_plugin/cli/__init__.py,sha256=YljXbeWxe1_FMqlfpAJKY7wIht4DNBB5APY6N24wfs8,1214
+langbot_plugin/cli/command.py,sha256=kJhzBn7yiy0qnTWpyzAJ-IVgeyC92y1vy94Jheh5gus,132
+langbot_plugin/cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langbot_plugin/entities/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langbot_plugin/entities/io/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langbot_plugin/entities/io/errors.py,sha256=c0SVQsA2Jbv2hNdqgt2BiqnZ4kgyAMz5gJC1iSb98zE,629
+langbot_plugin/entities/io/req.py,sha256=bnqmdtKGh6zYFopiUt6qJljwjRWrxHNSe2XMcDFA0U8,427
+langbot_plugin/entities/io/resp.py,sha256=ac_0F1k02pxaYH8z1k2WEGt7Hn9CXso7yaAgHNOJTNo,677
+langbot_plugin/runtime/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langbot_plugin/runtime/__main__.py,sha256=d1_jWWW1KdmqloXjKXT-_8nmmIY1j8q49jlzcNLMNSw,198
+langbot_plugin/runtime/app.py,sha256=SyMzhI4uFudS4mjzcoK6Uj1-bYLjpgevT0IY6apHyG0,1691
+langbot_plugin/runtime/controller/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langbot_plugin/runtime/controller/stdio/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langbot_plugin/runtime/controller/stdio/server.py,sha256=qhLFEvd9h9YPRa2wTtzkTuHF4o_YI3uB7uKcKiGa_L0,704
+langbot_plugin/runtime/controller/ws/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langbot_plugin/runtime/controller/ws/server.py,sha256=f1aptaveyN99Y7xOkQld-RzDOWciq4OV29bJbEXcAQs,2610
+langbot_plugin/runtime/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langbot_plugin/runtime/io/connection.py,sha256=YGqDJrou55kkkjinlhZGqMi4Hg27eJxqtLU8kWFjRdw,364
+langbot_plugin/runtime/io/handler.py,sha256=R3TKR2ZCutqv8c-LTFY4XfgmitcXjlXVFhGZympIpH4,4723
+langbot_plugin/runtime/io/connections/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langbot_plugin/runtime/io/connections/stdio.py,sha256=VZownx7jCAc6eVn-TY18I8yQjkxeqsdQTrQsLtJr3-E,539
+langbot_plugin/runtime/io/connections/ws.py,sha256=3NTIrlwA8r4VXi5t7StrmKMVjUvsSx3zPJewDTTz-_A,820
+langbot_plugin/runtime/io/handlers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langbot_plugin/runtime/io/handlers/control.py,sha256=sE4LNwr_sX0lsMgckbGCkWcAK-AEckF0mieloM8h7wI,737
+langbot_plugin/runtime/service/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langbot_plugin/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langbot_plugin/utils/importutil.py,sha256=1FLb67yL12UoOhVOo7rwrNroIkhFkPTqJG4JxuBuWm8,1018
+langbot_plugin-0.1.0.dist-info/METADATA,sha256=BKL2QcTG3PZ0U4klwigV4Ux39BI1mmPEEUN87FUmUBY,664
+langbot_plugin-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+langbot_plugin-0.1.0.dist-info/entry_points.txt,sha256=EfG3gGtCzia5YAO0Llvi4YqfaObIw-Kp-CkVqTEYcbE,48
+langbot_plugin-0.1.0.dist-info/RECORD,,

langbot_plugin-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

langbot_plugin-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+lbp = langbot_plugin.cli:main