Signed-off-by: Árpád Csepi <csepi.arpad@outlook.com>

feat: upgrade to dir v1.5.0 and implement grpc services

Signed-off-by: Árpád Csepi <csepi.arpad@outlook.com>

Author: arpad-csepi

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -30,6 +30,7 @@ body:
         If applicable, provide the version number or release tag where this
         issue was encountered
       options:
+        - v1.5.0
         - v1.4.0
         - v1.3.0
         - v1.2.1

CHANGELOG.md

@@ -3,6 +3,19 @@
 [agntcy/dir]: https://github.com/agntcy/dir
 [agntcy/dir-sdk-python]: https://github.com/agntcy/dir-sdk-python
 
+## 1.5.0 (2026-06-18)
+
+### Added
+
+- `AIFinderService` client methods: `list_agents`, `get_agent`, `export_agent`, and `get_well_known_catalog`.
+- `catalog_v1` model re-exports for AI Catalog protobuf types.
+- Integration tests for AI Finder against catalog-projectable OASF records.
+
+### Changed
+
+- Updated buf-generated SDK dependencies to track [agntcy/dir][agntcy/dir] `v1.5.0`.
+- Bumped the directory chart and `dirctl` image used in CI to `v1.5.0`.
+
 ## 1.4.0 (2026-06-12)
 
 ### Added

RELEASE.md

@@ -12,8 +12,8 @@ Create a branch for the new release:
    - `examples/pyproject.toml`
    - `.github/ISSUE_TEMPLATE/bug_report.yml`
 2. Update the dependencies if necessary:
-   - [agntcy-dir-grpc-python](https://buf.build/agntcy/dir/sdks/v1.4.0%3Agrpc/python) (Buf SDK)
-   - [agntcy-dir-protocolbuffers-python](https://buf.build/agntcy/dir/sdks/v1.4.0%3Aprotocolbuffers/python) (Buf SDK)
+   - [agntcy-dir-grpc-python](https://buf.build/agntcy/dir/sdks/v1.5.0%3Agrpc/python) (Buf SDK)
+   - [agntcy-dir-protocolbuffers-python](https://buf.build/agntcy/dir/sdks/v1.5.0%3Aprotocolbuffers/python) (Buf SDK)
    - `.github/workflows/ci.yaml` (dir & dir-ctl version)
 3. Add an entry to `CHANGELOG.md`
 
@@ -30,6 +30,6 @@ To trigger the release workflow, create and push the release tag
 for the last commit:
 
 ```sh
-git tag -a v1.4.0
-git push origin v1.4.0
+git tag -a v1.5.0
+git push origin v1.5.0
 ```

Taskfile.yml

@@ -4,8 +4,8 @@
 version: "3"
 
 vars:
-  DIR_CHART_VERSION: '{{ .DIR_CHART_VERSION | default "v1.4.0" }}'
-  DIRCTL_IMAGE_TAG: '{{ .DIRCTL_IMAGE_TAG | default "v1.4.0" }}'
+  DIR_CHART_VERSION: '{{ .DIR_CHART_VERSION | default "v1.5.0" }}'
+  DIRCTL_IMAGE_TAG: '{{ .DIRCTL_IMAGE_TAG | default "v1.5.0" }}'
 
   # renovate: datasource=github-releases depName=renovatebot/renovate versioning=semver
   RENOVATE_VERSION: "43.209.4"

dir-sdk-python/agntcy/dir_sdk/client/client.py

@@ -18,6 +18,7 @@
 from agntcy.dir_sdk.client.auth.session import OAuthSessionManager
 from agntcy.dir_sdk.client.auth.token_cache import CachedToken, TokenCache
 from agntcy.dir_sdk.client.config import Config
+from agntcy.dir_sdk.client.services.ai_finder import AIFinderService
 from agntcy.dir_sdk.client.services.events import EventService
 from agntcy.dir_sdk.client.services.naming import NamingService
 from agntcy.dir_sdk.client.services.publication import PublicationService
@@ -32,6 +33,7 @@
     JWTAuthInterceptor,
 )
 from agntcy.dir_sdk.models import (
+    catalog_v1,
     core_v1,
     events_v1,
     naming_v1,
@@ -40,6 +42,7 @@
     sign_v1,
     store_v1,
 )
+from google.api.httpbody_pb2 import HttpBody
 
 logger = logging.getLogger("client")
 
@@ -76,6 +79,7 @@ def __init__(self, config: Config | None = None) -> None:
         self.sync_client = store_v1.SyncServiceStub(channel)
         self.event_client = events_v1.EventServiceStub(channel)
         self.naming_client = naming_v1.NamingServiceStub(channel)
+        self.ai_finder_client = catalog_v1.AIFinderServiceStub(channel)
 
         # Service-layer adapters grouped by technical area.
         self.store_service = StoreService(self.store_client, logger)
@@ -86,6 +90,7 @@ def __init__(self, config: Config | None = None) -> None:
         self.sync_service = SyncService(self.sync_client, logger)
         self.event_service = EventService(self.event_client, logger)
         self.naming_service = NamingService(self.naming_client, logger)
+        self.ai_finder_service = AIFinderService(self.ai_finder_client, logger)
 
     def has_cached_oauth_token(self) -> bool:
         return self.oauth_session.has_access_token()
@@ -278,5 +283,33 @@ def verify(
     ) -> sign_v1.VerifyResponse:
         return self.sign_service.verify(req, metadata=metadata)
 
+    def list_agents(
+        self,
+        req: catalog_v1.ListAgentsRequest,
+        metadata: Sequence[tuple[str, str]] | None = None,
+    ) -> catalog_v1.ListAgentsResponse:
+        return self.ai_finder_service.list_agents(req, metadata=metadata)
+
+    def get_agent(
+        self,
+        req: catalog_v1.GetAgentRequest,
+        metadata: Sequence[tuple[str, str]] | None = None,
+    ) -> catalog_v1.GetAgentResponse:
+        return self.ai_finder_service.get_agent(req, metadata=metadata)
+
+    def export_agent(
+        self,
+        req: catalog_v1.ExportAgentRequest,
+        metadata: Sequence[tuple[str, str]] | None = None,
+    ) -> HttpBody:
+        return self.ai_finder_service.export_agent(req, metadata=metadata)
+
+    def get_well_known_catalog(
+        self,
+        req: catalog_v1.GetWellKnownCatalogRequest,
+        metadata: Sequence[tuple[str, str]] | None = None,
+    ) -> catalog_v1.GetWellKnownCatalogResponse:
+        return self.ai_finder_service.get_well_known_catalog(req, metadata=metadata)
+
     def sign(self, req: sign_v1.SignRequest) -> None:
         self.sign_service.sign(req)

dir-sdk-python/agntcy/dir_sdk/client/services/__init__.py

@@ -3,6 +3,7 @@
 
 """Service-layer wrappers around generated gRPC stubs."""
 
+from agntcy.dir_sdk.client.services.ai_finder import AIFinderService
 from agntcy.dir_sdk.client.services.events import EventService
 from agntcy.dir_sdk.client.services.naming import NamingService
 from agntcy.dir_sdk.client.services.publication import PublicationService
@@ -13,6 +14,7 @@
 from agntcy.dir_sdk.client.services.sync import SyncService
 
 __all__ = [
+    "AIFinderService",
     "EventService",
     "NamingService",
     "PublicationService",

dir-sdk-python/agntcy/dir_sdk/client/services/ai_finder.py

@@ -0,0 +1,67 @@
+# Copyright AGNTCY Contributors (https://github.com/agntcy)
+# SPDX-License-Identifier: Apache-2.0
+
+"""AI Finder service wrappers."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Sequence
+
+from agntcy.dir_sdk.client.services.base import RpcServiceBase
+from agntcy.dir_sdk.models import catalog_v1
+from google.api.httpbody_pb2 import HttpBody
+
+
+class AIFinderService(RpcServiceBase):
+    def __init__(
+        self,
+        ai_finder_client: catalog_v1.AIFinderServiceStub,
+        logger: logging.Logger,
+    ) -> None:
+        super().__init__(logger)
+        self._ai_finder_client = ai_finder_client
+
+    def list_agents(
+        self,
+        req: catalog_v1.ListAgentsRequest,
+        metadata: Sequence[tuple[str, str]] | None = None,
+    ) -> catalog_v1.ListAgentsResponse:
+        return self._invoke(
+            "list_agents",
+            "Failed to list agents",
+            lambda: self._ai_finder_client.ListAgents(req, metadata=metadata),
+        )
+
+    def get_agent(
+        self,
+        req: catalog_v1.GetAgentRequest,
+        metadata: Sequence[tuple[str, str]] | None = None,
+    ) -> catalog_v1.GetAgentResponse:
+        return self._invoke(
+            "get_agent",
+            "Failed to get agent",
+            lambda: self._ai_finder_client.GetAgent(req, metadata=metadata),
+        )
+
+    def export_agent(
+        self,
+        req: catalog_v1.ExportAgentRequest,
+        metadata: Sequence[tuple[str, str]] | None = None,
+    ) -> HttpBody:
+        return self._invoke(
+            "export_agent",
+            "Failed to export agent",
+            lambda: self._ai_finder_client.ExportAgent(req, metadata=metadata),
+        )
+
+    def get_well_known_catalog(
+        self,
+        req: catalog_v1.GetWellKnownCatalogRequest,
+        metadata: Sequence[tuple[str, str]] | None = None,
+    ) -> catalog_v1.GetWellKnownCatalogResponse:
+        return self._invoke(
+            "get_well_known_catalog",
+            "Failed to get well-known catalog",
+            lambda: self._ai_finder_client.GetWellKnownCatalog(req, metadata=metadata),
+        )

dir-sdk-python/agntcy/dir_sdk/models/__init__.py

@@ -4,6 +4,7 @@
 # Export all protobuf packages for easier module imports.
 # The actual subpackages in agntcy_dir.models expose gRPC stubs.
 
+from . import catalog_v1 as catalog_v1
 from . import core_v1 as core_v1
 from . import events_v1 as events_v1
 from . import naming_v1 as naming_v1

dir-sdk-python/agntcy/dir_sdk/models/catalog_v1.py

@@ -0,0 +1,7 @@
+# Copyright AGNTCY Contributors (https://github.com/agntcy)
+# SPDX-License-Identifier: Apache-2.0
+
+from agntcy.dir.catalog.v1.ai_finder_service_pb2 import *
+from agntcy.dir.catalog.v1.ai_finder_service_pb2_grpc import *
+from agntcy.dir.catalog.v1.models_pb2 import *
+from agntcy.dir.catalog.v1.models_pb2_grpc import *

dir-sdk-python/agntcy/dir_sdk/tests/test_client.py

@@ -1,5 +1,6 @@
 # Copyright AGNTCY Contributors (https://github.com/agntcy)
 # SPDX-License-Identifier: Apache-2.0
+import json
 import os
 import pathlib
 import subprocess
@@ -11,6 +12,7 @@
 import grpc
 from agntcy.dir_sdk.client import Client
 from agntcy.dir_sdk.models import (
+    catalog_v1,
     core_v1,
     events_v1,
     routing_v1,
@@ -623,6 +625,65 @@ def test_get_verification_info(self) -> None:
             or verify_response.error_message == ""
         )
 
+    def test_list_agents(self) -> None:
+        cid = self._push_catalog_fixture()
+        self._wait_for_catalog_entry(cid)
+
+        response = self.client.list_agents(catalog_v1.ListAgentsRequest())
+
+        assert isinstance(response, catalog_v1.ListAgentsResponse)
+        assert any(entry.identifier.find(cid) != -1 for entry in response.results)
+        assert any(
+            entry.display_name == "burger_seller_agent" for entry in response.results
+        )
+
+    def test_get_agent(self) -> None:
+        cid = self._push_catalog_fixture()
+        self._wait_for_catalog_entry(cid)
+
+        response = self.client.get_agent(catalog_v1.GetAgentRequest(cid=cid))
+
+        assert isinstance(response, catalog_v1.GetAgentResponse)
+        assert response.entry.identifier.find(cid) != -1
+
+    def test_get_well_known_catalog(self) -> None:
+        self._push_catalog_fixture()
+
+        response = self.client.get_well_known_catalog(
+            catalog_v1.GetWellKnownCatalogRequest()
+        )
+
+        assert isinstance(response, catalog_v1.GetWellKnownCatalogResponse)
+        assert response.catalog.spec_version
+        assert response.catalog.host.display_name
+
+    def test_export_agent(self) -> None:
+        cid = self._push_catalog_fixture()
+        self._wait_for_catalog_entry(cid)
+
+        response = self.client.export_agent(
+            catalog_v1.ExportAgentRequest(cid=cid, format="oasf")
+        )
+
+        assert response.data
+
+    def _push_catalog_fixture(self) -> str:
+        fixture_path = pathlib.Path(__file__).parent / "testdata" / "record_100.json"
+        with fixture_path.open(encoding="utf-8") as fixture_file:
+            record_data = json.load(fixture_file)
+        record_refs = self.client.push([core_v1.Record(data=record_data)])
+        return record_refs[0].cid
+
+    def _wait_for_catalog_entry(self, cid: str, timeout_sec: float = 30.0) -> None:
+        deadline = time.time() + timeout_sec
+        while time.time() < deadline:
+            response = self.client.list_agents(catalog_v1.ListAgentsRequest())
+            if any(entry.identifier.find(cid) != -1 for entry in response.results):
+                return
+            time.sleep(1)
+        msg = f"catalog entry for {cid} not found within {timeout_sec}s"
+        raise AssertionError(msg)
+
     def gen_records(self, count: int, test_function_name: str) -> list[core_v1.Record]:
         """
         Generate test records with unique names.