API Reference

Scope: This page is an integration overview checked against the three repositories. Generated API documentation and source remain authoritative for every parameter. VCP v3.1 is the published protocol baseline; v3.2 adaptation features remain candidate or experimental.

Source-only candidate. No registry release is currently claimed. Package names below identify candidate metadata, not registry availability.

Packages

# Run from the root of an immutable VCP-SDK checkout
# Python 3.10+
python -m pip install ./python

# TypeScript browser/WebMCP integration
npm install ./webmcp

# Rust
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 VCP/I identity syntax. It does not verify a signed bundle.

CSM1Code

from vcp import CSM1Code

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

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 for transitions. Bound 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 authorised key material. Keep signing keys outside source and 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. Run JSON Schema validation at ingestion when full schema conformance evidence is required.

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

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

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. An unhandled escalation becomes a block. Custom PDPPlugin implementations must return explicit evidence and must be tested for exception behavior.

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, hashes direct identifiers with a per-process salt, supports purge handlers, and can export JSON. Protect exports and define deletion behavior outside the SDK.

TypeScript: Browser WebMCP

registerVCPTools

import { registerVCPTools } from '@creed-space/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, 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. Its online revocation transport remains unimplemented, so configured network revocation currently fails closed as REVOKED; use the Python implementation for live CRL or endpoint checks until that follow-up lands.

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 they must not be copied into an external application as an npm package import.

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, minimised 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