hyperpocket 0.0.1__py3-none-any.whl

hyperpocket/tool/README.KR.md

@@ -0,0 +1,68 @@
+# Tool
+
+---
+
+## ToolRequest
+
+각 Tool을 초기화할 때 필요한 정보를 담고 있는 인터페이스
+
+## ToolAuth
+
+ToolAuth는 Tool을 호출하기 위해 필요한 Authentication 정보를 나타내는 객체
+
+다음과 같은 필드가 존재
+
+- auth_provider : tool 호출 시에 어떤 authentication provider의 인증 정보가 필요한지 표시
+    - auth_provider가 명시되지 않는 경우, authentication이 필요없는 Tool로 인식된다.
+- auth_handler : tool 호출 시 어떤 authentication handler를 사용할 것인지를 표시
+    - auth_handler가 명시되지 않는 경우, authentication provider의 default handler가 사용된다.
+- scopes : tool 호출 시에 어떤 authentication scopes가 필요한지를 표시
+    - authentication을 수행하지 않거나, authentication handler가 non-scoped인 경우에는 None값을 사용
+
+## Tool
+
+실제 Tool을 실행하는 인터페이스
+
+```python
+class Tool(BaseModel, abc.ABC):
+    name: str = Field(description="tool name")
+    description: str = Field(description="tool description")
+    argument_json_schema: Optional[dict] = Field(default=None, description="tool argument json schema")
+    auth: Optional[ToolAuth] = Field(default=None, description="authentication information to invoke tool")
+```
+
+### schema_model
+
+Tool.schema_model은 Tool이 호출 될 때 인자로 `profile`과 `thread_id`를 받기 위해 기존 Tool의 argument_json_schema을 wrapping한
+model을 반환
+
+이때 기존의 argument_json_schema는 `body` 필드로 이동
+
+## How to implement
+
+1. Tool을 상속한 클래스를 생성
+    - `invoke` 또는 `ainvoke` 내에서 툴 호출 시 수행할 작업을 정의
+    - Tool을 초기화할 factory method를 정의
+        - 이때 위의 필수 필드에 대한 값을 주입
+
+2. `Pocket` 내의 `ToolLike`에 클래스를 추가(Optional)
+    - `WasmTool`의 경우 ToolRequest, str을 입력으로 받을 수 있음
+    - `FunctionTool`의 경우 Callable을 입력으로 받을 수 있음
+
+3. `Pocket.__init__` 또는 `Pocket._load_tool` 함수 내에서 `ToolLike`값을 기반으로 Tool 초기화 수행
+
+## Invoke Flow
+
+1. `Pocket.invoke`를 통해 최초 Tool calling이 수행된다.
+2. Tool 호출을 위해 authentication이 필요한 경우 `PocketAuth.invoke`를 통해 authentication을 수행
+3. authentication이 완료된 후 `PocketAuth`에서 얻은 authentication 정보를 tool 호출 시 같이 전달
+
+```mermaid
+flowchart TD
+    Z["Agent"] -->|"Invoke tool"| A["Pocket"]
+    A["Pocket"] -->|Requires Authentication?| B{"Yes"}
+    B --> D["PocketAuth: Provide Authentication Info"]
+    D --> E["Pocket: Invoke Tool with Auth Info"]
+    B -->|No| F
+    E --> F["Tool: Perform Operations"]
+```

hyperpocket/tool/README.md

@@ -0,0 +1,75 @@
+# Tool
+
+---
+
+## ToolRequest
+
+The interface that contains information to initiate each tool
+
+## ToolAuth
+
+The class that contains authentication information to invoke tool
+
+authentication information fields are:
+
+- `auth_provider`: Indicates which authentication provider’s credentials are required to invoke the tool.
+    - If auth_provider is not specified, the tool is considered to require no authentication.
+
+- `auth_handler`: Specifies which authentication handler should be used when invoking the tool.
+    - If auth_handler is not specified, the default handler of the authentication provider will be used.
+
+- `scopes`: Indicates the authentication scopes required to invoke the tool.
+    - If authentication is not performed or the authentication handler is non-scoped, the value should be None.
+
+## Tool
+
+The interface to execute tool actually
+
+```python
+class Tool(BaseModel, abc.ABC):
+    name: str = Field(description="tool name")
+    description: str = Field(description="tool description")
+    argument_json_schema: Optional[dict] = Field(default=None, description="tool argument json schema")
+    auth: Optional[ToolAuth] = Field(default=None, description="authentication information to invoke tool")
+```
+
+### schema_model
+
+`Tool.schema_model` returns a model that wraps the existing `argument_json_schema` to include `profile` and `thread_id` as
+arguments when the tool is invoked.
+
+In this process, the original `argument_json_schema` is moved under the `body` field.
+
+## How to implement
+
+1. Create a class that inherits from Tool
+    - Define the tasks to be performed when invoking the tool in invoke or ainvoke.
+    - Define a factory method to initialize the tool.(Optional)
+    - Inject values for the required fields during initialization.
+
+2. Add the class to `ToolLike` in Pocket (Optional)
+    - For `WasmTool`, the input can be a ToolRequest or a str.
+    - For `FunctionTool`, the input can be a Callable.
+
+3. Perform tool initialization in `Pocket.__init__` or `Pocket._load_tool`
+    - The initialization is based on the provided ToolLike value.
+
+## Invoke Flow
+
+1. The initial tool invocation occurs via `Pocket.invoke`.
+2. If authentication is required for tool invocation, authentication is performed using `PocketAuth.invoke`.
+3. After successful authentication, the authentication information obtained from PocketAuth is included when invoking
+   the tool.
+
+```mermaid
+flowchart TD
+    Z["Agent"] -->|"Invoke tool"| A["Pocket"]
+    A["Pocket"] -->|Requires Authentication?| B{"Yes"}
+    B --> D["PocketAuth: Provide Authentication Info"]
+    D --> E["Pocket: Invoke Tool with Auth Info"]
+    B -->|No| F
+    E --> F["Tool: Perform Operations"]
+```
+
+
+

hyperpocket/tool/__init__.py

@@ -0,0 +1,13 @@
+from hyperpocket.tool.function import from_func, function_tool
+from hyperpocket.tool.tool import Tool, ToolRequest, ToolAuth
+from hyperpocket.tool.wasm.tool import from_local, from_git
+
+__all__ = [
+    'Tool',
+    'ToolAuth',
+    'ToolRequest',
+    'from_local',
+    'from_git',
+    "from_func",
+    "function_tool"
+]

hyperpocket/tool/builtins/example/add_tool.py

@@ -0,0 +1,18 @@
+# from pydantic import BaseModel, Field
+# 
+# from pocket.tool.builtin import BuiltinTool
+# from pocket.tool.tool import TAny, TModelGeneric
+# 
+# 
+# class Schema(BaseModel):
+#     a: int = Field(description="first number to add")
+#     b: int = Field(description="second number to add")
+# 
+# 
+# class AddTool(BuiltinTool):
+#     name: str = "add_two_number_tool"
+#     description: str = "add two numbers"
+#     argument_schema: TModelGeneric = Schema
+# 
+#     def invoke(self, a: int, b: int) -> TAny:
+#         return a + b

hyperpocket/tool/function/README.KR.md

@@ -0,0 +1,159 @@
+# Function
+
+python 함수를 tool로 등록해 사용
+
+---
+
+## How To Use
+
+### No Auth
+
+python method를 pocket tool에 그대로 입력
+
+```python
+from hyperpocket import Pocket
+
+pocket = Pocket(tools=[
+    my_function]
+)
+```
+
+### Auth
+
+python method에 `@function_tool`를 사용해 필요한 authentication provider를 명시
+
+```python
+from hyperpocket import Pocket
+from hyperpocket.auth import AuthProvider
+from hyperpocket.tool import function_tool
+
+
+@function_tool(
+    auth_provider=AuthProvider.SLACK,
+    scopes=["channels:history", "im:history", "mpim:history", "groups:history", "reactions:read", "mpim:read",
+            "im:read"]
+)
+def my_function():
+    pass
+
+
+pocket = Pocket(
+    tools=[
+        my_function
+    ]
+)
+```
+
+`from_function`을 통해 pocket을 초기화할 때에만 일시적으로 `FunctionTool`로 변환해 넣어줄 수 있다.
+
+```python
+from hyperpocket import Pocket
+from hyperpocket.auth import AuthProvider
+from hyperpocket.tool import from_func
+from hyperpocket.tool.tool import ToolAuth
+
+Pocket(tools=[
+    from_func(
+        func=my_function,
+        auth=ToolAuth(
+            auth_provider=AuthProvider.SLACK,
+            scopes=["channels:history", "im:history", "mpim:history", "groups:history", "reactions:read", "mpim:read",
+                    "im:read"]
+        )
+    )
+])
+```
+
+authentication access token은 python 함수의 variable keyword로 매핑되어 전달된다.
+
+```python
+from hyperpocket.tool import function_tool
+from hyperpocket.auth import AuthProvider
+
+
+@function_tool(
+    auth_provider=AuthProvider.SLACK
+)
+def my_function(**kwargs):
+    token = kwargs["SLACK_BOT_TOKEN"]
+
+    # ...
+```
+
+- 각 provider 별 mapping key값은 각 provider의 `_ACCESS_TOKEN_KEY` 필드를 확인
+
+## Docstring parsing
+
+docstring을 parsing해 argument 의미 파악
+
+다음 docstring style을 지원
+
+- google style
+- sphinx
+- javadoc
+- plain
+
+### Google Style
+
+```python
+def my_function(a: int, b: int):
+    """
+    My Function
+    
+    Args:
+        a(int): first argument
+        b(int): second argument
+    """
+    pass
+```
+
+### Sphinx Style
+
+```python
+def my_function(a: int, b: int):
+    """
+    My Function
+        
+    :param a: first argument
+    :param b: second argument
+    """
+    pass
+```
+
+## Javadoc Style
+
+```python
+def my_function(a: int, b: int):
+    """
+    My Function
+        
+    @param a: first argument
+    @param b: second argument
+    """
+    pass
+```
+
+## Other Style
+
+```python
+def my_function(a: int, b: int):
+    """
+    My Function
+        
+    @arg a: first argument
+    @arg b: second argument
+    
+    or 
+      
+    :arg a: first argument
+    :arg b: second argument
+    """
+    pass
+```
+
+하나의 docstring에서 여러 style이 혼용되는 경우는 고려하지 않음
+
+## Limits
+
+- input type은 python builtin type과 pydantic만 지원
+

hyperpocket/tool/function/README.md

@@ -0,0 +1,169 @@
+# Function
+
+Register and use Python functions as tools.
+
+---
+
+## How To Use
+
+### No Authentication Required
+
+Directly pass Python methods into the pocket tool.
+
+```python
+from hyperpocket import Pocket
+
+pocket = Pocket(tools=[
+    my_function
+])
+```
+
+### With Authentication
+
+Use the `@function_tool` decorator to specify the required authentication provider for a Python method.
+
+```python
+from hyperpocket import Pocket
+from hyperpocket.auth import AuthProvider
+from hyperpocket.tool import function_tool
+
+
+@function_tool(
+    auth_provider=AuthProvider.SLACK,
+    scopes=["channels:history", "im:history", "mpim:history", "groups:history", "reactions:read", "mpim:read",
+            "im:read"]
+)
+def my_function():
+    pass
+
+
+pocket = Pocket(
+    tools=[
+        my_function
+    ]
+)
+```
+
+You can temporarily convert a function into a FunctionTool when initializing a Pocket instance using `from_func`.
+
+```python
+from hyperpocket import Pocket
+from hyperpocket.auth import AuthProvider
+from hyperpocket.tool import from_func
+from hyperpocket.tool.tool import ToolAuth
+
+Pocket(tools=[
+    from_func(
+        func=my_function,
+        auth=ToolAuth(
+            auth_provider=AuthProvider.SLACK,
+            scopes=["channels:history", "im:history", "mpim:history", "groups:history", "reactions:read", "mpim:read",
+                    "im:read"]
+        )
+    )
+])
+```
+
+Authentication access tokens are passed to the Python function as __variable keyword__ arguments.
+
+```python
+from hyperpocket.tool import function_tool
+from hyperpocket.auth import AuthProvider
+
+
+@function_tool(
+    auth_provider=AuthProvider.SLACK
+)
+def my_function(**kwargs):
+    token = kwargs["SLACK_BOT_TOKEN"]
+
+    # ...
+```
+
+- Check the `_ACCESS_TOKEN_KEY` field of each provider for the mapping key of their access tokens.
+
+## Docstring Parsing
+
+Parse docstrings to understand the meanings of arguments.
+
+The following docstring styles are supported:
+
+- Google Style
+- Sphinx
+- Javadoc
+- Plain
+
+### Google Style
+
+```python
+def my_function(a: int, b: int):
+    """
+    My Function
+    
+    Args:
+        a (int): First argument
+        b (int): Second argument
+    """
+    pass
+```
+
+### Sphinx Style
+
+```python
+def my_function(a: int, b: int):
+    """
+    My Function
+        
+    :param a: First argument
+    :param b: Second argument
+    """
+    pass
+```
+
+### Javadoc Style
+
+```python
+def my_function(a: int, b: int):
+    """
+    My Function
+        
+    @param a: First argument
+    @param b: Second argument
+    """
+    pass
+```
+
+### Other Style
+
+```python
+def my_function(a: int, b: int):
+    """
+    My Function
+        
+    @arg a: First argument
+    @arg b: Second argument
+    
+    or 
+      
+    :arg a: First argument
+    :arg b: Second argument
+    """
+    pass
+```
+
+### Plain
+
+```python
+def my_function(a: int, b: int):
+    """
+    My Function
+        
+    a(int): First argument
+    b(int): Second argument
+    """
+    pass
+```
+
+## Limitations
+
+Input types are limited to Python built-in types and Pydantic.

hyperpocket/tool/function/__init__.py

@@ -0,0 +1,9 @@
+from hyperpocket.tool.function.annotation import function_tool
+from hyperpocket.tool.function.tool import FunctionTool
+
+from_func = FunctionTool.from_func
+
+__all__ = [
+    "from_func",
+    "function_tool"
+]

hyperpocket/tool/function/annotation.py

@@ -0,0 +1,30 @@
+from typing import List, Callable, Optional
+
+from hyperpocket.auth import AuthProvider
+from hyperpocket.tool.function.tool import FunctionTool
+from hyperpocket.tool.tool import ToolAuth
+
+
+def function_tool(func: Optional[Callable] = None, *, auth_provider: AuthProvider = None, scopes: List[str] = None,
+                  auth_handler: str = None):
+    def decorator(inner_func: Callable):
+        if not callable(inner_func):
+            raise ValueError("FunctionTool can only be created from a callable")
+        auth = None
+        if auth_provider is not None:
+            auth = ToolAuth(
+                auth_provider=auth_provider,
+                scopes=scopes if scopes else [],
+                auth_handler=auth_handler
+            )
+
+        return FunctionTool.from_func(
+            func=inner_func,
+            auth=auth,
+        )
+
+    if func is not None:
+        return decorator(func)
+
+    # return FunctionTool
+    return decorator

hyperpocket/tool/function/tool.py

@@ -0,0 +1,87 @@
+import copy
+import inspect
+from typing import Callable, Awaitable, Optional
+
+from pydantic import BaseModel
+
+from hyperpocket.tool.tool import Tool, ToolAuth
+from hyperpocket.util.flatten_json_schema import flatten_json_schema
+from hyperpocket.util.function_to_model import function_to_model
+
+
+class FunctionTool(Tool):
+    """
+    FunctionTool is Tool executing local python method.
+    """
+    func: Callable
+    afunc: Optional[Callable[..., Awaitable[str]]]
+
+    def invoke(self, **kwargs) -> str:
+        binding_args = self._get_binding_args(kwargs)
+        return str(self.func(**binding_args))
+
+    async def ainvoke(self, **kwargs) -> str:
+        binding_args = self._get_binding_args(kwargs)
+        if self.afunc is None:
+            return str(self.func(**binding_args))
+        return str(await self.afunc(**binding_args))
+
+    def _get_binding_args(self, kwargs):
+        _kwargs = copy.deepcopy(kwargs)
+
+        # make body args to model
+        schema_model = self.schema_model()
+        model = schema_model(body=_kwargs["body"])
+        _kwargs.pop("body")
+
+        # body model to dict
+        args = self.model_to_kwargs(model.body)
+
+        # binding args
+        binding_args = {}
+        sig = inspect.signature(self.func)
+        for param_name, param in sig.parameters.items():
+            if param_name not in args:
+                continue
+
+            if param.kind == param.VAR_KEYWORD:
+                # var keyword args should be passed by plain dict
+                binding_args |= args[param_name]
+                binding_args |= _kwargs.get("envs", {})
+
+                if "envs" in _kwargs:
+                    _kwargs.pop("envs")
+
+                binding_args |= _kwargs  # add other kwargs
+                continue
+
+            binding_args[param_name] = args[param_name]
+
+        return binding_args
+
+    @staticmethod
+    def model_to_kwargs(model: BaseModel) -> dict:
+        kwargs = {}
+        for field, value in model.model_fields.items():
+            attr_value = getattr(model, field)
+            kwargs[field] = attr_value
+        return kwargs
+
+    @classmethod
+    def from_func(
+            cls,
+            func: Callable,
+            afunc: Callable[..., Awaitable[str]] = None,
+            auth: Optional[ToolAuth] = None
+    ) -> "FunctionTool":
+        model = function_to_model(func)
+        argument_json_schema = flatten_json_schema(model.model_json_schema())
+
+        return cls(
+            func=func,
+            afunc=afunc,
+            name=func.__name__,
+            description=model.__doc__,
+            argument_json_schema=argument_json_schema,
+            auth=auth
+        )