digitalkin 1.0.4.dev7__tar.gz → 1.0.5.dev0__tar.gz

{digitalkin-1.0.4.dev7 → digitalkin-1.0.5.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: digitalkin
-Version: 1.0.4.dev7
+Version: 1.0.5.dev0
 Summary: SDK to build kin used in DigitalKin
 Author-email: "DigitalKin.ai" <contact@digitalkin.ai>
 License: Attribution-NonCommercial-ShareAlike 4.0 International
@@ -453,7 +453,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: ag-ui-protocol==0.1.21.dev1787220377
-Requires-Dist: agentic-mesh-protocol==1.0.2
+Requires-Dist: agentic-mesh-protocol==1.0.3.dev0
 Requires-Dist: agno<3,>=2.8.0
 Requires-Dist: anyio>=4.13.0
 Requires-Dist: grpcio-health-checking==1.82.1

{digitalkin-1.0.4.dev7 → digitalkin-1.0.5.dev0}/examples/redis_demo/client.py

@@ -2,11 +2,10 @@
 """Demo client for the Gateway gRPC service with per-endpoint testing.
 
 Subcommands:
-    full      Full pipeline: StartStream → ConsumeStream → SendSignal
+    full      Full pipeline: StartStream → Stream → SendSignal
     start     StartStream only (unary)
-    consume   ConsumeStream on existing task (requires --task-id)
-    produce   StartStream + ProduceStream (act as Module A)
-    signal    SendSignal on existing task (requires --task-id)
+    consume   Stream on existing task (requires --task-id)
+    signal    SendSignal(cancel) on existing task (requires --task-id)
     inspect   Dump Redis keys for a task (no gRPC)
 
 Usage:
@@ -14,8 +13,7 @@ Usage:
     python client.py full --prompt "Test" --setup '{"uppercase": true, "repeat": 5}'
     python client.py start --prompt "Hello"
     python client.py consume --task-id <uuid>
-    python client.py produce --task-id <uuid> --chunks 3
-    python client.py signal --task-id <uuid> --action cancel
+    python client.py signal --task-id <uuid>
     python client.py inspect --task-id <uuid>
 """
 
@@ -34,7 +32,7 @@ import grpc
 import redis.asyncio as aioredis
 from google.protobuf import json_format, struct_pb2
 
-from agentic_mesh_protocol.gateway.v1 import gateway_pb2, gateway_service_pb2_grpc
+from agentic_mesh_protocol.gateway.v1 import gateway_dto_pb2, gateway_messages_pb2, gateway_service_pb2_grpc
 
 # ── ANSI colors ─────────────────────────────────────────────────────
 
@@ -291,29 +289,18 @@ def _print_diff_report(tracker: RedisTracker, task_id: str) -> None:
 async def cmd_start(
     stub: gateway_service_pb2_grpc.GatewayServiceStub,
     task_id: str,
-    prompt: str,
-    setup: dict[str, Any] | None,
 ) -> bool:
     """StartStream — create a task session.
 
     Returns:
         True if accepted.
     """
-    input_struct = struct_pb2.Struct()
-    payload: dict[str, Any] = {
-        "root": {"protocol": "message", "text": prompt},
-    }
-    if setup:
-        payload["setup"] = setup
-    input_struct.update(payload)
-
     t0 = time.monotonic()
     resp = await stub.StartStream(
-        gateway_pb2.StartStreamRequest(
+        gateway_dto_pb2.StartStreamRequest(
             task_id=task_id,
-            input=input_struct,
-            setup_id="demo-setup",
-            mission_id="demo-mission",
+            setup_id="setups:demo",
+            mission_id="missions:demo",
         ),
     )
     elapsed = (time.monotonic() - t0) * 1000
@@ -327,112 +314,58 @@ async def cmd_start(
 async def cmd_consume(
     stub: gateway_service_pb2_grpc.GatewayServiceStub,
     task_id: str,
+        prompt: str,
+        setup: dict[str, Any] | None,
     verbose: bool,
 ) -> list[dict[str, Any]]:
-    """ConsumeStream — read module output from Redis.
+    """Stream — send the query, then read module output until ``stream.end``.
 
     Returns:
         List of received items.
     """
     received: list[dict[str, Any]] = []
+    query: dict[str, Any] = {"root": {"protocol": "message", "text": prompt}}
+    if setup:
+        query["setup"] = setup
+    query_struct = struct_pb2.Struct()
+    query_struct.update(query)
 
     async def _requests() -> AsyncGenerator:
-        yield gateway_pb2.ConsumeStreamRequest(
-            init=gateway_pb2.ConsumeStreamInit(task_id=task_id, from_seq=0),
-        )
+        yield gateway_messages_pb2.StreamRequest(task_id=task_id, from_seq=0, data=query_struct)
 
     t0 = time.monotonic()
-    resp_stream = stub.ConsumeStream(_requests())
-    async for resp in resp_stream:
-        elapsed = (time.monotonic() - t0) * 1000
-        payload_type = resp.WhichOneof("payload")
-
-        if payload_type == "output":
-            data_dict = json_format.MessageToDict(resp.output.data)
-            text = data_dict.get("root", {}).get("text", data_dict.get("root", {}).get("protocol", ""))
-            received.append({"seq": resp.output.seq, "text": text})
-            print(f"  {GREEN}seq={resp.output.seq:>2}{RESET}  {text}")  # noqa: T201
-            if verbose:
-                print(f"         {DIM}{json.dumps(data_dict, ensure_ascii=False)}{RESET}")  # noqa: T201
-
-        elif payload_type == "status":
-            state_name = gateway_pb2.StreamState.Name(resp.status.state)
-            received.append({"status": state_name})
-            color = GREEN if "COMPLETED" in state_name else YELLOW
-            print(f"  {color}status: {state_name}{RESET}  ({elapsed:.1f}ms total)")  # noqa: T201
-            break
-
-        elif payload_type == "error":
-            received.append({"error": resp.error.message})
-            print(f"  {RED}error: code={resp.error.code} msg={resp.error.message}{RESET}")  # noqa: T201
+    async for resp in stub.Stream(_requests()):
+        root = json_format.MessageToDict(resp.data).get("root", {})
+        protocol = root.get("protocol", "")
+        if protocol == "stream.error":
+            received.append({"seq": resp.seq, "error": root.get("message", "")})
+            print(f"  {RED}error: code={root.get('code')} msg={root.get('message')}{RESET}")  # noqa: T201
+            continue
+        if protocol == "stream.end":
+            received.append({"seq": resp.seq, "status": "stream.end"})
+            print(f"  {GREEN}stream.end{RESET}  ({(time.monotonic() - t0) * 1000:.1f}ms total)")  # noqa: T201
             break
-
-        elif payload_type == "heartbeat":
-            if verbose:
-                print(f"  {DIM}heartbeat{RESET}")  # noqa: T201
+        text = root.get("text", protocol)
+        received.append({"seq": resp.seq, "text": text})
+        print(f"  {GREEN}seq={resp.seq:>2}{RESET}  {text}")  # noqa: T201
+        if verbose:
+            print(f"         {DIM}{json.dumps(root, ensure_ascii=False)}{RESET}")  # noqa: T201
 
     return received
 
 
-async def cmd_produce(
-    stub: gateway_service_pb2_grpc.GatewayServiceStub,
-    task_id: str,
-    prompt: str,
-    num_chunks: int,
-) -> int:
-    """ProduceStream — act as Module A, push output chunks.
-
-    Returns:
-        Number of server responses.
-    """
-    async def _requests() -> AsyncGenerator:
-        yield gateway_pb2.ProduceStreamRequest(
-            init=gateway_pb2.ProduceStreamInit(task_id=task_id),
-        )
-        for i in range(num_chunks):
-            data = struct_pb2.Struct()
-            data.update({
-                "root": {
-                    "protocol": "message",
-                    "text": f"[{i + 1}/{num_chunks}] {prompt}",
-                },
-            })
-            yield gateway_pb2.ProduceStreamRequest(
-                output=gateway_pb2.ProduceStreamOutput(task_id=task_id, data=data),
-            )
-            await asyncio.sleep(0.05)
-
-    t0 = time.monotonic()
-    resp_stream = stub.ProduceStream(_requests())
-    count = 0
-    async for resp in resp_stream:
-        count += 1
-        payload = resp.WhichOneof("payload")
-        print(f"  response #{count}: {payload}")  # noqa: T201
-
-    elapsed = (time.monotonic() - t0) * 1000
-    print(f"  {DIM}stream closed ({count} responses, {elapsed:.1f}ms){RESET}")  # noqa: T201
-    return count
-
-
 async def cmd_signal(
     stub: gateway_service_pb2_grpc.GatewayServiceStub,
     task_id: str,
-    action: str,
 ) -> bool:
-    """SendSignal — send a control signal.
+    """SendSignal — cancel a running task.
 
     Returns:
         True if accepted.
     """
-    action_enum = (
-        gateway_pb2.SIGNAL_ACTION_CANCEL if action == "cancel"
-        else gateway_pb2.SIGNAL_ACTION_PAUSE
-    )
-
     t0 = time.monotonic()
     resp = await stub.SendSignal(
-        gateway_pb2.ClientSignalRequest(task_id=task_id, action=action_enum),
+        gateway_dto_pb2.SendSignalRequest(cancel=gateway_messages_pb2.CancelSignal(task_id=task_id)),
     )
     elapsed = (time.monotonic() - t0) * 1000
 
@@ -447,7 +380,7 @@ async def cmd_signal(
 
 
 async def run_full(args: argparse.Namespace) -> None:
-    """Full pipeline: StartStream → ConsumeStream → SendSignal."""
+    """Full pipeline: StartStream → Stream → SendSignal."""
     task_id = args.task_id or str(uuid.uuid4())
     setup = json.loads(args.setup) if args.setup else None
     tracker = RedisTracker(args.redis) if args.verbose else None
@@ -467,7 +400,7 @@ async def run_full(args: argparse.Namespace) -> None:
 
             # 1. StartStream
             print(f"\n{BOLD}[1] StartStream{RESET}")  # noqa: T201
-            accepted = await cmd_start(stub, task_id, args.prompt, setup)
+            accepted = await cmd_start(stub, task_id)
             if not accepted:
                 print(f"  {RED}Server rejected the task — aborting.{RESET}")  # noqa: T201
                 return
@@ -476,18 +409,17 @@ async def run_full(args: argparse.Namespace) -> None:
                 await asyncio.sleep(0.1)
                 await tracker.snapshot("StartStream", task_id)
 
-            # 2. ConsumeStream — wait for module output
-            print(f"\n{BOLD}[2] ConsumeStream{RESET}")  # noqa: T201
-            await asyncio.sleep(0.2)  # let module start
-            received = await cmd_consume(stub, task_id, args.verbose)
+            # 2. Stream — send the query, read module output
+            print(f"\n{BOLD}[2] Stream{RESET}")  # noqa: T201
+            received = await cmd_consume(stub, task_id, args.prompt, setup, args.verbose)
 
             if tracker:
                 await asyncio.sleep(0.1)
-                await tracker.snapshot("ConsumeStream", task_id)
+                await tracker.snapshot("Stream", task_id)
 
             # 3. SendSignal
             print(f"\n{BOLD}[3] SendSignal (cancel){RESET}")  # noqa: T201
-            await cmd_signal(stub, task_id, "cancel")
+            await cmd_signal(stub, task_id)
 
             if tracker:
                 await asyncio.sleep(0.1)
@@ -513,61 +445,39 @@ async def run_full(args: argparse.Namespace) -> None:
 async def run_start(args: argparse.Namespace) -> None:
     """StartStream only."""
     task_id = args.task_id or str(uuid.uuid4())
-    setup = json.loads(args.setup) if args.setup else None
 
     print(f"\n{BOLD}[StartStream]{RESET}  gateway={args.gateway}  task_id={task_id}")  # noqa: T201
 
     async with grpc.aio.insecure_channel(args.gateway, options=GRPC_OPTIONS) as channel:
         stub = gateway_service_pb2_grpc.GatewayServiceStub(channel)
-        await cmd_start(stub, task_id, args.prompt, setup)
+        await cmd_start(stub, task_id)
 
 
 async def run_consume(args: argparse.Namespace) -> None:
-    """ConsumeStream on existing task."""
+    """Stream on existing task."""
     if not args.task_id:
         print(f"{RED}--task-id is required for consume{RESET}")  # noqa: T201
         sys.exit(1)
 
-    print(f"\n{BOLD}[ConsumeStream]{RESET}  gateway={args.gateway}  task_id={args.task_id}")  # noqa: T201
-
-    async with grpc.aio.insecure_channel(args.gateway, options=GRPC_OPTIONS) as channel:
-        stub = gateway_service_pb2_grpc.GatewayServiceStub(channel)
-        await cmd_consume(stub, args.task_id, args.verbose)
-
-
-async def run_produce(args: argparse.Namespace) -> None:
-    """StartStream + ProduceStream (act as Module A)."""
-    task_id = args.task_id or str(uuid.uuid4())
     setup = json.loads(args.setup) if args.setup else None
-
-    print(f"\n{BOLD}[Produce]{RESET}  gateway={args.gateway}  task_id={task_id}")  # noqa: T201
+    print(f"\n{BOLD}[Stream]{RESET}  gateway={args.gateway}  task_id={args.task_id}")  # noqa: T201
 
     async with grpc.aio.insecure_channel(args.gateway, options=GRPC_OPTIONS) as channel:
         stub = gateway_service_pb2_grpc.GatewayServiceStub(channel)
-
-        # StartStream first (registers the session)
-        print(f"\n  {BOLD}StartStream{RESET}")  # noqa: T201
-        accepted = await cmd_start(stub, task_id, args.prompt, setup)
-        if not accepted:
-            print(f"  {RED}Rejected{RESET}")  # noqa: T201
-            return
-
-        # ProduceStream (act as Module A)
-        print(f"\n  {BOLD}ProduceStream ({args.chunks} chunks){RESET}")  # noqa: T201
-        await cmd_produce(stub, task_id, args.prompt, args.chunks)
+        await cmd_consume(stub, args.task_id, args.prompt, setup, args.verbose)
 
 
 async def run_signal(args: argparse.Namespace) -> None:
-    """SendSignal on existing task."""
+    """SendSignal(cancel) on existing task."""
     if not args.task_id:
         print(f"{RED}--task-id is required for signal{RESET}")  # noqa: T201
         sys.exit(1)
 
-    print(f"\n{BOLD}[SendSignal]{RESET}  gateway={args.gateway}  task_id={args.task_id}  action={args.action}")  # noqa: T201
+    print(f"\n{BOLD}[SendSignal]{RESET}  gateway={args.gateway}  task_id={args.task_id}  signal=cancel")  # noqa: T201
 
     async with grpc.aio.insecure_channel(args.gateway, options=GRPC_OPTIONS) as channel:
         stub = gateway_service_pb2_grpc.GatewayServiceStub(channel)
-        await cmd_signal(stub, args.task_id, args.action)
+        await cmd_signal(stub, args.task_id)
 
 
 async def run_inspect(args: argparse.Namespace) -> None:
@@ -613,8 +523,7 @@ examples:
   %(prog)s full --prompt "Test" --setup '{"uppercase": true, "repeat": 5}'
   %(prog)s start --prompt "Hello"
   %(prog)s consume --task-id <uuid>
-  %(prog)s produce --chunks 5 --prompt "Manual"
-  %(prog)s signal --task-id <uuid> --action cancel
+  %(prog)s signal --task-id <uuid>
   %(prog)s inspect --task-id <uuid>
 """,
     )
@@ -631,21 +540,16 @@ examples:
     sub = p.add_subparsers(dest="command", help="Endpoint to test")
 
     # full (default)
-    sub.add_parser("full", help="Full pipeline: StartStream -> ConsumeStream -> SendSignal")
+    sub.add_parser("full", help="Full pipeline: StartStream -> Stream -> SendSignal")
 
     # start
     sub.add_parser("start", help="StartStream only (unary)")
 
     # consume
-    sub.add_parser("consume", help="ConsumeStream on existing task (requires --task-id)")
-
-    # produce
-    sp_produce = sub.add_parser("produce", help="StartStream + ProduceStream (act as Module A)")
-    sp_produce.add_argument("--chunks", type=int, default=3, help="Number of chunks to produce (default: 3)")
+    sub.add_parser("consume", help="Stream on existing task (requires --task-id)")
 
     # signal
-    sp_signal = sub.add_parser("signal", help="SendSignal on existing task (requires --task-id)")
-    sp_signal.add_argument("--action", choices=["cancel", "pause"], default="cancel", help="Signal action (default: cancel)")
+    sub.add_parser("signal", help="SendSignal(cancel) on existing task (requires --task-id)")
 
     # inspect
     sub.add_parser("inspect", help="Dump Redis keys for a task (no gRPC)")
@@ -662,17 +566,10 @@ async def main() -> None:
     if not args.command:
         args.command = "full"
 
-    # Set defaults for subcommand-specific args
-    if not hasattr(args, "chunks"):
-        args.chunks = 3
-    if not hasattr(args, "action"):
-        args.action = "cancel"
-
     handlers = {
         "full": run_full,
         "start": run_start,
         "consume": run_consume,
-        "produce": run_produce,
         "signal": run_signal,
         "inspect": run_inspect,
     }

{digitalkin-1.0.4.dev7 → digitalkin-1.0.5.dev0}/examples/services/filesystem_module.py

@@ -10,8 +10,7 @@ from pydantic import BaseModel, Field
 from digitalkin.logger import logger
 from digitalkin.models.module import ModuleStatus
 from digitalkin.modules.archetype_module import ArchetypeModule
-from digitalkin.models.services.filesystem import FileType
-from digitalkin.services.filesystem import FileFilter, UploadFileData
+from digitalkin.services.filesystem.filesystem_strategy import FileFilter, UploadFileData
 from digitalkin.services.services_config import ServicesConfig
 from digitalkin.services.services_models import ServicesMode
 
@@ -119,9 +118,9 @@ class ExampleModule(ArchetypeModule[ExampleInput, ExampleOutput, ExampleSetup, E
         file = UploadFileData(
             content=b"%s\n%s" % (processed_message.encode(), str(processed_number).encode()),
             name="example_output.txt",
-            type=FileType.DOCUMENT,
+            file_type="text/plain",
             content_type="text/plain",
-            metadata={"sdk_created": True},
+            metadata={"example_key": "example_value"},
             replace_if_exists=True,
         )
 
@@ -177,10 +176,10 @@ async def test_module() -> None:
     # Check the storage
     if module.status == ModuleStatus.STOPPED:
         files, _nb_results = await module.filesystem.get_files(
-            filters=FileFilter(names=["example_output.txt"]),
+            filters=FileFilter(name="example_output.txt", context="test-mission-123"),
         )
         for file in files:
-            await module.filesystem.update_file(file.id, type=FileType.OTHER)
+            await module.filesystem.update_file(file.id, file_type="updated")
             # module.filesystem.delete_files(filters=FileFilter(name="example_output.txt", context="test-mission-123"), permanent=True)
 
             logger.info("Retrieved file: %s with ID: %s", file.name, file.id)
@@ -189,7 +188,7 @@ async def test_module() -> None:
                 if file_record:
                     logger.info("File ID: %s", file_record.id)
                     logger.info("File name: %s", file_record.name)
-                    logger.info("File type: %s", file_record.type)
+                    logger.info("File type: %s", file_record.file_type)
                     logger.info("File status: %s", file_record.status)
                     logger.info("File content: %s", file_record.content.decode())
             except Exception:

{digitalkin-1.0.4.dev7 → digitalkin-1.0.5.dev0}/pyproject.toml

@@ -31,7 +31,7 @@
         # which is how a nested run's output is attributed to its author. Pinned exactly
         # because it is a dated prerelease; move to >=0.1.21 once that ships stable.
         "ag-ui-protocol==0.1.21.dev1787220377",
-        "agentic-mesh-protocol==1.0.2",
+        "agentic-mesh-protocol==1.0.3.dev0",
         "agno>=2.8.0,<3",
         "anyio>=4.13.0",
         "grpcio-health-checking==1.82.1",
@@ -41,7 +41,7 @@
         "pydantic>=2.12.4",
         "redis[hiredis]>=7.4.0,<9",
     ]
-    version = "1.0.4.dev7"
+version = "1.0.5.dev0"
 
     [project.optional-dependencies]
         agno = [ "agno>=2.6" ]
@@ -208,15 +208,15 @@
         ]
 
         ignore = [
-            "any-type",                       # Allow typing.Any — gRPC stubs, callbacks, and dynamic APIs require it
-            "missing-trailing-comma",         # Disable because of formatter incompatibility
-            "docstring-extraneous-exception", # Allow extraneous-exception in docstring
-            "unused-import",                  # Allow unused imports — used for availability checks
-            "invalid-function-name",          # Allow PascalCase methods — gRPC servicer convention
-            "import-outside-top-level",       # Allow lazy imports — needed to break circular dependencies
-            "bad-dunder-method-name",         # Allow __get_pydantic_core_schema__ — Pydantic dunder hook
-            "hardcoded-password-string",      # Hardcoded-password
-            "suspicious-pickle-import",       # Allow pickle import
+            "ANN401",  # Allow typing.Any — gRPC stubs, callbacks, and dynamic APIs require it
+            "COM812",  # Disable because of formatter incompatibility
+            "DOC502",  # Allow extraneous-exception in docstring
+            "F401",    # Allow unused imports — used for availability checks
+            "N802",    # Allow PascalCase methods — gRPC servicer convention
+            "PLC0415", # Allow lazy imports — needed to break circular dependencies
+            "PLW3201", # Allow __get_pydantic_core_schema__ — Pydantic dunder hook
+            "S105",    # Hardcoded-password
+            "S403",    # Allow pickle import
         ]
 
         fixable = [ "ALL" ]
@@ -226,40 +226,40 @@
 
         [tool.ruff.lint.per-file-ignores]
             "tests/**/*.py" = [
-                "missing-type-function-argument",
-                "missing-type-args",
-                "missing-type-kwargs",
-                "missing-return-type-undocumented-public-function",
-                "any-type",
-                "unused-function-argument",
-                "unused-method-argument",
-                "complex-structure",
-                "undocumented-public-module",
-                "undocumented-public-class",
-                "undocumented-public-method",
-                "undocumented-public-function",
-                "undocumented-public-init",
-                "undocumented-param",
-                "docstring-missing-returns",
-                "docstring-missing-exception",
-                "line-too-long",
-                "commented-out-code",
-                "boolean-type-hint-positional-argument",
-                "boolean-default-value-positional-argument",
-                "logging-f-string",
-                "invalid-function-name",
-                "try-except-in-loop",
-                "import-private-name",
-                "too-many-return-statements",
-                "too-many-branches",
-                "too-many-locals",
-                "too-many-statements",
-                "too-many-nested-blocks",
-                "magic-value-comparison",
-                "no-self-use",
-                "assert",
-                "private-member-access",
-                "raise-vanilla-class",
+                "ANN001",
+                "ANN002",
+                "ANN003",
+                "ANN201",
+                "ANN401",
+                "ARG001",
+                "ARG002",
+                "C901",
+                "D100",
+                "D101",
+                "D102",
+                "D103",
+                "D107",
+                "D417",
+                "DOC201",
+                "DOC501",
+                "E501",
+                "ERA001",
+                "FBT001",
+                "FBT002",
+                "G004",
+                "N802",
+                "PERF203",
+                "PLC2701",
+                "PLR0911",
+                "PLR0912",
+                "PLR0914",
+                "PLR0915",
+                "PLR1702",
+                "PLR2004",
+                "PLR6301",
+                "S101",
+                "SLF001",
+                "TRY002",
             ]
 
         [tool.ruff.lint.pylint]

{digitalkin-1.0.4.dev7 → digitalkin-1.0.5.dev0}/src/digitalkin/__version__.py

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

{digitalkin-1.0.4.dev7 → digitalkin-1.0.5.dev0}/src/digitalkin/community/agno/toolkits/registry/action.py

@@ -16,6 +16,7 @@ from pydantic import Field
 from digitalkin.community.agno.toolkits.registry.base import RegistryAction
 from digitalkin.logger import logger
 from digitalkin.models.services.registry import (
+    RegistryModuleType,
     RegistrySetupStatus,
     RegistrySortBy,
     RegistryVisibility,
@@ -36,7 +37,7 @@ class GetAction(RegistryAction):
         """Read the setup (always its current version), refusing a foreign object type.
 
         Returns:
-            The setup with its current version, status and visibility.
+            The setup with its current version, status and visibility, and a service's key map.
         """
         return await ctx.ensure_kind(self.setup_id)
 
@@ -55,7 +56,6 @@ class SearchAction(RegistryAction):
     this manager's own kind. Filters combine with AND; within one filter the values are OR'd.
     """
 
-    _DOC_PREVIEW_CHARS: ClassVar[int] = 300
     # The service ceiling itself (storage and registry both cap a page at 100), so the toolkit
     # no longer imposes a tighter one of its own.
     _MAX_RESULTS: ClassVar[int] = 100
@@ -125,14 +125,16 @@ class SearchAction(RegistryAction):
         # would both contradict ``total_returned`` and, at exactly ``cap`` rows, promise an empty
         # next page.
         truncated = len(usable) > cap
-        rows = [self._row(setup) for setup in usable[:cap]]
+        rows = [self._row(setup, ctx.module_type) for setup in usable[:cap]]
         return {"total_returned": len(rows), "truncated": truncated, "offset": self.offset, "setups": rows}
 
-    def _row(self, setup: SetupSummary) -> dict[str, Any]:
+    @staticmethod
+    def _row(setup: SetupSummary, module_type: RegistryModuleType) -> dict[str, Any]:
         """Trim one search hit to the fields a caller can act on.
 
         Args:
             setup: The summary returned by the registry.
+            module_type: The manager's object type; only services render a structure map.
 
         Returns:
             The rendered row.
@@ -147,11 +149,16 @@ class SearchAction(RegistryAction):
             "tags": setup.tags,
             "visibility": setup.visibility.value if setup.visibility else None,
             "status": setup.status.value if setup.status else None,
-            "description": (setup.documentation or "")[: self._DOC_PREVIEW_CHARS],
+            "documentation": setup.documentation or None,
         }
-        # Only service setups carry a map. Omitting the key rather than rendering an empty
-        # one keeps the feature out of the tools and kins surfaces entirely.
-        if setup.structure:
+        # Only service setups carry a map, so tools and kins rows never show one. A service row
+        # always does, {} included: a caller iterating rows must not meet a missing key.
+        if module_type == RegistryModuleType.SERVICE:
+            if not setup.structure:
+                logger.info(
+                    "[VALIDATE STRUCTROW] service row rendered with an empty structure: setup_id=%s",
+                    setup.setup_id,
+                )  # TODO(validate): remove after prod validation
             row["structure"] = setup.structure
         return row
 
@@ -182,9 +189,10 @@ class UpdateAction(RegistryAction):
     )
     documentation: str | None = Field(
         default=None,
-        description="Free text describing what this instance is for, indexed by ``search``. "
-        "Omit to keep the text the instance already has; pass a string to replace it, or an "
-        "empty string to clear it.",
+        max_length=300,
+        description="Free text describing what this instance is for, indexed by ``search``, at "
+        "most 300 characters. Omit to keep the text the instance already has; pass a string to "
+        "replace it, or an empty string to clear it.",
     )
 
     def _type_payload(self) -> dict[str, Any]:  # ruff: ignore[no-self-use]