unique_toolkit 1.1.3__tar.gz → 1.1.4__tar.gz

{unique_toolkit-1.1.3 → unique_toolkit-1.1.4}/CHANGELOG.md

@@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), 
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+
+## [1.1.4] - 2025-09-23
+- First version human verification on api calls
+
 ## [1.1.3] - 2025-09-23
 - Updated LMI JSON schema input type to include annotated string field with title
 

{unique_toolkit-1.1.3 → unique_toolkit-1.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: unique_toolkit
-Version: 1.1.3
+Version: 1.1.4
 Summary: 
 License: Proprietary
 Author: Cedric Klinkert
@@ -118,6 +118,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), 
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+
+## [1.1.4] - 2025-09-23
+- First version human verification on api calls
+
 ## [1.1.3] - 2025-09-23
 - Updated LMI JSON schema input type to include annotated string field with title
 

{unique_toolkit-1.1.3 → unique_toolkit-1.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "unique_toolkit"
-version = "1.1.3"
+version = "1.1.4"
 description = ""
 authors = [
     "Cedric Klinkert <cedric.klinkert@unique.ch>",

unique_toolkit-1.1.4/unique_toolkit/_common/api_calling/human_verification_manager.py

@@ -0,0 +1,250 @@
+import hashlib
+from datetime import datetime
+from logging import Logger
+from typing import Any, Generic
+
+import jinja2
+from pydantic import BaseModel
+
+from unique_toolkit._common.endpoint_builder import (
+    ApiOperationProtocol,
+    PathParamsSpec,
+    PathParamsType,
+    PayloadParamSpec,
+    PayloadType,
+    ResponseType,
+)
+from unique_toolkit._common.endpoint_requestor import (
+    RequestorType,
+    build_requestor,
+)
+from unique_toolkit._common.pydantic_helpers import create_union_model
+from unique_toolkit._common.string_utilities import (
+    dict_to_markdown_table,
+    extract_dicts_from_string,
+)
+from unique_toolkit.chat.schemas import ChatMessage, ChatMessageRole
+
+
+class HumanConfirmation(BaseModel):
+    payload_hash: str
+    time_stamp: datetime
+
+
+NEXT_USER_MESSAGE_JINJA2_TEMPLATE = jinja2.Template("""I confirm the api call with the following data:
+```json
+{{ api_call_as_json }}
+```""")
+
+
+ASSISTANT_CONFIRMATION_MESSAGE_JINJA2_TEMPLATE = jinja2.Template("""I would like to call the api with the following data:
+
+{{ api_call_as_markdown_table }}
+
+[{{ button_text }}](https://prompt={{ next_user_message | urlencode }})""")
+
+
+class HumanVerificationManagerForApiCalling(
+    Generic[
+        PathParamsSpec,
+        PathParamsType,
+        PayloadParamSpec,
+        PayloadType,
+        ResponseType,
+    ]
+):
+    """
+    Manages human verification for api calling.
+
+    The idea is that the manager is able to produce the verification message to the user
+    and to detect an api call from the user message.
+
+    If it detects such a verification message in the user message, it will call the api
+    and incorporate the response into the user message.
+    """
+
+    def __init__(
+        self,
+        *,
+        logger: Logger,
+        operation: type[
+            ApiOperationProtocol[
+                PathParamsSpec,
+                PathParamsType,
+                PayloadParamSpec,
+                PayloadType,
+                ResponseType,
+            ]
+        ],
+        requestor_type: RequestorType = RequestorType.REQUESTS,
+        **kwargs: dict[str, Any],
+    ):
+        self._logger = logger
+        self._operation = operation
+
+        # Create internal models for this manager instance
+
+        class ConcreteApiCall(BaseModel):
+            confirmation: HumanConfirmation
+            payload: self._operation.payload_model()  # type: ignore
+
+        self._api_call_model = ConcreteApiCall
+
+        self._combined_params_model = create_union_model(
+            model_type_a=self._operation.path_params_model(),
+            model_type_b=self._operation.payload_model(),
+        )
+        self._requestor_type = requestor_type
+        self._requestor = build_requestor(
+            requestor_type=requestor_type,
+            operation_type=operation,
+            combined_model=self._combined_params_model,
+            **kwargs,
+        )
+
+    def detect_api_calls_from_user_message(
+        self, *, last_assistant_message: ChatMessage, user_message: str
+    ) -> PayloadType | None:
+        user_message_dicts = extract_dicts_from_string(user_message)
+        if len(user_message_dicts) == 0:
+            return None
+
+        user_message_dicts.reverse()
+        for user_message_dict in user_message_dicts:
+            try:
+                # Convert dict to payload model first, then create payload
+                api_call = self._api_call_model.model_validate(
+                    user_message_dict, by_alias=True, by_name=True
+                )
+                if self._verify_human_verification(
+                    api_call.confirmation, last_assistant_message
+                ):
+                    return api_call.payload
+            except Exception as e:
+                self._logger.error(f"Error detecting api calls from user message: {e}")
+
+        return None
+
+    def _verify_human_verification(
+        self, confirmation: HumanConfirmation, last_assistant_message: ChatMessage
+    ) -> bool:
+        if (
+            last_assistant_message.role != ChatMessageRole.ASSISTANT
+            or last_assistant_message.content is None
+        ):
+            self._logger.error(
+                "Last assistant message is not an assistant message or content is empty."
+            )
+            return False
+
+        return confirmation.payload_hash in last_assistant_message.content
+
+    def _create_next_user_message(self, payload: PayloadType) -> str:
+        api_call = self._api_call_model(
+            payload=payload,
+            confirmation=HumanConfirmation(
+                payload_hash=hashlib.sha256(
+                    payload.model_dump_json().encode()
+                ).hexdigest(),
+                time_stamp=datetime.now(),
+            ),
+        )
+        return NEXT_USER_MESSAGE_JINJA2_TEMPLATE.render(
+            api_call_as_json=api_call.model_dump_json(indent=2)
+        )
+
+    def create_assistant_confirmation_message(self, *, payload: PayloadType) -> str:
+        return ASSISTANT_CONFIRMATION_MESSAGE_JINJA2_TEMPLATE.render(
+            api_call_as_markdown_table=dict_to_markdown_table(payload.model_dump()),
+            button_text="Please confirm the call by pressing this button.",
+            next_user_message=self._create_next_user_message(payload),
+        )
+
+    def call_api(
+        self,
+        *,
+        headers: dict[str, str],
+        path_params: PathParamsType,
+        payload: PayloadType,
+    ) -> ResponseType:
+        params = path_params.model_dump()
+        params.update(payload.model_dump())
+
+        response = self._requestor.request(
+            headers=headers,
+            **params,
+        )
+        return self._operation.handle_response(response)
+
+
+if __name__ == "__main__":
+    import logging
+    from string import Template
+
+    from unique_toolkit._common.endpoint_builder import (
+        EndpointMethods,
+        build_api_operation,
+    )
+
+    class GetUserPathParams(BaseModel):
+        user_id: int
+
+    class GetUserRequestBody(BaseModel):
+        include_profile: bool = False
+
+    class UserResponse(BaseModel):
+        id: int
+        name: str
+
+    class CombinedParams(GetUserPathParams, GetUserRequestBody):
+        pass
+
+    UserEndpoint = build_api_operation(
+        method=EndpointMethods.GET,
+        url_template=Template("https://api.example.com/users/{user_id}"),
+        path_params_constructor=GetUserPathParams,
+        payload_constructor=GetUserRequestBody,
+        response_model_type=UserResponse,
+    )
+
+    human_verification_manager = HumanVerificationManagerForApiCalling(
+        logger=logging.getLogger(__name__),
+        operation=UserEndpoint,
+        requestor_type=RequestorType.FAKE,
+        return_value={"id": 100, "name": "John Doe"},
+    )
+
+    payload = GetUserRequestBody(include_profile=True)
+
+    api_call = human_verification_manager._api_call_model(
+        payload=payload,
+        confirmation=HumanConfirmation(
+            payload_hash=hashlib.sha256(payload.model_dump_json().encode()).hexdigest(),
+            time_stamp=datetime.now(),
+        ),
+    )
+
+    last_assistant_message = ChatMessage(
+        role=ChatMessageRole.ASSISTANT,
+        text=api_call.confirmation.payload_hash,
+        chat_id="123",
+    )
+
+    user_message_with_api_call = human_verification_manager._create_next_user_message(
+        payload=payload
+    )
+
+    print(user_message_with_api_call)
+
+    payload = human_verification_manager.detect_api_calls_from_user_message(
+        user_message=user_message_with_api_call,
+        last_assistant_message=last_assistant_message,
+    )
+
+    if payload is None:
+        print("❌ Detection failed - payload is None")
+        exit(1)
+    else:
+        print("✅ Detection successful!")
+        print(f"Payload: {payload.model_dump()}")
+        print("✅ Dict extraction from string works correctly!")

{unique_toolkit-1.1.3 → unique_toolkit-1.1.4}/unique_toolkit/_common/endpoint_builder.py

@@ -12,9 +12,11 @@ from typing import (
     ParamSpec,
     Protocol,
     TypeVar,
+    cast,
 )
 
 from pydantic import BaseModel
+from typing_extensions import deprecated
 
 # Paramspecs
 PayloadParamSpec = ParamSpec("PayloadParamSpec")
@@ -31,7 +33,7 @@ PayloadType = TypeVar("PayloadType", bound=BaseModel)
 ModelConstructor = Callable[..., BaseModel]
 
 
-class EndpointMethods(StrEnum):
+class HttpMethods(StrEnum):
     GET = "GET"
     POST = "POST"
     PUT = "PUT"
@@ -41,8 +43,11 @@ class EndpointMethods(StrEnum):
     HEAD = "HEAD"
 
 
-# Necessary for typing of make_endpoint_class
-class EndpointClassProtocol(
+# Backward compatibility TODO: Remove in 2.0.0.
+EndpointMethods = HttpMethods
+
+
+class ApiOperationProtocol(
     Protocol,
     Generic[
         PathParamsSpec,
@@ -52,9 +57,14 @@ class EndpointClassProtocol(
         ResponseType,
     ],
 ):
-    path_params_model: type[PathParamsType]
-    payload_model: type[PayloadType]
-    response_model: type[ResponseType]
+    @staticmethod
+    def path_params_model() -> type[PathParamsType]: ...
+
+    @staticmethod
+    def payload_model() -> type[PayloadType]: ...
+
+    @staticmethod
+    def response_model() -> type[ResponseType]: ...
 
     @staticmethod
     def create_url(
@@ -78,18 +88,23 @@ class EndpointClassProtocol(
     @staticmethod
     def request_method() -> EndpointMethods: ...
 
+    @staticmethod
+    def models_from_combined(
+        combined: dict[str, Any],
+    ) -> tuple[PathParamsType, PayloadType]: ...
+
 
 # Model for any client to implement
-def build_endpoint_class(
+def build_api_operation(
     *,
-    method: EndpointMethods,
+    method: HttpMethods,
     url_template: Template,
     path_params_constructor: Callable[PathParamsSpec, PathParamsType],
     payload_constructor: Callable[PayloadParamSpec, PayloadType],
     response_model_type: type[ResponseType],
     dump_options: dict | None = None,
 ) -> type[
-    EndpointClassProtocol[
+    ApiOperationProtocol[
         PathParamsSpec,
         PathParamsType,
         PayloadParamSpec,
@@ -107,11 +122,6 @@ def build_endpoint_class(
     """
 
     # Verify that the path_params_constructor and payload_constructor are valid pydantic models
-    if not isinstance(path_params_constructor, type(BaseModel)):
-        raise ValueError("path_params_constructor must be a pydantic model")
-    if not isinstance(payload_constructor, type(BaseModel)):
-        raise ValueError("payload_constructor must be a pydantic model")
-
     if not dump_options:
         dump_options = {
             "exclude_unset": True,
@@ -119,10 +129,18 @@ def build_endpoint_class(
             "exclude_defaults": True,
         }
 
-    class EndpointClass(EndpointClassProtocol):
-        path_params_model = path_params_constructor  # type: ignore
-        payload_model = payload_constructor  # type: ignore
-        response_model = response_model_type
+    class Operation(ApiOperationProtocol):
+        @staticmethod
+        def path_params_model() -> type[PathParamsType]:
+            return cast(type[PathParamsType], path_params_constructor)
+
+        @staticmethod
+        def payload_model() -> type[PayloadType]:
+            return cast(type[PayloadType], payload_constructor)
+
+        @staticmethod
+        def response_model() -> type[ResponseType]:
+            return response_model_type
 
         @staticmethod
         def create_url(
@@ -130,7 +148,7 @@ def build_endpoint_class(
             **kwargs: PathParamsSpec.kwargs,
         ) -> str:
             """Create URL from path parameters."""
-            path_model = EndpointClass.path_params_model(*args, **kwargs)
+            path_model = Operation.path_params_model()(*args, **kwargs)
             path_dict = path_model.model_dump(**dump_options)
 
             # Extract expected path parameters from template
@@ -158,7 +176,7 @@ def build_endpoint_class(
             *args: PayloadParamSpec.args, **kwargs: PayloadParamSpec.kwargs
         ) -> dict[str, Any]:
             """Create request body payload."""
-            request_model = EndpointClass.payload_model(*args, **kwargs)
+            request_model = Operation.payload_model()(*args, **kwargs)
             return request_model.model_dump(**dump_options)
 
         @staticmethod
@@ -167,13 +185,58 @@ def build_endpoint_class(
 
         @staticmethod
         def handle_response(response: dict[str, Any]) -> ResponseType:
-            return EndpointClass.response_model.model_validate(response)
+            return Operation.response_model().model_validate(response)
 
         @staticmethod
-        def request_method() -> EndpointMethods:
+        def request_method() -> HttpMethods:
             return method
 
-    return EndpointClass
+        @staticmethod
+        def models_from_combined(
+            combined: dict[str, Any],
+        ) -> tuple[PathParamsType, PayloadType]:
+            path_params = Operation.path_params_model().model_validate(
+                combined, by_alias=True, by_name=True
+            )
+            payload = Operation.payload_model().model_validate(
+                combined, by_alias=True, by_name=True
+            )
+            return path_params, payload
+
+    return Operation
+
+
+@deprecated("Use ApiOperationProtocol instead")
+class EndpointClassProtocol(ApiOperationProtocol):
+    pass
+
+
+@deprecated("Use build_api_operation instead")
+def build_endpoint_class(
+    *,
+    method: HttpMethods,
+    url_template: Template,
+    path_params_constructor: Callable[PathParamsSpec, PathParamsType],
+    payload_constructor: Callable[PayloadParamSpec, PayloadType],
+    response_model_type: type[ResponseType],
+    dump_options: dict | None = None,
+) -> type[
+    ApiOperationProtocol[
+        PathParamsSpec,
+        PathParamsType,
+        PayloadParamSpec,
+        PayloadType,
+        ResponseType,
+    ]
+]:
+    return build_api_operation(
+        method=method,
+        url_template=url_template,
+        path_params_constructor=path_params_constructor,
+        payload_constructor=payload_constructor,
+        response_model_type=response_model_type,
+        dump_options=dump_options,
+    )
 
 
 if __name__ == "__main__":
@@ -195,7 +258,7 @@ if __name__ == "__main__":
         name: str
 
     # Example usage of make_endpoint_class
-    UserEndpoint = build_endpoint_class(
+    UserOperation = build_endpoint_class(
         url_template=Template("/users/${user_id}"),
         path_params_constructor=GetUserPathParams,
         payload_constructor=GetUserRequestBody,
@@ -204,15 +267,15 @@ if __name__ == "__main__":
     )
 
     # Create URL from path parameters
-    url = UserEndpoint.create_url(user_id=123)
+    url = UserOperation.create_url(user_id=123)
     print(f"URL: {url}")
 
     # Create payload from request body parameters
-    payload = UserEndpoint.create_payload(include_profile=True)
+    payload = UserOperation.create_payload(include_profile=True)
     print(f"Payload: {payload}")
 
     # Create response from endpoint
-    response = UserEndpoint.handle_response(
+    response = UserOperation.handle_response(
         {
             "id": 123,
             "name": "John Doe",

{unique_toolkit-1.1.3 → unique_toolkit-1.1.4}/unique_toolkit/_common/endpoint_requestor.py

@@ -5,8 +5,8 @@ from pydantic import BaseModel
 from typing_extensions import ParamSpec
 
 from unique_toolkit._common.endpoint_builder import (
-    EndpointClassProtocol,
-    EndpointMethods,
+    ApiOperationProtocol,
+    HttpMethods,
     PathParamsSpec,
     PathParamsType,
     PayloadParamSpec,
@@ -21,19 +21,22 @@ CombinedParamsSpec = ParamSpec("CombinedParamsSpec")
 CombinedParamsType = TypeVar("CombinedParamsType", bound=BaseModel)
 
 
-class EndpointRequestorProtocol(Protocol, Generic[CombinedParamsSpec, ResponseType]):
+ResponseT_co = TypeVar("ResponseT_co", bound=BaseModel, covariant=True)
+
+
+class EndpointRequestorProtocol(Protocol, Generic[CombinedParamsSpec, ResponseT_co]):
     @classmethod
     def request(
         cls,
         headers: dict[str, str],
         *args: CombinedParamsSpec.args,
         **kwargs: CombinedParamsSpec.kwargs,
-    ) -> ResponseType: ...
+    ) -> ResponseT_co: ...
 
 
 def build_fake_requestor(
-    endpoint_type: type[
-        EndpointClassProtocol[
+    operation_type: type[
+        ApiOperationProtocol[
             PathParamsSpec,
             PathParamsType,
             PayloadParamSpec,
@@ -45,7 +48,7 @@ def build_fake_requestor(
     return_value: dict[str, Any],
 ) -> type[EndpointRequestorProtocol[CombinedParamsSpec, ResponseType]]:
     class FakeRequestor(EndpointRequestorProtocol):
-        _endpoint = endpoint_type
+        _operation = operation_type
 
         @classmethod
         def request(
@@ -55,20 +58,22 @@ def build_fake_requestor(
             **kwargs: CombinedParamsSpec.kwargs,
         ) -> ResponseType:
             try:
-                combined_model(*args, **kwargs)
+                path_params, payload_model = cls._operation.models_from_combined(
+                    combined=kwargs
+                )
             except Exception as e:
                 raise ValueError(
                     f"Invalid parameters passed to combined model {combined_model.__name__}: {e}"
                 )
 
-            return cls._endpoint.handle_response(return_value)
+            return cls._operation.handle_response(return_value)
 
     return FakeRequestor
 
 
 def build_request_requestor(
-    endpoint_type: type[
-        EndpointClassProtocol[
+    operation_type: type[
+        ApiOperationProtocol[
             PathParamsSpec,
             PathParamsType,
             PayloadParamSpec,
@@ -77,11 +82,11 @@ def build_request_requestor(
         ]
     ],
     combined_model: Callable[CombinedParamsSpec, CombinedParamsType],
-) -> type[EndpointRequestorProtocol]:
+) -> type[EndpointRequestorProtocol[CombinedParamsSpec, ResponseType]]:
     import requests
 
     class RequestRequestor(EndpointRequestorProtocol):
-        _endpoint = endpoint_type
+        _operation = operation_type
 
         @classmethod
         def request(
@@ -90,18 +95,21 @@ def build_request_requestor(
             *args: CombinedParamsSpec.args,
             **kwargs: CombinedParamsSpec.kwargs,
         ) -> ResponseType:
-            url = cls._endpoint.create_url_from_model(combined_model(*args, **kwargs))
-            payload = cls._endpoint.create_payload_from_model(
-                combined_model(*args, **kwargs)
+            # Create separate instances for path params and payload using endpoint helper
+            path_params, payload_model = cls._operation.models_from_combined(
+                combined=kwargs
             )
 
+            url = cls._operation.create_url_from_model(path_params)
+            payload = cls._operation.create_payload_from_model(payload_model)
+
             response = requests.request(
-                method=cls._endpoint.request_method(),
+                method=cls._operation.request_method(),
                 url=url,
                 headers=headers,
                 json=payload,
             )
-            return cls._endpoint.handle_response(response.json())
+            return cls._operation.handle_response(response.json())
 
     return RequestRequestor
 
@@ -113,8 +121,8 @@ class RequestorType(StrEnum):
 
 def build_requestor(
     requestor_type: RequestorType,
-    endpoint_type: type[
-        EndpointClassProtocol[
+    operation_type: type[
+        ApiOperationProtocol[
             PathParamsSpec,
             PathParamsType,
             PayloadParamSpec,
@@ -129,13 +137,13 @@ def build_requestor(
     match requestor_type:
         case RequestorType.REQUESTS:
             return build_request_requestor(
-                endpoint_type=endpoint_type, combined_model=combined_model
+                operation_type=operation_type, combined_model=combined_model
             )
         case RequestorType.FAKE:
             if return_value is None:
                 raise ValueError("return_value is required for fake requestor")
             return build_fake_requestor(
-                endpoint_type=endpoint_type,
+                operation_type=operation_type,
                 combined_model=combined_model,
                 return_value=return_value,
             )
@@ -144,7 +152,7 @@ def build_requestor(
 if __name__ == "__main__":
     from string import Template
 
-    from unique_toolkit._common.endpoint_builder import build_endpoint_class
+    from unique_toolkit._common.endpoint_builder import build_api_operation
 
     class GetUserPathParams(BaseModel):
         user_id: int
@@ -159,8 +167,8 @@ if __name__ == "__main__":
     class CombinedParams(GetUserPathParams, GetUserRequestBody):
         pass
 
-    UserEndpoint = build_endpoint_class(
-        method=EndpointMethods.GET,
+    UserEndpoint = build_api_operation(
+        method=HttpMethods.GET,
         url_template=Template("https://api.example.com/users/{user_id}"),
         path_params_constructor=GetUserPathParams,
         payload_constructor=GetUserRequestBody,
@@ -168,7 +176,7 @@ if __name__ == "__main__":
     )
 
     FakeUserRequestor = build_fake_requestor(
-        endpoint_type=UserEndpoint,
+        operation_type=UserEndpoint,
         combined_model=CombinedParams,
         return_value={"id": 100, "name": "John Doe"},
     )
@@ -180,6 +188,16 @@ if __name__ == "__main__":
         include_profile=True,
     )
 
+    RequestRequstor = build_request_requestor(
+        operation_type=UserEndpoint,
+        combined_model=CombinedParams,
+    )
+
+    # Check type hints
+    response = RequestRequstor().request(
+        headers={"a": "b"}, user_id=123, include_profile=True
+    )
+
     print(response.model_dump())
     print(response.model_json_schema())
     print(response.id)