Concepts
- Manifest reference: the currently supported package declarations and validation constraints.
- SDK reference: the public Python Provider types and enumerations.
- Reference implementation: the behavior defined by the published SDK code and its tests, rather than an unpublished transport protocol.
Manifest constants and fields
| Item | Current value or rule |
|---|---|
| Manifest filename | capability.yaml |
| Supported API version | vcp.shyda.ai/v1alpha1 |
| Required kind | Capability |
| Provider runtime | python only |
| Provider entrypoint | module:Class |
| Metadata ID | lowercase pattern [a-z0-9][a-z0-9._-]* |
| Action ID | dot-separated lowercase components, each beginning with a letter |
| Version | semantic version text |
Required top-level manifest fields are apiVersion, kind, metadata, vega, provider, and actions. vega.sdkVersion is required. Optional sections include compatibility, dependencies, resources, configuration, and secrets.
Action execution declarations
| Field | Values or default |
|---|---|
| defaultTimeoutSeconds | 30.0 by default; may be null |
| cancellation, pause, resume, progress | boolean; false by default |
| idempotency | idempotent, non_idempotent, conditional |
| restartRecovery | restart, resume, re_evaluate, manual_confirmation, not_recoverable |
resume: true requires pause: true. restartRecovery: resume requires resume: true. progress: true requires a progress schema.
Python Provider contract
async def initialize(context: ProviderInitializationContext) -> None: ...async def execute(request: CapabilityExecutionRequest,context: CapabilityExecutionContext,) -> CapabilityExecutionResult: ...async def health_check() -> CapabilityHealthResult: ...async def shutdown() -> None: ...
Optional protocols are CancellableProvider, PausableProvider, ResumableProvider, ReloadableProvider, and RecoveryCapableProvider.
Execution request and result
| Request field | Requirement |
|---|---|
| execution_id, capability_id, provider_id, action_id, action_version | nonblank strings |
| inputs, metadata | deeply immutable JSON-compatible values |
| deadline | optional timezone-aware UTC datetime |
| idempotency_key, mission_id, task_graph_id, node_id, trace_id | optional strings |
| Result field | Requirement |
|---|---|
| output, diagnostics | deeply immutable JSON-compatible values |
| artifact_references | strings or ArtifactReference values |
| physical_termination | optional termination-status enumeration |
Enumerations
| Enumeration | Values |
|---|---|
| Health | healthy, degraded, unhealthy, unknown |
| Cancellation reason | user_request, mission_cancelled, timeout, task_timeout, runtime_shutdown, safety_stop, operator_request, parent_cancelled |
| Physical termination | not_applicable, unknown, confirmed, failed_to_confirm |
| Resource mode | exclusive, shared |
| Recovery probe | active, succeeded, failed, cancelled, not_found, unknown, unavailable |
| Recovery safety class | pure, idempotent, retry_safe, status_query_required, non_idempotent, human_confirmation_required |
Standard error categories
CapabilityError.to_dict() produces error_code, category, message, retryable, severity, and details. Categories are invalid_input, precondition_failed, dependency_unavailable, resource_unavailable, hardware_error, communication_error, timeout, cancelled, safety_rejection, unsupported_operation, provider_internal_error, and output_validation_failed.
Recovery constraints
ProviderProbeResult rejects contradictory state: succeeded cannot include an error; failed cannot include a successful result; and not-found, unknown, or unavailable cannot include either result or error.
Example package validation
vega-capability validate /path/to/capabilityvega-capability validate . --json
The validator does not import the Provider, install dependencies, determine live hardware compatibility, or start Vega Runtime.