hyperpocket 0.0.3__py3-none-any.whl → 0.1.9__py3-none-any.whl

hyperpocket/tool/README.KR.md

@@ -1,68 +0,0 @@
-# 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/builtins/example/add_tool.py

@@ -1,18 +0,0 @@
-# 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

@@ -1,159 +0,0 @@
-# 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/tests/test_function_tool.py

@@ -1,266 +0,0 @@
-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/wasm/README.KR.md

@@ -1,144 +0,0 @@
-# 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
-```