versionhq 1.1.8__py3-none-any.whl → 1.1.9.0__py3-none-any.whl

versionhq/tool/__init__.py

@@ -0,0 +1,53 @@
+from enum import Enum
+
+DEFAULT_AUTH_SCHEME = "OAUTH2"
+
+class ComposioAuthScheme(str, Enum):
+    OAUTH2 = "OAUTH2"
+    BEARER_TOKEN = "BEARER_TOKEN"
+    API_KEY = "API_KEY"
+
+
+class ComposioAppName(str, Enum):
+    """
+    Enum to store app names that we can connect via Composio as data pipelines or destination services.
+    """
+
+    SALESFORCE = "salesforce"
+    AIRTABLE = "airtable"
+    MAILCHIMP = "mailchimp"
+    HUBSPOT = "hubspot"
+    KLAVIYO = "klaviyo"
+    GOOGLESHEET = "googlesheets"
+    GMAIL = "gmail"
+    FACEBOOK = "facebook"
+    TWITTER = "twitter"
+    TWITTER_MEDIA = "twitter_media"
+    LINKEDIN = "linkedin"
+
+
+composio_app_set = [
+    (ComposioAppName.SALESFORCE, ComposioAuthScheme.OAUTH2),
+    (ComposioAppName.AIRTABLE, ComposioAuthScheme.OAUTH2, ComposioAuthScheme.API_KEY, ComposioAuthScheme.BEARER_TOKEN),
+    (ComposioAppName.MAILCHIMP, ComposioAuthScheme.OAUTH2),
+    (ComposioAppName.HUBSPOT, ComposioAuthScheme.OAUTH2, ComposioAuthScheme.BEARER_TOKEN),
+    (ComposioAppName.KLAVIYO, ComposioAuthScheme.OAUTH2, ComposioAuthScheme.API_KEY),
+    (ComposioAppName.GOOGLESHEET, ComposioAuthScheme.OAUTH2),
+    (ComposioAppName.GMAIL, ComposioAuthScheme.OAUTH2, ComposioAuthScheme.BEARER_TOKEN),
+    (ComposioAppName.TWITTER, ComposioAuthScheme.OAUTH2),
+    (ComposioAppName.TWITTER_MEDIA, ComposioAuthScheme.OAUTH2),
+    (ComposioAppName.FACEBOOK, ComposioAuthScheme.OAUTH2),
+    (ComposioAppName.LINKEDIN, ComposioAuthScheme.OAUTH2),
+]
+
+class COMPOSIO_STATUS(str, Enum):
+    INITIATED = "initiated"
+    ACTIVE = "active"
+    FAILED = "failed"
+
+
+
+class ComposioAction(str, Enum):
+    """
+    Enum to store composio's action that can be called via `Actions.xxx`
+    """

versionhq/tool/composio.py

@@ -0,0 +1,149 @@
+import os
+import uuid
+from dotenv import load_dotenv
+from typing import Any, Callable, Type, get_args, get_origin, Optional, Tuple
+
+from pydantic import BaseModel, Field, model_validator, field_validator, UUID4
+from pydantic_core import PydanticCustomError
+
+from composio import ComposioToolSet, Action, App, action
+
+from versionhq.tool import ComposioAppName, ComposioAuthScheme, composio_app_set, COMPOSIO_STATUS
+
+load_dotenv(override=True)
+
+DEFAULT_REDIRECT_URL = os.environ.get("DEFAULT_REDIRECT_URL", None)
+DEFAULT_USER_ID = os.environ.get("DEFAULT_USER_ID", None)
+
+
+class Composio(BaseModel):
+    """
+    Class to handle composio tools.
+    """
+
+    id: UUID4 = Field(default_factory=uuid.uuid4, frozen=True)
+    app_name: str = Field(default=ComposioAppName.HUBSPOT)
+    user_id: str = Field(default=DEFAULT_USER_ID)
+    auth_scheme: str = Field(default=ComposioAuthScheme.OAUTH2)
+    redirect_url: str = Field(default=DEFAULT_REDIRECT_URL, description="redirect url after successful oauth2 connection")
+    connect_request_id: str = Field(default=None, description="store the client's composio id to connect with the app")
+
+    @property
+    def toolset(self) -> ComposioToolSet:
+        return ComposioToolSet(api_key=os.environ.get("COMPOSIO_API_KEY"))
+
+
+    def __name__(self):
+        return self.app_name
+
+
+    @field_validator("id", mode="before")
+    @classmethod
+    def _deny_user_set_id(cls, v: Optional[UUID4]) -> None:
+        if v:
+            raise PydanticCustomError("may_not_set_field", "This field is not to be set by the user.", {})
+
+
+    # @model_validator("user_id", mode="before")
+    # @classmethod
+    # def _deny_no_user_id(cls, v: Optional[str]) -> None:
+    #     if v is None:
+    #         raise PydanticCustomError("user_id_missing", "Need user_id to connect with the tool", {})
+
+
+    @model_validator(mode="after")
+    def validate_app_name(self):
+        if self.app_name not in ComposioAppName:
+            raise PydanticCustomError("no_app_name", f"The app name {self.app_name} is not valid.", {})
+
+        return self
+
+
+    @model_validator(mode="after")
+    def validate_auth_scheme(self):
+        """
+        Raise error when the client uses auth scheme unavailable for the app.
+        """
+        app_set = next(filter(lambda tup: self.app_name in tup, composio_app_set), None)
+        if not app_set:
+            raise  PydanticCustomError("no_app_set", f"The app set of {self.app_name} is missing.", {})
+
+        else:
+            acceptable_auth_scheme = next(filter(lambda item: self.auth_scheme in item, app_set), None)
+            if acceptable_auth_scheme is None:
+                raise  PydanticCustomError("invalid_auth_scheme", f"The app {self.app_name} must have different auth_scheme.", {})
+
+        return self
+
+
+    # connect with composio to use the tool
+    def connect(self, token: Optional[str] = None, api_key: Optional[str] = None) -> Tuple[str | Any]:
+        """
+        Connect with Composio, retrieve `connect_request_id`, and validate the connection.
+        """
+
+        if not self.user_id:
+            raise PydanticCustomError("user_id_missing", "Need user_id to connect with the tool", {})
+
+
+        connection_request, connected_account = None, None
+
+        if self.auth_scheme == ComposioAuthScheme.API_KEY:
+            collected_from_user = {}
+            collected_from_user["api_key"] = api_key
+            connection_request = self.toolset.initiate_connection(
+                connected_account_params = collected_from_user,
+                app=self.app_name,
+                entity_id=self.user_id,
+                auth_scheme=self.auth_scheme,
+            )
+
+        if self.auth_scheme == ComposioAuthScheme.BEARER_TOKEN:
+            collected_from_user = {}
+            collected_from_user["token"] = token
+            connection_request = self.toolset.initiate_connection(
+                connected_account_params = collected_from_user,
+                app=self.app_name,
+                entity_id=self.user_id,
+                auth_scheme=self.auth_scheme,
+            )
+
+        if self.auth_scheme == ComposioAuthScheme.OAUTH2:
+            connection_request = self.toolset.initiate_connection(
+                app=self.app_name,
+                redirect_url = self.redirect_url, # clients will be redirected to this url after successful auth.
+                entity_id=self.user_id,
+                auth_scheme=self.auth_scheme,
+            )
+
+        # connection_request.wait_until_active(self.toolset.client, timeout=60)
+
+        if connection_request.connectionStatus is not COMPOSIO_STATUS.FAILED:
+            self.connect_request_id = connection_request.connectedAccountId
+            connected_account = self.toolset.get_connected_account(id=self.connect_request_id)
+
+            if connected_account.status is not COMPOSIO_STATUS.FAILED:
+                setattr(self.toolset, "entity_id", self.user_id)
+
+        return connected_account, connected_account.status if connected_account else connection_request.connectionStatus
+
+
+
+
+    # @action(toolname=ComposioAppName.HUBSPOT)
+    # def deploy(self, param1: str, param2: str, execute_request: Callable) -> str:
+    #     """
+    #     Define custom actions
+    #     my custom action description which will be passed to llm
+
+    #     :param param1: param1 description which will be passed to llm
+    #     :param param2: param2 description which will be passed to llm
+    #     :return info: return description
+    #     """
+
+    #     response = execute_request(
+    #         "/my_action_endpoint",
+    #         "GET",
+    #         {} # body can be added here
+    #     )    # execute requests by appending credentials to the request
+    #     return str(response) # complete auth dict is available for local use if needed

versionhq/tool/decorator.py

@@ -1,5 +1,6 @@
 from typing import Callable
 from pydantic import BaseModel
+
 from versionhq.tool.model import Tool
 
 
@@ -13,6 +14,7 @@ def tool(*args):
         def _make_tool(f: Callable) -> Tool:
             if f.__doc__ is None:
                 raise ValueError("Function must have a docstring")
+
             if f.__annotations__ is None:
                 raise ValueError("Function must have type annotations")
 
@@ -26,7 +28,7 @@ def tool(*args):
                     },
                 },
             )
-            return Tool(name=tool_name, func=f, args_schema=args_schema)
+            return Tool(name=tool_name, function=f, args_schema=args_schema)
 
         return _make_tool
 

versionhq/tool/model.py

@@ -1,42 +1,26 @@
-from abc import ABC
+from abc import ABC, abstractmethod
 from inspect import signature
 from typing import Any, Dict, Callable, Type, Optional, get_args, get_origin
-from pydantic import InstanceOf, BaseModel, ConfigDict, Field, create_model, field_validator, model_validator
+from pydantic import InstanceOf, BaseModel, ConfigDict, Field, field_validator, model_validator
 
 from versionhq._utils.cache_handler import CacheHandler
 
 
-class Tool(ABC, BaseModel):
-    """
-    The function that will be executed when the tool is called.
-    """
+class BaseTool(ABC, BaseModel):
 
-    class ArgsSchema(BaseModel):
+    class _ArgsSchemaPlaceholder(BaseModel):
         pass
 
-    model_config = ConfigDict()
     name: str = Field(default=None)
-    func: Callable = Field(default=None)
+    goal: str = Field(default=None)
+    args_schema: Type[BaseModel] = Field(default_factory=_ArgsSchemaPlaceholder)
     cache_function: Callable = lambda _args=None, _result=None: True
-    args_schema: Type[BaseModel] = Field(default_factory=ArgsSchema)
-    tool_handler: Optional[Dict[str, Any]] = Field(
-        default=None,
-        description="store tool_handler to record the usage of this tool. to avoid circular import, set as Dict format",
-    )
-
-    @property
-    def description(self):
-        args_schema = {
-            name: { "description": field.description,  "type": Tool._get_arg_annotations(field.annotation) }
-            for name, field in self.args_schema.model_fields.items()
-        }
-        return f"Tool Name: {self.name}\nTool Arguments: {args_schema}\nTool Description: {self.description}"
 
 
     @field_validator("args_schema", mode="before")
     @classmethod
     def _default_args_schema(cls, v: Type[BaseModel]) -> Type[BaseModel]:
-        if not isinstance(v, cls.ArgsSchema):
+        if not isinstance(v, cls._ArgsSchemaPlaceholder):
             return v
 
         return type(
@@ -49,14 +33,15 @@ class Tool(ABC, BaseModel):
             },
         )
 
-    @model_validator(mode="after")
-    def set_up_tool_handler_instance(self):
-        from versionhq.tool.tool_handler import ToolHandler
 
-        if self.tool_handler:
-            ToolHandler(**self.tool_handler)
+    @abstractmethod
+    def _run(self, *args: Any, **kwargs: Any,) -> Any:
+        """any handling"""
+
+
+    def run(self, *args: Any, **kwargs: Any) -> Any:
+        return self._run(*args, **kwargs)
 
-        return self
 
     @staticmethod
     def _get_arg_annotations(annotation: type[Any] | None) -> str:
@@ -67,11 +52,7 @@ class Tool(ABC, BaseModel):
         args = get_args(annotation)
 
         if origin is None:
-            return (
-                annotation.__name__
-                if hasattr(annotation, "__name__")
-                else str(annotation)
-            )
+            return annotation.__name__ if hasattr(annotation, "__name__") else str(annotation)
 
         if args:
             args_str = ", ".join(Tool._get_arg_annotations(arg) for arg in args)
@@ -79,113 +60,157 @@ class Tool(ABC, BaseModel):
 
         return origin.__name__
 
-    def _set_args_schema(self):
-        if self.args_schema is None:
-            class_name = f"{self.__class__.__name__}Schema"
-
-            self.args_schema = type(
-                class_name,
-                (BaseModel,),
-                {
-                    "__annotations__": {
-                        k: v
-                        for k, v in self._run.__annotations__.items()
-                        if k != "return"
-                    },
-                },
-            )
 
-    @classmethod
-    def from_composio(
-        cls, func: Callable = None, tool_name: str = "Composio tool"
-    ) -> "Tool":
+    def _parse_args(self, raw_args: str | dict) -> dict:
         """
-        Create a Pydantic BaseModel instance from Composio tools, ensuring the Tool instance has a func to be executed.
-        Refer to the `args_schema` from the func signature if any. Else, create an `args_schema`.
+        Parse and validate the input arguments against the schema
         """
+        if isinstance(raw_args, str):
+            try:
+                import json
+                raw_args = json.loads(raw_args)
+            except json.JSONDecodeError as e:
+                raise ValueError(f"Failed to parse arguments as JSON: {e}")
+
+        try:
+            validated_args = self.args_schema.model_validate(raw_args)
+            return validated_args.model_dump()
 
-        if not func:
-            raise ValueError("Params must have a callable 'func' attribute.")
-
-        # args_schema = getattr(tool, "args_schema", None)
-        args_fields = {}
-        func_signature = signature(func)
-        annotations = func_signature.parameters
-        for name, param in annotations.items():
-            if name != "self":
-                param_annotation = (
-                    param.annotation if param.annotation != param.empty else Any
-                )
-                field_info = Field(default=..., description="")
-                args_fields[name] = (param_annotation, field_info)
-
-        args_schema = (
-            create_model(f"{tool_name}Input", **args_fields)
-            if args_fields
-            else create_model(f"{tool_name}Input", __base__=BaseModel)
+        except Exception as e:
+            raise ValueError(f"Arguments validation failed: {e}")
+
+
+    def _set_args_schema_from_func(self):
+        class_name = f"{self.__class__.__name__}Schema"
+        self.args_schema = type(
+            class_name,
+            (BaseModel,),
+            { "__annotations__": { k: v for k, v in self._run.__annotations__.items() if k != "return" } },
         )
+        return self
 
-        return cls(name=tool_name, func=func, args_schema=args_schema)
+
+    @property
+    def description(self) -> str:
+        args_schema = {
+            name: {
+                "description": field.description,
+                "type": self._get_arg_annotations(field.annotation),
+            }
+            for name, field in self.args_schema.model_fields.items()
+        }
+
+        return f"Tool Name: {self.name}\nTool Arguments: {args_schema}\nGoal: {self.goal}"
+
+
+
+class Tool(BaseTool):
+
+    function: Callable = Field(default=None)
+    tool_handler: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="store tool_handler to record the usage of this tool. to avoid circular import, set as Dict format",
+    )
+
+    @model_validator(mode="after")
+    def set_up_tool_handler(self):
+        from versionhq.tool.tool_handler import ToolHandler
+
+        if self.tool_handler:
+            ToolHandler(**self.tool_handler)
+        return self
+
+    @model_validator(mode="after")
+    def set_up_function(self):
+        if self.function is None:
+            self.function = self._run
+            self._set_args_schema_from_func()
+        return self
+
+
+    def _run(self, *args: Any, **kwargs: Any) -> Any:
+        return self.function(*args, **kwargs)
 
 
     def run(self, *args, **kwargs) -> Any:
         """
-        Use the tool.
-        When the tool has a func, execute the func and return any response from the func.
-        Else,
-
-        The response will be cascaded to the Task and stored in the TaskOutput.
+        Use tool
         """
+        from versionhq.tool.tool_handler import ToolHandler
 
-        print(f"Using the tool: {self.name}")
         result = None
 
-        if self.func is not None:
-            result = self.func(
-                *args, **kwargs
-            )  #! REFINEME - format - json dict, pydantic, raw
+        if self.function is not None:
+            result = self.function(*args, **kwargs)
 
         else:
             acceptable_args = self.args_schema.model_json_schema()["properties"].keys()
-            arguments = {k: v for k, v in kwargs.items() if k in acceptable_args}
-            tool_called = ToolCalled(tool=self, arguments=arguments)
+            acceptable_kwargs = { k: v for k, v in kwargs.items() if k in acceptable_args }
+            tool_called = ToolSet(tool=self, kwargs=acceptable_kwargs)
 
             if self.tool_handler:
                 if self.tool_handler.has_called_before(tool_called):
-                    self.tool_handler.error = "Agent execution error."
+                    self.tool_handler.error = "Agent execution error"
 
                 elif self.tool_handler.cache:
-                    result = self.tools_handler.cache.read(
-                        tool=tool_called.tool.name, input=tool_called.arguments
-                    )
-                    # from_cache = result is not None
+                    result = self.tools_handler.cache.read(tool=tool_called.tool.name, input=tool_called.kwargs)
                     if result is None:
-                        result = self.invoke(input=arguments)
+                        parsed_kwargs = self._parse_args(input=acceptable_kwargs)
+                        result = self.function(**parsed_kwargs)
 
             else:
-                from versionhq.tool.tool_handler import ToolHandler
-
-                tool_handler = ToolHandler(
-                    last_used_tool=tool_called, cache=CacheHandler()
-                )
+                tool_handler = ToolHandler(last_used_tool=tool_called, cache_handler=CacheHandler())
                 self.tool_handler = tool_handler
-                result = self.invoke(input=arguments)
+                parsed_kwargs = self._parse_args(input=acceptable_kwargs)
+                result = self.function(**parsed_kwargs)
 
         return result
 
 
-class ToolCalled(BaseModel):
+    # @classmethod
+    # def from_composio(
+    #     cls, func: Callable = None, tool_name: str = "Composio tool"
+    # ) -> "Tool":
+    #     """
+    #     Create Tool from the composio tool, ensuring the Tool instance has a func to be executed.
+    #     Refer to the `args_schema` from the func signature if any. Else, create an `args_schema`.
+    #     """
+
+    #     if not func:
+    #         raise ValueError("Params must have a callable 'function' attribute.")
+
+    #     # args_schema = getattr(tool, "args_schema", None)
+    #     args_fields = {}
+    #     func_signature = signature(func)
+    #     annotations = func_signature.parameters
+    #     for name, param in annotations.items():
+    #         if name != "self":
+    #             param_annotation = (
+    #                 param.annotation if param.annotation != param.empty else Any
+    #             )
+    #             field_info = Field(default=..., description="")
+    #             args_fields[name] = (param_annotation, field_info)
+
+    #     args_schema = (
+    #         create_model(f"{tool_name}Input", **args_fields)
+    #         if args_fields
+    #         else create_model(f"{tool_name}Input", __base__=BaseModel)
+    #     )
+
+    #     return cls(name=tool_name, func=func, args_schema=args_schema)
+
+
+class ToolSet(BaseModel):
     """
     Store the tool called and any kwargs used.
     """
-
     tool: InstanceOf[Tool] = Field(..., description="store the tool instance to be called.")
-    arguments: Optional[Dict[str, Any]] = Field(..., description="kwargs passed to the tool")
+    kwargs: Optional[Dict[str, Any]] = Field(..., description="kwargs passed to the tool")
 
 
-class InstructorToolCalled(BaseModel):
+class InstructorToolSet(BaseModel):
     tool: InstanceOf[Tool] = Field(..., description="store the tool instance to be called.")
-    arguments: Optional[Dict[str, Any]] = Field(..., description="kwargs passed to the tool")
+    kwargs: Optional[Dict[str, Any]] = Field(..., description="kwargs passed to the tool")
 
 
 class CacheTool(BaseModel):

versionhq/tool/tool_handler.py

@@ -1,48 +1,43 @@
 from typing import Any, Optional
 from pydantic import InstanceOf
-from versionhq.tool.model import ToolCalled, InstructorToolCalled, CacheTool
+from versionhq.tool.model import ToolSet, InstructorToolSet, CacheTool
 from versionhq._utils.cache_handler import CacheHandler
 
 
 class ToolHandler:
     """
-    Record the tool usage by ToolCalled instance with cache and error recording.
-    Use as a callback function.
+    Record the tool usage by ToolSet instance with cache and error recording.
     """
 
-    last_used_tool: ToolCalled = {}
+    last_used_tool: InstanceOf[ToolSet] | InstanceOf[InstructorToolSet]
     cache: Optional[CacheHandler]
     error: Optional[str]
 
-    def __init__(self, cache_handler: Optional[CacheHandler] = None):
-        """
-        Initialize the callback handler.
-        """
-
+    def __init__(
+            self,
+            last_used_tool: InstanceOf[ToolSet] | InstanceOf[InstructorToolSet] = None,
+            cache_handler: Optional[CacheHandler] = None
+    ):
         self.cache = cache_handler
-        self.last_used_tool = {}
+        self.last_used_tool = last_used_tool
+
 
     def record_last_tool_used(
         self,
-        last_used_tool: InstanceOf[ToolCalled] | InstanceOf[InstructorToolCalled],
+        last_used_tool: InstanceOf[ToolSet] | InstanceOf[InstructorToolSet],
         output: str,
         should_cache: bool = True,
     ) -> Any:
+
         self.last_used_tool = last_used_tool
 
         if self.cache and should_cache and last_used_tool.tool_name != CacheTool().name:
-            self.cache.add(
-                last_used_tool.tool_name,
-                input.last_used_tool.arguments,
-                output=output,
-            )
+            self.cache.add(last_used_tool.tool_name, input.last_used_tool.arguments, output=output)
+
 
-    def has_called_before(self, tool_called: ToolCalled = None) -> bool:
+    def has_called_before(self, tool_called: ToolSet = None) -> bool:
         if tool_called is None or not self.last_used_tool:
             return False
 
         if tool_called := self.last_used_tool:
-            return bool(
-                (tool_called.tool.name == self.last_used_tool.tool.name)
-                and (tool_called.arguments == self.last_used_tool.arguments)
-            )
+            return bool((tool_called.tool.name == self.last_used_tool.tool.name) and (tool_called.arguments == self.last_used_tool.arguments))

{versionhq-1.1.8.dist-info → versionhq-1.1.9.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: versionhq
-Version: 1.1.8
+Version: 1.1.9.0
 Summary: LLM orchestration frameworks for model-agnostic AI agents that handle complex outbound workflows
 Author-email: Kuriko Iwai <kuriko@versi0n.io>
 License: MIT License
@@ -312,7 +312,7 @@ src/
 4. Test the features using the `tests` directory.
 
    - Add a test function to respective components in the `tests` directory.
-   - Add your `LITELLM_API_KEY` and `OPENAI_API_KEY` to the Github `repository secrets` @ settings > secrets & variables > Actions.
+   - Add your `LITELLM_API_KEY`, `OPENAI_API_KEY`, `COMPOSIO_API_KEY`, `DEFAULT_USER_ID` to the Github `repository secrets` @ settings > secrets & variables > Actions.
    - Run a test.
       ```
       uv run pytest tests -vv