feat(sdk-playground): interactive SDK chat playground

.github/workflows/ci.yml

@@ -26,7 +26,7 @@ jobs:
       - name: Install dependencies
         run: bun install --frozen-lockfile
 
-      - name: Detect SDK package changes
+      - name: Detect SDK and playground changes
         id: sdk-changes
         run: |
           if git diff --quiet "${{ github.event.pull_request.base.sha }}" HEAD -- packages/tools; then
@@ -41,26 +41,63 @@ jobs:
             echo "ai_sdk=true" >> "$GITHUB_OUTPUT"
           fi
 
+          if git diff --quiet "${{ github.event.pull_request.base.sha }}" HEAD -- apps/sdk-playground; then
+            echo "sdk_playground=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "sdk_playground=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Setup Python for SDK Playground
+        if: steps.sdk-changes.outputs.sdk_playground == 'true'
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+
+      - name: Setup uv for SDK Playground
+        if: steps.sdk-changes.outputs.sdk_playground == 'true'
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: "0.12.5"
+          enable-cache: true
+          working-directory: apps/sdk-playground/python
+          cache-dependency-glob: uv.lock
+
+      - name: Validate SDK Playground Python server
+        if: steps.sdk-changes.outputs.sdk_playground == 'true'
+        working-directory: apps/sdk-playground/python
+        run: |
+          uv sync --locked --python 3.12
+          .venv/bin/python -m py_compile server.py
+          .venv/bin/python -c "import server"
+
       - name: Run Tools unit tests
         if: steps.sdk-changes.outputs.tools == 'true'
         run: bun run --cwd packages/tools test:unit
 
       - name: Build Tools package
-        if: steps.sdk-changes.outputs.tools == 'true' || steps.sdk-changes.outputs.ai_sdk == 'true'
+        if: steps.sdk-changes.outputs.tools == 'true' || steps.sdk-changes.outputs.ai_sdk == 'true' || steps.sdk-changes.outputs.sdk_playground == 'true'
         run: bun run --cwd packages/tools build
 
       - name: Run AI SDK type checking
-        if: steps.sdk-changes.outputs.tools == 'true' || steps.sdk-changes.outputs.ai_sdk == 'true'
+        if: steps.sdk-changes.outputs.tools == 'true' || steps.sdk-changes.outputs.ai_sdk == 'true' || steps.sdk-changes.outputs.sdk_playground == 'true'
         run: bun run --cwd packages/ai-sdk check-types
 
       - name: Run AI SDK unit tests
         if: steps.sdk-changes.outputs.ai_sdk == 'true'
         run: bun run --cwd packages/ai-sdk test:unit
 
       - name: Build AI SDK package
-        if: steps.sdk-changes.outputs.ai_sdk == 'true'
+        if: steps.sdk-changes.outputs.ai_sdk == 'true' || steps.sdk-changes.outputs.sdk_playground == 'true'
         run: bun run --cwd packages/ai-sdk build
 
+      - name: Run SDK Playground type checking
+        if: steps.sdk-changes.outputs.sdk_playground == 'true'
+        run: bun run --cwd apps/sdk-playground check-types:app
+
+      - name: Build SDK Playground
+        if: steps.sdk-changes.outputs.sdk_playground == 'true'
+        run: bun run --cwd apps/sdk-playground build:app
+
       - name: Run Memory Graph type checking
         run: bun run --cwd packages/memory-graph check-types
 

apps/sdk-playground/.env.example

@@ -0,0 +1,11 @@
+# Local development only. Use disposable development credentials, not production keys.
+SUPERMEMORY_API_KEY=
+OPENAI_API_KEY=
+SUPERMEMORY_BASE_URL=
+
+# Optional
+MODEL_NAME=gpt-4o-mini
+SDK_PLAYGROUND_PYTHON_URL=http://127.0.0.1:8792
+SDK_PLAYGROUND_PYTHON_PORT=8792
+# Leave unset unless a trusted non-local development hostname must use env keys.
+# SDK_PLAYGROUND_ALLOW_ENV_KEYS=true

apps/sdk-playground/.gitignore

@@ -0,0 +1,7 @@
+.next
+.env*
+!.env.example
+node_modules
+python/.venv
+next-env.d.ts
+*.tsbuildinfo

apps/sdk-playground/README.md

@@ -0,0 +1,94 @@
+# SDK Agent Playground
+
+Chat with a **real agent** and switch which Supermemory SDK integration powers it.
+
+> [!WARNING]
+> This is a local, single-user development tool. It makes real API calls, stores
+> browser-entered keys only in memory unless you opt into tab-scoped
+> `sessionStorage`, and exposes tools that can permanently delete documents. Use
+> disposable development credentials and a test container; do not deploy it or
+> point it at production data.
+
+## Integrations
+
+| SDK | Style | What happens |
+|-----|-------|----------------|
+| AI SDK + middleware | automatic | `withSupermemory` injects context + saves chat |
+| OpenAI + middleware | automatic | same, via OpenAI client wrapper |
+| AI SDK + tools | explicit | model calls 7 memory tools via `generateText` |
+| OpenAI + tools | explicit | OpenAI function-calling loop |
+| `@supermemory/ai-sdk` | explicit | re-export of tools/ai-sdk |
+| Python OpenAI middleware | automatic | `with_supermemory` |
+| Python OpenAI tools | explicit | `SupermemoryTools` loop |
+| Python supermemory direct | manual | `profile()` + OpenAI + `add()` |
+
+## Setup
+
+Prerequisites: Bun 1.3.6, Python 3.11+, and
+[`uv`](https://docs.astral.sh/uv/). Portless is required only for the HTTPS
+development hostname; the direct localhost commands below work without it.
+
+From the repository root:
+
+```bash
+bun install --frozen-lockfile
+
+cp apps/sdk-playground/.env.example apps/sdk-playground/.env.local
+# Required:
+# SUPERMEMORY_API_KEY=...
+# OPENAI_API_KEY=...
+```
+
+The playground scripts build `@supermemory/tools` first and
+`@supermemory/ai-sdk` second before starting, type-checking, or building the
+Next.js app. Development mode also watches both workspace packages.
+
+## Run
+
+```bash
+bun run --cwd apps/sdk-playground dev
+```
+
+Opens:
+
+- **Chat UI** — https://sdk.dev.supermemory.ai via Portless
+- **Next.js server** — http://127.0.0.1:3005
+- **Python server** — http://127.0.0.1:8792
+
+To run without Portless, use two terminals:
+
+```bash
+bun run --cwd apps/sdk-playground dev:next
+bun run --cwd apps/sdk-playground dev:python
+```
+
+For a production-mode local smoke check, build first and then start. `start`
+runs both the built Next.js app and the Python server, and remains intended for
+local use only.
+
+```bash
+bun run --cwd apps/sdk-playground build
+bun run --cwd apps/sdk-playground start
+```
+
+Try:
+
+- "Remember that I prefer oat milk in coffee"
+- "What do you know about my drink preferences?"
+- "Forget that I like tea" (tools mode)
+
+## Env
+
+| Variable | Required |
+|----------|----------|
+| `SUPERMEMORY_API_KEY` | yes |
+| `OPENAI_API_KEY` | yes |
+| `SUPERMEMORY_BASE_URL` | optional |
+| `MODEL_NAME` | optional (default `gpt-4o-mini`) |
+| `SDK_PLAYGROUND_PYTHON_URL` | optional (default `http://127.0.0.1:8792`) |
+| `SDK_PLAYGROUND_PYTHON_PORT` | optional (default `8792`) |
+| `SDK_PLAYGROUND_ALLOW_ENV_KEYS` | optional; set `true` only when a trusted non-local hostname must use server env keys |
+
+Server environment keys are exposed to the playground routes only on loopback
+hosts and `sdk.dev.supermemory.ai` by default. Browser-provided keys remain
+request-scoped and are never copied into process-global environment variables.

apps/sdk-playground/next.config.ts

@@ -0,0 +1,7 @@
+import type { NextConfig } from "next"
+
+const nextConfig: NextConfig = {
+	transpilePackages: ["@supermemory/tools", "@supermemory/ai-sdk"],
+}
+
+export default nextConfig

apps/sdk-playground/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "sdk-playground",
+  "version": "0.1.0",
+  "private": true,
+  "portless": { "name": "sdk.dev.supermemory", "script": "dev:app" },
+  "scripts": {
+    "dev": "portless",
+    "dev:app": "bun run build:dependencies && concurrently -k -n tools,ai-sdk,next,py -c yellow,magenta,blue,green \"bun run --cwd ../../packages/tools dev\" \"bun run --cwd ../../packages/ai-sdk dev\" \"next dev --hostname 127.0.0.1 --port ${PORT:-3005}\" \"bun run dev:python\"",
+    "dev:next": "bun run build:dependencies && next dev --hostname 127.0.0.1 --port ${PORT:-3005}",
+    "dev:python": "cd python && uv run server.py",
+    "build:dependencies": "bun run --cwd ../../packages/tools build && bun run --cwd ../../packages/ai-sdk build",
+    "build:app": "next build",
+    "build": "bun run build:dependencies && bun run build:app",
+    "start": "concurrently -k -n next,py -c blue,green \"next start --hostname 127.0.0.1 --port ${PORT:-3005}\" \"bun run dev:python\"",
+    "typegen": "next typegen",
+    "check-types:app": "bun run typegen && tsc --noEmit --incremental false",
+    "check-types": "bun run build:dependencies && bun run check-types:app"
+  },
+  "dependencies": {
+    "@ai-sdk/openai": "^2.0.22",
+    "@supermemory/ai-sdk": "workspace:*",
+    "@supermemory/tools": "workspace:*",
+    "ai": "^5.0.113",
+    "next": "16.0.7",
+    "openai": "^4.104.0",
+    "react": "19.2.0",
+    "react-dom": "19.2.0",
+    "supermemory": "^4.25.4"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "concurrently": "^9.1.2",
+    "tailwindcss": "^4",
+    "typescript": "^5"
+  }
+}

apps/sdk-playground/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+	plugins: {
+		"@tailwindcss/postcss": {},
+	},
+}
+
+export default config

apps/sdk-playground/python/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "sdk-playground-python"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi>=0.115.0",
+    "httpx>=0.28.0",
+    "uvicorn[standard]>=0.32.0",
+    "python-dotenv>=1.0.1",
+    "supermemory>=3.50.0",
+    "openai>=1.102.0",
+    "supermemory-openai-sdk[async]",
+]
+
+[tool.uv.sources]
+supermemory-openai-sdk = { path = "../../../packages/openai-sdk-python", editable = true }