allybuild-sdk 1.0.0__tar.gz

allybuild_sdk-1.0.0/MANIFEST.in

@@ -0,0 +1 @@
+include workflow.py

allybuild_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: allybuild-sdk
+Version: 1.0.0
+Summary: AllyBuild SDK for task scripts — pure-stdlib HTTP facade (client + tasks/mcp/status/reporter/reactive)
+License: MIT
+Keywords: allybuild,sdk,workflow
+Requires-Python: >=3.10

allybuild_sdk-1.0.0/allybuild_sdk/__init__.py

@@ -0,0 +1,33 @@
+"""AllyBuild SDK — workflow 平台交互面 + reactive 客户端（纯 HTTP，零第三方依赖）。"""
+from .client import AllyBuildClient, AllyBuildError
+from .reporter import Reporter
+from .tasks import ScriptContext, TasksApi
+from .agents import AgentsApi
+from .memories import MemoriesApi
+from .okf import OkfApi
+from .mcp import McpApi
+from .status import ProjectStatusProxy, fetch_statuses
+
+__all__ = [
+    "AllyBuildClient", "AllyBuildError", "Reporter",
+    "ScriptContext", "TasksApi", "AgentsApi", "MemoriesApi", "OkfApi",
+    "McpApi", "ProjectStatusProxy", "fetch_statuses",
+]
+
+
+def create_client(base_url: str, token: str, project_id: str):
+    """便捷工厂：一次构造 client + 全部域 API（返回 SimpleNamespace）。"""
+    from types import SimpleNamespace
+
+    client = AllyBuildClient(base_url, token, project_id)
+    ctx = ScriptContext()
+    return SimpleNamespace(
+        client=client,
+        reporter=Reporter(),
+        tasks=TasksApi(client, ctx),
+        agents=AgentsApi(client),
+        memories=MemoriesApi(client),
+        okf=OkfApi(client),
+        mcp=McpApi(client),
+        status=ProjectStatusProxy(client=client),
+    )

allybuild_sdk-1.0.0/allybuild_sdk/agents.py

@@ -0,0 +1,40 @@
+"""Agent and workspace listing — ported from runtime/environment/python/workflow.py."""
+from .client import AllyBuildClient
+
+
+class AgentsApi:
+    """List agents and workspaces in the project."""
+
+    def __init__(self, client: AllyBuildClient):
+        self._client = client
+
+    def _ensure(self) -> None:
+        if not self._client.configured():
+            raise RuntimeError("ALLYBUILD_API_URL / PROJECT_ID / TASK_JWT not set")
+
+    def list_agents(self) -> list:
+        """List all agents in this project.
+
+        Returns:
+            List of agent dicts with id, name, description, is_default, agent_type.
+
+        Example:
+            for agent in api.list_agents():
+                print(agent["name"], agent["agent_type"])
+        """
+        self._ensure()
+        return self._client.get(f"/projects/{self._client.project_id}/agents/")
+
+    def list_workspaces(self) -> list:
+        """List all workspaces in this project.
+
+        Returns:
+            List of workspace dicts with id, name, slug, type, is_default, artifact_type.
+
+        Example:
+            for ws in api.list_workspaces():
+                if ws["artifact_type"] == "knowledge_base":
+                    print(ws["name"])
+        """
+        self._ensure()
+        return self._client.get(f"/projects/{self._client.project_id}/workspaces/")

allybuild_sdk-1.0.0/allybuild_sdk/client.py

@@ -0,0 +1,79 @@
+"""AllyBuild SDK HTTP client — stdlib only, transport seam injectable."""
+import json
+import urllib.error
+import urllib.request
+
+
+class AllyBuildError(RuntimeError):
+    """HTTP-level error from the AllyBuild API."""
+
+    def __init__(self, status: int, message: str):
+        super().__init__(message)
+        self.status = status
+        self.message = message
+
+
+class AllyBuildClient:
+    """Project-scoped HTTP client for the AllyBuild API.
+
+    All config is explicit (base_url/token/project_id) — the SDK never reads
+    environment variables; the container thin-shell supplies env values.
+    """
+
+    def __init__(self, base_url: str, token: str, project_id: str):
+        self.base_url = (base_url or "").rstrip("/")
+        self.token = token or ""
+        self.project_id = project_id or ""
+
+    def configured(self) -> bool:
+        return bool(self.base_url and self.token and self.project_id)
+
+    def _headers(self, *, json_body: bool) -> dict:
+        h = {"Authorization": f"Bearer {self.token}"}
+        if json_body:
+            h["Content-Type"] = "application/json"
+        return h
+
+    def _build_request(self, method: str, path: str, body) -> urllib.request.Request:
+        data = json.dumps(body).encode() if body is not None else None
+        return urllib.request.Request(
+            f"{self.base_url}{path}",
+            data=data,
+            headers=self._headers(json_body=body is not None),
+            method=method,
+        )
+
+    def _send(self, req, timeout):
+        """Transport seam — tests override this; production uses urllib."""
+        return urllib.request.urlopen(req, timeout=timeout)
+
+    def _raise_http_error(self, method: str, path: str, exc: urllib.error.HTTPError):
+        detail = exc.read().decode(errors="replace") if exc.fp else ""
+        raise AllyBuildError(
+            exc.code, f"{method} {path} failed ({exc.code}): {detail}"
+        ) from exc
+
+    def request(self, method: str, path: str, *, body=None, timeout: float = 10):
+        req = self._build_request(method, path, body)
+        try:
+            with self._send(req, timeout) as resp:
+                raw = resp.read()
+                return json.loads(raw) if raw else None
+        except urllib.error.HTTPError as exc:
+            self._raise_http_error(method, path, exc)
+
+    def get(self, path: str, *, timeout: float = 10):
+        return self.request("GET", path, timeout=timeout)
+
+    def post(self, path: str, body=None, *, timeout: float = 10):
+        return self.request("POST", path, body=body, timeout=timeout)
+
+    def request_drain(self, method: str, path: str, *, body=None, timeout: float = 600) -> None:
+        """Send a request and drain the (possibly SSE) response — output discarded."""
+        req = self._build_request(method, path, body)
+        try:
+            with self._send(req, timeout) as resp:
+                while resp.read(4096):
+                    pass
+        except urllib.error.HTTPError as exc:
+            self._raise_http_error(method, path, exc)

allybuild_sdk-1.0.0/allybuild_sdk/mcp.py

@@ -0,0 +1,298 @@
+"""MCP JSON-RPC client — ported from runtime/environment/python/workflow.py."""
+import json
+import urllib.error
+import urllib.request
+
+from .client import AllyBuildClient
+
+
+class McpClient:
+    """MCP client for calling tools on a single streamable-http server.
+
+    Implements JSON-RPC 2.0 over HTTP POST, handling both plain JSON and
+    SSE-streamed responses transparently.
+
+    Sync usage:
+        exa = mcp("exa")
+        result = exa.call("web_search_exa", {"query": "latest MCP news"})
+        for item in result["content"]:
+            if item["type"] == "text":
+                print(item["text"])
+
+    Async usage (inside an async def run):
+        import asyncio
+        r1, r2 = await asyncio.gather(
+            mcp("exa").acall("web_search_exa", {"query": "python 3.13"}),
+            mcp("context7").acall("resolve-library-id",
+                                  {"query": "fastapi", "libraryName": "fastapi"}),
+        )
+    """
+
+    def __init__(self, name: str, url: str, headers: dict) -> None:
+        self._name = name
+        self._url = url
+        self._headers = headers
+        self._req_id = 0
+
+    def _send(self, req, timeout):
+        """Transport seam — tests override this; production uses urllib."""
+        return urllib.request.urlopen(req, timeout=timeout)
+
+    def _rpc(self, method: str, params: dict, timeout: int = 60) -> dict:
+        """Send a JSON-RPC 2.0 request and return the parsed response dict."""
+        self._req_id += 1
+        body = json.dumps({
+            "jsonrpc": "2.0",
+            "id": str(self._req_id),
+            "method": method,
+            "params": params,
+        }).encode()
+
+        req_headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json, text/event-stream",
+            **self._headers,
+        }
+        req = urllib.request.Request(
+            self._url, data=body, headers=req_headers, method="POST"
+        )
+        try:
+            with self._send(req, timeout) as resp:
+                content_type = resp.headers.get("Content-Type", "")
+                raw = resp.read()
+                # SSE stream: parse the first complete data: line
+                if "text/event-stream" in content_type:
+                    text = raw.decode(errors="replace")
+                    for line in text.splitlines():
+                        line = line.strip()
+                        if not line.startswith("data: "):
+                            continue
+                        payload = line[6:].strip()
+                        if payload in ("", "[DONE]"):
+                            continue
+                        try:
+                            return json.loads(payload)
+                        except ValueError:
+                            continue
+                    raise RuntimeError(
+                        f"MCP [{self._name}]: no parseable data in SSE stream"
+                    )
+                return json.loads(raw)
+        except urllib.error.HTTPError as exc:
+            detail = exc.read().decode(errors="replace") if exc.fp else ""
+            raise RuntimeError(
+                f"MCP [{self._name}] {method} failed (HTTP {exc.code}): {detail}"
+            ) from exc
+
+    def list_tools(self) -> list:
+        """List all tools available on this MCP server.
+
+        Returns:
+            List of tool dicts, each with 'name', 'description', 'inputSchema'.
+
+        Example:
+            for tool in mcp("exa").list_tools():
+                print(tool["name"], "-", tool["description"])
+        """
+        resp = self._rpc("tools/list", {})
+        err = resp.get("error")
+        if err:
+            raise RuntimeError(
+                f"MCP [{self._name}] tools/list error: {err.get('message', err)}"
+            )
+        return resp.get("result", {}).get("tools", [])
+
+    def call(self, tool_name: str, arguments: dict | None = None, timeout: int = 60) -> dict:
+        """Call a tool on this MCP server.
+
+        Args:
+            tool_name:  Name of the tool to invoke.
+            arguments:  Tool arguments dict (must match the tool's inputSchema).
+            timeout:    Request timeout in seconds (default 60).
+
+        Returns:
+            Result dict with a 'content' list of {type, text} items and
+            an optional 'isError' flag. Most tools return a single text item.
+
+        Raises:
+            RuntimeError: Server returned a JSON-RPC error.
+
+        Example:
+            result = mcp("exa").call("web_search_exa", {"query": "Python 3.13 changes"})
+            print(result["content"][0]["text"])
+        """
+        resp = self._rpc(
+            "tools/call",
+            {"name": tool_name, "arguments": arguments or {}},
+            timeout=timeout,
+        )
+        err = resp.get("error")
+        if err:
+            raise RuntimeError(
+                f"MCP [{self._name}] tools/call '{tool_name}' error: "
+                f"{err.get('message', err)}"
+            )
+        return resp.get("result", {})
+
+    async def acall(
+        self, tool_name: str, arguments: dict | None = None, timeout: int = 60
+    ) -> dict:
+        """Async version of call() — runs the HTTP request in a thread pool.
+
+        Use inside an ``async def run`` to fire multiple MCP calls concurrently
+        with ``asyncio.gather``.
+
+        Example:
+            import asyncio
+
+            async def run(params, reporter):
+                r1, r2 = await asyncio.gather(
+                    mcp("exa").acall("web_search_exa", {"query": "MCP news"}),
+                    mcp("context7").acall("resolve-library-id",
+                                          {"query": "fastapi", "libraryName": "fastapi"}),
+                )
+                print(r1["content"][0]["text"])
+        """
+        import asyncio
+        return await asyncio.to_thread(self.call, tool_name, arguments, timeout)
+
+    async def alist_tools(self) -> list:
+        """Async version of list_tools() — runs in a thread pool.
+
+        Example:
+            tools = await mcp("exa").alist_tools()
+        """
+        import asyncio
+        return await asyncio.to_thread(self.list_tools)
+
+
+class McpApi:
+    """MCP integration — resolve project server configs and call tools."""
+
+    def __init__(self, client: AllyBuildClient):
+        self._client = client
+        self._cache: dict | None = None
+
+    def _fetch_mcp_config(self) -> dict:
+        """Fetch project MCP server config from the AllyBuild API.
+
+        Returns {server_name: {"url": ..., "headers": {...}}} for all configured servers.
+        Returns {} on any error (no MCP servers configured, network failure, etc.).
+        """
+        if not self._client.configured():
+            return {}
+        try:
+            project = self._client.get(f"/projects/{self._client.project_id}", timeout=5)
+            mcp_config = project.get("mcp_config") or {}
+            return mcp_config.get("mcpServers") or {}
+        except Exception:
+            return {}
+
+    def _mcp_config(self) -> dict:
+        """Project MCP server config, fetched lazily on first mcp() call."""
+        if self._cache is None:
+            self._cache = self._fetch_mcp_config()
+        return self._cache
+
+    def mcp(self, server_name: str) -> McpClient:
+        """Return an MCP client for the named server.
+
+        The server must be configured in the project's MCP integration settings
+        (integration tab → streamable-http servers).
+
+        Args:
+            server_name: Key in the project's mcpServers config (e.g. "exa").
+
+        Returns:
+            McpClient with list_tools(), call(), alist_tools(), acall() methods.
+
+        Raises:
+            KeyError:   Server not found in project MCP config.
+            ValueError: Server has no URL (stdio servers are not supported here).
+
+        Sync example:
+            result = mcp("exa").call("web_search_exa", {"query": "Python 3.13"})
+            print(result["content"][0]["text"])
+
+        Async example (inside async def run):
+            import asyncio
+            r1, r2 = await asyncio.gather(
+                mcp("exa").acall("web_search_exa", {"query": "Python 3.13"}),
+                mcp("context7").acall("resolve-library-id",
+                                      {"query": "fastapi", "libraryName": "fastapi"}),
+            )
+        """
+        cfg_map = self._mcp_config()
+        if server_name not in cfg_map:
+            available = list(cfg_map.keys())
+            raise KeyError(
+                f"MCP server {server_name!r} not found in project config. "
+                f"Configured servers: {available}"
+            )
+        cfg = cfg_map[server_name]
+        url = cfg.get("url")
+        if not url:
+            raise ValueError(
+                f"MCP server {server_name!r} has no URL. "
+                "Only streamable-http servers (with a URL) are supported in workflow scripts."
+            )
+        return McpClient(name=server_name, url=url, headers=cfg.get("headers") or {})
+
+    def mcp_call(
+        self,
+        server_name: str,
+        tool_name: str,
+        arguments: dict | None = None,
+        timeout: int = 60,
+    ) -> dict:
+        """Call an MCP tool in one line.
+
+        Shorthand for mcp(server_name).call(tool_name, arguments).
+
+        Args:
+            server_name: MCP server name (e.g. "exa", "context7").
+            tool_name:   Tool to invoke.
+            arguments:   Tool arguments dict.
+            timeout:     Request timeout in seconds (default 60).
+
+        Returns:
+            Result dict with 'content' list.
+
+        Example:
+            result = mcp_call("exa", "web_search_exa", {"query": "MCP protocol 2025"})
+            print(result["content"][0]["text"])
+
+            result = mcp_call("context7", "resolve-library-id",
+                              {"query": "sqlalchemy", "libraryName": "sqlalchemy"})
+        """
+        return self.mcp(server_name).call(tool_name, arguments, timeout=timeout)
+
+    async def async_mcp_call(
+        self,
+        server_name: str,
+        tool_name: str,
+        arguments: dict | None = None,
+        timeout: int = 60,
+    ) -> dict:
+        """Async shorthand: await a single MCP tool call.
+
+        Equivalent to await mcp(server_name).acall(tool_name, arguments).
+        Runs the HTTP request in a thread pool so it doesn't block the event loop.
+
+        Example (inside async def run):
+            import asyncio
+
+            async def run(params, reporter):
+                # Sequential
+                result = await async_mcp_call("exa", "web_search_exa",
+                                              {"query": "MCP 2025"})
+
+                # Concurrent
+                r1, r2 = await asyncio.gather(
+                    async_mcp_call("exa", "web_search_exa", {"query": "python"}),
+                    async_mcp_call("context7", "resolve-library-id",
+                                   {"query": "fastapi", "libraryName": "fastapi"}),
+                )
+                print(r1["content"][0]["text"])
+        """
+        return await self.mcp(server_name).acall(tool_name, arguments, timeout=timeout)

allybuild_sdk-1.0.0/allybuild_sdk/memories.py

@@ -0,0 +1,88 @@
+"""Memory queries — ported from runtime/environment/python/workflow.py."""
+from .client import AllyBuildClient
+
+
+class MemoriesApi:
+    """List / search memories accumulated by meta-tasks and task runs."""
+
+    def __init__(self, client: AllyBuildClient):
+        self._client = client
+
+    def _ensure(self) -> None:
+        if not self._client.configured():
+            raise RuntimeError("ALLYBUILD_API_URL / PROJECT_ID / TASK_JWT not set")
+
+    def list_task_type_memories(
+        self,
+        task_type: str,
+        query: str | None = None,
+        k: int = 20,
+        order: str = "most",
+        limit: int = 20,
+        offset: int = 0,
+    ) -> list:
+        """List or semantically search memories accumulated by a meta-task.
+
+        Without query: paginated listing ordered by creation time (limit/offset).
+        With query:    semantic similarity search returning k results.
+
+        Args:
+            task_type: Meta-task identifier string or UUID.
+            query:     Semantic search query. When provided, switches to similarity
+                       search and the limit/offset params are ignored.
+            k:         Number of results for semantic search (default 20, max 100).
+            order:     "most"  — most relevant first (default).
+                       "least" — least relevant first.
+            limit:     Page size for paginated listing (default 20, max 100).
+            offset:    Items to skip for paginated listing (default 0).
+
+        Returns:
+            List of memory dicts. Semantic results include a "score" field.
+
+        Example:
+            # Paginated listing
+            for m in api.list_task_type_memories("summariser", limit=10):
+                print(m["memory"])
+
+            # Most relevant
+            hits = api.list_task_type_memories("summariser", query="authentication", k=5)
+
+            # Most novel / least similar to a known topic
+            novel = api.list_task_type_memories("summariser", query="authentication",
+                                                k=5, order="least")
+        """
+        self._ensure()
+        if query and query.strip():
+            qs = f"query={query.strip()}&k={k}&order={order}"
+        else:
+            qs = f"limit={limit}&offset={offset}"
+        result = self._client.get(
+            f"/projects/{self._client.project_id}/task-types/{task_type}/memories?{qs}"
+        )
+        return result.get("memories", result) if isinstance(result, dict) else result
+
+    def get_task_memories(
+        self,
+        task_id: str,
+        limit: int = 20,
+        offset: int = 0,
+    ) -> list:
+        """Get memories contributed by a single task run.
+
+        Args:
+            task_id: UUID of the task instance.
+            limit:   Page size (default 20, max 100).
+            offset:  Memories to skip for pagination (default 0).
+
+        Returns:
+            List of memory dicts.
+
+        Example:
+            for m in api.get_task_memories(TASK_ID):
+                print(m["memory"])
+        """
+        self._ensure()
+        result = self._client.get(
+            f"/projects/{self._client.project_id}/tasks/{task_id}/memories?limit={limit}&offset={offset}"
+        )
+        return result.get("memories", result) if isinstance(result, dict) else result

allybuild_sdk-1.0.0/allybuild_sdk/okf.py

@@ -0,0 +1,59 @@
+"""OKF knowledge-base operations — ported from runtime/environment/python/workflow.py."""
+from .client import AllyBuildClient
+
+
+class OkfApi:
+    """Search and lint the project's OKF knowledge-base workspace."""
+
+    def __init__(self, client: AllyBuildClient):
+        self._client = client
+
+    def _ensure(self) -> None:
+        if not self._client.configured():
+            raise RuntimeError("ALLYBUILD_API_URL / PROJECT_ID / TASK_JWT not set")
+
+    def search(self, query: str, workspace_id: str | None = None) -> list:
+        """Search the project's knowledge-base workspace for OKF concepts.
+
+        Args:
+            query:        Search query string.
+            workspace_id: Knowledge-base workspace UUID. Defaults to the
+                          project's knowledge-base workspace.
+
+        Returns:
+            List of concept summary dicts (title, description, concept_type, etc.).
+
+        Example:
+            hits = api.search("authentication flow")
+            for h in hits:
+                print(h["title"], "-", h.get("description", ""))
+        """
+        self._ensure()
+        body: dict = {"query": query}
+        if workspace_id:
+            body["workspace_id"] = workspace_id
+        return self._client.post(f"/projects/{self._client.project_id}/workspace/okf/search", body)
+
+    def lint(self, workspace_id: str | None = None) -> list:
+        """Run OKF health checks on the project's knowledge-base workspace.
+
+        Checks for broken links, orphan concepts, missing type/citations,
+        and duplicate titles.
+
+        Args:
+            workspace_id: Knowledge-base workspace UUID. Defaults to the
+                          project's knowledge-base workspace.
+
+        Returns:
+            List of issue dicts with issue_type, concept_id, message.
+
+        Example:
+            issues = api.lint()
+            for issue in issues:
+                print(f"[{issue['issue_type']}] {issue['concept_id']}: {issue['message']}")
+        """
+        self._ensure()
+        body: dict = {}
+        if workspace_id:
+            body["workspace_id"] = workspace_id
+        return self._client.post(f"/projects/{self._client.project_id}/workspace/okf/lint", body)