Vega Python SDK Overview — Shyda Platform SDKs

Overview

The Vega Capability SDK is the standalone Python toolkit for implementing Vega Capability Providers. Its distribution name is vega-capability-sdk; its import package is vega_capability_sdk. Use it to define a Provider lifecycle, receive immutable execution requests and restricted contexts, return structured results, report progress, raise standard errors, validate packages, and test Providers without starting Vega Runtime.

The SDK is not Vega Runtime, a VCP wire protocol, a robot driver, or a Capability architecture framework. It intentionally does not import Runtime internals or vendor packages.

This Guide targets Capability authors, robotics software engineers, platform integrators, and reviewers who need to implement a public VCP Provider contract in Python. It assumes familiarity with Python packaging, asynchronous Python, and JSON Schema.

Install

The SDK requires Python 3.12 or later:

bash

python -m pip install "vega-capability-sdk>=0.1.0,<0.2.0"

Use the compatibility range approved for your Capability release. The range above applies to the documented 0.1.x SDK line. Supported deployment targets are Linux x86-64 and Linux aarch64. Validate the Capability and all vendor dependencies on its declared target environment.

Concepts

Term	Meaning
Provider	A Python object implementing initialization, execution, health, and shutdown behavior.
Context	Runtime-injected services and state available at initialization or during one execution.
Manifest	A capability.yaml declaration validated by SDK tooling.
Conformance harness	SDK test helper that exercises a Provider lifecycle.
Action	A versioned operation declared by a Capability with input, output, execution, and real-world contract information.
Artifact	Externally stored binary or large output represented by a portable reference.

Why the SDK exists

The SDK lets a Capability author implement a stable public contract while keeping hardware, vendor, and service dependencies in the Capability package. It supplies common behavior — immutability, cancellation, errors, structured logging, Artifact contracts, and testing — so each Capability does not need to reinvent those boundaries.

Responsibilities and non-responsibilities

The SDK provides Provider base classes and protocols, execution and health contracts, configuration and secret wrappers, manifest validation, services, and deterministic test doubles.

It does not decide Runtime scheduling, task/session behavior, resource arbitration, mission retry, remote Provider transport, or robot safety policy. It has no public Task, Session, Event bus, streaming transport, or TypeScript binding. Runtime correlation fields may appear in an execution request, but the SDK does not expose Runtime task/session APIs.

Term	Meaning
Implement Action behavior	BaseCapabilityProvider hooks
Validate a Capability package	vega-capability validate or manifest APIs
Test without Runtime	vega_capability_sdk.testing
Schedule or continue a mission	Vega Runtime, not the SDK
Integrate vendor hardware	A Capability-owned adapter
Define a remote wire transport	No current SDK API

Relationship to Vega

Vega Runtime loads and invokes the Provider. VCP defines the public manifest and Provider contracts. Capability Development guidance explains package organization and release practice. This guide explains how Python code uses the SDK.

Guide and API Reference

This guide is intentionally decision- and workflow-oriented. It explains how Provider lifecycle hooks, requests, contexts, results, errors, and supporting utilities compose into a Capability implementation. The Python API Reference remains the authoritative place for exhaustive symbol coverage, defaults, and precise validation constraints.

Typical workflow

Define the manifest and schemas.
Implement the Provider.
Validate the package.
Run unit and conformance tests.
Deploy the validated package for Runtime loading.

Example

python

from vega_capability_sdk import BaseCapabilityProvider, CapabilityExecutionResult

class EchoProvider(BaseCapabilityProvider):
    async def on_execute(self, request, context):
        context.validate_request(request)
        return CapabilityExecutionResult(output={"echo": request.inputs})

This short example shows only Provider composition. Follow Getting Started for a complete installable project with a manifest, schemas, and tests.

Compatibility and stability

The SDK is currently 0.x. Use bounded dependency ranges and review release notes before changing the accepted minor version. Keep these versions distinct:

SDK distribution version: compatibility of the Python binding.
Capability package version: release identity of the Capability.
Action version: compatibility of one Action contract.
VCP apiVersion: version of the manifest/protocol definition.

Do not infer compatibility by comparing raw strings. Package validation applies the SDK range declared by vega.sdkVersion.

Common misconceptions

Installing the SDK does not install Vega Runtime.
Reporting Progress does not create a WebSocket or public event stream.
Cancelling a Python coroutine does not prove that a physical action stopped.
A resource lease is not device-level safety confirmation.
Secret redaction wrappers do not make a raw secret safe after extraction.
Passing the conformance harness does not replace hardware, integration, or safety testing.

Vega Capability SDK for Python