maximem-synap-microsoft-agent 0.1.1__tar.gz

maximem_synap_microsoft_agent-0.1.1/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: maximem-synap-microsoft-agent
+Version: 0.1.1
+Summary: Synap memory integration for Microsoft Agent Framework
+Author: Synap Team
+License-Expression: Apache-2.0
+Keywords: synap,memory,microsoft,agent-framework,ai,agents
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: maximem-synap>=0.2.0
+Requires-Dist: synap-integrations-common>=0.1.0
+Requires-Dist: agent-framework>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+
+# synap-microsoft-agent
+
+Synap memory integration for [Microsoft Agent Framework (MAF)](https://learn.microsoft.com/en-us/agent-framework/).
+
+## Install
+
+```bash
+pip install synap-microsoft-agent
+```
+
+Requires `agent-framework>=1.0`, `maximem-synap>=0.2.0`.
+
+## Quickstart
+
+```python
+from agent_framework import InMemoryHistoryProvider
+from agent_framework.openai import OpenAIChatClient
+from maximem_synap import MaximemSynapSDK
+from synap_microsoft_agent import SynapContextProvider, SynapHistoryProvider
+
+sdk = MaximemSynapSDK(api_key="sk-...")
+client = OpenAIChatClient(model="gpt-4o-mini")
+
+agent = client.as_agent(
+    name="MemoryAgent",
+    instructions="You are a helpful assistant.",
+    context_providers=[
+        SynapContextProvider(
+            sdk=sdk,
+            user_id="alice",
+            customer_id="acme",
+        ),
+        SynapHistoryProvider(
+            sdk=sdk,
+            user_id="alice",
+            customer_id="acme",
+        ),
+    ],
+)
+
+session = agent.create_session()
+result = await agent.run("What's my trial expiring?", session=session)
+```
+
+## What each provider does
+
+- **`SynapContextProvider`** — on every turn, fetches Synap context (facts, preferences, episodes, emotions, temporal events) and appends it as instructions. After the turn, records the user + assistant messages back to Synap.
+
+- **`SynapHistoryProvider`** — persists the conversation message log. Loads prior turns on session resume. Subclass of MAF's `HistoryProvider`, so all its flags (`load_messages`, `store_inputs`, `store_outputs`, `store_context_messages`) work as documented.
+
+You can use either or both; they coexist.
+
+## Error policy
+
+- **Read-side failures** (`fetch`, `get_context_for_prompt`) degrade gracefully — logged at `ERROR`, empty result returned. An outage never crashes an agent turn.
+- **Write-side failures** — `SynapContextProvider.after_run` logs and swallows (context providers must not raise per MAF's hook contract). `SynapHistoryProvider.save_messages` surfaces errors as `SynapIntegrationError` so explicit persistence failures are observable.

maximem_synap_microsoft_agent-0.1.1/README.md

@@ -0,0 +1,56 @@
+# synap-microsoft-agent
+
+Synap memory integration for [Microsoft Agent Framework (MAF)](https://learn.microsoft.com/en-us/agent-framework/).
+
+## Install
+
+```bash
+pip install synap-microsoft-agent
+```
+
+Requires `agent-framework>=1.0`, `maximem-synap>=0.2.0`.
+
+## Quickstart
+
+```python
+from agent_framework import InMemoryHistoryProvider
+from agent_framework.openai import OpenAIChatClient
+from maximem_synap import MaximemSynapSDK
+from synap_microsoft_agent import SynapContextProvider, SynapHistoryProvider
+
+sdk = MaximemSynapSDK(api_key="sk-...")
+client = OpenAIChatClient(model="gpt-4o-mini")
+
+agent = client.as_agent(
+    name="MemoryAgent",
+    instructions="You are a helpful assistant.",
+    context_providers=[
+        SynapContextProvider(
+            sdk=sdk,
+            user_id="alice",
+            customer_id="acme",
+        ),
+        SynapHistoryProvider(
+            sdk=sdk,
+            user_id="alice",
+            customer_id="acme",
+        ),
+    ],
+)
+
+session = agent.create_session()
+result = await agent.run("What's my trial expiring?", session=session)
+```
+
+## What each provider does
+
+- **`SynapContextProvider`** — on every turn, fetches Synap context (facts, preferences, episodes, emotions, temporal events) and appends it as instructions. After the turn, records the user + assistant messages back to Synap.
+
+- **`SynapHistoryProvider`** — persists the conversation message log. Loads prior turns on session resume. Subclass of MAF's `HistoryProvider`, so all its flags (`load_messages`, `store_inputs`, `store_outputs`, `store_context_messages`) work as documented.
+
+You can use either or both; they coexist.
+
+## Error policy
+
+- **Read-side failures** (`fetch`, `get_context_for_prompt`) degrade gracefully — logged at `ERROR`, empty result returned. An outage never crashes an agent turn.
+- **Write-side failures** — `SynapContextProvider.after_run` logs and swallows (context providers must not raise per MAF's hook contract). `SynapHistoryProvider.save_messages` surfaces errors as `SynapIntegrationError` so explicit persistence failures are observable.

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

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: maximem-synap-microsoft-agent
+Version: 0.1.1
+Summary: Synap memory integration for Microsoft Agent Framework
+Author: Synap Team
+License-Expression: Apache-2.0
+Keywords: synap,memory,microsoft,agent-framework,ai,agents
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: maximem-synap>=0.2.0
+Requires-Dist: synap-integrations-common>=0.1.0
+Requires-Dist: agent-framework>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+
+# synap-microsoft-agent
+
+Synap memory integration for [Microsoft Agent Framework (MAF)](https://learn.microsoft.com/en-us/agent-framework/).
+
+## Install
+
+```bash
+pip install synap-microsoft-agent
+```
+
+Requires `agent-framework>=1.0`, `maximem-synap>=0.2.0`.
+
+## Quickstart
+
+```python
+from agent_framework import InMemoryHistoryProvider
+from agent_framework.openai import OpenAIChatClient
+from maximem_synap import MaximemSynapSDK
+from synap_microsoft_agent import SynapContextProvider, SynapHistoryProvider
+
+sdk = MaximemSynapSDK(api_key="sk-...")
+client = OpenAIChatClient(model="gpt-4o-mini")
+
+agent = client.as_agent(
+    name="MemoryAgent",
+    instructions="You are a helpful assistant.",
+    context_providers=[
+        SynapContextProvider(
+            sdk=sdk,
+            user_id="alice",
+            customer_id="acme",
+        ),
+        SynapHistoryProvider(
+            sdk=sdk,
+            user_id="alice",
+            customer_id="acme",
+        ),
+    ],
+)
+
+session = agent.create_session()
+result = await agent.run("What's my trial expiring?", session=session)
+```
+
+## What each provider does
+
+- **`SynapContextProvider`** — on every turn, fetches Synap context (facts, preferences, episodes, emotions, temporal events) and appends it as instructions. After the turn, records the user + assistant messages back to Synap.
+
+- **`SynapHistoryProvider`** — persists the conversation message log. Loads prior turns on session resume. Subclass of MAF's `HistoryProvider`, so all its flags (`load_messages`, `store_inputs`, `store_outputs`, `store_context_messages`) work as documented.
+
+You can use either or both; they coexist.
+
+## Error policy
+
+- **Read-side failures** (`fetch`, `get_context_for_prompt`) degrade gracefully — logged at `ERROR`, empty result returned. An outage never crashes an agent turn.
+- **Write-side failures** — `SynapContextProvider.after_run` logs and swallows (context providers must not raise per MAF's hook contract). `SynapHistoryProvider.save_messages` surfaces errors as `SynapIntegrationError` so explicit persistence failures are observable.

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

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+maximem_synap_microsoft_agent.egg-info/PKG-INFO
+maximem_synap_microsoft_agent.egg-info/SOURCES.txt
+maximem_synap_microsoft_agent.egg-info/dependency_links.txt
+maximem_synap_microsoft_agent.egg-info/requires.txt
+maximem_synap_microsoft_agent.egg-info/top_level.txt
+synap_microsoft_agent/__init__.py
+synap_microsoft_agent/context_provider.py
+synap_microsoft_agent/history_provider.py

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

@@ -0,0 +1 @@
+

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

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

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

@@ -0,0 +1 @@
+synap_microsoft_agent

maximem_synap_microsoft_agent-0.1.1/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "maximem-synap-microsoft-agent"
+version = "0.1.1"
+description = "Synap memory integration for Microsoft Agent Framework"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [
+    {name = "Synap Team"}
+]
+keywords = ["synap", "memory", "microsoft", "agent-framework", "ai", "agents"]
+
+dependencies = [
+    "maximem-synap>=0.2.0",
+    "synap-integrations-common>=0.1.0",
+    "agent-framework>=1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["synap_microsoft_agent*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

maximem_synap_microsoft_agent-0.1.1/setup.cfg

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

maximem_synap_microsoft_agent-0.1.1/synap_microsoft_agent/__init__.py

@@ -0,0 +1,32 @@
+"""Synap integration for Microsoft Agent Framework (MAF).
+
+Two plug points into MAF's context-engineering pipeline:
+
+- :class:`SynapContextProvider` — subclass of ``ContextProvider``. Injects
+  Synap-sourced context into the agent's instructions on every turn via
+  ``before_run``, and records each turn back to Synap via ``after_run``.
+  Pattern mirrors ``agent_framework.mem0.Mem0ContextProvider``.
+
+- :class:`SynapHistoryProvider` — subclass of ``HistoryProvider``. Persists
+  the conversation message log to Synap via ``sdk.conversation.record_message``
+  and loads it back via ``sdk.conversation.context.get_context_for_prompt``.
+
+Typical wiring::
+
+    from agent_framework import InMemoryHistoryProvider
+    from synap_microsoft_agent import SynapContextProvider
+
+    agent = client.as_agent(
+        name="MemoryAgent",
+        instructions="You are a helpful assistant.",
+        context_providers=[
+            SynapContextProvider(sdk=sdk, user_id="alice", customer_id="acme"),
+            InMemoryHistoryProvider(load_messages=True),
+        ],
+    )
+"""
+
+from synap_microsoft_agent.context_provider import SynapContextProvider
+from synap_microsoft_agent.history_provider import SynapHistoryProvider
+
+__all__ = ["SynapContextProvider", "SynapHistoryProvider"]

maximem_synap_microsoft_agent-0.1.1/synap_microsoft_agent/context_provider.py

@@ -0,0 +1,187 @@
+"""SynapContextProvider — MAF ContextProvider backed by Synap.
+
+Pattern mirrors ``agent_framework.mem0.Mem0ContextProvider``:
+
+- ``before_run`` builds a query from ``context.input_messages`` text, calls
+  ``sdk.fetch(...)``, and appends the formatted result as instructions via
+  ``context.extend_instructions(source_id, ...)``. Read failures degrade
+  gracefully — we log + skip rather than breaking the agent turn.
+
+- ``after_run`` records each input + response message to Synap via
+  ``sdk.conversation.record_message(...)``. Write failures are logged but
+  never re-raised, following MAF's "context providers should not crash the
+  agent" contract (same as LangChain's ``SynapCallbackHandler``).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, ClassVar, Optional
+
+from agent_framework import ContextProvider
+from maximem_synap import MaximemSynapSDK
+
+logger = logging.getLogger(__name__)
+
+
+class SynapContextProvider(ContextProvider):
+    """Inject Synap context + record turns back to Synap."""
+
+    DEFAULT_SOURCE_ID: ClassVar[str] = "synap"
+    DEFAULT_CONTEXT_PROMPT: ClassVar[str] = (
+        "## User Memory Context\n"
+        "Consider the following context about the user and their history "
+        "when answering. Treat it as background knowledge, not direct input."
+    )
+
+    def __init__(
+        self,
+        sdk: MaximemSynapSDK,
+        user_id: str,
+        customer_id: str = "",
+        conversation_id: Optional[str] = None,
+        *,
+        source_id: str = DEFAULT_SOURCE_ID,
+        mode: str = "accurate",
+        max_results: int = 20,
+        context_prompt: Optional[str] = None,
+        include_scope_labels: bool = False,
+    ) -> None:
+        if sdk is None:
+            raise ValueError("SynapContextProvider requires a non-None sdk")
+        if not user_id:
+            raise ValueError("SynapContextProvider requires a non-empty user_id")
+
+        super().__init__(source_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
+        self.context_prompt = context_prompt or self.DEFAULT_CONTEXT_PROMPT
+        self.include_scope_labels = include_scope_labels
+
+    async def before_run(
+        self,
+        *,
+        agent: Any,
+        session: Any,
+        context: Any,
+        state: dict[str, Any],
+    ) -> None:
+        """Fetch Synap context and append it to the agent's instructions."""
+        input_text = self._concat_text(context.input_messages)
+        if not input_text:
+            return
+
+        conv_id = self._resolve_conversation_id(context)
+
+        try:
+            response = await self.sdk.fetch(
+                conversation_id=conv_id,
+                user_id=self.user_id,
+                customer_id=self.customer_id or None,
+                search_query=[input_text],
+                max_results=self.max_results,
+                mode=self.mode,
+                include_conversation_context=False,
+                include_scope_labels=self.include_scope_labels,
+            )
+        except Exception as exc:  # noqa: BLE001 — read-side degrades gracefully
+            logger.error(
+                "SynapContextProvider.before_run: sdk.fetch failed "
+                "user_id=%s conversation_id=%s error=%s",
+                self.user_id,
+                conv_id,
+                exc,
+                exc_info=True,
+            )
+            return
+
+        formatted = (response.formatted_context or "").strip()
+        if not formatted:
+            return
+
+        context.extend_instructions(
+            self.source_id,
+            f"{self.context_prompt}\n{formatted}",
+        )
+
+    async def after_run(
+        self,
+        *,
+        agent: Any,
+        session: Any,
+        context: Any,
+        state: dict[str, Any],
+    ) -> None:
+        """Record input + response messages to Synap conversation history."""
+        conv_id = self._resolve_conversation_id(context)
+        if not conv_id:
+            # Without a conversation id we can't attribute the turn — skip.
+            return
+
+        to_record: list[tuple[str, str]] = []
+        for message in context.input_messages or []:
+            role, text = self._message_to_role_text(message)
+            if role and text:
+                to_record.append((role, text))
+
+        response = context.response
+        if response is not None and getattr(response, "messages", None):
+            for message in response.messages:
+                role, text = self._message_to_role_text(message)
+                if role and text:
+                    to_record.append((role, text))
+
+        for role, text in to_record:
+            try:
+                await self.sdk.conversation.record_message(
+                    conversation_id=conv_id,
+                    role=role,
+                    content=text,
+                    user_id=self.user_id,
+                    customer_id=self.customer_id,
+                )
+            except Exception as exc:  # noqa: BLE001 — must not crash the agent
+                logger.error(
+                    "SynapContextProvider.after_run: record_message failed "
+                    "role=%s conversation_id=%s error=%s",
+                    role,
+                    conv_id,
+                    exc,
+                    exc_info=True,
+                )
+
+    # -- helpers --------------------------------------------------------------
+
+    def _resolve_conversation_id(self, context: Any) -> Optional[str]:
+        if self.conversation_id:
+            return self.conversation_id
+        sid = getattr(context, "session_id", None)
+        return sid if sid else None
+
+    @staticmethod
+    def _concat_text(messages: Any) -> str:
+        if not messages:
+            return ""
+        parts: list[str] = []
+        for msg in messages:
+            text = getattr(msg, "text", None)
+            if text and text.strip():
+                parts.append(text.strip())
+        return "\n".join(parts)
+
+    @staticmethod
+    def _message_to_role_text(message: Any) -> tuple[Optional[str], str]:
+        role_raw = getattr(message, "role", None)
+        if role_raw is None:
+            return None, ""
+        role = role_raw.value if hasattr(role_raw, "value") else str(role_raw)
+        if role not in {"user", "assistant", "system"}:
+            return None, ""
+        text = getattr(message, "text", "") or ""
+        if not text.strip():
+            return None, ""
+        return role, text

maximem_synap_microsoft_agent-0.1.1/synap_microsoft_agent/history_provider.py

@@ -0,0 +1,133 @@
+"""SynapHistoryProvider — MAF HistoryProvider backed by Synap.
+
+Persists conversation messages to Synap and loads them back into the MAF
+session. Wrap one or more of these in ``context_providers`` to get durable,
+cross-process conversation memory.
+
+Load path (``get_messages``) reads via ``sdk.conversation.context.get_context_for_prompt``
+and degrades gracefully on failure (returns ``[]``) — a history read outage
+shouldn't abort the agent turn.
+
+Save path (``save_messages``) iterates ``sdk.conversation.record_message``
+and surfaces SDK errors as :class:`SynapIntegrationError` because silent drops
+would hide ingestion problems from the caller.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, ClassVar, Optional, Sequence
+
+from agent_framework import Message
+from agent_framework._sessions import HistoryProvider
+from maximem_synap import MaximemSynapSDK
+from synap_integrations_common import wrap_sdk_errors_async
+
+logger = logging.getLogger(__name__)
+
+
+class SynapHistoryProvider(HistoryProvider):
+    """Store + load MAF conversation history via Synap."""
+
+    DEFAULT_SOURCE_ID: ClassVar[str] = "synap_history"
+
+    def __init__(
+        self,
+        sdk: MaximemSynapSDK,
+        user_id: str,
+        customer_id: str = "",
+        conversation_id: Optional[str] = None,
+        *,
+        source_id: str = DEFAULT_SOURCE_ID,
+        load_messages: bool = True,
+        store_inputs: bool = True,
+        store_context_messages: bool = False,
+        store_context_from: Optional[set[str]] = None,
+        store_outputs: bool = True,
+    ) -> None:
+        if sdk is None:
+            raise ValueError("SynapHistoryProvider requires a non-None sdk")
+        if not user_id:
+            raise ValueError("SynapHistoryProvider requires a non-empty user_id")
+
+        super().__init__(
+            source_id,
+            load_messages=load_messages,
+            store_inputs=store_inputs,
+            store_context_messages=store_context_messages,
+            store_context_from=store_context_from,
+            store_outputs=store_outputs,
+        )
+        self.sdk = sdk
+        self.user_id = user_id
+        self.customer_id = customer_id
+        self.conversation_id = conversation_id
+
+    async def get_messages(
+        self,
+        session_id: Optional[str],
+        *,
+        state: Optional[dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> list[Message]:
+        conv_id = self.conversation_id or session_id
+        if not conv_id:
+            return []
+
+        try:
+            response = await self.sdk.conversation.context.get_context_for_prompt(
+                conversation_id=conv_id,
+            )
+        except Exception as exc:  # noqa: BLE001 — read-side degrades gracefully
+            logger.error(
+                "SynapHistoryProvider.get_messages: get_context_for_prompt failed "
+                "conversation_id=%s error=%s",
+                conv_id,
+                exc,
+                exc_info=True,
+            )
+            return []
+
+        recent = getattr(response, "recent_messages", None) or []
+        messages: list[Message] = []
+        for rm in recent:
+            role = getattr(rm, "role", None)
+            content = getattr(rm, "content", None)
+            if not role or not content:
+                continue
+            messages.append(Message(role=role, contents=[content]))
+        return messages
+
+    async def save_messages(
+        self,
+        session_id: Optional[str],
+        messages: Sequence[Message],
+        *,
+        state: Optional[dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> None:
+        conv_id = self.conversation_id or session_id
+        if not conv_id or not messages:
+            return
+
+        async with wrap_sdk_errors_async(
+            "microsoft_agent.save_messages",
+            logger,
+            user_id=self.user_id,
+            conversation_id=conv_id,
+        ):
+            for message in messages:
+                role_raw = getattr(message, "role", None)
+                role = role_raw.value if hasattr(role_raw, "value") else str(role_raw)
+                if role not in {"user", "assistant", "system"}:
+                    continue
+                text = getattr(message, "text", "") or ""
+                if not text.strip():
+                    continue
+                await self.sdk.conversation.record_message(
+                    conversation_id=conv_id,
+                    role=role,
+                    content=text,
+                    user_id=self.user_id,
+                    customer_id=self.customer_id,
+                )