API reference

Scope: This page is an integration overview checked against the VCP-SDK, VCP-Spec and VCP-Demo-Site repositories. Generated API documentation and source remain authoritative for every parameter. VCP v3.1 is the current source baseline, not yet an immutable release; v3.2 adaptation features remain candidate or experimental.

Published 4.2.0. Registry releases exist for every artifact; conformance claims remain same-program evidence. The package names below are live on PyPI, npm and crates.io, and the publication-state record lists each registry receipt and the source commit.

Packages

# Python 3.10+
python -m pip install value-context-protocol==4.2.0

# TypeScript browser/WebMCP integration
npm install @creedspace/vcp-sdk@4.2.0

# Rust
cargo add vcp-core@4.2.0

# Or from the root of a VCP-SDK checkout at the published commit (tag v4.2.0, c5035e9)
python -m pip install ./python
npm install ./webmcp
cargo build --manifest-path ./rust/Cargo.toml -p vcp-core

Python: identity and semantics

Token

from vcp import Token

token = Token.parse("family.safe.guide@1.2.0")
token.full       # family.safe.guide@1.2.0
token.canonical  # family.safe.guide
token.domain     # family
token.role       # guide

Token.parse validates the syntax of a UVC token (the VCP/I identity token that names a constitution). It does not verify a signed bundle.

CSM1Code

from vcp import CSM1Code

code = CSM1Code.parse("N5+F+E")
canonical = code.encode()  # N5+E+F

CSM1Code parses a one-line CSM-1 code. N5+F+E is the Nanny persona at adherence level 5 with the Family and Education scopes, and encode() returns the canonical form, which sorts the scopes. SDK 4.2.0 parses and encodes the NANO and MICRO code tiers but not COMPACT. Use Composer for semantic composition and handle CompositionConflictError rather than discarding conflicts.

Python: adaptation context

VCPContext

from vcp.adaptation import (
    PersonalState,
    PersonalStateDimension,
    SituationalDimension,
    VCPContext,
)

context = VCPContext(
    situational={SituationalDimension.TIME: ["🌅"]},
    personal={
        PersonalStateDimension.COGNITIVE_STATE:
            PersonalState("focused", 4),
    },
)

wire = context.encode()
decoded = VCPContext.decode(wire)

Situational values and personal-state values are immutable value objects. The candidate v3.2 model contains 13 situational dimensions and five personal dimensions. Dimension remains a compatibility alias for SituationalDimension.

ContextEncoder

from vcp.adaptation import ContextEncoder

context = ContextEncoder().encode(
    time="morning",
    space="home",
    company="children",
)

Use StateTracker to detect transitions between contexts. Set size and lifetime limits on long-lived tracker and cache state in the hosting application.

Python: bundles and verification

BundleBuilder

BundleBuilder constructs a bundle manifest and content. Applications provide signing functions and authorized key material. Keep signing keys out of source code and out of process logs.

Orchestrator

from vcp import Orchestrator, VerificationContext, VerificationResult

context = VerificationContext(
    trust_config=trust,
    model_family="example-model-*",
    purpose="customer-support",
    environment="production",
    audience="adult",
    region="GB",
)

result = Orchestrator(trust).verify(bundle, context=context)
if result is not VerificationResult.VALID:
    raise PermissionError(result.name)

The Python verifier covers bounded size, content hash, issuer and auditor trust, Ed25519 signatures, attestation, revocation, temporal claims, replay, token budget, and configured scope, with malformed object structure mapped to INVALID_SCHEMA. Keep audience and region explicit where the bundle declares them. The verifier checks object structure but does not run full JSON Schema validation, so run JSON Schema validation at ingestion when you need evidence that a bundle conforms to the schema.

VerificationResult

VALID
SIZE_EXCEEDED | INVALID_SCHEMA
UNTRUSTED_ISSUER | INVALID_SIGNATURE
UNTRUSTED_AUDITOR | INVALID_ATTESTATION
HASH_MISMATCH | NOT_YET_VALID | EXPIRED | FUTURE_TIMESTAMP
REPLAY_DETECTED | TOKEN_MISMATCH | BUDGET_EXCEEDED
SCOPE_MISMATCH | REVOKED | FETCH_FAILED | REVOCATION_UNAVAILABLE

Only VALID permits the application to continue to enforcement. Use verify_or_raise when exception flow is clearer.

When a manifest configures revocation, a confirmed revocation returns REVOKED, and a revocation source that is unreachable or cannot establish a status returns REVOCATION_UNAVAILABLE. Both reject the bundle. FETCH_FAILED is reserved, and SDK 4.2.0 does not return it.

Python: enforcement

PDPEnforcer

from vcp import (
    BundleExpiryPlugin,
    PDPEnforcer,
    RefusalBoundaryPlugin,
)

enforcer = PDPEnforcer(fail_closed=True)
enforcer.register(BundleExpiryPlugin())
enforcer.register(RefusalBoundaryPlugin())

decision = enforcer.evaluate(
    bundle,
    content=user_input,
    verification_result=result,
)

if not decision.allowed:
    stop_action()

Decision types are ALLOW, BLOCK, MODIFY, and ESCALATE. The SDK 4.2.0 enforcer has no escalation handler, so a plugin's ESCALATE makes the final decision BLOCK and stays in the result's decision list for your application to route to human review. Custom PDPPlugin implementations must attach explicit evidence to every decision they return; returning None abstains. Test what happens when a plugin raises: with fail_closed=True, the enforcer turns the exception into a block.

Python: privacy and audit

The privacy module exposes PlatformManifest, ConsentRecord, filter_context_for_platform, field classifications, stakeholder visibility helpers, and share-preview utilities.

from vcp import filter_context_for_platform

filtered = filter_context_for_platform(
    context,
    platform_manifest,
    consent_record,
)

Filtering helpers do not choose your lawful basis, consent language, persistence tier, or retention period.

AuditLogger records verification and privacy-filter events and, by default, hashes direct identifiers with a per-process salt. Pass a stable privacy_salt so that hashes, and therefore purges, still match after a restart, and call track_exported_path to re-attach exports written before the restart. The logger supports purge handlers and can export JSON. Protect exports and define deletion behavior outside the SDK.

TypeScript: browser WebMCP

registerVCPTools

import { registerVCPTools } from '@creedspace/vcp-sdk';

const { registered, cleanup } = await registerVCPTools({
  chatEndpoint: '/api/chat',
  enableChat: false,
  enableTokenBuilder: true,
  enableTokenParser: true,
  enableSummary: true,
  enablePersonas: true,
});

cleanup();

The function returns an empty result during server rendering or when document.modelContext is unavailable. Tool definitions are also available through createVCPTools. The package exposes hooks and selected personal, relational, consensus, torch (session handoff), and capability-negotiation helpers.

The package never injects a remote polyfill. Use the exported polyfill loader with an application-owned, bundled import if you deliberately support that mode.

Rust: core types

use vcp_core::{
    Csm1Code,
    FullContext,
    Orchestrator,
    TrustConfig,
    VcpToken,
};

let identity = VcpToken::parse(
    "family.safe.guide@1.2.0"
)?;
let profile = Csm1Code::parse("N5+F+E")?;

vcp-core also exports context, personal and situational types, trust anchors, transport hashing and signature verification, hooks, revocation, composition, and negotiation. The workspace includes vcp-cli and vcp-wasm as separate crates. The Rust orchestrator accepts manifest JSON and performs required-field checks, but it is not a general JSON Schema validator. Native builds check revocation online through ReqwestRevocationTransport: the status endpoint first, then the certificate revocation list (CRL). If no configured source can establish a status, verification fails closed as RevocationUnavailable (code 17), which is distinct from a confirmed Revoked (code 15). The wasm32 build has no live transport, so a browser host must inject one or preload a CRL.

Demo-local TypeScript modules

This site imports application code from $lib/vcp and $lib/vcp-webmcp-sdk. Those aliases exist only inside VCP-Demo-Site. They are useful implementation examples, but an import from these aliases will not resolve in another application; install the published packages above instead.

Security-critical ordering

1. Bound and parse untrusted input
2. Load explicit trust configuration
3. Verify every bundle independently
4. Apply local enforcement and privacy filtering
5. Format only verified, minimized content
6. Invoke the model or tool through an application-owned adapter
7. Record redacted evidence and apply retention controls

Next steps

• Getting started: runnable package examples
• Security: trust and privacy boundaries
• VCP-SDK source: generated docs, tests, and examples
• VCP-Spec source: normative and pre-release status