supermemory 3.61.0__tar.gz → 5.0.0__tar.gz

supermemory-5.0.0/.github/workflows/ci.yml

@@ -0,0 +1,70 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: test (py${{ matrix.python }}${{ matrix.pydantic == 'v1' && ', pydantic v1' || '' }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        pydantic: [v2]
+        include:
+          - python: "3.10"
+            pydantic: v1
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - if: matrix.pydantic == 'v2'
+        run: uv run --python ${{ matrix.python }} --group dev pytest -q
+      - if: matrix.pydantic == 'v1'
+        run: uv run --python ${{ matrix.python }} --with 'pydantic<2' --group dev pytest -q
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv run --group dev ruff check .
+      - run: uv run --group dev ruff format --check custom tests scripts examples
+      - run: uv run --group dev mypy
+      - run: uv build
+
+  # src/supermemory must be exactly what scripts/generate produces from the
+  # committed spec + fern/ + custom/ — no hand edits.
+  generated:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - uses: astral-sh/setup-uv@v6
+      - run: SKIP_FETCH=1 scripts/generate
+      - name: Check for drift
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            git status --short
+            echo "::error::src/supermemory doesn't match scripts/generate. Edit fern/ or custom/ instead of src/, then run SKIP_FETCH=1 scripts/generate and commit."
+            exit 1
+          fi
+
+  # Against the real API; runs when the SUPERMEMORY_LIVE_API_KEY secret exists.
+  live:
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    env:
+      SUPERMEMORY_LIVE_API_KEY: ${{ secrets.SUPERMEMORY_LIVE_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+        if: env.SUPERMEMORY_LIVE_API_KEY != ''
+      - uses: astral-sh/setup-uv@v6
+        if: env.SUPERMEMORY_LIVE_API_KEY != ''
+      - if: env.SUPERMEMORY_LIVE_API_KEY != ''
+        run: uv run --group dev pytest tests/live -q

supermemory-5.0.0/.github/workflows/generate.yml

@@ -0,0 +1,75 @@
+name: Generate SDK
+on:
+  # Sent by the API deploy when /v5/openapi changes:
+  #   gh api repos/supermemoryai/python-sdk/dispatches -f event_type=openapi-updated
+  repository_dispatch:
+    types: [openapi-updated]
+  # Backstop in case a deploy didn't dispatch.
+  schedule:
+    - cron: "0 0 * * *"
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Set the SDK version (PEP 440, e.g. 5.0.0rc2 or 5.0.0). Empty = bump automatically if the SDK changed.
+        type: string
+        required: false
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: generate-sdk
+  cancel-in-progress: true
+
+jobs:
+  generate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Generate from https://api.supermemory.ai/v5/openapi
+        run: scripts/generate
+
+      - name: Version
+        id: meta
+        env:
+          VERSION: ${{ inputs.version }}
+        run: |
+          if [ -n "$VERSION" ]; then
+            sed -i "s/^version = \".*\"/version = \"$VERSION\"/" pyproject.toml
+            SKIP_FETCH=1 scripts/generate   # re-stamp the User-Agent version
+          elif [ -n "$(git status --porcelain -- src)" ]; then
+            python3 scripts/bump_version.py
+            SKIP_FETCH=1 scripts/generate
+          fi
+          echo "version=$(grep -m1 '^version' pyproject.toml | cut -d'"' -f2)" >> "$GITHUB_OUTPUT"
+          {
+            echo 'stat<<EOF'
+            git diff --stat -- fern/openapi.json src | tail -n 25
+            echo EOF
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Test
+        run: uv run --group dev pytest -q
+
+      # Opens (or updates) one PR; no-op if nothing changed. A PR opened with the
+      # default GITHUB_TOKEN doesn't trigger CI, so set CODEGEN_PR_TOKEN (a
+      # fine-grained PAT or app token with contents + pull-requests write).
+      - uses: peter-evans/create-pull-request@v7
+        with:
+          token: ${{ secrets.CODEGEN_PR_TOKEN || github.token }}
+          branch: codegen/regenerate
+          delete-branch: true
+          commit-message: "chore: regenerate SDK from v5 OpenAPI spec (${{ steps.meta.outputs.version }})"
+          title: "chore: regenerate SDK (${{ steps.meta.outputs.version }})"
+          body: |
+            Regenerated `src/supermemory` from `https://api.supermemory.ai/v5/openapi` (`scripts/generate`).
+
+            Merging publishes **supermemory ${{ steps.meta.outputs.version }}** to PyPI.
+
+            ```
+            ${{ steps.meta.outputs.stat }}
+            ```

supermemory-5.0.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,50 @@
+name: Publish to PyPI
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write # tag + GitHub release
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+
+      # Merges that don't bump the version (docs, CI tweaks) are no-ops.
+      - name: Check version
+        id: meta
+        run: |
+          VERSION=$(grep -m1 '^version' pyproject.toml | cut -d'"' -f2)
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          if curl -fsS "https://pypi.org/pypi/supermemory/$VERSION/json" >/dev/null 2>&1; then
+            echo "supermemory $VERSION is already on PyPI — skipping."
+            echo "publish=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "publish=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - if: steps.meta.outputs.publish == 'true'
+        run: uv run --group dev pytest -q
+
+      - if: steps.meta.outputs.publish == 'true'
+        run: uv build
+
+      - name: Publish ${{ steps.meta.outputs.version }}
+        if: steps.meta.outputs.publish == 'true'
+        run: uv publish
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.SUPERMEMORY_PYPI_TOKEN || secrets.PYPI_TOKEN }}
+
+      - name: Tag and release
+        if: steps.meta.outputs.publish == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ steps.meta.outputs.version }}
+        run: |
+          flags=(--target "$GITHUB_SHA" --generate-notes)
+          [[ "$VERSION" =~ (a|b|rc|dev)[0-9]+$ ]] && flags+=(--prerelease)
+          gh release create "v$VERSION" dist/* "${flags[@]}"

supermemory-5.0.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__
+.mypy_cache
+.pytest_cache
+.ruff_cache
+.venv
+dist
+.idea
+.env
+.envrc
+fern/openapi.sdk.json

supermemory-5.0.0/.python-version

@@ -0,0 +1 @@
+3.10

{supermemory-3.61.0 → supermemory-5.0.0}/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 5.0.0rc1 (2026-10-04)
+
+Generated from the Supermemory **v5 API** (`/v5/openapi`) with Fern's open-source generator, replacing Stainless. See [MIGRATION.md](MIGRATION.md).
+
+### Breaking
+
+- Namespace-first methods matching the TypeScript SDK: `client.add(namespace, ...)`, `client.search(namespace, query=...)`, `client.profile`, `client.list`, `documents.*`, `memories.*`, `profiles.*`, `namespaces.*`, `organization.*`.
+- Container tags are replaced by namespaces; `q` → `query`, `custom_id` → `id`, `filters` → `filter`, `include` → `attach`.
+- Requires Python 3.10+.
+
+### Kept from 3.x
+
+- Client options, environment variables, per-call `extra_headers` / `extra_query` / `extra_body` / `timeout`, `with_options`, the exception hierarchy, `with_raw_response`, `to_dict()` / `to_json()`, and dict-typed request params.
+
+### New
+
+- `client.connectors.*` for Notion, Google Drive, OneDrive, Gmail, GitHub, S3, web crawler, and Granola.
+- Named types (`Document`, `Memory`, `SearchResult`, `Connector`, …) and typed filter expressions.
+
+## 3.62.0 (2026-09-14)
+
+Full Changelog: [v3.61.0...v3.62.0](https://github.com/supermemoryai/python-sdk/compare/v3.61.0...v3.62.0)
+
+### Features
+
+* **api:** api update ([6b34d15](https://github.com/supermemoryai/python-sdk/commit/6b34d1561b825d8a08d0c922b2dcbf3b4f9522d0))
+
 ## 3.61.0 (2026-09-05)
 
 Full Changelog: [v3.60.0...v3.61.0](https://github.com/supermemoryai/python-sdk/compare/v3.60.0...v3.61.0)

supermemory-5.0.0/MIGRATION.md

@@ -0,0 +1,99 @@
+# Migrating from `supermemory` 3.x to 5.x
+
+Starting with **5.0.0**, the Python SDK is generated from the Supermemory **v5 API** (`/v5/openapi`) using Fern's open-source generator instead of Stainless. The method names match the TypeScript SDK ([sdk-ts](https://github.com/supermemoryai/sdk-ts)) v5.
+
+v5 is namespace-first. Every content operation is scoped to a namespace, which replaces container tags, and the namespace is passed as the first argument.
+
+```sh
+pip install --pre supermemory   # while 5.0 is in release candidate
+```
+
+## TL;DR
+
+Only the API methods change. Everything around them works as before:
+
+| | 3.x | 5.x |
+|---|---|---|
+| Import / auth / env vars | `from supermemory import Supermemory`, `SUPERMEMORY_API_KEY`, `SUPERMEMORY_BASE_URL` | unchanged |
+| Client options | `api_key`, `base_url`, `timeout`, `max_retries`, `default_headers`, `default_query`, `http_client` | unchanged |
+| Per-call options | `extra_headers`, `extra_query`, `extra_body`, `timeout`; `client.with_options(...)` | unchanged |
+| Retries / timeout | 2 retries, 60s | unchanged |
+| Errors | `supermemory.APIStatusError`, `NotFoundError`, `RateLimitError`, `APIConnectionError`, … | unchanged |
+| Raw responses | `client.with_raw_response.<method>(...).parse()` | unchanged |
+| Models | `.to_dict()`, `.to_json()` | unchanged |
+| Scoping | `container_tag` / `container_tags` in the body | `namespace` positional argument (one per call) |
+| Add | `client.add(content=..., container_tag="u")` | `client.add("u", content=...)` |
+| Search | `client.search.memories(q=...)` | `client.search("u", query=...)` |
+| Profile | profile + optional search (`q`) | profile only. Run `client.search` alongside it |
+| Python | 3.9+ | 3.10+ |
+
+## Method map
+
+| 3.x call | 5.x call |
+|---|---|
+| `client.add(...)` / `client.documents.add(...)` | `client.add(namespace, content=...)` |
+| `client.search.memories(...)` / `client.search.documents(...)` | `client.search(namespace, query=...)` |
+| `client.profile(...)` | `client.profile(namespace)` |
+| `client.documents.list(...)` / `client.memories.list(...)` | `client.list(namespace, "documents" \| "chunks" \| "memories")` |
+| `client.documents.get(id)` | `client.documents.get(namespace, id)` |
+| `client.documents.update(id, ...)` | `client.documents.update(namespace, id, ...)` |
+| `client.documents.delete(...)` / `delete_bulk(...)` | `client.documents.delete(namespace, ids=[...])` |
+| `client.documents.batch_add(...)` | `client.documents.batch_add(namespace, documents=[...])` |
+| `client.documents.upload_file(...)` | `client.documents.upload_file(namespace, file=...)` |
+| — | `client.documents.replace_with_file(...)`, `update_file(...)` |
+| `client.memories.forget(...)` | `client.memories.forget(namespace, ids=[...])` |
+| — | `client.memories.forget_matching(...)` |
+| — | `client.profiles.{get_buckets, set_buckets, delete_buckets}` |
+| `client.connections.*` | `client.connectors.{list_all, list, create, get, update, delete, sync}` |
+| container tag management | `client.namespaces.{list, get, update, delete}` |
+| `client.settings.{get, update}` | `client.organization.{get, update}` |
+
+### Renamed request fields
+
+| 3.x | 5.x |
+|---|---|
+| `container_tag` / `container_tags` | `namespace` (first argument) |
+| `custom_id` | `id` |
+| `q` | `query` |
+| `filters` | `filter` (typed filter expression) |
+| `include` | `include` (a list on GETs, a dict on search) |
+| search `timing` / `total` | `search_time` |
+
+## Profile no longer searches
+
+```python
+import asyncio
+from supermemory import AsyncSupermemory
+
+client = AsyncSupermemory()
+
+profile, search = await asyncio.gather(
+    client.profile("user_alex"),
+    client.search("user_alex", query="upcoming meetings"),
+)
+```
+
+## Several container tags
+
+v5 operations take exactly one namespace. To search several, fan out and merge:
+
+```python
+responses = await asyncio.gather(*(client.search(ns, query="roadmap") for ns in ["user_alex", "team_design"]))
+results = [r for resp in responses for r in resp.results]
+```
+
+## Smaller differences
+
+- Response types are generated from the v5 spec, so their names changed (e.g. `SearchMemoriesResponse` became `SearchResponse`). Import them from `supermemory.types`.
+- `client.with_streaming_response` is gone. None of the v5 endpoints stream.
+- `NOT_GIVEN` is gone. Leave out an argument (or pass `None`) to omit it.
+
+## Removed
+
+These 3.x methods have no v5 endpoint yet. Stay on `supermemory<4` if you depend on them:
+
+- `client.settings.{reset, suggest_buckets}` and chunking settings
+- `client.conversations.add`
+- `client.documents.{list_processing, chunks, file_url}`
+- container tag merge
+- `client.memories.{add, update_memory}`

supermemory-5.0.0/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.5
+Name: supermemory
+Version: 5.0.0
+Summary: The official Python library for the Supermemory API
+Project-URL: Homepage, https://supermemory.ai
+Project-URL: Documentation, https://docs.supermemory.ai
+Project-URL: Repository, https://github.com/supermemoryai/python-sdk
+Author-email: Supermemory <dhravya@supermemory.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.21.2
+Requires-Dist: pydantic-core>=2.18.2
+Requires-Dist: pydantic>=1.9.2
+Requires-Dist: typing-extensions>=4.0.0
+Provides-Extra: aiohttp
+Requires-Dist: httpx-aiohttp>=0.1.8; extra == 'aiohttp'
+Description-Content-Type: text/markdown
+
+# Supermemory Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/supermemory.svg)](https://pypi.org/project/supermemory/)
+
+The official Python library for the [Supermemory](https://supermemory.ai) v5 API, with sync and async clients built on [httpx](https://github.com/encode/httpx).
+
+> **Upgrading from 3.x?** v5 moves to the namespace-first v5 API. See [MIGRATION.md](MIGRATION.md).
+
+## Installation
+
+```sh
+pip install supermemory
+```
+
+## Usage
+
+```python
+from supermemory import Supermemory
+
+client = Supermemory()  # reads SUPERMEMORY_API_KEY; or Supermemory(api_key="...")
+
+client.add("user_alex", content="Alex prefers morning meetings.", id="pref-1")
+
+response = client.search("user_alex", query="when does alex like to meet?", limit=5)
+for result in response.results:
+    print(result)
+```
+
+Every content operation is scoped to a **namespace** (a user ID, project ID, or anything you want to isolate memories by), passed as the first argument.
+
+### Async
+
+```python
+import asyncio
+from supermemory import AsyncSupermemory
+
+async_client = AsyncSupermemory()
+
+
+async def main() -> None:
+    profile, results = await asyncio.gather(
+        async_client.profile("user_alex"),
+        async_client.search("user_alex", query="upcoming meetings"),
+    )
+
+
+asyncio.run(main())
+```
+
+Install `supermemory[aiohttp]` to use aiohttp as the async transport.
+
+## API surface
+
+| Call | Endpoint |
+|---|---|
+| `client.add(namespace, content=...)` | `POST /ns/{namespace}/document` |
+| `client.search(namespace, query=...)` | `POST /ns/{namespace}/search` |
+| `client.profile(namespace)` | `POST /ns/{namespace}/profile` |
+| `client.list(namespace, "documents" \| "chunks" \| "memories")` | `POST /ns/{namespace}/list/{type}` |
+| `client.documents.{get, update, delete, batch_add, upload_file, replace_with_file, update_file}` | `/ns/{namespace}/document…` |
+| `client.memories.{forget, forget_matching}` | `/ns/{namespace}/memories…` |
+| `client.profiles.{get_buckets, set_buckets, delete_buckets}` | `/ns/{namespace}/profile/buckets` |
+| `client.connectors.{list_all, list, create, get, update, delete, sync}` | `/connectors`, `/ns/{namespace}/connectors…` |
+| `client.namespaces.{list, get, update, delete}` | `/ns`, `/ns/{namespace}` |
+| `client.organization.{get, update}` | `/organization` |
+
+Full parameter reference: [reference.md](reference.md).
+
+## Filtering
+
+Filters are plain dicts (typed as `FilterExpressionParams`), combinable with `and` / `or`:
+
+```python
+response = client.search(
+    "user_alex",
+    query="launch plans",
+    filter={
+        "operator": "and",
+        "operands": [
+            {"field": "source", "operator": "eq", "value": "slack"},
+            {"field": "priority", "operator": "gte", "value": 3},
+        ],
+    },
+)
+```
+
+The same filter shape works for `client.list(...)` and `client.profile(...)`.
+
+## Listing
+
+```python
+page = client.list("user_alex", "documents", page=1, limit=50, sort="createdAt", order="desc")
+for document in page.documents or []:
+    print(document.id, document.title)
+print(page.pagination)
+```
+
+## File uploads
+
+```python
+with open("notes.pdf", "rb") as f:
+    client.documents.upload_file("user_alex", file=f)
+```
+
+## Errors
+
+Same exception classes as 3.x. Non-2xx responses raise a subclass of `supermemory.APIStatusError` with `status_code`, `body`, `message`, `request`, and `response`. Network failures raise `APIConnectionError` (`APITimeoutError` for timeouts):
+
+```python
+import supermemory
+from supermemory import Supermemory
+
+client = Supermemory()
+
+try:
+    client.documents.get("user_alex", "missing-id")
+except supermemory.NotFoundError:
+    ...
+except supermemory.RateLimitError as e:
+    print(e.response.headers.get("retry-after"))
+except supermemory.APIStatusError as e:
+    print(e.status_code, e.body)
+except supermemory.APIConnectionError:
+    ...
+```
+
+| Status | Error |
+|---|---|
+| 400 | `BadRequestError` |
+| 401 | `AuthenticationError` |
+| 403 | `PermissionDeniedError` |
+| 404 | `NotFoundError` |
+| 409 | `ConflictError` |
+| 422 | `UnprocessableEntityError` |
+| 429 | `RateLimitError` |
+| >=500 | `InternalServerError` |
+
+## Retries, timeouts, and per-request options
+
+Connection errors, 408, 429, and 5xx responses are retried twice with exponential backoff, and requests time out after 60 seconds (5 seconds to connect). All of these can be set on the client, or for one request with `with_options`:
+
+```python
+import httpx
+
+client = Supermemory(max_retries=5, timeout=20.0, default_headers={"X-App": "my-app"})
+
+client.with_options(max_retries=0, timeout=httpx.Timeout(5.0)).search("user_alex", query="...")
+```
+
+Every method also takes `extra_headers`, `extra_query`, `extra_body`, and `timeout`:
+
+```python
+client.search("user_alex", query="...", extra_headers={"X-Trace": "1"}, timeout=5)
+```
+
+The client reads `SUPERMEMORY_API_KEY`, `SUPERMEMORY_BASE_URL`, and `SUPERMEMORY_CUSTOM_HEADERS` from the environment.
+
+## Raw responses
+
+```python
+response = client.with_raw_response.search("user_alex", query="...")
+print(response.headers.get("x-request-id"))
+results = response.parse()  # SearchResponse
+```
+
+Response models have `.to_dict()` and `.to_json()`.
+
+## Development
+
+The SDK is generated from the live v5 OpenAPI spec with [Fern](https://buildwithfern.com)'s open-source Python generator, run locally in Docker. No hosted codegen service is involved. Don't edit `src/supermemory` by hand; CI fails if it doesn't match a fresh generation.
+
+| To change | Edit |
+|---|---|
+| Method names, grouping, parameter names, hidden endpoints | `fern/overlay.yaml` (`x-fern-sdk-group-name`, `x-fern-sdk-method-name`, `x-fern-parameter-name`, `x-fern-ignore`) |
+| Type names (`Document`, `Memory`, `Connector`, …) | `fern/schemas.yaml` |
+| Generator options | `fern/generators.yml` |
+| Client conventions (options, errors, per-call options) | `custom/supermemory/_compat.py` |
+| Small fixes to Fern's generated core | `custom/patches/*.patch` |
+
+`scripts/generate` fetches the spec, names its schemas, runs Fern, then layers `custom/` on top.
+
+```sh
+scripts/generate              # fetch /v5/openapi and regenerate (needs Docker, bun, uv)
+SKIP_FETCH=1 scripts/generate # regenerate from the committed fern/openapi.json
+uv run --group dev pytest     # offline tests, including every snippet in README.md and MIGRATION.md
+SUPERMEMORY_LIVE_API_KEY=... uv run --group dev pytest tests/live   # against the real API
+```
+
+Runnable examples are in [`examples/`](examples).
+
+### Releases
+
+- When the API deploy sends `openapi-updated` (or on the daily backstop run), **Generate SDK** regenerates. If the SDK changed, it bumps the version and opens a PR with the tests already run.
+- Merging a PR that changes the version in `pyproject.toml` publishes it to PyPI and creates a GitHub release.
+- To cut a specific version, run **Generate SDK** manually with `version` set.