langbot-plugin 0.1.0__tar.gz

langbot_plugin-0.1.0/.gitignore

@@ -0,0 +1,174 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc

langbot_plugin-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

langbot_plugin-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,17 @@
+# 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/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "langbot-plugin"
+version = "0.1.0"
+description = "This package contains the SDK, CLI for building plugins for LangBot, plus the runtime for hosting LangBot plugins"
+readme = "README.md"
+authors = [
+    { name = "Junyan Qin", email = "rockchinq@gmail.com" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "mypy>=1.16.0",
+    "pydantic>=2.11.5",
+    "ruff>=0.11.12",
+    "textual>=3.2.0",
+    "websockets>=15.0.1",
+]
+
+[project.scripts]
+lbp = "langbot_plugin.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

langbot_plugin-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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()