digitalkin 1.0.5.dev6__tar.gz → 1.1.0.dev0__tar.gz

{digitalkin-1.0.5.dev6 → digitalkin-1.1.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: digitalkin
-Version: 1.0.5.dev6
+Version: 1.1.0.dev0
 Summary: SDK to build kin used in DigitalKin
 Author-email: "DigitalKin.ai" <contact@digitalkin.ai>
 License: Attribution-NonCommercial-ShareAlike 4.0 International

{digitalkin-1.0.5.dev6 → digitalkin-1.1.0.dev0}/pyproject.toml

@@ -43,7 +43,7 @@
         "pydantic>=2.12.4",
         "redis[hiredis]>=7.4.0,<9",
     ]
-version = "1.0.5.dev6"
+version = "1.1.0.dev0"
 
     [project.optional-dependencies]
         agno = [ "agno>=3.1.1,<4" ]

{digitalkin-1.0.5.dev6 → digitalkin-1.1.0.dev0}/src/digitalkin/__version__.py

@@ -5,4 +5,4 @@ from importlib.metadata import PackageNotFoundError, version
 try:
     __version__ = version("digitalkin")
 except PackageNotFoundError:
-    __version__ = "1.0.5.dev6"
+    __version__ = "1.1.0.dev0"

{digitalkin-1.0.5.dev6 → digitalkin-1.1.0.dev0}/src/digitalkin/community/agno/toolkits/__init__.py

@@ -8,6 +8,7 @@ Requires the optional ``agno`` dependency — importing this subpackage without
 from digitalkin.community.agno.toolkits.base import DkToolkit
 from digitalkin.community.agno.toolkits.chat_history import ChatHistoryTools
 from digitalkin.community.agno.toolkits.defaults import DefaultToolkits
+from digitalkin.community.agno.toolkits.knowledge import KnowledgeTools
 from digitalkin.community.agno.toolkits.registry.kins.kit import KinsManager
 from digitalkin.community.agno.toolkits.registry.loader.kit import LoadManager
 from digitalkin.community.agno.toolkits.registry.services.kit import ServicesManager
@@ -19,6 +20,7 @@ __all__ = [
     "DefaultToolkits",
     "DkToolkit",
     "KinsManager",
+    "KnowledgeTools",
     "LoadManager",
     "ServicesManager",
     "ToolsManager",

{digitalkin-1.0.5.dev6 → digitalkin-1.1.0.dev0}/src/digitalkin/community/agno/toolkits/defaults.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any
 
 from digitalkin.community.agno.toolkits.chat_history import ChatHistoryTools
+from digitalkin.community.agno.toolkits.knowledge import KnowledgeTools
 from digitalkin.community.agno.toolkits.registry.kins.kit import KinsManager
 from digitalkin.community.agno.toolkits.registry.loader.kit import LoadManager
 from digitalkin.community.agno.toolkits.registry.services.kit import ServicesManager
@@ -20,7 +21,7 @@ if TYPE_CHECKING:
 
 
 class DefaultToolkits:
-    """Assemble the default DigitalKin toolkits (chat history, user profile, registry).
+    """Assemble the default DigitalKin toolkits (chat history, user profile, knowledge, registry).
 
     Two-phase usage — ChatHistoryTools needs the constructed Agent/Team::
 
@@ -46,12 +47,13 @@ class DefaultToolkits:
             session_id: The Agno session whose chat history should be readable.
 
         Returns:
-            [ChatHistoryTools, UserProfileTools,
+            [ChatHistoryTools, UserProfileTools, KnowledgeTools,
              (ToolsManager, ServicesManager, KinsManager)?, LoadManager].
         """
         tools: list[Toolkit] = [
             ChatHistoryTools(session_id=session_id, context=context),
             UserProfileTools(context.user_profile, context=context),
+            KnowledgeTools(context.knowledge, context=context),
         ]
         if context.setup is not None:
             tools.extend((

digitalkin-1.1.0.dev0/src/digitalkin/community/agno/toolkits/knowledge.py

@@ -0,0 +1,113 @@
+"""Toolkit exposing the user's connected knowledge base to the agent."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from digitalkin.community.agno.toolkits.base import DkToolkit
+from digitalkin.logger import logger
+from digitalkin.models.services.knowledge import Citation, Modality
+from digitalkin.services.knowledge.exceptions import KnowledgeServiceError
+
+if TYPE_CHECKING:
+    from digitalkin.models.module import ModuleContext
+    from digitalkin.services.knowledge.knowledge_strategy import KnowledgeStrategy
+
+
+class KnowledgeTools(DkToolkit):
+    """Toolkit that lets the agent search the enterprise knowledge base.
+
+    What the search reaches is what the *current user* connected and may read: the
+    permission filter is compiled into the query by the platform, so there is no identity
+    to pass and no result to filter afterwards.
+
+    An empty answer is a legitimate answer — nothing matched, or nothing is connected —
+    and is reported as a success with zero results so the agent says so rather than retrying.
+    """
+
+    def __init__(self, knowledge: KnowledgeStrategy, context: ModuleContext | None = None) -> None:
+        """Initialize the toolkit with the ``search_knowledge_base`` tool.
+
+        Args:
+            knowledge: The module's knowledge service strategy.
+            context: Module context; enables AG-UI notifications via the base toolkit.
+        """
+        self._knowledge = knowledge
+        super().__init__(
+            name="knowledge_tools",
+            tools=[self.search_knowledge_base],
+            context=context,
+        )
+
+    @staticmethod
+    def _row(citation: Citation) -> dict[str, Any]:
+        """Trim a citation to what an agent can reason and cite from.
+
+        ``score`` is dropped on purpose: it is a fused rank comparable only within one
+        answer, and a model shown a number reads it as a confidence.
+
+        Args:
+            citation: The citation to render.
+
+        Returns:
+            The fields worth spending context on.
+        """
+        row: dict[str, Any] = {
+            "document_id": citation.document_id,
+            "title": citation.title,
+            "passage": citation.snippet,
+            "source": citation.source,
+            "source_url": citation.source_url,
+        }
+        if headings := citation.heading_path:
+            row["section"] = " > ".join(headings)
+        if citation.modality not in {Modality.TEXT, Modality.UNSPECIFIED}:
+            row["modality"] = citation.modality.value
+        return row
+
+    async def search_knowledge_base(
+        self,
+        query: str,
+        sources: list[str] | None = None,
+        limit: int = 10,
+    ) -> str:
+        """Search the user's own documents — their connected Google Drive, Notion, and the like.
+
+        Use this whenever the answer could live in the user's company documents rather than
+        in your general knowledge: internal decisions, meeting notes, specifications,
+        contracts, processes, numbers. Prefer one precise question in natural language over
+        keywords; the search is semantic as well as lexical.
+
+        Each result is a whole passage, not an excerpt, plus the URL of the document it came
+        from — quote the passage and cite the ``source_url`` rather than paraphrasing blindly.
+        Only documents this user is allowed to read are ever returned, so anything you get
+        back is safe to show them.
+
+        An empty result list means nothing matched or nothing is connected: say so, and do
+        not call the tool again with the same question.
+
+        Args:
+            query: The question to answer, in natural language (1-4000 characters).
+            sources: Restrict the search to these connectors, e.g. ``["google_drive"]`` or
+                ``["notion"]``. Lowercase connector names only, never a display name like
+                ``"Google Drive"``. Omit it to search everything the user connected, which
+                is almost always what you want.
+            limit: How many documents to return, 1-50 (default 10). Several passages of one
+                document collapse into a single result, so this counts documents.
+
+        Returns:
+            JSON string: ``{"output": {"results": [{"document_id", "title", "passage",
+            "source", "source_url", "section"?}], "returned": N}}``, or ``{"error": ...}``
+            when the knowledge base could not be reached.
+        """
+        try:
+            citations = await self._knowledge.search(query, sources=sources, limit=limit)
+        except ValueError as error:
+            return self._fail(str(error), tool="search_knowledge_base")
+        except KnowledgeServiceError as error:
+            logger.warning("KnowledgeTools: search failed: %s", error)
+            return self._fail("the knowledge base could not be reached", tool="search_knowledge_base")
+
+        rows = [self._row(citation) for citation in citations]
+        await self._notify("knowledge_searched", {"query": query, "sources": sources or [], "results": len(rows)})
+        return self._ok({"results": rows, "returned": len(rows)}, tool="search_knowledge_base")

{digitalkin-1.0.5.dev6 → digitalkin-1.1.0.dev0}/src/digitalkin/grpc_servers/module_server.py

@@ -65,7 +65,7 @@ class ModuleServer(BaseServer):
         self._gateway_servicer: GatewayServicer | None = None
         self._gateway_redis_client: RedisClient | None = None
 
-        self._prepare_registry_config()
+        self._prepare_platform_configs()
 
     def _register_servicers(self) -> None:
         """Register module and gateway servicers.
@@ -207,14 +207,20 @@ class ModuleServer(BaseServer):
         await GrpcClientWrapper.close_all_cached_channels()
         Bulkhead.clear_all()
 
-    def _prepare_registry_config(self) -> None:
-        """Inject registry client config into module_class for spawned instances."""
+    def _prepare_platform_configs(self) -> None:
+        """Inject the Service Provider client config into module_class for spawned instances.
+
+        Covers the services a module never configures itself because they are platform
+        machinery served by that same provider: the registry, and the knowledge base the
+        customer connected. The server's address wins, as it did for the registry alone.
+        """
         if not self.client_config:
             return
 
         if "services_config_params" not in self.module_class.__dict__:
             self.module_class.services_config_params = dict(self.module_class.services_config_params)
-        self.module_class.services_config_params["registry"] = {"client_config": self.client_config}
+        for service in ("registry", "knowledge"):
+            self.module_class.services_config_params[service] = {"client_config": self.client_config}
 
     async def _init_and_register(self) -> None:
         """Initialize registry client, health-check, and register.

{digitalkin-1.0.5.dev6 → digitalkin-1.1.0.dev0}/src/digitalkin/models/module/module_context.py

@@ -20,6 +20,7 @@ from digitalkin.services.communication.exceptions import ToolCallError
 from digitalkin.services.cost.cost_strategy import CostStrategy
 from digitalkin.services.filesystem.filesystem_strategy import FilesystemStrategy
 from digitalkin.services.identity.identity_strategy import IdentityStrategy
+from digitalkin.services.knowledge.knowledge_strategy import KnowledgeStrategy
 from digitalkin.services.registry.exceptions import RegistryModuleNotFoundError
 from digitalkin.services.registry.registry_strategy import RegistryStrategy
 from digitalkin.services.secret.secret_strategy import SecretStrategy
@@ -104,6 +105,7 @@ class ModuleContext:
     cost: CostStrategy
     filesystem: FilesystemStrategy
     identity: IdentityStrategy
+    knowledge: KnowledgeStrategy
     registry: RegistryStrategy
     secret: SecretStrategy
     setup: SetupStrategy | None
@@ -127,6 +129,7 @@ class ModuleContext:
         cost: CostStrategy,
         filesystem: FilesystemStrategy,
         identity: IdentityStrategy,
+        knowledge: KnowledgeStrategy,
         registry: RegistryStrategy,
         secret: SecretStrategy,
         storage: StorageStrategy,
@@ -149,6 +152,7 @@ class ModuleContext:
             cost: CostStrategy.
             filesystem: FilesystemStrategy.
             identity: IdentityStrategy.
+            knowledge: KnowledgeStrategy.
             registry: RegistryStrategy.
             secret: SecretStrategy.
             storage: StorageStrategy.
@@ -169,6 +173,7 @@ class ModuleContext:
         self.cost = cost
         self.filesystem = filesystem
         self.identity = identity
+        self.knowledge = knowledge
         self.registry = registry
         self.secret = secret
         self.setup = setup
@@ -574,6 +579,7 @@ class ModuleContext:
             ("cost", self.cost),
             ("storage", self.storage),
             ("registry", self.registry),
+            ("knowledge", self.knowledge),
             ("filesystem", self.filesystem),
             ("user_profile", self.user_profile),
             ("secret", self.secret),

{digitalkin-1.0.5.dev6 → digitalkin-1.1.0.dev0}/src/digitalkin/models/services/__init__.py

@@ -1,14 +1,17 @@
 """This module contains the models for the services."""
 
 from digitalkin.models.services.filesystem import FileMetadata, FileType, FileUploadMetadata
+from digitalkin.models.services.knowledge import Citation, Modality
 from digitalkin.models.services.storage import BaseMessage, BaseRole, ChatHistory, Role
 
 __all__ = [
     "BaseMessage",
     "BaseRole",
     "ChatHistory",
+    "Citation",
     "FileMetadata",
     "FileType",
     "FileUploadMetadata",
+    "Modality",
     "Role",
 ]

digitalkin-1.1.0.dev0/src/digitalkin/models/services/knowledge.py

@@ -0,0 +1,61 @@
+"""Knowledge-service data models.
+
+The knowledge service searches the enterprise knowledge base a user has connected
+(Google Drive, Notion, ...) through the Context Platform. It answers with citations:
+one per document, carrying the passage that matched and the URL to the original.
+"""
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class Modality(str, Enum):
+    """What kind of content a citation's passage is.
+
+    Member names mirror the proto ``Modality`` enum, whose values are bare since
+    protocol 1.2.0 (``TEXT``, ``IMAGE``, ...) except ``MODALITY_UNSPECIFIED``: they are
+    looked up by name from the wire value, so they must match.
+    """
+
+    UNSPECIFIED = "unspecified"
+    TEXT = "text"
+    IMAGE = "image"
+    PAGE = "page"
+    SLIDE = "slide"
+    TABLE = "table"
+    AUDIO = "audio"
+    VIDEO = "video"
+
+
+class Citation(BaseModel):
+    """One document the search matched, with the passage that matched it.
+
+    A document contributes a single citation however many of its passages matched,
+    which is why ``limit`` counts documents and not passages.
+    """
+
+    document_id: str = ""
+    title: str = ""
+    snippet: str = ""
+    score: float = 0.0
+    """Fused rank, NOT a similarity: comparable only against the other citations of the
+    same answer, and never to be shown as a confidence."""
+    source: str = ""
+    """The connector the document came from, e.g. ``google_drive`` or ``notion``."""
+    source_url: str = ""
+    modality: Modality = Modality.UNSPECIFIED
+    locator: dict[str, Any] = Field(default_factory=dict)
+    """Where the passage sits in the document: ``index``, ``start``, ``end``, ``heading_path``."""
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @property
+    def heading_path(self) -> list[str]:
+        """The document headings leading to the passage, outermost first.
+
+        Returns:
+            The heading path, or an empty list when the locator carries none.
+        """
+        path = self.locator.get("heading_path")
+        return [str(item) for item in path] if isinstance(path, list) else []

digitalkin-1.1.0.dev0/src/digitalkin/models/settings/knowledge.py

@@ -0,0 +1,35 @@
+"""Knowledge-scope runtime settings."""
+
+from functools import lru_cache
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class KnowledgeSettings(BaseSettings):
+    """Knowledge client runtime configuration."""
+
+    model_config = SettingsConfigDict(env_prefix="DIGITALKIN_KNOWLEDGE_", case_sensitive=False)
+
+    search_timeout_s: float = Field(
+        default=10.0,
+        gt=0,
+        description="Per-call deadline for a knowledge search (shorter than the global gRPC default).",
+    )
+    default_limit: int = Field(
+        default=10,
+        ge=1,
+        description="Documents returned when a caller asks for no particular number.",
+    )
+
+
+@lru_cache(maxsize=1)
+def get_knowledge_settings() -> KnowledgeSettings:
+    """Process-wide ``KnowledgeSettings`` singleton.
+
+    Tests must call ``get_knowledge_settings.cache_clear()`` after mutating env.
+
+    Returns:
+        The shared ``KnowledgeSettings`` instance.
+    """
+    return KnowledgeSettings()

{digitalkin-1.0.5.dev6 → digitalkin-1.1.0.dev0}/src/digitalkin/modules/triggers/healthcheck_services_trigger.py

@@ -44,6 +44,7 @@ class HealthcheckServicesTrigger(TriggerHandler, BaseMixin):
             "cost": context.cost,
             "filesystem": context.filesystem,
             "registry": context.registry,
+            "knowledge": context.knowledge,
             "user_profile": context.user_profile,
         }
         services_status: list[ServiceHealthStatus] = []

digitalkin-1.1.0.dev0/src/digitalkin/services/knowledge/__init__.py

@@ -0,0 +1,16 @@
+"""This module is responsible for handling the knowledge service."""
+
+from digitalkin.models.services.knowledge import Citation, Modality
+from digitalkin.services.knowledge.default_knowledge import DefaultKnowledge
+from digitalkin.services.knowledge.exceptions import KnowledgeServiceError
+from digitalkin.services.knowledge.grpc_knowledge import GrpcKnowledge
+from digitalkin.services.knowledge.knowledge_strategy import KnowledgeStrategy
+
+__all__ = [
+    "Citation",
+    "DefaultKnowledge",
+    "GrpcKnowledge",
+    "KnowledgeServiceError",
+    "KnowledgeStrategy",
+    "Modality",
+]

digitalkin-1.1.0.dev0/src/digitalkin/services/knowledge/default_knowledge.py

@@ -0,0 +1,88 @@
+"""Default knowledge implementation."""
+
+import re
+from typing import Any
+
+from digitalkin.models.services.knowledge import Citation
+from digitalkin.services.knowledge.knowledge_strategy import KnowledgeStrategy
+
+_WORDS = re.compile(r"\w+", re.UNICODE)
+
+
+class DefaultKnowledge(KnowledgeStrategy):
+    """Local knowledge strategy backed by an in-memory corpus.
+
+    Keeps ``mode=LOCAL`` usable without the Context Platform: a sandbox or a test seeds
+    documents through the strategy config and gets deterministic answers offline::
+
+        services_config_params = {
+            "knowledge": {
+                "config": {
+                    "documents": [
+                        {
+                            "document_id": "doc_1",
+                            "title": "Pricing",
+                            "snippet": "Apollo moved to per-seat.",
+                            "source": "google_drive",
+                            "source_url": "https://...",
+                        },
+                    ]
+                }
+            }
+        }
+
+    Matching is word overlap over title and snippet — enough to exercise a caller, never
+    a substitute for the real hybrid search.
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        """Initialize with the corpus declared in the strategy config."""
+        super().__init__(*args, **kwargs)
+        documents = (self.config or {}).get("documents") or []
+        self._documents: list[Citation] = [
+            document if isinstance(document, Citation) else Citation.model_validate(document) for document in documents
+        ]
+
+    @staticmethod
+    def _overlap(query: str, document: Citation) -> float:
+        """Score a document by how much of the query its text carries.
+
+        Args:
+            query: The search query.
+            document: The candidate document.
+
+        Returns:
+            The share of distinct query words found, between 0 and 1.
+        """
+        wanted = {word.casefold() for word in _WORDS.findall(query)}
+        if not wanted:
+            return 0.0
+        haystack = {word.casefold() for word in _WORDS.findall(f"{document.title} {document.snippet}")}
+        return len(wanted & haystack) / len(wanted)
+
+    async def search(
+        self,
+        query: str,
+        sources: list[str] | None = None,
+        limit: int | None = None,
+    ) -> list[Citation]:
+        """Search the in-memory corpus.
+
+        Args:
+            query: What to look for.
+            sources: Restrict to these connectors; ``None`` searches the whole corpus.
+            limit: Maximum number of documents to return.
+
+        Returns:
+            The matching documents, best first.
+        """
+        text, wanted_sources, bounded = self.normalize(query, sources, limit)
+        scored = [
+            (score, document)
+            for document in self._documents
+            if (not wanted_sources or document.source in wanted_sources)
+            and (score := self._overlap(text, document)) > 0
+        ]
+        # Title breaks ties, so a corpus always answers in the same order.
+        scored.sort(key=lambda pair: (-pair[0], pair[1].title))
+        return [document.model_copy(update={"score": score}) for score, document in scored[:bounded]]

digitalkin-1.1.0.dev0/src/digitalkin/services/knowledge/exceptions.py

@@ -0,0 +1,5 @@
+"""Knowledge-specific exceptions."""
+
+
+class KnowledgeServiceError(Exception):
+    """Raised when a knowledge search could not be answered."""

digitalkin-1.1.0.dev0/src/digitalkin/services/knowledge/grpc_knowledge.py

@@ -0,0 +1,145 @@
+"""gRPC knowledge client implementation.
+
+Searches the enterprise knowledge base through the Service Provider's ContextService,
+which relays to the Context Platform.
+
+``SearchDocumentsRequest`` carries no identity: *who* is searching travels as the ambient
+``x-mission-id`` metadata every outbound call already gets
+(:class:`~digitalkin.grpc_servers.interceptors.request_ids.RequestIdClientInterceptor`),
+and the Service Provider resolves it into the user and organization the search runs for.
+A module therefore cannot widen its own scope, and cannot forget to narrow it.
+"""
+
+from typing import Any
+
+import grpc
+from agentic_mesh_protocol.context.v1 import (
+    context_dto_pb2,
+    context_enums_pb2,
+    context_messages_pb2,
+    context_service_pb2_grpc,
+)
+from google.protobuf import json_format
+from grpc_health.v1 import health_pb2, health_pb2_grpc
+
+from digitalkin.grpc_servers.exceptions import PermissionDeniedError, ServerError
+from digitalkin.grpc_servers.utils.grpc_client_wrapper import GrpcClientWrapper
+from digitalkin.grpc_servers.utils.grpc_error_handler import GrpcErrorHandlerMixin
+from digitalkin.logger import logger
+from digitalkin.models.grpc_servers.models import ClientConfig
+from digitalkin.models.services.knowledge import Citation, Modality
+from digitalkin.models.settings.knowledge import get_knowledge_settings
+from digitalkin.services.knowledge.exceptions import KnowledgeServiceError
+from digitalkin.services.knowledge.knowledge_strategy import KnowledgeStrategy
+
+
+class GrpcKnowledge(KnowledgeStrategy, GrpcClientWrapper, GrpcErrorHandlerMixin):
+    """gRPC-based knowledge client talking to the Service Provider's ContextService."""
+
+    service_name: str = "ContextService"
+
+    def __init__(
+        self,
+        mission_id: str,
+        setup_id: str,
+        setup_version_id: str,
+        client_config: ClientConfig,
+        config: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize the gRPC knowledge client."""
+        KnowledgeStrategy.__init__(self, mission_id, setup_id, setup_version_id, config)
+        self.service_name = "ContextService"
+        self._init_channel(client_config)
+        self.stub = self._get_or_create_stub(context_service_pb2_grpc.ContextServiceStub)
+        logger.debug("Channel client 'Knowledge' initialized successfully")
+
+    async def close(self) -> None:
+        """Release this instance's pooled gRPC channel ref."""
+        await self.close_channel()
+
+    async def wait_for_ready(self, timeout: float = 1.0) -> bool:
+        """Probe the backend via the standard gRPC Health Check service.
+
+        Args:
+            timeout: Max seconds for the round-trip.
+
+        Returns:
+            True if the server responded SERVING, False otherwise.
+        """
+        health_stub = health_pb2_grpc.HealthStub(self._channel)
+        try:
+            response = await health_stub.Check(  # type: ignore[attr-defined]  # grpc_health generated stub lacks typed Check
+                health_pb2.HealthCheckRequest(service=""),
+                timeout=timeout,
+            )
+        except grpc.aio.AioRpcError:
+            return False
+        return response.status == health_pb2.HealthCheckResponse.SERVING
+
+    @staticmethod
+    def _proto_to_citation(citation: context_messages_pb2.Citation) -> Citation:
+        """Convert a proto ``Citation`` to the SDK model.
+
+        Args:
+            citation: Proto Citation message.
+
+        Returns:
+            Citation with mapped fields.
+        """
+        # Only ``MODALITY_UNSPECIFIED`` still carries the prefix; the rest are bare since protocol 1.2.0.
+        modality_name = context_enums_pb2.Modality.Name(citation.modality).removeprefix("MODALITY_")
+        return Citation(
+            document_id=citation.document_id,
+            title=citation.title,
+            snippet=citation.snippet,
+            score=citation.score,
+            source=citation.source,
+            source_url=citation.source_url,
+            modality=Modality[modality_name],
+            locator=json_format.MessageToDict(citation.locator),
+            metadata=json_format.MessageToDict(citation.metadata),
+        )
+
+    async def search(
+        self,
+        query: str,
+        sources: list[str] | None = None,
+        limit: int | None = None,
+    ) -> list[Citation]:
+        """Search the knowledge base the current user may read.
+
+        Args:
+            query: What to look for, in natural language.
+            sources: Restrict the search to these connectors; ``None`` searches every source.
+            limit: Maximum number of documents to return; ``None`` uses the configured default.
+
+        Returns:
+            One citation per matching document, best first.
+
+        Raises:
+            ValueError: If the query holds nothing to search for, or a source is not a
+                connector name.
+            PermissionDeniedError: If the caller is not permitted.
+            KnowledgeServiceError: If the gRPC call fails.
+        """
+        # Normalized before the error-handler scope: an empty query and an unusable source name
+        # are permanent conditions, and must reach the caller as a ValueError rather than be
+        # wrapped as a retryable service error.
+        text, wanted_sources, bounded = self.normalize(query, sources, limit)
+
+        async with self.handle_grpc_errors("SearchDocuments", KnowledgeServiceError):
+            try:
+                response = await self.exec_grpc_query(
+                    "SearchDocuments",
+                    context_dto_pb2.SearchDocumentsRequest(query=text, sources=wanted_sources, limit=bounded),
+                    timeout=get_knowledge_settings().search_timeout_s,
+                )
+            except PermissionDeniedError:
+                raise
+            except ServerError as e:
+                msg = f"Failed to search the knowledge base: {e}"
+                logger.error(msg)
+                raise KnowledgeServiceError(msg) from e
+
+            logger.debug("Knowledge search returned %d document(s)", len(response.results))
+            return [self._proto_to_citation(citation) for citation in response.results]