@maximem/synap-js-sdk 0.1.1

package/bridge/synap_bridge.py

@@ -0,0 +1,493 @@
+#!/usr/bin/env python3
+"""Synap SDK Bridge: JSON-RPC over stdin/stdout for the Node.js wrapper.
+
+Protocol:
+  stdin  -> {"id": 1, "method": "init", "params": {...}}\n
+  stdout <- {"id": 1, "result": {...}, "error": null}\n
+Methods:
+  init, add_memory, search_memory, get_memories, delete_memory, shutdown
+"""
+
+import asyncio
+import json
+import logging
+import sys
+import time
+import traceback
+from typing import Dict, List, Optional
+from uuid import UUID
+
+# Keep stdout clean for protocol responses.
+logging.basicConfig(
+    stream=sys.stderr,
+    level=logging.INFO,
+    format="%(asctime)s %(name)s %(levelname)s %(message)s",
+)
+logger = logging.getLogger("synap.bridge")
+
+try:
+    from maximem_synap import MaximemSynapSDK
+except Exception as import_error:  # pragma: no cover
+    sys.stderr.write(
+        "Failed to import maximem_synap. Run `synap-js-sdk setup` first.\n"
+    )
+    sys.stderr.write(f"Import error: {import_error}\n")
+    raise
+
+sdk = None
+user_memory_ids: Dict[str, List[str]] = {}
+
+
+def ms_since(start: float) -> int:
+    return int((time.perf_counter() - start) * 1000)
+
+
+def append_step(timings: List[dict], step: str, started: float) -> None:
+    timings.append({"step": step, "ms": ms_since(started)})
+
+
+def write_response(obj: dict) -> None:
+    sys.stdout.write(json.dumps(obj, default=str) + "\n")
+    sys.stdout.flush()
+
+
+def messages_to_text(messages: List[dict]) -> str:
+    lines: List[str] = []
+    for message in messages:
+        content = (message.get("content") or "").strip()
+        if not content:
+            continue
+        role = "Assistant" if message.get("role") == "assistant" else "User"
+        lines.append(f"{role}: {content}")
+    return "\n".join(lines)
+
+
+def on_anticipated_context(bundle: dict) -> None:
+    logger.info(
+        "Anticipated context bundle received: %s",
+        json.dumps(bundle, default=str)[:300],
+    )
+
+
+async def handle_init(params: dict) -> dict:
+    global sdk
+
+    handler_start = time.perf_counter()
+    timings: List[dict] = []
+
+    instance_id = params.get("instance_id", "")
+    bootstrap_token = params.get("bootstrap_token") or params.get("bootstrap_key")
+
+    step = time.perf_counter()
+    try:
+        sdk = MaximemSynapSDK(
+            instance_id=instance_id,
+            bootstrap_token=bootstrap_token,
+            _force_new=True,
+        )
+    except TypeError:
+        # Backward compatibility with older SDK constructors.
+        sdk = MaximemSynapSDK(instance_id=instance_id, _force_new=True)
+    append_step(timings, "construct_sdk", step)
+
+    config_kwargs = {"log_level": "DEBUG", "cache_backend": "sqlite"}
+
+    if params.get("base_url"):
+        config_kwargs["api_base_url"] = params["base_url"]
+    if params.get("grpc_host"):
+        config_kwargs["grpc_host"] = params["grpc_host"]
+    if params.get("grpc_port"):
+        config_kwargs["grpc_port"] = int(params["grpc_port"])
+    if "grpc_use_tls" in params:
+        config_kwargs["grpc_use_tls"] = bool(params["grpc_use_tls"])
+
+    step = time.perf_counter()
+    sdk.configure(**config_kwargs)
+    append_step(timings, "configure_sdk", step)
+
+    step = time.perf_counter()
+    if bootstrap_token:
+        await sdk.initialize(bootstrap_token=bootstrap_token)
+    else:
+        await sdk.initialize()
+    append_step(timings, "initialize_sdk", step)
+
+    grpc_listening = False
+
+    step = time.perf_counter()
+    try:
+        await sdk.instance.listen(
+            on_context=on_anticipated_context,
+            on_reconnect=lambda attempt: logger.info(
+                "gRPC reconnect attempt %d", attempt
+            ),
+            on_disconnect=lambda reason: logger.warning(
+                "gRPC disconnected: %s", reason
+            ),
+        )
+        grpc_listening = sdk.instance.is_listening
+    except Exception as exc:  # non-fatal
+        logger.warning("gRPC listen failed (non-fatal): %s", exc)
+    append_step(timings, "start_grpc_listener", step)
+
+    return {
+        "success": True,
+        "instance_id": instance_id,
+        "bootstrap_token_used": bool(bootstrap_token),
+        "grpc_listening": grpc_listening,
+        "bridgeTiming": {
+            "python_total_ms": ms_since(handler_start),
+            "steps": timings,
+        },
+    }
+
+
+async def handle_add_memory(params: dict) -> dict:
+    handler_start = time.perf_counter()
+    timings: List[dict] = []
+
+    user_id = params["user_id"]
+    messages = params["messages"]
+
+    step = time.perf_counter()
+    transcript = messages_to_text(messages)
+    append_step(timings, "build_transcript", step)
+
+    if not transcript:
+        return {
+            "success": True,
+            "latencyMs": 0,
+            "rawResponse": {"note": "Empty input; skipped"},
+            "note": "No text content to ingest",
+            "bridgeTiming": {
+                "python_total_ms": ms_since(handler_start),
+                "steps": timings,
+            },
+        }
+
+    start = time.perf_counter()
+
+    step = time.perf_counter()
+    create_result = await sdk.memories.create(
+        document=transcript,
+        document_type="ai-chat-conversation",
+        user_id=user_id,
+        mode="long-range",
+    )
+    append_step(timings, "memories_create", step)
+
+    ingestion_id = create_result.ingestion_id
+
+    step = time.perf_counter()
+    if sdk.instance.is_listening:
+        for message in messages:
+            content = (message.get("content") or "").strip()
+            if not content:
+                continue
+            try:
+                await sdk.instance.send_message(
+                    content=content,
+                    role=message.get("role", "user"),
+                    user_id=user_id,
+                )
+            except Exception as exc:
+                logger.debug("gRPC send_message failed (non-fatal): %s", exc)
+    append_step(timings, "grpc_send_messages", step)
+
+    step = time.perf_counter()
+    try:
+        final_status = await sdk.memories.wait_for_completion(
+            ingestion_id,
+            timeout_seconds=60,
+            poll_interval_seconds=2,
+        )
+    except TimeoutError:
+        append_step(timings, "wait_for_completion_timeout", step)
+        return {
+            "success": True,
+            "latencyMs": ms_since(start),
+            "rawResponse": {"ingestion_id": str(ingestion_id), "status": "timeout"},
+            "note": "Ingestion timed out after 60s and may still complete later",
+            "bridgeTiming": {
+                "python_total_ms": ms_since(handler_start),
+                "steps": timings,
+            },
+        }
+    append_step(timings, "wait_for_completion", step)
+
+    memory_ids = [str(memory_id) for memory_id in (final_status.memory_ids or [])]
+    if memory_ids:
+        user_memory_ids.setdefault(user_id, []).extend(memory_ids)
+
+    return {
+        "success": final_status.status.value != "failed",
+        "latencyMs": ms_since(start),
+        "rawResponse": {
+            "ingestion_id": str(ingestion_id),
+            "status": final_status.status.value,
+            "memories_created": final_status.memories_created,
+            "memory_ids": memory_ids,
+        },
+        "note": f"Ingestion {final_status.status.value}; created {final_status.memories_created}",
+        "bridgeTiming": {
+            "python_total_ms": ms_since(handler_start),
+            "steps": timings,
+        },
+    }
+
+
+async def handle_search_memory(params: dict) -> dict:
+    handler_start = time.perf_counter()
+    timings: List[dict] = []
+
+    user_id = params["user_id"]
+    query = params["query"]
+    max_results = params.get("max_results", 10)
+
+    start = time.perf_counter()
+
+    step = time.perf_counter()
+    context = await sdk.user.context.fetch(
+        user_id=user_id,
+        search_query=[query],
+        max_results=max_results,
+        types=["all"],
+        mode="fast",
+    )
+    append_step(timings, "context_fetch", step)
+
+    step = time.perf_counter()
+    results = []
+    for fact in context.facts:
+        results.append({"id": fact.id, "memory": fact.content, "score": fact.confidence})
+    for preference in context.preferences:
+        results.append(
+            {"id": preference.id, "memory": preference.content, "score": preference.strength}
+        )
+    for episode in context.episodes:
+        results.append(
+            {"id": episode.id, "memory": episode.summary, "score": episode.significance}
+        )
+    for emotion in context.emotions:
+        results.append(
+            {"id": emotion.id, "memory": emotion.context, "score": emotion.intensity}
+        )
+    append_step(timings, "map_context_results", step)
+
+    return {
+        "success": True,
+        "latencyMs": ms_since(start),
+        "results": results,
+        "resultsCount": len(results),
+        "rawResponse": context.raw if hasattr(context, "raw") else {},
+        "source": context.metadata.source if context.metadata else "unknown",
+        "bridgeTiming": {
+            "python_total_ms": ms_since(handler_start),
+            "steps": timings,
+        },
+    }
+
+
+async def handle_get_memories(params: dict) -> dict:
+    handler_start = time.perf_counter()
+    timings: List[dict] = []
+
+    user_id = params["user_id"]
+
+    start = time.perf_counter()
+
+    step = time.perf_counter()
+    context = await sdk.user.context.fetch(
+        user_id=user_id,
+        search_query=[],
+        max_results=100,
+        types=["all"],
+        mode="fast",
+    )
+    append_step(timings, "context_fetch_all", step)
+
+    step = time.perf_counter()
+    memories = []
+    for fact in context.facts:
+        memories.append({"id": fact.id, "memory": fact.content})
+    for preference in context.preferences:
+        memories.append({"id": preference.id, "memory": preference.content})
+    for episode in context.episodes:
+        memories.append({"id": episode.id, "memory": episode.summary})
+    for emotion in context.emotions:
+        memories.append({"id": emotion.id, "memory": emotion.context})
+    append_step(timings, "map_memories", step)
+
+    return {
+        "success": True,
+        "latencyMs": ms_since(start),
+        "memories": memories,
+        "memoriesCount": len(memories),
+        "rawResponse": context.raw if hasattr(context, "raw") else {},
+        "bridgeTiming": {
+            "python_total_ms": ms_since(handler_start),
+            "steps": timings,
+        },
+    }
+
+
+async def handle_delete_memory(params: dict) -> dict:
+    handler_start = time.perf_counter()
+    timings: List[dict] = []
+
+    user_id = params["user_id"]
+    memory_id = params.get("memory_id")
+
+    start = time.perf_counter()
+
+    step = time.perf_counter()
+    if memory_id:
+        await sdk.memories.delete(UUID(memory_id))
+        append_step(timings, "delete_single_memory", step)
+        return {
+            "success": True,
+            "latencyMs": ms_since(start),
+            "rawResponse": {"deleted": 1},
+            "bridgeTiming": {
+                "python_total_ms": ms_since(handler_start),
+                "steps": timings,
+            },
+        }
+
+    tracked_ids = user_memory_ids.get(user_id, [])
+    if not tracked_ids:
+        return {
+            "success": True,
+            "latencyMs": 0,
+            "rawResponse": None,
+            "note": "No tracked memory IDs for this user",
+            "bridgeTiming": {
+                "python_total_ms": ms_since(handler_start),
+                "steps": timings,
+            },
+        }
+
+    last_error: Optional[str] = None
+
+    step = time.perf_counter()
+    for tracked_id in tracked_ids:
+        try:
+            await sdk.memories.delete(UUID(tracked_id))
+        except Exception as exc:
+            last_error = str(exc)
+    append_step(timings, "delete_tracked_memories", step)
+
+    user_memory_ids.pop(user_id, None)
+
+    if last_error:
+        return {
+            "success": False,
+            "latencyMs": ms_since(start),
+            "error": last_error,
+            "bridgeTiming": {
+                "python_total_ms": ms_since(handler_start),
+                "steps": timings,
+            },
+        }
+
+    return {
+        "success": True,
+        "latencyMs": ms_since(start),
+        "rawResponse": {"deleted": len(tracked_ids)},
+        "note": f"Deleted {len(tracked_ids)} memories",
+        "bridgeTiming": {
+            "python_total_ms": ms_since(handler_start),
+            "steps": timings,
+        },
+    }
+
+
+async def handle_shutdown(_params: dict) -> dict:
+    handler_start = time.perf_counter()
+    timings: List[dict] = []
+
+    if sdk:
+        step = time.perf_counter()
+        try:
+            await sdk.instance.stop_listening()
+        except Exception:
+            pass
+        append_step(timings, "stop_listener", step)
+
+        step = time.perf_counter()
+        await sdk.shutdown()
+        append_step(timings, "sdk_shutdown", step)
+    return {
+        "success": True,
+        "bridgeTiming": {
+            "python_total_ms": ms_since(handler_start),
+            "steps": timings,
+        },
+    }
+
+
+HANDLERS = {
+    "init": handle_init,
+    "add_memory": handle_add_memory,
+    "search_memory": handle_search_memory,
+    "get_memories": handle_get_memories,
+    "delete_memory": handle_delete_memory,
+    "shutdown": handle_shutdown,
+}
+
+
+async def main() -> None:
+    logger.info("Synap bridge starting")
+
+    reader = asyncio.StreamReader()
+    protocol = asyncio.StreamReaderProtocol(reader)
+    await asyncio.get_event_loop().connect_read_pipe(lambda: protocol, sys.stdin)
+
+    while True:
+        line = await reader.readline()
+        if not line:
+            logger.info("stdin closed; shutting down bridge")
+            if sdk and getattr(sdk, "_initialized", False):
+                await handle_shutdown({})
+            break
+
+        payload = line.decode().strip()
+        if not payload:
+            continue
+
+        try:
+            request = json.loads(payload)
+        except json.JSONDecodeError as exc:
+            write_response({"id": None, "result": None, "error": f"Invalid JSON: {exc}"})
+            continue
+
+        req_id = request.get("id")
+        method = request.get("method")
+        params = request.get("params", {})
+
+        handler = HANDLERS.get(method)
+        if not handler:
+            write_response({"id": req_id, "result": None, "error": f"Unknown method: {method}"})
+            continue
+
+        try:
+            handler_started = time.perf_counter()
+            result = await handler(params)
+            if isinstance(result, dict):
+                bridge_timing = result.get("bridgeTiming")
+                if isinstance(bridge_timing, dict):
+                    bridge_timing.setdefault("python_total_ms", ms_since(handler_started))
+                    bridge_timing.setdefault("steps", [])
+                else:
+                    result["bridgeTiming"] = {
+                        "python_total_ms": ms_since(handler_started),
+                        "steps": [],
+                    }
+            write_response({"id": req_id, "result": result, "error": None})
+        except Exception as exc:
+            logger.error("Handler error for %s: %s", method, traceback.format_exc())
+            write_response({"id": req_id, "result": None, "error": str(exc)})
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@maximem/synap-js-sdk",
+  "version": "0.1.1",
+  "description": "JavaScript wrapper around the Synap Python SDK",
+  "main": "src/index.js",
+  "types": "types/index.d.ts",
+  "type": "commonjs",
+  "bin": {
+    "synap-js-sdk": "bin/synap-js-sdk.js"
+  },
+  "files": [
+    "src",
+    "types",
+    "bridge/synap_bridge.py",
+    "bin",
+    "README.md",
+    ".env.example"
+  ],
+  "scripts": {
+    "setup": "node bin/synap-js-sdk.js setup",
+    "setup:ts": "node bin/synap-js-sdk.js setup-ts",
+    "check": "node -e \"const sdk=require('./src'); console.log(Object.keys(sdk));\""
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "synap",
+    "sdk",
+    "python",
+    "wrapper",
+    "bridge"
+  ],
+  "license": "MIT"
+}