agent-framework-goodmem 0.1.0__py3-none-any.whl

agent_framework_goodmem/__init__.py

@@ -0,0 +1,45 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""GoodMem integration for Microsoft Agent Framework.
+
+This package provides two ways to use GoodMem with Agent Framework agents:
+
+1. **Context provider** — :class:`GoodMemContextProvider` automatically
+   retrieves relevant memories before each agent run and stores
+   conversations after, using the ``BaseContextProvider`` hooks pattern.
+
+2. **Tools** — :func:`create_goodmem_tools` exposes GoodMem operations
+   as agent tools, letting the model decide when to read/write memories.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+from typing import TYPE_CHECKING
+
+from ._client import GoodMemClient
+from ._context_provider import GoodMemContextProvider
+
+if TYPE_CHECKING:
+    from ._tools import create_goodmem_tools as create_goodmem_tools
+else:
+
+    def __getattr__(name: str):  # noqa: ANN001, ANN202
+        if name == "create_goodmem_tools":
+            from ._tools import create_goodmem_tools
+
+            return create_goodmem_tools
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+try:
+    __version__ = importlib.metadata.version(__name__)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"  # Fallback for development mode
+
+__all__ = [
+    "GoodMemClient",
+    "GoodMemContextProvider",
+    "create_goodmem_tools",
+    "__version__",
+]

agent_framework_goodmem/_client.py

@@ -0,0 +1,424 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Low-level HTTP client for the GoodMem API.
+
+This module provides ``GoodMemClient``, a thin async wrapper around the
+GoodMem REST API.  It handles authentication, URL normalization, and
+JSON serialization so that the tool layer can stay focused on schema
+definitions and result formatting.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import time
+from typing import Any
+
+import httpx
+
+
+# -- MIME helpers --------------------------------------------------------------
+
+_MIME_TYPES: dict[str, str] = {
+    "pdf": "application/pdf",
+    "png": "image/png",
+    "jpg": "image/jpeg",
+    "jpeg": "image/jpeg",
+    "gif": "image/gif",
+    "webp": "image/webp",
+    "txt": "text/plain",
+    "html": "text/html",
+    "md": "text/markdown",
+    "csv": "text/csv",
+    "json": "application/json",
+    "xml": "application/xml",
+    "doc": "application/msword",
+    "docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    "xls": "application/vnd.ms-excel",
+    "xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    "ppt": "application/vnd.ms-powerpoint",
+    "pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+}
+
+
+def _guess_mime(extension: str) -> str:
+    """Return MIME type for a file extension, falling back to octet-stream."""
+    return _MIME_TYPES.get(extension.lower().lstrip("."), "application/octet-stream")
+
+
+class GoodMemClient:
+    """Async client for the GoodMem REST API.
+
+    Args:
+        base_url: Base URL of the GoodMem server (e.g. ``https://api.goodmem.ai``).
+        api_key: API key used for ``X-API-Key`` authentication.
+    """
+
+    def __init__(self, base_url: str, api_key: str, *, verify_ssl: bool = True) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self._http = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers={
+                "X-API-Key": self._api_key,
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            },
+            verify=verify_ssl,
+            timeout=httpx.Timeout(60.0),
+        )
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._http.aclose()
+
+    # -- Spaces ----------------------------------------------------------------
+
+    async def list_spaces(self) -> list[dict[str, Any]]:
+        """List all spaces."""
+        resp = await self._http.get("/v1/spaces")
+        resp.raise_for_status()
+        body = resp.json()
+        return body if isinstance(body, list) else body.get("spaces", [])
+
+    async def create_space(
+        self,
+        name: str,
+        embedder_id: str,
+        chunk_size: int = 256,
+        chunk_overlap: int = 25,
+        keep_strategy: str = "KEEP_END",
+        length_measurement: str = "CHARACTER_COUNT",
+    ) -> dict[str, Any]:
+        """Create a new space, or return the existing one if a space with *name* already exists."""
+        # Check for existing space with the same name
+        spaces = await self.list_spaces()
+        for space in spaces:
+            if space.get("name") == name:
+                return {
+                    "success": True,
+                    "spaceId": space["spaceId"],
+                    "name": space["name"],
+                    "embedderId": embedder_id,
+                    "message": "Space already exists, reusing existing space",
+                    "reused": True,
+                }
+
+        payload: dict[str, Any] = {
+            "name": name,
+            "spaceEmbedders": [{"embedderId": embedder_id, "defaultRetrievalWeight": 1.0}],
+            "defaultChunkingConfig": {
+                "recursive": {
+                    "chunkSize": chunk_size,
+                    "chunkOverlap": chunk_overlap,
+                    "separators": ["\n\n", "\n", ". ", " ", ""],
+                    "keepStrategy": keep_strategy,
+                    "separatorIsRegex": False,
+                    "lengthMeasurement": length_measurement,
+                },
+            },
+        }
+        resp = await self._http.post("/v1/spaces", json=payload)
+        resp.raise_for_status()
+        data = resp.json()
+        return {
+            "success": True,
+            "spaceId": data["spaceId"],
+            "name": data["name"],
+            "embedderId": embedder_id,
+            "chunkingConfig": payload["defaultChunkingConfig"],
+            "message": "Space created successfully",
+            "reused": False,
+        }
+
+    async def get_space(self, space_id: str) -> dict[str, Any]:
+        """Fetch a single space by ID."""
+        resp = await self._http.get(f"/v1/spaces/{space_id}")
+        resp.raise_for_status()
+        return {"success": True, "space": resp.json()}
+
+    async def update_space(
+        self,
+        space_id: str,
+        *,
+        name: str | None = None,
+        replace_labels: dict[str, str] | None = None,
+        merge_labels: dict[str, str] | None = None,
+        public_read: bool | None = None,
+    ) -> dict[str, Any]:
+        """Update an existing space.
+
+        The server accepts ``name``, ``publicRead``, ``replaceLabels`` (full
+        replacement of the labels map), and ``mergeLabels`` (per-key upsert).
+        """
+        payload: dict[str, Any] = {}
+        if name is not None:
+            payload["name"] = name
+        if replace_labels is not None:
+            payload["replaceLabels"] = replace_labels
+        if merge_labels is not None:
+            payload["mergeLabels"] = merge_labels
+        if public_read is not None:
+            payload["publicRead"] = public_read
+        if not payload:
+            return {"success": False, "error": "No fields provided to update."}
+
+        resp = await self._http.put(f"/v1/spaces/{space_id}", json=payload)
+        resp.raise_for_status()
+        return {
+            "success": True,
+            "spaceId": space_id,
+            "space": resp.json(),
+            "message": "Space updated successfully",
+        }
+
+    async def delete_space(self, space_id: str) -> dict[str, Any]:
+        """Delete a space by ID."""
+        resp = await self._http.delete(f"/v1/spaces/{space_id}")
+        resp.raise_for_status()
+        return {"success": True, "spaceId": space_id, "message": "Space deleted successfully"}
+
+    # -- Embedders -------------------------------------------------------------
+
+    async def list_embedders(self) -> list[dict[str, Any]]:
+        """List available embedder models."""
+        resp = await self._http.get("/v1/embedders")
+        resp.raise_for_status()
+        body = resp.json()
+        return body if isinstance(body, list) else body.get("embedders", [])
+
+    # -- Memories --------------------------------------------------------------
+
+    async def list_memories(
+        self,
+        space_id: str,
+        *,
+        page_size: int | None = None,
+        next_token: str | None = None,
+    ) -> dict[str, Any]:
+        """List memories in a space."""
+        params: dict[str, Any] = {}
+        if page_size is not None:
+            params["pageSize"] = page_size
+        if next_token:
+            params["nextToken"] = next_token
+
+        resp = await self._http.get(f"/v1/spaces/{space_id}/memories", params=params)
+        resp.raise_for_status()
+        body = resp.json()
+        return {
+            "success": True,
+            "spaceId": space_id,
+            "memories": body.get("memories", []) if isinstance(body, dict) else body,
+            "nextToken": body.get("nextToken") if isinstance(body, dict) else None,
+        }
+
+
+    async def create_memory(
+        self,
+        space_id: str,
+        *,
+        text_content: str | None = None,
+        file_path: str | None = None,
+        file_bytes: bytes | None = None,
+        file_extension: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Create a memory from text or a file (binary uploaded as base64).
+
+        Exactly one of *text_content* or *file_path*/*file_bytes* must be provided.
+        """
+        payload: dict[str, Any] = {"spaceId": space_id}
+
+        if file_path is not None:
+            ext = file_path.rsplit(".", 1)[-1] if "." in file_path else ""
+            mime = _guess_mime(ext)
+            with open(file_path, "rb") as fh:
+                raw = fh.read()
+            if mime.startswith("text/"):
+                payload["contentType"] = mime
+                payload["originalContent"] = raw.decode("utf-8", errors="replace")
+            else:
+                payload["contentType"] = mime
+                payload["originalContentB64"] = base64.b64encode(raw).decode()
+        elif file_bytes is not None:
+            ext = file_extension or ""
+            mime = _guess_mime(ext)
+            if mime.startswith("text/"):
+                payload["contentType"] = mime
+                payload["originalContent"] = file_bytes.decode("utf-8", errors="replace")
+            else:
+                payload["contentType"] = mime
+                payload["originalContentB64"] = base64.b64encode(file_bytes).decode()
+        elif text_content is not None:
+            payload["contentType"] = "text/plain"
+            payload["originalContent"] = text_content
+        else:
+            raise ValueError("No content provided. Supply text_content, file_path, or file_bytes.")
+
+        if metadata:
+            payload["metadata"] = metadata
+
+        resp = await self._http.post("/v1/memories", json=payload)
+        resp.raise_for_status()
+        data = resp.json()
+        return {
+            "success": True,
+            "memoryId": data.get("memoryId"),
+            "spaceId": data.get("spaceId"),
+            "status": data.get("processingStatus", "PENDING"),
+            "contentType": payload["contentType"],
+            "message": "Memory created successfully",
+        }
+
+    async def retrieve_memories(
+        self,
+        query: str,
+        space_ids: list[str],
+        *,
+        max_results: int = 5,
+        include_memory_definition: bool = True,
+        wait_for_indexing: bool = True,
+        reranker_id: str | None = None,
+        llm_id: str | None = None,
+        relevance_threshold: float | None = None,
+        llm_temperature: float | None = None,
+        chronological_resort: bool = False,
+    ) -> dict[str, Any]:
+        """Retrieve memories via semantic search."""
+        space_keys = [{"spaceId": sid} for sid in space_ids if sid]
+        if not space_keys:
+            return {"success": False, "error": "At least one space must be provided."}
+
+        payload: dict[str, Any] = {
+            "message": query,
+            "spaceKeys": space_keys,
+            "requestedSize": max_results,
+            "fetchMemory": include_memory_definition,
+        }
+
+        if reranker_id or llm_id:
+            config: dict[str, Any] = {}
+            if reranker_id:
+                config["reranker_id"] = reranker_id
+            if llm_id:
+                config["llm_id"] = llm_id
+            if relevance_threshold is not None:
+                config["relevance_threshold"] = relevance_threshold
+            if llm_temperature is not None:
+                config["llm_temp"] = llm_temperature
+            if max_results:
+                config["max_results"] = max_results
+            if chronological_resort:
+                config["chronological_resort"] = True
+            payload["postProcessor"] = {
+                "name": "com.goodmem.retrieval.postprocess.ChatPostProcessorFactory",
+                "config": config,
+            }
+
+        max_wait = 60.0 if wait_for_indexing else 0.0
+        poll_interval = 0.5
+        should_wait = wait_for_indexing
+        start = time.monotonic()
+
+        while True:
+            headers = {
+                "X-API-Key": self._api_key,
+                "Content-Type": "application/json",
+                "Accept": "application/x-ndjson",
+            }
+            resp = await self._http.post("/v1/memories:retrieve", json=payload, headers=headers)
+            resp.raise_for_status()
+
+            results, memories, result_set_id, abstract_reply = self._parse_ndjson(resp.text)
+
+            result: dict[str, Any] = {
+                "success": True,
+                "resultSetId": result_set_id,
+                "results": results,
+                "memories": memories,
+                "totalResults": len(results),
+                "query": query,
+            }
+            if abstract_reply:
+                result["abstractReply"] = abstract_reply
+
+            if results or not should_wait:
+                return result
+
+            elapsed = time.monotonic() - start
+            if elapsed >= max_wait:
+                result["message"] = "No results found after waiting 60 seconds for indexing. Memories may still be processing."
+                return result
+
+            import asyncio
+            await asyncio.sleep(poll_interval)
+
+    async def get_memory(self, memory_id: str, *, include_content: bool = True) -> dict[str, Any]:
+        """Fetch a single memory by ID."""
+        resp = await self._http.get(f"/v1/memories/{memory_id}")
+        resp.raise_for_status()
+        result: dict[str, Any] = {"success": True, "memory": resp.json()}
+
+        if include_content:
+            try:
+                content_resp = await self._http.get(f"/v1/memories/{memory_id}/content")
+                content_resp.raise_for_status()
+                # The content endpoint may return raw text or JSON depending on content type
+                try:
+                    result["content"] = content_resp.json()
+                except Exception:
+                    result["content"] = content_resp.text
+            except Exception as exc:
+                result["contentError"] = f"Failed to fetch content: {exc}"
+
+        return result
+
+    async def delete_memory(self, memory_id: str) -> dict[str, Any]:
+        """Delete a memory by ID."""
+        resp = await self._http.delete(f"/v1/memories/{memory_id}")
+        resp.raise_for_status()
+        return {"success": True, "memoryId": memory_id, "message": "Memory deleted successfully"}
+
+    # -- Helpers ---------------------------------------------------------------
+
+    @staticmethod
+    def _parse_ndjson(text: str) -> tuple[list[dict[str, Any]], list[dict[str, Any]], str, dict[str, Any] | None]:
+        """Parse NDJSON / SSE response from the retrieve endpoint."""
+        results: list[dict[str, Any]] = []
+        memories: list[dict[str, Any]] = []
+        result_set_id = ""
+        abstract_reply: dict[str, Any] | None = None
+
+        for line in text.strip().split("\n"):
+            json_str = line.strip()
+            if not json_str:
+                continue
+            if json_str.startswith("data:"):
+                json_str = json_str[5:].strip()
+            if json_str.startswith("event:") or not json_str:
+                continue
+            try:
+                item = json.loads(json_str)
+            except json.JSONDecodeError:
+                continue
+
+            if "resultSetBoundary" in item:
+                result_set_id = item["resultSetBoundary"].get("resultSetId", "")
+            elif "memoryDefinition" in item:
+                memories.append(item["memoryDefinition"])
+            elif "abstractReply" in item:
+                abstract_reply = item["abstractReply"]
+            elif "retrievedItem" in item:
+                chunk = item["retrievedItem"].get("chunk", {})
+                inner = chunk.get("chunk", {})
+                results.append({
+                    "chunkId": inner.get("chunkId"),
+                    "chunkText": inner.get("chunkText"),
+                    "memoryId": inner.get("memoryId"),
+                    "relevanceScore": chunk.get("relevanceScore"),
+                    "memoryIndex": chunk.get("memoryIndex"),
+                })
+
+        return results, memories, result_set_id, abstract_reply

agent_framework_goodmem/_context_provider.py

@@ -0,0 +1,195 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""GoodMem context provider using BaseContextProvider.
+
+This module provides ``GoodMemContextProvider``, built on the
+:class:`BaseContextProvider` hooks pattern.  It automatically retrieves
+relevant memories before each agent run and optionally stores
+conversations after.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from agent_framework import Message
+from agent_framework._sessions import AgentSession, SessionContext
+
+try:
+    # agent-framework-core >= 1.2 renamed BaseContextProvider -> ContextProvider.
+    from agent_framework._sessions import ContextProvider as _BaseContextProvider
+except ImportError:  # pragma: no cover - older versions
+    from agent_framework._sessions import BaseContextProvider as _BaseContextProvider  # type: ignore[no-redef]
+
+from ._client import GoodMemClient
+
+if TYPE_CHECKING:
+    from agent_framework._agents import SupportsAgentRun
+
+logger = logging.getLogger(__name__)
+
+
+class GoodMemContextProvider(_BaseContextProvider):
+    """GoodMem context provider using the BaseContextProvider hooks pattern.
+
+    Integrates GoodMem for persistent semantic memory, automatically
+    searching for relevant memories before each agent run and optionally
+    storing conversations after.
+
+    Two integration approaches are supported:
+
+    - **Automatic (context provider)** — attach this provider to an agent
+      via ``context_providers=[provider]``. Memories are retrieved and
+      stored transparently on every ``agent.run()`` call.
+    - **Tool-based** — use :func:`create_goodmem_tools` to let the agent
+      decide when to read/write memories via tool calls.
+
+    Args:
+        source_id: Unique identifier for this provider instance.
+        client: A configured :class:`GoodMemClient` instance.
+        space_id: The GoodMem space ID to search and store memories in.
+        max_results: Maximum number of memory chunks to retrieve per query.
+        context_prompt: Prompt prepended to retrieved memories in the context.
+        store_conversations: Whether to store input/response messages as
+            new memories after each run.
+        wait_for_indexing: Whether to wait for newly created memories to
+            be indexed before returning retrieval results.
+    """
+
+    DEFAULT_CONTEXT_PROMPT: ClassVar[str] = (
+        "## Relevant Memories\n"
+        "The following memories were retrieved from long-term storage "
+        "and may be relevant to the current conversation:"
+    )
+    DEFAULT_SOURCE_ID: ClassVar[str] = "goodmem"
+
+    def __init__(
+        self,
+        client: GoodMemClient,
+        space_id: str,
+        source_id: str = DEFAULT_SOURCE_ID,
+        *,
+        max_results: int = 5,
+        context_prompt: str | None = None,
+        store_conversations: bool = True,
+        wait_for_indexing: bool = False,
+    ) -> None:
+        """Initialize the GoodMem context provider.
+
+        Args:
+            client: A configured :class:`GoodMemClient` instance.
+            space_id: The GoodMem space ID to search and store memories in.
+            source_id: Unique identifier for this provider instance.
+            max_results: Maximum number of memory chunks to retrieve.
+            context_prompt: Prompt prepended to retrieved memories.
+            store_conversations: Whether to store conversations after each run.
+            wait_for_indexing: Whether to wait for indexing during retrieval.
+        """
+        super().__init__(source_id)
+        self.client = client
+        self.space_id = space_id
+        self.max_results = max_results
+        self.context_prompt = context_prompt or self.DEFAULT_CONTEXT_PROMPT
+        self.store_conversations = store_conversations
+        self.wait_for_indexing = wait_for_indexing
+
+    # -- Hooks pattern ---------------------------------------------------------
+
+    async def before_run(
+        self,
+        *,
+        agent: SupportsAgentRun,
+        session: AgentSession,
+        context: SessionContext,
+        state: dict[str, Any],
+    ) -> None:
+        """Search GoodMem for relevant memories and add to the session context.
+
+        Extracts text from the input messages, performs a semantic search
+        across the configured space, and injects matching chunks as a
+        user message so the model can reference them.
+        """
+        input_text = "\n".join(
+            msg.text for msg in context.input_messages if msg and msg.text and msg.text.strip()
+        )
+        if not input_text.strip():
+            return
+
+        try:
+            result = await self.client.retrieve_memories(
+                query=input_text,
+                space_ids=[self.space_id],
+                max_results=self.max_results,
+                wait_for_indexing=self.wait_for_indexing,
+            )
+        except Exception:
+            logger.warning("GoodMem retrieval failed", exc_info=True)
+            return
+
+        if not result.get("success"):
+            logger.warning("GoodMem retrieval returned unsuccessful: %s", result.get("error"))
+            return
+
+        chunks = result.get("results", [])
+        if not chunks:
+            return
+
+        memory_lines = [chunk.get("chunkText", "") for chunk in chunks if chunk.get("chunkText")]
+        if not memory_lines:
+            return
+
+        memory_text = "\n".join(memory_lines)
+        context.extend_messages(
+            self,
+            [Message(role="user", text=f"{self.context_prompt}\n{memory_text}")],
+        )
+
+    async def after_run(
+        self,
+        *,
+        agent: SupportsAgentRun,
+        session: AgentSession,
+        context: SessionContext,
+        state: dict[str, Any],
+    ) -> None:
+        """Store request/response messages to GoodMem for future retrieval.
+
+        Concatenates input and response messages into a single text block
+        and creates a new memory in the configured space.
+        """
+        if not self.store_conversations:
+            return
+
+        messages_to_store: list[Message] = list(context.input_messages)
+        if context.response and context.response.messages:
+            messages_to_store.extend(context.response.messages)
+
+        def _get_role(role: Any) -> str:
+            return role.value if hasattr(role, "value") else str(role)
+
+        lines: list[str] = [
+            f"{_get_role(msg.role)}: {msg.text}"
+            for msg in messages_to_store
+            if _get_role(msg.role) in {"user", "assistant", "system"} and msg.text and msg.text.strip()
+        ]
+
+        if not lines:
+            return
+
+        conversation_text = "\n".join(lines)
+
+        try:
+            await self.client.create_memory(
+                space_id=self.space_id,
+                text_content=conversation_text,
+                metadata={
+                    "source": "agent-framework-context-provider",
+                    "session_id": session.session_id,
+                },
+            )
+        except Exception:
+            logger.warning("GoodMem memory storage failed", exc_info=True)
+
+
+__all__ = ["GoodMemContextProvider"]

agent_framework_goodmem/_tools.py

@@ -0,0 +1,330 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""GoodMem tools for the Agent Framework.
+
+Each public function in this module is decorated with ``@tool`` so it can be
+passed directly to an ``Agent`` instance.  The functions are thin wrappers
+around :class:`GoodMemClient` that handle JSON serialization of results.
+
+All tools require a pre-configured ``GoodMemClient`` instance to be injected
+via :func:`create_goodmem_tools`.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated, Any
+
+from agent_framework import tool
+from pydantic import Field
+
+from ._client import GoodMemClient
+
+
+def create_goodmem_tools(client: GoodMemClient) -> list[Any]:
+    """Create a list of GoodMem ``FunctionTool`` instances bound to *client*.
+
+    Args:
+        client: A configured :class:`GoodMemClient` instance.
+
+    Returns:
+        A list of ``FunctionTool`` objects covering embedders, spaces (CRUD),
+        and memories (CRUD + retrieve).
+    """
+
+    # -- List Embedders --------------------------------------------------------
+
+    @tool(
+        name="goodmem_list_embedders",
+        description=(
+            "List the embedder models available on the GoodMem server. "
+            "Use the returned embedderId values when creating new spaces."
+        ),
+    )
+    async def goodmem_list_embedders() -> str:
+        """List available embedder models."""
+        try:
+            embedders = await client.list_embedders()
+            return json.dumps({"success": True, "embedders": embedders, "count": len(embedders)})
+        except Exception as exc:
+            return json.dumps({"success": False, "error": str(exc)})
+
+    # -- List Spaces -----------------------------------------------------------
+
+    @tool(
+        name="goodmem_list_spaces",
+        description="List all GoodMem spaces accessible to the current API key.",
+    )
+    async def goodmem_list_spaces() -> str:
+        """List all spaces."""
+        try:
+            spaces = await client.list_spaces()
+            return json.dumps({"success": True, "spaces": spaces, "count": len(spaces)}, default=str)
+        except Exception as exc:
+            return json.dumps({"success": False, "error": str(exc)})
+
+    # -- Get Space -------------------------------------------------------------
+
+    @tool(
+        name="goodmem_get_space",
+        description="Fetch the metadata for a specific GoodMem space by its ID.",
+    )
+    async def goodmem_get_space(
+        space_id: Annotated[str, Field(description="The UUID of the space to fetch.")],
+    ) -> str:
+        """Fetch a single space by ID."""
+        try:
+            result = await client.get_space(space_id)
+            return json.dumps(result, default=str)
+        except Exception as exc:
+            return json.dumps({"success": False, "error": str(exc)})
+
+    # -- Create Space ----------------------------------------------------------
+
+    @tool(
+        name="goodmem_create_space",
+        description=(
+            "Create a new GoodMem space or reuse an existing one. "
+            "A space is a logical container for organizing related memories, "
+            "configured with an embedder that converts text to vector embeddings."
+        ),
+    )
+    async def goodmem_create_space(
+        name: Annotated[str, Field(description="A unique name for the space. If a space with this name already exists, its ID will be returned instead of creating a duplicate.")],
+        embedder_id: Annotated[str, Field(description="The embedder ID that converts text into vector representations for similarity search. Use goodmem_list_embedders to find available IDs.")] = "",
+        chunk_size: Annotated[int, Field(description="Number of characters per chunk when splitting documents.")] = 256,
+        chunk_overlap: Annotated[int, Field(description="Number of overlapping characters between consecutive chunks.")] = 25,
+        keep_strategy: Annotated[str, Field(description="Where to attach the separator when splitting: KEEP_END, KEEP_START, or DISCARD.")] = "KEEP_END",
+        length_measurement: Annotated[str, Field(description="How chunk size is measured: CHARACTER_COUNT or TOKEN_COUNT.")] = "CHARACTER_COUNT",
+    ) -> str:
+        """Create a new GoodMem space or reuse an existing one."""
+        actual_embedder_id = embedder_id
+        if not actual_embedder_id:
+            embedders = await client.list_embedders()
+            if embedders:
+                actual_embedder_id = embedders[0].get("embedderId") or embedders[0].get("id", "")
+            if not actual_embedder_id:
+                return json.dumps({"success": False, "error": "No embedder_id provided and no embedders available on the server."})
+
+        try:
+            result = await client.create_space(
+                name=name,
+                embedder_id=actual_embedder_id,
+                chunk_size=chunk_size,
+                chunk_overlap=chunk_overlap,
+                keep_strategy=keep_strategy,
+                length_measurement=length_measurement,
+            )
+            return json.dumps(result)
+        except Exception as exc:
+            return json.dumps({"success": False, "error": str(exc)})
+
+    # -- Update Space ----------------------------------------------------------
+
+    @tool(
+        name="goodmem_update_space",
+        description="Update an existing GoodMem space's name, labels, or public_read flag.",
+    )
+    async def goodmem_update_space(
+        space_id: Annotated[str, Field(description="The UUID of the space to update.")],
+        name: Annotated[str, Field(description="Optional new name for the space.")] = "",
+        replace_labels_json: Annotated[str, Field(description="Optional JSON object that REPLACES all labels on the space.")] = "",
+        merge_labels_json: Annotated[str, Field(description="Optional JSON object whose entries are MERGED into existing labels (upsert per key).")] = "",
+        public_read: Annotated[bool, Field(description="If true, makes the space publicly readable. If false, restricts to the owner.")] = False,
+        set_public_read: Annotated[bool, Field(description="Whether to apply the public_read value (so the default `false` is not always sent).")] = False,
+    ) -> str:
+        """Update an existing GoodMem space."""
+
+        def _parse_labels(raw: str, field: str) -> dict[str, str] | None | str:
+            if not raw:
+                return None
+            try:
+                parsed = json.loads(raw)
+            except json.JSONDecodeError:
+                return f"{field} is not valid JSON."
+            if not isinstance(parsed, dict):
+                return f"{field} must decode to a JSON object."
+            return {str(k): str(v) for k, v in parsed.items()}
+
+        replace_labels = _parse_labels(replace_labels_json, "replace_labels_json")
+        if isinstance(replace_labels, str):
+            return json.dumps({"success": False, "error": replace_labels})
+        merge_labels = _parse_labels(merge_labels_json, "merge_labels_json")
+        if isinstance(merge_labels, str):
+            return json.dumps({"success": False, "error": merge_labels})
+
+        try:
+            result = await client.update_space(
+                space_id,
+                name=name or None,
+                replace_labels=replace_labels,
+                merge_labels=merge_labels,
+                public_read=public_read if set_public_read else None,
+            )
+            return json.dumps(result, default=str)
+        except Exception as exc:
+            return json.dumps({"success": False, "error": str(exc)})
+
+    # -- Delete Space ----------------------------------------------------------
+
+    @tool(
+        name="goodmem_delete_space",
+        description="Permanently delete a GoodMem space and all of its memories.",
+    )
+    async def goodmem_delete_space(
+        space_id: Annotated[str, Field(description="The UUID of the space to delete.")],
+    ) -> str:
+        """Delete a space by ID."""
+        try:
+            result = await client.delete_space(space_id)
+            return json.dumps(result)
+        except Exception as exc:
+            return json.dumps({"success": False, "error": str(exc)})
+
+    # -- Create Memory ---------------------------------------------------------
+
+    @tool(
+        name="goodmem_create_memory",
+        description=(
+            "Store a document as a new memory in a GoodMem space. "
+            "The memory is processed asynchronously -- chunked into searchable "
+            "pieces and embedded into vectors. Accepts plain text or a file path."
+        ),
+    )
+    async def goodmem_create_memory(
+        space_id: Annotated[str, Field(description="The ID of the space to store the memory in.")],
+        text_content: Annotated[str, Field(description="Plain text content to store as memory. Ignored when file_path is provided.")] = "",
+        file_path: Annotated[str, Field(description="Absolute path to a file to store as memory (PDF, DOCX, image, etc.). Takes priority over text_content.")] = "",
+        metadata_json: Annotated[str, Field(description="Optional JSON string of key-value metadata to attach to the memory.")] = "",
+    ) -> str:
+        """Store a document as a new memory in a GoodMem space."""
+        metadata: dict[str, Any] | None = None
+        if metadata_json:
+            try:
+                metadata = json.loads(metadata_json)
+            except json.JSONDecodeError:
+                return json.dumps({"success": False, "error": "metadata_json is not valid JSON."})
+
+        try:
+            result = await client.create_memory(
+                space_id=space_id,
+                text_content=text_content or None,
+                file_path=file_path or None,
+                metadata=metadata,
+            )
+            return json.dumps(result)
+        except Exception as exc:
+            return json.dumps({"success": False, "error": str(exc)})
+
+    # -- List Memories ---------------------------------------------------------
+
+    @tool(
+        name="goodmem_list_memories",
+        description="List the memories stored in a specific GoodMem space.",
+    )
+    async def goodmem_list_memories(
+        space_id: Annotated[str, Field(description="The UUID of the space whose memories should be listed.")],
+        page_size: Annotated[int, Field(description="Maximum number of memories to return in this page. 0 means use server default.")] = 0,
+        next_token: Annotated[str, Field(description="Pagination token returned from a previous call.")] = "",
+    ) -> str:
+        """List memories in a space."""
+        try:
+            result = await client.list_memories(
+                space_id,
+                page_size=page_size or None,
+                next_token=next_token or None,
+            )
+            return json.dumps(result, default=str)
+        except Exception as exc:
+            return json.dumps({"success": False, "error": str(exc)})
+
+    # -- Retrieve Memories -----------------------------------------------------
+
+    @tool(
+        name="goodmem_retrieve_memories",
+        description=(
+            "Perform similarity-based semantic retrieval across one or more "
+            "GoodMem spaces. Returns matching chunks ranked by relevance. "
+            "Supports optional reranker and LLM post-processing."
+        ),
+    )
+    async def goodmem_retrieve_memories(
+        query: Annotated[str, Field(description="A natural language query used to find semantically similar memory chunks.")],
+        space_ids: Annotated[str, Field(description="Comma-separated list of space IDs to search across.")],
+        max_results: Annotated[int, Field(description="Maximum number of results to return.")] = 5,
+        include_memory_definition: Annotated[bool, Field(description="Include full memory metadata alongside matched chunks.")] = True,
+        wait_for_indexing: Annotated[bool, Field(description="Retry for up to 60 seconds when no results are found (useful for recently added memories).")] = True,
+        reranker_id: Annotated[str, Field(description="Optional UUID of a reranker model to improve result ordering.")] = "",
+        llm_id: Annotated[str, Field(description="Optional UUID of an LLM to generate a contextual abstract reply.")] = "",
+        relevance_threshold: Annotated[float, Field(description="Minimum relevance score (0-1) for including a result. 0 disables.")] = 0.0,
+        llm_temperature: Annotated[float, Field(description="Creativity setting for the LLM post-processor (0-2). Negative disables.")] = -1.0,
+        chronological_resort: Annotated[bool, Field(description="If true, reorder results by memory creation time.")] = False,
+    ) -> str:
+        """Retrieve memories via semantic search."""
+        ids = [s.strip() for s in space_ids.split(",") if s.strip()]
+        try:
+            result = await client.retrieve_memories(
+                query=query,
+                space_ids=ids,
+                max_results=max_results,
+                include_memory_definition=include_memory_definition,
+                wait_for_indexing=wait_for_indexing,
+                reranker_id=reranker_id or None,
+                llm_id=llm_id or None,
+                relevance_threshold=relevance_threshold if relevance_threshold > 0 else None,
+                llm_temperature=llm_temperature if llm_temperature >= 0 else None,
+                chronological_resort=chronological_resort,
+            )
+            return json.dumps(result, default=str)
+        except Exception as exc:
+            return json.dumps({"success": False, "error": str(exc)})
+
+    # -- Get Memory ------------------------------------------------------------
+
+    @tool(
+        name="goodmem_get_memory",
+        description=(
+            "Fetch a specific memory record by its ID, including metadata, "
+            "processing status, and optionally the original content."
+        ),
+    )
+    async def goodmem_get_memory(
+        memory_id: Annotated[str, Field(description="The UUID of the memory to fetch.")],
+        include_content: Annotated[bool, Field(description="Also fetch the original document content.")] = True,
+    ) -> str:
+        """Fetch a specific memory by ID."""
+        try:
+            result = await client.get_memory(memory_id, include_content=include_content)
+            return json.dumps(result, default=str)
+        except Exception as exc:
+            return json.dumps({"success": False, "error": str(exc)})
+
+    # -- Delete Memory ---------------------------------------------------------
+
+    @tool(
+        name="goodmem_delete_memory",
+        description="Permanently delete a memory and its associated chunks and vector embeddings.",
+    )
+    async def goodmem_delete_memory(
+        memory_id: Annotated[str, Field(description="The UUID of the memory to delete.")],
+    ) -> str:
+        """Delete a memory by ID."""
+        try:
+            result = await client.delete_memory(memory_id)
+            return json.dumps(result)
+        except Exception as exc:
+            return json.dumps({"success": False, "error": str(exc)})
+
+    return [
+        goodmem_list_embedders,
+        goodmem_list_spaces,
+        goodmem_get_space,
+        goodmem_create_space,
+        goodmem_update_space,
+        goodmem_delete_space,
+        goodmem_create_memory,
+        goodmem_list_memories,
+        goodmem_retrieve_memories,
+        goodmem_get_memory,
+        goodmem_delete_memory,
+    ]

agent_framework_goodmem-0.1.0.dist-info/METADATA

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: agent-framework-goodmem
+Version: 0.1.0
+Summary: GoodMem integration for Microsoft Agent Framework.
+Author-email: GoodMem <support@goodmem.ai>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+License-File: LICENSE
+Requires-Dist: agent-framework-core>=1.0.0rc4
+Requires-Dist: httpx>=0.24.0,<1
+Requires-Dist: pydantic>=2.0,<3
+Requires-Dist: pytest>=7.0 ; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23 ; extra == "dev"
+Requires-Dist: pytest-timeout ; extra == "dev"
+Requires-Dist: build ; extra == "dev"
+Requires-Dist: twine ; extra == "dev"
+Project-URL: homepage, https://github.com/bashareid/goodmem_agent-framework
+Project-URL: issues, https://github.com/bashareid/goodmem_agent-framework/issues
+Project-URL: source, https://github.com/bashareid/goodmem_agent-framework
+Provides-Extra: dev
+
+# agent-framework-goodmem
+
+[GoodMem](https://goodmem.ai) integration for the
+[Microsoft Agent Framework](https://github.com/microsoft/agent-framework).
+
+This package gives Agent Framework agents persistent, semantic long-term memory
+backed by a GoodMem server. It exposes:
+
+- **`GoodMemClient`** — an async REST client for the GoodMem v1 API.
+- **`GoodMemContextProvider`** — a `BaseContextProvider` that automatically
+  retrieves relevant memories before each agent run and stores conversations
+  afterwards.
+- **`create_goodmem_tools`** — a factory that returns ready-to-use function
+  tools so the model itself can manage spaces and memories.
+
+## Installation
+
+```bash
+pip install agent-framework-goodmem
+```
+
+For local development:
+
+```bash
+pip install -e .
+```
+
+## Quickstart
+
+```python
+import asyncio
+from agent_framework_goodmem import GoodMemClient, create_goodmem_tools
+
+async def main():
+    client = GoodMemClient(
+        base_url="https://localhost:8080",
+        api_key="gm_xxxxxxxxxxxxxxxxxxxxxxxx",
+        verify_ssl=False,  # self-signed local server
+    )
+
+    embedders = await client.list_embedders()
+    embedder_id = embedders[0]["embedderId"]
+
+    space = await client.create_space(name="quickstart", embedder_id=embedder_id)
+    space_id = space["spaceId"]
+
+    await client.create_memory(
+        space_id=space_id,
+        text_content="The capital of France is Paris.",
+    )
+
+    results = await client.retrieve_memories(
+        query="What is the capital of France?",
+        space_ids=[space_id],
+        max_results=3,
+        wait_for_indexing=True,
+    )
+    print(results)
+
+    await client.close()
+
+asyncio.run(main())
+```
+
+## Available tools
+
+`create_goodmem_tools(client)` returns the following 11 function tools:
+
+| Tool | Description |
+|------|-------------|
+| `goodmem_list_embedders` | List embedder models available on the server |
+| `goodmem_list_spaces` | List all spaces accessible to the API key |
+| `goodmem_get_space` | Fetch a space by ID |
+| `goodmem_create_space` | Create a space (idempotent by name) |
+| `goodmem_update_space` | Update a space's name/labels/visibility |
+| `goodmem_delete_space` | Delete a space |
+| `goodmem_create_memory` | Store text or a file as a memory |
+| `goodmem_list_memories` | List memories in a space |
+| `goodmem_retrieve_memories` | Semantic retrieval, with optional reranker/LLM |
+| `goodmem_get_memory` | Fetch a memory by ID (with original content) |
+| `goodmem_delete_memory` | Delete a memory |
+
+### Retrieval options
+
+`goodmem_retrieve_memories` (and `GoodMemClient.retrieve_memories`) accept the
+GoodMem post-processor parameters:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `reranker_id` | UUID | Reranker model to improve result ordering |
+| `llm_id` | UUID | LLM used to generate a contextual abstract reply |
+| `relevance_threshold` | 0–1 | Minimum score for including a result |
+| `llm_temperature` | 0–2 | Creativity for the LLM post-processor |
+| `max_results` | int | Cap on returned chunks |
+| `chronological_resort` | bool | Reorder results by memory creation time |
+
+## Context provider
+
+```python
+from agent_framework import Agent
+from agent_framework.openai import OpenAIChatClient
+from agent_framework_goodmem import GoodMemClient, GoodMemContextProvider
+
+client = GoodMemClient(base_url="https://localhost:8080", api_key="gm_...", verify_ssl=False)
+
+provider = GoodMemContextProvider(
+    client=client,
+    space_id=space_id,
+    max_results=5,
+    store_conversations=True,
+)
+
+agent = Agent(
+    client=OpenAIChatClient(model="gpt-4o"),
+    name="memory-agent",
+    instructions="You are a helpful assistant with persistent memory.",
+    context_providers=[provider],
+)
+```
+
+## Running the integration tests
+
+```bash
+export GOODMEM_API_KEY=gm_xxxxxxxxxxxxxxxxxxxxxxxx
+export GOODMEM_BASE_URL=https://localhost:8080
+pip install -e ".[dev]"
+pytest -m integration -v tests/test_goodmem_integration.py
+```
+

agent_framework_goodmem-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+agent_framework_goodmem/__init__.py,sha256=Vi1zByGjJHUfSb223Rz72gYBW5mweYhIgzAbopOxPeA,1377
+agent_framework_goodmem/_client.py,sha256=MKVE-nTD35MeWJsrc76ueB0pqYPnW1O0v1kB_na61Og,15959
+agent_framework_goodmem/_context_provider.py,sha256=EClXl3v3UgwgP601_RIRnrEMNc-6Pv9nFOFGkkskPKw,7105
+agent_framework_goodmem/_tools.py,sha256=MZoEcnHvo6AimCXD0DG8zGekZugsMPl2GxFvaB3OT_k,15407
+agent_framework_goodmem/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agent_framework_goodmem-0.1.0.dist-info/licenses/LICENSE,sha256=ffINzfkZfplFwUhY1Bxg8RtSuT5baeK2NBa4dNWY0yI,1074
+agent_framework_goodmem-0.1.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+agent_framework_goodmem-0.1.0.dist-info/METADATA,sha256=7_jruaHkix2JT3bFdcae7s6ymFZhgUkie_Z9jEwGIEA,5210
+agent_framework_goodmem-0.1.0.dist-info/RECORD,,

agent_framework_goodmem-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: flit 3.12.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_framework_goodmem-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Microsoft Corporation.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.