release: 3.1.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "3.0.0-alpha.30"
+  ".": "3.1.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 12
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/supermemory--inc%2Fsupermemory-new-f181eaeb22a42d197dbd9c45fa61bf9a9b78a91d3334fc0f841494dc73d1a203.yml
-openapi_spec_hash: bb8262ebcdea53979cf1cafbc2c68dc8
-config_hash: 9b9291a6c872b063900a46386729ba3c
+configured_endpoints: 18
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/supermemory--inc%2Fsupermemory-new-b7bf8402df5372a3fac3cb55e083d7c09867328639cb7e2ceb7826de125ccff7.yml
+openapi_spec_hash: a91c06034ad9e8a7315927d6f2e18521
+config_hash: 5deef1e3a49e3a7816348fbf7ba259bf

CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 3.1.0 (2025-09-20)
+
+Full Changelog: [v3.0.0-alpha.30...v3.1.0](https://github.com/supermemoryai/python-sdk/compare/v3.0.0-alpha.30...v3.1.0)
+
+### Features
+
+* **api:** api update ([19c5dd3](https://github.com/supermemoryai/python-sdk/commit/19c5dd364b496d9a7858e1764000aba6d71613c6))
+* **api:** api update ([3082481](https://github.com/supermemoryai/python-sdk/commit/30824814233753584a89c56a2efb69d72995be02))
+* **api:** manual updates ([e92cb27](https://github.com/supermemoryai/python-sdk/commit/e92cb27550c2190a6804a2865ae359ff79fa1866))
+* **api:** manual updates ([251fdf1](https://github.com/supermemoryai/python-sdk/commit/251fdf116f5f1b0c1ecfb74bef94ba08f7921dca))
+
+
+### Chores
+
+* do not install brew dependencies in ./scripts/bootstrap by default ([fb748cf](https://github.com/supermemoryai/python-sdk/commit/fb748cf2375b1ce1eddd2584503e81d3b8386443))
+* **internal:** update pydantic dependency ([8c480f7](https://github.com/supermemoryai/python-sdk/commit/8c480f70cf3d0e55c4c5bc3b77d83bd6b21c4fdf))
+* **types:** change optional parameter type from NotGiven to Omit ([3031781](https://github.com/supermemoryai/python-sdk/commit/30317810d7089dbdf59f5e143bd66b1a0495b2b6))
+
 ## 3.0.0-alpha.30 (2025-09-15)
 
 Full Changelog: [v3.0.0-alpha.29...v3.0.0-alpha.30](https://github.com/supermemoryai/python-sdk/compare/v3.0.0-alpha.29...v3.0.0-alpha.30)

README.md

@@ -17,7 +17,7 @@ The REST API documentation can be found on [docs.supermemory.ai](https://docs.su
 
 ```sh
 # install from PyPI
-pip install --pre supermemory
+pip install supermemory
 ```
 
 ## Usage
@@ -77,7 +77,7 @@ You can enable this by installing `aiohttp`:
 
 ```sh
 # install from PyPI
-pip install --pre supermemory[aiohttp]
+pip install supermemory[aiohttp]
 ```
 
 Then you can enable it by instantiating the client with `http_client=DefaultAioHttpClient()`:
@@ -127,6 +127,23 @@ response = client.search.memories(
 print(response.include)
 ```
 
+## File uploads
+
+Request parameters that correspond to file uploads can be passed as `bytes`, or a [`PathLike`](https://docs.python.org/3/library/os.html#os.PathLike) instance or a tuple of `(filename, contents, media type)`.
+
+```python
+from pathlib import Path
+from supermemory import Supermemory
+
+client = Supermemory()
+
+client.memories.upload_file(
+    file=Path("/path/to/file"),
+)
+```
+
+The async client uses the exact same interface. If you pass a [`PathLike`](https://docs.python.org/3/library/os.html#os.PathLike) instance, the file contents will be read asynchronously automatically.
+
 ## Handling errors
 
 When the library is unable to connect to the API (for example, due to network connection problems or a timeout), a subclass of `supermemory.APIConnectionError` is raised.
@@ -143,8 +160,8 @@ from supermemory import Supermemory
 client = Supermemory()
 
 try:
-    client.search.documents(
-        q="machine learning concepts",
+    client.memories.add(
+        content="This is a detailed article about machine learning concepts...",
     )
 except supermemory.APIConnectionError as e:
     print("The server could not be reached")
@@ -188,8 +205,8 @@ client = Supermemory(
 )
 
 # Or, configure per-request:
-client.with_options(max_retries=5).search.documents(
-    q="machine learning concepts",
+client.with_options(max_retries=5).memories.add(
+    content="This is a detailed article about machine learning concepts...",
 )
 ```
 
@@ -213,8 +230,8 @@ client = Supermemory(
 )
 
 # Override per-request:
-client.with_options(timeout=5.0).search.documents(
-    q="machine learning concepts",
+client.with_options(timeout=5.0).memories.add(
+    content="This is a detailed article about machine learning concepts...",
 )
 ```
 
@@ -256,13 +273,13 @@ The "raw" Response object can be accessed by prefixing `.with_raw_response.` to
 from supermemory import Supermemory
 
 client = Supermemory()
-response = client.search.with_raw_response.documents(
-    q="machine learning concepts",
+response = client.memories.with_raw_response.add(
+    content="This is a detailed article about machine learning concepts...",
 )
 print(response.headers.get('X-My-Header'))
 
-search = response.parse()  # get the object that `search.documents()` would have returned
-print(search.results)
+memory = response.parse()  # get the object that `memories.add()` would have returned
+print(memory.id)
 ```
 
 These methods return an [`APIResponse`](https://github.com/supermemoryai/python-sdk/tree/main/src/supermemory/_response.py) object.
@@ -276,8 +293,8 @@ The above interface eagerly reads the full response body when you make the reque
 To stream the response body, use `.with_streaming_response` instead, which requires a context manager and only reads the response body once you call `.read()`, `.text()`, `.json()`, `.iter_bytes()`, `.iter_text()`, `.iter_lines()` or `.parse()`. In the async client, these are async methods.
 
 ```python
-with client.search.with_streaming_response.documents(
-    q="machine learning concepts",
+with client.memories.with_streaming_response.add(
+    content="This is a detailed article about machine learning concepts...",
 ) as response:
     print(response.headers.get("X-My-Header"))
 

api.md

@@ -1,3 +1,49 @@
+# Memories
+
+Types:
+
+```python
+from supermemory.types import (
+    MemoryUpdateResponse,
+    MemoryListResponse,
+    MemoryAddResponse,
+    MemoryGetResponse,
+    MemoryUploadFileResponse,
+)
+```
+
+Methods:
+
+- <code title="patch /v3/documents/{id}">client.memories.<a href="./src/supermemory/resources/memories.py">update</a>(id, \*\*<a href="src/supermemory/types/memory_update_params.py">params</a>) -> <a href="./src/supermemory/types/memory_update_response.py">MemoryUpdateResponse</a></code>
+- <code title="post /v3/documents/list">client.memories.<a href="./src/supermemory/resources/memories.py">list</a>(\*\*<a href="src/supermemory/types/memory_list_params.py">params</a>) -> <a href="./src/supermemory/types/memory_list_response.py">MemoryListResponse</a></code>
+- <code title="delete /v3/documents/{id}">client.memories.<a href="./src/supermemory/resources/memories.py">delete</a>(id) -> None</code>
+- <code title="post /v3/documents">client.memories.<a href="./src/supermemory/resources/memories.py">add</a>(\*\*<a href="src/supermemory/types/memory_add_params.py">params</a>) -> <a href="./src/supermemory/types/memory_add_response.py">MemoryAddResponse</a></code>
+- <code title="get /v3/documents/{id}">client.memories.<a href="./src/supermemory/resources/memories.py">get</a>(id) -> <a href="./src/supermemory/types/memory_get_response.py">MemoryGetResponse</a></code>
+- <code title="post /v3/documents/file">client.memories.<a href="./src/supermemory/resources/memories.py">upload_file</a>(\*\*<a href="src/supermemory/types/memory_upload_file_params.py">params</a>) -> <a href="./src/supermemory/types/memory_upload_file_response.py">MemoryUploadFileResponse</a></code>
+
+# Documents
+
+Types:
+
+```python
+from supermemory.types import (
+    DocumentUpdateResponse,
+    DocumentListResponse,
+    DocumentAddResponse,
+    DocumentGetResponse,
+    DocumentUploadFileResponse,
+)
+```
+
+Methods:
+
+- <code title="patch /v3/documents/{id}">client.documents.<a href="./src/supermemory/resources/documents.py">update</a>(id, \*\*<a href="src/supermemory/types/document_update_params.py">params</a>) -> <a href="./src/supermemory/types/document_update_response.py">DocumentUpdateResponse</a></code>
+- <code title="post /v3/documents/list">client.documents.<a href="./src/supermemory/resources/documents.py">list</a>(\*\*<a href="src/supermemory/types/document_list_params.py">params</a>) -> <a href="./src/supermemory/types/document_list_response.py">DocumentListResponse</a></code>
+- <code title="delete /v3/documents/{id}">client.documents.<a href="./src/supermemory/resources/documents.py">delete</a>(id) -> None</code>
+- <code title="post /v3/documents">client.documents.<a href="./src/supermemory/resources/documents.py">add</a>(\*\*<a href="src/supermemory/types/document_add_params.py">params</a>) -> <a href="./src/supermemory/types/document_add_response.py">DocumentAddResponse</a></code>
+- <code title="get /v3/documents/{id}">client.documents.<a href="./src/supermemory/resources/documents.py">get</a>(id) -> <a href="./src/supermemory/types/document_get_response.py">DocumentGetResponse</a></code>
+- <code title="post /v3/documents/file">client.documents.<a href="./src/supermemory/resources/documents.py">upload_file</a>(\*\*<a href="src/supermemory/types/document_upload_file_params.py">params</a>) -> <a href="./src/supermemory/types/document_upload_file_response.py">DocumentUploadFileResponse</a></code>
+
 # Search
 
 Types:

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "supermemory"
-version = "3.0.0-alpha.30"
+version = "3.1.0"
 description = "The official Python library for the supermemory API"
 dynamic = ["readme"]
 license = "Apache-2.0"

requirements-dev.lock

@@ -88,9 +88,9 @@ pluggy==1.5.0
 propcache==0.3.1
     # via aiohttp
     # via yarl
-pydantic==2.10.3
+pydantic==2.11.9
     # via supermemory
-pydantic-core==2.27.1
+pydantic-core==2.33.2
     # via pydantic
 pygments==2.18.0
     # via rich
@@ -126,6 +126,9 @@ typing-extensions==4.12.2
     # via pydantic-core
     # via pyright
     # via supermemory
+    # via typing-inspection
+typing-inspection==0.4.1
+    # via pydantic
 virtualenv==20.24.5
     # via nox
 yarl==1.20.0

requirements.lock

@@ -55,9 +55,9 @@ multidict==6.4.4
 propcache==0.3.1
     # via aiohttp
     # via yarl
-pydantic==2.10.3
+pydantic==2.11.9
     # via supermemory
-pydantic-core==2.27.1
+pydantic-core==2.33.2
     # via pydantic
 sniffio==1.3.0
     # via anyio
@@ -68,5 +68,8 @@ typing-extensions==4.12.2
     # via pydantic
     # via pydantic-core
     # via supermemory
+    # via typing-inspection
+typing-inspection==0.4.1
+    # via pydantic
 yarl==1.20.0
     # via aiohttp

scripts/bootstrap

@@ -4,10 +4,18 @@ set -e
 
 cd "$(dirname "$0")/.."
 
-if ! command -v rye >/dev/null 2>&1 && [ -f "Brewfile" ] && [ "$(uname -s)" = "Darwin" ]; then
+if [ -f "Brewfile" ] && [ "$(uname -s)" = "Darwin" ] && [ "$SKIP_BREW" != "1" ] && [ -t 0 ]; then
   brew bundle check >/dev/null 2>&1 || {
-    echo "==> Installing Homebrew dependencies…"
-    brew bundle
+    echo -n "==> Install Homebrew dependencies? (y/N): "
+    read -r response
+    case "$response" in
+      [yY][eE][sS]|[yY])
+        brew bundle
+        ;;
+      *)
+        ;;
+    esac
+    echo
   }
 fi
 

src/supermemory/__init__.py

@@ -3,7 +3,7 @@
 import typing as _t
 
 from . import types
-from ._types import NOT_GIVEN, Omit, NoneType, NotGiven, Transport, ProxiesTypes
+from ._types import NOT_GIVEN, Omit, NoneType, NotGiven, Transport, ProxiesTypes, omit, not_given
 from ._utils import file_from_path
 from ._client import (
     Client,
@@ -48,7 +48,9 @@
     "ProxiesTypes",
     "NotGiven",
     "NOT_GIVEN",
+    "not_given",
     "Omit",
+    "omit",
     "SupermemoryError",
     "APIError",
     "APIStatusError",

src/supermemory/_base_client.py

@@ -42,7 +42,6 @@
 from ._qs import Querystring
 from ._files import to_httpx_files, async_to_httpx_files
 from ._types import (
-    NOT_GIVEN,
     Body,
     Omit,
     Query,
@@ -57,6 +56,7 @@
     RequestOptions,
     HttpxRequestFiles,
     ModelBuilderProtocol,
+    not_given,
 )
 from ._utils import is_dict, is_list, asyncify, is_given, lru_cache, is_mapping
 from ._compat import PYDANTIC_V1, model_copy, model_dump
@@ -145,9 +145,9 @@ def __init__(
     def __init__(
         self,
         *,
-        url: URL | NotGiven = NOT_GIVEN,
-        json: Body | NotGiven = NOT_GIVEN,
-        params: Query | NotGiven = NOT_GIVEN,
+        url: URL | NotGiven = not_given,
+        json: Body | NotGiven = not_given,
+        params: Query | NotGiven = not_given,
     ) -> None:
         self.url = url
         self.json = json
@@ -595,7 +595,7 @@ def _maybe_override_cast_to(self, cast_to: type[ResponseT], options: FinalReques
         # we internally support defining a temporary header to override the
         # default `cast_to` type for use with `.with_raw_response` and `.with_streaming_response`
         # see _response.py for implementation details
-        override_cast_to = headers.pop(OVERRIDE_CAST_TO_HEADER, NOT_GIVEN)
+        override_cast_to = headers.pop(OVERRIDE_CAST_TO_HEADER, not_given)
         if is_given(override_cast_to):
             options.headers = headers
             return cast(Type[ResponseT], override_cast_to)
@@ -825,7 +825,7 @@ def __init__(
         version: str,
         base_url: str | URL,
         max_retries: int = DEFAULT_MAX_RETRIES,
-        timeout: float | Timeout | None | NotGiven = NOT_GIVEN,
+        timeout: float | Timeout | None | NotGiven = not_given,
         http_client: httpx.Client | None = None,
         custom_headers: Mapping[str, str] | None = None,
         custom_query: Mapping[str, object] | None = None,
@@ -1356,7 +1356,7 @@ def __init__(
         base_url: str | URL,
         _strict_response_validation: bool,
         max_retries: int = DEFAULT_MAX_RETRIES,
-        timeout: float | Timeout | None | NotGiven = NOT_GIVEN,
+        timeout: float | Timeout | None | NotGiven = not_given,
         http_client: httpx.AsyncClient | None = None,
         custom_headers: Mapping[str, str] | None = None,
         custom_query: Mapping[str, object] | None = None,
@@ -1818,8 +1818,8 @@ def make_request_options(
     extra_query: Query | None = None,
     extra_body: Body | None = None,
     idempotency_key: str | None = None,
-    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
-    post_parser: PostParser | NotGiven = NOT_GIVEN,
+    timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    post_parser: PostParser | NotGiven = not_given,
 ) -> RequestOptions:
     """Create a dict of type RequestOptions without keys of NotGiven values."""
     options: RequestOptions = {}