maximem-synap-haystack 0.1.1__py3-none-any.whl

maximem_synap_haystack-0.1.1.dist-info/METADATA

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: maximem-synap-haystack
+Version: 0.1.1
+Summary: Synap memory integration for Haystack
+License-Expression: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: maximem-synap>=0.2.0
+Requires-Dist: synap-integrations-common>=0.1.0
+Requires-Dist: haystack-ai>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"

maximem_synap_haystack-0.1.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+synap_haystack/__init__.py,sha256=Nnd-c_ki2ZLu3ohGPBFHYc3s3o2am2TybhVkG0_IEcI,201
+synap_haystack/retriever.py,sha256=CNjLTbSt6EPBNVWMLTa_o8wV9e9F8HRkVwKFoF_bJXM,3529
+synap_haystack/writer.py,sha256=4Dlypnb7aklpBrz6uGlCLOSGA-zE3rwn3I8W6BQNCTk,4784
+maximem_synap_haystack-0.1.1.dist-info/METADATA,sha256=Ac3hVqhJ9s3fKjNOXN9PxMxJQiklW7gToLwkAl_MKZA,399
+maximem_synap_haystack-0.1.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+maximem_synap_haystack-0.1.1.dist-info/top_level.txt,sha256=0Kv9DHCP1HE400j0_1FSJgUFTDyp1B8LdTF02mJFrKs,15
+maximem_synap_haystack-0.1.1.dist-info/RECORD,,

maximem_synap_haystack-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

maximem_synap_haystack-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+synap_haystack

synap_haystack/__init__.py

@@ -0,0 +1,6 @@
+"""Synap memory integration for Haystack."""
+
+from synap_haystack.retriever import SynapRetriever
+from synap_haystack.writer import SynapMemoryWriter
+
+__all__ = ["SynapRetriever", "SynapMemoryWriter"]

synap_haystack/retriever.py

@@ -0,0 +1,107 @@
+"""Synap retriever component for Haystack pipelines.
+
+A Haystack @component that retrieves memory context from Synap
+and returns it as a list of Haystack Documents.
+"""
+
+import logging
+from typing import Dict, List, Optional
+
+from haystack import Document, component
+
+from maximem_synap import MaximemSynapSDK
+from synap_integrations_common import run_async, wrap_sdk_errors_async
+
+logger = logging.getLogger(__name__)
+
+
+@component
+class SynapRetriever:
+    """Haystack component that retrieves memory from Synap.
+
+    Example::
+
+        retriever = SynapRetriever(sdk=sdk, user_id="u1")
+        pipeline.add_component("memory", retriever)
+    """
+
+    def __init__(
+        self,
+        sdk: MaximemSynapSDK,
+        user_id: str,
+        customer_id: str = "",
+        conversation_id: Optional[str] = None,
+        mode: str = "accurate",
+        max_results: int = 20,
+    ):
+        if sdk is None:
+            raise ValueError("SynapRetriever requires a non-None sdk")
+        if not user_id:
+            raise ValueError("SynapRetriever requires a non-empty user_id")
+
+        self.sdk = sdk
+        self.user_id = user_id
+        self.customer_id = customer_id
+        self.conversation_id = conversation_id
+        self.mode = mode
+        self.max_results = max_results
+
+    @component.output_types(documents=List[Document])
+    def run(self, query: str) -> Dict[str, List[Document]]:
+        return run_async(self._arun(query))
+
+    async def _arun(self, query: str) -> Dict[str, List[Document]]:
+        async with wrap_sdk_errors_async(
+            "haystack.SynapRetriever.run",
+            logger,
+            user_id=self.user_id,
+            query_len=len(query),
+        ):
+            response = await self.sdk.fetch(
+                conversation_id=self.conversation_id,
+                user_id=self.user_id,
+                customer_id=self.customer_id or None,
+                search_query=[query],
+                max_results=self.max_results,
+                mode=self.mode,
+                include_conversation_context=False,
+            )
+
+        docs: List[Document] = []
+
+        for fact in response.facts:
+            docs.append(Document(
+                content=fact.content,
+                meta={"type": "fact", "id": fact.id, "confidence": fact.confidence,
+                      "scope": response.scope_map.get(fact.id, "")},
+            ))
+
+        for pref in response.preferences:
+            docs.append(Document(
+                content=pref.content,
+                meta={"type": "preference", "id": pref.id, "strength": pref.strength,
+                      "scope": response.scope_map.get(pref.id, "")},
+            ))
+
+        for ep in response.episodes:
+            docs.append(Document(
+                content=ep.summary,
+                meta={"type": "episode", "id": ep.id, "significance": ep.significance,
+                      "scope": response.scope_map.get(ep.id, "")},
+            ))
+
+        for em in response.emotions:
+            docs.append(Document(
+                content=f"{em.emotion_type}: {em.context}",
+                meta={"type": "emotion", "id": em.id, "intensity": em.intensity,
+                      "scope": response.scope_map.get(em.id, "")},
+            ))
+
+        for te in response.temporal_events:
+            docs.append(Document(
+                content=te.content,
+                meta={"type": "temporal_event", "id": te.id,
+                      "scope": response.scope_map.get(te.id, "")},
+            ))
+
+        return {"documents": docs}

synap_haystack/writer.py

@@ -0,0 +1,139 @@
+"""Synap memory writer component for Haystack pipelines.
+
+Records conversation messages to Synap for server-side extraction.
+
+Previously this component caught every ingestion exception and demoted
+it to a ``warning`` log line, then reported whatever happened to succeed
+via ``written_count``. Hidden ingestion failures are dangerous: a
+Haystack pipeline that looks green is not the same as a pipeline whose
+memory ingestion actually worked.
+
+New semantics:
+
+- Track ``written_count`` and ``failed_count`` separately and expose
+  both as component outputs, so downstream components can branch on
+  partial failures.
+- Also emit ``first_error`` (string) when at least one document fails,
+  so operators can see *what* went wrong without grepping logs.
+- If **every** document fails, raise :class:`SynapIntegrationError`.
+  A 100% failure rate is not "partial" — it's a broken pipeline and
+  should stop.
+- Per-document failures are logged at ``ERROR`` (not ``WARNING``) with
+  structured context.
+- Documents with an unrecognized role are skipped and surfaced via
+  ``skipped_count``.
+"""
+
+import logging
+from typing import Dict, List, Optional
+
+from haystack import Document, component
+
+from maximem_synap import MaximemSynapSDK
+from synap_integrations_common import SynapIntegrationError, run_async
+
+logger = logging.getLogger(__name__)
+
+_VALID_ROLES = frozenset(("user", "assistant"))
+
+
+@component
+class SynapMemoryWriter:
+    """Haystack component that writes conversation turns to Synap.
+
+    Accepts Documents where content is the message text and
+    meta["role"] is "user" or "assistant".
+
+    Example::
+
+        writer = SynapMemoryWriter(sdk=sdk, conversation_id="c1", user_id="u1")
+        pipeline.add_component("memory_writer", writer)
+    """
+
+    def __init__(
+        self,
+        sdk: MaximemSynapSDK,
+        conversation_id: str,
+        user_id: str,
+        customer_id: str = "",
+    ):
+        if sdk is None:
+            raise ValueError("SynapMemoryWriter requires a non-None sdk")
+        if not user_id:
+            raise ValueError("SynapMemoryWriter requires a non-empty user_id")
+        if not conversation_id:
+            raise ValueError(
+                "SynapMemoryWriter requires a non-empty conversation_id"
+            )
+
+        self.sdk = sdk
+        self.conversation_id = conversation_id
+        self.user_id = user_id
+        self.customer_id = customer_id
+
+    @component.output_types(
+        written_count=int,
+        failed_count=int,
+        skipped_count=int,
+        first_error=Optional[str],
+    )
+    def run(self, documents: List[Document]) -> Dict[str, object]:
+        return run_async(self._arun(documents))
+
+    async def _arun(self, documents: List[Document]) -> Dict[str, object]:
+        written = 0
+        failed = 0
+        skipped = 0
+        first_error: Optional[str] = None
+
+        for doc in documents:
+            role = doc.meta.get("role", "user")
+            if role not in _VALID_ROLES:
+                skipped += 1
+                logger.info(
+                    "SynapMemoryWriter: skipping document with unsupported "
+                    "role=%r (expected one of %s)",
+                    role,
+                    sorted(_VALID_ROLES),
+                )
+                continue
+
+            try:
+                await self.sdk.conversation.record_message(
+                    conversation_id=self.conversation_id,
+                    role=role,
+                    content=doc.content,
+                    user_id=self.user_id,
+                    customer_id=self.customer_id,
+                )
+                written += 1
+            except Exception as exc:  # noqa: BLE001 — boundary
+                failed += 1
+                logger.error(
+                    "SynapMemoryWriter: record_message failed "
+                    "conversation_id=%s role=%s error=%s",
+                    self.conversation_id,
+                    role,
+                    exc,
+                    exc_info=True,
+                )
+                if first_error is None:
+                    first_error = f"{type(exc).__name__}: {exc}"
+
+        processed = written + failed
+        if processed > 0 and written == 0:
+            # Every single attempt failed — this is a broken pipeline,
+            # not a partial result. Stop loudly.
+            raise SynapIntegrationError(
+                "haystack.SynapMemoryWriter.run",
+                f"all {failed} record_message attempts failed; "
+                f"first error: {first_error}",
+                {"conversation_id": self.conversation_id, "failed": failed},
+            )
+
+        return {
+            "written_count": written,
+            "failed_count": failed,
+            "skipped_count": skipped,
+            "first_error": first_error,
+        }