egain-api-python 0.1.1__py3-none-any.whl

egain_api_python/retrieve.py

@@ -0,0 +1,265 @@
+"""Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT."""
+
+from .basesdk import BaseSDK
+from egain_api_python import errors, models, utils
+from egain_api_python._hooks import HookContext
+from egain_api_python.types import OptionalNullable, UNSET
+from egain_api_python.utils import get_security_from_env
+from egain_api_python.utils.unmarshal_json_response import unmarshal_json_response
+from typing import Dict, List, Mapping, Optional, Union
+
+
+class Retrieve(BaseSDK):
+    def post_portal_id_retrieve(
+        self,
+        *,
+        q: str,
+        portal_id: str,
+        dollar_filter_user_profile_id: Optional[str] = None,
+        language: Optional[models.LanguageCodeParameter] = None,
+        dollar_filter_tags: Optional[Dict[str, List[str]]] = None,
+        dollar_filter_topic_ids: Optional[List[str]] = None,
+        channel: Optional[
+            Union[models.RetrieveRequestChannel, models.RetrieveRequestChannelTypedDict]
+        ] = None,
+        event_id: Optional[str] = None,
+        session_id: Optional[str] = None,
+        retries: OptionalNullable[utils.RetryConfig] = UNSET,
+        server_url: Optional[str] = None,
+        timeout_ms: Optional[int] = None,
+        http_headers: Optional[Mapping[str, str]] = None,
+    ) -> models.RetrieveResponse:
+        r"""Retrieve Chunks
+
+        The Retrieve API enables enterprises to directly access relevant content chunks from their organizational knowledge sources. It is designed for scenarios where developers want granular control over retrieved information, such as powering custom search, analytics, or retrieval-augmented generation (RAG) pipelines. <br><br> In addition to raw chunk retrieval, the API can return **Certified Answers** if it meets the 'Certified Answer' threshold score. Responses include relevance scores, metadata, and references to maintain transparency and flexibility. By leveraging the Retrieve API, organizations can build tailored experiences while retaining confidence in the source material.
+
+        :param q: The search query string. The string must be escaped as required by the URL syntax rules.
+        :param portal_id: The ID of the portal being accessed.<br><br>A portal ID is composed of a 2-4 letter prefix, followed by a dash and 4-15 digits.
+        :param dollar_filter_user_profile_id:
+        :param language: The language that describes the details of a resource. Resources available in different languages may differ from each other. <br><br> If lang is not passed, then the portal's default language is used.
+        :param dollar_filter_tags: An object where each key is a **Category Tag ID** (numeric string),   and each value is an array of **Tag IDs** for that category.
+        :param dollar_filter_topic_ids: An array of topic IDs. It is used to restrict search results to specific topics.
+        :param channel:
+        :param event_id: Unique ID for this specific API call or event.
+        :param session_id: ID that ties multiple API calls to the same user session. Will be used as part of to tie events back to a session.
+        :param retries: Override the default retry configuration for this method
+        :param server_url: Override the default server URL for this method
+        :param timeout_ms: Override the default request timeout configuration for this method in milliseconds
+        :param http_headers: Additional headers to set or replace on requests.
+        """
+        base_url = None
+        url_variables = None
+        if timeout_ms is None:
+            timeout_ms = self.sdk_configuration.timeout_ms
+
+        if server_url is not None:
+            base_url = server_url
+        else:
+            base_url = models.POST_PORTAL_ID_RETRIEVE_OP_SERVERS[0]
+            url_variables = {
+                "API_DOMAIN": "api.egain.cloud",
+            }
+
+        request = models.PostPortalIDRetrieveRequest(
+            q=q,
+            portal_id=portal_id,
+            dollar_filter_user_profile_id=dollar_filter_user_profile_id,
+            language=language,
+            dollar_filter_tags=dollar_filter_tags,
+            dollar_filter_topic_ids=dollar_filter_topic_ids,
+            retrieve_request=models.RetrieveRequest(
+                channel=utils.get_pydantic_model(
+                    channel, Optional[models.RetrieveRequestChannel]
+                ),
+                event_id=event_id,
+                session_id=session_id,
+            ),
+        )
+
+        req = self._build_request(
+            method="POST",
+            path="/{portalID}/retrieve",
+            base_url=base_url,
+            url_variables=url_variables,
+            request=request,
+            request_body_required=False,
+            request_has_path_params=True,
+            request_has_query_params=True,
+            user_agent_header="user-agent",
+            accept_header_value="application/json",
+            http_headers=http_headers,
+            security=self.sdk_configuration.security,
+            get_serialized_body=lambda: utils.serialize_request_body(
+                request.retrieve_request,
+                False,
+                True,
+                "json",
+                Optional[models.RetrieveRequest],
+            ),
+            timeout_ms=timeout_ms,
+        )
+
+        if retries == UNSET:
+            if self.sdk_configuration.retry_config is not UNSET:
+                retries = self.sdk_configuration.retry_config
+
+        retry_config = None
+        if isinstance(retries, utils.RetryConfig):
+            retry_config = (retries, ["429", "500", "502", "503", "504"])
+
+        http_res = self.do_request(
+            hook_ctx=HookContext(
+                config=self.sdk_configuration,
+                base_url=base_url or "",
+                operation_id="post_/{portalID}/retrieve",
+                oauth2_scopes=[],
+                security_source=get_security_from_env(
+                    self.sdk_configuration.security, models.Security
+                ),
+            ),
+            request=req,
+            error_status_codes=["400", "4XX", "500", "5XX"],
+            retry_config=retry_config,
+        )
+
+        if utils.match_response(http_res, "200", "application/json"):
+            return unmarshal_json_response(models.RetrieveResponse, http_res)
+        if utils.match_response(http_res, ["400", "4XX"], "*"):
+            http_res_text = utils.stream_to_text(http_res)
+            raise errors.EgainDefaultError(
+                "API error occurred", http_res, http_res_text
+            )
+        if utils.match_response(http_res, ["500", "5XX"], "*"):
+            http_res_text = utils.stream_to_text(http_res)
+            raise errors.EgainDefaultError(
+                "API error occurred", http_res, http_res_text
+            )
+
+        raise errors.EgainDefaultError("Unexpected response received", http_res)
+
+    async def post_portal_id_retrieve_async(
+        self,
+        *,
+        q: str,
+        portal_id: str,
+        dollar_filter_user_profile_id: Optional[str] = None,
+        language: Optional[models.LanguageCodeParameter] = None,
+        dollar_filter_tags: Optional[Dict[str, List[str]]] = None,
+        dollar_filter_topic_ids: Optional[List[str]] = None,
+        channel: Optional[
+            Union[models.RetrieveRequestChannel, models.RetrieveRequestChannelTypedDict]
+        ] = None,
+        event_id: Optional[str] = None,
+        session_id: Optional[str] = None,
+        retries: OptionalNullable[utils.RetryConfig] = UNSET,
+        server_url: Optional[str] = None,
+        timeout_ms: Optional[int] = None,
+        http_headers: Optional[Mapping[str, str]] = None,
+    ) -> models.RetrieveResponse:
+        r"""Retrieve Chunks
+
+        The Retrieve API enables enterprises to directly access relevant content chunks from their organizational knowledge sources. It is designed for scenarios where developers want granular control over retrieved information, such as powering custom search, analytics, or retrieval-augmented generation (RAG) pipelines. <br><br> In addition to raw chunk retrieval, the API can return **Certified Answers** if it meets the 'Certified Answer' threshold score. Responses include relevance scores, metadata, and references to maintain transparency and flexibility. By leveraging the Retrieve API, organizations can build tailored experiences while retaining confidence in the source material.
+
+        :param q: The search query string. The string must be escaped as required by the URL syntax rules.
+        :param portal_id: The ID of the portal being accessed.<br><br>A portal ID is composed of a 2-4 letter prefix, followed by a dash and 4-15 digits.
+        :param dollar_filter_user_profile_id:
+        :param language: The language that describes the details of a resource. Resources available in different languages may differ from each other. <br><br> If lang is not passed, then the portal's default language is used.
+        :param dollar_filter_tags: An object where each key is a **Category Tag ID** (numeric string),   and each value is an array of **Tag IDs** for that category.
+        :param dollar_filter_topic_ids: An array of topic IDs. It is used to restrict search results to specific topics.
+        :param channel:
+        :param event_id: Unique ID for this specific API call or event.
+        :param session_id: ID that ties multiple API calls to the same user session. Will be used as part of to tie events back to a session.
+        :param retries: Override the default retry configuration for this method
+        :param server_url: Override the default server URL for this method
+        :param timeout_ms: Override the default request timeout configuration for this method in milliseconds
+        :param http_headers: Additional headers to set or replace on requests.
+        """
+        base_url = None
+        url_variables = None
+        if timeout_ms is None:
+            timeout_ms = self.sdk_configuration.timeout_ms
+
+        if server_url is not None:
+            base_url = server_url
+        else:
+            base_url = models.POST_PORTAL_ID_RETRIEVE_OP_SERVERS[0]
+            url_variables = {
+                "API_DOMAIN": "api.egain.cloud",
+            }
+
+        request = models.PostPortalIDRetrieveRequest(
+            q=q,
+            portal_id=portal_id,
+            dollar_filter_user_profile_id=dollar_filter_user_profile_id,
+            language=language,
+            dollar_filter_tags=dollar_filter_tags,
+            dollar_filter_topic_ids=dollar_filter_topic_ids,
+            retrieve_request=models.RetrieveRequest(
+                channel=utils.get_pydantic_model(
+                    channel, Optional[models.RetrieveRequestChannel]
+                ),
+                event_id=event_id,
+                session_id=session_id,
+            ),
+        )
+
+        req = self._build_request_async(
+            method="POST",
+            path="/{portalID}/retrieve",
+            base_url=base_url,
+            url_variables=url_variables,
+            request=request,
+            request_body_required=False,
+            request_has_path_params=True,
+            request_has_query_params=True,
+            user_agent_header="user-agent",
+            accept_header_value="application/json",
+            http_headers=http_headers,
+            security=self.sdk_configuration.security,
+            get_serialized_body=lambda: utils.serialize_request_body(
+                request.retrieve_request,
+                False,
+                True,
+                "json",
+                Optional[models.RetrieveRequest],
+            ),
+            timeout_ms=timeout_ms,
+        )
+
+        if retries == UNSET:
+            if self.sdk_configuration.retry_config is not UNSET:
+                retries = self.sdk_configuration.retry_config
+
+        retry_config = None
+        if isinstance(retries, utils.RetryConfig):
+            retry_config = (retries, ["429", "500", "502", "503", "504"])
+
+        http_res = await self.do_request_async(
+            hook_ctx=HookContext(
+                config=self.sdk_configuration,
+                base_url=base_url or "",
+                operation_id="post_/{portalID}/retrieve",
+                oauth2_scopes=[],
+                security_source=get_security_from_env(
+                    self.sdk_configuration.security, models.Security
+                ),
+            ),
+            request=req,
+            error_status_codes=["400", "4XX", "500", "5XX"],
+            retry_config=retry_config,
+        )
+
+        if utils.match_response(http_res, "200", "application/json"):
+            return unmarshal_json_response(models.RetrieveResponse, http_res)
+        if utils.match_response(http_res, ["400", "4XX"], "*"):
+            http_res_text = await utils.stream_to_text_async(http_res)
+            raise errors.EgainDefaultError(
+                "API error occurred", http_res, http_res_text
+            )
+        if utils.match_response(http_res, ["500", "5XX"], "*"):
+            http_res_text = await utils.stream_to_text_async(http_res)
+            raise errors.EgainDefaultError(
+                "API error occurred", http_res, http_res_text
+            )
+
+        raise errors.EgainDefaultError("Unexpected response received", http_res)

egain_api_python/sdk.py

@@ -0,0 +1,216 @@
+"""Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT."""
+
+from .basesdk import BaseSDK
+from .httpclient import AsyncHttpClient, ClientOwner, HttpClient, close_clients
+from .sdkconfiguration import SDKConfiguration
+from .utils.logger import Logger, get_default_logger
+from .utils.retries import RetryConfig
+from egain_api_python import models, utils
+from egain_api_python._hooks import SDKHooks
+from egain_api_python.types import OptionalNullable, UNSET
+import httpx
+import importlib
+import sys
+from typing import Any, Callable, Dict, List, Optional, TYPE_CHECKING, Union, cast
+import weakref
+
+if TYPE_CHECKING:
+    from egain_api_python.aiservices import Aiservices
+    from egain_api_python.content import Content
+    from egain_api_python.portal_sdk import PortalSDK
+
+
+class Egain(BaseSDK):
+    r"""Knowledge Portal Manager APIs: ### License
+    The following licenses are required to use the Knowledge Access APIs:
+    * If the user is an agent, then the *Knowledge + AI* license is required.
+    * If the user is a customer, the *Self-Service* and *Advanced Self-Service* licenses must be available.
+    ### API Resource Limits
+    The following Resources have predefined limits for specific access attributes for Enterprise use.
+
+    | Resource | Attribute | Enterprise
+    | ---------------- | ---------------------------- | ----------
+    | Article Reference Limits |Number of attachments used in any article | 50
+    |  |Number of custom attributes in an article | 15
+    |  |Number of publish views used in an article version | 20
+    | Topic Reference Limits |User-defined topics in a department| 50000
+    |  |Depth of topics  | 20
+    |  |Topics at any level | 2500
+    |  |Number of custom attributes in a topic | 15
+    | Portal Reference Limits | Tag categories in a portal | 15
+    |  |Topics to be included in a portal | 2500
+    |  |Number of articles to display in announcements | 25
+    |  |Maximum related articles in portal setting | 100
+    |  |Usage links and link groups setup for a portal | 25
+
+
+
+    """
+
+    aiservices: "Aiservices"
+    content: "Content"
+    portal: "PortalSDK"
+    _sub_sdk_map = {
+        "aiservices": ("egain_api_python.aiservices", "Aiservices"),
+        "content": ("egain_api_python.content", "Content"),
+        "portal": ("egain_api_python.portal_sdk", "PortalSDK"),
+    }
+
+    def __init__(
+        self,
+        access_token: Optional[
+            Union[Optional[str], Callable[[], Optional[str]]]
+        ] = None,
+        api_domain: Optional[str] = None,
+        server_idx: Optional[int] = None,
+        server_url: Optional[str] = None,
+        url_params: Optional[Dict[str, str]] = None,
+        client: Optional[HttpClient] = None,
+        async_client: Optional[AsyncHttpClient] = None,
+        retry_config: OptionalNullable[RetryConfig] = UNSET,
+        timeout_ms: Optional[int] = None,
+        debug_logger: Optional[Logger] = None,
+    ) -> None:
+        r"""Instantiates the SDK configuring it with the provided parameters.
+
+        :param access_token: The access_token required for authentication
+        :param api_domain: Allows setting the API_DOMAIN variable for url substitution
+        :param server_idx: The index of the server to use for all methods
+        :param server_url: The server URL to use for all methods
+        :param url_params: Parameters to optionally template the server URL with
+        :param client: The HTTP client to use for all synchronous methods
+        :param async_client: The Async HTTP client to use for all asynchronous methods
+        :param retry_config: The retry configuration to use for all supported methods
+        :param timeout_ms: Optional request timeout applied to each operation in milliseconds
+        """
+        client_supplied = True
+        if client is None:
+            client = httpx.Client(follow_redirects=True)
+            client_supplied = False
+
+        assert issubclass(
+            type(client), HttpClient
+        ), "The provided client must implement the HttpClient protocol."
+
+        async_client_supplied = True
+        if async_client is None:
+            async_client = httpx.AsyncClient(follow_redirects=True)
+            async_client_supplied = False
+
+        if debug_logger is None:
+            debug_logger = get_default_logger()
+
+        assert issubclass(
+            type(async_client), AsyncHttpClient
+        ), "The provided async_client must implement the AsyncHttpClient protocol."
+
+        security: Any = None
+        if callable(access_token):
+            # pylint: disable=unnecessary-lambda-assignment
+            security = lambda: models.Security(access_token=access_token())
+        else:
+            security = models.Security(access_token=access_token)
+
+        if server_url is not None:
+            if url_params is not None:
+                server_url = utils.template_url(server_url, url_params)
+        server_defaults: List[Dict[str, str]] = [
+            {
+                "API_DOMAIN": api_domain or "api.egain.cloud",
+            },
+        ]
+
+        BaseSDK.__init__(
+            self,
+            SDKConfiguration(
+                client=client,
+                client_supplied=client_supplied,
+                async_client=async_client,
+                async_client_supplied=async_client_supplied,
+                security=security,
+                server_url=server_url,
+                server_idx=server_idx,
+                server_defaults=server_defaults,
+                retry_config=retry_config,
+                timeout_ms=timeout_ms,
+                debug_logger=debug_logger,
+            ),
+            parent_ref=self,
+        )
+
+        hooks = SDKHooks()
+
+        # pylint: disable=protected-access
+        self.sdk_configuration.__dict__["_hooks"] = hooks
+
+        self.sdk_configuration = hooks.sdk_init(self.sdk_configuration)
+
+        weakref.finalize(
+            self,
+            close_clients,
+            cast(ClientOwner, self.sdk_configuration),
+            self.sdk_configuration.client,
+            self.sdk_configuration.client_supplied,
+            self.sdk_configuration.async_client,
+            self.sdk_configuration.async_client_supplied,
+        )
+
+    def dynamic_import(self, modname, retries=3):
+        for attempt in range(retries):
+            try:
+                return importlib.import_module(modname)
+            except KeyError:
+                # Clear any half-initialized module and retry
+                sys.modules.pop(modname, None)
+                if attempt == retries - 1:
+                    break
+        raise KeyError(f"Failed to import module '{modname}' after {retries} attempts")
+
+    def __getattr__(self, name: str):
+        if name in self._sub_sdk_map:
+            module_path, class_name = self._sub_sdk_map[name]
+            try:
+                module = self.dynamic_import(module_path)
+                klass = getattr(module, class_name)
+                instance = klass(self.sdk_configuration, parent_ref=self)
+                setattr(self, name, instance)
+                return instance
+            except ImportError as e:
+                raise AttributeError(
+                    f"Failed to import module {module_path} for attribute {name}: {e}"
+                ) from e
+            except AttributeError as e:
+                raise AttributeError(
+                    f"Failed to find class {class_name} in module {module_path} for attribute {name}: {e}"
+                ) from e
+
+        raise AttributeError(
+            f"'{type(self).__name__}' object has no attribute '{name}'"
+        )
+
+    def __dir__(self):
+        default_attrs = list(super().__dir__())
+        lazy_attrs = list(self._sub_sdk_map.keys())
+        return sorted(list(set(default_attrs + lazy_attrs)))
+
+    def __enter__(self):
+        return self
+
+    async def __aenter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if (
+            self.sdk_configuration.client is not None
+            and not self.sdk_configuration.client_supplied
+        ):
+            self.sdk_configuration.client.close()
+        self.sdk_configuration.client = None
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        if (
+            self.sdk_configuration.async_client is not None
+            and not self.sdk_configuration.async_client_supplied
+        ):
+            await self.sdk_configuration.async_client.aclose()
+        self.sdk_configuration.async_client = None

egain_api_python/sdkconfiguration.py

@@ -0,0 +1,50 @@
+"""Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT."""
+
+from ._version import (
+    __gen_version__,
+    __openapi_doc_version__,
+    __user_agent__,
+    __version__,
+)
+from .httpclient import AsyncHttpClient, HttpClient
+from .utils import Logger, RetryConfig, remove_suffix
+from dataclasses import dataclass, field
+from egain_api_python import models
+from egain_api_python.types import OptionalNullable, UNSET
+from pydantic import Field
+from typing import Callable, Dict, List, Optional, Tuple, Union
+
+
+SERVERS = [
+    "https://${API_DOMAIN}/knowledge/portalmgr/v4",
+    # Production Server
+]
+"""Contains the list of servers available to the SDK"""
+
+
+@dataclass
+class SDKConfiguration:
+    client: Union[HttpClient, None]
+    client_supplied: bool
+    async_client: Union[AsyncHttpClient, None]
+    async_client_supplied: bool
+    debug_logger: Logger
+    security: Optional[Union[models.Security, Callable[[], models.Security]]] = None
+    server_url: Optional[str] = ""
+    server_idx: Optional[int] = 0
+    server_defaults: List[Dict[str, str]] = field(default_factory=List)
+    language: str = "python"
+    openapi_doc_version: str = __openapi_doc_version__
+    sdk_version: str = __version__
+    gen_version: str = __gen_version__
+    user_agent: str = __user_agent__
+    retry_config: OptionalNullable[RetryConfig] = Field(default_factory=lambda: UNSET)
+    timeout_ms: Optional[int] = None
+
+    def get_server_details(self) -> Tuple[str, Dict[str, str]]:
+        if self.server_url is not None and self.server_url:
+            return remove_suffix(self.server_url, "/"), {}
+        if self.server_idx is None:
+            self.server_idx = 0
+
+        return SERVERS[self.server_idx], self.server_defaults[self.server_idx]