Skip to content

API_REFERENCE.md

Latest commit

 

History

History
1743 lines (1346 loc) · 43.7 KB

API_REFERENCE.md

File metadata and controls

1743 lines (1346 loc) · 43.7 KB

vCon Library API Reference

Complete API documentation for the vCon library - a Python implementation of the latest vCon specification for Virtual Conversation objects.

Table of Contents

Overview

The vCon library provides a complete Python implementation of the latest vCon specification for representing virtual conversations. It supports all features including parties, dialogs, attachments, analysis, digital signatures, extensibility, and advanced extensions for lawful basis management and standardized transcription formats.

Installation

pip install vcon

Image/PDF processing support is included by default with the standard installation.

Core Classes

Vcon Class

The main class for working with vCon objects.

Constructor

Vcon(vcon_dict: Dict[str, Any] = None, property_handling: str = "default")

Parameters:

  • vcon_dict (Dict[str, Any], optional): Dictionary representing a vCon. Defaults to empty dict.
  • property_handling (str): How to handle non-standard properties:
    • "default": Keep non-standard properties (default)
    • "strict": Remove non-standard properties
    • "meta": Move non-standard properties to meta object

Class Methods

build_new() -> Vcon

Create a new vCon object with default values.

vcon = Vcon.build_new()
build_from_json(json_str: str, property_handling: str = "default") -> Vcon

Create a vCon object from JSON string.

vcon = Vcon.build_from_json('{"uuid": "123", "created_at": "2024-01-01T00:00:00Z"}')
load(file_path_or_url: str, property_handling: str = "default") -> Vcon

Load a vCon from file or URL.

# From file
vcon = Vcon.load("conversation.vcon.json")

# From URL
vcon = Vcon.load("https://example.com/conversation.vcon.json")
load_from_file(file_path: str, property_handling: str = "default") -> Vcon

Load a vCon from a local file.

load_from_url(url: str, property_handling: str = "default") -> Vcon

Load a vCon from a URL.

validate_file(file_path: str) -> Tuple[bool, List[str]]

Validate a vCon file.

is_valid, errors = Vcon.validate_file("conversation.vcon.json")
validate_json(json_str: str) -> Tuple[bool, List[str]]

Validate a vCon JSON string.

generate_key_pair() -> Tuple[rsa.RSAPrivateKey, rsa.RSAPublicKey]

Generate RSA key pair for digital signatures.

private_key, public_key = Vcon.generate_key_pair()
uuid8_domain_name(domain_name: str) -> str

Generate UUID8 with domain name.

uuid8_time(custom_c_62_bits: int) -> str

Generate UUID8 with custom time bits.

Instance Methods

Party Management
add_party(party: Party) -> None

Add a party to the vCon.

party = Party(tel="+1234567890", name="Alice", role="caller")
vcon.add_party(party)
find_party_index(by: str, val: str) -> Optional[int]

Find party index by field value.

index = vcon.find_party_index("tel", "+1234567890")
Dialog Management
add_dialog(dialog: Dialog) -> None

Add a dialog to the vCon.

dialog = Dialog(type="text", start=datetime.now(), parties=[0, 1], body="Hello")
vcon.add_dialog(dialog)
find_dialog(by: str, val: str) -> Optional[Dialog]

Find dialog by field value.

dialog = vcon.find_dialog("type", "text")
find_dialogs_by_type(type: str) -> List[Dict[str, Any]]

Find all dialogs of a specific type.

text_dialogs = vcon.find_dialogs_by_type("text")
add_transfer_dialog(start: Union[datetime, str], transfer_data: Dict[str, Any], parties: List[int]) -> None

Add a transfer dialog.

transfer_data = {
    "transferee": 0,
    "transferor": 1,
    "transfer_target": 2
}
vcon.add_transfer_dialog(datetime.now(), transfer_data, [0, 1, 2])
add_incomplete_dialog(start: Union[datetime, str], disposition: str, parties: List[int]) -> None

Add an incomplete dialog.

vcon.add_incomplete_dialog(datetime.now(), "no-answer", [0])
Attachment Management
add_attachment(purpose: str, body: Any, encoding: str = "none") -> Attachment

Add an attachment to the vCon.

attachment = vcon.add_attachment("transcript", "Full conversation...", "none")
add_image(image_path: str, type: str = "image") -> Attachment

Add an image attachment from file.

attachment = vcon.add_image("screenshot.png", "screenshot")
find_attachment_by_purpose(purpose: str) -> Optional[Dict[str, Any]]

Find attachment by type.

transcript = vcon.find_attachment_by_purpose("transcript")
Analysis Management
add_analysis(type: str, dialog: Union[int, List[int]], vendor: str, body: Any, encoding: str = "none") -> None

Add analysis data to the vCon.

vcon.add_analysis(
    type="sentiment",
    dialog=[0, 1],
    vendor="SentimentAnalyzer",
    body={"sentiment": "positive", "confidence": 0.85},
    encoding="json"
)
find_analysis_by_type(type: str) -> Optional[Dict[str, Any]]

Find analysis by type.

sentiment = vcon.find_analysis_by_type("sentiment")
Tag Management
add_tag(tag_name: str, tag_value: str) -> None

Add a tag to the vCon.

vcon.add_tag("customer_id", "12345")
get_tag(tag_name: str) -> Optional[str]

Get a tag value.

customer_id = vcon.get_tag("customer_id")
Extension Management
add_extension(extension: str) -> None

Add an extension to the vCon.

vcon.add_extension("video")
get_extensions() -> List[str]

Get list of extensions.

extensions = vcon.get_extensions()
remove_extension(extension: str) -> None

Remove an extension.

vcon.remove_extension("video")
add_critical(extension: str) -> None

Add a must-support extension.

vcon.add_critical("encryption")
get_critical() -> List[str]

Get list of must-support extensions.

critical = vcon.get_critical()
remove_critical(extension: str) -> None

Remove a must-support extension.

Extension-Specific Methods
add_lawful_basis_attachment(lawful_basis: str, expiration: str, purpose_grants: list, party_index: Optional[int] = None, dialog_index: Optional[int] = None, **kwargs) -> None

Add a lawful basis attachment to the vCon.

vcon.add_lawful_basis_attachment(
    lawful_basis="consent",
    expiration="2026-01-01T00:00:00Z",
    purpose_grants=[
        {"purpose": "recording", "granted": True, "granted_at": "2025-01-01T00:00:00Z"}
    ],
    party_index=0
)
add_wtf_transcription_attachment(transcript: Dict[str, Any], segments: List[Dict[str, Any]], metadata: Dict[str, Any], party_index: Optional[int] = None, dialog_index: Optional[int] = None, **kwargs) -> None

Add a WTF transcription attachment to the vCon.

vcon.add_wtf_transcription_attachment(
    transcript={"text": "Hello world", "language": "en", "duration": 2.0, "confidence": 0.95},
    segments=[{"id": 0, "start": 0.0, "end": 2.0, "text": "Hello world", "confidence": 0.95}],
    metadata={"created_at": "2025-01-01T00:00:00Z", "provider": "whisper", "model": "whisper-1"}
)
find_lawful_basis_attachments(party_index: Optional[int] = None) -> List[Dict[str, Any]]

Find lawful basis attachments in the vCon.

attachments = vcon.find_lawful_basis_attachments(party_index=0)
find_wtf_attachments(party_index: Optional[int] = None) -> List[Dict[str, Any]]

Find WTF transcription attachments in the vCon.

attachments = vcon.find_wtf_attachments(party_index=0)
check_lawful_basis_permission(purpose: str, party_index: Optional[int] = None) -> bool

Check if permission is granted for a specific purpose.

has_permission = vcon.check_lawful_basis_permission("recording", party_index=0)
validate_extensions() -> Dict[str, Any]

Validate all extensions in the vCon.

results = vcon.validate_extensions()
process_extensions() -> Dict[str, Any]

Process all extensions in the vCon.

results = vcon.process_extensions()
Security
sign(private_key: Union[rsa.RSAPrivateKey, bytes]) -> None

Sign the vCon with a private key.

vcon.sign(private_key)
verify(public_key: Union[rsa.RSAPublicKey, bytes]) -> bool

Verify the vCon signature.

is_valid = vcon.verify(public_key)
Validation
is_valid() -> Tuple[bool, List[str]]

Validate the vCon object.

is_valid, errors = vcon.is_valid()
Serialization
to_json() -> str

Convert vCon to JSON string.

json_str = vcon.to_json()
to_dict() -> Dict[str, Any]

Convert vCon to dictionary.

vcon_dict = vcon.to_dict()
dumps() -> str

Alias for to_json().

save_to_file(file_path: str) -> None

Save vCon to file.

vcon.save_to_file("conversation.vcon.json")
HTTP Operations
post_to_url(url: str, headers: Optional[Dict[str, str]] = None) -> requests.Response

Post vCon to URL.

response = vcon.post_to_url("https://api.example.com/vcon", headers={"Authorization": "Bearer token"})
Timestamp Management
set_created_at(created_at: Union[str, datetime]) -> None

Set the creation timestamp.

set_updated_at(timestamp: Union[str, datetime]) -> None

Set the update timestamp.

Properties

uuid -> str

Get the vCon UUID.

vcon -> Optional[str]

Get the vCon version (optional field).

subject -> Optional[str]

Get the vCon subject.

created_at

Get the creation timestamp.

updated_at

Get the update timestamp.

redacted

Get the redacted flag.

amended

Get the amended flag.

group

Get the group information.

meta

Get the metadata.

parties -> List[Party]

Get list of parties.

dialog -> List[Dict[str, Any]]

Get list of dialogs.

attachments -> List[Dict[str, Any]]

Get list of attachments.

analysis -> List[Dict[str, Any]]

Get list of analysis data.

tags -> Optional[Dict[str, Any]]

Get all tags.

Party Class

Represents a participant in a vCon conversation.

Constructor

Party(
    tel: Optional[str] = None,
    stir: Optional[str] = None,
    mailto: Optional[str] = None,
    name: Optional[str] = None,
    validation: Optional[str] = None,
    gmlpos: Optional[str] = None,
    civicaddress: Optional[CivicAddress] = None,
    uuid: Optional[str] = None,
    role: Optional[str] = None,
    contact_list: Optional[str] = None,
    meta: Optional[dict] = None,
    sip: Optional[str] = None,
    did: Optional[str] = None,
    jCard: Optional[dict] = None,
    timezone: Optional[str] = None,
    **kwargs
)

Parameters:

  • tel (str, optional): Telephone number
  • stir (str, optional): STIR identifier
  • mailto (str, optional): Email address
  • name (str, optional): Display name
  • validation (str, optional): Validation information
  • gmlpos (str, optional): GML position coordinates
  • civicaddress (CivicAddress, optional): Civic address information
  • uuid (str, optional): Unique identifier
  • role (str, optional): Role in conversation (e.g., "caller", "agent")
  • contact_list (str, optional): Contact list reference
  • meta (dict, optional): Additional metadata
  • sip (str, optional): SIP URI for VoIP communication
  • did (str, optional): Decentralized Identifier
  • jCard (dict, optional): vCard format contact information
  • timezone (str, optional): Party's timezone

Methods

to_dict() -> Dict[str, Any]

Convert Party to dictionary.

party_dict = party.to_dict()

Dialog Class

Represents a dialog segment in a vCon conversation.

Constructor

Dialog(
    type: str,
    start: Union[datetime, str],
    parties: List[int],
    originator: Optional[int] = None,
    mediatype: Optional[str] = None,
    filename: Optional[str] = None,
    body: Optional[str] = None,
    encoding: Optional[str] = None,
    url: Optional[str] = None,
    disposition: Optional[str] = None,
    party_history: Optional[List[PartyHistory]] = None,
    transferee: Optional[int] = None,
    transferor: Optional[int] = None,
    transfer_target: Optional[int] = None,
    original: Optional[int] = None,
    consultation: Optional[int] = None,
    target_dialog: Optional[int] = None,
    campaign: Optional[str] = None,
    interaction: Optional[str] = None,
    skill: Optional[str] = None,
    duration: Optional[float] = None,
    meta: Optional[dict] = None,
    metadata: Optional[Dict[str, Any]] = None,
    transfer: Optional[Dict[str, Any]] = None,
    signaling: Optional[Dict[str, Any]] = None,
    resolution: Optional[str] = None,
    frame_rate: Optional[float] = None,
    codec: Optional[str] = None,
    bitrate: Optional[int] = None,
    thumbnail: Optional[str] = None,
    session_id: Optional[Union[Dict[str, str], List[Dict[str, str]]]] = None,
    content_hash: Optional[str] = None,
    application: Optional[str] = None,
    message_id: Optional[str] = None,
    **kwargs
)

Parameters:

  • type (str): Dialog type ("text", "recording", "transfer", "incomplete", "audio", "video")
  • start (Union[datetime, str]): Start time
  • parties (List[int]): List of party indices
  • originator (int, optional): Originator party index
  • mediatype (str, optional): MIME type of content
  • filename (str, optional): Filename
  • body (str, optional): Content body
  • encoding (str, optional): Content encoding
  • url (str, optional): External URL
  • disposition (str, optional): Disposition for incomplete dialogs
  • party_history (List[PartyHistory], optional): Party event history
  • transferee (int, optional): Transferee party index
  • transferor (int, optional): Transferor party index
  • transfer_target (int, optional): Transfer target party index
  • original (int, optional): Original dialog index
  • consultation (int, optional): Consultation dialog index
  • target_dialog (int, optional): Target dialog index
  • campaign (str, optional): Campaign identifier
  • interaction (str, optional): Interaction identifier
  • skill (str, optional): Skill identifier
  • duration (float, optional): Dialog duration
  • meta (dict, optional): Additional metadata
  • metadata (Dict[str, Any], optional): Structured metadata
  • transfer (Dict[str, Any], optional): Transfer-specific information
  • signaling (Dict[str, Any], optional): Signaling information
  • resolution (str, optional): Video resolution (e.g., "1920x1080")
  • frame_rate (float, optional): Video frame rate
  • codec (str, optional): Video codec
  • bitrate (int, optional): Video bitrate
  • thumbnail (str, optional): Base64-encoded thumbnail
  • session_id (dict or list, optional): Session identifier (SessionId or list of SessionId)
  • content_hash (str, optional): Content hash for external files
  • application (str, optional): Application identifier
  • message_id (str, optional): Message identifier

Methods

to_dict() -> Dict[str, Any]

Convert Dialog to dictionary.

add_external_data(url: str, filename: str, mediatype: str) -> None

Add external data to dialog.

add_inline_data(body: str, filename: str, mediatype: str) -> None

Add inline data to dialog.

is_external_data() -> bool

Check if dialog has external data.

is_inline_data() -> bool

Check if dialog has inline data.

is_text() -> bool

Check if dialog is text type.

is_recording() -> bool

Check if dialog is recording type.

is_transfer() -> bool

Check if dialog is transfer type.

is_incomplete() -> bool

Check if dialog is incomplete type.

is_audio() -> bool

Check if dialog has audio content.

is_video(content_type: Optional[str] = None) -> bool

Check if dialog has video content.

is_email() -> bool

Check if dialog is email type.

is_image() -> bool

Check if dialog has image content.

is_pdf() -> bool

Check if dialog has PDF content.

add_video_data(video_data, filename: Optional[str] = None, mediatype: Optional[str] = None, inline: bool = True, metadata: Optional[dict] = None) -> None

Add video data to dialog.

extract_video_metadata(video_path: Optional[str] = None) -> dict

Extract video metadata using FFmpeg.

generate_thumbnail(timestamp: float = 0.0, width: int = 320, height: int = 240, quality: int = 90) -> bytes

Generate video thumbnail.

add_streaming_video_reference(reference_id: str, mediatype: str, metadata: Optional[dict] = None) -> None

Add streaming video reference.

add_video_with_optimal_storage(video_data, filename: str, mediatype: Optional[str] = None, size_threshold_mb: int = 10) -> None

Add video with optimal storage method.

transcode_video(target_format: str, codec: Optional[str] = None, bit_rate: Optional[int] = None, width: Optional[int] = None, height: Optional[int] = None) -> None

Transcode video to different format.

add_image_data(image_path: str, mediatype: Optional[str] = None) -> None

Add image data from file.

extract_image_metadata(image_data: bytes, mediatype: str) -> None

Extract image metadata.

generate_thumbnail(max_size: Tuple[int, int] = (200, 200)) -> Optional[str]

Generate image thumbnail.

is_external_data_changed() -> bool

Check if external data has changed.

to_inline_data() -> None

Convert external data to inline data.

set_session_id(session_id: Union[Dict[str, str], List[Dict[str, str]]]) -> None

Set session identifier.

get_session_id() -> Optional[Union[Dict[str, str], List[Dict[str, str]]]]

Get session identifier.

set_content_hash(content_hash: str) -> None

Set content hash.

get_content_hash() -> Optional[str]

Get content hash.

calculate_content_hash(algorithm: str = "sha256") -> str

Calculate content hash.

verify_content_hash(expected_hash: str, algorithm: str = "sha256") -> bool

Verify content hash.

CivicAddress Class

Represents civic address information according to GEOPRIV specification.

Constructor

CivicAddress(
    country: Optional[str] = None,
    a1: Optional[str] = None,
    a2: Optional[str] = None,
    a3: Optional[str] = None,
    a4: Optional[str] = None,
    a5: Optional[str] = None,
    a6: Optional[str] = None,
    prd: Optional[str] = None,
    pod: Optional[str] = None,
    sts: Optional[str] = None,
    hno: Optional[str] = None,
    hns: Optional[str] = None,
    lmk: Optional[str] = None,
    loc: Optional[str] = None,
    flr: Optional[str] = None,
    nam: Optional[str] = None,
    pc: Optional[str] = None
)

Parameters:

  • country (str, optional): Country code (ISO 3166-1 alpha-2)
  • a1 (str, optional): Administrative area 1 (state/province)
  • a2 (str, optional): Administrative area 2 (county/municipality)
  • a3 (str, optional): Administrative area 3 (city/town)
  • a4 (str, optional): Administrative area 4 (neighborhood/district)
  • a5 (str, optional): Administrative area 5 (postal code)
  • a6 (str, optional): Administrative area 6 (building/floor)
  • prd (str, optional): Premier (department/suite number)
  • pod (str, optional): Post office box identifier
  • sts (str, optional): Street name
  • hno (str, optional): House number
  • hns (str, optional): House name
  • lmk (str, optional): Landmark name
  • loc (str, optional): Location name
  • flr (str, optional): Floor
  • nam (str, optional): Name of location
  • pc (str, optional): Postal code

Methods

to_dict() -> Dict[str, Optional[str]]

Convert CivicAddress to dictionary.

PartyHistory Class

Represents party history events in a vCon dialog.

Constructor

PartyHistory(party: int, event: str, time: datetime)

Parameters:

  • party (int): Index of the party
  • event (str): Event type ("join", "drop", "hold", "unhold", "mute", "unmute")
  • time (datetime): Time of the event

Methods

to_dict() -> Dict[str, Any]

Convert PartyHistory to dictionary.

Attachment Class

Represents an attachment in a vCon.

Constructor

Attachment(type: str, body: Any, encoding: str = "none")

Parameters:

  • type (str): Type of attachment
  • body (Any): Content of attachment
  • encoding (str): Encoding format ("base64", "base64url", "none")

Methods

to_dict() -> Dict[str, Any]

Convert Attachment to dictionary.

from_image(image_path: str, type: str = "image") -> 'Attachment'

Create attachment from image file.

Extensions

The vCon library includes a comprehensive extension framework that allows for standardized implementation of additional functionality. Two major extensions are currently implemented: the Lawful Basis extension for privacy compliance and the WTF (World Transcription Format) extension for standardized transcription data.

Extension Framework

The extension framework provides a standardized way to add new functionality to vCon objects while maintaining compatibility and validation.

Core Extension Classes

ExtensionType

Enumeration of extension types:

  • COMPATIBLE: Safe to ignore, no breaking changes
  • INCOMPATIBLE: Must be supported, breaking changes
  • EXPERIMENTAL: Development/testing only
ExtensionValidator

Abstract base class for extension validation logic.

ExtensionProcessor

Abstract base class for extension processing logic.

ExtensionRegistry

Central registry for managing extensions.

from vcon.extensions import get_extension_registry

# Get the global registry
registry = get_extension_registry()

# List all registered extensions
extensions = registry.list_extensions()

Lawful Basis Extension

The Lawful Basis extension provides comprehensive support for privacy compliance and consent management according to GDPR and other privacy regulations.

Key Features

  • Multiple Lawful Basis Types: consent, contract, legal_obligation, vital_interests, public_task, legitimate_interests
  • Purpose-Specific Permissions: Granular permission grants with conditions
  • Cryptographic Proof Mechanisms: Verbal confirmation, signed documents, cryptographic signatures, external systems
  • Temporal Validity: Expiration dates and status intervals
  • Content Integrity: Hash validation and canonicalization
  • External Registry Integration: SCITT (Supply Chain Integrity, Transparency, and Trust) support

Core Classes

LawfulBasisAttachment

Main class representing a lawful basis attachment.

from vcon.extensions.lawful_basis import LawfulBasisAttachment, LawfulBasisType, PurposeGrant
from datetime import datetime, timezone, timedelta

# Create purpose grants
purpose_grants = [
    PurposeGrant(
        purpose="recording",
        granted=True,
        granted_at=datetime.now(timezone.utc).isoformat()
    ),
    PurposeGrant(
        purpose="analysis",
        granted=True,
        granted_at=datetime.now(timezone.utc).isoformat(),
        conditions=["anonymized_data_only"]
    )
]

# Create lawful basis attachment
attachment = LawfulBasisAttachment(
    lawful_basis=LawfulBasisType.CONSENT,
    expiration=(datetime.now(timezone.utc) + timedelta(days=365)).isoformat(),
    purpose_grants=purpose_grants
)
PurposeGrant

Represents a purpose-specific permission grant.

grant = PurposeGrant(
    purpose="recording",
    granted=True,
    granted_at=datetime.now(timezone.utc).isoformat(),
    conditions=["anonymized_data_only"]
)
ContentHash

Represents content integrity information.

from vcon.extensions.lawful_basis import ContentHash, HashAlgorithm, CanonicalizationMethod

content_hash = ContentHash(
    algorithm=HashAlgorithm.SHA_256,
    canonicalization=CanonicalizationMethod.JCS,
    value="computed_hash_value"
)
ProofMechanism

Represents a proof mechanism for lawful basis.

from vcon.extensions.lawful_basis import ProofMechanism, ProofType

proof = ProofMechanism(
    proof_type=ProofType.VERBAL_CONFIRMATION,
    timestamp=datetime.now(timezone.utc).isoformat(),
    proof_data={
        "dialog_reference": 0,
        "confirmation_text": "I consent to recording"
    }
)

Validation and Processing

LawfulBasisValidator

Validates lawful basis attachments and extension usage.

from vcon.extensions.lawful_basis import LawfulBasisValidator

validator = LawfulBasisValidator()
result = validator.validate_attachment(attachment_dict)
LawfulBasisProcessor

Processes lawful basis attachments and evaluates permissions.

from vcon.extensions.lawful_basis import LawfulBasisProcessor

processor = LawfulBasisProcessor()
result = processor.check_permission(vcon_dict, "recording", party_index=0)

Registry Integration

SCITTRegistryClient

Client for SCITT (Supply Chain Integrity, Transparency, and Trust) registries.

from vcon.extensions.lawful_basis import SCITTRegistryClient

client = SCITTRegistryClient("https://registry.example.com", auth_token="token")
receipt_id = client.submit_attestation(lawful_basis_attachment)

WTF Extension

The WTF (World Transcription Format) extension provides standardized representation of speech-to-text transcription data from multiple providers.

Key Features

  • Multi-Provider Support: Whisper, Deepgram, AssemblyAI, Google, Amazon, Azure, and more
  • Standardized Format: Hierarchical structure with transcripts, segments, words, and speakers
  • Quality Metrics: Audio quality assessment and confidence scoring
  • Export Capabilities: SRT and WebVTT subtitle formats
  • Provider Adapters: Automatic conversion from provider-specific formats
  • Analysis Tools: Keyword extraction, confidence analysis, and transcription comparison

Core Classes

WTFAttachment

Main class representing a WTF transcription attachment.

from vcon.extensions.wtf import WTFAttachment, Transcript, Segment, Metadata
from datetime import datetime, timezone

# Create transcript
transcript = Transcript(
    text="Hello world",
    language="en",
    duration=2.0,
    confidence=0.95
)

# Create segments
segments = [
    Segment(
        id=0,
        start=0.0,
        end=2.0,
        text="Hello world",
        confidence=0.95
    )
]

# Create metadata
metadata = Metadata(
    created_at=datetime.now(timezone.utc).isoformat(),
    processed_at=datetime.now(timezone.utc).isoformat(),
    provider="whisper",
    model="whisper-1"
)

# Create WTF attachment
attachment = WTFAttachment(
    transcript=transcript,
    segments=segments,
    metadata=metadata
)
Transcript

Represents high-level transcript information.

transcript = Transcript(
    text="Hello world",
    language="en",
    duration=2.0,
    confidence=0.95
)
Segment

Represents a logical chunk of transcribed content.

segment = Segment(
    id=0,
    start=0.0,
    end=2.0,
    text="Hello world",
    confidence=0.95,
    speaker=0
)
Word

Represents a single word in the transcription.

word = Word(
    id=0,
    start=0.0,
    end=1.0,
    text="Hello",
    confidence=0.95,
    speaker=0
)
Speaker

Represents speaker information for diarization.

speaker = Speaker(
    id=0,
    label="Speaker 1",
    segments=[0, 1, 2],
    total_time=10.5,
    confidence=0.9
)
Quality

Represents quality metrics for the transcription.

quality = Quality(
    audio_quality="high",
    background_noise=0.1,
    multiple_speakers=True,
    overlapping_speech=False,
    silence_ratio=0.2,
    average_confidence=0.95,
    low_confidence_words=5,
    processing_warnings=[]
)

Provider Adapters

WhisperAdapter

Converts Whisper transcription data to WTF format.

from vcon.extensions.wtf import WhisperAdapter

adapter = WhisperAdapter()
wtf_attachment = adapter.convert(whisper_data)
DeepgramAdapter

Converts Deepgram transcription data to WTF format.

from vcon.extensions.wtf import DeepgramAdapter

adapter = DeepgramAdapter()
wtf_attachment = adapter.convert(deepgram_data)
AssemblyAIAdapter

Converts AssemblyAI transcription data to WTF format.

from vcon.extensions.wtf import AssemblyAIAdapter

adapter = AssemblyAIAdapter()
wtf_attachment = adapter.convert(assemblyai_data)

Export Capabilities

SRT Export

Export transcription to SRT subtitle format.

srt_content = attachment.export_to_srt()
WebVTT Export

Export transcription to WebVTT format.

vtt_content = attachment.export_to_vtt()

Analysis Tools

Keyword Extraction

Extract keywords from high-confidence words.

keywords = attachment.extract_keywords(min_confidence=0.8)
Low Confidence Detection

Find segments with confidence below threshold.

low_confidence_segments = attachment.find_low_confidence_segments(threshold=0.5)
Speaking Time Calculation

Calculate speaking time for each speaker.

speaking_times = attachment.get_speaking_time()

Validation and Processing

WTFValidator

Validates WTF transcription attachments.

from vcon.extensions.wtf import WTFValidator

validator = WTFValidator()
result = validator.validate_attachment(attachment_dict)
WTFProcessor

Processes WTF transcription attachments and provides analysis.

from vcon.extensions.wtf import WTFProcessor

processor = WTFProcessor()
analysis = processor.analyze_transcription(attachment)

Constants

Property Handling Modes

PROPERTY_HANDLING_DEFAULT = "default"  # Keep non-standard properties
PROPERTY_HANDLING_STRICT = "strict"    # Remove non-standard properties
PROPERTY_HANDLING_META = "meta"        # Move non-standard properties to meta

Dialog Types

VALID_TYPES = ["recording", "text", "transfer", "incomplete", "audio", "video"]

Disposition Values

VALID_DISPOSITIONS = [
    "no-answer", "congestion", "failed", "busy", 
    "hung-up", "voicemail-no-message"
]

Party History Events

VALID_EVENTS = ["join", "drop", "hold", "unhold", "mute", "unmute"]

Attachment Encodings

VALID_ENCODINGS = ["base64", "base64url", "none"]

Supported MIME Types

MIME_TYPES = [
    "text/plain",
    "audio/x-wav", "audio/wav", "audio/wave", "audio/mpeg", "audio/mp3",
    "audio/x-mp3", "audio/x-mp4", "audio/ogg", "audio/webm", "audio/x-m4a", "audio/aac",
    "video/x-mp4", "video/ogg", "video/mp4", "video/quicktime", "video/webm",
    "video/x-msvideo", "video/x-matroska", "video/mpeg", "video/x-flv", "video/3gpp", "video/x-m4v",
    "multipart/mixed", "message/rfc822",
    "image/jpeg", "image/tiff", "application/pdf", "application/json"
]

Extension Types

from vcon.extensions.base import ExtensionType

ExtensionType.COMPATIBLE     # Safe to ignore, no breaking changes
ExtensionType.INCOMPATIBLE   # Must be supported, breaking changes
ExtensionType.EXPERIMENTAL   # Development/testing only

Lawful Basis Types

from vcon.extensions.lawful_basis import LawfulBasisType

LawfulBasisType.CONSENT              # Explicit consent
LawfulBasisType.CONTRACT             # Contractual necessity
LawfulBasisType.LEGAL_OBLIGATION     # Legal obligation
LawfulBasisType.VITAL_INTERESTS      # Vital interests
LawfulBasisType.PUBLIC_TASK          # Public task
LawfulBasisType.LEGITIMATE_INTERESTS # Legitimate interests

Proof Types

from vcon.extensions.lawful_basis import ProofType

ProofType.VERBAL_CONFIRMATION        # Verbal confirmation
ProofType.SIGNED_DOCUMENT           # Signed document
ProofType.CRYPTOGRAPHIC_SIGNATURE   # Cryptographic signature
ProofType.EXTERNAL_SYSTEM           # External system attestation

Hash Algorithms

from vcon.extensions.lawful_basis import HashAlgorithm

HashAlgorithm.SHA_256    # SHA-256
HashAlgorithm.SHA_384    # SHA-384
HashAlgorithm.SHA_512    # SHA-512

Canonicalization Methods

from vcon.extensions.lawful_basis import CanonicalizationMethod

CanonicalizationMethod.JCS    # JSON Canonicalization Scheme

WTF Provider Adapters

from vcon.extensions.wtf import (
    WhisperAdapter,      # OpenAI Whisper
    DeepgramAdapter,     # Deepgram
    AssemblyAIAdapter,   # AssemblyAI
    ProviderAdapter      # Base adapter class
)

Examples

Basic vCon Creation

from vcon import Vcon
from vcon.party import Party
from vcon.dialog import Dialog
from datetime import datetime

# Create new vCon
vcon = Vcon.build_new()

# Add parties
caller = Party(tel="+1234567890", name="Alice", role="caller")
agent = Party(tel="+1987654321", name="Bob", role="agent")
vcon.add_party(caller)
vcon.add_party(agent)

# Add dialog
dialog = Dialog(
    type="text",
    start=datetime.now(),
    parties=[0, 1],
    originator=0,
    body="Hello, I need help with my account."
)
vcon.add_dialog(dialog)

# Save to file
vcon.save_to_file("conversation.vcon.json")

Loading and Validation

# Load vCon
vcon = Vcon.load("conversation.vcon.json")

# Validate
is_valid, errors = vcon.is_valid()
if not is_valid:
    print("Validation errors:", errors)

# Access data
print(f"UUID: {vcon.uuid}")
print(f"Parties: {len(vcon.parties)}")
print(f"Dialogs: {len(vcon.dialog)}")

Digital Signatures

# Generate key pair
private_key, public_key = Vcon.generate_key_pair()

# Sign vCon
vcon.sign(private_key)

# Verify signature
is_valid = vcon.verify(public_key)
print(f"Signature valid: {is_valid}")

Extensions and Must-Support

# Add extensions
vcon.add_extension("video")
vcon.add_extension("encryption")

# Add must-support
vcon.add_critical("encryption")

print(f"Extensions: {vcon.get_extensions()}")
print(f"Critical: {vcon.get_critical()}")

Analysis and Attachments

# Add analysis
vcon.add_analysis(
    type="sentiment",
    dialog=[0, 1],
    vendor="SentimentAnalyzer",
    body={"sentiment": "positive", "confidence": 0.85},
    encoding="json"
)

# Add attachment
vcon.add_attachment(
    type="transcript",
    body="Full conversation transcript...",
    encoding="none"
)

# Add tags
vcon.add_tag("customer_id", "12345")
vcon.add_tag("priority", "high")

Video Content

# Add video dialog
video_dialog = Dialog(
    type="video",
    start=datetime.now(),
    parties=[0, 1],
    mediatype="video/mp4",
    resolution="1920x1080",
    frame_rate=30.0,
    codec="H.264"
)

# Add video data
video_dialog.add_video_data(
    video_data=binary_video_data,
    filename="recording.mp4",
    mediatype="video/mp4",
    inline=True
)

# Extract metadata
metadata = video_dialog.extract_video_metadata()

# Generate thumbnail
thumbnail = video_dialog.generate_thumbnail(timestamp=10.0)

vcon.add_dialog(video_dialog)

Civic Address

from vcon.civic_address import CivicAddress

# Create civic address
address = CivicAddress(
    country="US",
    a1="CA",
    a3="San Francisco",
    sts="Market Street",
    hno="123",
    pc="94102"
)

# Add to party
party = Party(
    name="Jane",
    tel="+1555123456",
    civicaddress=address
)

Party History

from vcon.party import PartyHistory

# Create party history
history = [
    PartyHistory(0, "join", datetime.now()),
    PartyHistory(1, "join", datetime.now()),
    PartyHistory(0, "hold", datetime.now()),
    PartyHistory(0, "unhold", datetime.now()),
    PartyHistory(1, "drop", datetime.now())
]

# Add to dialog
dialog = Dialog(
    type="recording",
    start=datetime.now(),
    parties=[0, 1],
    party_history=history
)

HTTP Operations

# Post vCon to server
response = vcon.post_to_url(
    "https://api.example.com/vcon",
    headers={
        "Authorization": "Bearer your-token",
        "Content-Type": "application/json"
    }
)

if response.status_code == 200:
    print("Successfully posted vCon")
else:
    print(f"Error: {response.status_code}")

Property Handling

# Strict mode - remove non-standard properties
vcon = Vcon.load("file.json", property_handling="strict")

# Meta mode - move non-standard properties to meta
vcon = Vcon.load("file.json", property_handling="meta")

# Default mode - keep all properties
vcon = Vcon.load("file.json", property_handling="default")

Lawful Basis Extension

from vcon import Vcon
from vcon.party import Party
from vcon.dialog import Dialog
from datetime import datetime, timezone, timedelta

# Create vCon with parties and dialog
vcon = Vcon.build_new()
caller = Party(tel="+1234567890", name="Alice", role="caller")
agent = Party(tel="+1987654321", name="Bob", role="agent")
vcon.add_party(caller)
vcon.add_party(agent)

# Add dialog
dialog = Dialog(
    type="recording",
    start=datetime.now(timezone.utc),
    parties=[0, 1],
    mediatype="audio/mp3"
)
vcon.add_dialog(dialog)

# Add lawful basis attachment
vcon.add_lawful_basis_attachment(
    lawful_basis="consent",
    expiration=(datetime.now(timezone.utc) + timedelta(days=365)).isoformat(),
    purpose_grants=[
        {
            "purpose": "recording",
            "granted": True,
            "granted_at": datetime.now(timezone.utc).isoformat()
        },
        {
            "purpose": "analysis",
            "granted": True,
            "granted_at": datetime.now(timezone.utc).isoformat(),
            "conditions": ["anonymized_data_only"]
        }
    ],
    party_index=0,
    dialog_index=0
)

# Check permissions
recording_permission = vcon.check_lawful_basis_permission("recording", party_index=0)
marketing_permission = vcon.check_lawful_basis_permission("marketing", party_index=0)

print(f"Recording permission: {recording_permission}")
print(f"Marketing permission: {marketing_permission}")

# Find lawful basis attachments
attachments = vcon.find_lawful_basis_attachments(party_index=0)
print(f"Found {len(attachments)} lawful basis attachments")

WTF Extension

from vcon import Vcon
from vcon.party import Party
from vcon.dialog import Dialog
from datetime import datetime, timezone

# Create vCon with parties and dialog
vcon = Vcon.build_new()
caller = Party(tel="+1234567890", name="Alice", role="caller")
agent = Party(tel="+1987654321", name="Bob", role="agent")
vcon.add_party(caller)
vcon.add_party(agent)

# Add dialog
dialog = Dialog(
    type="recording",
    start=datetime.now(timezone.utc),
    parties=[0, 1],
    mediatype="audio/mp3"
)
vcon.add_dialog(dialog)

# Add WTF transcription attachment
vcon.add_wtf_transcription_attachment(
    transcript={
        "text": "Hello, this is a test transcription.",
        "language": "en",
        "duration": 3.5,
        "confidence": 0.95
    },
    segments=[
        {
            "id": 0,
            "start": 0.0,
            "end": 1.5,
            "text": "Hello, this is",
            "confidence": 0.95,
            "speaker": 0
        },
        {
            "id": 1,
            "start": 1.5,
            "end": 3.5,
            "text": "a test transcription.",
            "confidence": 0.94,
            "speaker": 0
        }
    ],
    metadata={
        "created_at": datetime.now(timezone.utc).isoformat(),
        "processed_at": datetime.now(timezone.utc).isoformat(),
        "provider": "whisper",
        "model": "whisper-1",
        "audio_quality": "high",
        "background_noise": 0.1
    },
    party_index=0,
    dialog_index=0
)

# Find WTF attachments
attachments = vcon.find_wtf_attachments(party_index=0)
print(f"Found {len(attachments)} WTF attachments")

# Export to SRT format
if attachments:
    from vcon.extensions.wtf import WTFAttachment
    wtf_attachment = WTFAttachment.from_dict(attachments[0]["body"])
    srt_content = wtf_attachment.export_to_srt()
    print("SRT Export:")
    print(srt_content)

Extension Validation and Processing

# Validate all extensions
validation_results = vcon.validate_extensions()
print("Extension validation results:")
for extension, result in validation_results.items():
    if extension != "attachments":
        status = "✓ Valid" if result["is_valid"] else "✗ Invalid"
        print(f"  {extension}: {status}")
        if result["errors"]:
            for error in result["errors"]:
                print(f"    Error: {error}")
        if result["warnings"]:
            for warning in result["warnings"]:
                print(f"    Warning: {warning}")

# Process all extensions
processing_results = vcon.process_extensions()
print("Extension processing completed")

Provider Data Conversion

from vcon.extensions.wtf import WhisperAdapter, DeepgramAdapter

# Convert Whisper data to WTF format
whisper_data = {
    "text": "Hello world from Whisper",
    "segments": [
        {
            "start": 0.0,
            "end": 2.0,
            "text": "Hello world from Whisper"
        }
    ]
}

whisper_adapter = WhisperAdapter()
wtf_attachment = whisper_adapter.convert(whisper_data)

# Add to vCon
vcon.add_wtf_transcription_attachment(
    transcript=wtf_attachment.transcript.to_dict(),
    segments=[segment.to_dict() for segment in wtf_attachment.segments],
    metadata=wtf_attachment.metadata.to_dict()
)

Complete Extension Workflow

from vcon import Vcon
from vcon.party import Party
from vcon.dialog import Dialog
from datetime import datetime, timezone, timedelta

# Create comprehensive vCon with extensions
vcon = Vcon.build_new()

# Add parties
caller = Party(tel="+1234567890", name="Alice", role="caller")
agent = Party(tel="+1987654321", name="Bob", role="agent")
vcon.add_party(caller)
vcon.add_party(agent)

# Add dialog
dialog = Dialog(
    type="recording",
    start=datetime.now(timezone.utc),
    parties=[0, 1],
    mediatype="audio/mp3"
)
vcon.add_dialog(dialog)

# Add lawful basis for consent
vcon.add_lawful_basis_attachment(
    lawful_basis="consent",
    expiration=(datetime.now(timezone.utc) + timedelta(days=365)).isoformat(),
    purpose_grants=[
        {
            "purpose": "recording",
            "granted": True,
            "granted_at": datetime.now(timezone.utc).isoformat()
        },
        {
            "purpose": "transcription",
            "granted": True,
            "granted_at": datetime.now(timezone.utc).isoformat()
        }
    ],
    party_index=0
)

# Add transcription
vcon.add_wtf_transcription_attachment(
    transcript={
        "text": "Hello, I need help with my account.",
        "language": "en",
        "duration": 4.2,
        "confidence": 0.92
    },
    segments=[
        {
            "id": 0,
            "start": 0.0,
            "end": 4.2,
            "text": "Hello, I need help with my account.",
            "confidence": 0.92,
            "speaker": 0
        }
    ],
    metadata={
        "created_at": datetime.now(timezone.utc).isoformat(),
        "processed_at": datetime.now(timezone.utc).isoformat(),
        "provider": "whisper",
        "model": "whisper-1"
    },
    party_index=0,
    dialog_index=0
)

# Validate and process
validation_results = vcon.validate_extensions()
processing_results = vcon.process_extensions()

# Check permissions
can_record = vcon.check_lawful_basis_permission("recording", party_index=0)
can_transcribe = vcon.check_lawful_basis_permission("transcription", party_index=0)

print(f"Can record: {can_record}")
print(f"Can transcribe: {can_transcribe}")

# Save vCon
vcon.save_to_file("conversation_with_extensions.vcon.json")
print("Saved vCon with extensions")

This API reference covers all the main functionality of the vCon library, including the new extension framework. For more detailed examples and use cases, see the Quickstart Guide and the samples directory.