elizaos-plugin-github 2.0.0a4__py3-none-any.whl

elizaos_plugin_github/config.py

@@ -0,0 +1,68 @@
+import os
+
+from pydantic import BaseModel, ConfigDict, field_validator
+
+from elizaos_plugin_github.error import ConfigError, MissingSettingError
+
+
+class GitHubConfig(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    # Required fields
+    api_token: str
+
+    # Optional fields with defaults
+    owner: str | None = None
+    repo: str | None = None
+    branch: str = "main"
+    webhook_secret: str | None = None
+    app_id: str | None = None
+    app_private_key: str | None = None
+    installation_id: str | None = None
+
+    @field_validator("api_token")
+    @classmethod
+    def validate_api_token(cls, v: str) -> str:
+        if not v or not v.strip():
+            raise ConfigError("API token cannot be empty")
+        return v
+
+    @classmethod
+    def from_env(cls) -> "GitHubConfig":
+        api_token = os.environ.get("GITHUB_API_TOKEN")
+        if not api_token:
+            raise MissingSettingError("GITHUB_API_TOKEN")
+
+        return cls(
+            api_token=api_token,
+            owner=os.environ.get("GITHUB_OWNER"),
+            repo=os.environ.get("GITHUB_REPO"),
+            branch=os.environ.get("GITHUB_BRANCH", "main"),
+            webhook_secret=os.environ.get("GITHUB_WEBHOOK_SECRET"),
+            app_id=os.environ.get("GITHUB_APP_ID"),
+            app_private_key=os.environ.get("GITHUB_APP_PRIVATE_KEY"),
+            installation_id=os.environ.get("GITHUB_INSTALLATION_ID"),
+        )
+
+    def get_repository_ref(
+        self, owner: str | None = None, repo: str | None = None
+    ) -> tuple[str, str]:
+        resolved_owner = owner or self.owner
+        resolved_repo = repo or self.repo
+
+        if not resolved_owner:
+            raise MissingSettingError("owner (GITHUB_OWNER)")
+
+        if not resolved_repo:
+            raise MissingSettingError("repo (GITHUB_REPO)")
+
+        return resolved_owner, resolved_repo
+
+    def has_app_auth(self) -> bool:
+        return bool(self.app_id and self.app_private_key)
+
+    def validate_all(self) -> None:
+        if self.has_app_auth() and not self.installation_id:
+            raise ConfigError(
+                "GITHUB_INSTALLATION_ID is required when using GitHub App authentication"
+            )

elizaos_plugin_github/error.py

@@ -0,0 +1,165 @@
+from datetime import datetime
+
+
+class GitHubError(Exception):
+    def __init__(self, message: str) -> None:
+        self.message = message
+        super().__init__(message)
+
+    def is_retryable(self) -> bool:
+        return False
+
+    def retry_after_ms(self) -> int | None:
+        return None
+
+
+class ClientNotInitializedError(GitHubError):
+    def __init__(self) -> None:
+        super().__init__("GitHub client not initialized - ensure GITHUB_API_TOKEN is configured")
+
+
+class ConfigError(GitHubError):
+    def __init__(self, message: str) -> None:
+        super().__init__(f"Configuration error: {message}")
+
+
+class MissingSettingError(GitHubError):
+    def __init__(self, setting_name: str) -> None:
+        self.setting_name = setting_name
+        super().__init__(f"Missing required setting: {setting_name}")
+
+
+class InvalidArgumentError(GitHubError):
+    def __init__(self, message: str) -> None:
+        super().__init__(f"Invalid argument: {message}")
+
+
+class RepositoryNotFoundError(GitHubError):
+    def __init__(self, owner: str, repo: str) -> None:
+        self.owner = owner
+        self.repo = repo
+        super().__init__(f"Repository not found: {owner}/{repo}")
+
+
+class BranchNotFoundError(GitHubError):
+    def __init__(self, branch: str, owner: str, repo: str) -> None:
+        self.branch = branch
+        super().__init__(f"Branch not found: {branch} in {owner}/{repo}")
+
+
+class FileNotFoundError(GitHubError):
+    def __init__(self, path: str, owner: str, repo: str) -> None:
+        self.path = path
+        super().__init__(f"File not found: {path} in {owner}/{repo}")
+
+
+class IssueNotFoundError(GitHubError):
+    def __init__(self, issue_number: int, owner: str, repo: str) -> None:
+        self.issue_number = issue_number
+        super().__init__(f"Issue #{issue_number} not found in {owner}/{repo}")
+
+
+class PullRequestNotFoundError(GitHubError):
+    def __init__(self, pull_number: int, owner: str, repo: str) -> None:
+        self.pull_number = pull_number
+        super().__init__(f"Pull request #{pull_number} not found in {owner}/{repo}")
+
+
+class PermissionDeniedError(GitHubError):
+    def __init__(self, action: str) -> None:
+        super().__init__(f"Permission denied: {action}")
+
+
+class RateLimitedError(GitHubError):
+    def __init__(self, retry_after_ms: int, remaining: int, reset_at: datetime) -> None:
+        self._retry_after_ms = retry_after_ms
+        self.remaining = remaining
+        self.reset_at = reset_at
+        super().__init__(f"Rate limited by GitHub API, retry after {retry_after_ms // 1000}s")
+
+    def is_retryable(self) -> bool:
+        return True
+
+    def retry_after_ms(self) -> int | None:
+        return self._retry_after_ms
+
+
+class SecondaryRateLimitError(GitHubError):
+    def __init__(self, retry_after_ms: int) -> None:
+        self._retry_after_ms = retry_after_ms
+        super().__init__(f"Secondary rate limit hit, retry after {retry_after_ms // 1000}s")
+
+    def is_retryable(self) -> bool:
+        return True
+
+    def retry_after_ms(self) -> int | None:
+        return self._retry_after_ms
+
+
+class TimeoutError(GitHubError):
+    def __init__(self, timeout_ms: int, operation: str) -> None:
+        self._timeout_ms = timeout_ms
+        super().__init__(f"Operation timed out after {timeout_ms}ms: {operation}")
+
+    def is_retryable(self) -> bool:
+        return True
+
+    def retry_after_ms(self) -> int | None:
+        return self._timeout_ms // 2
+
+
+class MergeConflictError(GitHubError):
+    def __init__(self, pull_number: int, owner: str, repo: str) -> None:
+        self.pull_number = pull_number
+        super().__init__(f"Merge conflict in pull request #{pull_number} in {owner}/{repo}")
+
+
+class BranchExistsError(GitHubError):
+    def __init__(self, branch: str, owner: str, repo: str) -> None:
+        self.branch = branch
+        super().__init__(f"Branch already exists: {branch} in {owner}/{repo}")
+
+
+class ValidationError(GitHubError):
+    def __init__(self, field: str, reason: str) -> None:
+        self.field = field
+        super().__init__(f"Validation failed for {field}: {reason}")
+
+
+class GitHubApiError(GitHubError):
+    def __init__(
+        self,
+        status: int,
+        message: str,
+        code: str | None = None,
+        documentation_url: str | None = None,
+    ) -> None:
+        self.status = status
+        self.code = code
+        self.documentation_url = documentation_url
+        super().__init__(f"GitHub API error ({status}): {message}")
+
+    def is_retryable(self) -> bool:
+        return self.status >= 500
+
+
+class NetworkError(GitHubError):
+    def __init__(self, message: str) -> None:
+        super().__init__(f"Network error: {message}")
+
+    def is_retryable(self) -> bool:
+        return True
+
+    def retry_after_ms(self) -> int | None:
+        return 1000
+
+
+class GitOperationError(GitHubError):
+    def __init__(self, operation: str, reason: str) -> None:
+        self.operation = operation
+        super().__init__(f"Git operation failed ({operation}): {reason}")
+
+
+class WebhookVerificationError(GitHubError):
+    def __init__(self, reason: str) -> None:
+        super().__init__(f"Webhook verification failed: {reason}")

elizaos_plugin_github/generated/specs/__init__.py

@@ -0,0 +1 @@
+"""Auto-generated module package."""

elizaos_plugin_github/generated/specs/specs.py

@@ -0,0 +1,171 @@
+"""
+Auto-generated canonical action/provider/evaluator docs for plugin-github.
+DO NOT EDIT - Generated from prompts/specs/**.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TypedDict
+
+
+class ActionDoc(TypedDict, total=False):
+    name: str
+    description: str
+    similes: list[str]
+    parameters: list[object]
+    examples: list[list[object]]
+
+
+class ProviderDoc(TypedDict, total=False):
+    name: str
+    description: str
+    position: int
+    dynamic: bool
+
+
+class EvaluatorDoc(TypedDict, total=False):
+    name: str
+    description: str
+    similes: list[str]
+    alwaysRun: bool
+    examples: list[object]
+
+
+_CORE_ACTION_DOCS_JSON = """{
+  "version": "1.0.0",
+  "actions": [
+    {
+      "name": "CREATE_GITHUB_BRANCH",
+      "description": "",
+      "parameters": []
+    },
+    {
+      "name": "CREATE_GITHUB_COMMENT",
+      "description": "",
+      "parameters": []
+    },
+    {
+      "name": "CREATE_GITHUB_ISSUE",
+      "description": "",
+      "parameters": []
+    },
+    {
+      "name": "CREATE_GITHUB_PULL_REQUEST",
+      "description": "",
+      "parameters": []
+    },
+    {
+      "name": "MERGE_GITHUB_PULL_REQUEST",
+      "description": "",
+      "parameters": []
+    },
+    {
+      "name": "PUSH_GITHUB_CODE",
+      "description": "",
+      "parameters": []
+    },
+    {
+      "name": "REVIEW_GITHUB_PULL_REQUEST",
+      "description": "",
+      "parameters": []
+    }
+  ]
+}"""
+_ALL_ACTION_DOCS_JSON = """{
+  "version": "1.0.0",
+  "actions": [
+    {
+      "name": "CREATE_GITHUB_BRANCH",
+      "description": "",
+      "parameters": []
+    },
+    {
+      "name": "CREATE_GITHUB_COMMENT",
+      "description": "",
+      "parameters": []
+    },
+    {
+      "name": "CREATE_GITHUB_ISSUE",
+      "description": "",
+      "parameters": []
+    },
+    {
+      "name": "CREATE_GITHUB_PULL_REQUEST",
+      "description": "",
+      "parameters": []
+    },
+    {
+      "name": "MERGE_GITHUB_PULL_REQUEST",
+      "description": "",
+      "parameters": []
+    },
+    {
+      "name": "PUSH_GITHUB_CODE",
+      "description": "",
+      "parameters": []
+    },
+    {
+      "name": "REVIEW_GITHUB_PULL_REQUEST",
+      "description": "",
+      "parameters": []
+    }
+  ]
+}"""
+_CORE_PROVIDER_DOCS_JSON = """{
+  "version": "1.0.0",
+  "providers": [
+    {
+      "name": "GITHUB_ISSUE_CONTEXT",
+      "description": "Provides detailed context about a specific GitHub issue or pull request when referenced",
+      "dynamic": true
+    },
+    {
+      "name": "GITHUB_REPOSITORY_STATE",
+      "description": "Provides context about the current GitHub repository including recent activity",
+      "dynamic": true
+    }
+  ]
+}"""
+_ALL_PROVIDER_DOCS_JSON = """{
+  "version": "1.0.0",
+  "providers": [
+    {
+      "name": "GITHUB_ISSUE_CONTEXT",
+      "description": "Provides detailed context about a specific GitHub issue or pull request when referenced",
+      "dynamic": true
+    },
+    {
+      "name": "GITHUB_REPOSITORY_STATE",
+      "description": "Provides context about the current GitHub repository including recent activity",
+      "dynamic": true
+    }
+  ]
+}"""
+_CORE_EVALUATOR_DOCS_JSON = """{
+  "version": "1.0.0",
+  "evaluators": []
+}"""
+_ALL_EVALUATOR_DOCS_JSON = """{
+  "version": "1.0.0",
+  "evaluators": []
+}"""
+
+core_action_docs: dict[str, object] = json.loads(_CORE_ACTION_DOCS_JSON)
+all_action_docs: dict[str, object] = json.loads(_ALL_ACTION_DOCS_JSON)
+core_provider_docs: dict[str, object] = json.loads(_CORE_PROVIDER_DOCS_JSON)
+all_provider_docs: dict[str, object] = json.loads(_ALL_PROVIDER_DOCS_JSON)
+core_evaluator_docs: dict[str, object] = json.loads(_CORE_EVALUATOR_DOCS_JSON)
+all_evaluator_docs: dict[str, object] = json.loads(_ALL_EVALUATOR_DOCS_JSON)
+
+__all__ = [
+    "ActionDoc",
+    "ProviderDoc",
+    "EvaluatorDoc",
+    "core_action_docs",
+    "all_action_docs",
+    "core_provider_docs",
+    "all_provider_docs",
+    "core_evaluator_docs",
+    "all_evaluator_docs",
+]

elizaos_plugin_github/providers/__init__.py

@@ -0,0 +1,12 @@
+from elizaos_plugin_github.providers.issue_context import IssueContextProvider
+from elizaos_plugin_github.providers.repository_state import RepositoryStateProvider
+
+__all__ = [
+    "RepositoryStateProvider",
+    "IssueContextProvider",
+]
+
+all_providers = [
+    RepositoryStateProvider(),
+    IssueContextProvider(),
+]

elizaos_plugin_github/providers/issue_context.py

@@ -0,0 +1,136 @@
+import re
+from typing import Protocol
+
+
+class ProviderContext(Protocol):
+    message: dict[str, object]
+
+
+def extract_issue_number(text: str) -> int | None:
+    patterns = [
+        r"#(\d+)",
+        r"issue\s*#?(\d+)",
+        r"pr\s*#?(\d+)",
+        r"pull\s*request\s*#?(\d+)",
+    ]
+
+    for pattern in patterns:
+        match = re.search(pattern, text, re.IGNORECASE)
+        if match:
+            return int(match.group(1))
+
+    return None
+
+
+class IssueContextProvider:
+    @property
+    def name(self) -> str:
+        return "GITHUB_ISSUE_CONTEXT"
+
+    @property
+    def description(self) -> str:
+        return "Provides detailed context about a specific GitHub issue or pull request when referenced"
+
+    async def get(
+        self,
+        context: ProviderContext,
+        service: object,
+    ) -> str | None:
+        from elizaos_plugin_github.service import GitHubService
+
+        if not isinstance(service, GitHubService):
+            return None
+
+        content = context.message.get("content", {})
+        text = ""
+        if isinstance(content, dict):
+            text = str(content.get("text", ""))
+
+        issue_number = extract_issue_number(text)
+        if not issue_number:
+            return None
+
+        try:
+            config = service.config
+
+            if not config.owner or not config.repo:
+                return None
+
+            try:
+                issue = await service.get_issue(config.owner, config.repo, issue_number)
+
+                if issue.is_pull_request:
+                    pr = await service.get_pull_request(config.owner, config.repo, issue_number)
+
+                    labels = ", ".join(label.name for label in pr.labels)
+                    assignees = ", ".join(a.login for a in pr.assignees)
+                    reviewers = ", ".join(r.login for r in pr.requested_reviewers)
+
+                    parts = [
+                        f"## Pull Request #{pr.number}: {pr.title}",
+                        "",
+                        f"**State:** {pr.state.value}{'  (Draft)' if pr.draft else ''}{'  (Merged)' if pr.merged else ''}",
+                        f"**Author:** {pr.user.login}",
+                        f"**Branch:** {pr.head.ref} → {pr.base.ref}",
+                        f"**Created:** {pr.created_at}",
+                        f"**Updated:** {pr.updated_at}",
+                    ]
+
+                    if labels:
+                        parts.append(f"**Labels:** {labels}")
+                    if assignees:
+                        parts.append(f"**Assignees:** {assignees}")
+                    if reviewers:
+                        parts.append(f"**Reviewers Requested:** {reviewers}")
+
+                    parts.extend(
+                        [
+                            "",
+                            f"**Changes:** +{pr.additions} / -{pr.deletions} ({pr.changed_files} files)",
+                            "",
+                            "### Description",
+                            pr.body or "_No description provided_",
+                            "",
+                            f"**URL:** {pr.html_url}",
+                        ]
+                    )
+
+                    return "\n".join(parts)
+
+                labels = ", ".join(label.name for label in issue.labels)
+                assignees = ", ".join(a.login for a in issue.assignees)
+
+                parts = [
+                    f"## Issue #{issue.number}: {issue.title}",
+                    "",
+                    f"**State:** {issue.state.value}{(' (' + issue.state_reason.value + ')') if issue.state_reason else ''}",
+                    f"**Author:** {issue.user.login}",
+                    f"**Created:** {issue.created_at}",
+                    f"**Updated:** {issue.updated_at}",
+                    f"**Comments:** {issue.comments}",
+                ]
+
+                if labels:
+                    parts.append(f"**Labels:** {labels}")
+                if assignees:
+                    parts.append(f"**Assignees:** {assignees}")
+                if issue.milestone:
+                    parts.append(f"**Milestone:** {issue.milestone.title}")
+
+                parts.extend(
+                    [
+                        "",
+                        "### Description",
+                        issue.body or "_No description provided_",
+                        "",
+                        f"**URL:** {issue.html_url}",
+                    ]
+                )
+
+                return "\n".join(parts)
+
+            except Exception:
+                return f"Issue/PR #{issue_number} not found in {config.owner}/{config.repo}"
+
+        except Exception as e:
+            return f"Unable to fetch issue context: {e}"

elizaos_plugin_github/providers/repository_state.py

@@ -0,0 +1,87 @@
+from typing import Protocol
+
+from elizaos_plugin_github.types import ListIssuesParams, ListPullRequestsParams, RepositoryRef
+
+
+class ProviderContext(Protocol):
+    pass
+
+
+class RepositoryStateProvider:
+    @property
+    def name(self) -> str:
+        return "GITHUB_REPOSITORY_STATE"
+
+    @property
+    def description(self) -> str:
+        return "Provides context about the current GitHub repository including recent activity"
+
+    async def get(
+        self,
+        _context: ProviderContext,
+        service: object,
+    ) -> str | None:
+        from elizaos_plugin_github.service import GitHubService
+
+        if not isinstance(service, GitHubService):
+            return None
+
+        try:
+            config = service.config
+
+            if not config.owner or not config.repo:
+                return "GitHub repository not configured. Please set GITHUB_OWNER and GITHUB_REPO."
+
+            repo = await service.get_repository(RepositoryRef(owner=config.owner, repo=config.repo))
+
+            issues = await service.list_issues(
+                ListIssuesParams(
+                    owner=config.owner,
+                    repo=config.repo,
+                    state="open",
+                    per_page=5,
+                )
+            )
+
+            # Fetch recent open PRs (limit 5)
+            pull_requests = await service.list_pull_requests(
+                ListPullRequestsParams(
+                    owner=config.owner,
+                    repo=config.repo,
+                    state="open",
+                    per_page=5,
+                )
+            )
+
+            parts: list[str] = [
+                f"## GitHub Repository: {repo.full_name}",
+                "",
+                f"**Description:** {repo.description or 'No description'}",
+                f"**Default Branch:** {repo.default_branch}",
+                f"**Language:** {repo.language or 'Not specified'}",
+                f"**Stars:** {repo.stargazers_count} | **Forks:** {repo.forks_count}",
+                f"**Open Issues:** {repo.open_issues_count}",
+                "",
+            ]
+
+            if issues:
+                parts.append("### Recent Open Issues")
+                for issue in issues:
+                    labels = ", ".join(label.name for label in issue.labels)
+                    label_str = f" [{labels}]" if labels else ""
+                    parts.append(f"- #{issue.number}: {issue.title}{label_str}")
+                parts.append("")
+
+            if pull_requests:
+                parts.append("### Recent Open Pull Requests")
+                for pr in pull_requests:
+                    status = "[DRAFT] " if pr.draft else ""
+                    parts.append(
+                        f"- #{pr.number}: {status}{pr.title} ({pr.head.ref} → {pr.base.ref})"
+                    )
+                parts.append("")
+
+            return "\n".join(parts)
+
+        except Exception as e:
+            return f"Unable to fetch GitHub repository state: {e}"