Capability Development — Shyda Platform Docs

Concepts

Manifest-first development: define the contract before behavior.
Provider: lifecycle-aware class implementing an Action.
Adapter: testable component performing integration-specific work.
Context: injected services that avoid Runtime-internal dependencies.

Workflow

Define schemas & contract

→

Create package

→

Implement Provider & adapter

→

Validate package

→

Unit & conformance tests

→

Controlled integration test

Implementation walkthrough

Project metadata should depend on vega-capability-sdk>=0.1.0,<0.2.0. Define strict input/output schemas and a manifest Action that names their paths. Then implement a Provider:

python

from dataclasses import dataclass
from vega_capability_sdk import BaseCapabilityProvider, CapabilityExecutionResult
from vega_capability_sdk import CapabilityHealthResult, InvalidInputError

@dataclass
class EchoAdapter:
    async def echo(self, text: str) -> str:
        return text

class EchoProvider(BaseCapabilityProvider):
    def __init__(self, adapter: EchoAdapter | None = None) -> None:
        super().__init__()
        self._adapter = adapter or EchoAdapter()

    async def on_execute(self, request, context):
        context.validate_request(request)
        text = request.inputs.get("text")
        if request.action_id != "example.echo.run" or not isinstance(text, str) or not text.strip():
            raise InvalidInputError("text must be a non-empty string")
        context.cancellation.raise_if_cancelled()
        await context.progress.report({"phase": "working"})
        return CapabilityExecutionResult(output={"echo": await self._adapter.echo(text)})

    async def on_health_check(self):
        return CapabilityHealthResult.healthy()

Context, state, and errors

Use context.configuration for public settings and self.init_context.secrets for declared secrets. Use the injected logger, clock, trace, Artifact service, and resource leases. Keep Provider state to managed connections and adapter state initialized/released by lifecycle hooks.

Raise a specific SDK error: invalid input, precondition failed, dependency unavailable, resource unavailable, hardware, communication, timeout, cancellation, safety rejection, unsupported operation, or output validation. Report progress only when the manifest declares it and payload matches its schema.

Performance and reliability

Avoid blocking the event loop with synchronous device calls.
Respect cancellation at safe points.
Avoid unbounded diagnostics or buffers; write large binary output through the Artifact service.
Declare non-idempotent behavior and physical-termination limits honestly.