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.forget_result import ForgetResult
from ..types.memory_details import MemoryDetails
from ..types.memory_include import MemoryInclude
from .raw_client import AsyncRawMemoriesClient, RawMemoriesClient

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


class MemoriesClient:
    def __init__(self, *, client_wrapper: SyncClientWrapper):
        self._raw_client = RawMemoriesClient(client_wrapper=client_wrapper)

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

        Returns
        -------
        RawMemoriesClient
        """
        return self._raw_client

    def forget(
        self,
        namespace: str,
        *,
        ids: typing.Sequence[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,
    ) -> ForgetResult:
        """
        Remove exact memories from normal recall while preserving their audit history. Each ID is handled independently and any missing or ineligible memory is reported without rolling back successful changes.

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

        ids : typing.Sequence[str]
            Memory identifiers to remove from normal recall

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

        Returns
        -------
        ForgetResult
            Exact memory forget completed

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

        client = Supermemory(
            api_key="YOUR_API_KEY",
        )
        client.memories.forget(
            namespace="user_alex",
            ids=["mem_abc123"],
        )
        """
        _response = self._raw_client.forget(namespace, ids=ids, request_options=request_options)
        return _response.data

    def forget_matching(
        self,
        namespace: str,
        *,
        query: str,
        dry_run: bool,
        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,
    ) -> ForgetResult:
        """
        Describe what should be forgotten in natural language, then preview or apply the matching set. Use dry-run results with the exact-ID endpoint when you need a reviewable, drift-free workflow.

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

        query : str
            Natural-language description of the memories that should be forgotten

        dry_run : bool
            When true, preview matching memories without changing their recall state

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

        Returns
        -------
        ForgetResult
            Semantic memory forget completed or previewed

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

        client = Supermemory(
            api_key="YOUR_API_KEY",
        )
        client.memories.forget_matching(
            namespace="user_alex",
            query="everything about the old pricing plans",
            dry_run=True,
        )
        """
        _response = self._raw_client.forget_matching(
            namespace, query=query, dry_run=dry_run, request_options=request_options
        )
        return _response.data

    def get(
        self,
        namespace: str,
        id: str,
        *,
        include: typing.Optional[typing.Union[MemoryInclude, typing.Sequence[MemoryInclude]]] = None,
        related_limit: typing.Optional[int] = 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,
    ) -> MemoryDetails:
        """
        Retrieve one memory by ID. Optionally include its version history and connected memories (each list walks outward up to relatedLimit, nearest first) and its source document.

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

        id : str
            Memory identifier

        include : typing.Optional[typing.Union[MemoryInclude, typing.Sequence[MemoryInclude]]]
            Comma-separated extras. related: the memory's version history and connected memories. documents: the source document, also attached to each related memory when both are requested.

        related_limit : typing.Optional[int]
            Maximum parents, children and siblings to return, applied to each list separately. Each list walks outward from the memory, nearest first, until it reaches this many.

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

        Returns
        -------
        MemoryDetails
            Memory retrieved

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

        client = Supermemory(
            api_key="YOUR_API_KEY",
        )
        client.memories.get(
            namespace="user_alex",
            id="mem_abc123",
        )
        """
        _response = self._raw_client.get(
            namespace, id, include=include, related_limit=related_limit, request_options=request_options
        )
        return _response.data


class AsyncMemoriesClient:
    def __init__(self, *, client_wrapper: AsyncClientWrapper):
        self._raw_client = AsyncRawMemoriesClient(client_wrapper=client_wrapper)

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

        Returns
        -------
        AsyncRawMemoriesClient
        """
        return self._raw_client

    async def forget(
        self,
        namespace: str,
        *,
        ids: typing.Sequence[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,
    ) -> ForgetResult:
        """
        Remove exact memories from normal recall while preserving their audit history. Each ID is handled independently and any missing or ineligible memory is reported without rolling back successful changes.

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

        ids : typing.Sequence[str]
            Memory identifiers to remove from normal recall

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

        Returns
        -------
        ForgetResult
            Exact memory forget completed

        Examples
        --------
        import asyncio

        from supermemory import AsyncSupermemory

        client = AsyncSupermemory(
            api_key="YOUR_API_KEY",
        )


        async def main() -> None:
            await client.memories.forget(
                namespace="user_alex",
                ids=["mem_abc123"],
            )


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

    async def forget_matching(
        self,
        namespace: str,
        *,
        query: str,
        dry_run: bool,
        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,
    ) -> ForgetResult:
        """
        Describe what should be forgotten in natural language, then preview or apply the matching set. Use dry-run results with the exact-ID endpoint when you need a reviewable, drift-free workflow.

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

        query : str
            Natural-language description of the memories that should be forgotten

        dry_run : bool
            When true, preview matching memories without changing their recall state

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

        Returns
        -------
        ForgetResult
            Semantic memory forget completed or previewed

        Examples
        --------
        import asyncio

        from supermemory import AsyncSupermemory

        client = AsyncSupermemory(
            api_key="YOUR_API_KEY",
        )


        async def main() -> None:
            await client.memories.forget_matching(
                namespace="user_alex",
                query="everything about the old pricing plans",
                dry_run=True,
            )


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

    async def get(
        self,
        namespace: str,
        id: str,
        *,
        include: typing.Optional[typing.Union[MemoryInclude, typing.Sequence[MemoryInclude]]] = None,
        related_limit: typing.Optional[int] = 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,
    ) -> MemoryDetails:
        """
        Retrieve one memory by ID. Optionally include its version history and connected memories (each list walks outward up to relatedLimit, nearest first) and its source document.

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

        id : str
            Memory identifier

        include : typing.Optional[typing.Union[MemoryInclude, typing.Sequence[MemoryInclude]]]
            Comma-separated extras. related: the memory's version history and connected memories. documents: the source document, also attached to each related memory when both are requested.

        related_limit : typing.Optional[int]
            Maximum parents, children and siblings to return, applied to each list separately. Each list walks outward from the memory, nearest first, until it reaches this many.

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

        Returns
        -------
        MemoryDetails
            Memory retrieved

        Examples
        --------
        import asyncio

        from supermemory import AsyncSupermemory

        client = AsyncSupermemory(
            api_key="YOUR_API_KEY",
        )


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


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