TGO Plugin Python SDK

Python SDK for fast development of TGO (The Great Open) customer service system plugins.

Features

• Language Agnostic: TGO plugins communicate over Unix Socket using JSON-RPC 2.0.
• Easy to Use: Clean, decorator-like or override-based API.
• Type Safe: Fully powered by Pydantic v2 for data validation and IDE autocompletion.
• UI Builders: Chainable API to build complex JSON-UI templates (KeyValue, Table, Group, etc.).
• Action Helpers: Simple methods to return system actions like open_url or insert_text.

Installation

# Clone the repository
git clone https://github.com/tgoai/tgo.git
cd repos/tgo-plugin-sdk/tgo-plugin-python
pip install .

Quick Start

Create a main.py:

from tgo_plugin import TGOPlugin, Capability, RenderContext, KeyValue, Action

class MyPlugin(TGOPlugin):
    name = "hello-plugin"
    version = "1.0.0"
    
    # 1. Define capabilities
    capabilities = [
        Capability.visitor_panel(title="My Info", icon="info")
    ]

    # 2. Handle render requests
    def on_visitor_panel_render(self, ctx: RenderContext):
        return KeyValue(title="Visitor Info") \
            .add("Name", ctx.visitor.name if ctx.visitor else "Unknown") \
            .add("ID", ctx.visitor_id)

    # 3. Handle events
    def on_visitor_panel_event(self, ctx, event):
        return Action.show_toast("Clicked!")

if __name__ == "__main__":
    MyPlugin().run()

Local Debugging

When running TGO via Docker Compose on macOS, Unix socket bind mounts are not accessible from the host. You should use TCP port 8005 for local debugging:

if __name__ == "__main__":
    # Connect to the exposed TCP port
    MyPlugin(tcp_addr="localhost:8005").run()

For Linux users, you can still use the mounted socket path:

if __name__ == "__main__":
    # Connect to the mounted socket path
    MyPlugin(socket_path="./data/tgo-api/run/tgo.sock").run()

Documentation

For full documentation on protocol and UI templates, please visit: https://tgo.ai/docs/plugin/overview

License

MIT