feat: implement NotificationReaderAgent to pre-screen Gitea notifications (#2)

core/notification_tools.py

@@ -0,0 +1,68 @@
+import logging
+from typing import Any
+
+logger: logging.Logger = logging.getLogger("notification-tools")
+
+
+class NotificationTools:
+    """Tools exposed to the Notification Reader Agent for routing decisions."""
+
+    def __init__(self) -> None:
+        self.tool_called: bool = False
+        self.action: str = "NO_ACTION"
+        self.arguments: dict[str, Any] = {}
+
+    def process_issue(self, owner: str, repo: str, issue_number: int, reason: str) -> str:
+        """Process the notification as an issue.
+        Use this when a notification refers to an issue that requires agent action.
+
+        Args:
+            owner: The repository owner (organization).
+            repo: The repository name.
+            issue_number: The Gitea issue number.
+            reason: Why this notification should be processed.
+        """
+        logger.info(f"Notification tool 'process_issue' called for {owner}/{repo}#{issue_number}: {reason}")
+        self.tool_called = True
+        self.action = "PROCESS_ISSUE"
+        self.arguments = {
+            "owner": owner,
+            "repo": repo,
+            "issue_number": issue_number,
+            "reason": reason,
+        }
+        return "Issue notification marked for processing."
+
+    def process_pr(self, owner: str, repo: str, pr_number: int, reason: str) -> str:
+        """Process the notification as a pull request.
+        Use this when a notification refers to a PR that requires agent action.
+
+        Args:
+            owner: The repository owner (organization).
+            repo: The repository name.
+            pr_number: The Gitea PR number.
+            reason: Why this notification should be processed.
+        """
+        logger.info(f"Notification tool 'process_pr' called for {owner}/{repo}#{pr_number}: {reason}")
+        self.tool_called = True
+        self.action = "PROCESS_PR"
+        self.arguments = {
+            "owner": owner,
+            "repo": repo,
+            "pr_number": pr_number,
+            "reason": reason,
+        }
+        return "PR notification marked for processing."
+
+    def skip_notification(self, reason: str) -> str:
+        """Skip the notification and take no action.
+        Use this if the notification is irrelevant, already handled, or does not require agent intervention.
+
+        Args:
+            reason: The reason for skipping this notification.
+        """
+        logger.info(f"Notification tool 'skip_notification' called: {reason}")
+        self.tool_called = True
+        self.action = "SKIP"
+        self.arguments = {"reason": reason}
+        return "Notification marked to be skipped."