hyperpocket 0.0.1__py3-none-any.whl

hyperpocket/tool/tests/test_function_tool.py

@@ -0,0 +1,266 @@
+from unittest import TestCase
+
+from pydantic import BaseModel
+
+from hyperpocket.auth import AuthProvider
+from hyperpocket.tool.function.annotation import function_tool
+from hyperpocket.tool.function.tool import FunctionTool
+from hyperpocket.util.flatten_json_schema import flatten_json_schema
+
+
+class TestFunctionTool(TestCase):
+
+    def test_function_tool_call(self):
+        # given
+        @function_tool
+        def add_numbers(a: int, b: int):
+            """
+            add two numbers
+            a(int): first name
+            b(int): second name
+            """
+            return a + b
+
+        # when
+        result = add_numbers.invoke(body={
+            "a": 1,
+            "b": 2
+        })
+
+        # then
+        self.assertEqual(result, '3')
+
+    def test_pydantic_input_function_tool_call(self):
+        # given
+        class FirstNumber(BaseModel):
+            first: int
+
+        class SecondNumber(BaseModel):
+            second: int
+
+        @function_tool
+        def add_numbers(a: FirstNumber, b: SecondNumber):
+            """
+            add two numbers
+            a(FirstNumber): first number
+            b(SecondNumber): second number
+            """
+            return a.first + b.second
+
+        # when
+        result = add_numbers.invoke(body={
+            "a": {
+                "first": 1,
+            },
+            "b": {
+                "second": 2
+            }
+        })
+
+        # then
+        self.assertEqual(result, '3')
+
+    def test_register_no_auth_no_init_func_case(self):
+        """
+        Test register functionTool in case of no-auth and no-init function
+        """
+
+        @function_tool
+        def add_numbers(a: int, b: int):
+            """
+            add two numbers
+            a(int): first name
+            b(int): second name
+            """
+            return a + b
+
+        # when
+        result = add_numbers.invoke(body={
+            "a": 1,
+            "b": 2
+        })
+
+        # then
+        self.assertIsInstance(add_numbers, FunctionTool)
+        self.assertEqual(result, '3')
+
+    def test_register_no_auth_init_func_case(self):
+        """
+        Test register functionTool in case of no-auth and init function
+        """
+
+        @function_tool()
+        def add_numbers(a: int, b: int):
+            """
+            add two numbers
+            a(int): first name
+            b(int): second name
+            """
+            return a + b
+
+        # when
+        result = add_numbers.invoke(body={
+            "a": 1,
+            "b": 2
+        })
+
+        # then
+        self.assertIsInstance(add_numbers, FunctionTool)
+        self.assertEqual(result, '3')
+
+    def test_register_auth_init_func_case(self):
+        """
+        Test register functionTool in case of auth and init function
+
+        """
+
+        @function_tool(auth_provider=AuthProvider.SLACK)
+        def add_numbers(a: int, b: int):
+            """
+            add two numbers
+            a(int): first name
+            b(int): second name
+            """
+            return a + b
+
+        # when
+        result = add_numbers.invoke(body={
+            "a": 1,
+            "b": 2
+        },
+            envs={
+                "SLACK_BOT_TOKEN": "test"
+            })
+
+        # then
+        self.assertIsInstance(add_numbers, FunctionTool)
+        self.assertEqual(result, '3')
+
+    def test_google_style_docstring_parsing(self):
+        """
+        Test google style docstring parsing
+        """
+
+        # given
+        @function_tool
+        def add_numbers(a: int, b: int):
+            """
+            add two numbers
+
+            Args:
+                a(int): first name
+                b(int): second name
+            """
+            return a + b
+
+        # when
+        schema = add_numbers.schema_model()
+        schema_json = schema.model_json_schema()
+        flatten_schema_json = flatten_json_schema(schema_json)
+        func_schema = flatten_schema_json["properties"]["body"]
+
+        # then
+        self.assertTrue(str(func_schema["description"]).startswith("add two numbers"))
+        self.assertEqual(func_schema["title"], "add_numbers")
+        self.assertEqual(func_schema["required"], ["a", "b"])
+        self.assertEqual(func_schema["type"], "object")
+        self.assertEqual(func_schema["properties"]["a"]["type"], "integer")
+        self.assertEqual(func_schema["properties"]["a"]["description"], "first name")
+        self.assertEqual(func_schema["properties"]["b"]["type"], "integer")
+        self.assertEqual(func_schema["properties"]["b"]["description"], "second name")
+
+    def test_javadoc_style_docstring_parsing(self):
+        """
+        Test javadoc style docstring parsing
+        """
+
+        # given
+        @function_tool
+        def add_numbers(a: int, b: int):
+            """
+            add two numbers
+
+            @param a first name
+            @param b second name
+            """
+            return a + b
+
+        # when
+        schema = add_numbers.schema_model()
+        schema_json = schema.model_json_schema()
+        flatten_schema_json = flatten_json_schema(schema_json)
+        func_schema = flatten_schema_json["properties"]["body"]
+
+        # then
+        self.assertTrue(str(func_schema["description"]).startswith("add two numbers"))
+        self.assertEqual(func_schema["title"], "add_numbers")
+        self.assertEqual(func_schema["required"], ["a", "b"])
+        self.assertEqual(func_schema["type"], "object")
+        self.assertEqual(func_schema["properties"]["a"]["type"], "integer")
+        self.assertEqual(func_schema["properties"]["a"]["description"], "first name")
+        self.assertEqual(func_schema["properties"]["b"]["type"], "integer")
+        self.assertEqual(func_schema["properties"]["b"]["description"], "second name")
+
+    def test_sphinx_style_docstring_parsing(self):
+        """
+        Test sphinx style docstring parsing
+        """
+
+        # given
+        @function_tool
+        def add_numbers(a: int, b: int):
+            """
+            add two numbers
+
+            :param a: first name
+            :param b: second name
+            """
+            return a + b
+
+        # when
+        schema = add_numbers.schema_model()
+        schema_json = schema.model_json_schema()
+        flatten_schema_json = flatten_json_schema(schema_json)
+        func_schema = flatten_schema_json["properties"]["body"]
+
+        # then
+        self.assertTrue(str(func_schema["description"]).startswith("add two numbers"))
+        self.assertEqual(func_schema["title"], "add_numbers")
+        self.assertEqual(func_schema["required"], ["a", "b"])
+        self.assertEqual(func_schema["type"], "object")
+        self.assertEqual(func_schema["properties"]["a"]["type"], "integer")
+        self.assertEqual(func_schema["properties"]["a"]["description"], "first name")
+        self.assertEqual(func_schema["properties"]["b"]["type"], "integer")
+        self.assertEqual(func_schema["properties"]["b"]["description"], "second name")
+
+    def test_simple_style_docstring_parsing(self):
+        """
+        Test simple docstring parsing
+        """
+
+        # given
+        @function_tool
+        def add_numbers(a: int, b: int):
+            """
+            add two numbers
+
+            a: first name
+            b(int): second name
+            """
+            return a + b
+
+        # when
+        schema = add_numbers.schema_model()
+        schema_json = schema.model_json_schema()
+        flatten_schema_json = flatten_json_schema(schema_json)
+        func_schema = flatten_schema_json["properties"]["body"]
+
+        # then
+        self.assertTrue(str(func_schema["description"]).startswith("add two numbers"))
+        self.assertEqual(func_schema["title"], "add_numbers")
+        self.assertEqual(func_schema["required"], ["a", "b"])
+        self.assertEqual(func_schema["type"], "object")
+        self.assertEqual(func_schema["properties"]["a"]["type"], "integer")
+        self.assertEqual(func_schema["properties"]["a"]["description"], "first name")
+        self.assertEqual(func_schema["properties"]["b"]["type"], "integer")
+        self.assertEqual(func_schema["properties"]["b"]["description"], "second name")

hyperpocket/tool/tool.py

@@ -0,0 +1,106 @@
+import abc
+from typing import TypeVar, Optional, Type
+
+from pydantic import BaseModel, Field
+
+from hyperpocket.auth.provider import AuthProvider
+from hyperpocket.config.logger import pocket_logger
+from hyperpocket.util.json_schema_to_model import json_schema_to_model
+
+
+class ToolAuth(BaseModel):
+    """
+    ToolAuth is an object that represents the authentication information required to invoke a tool
+    """
+    scopes: list[str] = Field(
+        default=None,
+        description="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_provider: Optional[AuthProvider] = Field(
+        default=None,
+        description="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.")
+    auth_handler: Optional[str] = Field(
+        default=None,
+        description="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.")
+
+
+class ToolRequest(abc.ABC):
+    @abc.abstractmethod
+    def __str__(self):
+        raise NotImplementedError
+
+
+class Tool(BaseModel, abc.ABC):
+    """
+    Pocket Tool Interface
+    """
+    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")
+
+    @abc.abstractmethod
+    def invoke(self, **kwargs) -> str:
+        """
+        Invoke the tool
+        """
+        raise NotImplementedError()
+
+    async def ainvoke(self, **kwargs) -> str:
+        """
+        Asynchronously invoke the tool
+        """
+        raise NotImplementedError()
+
+    def schema_model(self) -> Optional[Type[BaseModel]]:
+        """
+        Returns a schema_model that wraps the existing argument_json_schema
+        to include profile and thread_id as arguments when the tool is invoked
+        """
+        return self._get_schema_model(self.name, self.argument_json_schema)
+
+    @classmethod
+    def from_tool_request(cls, tool_req: ToolRequest, **kwargs) -> 'Tool':
+        from hyperpocket.tool.wasm.tool import WasmTool, WasmToolRequest
+        if isinstance(tool_req, WasmToolRequest):
+            return WasmTool.from_tool_request(tool_req, **kwargs)
+        raise ValueError('Unknown tool request type')
+
+    @classmethod
+    def _get_schema_model(cls, name: str, json_schema: Optional[dict]) -> Optional[Type[BaseModel]]:
+        try:
+            if not json_schema:
+                pocket_logger.info(f"{name} tool's json_schema is none.")
+                return None
+            if 'description' not in json_schema:
+                json_schema['description'] = f'The argument of the tool.'
+            extended_schema = {
+                'title': name,
+                'type': 'object',
+                'properties': {
+                    'thread_id': {
+                        'type': 'string',
+                        'default': 'default',
+                        'description': 'The ID of the chat thread where the tool is invoked. Omitted when unknown.',
+                    },
+                    'profile': {
+                        'type': 'string',
+                        'default': 'default',
+                        'description': '''The profile of the user invoking the tool. Inferred from user's messages.
+                        Users can request tools to be invoked in specific personas, which is called a profile.
+                        If the user's profile name can be inferred from the query, pass it as a string in the 'profile'
+                        JSON property. Omitted when unknown.''',
+                    },
+                    'body': json_schema
+                },
+                'required': [
+                    'body',
+                ]
+            }
+            model = json_schema_to_model(extended_schema, name)
+            return model
+        except Exception as e:
+            pocket_logger.warning(f"failed to get tool({name}) schema model. error : {e}")
+            pass

hyperpocket/tool/wasm/README.KR.md

@@ -0,0 +1,144 @@
+# Wasm(WebAssembly)
+
+---
+
+## How To Use
+
+### plain url
+
+`Pocket` 초기화 시 github url을 넣어서 해당 툴을 불러올 수 있다.
+
+```python
+from hyperpocket import Pocket
+
+pocket = Pocket(tools=[
+    'https://github.com/your-organization/your-repository/tree/main',
+])
+```
+
+- 이 경우 기본적으로 `main` branch를 기준으로 코드를 읽어오게 된다.
+
+### from_git
+
+`from_git`을 통해 명시적으로 branch나 경로를 지정해 툴을 불러올 수 있다.
+
+```python
+from hyperpocket import Pocket
+from hyperpocket.tool import from_git
+
+pocket = Pocket(tools=[
+    from_git("https://github.com/your-organization/your-repository", "branch-name", "your/tool/code/path"),
+])
+```
+
+### from_local
+
+`from_local`을 통해 로컬 경로를 지정해 툴을 불러올 수 있다.
+
+```python
+from hyperpocket import Pocket
+from hyperpocket.tool import from_local
+
+pocket = Pocket(tools=[
+    from_local("your/local/tool/code/path")
+])
+```
+
+## WasmToolRequest
+
+WasmTool을 초기화 하기 위한 객체
+
+WasmToolRequest는 다음 build 함수를 제공
+
+- `from_local`
+- `from_git`
+- `from_github`
+
+WasmToolRequest는 각각 request에 대한 `lock` 객체를 가지고 있다.
+
+해당 `lock` 객체들은 `Pocket`에서 `Lockfile` 객체를 통해 관리된다.
+
+```mermaid
+classDiagram
+    class WasmToolRequest {
+        +Lock lock
+        + from_git()
+        + from_local()
+    }
+
+    class Lock{
+        +key()
+        +sync()
+    }
+
+    class GitLock{
+        +key()
+        +sync()
+    }
+
+    class LocalLock{
+        +key()
+        +sync()
+    }
+
+    class Lockfile {
+        +dict[tuple,Lock] locks
+
+        + add_lock()
+        + get_lock()
+        + sync()
+        + write()
+    }
+
+    ToolRequest <|.. WasmToolRequest : Implementation
+    Lock o-- WasmToolRequest : 1..1
+    Lock <|.. GitLock : Implementation
+    Lock <|.. LocalLock : Implementation
+    Lock o-- Lockfile : n..1
+    Lockfile o-- Pocket : 1..1
+```
+
+## WasmTool
+
+```python
+class WasmTool(Tool):
+    _invoker: WasmInvoker = None
+    pkg_lock: Lock = None
+    rel_path: str
+    runtime: ScriptRuntime = None
+    json_schema: Optional[dict] = None
+    readme: Optional[str] = None
+```
+
+- `_invoker` : wasm을 실행시키기 위한 클래스
+- `pkg_lock` : 해당 Tool의 lock 클래스
+    - pkg_lock을 통해 현재 wasm code가 저장되어 있는 패키지 경로를 확인
+- `rel_path` : package 내에서 wasm code가 존재하는 상대 위치
+- `runtime` : wasm code의 runtime 언어
+- `json_schema` : wasm tool의 json schema
+    - `schema.json`로 읽어온 정보
+- `readme` : readme 정보
+
+## WasmInvoker
+
+실제 wasm을 구동하기 위한 클래스
+
+1. runtime 정보, auth 정보, body 정보 등을 종합해 html을 rendering
+2. rendering된 html을 메모리에 저장
+3. wasm 실행을 위한 browser를 실행
+4. browser에서는 서버로 요청을 보내 rendering된 html을 불러옴
+5. 해당 html에서 각 runtime에 맞는 코드를 실행 후 결괏값을 전달
+
+```mermaid
+sequenceDiagram
+    participant WasmTool as WasmTool (Includes Server)
+    participant Browser as Browser (Executes WASM Runtime)
+
+    
+    WasmTool->>WasmTool: Render HTML and Store in Memory
+    WasmTool->>Browser: Launch Browser
+    Browser->>WasmTool: Request Rendered HTML
+    WasmTool->>Browser: Provide Rendered HTML
+    Browser->>Browser: Execute Injected WASM Runtime Script
+    Browser->>WasmTool: Return Execution Result
+```

hyperpocket/tool/wasm/README.md

@@ -0,0 +1,144 @@
+# Wasm(WebAssembly)
+
+---
+
+## How To Use
+
+### plain url
+
+load the tool by providing a GitHub URL
+
+```python
+from hyperpocket import Pocket
+
+pocket = Pocket(tools=[
+    'https://github.com/your-organization/your-repository/tree/main',
+])
+```
+
+- in this case, read tool code from `main` branch by default
+
+### from_git
+
+- using `from_git`, you can specify branch and tool code path
+
+```python
+from hyperpocket import Pocket
+from hyperpocket.tool import from_git
+
+pocket = Pocket(tools=[
+    from_git("https://github.com/your-organization/your-repository", "branch-name", "your/tool/code/path"),
+])
+```
+
+### from_local
+
+- using `from_local`, you can load a tool by specifying a local path
+
+```python
+from hyperpocket import Pocket
+from hyperpocket.tool import from_local
+
+pocket = Pocket(tools=[
+    from_local("your/local/tool/code/path")
+])
+```
+
+## WasmToolRequest
+
+The class to initiate WasmTool
+
+WasmToolRequest offer those build method:
+
+- `from_local`
+- `from_git`
+- `from_github`
+
+Each `WasmToolRequest` has it's own `Lock` object
+
+Those `Lock` object is managed by `Lockfile` in the `Pocket` class
+
+```mermaid
+classDiagram
+    class WasmToolRequest {
+        +Lock lock
+        + from_git()
+        + from_local()
+    }
+
+    class Lock{
+        +key()
+        +sync()
+    }
+
+    class GitLock{
+        +key()
+        +sync()
+    }
+
+    class LocalLock{
+        +key()
+        +sync()
+    }
+
+    class Lockfile {
+        +dict[tuple,Lock] locks
+
+        + add_lock()
+        + get_lock()
+        + sync()
+        + write()
+    }
+
+    ToolRequest <|.. WasmToolRequest : Implementation
+    Lock o-- WasmToolRequest : 1..1
+    Lock <|.. GitLock : Implementation
+    Lock <|.. LocalLock : Implementation
+    Lock o-- Lockfile : n..1
+    Lockfile o-- Pocket : 1..1
+```
+
+## WasmTool
+
+```python
+class WasmTool(Tool):
+    _invoker: WasmInvoker = None
+    pkg_lock: Lock = None
+    rel_path: str
+    runtime: ScriptRuntime = None
+    json_schema: Optional[dict] = None
+    readme: Optional[str] = None
+```
+
+- `_invoker`: A class for executing WASM.
+- `pkg_lock`: The lock class for the tool.
+    - Used to determine the package path where the current WASM code is stored.
+- `rel_path`: The relative path to the location of the WASM code within the package.
+- `runtime`: The runtime language of the WASM code.
+- `json_schema`: The JSON schema for the WASM tool.
+    - Information read from schema.json.
+- `readme`: The README information.
+
+## WasmInvoker
+
+A class for running actual WASM
+
+1. Combines runtime information, authentication details, and body content to render HTML.
+2. Stores the rendered HTML in memory.
+3. Launches a browser to execute the WASM.
+4. The browser sends a request to the server to retrieve the rendered HTML.
+5. Executes code specific to each runtime within the HTML and returns the result.
+
+```mermaid
+sequenceDiagram
+    participant WasmTool as WasmTool (Includes Server)
+    participant Browser as Browser (Executes WASM Runtime)
+
+    
+    WasmTool->>WasmTool: Render HTML and Store in Memory
+    WasmTool->>Browser: Launch Browser
+    Browser->>WasmTool: Request Rendered HTML
+    WasmTool->>Browser: Provide Rendered HTML
+    Browser->>Browser: Execute Injected WASM Runtime Script
+    Browser->>WasmTool: Return Execution Result
+```

hyperpocket/tool/wasm/__init__.py

@@ -0,0 +1,3 @@
+from hyperpocket.tool.wasm.tool import WasmTool
+
+__all__ = ["WasmTool"]