refactor(tool-framework): migrate metadata declarations to enums (#4767) (#4822)

* refactor(tool-framework): migrate metadata declarations to enums (#4767)

Signed-off-by: DevSars24 <saurabhsingh100605@gmail.com>

* fix(tool-framework): address maintainer review feedback

---------

Signed-off-by: DevSars24 <saurabhsingh100605@gmail.com>

Author: DevSars24

core/tool_framework/base.py

@@ -45,11 +45,8 @@ class BaseTool(ABC):
     input_model: ClassVar[type[BaseModel] | None] = None
     source: ClassVar[EvidenceSource]
     source_id: ClassVar[str | None] = None
-    # Declared as ``... | str`` so subclasses may keep using the plain wire
-    # values (``"logs"``, ``"read_only"``); ``ToolMetadata`` validation in
-    # ``__init_subclass__`` coerces them to the enum member.
-    evidence_type: ClassVar[EvidenceType | str | None] = None
-    side_effect_level: ClassVar[SideEffectLevel | str | None] = None
+    evidence_type: ClassVar[EvidenceType | None] = None
+    side_effect_level: ClassVar[SideEffectLevel | None] = None
     use_cases: ClassVar[Sequence[str]] = ()
     examples: ClassVar[Sequence[str]] = ()
     anti_examples: ClassVar[Sequence[str]] = ()
@@ -61,7 +58,7 @@ class BaseTool(ABC):
     retrieval_controls: ClassVar[RetrievalControls] = (
         RetrievalControls()
     )  # Declares supported controls
-    surfaces: ClassVar[tuple[ToolSurface | str, ...]] = ("investigation",)
+    surfaces: ClassVar[tuple[ToolSurface | str, ...]] = (ToolSurface.INVESTIGATION,)
     tags: ClassVar[Sequence[str]] = ()
     parallel_safe: ClassVar[bool] = True
     requires_approval: ClassVar[bool] = False  # Whether this tool needs approval from messaging

core/tool_framework/registered_tool.py

@@ -53,10 +53,8 @@ class RegisteredTool:
     run: Callable[..., Any] = field(repr=False)
     display_name: str | None = None
     source_id: str | None = None
-    # ``... | str`` keeps plain wire values accepted from callers; the
-    # ``ToolMetadata`` round-trip in ``__post_init__`` coerces them to members.
-    evidence_type: EvidenceType | str | None = None
-    side_effect_level: SideEffectLevel | str | None = None
+    evidence_type: EvidenceType | None = None
+    side_effect_level: SideEffectLevel | None = None
     surfaces: tuple[ToolSurface | str, ...] = _DEFAULT_SURFACES
     use_cases: list[str] = field(default_factory=list)
     examples: list[str] = field(default_factory=list)
@@ -290,8 +288,8 @@ def from_function(
         input_model: type[BaseModel] | None = None,
         source: EvidenceSource | None,
         source_id: str | None = None,
-        evidence_type: EvidenceType | str | None = None,
-        side_effect_level: SideEffectLevel | str | None = None,
+        evidence_type: EvidenceType | None = None,
+        side_effect_level: SideEffectLevel | None = None,
         surfaces: Iterable[str] | None = None,
         use_cases: list[str] | None = None,
         examples: list[str] | None = None,

core/tool_framework/tool_decorator.py

@@ -25,8 +25,8 @@ def tool(
     input_model: type[BaseModel] | None = None,
     source: EvidenceSource | None = None,
     source_id: str | None = None,
-    evidence_type: EvidenceType | str | None = None,
-    side_effect_level: SideEffectLevel | str | None = None,
+    evidence_type: EvidenceType | None = None,
+    side_effect_level: SideEffectLevel | None = None,
     surfaces: tuple[str, ...] | None = None,
     use_cases: list[str] | None = None,
     examples: list[str] | None = None,
@@ -60,8 +60,8 @@ def tool[F: Callable[..., Any]](
     input_model: type[BaseModel] | None = None,
     source: EvidenceSource | None = None,
     source_id: str | None = None,
-    evidence_type: EvidenceType | str | None = None,
-    side_effect_level: SideEffectLevel | str | None = None,
+    evidence_type: EvidenceType | None = None,
+    side_effect_level: SideEffectLevel | None = None,
     surfaces: tuple[str, ...] | None = None,
     use_cases: list[str] | None = None,
     examples: list[str] | None = None,
@@ -95,8 +95,8 @@ def tool[F: Callable[..., Any]](
     input_model: type[BaseModel] | None = None,
     source: EvidenceSource | None = None,
     source_id: str | None = None,
-    evidence_type: EvidenceType | str | None = None,
-    side_effect_level: SideEffectLevel | str | None = None,
+    evidence_type: EvidenceType | None = None,
+    side_effect_level: SideEffectLevel | None = None,
     surfaces: tuple[str, ...] | None = None,
     use_cases: list[str] | None = None,
     examples: list[str] | None = None,
@@ -129,8 +129,8 @@ def tool[F: Callable[..., Any]](
     input_model: type[BaseModel] | None = None,
     source: EvidenceSource | None = None,
     source_id: str | None = None,
-    evidence_type: EvidenceType | str | None = None,
-    side_effect_level: SideEffectLevel | str | None = None,
+    evidence_type: EvidenceType | None = None,
+    side_effect_level: SideEffectLevel | None = None,
     surfaces: tuple[str, ...] | None = None,
     use_cases: list[str] | None = None,
     examples: list[str] | None = None,

integrations/buzz/tools/buzz_send_message_tool/tool.py

@@ -5,6 +5,7 @@
 from typing import Any
 
 from core.tool_framework.base import BaseTool
+from core.tool_framework.metadata import SideEffectLevel
 from core.tool_framework.tool_decorator import tool
 from integrations.buzz.tools.buzz_send_message_tool.constants import SOURCE
 from integrations.buzz.tools.buzz_send_message_tool.delivery import (
@@ -35,7 +36,7 @@ class BuzzSendMessageTool(BaseTool):
         "Following up after an investigation with a short status update",
     ]
     requires = ["buzz"]
-    side_effect_level = "external"
+    side_effect_level = SideEffectLevel.EXTERNAL
     requires_approval = True
     approval_reason = "Sends a message via Buzz on your behalf."
     input_schema = {

integrations/datadog/tools/__init__.py

@@ -9,6 +9,7 @@
 import re
 from typing import Any
 
+from core.tool_framework.metadata import EvidenceType, SideEffectLevel
 from core.tool_framework.tool_decorator import tool
 from core.tool_framework.utils.tool_availability import tool_unavailable
 from integrations.datadog._client import make_async_client
@@ -557,8 +558,8 @@ def _metrics_extract_params(sources: dict[str, dict]) -> dict[str, Any]:
     ],
     requires=[],
     source_id="datadog_metrics_api",
-    evidence_type="metrics",
-    side_effect_level="read_only",
+    evidence_type=EvidenceType.METRICS,
+    side_effect_level=SideEffectLevel.READ_ONLY,
     examples=[
         "Check `system.cpu.user` around incident window for saturation patterns.",
         "Run a custom metrics query string for service-specific error-rate metrics.",

integrations/eks/tools/__init__.py

@@ -7,6 +7,7 @@
 import logging
 from typing import Any
 
+from core.tool_framework.metadata import EvidenceType, SideEffectLevel
 from core.tool_framework.tool_decorator import tool
 from core.tool_framework.utils.tool_availability import tool_unavailable
 from integrations.eks.eks_k8s_client import build_k8s_clients
@@ -777,8 +778,8 @@ class ListEKSPodsOutput(BaseModel):
     ],
     requires=["cluster_name"],
     source_id="eks_core_v1",
-    evidence_type="topology",
-    side_effect_level="read_only",
+    evidence_type=EvidenceType.TOPOLOGY,
+    side_effect_level=SideEffectLevel.READ_ONLY,
     examples=[
         "List pods in `payments` namespace to identify CrashLoopBackOff pods.",
         "Use namespace `all` to detect widespread node scheduling issues.",

integrations/github/tools/architecture_issue_tool/tool.py

@@ -5,6 +5,7 @@
 from typing import Any
 
 from core.agent_harness.tools.tool_context import action_context_from_agent_context
+from core.tool_framework.metadata import SideEffectLevel
 from core.tool_framework.tool_decorator import tool
 from integrations.github.tools.architecture_issue_tool.repo_workspace import (
     WorkspaceError,
@@ -78,7 +79,7 @@ def _session_id_from_runtime(context: Any, explicit: str = "") -> str:
     ],
     requires=["owner", "repo"],
     surfaces=("action",),
-    side_effect_level="mutating",
+    side_effect_level=SideEffectLevel.MUTATING,
     input_schema={
         "type": "object",
         "properties": {
@@ -153,7 +154,7 @@ def architecture_clone_repo(
     use_cases=["Cleanup after architecture_clone_repo"],
     anti_examples=["Deleting arbitrary paths outside the architecture workspace"],
     surfaces=("action",),
-    side_effect_level="mutating",
+    side_effect_level=SideEffectLevel.MUTATING,
     input_schema={
         "type": "object",
         "properties": {
@@ -201,7 +202,7 @@ def architecture_cleanup_repo(
     ],
     requires=["repo_name", "observations"],
     surfaces=("action",),
-    side_effect_level="mutating",
+    side_effect_level=SideEffectLevel.MUTATING,
     accepts_runtime_context=True,
     input_schema={
         "type": "object",

integrations/github/tools/ci_fix/tool.py

@@ -5,6 +5,7 @@
 from typing import Any
 
 from core.agent_harness.tools.tool_context import action_context_from_agent_context
+from core.tool_framework.metadata import SideEffectLevel
 from core.tool_framework.tool_decorator import tool
 from integrations.github.client import resolve_github_token
 from integrations.github.helpers import (
@@ -104,7 +105,7 @@ def _confirm_fn(context: Any) -> Any:
         "Fixing GitHub security alerts (use fix_github_security_alert)",
     ],
     surfaces=("action",),
-    side_effect_level="mutating",
+    side_effect_level=SideEffectLevel.MUTATING,
     requires_approval=True,
     approval_reason=("Checks out the PR branch, edits files, commits, and pushes to that branch."),
     parallel_safe=False,

integrations/github/tools/community_followup_tool/__init__.py

@@ -4,6 +4,7 @@
 
 from typing import Any
 
+from core.tool_framework.metadata import SideEffectLevel
 from core.tool_framework.tool_decorator import tool
 from core.tool_framework.utils.tool_availability import tool_unavailable
 from integrations.github.client import GitHubApiError, GitHubRestClient, resolve_github_token
@@ -42,7 +43,7 @@ def _community_extract_params(sources: dict[str, dict]) -> dict[str, Any]:
     ],
     anti_examples=["Posting replies", "Changing GitHub labels or assignees"],
     surfaces=("investigation", "chat"),
-    side_effect_level="read_only",
+    side_effect_level=SideEffectLevel.READ_ONLY,
     input_schema={
         "type": "object",
         "properties": {

integrations/github/tools/github_cli/tool.py

@@ -4,6 +4,7 @@
 
 from typing import Any
 
+from core.tool_framework.metadata import SideEffectLevel
 from core.tool_framework.tool_decorator import tool
 from integrations.github.tools.github_cli.credentials import (
     GITHUB_CLI_INJECTED_PARAMS,
@@ -95,7 +96,7 @@ def _normalize_args(args: list[str] | None) -> list[str]:
         "Inventing repo lists without calling github_cli",
     ],
     surfaces=("action",),
-    side_effect_level="mutating",
+    side_effect_level=SideEffectLevel.MUTATING,
     requires_approval=False,
     input_schema=_ARGS_SCHEMA,
     is_available=_github_cli_available,