@maximem/synap-js-sdk 0.1.1 → 0.1.4

package/README.md

@@ -1,88 +1,52 @@
 # @maximem/synap-js-sdk
 
-JavaScript SDK wrapper for the Synap Python SDK.
+Node.js wrapper for the Synap Python SDK.
 
-This package gives Node.js apps a normal SDK interface, while internally running a Python bridge process that executes the real `maximem_synap` SDK.
+## Prerequisites
 
-## Why this wrapper exists
+- Node.js 18+
+- Python 3.8+
 
-The Synap Python SDK currently has the full feature surface (gRPC anticipation, ingestion lifecycle, context fetch modes, telemetry hooks). This JS SDK keeps your app code in Node while delegating memory operations to Python.
-
-## Architecture
+## Install
 
-```text
-Your Node app
-  -> @maximem/synap-js-sdk (JS API)
-    -> BridgeManager (JSON-RPC over stdin/stdout)
-      -> synap_bridge.py
-        -> maximem_synap (Python SDK)
-          -> Synap API + gRPC
+```bash
+npm install @maximem/synap-js-sdk
 ```
 
-## Flow and failure map
-
-```text
-[1] App calls createClient()/client.init()
-  ->
-[2] BridgeManager resolves python path + bridge path
-  -> FAIL A: python not found / bridge file missing
-  ->
-[3] Node spawns synap_bridge.py child process
-  -> FAIL B: process spawn/runtime error
-  ->
-[4] Node sends JSON-RPC "init"
-  ->
-[5] Python imports maximem_synap + builds SDK config
-  -> FAIL C: maximem_synap not installed in chosen python/venv
-  ->
-[6] SDK initialize() + optional gRPC listen
-  -> FAIL D: invalid instance/auth OR API/gRPC endpoint unreachable
-  ->
-[7] App calls add/search/get/delete
-  ->
-[8] Node sends JSON-RPC method
-  -> FAIL E: IPC timeout / broken pipe / bridge crash
-  ->
-[9] Python executes SDK operation
-  -> FAIL F: SDK/server error, bad input, ingestion timeout
-  ->
-[10] Python returns JSON result
-  ->
-[11] Node resolves promise and returns to app
-```
+## Setup (JS Runtime)
 
-## What this means operationally
+Install the Python runtime used by the wrapper:
 
-Because this is a wrapper SDK, your deployment must include both runtimes:
+```bash
+npx synap-js-sdk setup --sdk-version 0.1.1
+```
 
-1. Node.js (for your app + wrapper)
-2. Python (for the bridge + Synap Python SDK)
-3. A virtualenv containing `maximem-synap`
+If you want the latest Python SDK version, omit `--sdk-version`.
 
-This is the main difference versus pure JS SDKs.
+## Verify Runtime
 
-## Install
+macOS/Linux:
 
 ```bash
-npm install @maximem/synap-js-sdk
+~/.synap-js-sdk/.venv/bin/python -c "import maximem_synap; print(maximem_synap.__version__)"
 ```
 
-Then set up the Python runtime used by the wrapper (JS runtime flow):
+Windows:
 
-```bash
-npx synap-js-sdk setup --sdk-version <PY_SDK_VERSION>
+```powershell
+$env:USERPROFILE\.synap-js-sdk\.venv\Scripts\python.exe -c "import maximem_synap; print(maximem_synap.__version__)"
 ```
 
-If you omit `--sdk-version`, it installs the latest package configured as `maximem-synap`.
-This wrapper installs the Python SDK from package indexes (PyPI by default), not from local source paths.
+## Required Environment Variables
 
-If you want TypeScript support from the start, run:
+- `SYNAP_INSTANCE_ID`
+- `SYNAP_BOOTSTRAP_TOKEN` (required for first-time initialization/new instance)
+- `SYNAP_BASE_URL`
+- `SYNAP_GRPC_HOST`
+- `SYNAP_GRPC_PORT`
+- `SYNAP_GRPC_TLS`
 
-```bash
-npm install @maximem/synap-js-sdk && npx synap-js-sdk setup --sdk-version <PY_SDK_VERSION> && npx synap-js-sdk setup-ts
-```
-
-## Quick start in a Node project
+## Quick Start (JavaScript)
 
 ```js
 const { createClient } = require('@maximem/synap-js-sdk');
@@ -101,10 +65,7 @@ async function run() {
 
   await synap.addMemory({
     userId: 'user-123',
-    messages: [
-      { role: 'user', content: 'My name is Alex and I live in Austin.' },
-      { role: 'assistant', content: 'Got it.' },
-    ],
+    messages: [{ role: 'user', content: 'My name is Alex and I live in Austin.' }],
   });
 
   const result = await synap.searchMemory({
@@ -120,147 +81,28 @@ async function run() {
 run().catch(console.error);
 ```
 
-## API
-
-### `createClient(options)` / `new SynapClient(options)`
+## TypeScript Extension Setup
 
-Options:
-
-- `instanceId`: explicit Synap instance id. If omitted, the SDK tries `SYNAP_INSTANCE_ID`, then `~/.synap/instances/*/metadata.json`.
-- `bootstrapToken`: one-time bootstrap token/key (env: `SYNAP_BOOTSTRAP_TOKEN` or `SYNAP_BOOTSTRAP_KEY`). Required on first initialization of a new instance.
-- `baseUrl`, `grpcHost`, `grpcPort`, `grpcUseTls`: Synap endpoints.
-- `pythonBin`: explicit Python path for the bridge.
-- `bridgeScriptPath`: override Python bridge script path.
-- `sdkHome`: home for managed runtime (default `~/.synap-js-sdk`).
-- `venvPath`: override managed venv path.
-- `pythonPackage`: pip package name (default `maximem-synap`).
-- `pythonSdkVersion`: pip version pin.
-- `noDeps`: use pip `--no-deps` during auto setup.
-- `noBuildIsolation`: use pip `--no-build-isolation` during auto setup.
-- `upgrade`: use pip `--upgrade` during auto setup.
-- `forceRecreateVenv`: recreate managed venv during auto setup.
-- `autoSetup`: if `true`, runtime setup is attempted automatically when Python is missing.
-
-### Methods
-
-- `init()`
-- `addMemory({ userId, messages })`
-- `searchMemory({ userId, query, maxResults })`
-- `getMemories({ userId })`
-- `deleteMemory({ userId, memoryId })`
-- `shutdown()`
-
-## CLI
+Add TypeScript support to an existing JS project:
 
 ```bash
-synap-js-sdk setup [options]
-synap-js-sdk setup-ts [options]
+npx synap-js-sdk setup-ts
 ```
 
-Options:
-
-`setup`:
-- `--python <bin>`: bootstrap Python command (default `python3`)
-- `--sdk-home <path>`: runtime home directory
-- `--venv <path>`: virtualenv path
-- `--package <name>`: Python package name
-- `--sdk-version <ver>`: Python SDK version pin
-- `--no-deps`: install package with no dependency resolution
-- `--no-build-isolation`: disable pip build isolation
-- `--upgrade`: use pip `--upgrade`
-- `--force-recreate-venv`: recreate venv
+This command can:
+- install `typescript` and `@types/node`
+- generate `tsconfig.json` (if missing)
+- generate `src/synap.ts` typed wrapper (if missing)
 
-`setup-ts`:
-- `--project-dir <path>`: target Node project (default: current working directory)
-- `--package-manager <name>`: one of `npm`, `pnpm`, `yarn`, `bun` (auto-detected by lockfile if omitted)
-- `--skip-install`: skip TypeScript dependency install (`typescript`, `@types/node`)
-- `--tsconfig-path <path>`: output path for generated tsconfig (default: `tsconfig.json`)
-- `--wrapper-path <path>`: output path for generated typed wrapper (default: `src/synap.ts`)
-- `--no-wrapper`: do not generate typed wrapper file
-- `--force`: overwrite generated files if they already exist
-
-## TypeScript Extension Flow
-
-Use this when a project already has `@maximem/synap-js-sdk` installed and wants type safety without rewriting runtime JS:
-
-1. Run `npx synap-js-sdk setup-ts`
-2. This installs `typescript` and `@types/node` (unless `--skip-install`)
-3. This generates `tsconfig.json` (if missing)
-4. This generates `src/synap.ts` typed wrapper (unless `--no-wrapper`)
-
-Programmatic alternative:
-
-```js
-const { setupTypeScriptExtension } = require('@maximem/synap-js-sdk');
-
-setupTypeScriptExtension({ projectDir: process.cwd() });
-```
-
-## Environment template
-
-Use the provided template:
+## Single-Flow Setup (JS + TS)
 
 ```bash
-cp .env.example .env
-```
-
-Template file: `.env.example`
-
-## EC2 + Docker flow (recommended)
-
-Build time should install Node deps and Python runtime once, not on every container start.
-
-```dockerfile
-FROM node:20-bullseye
-
-RUN apt-get update && apt-get install -y python3 python3-venv && rm -rf /var/lib/apt/lists/*
-
-WORKDIR /app
-COPY package*.json ./
-RUN npm ci
-
-# Install wrapper python runtime deterministically
-RUN npx synap-js-sdk setup --python python3 --sdk-home /opt/synap-js-sdk --sdk-version <PY_SDK_VERSION>
-
-COPY . .
-
-ENV SYNAP_JS_SDK_HOME=/opt/synap-js-sdk
-ENV SYNAP_BASE_URL=http://<synap-api-host>:8000
-ENV SYNAP_GRPC_HOST=<synap-grpc-host>
-ENV SYNAP_GRPC_PORT=50051
-ENV SYNAP_GRPC_TLS=false
-
-CMD ["node", "server.js"]
+npm install @maximem/synap-js-sdk && npx synap-js-sdk setup --sdk-version 0.1.1 && npx synap-js-sdk setup-ts
 ```
 
-Runtime flow in container:
-
-1. Node app starts.
-2. First Synap call starts Python bridge process.
-3. Bridge sends `init` to Python SDK.
-4. API methods run through JSON-RPC.
-5. On shutdown, wrapper sends `shutdown` and stops bridge.
-
-## Versioning and compatibility matrix
-
-Recommended policy:
-
-1. Keep JS and Python SDK on the same semantic version (`x.y.z`).
-2. Publish JS only after Python package `x.y.z` is available.
-3. CI release pipeline should verify `pip install maximem-synap==x.y.z` before npm publish.
-
-Even with same-version policy, keep a compatibility table in docs for rollback safety:
+## CLI Commands
 
-```text
-JS 1.3.x -> Python 1.3.x
-JS 1.2.x -> Python 1.2.x
+```bash
+synap-js-sdk setup [options]
+synap-js-sdk setup-ts [options]
 ```
-
-## Failure modes to expect
-
-- Python not installed or not found
-- Bridge process crash/restart
-- pip install failure due to network/private index
-- auth/instance id missing or expired
-
-Treat this SDK as a managed dual-runtime component in production.

package/bridge/synap_bridge.py

@@ -168,11 +168,12 @@ async def handle_add_memory(params: dict) -> dict:
     start = time.perf_counter()
 
     step = time.perf_counter()
+    mode = params.get("mode", "long-range")
     create_result = await sdk.memories.create(
         document=transcript,
         document_type="ai-chat-conversation",
         user_id=user_id,
-        mode="long-range",
+        mode=mode,
     )
     append_step(timings, "memories_create", step)
 
@@ -243,6 +244,7 @@ async def handle_search_memory(params: dict) -> dict:
     user_id = params["user_id"]
     query = params["query"]
     max_results = params.get("max_results", 10)
+    mode = params.get("mode", "fast")
 
     start = time.perf_counter()
 
@@ -252,7 +254,7 @@ async def handle_search_memory(params: dict) -> dict:
         search_query=[query],
         max_results=max_results,
         types=["all"],
-        mode="fast",
+        mode=mode,
     )
     append_step(timings, "context_fetch", step)
 
@@ -293,6 +295,7 @@ async def handle_get_memories(params: dict) -> dict:
     timings: List[dict] = []
 
     user_id = params["user_id"]
+    mode = params.get("mode", "fast")
 
     start = time.perf_counter()
 
@@ -302,7 +305,7 @@ async def handle_get_memories(params: dict) -> dict:
         search_query=[],
         max_results=100,
         types=["all"],
-        mode="fast",
+        mode=mode,
     )
     append_step(timings, "context_fetch_all", step)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maximem/synap-js-sdk",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "JavaScript wrapper around the Synap Python SDK",
   "main": "src/index.js",
   "types": "types/index.d.ts",

package/src/synap-client.js

@@ -14,32 +14,33 @@ class SynapClient {
     await this.bridge.ensureStarted();
   }
 
-  async addMemory({ userId, messages }) {
+  async addMemory({ userId, messages, mode }) {
     this.#assert(userId, 'userId is required');
     this.#assert(Array.isArray(messages), 'messages must be an array');
 
-    return this.bridge.call(
-      'add_memory',
-      { user_id: userId, messages },
-      this.options.ingestTimeoutMs
-    );
+    const params = { user_id: userId, messages };
+    if (mode !== undefined) params.mode = mode;
+
+    return this.bridge.call('add_memory', params, this.options.ingestTimeoutMs);
   }
 
-  async searchMemory({ userId, query, maxResults = 10 }) {
+  async searchMemory({ userId, query, maxResults = 10, mode }) {
     this.#assert(userId, 'userId is required');
     this.#assert(query, 'query is required');
 
-    return this.bridge.call('search_memory', {
-      user_id: userId,
-      query,
-      max_results: maxResults,
-    });
+    const params = { user_id: userId, query, max_results: maxResults };
+    if (mode !== undefined) params.mode = mode;
+
+    return this.bridge.call('search_memory', params);
   }
 
-  async getMemories({ userId }) {
+  async getMemories({ userId, mode }) {
     this.#assert(userId, 'userId is required');
 
-    return this.bridge.call('get_memories', { user_id: userId });
+    const params = { user_id: userId };
+    if (mode !== undefined) params.mode = mode;
+
+    return this.bridge.call('get_memories', params);
   }
 
   async deleteMemory({ userId, memoryId = null }) {