dspy-moss 0.0.1__tar.gz

dspy_moss-0.0.1/LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2025, InferEdge Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

dspy_moss-0.0.1/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: dspy-moss
+Version: 0.0.1
+Summary: Moss semantic search retrieval module for DSPy
+License: BSD-2-Clause
+Requires-Python: <3.15,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: moss>=1.1.1
+Requires-Dist: dspy>=2.0.0
+Dynamic: license-file
+
+# dspy-moss
+
+Moss semantic search retrieval module for [DSPy](https://dspy.ai).
+
+Provides `MossRM` — a `dspy.Retrieve` subclass that plugs into DSPy's RM interface for sub-10ms knowledge retrieval with no external embedder.
+
+## Installation
+
+```bash
+pip install dspy-moss
+# or
+uv add dspy-moss
+```
+
+## Quickstart
+
+```python
+import dspy
+from dspy_moss import MossRM
+
+# Reads MOSS_PROJECT_ID and MOSS_PROJECT_KEY from environment
+rm = MossRM(index_name="my-index")
+rm.load_index()  # load into this process's memory before querying
+dspy.configure(lm=dspy.LM("openai/gpt-4o"), rm=rm)
+
+retrieve = dspy.Retrieve(k=3)
+result = retrieve("What is the refund policy?")
+for passage in result.passages:
+    print(f"[{passage['score']:.3f}] {passage['long_text']}")
+```
+
+## Usage patterns
+
+### As a configured retriever
+
+Set `MossRM` as the default retriever for all `dspy.Retrieve` calls in your program:
+
+```python
+import dspy
+from dspy_moss import MossRM
+
+rm = MossRM(
+    index_name="support-kb",
+    k=5,
+    alpha=0.8,  # 1.0 = semantic only, 0.0 = keyword only
+)
+dspy.configure(lm=dspy.LM("openai/gpt-4o"), rm=rm)
+
+# Any dspy.Retrieve() now uses Moss
+class RAG(dspy.Module):
+    def __init__(self):
+        self.retrieve = dspy.Retrieve(k=3)
+        self.generate = dspy.ChainOfThought("context, question -> answer")
+
+    def forward(self, question):
+        context = self.retrieve(question).passages
+        return self.generate(context=context, question=question)
+
+rag = RAG()
+print(rag("How long do refunds take?").answer)
+```
+
+### As a ReAct tool
+
+`MossRM.forward()` is already sync, so pass the instance directly — no wrapper needed:
+
+```python
+import dspy
+from dspy_moss import MossRM
+
+rm = MossRM(index_name="support-kb", k=5)
+rm.load_index()
+agent = dspy.ReAct(signature="question -> answer", tools=[rm])
+print(agent(question="What payment methods do you accept?").answer)
+```
+
+### With an explicit client
+
+```python
+from moss import MossClient
+from dspy_moss import MossRM
+
+client = MossClient("proj-id", "proj-key")
+rm = MossRM(index_name="my-index", moss_client=client, k=5)
+```
+
+## Configuration
+
+### MossRM
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `index_name` | (required) | Name of the Moss index to query |
+| `moss_client` | `None` | Existing `MossClient`. When omitted, one is created from credentials |
+| `project_id` | `MOSS_PROJECT_ID` env var | Moss project ID |
+| `project_key` | `MOSS_PROJECT_KEY` env var | Moss project key |
+| `k` | `3` | Default number of passages per query |
+| `alpha` | `0.8` | Search blend: 1.0 = semantic only, 0.0 = keyword only |
+
+### Passage format
+
+Each entry in `result.passages` is a dict with:
+
+| Key | Type | Description |
+| --- | --- | --- |
+| `long_text` | `str` | Document text (DSPy's standard passage field) |
+| `id` | `str` | Document ID |
+| `score` | `float` | Relevance score |
+| `metadata` | `dict` | Key-value metadata stored with the document |
+
+### Mutable index helpers
+
+`MossRM` also exposes two optional helpers for agents that write to the knowledge base:
+
+```python
+# Read documents
+objects = rm.get_objects(num_samples=10)
+
+# Add / upsert documents
+rm.insert([{"id": "doc-1", "text": "New fact.", "metadata": {"source": "agent"}}])
+```
+
+## License
+
+BSD 2-Clause — see [LICENSE](LICENSE).
+
+## Support
+
+- [Moss Docs](https://docs.moss.dev)
+- [Moss Discord](https://discord.gg/eMXExuafBR)
+- [DSPy Docs](https://dspy.ai)

dspy_moss-0.0.1/README.md

@@ -0,0 +1,131 @@
+# dspy-moss
+
+Moss semantic search retrieval module for [DSPy](https://dspy.ai).
+
+Provides `MossRM` — a `dspy.Retrieve` subclass that plugs into DSPy's RM interface for sub-10ms knowledge retrieval with no external embedder.
+
+## Installation
+
+```bash
+pip install dspy-moss
+# or
+uv add dspy-moss
+```
+
+## Quickstart
+
+```python
+import dspy
+from dspy_moss import MossRM
+
+# Reads MOSS_PROJECT_ID and MOSS_PROJECT_KEY from environment
+rm = MossRM(index_name="my-index")
+rm.load_index()  # load into this process's memory before querying
+dspy.configure(lm=dspy.LM("openai/gpt-4o"), rm=rm)
+
+retrieve = dspy.Retrieve(k=3)
+result = retrieve("What is the refund policy?")
+for passage in result.passages:
+    print(f"[{passage['score']:.3f}] {passage['long_text']}")
+```
+
+## Usage patterns
+
+### As a configured retriever
+
+Set `MossRM` as the default retriever for all `dspy.Retrieve` calls in your program:
+
+```python
+import dspy
+from dspy_moss import MossRM
+
+rm = MossRM(
+    index_name="support-kb",
+    k=5,
+    alpha=0.8,  # 1.0 = semantic only, 0.0 = keyword only
+)
+dspy.configure(lm=dspy.LM("openai/gpt-4o"), rm=rm)
+
+# Any dspy.Retrieve() now uses Moss
+class RAG(dspy.Module):
+    def __init__(self):
+        self.retrieve = dspy.Retrieve(k=3)
+        self.generate = dspy.ChainOfThought("context, question -> answer")
+
+    def forward(self, question):
+        context = self.retrieve(question).passages
+        return self.generate(context=context, question=question)
+
+rag = RAG()
+print(rag("How long do refunds take?").answer)
+```
+
+### As a ReAct tool
+
+`MossRM.forward()` is already sync, so pass the instance directly — no wrapper needed:
+
+```python
+import dspy
+from dspy_moss import MossRM
+
+rm = MossRM(index_name="support-kb", k=5)
+rm.load_index()
+agent = dspy.ReAct(signature="question -> answer", tools=[rm])
+print(agent(question="What payment methods do you accept?").answer)
+```
+
+### With an explicit client
+
+```python
+from moss import MossClient
+from dspy_moss import MossRM
+
+client = MossClient("proj-id", "proj-key")
+rm = MossRM(index_name="my-index", moss_client=client, k=5)
+```
+
+## Configuration
+
+### MossRM
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `index_name` | (required) | Name of the Moss index to query |
+| `moss_client` | `None` | Existing `MossClient`. When omitted, one is created from credentials |
+| `project_id` | `MOSS_PROJECT_ID` env var | Moss project ID |
+| `project_key` | `MOSS_PROJECT_KEY` env var | Moss project key |
+| `k` | `3` | Default number of passages per query |
+| `alpha` | `0.8` | Search blend: 1.0 = semantic only, 0.0 = keyword only |
+
+### Passage format
+
+Each entry in `result.passages` is a dict with:
+
+| Key | Type | Description |
+| --- | --- | --- |
+| `long_text` | `str` | Document text (DSPy's standard passage field) |
+| `id` | `str` | Document ID |
+| `score` | `float` | Relevance score |
+| `metadata` | `dict` | Key-value metadata stored with the document |
+
+### Mutable index helpers
+
+`MossRM` also exposes two optional helpers for agents that write to the knowledge base:
+
+```python
+# Read documents
+objects = rm.get_objects(num_samples=10)
+
+# Add / upsert documents
+rm.insert([{"id": "doc-1", "text": "New fact.", "metadata": {"source": "agent"}}])
+```
+
+## License
+
+BSD 2-Clause — see [LICENSE](LICENSE).
+
+## Support
+
+- [Moss Docs](https://docs.moss.dev)
+- [Moss Discord](https://discord.gg/eMXExuafBR)
+- [DSPy Docs](https://dspy.ai)

dspy_moss-0.0.1/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "dspy-moss"
+version = "0.0.1"
+description = "Moss semantic search retrieval module for DSPy"
+readme = "README.md"
+license = { text = "BSD-2-Clause" }
+requires-python = ">=3.10,<3.15"
+dependencies = [
+    "moss>=1.1.1",
+    "dspy>=2.0.0",
+]
+
+[dependency-groups]
+dev = [
+    "python-dotenv>=1.2.1",
+    "ruff>=0.1.0",
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23.0",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "B", "UP", "D"]
+ignore = ["D100", "D104"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["D101", "D102", "D103", "D107"]
+"examples/**/*.py" = ["D101", "D102", "D103"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+namespaces = false

dspy_moss-0.0.1/setup.cfg

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

dspy_moss-0.0.1/src/dspy_moss/__init__.py

@@ -0,0 +1,22 @@
+"""Moss semantic search retrieval module for DSPy."""
+
+from __future__ import annotations
+
+from moss import (
+    DocumentInfo,
+    GetDocumentsOptions,
+    IndexInfo,
+    MossClient,
+    SearchResult,
+)
+
+from .retrieve import MossRM
+
+__all__ = [
+    "DocumentInfo",
+    "GetDocumentsOptions",
+    "IndexInfo",
+    "MossClient",
+    "MossRM",
+    "SearchResult",
+]

dspy_moss-0.0.1/src/dspy_moss/retrieve.py

@@ -0,0 +1,239 @@
+#
+# Copyright (c) 2025, InferEdge Inc.
+#
+# SPDX-License-Identifier: BSD 2-Clause License
+#
+
+"""DSPy retrieval module backed by Moss semantic search."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any
+
+import dspy
+from moss import DocumentInfo, MossClient, MutationOptions, QueryOptions
+
+
+class _DotDict(dict):
+    """Dict with attribute-style read access, compatible with DSPy passage objects."""
+
+    __getattr__ = dict.get  # type: ignore[assignment]
+
+
+__all__ = ["MossRM"]
+
+logger = logging.getLogger("dspy_moss")
+
+
+class MossRM(dspy.Retrieve):
+    """DSPy retrieval module that uses Moss for sub-10ms semantic search.
+
+    Integrates with DSPy's RM interface so it can be set as the default
+    retriever via ``dspy.configure(rm=MossRM(...))``, or used directly as
+    a tool in ``dspy.ReAct``.
+
+    Args:
+        index_name: Name of the Moss index to query.
+        moss_client: An existing ``MossClient`` instance. When omitted, one
+            is created from ``project_id`` / ``project_key`` (or their env-var
+            equivalents ``MOSS_PROJECT_ID`` / ``MOSS_PROJECT_KEY``).
+        project_id: Moss project ID. Falls back to ``MOSS_PROJECT_ID`` env var.
+        project_key: Moss project key. Falls back to ``MOSS_PROJECT_KEY`` env var.
+        k: Default number of passages to retrieve per query (default: 3).
+        alpha: Hybrid search blend — 1.0 = pure semantic, 0.0 = pure keyword
+            (default: 0.8).
+
+    Examples::
+
+        import dspy
+        from dspy_moss import MossRM
+
+        rm = MossRM("my-index")          # reads MOSS_PROJECT_ID / KEY from env
+        dspy.configure(lm=dspy.LM("openai/gpt-4o"), rm=rm)
+
+        retrieve = dspy.Retrieve(k=3)
+        result = retrieve("What is the refund policy?")
+        print(result.passages)
+    """
+
+    def __init__(
+        self,
+        index_name: str,
+        moss_client: MossClient | None = None,
+        project_id: str | None = None,
+        project_key: str | None = None,
+        k: int = 3,
+        alpha: float = 0.8,
+    ):
+        """Initialize the MossRM retrieval module."""
+        if moss_client is None:
+            resolved_id = project_id or os.getenv("MOSS_PROJECT_ID") or ""
+            resolved_key = project_key or os.getenv("MOSS_PROJECT_KEY") or ""
+            if not resolved_id or not resolved_key:
+                raise ValueError(
+                    "Moss credentials required. Provide moss_client or project_id/project_key, "
+                    "or set MOSS_PROJECT_ID and MOSS_PROJECT_KEY environment variables."
+                )
+            moss_client = MossClient(resolved_id, resolved_key)
+
+        self._index_name = index_name
+        self._client = moss_client
+        self._alpha = alpha
+        self._executor = ThreadPoolExecutor(max_workers=1, thread_name_prefix="dspy-moss")
+        super().__init__(k=k)
+
+    # ------------------------------------------------------------------
+    # Async helper
+    # ------------------------------------------------------------------
+
+    def _run(self, coro: Any) -> Any:
+        """Run a coroutine from sync context, safe inside a running event loop."""
+        try:
+            asyncio.get_running_loop()
+            in_running_loop = True
+        except RuntimeError:
+            in_running_loop = False
+
+        if in_running_loop:
+            return self._executor.submit(asyncio.run, coro).result()
+        return asyncio.run(coro)
+
+    def close(self) -> None:
+        """Release the background executor used when called inside an event loop."""
+        self._executor.shutdown(wait=True)
+
+    def __enter__(self) -> MossRM:
+        """Return this retriever for use as a context manager."""
+        return self
+
+    def __exit__(self, *_exc_info: object) -> None:
+        """Release executor resources when leaving a context manager."""
+        self.close()
+
+    # ------------------------------------------------------------------
+    # Index loading
+    # ------------------------------------------------------------------
+
+    def load_index(
+        self,
+        auto_refresh: bool = False,
+        polling_interval_in_seconds: int = 600,
+    ) -> None:
+        """Load the index into memory for fast local queries.
+
+        Without this, every query falls back to the cloud API. Call once at
+        startup before any ``forward()`` or ``dspy.Retrieve`` calls.
+
+        Args:
+            auto_refresh: Reload automatically when the cloud index is updated.
+            polling_interval_in_seconds: Refresh interval when ``auto_refresh=True``.
+        """
+        logger.info("Loading Moss index '%s' into memory", self._index_name)
+        self._run(
+            self._client.load_index(
+                self._index_name,
+                auto_refresh=auto_refresh,
+                polling_interval_in_seconds=polling_interval_in_seconds,
+            )
+        )
+        logger.info("Moss index '%s' ready", self._index_name)
+
+    def forward(
+        self,
+        query_or_queries: str | list[str],
+        k: int | None = None,
+        **kwargs: Any,
+    ) -> list[_DotDict]:
+        """Retrieve the top-k passages for one or more queries.
+
+        Returns a list of dot-accessible dicts (``long_text``, ``id``,
+        ``score``, ``metadata``). DSPy's ``Retrieve`` base class wraps this
+        list in a ``Prediction`` and extracts ``long_text`` from each item.
+
+        Args:
+            query_or_queries: A single query string or a list of query strings.
+            k: Number of passages to retrieve. Defaults to ``self.k``.
+            **kwargs: Additional keyword arguments.
+        """
+        k = k if k is not None else self.k
+        queries = (
+            [query_or_queries]
+            if isinstance(query_or_queries, str)
+            else query_or_queries
+        )
+        queries = [q for q in queries if q]
+
+        option_kwargs = dict(kwargs)
+        top_k = option_kwargs.pop("top_k", k)
+        alpha = option_kwargs.pop("alpha", self._alpha)
+
+        passages = []
+        for query in queries:
+            result = self._run(
+                self._client.query(
+                    self._index_name,
+                    query,
+                    options=QueryOptions(top_k=top_k, alpha=alpha, **option_kwargs),
+                )
+            )
+            for doc in result.docs:
+                passages.append(
+                    _DotDict(
+                        long_text=doc.text,
+                        id=doc.id,
+                        score=doc.score,
+                        metadata=doc.metadata or {},
+                    )
+                )
+            logger.debug("Moss query '%s' returned %d docs", query, len(result.docs))
+
+        return passages
+
+    # ------------------------------------------------------------------
+    # Mutable RM helpers (optional — for agents that write to the index)
+    # ------------------------------------------------------------------
+
+    def get_objects(self, num_samples: int = 5) -> list[dict[str, Any]]:
+        """Fetch up to ``num_samples`` documents from the index.
+
+        Args:
+            num_samples: Maximum number of documents to return.
+
+        Returns:
+            List of dicts with ``id``, ``text``, and ``metadata`` keys.
+        """
+        docs = self._run(self._client.get_docs(self._index_name))
+        return [
+            {"id": d.id, "text": d.text, "metadata": d.metadata or {}}
+            for d in docs[:num_samples]
+        ]
+
+    def insert(self, new_objects: dict[str, Any] | list[dict[str, Any]]) -> None:
+        """Add or upsert documents into the index.
+
+        Args:
+            new_objects: A single document dict or a list of dicts.
+                Each dict must have an ``id`` and ``text`` key; ``metadata``
+                is optional.
+        """
+        if isinstance(new_objects, dict):
+            new_objects = [new_objects]
+
+        moss_docs = [
+            DocumentInfo(
+                id=obj["id"],
+                text=obj["text"],
+                metadata={str(k): str(v) for k, v in obj.get("metadata", {}).items()} or None,
+            )
+            for obj in new_objects
+        ]
+        self._run(
+            self._client.add_docs(
+                self._index_name, moss_docs, options=MutationOptions(upsert=True)
+            )
+        )
+        logger.info("Inserted %d documents into Moss index '%s'", len(moss_docs), self._index_name)

dspy_moss-0.0.1/src/dspy_moss.egg-info/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: dspy-moss
+Version: 0.0.1
+Summary: Moss semantic search retrieval module for DSPy
+License: BSD-2-Clause
+Requires-Python: <3.15,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: moss>=1.1.1
+Requires-Dist: dspy>=2.0.0
+Dynamic: license-file
+
+# dspy-moss
+
+Moss semantic search retrieval module for [DSPy](https://dspy.ai).
+
+Provides `MossRM` — a `dspy.Retrieve` subclass that plugs into DSPy's RM interface for sub-10ms knowledge retrieval with no external embedder.
+
+## Installation
+
+```bash
+pip install dspy-moss
+# or
+uv add dspy-moss
+```
+
+## Quickstart
+
+```python
+import dspy
+from dspy_moss import MossRM
+
+# Reads MOSS_PROJECT_ID and MOSS_PROJECT_KEY from environment
+rm = MossRM(index_name="my-index")
+rm.load_index()  # load into this process's memory before querying
+dspy.configure(lm=dspy.LM("openai/gpt-4o"), rm=rm)
+
+retrieve = dspy.Retrieve(k=3)
+result = retrieve("What is the refund policy?")
+for passage in result.passages:
+    print(f"[{passage['score']:.3f}] {passage['long_text']}")
+```
+
+## Usage patterns
+
+### As a configured retriever
+
+Set `MossRM` as the default retriever for all `dspy.Retrieve` calls in your program:
+
+```python
+import dspy
+from dspy_moss import MossRM
+
+rm = MossRM(
+    index_name="support-kb",
+    k=5,
+    alpha=0.8,  # 1.0 = semantic only, 0.0 = keyword only
+)
+dspy.configure(lm=dspy.LM("openai/gpt-4o"), rm=rm)
+
+# Any dspy.Retrieve() now uses Moss
+class RAG(dspy.Module):
+    def __init__(self):
+        self.retrieve = dspy.Retrieve(k=3)
+        self.generate = dspy.ChainOfThought("context, question -> answer")
+
+    def forward(self, question):
+        context = self.retrieve(question).passages
+        return self.generate(context=context, question=question)
+
+rag = RAG()
+print(rag("How long do refunds take?").answer)
+```
+
+### As a ReAct tool
+
+`MossRM.forward()` is already sync, so pass the instance directly — no wrapper needed:
+
+```python
+import dspy
+from dspy_moss import MossRM
+
+rm = MossRM(index_name="support-kb", k=5)
+rm.load_index()
+agent = dspy.ReAct(signature="question -> answer", tools=[rm])
+print(agent(question="What payment methods do you accept?").answer)
+```
+
+### With an explicit client
+
+```python
+from moss import MossClient
+from dspy_moss import MossRM
+
+client = MossClient("proj-id", "proj-key")
+rm = MossRM(index_name="my-index", moss_client=client, k=5)
+```
+
+## Configuration
+
+### MossRM
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `index_name` | (required) | Name of the Moss index to query |
+| `moss_client` | `None` | Existing `MossClient`. When omitted, one is created from credentials |
+| `project_id` | `MOSS_PROJECT_ID` env var | Moss project ID |
+| `project_key` | `MOSS_PROJECT_KEY` env var | Moss project key |
+| `k` | `3` | Default number of passages per query |
+| `alpha` | `0.8` | Search blend: 1.0 = semantic only, 0.0 = keyword only |
+
+### Passage format
+
+Each entry in `result.passages` is a dict with:
+
+| Key | Type | Description |
+| --- | --- | --- |
+| `long_text` | `str` | Document text (DSPy's standard passage field) |
+| `id` | `str` | Document ID |
+| `score` | `float` | Relevance score |
+| `metadata` | `dict` | Key-value metadata stored with the document |
+
+### Mutable index helpers
+
+`MossRM` also exposes two optional helpers for agents that write to the knowledge base:
+
+```python
+# Read documents
+objects = rm.get_objects(num_samples=10)
+
+# Add / upsert documents
+rm.insert([{"id": "doc-1", "text": "New fact.", "metadata": {"source": "agent"}}])
+```
+
+## License
+
+BSD 2-Clause — see [LICENSE](LICENSE).
+
+## Support
+
+- [Moss Docs](https://docs.moss.dev)
+- [Moss Discord](https://discord.gg/eMXExuafBR)
+- [DSPy Docs](https://dspy.ai)

dspy_moss-0.0.1/src/dspy_moss.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/dspy_moss/__init__.py
+src/dspy_moss/retrieve.py
+src/dspy_moss.egg-info/PKG-INFO
+src/dspy_moss.egg-info/SOURCES.txt
+src/dspy_moss.egg-info/dependency_links.txt
+src/dspy_moss.egg-info/requires.txt
+src/dspy_moss.egg-info/top_level.txt
+tests/test_retrieve.py

dspy_moss-0.0.1/src/dspy_moss.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

dspy_moss-0.0.1/src/dspy_moss.egg-info/requires.txt

@@ -0,0 +1,2 @@
+moss>=1.1.1
+dspy>=2.0.0

dspy_moss-0.0.1/src/dspy_moss.egg-info/top_level.txt

@@ -0,0 +1 @@
+dspy_moss

dspy_moss-0.0.1/tests/test_retrieve.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import pytest
+
+from dspy_moss import MossRM
+
+
+@dataclass
+class FakeDoc:
+    id: str
+    text: str
+    score: float
+    metadata: dict[str, str] | None = None
+
+
+@dataclass
+class FakeResult:
+    docs: list[FakeDoc]
+
+
+class FakeMossClient:
+    def __init__(self) -> None:
+        self.queries: list[dict[str, Any]] = []
+        self.load_calls: list[dict[str, Any]] = []
+
+    async def query(self, index_name: str, query: str, options: Any) -> FakeResult:
+        self.queries.append({"index_name": index_name, "query": query, "options": options})
+        return FakeResult(
+            docs=[
+                FakeDoc(
+                    id=f"{query}-1",
+                    text=f"passage for {query}",
+                    score=0.91,
+                    metadata={"source": "unit-test"},
+                )
+            ]
+        )
+
+    async def load_index(
+        self,
+        index_name: str,
+        auto_refresh: bool = False,
+        polling_interval_in_seconds: int = 600,
+    ) -> str:
+        self.load_calls.append(
+            {
+                "index_name": index_name,
+                "auto_refresh": auto_refresh,
+                "polling_interval_in_seconds": polling_interval_in_seconds,
+            }
+        )
+        return index_name
+
+
+def test_forward_returns_dspy_passage_objects_and_query_options() -> None:
+    client = FakeMossClient()
+    rm = MossRM(index_name="support-kb", moss_client=client, k=3, alpha=0.8)
+
+    try:
+        passages = rm.forward("refund policy", k=5, alpha=0.25, filter={"tier": "pro"})
+    finally:
+        rm.close()
+
+    assert len(passages) == 1
+    assert passages[0].long_text == "passage for refund policy"
+    assert passages[0]["long_text"] == "passage for refund policy"
+    assert passages[0].id == "refund policy-1"
+    assert passages[0].score == 0.91
+    assert passages[0].metadata == {"source": "unit-test"}
+
+    assert client.queries[0]["index_name"] == "support-kb"
+    assert client.queries[0]["query"] == "refund policy"
+    options = client.queries[0]["options"]
+    assert options.top_k == 5
+    assert options.alpha == 0.25
+    assert options.filter == {"tier": "pro"}
+
+
+def test_forward_handles_multiple_queries_and_skips_empty_queries() -> None:
+    client = FakeMossClient()
+    rm = MossRM(index_name="support-kb", moss_client=client, k=2)
+
+    try:
+        passages = rm.forward(["refund policy", "", "payment methods"])
+    finally:
+        rm.close()
+
+    assert [call["query"] for call in client.queries] == ["refund policy", "payment methods"]
+    assert [passage.long_text for passage in passages] == [
+        "passage for refund policy",
+        "passage for payment methods",
+    ]
+    assert all(call["options"].top_k == 2 for call in client.queries)
+    assert all(call["options"].alpha == pytest.approx(0.8) for call in client.queries)
+
+
+@pytest.mark.asyncio
+async def test_forward_inside_running_event_loop_reuses_executor() -> None:
+    client = FakeMossClient()
+    rm = MossRM(index_name="support-kb", moss_client=client)
+    executor = rm._executor
+
+    try:
+        first = rm.forward("first")
+        second = rm.forward("second")
+    finally:
+        rm.close()
+
+    assert rm._executor is executor
+    assert [call["query"] for call in client.queries] == ["first", "second"]
+    assert first[0].long_text == "passage for first"
+    assert second[0].long_text == "passage for second"
+
+
+def test_load_index_forwards_refresh_options() -> None:
+    client = FakeMossClient()
+    rm = MossRM(index_name="support-kb", moss_client=client)
+
+    try:
+        rm.load_index(auto_refresh=True, polling_interval_in_seconds=120)
+    finally:
+        rm.close()
+
+    assert client.load_calls == [
+        {
+            "index_name": "support-kb",
+            "auto_refresh": True,
+            "polling_interval_in_seconds": 120,
+        }
+    ]