xyberos-github 0.1.0__py3-none-any.whl

xyberos_github/__init__.py

@@ -0,0 +1,6 @@
+"""GitHub REST plugin (RFC-0019, M7)."""
+
+from .client import GithubClient
+from .plugin import GithubPlugin
+
+__all__ = ["GithubClient", "GithubPlugin"]

xyberos_github/client.py

@@ -0,0 +1,95 @@
+"""A minimal GitHub REST client (stdlib ``urllib``, injectable transport)."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from xyberos.exceptions.provider import ProviderError
+
+from .http import RequestTransport, default_request
+
+
+def _raise_for_status(status: int, body: Any) -> None:
+    if 200 <= status < 300:
+        return
+    message = body if isinstance(body, str) else str(body)
+    raise ProviderError(f"GitHub API returned HTTP {status}: {message[:200]}")
+
+
+class GithubClient:
+    """Thin client for the GitHub REST API v3."""
+
+    def __init__(
+        self,
+        token: str | None = None,
+        *,
+        base_url: str = "https://api.github.com",
+        request: RequestTransport | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self._token = token if token is not None else os.getenv("GITHUB_TOKEN")
+        self._base_url = base_url.rstrip("/")
+        self._request = request or default_request
+        self._timeout = timeout
+
+    # -- users --------------------------------------------------------------
+
+    def get_user(self, username: str) -> dict[str, Any]:
+        status, body = self._request(
+            "GET",
+            f"{self._base_url}/users/{username}",
+            headers=self._headers(),
+            timeout=self._timeout,
+        )
+        _raise_for_status(status, body)
+        return {
+            "login": body.get("login"),
+            "name": body.get("name"),
+            "public_repos": body.get("public_repos"),
+            "html_url": body.get("html_url"),
+        }
+
+    # -- repositories -------------------------------------------------------
+
+    def list_repos(self, username: str, *, per_page: int = 30) -> list[dict[str, Any]]:
+        status, body = self._request(
+            "GET",
+            f"{self._base_url}/users/{username}/repos",
+            query={"per_page": per_page},
+            headers=self._headers(),
+            timeout=self._timeout,
+        )
+        _raise_for_status(status, body)
+        return [
+            {"full_name": repo.get("full_name"), "html_url": repo.get("html_url"), "language": repo.get("language")}
+            for repo in body
+        ]
+
+    # -- issues -------------------------------------------------------------
+
+    def create_issue(self, owner: str, repo: str, title: str, body: str = "") -> dict[str, Any]:
+        self._require_auth("create_issue")
+        status, body_ = self._request(
+            "POST",
+            f"{self._base_url}/repos/{owner}/{repo}/issues",
+            json_body={"title": title, "body": body},
+            headers=self._headers(),
+            timeout=self._timeout,
+        )
+        _raise_for_status(status, body_)
+        return {"number": body_.get("number"), "html_url": body_.get("html_url"), "state": body_.get("state")}
+
+    # -- internals ----------------------------------------------------------
+
+    def _headers(self) -> dict[str, str]:
+        headers = {"Accept": "application/vnd.github+json", "User-Agent": "xyberos-github"}
+        if self._token:
+            headers["Authorization"] = f"Bearer {self._token}"
+        return headers
+
+    def _require_auth(self, action: str) -> None:
+        if not self._token:
+            raise ProviderError(
+                f"GitHub '{action}' requires a token (set GITHUB_TOKEN)"
+            )

xyberos_github/http.py

@@ -0,0 +1,57 @@
+"""A tiny stdlib HTTP helper (no third-party deps).
+
+``default_request`` performs one HTTP request with ``urllib`` and returns
+``(status, body)`` where ``body`` is parsed JSON when the response is JSON,
+otherwise raw text. Injectable so tests run without a network.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable
+
+#: (method, url, *, json_body, headers, query, timeout) -> (status, body)
+RequestTransport = Callable[..., tuple[int, Any]]
+
+
+def default_request(
+    method: str,
+    url: str,
+    *,
+    json_body: Any = None,
+    headers: dict[str, str] | None = None,
+    query: dict[str, Any] | None = None,
+    timeout: float = 30.0,
+) -> tuple[int, Any]:
+    """Send one request and return ``(status, parsed_json_or_text)``."""
+    final_url = url
+    if query:
+        separator = "&" if "?" in url else "?"
+        final_url = url + separator + urllib.parse.urlencode(query)
+
+    data: bytes | None = None
+    request_headers = dict(headers or {})
+    if json_body is not None:
+        data = json.dumps(json_body).encode("utf-8")
+        request_headers.setdefault("Content-Type", "application/json")
+
+    request = urllib.request.Request(
+        final_url, data=data, headers=request_headers, method=method
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            raw = response.read()
+            content_type = response.headers.get("Content-Type", "")
+    except urllib.error.HTTPError as exc:
+        return exc.code, exc.read().decode("utf-8", errors="replace")
+
+    text = raw.decode("utf-8", errors="replace")
+    if "application/json" in content_type or text.lstrip().startswith("{"):
+        try:
+            return 200, json.loads(text)
+        except json.JSONDecodeError:
+            return 200, text
+    return 200, text

xyberos_github/plugin.py

@@ -0,0 +1,64 @@
+"""GitHub plugin entry point (RFC-0019, M7)."""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+from xyberos.contracts import Plugin, Tool
+from xyberos.tools import FunctionTool
+
+from .client import GithubClient
+from .http import RequestTransport
+
+
+def _pop_tool(registry: Any, name: str) -> None:
+    unregister = getattr(registry, "unregister", None)
+    if callable(unregister):
+        unregister(name)
+        return
+    store = getattr(registry, "_tools", None)
+    if isinstance(store, dict):
+        cast(dict[str, Any], store).pop(name, None)
+
+
+class GithubPlugin(Plugin):
+    """Registers GitHub tools (user / repos / issues)."""
+
+    def __init__(self, token: str | None = None, *, request: RequestTransport | None = None) -> None:
+        self._client = GithubClient(token, request=request)
+
+    @property
+    def name(self) -> str:
+        return "github"
+
+    def tools(self) -> list[Tool]:
+        client = self._client
+
+        def _get_user(username: str) -> dict[str, Any]:
+            return client.get_user(username)
+
+        def _list_repos(username: str, per_page: int = 30) -> list[dict[str, Any]]:
+            return client.list_repos(username, per_page=per_page)
+
+        def _create_issue(owner: str, repo: str, title: str, body: str = "") -> dict[str, Any]:
+            return client.create_issue(owner, repo, title, body)
+
+        return [
+            FunctionTool("github_get_user", _get_user, description="Get a GitHub user's public profile."),
+            FunctionTool("github_list_repos", _list_repos, description="List a GitHub user's public repositories."),
+            FunctionTool("github_create_issue", _create_issue, description="Create a GitHub issue on a repository."),
+        ]
+
+    def register(self, kernel: object) -> None:
+        registry = kernel.resolve("tools")
+        for tool in self.tools():
+            registry.register(tool)
+
+    def unregister(self, kernel: object) -> None:
+        registry = kernel.resolve("tools")
+        for tool in self.tools():
+            _pop_tool(registry, tool.name)
+
+
+#: Auto-discovered by ``app.load_entry_points()``.
+plugin = GithubPlugin()

xyberos_github-0.1.0.dist-info/METADATA

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: xyberos-github
+Version: 0.1.0
+Summary: GitHub REST plugin (RFC-0019, M7): user/repo/issue tools for Xyberos agents
+License: Apache-2.0
+Keywords: xyberos,plugin,github,tool
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: xyberos>=1.0
+
+# xyberos-github
+
+**GitHub REST plugin — RFC-0019, M7 (community wave).** User / repository /
+issue tools for Xyberos agents, via the GitHub REST API v3. Stdlib-only
+(`urllib`) with an injectable transport for tests.
+
+## Install
+
+```bash
+pip install -e ./github
+```
+
+## Usage
+
+```python
+from xyberos import create_app
+from xyberos_github import GithubPlugin
+
+app = create_app()
+app.load_plugin(GithubPlugin())          # token from GITHUB_TOKEN (optional for public reads)
+
+app.tools.execute("github_get_user", None, username="octocat")
+app.tools.execute("github_list_repos", None, username="octocat", per_page=30)
+app.tools.execute("github_create_issue", None, owner="o", repo="r", title="Bug", body="...")
+```
+
+## Tools
+
+| Tool | Notes |
+| ---- | ----- |
+| `github_get_user(username)` | public profile |
+| `github_list_repos(username, per_page=30)` | public repositories |
+| `github_create_issue(owner, repo, title, body="")` | requires `GITHUB_TOKEN` |
+
+## Tests
+
+```bash
+pip install pytest
+pytest tests/
+```
+
+Canned responses via an injectable transport — no network.
+
+## Ship location
+
+Plugin (`xyberos.plugins` entry point) — community wave (M7).

xyberos_github-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+xyberos_github/__init__.py,sha256=iHtpE4G_2B1ULsVkZ6CUjbL5KKRbwvrchUtr2u7iRZQ,152
+xyberos_github/client.py,sha256=6TCcl87PFVX--sCYdP74l_0THZ3knJ9AMIhUuSABzho,3338
+xyberos_github/http.py,sha256=6w9_RJnzXazWN6e3VB5IfBDNvTSqPvYefHfmLOrpFGg,1888
+xyberos_github/plugin.py,sha256=RHOcvpyVWEN5U09jFvvBm6hIAh0FS4HTot5D4tjCQwc,2149
+xyberos_github-0.1.0.dist-info/METADATA,sha256=FV1bbLkeTW4TRoYZDn4ji-GggETN6J7IimcmR-a7oKI,1452
+xyberos_github-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+xyberos_github-0.1.0.dist-info/entry_points.txt,sha256=bnHRPCdFyB6oKTWirFbRbtck68Yj-W52zVGynGpLQxI,56
+xyberos_github-0.1.0.dist-info/top_level.txt,sha256=WBDAlKP-AyOAxurOU7rpVZfDPV7x_Igdzu17UuKS5bE,15
+xyberos_github-0.1.0.dist-info/RECORD,,

xyberos_github-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

xyberos_github-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[xyberos.plugins]
+github = xyberos_github.plugin:plugin

xyberos_github-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+xyberos_github