dewey-haystack 0.1.0__py3-none-any.whl

dewey_haystack-0.1.0.dist-info/METADATA

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: dewey-haystack
+Version: 0.1.0
+Summary: Haystack integration for Dewey — document store, retriever, and research component
+Author-email: Dewey <hi@meetdewey.com>
+License-Expression: MIT
+Project-URL: Homepage, https://meetdewey.com
+Project-URL: Repository, https://github.com/meetdewey/dewey-haystack
+Keywords: haystack,dewey,rag,retrieval,document-store,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: meetdewey>=1.0
+Requires-Dist: haystack-ai>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-mock>=3; extra == "dev"
+
+# dewey-haystack
+
+[![CI](https://github.com/meetdewey/dewey-haystack/actions/workflows/ci.yml/badge.svg)](https://github.com/meetdewey/dewey-haystack/actions/workflows/ci.yml)
+
+[Haystack](https://haystack.deepset.ai/) integration for [Dewey](https://meetdewey.com) — document store, retriever, and research component.
+
+## Installation
+
+```bash
+pip install dewey-haystack
+```
+
+## Components
+
+### DeweyDocumentStore
+
+Haystack DocumentStore backed by a Dewey collection. Handles document upload and deletion; Dewey manages chunking and embeddings automatically.
+
+```python
+from haystack_integrations.document_stores.dewey import DeweyDocumentStore
+from haystack.utils import Secret
+
+store = DeweyDocumentStore(
+    api_key=Secret.from_env_var("DEWEY_API_KEY"),
+    collection_id="3f7a1b2c-...",
+)
+```
+
+Upload Haystack Documents:
+
+```python
+from haystack import Document
+
+store.write_documents([
+    Document(content="Neural networks learn via backpropagation.", meta={"source": "ml.txt"}),
+    Document(content="Transformers use self-attention mechanisms."),
+])
+```
+
+### DeweyRetriever
+
+Drop-in Haystack retriever backed by Dewey's hybrid semantic + BM25 search.
+
+```python
+from haystack import Pipeline
+from haystack_integrations.document_stores.dewey import DeweyDocumentStore
+from haystack_integrations.components.retrievers.dewey import DeweyRetriever
+from haystack.utils import Secret
+
+store = DeweyDocumentStore(
+    api_key=Secret.from_env_var("DEWEY_API_KEY"),
+    collection_id="3f7a1b2c-...",
+)
+
+pipeline = Pipeline()
+pipeline.add_component("retriever", DeweyRetriever(document_store=store, top_k=8))
+
+result = pipeline.run({"retriever": {"query": "What are the key findings?"}})
+for doc in result["retriever"]["documents"]:
+    print(f"[{doc.meta['filename']}] {doc.content}")
+```
+
+Each returned `Document` carries citation metadata:
+
+| Field | Description |
+|---|---|
+| `score` | Relevance score (0–1) |
+| `document_id` | Dewey document ID |
+| `filename` | Original filename |
+| `section_id` | Section ID |
+| `section_title` | Section heading |
+| `section_level` | Heading depth (1 = top-level) |
+
+**RAG pipeline with an LLM:**
+
+```python
+from haystack.components.builders import PromptBuilder
+from haystack.components.generators import OpenAIGenerator
+
+prompt_template = """
+Answer the question using only the provided context.
+
+Context:
+{% for doc in documents %}
+- {{ doc.content }}
+{% endfor %}
+
+Question: {{ query }}
+"""
+
+pipeline = Pipeline()
+pipeline.add_component("retriever", DeweyRetriever(document_store=store, top_k=5))
+pipeline.add_component("prompt", PromptBuilder(template=prompt_template))
+pipeline.add_component("llm", OpenAIGenerator(model="gpt-4o-mini"))
+
+pipeline.connect("retriever.documents", "prompt.documents")
+pipeline.connect("prompt.prompt", "llm.prompt")
+
+result = pipeline.run({
+    "retriever": {"query": "What were the main findings?"},
+    "prompt": {"query": "What were the main findings?"},
+})
+print(result["llm"]["replies"][0])
+```
+
+### DeweyResearchComponent
+
+A Haystack component that runs Dewey's full agentic research loop — searching, reading, and synthesising across multiple documents — and returns a grounded Markdown answer with cited sources.
+
+Use this as a drop-in replacement for an LLM generator when you want Dewey to handle both retrieval *and* generation.
+
+```python
+from haystack import Pipeline
+from haystack_integrations.components.retrievers.dewey import DeweyResearchComponent
+from haystack.utils import Secret
+
+pipeline = Pipeline()
+pipeline.add_component(
+    "research",
+    DeweyResearchComponent(
+        api_key=Secret.from_env_var("DEWEY_API_KEY"),
+        collection_id="3f7a1b2c-...",
+        depth="balanced",
+    ),
+)
+
+result = pipeline.run({"research": {"query": "What were the key findings across all studies?"}})
+print(result["research"]["answer"])
+
+for source in result["research"]["sources"]:
+    print(f"  [{source.meta['filename']}] {source.content[:80]}...")
+```
+
+**Outputs:**
+
+| Key | Type | Description |
+|---|---|---|
+| `answer` | `str` | Synthesised Markdown answer |
+| `sources` | `list[Document]` | Source chunks cited by the answer |
+
+**Research depths:**
+
+| depth | Speed | Tools | Requires BYOK |
+|---|---|---|---|
+| `quick` | fast | basic search | no |
+| `balanced` | fast | basic search | no |
+| `deep` | slower | full tool suite | yes |
+| `exhaustive` | slowest | full tool suite | yes |
+
+`deep` and `exhaustive` require a Dewey Pro plan and a BYOK API key configured on your project.
+
+**With a custom model:**
+
+```python
+DeweyResearchComponent(
+    api_key=Secret.from_env_var("DEWEY_API_KEY"),
+    collection_id="3f7a1b2c-...",
+    depth="deep",
+    model="claude-sonnet-4-6",  # requires Anthropic BYOK key on your project
+)
+```
+
+## Requirements
+
+- Python 3.9+
+- `meetdewey >= 1.0`
+- `haystack-ai >= 2.0`
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

dewey_haystack-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+haystack_integrations/components/retrievers/dewey/__init__.py,sha256=NmjzgaPoebXfq31dse_dH-7VK-jTOJQxnpfs81Fw_T8,277
+haystack_integrations/components/retrievers/dewey/dewey_research_component.py,sha256=WIQ6odb_835QdvWJR6eDulKujoT8_jRLsrrujUpk5kE,6190
+haystack_integrations/components/retrievers/dewey/dewey_retriever.py,sha256=lFPXpNauvT0ot-q5teBS29o5xksMJBQor9HMuU7hNDk,4126
+haystack_integrations/document_stores/dewey/__init__.py,sha256=8i96VIg-8vh1oWZENMMBuZtMJQo4ho-J31k7tJSxU7o,139
+haystack_integrations/document_stores/dewey/dewey_document_store.py,sha256=GGpJ0CTvhQW2Ir522Sfwi4tOVMd1tpYFupyBK0LD9dQ,8391
+dewey_haystack-0.1.0.dist-info/METADATA,sha256=PWDpEDxyt1jyMLjD1GFRLIXn7nBmGb_izxzY0c5zd7I,5901
+dewey_haystack-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+dewey_haystack-0.1.0.dist-info/top_level.txt,sha256=xEV0YMHti-yzzXgkLgSzsILiqsuC91-4ShNpDgsKNRI,22
+dewey_haystack-0.1.0.dist-info/RECORD,,

dewey_haystack-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

dewey_haystack-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+haystack_integrations

haystack_integrations/components/retrievers/dewey/__init__.py

@@ -0,0 +1,8 @@
+from haystack_integrations.components.retrievers.dewey.dewey_research_component import (
+    DeweyResearchComponent,
+)
+from haystack_integrations.components.retrievers.dewey.dewey_retriever import (
+    DeweyRetriever,
+)
+
+__all__ = ["DeweyRetriever", "DeweyResearchComponent"]

haystack_integrations/components/retrievers/dewey/dewey_research_component.py

@@ -0,0 +1,162 @@
+"""DeweyResearchComponent — Haystack component that runs a full Dewey research query."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from haystack import Document, component, default_from_dict, default_to_dict
+from haystack.utils import Secret, deserialize_secrets_inplace
+
+
+@component
+class DeweyResearchComponent:
+    """Haystack component that performs agentic research over a Dewey collection.
+
+    Unlike :class:`DeweyRetriever` (single-shot search), this component runs
+    Dewey's full multi-step research loop: it searches, reads, and synthesises
+    content across multiple documents, returning a grounded Markdown answer and
+    the source chunks it cited.
+
+    This component is a drop-in replacement for an LLM generator in a Haystack
+    pipeline when you want Dewey to handle both retrieval *and* generation.
+
+    Example — research pipeline::
+
+        from haystack import Pipeline
+        from haystack_integrations.components.retrievers.dewey import DeweyResearchComponent
+        from haystack.utils import Secret
+
+        pipeline = Pipeline()
+        pipeline.add_component(
+            "research",
+            DeweyResearchComponent(
+                api_key=Secret.from_env_var("DEWEY_API_KEY"),
+                collection_id="3f7a1b2c-...",
+                depth="balanced",
+            ),
+        )
+
+        result = pipeline.run({"research": {"query": "What were the key findings?"}})
+        print(result["research"]["answer"])
+        for source in result["research"]["sources"]:
+            print(f"  [{source.meta['filename']}] {source.content[:80]}...")
+
+    Research depths:
+
+    +-------------+------+-------+-------+
+    | depth       | fast | tools | BYOK  |
+    +=============+======+=======+=======+
+    | quick       | yes  | basic | no    |
+    +-------------+------+-------+-------+
+    | balanced    | yes  | basic | no    |
+    +-------------+------+-------+-------+
+    | deep        | no   | full  | yes   |
+    +-------------+------+-------+-------+
+    | exhaustive  | no   | full  | yes   |
+    +-------------+------+-------+-------+
+
+    ``deep`` and ``exhaustive`` depths require a Pro plan and a BYOK API key
+    configured on your Dewey project.
+    """
+
+    def __init__(
+        self,
+        api_key: Secret = Secret.from_env_var("DEWEY_API_KEY"),  # noqa: B008
+        collection_id: str = "",
+        depth: str = "balanced",
+        model: Optional[str] = None,
+        base_url: str = "https://api.meetdewey.com/v1",
+    ) -> None:
+        """
+        Args:
+            api_key: Dewey project API key. Defaults to the ``DEWEY_API_KEY``
+                environment variable.
+            collection_id: ID of the Dewey collection to research.
+            depth: Research depth — ``"quick"``, ``"balanced"`` (default),
+                ``"deep"``, or ``"exhaustive"``.
+            model: Optional model override (e.g. ``"gpt-4o"``,
+                ``"claude-sonnet-4-6"``). Defaults to Dewey's server-side
+                default for the chosen depth.
+            base_url: Dewey API base URL. Override for local development.
+        """
+        if depth not in ("quick", "balanced", "deep", "exhaustive"):
+            raise ValueError(
+                f"Invalid depth {depth!r}. Must be one of: quick, balanced, deep, exhaustive"
+            )
+        self.api_key = api_key
+        self.collection_id = collection_id
+        self.depth = depth
+        self.model = model
+        self.base_url = base_url
+        self._client: Any = None
+
+    def _get_client(self) -> Any:
+        if self._client is None:
+            from dewey import DeweyClient
+
+            self._client = DeweyClient(
+                api_key=self.api_key.resolve_value(), base_url=self.base_url
+            )
+        return self._client
+
+    @component.output_types(answer=str, sources=List[Document])
+    def run(self, query: str) -> Dict[str, Any]:
+        """Run a research query against the collection.
+
+        Streams the Dewey research SSE endpoint internally and returns the
+        completed answer once the stream closes.
+
+        Args:
+            query: The research question.
+
+        Returns:
+            A dict with:
+            - ``"answer"`` (``str``): The synthesised Markdown answer.
+            - ``"sources"`` (``list[Document]``): Source chunks cited, each
+              with ``content`` and metadata (``filename``, ``document_id``,
+              ``section_id``, ``section_title``, ``section_level``).
+        """
+        client = self._get_client()
+        kwargs: Dict[str, Any] = {"depth": self.depth}
+        if self.model:
+            kwargs["model"] = self.model
+
+        answer_parts: List[str] = []
+        sources: List[Document] = []
+
+        for event in client.research.stream(self.collection_id, query, **kwargs):
+            if event.type == "chunk":
+                answer_parts.append(event.content)
+            elif event.type == "done":
+                sources = [
+                    Document(
+                        content=s.content,
+                        meta={
+                            "document_id": s.documentId,
+                            "filename": s.filename,
+                            "section_id": s.sectionId,
+                            "section_title": s.sectionTitle,
+                            "section_level": s.sectionLevel,
+                        },
+                    )
+                    for s in (getattr(event, "sources", None) or [])
+                ]
+            elif event.type == "error":
+                raise RuntimeError(f"Dewey research error: {event.message}")
+
+        return {"answer": "".join(answer_parts), "sources": sources}
+
+    def to_dict(self) -> Dict[str, Any]:
+        return default_to_dict(
+            self,
+            api_key=self.api_key.to_dict(),
+            collection_id=self.collection_id,
+            depth=self.depth,
+            model=self.model,
+            base_url=self.base_url,
+        )
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "DeweyResearchComponent":
+        deserialize_secrets_inplace(data["init_parameters"], keys=["api_key"])
+        return default_from_dict(cls, data)

haystack_integrations/components/retrievers/dewey/dewey_retriever.py

@@ -0,0 +1,116 @@
+"""DeweyRetriever — Haystack component backed by Dewey hybrid search."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from haystack import Document, component, default_from_dict, default_to_dict
+
+from haystack_integrations.document_stores.dewey import DeweyDocumentStore
+
+
+@component
+class DeweyRetriever:
+    """Haystack retriever that queries a Dewey collection.
+
+    Uses Dewey's hybrid semantic + BM25 search and returns chunks as Haystack
+    ``Document`` objects with full citation metadata.
+
+    Must be paired with a :class:`~haystack_integrations.document_stores.dewey.DeweyDocumentStore`.
+
+    Example — standalone retrieval pipeline::
+
+        from haystack import Pipeline
+        from haystack_integrations.document_stores.dewey import DeweyDocumentStore
+        from haystack_integrations.components.retrievers.dewey import DeweyRetriever
+        from haystack.utils import Secret
+
+        store = DeweyDocumentStore(
+            api_key=Secret.from_env_var("DEWEY_API_KEY"),
+            collection_id="3f7a1b2c-...",
+        )
+
+        pipeline = Pipeline()
+        pipeline.add_component("retriever", DeweyRetriever(document_store=store, top_k=8))
+
+        result = pipeline.run({"retriever": {"query": "What are the key findings?"}})
+        for doc in result["retriever"]["documents"]:
+            print(doc.content, doc.meta["score"])
+
+    Example — RAG pipeline with an LLM::
+
+        from haystack.components.builders import PromptBuilder
+        from haystack.components.generators import OpenAIGenerator
+
+        prompt_template = \"\"\"
+        Answer the question using the provided context.
+        Context:
+        {% for doc in documents %}{{ doc.content }}{% endfor %}
+        Question: {{ query }}
+        \"\"\"
+
+        pipeline = Pipeline()
+        pipeline.add_component("retriever", DeweyRetriever(document_store=store, top_k=5))
+        pipeline.add_component("prompt", PromptBuilder(template=prompt_template))
+        pipeline.add_component("llm", OpenAIGenerator(model="gpt-4o-mini"))
+
+        pipeline.connect("retriever.documents", "prompt.documents")
+        pipeline.connect("prompt.prompt", "llm.prompt")
+
+        result = pipeline.run({
+            "retriever": {"query": "summarise the main themes"},
+            "prompt": {"query": "summarise the main themes"},
+        })
+        print(result["llm"]["replies"][0])
+    """
+
+    def __init__(
+        self,
+        document_store: DeweyDocumentStore,
+        top_k: int = 10,
+        filters: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """
+        Args:
+            document_store: A :class:`DeweyDocumentStore` instance.
+            top_k: Maximum number of chunks to return (1–50).
+            filters: Unused — present for interface compatibility. Dewey does
+                not support metadata filtering at retrieval time.
+        """
+        self.document_store = document_store
+        self.top_k = top_k
+        self.filters = filters
+
+    @component.output_types(documents=List[Document])
+    def run(
+        self,
+        query: str,
+        top_k: Optional[int] = None,
+    ) -> Dict[str, List[Document]]:
+        """Run the retriever.
+
+        Args:
+            query: The search query.
+            top_k: Override the instance-level ``top_k`` for this call.
+
+        Returns:
+            A dict with a single key ``"documents"`` containing a list of
+            :class:`~haystack.Document` objects ordered by relevance score.
+        """
+        k = top_k if top_k is not None else self.top_k
+        documents = self.document_store._search(query, k)
+        return {"documents": documents}
+
+    def to_dict(self) -> Dict[str, Any]:
+        return default_to_dict(
+            self,
+            document_store=self.document_store.to_dict(),
+            top_k=self.top_k,
+        )
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "DeweyRetriever":
+        data["init_parameters"]["document_store"] = DeweyDocumentStore.from_dict(
+            data["init_parameters"]["document_store"]
+        )
+        return default_from_dict(cls, data)

haystack_integrations/document_stores/dewey/__init__.py

@@ -0,0 +1,5 @@
+from haystack_integrations.document_stores.dewey.dewey_document_store import (
+    DeweyDocumentStore,
+)
+
+__all__ = ["DeweyDocumentStore"]

haystack_integrations/document_stores/dewey/dewey_document_store.py

@@ -0,0 +1,210 @@
+"""DeweyDocumentStore — Haystack DocumentStore backed by a Dewey collection."""
+
+from __future__ import annotations
+
+import io
+import time
+from typing import Any, Dict, List, Optional
+
+from haystack import Document, default_from_dict, default_to_dict
+from haystack.document_stores.types import DocumentStore, DuplicatePolicy
+from haystack.utils import Secret, deserialize_secrets_inplace
+
+
+class DeweyDocumentStore:
+    """Haystack DocumentStore backed by a Dewey collection.
+
+    Dewey manages its own chunking and embeddings. Each Haystack ``Document``
+    written to the store is uploaded as a plain-text file and processed by
+    Dewey's ingestion pipeline. Use :class:`DeweyRetriever` to query the
+    store — ``filter_documents`` is intentionally limited (see below).
+
+    Example::
+
+        from haystack_integrations.document_stores.dewey import DeweyDocumentStore
+        from haystack_integrations.components.retrievers.dewey import DeweyRetriever
+        from haystack.utils import Secret
+
+        store = DeweyDocumentStore(
+            api_key=Secret.from_env_var("DEWEY_API_KEY"),
+            collection_id="3f7a1b2c-...",
+        )
+        retriever = DeweyRetriever(document_store=store, top_k=8)
+    """
+
+    def __init__(
+        self,
+        api_key: Secret = Secret.from_env_var("DEWEY_API_KEY"),  # noqa: B008
+        collection_id: str = "",
+        base_url: str = "https://api.meetdewey.com/v1",
+        poll_interval: float = 2.0,
+        poll_timeout: float = 300.0,
+    ) -> None:
+        """
+        Args:
+            api_key: Dewey project API key. Defaults to the ``DEWEY_API_KEY``
+                environment variable.
+            collection_id: ID of the Dewey collection to use.
+            base_url: Dewey API base URL. Override for local development.
+            poll_interval: Seconds between status polls in ``write_documents``.
+            poll_timeout: Maximum seconds to wait for documents to be ready.
+        """
+        self.api_key = api_key
+        self.collection_id = collection_id
+        self.base_url = base_url
+        self.poll_interval = poll_interval
+        self.poll_timeout = poll_timeout
+        self._client: Any = None
+
+    def _get_client(self) -> Any:
+        if self._client is None:
+            from dewey import DeweyClient
+
+            self._client = DeweyClient(
+                api_key=self.api_key.resolve_value(), base_url=self.base_url
+            )
+        return self._client
+
+    # ── DocumentStore protocol ────────────────────────────────────────────────
+
+    def count_documents(self) -> int:
+        """Return the number of documents (files) in the collection."""
+        client = self._get_client()
+        docs = client.documents.list(self.collection_id)
+        return len(docs)
+
+    def filter_documents(self, filters: Optional[Dict[str, Any]] = None) -> List[Document]:
+        """Return documents matching ``filters``.
+
+        Dewey does not support arbitrary metadata filtering. Passing ``filters``
+        will raise ``NotImplementedError``. Use :class:`DeweyRetriever` for
+        semantic search instead.
+
+        Calling with ``filters=None`` returns an empty list — use
+        ``count_documents`` to check collection size, and ``DeweyRetriever``
+        to retrieve content.
+        """
+        if filters is not None:
+            raise NotImplementedError(
+                "DeweyDocumentStore does not support metadata filters. "
+                "Use DeweyRetriever for semantic search."
+            )
+        return []
+
+    def write_documents(
+        self,
+        documents: List[Document],
+        policy: DuplicatePolicy = DuplicatePolicy.NONE,
+    ) -> int:
+        """Upload documents to the Dewey collection and wait for them to be ready.
+
+        Each Haystack ``Document`` is uploaded as a ``.txt`` file. The document's
+        ``id`` is used as the filename when no ``"source"`` key is present in
+        ``meta``. Dewey handles chunking and embedding automatically.
+
+        Args:
+            documents: Haystack Documents to upload. Each must have non-empty
+                ``content``.
+            policy: Duplicate handling policy. Only ``NONE`` and ``OVERWRITE``
+                are meaningful — Dewey deduplicates by content hash.
+
+        Returns:
+            Number of documents successfully submitted for ingestion.
+        """
+        client = self._get_client()
+        uploaded_ids: List[str] = []
+
+        for doc in documents:
+            if not doc.content:
+                continue
+            source = doc.meta.get("source") or doc.meta.get("filename") or f"{doc.id}.txt"
+            if "." not in source.split("/")[-1]:
+                source = f"{source}.txt"
+
+            uploaded = client.documents.upload(
+                self.collection_id,
+                io.BytesIO(doc.content.encode("utf-8")),
+                filename=source,
+                content_type="text/plain",
+            )
+            uploaded_ids.append(uploaded.id)
+
+        self._wait_for_ready(uploaded_ids)
+        return len(uploaded_ids)
+
+    def delete_documents(self, document_ids: List[str]) -> None:
+        """Delete documents from the collection by their Dewey document IDs."""
+        client = self._get_client()
+        for doc_id in document_ids:
+            client.documents.delete(self.collection_id, doc_id)
+
+    # ── Search (used by DeweyRetriever) ───────────────────────────────────────
+
+    def _wait_for_ready(self, ids: List[str]) -> None:
+        """Poll until all documents in ``ids`` reach ``ready`` status."""
+        client = self._get_client()
+        pending = set(ids)
+        deadline = time.monotonic() + self.poll_timeout
+
+        while pending and time.monotonic() < deadline:
+            still_pending: set[str] = set()
+            for doc_id in pending:
+                doc = client.documents.get(self.collection_id, doc_id)
+                if doc.status == "error":
+                    raise RuntimeError(
+                        f"Document {doc_id} failed to process: {getattr(doc, 'errorMessage', 'unknown error')}"
+                    )
+                if doc.status != "ready":
+                    still_pending.add(doc_id)
+            pending = still_pending
+            if pending:
+                time.sleep(self.poll_interval)
+
+        if pending:
+            raise TimeoutError(
+                f"{len(pending)} document(s) not ready after {self.poll_timeout}s"
+            )
+
+    def _search(self, query: str, top_k: int) -> List[Document]:
+        """Run a hybrid search and return Haystack Documents with metadata."""
+        client = self._get_client()
+        results = client.retrieval.query(self.collection_id, query, limit=top_k)
+        return [_result_to_document(r) for r in results]
+
+    # ── Serialization ─────────────────────────────────────────────────────────
+
+    def to_dict(self) -> Dict[str, Any]:
+        return default_to_dict(
+            self,
+            api_key=self.api_key.to_dict(),
+            collection_id=self.collection_id,
+            base_url=self.base_url,
+            poll_interval=self.poll_interval,
+            poll_timeout=self.poll_timeout,
+        )
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "DeweyDocumentStore":
+        deserialize_secrets_inplace(data["init_parameters"], keys=["api_key"])
+        return default_from_dict(cls, data)
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+
+def _result_to_document(r: Any) -> Document:
+    return Document(
+        content=r.chunk.content,
+        meta={
+            "score": r.score,
+            "document_id": r.document.id,
+            "filename": r.document.filename,
+            "section_id": r.section.id,
+            "section_title": r.section.title,
+            "section_level": r.section.level,
+        },
+    )
+
+
+# Register the protocol compliance check at import time
+DocumentStore.register(DeweyDocumentStore)  # type: ignore[attr-defined]