client.py

# This file was auto-generated by Fern from our API Definition.

import typing

import httpx

from supermemory._types import NOT_GIVEN, NotGiven

from ..core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
from ..core.request_options import RequestOptions
from ..types.namespace_deleted import NamespaceDeleted
from ..types.namespace_details import NamespaceDetails
from ..types.namespace_list import NamespaceList
from .raw_client import AsyncRawNamespacesClient, RawNamespacesClient

# this is used as the default value for optional parameters
OMIT = typing.cast(typing.Any, ...)


class NamespacesClient:
    def __init__(self, *, client_wrapper: SyncClientWrapper):
        self._raw_client = RawNamespacesClient(client_wrapper=client_wrapper)

    @property
    def with_raw_response(self) -> RawNamespacesClient:
        """
        Retrieves a raw implementation of this client that returns raw responses.

        Returns
        -------
        RawNamespacesClient
        """
        return self._raw_client

    def list(
        self,
        *,
        page: typing.Optional[int] = None,
        limit: typing.Optional[int] = None,
        q: typing.Optional[str] = None,
        request_options: typing.Optional[RequestOptions] = None,
        extra_headers: typing.Optional[typing.Mapping[str, str]] = None,
        extra_query: typing.Optional[typing.Mapping[str, typing.Any]] = None,
        extra_body: typing.Optional[typing.Mapping[str, typing.Any]] = None,
        timeout: typing.Union[float, httpx.Timeout, None, NotGiven] = NOT_GIVEN,
    ) -> NamespaceList:
        """
        Discover every namespace available to the caller, including its purpose, document volume, memory count, and lifecycle timestamps.

        Parameters
        ----------
        page : typing.Optional[int]
            One-based page number

        limit : typing.Optional[int]
            Maximum namespaces to return per page

        q : typing.Optional[str]
            Case-insensitive substring to match against namespace names

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        NamespaceList
            Namespaces available to the caller

        Examples
        --------
        from supermemory import Supermemory

        client = Supermemory(
            api_key="YOUR_API_KEY",
        )
        client.namespaces.list()
        """
        _response = self._raw_client.list(page=page, limit=limit, q=q, request_options=request_options)
        return _response.data

    def get(
        self,
        namespace: str,
        *,
        request_options: typing.Optional[RequestOptions] = None,
        extra_headers: typing.Optional[typing.Mapping[str, str]] = None,
        extra_query: typing.Optional[typing.Mapping[str, typing.Any]] = None,
        extra_body: typing.Optional[typing.Mapping[str, typing.Any]] = None,
        timeout: typing.Union[float, httpx.Timeout, None, NotGiven] = NOT_GIVEN,
    ) -> NamespaceDetails:
        """
        Read the supporting context that helps Supermemory understand content and form better memories inside this namespace.

        Parameters
        ----------
        namespace : str
            Namespace identifier. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope documents and memories.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        NamespaceDetails
            Namespace settings

        Examples
        --------
        from supermemory import Supermemory

        client = Supermemory(
            api_key="YOUR_API_KEY",
        )
        client.namespaces.get(
            namespace="user_alex",
        )
        """
        _response = self._raw_client.get(namespace, request_options=request_options)
        return _response.data

    def delete(
        self,
        namespace: str,
        *,
        move_to: typing.Optional[str] = None,
        request_options: typing.Optional[RequestOptions] = None,
        extra_headers: typing.Optional[typing.Mapping[str, str]] = None,
        extra_query: typing.Optional[typing.Mapping[str, typing.Any]] = None,
        extra_body: typing.Optional[typing.Mapping[str, typing.Any]] = None,
        timeout: typing.Union[float, httpx.Timeout, None, NotGiven] = NOT_GIVEN,
    ) -> NamespaceDeleted:
        """
        Retire a namespace by permanently deleting its content, or preserve that knowledge by moving everything into another namespace first. Moves are queued and complete asynchronously.

        Parameters
        ----------
        namespace : str
            Namespace identifier. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope documents and memories.

        move_to : typing.Optional[str]
            Destination namespace that should receive this namespace's content before deletion. Omit to permanently delete the content.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        NamespaceDeleted
            Namespace permanently deleted (status "deleted"). A move answers 202 with status "queued".

        Examples
        --------
        from supermemory import Supermemory

        client = Supermemory(
            api_key="YOUR_API_KEY",
        )
        client.namespaces.delete(
            namespace="user_alex",
            move_to="project_archive",
        )
        """
        _response = self._raw_client.delete(namespace, move_to=move_to, request_options=request_options)
        return _response.data

    def update(
        self,
        namespace: str,
        *,
        supporting_context: typing.Optional[str] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
        extra_headers: typing.Optional[typing.Mapping[str, str]] = None,
        extra_query: typing.Optional[typing.Mapping[str, typing.Any]] = None,
        extra_body: typing.Optional[typing.Mapping[str, typing.Any]] = None,
        timeout: typing.Union[float, httpx.Timeout, None, NotGiven] = NOT_GIVEN,
    ) -> NamespaceDetails:
        """
        Shape how Supermemory understands an existing namespace by updating the background context used during ingestion and memory formation.

        Parameters
        ----------
        namespace : str
            Namespace identifier. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope documents and memories.

        supporting_context : typing.Optional[str]
            Background that guides how Supermemory interprets documents and forms memories. Max 1500 characters. Set null to clear it.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        NamespaceDetails
            Updated namespace settings

        Examples
        --------
        from supermemory import Supermemory

        client = Supermemory(
            api_key="YOUR_API_KEY",
        )
        client.namespaces.update(
            namespace="user_alex",
        )
        """
        _response = self._raw_client.update(
            namespace, supporting_context=supporting_context, request_options=request_options
        )
        return _response.data


class AsyncNamespacesClient:
    def __init__(self, *, client_wrapper: AsyncClientWrapper):
        self._raw_client = AsyncRawNamespacesClient(client_wrapper=client_wrapper)

    @property
    def with_raw_response(self) -> AsyncRawNamespacesClient:
        """
        Retrieves a raw implementation of this client that returns raw responses.

        Returns
        -------
        AsyncRawNamespacesClient
        """
        return self._raw_client

    async def list(
        self,
        *,
        page: typing.Optional[int] = None,
        limit: typing.Optional[int] = None,
        q: typing.Optional[str] = None,
        request_options: typing.Optional[RequestOptions] = None,
        extra_headers: typing.Optional[typing.Mapping[str, str]] = None,
        extra_query: typing.Optional[typing.Mapping[str, typing.Any]] = None,
        extra_body: typing.Optional[typing.Mapping[str, typing.Any]] = None,
        timeout: typing.Union[float, httpx.Timeout, None, NotGiven] = NOT_GIVEN,
    ) -> NamespaceList:
        """
        Discover every namespace available to the caller, including its purpose, document volume, memory count, and lifecycle timestamps.

        Parameters
        ----------
        page : typing.Optional[int]
            One-based page number

        limit : typing.Optional[int]
            Maximum namespaces to return per page

        q : typing.Optional[str]
            Case-insensitive substring to match against namespace names

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        NamespaceList
            Namespaces available to the caller

        Examples
        --------
        import asyncio

        from supermemory import AsyncSupermemory

        client = AsyncSupermemory(
            api_key="YOUR_API_KEY",
        )


        async def main() -> None:
            await client.namespaces.list()


        asyncio.run(main())
        """
        _response = await self._raw_client.list(page=page, limit=limit, q=q, request_options=request_options)
        return _response.data

    async def get(
        self,
        namespace: str,
        *,
        request_options: typing.Optional[RequestOptions] = None,
        extra_headers: typing.Optional[typing.Mapping[str, str]] = None,
        extra_query: typing.Optional[typing.Mapping[str, typing.Any]] = None,
        extra_body: typing.Optional[typing.Mapping[str, typing.Any]] = None,
        timeout: typing.Union[float, httpx.Timeout, None, NotGiven] = NOT_GIVEN,
    ) -> NamespaceDetails:
        """
        Read the supporting context that helps Supermemory understand content and form better memories inside this namespace.

        Parameters
        ----------
        namespace : str
            Namespace identifier. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope documents and memories.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        NamespaceDetails
            Namespace settings

        Examples
        --------
        import asyncio

        from supermemory import AsyncSupermemory

        client = AsyncSupermemory(
            api_key="YOUR_API_KEY",
        )


        async def main() -> None:
            await client.namespaces.get(
                namespace="user_alex",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.get(namespace, request_options=request_options)
        return _response.data

    async def delete(
        self,
        namespace: str,
        *,
        move_to: typing.Optional[str] = None,
        request_options: typing.Optional[RequestOptions] = None,
        extra_headers: typing.Optional[typing.Mapping[str, str]] = None,
        extra_query: typing.Optional[typing.Mapping[str, typing.Any]] = None,
        extra_body: typing.Optional[typing.Mapping[str, typing.Any]] = None,
        timeout: typing.Union[float, httpx.Timeout, None, NotGiven] = NOT_GIVEN,
    ) -> NamespaceDeleted:
        """
        Retire a namespace by permanently deleting its content, or preserve that knowledge by moving everything into another namespace first. Moves are queued and complete asynchronously.

        Parameters
        ----------
        namespace : str
            Namespace identifier. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope documents and memories.

        move_to : typing.Optional[str]
            Destination namespace that should receive this namespace's content before deletion. Omit to permanently delete the content.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        NamespaceDeleted
            Namespace permanently deleted (status "deleted"). A move answers 202 with status "queued".

        Examples
        --------
        import asyncio

        from supermemory import AsyncSupermemory

        client = AsyncSupermemory(
            api_key="YOUR_API_KEY",
        )


        async def main() -> None:
            await client.namespaces.delete(
                namespace="user_alex",
                move_to="project_archive",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.delete(namespace, move_to=move_to, request_options=request_options)
        return _response.data

    async def update(
        self,
        namespace: str,
        *,
        supporting_context: typing.Optional[str] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
        extra_headers: typing.Optional[typing.Mapping[str, str]] = None,
        extra_query: typing.Optional[typing.Mapping[str, typing.Any]] = None,
        extra_body: typing.Optional[typing.Mapping[str, typing.Any]] = None,
        timeout: typing.Union[float, httpx.Timeout, None, NotGiven] = NOT_GIVEN,
    ) -> NamespaceDetails:
        """
        Shape how Supermemory understands an existing namespace by updating the background context used during ingestion and memory formation.

        Parameters
        ----------
        namespace : str
            Namespace identifier. This can be an ID for your user, a project ID, or any other identifier you wish to use to scope documents and memories.

        supporting_context : typing.Optional[str]
            Background that guides how Supermemory interprets documents and forms memories. Max 1500 characters. Set null to clear it.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        NamespaceDetails
            Updated namespace settings

        Examples
        --------
        import asyncio

        from supermemory import AsyncSupermemory

        client = AsyncSupermemory(
            api_key="YOUR_API_KEY",
        )


        async def main() -> None:
            await client.namespaces.update(
                namespace="user_alex",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.update(
            namespace, supporting_context=supporting_context, request_options=request_options
        )
        return _response.data