maximem-synap-haystack 0.2.1__tar.gz → 0.2.2__tar.gz

{maximem_synap_haystack-0.2.1 → maximem_synap_haystack-0.2.2}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: maximem-synap-haystack
-Version: 0.2.1
+Version: 0.2.2
 Summary: Synap memory integration for Haystack — SynapMemoryStore + retriever/writer components
 License-Expression: Apache-2.0
 Requires-Python: >=3.11
 Requires-Dist: maximem-synap>=0.5.3
-Requires-Dist: maximem-synap-integrations-common>=0.2.1
+Requires-Dist: maximem-synap-integrations-common>=0.2.3
 Requires-Dist: haystack-ai>=2.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"

{maximem_synap_haystack-0.2.1 → maximem_synap_haystack-0.2.2}/maximem_synap_haystack.egg-info/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: maximem-synap-haystack
-Version: 0.2.1
+Version: 0.2.2
 Summary: Synap memory integration for Haystack — SynapMemoryStore + retriever/writer components
 License-Expression: Apache-2.0
 Requires-Python: >=3.11
 Requires-Dist: maximem-synap>=0.5.3
-Requires-Dist: maximem-synap-integrations-common>=0.2.1
+Requires-Dist: maximem-synap-integrations-common>=0.2.3
 Requires-Dist: haystack-ai>=2.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"

{maximem_synap_haystack-0.2.1 → maximem_synap_haystack-0.2.2}/maximem_synap_haystack.egg-info/SOURCES.txt

@@ -5,10 +5,13 @@ maximem_synap_haystack.egg-info/dependency_links.txt
 maximem_synap_haystack.egg-info/requires.txt
 maximem_synap_haystack.egg-info/top_level.txt
 synap_haystack/__init__.py
+synap_haystack/hooks.py
 synap_haystack/retriever.py
 synap_haystack/short_term.py
 synap_haystack/store.py
 synap_haystack/writer.py
+tests/test_default_path.py
+tests/test_hooks.py
 tests/test_retriever.py
 tests/test_short_term.py
 tests/test_store.py

{maximem_synap_haystack-0.2.1 → maximem_synap_haystack-0.2.2}/maximem_synap_haystack.egg-info/requires.txt

@@ -1,5 +1,5 @@
 maximem-synap>=0.5.3
-maximem-synap-integrations-common>=0.2.1
+maximem-synap-integrations-common>=0.2.3
 haystack-ai>=2.0
 
 [dev]

{maximem_synap_haystack-0.2.1 → maximem_synap_haystack-0.2.2}/pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "maximem-synap-haystack"
-version = "0.2.1"
+version = "0.2.2"
 description = "Synap memory integration for Haystack — SynapMemoryStore + retriever/writer components"
 requires-python = ">=3.11"
 license = "Apache-2.0"
-dependencies = ["maximem-synap>=0.5.3", "maximem-synap-integrations-common>=0.2.1", "haystack-ai>=2.0"]
+dependencies = ["maximem-synap>=0.5.3", "maximem-synap-integrations-common>=0.2.3", "haystack-ai>=2.0"]
 
 [project.optional-dependencies]
 dev = ["pytest>=7.0", "pytest-asyncio>=0.21"]

{maximem_synap_haystack-0.2.1 → maximem_synap_haystack-0.2.2}/synap_haystack/__init__.py

@@ -5,12 +5,20 @@ Store-centric, matching the official ``mem0-haystack`` shape:
 - :class:`SynapMemoryStore` — the memory store (a plain object, not a component)
   that owns all Synap SDK interaction. ``add_memories`` / ``search_memories`` /
   ``search_memories_as_single_message`` / ``delete_*`` + ``to_dict`` / ``from_dict``.
+  It is also a Haystack ``ChatMessageStore`` (``write_messages`` /
+  ``retrieve_messages`` / ``count_messages``), so an experimental ``Agent`` takes it
+  as ``chat_message_store=`` and loads Synap's compaction and the turns after it
+  instead of a ten-message window. Turns are written on the gRPC stream, which
+  the first one opens (``SYNAP_AUTO_LISTEN=false`` turns that off).
 - :class:`SynapMemoryRetriever` — ``@component`` returning ``ChatMessage``s
   (Mem0-shaped chat read path).
 - :class:`SynapRetriever` — ``@component`` returning ``Document``s (RAG read path).
 - :class:`SynapMemoryWriter` — ``@component`` that records conversation turns.
-- :class:`SynapShortTermContext` — ``@component`` for the short-term conversation
-  context pipeline.
+- :class:`SynapHistoryHook` / :class:`SynapRecordHook` — hooks for haystack-ai 3's
+  ``Agent(hooks=...)``: Synap's compaction in place of the earlier turns
+  (``before_llm``) and the run recorded on the stream (``after_run``).
+- :class:`SynapShortTermContext` — ``@component`` emitting Synap's compaction of
+  the conversation for a prompt builder.
 
 The components accept a ready ``store=...`` or an ``sdk=...`` + scope kwargs.
 """
@@ -20,10 +28,17 @@ from synap_haystack.retriever import SynapMemoryRetriever, SynapRetriever
 from synap_haystack.writer import SynapMemoryWriter
 from synap_haystack.short_term import SynapShortTermContext
 
+try:  # needs haystack-ai 3's Agent hooks only at run time; importing is safe
+    from synap_haystack.hooks import SynapHistoryHook, SynapRecordHook
+except ImportError:  # pragma: no cover
+    SynapHistoryHook = SynapRecordHook = None  # type: ignore[assignment,misc]
+
 __all__ = [
     "SynapMemoryStore",
     "SynapMemoryRetriever",
     "SynapRetriever",
     "SynapMemoryWriter",
     "SynapShortTermContext",
+    "SynapHistoryHook",
+    "SynapRecordHook",
 ]

maximem_synap_haystack-0.2.2/synap_haystack/hooks.py

@@ -0,0 +1,127 @@
+"""Synap's compaction in place of a Haystack agent's earlier turns, via hooks.
+
+Haystack 3's ``Agent`` has no chat-message store. It takes ``hooks``: objects run
+at points in its loop that mutate the live ``State`` in place. That is where its
+own compaction lives (``haystack.hooks.compaction.CompactionHook``), and it is
+where Synap's goes:
+
+- :class:`SynapHistoryHook` on ``before_llm``: once Synap has compacted the
+  conversation, every turn before the current one in ``state["messages"]`` is
+  replaced by Synap's compaction (a system message) and the turns after it.
+  Until then, and whenever Synap cannot answer, the messages are left alone.
+  The agent's own compaction hooks can stay installed: with a short history they
+  do not fire, and they are the fallback.
+- :class:`SynapRecordHook` on ``after_run``: records the run's turns on Synap's
+  gRPC stream (opened by the first one) and reports its tool calls, results and
+  reasoning, through :meth:`SynapMemoryStore.write_messages`.
+
+::
+
+    store = SynapMemoryStore(sdk, user_id="alice")
+    agent = Agent(
+        chat_generator=...,
+        hooks={
+            "before_llm": [SynapHistoryHook(store, "conv-1")],
+            "after_run": [SynapRecordHook(store, "conv-1")],
+        },
+    )
+
+On haystack-ai 2.x use ``SynapMemoryStore`` as the experimental ``Agent``'s
+``chat_message_store`` instead; this module needs the 3.x ``Agent.hooks``.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict
+
+from haystack.core.serialization import default_from_dict, default_to_dict
+from haystack.dataclasses import ChatMessage, ChatRole
+
+from synap_integrations_common import (
+    fetch_compacted_history,
+    run_async,
+    splice_history,
+)
+
+from synap_haystack.store import RECORDED_KEY, SynapMemoryStore
+
+logger = logging.getLogger(__name__)
+
+_ROLES = {ChatRole.USER: "user", ChatRole.ASSISTANT: "assistant", ChatRole.SYSTEM: "system"}
+
+
+def _role_of(message: ChatMessage) -> str:
+    return _ROLES.get(message.role, "other")
+
+
+def _text_of(message: ChatMessage) -> str:
+    return message.text or ""
+
+
+def _replace(_current: Any, new: Any) -> Any:
+    return new
+
+
+class _StoreHook:
+    """Shared construction and serialization for the two hooks."""
+
+    def __init__(self, store: SynapMemoryStore, chat_history_id: str) -> None:
+        if store is None:
+            raise ValueError(f"{type(self).__name__} requires a store")
+        if not chat_history_id or not str(chat_history_id).strip():
+            raise ValueError(f"{type(self).__name__} requires a non-empty chat_history_id")
+        self.store = store
+        self.chat_history_id = chat_history_id
+
+    def to_dict(self) -> Dict[str, Any]:
+        return default_to_dict(self, store=self.store.to_dict(), chat_history_id=self.chat_history_id)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "_StoreHook":
+        init = dict(data.get("init_parameters", {}))
+        init["store"] = SynapMemoryStore.from_dict(init["store"])
+        return default_from_dict(cls, {**data, "init_parameters": init})
+
+
+class SynapHistoryHook(_StoreHook):
+    """``before_llm`` hook: Synap's compaction in place of the earlier turns."""
+
+    def run(self, state: Any) -> None:
+        run_async(self.run_async(state))
+
+    async def run_async(self, state: Any) -> None:
+        messages = list(state.get("messages") or [])
+        if not any(_role_of(m) == "user" for m in messages):
+            return
+        history = await fetch_compacted_history(self.store.sdk, self.chat_history_id)
+        if history is None:
+            return
+
+        def make(role: str, text: str) -> ChatMessage:
+            if role == "system":
+                return ChatMessage.from_system(text)
+            meta = {RECORDED_KEY: self.chat_history_id}  # Synap already has it
+            return (ChatMessage.from_assistant(text, meta=meta) if role == "assistant"
+                    else ChatMessage.from_user(text, meta=meta))
+
+        try:
+            spliced = splice_history(messages, history, role_of=_role_of, text_of=_text_of,
+                                     make_message=make)
+        except Exception:  # noqa: BLE001 — the agent's own messages still stand
+            logger.warning("synap: could not splice the compacted history", exc_info=True)
+            return
+        state.set("messages", spliced, handler_override=_replace)
+
+
+class SynapRecordHook(_StoreHook):
+    """``after_run`` hook: record the run on Synap, each message once."""
+
+    def run(self, state: Any) -> None:
+        self.store.write_messages(self.chat_history_id, list(state.get("messages") or []))
+
+    async def run_async(self, state: Any) -> None:
+        await self.store.awrite_messages(self.chat_history_id, list(state.get("messages") or []))
+
+
+__all__ = ["SynapHistoryHook", "SynapRecordHook"]

{maximem_synap_haystack-0.2.1 → maximem_synap_haystack-0.2.2}/synap_haystack/short_term.py

@@ -5,8 +5,14 @@ Mirrors the LangGraph template, adapted to Haystack's
 ``sdk.conversation.context.get_context_for_prompt`` (cache-first behind
 ``SYNAP_SDK_ST_AUTHORITATIVE``).
 
-Exposes :class:`SynapShortTermContext` — a component that emits the
-formatted Synap short-term context string on its ``synap_st`` output.
+Exposes :class:`SynapShortTermContext` — a component that emits Synap's
+compaction of the conversation, as a string, on its ``synap_st`` output. It is
+the compaction only: the turns after it are the ones your pipeline already
+passes (a chat history, an agent's messages), and Synap's ``formatted_context``
+carries them too, so a block built from it showed every recent turn twice. Until
+the conversation has been compacted the block is empty. (An agent should use
+``SynapMemoryStore`` as its ``chat_message_store`` instead, which replaces the
+history it loads.)
 Wire it before your prompt builder, then reference ``{synap_st}`` (or
 your prompt builder's variable name) in the template. The component
 re-fetches on every pipeline run, so ST stays fresh.
@@ -18,7 +24,7 @@ Quality contract identical to the LangGraph adapter:
   raise abort the whole pipeline. The default ``on_error="fallback"``
   emits the bare user system text (or empty string) on SDK failure,
   with an ERROR log. ``on_error="raise"`` surfaces failures.
-- Empty ST is a no-op — never wipes the user's system text.
+- No compaction yet is a no-op — never wipes the user's system text.
 """
 
 from __future__ import annotations
@@ -141,8 +147,14 @@ class SynapShortTermContext:
                     conversation_id=self.conversation_id,
                     style=self.style,
                 )
-            if getattr(response, "available", False):
-                st_block = (getattr(response, "formatted_context", None) or "").strip()
+            compaction = getattr(response, "context_block", None)
+            if getattr(response, "available", True) is not False and isinstance(compaction, str) \
+                    and compaction.strip():
+                parts = [compaction.strip()]
+                found = getattr(response, "history_block", None)
+                if isinstance(found, str) and found.strip():
+                    parts.append(found.strip())
+                st_block = "\n\n".join(parts)
         except SynapIntegrationError:
             if self.on_error == "raise":
                 raise

{maximem_synap_haystack-0.2.1 → maximem_synap_haystack-0.2.2}/synap_haystack/store.py

@@ -7,14 +7,30 @@ is a plain object that owns *all* Synap SDK interaction, and the retriever/write
 shape ``synap_langgraph.SynapStore`` follows for LangGraph — the store is the
 center of gravity; everything else delegates to it.
 
-Why a memory store (and not the generic ``ChatMessageStore`` protocol)? Memory —
-unlike a verbatim chat log — is *semantic and cross-conversation*: writes are
-extracted/synthesised server-side, reads are query-driven. So this implements
-Mem0's ``add_memories`` / ``search_memories`` contract rather than Haystack's
-recency-based ``ChatMessageStore`` protocol (``write_messages`` /
-``retrieve_messages`` keyed by ``chat_history_id``), which is designed for
-verbatim turn storage. This is the same reason Mem0 deliberately did not conform
-to ``ChatMessageStore``.
+It implements two contracts, because Haystack's experimental ``Agent`` has two
+slots and Synap fits both:
+
+- Mem0's ``add_memories`` / ``search_memories`` (the ``memory_store=`` slot):
+  semantic and cross-conversation, writes extracted server-side, reads
+  query-driven.
+- Haystack's ``ChatMessageStore`` protocol (the ``chat_message_store=`` slot):
+  ``write_messages`` / ``retrieve_messages`` / ``count_messages`` /
+  ``delete_*``, with ``chat_history_id`` as the Synap conversation id. This is the
+  one place a Haystack agent's history is decided: the agent's
+  ``ChatMessageRetriever`` asks for the last ten messages and puts them before
+  the new ones. Here that history is Synap's compaction of the conversation (a
+  system message) followed by the turns after it, so once Synap has compacted,
+  the model sees the compaction instead of a ten-message window. Haystack has no
+  compaction of its own to leave in place; the window is the fallback when Synap
+  has nothing yet. Give the agent the store in both slots if you want both::
+
+      store = SynapMemoryStore(sdk, user_id="alice", conversation_id="conv-1")
+      agent = Agent(chat_generator=..., chat_message_store=store, memory_store=store)
+      agent.run(messages=[...], chat_message_store_kwargs={"chat_history_id": "conv-1"})
+
+  The agent hands both stores the same messages, history included, so a message
+  this store has recorded or retrieved carries ``meta["synap_recorded"]`` and is
+  never recorded or reported a second time.
 
 Scope:
 
@@ -52,7 +68,8 @@ tool message, and ``ReasoningContent(reasoning_text)`` on either.
 it as ``origin.id``, which is what ties a call to its result.
 
 Only the turns are also memory, and they follow the one rule that matters:
-**stream first, REST only as a fallback, never both**. The server persists
+**on the gRPC stream (opened by the first event, no ``listen()`` call needed;
+``SYNAP_AUTO_LISTEN=false`` turns that off), REST only as a fallback, never both**. The server persists
 ``user_message`` and ``assistant_message`` straight off the stream
 (``grpc/servicer.py``), so a ``record_message`` on top of a delivered stream
 event writes the turn twice and extracts it twice. Tool calls, tool results
@@ -76,6 +93,7 @@ from haystack.dataclasses import ChatMessage
 
 from maximem_synap import MaximemSynapSDK
 from synap_integrations_common import SynapIntegrationError, run_async
+from synap_integrations_common.history import HISTORY_CLOSE, HISTORY_OPEN
 from synap_integrations_common.stream_events import (
     report_reasoning,
     report_tool_call,
@@ -89,6 +107,9 @@ logger = logging.getLogger(__name__)
 # only user/assistant turns carry signal; system/tool messages are skipped.
 _WRITE_ROLES = frozenset(("user", "assistant"))
 
+# Set in a message's meta once this store has recorded or retrieved it.
+RECORDED_KEY = "synap_recorded"
+
 
 class SynapMemoryStore:
     """Haystack-native memory store backed by Synap semantic memory.
@@ -203,6 +224,13 @@ class SynapMemoryStore:
         for msg in messages:
             role = _role_of(msg)
 
+            # Recorded or retrieved by this store already: an agent hands the
+            # same messages (history included) to its chat store and its memory
+            # store, and to either again on the next run.
+            if _is_recorded(msg):
+                results.append({"role": role, "status": "skipped", "reason": "already recorded"})
+                continue
+
             # ── the live stream ──────────────────────────────────────────
             # Reported for every role, including the ones that are never
             # written as memory: a tool result is not a turn, but it is
@@ -218,6 +246,22 @@ class SynapMemoryStore:
                     role,
                     sorted(_WRITE_ROLES),
                 )
+                if role != "system":
+                    _mark_recorded(msg, conv_id)  # its tool results went out above
+                continue
+
+            text = msg.text or ""
+            calls = getattr(msg, "tool_calls", None)
+            if not text.strip() or (role == "assistant" and calls):
+                # A tool call lap is not an answer: its words (when it has any)
+                # narrate a step, and the anticipation event for "a turn ended"
+                # is the final reply. With no words at all it used to go out as
+                # an empty turn, which the stream dropped and REST refused, so
+                # the message counted as a failed write.
+                results.append({"role": role, "status": "skipped",
+                                "reason": "tool call" if text.strip() else "no text"})
+                await self._report_tool_calls(msg, ids)
+                _mark_recorded(msg, conv_id)
                 continue
 
             # Stream first, REST only as a fallback, never both.
@@ -230,7 +274,7 @@ class SynapMemoryStore:
             # fallback and lose it silently. REST fails loudly instead, which
             # is what this store did before there was a stream at all.
             if uid and await report_turn(
-                self.sdk, role=role, content=msg.text or "", **ids
+                self.sdk, role=role, content=text, **ids
             ):
                 written += 1
                 results.append({
@@ -244,7 +288,7 @@ class SynapMemoryStore:
                     resp = await self.sdk.conversation.record_message(
                         conversation_id=conv_id,
                         role=role,
-                        content=msg.text or "",
+                        content=text,
                         user_id=uid or None,
                         customer_id=cid,
                     )
@@ -269,6 +313,8 @@ class SynapMemoryStore:
 
             # After the turn: the model says its piece, then asks for tools.
             await self._report_tool_calls(msg, ids)
+            if results[-1]["status"] == "written":
+                _mark_recorded(msg, conv_id)
 
         processed = written + failed
         if processed > 0 and written == 0:
@@ -428,6 +474,93 @@ class SynapMemoryStore:
         )
         return [Document(content=r["content"], meta=r["meta"]) for r in records]
 
+    # ── Haystack's ChatMessageStore protocol ───────────────────────────────────
+    #
+    # `chat_history_id` is the Synap conversation id.
+
+    def write_messages(self, chat_history_id: str, messages: List[ChatMessage]) -> int:
+        """Record the messages this store has not seen. Returns how many turns it wrote.
+
+        An agent's chat writer passes the whole run, history and system prompt
+        included; only what is new and said by a user or the assistant is a
+        turn. Tool calls, results and reasoning go on the stream.
+        """
+        return run_async(self.awrite_messages(chat_history_id, messages))
+
+    async def awrite_messages(self, chat_history_id: str, messages: List[ChatMessage]) -> int:
+        results = await self.aadd_memories(messages=messages, conversation_id=chat_history_id)
+        return sum(1 for r in results if r.get("status") == "written")
+
+    def retrieve_messages(self, chat_history_id: str, last_k: Optional[int] = None) -> List[ChatMessage]:
+        """Synap's history of the conversation, oldest first.
+
+        Once Synap has compacted the conversation: its compaction as a system
+        message, then the turns after it. Before that: the recent turns.
+        ``last_k`` keeps only that many of the turns (the compaction is always
+        kept). Degrades to ``[]`` on SDK failure.
+        """
+        return run_async(self.aretrieve_messages(chat_history_id, last_k))
+
+    async def aretrieve_messages(
+        self, chat_history_id: str, last_k: Optional[int] = None
+    ) -> List[ChatMessage]:
+        ctx = await self._acontext(chat_history_id)
+        if ctx is None:
+            return []
+        out: List[ChatMessage] = []
+        compaction = getattr(ctx, "context_block", None)
+        if getattr(ctx, "available", True) is not False and isinstance(compaction, str) \
+                and compaction.strip():
+            parts = [compaction.strip()]
+            found = getattr(ctx, "history_block", None)
+            if isinstance(found, str) and found.strip():
+                parts.append(found.strip())
+            out.append(ChatMessage.from_system(
+                f"{HISTORY_OPEN}\n" + "\n\n".join(parts) + f"\n{HISTORY_CLOSE}"))
+        turns: List[ChatMessage] = []
+        for rm in getattr(ctx, "recent_messages", None) or []:
+            role, content = getattr(rm, "role", None), getattr(rm, "content", None)
+            if not isinstance(content, str) or not content.strip():
+                continue
+            meta = {RECORDED_KEY: chat_history_id}
+            if role == "user":
+                turns.append(ChatMessage.from_user(content, meta=meta))
+            elif role == "assistant":
+                turns.append(ChatMessage.from_assistant(content, meta=meta))
+        if last_k is not None and last_k >= 0:
+            turns = turns[-last_k:] if last_k else []
+        return out + turns
+
+    def count_messages(self, chat_history_id: str) -> int:
+        """How many messages Synap holds for the conversation (0 on SDK failure)."""
+        return run_async(self.acount_messages(chat_history_id))
+
+    async def acount_messages(self, chat_history_id: str) -> int:
+        ctx = await self._acontext(chat_history_id)
+        total = getattr(ctx, "total_message_count", 0) if ctx is not None else 0
+        return total if isinstance(total, int) else 0
+
+    def delete_messages(self, chat_history_id: str) -> None:
+        """No-op: Synap has no public delete API (warns once)."""
+        self._warn_delete()
+
+    def delete_all_messages(self) -> None:
+        """No-op: Synap has no public delete API (warns once)."""
+        self._warn_delete()
+
+    async def _acontext(self, chat_history_id: str) -> Any:
+        try:
+            return await self.sdk.conversation.context.get_context_for_prompt(
+                conversation_id=chat_history_id,
+            )
+        except Exception as exc:  # noqa: BLE001 — read-side degrades gracefully
+            logger.error(
+                "SynapMemoryStore.retrieve_messages: get_context_for_prompt failed "
+                "conversation_id=%s error=%s",
+                chat_history_id, exc, exc_info=True,
+            )
+            return None
+
     # ── delete (no public Synap delete API) ────────────────────────────────────
 
     def delete_memory(self, memory_id: str, **kwargs: Any) -> None:
@@ -525,6 +658,19 @@ def _role_of(message: ChatMessage) -> str:
     return getattr(role, "value", role)
 
 
+def _is_recorded(message: ChatMessage) -> bool:
+    meta = getattr(message, "meta", None)
+    return isinstance(meta, dict) and bool(meta.get(RECORDED_KEY))
+
+
+def _mark_recorded(message: ChatMessage, conversation_id: str) -> None:
+    """Stamp a message so no store records it twice. `meta` is a plain dict on a
+    frozen dataclass, so this does not need to rebuild the message."""
+    meta = getattr(message, "meta", None)
+    if isinstance(meta, dict):
+        meta[RECORDED_KEY] = conversation_id
+
+
 def _message_id(resp: Any) -> Optional[str]:
     if isinstance(resp, dict):
         return resp.get("message_id")

{maximem_synap_haystack-0.2.1 → maximem_synap_haystack-0.2.2}/synap_haystack/writer.py

@@ -7,7 +7,11 @@ failure policy (see ``store.py``).
 Semantics:
 
 - Accepts ``Document``s where ``content`` is the message text and
-  ``meta["role"]`` is ``"user"`` or ``"assistant"``.
+  ``meta["role"]`` is ``"user"`` or ``"assistant"``, and/or ``ChatMessage``s on
+  ``messages``. Connect an agent's or generator's ``messages`` / ``replies`` to
+  ``messages`` and tool calls, tool results and reasoning reach Synap's stream
+  with the turns; a ``Document`` is text and role only, so it can carry none of
+  that.
 - Tracks ``written_count`` / ``failed_count`` / ``skipped_count`` separately and
   exposes all three plus ``first_error`` so downstream components can branch on
   partial failures.
@@ -84,9 +88,14 @@ class SynapMemoryWriter:
         skipped_count=int,
         first_error=Optional[str],
     )
-    def run(self, documents: List[Document]) -> Dict[str, object]:
-        messages: List[ChatMessage] = []
+    def run(
+        self,
+        documents: Optional[List[Document]] = None,
+        messages: Optional[List[ChatMessage]] = None,
+    ) -> Dict[str, object]:
+        chat_messages: List[ChatMessage] = list(messages or [])
         skipped = 0
+        documents = documents or []
         for doc in documents:
             role = doc.meta.get("role", "user")
             if role not in _VALID_ROLES:
@@ -98,16 +107,16 @@ class SynapMemoryWriter:
                 )
                 continue
             if role == "user":
-                messages.append(ChatMessage.from_user(doc.content or ""))
+                chat_messages.append(ChatMessage.from_user(doc.content or ""))
             else:
-                messages.append(ChatMessage.from_assistant(doc.content or ""))
+                chat_messages.append(ChatMessage.from_assistant(doc.content or ""))
 
         # add_memories raises SynapIntegrationError on 100% failure — propagate.
         results = (
             self.store.add_memories(
-                messages=messages, conversation_id=self.conversation_id
+                messages=chat_messages, conversation_id=self.conversation_id
             )
-            if messages
+            if chat_messages
             else []
         )
 

maximem_synap_haystack-0.2.2/tests/test_default_path.py

@@ -0,0 +1,215 @@
+"""The defaults, against Haystack's real experimental ``Agent``.
+
+Nothing here calls ``listen()``. The SDK is a fake whose ``instance.is_listening``
+starts False, the way a fresh SDK's does, and the generator is a scripted fake
+that keeps every message list it was sent.
+"""
+
+from types import SimpleNamespace
+from typing import Any, Dict, List, Optional
+from unittest.mock import AsyncMock
+
+import pytest
+from haystack import Document, component
+from haystack.dataclasses import ChatMessage, ToolCall
+from haystack.tools import Tool
+
+from synap_haystack import SynapMemoryStore, SynapMemoryWriter
+
+# The experimental Agent (and its chat_message_store slot) needs haystack-ai 2.x;
+# haystack-experimental 0.19 does not import against haystack-ai 3.
+try:
+    from haystack_experimental.components.agents import Agent
+except ImportError:
+    Agent = None
+
+needs_experimental_agent = pytest.mark.skipif(
+    Agent is None, reason="haystack_experimental's Agent needs haystack-ai 2.x")
+
+COMPACTION = "## Conversation so far (compacted 1x)\nThe user is planning a trip to Lisbon."
+
+
+class FakeInstance:
+    def __init__(self):
+        self.is_listening = False
+        self.listen_calls = 0
+        self.send_message = AsyncMock()
+        self.record_tool_call = AsyncMock()
+        self.record_tool_result = AsyncMock()
+        self.record_thinking = AsyncMock()
+
+    async def listen(self):
+        self.listen_calls += 1
+        self.is_listening = True
+
+
+def make_sdk(context=None):
+    return SimpleNamespace(
+        instance=FakeInstance(),
+        instance_id="inst",
+        conversation=SimpleNamespace(
+            record_message=AsyncMock(return_value={"message_id": "m1"}),
+            context=SimpleNamespace(get_context_for_prompt=AsyncMock(return_value=context)),
+        ),
+        fetch=AsyncMock(return_value=SimpleNamespace(
+            facts=[], preferences=[], episodes=[], emotions=[], temporal_events=[], scope_map={})),
+    )
+
+
+def ctx(compaction=COMPACTION, turns=(), total=0):
+    return SimpleNamespace(
+        context_block=compaction, history_block=None, available=True,
+        formatted_context="recent", total_message_count=total,
+        recent_messages=[SimpleNamespace(role=r, content=t) for r, t in turns],
+    )
+
+
+@component
+class ScriptedGenerator:
+    def __init__(self, script):
+        self.script = script
+        self.seen: List[Any] = []
+
+    @component.output_types(replies=List[ChatMessage])
+    def run(self, messages: List[ChatMessage], tools: Optional[Any] = None, **kwargs) -> Dict[str, Any]:
+        self.seen.append(list(messages))
+        return {"replies": [self.script.pop(0)]}
+
+
+def lookup(city: str) -> str:
+    return f"{city}: sunny"
+
+
+TOOL = Tool(name="lookup", description="Look a city up.",
+            parameters={"type": "object", "properties": {"city": {"type": "string"}},
+                        "required": ["city"]},
+            function=lookup)
+
+
+def tool_turn():
+    return [
+        ChatMessage.from_assistant("Let me check.", tool_calls=[
+            ToolCall(tool_name="lookup", arguments={"city": "Lisbon"}, id="c1")]),
+        ChatMessage.from_assistant("It is sunny in Lisbon."),
+    ]
+
+
+def agent_for(script, **stores):
+    gen = ScriptedGenerator(script)
+    agent = Agent(chat_generator=gen, tools=[TOOL], system_prompt="Be brief.", **stores)
+    return gen, agent
+
+
+def sent(sdk, event_type):
+    return [c.kwargs["content"] for c in sdk.instance.send_message.await_args_list
+            if c.kwargs["event_type"] == event_type]
+
+
+def texts(messages):
+    return [m.text for m in messages]
+
+
+def test_the_store_is_a_chat_message_store():
+    store = SynapMemoryStore(make_sdk(), user_id="u1")
+    for name in ("to_dict", "from_dict", "count_messages", "write_messages",
+                 "delete_messages", "delete_all_messages", "retrieve_messages"):
+        assert callable(getattr(store, name))
+    if Agent is not None:
+        Agent(chat_generator=ScriptedGenerator([]), chat_message_store=store)
+
+
+@needs_experimental_agent
+def test_an_agent_loads_synaps_compaction_instead_of_a_ten_message_window():
+    sdk = make_sdk(ctx(turns=[("user", "synap kept q"), ("assistant", "synap kept a")]))
+    store = SynapMemoryStore(sdk, user_id="u1")
+    gen, agent = agent_for([ChatMessage.from_assistant("Book the 9am flight.")], chat_message_store=store)
+
+    agent.run(messages=[ChatMessage.from_user("what now?")],
+              chat_message_store_kwargs={"chat_history_id": "c1"})
+
+    seen = gen.seen[0]
+    assert seen[0].text == "Be brief."
+    assert "The user is planning a trip to Lisbon." in seen[1].text and seen[1].is_from("system")
+    assert texts(seen[2:]) == ["synap kept q", "synap kept a", "what now?"]
+
+
+@needs_experimental_agent
+def test_an_agent_before_the_first_compaction_gets_the_recent_turns():
+    sdk = make_sdk(ctx(compaction=None, turns=[("user", "q1"), ("assistant", "a1")]))
+    gen, agent = agent_for([ChatMessage.from_assistant("ok")],
+                           chat_message_store=SynapMemoryStore(sdk, user_id="u1"))
+    agent.run(messages=[ChatMessage.from_user("q2")], chat_message_store_kwargs={"chat_history_id": "c1"})
+    assert texts(gen.seen[0][1:]) == ["q1", "a1", "q2"]
+
+
+def test_last_k_keeps_the_compaction_and_trims_the_turns():
+    sdk = make_sdk(ctx(turns=[("user", "t1"), ("assistant", "t2"), ("user", "t3"), ("assistant", "t4")]))
+    msgs = SynapMemoryStore(sdk, user_id="u1").retrieve_messages("c1", last_k=2)
+    assert msgs[0].is_from("system") and texts(msgs[1:]) == ["t3", "t4"]
+
+
+@needs_experimental_agent
+def test_an_agent_run_records_each_turn_once_on_an_auto_opened_stream():
+    sdk = make_sdk(ctx(compaction=None, turns=[("user", "q1"), ("assistant", "a1")]))
+    store = SynapMemoryStore(sdk, user_id="u1", conversation_id="c1")
+    gen, agent = agent_for(tool_turn(), chat_message_store=store, memory_store=store)
+
+    agent.run(messages=[ChatMessage.from_user("weather in Lisbon?")],
+              chat_message_store_kwargs={"chat_history_id": "c1"})
+
+    assert sdk.instance.listen_calls == 1  # opened by the first turn, never by the caller
+    # Both slots got the same messages, history included: each turn goes out once,
+    # and the retrieved history (already in Synap) not at all.
+    assert sent(sdk, "user_message") == ["weather in Lisbon?"]
+    assert sent(sdk, "assistant_message") == ["It is sunny in Lisbon."]  # the tool-call lap has no words to record
+    sdk.conversation.record_message.assert_not_awaited()
+    sdk.instance.record_tool_call.assert_awaited_once()
+    sdk.instance.record_tool_result.assert_awaited_once()
+
+
+def test_a_message_with_no_words_is_not_an_empty_turn():
+    sdk = make_sdk()
+    store = SynapMemoryStore(sdk, user_id="u1")
+    results = store.add_memories(
+        messages=[ChatMessage.from_assistant(tool_calls=[ToolCall(tool_name="lookup", arguments={}, id="c1")])],
+        conversation_id="c1")
+    assert results == [{"role": "assistant", "status": "skipped", "reason": "no text"}]
+    sdk.instance.send_message.assert_not_awaited()
+    sdk.conversation.record_message.assert_not_awaited()
+    sdk.instance.record_tool_call.assert_awaited_once()
+
+
+def test_count_and_delete():
+    store = SynapMemoryStore(make_sdk(ctx(total=7)), user_id="u1")
+    assert store.count_messages("c1") == 7
+    store.delete_messages("c1")
+    store.delete_all_messages()  # warn once, no-op
+
+
+def test_retrieve_degrades_to_nothing_on_an_outage():
+    sdk = make_sdk()
+    sdk.conversation.context.get_context_for_prompt.side_effect = RuntimeError("down")
+    store = SynapMemoryStore(sdk, user_id="u1")
+    assert store.retrieve_messages("c1") == []
+    assert store.count_messages("c1") == 0
+
+
+def test_the_writer_keeps_tool_calls_and_results_when_given_messages():
+    sdk = make_sdk()
+    writer = SynapMemoryWriter(store=SynapMemoryStore(sdk, user_id="u1"), conversation_id="c1")
+    result = writer.run(messages=[
+        ChatMessage.from_user("weather?"),
+        ChatMessage.from_assistant("checking", tool_calls=[ToolCall(tool_name="lookup", arguments={"city": "X"}, id="c1")]),
+        ChatMessage.from_tool("sunny", origin=ToolCall(tool_name="lookup", arguments={"city": "X"}, id="c1")),
+    ])
+    assert result["written_count"] == 1  # the question; "checking" narrates a tool call
+    sdk.instance.record_tool_call.assert_awaited_once()
+    sdk.instance.record_tool_result.assert_awaited_once()
+
+
+def test_the_writer_still_takes_documents():
+    sdk = make_sdk()
+    writer = SynapMemoryWriter(store=SynapMemoryStore(sdk, user_id="u1"), conversation_id="c1")
+    result = writer.run(documents=[Document(content="hi", meta={"role": "user"})])
+    assert result["written_count"] == 1
+    assert sent(sdk, "user_message") == ["hi"]

maximem_synap_haystack-0.2.2/tests/test_hooks.py

@@ -0,0 +1,103 @@
+"""The hooks, against haystack-ai 3's real ``Agent``.
+
+Nothing here calls ``listen()``: the SDK is a fake whose ``instance.is_listening``
+starts False.
+"""
+
+from typing import Any, Dict, List, Optional
+
+import pytest
+from haystack import component
+from haystack.dataclasses import ChatMessage, ToolCall
+from haystack.tools import Tool
+
+from synap_haystack import SynapMemoryStore
+
+from .test_default_path import COMPACTION, ctx, make_sdk, sent, texts, TOOL, tool_turn, ScriptedGenerator
+
+Agent = pytest.importorskip("haystack.components.agents", exc_type=ImportError).Agent
+hooks_mod = pytest.importorskip("haystack.hooks", exc_type=ImportError)
+from synap_haystack import SynapHistoryHook, SynapRecordHook  # noqa: E402
+
+OLD = [ChatMessage.from_user("old q1"), ChatMessage.from_assistant("old a1"),
+       ChatMessage.from_user("old q2"), ChatMessage.from_assistant("old a2")]
+
+
+def agent_for(script, store, with_record=True):
+    gen = ScriptedGenerator(script)
+    hooks = {"before_llm": [SynapHistoryHook(store, "c1")]}
+    if with_record:
+        hooks["after_run"] = [SynapRecordHook(store, "c1")]
+    return gen, Agent(chat_generator=gen, tools=[TOOL], system_prompt="Be brief.", hooks=hooks)
+
+
+def test_the_model_sees_synaps_compaction_in_place_of_the_earlier_turns():
+    sdk = make_sdk(ctx(turns=[("user", "synap kept q"), ("assistant", "synap kept a")]))
+    gen, agent = agent_for([ChatMessage.from_assistant("Book the 9am flight.")],
+                           SynapMemoryStore(sdk, user_id="u1"))
+
+    agent.run(messages=[*OLD, ChatMessage.from_user("what now?")])
+
+    seen = gen.seen[0]
+    assert seen[0].text == "Be brief."
+    assert seen[1].is_from("system") and "The user is planning a trip to Lisbon." in seen[1].text
+    assert texts(seen[2:]) == ["synap kept q", "synap kept a", "what now?"]
+    assert not any("old q" in (m.text or "") for m in seen)
+
+
+def test_the_messages_are_untouched_until_synap_has_compacted():
+    sdk = make_sdk(ctx(compaction=None))
+    gen, agent = agent_for([ChatMessage.from_assistant("fine")], SynapMemoryStore(sdk, user_id="u1"))
+    agent.run(messages=[*OLD, ChatMessage.from_user("what now?")])
+    assert texts(gen.seen[0][1:]) == ["old q1", "old a1", "old q2", "old a2", "what now?"]
+
+
+def test_a_synap_outage_does_not_stop_the_run():
+    sdk = make_sdk()
+    sdk.conversation.context.get_context_for_prompt.side_effect = RuntimeError("down")
+    gen, agent = agent_for([ChatMessage.from_assistant("fine")], SynapMemoryStore(sdk, user_id="u1"))
+    agent.run(messages=[ChatMessage.from_user("hi")])
+    assert gen.seen[0][-1].text == "hi"
+
+
+def test_the_tool_loop_stays_paired_on_every_lap():
+    sdk = make_sdk(ctx())
+    gen, agent = agent_for(tool_turn(), SynapMemoryStore(sdk, user_id="u1"), with_record=False)
+    agent.run(messages=[*OLD, ChatMessage.from_user("weather?")])
+    second = gen.seen[1]
+    assert any(m.tool_call_results for m in second)
+    assert not any("old q" in (m.text or "") for m in second)
+    assert sdk.conversation.context.get_context_for_prompt.await_count == 2  # per model call
+
+
+def test_a_run_is_recorded_once_on_an_auto_opened_stream():
+    sdk = make_sdk(ctx(compaction=None))
+    gen, agent = agent_for(tool_turn(), SynapMemoryStore(sdk, user_id="u1"))
+
+    agent.run(messages=[ChatMessage.from_user("weather in Lisbon?")])
+
+    assert sdk.instance.listen_calls == 1  # opened by the first turn, never by the caller
+    assert sent(sdk, "user_message") == ["weather in Lisbon?"]
+    assert sent(sdk, "assistant_message") == ["It is sunny in Lisbon."]  # not the tool-call lap
+    sdk.conversation.record_message.assert_not_awaited()
+    sdk.instance.record_tool_call.assert_awaited_once()
+    sdk.instance.record_tool_result.assert_awaited_once()
+
+
+def test_history_the_hook_loaded_is_not_recorded_again():
+    sdk = make_sdk(ctx(turns=[("user", "synap kept q"), ("assistant", "synap kept a")]))
+    gen, agent = agent_for([ChatMessage.from_assistant("Book it.")], SynapMemoryStore(sdk, user_id="u1"))
+    agent.run(messages=[ChatMessage.from_user("what now?")])
+    assert sent(sdk, "user_message") == ["what now?"]
+    assert sent(sdk, "assistant_message") == ["Book it."]
+
+
+def test_the_hooks_serialize():
+    store = SynapMemoryStore(make_sdk(), user_id="u1")
+    data = SynapHistoryHook(store, "c1").to_dict()
+    assert data["init_parameters"]["chat_history_id"] == "c1"
+
+
+def test_the_hooks_need_a_conversation():
+    with pytest.raises(ValueError, match="chat_history_id"):
+        SynapHistoryHook(SynapMemoryStore(make_sdk(), user_id="u1"), "")

{maximem_synap_haystack-0.2.1 → maximem_synap_haystack-0.2.2}/tests/test_short_term.py

@@ -25,9 +25,14 @@ from synap_integrations_common import SynapIntegrationError
 
 
 def _make_response(formatted: str | None, available: bool):
+    """`formatted` is the compaction. `formatted_context` is what the server sends
+    beside it: the compaction AND the recent turns, which the pipeline already
+    passes, so it must never reach the prompt."""
     resp = MagicMock()
     resp.available = available
-    resp.formatted_context = formatted
+    resp.context_block = formatted
+    resp.history_block = None
+    resp.formatted_context = f"{formatted}\nRECENT-TURNS-DUPLICATE" if formatted else None
     return resp
 
 
@@ -39,6 +44,19 @@ def _fake_sdk(formatted: str | None = "Customer is on Pro plan.", available: boo
     return sdk
 
 
+class TestNoDuplicatedTurns:
+    def test_emits_the_compaction_and_not_the_recent_turns(self):
+        sdk = _fake_sdk(formatted="## Conversation so far (compacted 1x)\nThey asked about refunds.")
+        out = SynapShortTermContext(sdk, "conv_abc", system="Be brief.").run()["synap_st"]
+        assert "They asked about refunds." in out
+        assert "RECENT-TURNS-DUPLICATE" not in out
+
+    def test_no_compaction_yet_emits_only_the_system_text(self):
+        sdk = _fake_sdk(formatted=None, available=True)
+        sdk.conversation.context.get_context_for_prompt.return_value.formatted_context = "recent"
+        assert SynapShortTermContext(sdk, "conv_abc", system="Be brief.").run()["synap_st"] == "Be brief."
+
+
 # ---------------------------------------------------------------------------
 # Construction validation
 # ---------------------------------------------------------------------------