autogen-goodmem 0.1.0__tar.gz

autogen_goodmem-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: autogen-goodmem
+Version: 0.1.0
+Summary: GoodMem memory and tools for the AutoGen agent framework.
+Keywords: autogen,goodmem,memory,rag,agents,llm
+Author: PAIR Systems
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Dist: autogen-core>=0.7.5
+Requires-Dist: httpx>=0.24.0,<1
+Requires-Dist: pydantic>=2.0,<3
+Requires-Dist: typing-extensions>=4.7
+Requires-Dist: pytest>=7 ; 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/PAIR-Systems-Inc/autogen-goodmem
+Project-URL: Issues, https://github.com/PAIR-Systems-Inc/autogen-goodmem/issues
+Project-URL: Repository, https://github.com/PAIR-Systems-Inc/autogen-goodmem
+Provides-Extra: dev
+
+# autogen-goodmem
+
+[GoodMem](https://goodmem.ai) memory and tools for the [AutoGen](https://github.com/microsoft/autogen) agent framework.
+
+`autogen-goodmem` gives an AutoGen agent two things:
+
+1. **`GoodMemContextProvider`** — an `autogen_core.memory.Memory` implementation backed by a GoodMem space, so context retrieval is automatic on every turn.
+2. **`create_goodmem_tools(client)`** — 11 `FunctionTool`s the agent can call directly to manage spaces and memories.
+
+## Install
+
+```bash
+pip install autogen-goodmem
+```
+
+## Quickstart
+
+### As an AutoGen `Memory`
+
+```python
+import asyncio
+from autogen_core.memory import MemoryContent, MemoryMimeType
+from autogen_goodmem import GoodMemContextProvider, GoodMemMemoryConfig
+
+
+async def main() -> None:
+    provider = GoodMemContextProvider(
+        config=GoodMemMemoryConfig(
+            base_url="https://localhost:8080",
+            api_key="gm_...",
+            space_name="my-kb",
+            embedder_id="<embedder-uuid>",
+            verify_ssl=False,
+        )
+    )
+    await provider.add(MemoryContent(content="The capital of France is Paris.", mime_type=MemoryMimeType.TEXT))
+    results = await provider.query("What is the capital of France?")
+    for r in results.results:
+        print(r.content)
+    await provider.close()
+
+
+asyncio.run(main())
+```
+
+### As tools on an agent
+
+```python
+from autogen_goodmem import GoodMemClient, create_goodmem_tools
+
+client = GoodMemClient(base_url="https://localhost:8080", api_key="gm_...", verify_ssl=False)
+tools = create_goodmem_tools(client)  # 11 FunctionTools
+# pass `tools=tools` to your AssistantAgent
+```
+
+## Tool surface
+
+`create_goodmem_tools(client)` returns these 11 tools in order:
+
+| Tool | Purpose |
+| --- | --- |
+| `goodmem_list_embedders` | List embedder models available on the server. |
+| `goodmem_list_spaces` | List all spaces visible to the API key. |
+| `goodmem_get_space` | Fetch one space by ID. |
+| `goodmem_create_space` | Create a space (idempotent by name). |
+| `goodmem_update_space` | Update name / publicRead / labels / chunking. |
+| `goodmem_delete_space` | Delete a space and everything in it. |
+| `goodmem_create_memory` | Add a memory from text or a local file. |
+| `goodmem_list_memories` | Paginated listing of a space's memories. |
+| `goodmem_retrieve_memories` | Semantic retrieval, optional reranker + LLM. |
+| `goodmem_get_memory` | Fetch a memory's metadata and original content. |
+| `goodmem_delete_memory` | Delete a memory and its embeddings. |
+
+`goodmem_retrieve_memories` (and `GoodMemClient.retrieve_memories`) accept the optional post-processor params: `reranker_id`, `llm_id`, `relevance_threshold` (0-1), `llm_temperature` (0-2), `max_results`, `chronological_resort`.
+
+## Integration tests
+
+The tests in `tests/test_goodmem_integration.py` exercise every public method against a live GoodMem server. They are opt-in via the `integration` marker.
+
+```bash
+pip install -e ".[dev]"
+
+export GOODMEM_API_KEY=gm_...
+export GOODMEM_BASE_URL=https://localhost:8080
+export GOODMEM_EMBEDDER_ID=<uuid>
+export GOODMEM_RERANKER_ID=<uuid>
+export GOODMEM_LLM_ID=<uuid>
+export GOODMEM_PDF_PATH=/path/to/sample.pdf   # optional
+
+python -m pytest tests/test_goodmem_integration.py -v -s -m integration
+```
+
+## License
+
+MIT
+

autogen_goodmem-0.1.0/README.md

@@ -0,0 +1,95 @@
+# autogen-goodmem
+
+[GoodMem](https://goodmem.ai) memory and tools for the [AutoGen](https://github.com/microsoft/autogen) agent framework.
+
+`autogen-goodmem` gives an AutoGen agent two things:
+
+1. **`GoodMemContextProvider`** — an `autogen_core.memory.Memory` implementation backed by a GoodMem space, so context retrieval is automatic on every turn.
+2. **`create_goodmem_tools(client)`** — 11 `FunctionTool`s the agent can call directly to manage spaces and memories.
+
+## Install
+
+```bash
+pip install autogen-goodmem
+```
+
+## Quickstart
+
+### As an AutoGen `Memory`
+
+```python
+import asyncio
+from autogen_core.memory import MemoryContent, MemoryMimeType
+from autogen_goodmem import GoodMemContextProvider, GoodMemMemoryConfig
+
+
+async def main() -> None:
+    provider = GoodMemContextProvider(
+        config=GoodMemMemoryConfig(
+            base_url="https://localhost:8080",
+            api_key="gm_...",
+            space_name="my-kb",
+            embedder_id="<embedder-uuid>",
+            verify_ssl=False,
+        )
+    )
+    await provider.add(MemoryContent(content="The capital of France is Paris.", mime_type=MemoryMimeType.TEXT))
+    results = await provider.query("What is the capital of France?")
+    for r in results.results:
+        print(r.content)
+    await provider.close()
+
+
+asyncio.run(main())
+```
+
+### As tools on an agent
+
+```python
+from autogen_goodmem import GoodMemClient, create_goodmem_tools
+
+client = GoodMemClient(base_url="https://localhost:8080", api_key="gm_...", verify_ssl=False)
+tools = create_goodmem_tools(client)  # 11 FunctionTools
+# pass `tools=tools` to your AssistantAgent
+```
+
+## Tool surface
+
+`create_goodmem_tools(client)` returns these 11 tools in order:
+
+| Tool | Purpose |
+| --- | --- |
+| `goodmem_list_embedders` | List embedder models available on the server. |
+| `goodmem_list_spaces` | List all spaces visible to the API key. |
+| `goodmem_get_space` | Fetch one space by ID. |
+| `goodmem_create_space` | Create a space (idempotent by name). |
+| `goodmem_update_space` | Update name / publicRead / labels / chunking. |
+| `goodmem_delete_space` | Delete a space and everything in it. |
+| `goodmem_create_memory` | Add a memory from text or a local file. |
+| `goodmem_list_memories` | Paginated listing of a space's memories. |
+| `goodmem_retrieve_memories` | Semantic retrieval, optional reranker + LLM. |
+| `goodmem_get_memory` | Fetch a memory's metadata and original content. |
+| `goodmem_delete_memory` | Delete a memory and its embeddings. |
+
+`goodmem_retrieve_memories` (and `GoodMemClient.retrieve_memories`) accept the optional post-processor params: `reranker_id`, `llm_id`, `relevance_threshold` (0-1), `llm_temperature` (0-2), `max_results`, `chronological_resort`.
+
+## Integration tests
+
+The tests in `tests/test_goodmem_integration.py` exercise every public method against a live GoodMem server. They are opt-in via the `integration` marker.
+
+```bash
+pip install -e ".[dev]"
+
+export GOODMEM_API_KEY=gm_...
+export GOODMEM_BASE_URL=https://localhost:8080
+export GOODMEM_EMBEDDER_ID=<uuid>
+export GOODMEM_RERANKER_ID=<uuid>
+export GOODMEM_LLM_ID=<uuid>
+export GOODMEM_PDF_PATH=/path/to/sample.pdf   # optional
+
+python -m pytest tests/test_goodmem_integration.py -v -s -m integration
+```
+
+## License
+
+MIT

autogen_goodmem-0.1.0/autogen_goodmem/__init__.py

@@ -0,0 +1,24 @@
+"""autogen-goodmem: GoodMem memory + tools for the AutoGen agent framework."""
+
+from ._client import GoodMemClient
+from ._config import ChunkingConfig, GoodMemMemoryConfig, PostProcessorConfig
+from ._context_provider import GoodMemContextProvider
+from ._tools import TOOL_NAMES, create_goodmem_tools
+
+# Backwards-compatible alias for code that imported GoodMemMemory from the
+# autogen-ext monorepo location.
+GoodMemMemory = GoodMemContextProvider
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "GoodMemClient",
+    "GoodMemContextProvider",
+    "GoodMemMemory",
+    "GoodMemMemoryConfig",
+    "ChunkingConfig",
+    "PostProcessorConfig",
+    "create_goodmem_tools",
+    "TOOL_NAMES",
+    "__version__",
+]

autogen_goodmem-0.1.0/autogen_goodmem/_client.py

@@ -0,0 +1,500 @@
+"""Pure-async REST client for the GoodMem v1 API.
+
+This client is framework-agnostic: it returns plain dictionaries (and lists of
+them) and never imports anything from AutoGen. :class:`GoodMemContextProvider`
+and :func:`create_goodmem_tools` are built on top of it.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import logging
+import mimetypes
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+import httpx
+
+from ._config import ChunkingConfig, PostProcessorConfig
+
+logger = logging.getLogger(__name__)
+
+
+# ── MIME type detection ─────────────────────────────────────────────────
+
+_EXTRA_MIME: Dict[str, str] = {
+    ".md": "text/markdown",
+    ".pdf": "application/pdf",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+}
+
+
+def _guess_mime(path: Path) -> str:
+    mime, _ = mimetypes.guess_type(path.name)
+    if mime:
+        return mime
+    return _EXTRA_MIME.get(path.suffix.lower(), "application/octet-stream")
+
+
+# ── Retrieve-response NDJSON/SSE parser ────────────────────────────────
+
+
+def _parse_retrieve_response(
+    response_text: str,
+) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]], Any]:
+    """Parse the NDJSON / SSE body returned by ``POST /v1/memories:retrieve``.
+
+    Returns ``(results, memories, abstract_reply)`` where ``results`` is a list
+    of ``{chunkId, chunkText, memoryId, relevanceScore, memoryIndex}`` dicts.
+    """
+    results: List[Dict[str, Any]] = []
+    memories: List[Dict[str, Any]] = []
+    abstract_reply: Any = None
+
+    for raw_line in response_text.splitlines():
+        line = raw_line.strip()
+        if not line:
+            continue
+        if line.startswith("event:"):
+            continue
+        if line.startswith("data:"):
+            line = line[5:].strip()
+        if not line:
+            continue
+        try:
+            item = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+
+        if item.get("memoryDefinition"):
+            memories.append(item["memoryDefinition"])
+        elif item.get("abstractReply"):
+            abstract_reply = item["abstractReply"]
+        elif item.get("retrievedItem"):
+            chunk_outer = item["retrievedItem"].get("chunk", {})
+            chunk = chunk_outer.get("chunk", {})
+            results.append(
+                {
+                    "chunkId": chunk.get("chunkId"),
+                    "chunkText": chunk.get("chunkText"),
+                    "memoryId": chunk.get("memoryId"),
+                    "relevanceScore": chunk_outer.get("relevanceScore"),
+                    "memoryIndex": chunk_outer.get("memoryIndex"),
+                }
+            )
+
+    return results, memories, abstract_reply
+
+
+# ── Client ──────────────────────────────────────────────────────────────
+
+
+class GoodMemClient:
+    """Async REST client for the GoodMem v1 API.
+
+    Args:
+        base_url: Base URL, e.g. ``https://localhost:8080``.
+        api_key: API key sent as the ``X-API-Key`` header.
+        verify_ssl: Pass ``False`` for self-signed local servers.
+        timeout: Per-request timeout (seconds).
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        *,
+        verify_ssl: bool = True,
+        timeout: float = 120.0,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self._verify_ssl = verify_ssl
+        self._timeout = timeout
+        self._headers = {
+            "X-API-Key": api_key,
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+        self._client: Optional[httpx.AsyncClient] = None
+
+    # ── Lifecycle ──────────────────────────────────────────────────────
+
+    def _ensure_client(self) -> httpx.AsyncClient:
+        if self._client is None or self._client.is_closed:
+            self._client = httpx.AsyncClient(timeout=self._timeout, verify=self._verify_ssl)
+        return self._client
+
+    async def close(self) -> None:
+        if self._client and not self._client.is_closed:
+            await self._client.aclose()
+        self._client = None
+
+    async def __aenter__(self) -> "GoodMemClient":
+        self._ensure_client()
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        await self.close()
+
+    # ── Embedders ──────────────────────────────────────────────────────
+
+    async def list_embedders(self) -> List[Dict[str, Any]]:
+        """``GET /v1/embedders`` -> list of embedder definitions."""
+        client = self._ensure_client()
+        resp = await client.get(f"{self._base_url}/v1/embedders", headers=self._headers)
+        resp.raise_for_status()
+        body = resp.json()
+        return body if isinstance(body, list) else body.get("embedders", [])
+
+    # ── Spaces ─────────────────────────────────────────────────────────
+
+    async def list_spaces(self) -> List[Dict[str, Any]]:
+        """``GET /v1/spaces`` -> list of spaces."""
+        client = self._ensure_client()
+        resp = await client.get(f"{self._base_url}/v1/spaces", headers=self._headers)
+        resp.raise_for_status()
+        body = resp.json()
+        return body if isinstance(body, list) else body.get("spaces", [])
+
+    async def get_space(self, space_id: str) -> Dict[str, Any]:
+        """``GET /v1/spaces/{id}``."""
+        client = self._ensure_client()
+        resp = await client.get(f"{self._base_url}/v1/spaces/{space_id}", headers=self._headers)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def create_space(
+        self,
+        name: str,
+        embedder_id: str,
+        *,
+        chunking: Optional[ChunkingConfig] = None,
+    ) -> Dict[str, Any]:
+        """Create a space, or reuse an existing one with the same name.
+
+        Returns a dict that includes ``reused: True`` when a name collision was
+        found. Handles a race condition where ``POST /v1/spaces`` returns 409
+        between the list-check and the create call.
+        """
+        chunking = chunking or ChunkingConfig()
+        client = self._ensure_client()
+
+        try:
+            existing = await self.list_spaces()
+            for space in existing:
+                if space.get("name") == name:
+                    sid = space.get("spaceId") or space.get("id")
+                    return {
+                        "spaceId": sid,
+                        "name": name,
+                        "embedderId": embedder_id,
+                        "reused": True,
+                    }
+        except Exception:
+            logger.debug("list_spaces failed before create; will attempt create anyway", exc_info=True)
+
+        body = {
+            "name": name,
+            "spaceEmbedders": [{"embedderId": embedder_id, "defaultRetrievalWeight": 1.0}],
+            "defaultChunkingConfig": {
+                "recursive": {
+                    "chunkSize": chunking.chunk_size,
+                    "chunkOverlap": chunking.chunk_overlap,
+                    "separators": chunking.separators,
+                    "keepStrategy": chunking.keep_strategy,
+                    "separatorIsRegex": chunking.separator_is_regex,
+                    "lengthMeasurement": chunking.length_measurement,
+                },
+            },
+        }
+        resp = await client.post(
+            f"{self._base_url}/v1/spaces",
+            headers=self._headers,
+            json=body,
+        )
+        if resp.status_code == 409:
+            # Race: someone else just created it. Re-list and find by name.
+            for space in await self.list_spaces():
+                if space.get("name") == name:
+                    sid = space.get("spaceId") or space.get("id")
+                    return {
+                        "spaceId": sid,
+                        "name": name,
+                        "embedderId": embedder_id,
+                        "reused": True,
+                    }
+            resp.raise_for_status()
+
+        resp.raise_for_status()
+        result = resp.json()
+        return {
+            "spaceId": result.get("spaceId") or result.get("id"),
+            "name": result.get("name", name),
+            "embedderId": embedder_id,
+            "chunkingConfig": body["defaultChunkingConfig"],
+            "reused": False,
+        }
+
+    async def update_space(
+        self,
+        space_id: str,
+        *,
+        name: Optional[str] = None,
+        public_read: Optional[bool] = None,
+        replace_labels: Optional[Dict[str, str]] = None,
+        merge_labels: Optional[Dict[str, str]] = None,
+        chunking: Optional[ChunkingConfig] = None,
+    ) -> Dict[str, Any]:
+        """``PUT /v1/spaces/{id}`` with only the fields the API accepts.
+
+        Note: the server rejects a bare ``labels`` field with 400 — use
+        ``replace_labels`` (full replacement) or ``merge_labels`` (additive).
+        """
+        body: Dict[str, Any] = {}
+        if name is not None:
+            body["name"] = name
+        if public_read is not None:
+            body["publicRead"] = public_read
+        if replace_labels is not None:
+            body["replaceLabels"] = replace_labels
+        if merge_labels is not None:
+            body["mergeLabels"] = merge_labels
+        if chunking is not None:
+            body["defaultChunkingConfig"] = {
+                "recursive": {
+                    "chunkSize": chunking.chunk_size,
+                    "chunkOverlap": chunking.chunk_overlap,
+                    "separators": chunking.separators,
+                    "keepStrategy": chunking.keep_strategy,
+                    "separatorIsRegex": chunking.separator_is_regex,
+                    "lengthMeasurement": chunking.length_measurement,
+                },
+            }
+
+        client = self._ensure_client()
+        resp = await client.put(
+            f"{self._base_url}/v1/spaces/{space_id}",
+            headers=self._headers,
+            json=body,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    async def delete_space(self, space_id: str) -> Dict[str, Any]:
+        """``DELETE /v1/spaces/{id}``."""
+        client = self._ensure_client()
+        resp = await client.delete(
+            f"{self._base_url}/v1/spaces/{space_id}",
+            headers=self._headers,
+        )
+        resp.raise_for_status()
+        return {"spaceId": space_id, "success": True}
+
+    # ── Memories ───────────────────────────────────────────────────────
+
+    async def create_memory(
+        self,
+        *,
+        space_id: str,
+        content: Optional[str] = None,
+        file_path: Optional[str] = None,
+        content_type: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Create a memory from text or a file.
+
+        Exactly one of ``content`` (inline text) or ``file_path`` (any file —
+        binary content is base64-encoded into ``originalContentB64``) must be
+        supplied. When ``file_path`` is used, the MIME type is auto-detected
+        from the extension unless overridden via ``content_type``.
+        """
+        if (content is None) == (file_path is None):
+            raise ValueError("create_memory requires exactly one of content or file_path")
+
+        body: Dict[str, Any] = {"spaceId": space_id}
+
+        if file_path is not None:
+            path = Path(file_path)
+            if not path.exists():
+                raise FileNotFoundError(f"File not found: {file_path}")
+            mime = content_type or _guess_mime(path)
+            body["contentType"] = mime
+            file_bytes = path.read_bytes()
+            if mime.startswith("text/"):
+                body["originalContent"] = file_bytes.decode("utf-8")
+            else:
+                body["originalContentB64"] = base64.b64encode(file_bytes).decode("ascii")
+        else:
+            body["contentType"] = content_type or "text/plain"
+            body["originalContent"] = content  # type: ignore[assignment]
+
+        if metadata:
+            body["metadata"] = metadata
+
+        client = self._ensure_client()
+        resp = await client.post(
+            f"{self._base_url}/v1/memories",
+            headers=self._headers,
+            json=body,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    async def list_memories(
+        self,
+        space_id: str,
+        *,
+        next_token: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """``GET /v1/spaces/{id}/memories`` -> ``{memories, nextToken}``.
+
+        There is no top-level ``GET /v1/memories`` — listing is always
+        scoped to a space.
+        """
+        params: Dict[str, Any] = {}
+        if next_token:
+            params["nextToken"] = next_token
+        client = self._ensure_client()
+        resp = await client.get(
+            f"{self._base_url}/v1/spaces/{space_id}/memories",
+            headers=self._headers,
+            params=params,
+        )
+        resp.raise_for_status()
+        body = resp.json()
+        if isinstance(body, list):
+            return {"memories": body, "nextToken": None}
+        return {
+            "memories": body.get("memories", []),
+            "nextToken": body.get("nextToken"),
+        }
+
+    async def get_memory(
+        self,
+        memory_id: str,
+        *,
+        include_content: bool = True,
+    ) -> Dict[str, Any]:
+        """``GET /v1/memories/{id}`` (and optionally ``/content``).
+
+        The ``/content`` endpoint may return plain text rather than JSON for
+        text memories — both shapes are handled.
+        """
+        client = self._ensure_client()
+        resp = await client.get(
+            f"{self._base_url}/v1/memories/{memory_id}",
+            headers=self._headers,
+        )
+        resp.raise_for_status()
+        result: Dict[str, Any] = {"memory": resp.json()}
+
+        if include_content:
+            try:
+                content_resp = await client.get(
+                    f"{self._base_url}/v1/memories/{memory_id}/content",
+                    headers=self._headers,
+                )
+                content_resp.raise_for_status()
+                ctype = content_resp.headers.get("content-type", "")
+                if "application/json" in ctype:
+                    try:
+                        result["content"] = content_resp.json()
+                    except json.JSONDecodeError:
+                        result["content"] = content_resp.text
+                else:
+                    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 /v1/memories/{id}``."""
+        client = self._ensure_client()
+        resp = await client.delete(
+            f"{self._base_url}/v1/memories/{memory_id}",
+            headers=self._headers,
+        )
+        resp.raise_for_status()
+        return {"memoryId": memory_id, "success": True}
+
+    # ── Retrieve ────────────────────────────────────────────────────────
+
+    async def retrieve_memories(
+        self,
+        *,
+        message: str,
+        space_ids: List[str],
+        max_results: int = 5,
+        fetch_memory: bool = True,
+        wait_for_indexing: bool = False,
+        wait_seconds: float = 60.0,
+        poll_interval: float = 5.0,
+        # Post-processor params
+        reranker_id: Optional[str] = None,
+        llm_id: Optional[str] = None,
+        relevance_threshold: Optional[float] = None,
+        llm_temperature: Optional[float] = None,
+        chronological_resort: bool = False,
+    ) -> Dict[str, Any]:
+        """``POST /v1/memories:retrieve`` with optional reranker + LLM.
+
+        When ``wait_for_indexing=True`` and no results come back yet, polls
+        every ``poll_interval`` seconds for up to ``wait_seconds`` total —
+        new memories take a few seconds to embed and become searchable.
+
+        Returns ``{"results": [...], "memories": [...], "abstractReply": ...}``.
+        """
+        body: Dict[str, Any] = {
+            "message": message,
+            "spaceKeys": [{"spaceId": sid} for sid in space_ids],
+            "requestedSize": max_results,
+            "fetchMemory": fetch_memory,
+        }
+
+        use_post = any(
+            v is not None for v in (reranker_id, llm_id, relevance_threshold, llm_temperature)
+        ) or chronological_resort
+        if use_post:
+            cfg: Dict[str, Any] = {"max_results": max_results}
+            if reranker_id is not None:
+                cfg["reranker_id"] = reranker_id
+            if llm_id is not None:
+                cfg["llm_id"] = llm_id
+            if relevance_threshold is not None:
+                cfg["relevance_threshold"] = relevance_threshold
+            if llm_temperature is not None:
+                cfg["llm_temp"] = llm_temperature
+            if chronological_resort:
+                cfg["chronological_resort"] = True
+            body["postProcessor"] = {
+                "name": "com.goodmem.retrieval.postprocess.ChatPostProcessorFactory",
+                "config": cfg,
+            }
+
+        headers = {**self._headers, "Accept": "application/x-ndjson"}
+        client = self._ensure_client()
+
+        start = asyncio.get_event_loop().time()
+        while True:
+            resp = await client.post(
+                f"{self._base_url}/v1/memories:retrieve",
+                headers=headers,
+                json=body,
+            )
+            resp.raise_for_status()
+            results, memories, abstract = _parse_retrieve_response(resp.text)
+
+            if results or not wait_for_indexing:
+                return {"results": results, "memories": memories, "abstractReply": abstract}
+
+            if asyncio.get_event_loop().time() - start >= wait_seconds:
+                logger.warning("retrieve_memories: no results after %.0fs of polling", wait_seconds)
+                return {"results": results, "memories": memories, "abstractReply": abstract}
+
+            await asyncio.sleep(poll_interval)

autogen_goodmem-0.1.0/autogen_goodmem/_config.py

@@ -0,0 +1,47 @@
+"""Configuration classes for the autogen-goodmem integration."""
+
+from typing import Dict, List, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+
+class ChunkingConfig(BaseModel):
+    """Recursive chunking config used when creating a space."""
+
+    chunk_size: int = Field(default=256, description="Characters per chunk")
+    chunk_overlap: int = Field(default=25, description="Overlap between consecutive chunks")
+    keep_strategy: Literal["KEEP_END", "KEEP_START", "DISCARD"] = Field(default="KEEP_END")
+    length_measurement: Literal["CHARACTER_COUNT", "TOKEN_COUNT"] = Field(default="CHARACTER_COUNT")
+    separators: List[str] = Field(default=["\n\n", "\n", ". ", " ", ""])
+    separator_is_regex: bool = Field(default=False)
+
+
+class PostProcessorConfig(BaseModel):
+    """Optional reranker / LLM post-processor used by retrieve_memories."""
+
+    reranker_id: Optional[str] = Field(default=None)
+    llm_id: Optional[str] = Field(default=None)
+    relevance_threshold: Optional[float] = Field(default=None, description="0-1")
+    llm_temperature: Optional[float] = Field(default=None, description="0-2")
+    max_results: Optional[int] = Field(default=None)
+    chronological_resort: bool = Field(default=False)
+
+
+class GoodMemMemoryConfig(BaseModel):
+    """Configuration for :class:`GoodMemContextProvider`.
+
+    Connects an AutoGen ``Memory`` to a single GoodMem space, automatically
+    creating or reusing the space by name on first use.
+    """
+
+    base_url: str = Field(description="GoodMem API base URL, e.g. https://localhost:8080")
+    api_key: str = Field(description="GoodMem API key (sent as X-API-Key)")
+    space_name: str = Field(description="Space to create or reuse")
+    embedder_id: str = Field(description="Embedder model ID for this space")
+    max_results: int = Field(default=5)
+    include_memory_definition: bool = Field(default=True)
+    wait_for_indexing: bool = Field(default=True, description="Poll up to ~60s for first results")
+    chunking: ChunkingConfig = Field(default_factory=ChunkingConfig)
+    post_processor: Optional[PostProcessorConfig] = Field(default=None)
+    metadata: Optional[Dict[str, str]] = Field(default=None)
+    verify_ssl: bool = Field(default=True)

autogen_goodmem-0.1.0/autogen_goodmem/_context_provider.py

@@ -0,0 +1,232 @@
+"""AutoGen-native memory provider backed by GoodMem.
+
+In AutoGen, the extension point for retrieval-augmented context injection is
+:class:`autogen_core.memory.Memory` — the equivalent of "BaseContextProvider"
+in other frameworks. :class:`GoodMemContextProvider` plugs a single GoodMem
+space into that surface so an AutoGen agent can call ``memory.add(...)`` /
+``memory.query(...)`` and ``update_context`` will inject retrieved chunks as
+a system message.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from autogen_core import CancellationToken, Component
+from autogen_core.memory import (
+    Memory,
+    MemoryContent,
+    MemoryMimeType,
+    MemoryQueryResult,
+    UpdateContextResult,
+)
+from autogen_core.model_context import ChatCompletionContext
+from autogen_core.models import SystemMessage
+from typing_extensions import Self
+
+from ._client import GoodMemClient
+from ._config import GoodMemMemoryConfig
+
+logger = logging.getLogger(__name__)
+
+
+class GoodMemContextProvider(Memory, Component[GoodMemMemoryConfig]):
+    """AutoGen ``Memory`` provider backed by a GoodMem space.
+
+    Args:
+        config: Connection details and space configuration.
+
+    Example:
+
+        .. code-block:: python
+
+            from autogen_goodmem import GoodMemContextProvider, GoodMemMemoryConfig
+
+            provider = GoodMemContextProvider(
+                config=GoodMemMemoryConfig(
+                    base_url="https://localhost:8080",
+                    api_key="gm_...",
+                    space_name="my-kb",
+                    embedder_id="<embedder-uuid>",
+                    verify_ssl=False,
+                )
+            )
+            await provider.add(MemoryContent(content="hi", mime_type=MemoryMimeType.TEXT))
+            results = await provider.query("hello")
+            await provider.close()
+    """
+
+    component_config_schema = GoodMemMemoryConfig
+    component_provider_override = "autogen_goodmem.GoodMemContextProvider"
+
+    def __init__(self, config: GoodMemMemoryConfig) -> None:
+        self._config = config
+        self._client = GoodMemClient(
+            base_url=config.base_url,
+            api_key=config.api_key,
+            verify_ssl=config.verify_ssl,
+        )
+        self._space_id: Optional[str] = None
+
+    # ── Internals ──────────────────────────────────────────────────────
+
+    async def _ensure_space(self) -> str:
+        if self._space_id is not None:
+            return self._space_id
+        result = await self._client.create_space(
+            self._config.space_name,
+            self._config.embedder_id,
+            chunking=self._config.chunking,
+        )
+        self._space_id = result["spaceId"]
+        if result.get("reused"):
+            logger.info("Reusing GoodMem space %s (%s)", self._config.space_name, self._space_id)
+        else:
+            logger.info("Created GoodMem space %s (%s)", self._config.space_name, self._space_id)
+        return self._space_id  # type: ignore[return-value]
+
+    # ── AutoGen Memory interface ───────────────────────────────────────
+
+    async def update_context(self, model_context: ChatCompletionContext) -> UpdateContextResult:
+        messages = await model_context.get_messages()
+        if not messages:
+            return UpdateContextResult(memories=MemoryQueryResult(results=[]))
+
+        last = messages[-1]
+        query_text = last.content if isinstance(last.content, str) else str(last)
+        query_results = await self.query(query_text)
+
+        if query_results.results:
+            lines = [f"{i}. {str(m.content)}" for i, m in enumerate(query_results.results, 1)]
+            await model_context.add_message(SystemMessage(content="\nRelevant memory content:\n" + "\n".join(lines)))
+
+        return UpdateContextResult(memories=query_results)
+
+    async def add(
+        self,
+        content: MemoryContent,
+        cancellation_token: CancellationToken | None = None,
+    ) -> None:
+        """Store a text memory. Use :meth:`add_file` for binary files."""
+        space_id = await self._ensure_space()
+        text = content.content
+        if not isinstance(text, str):
+            raise ValueError(
+                "GoodMemContextProvider.add() only supports text content. "
+                "Use add_file() for binary files (PDF, images, etc.)."
+            )
+
+        merged: Dict[str, Any] = {}
+        if self._config.metadata:
+            merged.update(self._config.metadata)
+        if content.metadata:
+            merged.update(content.metadata)
+
+        await self._client.create_memory(
+            space_id=space_id,
+            content=text,
+            content_type="text/plain",
+            metadata=merged or None,
+        )
+
+    async def add_file(
+        self,
+        file_path: str,
+        metadata: Optional[Dict[str, Any]] = None,
+        cancellation_token: CancellationToken | None = None,
+    ) -> Dict[str, Any]:
+        space_id = await self._ensure_space()
+        merged: Dict[str, Any] = {}
+        if self._config.metadata:
+            merged.update(self._config.metadata)
+        if metadata:
+            merged.update(metadata)
+        result = await self._client.create_memory(
+            space_id=space_id,
+            file_path=file_path,
+            metadata=merged or None,
+        )
+        return {
+            "memoryId": result.get("memoryId"),
+            "spaceId": result.get("spaceId"),
+            "status": result.get("processingStatus", "PENDING"),
+            "contentType": result.get("contentType"),
+            "fileName": file_path.rsplit("/", 1)[-1],
+        }
+
+    async def query(
+        self,
+        query: str | MemoryContent,
+        cancellation_token: CancellationToken | None = None,
+        **kwargs: Any,
+    ) -> MemoryQueryResult:
+        space_id = await self._ensure_space()
+        space_ids: List[str] = kwargs.get("space_ids", [space_id])
+        query_text = query if isinstance(query, str) else str(query.content)
+
+        pp = self._config.post_processor
+        kw: Dict[str, Any] = {}
+        if pp is not None:
+            kw.update(
+                reranker_id=pp.reranker_id,
+                llm_id=pp.llm_id,
+                relevance_threshold=pp.relevance_threshold,
+                llm_temperature=pp.llm_temperature,
+                chronological_resort=pp.chronological_resort,
+            )
+
+        result = await self._client.retrieve_memories(
+            message=query_text,
+            space_ids=space_ids,
+            max_results=self._config.max_results,
+            fetch_memory=self._config.include_memory_definition,
+            wait_for_indexing=self._config.wait_for_indexing,
+            **kw,
+        )
+
+        abstract = result.get("abstractReply")
+        out: List[MemoryContent] = []
+        for item in result["results"]:
+            meta: Dict[str, Any] = {
+                "chunkId": item.get("chunkId"),
+                "memoryId": item.get("memoryId"),
+                "relevanceScore": item.get("relevanceScore"),
+                "memoryIndex": item.get("memoryIndex"),
+            }
+            if abstract:
+                meta["abstractReply"] = abstract
+            out.append(
+                MemoryContent(
+                    content=item.get("chunkText", ""),
+                    mime_type=MemoryMimeType.TEXT,
+                    metadata=meta,
+                )
+            )
+        return MemoryQueryResult(results=out)
+
+    async def clear(self) -> None:
+        logger.warning(
+            "GoodMem does not support bulk clear; delete memories individually "
+            "or recreate the space."
+        )
+
+    async def close(self) -> None:
+        await self._client.close()
+        self._space_id = None
+
+    # ── Convenience pass-throughs ──────────────────────────────────────
+
+    @property
+    def client(self) -> GoodMemClient:
+        """The underlying :class:`GoodMemClient` (useful for advanced ops)."""
+        return self._client
+
+    # ── Serialization ──────────────────────────────────────────────────
+
+    def _to_config(self) -> GoodMemMemoryConfig:
+        return self._config
+
+    @classmethod
+    def _from_config(cls, config: GoodMemMemoryConfig) -> Self:
+        return cls(config=config)

autogen_goodmem-0.1.0/autogen_goodmem/_tools.py

@@ -0,0 +1,180 @@
+"""Factory for the 11 GoodMem AutoGen ``FunctionTool`` instances.
+
+Each tool is a thin wrapper around :class:`GoodMemClient`, exposed as an
+AutoGen ``FunctionTool`` that an agent can call. Tool names are prefixed
+with ``goodmem_`` so multiple memory backends can coexist on one agent.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from autogen_core.tools import FunctionTool
+
+from ._client import GoodMemClient
+
+
+TOOL_NAMES: List[str] = [
+    "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",
+]
+
+
+def create_goodmem_tools(client: GoodMemClient) -> List[FunctionTool]:
+    """Return the 11 GoodMem ``FunctionTool`` instances bound to ``client``.
+
+    The returned list is in the order declared in :data:`TOOL_NAMES`.
+    """
+
+    async def goodmem_list_embedders() -> List[Dict[str, Any]]:
+        """List available embedder models on the GoodMem server."""
+        return await client.list_embedders()
+
+    async def goodmem_list_spaces() -> List[Dict[str, Any]]:
+        """List all GoodMem spaces visible to the current API key."""
+        return await client.list_spaces()
+
+    async def goodmem_get_space(space_id: str) -> Dict[str, Any]:
+        """Fetch a single GoodMem space by ID."""
+        return await client.get_space(space_id)
+
+    async def goodmem_create_space(
+        name: str,
+        embedder_id: str,
+    ) -> Dict[str, Any]:
+        """Create a GoodMem space, or reuse the existing one with the same name.
+
+        Returns ``{spaceId, name, embedderId, reused}``.
+        """
+        return await client.create_space(name=name, embedder_id=embedder_id)
+
+    async def goodmem_update_space(
+        space_id: str,
+        name: Optional[str] = None,
+        public_read: Optional[bool] = None,
+        replace_labels: Optional[Dict[str, str]] = None,
+        merge_labels: Optional[Dict[str, str]] = None,
+    ) -> Dict[str, Any]:
+        """Update a GoodMem space.
+
+        Only ``name``, ``publicRead``, ``replaceLabels``, ``mergeLabels``, and
+        ``defaultChunkingConfig`` are accepted by the server — passing a bare
+        ``labels`` field returns 400, so prefer ``replace_labels`` (full
+        replacement) or ``merge_labels`` (additive merge).
+        """
+        return await client.update_space(
+            space_id,
+            name=name,
+            public_read=public_read,
+            replace_labels=replace_labels,
+            merge_labels=merge_labels,
+        )
+
+    async def goodmem_delete_space(space_id: str) -> Dict[str, Any]:
+        """Permanently delete a GoodMem space and every memory inside it."""
+        return await client.delete_space(space_id)
+
+    async def goodmem_create_memory(
+        space_id: str,
+        content: Optional[str] = None,
+        file_path: Optional[str] = None,
+        content_type: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Create a memory in a space from inline text or a local file.
+
+        Exactly one of ``content`` (inline text) or ``file_path`` must be
+        provided. Binary files (PDF, images) are base64-encoded; text files
+        are sent inline. MIME type is auto-detected from the extension when
+        ``content_type`` is omitted.
+        """
+        return await client.create_memory(
+            space_id=space_id,
+            content=content,
+            file_path=file_path,
+            content_type=content_type,
+            metadata=metadata,
+        )
+
+    async def goodmem_list_memories(
+        space_id: str,
+        next_token: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """List memories in a space (paginated via ``nextToken``).
+
+        Note: GoodMem has no top-level ``GET /v1/memories`` — listing is
+        always scoped to a space.
+        """
+        return await client.list_memories(space_id, next_token=next_token)
+
+    async def goodmem_retrieve_memories(
+        message: str,
+        space_ids: List[str],
+        max_results: int = 5,
+        fetch_memory: bool = True,
+        wait_for_indexing: bool = False,
+        reranker_id: Optional[str] = None,
+        llm_id: Optional[str] = None,
+        relevance_threshold: Optional[float] = None,
+        llm_temperature: Optional[float] = None,
+        chronological_resort: bool = False,
+    ) -> Dict[str, Any]:
+        """Semantic retrieval against one or more GoodMem spaces.
+
+        Optionally re-orders results with ``reranker_id`` and/or generates a
+        natural-language ``abstractReply`` with ``llm_id``.
+        """
+        return await client.retrieve_memories(
+            message=message,
+            space_ids=space_ids,
+            max_results=max_results,
+            fetch_memory=fetch_memory,
+            wait_for_indexing=wait_for_indexing,
+            reranker_id=reranker_id,
+            llm_id=llm_id,
+            relevance_threshold=relevance_threshold,
+            llm_temperature=llm_temperature,
+            chronological_resort=chronological_resort,
+        )
+
+    async def goodmem_get_memory(
+        memory_id: str,
+        include_content: bool = True,
+    ) -> Dict[str, Any]:
+        """Fetch a memory's metadata, and optionally its original content."""
+        return await client.get_memory(memory_id, include_content=include_content)
+
+    async def goodmem_delete_memory(memory_id: str) -> Dict[str, Any]:
+        """Permanently delete a memory and its chunks/embeddings."""
+        return await client.delete_memory(memory_id)
+
+    funcs = [
+        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,
+    ]
+    return [
+        FunctionTool(
+            f,
+            name=f.__name__,
+            description=(f.__doc__ or f.__name__).strip().splitlines()[0],
+        )
+        for f in funcs
+    ]

autogen_goodmem-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "autogen-goodmem"
+version = "0.1.0"
+description = "GoodMem memory and tools for the AutoGen agent framework."
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [{name = "PAIR Systems"}]
+keywords = ["autogen", "goodmem", "memory", "rag", "agents", "llm"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "autogen-core>=0.7.5",
+    "httpx>=0.24.0,<1",
+    "pydantic>=2.0,<3",
+    "typing-extensions>=4.7",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+    "pytest-asyncio>=0.23",
+    "pytest-timeout",
+    "build",
+    "twine",
+]
+
+[project.urls]
+Homepage = "https://github.com/PAIR-Systems-Inc/autogen-goodmem"
+Repository = "https://github.com/PAIR-Systems-Inc/autogen-goodmem"
+Issues = "https://github.com/PAIR-Systems-Inc/autogen-goodmem/issues"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+markers = ["integration: live-server tests"]
+
+[build-system]
+requires = ["flit-core>=3.11,<4.0"]
+build-backend = "flit_core.buildapi"
+
+[tool.flit.module]
+name = "autogen_goodmem"