unique_toolkit 1.8.1__py3-none-any.whl → 1.23.0__py3-none-any.whl

unique_toolkit/_common/endpoint_requestor.py

@@ -1,7 +1,8 @@
 from enum import StrEnum
 from typing import Any, Callable, Generic, Protocol, TypeVar
+from urllib.parse import urljoin, urlparse
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 from typing_extensions import ParamSpec
 
 from unique_toolkit._common.endpoint_builder import (
@@ -24,11 +25,30 @@ CombinedParamsType = TypeVar("CombinedParamsType", bound=BaseModel)
 ResponseT_co = TypeVar("ResponseT_co", bound=BaseModel, covariant=True)
 
 
+class RequestContext(BaseModel):
+    base_url: str
+    headers: dict[str, str] = Field(default_factory=dict)
+
+
+def _verify_url(url: str) -> None:
+    parse_result = urlparse(url)
+    if not (parse_result.netloc and parse_result.scheme):
+        raise ValueError("Scheme and netloc are required for url")
+
+
 class EndpointRequestorProtocol(Protocol, Generic[CombinedParamsSpec, ResponseT_co]):
     @classmethod
     def request(
         cls,
-        headers: dict[str, str],
+        context: RequestContext,
+        *args: CombinedParamsSpec.args,
+        **kwargs: CombinedParamsSpec.kwargs,
+    ) -> ResponseT_co: ...
+
+    @classmethod
+    async def request_async(
+        cls,
+        context: RequestContext,
         *args: CombinedParamsSpec.args,
         **kwargs: CombinedParamsSpec.kwargs,
     ) -> ResponseT_co: ...
@@ -53,7 +73,7 @@ def build_fake_requestor(
         @classmethod
         def request(
             cls,
-            headers: dict[str, str],
+            context: RequestContext,
             *args: CombinedParamsSpec.args,
             **kwargs: CombinedParamsSpec.kwargs,
         ) -> ResponseType:
@@ -66,7 +86,22 @@ def build_fake_requestor(
                     f"Invalid parameters passed to combined model {combined_model.__name__}: {e}"
                 )
 
-            return cls._operation.handle_response(return_value)
+            return cls._operation.handle_response(
+                return_value,
+                model_validate_options=cls._operation.response_validate_options(),
+            )
+
+        @classmethod
+        async def request_async(
+            cls,
+            context: RequestContext,
+            headers: dict[str, str] | None = None,
+            *args: CombinedParamsSpec.args,
+            **kwargs: CombinedParamsSpec.kwargs,
+        ) -> ResponseType:
+            raise NotImplementedError(
+                "Async request not implemented for fake requestor"
+            )
 
     return FakeRequestor
 
@@ -91,7 +126,7 @@ def build_request_requestor(
         @classmethod
         def request(
             cls,
-            headers: dict[str, str],
+            context: RequestContext,
             *args: CombinedParamsSpec.args,
             **kwargs: CombinedParamsSpec.kwargs,
         ) -> ResponseType:
@@ -100,23 +135,204 @@ def build_request_requestor(
                 combined=kwargs
             )
 
-            url = cls._operation.create_url_from_model(path_params)
-            payload = cls._operation.create_payload_from_model(payload_model)
+            path = cls._operation.create_path_from_model(
+                path_params, model_dump_options=cls._operation.path_dump_options()
+            )
+            url = urljoin(context.base_url, path)
+            _verify_url(url)
+
+            payload = cls._operation.create_payload_from_model(
+                payload_model, model_dump_options=cls._operation.payload_dump_options()
+            )
 
             response = requests.request(
                 method=cls._operation.request_method(),
                 url=url,
-                headers=headers,
+                headers=context.headers,
                 json=payload,
             )
-            return cls._operation.handle_response(response.json())
+
+            response_json = response.json()
+
+            return cls._operation.handle_response(
+                response_json,
+                model_validate_options=cls._operation.response_validate_options(),
+            )
+
+        @classmethod
+        async def request_async(
+            cls,
+            base_url: str = "",
+            headers: dict[str, str] | None = None,
+            *args: CombinedParamsSpec.args,
+            **kwargs: CombinedParamsSpec.kwargs,
+        ) -> ResponseType:
+            raise NotImplementedError(
+                "Async request not implemented for request requestor"
+            )
 
     return RequestRequestor
 
 
+def build_httpx_requestor(
+    operation_type: type[
+        ApiOperationProtocol[
+            PathParamsSpec,
+            PathParamsType,
+            PayloadParamSpec,
+            PayloadType,
+            ResponseType,
+        ]
+    ],
+    combined_model: Callable[CombinedParamsSpec, CombinedParamsType],
+) -> type[EndpointRequestorProtocol[CombinedParamsSpec, ResponseType]]:
+    import httpx
+
+    class HttpxRequestor(EndpointRequestorProtocol):
+        _operation = operation_type
+
+        @classmethod
+        def request(
+            cls,
+            context: RequestContext,
+            *args: CombinedParamsSpec.args,
+            **kwargs: CombinedParamsSpec.kwargs,
+        ) -> ResponseType:
+            headers = context.headers or {}
+
+            path_params, payload_model = cls._operation.models_from_combined(
+                combined=kwargs
+            )
+
+            path = cls._operation.create_path_from_model(
+                path_params, model_dump_options=cls._operation.path_dump_options()
+            )
+            url = urljoin(context.base_url, path)
+            _verify_url(url)
+            with httpx.Client() as client:
+                response = client.request(
+                    method=cls._operation.request_method(),
+                    url=url,
+                    headers=headers,
+                    json=cls._operation.create_payload_from_model(
+                        payload_model,
+                        model_dump_options=cls._operation.payload_dump_options(),
+                    ),
+                )
+                response_json = response.json()
+                return cls._operation.handle_response(
+                    response_json,
+                    model_validate_options=cls._operation.response_validate_options(),
+                )
+
+        @classmethod
+        async def request_async(
+            cls,
+            context: RequestContext,
+            *args: CombinedParamsSpec.args,
+            **kwargs: CombinedParamsSpec.kwargs,
+        ) -> ResponseType:
+            headers = context.headers or {}
+
+            path_params, payload_model = cls._operation.models_from_combined(
+                combined=kwargs
+            )
+
+            path = cls._operation.create_path_from_model(
+                path_params, model_dump_options=cls._operation.path_dump_options()
+            )
+            url = urljoin(context.base_url, path)
+            _verify_url(url)
+            async with httpx.AsyncClient() as client:
+                response = await client.request(
+                    method=cls._operation.request_method(),
+                    url=url,
+                    headers=headers,
+                    json=cls._operation.create_payload_from_model(
+                        payload_model,
+                        model_dump_options=cls._operation.payload_dump_options(),
+                    ),
+                )
+                response_json = response.json()
+                return cls._operation.handle_response(
+                    response_json,
+                    model_validate_options=cls._operation.response_validate_options(),
+                )
+
+    return HttpxRequestor
+
+
+def build_aiohttp_requestor(
+    operation_type: type[
+        ApiOperationProtocol[
+            PathParamsSpec,
+            PathParamsType,
+            PayloadParamSpec,
+            PayloadType,
+            ResponseType,
+        ]
+    ],
+    combined_model: Callable[CombinedParamsSpec, CombinedParamsType],
+) -> type[EndpointRequestorProtocol[CombinedParamsSpec, ResponseType]]:
+    import aiohttp
+
+    class AiohttpRequestor(EndpointRequestorProtocol):
+        _operation = operation_type
+
+        @classmethod
+        def request(
+            cls,
+            context: RequestContext,
+            *args: CombinedParamsSpec.args,
+            **kwargs: CombinedParamsSpec.kwargs,
+        ) -> ResponseType:
+            raise NotImplementedError(
+                "Sync request not implemented for aiohttp requestor"
+            )
+
+        @classmethod
+        async def request_async(
+            cls,
+            context: RequestContext,
+            headers: dict[str, str] | None = None,
+            *args: CombinedParamsSpec.args,
+            **kwargs: CombinedParamsSpec.kwargs,
+        ) -> ResponseType:
+            headers = context.headers or {}
+
+            path_params, payload_model = cls._operation.models_from_combined(
+                combined=kwargs
+            )
+            path = cls._operation.create_path_from_model(
+                path_params, model_dump_options=cls._operation.path_dump_options()
+            )
+            url = urljoin(context.base_url, path)
+            _verify_url(url)
+
+            async with aiohttp.ClientSession() as session:
+                response = await session.request(
+                    method=cls._operation.request_method(),
+                    url=url,
+                    headers=headers,
+                    json=cls._operation.create_payload_from_model(
+                        payload=payload_model,
+                        model_dump_options=cls._operation.payload_dump_options(),
+                    ),
+                )
+                response_json = await response.json()
+                return cls._operation.handle_response(
+                    response=response_json,
+                    model_validate_options=cls._operation.response_validate_options(),
+                )
+
+    return AiohttpRequestor
+
+
 class RequestorType(StrEnum):
     REQUESTS = "requests"
     FAKE = "fake"
+    HTTPIX = "httpx"
+    AIOHTTP = "aiohttp"
 
 
 def build_requestor(
@@ -147,6 +363,14 @@ def build_requestor(
                 combined_model=combined_model,
                 return_value=return_value,
             )
+        case RequestorType.HTTPIX:
+            return build_httpx_requestor(
+                operation_type=operation_type, combined_model=combined_model
+            )
+        case RequestorType.AIOHTTP:
+            return build_aiohttp_requestor(
+                operation_type=operation_type, combined_model=combined_model
+            )
 
 
 if __name__ == "__main__":
@@ -169,7 +393,7 @@ if __name__ == "__main__":
 
     UserEndpoint = build_api_operation(
         method=HttpMethods.GET,
-        url_template=Template("https://api.example.com/users/{user_id}"),
+        path_template=Template("/users/{user_id}"),
         path_params_constructor=GetUserPathParams,
         payload_constructor=GetUserRequestBody,
         response_model_type=UserResponse,
@@ -183,19 +407,21 @@ if __name__ == "__main__":
 
     # Note that the return value is a pydantic UserResponse object
     response = FakeUserRequestor().request(
-        headers={"a": "b"},
+        context=RequestContext(base_url="https://example.com", headers={"a": "b"}),
         user_id=123,
         include_profile=True,
     )
 
-    RequestRequstor = build_request_requestor(
+    RequestRequestor = build_request_requestor(
         operation_type=UserEndpoint,
         combined_model=CombinedParams,
     )
 
     # Check type hints
-    response = RequestRequstor().request(
-        headers={"a": "b"}, user_id=123, include_profile=True
+    response = RequestRequestor().request(
+        context=RequestContext(base_url="https://example.com", headers={"a": "b"}),
+        user_id=123,
+        include_profile=True,
     )
 
     print(response.model_dump())

unique_toolkit/_common/exception.py

@@ -35,3 +35,23 @@ class CommonException(Exception):
 
 class ConfigurationException(Exception):
     pass
+
+
+class InfoExceptionForAi(Exception):
+    """
+    This exception is raised as information to the AI.
+    Such that it can be used to inform the user about the error.
+    In a meaningful way.
+    """
+
+    def __init__(
+        self,
+        error_message: str,
+        message_for_ai: str,
+    ):
+        super().__init__(error_message)
+        self._message_for_ai = message_for_ai
+
+    @property
+    def message_for_ai(self):
+        return self._message_for_ai

unique_toolkit/_common/feature_flags/schema.py

@@ -1,4 +1,4 @@
-from pydantic import BaseModel, Field
+from pydantic import BaseModel
 
 from unique_toolkit.agentic.tools.config import get_configuration_dict
 
@@ -7,7 +7,3 @@ class FeatureExtendedSourceSerialization(BaseModel):
     """Mixin for experimental feature in Source serialization"""
 
     model_config = get_configuration_dict()
-    full_sources_serialize_dump: bool = Field(
-        default=False,
-        description="Whether to include the full source object in the tool response. If True, includes the full Source object. If False, uses the old format with only source_number and content.",
-    )

unique_toolkit/_common/referencing.py

@@ -0,0 +1,53 @@
+"""
+Utilities for handling references in the "postprocessed" format, i.e <sup>X</sup>
+"""
+
+import functools
+import re
+from typing import Generator
+
+_REF_DETECTION_PATTERN = re.compile(r"<sup>\s*(?P<reference_number>\d+)\s*</sup>")
+
+
+def _iter_ref_numbers(text: str) -> Generator[int, None, None]:
+    for match in _REF_DETECTION_PATTERN.finditer(text):
+        yield int(match.group("reference_number"))
+
+
+@functools.cache
+def _get_detection_pattern_for_ref(ref_number: int) -> re.Pattern[str]:
+    return re.compile(rf"<sup>\s*{ref_number}\s*</sup>")
+
+
+def get_reference_pattern(ref_number: int) -> str:
+    return f"<sup>{ref_number}</sup>"
+
+
+def get_all_ref_numbers(text: str) -> list[int]:
+    return sorted(set(_iter_ref_numbers(text)))
+
+
+def get_max_ref_number(text: str) -> int | None:
+    return max(_iter_ref_numbers(text), default=None)
+
+
+def replace_ref_number(text: str, ref_number: int, replacement: int | str) -> str:
+    if isinstance(replacement, int):
+        replacement = get_reference_pattern(replacement)
+
+    return _get_detection_pattern_for_ref(ref_number).sub(replacement, text)
+
+
+def remove_ref_number(text: str, ref_number: int) -> str:
+    return _get_detection_pattern_for_ref(ref_number).sub("", text)
+
+
+def remove_all_refs(text: str) -> str:
+    return _REF_DETECTION_PATTERN.sub("", text)
+
+
+def remove_consecutive_ref_space(text: str) -> str:
+    """
+    Remove spaces between consecutive references.
+    """
+    return re.sub(r"</sup>\s*<sup>", "</sup><sup>", text)

unique_toolkit/_common/string_utilities.py

@@ -1,6 +1,7 @@
 import json
 import re
-from typing import Any
+from typing import Any, Iterable, Sequence
+from uuid import uuid4
 
 
 def _is_elementary_type(value: Any) -> bool:
@@ -87,3 +88,53 @@ def extract_dicts_from_string(text: str) -> list[dict[str, Any]]:
             continue
 
     return dictionaries
+
+
+def _replace_in_text_non_overlapping(
+    text: str, repls: Iterable[tuple[str | re.Pattern[str], str]]
+) -> str:
+    for pattern, replacement in repls:
+        text = re.sub(pattern, replacement, text)
+    return text
+
+
+def replace_in_text(
+    text: str, repls: Sequence[tuple[str | re.Pattern[str], str]]
+) -> str:
+    """
+    Replace multiple patterns in text without replacement interference.
+
+    This function performs all replacements independently, preventing cases where
+    a replacement value matches another pattern, which would cause unintended
+    cascading replacements.
+
+    Why this is needed:
+    - Naive sequential replacements can interfere with each other
+    - Example: replacing "foo" -> "bar" and "bar" -> "baz" would incorrectly
+      turn "foo" into "baz" if done sequentially
+    - This function uses a two-phase approach with UUID placeholders to ensure
+      each pattern is replaced exactly once with its intended value
+
+    Args:
+        text: The input text to perform replacements on
+        repls: Sequence of (pattern, replacement) tuples where pattern can be
+               a string or compiled regex pattern
+
+    Returns:
+        Text with all patterns replaced by their corresponding replacements
+
+    Example:
+        >>> text = "foo and bar"
+        >>> repls = [("foo", "bar"), ("bar", "baz")]
+        >>> replace_in_text(text, repls)
+        "bar and baz"  # Both replacements applied independently
+    """
+    if len(repls) == 0:
+        return text
+
+    placeholders = [uuid4().hex for _ in range(len(repls))]
+    orig, repls = zip(*repls)
+
+    # 2 phase replacement, since the map keys and values can overlap
+    text = _replace_in_text_non_overlapping(text, zip(orig, placeholders))
+    return _replace_in_text_non_overlapping(text, zip(placeholders, repls))