ShydaSHYDAPLATFORM
Vega
Vega Capability Protocol

Protocol specification

This specification describes the implemented public VCP contract — Capability package validation and the Python Provider binding. It does not define network messages, a serialization envelope, or a remote transport.

Concepts

  • Manifest contract: the package structure and declarations accepted by the standalone validator.
  • Provider contract: the Python lifecycle methods and data types invoked by Vega Runtime.
  • Execution contract: the request, context, progress, result, error, and cancellation semantics for one direct Provider call.

Package contract

A package MUST contain capability.yaml. The manifest MUST use apiVersion: vcp.shyda.ai/v1alpha1, kind: Capability, metadata, vega.sdkVersion, provider, and at least one Action. The current validator supports only provider.runtime: python and a module:Class entrypoint.

An Action MUST declare an ID, semantic version, input/output schema paths, and a contract with required description plus optional can, cannot, requires, guarantees, and limitations. The validator checks schema syntax, path containment, resource references, execution declarations, and SDK range.

Capability package
→
Standalone validation
→
Runtime loads Provider
→
initialize(context)
→
execute(request, context)
→
Result or CapabilityError
yaml
apiVersion: vcp.shyda.ai/v1alpha1
kind: Capability
metadata: {id: example.echo, name: Example Echo, version: 1.0.0}
vega: {sdkVersion: ">=0.1.0,<0.2.0"}
provider: {id: example.echo.provider, runtime: python, entrypoint: echo:Provider}
actions:
  - id: example.echo.run
    version: 1.0.0
    inputSchema: schemas/input.json
    outputSchema: schemas/output.json
    contract: {description: Return a supplied value.}

Execution contract

The Runtime calls Provider.execute(request, context) directly. Request inputs and metadata MUST be JSON-compatible and are deeply immutable. Required identity fields MUST be nonblank. A supplied deadline MUST be timezone-aware and is normalized to UTC. The execution context MUST use the same execution ID.

The Provider returns CapabilityExecutionResult with JSON-compatible output, optional Artifact references, diagnostics, and optional physical termination status. It SHOULD use an Artifact service for binary output and MUST NOT return a local absolute path as portable Action output.

sequence
Runtime → Provider : initialize(initialization context)
Runtime → Provider : execute(request, execution context)
Provider → Runtime : progress via context.progress.report()
alt success
  Provider → Runtime : CapabilityExecutionResult
else expected failure
  Provider → Runtime : CapabilityError

Errors, cancellation, progress, recovery

Providers SHOULD raise the most specific standard error category: invalid input, precondition failed, dependency unavailable, resource unavailable, hardware, communication, timeout, cancellation, safety rejection, unsupported operation, internal Provider failure, or output validation failure.

Cancellation is cooperative. CancellationToken preserves the first terminal reason and records later distinct reasons as secondary diagnostics. A Provider may implement CancellableProvider.cancel(execution_id). Coroutine completion does not prove physical stop; report physical termination accurately.

ProgressReporter.report accepts a JSON-compatible payload, validates it when a validator is injected, applies a 64 KiB default size limit, and assigns an increasing sequence and UTC timestamp. VCP defines no remote event stream.

RecoveryCapableProvider optionally reports observed restart facts through ProviderProbeResult. It MUST NOT retry or replay work; recovery decisions remain with the Runtime.

Versioning

The current manifest API is vcp.shyda.ai/v1alpha1. The current Python SDK is 0.1.0; Capability packages SHOULD declare a bounded range such as >=0.1.0,<0.2.0. versions_compatible compares normalized Action versions for equality and does not negotiate ranges.