goodmem-llamaindex 0.2.3__tar.gz

goodmem_llamaindex-0.2.3/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.venv-*/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.DS_Store

goodmem_llamaindex-0.2.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bashareid
+
+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.

goodmem_llamaindex-0.2.3/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.5
+Name: goodmem-llamaindex
+Version: 0.2.3
+Summary: Native LlamaIndex retrieval, Document ingestion and agent tools for GoodMem.
+Project-URL: Homepage, https://goodmem.ai
+Project-URL: Repository, https://github.com/PAIR-Systems-Inc/goodmem-llamaindex
+Project-URL: Documentation, https://github.com/PAIR-Systems-Inc/goodmem-llamaindex/blob/main/docs/usage.md
+Project-URL: Changelog, https://github.com/PAIR-Systems-Inc/goodmem-llamaindex/blob/main/CHANGELOG.md
+Author: bashareid
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,goodmem,llama-index,llm,memory,semantic-search,vector-search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: <4.0,>=3.10
+Requires-Dist: goodmem<0.2,>=0.1.34
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: llama-index-core<0.15,>=0.14.24
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=1.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.12; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# GoodMem for LlamaIndex
+
+Use [GoodMem](https://goodmem.ai) as a persistent document and retrieval service in LlamaIndex. GoodMem handles chunking, embeddings and optional reranking; the integration returns native `NodeWithScore` objects for query engines and agents.
+
+```bash
+pip install 'goodmem-llamaindex>=0.2.3'
+```
+
+The import namespace is `llama_index.tools.goodmem`. Set `GOODMEM_BASE_URL` to your server’s REST root and `GOODMEM_API_KEY` to its API key.
+
+## Store and retrieve Documents
+
+Use an existing GoodMem space configured with an embedder:
+
+```python
+import os
+
+from goodmem import Goodmem
+from llama_index.core.schema import Document
+from llama_index.tools.goodmem import (
+    GoodMemDocumentIngestor,
+    GoodMemRetriever,
+    wait_for_memories,
+)
+
+with Goodmem(base_url=os.environ["GOODMEM_BASE_URL"],
+             api_key=os.environ["GOODMEM_API_KEY"]) as client:
+    space_id = os.environ["GOODMEM_SPACE_ID"]
+    ids = GoodMemDocumentIngestor(client=client, space_id=space_id).add_documents([
+        Document(text="The returns period is 30 days.",
+                 metadata={"source": "https://example.com/returns"})
+    ])
+    wait_for_memories(client, ids, timeout=120)
+
+    retriever = GoodMemRetriever(client=client, space_ids=[space_id])
+    for result in retriever.retrieve("How long do I have to return an item?"):
+        print(result.score, result.text, result.metadata.get("source"))
+```
+
+`add_documents` returns accepted IDs without waiting. Waiting is explicit and checks only those IDs. Ordinary empty searches return immediately.
+
+## Connect an agent
+
+Use LlamaIndex’s own tool wrapper. Give each collection a useful name and description:
+
+```python
+import os
+
+from llama_index.core.tools import RetrieverTool
+from llama_index.tools.goodmem import GoodMemRetriever
+
+space_id = os.environ["GOODMEM_SPACE_ID"]
+retriever = GoodMemRetriever(space_ids=[space_id])  # uses environment settings
+search = RetrieverTool.from_defaults(
+    retriever,
+    name="returns_policy",
+    description="Search the company's returns and refund policies.",
+)
+# Pass search to a workflow-based ReActAgent or FunctionAgent.
+```
+
+The model supplies the query; the application configures spaces, filters and reranking. The same retriever works with `RetrieverQueryEngine` and standard LlamaIndex callbacks.
+
+Pass `filters=MetadataFilters(...)` for supported scalar comparisons, membership tests and nested conditions. Pass `reranker_id=...` to rerank on the server without an LLM. Sources, custom metadata and Document metadata exclusions survive storage. Framework scores rank higher as more relevant; `raw_score` preserves the original value.
+
+Retrieval does not raise on problems the server reports in its results; it returns what the server sent. HTTP errors, such as an unknown space, still raise the SDK's exception. If a configured reranker fails (for example, its ID does not exist), GoodMem reports `NOT_FOUND` and `RERANKING_FAILED` and still returns the vector-search hits. The retriever returns those hits as vector scores, negated like any vector score, with `score_kind="negative_inner_product"`, `partial=True` and the server's `statuses` on each result, and logs a WARNING. A reported problem with no hits returns an empty list, a `UserWarning` and a WARNING log line naming the statuses.
+
+## Async and administrative tools
+
+`aretrieve` and `aadd_documents` use the SDK’s `AsyncGoodmem` directly. Inject `async_client` to share its connection pool; caller-owned clients remain open.
+
+`GoodMemToolSpec` supplies optional space and memory management tools. Its retrieval result includes chunks with the server's raw scores, `statuses`, a `partial` flag and `score_kind` (`reranker`, or `negative_inner_product` for vector scores, including when reranking failed). File uploads require an explicitly configured directory. Prefer a scoped retriever tool when an agent only needs search.
+
+Every GoodMem ID you or a model pass in (space, memory, embedder, reranker or LLM) must be a UUID. Anything else raises `ValueError` before a request is sent, because the SDK puts IDs into URL paths, where a value such as `../spaces/<id>` would reach a different resource.
+
+See [usage and migration](https://github.com/PAIR-Systems-Inc/goodmem-llamaindex/blob/v0.2.3/docs/usage.md) for async examples, supported filters and diagnostics, and the [changelog](https://github.com/PAIR-Systems-Inc/goodmem-llamaindex/blob/v0.2.3/CHANGELOG.md) for the changes from 0.1. Run `pip install -e '.[dev]'`, then `pytest`, `ruff check llama_index tests` and `ruff format --check llama_index tests`, as CI does. Live tests are opt-in and clean up their own spaces.

goodmem_llamaindex-0.2.3/README.md

@@ -0,0 +1,76 @@
+# GoodMem for LlamaIndex
+
+Use [GoodMem](https://goodmem.ai) as a persistent document and retrieval service in LlamaIndex. GoodMem handles chunking, embeddings and optional reranking; the integration returns native `NodeWithScore` objects for query engines and agents.
+
+```bash
+pip install 'goodmem-llamaindex>=0.2.3'
+```
+
+The import namespace is `llama_index.tools.goodmem`. Set `GOODMEM_BASE_URL` to your server’s REST root and `GOODMEM_API_KEY` to its API key.
+
+## Store and retrieve Documents
+
+Use an existing GoodMem space configured with an embedder:
+
+```python
+import os
+
+from goodmem import Goodmem
+from llama_index.core.schema import Document
+from llama_index.tools.goodmem import (
+    GoodMemDocumentIngestor,
+    GoodMemRetriever,
+    wait_for_memories,
+)
+
+with Goodmem(base_url=os.environ["GOODMEM_BASE_URL"],
+             api_key=os.environ["GOODMEM_API_KEY"]) as client:
+    space_id = os.environ["GOODMEM_SPACE_ID"]
+    ids = GoodMemDocumentIngestor(client=client, space_id=space_id).add_documents([
+        Document(text="The returns period is 30 days.",
+                 metadata={"source": "https://example.com/returns"})
+    ])
+    wait_for_memories(client, ids, timeout=120)
+
+    retriever = GoodMemRetriever(client=client, space_ids=[space_id])
+    for result in retriever.retrieve("How long do I have to return an item?"):
+        print(result.score, result.text, result.metadata.get("source"))
+```
+
+`add_documents` returns accepted IDs without waiting. Waiting is explicit and checks only those IDs. Ordinary empty searches return immediately.
+
+## Connect an agent
+
+Use LlamaIndex’s own tool wrapper. Give each collection a useful name and description:
+
+```python
+import os
+
+from llama_index.core.tools import RetrieverTool
+from llama_index.tools.goodmem import GoodMemRetriever
+
+space_id = os.environ["GOODMEM_SPACE_ID"]
+retriever = GoodMemRetriever(space_ids=[space_id])  # uses environment settings
+search = RetrieverTool.from_defaults(
+    retriever,
+    name="returns_policy",
+    description="Search the company's returns and refund policies.",
+)
+# Pass search to a workflow-based ReActAgent or FunctionAgent.
+```
+
+The model supplies the query; the application configures spaces, filters and reranking. The same retriever works with `RetrieverQueryEngine` and standard LlamaIndex callbacks.
+
+Pass `filters=MetadataFilters(...)` for supported scalar comparisons, membership tests and nested conditions. Pass `reranker_id=...` to rerank on the server without an LLM. Sources, custom metadata and Document metadata exclusions survive storage. Framework scores rank higher as more relevant; `raw_score` preserves the original value.
+
+Retrieval does not raise on problems the server reports in its results; it returns what the server sent. HTTP errors, such as an unknown space, still raise the SDK's exception. If a configured reranker fails (for example, its ID does not exist), GoodMem reports `NOT_FOUND` and `RERANKING_FAILED` and still returns the vector-search hits. The retriever returns those hits as vector scores, negated like any vector score, with `score_kind="negative_inner_product"`, `partial=True` and the server's `statuses` on each result, and logs a WARNING. A reported problem with no hits returns an empty list, a `UserWarning` and a WARNING log line naming the statuses.
+
+## Async and administrative tools
+
+`aretrieve` and `aadd_documents` use the SDK’s `AsyncGoodmem` directly. Inject `async_client` to share its connection pool; caller-owned clients remain open.
+
+`GoodMemToolSpec` supplies optional space and memory management tools. Its retrieval result includes chunks with the server's raw scores, `statuses`, a `partial` flag and `score_kind` (`reranker`, or `negative_inner_product` for vector scores, including when reranking failed). File uploads require an explicitly configured directory. Prefer a scoped retriever tool when an agent only needs search.
+
+Every GoodMem ID you or a model pass in (space, memory, embedder, reranker or LLM) must be a UUID. Anything else raises `ValueError` before a request is sent, because the SDK puts IDs into URL paths, where a value such as `../spaces/<id>` would reach a different resource.
+
+See [usage and migration](https://github.com/PAIR-Systems-Inc/goodmem-llamaindex/blob/v0.2.3/docs/usage.md) for async examples, supported filters and diagnostics, and the [changelog](https://github.com/PAIR-Systems-Inc/goodmem-llamaindex/blob/v0.2.3/CHANGELOG.md) for the changes from 0.1. Run `pip install -e '.[dev]'`, then `pytest`, `ruff check llama_index tests` and `ruff format --check llama_index tests`, as CI does. Live tests are opt-in and clean up their own spaces.

goodmem_llamaindex-0.2.3/llama_index/tools/goodmem/__init__.py

@@ -0,0 +1,23 @@
+"""GoodMem integration for LlamaIndex."""
+
+from .base import GoodMemToolSpec
+from .ingestion import (
+    GoodMemDocumentIngestor,
+    GoodMemIndexingError,
+    GoodMemIngestionError,
+    await_memories,
+    wait_for_memories,
+)
+from .retriever import GoodMemNodeWithScore, GoodMemRetrievalError, GoodMemRetriever
+
+__all__ = [
+    "GoodMemToolSpec",
+    "GoodMemRetriever",
+    "GoodMemNodeWithScore",
+    "GoodMemRetrievalError",
+    "GoodMemDocumentIngestor",
+    "GoodMemIngestionError",
+    "GoodMemIndexingError",
+    "wait_for_memories",
+    "await_memories",
+]

goodmem_llamaindex-0.2.3/llama_index/tools/goodmem/_connection.py

@@ -0,0 +1,63 @@
+"""SDK sessions with explicit ownership and native async support."""
+
+import os
+from collections.abc import AsyncIterator, Iterator
+from contextlib import asynccontextmanager, contextmanager
+
+from goodmem import AsyncGoodmem, Goodmem
+
+
+class Connection:
+    """Use injected SDK clients, or create short-lived clients from configuration.
+
+    Args:
+        client: Caller-owned synchronous SDK client. With injected clients,
+            synchronous calls require this client even when environment settings exist.
+        async_client: Caller-owned asynchronous SDK client. With injected clients,
+            asynchronous calls require this client even when environment settings exist.
+        api_key: API key, defaulting to GOODMEM_API_KEY.
+        base_url: Server root, defaulting to GOODMEM_BASE_URL.
+        verify_ssl: Certificate verification, or a path to a trusted CA bundle.
+        timeout: SDK HTTP timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        *,
+        client: Goodmem | None = None,
+        async_client: AsyncGoodmem | None = None,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        verify_ssl: bool | str = True,
+        timeout: float = 120,
+    ) -> None:
+        self.client = client
+        self.async_client = async_client
+        self.options = {
+            "api_key": api_key or os.getenv("GOODMEM_API_KEY"),
+            "base_url": base_url or os.getenv("GOODMEM_BASE_URL"),
+            "verify": verify_ssl,
+            "timeout": timeout,
+        }
+
+    @contextmanager
+    def sync(self) -> Iterator[Goodmem]:
+        """Yield a synchronous client without closing caller-owned connections."""
+        if self.client is not None:
+            yield self.client
+        else:
+            if self.async_client is not None:
+                raise ValueError("Pass client for sync calls with an injected async SDK client")
+            with Goodmem(**self.options) as client:
+                yield client
+
+    @asynccontextmanager
+    async def async_(self) -> AsyncIterator[AsyncGoodmem]:
+        """Yield a native async client without using a worker thread."""
+        if self.async_client is not None:
+            yield self.async_client
+        else:
+            if self.client is not None:
+                raise ValueError("Pass async_client for async calls with an injected SDK client")
+            async with AsyncGoodmem(**self.options) as client:
+                yield client

goodmem_llamaindex-0.2.3/llama_index/tools/goodmem/_ids.py

@@ -0,0 +1,30 @@
+"""GoodMem resource IDs are UUIDs; anything else is refused before a request.
+
+The official SDK interpolates IDs into URL paths without escaping them, and httpx
+resolves dot segments before sending. An ID such as "../spaces/<uuid>" would
+therefore address a different resource, so every ID is checked here first.
+"""
+
+import re
+from typing import Annotated
+
+from pydantic import Field
+
+UUID_PATTERN = r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
+_UUID = re.compile(UUID_PATTERN)
+
+# Tool schemas tell the model an ID is a UUID with the standard JSON-schema format.
+# LlamaIndex keeps only json_schema_extra from a top-level annotation and prints the
+# annotation in each tool description; a pattern there would push retrieve_memories
+# past OpenAI's 1024-character description limit. require_uuid is the real guard.
+UuidStr = Annotated[str, Field(json_schema_extra={"format": "uuid"})]
+
+
+def require_uuid(value: object, field: str) -> str:
+    """Return the canonical lowercase UUID, or raise ValueError naming the field."""
+    # fullmatch, unlike match with "$", also rejects a trailing newline.
+    if not isinstance(value, str) or not _UUID.fullmatch(value):
+        raise ValueError(
+            f"{field} must be a UUID (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx); no request was sent"
+        )
+    return value.lower()

goodmem_llamaindex-0.2.3/llama_index/tools/goodmem/_metadata.py

@@ -0,0 +1,28 @@
+"""Persist LlamaIndex metadata visibility settings alongside user metadata."""
+
+_DOCUMENT_METADATA = "_llamaindex_goodmem"
+_EXCLUSIONS = ("excluded_llm_metadata_keys", "excluded_embed_metadata_keys")
+
+
+def document_metadata(document):
+    """Encode formatting settings without overwriting a user metadata field."""
+    if _DOCUMENT_METADATA in document.metadata:
+        raise ValueError(f"Metadata key {_DOCUMENT_METADATA} is reserved for LlamaIndex settings")
+    return dict(document.metadata) | {
+        _DOCUMENT_METADATA: {key: list(getattr(document, key)) for key in _EXCLUSIONS}
+    }
+
+
+def stored_metadata(metadata):
+    """Separate stored settings, rejecting malformed exclusions before rendering."""
+    metadata = dict(metadata or {})
+    options = metadata.pop(_DOCUMENT_METADATA, {})
+    if not isinstance(options, dict):
+        raise ValueError(f"Invalid {_DOCUMENT_METADATA} metadata settings")
+    exclusions = {}
+    for key in _EXCLUSIONS:
+        value = options.get(key, [])
+        if not isinstance(value, list) or any(not isinstance(item, str) for item in value):
+            raise ValueError(f"Invalid stored {key}: expected a list of strings")
+        exclusions[key] = list(value)
+    return metadata, exclusions