agno 2.2.13__py3-none-any.whl

agno/tools/todoist.py

@@ -0,0 +1,218 @@
+import json
+from os import getenv
+from typing import Any, Dict, List, Optional
+
+from agno.tools import Toolkit
+from agno.utils.log import logger
+
+try:
+    from todoist_api_python.api import TodoistAPI
+except ImportError:
+    raise ImportError("`todoist-api-python` not installed. Please install using `pip install todoist-api-python`")
+
+
+class TodoistTools(Toolkit):
+    """A toolkit for interacting with Todoist tasks and projects."""
+
+    def __init__(
+        self,
+        api_token: Optional[str] = None,
+        **kwargs,
+    ):
+        """Initialize the Todoist toolkit.
+
+        Args:
+            api_token: Optional Todoist API token. If not provided, will look for TODOIST_API_TOKEN env var
+        """
+        self.api_token = api_token or getenv("TODOIST_API_TOKEN")
+        if not self.api_token:
+            raise ValueError("TODOIST_API_TOKEN not set. Please set the TODOIST_API_TOKEN environment variable.")
+
+        self.api = TodoistAPI(self.api_token)
+
+        tools: List[Any] = [
+            self.create_task,
+            self.get_task,
+            self.update_task,
+            self.close_task,
+            self.delete_task,
+            self.get_active_tasks,
+            self.get_projects,
+        ]
+
+        super().__init__(name="todoist", tools=tools, **kwargs)
+
+    def _task_to_dict(self, task: Any) -> Dict[str, Any]:
+        """Convert a Todoist task to a dictionary with proper typing."""
+        task_dict: Dict[str, Any] = {
+            "id": task.id,
+            "content": task.content,
+            "description": task.description,
+            "project_id": task.project_id,
+            "section_id": task.section_id,
+            "parent_id": task.parent_id,
+            "order": task.order,
+            "priority": task.priority,
+            "url": task.url,
+            "creator_id": task.creator_id,
+            "created_at": task.created_at,
+            "labels": task.labels,
+        }
+        if hasattr(task, "comment_count"):
+            task_dict["comment_count"] = task.comment_count
+        if task.due:
+            task_dict["due"] = {
+                "date": task.due.date,
+                "string": task.due.string,
+                "lang": task.due.lang,
+                "is_recurring": task.due.is_recurring,
+                "timezone": task.due.timezone,
+            }
+        return task_dict
+
+    def create_task(
+        self,
+        content: str,
+        project_id: Optional[str] = None,
+        due_string: Optional[str] = None,
+        priority: Optional[int] = None,
+        labels: Optional[List[str]] = None,
+    ) -> str:
+        """
+        Create a new task in Todoist.
+
+        Args:
+            content: The task content/description
+            project_id: Optional ID of the project to add the task to
+            due_string: Optional due date in natural language (e.g., "tomorrow at 12:00")
+            priority: Optional priority level (1-4, where 4 is highest)
+            labels: Optional list of label names to apply to the task
+
+        Returns:
+            str: JSON string containing the created task
+        """
+        try:
+            task = self.api.add_task(
+                content=content, project_id=project_id, due_string=due_string, priority=priority, labels=labels or []
+            )
+            # Convert task to a dictionary and handle the Due object
+            task_dict = self._task_to_dict(task)
+            return json.dumps(task_dict, default=str)
+        except Exception as e:
+            logger.error(f"Failed to create task: {str(e)}")
+            return json.dumps({"error": str(e)})
+
+    def get_task(self, task_id: str) -> str:
+        """Get a specific task by ID."""
+        try:
+            task = self.api.get_task(task_id)
+            task_dict = self._task_to_dict(task)
+            return json.dumps(task_dict, default=str)
+        except Exception as e:
+            logger.error(f"Failed to get task: {str(e)}")
+            return json.dumps({"error": str(e)})
+
+    def update_task(
+        self,
+        task_id: str,
+        content: Optional[str] = None,
+        description: Optional[str] = None,
+        labels: Optional[List[str]] = None,
+        priority: Optional[int] = None,
+        due_string: Optional[str] = None,
+        due_date: Optional[str] = None,
+        due_datetime: Optional[str] = None,
+        due_lang: Optional[str] = None,
+        assignee_id: Optional[str] = None,
+        section_id: Optional[str] = None,
+    ) -> str:
+        """
+        Update an existing task with the specified parameters.
+
+        Args:
+            task_id: The ID of the task to update
+            content: The task content/name
+            description: The task description
+            labels: Array of label names
+            priority: Task priority from 1 (normal) to 4 (urgent)
+            due_string: Human readable date ("next Monday", "tomorrow", etc)
+            due_date: Specific date in YYYY-MM-DD format
+            due_datetime: Specific date and time in RFC3339 format
+            due_lang: 2-letter code specifying language of due_string ("en", "fr", etc)
+            assignee_id: The responsible user ID
+            section_id: ID of the section to move task to
+
+        Returns:
+            str: JSON string containing success status or error message
+        """
+        try:
+            # Build updates dictionary with only provided parameters
+            updates: Dict[str, Any] = {}
+            if content is not None:
+                updates["content"] = content
+            if description is not None:
+                updates["description"] = description
+            if labels is not None:
+                updates["labels"] = labels
+            if priority is not None:
+                updates["priority"] = priority
+            if due_string is not None:
+                updates["due_string"] = due_string
+            if due_date is not None:
+                updates["due_date"] = due_date
+            if due_datetime is not None:
+                updates["due_datetime"] = due_datetime
+            if due_lang is not None:
+                updates["due_lang"] = due_lang
+            if assignee_id is not None:
+                updates["assignee_id"] = assignee_id
+            if section_id is not None:
+                updates["section_id"] = section_id
+
+            success = self.api.update_task(task_id=task_id, **updates)
+            return json.dumps({"success": success})
+        except Exception as e:
+            error_msg = str(e)
+            logger.error(f"Failed to update task: {error_msg}")
+            return json.dumps({"error": error_msg})
+
+    def close_task(self, task_id: str) -> str:
+        """Mark a task as completed."""
+        try:
+            success = self.api.complete_task(task_id)
+            return json.dumps({"success": success})
+        except Exception as e:
+            logger.error(f"Failed to close task: {str(e)}")
+            return json.dumps({"error": str(e)})
+
+    def delete_task(self, task_id: str) -> str:
+        """Delete a task."""
+        try:
+            success = self.api.delete_task(task_id)
+            return json.dumps({"success": success})
+        except Exception as e:
+            logger.error(f"Failed to delete task: {str(e)}")
+            return json.dumps({"error": str(e)})
+
+    def get_active_tasks(self) -> str:
+        """Get all active (not completed) tasks."""
+        try:
+            tasks_response = self.api.get_tasks()
+            tasks = list(tasks_response)[0]
+            tasks_list = []
+            for task in tasks:
+                task_dict = self._task_to_dict(task)
+                tasks_list.append(task_dict)
+            return json.dumps(tasks_list, default=str)
+        except Exception as e:
+            logger.error(f"Failed to get active tasks: {str(e)}")
+            return json.dumps({"error": str(e)})
+
+    def get_projects(self) -> str:
+        """Get all projects."""
+        try:
+            projects = self.api.get_projects()
+            return json.dumps([project.__dict__ for project in projects])
+        except Exception as e:
+            logger.error(f"Failed to get projects: {str(e)}")
+            return json.dumps({"error": str(e)})

agno/tools/tool_registry.py

@@ -0,0 +1 @@
+from agno.tools.toolkit import Toolkit as ToolRegistry  # type: ignore  # noqa: F401

agno/tools/toolkit.py

@@ -0,0 +1,146 @@
+from collections import OrderedDict
+from typing import Any, Callable, Dict, List, Optional
+
+from agno.tools.function import Function
+from agno.utils.log import log_debug, log_warning, logger
+
+
+class Toolkit:
+    def __init__(
+        self,
+        name: str = "toolkit",
+        tools: List[Callable] = [],
+        instructions: Optional[str] = None,
+        add_instructions: bool = False,
+        include_tools: Optional[list[str]] = None,
+        exclude_tools: Optional[list[str]] = None,
+        requires_confirmation_tools: Optional[list[str]] = None,
+        external_execution_required_tools: Optional[list[str]] = None,
+        stop_after_tool_call_tools: Optional[List[str]] = None,
+        show_result_tools: Optional[List[str]] = None,
+        cache_results: bool = False,
+        cache_ttl: int = 3600,
+        cache_dir: Optional[str] = None,
+        auto_register: bool = True,
+    ):
+        """Initialize a new Toolkit.
+
+        Args:
+            name: A descriptive name for the toolkit
+            tools: List of tools to include in the toolkit
+            instructions: Instructions for the toolkit
+            add_instructions: Whether to add instructions to the toolkit
+            include_tools: List of tool names to include in the toolkit
+            exclude_tools: List of tool names to exclude from the toolkit
+            requires_confirmation_tools: List of tool names that require user confirmation
+            external_execution_required_tools: List of tool names that will be executed outside of the agent loop
+            cache_results (bool): Enable in-memory caching of function results.
+            cache_ttl (int): Time-to-live for cached results in seconds.
+            cache_dir (Optional[str]): Directory to store cache files. Defaults to system temp dir.
+            auto_register (bool): Whether to automatically register all methods in the class.
+            stop_after_tool_call_tools (Optional[List[str]]): List of function names that should stop the agent after execution.
+            show_result_tools (Optional[List[str]]): List of function names whose results should be shown.
+        """
+        self.name: str = name
+        self.tools: List[Callable] = tools
+        self.functions: Dict[str, Function] = OrderedDict()
+        self.instructions: Optional[str] = instructions
+        self.add_instructions: bool = add_instructions
+
+        self.requires_confirmation_tools: list[str] = requires_confirmation_tools or []
+        self.external_execution_required_tools: list[str] = external_execution_required_tools or []
+
+        self.stop_after_tool_call_tools: list[str] = stop_after_tool_call_tools or []
+        self.show_result_tools: list[str] = show_result_tools or []
+
+        self._check_tools_filters(
+            available_tools=[tool.__name__ for tool in tools], include_tools=include_tools, exclude_tools=exclude_tools
+        )
+
+        self.include_tools = include_tools
+        self.exclude_tools = exclude_tools
+
+        self.cache_results: bool = cache_results
+        self.cache_ttl: int = cache_ttl
+        self.cache_dir: Optional[str] = cache_dir
+
+        # Automatically register all methods if auto_register is True
+        if auto_register and self.tools:
+            self._register_tools()
+
+    def _check_tools_filters(
+        self,
+        available_tools: List[str],
+        include_tools: Optional[list[str]] = None,
+        exclude_tools: Optional[list[str]] = None,
+    ) -> None:
+        """Check if `include_tools` and `exclude_tools` are valid"""
+        if include_tools or exclude_tools:
+            if include_tools:
+                missing_includes = set(include_tools) - set(available_tools)
+                if missing_includes:
+                    raise ValueError(f"Included tool(s) not present in the toolkit: {', '.join(missing_includes)}")
+
+            if exclude_tools:
+                missing_excludes = set(exclude_tools) - set(available_tools)
+                if missing_excludes:
+                    raise ValueError(f"Excluded tool(s) not present in the toolkit: {', '.join(missing_excludes)}")
+
+        if self.requires_confirmation_tools:
+            missing_requires_confirmation = set(self.requires_confirmation_tools) - set(available_tools)
+            if missing_requires_confirmation:
+                log_warning(
+                    f"Requires confirmation tool(s) not present in the toolkit: {', '.join(missing_requires_confirmation)}"
+                )
+
+        if self.external_execution_required_tools:
+            missing_external_execution_required = set(self.external_execution_required_tools) - set(available_tools)
+            if missing_external_execution_required:
+                log_warning(
+                    f"External execution required tool(s) not present in the toolkit: {', '.join(missing_external_execution_required)}"
+                )
+
+    def _register_tools(self) -> None:
+        """Register all tools."""
+        for tool in self.tools:
+            self.register(tool)
+
+    def register(self, function: Callable[..., Any], name: Optional[str] = None):
+        """Register a function with the toolkit.
+
+        Args:
+            function: The callable to register
+            name: Optional custom name for the function
+
+        Returns:
+            The registered function
+        """
+        try:
+            tool_name = name or function.__name__
+            if self.include_tools is not None and tool_name not in self.include_tools:
+                return
+            if self.exclude_tools is not None and tool_name in self.exclude_tools:
+                return
+
+            f = Function(
+                name=tool_name,
+                entrypoint=function,
+                cache_results=self.cache_results,
+                cache_dir=self.cache_dir,
+                cache_ttl=self.cache_ttl,
+                requires_confirmation=tool_name in self.requires_confirmation_tools,
+                external_execution=tool_name in self.external_execution_required_tools,
+                stop_after_tool_call=tool_name in self.stop_after_tool_call_tools,
+                show_result=tool_name in self.show_result_tools or tool_name in self.stop_after_tool_call_tools,
+            )
+            self.functions[f.name] = f
+            log_debug(f"Function: {f.name} registered with {self.name}")
+        except Exception as e:
+            logger.warning(f"Failed to create Function for: {function.__name__}")
+            raise e
+
+    def __repr__(self):
+        return f"<{self.__class__.__name__} name={self.name} functions={list(self.functions.keys())}>"
+
+    def __str__(self):
+        return self.__repr__()