maximem-synap-nemo-agent-toolkit 0.1.1__tar.gz

maximem_synap_nemo_agent_toolkit-0.1.1/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: maximem-synap-nemo-agent-toolkit
+Version: 0.1.1
+Summary: Synap memory plugin for NVIDIA NeMo Agent Toolkit (NAT)
+Author: Synap Team
+License-Expression: Apache-2.0
+Keywords: synap,memory,nemo,nvidia,nat,agents,ai
+Requires-Python: <3.14,>=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: maximem-synap>=0.2.0
+Requires-Dist: synap-integrations-common>=0.1.0
+Requires-Dist: nvidia-nat-core>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+
+# synap-nemo-agent-toolkit
+
+Synap memory plugin for **NVIDIA NeMo Agent Toolkit (NAT)**.
+
+Implements `nat.memory.interfaces.MemoryEditor` so that NAT workflows can
+use Synap as long-term memory out of the box — either programmatically,
+or via a single YAML line:
+
+```yaml
+memory:
+  synap:
+    _type: synap_memory
+    customer_id: "acme"          # optional scope
+    mode: "accurate"              # or "fast"
+```
+
+## Install
+
+```bash
+pip install synap-nemo-agent-toolkit
+```
+
+Depends on `maximem-synap>=0.2.0`, `synap-integrations-common>=0.1.0`,
+and `nvidia-nat-core>=1.0`.
+
+## Use (programmatic)
+
+```python
+from maximem_synap import MaximemSynapSDK
+from nat.memory.models import MemoryItem
+from synap_nemo_agent_toolkit import SynapMemoryEditor
+
+sdk = MaximemSynapSDK(api_key="...")
+await sdk.initialize()
+
+editor = SynapMemoryEditor(sdk=sdk, customer_id="acme", mode="accurate")
+
+# Write
+await editor.add_items([
+    MemoryItem(
+        user_id="alice",
+        memory="Prefers tea over coffee",
+        tags=["beverage", "preference"],
+    ),
+])
+
+# Read — user_id is required on every search
+hits = await editor.search("beverage preference", top_k=5, user_id="alice")
+for hit in hits:
+    print(hit.memory, hit.tags, hit.similarity_score)
+```
+
+## Use (YAML / NAT workflow)
+
+Set `SYNAP_API_KEY` (optionally `SYNAP_INSTANCE_ID`) in the environment
+and declare the memory provider in the workflow config:
+
+```yaml
+memory:
+  synap:
+    _type: synap_memory
+    customer_id: "acme"
+    mode: "accurate"
+    # Optional — falls back to SYNAP_API_KEY env if omitted
+    # api_key: "${SYNAP_API_KEY}"
+```
+
+NAT's plugin loader picks up `synap_memory` via the `nat.components`
+entry-point registered in this package's `pyproject.toml`.
+
+## Error policy
+
+| Operation       | Synap failure          | Why                                       |
+|-----------------|------------------------|-------------------------------------------|
+| `add_items`     | `SynapIntegrationError`| Writes must be observable                 |
+| `search`        | Returns `[]`           | A read blip must never crash an agent turn |
+| `remove_items`  | Warn once, no-op       | Synap has no public delete API            |
+
+Every write is tagged with an internal marker so `search` filters out
+non-NAT memories that happen to share the same user scope — the
+`MemoryItem` stream stays NAT-owned.
+
+## License
+
+Apache-2.0.

maximem_synap_nemo_agent_toolkit-0.1.1/README.md

@@ -0,0 +1,85 @@
+# synap-nemo-agent-toolkit
+
+Synap memory plugin for **NVIDIA NeMo Agent Toolkit (NAT)**.
+
+Implements `nat.memory.interfaces.MemoryEditor` so that NAT workflows can
+use Synap as long-term memory out of the box — either programmatically,
+or via a single YAML line:
+
+```yaml
+memory:
+  synap:
+    _type: synap_memory
+    customer_id: "acme"          # optional scope
+    mode: "accurate"              # or "fast"
+```
+
+## Install
+
+```bash
+pip install synap-nemo-agent-toolkit
+```
+
+Depends on `maximem-synap>=0.2.0`, `synap-integrations-common>=0.1.0`,
+and `nvidia-nat-core>=1.0`.
+
+## Use (programmatic)
+
+```python
+from maximem_synap import MaximemSynapSDK
+from nat.memory.models import MemoryItem
+from synap_nemo_agent_toolkit import SynapMemoryEditor
+
+sdk = MaximemSynapSDK(api_key="...")
+await sdk.initialize()
+
+editor = SynapMemoryEditor(sdk=sdk, customer_id="acme", mode="accurate")
+
+# Write
+await editor.add_items([
+    MemoryItem(
+        user_id="alice",
+        memory="Prefers tea over coffee",
+        tags=["beverage", "preference"],
+    ),
+])
+
+# Read — user_id is required on every search
+hits = await editor.search("beverage preference", top_k=5, user_id="alice")
+for hit in hits:
+    print(hit.memory, hit.tags, hit.similarity_score)
+```
+
+## Use (YAML / NAT workflow)
+
+Set `SYNAP_API_KEY` (optionally `SYNAP_INSTANCE_ID`) in the environment
+and declare the memory provider in the workflow config:
+
+```yaml
+memory:
+  synap:
+    _type: synap_memory
+    customer_id: "acme"
+    mode: "accurate"
+    # Optional — falls back to SYNAP_API_KEY env if omitted
+    # api_key: "${SYNAP_API_KEY}"
+```
+
+NAT's plugin loader picks up `synap_memory` via the `nat.components`
+entry-point registered in this package's `pyproject.toml`.
+
+## Error policy
+
+| Operation       | Synap failure          | Why                                       |
+|-----------------|------------------------|-------------------------------------------|
+| `add_items`     | `SynapIntegrationError`| Writes must be observable                 |
+| `search`        | Returns `[]`           | A read blip must never crash an agent turn |
+| `remove_items`  | Warn once, no-op       | Synap has no public delete API            |
+
+Every write is tagged with an internal marker so `search` filters out
+non-NAT memories that happen to share the same user scope — the
+`MemoryItem` stream stays NAT-owned.
+
+## License
+
+Apache-2.0.

maximem_synap_nemo_agent_toolkit-0.1.1/maximem_synap_nemo_agent_toolkit.egg-info/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: maximem-synap-nemo-agent-toolkit
+Version: 0.1.1
+Summary: Synap memory plugin for NVIDIA NeMo Agent Toolkit (NAT)
+Author: Synap Team
+License-Expression: Apache-2.0
+Keywords: synap,memory,nemo,nvidia,nat,agents,ai
+Requires-Python: <3.14,>=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: maximem-synap>=0.2.0
+Requires-Dist: synap-integrations-common>=0.1.0
+Requires-Dist: nvidia-nat-core>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+
+# synap-nemo-agent-toolkit
+
+Synap memory plugin for **NVIDIA NeMo Agent Toolkit (NAT)**.
+
+Implements `nat.memory.interfaces.MemoryEditor` so that NAT workflows can
+use Synap as long-term memory out of the box — either programmatically,
+or via a single YAML line:
+
+```yaml
+memory:
+  synap:
+    _type: synap_memory
+    customer_id: "acme"          # optional scope
+    mode: "accurate"              # or "fast"
+```
+
+## Install
+
+```bash
+pip install synap-nemo-agent-toolkit
+```
+
+Depends on `maximem-synap>=0.2.0`, `synap-integrations-common>=0.1.0`,
+and `nvidia-nat-core>=1.0`.
+
+## Use (programmatic)
+
+```python
+from maximem_synap import MaximemSynapSDK
+from nat.memory.models import MemoryItem
+from synap_nemo_agent_toolkit import SynapMemoryEditor
+
+sdk = MaximemSynapSDK(api_key="...")
+await sdk.initialize()
+
+editor = SynapMemoryEditor(sdk=sdk, customer_id="acme", mode="accurate")
+
+# Write
+await editor.add_items([
+    MemoryItem(
+        user_id="alice",
+        memory="Prefers tea over coffee",
+        tags=["beverage", "preference"],
+    ),
+])
+
+# Read — user_id is required on every search
+hits = await editor.search("beverage preference", top_k=5, user_id="alice")
+for hit in hits:
+    print(hit.memory, hit.tags, hit.similarity_score)
+```
+
+## Use (YAML / NAT workflow)
+
+Set `SYNAP_API_KEY` (optionally `SYNAP_INSTANCE_ID`) in the environment
+and declare the memory provider in the workflow config:
+
+```yaml
+memory:
+  synap:
+    _type: synap_memory
+    customer_id: "acme"
+    mode: "accurate"
+    # Optional — falls back to SYNAP_API_KEY env if omitted
+    # api_key: "${SYNAP_API_KEY}"
+```
+
+NAT's plugin loader picks up `synap_memory` via the `nat.components`
+entry-point registered in this package's `pyproject.toml`.
+
+## Error policy
+
+| Operation       | Synap failure          | Why                                       |
+|-----------------|------------------------|-------------------------------------------|
+| `add_items`     | `SynapIntegrationError`| Writes must be observable                 |
+| `search`        | Returns `[]`           | A read blip must never crash an agent turn |
+| `remove_items`  | Warn once, no-op       | Synap has no public delete API            |
+
+Every write is tagged with an internal marker so `search` filters out
+non-NAT memories that happen to share the same user scope — the
+`MemoryItem` stream stays NAT-owned.
+
+## License
+
+Apache-2.0.

maximem_synap_nemo_agent_toolkit-0.1.1/maximem_synap_nemo_agent_toolkit.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+maximem_synap_nemo_agent_toolkit.egg-info/PKG-INFO
+maximem_synap_nemo_agent_toolkit.egg-info/SOURCES.txt
+maximem_synap_nemo_agent_toolkit.egg-info/dependency_links.txt
+maximem_synap_nemo_agent_toolkit.egg-info/entry_points.txt
+maximem_synap_nemo_agent_toolkit.egg-info/requires.txt
+maximem_synap_nemo_agent_toolkit.egg-info/top_level.txt
+synap_nemo_agent_toolkit/__init__.py
+synap_nemo_agent_toolkit/editor.py
+synap_nemo_agent_toolkit/plugin.py
+synap_nemo_agent_toolkit/register.py

maximem_synap_nemo_agent_toolkit-0.1.1/maximem_synap_nemo_agent_toolkit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

maximem_synap_nemo_agent_toolkit-0.1.1/maximem_synap_nemo_agent_toolkit.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[nat.components]
+synap_memory = synap_nemo_agent_toolkit.register

maximem_synap_nemo_agent_toolkit-0.1.1/maximem_synap_nemo_agent_toolkit.egg-info/requires.txt

@@ -0,0 +1,7 @@
+maximem-synap>=0.2.0
+synap-integrations-common>=0.1.0
+nvidia-nat-core>=1.0
+
+[dev]
+pytest>=7.0
+pytest-asyncio>=0.21

maximem_synap_nemo_agent_toolkit-0.1.1/maximem_synap_nemo_agent_toolkit.egg-info/top_level.txt

@@ -0,0 +1 @@
+synap_nemo_agent_toolkit

maximem_synap_nemo_agent_toolkit-0.1.1/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "maximem-synap-nemo-agent-toolkit"
+version = "0.1.1"
+description = "Synap memory plugin for NVIDIA NeMo Agent Toolkit (NAT)"
+readme = "README.md"
+requires-python = ">=3.11,<3.14"
+license = "Apache-2.0"
+authors = [
+    {name = "Synap Team"}
+]
+keywords = ["synap", "memory", "nemo", "nvidia", "nat", "agents", "ai"]
+
+dependencies = [
+    "maximem-synap>=0.2.0",
+    "synap-integrations-common>=0.1.0",
+    "nvidia-nat-core>=1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+]
+
+[project.entry-points."nat.components"]
+synap_memory = "synap_nemo_agent_toolkit.register"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["synap_nemo_agent_toolkit*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

maximem_synap_nemo_agent_toolkit-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

maximem_synap_nemo_agent_toolkit-0.1.1/synap_nemo_agent_toolkit/__init__.py

@@ -0,0 +1,27 @@
+"""Synap memory plugin for NVIDIA NeMo Agent Toolkit (NAT).
+
+Two integration paths:
+
+1. **Programmatic** — construct a :class:`MaximemSynapSDK` yourself and
+   wrap it in :class:`SynapMemoryEditor` to plug into any NAT surface
+   that expects a :class:`nat.memory.interfaces.MemoryEditor`.
+
+2. **YAML-wired** — declare ``_type: synap_memory`` in a NAT workflow's
+   ``memory:`` block. NAT's plugin loader imports
+   :mod:`synap_nemo_agent_toolkit.register` via the ``nat.components``
+   entry-point, which pulls in :class:`SynapMemoryClientConfig` and the
+   ``@register_memory`` factory.
+
+Error policy (matches every other Synap integration):
+
+- Reads (``search``) degrade gracefully — a Synap blip returns ``[]``
+  rather than crashing the agent turn.
+- Writes (``add_items``) surface as
+  :class:`synap_integrations_common.SynapIntegrationError`.
+- Deletes (``remove_items``) warn once and no-op — Synap has no public
+  delete API.
+"""
+
+from synap_nemo_agent_toolkit.editor import SynapMemoryEditor
+
+__all__ = ["SynapMemoryEditor"]

maximem_synap_nemo_agent_toolkit-0.1.1/synap_nemo_agent_toolkit/editor.py

@@ -0,0 +1,219 @@
+"""SynapMemoryEditor — NAT :class:`MemoryEditor` implementation backed by Synap.
+
+NAT's memory contract is three async methods on
+:class:`nat.memory.interfaces.MemoryEditor`:
+
+- ``add_items(items)``        → writes
+- ``search(query, top_k, **kw)`` → reads
+- ``remove_items(**kw)``      → deletes (no-op on Synap; see below)
+
+Error policy mirrors every other Synap integration:
+
+- **Writes** (``add_items``): failures surface as
+  :class:`SynapIntegrationError` so ingestion outages are observable.
+- **Reads** (``search``): failures degrade gracefully — log at ERROR and
+  return ``[]``. A Synap blip should never crash an agent turn.
+- **Deletes** (``remove_items``): Synap has no public delete API. We warn
+  once and no-op, same contract used by synap-crewai and synap-agno.
+
+We tag every Synap memory we create with a marker key so that future
+NAT searches can distinguish NAT-originated records from other
+memories written to the same user's scope.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any, Optional
+
+from maximem_synap import MaximemSynapSDK
+from nat.memory.interfaces import MemoryEditor
+from nat.memory.models import MemoryItem
+
+from synap_integrations_common import wrap_sdk_errors_async
+
+logger = logging.getLogger(__name__)
+
+# Metadata marker — every Synap memory NAT creates carries this, so we
+# can filter them back out on search and avoid leaking non-NAT facts
+# into NAT's MemoryItem stream.
+_MARKER = "nat_memory_item"
+
+
+class SynapMemoryEditor(MemoryEditor):
+    """Synap-backed NAT :class:`MemoryEditor`.
+
+    Args:
+        sdk: Configured :class:`MaximemSynapSDK`.
+        customer_id: Optional customer/org scope. Empty string means
+            customer-less (forwarded to the SDK as ``None``).
+        mode: Synap fetch mode — ``"accurate"`` (default) or ``"fast"``.
+        document_type: ``document_type`` stamped on every ``memories.create``
+            write. Defaults to ``"ai-chat-conversation"`` to match the
+            other integrations.
+    """
+
+    def __init__(
+        self,
+        sdk: MaximemSynapSDK,
+        *,
+        customer_id: str = "",
+        mode: str = "accurate",
+        document_type: str = "ai-chat-conversation",
+    ) -> None:
+        if sdk is None:
+            raise ValueError("SynapMemoryEditor requires a non-None sdk")
+        self.sdk = sdk
+        self.customer_id = customer_id
+        self.mode = mode
+        self.document_type = document_type
+        self._delete_warned = False
+
+    # ── writes ─────────────────────────────────────────────────────────────
+
+    async def add_items(self, items: list[MemoryItem]) -> None:
+        """Insert one ``memories.create`` per ``MemoryItem``.
+
+        Each item's ``user_id`` is required (Synap memory is user-scoped).
+        We write ``item.memory`` when present, otherwise fall back to a
+        joined string of the conversation's ``content`` fields — NAT's
+        Mem0 path accepts conversation-only items, so we must too.
+        """
+        if not items:
+            return
+
+        async def _one(item: MemoryItem) -> None:
+            if not item.user_id:
+                raise ValueError("MemoryItem.user_id is required for Synap writes")
+            document = item.memory or _conversation_to_text(item.conversation)
+            if not document:
+                # Nothing worth recording — skip rather than writing empty
+                # documents that pollute fetch results.
+                return
+            metadata: dict[str, Any] = {
+                _MARKER: True,
+                "tags": list(item.tags or []),
+                **(item.metadata or {}),
+            }
+            if item.conversation:
+                metadata["conversation"] = list(item.conversation)
+
+            async with wrap_sdk_errors_async(
+                "nemo_agent_toolkit.add_items",
+                logger,
+                user_id=item.user_id,
+                tags=item.tags,
+            ):
+                await self.sdk.memories.create(
+                    document=document,
+                    user_id=item.user_id,
+                    customer_id=self.customer_id or "",
+                    document_type=self.document_type,
+                    metadata=metadata,
+                )
+
+        # Fan out concurrently — mirrors Mem0Editor's asyncio.gather shape
+        # so throughput on bulk add_items matches the reference plugin.
+        await asyncio.gather(*(_one(item) for item in items))
+
+    # ── reads ──────────────────────────────────────────────────────────────
+
+    async def search(self, query: str, top_k: int = 5, **kwargs) -> list[MemoryItem]:
+        """Query Synap and map hits to :class:`MemoryItem`.
+
+        The ``user_id`` kwarg is required — Synap memory is user-scoped.
+        On SDK failure we log and return an empty list so the agent turn
+        can continue without long-term memory.
+        """
+        user_id = kwargs.pop("user_id", None)
+        if not user_id:
+            # Mem0Editor also requires user_id in kwargs; be consistent.
+            raise ValueError(
+                "SynapMemoryEditor.search requires user_id in kwargs"
+            )
+        customer_id = kwargs.pop("customer_id", None) or self.customer_id or None
+        include_conversation_context = bool(
+            kwargs.pop("include_conversation_context", False)
+        )
+        tag_filter = kwargs.pop("tag_filter", None)
+
+        try:
+            response = await self.sdk.fetch(
+                user_id=user_id,
+                customer_id=customer_id,
+                search_query=[query] if query else None,
+                max_results=max(int(top_k), 1),
+                mode=self.mode,
+                include_conversation_context=include_conversation_context,
+            )
+        except Exception as exc:  # noqa: BLE001 — read-side graceful degrade
+            logger.error(
+                "SynapMemoryEditor.search: sdk.fetch failed user_id=%s error=%s",
+                user_id, exc, exc_info=True,
+            )
+            return []
+
+        facts = list(getattr(response, "facts", None) or [])
+        items: list[MemoryItem] = []
+        for fact in facts:
+            # Synap does not echo back custom metadata written with
+            # memories.create(), so _MARKER-based filtering is not possible.
+            # All facts for the user/customer scope are returned as-is.
+            md = getattr(fact, "metadata", None) or {}
+            if tag_filter:
+                fact_tags = md.get("tags") or []
+                if not any(t in fact_tags for t in tag_filter):
+                    continue
+            items.append(_fact_to_memory_item(fact, user_id=user_id))
+        return items
+
+    # ── deletes (warn + no-op) ─────────────────────────────────────────────
+
+    async def remove_items(self, **kwargs) -> None:
+        """Warn once, then no-op — Synap has no public delete surface."""
+        if not self._delete_warned:
+            logger.warning(
+                "SynapMemoryEditor: Synap has no public delete API. "
+                "remove_items is a no-op. This warning fires once."
+            )
+            self._delete_warned = True
+
+
+# ── helpers ────────────────────────────────────────────────────────────────
+
+
+def _conversation_to_text(conversation: Optional[list[dict[str, str]]]) -> str:
+    if not conversation:
+        return ""
+    lines = []
+    for msg in conversation:
+        role = msg.get("role", "?")
+        content = msg.get("content", "")
+        if content:
+            lines.append(f"{role}: {content}")
+    return "\n".join(lines)
+
+
+def _fact_to_memory_item(fact: Any, *, user_id: str) -> MemoryItem:
+    md = getattr(fact, "metadata", None) or {}
+    tags = md.get("tags") or []
+    if not isinstance(tags, list):
+        tags = []
+    conversation = md.get("conversation")
+    if conversation is not None and not isinstance(conversation, list):
+        conversation = None
+    # Strip our internal marker + conversation copy so downstream consumers
+    # don't see implementation detail in MemoryItem.metadata.
+    clean_metadata = {k: v for k, v in md.items() if k not in (_MARKER, "tags", "conversation")}
+    return MemoryItem(
+        conversation=conversation,
+        user_id=user_id,
+        memory=getattr(fact, "content", None) or None,
+        tags=list(tags),
+        metadata=clean_metadata,
+        similarity_score=getattr(fact, "confidence", None),
+    )
+
+
+__all__ = ["SynapMemoryEditor"]

maximem_synap_nemo_agent_toolkit-0.1.1/synap_nemo_agent_toolkit/plugin.py

@@ -0,0 +1,108 @@
+"""NAT ``register_memory`` factory for YAML-wired Synap memory.
+
+Drop ``_type: synap_memory`` into a NAT workflow's ``memory:`` block and
+the toolkit will construct a :class:`SynapMemoryEditor` from env vars
+(``SYNAP_API_KEY`` / optional ``SYNAP_INSTANCE_ID``). Config fields let
+operators override the scope, fetch mode, and document type from YAML.
+
+Example YAML::
+
+    memory:
+      synap:
+        _type: synap_memory
+        customer_id: "acme"
+        mode: "accurate"
+
+Programmatic callers that want to share a pre-constructed SDK should
+instantiate :class:`SynapMemoryEditor` directly instead.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Optional
+
+from pydantic import Field
+
+from nat.builder.builder import Builder
+from nat.cli.register_workflow import register_memory
+from nat.data_models.common import OptionalSecretStr, get_secret_value
+from nat.data_models.memory import MemoryBaseConfig
+
+from maximem_synap import MaximemSynapSDK
+
+from synap_nemo_agent_toolkit.editor import SynapMemoryEditor
+
+logger = logging.getLogger(__name__)
+
+
+class SynapMemoryClientConfig(MemoryBaseConfig, name="synap_memory"):
+    """YAML-wired config for the Synap memory provider."""
+
+    customer_id: str = Field(
+        default="",
+        description="Optional customer/org scope. Empty means customer-less.",
+    )
+    mode: str = Field(
+        default="accurate",
+        description='Synap fetch mode: "accurate" or "fast".',
+    )
+    document_type: str = Field(
+        default="ai-chat-conversation",
+        description="document_type stamped on every Synap memories.create write.",
+    )
+    api_key: OptionalSecretStr = Field(
+        default=None,
+        description=(
+            "Synap API key. When omitted, falls back to SYNAP_API_KEY env var."
+        ),
+    )
+    instance_id: str = Field(
+        default="",
+        description=(
+            "Optional Synap instance ID. When empty the SDK resolves it from "
+            "the API key via /auth/whoami. Falls back to SYNAP_INSTANCE_ID env."
+        ),
+    )
+
+
+@register_memory(config_type=SynapMemoryClientConfig)
+async def synap_memory_client(config: SynapMemoryClientConfig, builder: Builder):
+    """Construct + initialize a Synap SDK, yield a :class:`SynapMemoryEditor`."""
+    api_key: Optional[str] = get_secret_value(config.api_key) or os.environ.get(
+        "SYNAP_API_KEY"
+    )
+    if api_key is None:
+        raise RuntimeError(
+            "Synap API key is not set. Provide it via SynapMemoryClientConfig.api_key "
+            "or the SYNAP_API_KEY environment variable."
+        )
+
+    sdk = MaximemSynapSDK(
+        instance_id=config.instance_id or os.environ.get("SYNAP_INSTANCE_ID", ""),
+        api_key=api_key,
+        _force_new=True,
+    )
+    await sdk.initialize()
+
+    editor = SynapMemoryEditor(
+        sdk=sdk,
+        customer_id=config.customer_id,
+        mode=config.mode,
+        document_type=config.document_type,
+    )
+    try:
+        yield editor
+    finally:
+        close = getattr(sdk, "close", None)
+        if close is not None:
+            try:
+                await close()
+            except Exception:  # noqa: BLE001 — teardown must not mask workflow errors
+                logger.exception(
+                    "synap_memory_client: SDK teardown raised (suppressing)"
+                )
+
+
+__all__ = ["SynapMemoryClientConfig", "synap_memory_client"]

maximem_synap_nemo_agent_toolkit-0.1.1/synap_nemo_agent_toolkit/register.py

@@ -0,0 +1,13 @@
+"""NAT plugin entry point.
+
+Importing this module has the side effect of registering
+:class:`SynapMemoryClientConfig` + the ``synap_memory`` YAML ``_type``
+with NAT's :class:`GlobalTypeRegistry`. Wired via the ``nat.components``
+entry-point in ``pyproject.toml`` so NAT picks it up automatically on
+workflow load.
+"""
+
+# flake8: noqa — side-effectful import; don't remove
+# isort:skip_file
+
+from . import plugin  # noqa: F401 — registers @register_memory