deer-agent-framework 0.0__py3-none-any.whl

deer/tools/builtin/git_manager.py

@@ -0,0 +1,67 @@
+from deer.tools import ToolProvider, tool, Return
+
+from dataclasses import dataclass
+from pathlib import Path
+import shlex
+
+
+class GitManagerError(ValueError):
+    pass
+
+
+CommandOut = Return(stdout=str, stderr=str, returncode=int)
+
+
+@dataclass
+class GitManager(ToolProvider):
+
+    def git(self, path: str, *args: str | int) -> CommandOut:
+        quoted_args = " ".join(shlex.quote(str(arg)) for arg in args)
+        return self.run_command(f"git {quoted_args}", cwd=path)
+
+    @tool()
+    def git_status(self, path: str) -> CommandOut:
+        """Returns the short git status for a repository path inside the jail."""
+        return self.git(path, "status", "--short")
+
+    @tool()
+    def git_current_branch(self, path: str) -> CommandOut:
+        """Returns the current branch name for a repository path inside the jail."""
+        return self.git(path, "branch", "--show-current")
+
+    @tool()
+    def git_log(self, path: str, max_count: int) -> CommandOut:
+        """Returns the recent commit log for a repository path inside the jail."""
+        return self.git(
+            path, "log", "--oneline", "--decorate", f"--max-count={max_count}"
+        )
+
+    @tool()
+    def git_diff(self, path: str, target: str) -> CommandOut:
+        """Returns the unstaged diff for a target path inside a repository."""
+        return self.git(path, "diff", "--", target)
+
+    @tool()
+    def git_staged_diff(self, path: str, target: str) -> CommandOut:
+        """Returns the staged diff for a target path inside a repository."""
+        return self.git(path, "diff", "--cached", "--", target)
+
+    @tool()
+    def git_show(self, path: str, revision: str) -> CommandOut:
+        """Returns details for a git revision inside a repository path."""
+        return self.git(path, "show", "--stat", "--patch", revision)
+
+    @tool(modifies_state=True)
+    def git_add(self, path: str, target: str) -> CommandOut:
+        """Stages a target path inside a repository."""
+        return self.git(path, "add", "--", target)
+
+    @tool(modifies_state=True)
+    def git_commit(self, path: str, message: str) -> CommandOut:
+        """Creates a commit in a repository path with the provided message."""
+        return self.git(path, "commit", "-m", message)
+
+    @tool(modifies_state=True)
+    def git_restore(self, path: str, target: str) -> CommandOut:
+        """Restores unstaged changes for a target path inside a repository."""
+        return self.git(path, "restore", "--", target)

deer/tools/builtin/search_manager.py

@@ -0,0 +1,123 @@
+from deer.tools import ToolProvider, tool, Return
+
+from dataclasses import dataclass
+from pathlib import Path
+import shlex
+
+
+class SearchManagerError(ValueError):
+    pass
+
+
+CommandOut = Return(stdout=str, stderr=str, returncode=int)
+
+
+@dataclass
+class SearchManager(ToolProvider):
+
+    def rg(self, path: str, *args: str | int) -> CommandOut:
+        quoted_args = " ".join(shlex.quote(str(arg)) for arg in args)
+        return self.run_command(f"rg {quoted_args}", cwd=path)
+
+    @tool()
+    def search_text(self, path: str, query: str) -> CommandOut:
+        """Searches for literal text under a path inside the jail."""
+        return self.rg(
+            path,
+            "--fixed-strings",
+            "--line-number",
+            "--column",
+            "--no-heading",
+            query,
+            ".",
+        )
+
+    @tool()
+    def search_regex(self, path: str, pattern: str) -> CommandOut:
+        """Searches for a regex pattern under a path inside the jail."""
+        return self.rg(
+            path,
+            "--line-number",
+            "--column",
+            "--no-heading",
+            pattern,
+            ".",
+        )
+
+    @tool()
+    def search_text_ignore_case(self, path: str, query: str) -> CommandOut:
+        """Searches for literal text case-insensitively under a path inside the jail."""
+        return self.rg(
+            path,
+            "--fixed-strings",
+            "--ignore-case",
+            "--line-number",
+            "--column",
+            "--no-heading",
+            query,
+            ".",
+        )
+
+    @tool()
+    def search_regex_ignore_case(self, path: str, pattern: str) -> CommandOut:
+        """Searches for a regex pattern case-insensitively under a path inside the jail."""
+        return self.rg(
+            path,
+            "--ignore-case",
+            "--line-number",
+            "--column",
+            "--no-heading",
+            pattern,
+            ".",
+        )
+
+    @tool()
+    def find_files(self, path: str, pattern: str) -> CommandOut:
+        """Finds files matching a glob pattern under a path inside the jail."""
+        return self.rg(path, "--files", "-g", pattern, ".")
+
+    @tool()
+    def search_file_names(self, path: str, pattern: str) -> CommandOut:
+        """Finds files whose names contain text under a path inside the jail."""
+        return self.rg(path, "--files", "-g", f"*{pattern}*", ".")
+
+    @tool()
+    def list_files(self, path: str) -> CommandOut:
+        """Lists files under a path inside the jail."""
+        return self.rg(path, "--files", ".")
+
+    @tool()
+    def search_by_extension(self, path: str, extension: str) -> CommandOut:
+        """Lists files with an extension under a path inside the jail."""
+        normalized_extension = extension.lstrip(".")
+        return self.rg(path, "--files", "-g", f"*.{normalized_extension}", ".")
+
+    @tool()
+    def search_text_in_files(self, path: str, query: str, glob: str) -> CommandOut:
+        """Searches for literal text under a path, restricted to files matching a glob."""
+        return self.rg(
+            path,
+            "--fixed-strings",
+            "--line-number",
+            "--column",
+            "--no-heading",
+            "-g",
+            glob,
+            query,
+            ".",
+        )
+
+    @tool()
+    def files_with_matches(self, path: str, query: str) -> CommandOut:
+        """Lists files containing literal text under a path inside the jail."""
+        return self.rg(path, "--fixed-strings", "--files-with-matches", query, ".")
+
+    @tool()
+    def files_without_matches(self, path: str, query: str) -> CommandOut:
+        """Lists files that do not contain literal text under a path inside the jail."""
+        return self.rg(path, "--fixed-strings", "--files-without-match", query, ".")
+
+    @tool()
+    def count_matches(self, path: str, query: str) -> CommandOut:
+        """Counts literal text matches per file under a path inside the jail."""
+        return self.rg(path, "--fixed-strings", "--count-matches", query, ".")

deer/tools/decorators.py

@@ -0,0 +1,127 @@
+import inspect
+from typing import get_type_hints, Any, Callable
+from dataclasses import dataclass
+
+from pydantic import BaseModel
+
+from .base import Tool
+
+_TOOL_METADATA_ATTR = "__deer_tool_metadata__"
+_MISSING = object()
+
+
+def tool(
+    *,
+    modifies_state: bool = False,
+):
+    """Mark an instance method as a deterministic tool."""
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        assert func.__doc__, f"Tool '{func.__name__}' must have a docstring annotation."
+
+        metadata = _build_tool_metadata(
+            func=func,
+            name=func.__name__,
+            description=func.__doc__,
+            modifies_state=modifies_state,
+        )
+        setattr(
+            func,
+            _TOOL_METADATA_ATTR,
+            metadata,
+        )
+        return func
+        # return staticmethod(func)
+
+    return decorator
+
+
+@dataclass(slots=True)
+class MethodTool(Tool):
+    """Adapter that exposes a decorated method as a Tool instance."""
+
+    name: str
+    description: str
+    full_description: str
+    params_type: Any
+    return_type: Any
+    method: Callable[..., Any]
+    modifies_state: bool
+
+    def run(
+        self,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        return self.method(**(params or {}))
+
+
+def is_tool_method(obj: Any) -> bool:
+    return hasattr(obj, _TOOL_METADATA_ATTR) and (
+        not obj.__self__.tools or obj.__name__ in obj.__self__.tools
+    )
+
+
+def get_tool_metadata(obj: Any) -> dict[str, Any]:
+    return getattr(obj, _TOOL_METADATA_ATTR)
+
+
+def _build_tool_metadata(
+    *,
+    func: Callable[..., Any],
+    name: str,
+    description: str,
+    modifies_state: bool,
+) -> dict[str, Any]:
+    if not name or not name.strip():
+        raise ValueError("Tool name cannot be empty.")
+
+    if not description or not description.strip():
+        raise ValueError("Tool description cannot be empty.")
+
+    signature = inspect.signature(func)
+    type_hints = get_type_hints(func)
+
+    return_type = type_hints.pop("return")
+    params_type = type_hints
+
+    if issubclass(return_type, BaseModel):
+        return_type = {
+            name: field.annotation for name, field in return_type.model_fields.items()
+        }
+
+    if return_type is _MISSING:
+        raise TypeError(
+            f"Tool '{name}' must declare a return type annotation on "
+            f"{func.__qualname__}."
+        )
+
+    full_description = _build_description(
+        base_description=description.strip(),
+        params_type=params_type,
+        return_type=return_type,
+    )
+
+    return {
+        "name": name,
+        "description": description.strip(),
+        "full_description": full_description,
+        "modifies_state": modifies_state,
+        "params_type": params_type,
+        "return_type": return_type,
+    }
+
+
+def _build_description(
+    *,
+    base_description: str,
+    params_type: Any,
+    return_type: Any,
+) -> str:
+
+    return "\n".join(
+        [
+            base_description,
+            f"Parameters: {params_type}.",
+            f"Return: {return_type}.",
+        ]
+    )

deer/tools/registry.py

@@ -0,0 +1,114 @@
+from typing import Any, Dict, Iterable
+
+from .base import Tool
+from .decorators import MethodTool, get_tool_metadata, is_tool_method
+from deer.schema.io import Return
+
+
+class ToolRegistry:
+    def __init__(self) -> None:
+        self._tools: Dict[str, Tool] = {}
+        self._providers: list = []
+
+    def register(self, *provider_tools: list):
+        for tool in provider_tools:
+            if isinstance(tool, Tool):
+                self._register_tool(tool)
+            else:
+                self._register_collection(tool)
+
+    def _register_tool(self, tool: Tool) -> None:
+        if not tool.name or not tool.name.strip():
+            raise ValueError("Tool name cannot be empty.")
+
+        self._tools[tool.name] = tool
+
+    def _register_collection(self, provider: Any) -> None:
+        self._providers.append(provider)
+        for attr_name in dir(provider):
+
+            if attr_name == "jail":
+                continue
+
+            attr = getattr(provider, attr_name)
+
+            if not is_tool_method(attr):
+                continue
+
+            metadata = get_tool_metadata(attr)
+
+            self.register(
+                MethodTool(
+                    name=metadata["name"],
+                    description=metadata["description"],
+                    full_description=metadata["full_description"],
+                    modifies_state=metadata["modifies_state"],
+                    params_type=metadata["params_type"],
+                    return_type=metadata["return_type"],
+                    method=attr,
+                )
+            )
+
+    def get(self, name: str) -> Tool:
+        if not name or not name.strip():
+            raise KeyError("Tool name cannot be empty.")
+
+        if name not in self._tools:
+            raise KeyError(f"Tool not found: {name}")
+
+        return self._tools[name]
+
+    def has(self, name: str | None) -> bool:
+        if not name:
+            return False
+
+        return name in self._tools
+
+    def list_tools(self) -> Iterable[str]:
+        return self._tools.keys()
+
+    def providers(self):
+        return self._providers
+
+    def set_jail(self, jail_path):
+        self.jail_path = jail_path
+        for provider in self._providers:
+            provider.jail = jail_path
+
+    def describe(self, include_state_modifying=True, markdown=False) -> str:
+        if not self._tools:
+            return "- No tools are available."
+
+        lines = []
+
+        for tool in self._tools.values():
+
+            if not include_state_modifying and tool.modifies_state:
+                continue
+
+            if markdown:
+                cont = tool.description.split('\n')[0]
+                lines.append(f" - `{tool.name}`: *{cont}*")
+            else:
+                cont = tool.full_description.replace("\n", "\n  ")
+                lines.append(
+                    f"- {tool.name}: {cont}"
+                )
+
+        return "\n".join(lines)
+
+
+class EchoTool(Tool):
+    name = "echo"
+    description = "Returns params['echo'] when provided; otherwise returns the input value unchanged."
+    modifies_state = False
+
+    def run(self, params: dict[str, Any] | None = None) -> Return(echo=dict):
+        params = params or {}
+        return params
+
+
+def default_registry() -> ToolRegistry:
+    reg = ToolRegistry()
+    reg.register(EchoTool())
+    return reg

deer/tracing/__init__.py

@@ -0,0 +1,2 @@
+from .store import TraceStore
+from .logging_config import logger, logger_llm

deer/tracing/logging_config.py

@@ -0,0 +1,20 @@
+import logging
+
+formatter = logging.Formatter("%(asctime)s [%(levelname)s] %(message)s")
+
+logger = logging.getLogger("DEER")
+if not logger.handlers:
+    handler = logging.StreamHandler()
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+logger.setLevel(logging.WARNING)
+logger.propagate = False
+
+
+logger_llm = logging.getLogger("DEER-LLM")
+if not logger_llm.handlers:
+    handler = logging.StreamHandler()
+    handler.setFormatter(formatter)
+    logger_llm.addHandler(handler)
+logger_llm.setLevel(logging.WARNING)
+logger_llm.propagate = False

deer/tracing/store.py

@@ -0,0 +1,21 @@
+from typing import List
+from deer.schema.io import StepTrace
+
+
+class TraceStore:
+    def __init__(self) -> None:
+        self._buffer: List[StepTrace] = []
+
+    def reset(self) -> None:
+        """Limpia la traza actual (para una nueva ejecución)."""
+        self._buffer.clear()
+
+    def append(self, trace: StepTrace) -> None:
+        self._buffer.append(trace)
+
+    def extend(self, traces: list[StepTrace]):
+        self._buffer.extend(traces)
+
+    def get_trace(self) -> List[StepTrace]:
+        """Devuelve una copia de la traza acumulada."""
+        return list(self._buffer)

deer/utils/console.py

@@ -0,0 +1,11 @@
+from rich.console import Console
+
+console = Console()
+
+
+def info(message: str):
+    console.print(f"[bold cyan]INFO[/bold cyan]  {message}")
+
+
+def error(message: str):
+    console.print(f"[bold red]ERROR[/bold red] {message}")

deer/utils/plots/__init__.py

@@ -0,0 +1,7 @@
+from .plot_traces import (
+    get_plot_data,
+    plot_steps,
+    draw_trace_frequency_bars,
+    get_execution_metrics,
+    plot_execution_profile,
+)