feat!: generate the SDK from the v5 API with Fern (5.0.0rc1), replacing Stainless

[Dhravya]

What

Replaces the Stainless-generated SDK with one generated from the v5 API (https://api.supermemory.ai/v5/openapi) by Fern's open-source Python generator. It runs locally in Docker, the same way cloudflare/forge generates its SDKs, so there's no hosted codegen service or per-language plan. It's versioned 5.0.0rc1, a prerelease, so pip install supermemory stays on 3.62.0 until 5.0.0.

The SDK

Method names match the TypeScript SDK's v5 surface. Everything around the methods keeps the 3.x conventions.

from supermemory import Supermemory, NotFoundError

client = Supermemory()  # SUPERMEMORY_API_KEY
client.add("user_alex", content="Alex prefers morning meetings.", id="pref-1")
results = client.search("user_alex", query="when does alex meet?", limit=5).results

• Surface:
  • root: client.{add, search, profile, list}
  • documents.{get, update, delete, batch_add, upload_file, replace_with_file, update_file}
  • memories.{forget, forget_matching}
  • profiles.{get_buckets, set_buckets, delete_buckets}
  • connectors.{list_providers, list, create, get, update, delete, sync}
  • namespaces.* and organization.*
• Kept from 3.x:
  • client options: api_key, base_url, timeout, max_retries, default_headers, default_query, http_client
  • the SUPERMEMORY_* env vars
  • per-call options: extra_headers, extra_query, extra_body, timeout, plus with_options
  • the exception hierarchy, e.g. NotFoundError and RateLimitError, with .response and .request
  • with_raw_response.parse(), .to_dict() / .to_json(), and plain dicts for request params, typed as TypedDicts
• Named types: Document, Memory, SearchResult, Connector, Profile, FilterAnd, … 104 types instead of 204, set in fern/schemas.yaml.
• Breaking: container tags become namespaces, and Python 3.10+ is required. See MIGRATION.md.

How it's built

Path	Role
fern/overlay.yaml	method names and grouping, i.e. the SDK's syntax
fern/schemas.yaml	type names (structural matching, so new endpoints pick them up)
fern/generators.yml, fern/openapi.json	generator config and the committed spec snapshot
custom/	hand-written 3.x-compatible layer, spec-agnostic, plus 2 patches for bugs in Fern's generated core: nested filters were sent unconverted (e.g. case_sensitive instead of caseSensitive), and a crash on Python 3.9 with current pydantic
scripts/generate	fetch spec → name schemas → fern generate --local → layer custom/ → format

src/supermemory is never edited by hand. CI fails if it doesn't match a fresh generation.

Automation

• Generate SDK (generate.yml) runs on repository_dispatch: openapi-updated from the API deploy, a daily cron, or a manual run with an optional version. If the generated code changed, it bumps the version (rc1 → rc2, 5.0.0 → 5.0.1), runs the tests and opens a PR.
• Publish to PyPI runs on merge to main when the version is new: it builds, publishes with SUPERMEMORY_PYPI_TOKEN, then creates a tag and GitHub release.
• CI runs:
  • tests on Python 3.10–3.14 and on pydantic v1
  • ruff, the format check, mypy and the build
  • the generated-code drift check
  • optional live-API tests

Testing

• 36 offline tests pass on Python 3.10, 3.11, 3.12, 3.13 and 3.14, and on pydantic v1. They cover:
  • the wire format of every route group: method, path, auth header and body
  • nested filter and connector dicts sent with the API's camelCase field names
  • the 3.x conventions: options, env vars, the error class for each status code, timeouts, connection errors, raw responses and model helpers
  • every Python snippet in README.md and MIGRATION.md, run against a mock API
• ruff, mypy and pyright are clean, and pyright accepts valid filter dicts and rejects invalid ones.
• Regenerating twice gives identical output, and actionlint passes.
• ⚠️ The live-API tests (tests/live/) haven't passed yet. The key used locally got 401 Unauthorized on every v5 route, including GET /organization. Needs a valid key to confirm.

Before merging

• Add repo secret CODEGEN_PR_TOKEN (a fine-grained PAT or app token with contents and pull-requests write). PRs opened with the default token don't trigger CI.
• Optionally add SUPERMEMORY_LIVE_API_KEY to turn on the live tests, and run them once.
• Add the dispatch to mono's API deploy: gh api repos/supermemoryai/python-sdk/dispatches -f event_type=openapi-updated.
• Merging publishes supermemory==5.0.0rc1 to PyPI.

🤖 Generated with Claude Code

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	pypi/​mypy@​2.4.0
	pypi/​pytest@​9.1.1
	pypi/​ruff@​0.16.10
	pypi/​pydantic-core@​2.46.5
	pypi/​pytest-asyncio@​1.4.0

View full report