golem-agent-sdk 0.1.0__tar.gz

golem_agent_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.3
+Name: golem-agent-sdk
+Version: 0.1.0
+Summary: Python SDK for Golem extensions
+Author: Nawaz Gafar
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# golem-sdk
+
+Python SDK for [Golem](https://github.com/terracotta4u/golem) extensions (channels, providers, and other long-running processes).
+
+Install from PyPI:
+
+```sh
+uv add golem-agent-sdk
+```
+
+Or from this directory:
+
+```sh
+uv sync --dev
+```
+
+Import as `golem`. The wire protocol lives in Golem: [docs/extensions.md](https://github.com/terracotta4u/golem/blob/main/docs/extensions.md).
+
+```python
+from golem import Client, Extension, Provider
+
+client = Client.from_env()
+client.wait_ready()
+text = client.send(conversation_id, "telegram", "hello")
+```
+
+`post_turn` and `stream_turn` expose the same flow as SSE events (`log`, `done`, `error`).
+
+A provider extension binds a loopback callback, registers, and heartbeats:
+
+```python
+from golem import Extension, Message, Provider
+
+class Echo(Provider):
+    def chat(self, model, messages, tools=None) -> Message:
+        return Message(role="assistant", content=messages[-1].content)
+
+Extension.from_env("golem-echo").provider("echo", Echo()).run()
+```
+
+`task()` runs your own loop (a channel). `capability()` registers kinds Golem does not call.
+
+## Develop
+
+```sh
+uv sync --dev
+uv run pytest
+```

golem_agent_sdk-0.1.0/README.md

@@ -0,0 +1,48 @@
+# golem-sdk
+
+Python SDK for [Golem](https://github.com/terracotta4u/golem) extensions (channels, providers, and other long-running processes).
+
+Install from PyPI:
+
+```sh
+uv add golem-agent-sdk
+```
+
+Or from this directory:
+
+```sh
+uv sync --dev
+```
+
+Import as `golem`. The wire protocol lives in Golem: [docs/extensions.md](https://github.com/terracotta4u/golem/blob/main/docs/extensions.md).
+
+```python
+from golem import Client, Extension, Provider
+
+client = Client.from_env()
+client.wait_ready()
+text = client.send(conversation_id, "telegram", "hello")
+```
+
+`post_turn` and `stream_turn` expose the same flow as SSE events (`log`, `done`, `error`).
+
+A provider extension binds a loopback callback, registers, and heartbeats:
+
+```python
+from golem import Extension, Message, Provider
+
+class Echo(Provider):
+    def chat(self, model, messages, tools=None) -> Message:
+        return Message(role="assistant", content=messages[-1].content)
+
+Extension.from_env("golem-echo").provider("echo", Echo()).run()
+```
+
+`task()` runs your own loop (a channel). `capability()` registers kinds Golem does not call.
+
+## Develop
+
+```sh
+uv sync --dev
+uv run pytest
+```

golem_agent_sdk-0.1.0/golem/__init__.py

@@ -0,0 +1,28 @@
+from golem.client import Client, GolemError, TurnEvent
+from golem.extension import Extension
+from golem.provider import (
+    FunctionCall,
+    JSONSchema,
+    Message,
+    Provider,
+    ToolCall,
+    ToolDef,
+    UnsupportedFormat,
+)
+
+__all__ = [
+    "Client",
+    "Extension",
+    "FunctionCall",
+    "GolemError",
+    "JSONSchema",
+    "Message",
+    "Provider",
+    "ToolCall",
+    "ToolDef",
+    "TurnEvent",
+    "UnsupportedFormat",
+    "__version__",
+]
+
+__version__ = "0.1.0"

golem_agent_sdk-0.1.0/golem/client.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Iterator
+
+
+class GolemError(Exception):
+    def __init__(self, message: str, status: int | None = None) -> None:
+        super().__init__(message)
+        self.status = status
+
+
+@dataclass(frozen=True)
+class TurnEvent:
+    name: str
+    data: dict[str, Any]
+
+
+class Client:
+    def __init__(self, url: str, token: str = "") -> None:
+        self.url = url.rstrip("/")
+        self.token = token
+
+    @classmethod
+    def from_env(cls) -> Client:
+        url = os.environ.get("GOLEM_URL", "").strip() or "http://127.0.0.1:8743"
+        token = os.environ.get("GOLEM_TOKEN", "").strip()
+        return cls(url, token)
+
+    def wait_ready(self, timeout: float = 30.0) -> None:
+        deadline = time.monotonic() + timeout
+        last: Exception | None = None
+        while time.monotonic() < deadline:
+            try:
+                body = self._request("GET", "/v1/health")
+                if body.get("ok"):
+                    return
+                last = GolemError("golem health not ok")
+            except Exception as exc:
+                last = exc
+            time.sleep(0.4)
+        if last is None:
+            last = GolemError("golem not ready")
+        raise GolemError(f"golem not ready: {last}") from last
+
+    def post_turn(self, conversation_id: str, channel: str, text: str) -> str:
+        accepted = self._request(
+            "POST",
+            f"/v1/conversations/{conversation_id}/turns",
+            {"channel": channel, "text": text},
+        )
+        if accepted.get("error"):
+            raise GolemError(accepted["error"])
+        turn_id = accepted.get("id")
+        if not turn_id:
+            raise GolemError("missing turn id")
+        return str(turn_id)
+
+    def stream_turn(self, turn_id: str) -> Iterator[TurnEvent]:
+        req = urllib.request.Request(
+            self.url + f"/v1/turns/{turn_id}",
+            headers=self._headers(),
+            method="GET",
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=None) as resp:
+                for name, raw in _read_sse(resp):
+                    data = json.loads(raw) if raw else {}
+                    if not isinstance(data, dict):
+                        raise GolemError(f"invalid event data: {raw}")
+                    yield TurnEvent(name=name, data=data)
+                    if name in ("done", "error"):
+                        return
+        except urllib.error.HTTPError as exc:
+            raw = exc.read()
+            raise GolemError(
+                f"unexpected status {exc.code}: {raw.decode(errors='replace')}",
+                status=exc.code,
+            ) from exc
+        except urllib.error.URLError as exc:
+            raise GolemError(f"request failed: {exc.reason}") from exc
+        except json.JSONDecodeError as exc:
+            raise GolemError(f"invalid json: {exc}") from exc
+
+    def send(self, conversation_id: str, channel: str, text: str) -> str:
+        turn_id = self.post_turn(conversation_id, channel, text)
+        for ev in self.stream_turn(turn_id):
+            if ev.name == "done":
+                return str(ev.data.get("text") or "")
+            if ev.name == "error":
+                raise GolemError(str(ev.data.get("error") or "turn failed"))
+        raise GolemError("turn ended without done")
+
+    def register(self, name: str, callback_url: str, capabilities: list[dict[str, Any]]) -> None:
+        body = self._request(
+            "POST",
+            "/v1/extensions/register",
+            {"name": name, "callback_url": callback_url, "capabilities": capabilities},
+        )
+        if not isinstance(body, dict) or not body.get("ok"):
+            raise GolemError("register failed")
+
+    def heartbeat(self, name: str) -> None:
+        body = self._request("POST", "/v1/extensions/heartbeat", {"name": name})
+        if not isinstance(body, dict) or not body.get("ok"):
+            raise GolemError("heartbeat failed")
+
+    def _headers(self, body: dict[str, Any] | None = None) -> dict[str, str]:
+        headers: dict[str, str] = {}
+        if self.token:
+            headers["Authorization"] = "Bearer " + self.token
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+        return headers
+
+    def _request(self, method: str, path: str, body: dict[str, Any] | None = None) -> Any:
+        data = None
+        headers = self._headers(body)
+        if body is not None:
+            data = json.dumps(body).encode()
+        req = urllib.request.Request(
+            self.url + path,
+            data=data,
+            headers=headers,
+            method=method,
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=30) as resp:
+                raw = resp.read()
+        except urllib.error.HTTPError as exc:
+            raw = exc.read()
+            raise GolemError(
+                f"unexpected status {exc.code}: {raw.decode(errors='replace')}",
+                status=exc.code,
+            ) from exc
+        except urllib.error.URLError as exc:
+            raise GolemError(f"request failed: {exc.reason}") from exc
+        if not raw:
+            return {}
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise GolemError(f"invalid json: {raw.decode(errors='replace')}") from exc
+
+
+def _read_sse(resp: Any) -> Iterator[tuple[str, str]]:
+    event = "message"
+    data: list[str] = []
+    while True:
+        line = resp.readline()
+        if not line:
+            break
+        text = line.decode("utf-8", errors="replace").rstrip("\r\n")
+        if text == "":
+            if data:
+                yield event, "\n".join(data)
+            event = "message"
+            data = []
+            continue
+        if text.startswith(":"):
+            continue
+        if text.startswith("event:"):
+            event = text[6:].lstrip()
+        elif text.startswith("data:"):
+            value = text[5:]
+            if value.startswith(" "):
+                value = value[1:]
+            data.append(value)
+    if data:
+        yield event, "\n".join(data)

golem_agent_sdk-0.1.0/golem/extension.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+import json
+import signal
+import sys
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from types import FrameType
+from typing import Any, Callable
+
+from golem.client import Client, GolemError
+from golem.provider import JSONSchema, Message, Provider, ToolDef, UnsupportedFormat
+
+Task = Callable[[Client, threading.Event], None]
+
+
+class Extension:
+    def __init__(
+        self,
+        name: str,
+        client: Client | str | None = None,
+        token: str = "",
+        *,
+        heartbeat_interval: float = 10.0,
+    ) -> None:
+        name = name.strip()
+        if not name:
+            raise ValueError("name is required")
+        self.name = name
+        if isinstance(client, Client):
+            self.client = client
+        elif isinstance(client, str):
+            self.client = Client(client, token)
+        else:
+            self.client = Client.from_env()
+        self.heartbeat_interval = heartbeat_interval
+        self._provider_id = ""
+        self._provider: Provider | None = None
+        self._tasks: list[Task] = []
+        self._extra_caps: list[dict[str, Any]] = []
+
+    @classmethod
+    def from_env(cls, name: str, **kwargs: Any) -> Extension:
+        return cls(name, Client.from_env(), **kwargs)
+
+    def provider(self, provider_id: str, impl: Provider) -> Extension:
+        provider_id = provider_id.strip()
+        if not provider_id:
+            raise ValueError("provider id is required")
+        if self._provider is not None:
+            raise ValueError("provider already set")
+        self._provider_id = provider_id
+        self._provider = impl
+        return self
+
+    def capability(self, cap: dict[str, Any]) -> Extension:
+        self._extra_caps.append(cap)
+        return self
+
+    def task(self, fn: Task) -> Extension:
+        self._tasks.append(fn)
+        return self
+
+    def run(self, stop: threading.Event | None = None) -> None:
+        own_stop = stop is None
+        if stop is None:
+            stop = threading.Event()
+            if threading.current_thread() is threading.main_thread():
+                def handle(_signum: int, _frame: FrameType | None) -> None:
+                    stop.set()
+
+                signal.signal(signal.SIGINT, handle)
+                signal.signal(signal.SIGTERM, handle)
+
+        server = ThreadingHTTPServer(("127.0.0.1", 0), _handler(self))
+        callback = f"http://127.0.0.1:{server.server_address[1]}"
+        serving = threading.Thread(target=server.serve_forever, daemon=True)
+        serving.start()
+        try:
+            self._loop(callback, stop)
+        finally:
+            if own_stop:
+                stop.set()
+            server.shutdown()
+            serving.join(timeout=2)
+            server.server_close()
+
+    def _loop(self, callback: str, stop: threading.Event) -> None:
+        while not stop.is_set():
+            try:
+                self.client.wait_ready(timeout=5)
+                self._register(callback)
+                break
+            except GolemError as exc:
+                print(f"{self.name}: {exc}", file=sys.stderr, flush=True)
+                if stop.wait(2):
+                    return
+        else:
+            return
+
+        print(f"{self.name}: {callback} → {self.client.url}", file=sys.stderr, flush=True)
+        threading.Thread(target=self._heartbeat_loop, args=(callback, stop), daemon=True).start()
+        for fn in self._tasks:
+            threading.Thread(target=self._run_task, args=(fn, stop), daemon=True).start()
+        stop.wait()
+
+    def _register(self, callback: str) -> None:
+        self.client.register(self.name, callback, self._capabilities())
+
+    def _heartbeat_loop(self, callback: str, stop: threading.Event) -> None:
+        while not stop.wait(self.heartbeat_interval):
+            try:
+                self.client.heartbeat(self.name)
+            except GolemError as exc:
+                if exc.status == 404:
+                    try:
+                        self._register(callback)
+                    except GolemError:
+                        pass
+
+    def _run_task(self, fn: Task, stop: threading.Event) -> None:
+        try:
+            fn(self.client, stop)
+        except Exception as exc:
+            print(f"{self.name} task: {exc}", file=sys.stderr, flush=True)
+
+    def _capabilities(self) -> list[dict[str, Any]]:
+        caps: list[dict[str, Any]] = []
+        if self._provider is not None:
+            cap: dict[str, Any] = {"kind": "provider", "id": self._provider_id, "chat": True}
+            if _overrides(self._provider, "chat_structured"):
+                cap["structured"] = True
+            if _overrides(self._provider, "embed"):
+                cap["embed"] = True
+            caps.append(cap)
+        caps.extend(self._extra_caps)
+        return caps
+
+    def _dispatch(self, path: str, body: dict[str, Any]) -> tuple[int, dict[str, Any]]:
+        if self._provider is None:
+            return 404, _error("not found")
+        model = str(body.get("model") or "")
+        try:
+            if path == "/v1/chat":
+                msg = self._provider.chat(model, _messages(body), _tools(body))
+                return 200, msg.to_dict()
+            if path == "/v1/chat/structured":
+                raw = body.get("schema") if isinstance(body.get("schema"), dict) else {}
+                data = self._provider.chat_structured(model, _messages(body), JSONSchema.from_dict(raw))
+                return 200, {"data": data}
+            if path == "/v1/embed":
+                texts = body.get("texts") or []
+                if not isinstance(texts, list):
+                    return 400, _error("texts must be a list")
+                vectors = self._provider.embed(model, [str(t) for t in texts])
+                return 200, {"vectors": vectors}
+        except UnsupportedFormat as exc:
+            return 400, {"error": {"code": "unsupported_format", "message": str(exc) or "no json schema"}}
+        except NotImplementedError:
+            return 404, _error("not found")
+        except Exception as exc:
+            return 500, _error(str(exc))
+        return 404, _error("not found")
+
+
+def _overrides(provider: Provider, method: str) -> bool:
+    return getattr(type(provider), method) is not getattr(Provider, method)
+
+
+def _messages(body: dict[str, Any]) -> list[Message]:
+    out: list[Message] = []
+    for raw in body.get("messages") or []:
+        if isinstance(raw, dict):
+            out.append(Message.from_dict(raw))
+    return out
+
+
+def _tools(body: dict[str, Any]) -> list[ToolDef] | None:
+    raw = body.get("tools") or []
+    if not raw:
+        return None
+    return [ToolDef.from_dict(item) for item in raw if isinstance(item, dict)]
+
+
+def _error(message: str) -> dict[str, Any]:
+    return {"error": {"message": message}}
+
+
+def _handler(ext: Extension) -> type[BaseHTTPRequestHandler]:
+    class Handler(BaseHTTPRequestHandler):
+        protocol_version = "HTTP/1.1"
+
+        def log_message(self, format: str, *args: object) -> None:
+            return
+
+        def do_POST(self) -> None:
+            if not self._authorized():
+                self._write(401, _error("unauthorized"))
+                return
+            length = int(self.headers.get("Content-Length") or 0)
+            raw = self.rfile.read(length) if length else b""
+            if not raw:
+                body: dict[str, Any] = {}
+            else:
+                try:
+                    parsed = json.loads(raw)
+                except json.JSONDecodeError:
+                    self._write(400, _error("invalid json"))
+                    return
+                if not isinstance(parsed, dict):
+                    self._write(400, _error("invalid json"))
+                    return
+                body = parsed
+            status, payload = ext._dispatch(self.path, body)
+            self._write(status, payload)
+
+        def do_GET(self) -> None:
+            if not self._authorized():
+                self._write(401, _error("unauthorized"))
+                return
+            self._write(404, _error("not found"))
+
+        def _authorized(self) -> bool:
+            token = ext.client.token
+            if not token:
+                return True
+            return self.headers.get("Authorization") == "Bearer " + token
+
+        def _write(self, status: int, payload: dict[str, Any]) -> None:
+            raw = json.dumps(payload).encode()
+            self.send_response(status)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(raw)))
+            self.end_headers()
+            self.wfile.write(raw)
+
+    return Handler

golem_agent_sdk-0.1.0/golem/provider.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+
+class UnsupportedFormat(Exception):
+    pass
+
+
+@dataclass
+class FunctionCall:
+    name: str
+    arguments: str = ""
+
+
+@dataclass
+class ToolCall:
+    id: str
+    type: str = "function"
+    function: FunctionCall = field(default_factory=lambda: FunctionCall(""))
+
+
+@dataclass
+class Message:
+    role: str
+    content: str = ""
+    tool_calls: list[ToolCall] = field(default_factory=list)
+    tool_call_id: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Message:
+        calls: list[ToolCall] = []
+        for raw in data.get("tool_calls") or []:
+            if not isinstance(raw, dict):
+                continue
+            fn = raw.get("function") if isinstance(raw.get("function"), dict) else {}
+            calls.append(
+                ToolCall(
+                    id=str(raw.get("id") or ""),
+                    type=str(raw.get("type") or "function"),
+                    function=FunctionCall(
+                        name=str(fn.get("name") or ""),
+                        arguments=str(fn.get("arguments") or ""),
+                    ),
+                )
+            )
+        return cls(
+            role=str(data.get("role") or ""),
+            content=str(data.get("content") or ""),
+            tool_calls=calls,
+            tool_call_id=str(data.get("tool_call_id") or ""),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        out: dict[str, Any] = {"role": self.role}
+        if self.content:
+            out["content"] = self.content
+        if self.tool_calls:
+            out["tool_calls"] = [
+                {
+                    "id": call.id,
+                    "type": call.type,
+                    "function": {"name": call.function.name, "arguments": call.function.arguments},
+                }
+                for call in self.tool_calls
+            ]
+        if self.tool_call_id:
+            out["tool_call_id"] = self.tool_call_id
+        return out
+
+
+@dataclass
+class ToolDef:
+    name: str
+    description: str = ""
+    parameters: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ToolDef:
+        params = data.get("parameters")
+        return cls(
+            name=str(data.get("name") or ""),
+            description=str(data.get("description") or ""),
+            parameters=params if isinstance(params, dict) else {},
+        )
+
+
+@dataclass
+class JSONSchema:
+    name: str
+    strict: bool = False
+    schema: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> JSONSchema:
+        inner = data.get("schema")
+        return cls(
+            name=str(data.get("name") or ""),
+            strict=bool(data.get("strict")),
+            schema=inner if isinstance(inner, dict) else {},
+        )
+
+
+class Provider(ABC):
+    @abstractmethod
+    def chat(self, model: str, messages: list[Message], tools: list[ToolDef] | None = None) -> Message:
+        raise NotImplementedError
+
+    def chat_structured(self, model: str, messages: list[Message], schema: JSONSchema) -> Any:
+        raise UnsupportedFormat("no json schema")
+
+    def embed(self, model: str, texts: list[str]) -> list[list[float]]:
+        raise NotImplementedError

golem_agent_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "golem-agent-sdk"
+version = "0.1.0"
+description = "Python SDK for Golem extensions"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = []
+
+[[project.authors]]
+name = "Nawaz Gafar"
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = ""
+module-name = "golem"
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = ["pytest>=9.1.1"]

golem_agent_sdk-0.1.0/pyproject.toml.orig

@@ -0,0 +1,27 @@
+[project]
+name = "golem-agent-sdk"
+version = "0.1.0"
+description = "Python SDK for Golem extensions"
+readme = "README.md"
+authors = [
+    { name = "Nawaz Gafar" }
+]
+requires-python = ">=3.10"
+dependencies = []
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = ""
+module-name = "golem"
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+]