vcon package
Module contents
The package root re-exports the classes and functions most code needs.
- exception vcon.AlgorithmNotPermittedError[source]
Bases:
ValueErrorA JWS used
alg“none” (forbidden by core-05) or an unsupported algorithm.
- class vcon.Dialog(type: str, start: datetime | str, parties: List[int], mediatype: str | None = None, filename: str | None = None, body: str | None = None, encoding: str | None = None, url: str | None = None, disposition: str | None = None, campaign: str | None = None, interaction: str | None = None, skill: str | None = None, duration: float | None = None, meta: dict | None = None, metadata: Dict[str, Any] | None = None, signaling: Dict[str, Any] | None = None, resolution: str | None = None, frame_rate: float | None = None, codec: str | None = None, bitrate: int | None = None, thumbnail: str | None = None, session_id: Dict[str, str] | List[Dict[str, str]] | None = None, content_hash: str | None = None, application: str | None = None, message_id: str | None = None, redacted_segments: List[Dict[str, Any]] | None = None, **kwargs)[source]
Bases:
objectA class representing a dialog segment in a vCon conversation.
A dialog represents a piece of conversation content, which can be: - text: Text-based communication (email, chat, SMS) - recording: Audio/video recording of the conversation - incomplete: Failed or incomplete conversation setup
"audio"and"video"are accepted as deprecated aliases forrecording.Dialog content can be stored inline or referenced externally: - Inline: Content stored directly in the body field - External: Content referenced via URL with content_hash for integrity
Media support: - Audio formats: WAV, MP3, MP4, OGG, WebM, AAC - Video formats: MP4, WebM, AVI, MKV, MOV, FLV, 3GP - Text formats: Plain text, multipart messages - Images: JPEG, TIFF, PDF
Changes in vCon 0.5.0 (draft-ietf-vcon-vcon-core-05):
partieslists the contributors only. The receivers are in thepartiesof the Session Object that references the dialog.originatormoved to the Session Object.party_historywas replaced by Event Objects (vcon.event.Event).The
transferandrecording-setdialog types were removed. Transfers are Events; a recording set is a Session.An empty Dialog Object (
Dialog.placeholder(), serialized as{}) holds a position in the dialog array so that indices do not change.redacted_segmentswas added.
- 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']
- VALID_DISPOSITIONS = ['no-answer', 'congestion', 'failed', 'busy', 'hung-up', 'voicemail-no-message']
- VALID_TYPES = ['recording', 'text', 'incomplete', 'audio', 'video']
- __init__(type: str, start: datetime | str, parties: List[int], mediatype: str | None = None, filename: str | None = None, body: str | None = None, encoding: str | None = None, url: str | None = None, disposition: str | None = None, campaign: str | None = None, interaction: str | None = None, skill: str | None = None, duration: float | None = None, meta: dict | None = None, metadata: Dict[str, Any] | None = None, signaling: Dict[str, Any] | None = None, resolution: str | None = None, frame_rate: float | None = None, codec: str | None = None, bitrate: int | None = None, thumbnail: str | None = None, session_id: Dict[str, str] | List[Dict[str, str]] | None = None, content_hash: str | None = None, application: str | None = None, message_id: str | None = None, redacted_segments: List[Dict[str, Any]] | None = None, **kwargs) None[source]
Initialize a Dialog object. :param type: the type of the dialog (e.g. “text”, “recording”, “incomplete”, “video”) :type type: str :param start: the start time of the dialog :type start: datetime :param parties: the parties that contributed to the dialog (the receivers are in the Session Object) :type parties: List[int] :param mediatype: the MIME type of the dialog body :type mediatype: str or None :param filename: the filename of the dialog body :type filename: str or None :param body: the body of the dialog :type body: str or None :param encoding: the encoding of the dialog body :type encoding: str or None :param url: the URL of the dialog :type url: str or None :param disposition: the disposition of the dialog :type disposition: str or None :param campaign: the campaign that the dialog is associated with :type campaign: str or None :param interaction: the interaction that the dialog is associated with :type interaction: str or None :param skill: the skill that the dialog is associated with :type skill: str or None :param duration: the duration of the dialog :type duration: float or None :param meta: additional metadata for the dialog :type meta: dict or None :param metadata: structured metadata for the dialog (newer format) :type metadata: dict or None :param signaling: signaling-specific information :type signaling: dict or None :param resolution: video resolution (e.g., “1920x1080”) :type resolution: str or None :param frame_rate: video frame rate in fps :type frame_rate: float or None :param codec: video codec (e.g., “H.264”, “H.265”) :type codec: str or None :param bitrate: video bitrate in kbps :type bitrate: int or None :param thumbnail: base64-encoded thumbnail image :type thumbnail: str or None :param session_id: Session identifier :type session_id: str or None :param content_hash: Hash for externally referenced files (replaces alg and signature) :type content_hash: str or None :param application: Application identifier for the dialog :type application: str or None :param message_id: Message identifier for email/text dialogs :type message_id: str or None :param redacted_segments: Redacted_segments Objects (start, end, optional parties) :type redacted_segments: list or None :param kwargs: Additional attributes to be set on the dialog
- add_external_data(url: str, filename: str, mediatype: str) None[source]
Add external data to the dialog.
- Parameters:
url (str) – the URL of the external data
- Returns:
None
- Return type:
None
- add_image_data(image_path: str, mediatype: str | None = None) None[source]
Add image data to the dialog from a local file.
- Parameters:
image_path (str) – Path to the image file
mediatype (str or None) – MIME type of the image (optional, auto-detected if not provided)
- Returns:
None
- Return type:
None
- add_inline_data(body: str | bytes, filename: str, mediatype: str) None[source]
Add inline data to the dialog.
The Dialog is written with
encoding: "base64url". Pass rawbytesand they are encoded; astris taken to be base64url already. Thecontent_hashis over the decoded content.- Parameters:
body (bytes or str) – the content as bytes, or as a base64url string
filename (str) – the filename of the inline data
mediatype (str) – the mediatype of the inline data
- Returns:
None
- Return type:
None
- add_streaming_video_reference(reference_id, mediatype, metadata=None) None[source]
Add a reference to a streamable video.
- Parameters:
reference_id – Unique identifier for the streamable video
mediatype – MIME type of the video
metadata – Optional video metadata
- Returns:
None
- add_video_data(video_data, filename=None, mediatype=None, inline=True, metadata=None) None[source]
Add video data to the dialog.
- Parameters:
video_data – Binary video data or URL to video
filename – Name of the video file
mediatype – MIME type of the video, or auto-detected from filename if None
inline – Whether to include the video as inline content (True) or external reference (False)
metadata – Optional video metadata to include
- Returns:
None
- add_video_with_optimal_storage(video_data, filename, mediatype=None, size_threshold_mb=10) None[source]
Add video with the optimal storage method based on size.
- Parameters:
video_data – Binary video data or URL
filename – Name of the video file
mediatype – MIME type of the video (optional)
size_threshold_mb – Size threshold in MB for inline vs external storage
- Returns:
None
- calculate_content_hash(algorithm: str = 'sha512') str[source]
Calculate the content hash for the dialog body.
The hash covers the content itself: for a
base64urlbody that is the decoded bytes, so the value matches a hash of the original file (whatadd_image_data()stores). Other bodies are hashed as UTF-8.The returned value is spec-formatted as
"<algorithm>-<base64url>"with no base64 padding (draft-ietf-vcon-vcon-core-02), e.g."sha512-GLy6IPa...".- Parameters:
algorithm (str) – The hash algorithm to use (default:
"sha512")."sha256"is also supported for backwards compatibility.- Returns:
The calculated hash value, prefixed with the algorithm name
- Return type:
str
- Raises:
ValueError – if there is no body to hash, or
algorithmis not a supported algorithm
- extract_image_metadata(image_data: bytes, mediatype: str) None[source]
Extract metadata from image data and add it to the dialog metadata.
- Parameters:
image_data (bytes) – Raw image data
mediatype (str) – MIME type of the image
- Returns:
None
- Return type:
None
- extract_video_metadata(video_path=None) dict[source]
Extract comprehensive metadata from video content using FFmpeg.
- Parameters:
video_path – Optional path to video file. If None, uses the dialog’s content.
- Returns:
Dictionary containing detailed video metadata
- generate_image_thumbnail(max_size: Tuple[int, int] = (200, 200)) str | None[source]
Generate a thumbnail for the image and return it as a base64-encoded string.
- Parameters:
max_size (Tuple[int, int]) – Maximum thumbnail dimensions (width, height)
- Returns:
Base64-encoded thumbnail or None if generation fails
- Return type:
str or None
- generate_thumbnail(*args, **kwargs)[source]
Generate a thumbnail for an image or a video Dialog.
For an image this calls
generate_image_thumbnail()(max_size, returns a base64url string or None). For a video it callsgenerate_video_thumbnail()(timestamp,width,height,quality; returns JPEG bytes).
- generate_video_thumbnail(timestamp=0.0, width=320, height=240, quality=90) bytes[source]
Generate a high-quality thumbnail from the video at the specified timestamp.
- Parameters:
timestamp – Time in seconds at which to extract the thumbnail frame
width – Desired width of the thumbnail in pixels
height – Desired height of the thumbnail in pixels
quality – JPEG quality (1-100)
- Returns:
Binary thumbnail data in JPEG format
- get_content_hash() str | None[source]
Get the content hash for externally referenced files.
- Returns:
The content hash if set, None otherwise
- Return type:
str or None
- get_session_id() Dict[str, str] | List[Dict[str, str]] | None[source]
Get the session identifier for this dialog.
- Returns:
The session identifier if set, None otherwise
- Return type:
str or None
- get_video_format_from_mediatype(mediatype: str | None = None) str[source]
Get the video format name from a MIME type.
- Parameters:
mediatype – MIME type of the video (default: this Dialog’s mediatype)
- Returns:
Format name (mp4, mov, etc.)
- has_thumbnail() bool[source]
Check if the video has a thumbnail.
- Returns:
True if the video has a thumbnail, False otherwise
- is_audio() bool[source]
Check if the dialog has audio content. :return: True if the dialog has audio content, False otherwise :rtype: bool
- is_email() bool[source]
Check if the dialog is an email dialog. :return: True if the dialog is an email dialog, False otherwise :rtype: bool
- is_external_data() bool[source]
Check if the dialog is an external data dialog.
- Returns:
True if the dialog is an external data dialog, False otherwise
- Return type:
bool
- is_external_data_changed() bool[source]
Check to see if it’s an external data dialog and verify the content hash.
- Returns:
True if the dialog is an external data dialog and the contents are valid, False otherwise
- Return type:
bool
- is_image() bool[source]
Check if the dialog has image content.
- Returns:
True if the dialog has image content, False otherwise
- Return type:
bool
- is_incomplete() bool[source]
Check if the dialog is an incomplete dialog. :return: True if the dialog is an incomplete dialog, False otherwise :rtype: bool
- is_inline_data() bool[source]
Check if the dialog is an inline data dialog.
- Returns:
True if the dialog is an inline data dialog, False otherwise
- Return type:
bool
- is_pdf() bool[source]
Check if the dialog has PDF content.
- Returns:
True if the dialog has PDF content, False otherwise
- Return type:
bool
- is_placeholder() bool[source]
Check if the dialog is an empty placeholder Dialog Object (
{}).
- is_recording() bool[source]
Check if the dialog is a recording dialog. :return: True if the dialog is a recording dialog, False otherwise :rtype: bool
- is_text() bool[source]
Check if the dialog is a text dialog. :return: True if the dialog is a text dialog, False otherwise :rtype: bool
- is_transfer() bool[source]
Deprecated: core-05 has no transfer Dialog type, so this is always False.
- is_video(content_type=None) bool[source]
Check if the dialog has video content.
- Parameters:
content_type – Optional content type to check. If None, use the dialog’s mediatype.
- Returns:
True if the content is a video format, False otherwise
- classmethod placeholder() Dialog[source]
Create an empty Dialog Object (core-05 section 4.5.1).
It has no parameters and no meaning; it holds a position in the dialog array so that the indices of the other Dialog Objects, and the references to them, do not change. It serializes as
{}.
- set_content_hash(content_hash: str) None[source]
Set the content hash for externally referenced files.
- Parameters:
content_hash (str) – The content hash value
- Returns:
None
- Return type:
None
- set_session_id(session_id: Dict[str, str] | List[Dict[str, str]]) None[source]
Set the session identifier for this dialog.
- Parameters:
session_id (dict or list) – The session identifier (SessionId or list of SessionId)
- Returns:
None
- Return type:
None
- to_dict()[source]
Returns a dictionary representation of the Dialog object.
- Returns:
a dictionary containing all non-None Dialog object attributes
- Return type:
dict
- to_inline_data() None[source]
Convert the dialog from an external data dialog to an inline data dialog by reading the contents from the URL then adding the contents to the body.
- Returns:
None
- Return type:
None
- transcode_video(target_format, codec=None, bit_rate=None, width=None, height=None) None[source]
Transcode the video to a different format or with different encoding parameters.
- Parameters:
target_format – Target video format (mp4, webm, etc.)
codec – Video codec to use (h264, vp9, etc.)
bit_rate – Target bitrate in bits per second
width – Target width (if resizing)
height – Target height (if resizing)
- Returns:
None - updates the dialog’s content in place
- verify_content_hash(expected_hash: str, algorithm: str | None = None) bool[source]
Verify the content hash against the expected value.
The algorithm is inferred from the
expected_hashprefix ("sha512-"or"sha256-") so values produced by either this or older releases of the library verify correctly. A legacy unprefixed hash is treated as the padded base64url SHA-256 that vcon-lib emitted prior to the algorithm-prefixed format.- Parameters:
expected_hash (str) – The expected hash value
algorithm (str or None) – Optional explicit algorithm override; when omitted the algorithm is taken from the
expected_hashprefix
- Returns:
True if the hash matches, False otherwise
- Return type:
bool
- class vcon.Event(type: str, time: datetime | str, sessions: int | List[int] | None = None, party: int | None = None, dialog: int | List[int] | None = None, channel: int | None = None, contributors: int | List[int] | None = None, button: str | None = None, transferee: int | None = None, transfer_target: int | None = None, consultation: int | None = None, target_session: int | None = None, validate: bool = True, **extra: Any)[source]
Bases:
objectAn Event Object (core-05 section 4.3).
- Parameters:
type – Event type token, for example
"join"or"blind-transfer".time – When the event occurred (
datetimeor ISO 8601 string).sessions – Session index or list of indices (not for channel-contributors).
party – Party index (not for channel-contributors).
dialog – Dialog index (channel-contributors; SHOULD NOT be used otherwise).
channel – Channel index (channel-contributors only).
contributors – Party index, list of indices, or
None(channel-contributors only).button – DTMF digit or key label (keydown and keyup only).
transferee – Party indices (transfer types).
transfer_target – Party indices (transfer types).
consultation – Session indices (transfer types).
target_session – Session indices (transfer types).
validate – Apply the parameter applicability table and raise
ValueErroron anM/Xviolation (default True).**extra – Parameters defined by a vCon extension.
- to_dict() Dict[str, Any][source]
Serialize, omitting parameters that are
None.
- exception vcon.MigrationError[source]
Bases:
ValueErrorThe vCon cannot be migrated (or, in strict mode, a MUST field has no source).
- class vcon.MigrationReport(source_version: str | None = None, target_version: str = '0.5.0', strict: bool = False, resign_required: bool = False, entries: ~typing.List[~vcon.migration.ReportEntry] = <factory>, removed_dialogs: ~typing.Dict[int, ~typing.Dict[str, ~typing.Any]] = <factory>, steps_run: ~typing.List[str] = <factory>)[source]
Bases:
objectWhat a migration did that the draft did not dictate.
- add(step: str, kind: str, message: str, code: str | None = None, **details: Any) None[source]
- entries: List[ReportEntry]
- property fallbacks: List[ReportEntry]
- property inferred: List[ReportEntry]
- property notes: List[ReportEntry]
- removed_dialogs: Dict[int, Dict[str, Any]]
Original content of every Dialog replaced by
{}, keyed by its (unchanged) index.
- resign_required: bool = False
the signature is dropped and the result is unsigned.
- Type:
True when the input was signed
- source_version: str | None = None
- steps_run: List[str]
Steps that ran, in order.
- strict: bool = False
- summary() str[source]
- target_version: str = '0.5.0'
- to_dict() Dict[str, Any][source]
- property unresolved: List[ReportEntry]
- class vcon.MigrationResult(vcon: Dict[str, Any], report: MigrationReport)[source]
Bases:
NamedTupleResult of a migration. Unpacks as
(vcon, report).- report: MigrationReport
Alias for field number 1
- vcon: Dict[str, Any]
Alias for field number 0
- class vcon.Session(start: str | datetime | None = None, duration: int | float | None = None, parties: List[int] | None = None, originator: int | None = None, session_id: Dict[str, str] | None = None, sessions: List[SessionReference | Dict[str, Any]] | None = None, dialog: List[int] | None = None)[source]
Bases:
objectA Session Object.
- Parameters:
start – Session start (
datetimeor ISO 8601 string). SHOULD be present.duration – Session duration in seconds. Absent means the session has no end.
parties – Indices of the receivers. The first one is the implied originator.
originator – Index of the originator, only when it is not the first party.
session_id – A SessionId Object (
{"local": ..., "remote": ...}).sessions – Relationships to other Sessions (
SessionReferenceor dicts).dialog – Indices of the Dialog Objects that are part of the session.
- to_dict() Dict[str, Any][source]
Serialize, omitting parameters that are
None. An empty Session is{}.
- class vcon.SessionReference(session: int, type: str, description: str | None = None)[source]
Bases:
objectSession_Reference Object: how another Session relates to this one.
- to_dict() Dict[str, Any][source]
- class vcon.Vcon(vcon_dict: Dict[str, Any] = None, property_handling: str = 'default', migrate_legacy: bool = True, strict_migration: bool = False)[source]
Bases:
objectA class representing a vCon (Virtual Conversation) object according to the vCon specification.
A vCon is a standardized format for representing conversations and related metadata. It includes information about participants (parties), dialog content, attachments, and analysis data.
The vCon format supports features such as:
Unique identification via UUID
The
vconsyntax version (written as"0.5.0")Timestamps for creation and updates
Party information with contact details (tel, name, sip, did, jCard, timezone)
Dialog content with media types and session information
Attachments for ancillary documents
Analysis data for conversation insights
Digital signatures and encryption
Extensions and critical for extensibility
Civic address information for location data
Sessions (
sessions) grouping dialog and events, and Events (events) for joins, drops, holds, key presses and transfers
New in vCon 0.5.0 (draft-ietf-vcon-vcon-core-05):
sessionsandeventsarrays;SessionandEventclassesredacted_fromandamended_fromreplaceredactedandamendedAttachments need
partyanddialogorsessionextensionsMUST list every extension in use;alg: "none"is rejectedDialog
partiesare contributors only; empty{}Dialog placeholders0.4.0 input is migrated on load (see
migrate_0_4_0_to_0_5_0)
- vcon_dict
The underlying dictionary containing all vCon data
- Type:
Dict
- property_handling
How non-standard properties are handled
- Type:
str
- WTF_SCHEMA_URL = 'https://datatracker.ietf.org/doc/html/draft-howe-vcon-wtf-extension'
- __init__(vcon_dict: Dict[str, Any] = None, property_handling: str = 'default', migrate_legacy: bool = True, strict_migration: bool = False) None[source]
Initialize a Vcon object from a dictionary.
A dict that declares
"vcon": "0.4.0"is migrated to 0.5.0 here, usingmigrate_0_4_0_to_0_5_0. The report is kept inself.migration_report. A signed vCon whose payload is 0.4.0 is NOT migrated on load, because migrating drops the signature: verify it, then callVcon.migrate_0_4_0_to_0_5_0(). An unmigrated 0.4.0 dict (signed, ormigrate_legacy=False) is kept as is;property_handlingis not applied to it. A dict with any other (or no)vconvalue is taken as is.- Parameters:
vcon_dict – A dictionary representing a vCon. Defaults to an empty dict.
property_handling – How to handle non-standard properties. Options are: - “default”: Keep non-standard properties (default) - “strict”: Remove non-standard properties - “meta”: Move non-standard properties to meta object
migrate_legacy – Migrate 0.4.0 input to 0.5.0 (default True). When False the 0.4.0 dict is kept untouched and
is_valid()will report it as not 0.5.0.strict_migration – Passed to the migration as
strict; raisesMigrationErrorwhen a required field has no source.
Example
>>> vcon = Vcon({"uuid": "123", "custom_field": "value"})
>>> strict_vcon = Vcon({"uuid": "123", "custom_field": "value"}, property_handling="strict") >>> meta_vcon = Vcon({"uuid": "123", "custom_field": "value"}, property_handling="meta")
- add_analysis(*, type: str, vendor: str, body: Dict[str, Any] | List[Any] | str, dialog: int | List[int] | None = None, sessions: int | List[int] | None = None, attachment: int | List[int] | None = None, analysis: int | List[int] | None = None, encoding: str = 'none', mediatype: str | None = None, filename: str | None = None, product: str | None = None, url: str | None = None, content_hash: str | None = None, schema: Dict[str, Any] | None = None, meta: Dict[str, Any] | None = None, **extra) None[source]
Add analysis data to the vCon.
This method adds analysis data with the specified parameters to the vCon’s analysis list. Analysis data can be associated with one or more dialog entries and includes metadata about the vendor who performed the analysis.
- Parameters:
type – The type of analysis
dialog – Index or list of indices of the associated dialog entries (optional)
sessions – Index or list of indices of the Sessions analysed (optional)
attachment – Index or list of indices of the attachments analysed (optional)
analysis – Index or list of indices of other Analysis Objects used (optional)
vendor – The name of the vendor who performed the analysis
body – The analysis data
encoding – The encoding format of the body (default: “none”)
mediatype – Optional media type of the analysis content
filename – Optional filename for the analysis content
product – Optional product name of the vendor
url – Optional URL for external analysis content
content_hash – Optional content hash for external analysis content
schema – Optional schema information about the analysis (default: None)
meta – Optional metadata about the analysis (default: None)
**extra – Additional key-value pairs to include in the analysis
- Raises:
Exception – If the encoding is invalid or if the body format is invalid for the specified encoding
Example
>>> vcon = Vcon.build_new() >>> vcon.add_analysis( ... type="sentiment", ... dialog=[0], ... vendor="acme", ... body={"score": 0.8}, ... encoding="json", ... schema={"version": "1.0"}, ... meta={"confidence": "high"} ... )
- add_attachment(purpose: str, body: Any = None, encoding: str = 'none', mediatype: str | None = None, filename: str | None = None, url: str | None = None, content_hash: str | None = None, start: str | None = None, party: int | None = None, dialog: int | None = None, session: int | List[int] | None = None) Attachment[source]
Add an attachment to the vCon.
This method creates a new attachment with the specified type, body, and encoding and adds it to the vCon’s attachments list.
Core-05 needs
partyplusdialogorsession.partydefaults to 0. If neitherdialognorsessionis given, the attachment is scoped to the only Session when the vCon has exactly one; otherwiseValueErroris raised rather than inventing a scope.- Parameters:
purpose – The purpose of the attachment
body – The content of the attachment
encoding – The encoding format for the body (default: “none”)
mediatype – Optional media type of the attachment
filename – Optional file name of the attachment
url – Optional URL for external attachments
content_hash – Optional content hash for external attachments
start – Optional timestamp for the attachment
party – Optional party index (default 0)
dialog – Optional dialog index
session – Optional Session index or list of indices
- Returns:
The created Attachment object
- Raises:
ValueError – If the specified encoding is not supported
Example
>>> vcon = Vcon.build_new() >>> vcon.add_party(Party(name="Alice")) >>> vcon.add_session() >>> attachment = vcon.add_attachment("metadata", {"version": "1.0"}, "json") >>> print(attachment.purpose) # Prints "metadata"
- add_critical(extension: str) None[source]
Add an extension to the critical list.
- Parameters:
extension – The name of the extension that must be supported
Example
>>> vcon = Vcon.build_new() >>> vcon.add_critical("encryption") >>> vcon.add_critical("video")
- add_dialog(dialog: Dialog, session: int | None = None) int[source]
Add a dialog entry to the vCon.
This method adds a Dialog object to the vCon’s dialog list. A dialog entry represents a segment of the conversation with its associated metadata. Use
Dialog.placeholder()to add an empty Dialog Object ({}) that holds an array position.- Parameters:
dialog – The Dialog object to add
session – Optional index of an existing Session; the new Dialog’s index is appended to that Session’s
dialoglist. Core-05 requires at least one Session when the vCon has Dialogs, so add Sessions withadd_session().
- Returns:
The index of the new Dialog in the
dialogarray.
Example
>>> vcon = Vcon.build_new() >>> dialog = Dialog(type="text", start="2023-01-01T00:00:00Z", parties=[0]) >>> index = vcon.add_dialog(dialog)
- add_event(event: Event | Dict[str, Any]) int[source]
Add an Event Object and return its index in the
eventsarray.An
Eventis checked against the per-type parameter table when it is built; a plain dict is checked byis_valid().Example
>>> vcon = Vcon.build_new() >>> vcon.add_event(Event(type="join", time="2023-01-01T00:00:00Z", sessions=0, party=0))
- add_extension(extension: str) None[source]
Add an extension to the vCon.
- Parameters:
extension – The name of the extension to add
Example
>>> vcon = Vcon.build_new() >>> vcon.add_extension("video") >>> vcon.add_extension("encryption")
- add_image(image_path: str, purpose: str = 'image', party: int | None = None, dialog: int | None = None, session: int | List[int] | None = None) Attachment[source]
Add an image attachment to the vCon.
This method creates a new attachment with the specified image and adds it to the vCon’s attachments list.
- Parameters:
image_path – Path to the image file
purpose – The purpose of the attachment (default: “image”)
party – Party index (default 0)
dialog – Dialog index
session – Session index or list of indices. With neither
dialognorsession, the only Session is used when the vCon has exactly one, as inadd_attachment().
- Returns:
The created Attachment object
- Raises:
FileNotFoundError – If the image file cannot be found
ValueError – If the image format is not supported, or no
dialog/sessionis given and the vCon does not have exactly one Session
Example
>>> vcon = Vcon.build_new() >>> vcon.add_session() >>> attachment = vcon.add_image("document.pdf", "identification") >>> print(attachment.mediatype) # Prints "application/pdf"
- add_incomplete_dialog(start: str | datetime, disposition: str, details: Dict[str, Any] | None = None, parties: List[int] = None, metadata: Dict[str, Any] | None = None, session: int | None = None) int[source]
Add an incomplete dialog entry to the vCon.
This method creates a dialog entry of type “incomplete” for conversations that failed to be set up. Under core-05 an incomplete Dialog has no content (no body, mediatype, filename, encoding, url or content_hash), and its
partiesis the party that attempted the call, the originator.detailsis kept undermetadata["details"].- Parameters:
start – When the attempt occurred (ISO 8601 string or datetime)
disposition – Reason for the incomplete conversation (for example “no-answer”)
details – Additional details about the failure (optional)
parties – The party (or parties) that attempted the conversation (optional)
metadata – Additional metadata (optional)
session – Optional Session index to add the Dialog to
- Returns:
The index of the new Dialog.
Example
>>> vcon = Vcon.build_new() >>> vcon.add_incomplete_dialog( ... start="2023-01-20T14:00:00Z", ... disposition="no-answer", ... details={"ringDuration": 45000}, ... parties=[0] ... )
- add_lawful_basis_attachment(lawful_basis: str, expiration: str, purpose_grants: list, party_index: int | None = None, dialog_index: int | None = None, session_index: int | List[int] | None = None, **kwargs) None[source]
Add a lawful basis attachment to the vCon.
The attachment has
purpose"lawful_basis". Under core-05 it is scoped withpartyplussession: passsession_index(andparty_index, the party that records the basis). The scope is never widened or invented:dialog_indexalone gives a dialog-only scope (a warning is logged, because 0.5.0 scopes a basis to Sessions), and with neither index the only Session is used when the vCon has exactly one; otherwiseValueErroris raised.partydefaults to 0 with a warning. Thelawful_basisextension name is added toextensions.- Parameters:
lawful_basis – The lawful basis type (consent, contract, etc.)
expiration – ISO 8601 timestamp when the lawful basis expires
purpose_grants – List of purpose grant dictionaries
party_index – Index of the party that records the basis (default 0)
dialog_index – Index of the dialog this applies to (optional)
session_index – Session index or list of indices this applies to (optional)
**kwargs – Additional lawful basis parameters
Example
>>> vcon = Vcon.build_new() >>> vcon.add_party(Party(name="Alice")) >>> vcon.add_session() >>> 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"} ... ] ... )
- add_party(party: Party) None[source]
Add a party to the vCon.
This method adds a party object to the vCon’s parties list. A party represents a participant in the conversation.
- Parameters:
party – The Party object to add
Example
>>> vcon = Vcon.build_new() >>> party = Party(type="person", name="John Doe") >>> vcon.add_party(party)
- add_session(session: Session | Dict[str, Any] | None = None) int[source]
Add a Session Object and return its index in the
sessionsarray.With no argument an empty placeholder Session (
{}) is added, which core-05 permits.Example
>>> vcon = Vcon.build_new() >>> s = vcon.add_session(Session(start="2023-01-01T00:00:00Z", parties=[0, 1]))
- add_tag(tag_name: str, tag_value: str, party: int | None = None) None[source]
Add a tag to the vCon.
This method adds a tag with the specified name and value to the vCon’s tags attachment. If no tags attachment exists, it creates one.
Core-05 requires the attachment’s
partyto be a valid party index (the party that adds the tags). It defaults to 0. On a vCon with no parties this still writes party 0 but warns (DeprecationWarning), because the result failsis_valid(); from vcon 1.1 it will raise.- Parameters:
tag_name – The name of the tag
tag_value – The value to associate with the tag
party – Party index for a new tags attachment (default 0)
- Raises:
ValueError – If
partyis given (or the vCon has parties) and it is not a valid party index
Example
>>> vcon = Vcon.build_new() >>> vcon.add_party(Party(name="Acme Corp")) >>> vcon.add_tag("category", "meeting") >>> vcon.add_tag("priority", "high")
- add_transfer_dialog(*args: Any, **kwargs: Any) None[source]
Removed: core-05 has no transfer Dialog type.
Raises
NotImplementedErrorwith the replacement: a transfer is one or two transfer Events (blind-transfer,consultation-startplusconsultative-transfer, ortransfer-abandoned) added withadd_event(Event(...)), whosesessions/consultation/target_sessionreference Sessions for the calls involved.
- add_wtf_transcription_analysis(transcript: Dict[str, Any], segments: List[Dict[str, Any]], metadata: Dict[str, Any], dialog_index: int | None = None, session_index: int | List[int] | None = None, **kwargs) None[source]
Add a WTF transcription as an analysis entry (vs. an attachment).
This is the placement draft-howe-vcon-wtf-extension requires (section 6.1: transcription results MUST be stored as analysis).
add_wtf_transcription_attachmentwrites to attachments[] and is deprecated.Emits the analysis entry defined by draft-howe-vcon-wtf-extension (section 5.3):
type="wtf_transcription",vendorandproducttaken frommetadata["provider"]/metadata["model"],schemaset to the WTF draft URL,encoding="json", andbodyas the WTF document itself (a JSON value, not a serialized string).- Parameters:
transcript – Transcript information dictionary
segments – List of segment dictionaries
metadata – Metadata dictionary;
providerandmodelkeys map tovendorandproducton the analysis entrydialog_index – Index of the dialog this transcription applies to
session_index – Session index or indices this transcription applies to
**kwargs – Additional WTF parameters (words, speakers, quality, etc.)
- add_wtf_transcription_attachment(transcript: Dict[str, Any], segments: List[Dict[str, Any]], metadata: Dict[str, Any], party_index: int | None = None, dialog_index: int | None = None, session_index: int | List[int] | None = None, **kwargs) None[source]
Add a WTF transcription attachment to the vCon.
Deprecated: draft-howe-vcon-wtf-extension stores transcriptions as analysis (section 6.1). Use
add_wtf_transcription_analysis().Scoped by
dialog_indexand/orsession_indexas given; with neither, the only Session when the vCon has exactly one, elseValueError(seeadd_attachment).- Parameters:
transcript – Transcript information dictionary
segments – List of segment dictionaries
metadata – Metadata dictionary
party_index – Index of the party this applies to (optional)
dialog_index – Index of the dialog this applies to (optional)
session_index – Session index or list of indices (optional)
**kwargs – Additional WTF parameters
Example
>>> vcon = Vcon.build_new() >>> vcon.add_party(Party(name="Alice")) >>> vcon.add_session() >>> 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", "processed_at": "2025-01-01T00:00:01Z", ... "provider": "whisper", "model": "whisper-1"} ... )
- property amended
Deprecated 0.4.0 name; returns
amended_from.
- property amended_from
- property analysis: List[Dict[str, Any]]
Get the list of analysis entries in the vCon.
- Returns:
A list of analysis dictionaries
Example
>>> vcon = Vcon.build_new() >>> vcon.add_analysis(type="sentiment", dialog=[0], vendor="acme", body={"score": 0.8}) >>> analysis = vcon.analysis >>> print(analysis[0]["type"]) # Prints "sentiment"
- property attachments: List[Dict[str, Any]]
Get the list of attachments in the vCon.
- Returns:
A list of attachment dictionaries
Example
>>> vcon = Vcon.build_new() >>> vcon.add_party(Party(name="Alice")) >>> vcon.add_session() >>> vcon.add_attachment("metadata", {"version": "1.0"}) >>> attachments = vcon.attachments >>> print(attachments[0]["purpose"]) # Prints "metadata"
- classmethod build_from_json(json_string: str, property_handling: str = 'default', migrate_legacy: bool = True, strict_migration: bool = False) Vcon[source]
Initialize a Vcon object from a JSON string.
This method parses a JSON string representation of a vCon and creates a new Vcon object from it.
- Parameters:
json_string – A JSON string representing a vCon
property_handling – How to handle non-standard properties.
- Returns:
A new Vcon object initialized with the parsed JSON data
- Raises:
json.JSONDecodeError – If the JSON string is invalid
Example
>>> json_str = '{"uuid": "123"}' >>> vcon = Vcon.build_from_json(json_str)
- classmethod build_new(created_at: str | datetime = None, property_handling: str = 'default') Vcon[source]
Initialize a new Vcon object with default values.
This method creates a new vCon with a generated UUID and initialized with empty arrays for groups, parties, dialog, attachments, and analysis.
- Parameters:
created_at (Union[str, datetime], optional) – The timestamp to set for creation, either as a string in ISO format or as a datetime object. Defaults to current time.
property_handling – How to handle non-standard properties.
- Returns:
A new Vcon object with default values
Example
>>> vcon = Vcon.build_new() >>> print(vcon.uuid) # Prints a new UUID8
- check_lawful_basis_permission(purpose: str, party_index: int | None = None) bool[source]
Check if permission is granted for a specific purpose.
- Parameters:
purpose – The purpose to check permission for
party_index – Index of the party to check (optional)
- Returns:
True if permission is granted, False otherwise
- property created_at
- static decoded_body(entry: Dict[str, Any] | None) Any[source]
Return the decoded
bodyof an attachment, analysis, or dialog entry.Under
draft-ietf-vcon-vcon-core-04, a"json"-encoded body is the JSON value itself, not ajson.dumpsstring. This accepts both that shape and the JSON-string bodies written under -02 conventions (or by this library prior to 0.10.0), so callers don’t need to special-case legacy vCons.- Parameters:
entry – An attachment, analysis, or dialog dictionary
- Returns:
The decoded body, or None if there is no body
Example
>>> vcon = Vcon.build_new() >>> vcon.add_party(Party(name="Alice")) >>> vcon.add_session() >>> vcon.add_tag("category", "meeting") >>> Vcon.decoded_body(vcon.tags) # ["category:meeting"]
- property dialog: List[Dict[str, Any]]
Get the list of dialog entries in the vCon.
- Returns:
A list of dialog dictionaries representing the conversation content. These are mutable references to the internal data structure, allowing in-place modifications.
Example
>>> vcon = Vcon.build_new() >>> vcon.add_dialog(Dialog(type="text", start="2023-01-01T00:00:00Z", parties=[0])) >>> dialog = vcon.dialog >>> print(dialog[0]["type"]) # Prints "text" >>> dialog[0]["body"] = "Modified content" # In-place modification works >>> print(vcon.dialog[0]["body"]) # Prints "Modified content"
- dumps() str[source]
Alias for to_json().
This method is an alias for to_json() and converts the vCon object to a JSON string representation.
- Returns:
A JSON string representation of the vCon
Example
>>> vcon = Vcon.build_new() >>> json_str = vcon.dumps() >>> print(type(json_str)) # Prints "<class 'str'>"
- property events: List[Dict[str, Any]]
The
eventsarray (Event Objects).
- find_analysis_by_type(type: str) Dict[str, Any] | None[source]
Find an analysis entry in the vCon by its type.
This method searches through the vCon’s analysis entries and returns the first one matching the specified type.
- Parameters:
type – The type of analysis to find
- Returns:
The matching analysis dictionary if found, None otherwise
Example
>>> vcon = Vcon.build_new() >>> vcon.add_analysis(type="sentiment", dialog=[0], vendor="acme", body={"score": 0.8}) >>> sentiment = vcon.find_analysis_by_type("sentiment")
- find_attachment_by_purpose(purpose: str) Dict[str, Any] | None[source]
Find an attachment in the vCon by its purpose.
This method searches through the vCon’s attachments and returns the first attachment matching the specified type.
- Parameters:
purpose – The purpose of attachment to find
- Returns:
The matching attachment dictionary if found, None otherwise
Example
>>> vcon = Vcon.build_new() >>> vcon.add_party(Party(name="Alice")) >>> vcon.add_session() >>> vcon.add_attachment("metadata", {"version": "1.0"}) >>> metadata = vcon.find_attachment_by_purpose("metadata")
- find_dialog(by: str, val: str) Dialog | None[source]
Find a dialog entry in the vCon by a key-value pair.
This method searches through the dialog list and returns the first dialog entry that matches the specified key-value pair, converted to a Dialog object.
- Parameters:
by – The key to search by (e.g., “type”, “start”)
val – The value to match
- Returns:
A Dialog object if found, None otherwise
Example
>>> vcon = Vcon.build_new() >>> dialog = Dialog(type="text", start="2023-01-01T00:00:00Z", parties=[0]) >>> vcon.add_dialog(dialog) >>> found = vcon.find_dialog("type", "text") >>> print(found.type) # Prints "text"
- find_dialogs_by_type(type: str) List[Dict[str, Any]][source]
Find all dialog entries in the vCon by type. This method searches through the dialog list and returns all dialog entries matching the specified type. :param type: The type of dialogs to find
- Returns:
A list of matching dialog dictionaries
Example
>>> vcon = Vcon.build_new() >>> incomplete = vcon.find_dialogs_by_type("incomplete")
- find_lawful_basis_attachments(party_index: int | None = None) List[Dict[str, Any]][source]
Find lawful basis attachments in the vCon.
- Parameters:
party_index – Filter by party index (optional)
- Returns:
List of lawful basis attachment dictionaries
- find_party_index(by: str, val: str) int | None[source]
Find the index of a party in the vCon’s parties list.
This method searches through the parties list and returns the index of the first party that matches the specified key-value pair.
- Parameters:
by – The key to search by (e.g., “name”, “type”)
val – The value to match
- Returns:
The index of the matching party if found, None otherwise
Example
>>> vcon = Vcon.build_new() >>> vcon.add_party(Party(type="person", name="John Doe")) >>> index = vcon.find_party_index("name", "John Doe") >>> print(index) # Prints 0
- find_wtf_attachments(party_index: int | None = None) List[Dict[str, Any]][source]
Find WTF transcription attachments in the vCon.
- Parameters:
party_index – Filter by party index (optional)
- Returns:
List of WTF attachment dictionaries
- classmethod generate_key_pair() Tuple[RSAPrivateKey, RSAPublicKey][source]
Generate a new RSA key pair for signing vCons.
This method generates a new RSA key pair that can be used for signing and verifying vCons.
- Returns:
A tuple containing the private key and public key
Example
>>> private_key, public_key = Vcon.generate_key_pair() >>> vcon = Vcon.build_new() >>> vcon.sign(private_key) >>> is_valid = vcon.verify(public_key)
- get_critical() List[str][source]
Get the list of critical extensions that must be supported.
- Returns:
List of extension names that must be supported, empty list if none are defined
Example
>>> vcon = Vcon.build_new() >>> vcon.add_critical("encryption") >>> critical = vcon.get_critical() >>> print(critical) # Prints ["encryption"]
- get_extensions() List[str][source]
Get the list of extensions used in this vCon.
- Returns:
List of extension names, empty list if none are defined
Example
>>> vcon = Vcon.build_new() >>> vcon.add_extension("video") >>> extensions = vcon.get_extensions() >>> print(extensions) # Prints ["video"]
- get_party_objects() List[Party][source]
Get the list of parties as Party objects.
This method creates Party objects from the underlying dictionary data. Use this when you need Party objects instead of raw dictionaries.
- Returns:
A list of Party objects representing all participants in the conversation
Example
>>> vcon = Vcon.build_new() >>> vcon.add_party(Party(type="person", name="John Doe")) >>> party_objects = vcon.get_party_objects() >>> print(party_objects[0].name) # Prints "John Doe"
- get_tag(tag_name: str) str | None[source]
Get the value of a specific tag by name.
- Parameters:
tag_name – The name of the tag to retrieve
- Returns:
The value of the tag if found, None otherwise
Example
>>> vcon = Vcon.build_new() >>> vcon.add_party(Party(name="Alice")) >>> vcon.add_session() >>> vcon.add_tag("category", "meeting") >>> value = vcon.get_tag("category") >>> print(value) # Prints "meeting"
- get_validation_warnings() List[str][source]
SHOULD-level findings (for example SHOULD NOT parameters on Events).
- property group
- is_valid() Tuple[bool, List[str]][source]
Validate the vCon against the core-05 rules.
Checks required fields and types, that
vcon(if present) is “0.5.0”, that Sessions, Events, Dialogs, attachments and analysis reference existing objects, the per-event-type parameter table, that at least one Session exists when there are Dialogs or Events, that attachments havepartyanddialogorsession, thatredacted_fromandamended_fromare exclusive, thatextensionslists every extension in use (and everycriticalentry), that every__REDACTED_REF_#has aredacted_stringsentry, that everyurlhas acontent_hashand everycontent_hashis well formed, and the body of everylawful_basisattachment.SHOULD-level findings are not errors; see
get_validation_warnings().- Returns:
A tuple where the first element is True if the vCon is valid and False otherwise, and the second element is a list of error messages.
- Return type:
Tuple[bool, List[str]]
- classmethod load(source: str, property_handling: str = 'default', migrate_legacy: bool = True, strict_migration: bool = False) Vcon[source]
Load a vCon from either a file path or URL.
- Parameters:
source – File path or URL to load the vCon from
property_handling – How to handle non-standard properties. Options are “default”, “strict”, or “meta”
- Returns:
A Vcon object
- Raises:
ValueError – If the source is invalid or cannot be loaded
requests.RequestException – If there is an error fetching from URL
json.JSONDecodeError – If the source contains invalid JSON
- classmethod load_from_file(file_path: str, property_handling: str = 'default', migrate_legacy: bool = True, strict_migration: bool = False) Vcon[source]
Load a vCon from a file.
- Parameters:
file_path – Path to the vCon JSON file
property_handling – How to handle non-standard properties. Options are “default”, “strict”, or “meta”
- Returns:
A Vcon object
- Raises:
FileNotFoundError – If the file does not exist
json.JSONDecodeError – If the file contains invalid JSON
- classmethod load_from_url(url: str, property_handling: str = 'default', migrate_legacy: bool = True, strict_migration: bool = False) Vcon[source]
Load a vCon from a URL.
- Parameters:
url – URL to fetch the vCon JSON from
property_handling – How to handle non-standard properties. Options are “default”, “strict”, or “meta”
- Returns:
A Vcon object
- Raises:
requests.RequestException – If there is an error fetching from URL
json.JSONDecodeError – If the response contains invalid JSON
- property meta
- classmethod migrate_0_4_0_to_0_5_0(source: str | Dict[str, Any], strict: bool = False, property_handling: str = 'default') Vcon[source]
Explicitly migrate a 0.4.0 vCon (dict or JSON string) and return a Vcon.
The migration report is available as
vcon.migration_report. Unlike the implicit migration on load, this also accepts input with novconparameter. Seevcon.migration.migrate_0_4_0_to_0_5_0().
- migration_report: MigrationReport | None
MigrationReport when the input was migrated from 0.4.0, else None.
- property parties: List[Dict[str, Any]]
Get the list of parties in the vCon.
- Returns:
A list of party dictionaries representing all participants in the conversation. These are mutable references to the internal data structure, allowing in-place modifications.
Example
>>> vcon = Vcon.build_new() >>> vcon.add_party(Party(type="person", name="John Doe")) >>> parties = vcon.parties >>> print(parties[0]["name"]) # Prints "John Doe" >>> parties[0]["name"] = "Jane Doe" # In-place modification works >>> print(vcon.parties[0]["name"]) # Prints "Jane Doe"
- post_to_url(url: str, headers: Dict[str, str] | None = None) Response[source]
Post the vCon as JSON to a URL with optional headers.
- Parameters:
url (str) – The URL to post the vCon to
headers (Optional[Dict[str, str]]) – Optional dictionary of HTTP headers (e.g., {‘x-conserver-api-token’: ‘token123’})
- Returns:
The HTTP response from the server
- Return type:
requests.Response
- Raises:
requests.RequestException – If there is an error making the HTTP request
Example
>>> vcon = Vcon.build_new() >>> response = vcon.post_to_url( ... 'https://api.example.com/vcons', ... headers={'x-conserver-api-token': 'your-token-here'} ... ) >>> print(response.status_code) # Prints HTTP status code (e.g., 200 for success)
- process_extensions() Dict[str, Any][source]
Process all extensions in the vCon.
- Returns:
Dictionary with processing results for each extension
- property redacted
Deprecated 0.4.0 name; returns
redacted_from.
- property redacted_from
- property redacted_strings: List[Dict[str, Any]]
- remove_critical(extension: str) None[source]
Remove an extension from the critical list.
- Parameters:
extension – The name of the extension to remove from critical
Example
>>> vcon = Vcon.build_new() >>> vcon.add_critical("encryption") >>> vcon.remove_critical("encryption")
- remove_extension(extension: str) None[source]
Remove an extension from the vCon.
- Parameters:
extension – The name of the extension to remove
Example
>>> vcon = Vcon.build_new() >>> vcon.add_extension("video") >>> vcon.remove_extension("video")
- save_to_file(file_path: str) None[source]
Save the vCon to a JSON file.
- Parameters:
file_path (str) – Path where the vCon JSON should be saved
- Raises:
IOError – If there is an error writing to the file
- property sessions: List[Dict[str, Any]]
The
sessionsarray (Session Objects).
- set_created_at(created_at: str | datetime) None[source]
Set the created_at field in the vCon.
- Parameters:
created_at (Union[str, datetime]) – The timestamp to set, either as a string in ISO format or as a datetime object.
- set_updated_at(timestamp: str | datetime) None[source]
Set the updated_at timestamp.
Args: timestamp: The timestamp to set, either as ISO 8601 string or datetime object
Example: >>> vcon = Vcon.build_new() >>> vcon.set_updated_at(datetime.now(timezone.utc)) >>> vcon.set_updated_at(“2025-02-18T12:00:00Z”)
- sign(private_key: RSAPrivateKey | bytes, alg: str = 'RS256') None[source]
Sign the vCon using JWS (JSON Web Signature).
This method signs the vCon using the provided private key, adding the signature information to the vCon. The signature can later be verified using the corresponding public key.
- Parameters:
private_key – The RSA private key or its PEM representation
alg – JWS algorithm (default “RS256”, the value core-05 says SHOULD be used). “none” is rejected (6.2.2).
- Raises:
AlgorithmNotPermittedError – If
algis “none” (any case) or is not a permitted algorithm.Exception – If there is an error during the signing process
Example
>>> from cryptography.hazmat.primitives.asymmetric import rsa >>> private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048) >>> vcon = Vcon.build_new() >>> vcon.sign(private_key)
- property subject: str | None
- property tags: Dict[str, Any] | None
Get the tags attachment from the vCon.
- Returns:
The tags attachment dictionary if it exists, None otherwise
Example
>>> vcon = Vcon.build_new() >>> vcon.add_party(Party(name="Alice")) >>> vcon.add_session() >>> vcon.add_tag("category", "meeting") >>> tags = vcon.tags >>> print(tags["body"]) # Prints ["category:meeting"]
- to_dict() Dict[str, Any][source]
Convert the vCon to a dictionary.
This method returns a dictionary representation of the vCon object, which can be used for direct manipulation or inspection.
- Returns:
A dictionary representation of the vCon
Example
>>> vcon = Vcon.build_new() >>> vcon_dict = vcon.to_dict() >>> print(vcon_dict["vcon"]) # Prints "0.5.0"
- to_json() str[source]
Serialize the vCon to a JSON string.
This method converts the entire vCon object to a JSON string representation, which can be used for storage or transmission.
- Returns:
A JSON string representation of the vCon
Example
>>> vcon = Vcon.build_new() >>> json_str = vcon.to_json() >>> print(type(json_str)) # Prints "<class 'str'>"
- property updated_at
- property uuid: str
- static uuid8_domain_name(domain_name: str) str[source]
- static uuid8_time(custom_c_62_bits: int) str[source]
- validate_extensions() Dict[str, Any][source]
Validate all extensions in the vCon.
- Returns:
Dictionary with validation results for each extension
- static validate_file(file_path: str) tuple[bool, list[str]][source]
Validate a vCon file at the given path.
- Parameters:
file_path (str) – Path to the vCon JSON file
- Returns:
A tuple containing (is_valid, list_of_errors)
- Return type:
tuple[bool, list[str]]
- static validate_json(json_str: str) tuple[bool, list[str]][source]
Validate a vCon from a JSON string.
- Parameters:
json_str (str) – JSON string representing a vCon
- Returns:
A tuple containing (is_valid, list_of_errors)
- Return type:
tuple[bool, list[str]]
- property vcon: str | None
- verify(public_key: RSAPublicKey | bytes) bool[source]
Verify the JWS signature of the vCon.
This method verifies the vCon’s signature using the provided public key. The vCon must have been previously signed using the corresponding private key.
- Parameters:
public_key – The RSA public key or its PEM representation
- Returns:
True if the signature is valid, False otherwise
- Raises:
ValueError – If the vCon is not signed
AlgorithmNotPermittedError – If the signature declares
alg“none” (in the protected header or the signature’s header), which core-05 forbids. Verification is refused rather than skipped.
Example
>>> private_key, public_key = Vcon.generate_key_pair() >>> vcon = Vcon.build_new() >>> vcon.sign(private_key) >>> is_valid = vcon.verify(public_key) >>> print(is_valid) # Prints True
- vcon.compute_content_hash(data: bytes, algorithm: str = 'sha512') str[source]
Compute a spec-formatted content hash for raw bytes.
Returns
"<algorithm>-<base64url-no-padding>"as required by draft-ietf-vcon-vcon-core-02 (e.g."sha512-GLy6IPa...").- Parameters:
data (bytes) – the raw bytes to hash
algorithm (str) – the hash algorithm to use (default:
"sha512");"sha256"is also supported for backwards compatibility
- Returns:
the algorithm-prefixed, unpadded base64url content hash
- Return type:
str
- Raises:
ValueError – if
algorithmis not a supported algorithm
- vcon.migrate_0_4_0_to_0_5_0(vcon: Any, *, strict: bool = False) MigrationResult[source]
Migrate a 0.4.0 vCon dict (or JSON string) to 0.5.0.
- Parameters:
vcon – The 0.4.0 vCon as a dict or JSON string. A signed vCon (JWS general form) is migrated as its unsigned payload. The input is not modified.
strict – When True, raise
MigrationErrorinstead of using a fallback for a MUST field that cannot be sourced from the input.
- Returns:
the 0.5.0 dict and the
MigrationReportlisting every inferred value, fallback and unresolved item.- Return type:
MigrationResult(vcon, report)- Raises:
MigrationError – the input is not a 0.4.0 vCon, is encrypted, or (strict) a required field has no source.
- vcon.parse_content_hash_algorithm(content_hash: str) str | None[source]
Return the algorithm prefix of
content_hash.- Parameters:
content_hash (str) – a content hash value, optionally prefixed
- Returns:
"sha512"or"sha256"for a prefixed value, orNonefor a legacy unprefixed hash (which this library historically emitted as a padded base64url SHA-256 digest)- Return type:
str or None
vcon.body module
Helpers for decoding vCon attachment/analysis/dialog bodies.
Under draft-ietf-vcon-vcon-core-04 section 2.3.2, when encoding is
"json" the body field is the JSON value itself (object, array,
string, number, bool, or null) rather than a json.dumps-serialized
string. Earlier drafts (and adapters/generators written against them, plus
some helpers in this library prior to 0.10.0) instead stored the JSON
representation of the value as a string body.
decode_body lets every reader in this library – and callers of it –
accept either shape without special-casing each call site. It is exported
both as a module-level function and as Vcon.decoded_body for
discoverability.
- vcon.body.decode_body(entry: Dict[str, Any] | None) Any[source]
Return the decoded
bodyof an attachment, analysis, or dialog entry.If
encodingis"json"(or absent – structured bodies were most commonly written without an explicit encoding under -02 conventions) andbodyis a string, the string is parsed as JSON and the resulting value is returned. This accepts both:vCons written under -02 conventions (or by this library prior to 0.10.0), where a JSON body was serialized to a string, and
-04-conformant vCons, where
bodyis already the decoded value.
Any other shape – an already-decoded value, a
base64url/noneencoded body, or a string that fails to parse as JSON – is returned unchanged.- Parameters:
entry (dict or None) – an attachment, analysis, or dialog dict, or
None- Returns:
the decoded body, or
Noneif there is no body to decode- Return type:
Any
vcon.civic_address module
- class vcon.civic_address.CivicAddress(country: str | None = None, a1: str | None = None, a2: str | None = None, a3: str | None = None, a4: str | None = None, a5: str | None = None, a6: str | None = None, prd: str | None = None, pod: str | None = None, sts: str | None = None, hno: str | None = None, hns: str | None = None, lmk: str | None = None, loc: str | None = None, flr: str | None = None, nam: str | None = None, pc: str | None = None)[source]
Bases:
objectA class representing civic address information according to GEOPRIV specification.
This class supports all civic address fields defined in RFC 4776 (GEOPRIV) and is used within vCon Party objects to provide location information.
Administrative areas (a1-a6): - a1: Administrative area 1 (e.g., state or province) - a2: Administrative area 2 (e.g., county or municipality) - a3: Administrative area 3 (e.g., city or town) - a4: Administrative area 4 (e.g., neighborhood or district) - a5: Administrative area 5 (e.g., postal code) - a6: Administrative area 6 (e.g., building or floor)
Street and building information: - sts: Street name - hno: House number - hns: House name - prd: Premier (e.g., department or suite number) - flr: Floor
Location and identification: - country: Country code (ISO 3166-1 alpha-2) - pc: Postal code - nam: Name of the location - lmk: Landmark name - loc: Location name - pod: Post office box identifier
All fields are optional and follow the GEOPRIV specification format. Field names are in lowercase as required by the vCon specification.
- __init__(country: str | None = None, a1: str | None = None, a2: str | None = None, a3: str | None = None, a4: str | None = None, a5: str | None = None, a6: str | None = None, prd: str | None = None, pod: str | None = None, sts: str | None = None, hno: str | None = None, hns: str | None = None, lmk: str | None = None, loc: str | None = None, flr: str | None = None, nam: str | None = None, pc: str | None = None)[source]
Initialize a new CivicAddress object.
- Parameters:
country (str) – Country code (ISO 3166-1 alpha-2)
a1 (str) – Administrative area 1 (e.g. state or province)
a2 (str) – Administrative area 2 (e.g. county or municipality)
a3 (str) – Administrative area 3 (e.g. city or town)
a4 (str) – Administrative area 4 (e.g. neighborhood or district)
a5 (str) – Administrative area 5 (e.g. postal code)
a6 (str) – Administrative area 6 (e.g. building or floor)
prd (str) – Premier (e.g. department or suite number)
pod (str) – Post office box identifier
sts (str) – Street name
hno (str) – House number
hns (str) – House name
lmk (str) – Landmark name
loc (str) – Location name
flr (str) – Floor
nam (str) – Name of the location
pc (str) – Postal code
vcon.dialog module
- class vcon.dialog.Dialog(type: str, start: datetime | str, parties: List[int], mediatype: str | None = None, filename: str | None = None, body: str | None = None, encoding: str | None = None, url: str | None = None, disposition: str | None = None, campaign: str | None = None, interaction: str | None = None, skill: str | None = None, duration: float | None = None, meta: dict | None = None, metadata: Dict[str, Any] | None = None, signaling: Dict[str, Any] | None = None, resolution: str | None = None, frame_rate: float | None = None, codec: str | None = None, bitrate: int | None = None, thumbnail: str | None = None, session_id: Dict[str, str] | List[Dict[str, str]] | None = None, content_hash: str | None = None, application: str | None = None, message_id: str | None = None, redacted_segments: List[Dict[str, Any]] | None = None, **kwargs)[source]
Bases:
objectA class representing a dialog segment in a vCon conversation.
A dialog represents a piece of conversation content, which can be: - text: Text-based communication (email, chat, SMS) - recording: Audio/video recording of the conversation - incomplete: Failed or incomplete conversation setup
"audio"and"video"are accepted as deprecated aliases forrecording.Dialog content can be stored inline or referenced externally: - Inline: Content stored directly in the body field - External: Content referenced via URL with content_hash for integrity
Media support: - Audio formats: WAV, MP3, MP4, OGG, WebM, AAC - Video formats: MP4, WebM, AVI, MKV, MOV, FLV, 3GP - Text formats: Plain text, multipart messages - Images: JPEG, TIFF, PDF
Changes in vCon 0.5.0 (draft-ietf-vcon-vcon-core-05):
partieslists the contributors only. The receivers are in thepartiesof the Session Object that references the dialog.originatormoved to the Session Object.party_historywas replaced by Event Objects (vcon.event.Event).The
transferandrecording-setdialog types were removed. Transfers are Events; a recording set is a Session.An empty Dialog Object (
Dialog.placeholder(), serialized as{}) holds a position in the dialog array so that indices do not change.redacted_segmentswas added.
- 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']
- VALID_DISPOSITIONS = ['no-answer', 'congestion', 'failed', 'busy', 'hung-up', 'voicemail-no-message']
- VALID_TYPES = ['recording', 'text', 'incomplete', 'audio', 'video']
- __init__(type: str, start: datetime | str, parties: List[int], mediatype: str | None = None, filename: str | None = None, body: str | None = None, encoding: str | None = None, url: str | None = None, disposition: str | None = None, campaign: str | None = None, interaction: str | None = None, skill: str | None = None, duration: float | None = None, meta: dict | None = None, metadata: Dict[str, Any] | None = None, signaling: Dict[str, Any] | None = None, resolution: str | None = None, frame_rate: float | None = None, codec: str | None = None, bitrate: int | None = None, thumbnail: str | None = None, session_id: Dict[str, str] | List[Dict[str, str]] | None = None, content_hash: str | None = None, application: str | None = None, message_id: str | None = None, redacted_segments: List[Dict[str, Any]] | None = None, **kwargs) None[source]
Initialize a Dialog object. :param type: the type of the dialog (e.g. “text”, “recording”, “incomplete”, “video”) :type type: str :param start: the start time of the dialog :type start: datetime :param parties: the parties that contributed to the dialog (the receivers are in the Session Object) :type parties: List[int] :param mediatype: the MIME type of the dialog body :type mediatype: str or None :param filename: the filename of the dialog body :type filename: str or None :param body: the body of the dialog :type body: str or None :param encoding: the encoding of the dialog body :type encoding: str or None :param url: the URL of the dialog :type url: str or None :param disposition: the disposition of the dialog :type disposition: str or None :param campaign: the campaign that the dialog is associated with :type campaign: str or None :param interaction: the interaction that the dialog is associated with :type interaction: str or None :param skill: the skill that the dialog is associated with :type skill: str or None :param duration: the duration of the dialog :type duration: float or None :param meta: additional metadata for the dialog :type meta: dict or None :param metadata: structured metadata for the dialog (newer format) :type metadata: dict or None :param signaling: signaling-specific information :type signaling: dict or None :param resolution: video resolution (e.g., “1920x1080”) :type resolution: str or None :param frame_rate: video frame rate in fps :type frame_rate: float or None :param codec: video codec (e.g., “H.264”, “H.265”) :type codec: str or None :param bitrate: video bitrate in kbps :type bitrate: int or None :param thumbnail: base64-encoded thumbnail image :type thumbnail: str or None :param session_id: Session identifier :type session_id: str or None :param content_hash: Hash for externally referenced files (replaces alg and signature) :type content_hash: str or None :param application: Application identifier for the dialog :type application: str or None :param message_id: Message identifier for email/text dialogs :type message_id: str or None :param redacted_segments: Redacted_segments Objects (start, end, optional parties) :type redacted_segments: list or None :param kwargs: Additional attributes to be set on the dialog
- add_external_data(url: str, filename: str, mediatype: str) None[source]
Add external data to the dialog.
- Parameters:
url (str) – the URL of the external data
- Returns:
None
- Return type:
None
- add_image_data(image_path: str, mediatype: str | None = None) None[source]
Add image data to the dialog from a local file.
- Parameters:
image_path (str) – Path to the image file
mediatype (str or None) – MIME type of the image (optional, auto-detected if not provided)
- Returns:
None
- Return type:
None
- add_inline_data(body: str | bytes, filename: str, mediatype: str) None[source]
Add inline data to the dialog.
The Dialog is written with
encoding: "base64url". Pass rawbytesand they are encoded; astris taken to be base64url already. Thecontent_hashis over the decoded content.- Parameters:
body (bytes or str) – the content as bytes, or as a base64url string
filename (str) – the filename of the inline data
mediatype (str) – the mediatype of the inline data
- Returns:
None
- Return type:
None
- add_streaming_video_reference(reference_id, mediatype, metadata=None) None[source]
Add a reference to a streamable video.
- Parameters:
reference_id – Unique identifier for the streamable video
mediatype – MIME type of the video
metadata – Optional video metadata
- Returns:
None
- add_video_data(video_data, filename=None, mediatype=None, inline=True, metadata=None) None[source]
Add video data to the dialog.
- Parameters:
video_data – Binary video data or URL to video
filename – Name of the video file
mediatype – MIME type of the video, or auto-detected from filename if None
inline – Whether to include the video as inline content (True) or external reference (False)
metadata – Optional video metadata to include
- Returns:
None
- add_video_with_optimal_storage(video_data, filename, mediatype=None, size_threshold_mb=10) None[source]
Add video with the optimal storage method based on size.
- Parameters:
video_data – Binary video data or URL
filename – Name of the video file
mediatype – MIME type of the video (optional)
size_threshold_mb – Size threshold in MB for inline vs external storage
- Returns:
None
- calculate_content_hash(algorithm: str = 'sha512') str[source]
Calculate the content hash for the dialog body.
The hash covers the content itself: for a
base64urlbody that is the decoded bytes, so the value matches a hash of the original file (whatadd_image_data()stores). Other bodies are hashed as UTF-8.The returned value is spec-formatted as
"<algorithm>-<base64url>"with no base64 padding (draft-ietf-vcon-vcon-core-02), e.g."sha512-GLy6IPa...".- Parameters:
algorithm (str) – The hash algorithm to use (default:
"sha512")."sha256"is also supported for backwards compatibility.- Returns:
The calculated hash value, prefixed with the algorithm name
- Return type:
str
- Raises:
ValueError – if there is no body to hash, or
algorithmis not a supported algorithm
- extract_image_metadata(image_data: bytes, mediatype: str) None[source]
Extract metadata from image data and add it to the dialog metadata.
- Parameters:
image_data (bytes) – Raw image data
mediatype (str) – MIME type of the image
- Returns:
None
- Return type:
None
- extract_video_metadata(video_path=None) dict[source]
Extract comprehensive metadata from video content using FFmpeg.
- Parameters:
video_path – Optional path to video file. If None, uses the dialog’s content.
- Returns:
Dictionary containing detailed video metadata
- generate_image_thumbnail(max_size: Tuple[int, int] = (200, 200)) str | None[source]
Generate a thumbnail for the image and return it as a base64-encoded string.
- Parameters:
max_size (Tuple[int, int]) – Maximum thumbnail dimensions (width, height)
- Returns:
Base64-encoded thumbnail or None if generation fails
- Return type:
str or None
- generate_thumbnail(*args, **kwargs)[source]
Generate a thumbnail for an image or a video Dialog.
For an image this calls
generate_image_thumbnail()(max_size, returns a base64url string or None). For a video it callsgenerate_video_thumbnail()(timestamp,width,height,quality; returns JPEG bytes).
- generate_video_thumbnail(timestamp=0.0, width=320, height=240, quality=90) bytes[source]
Generate a high-quality thumbnail from the video at the specified timestamp.
- Parameters:
timestamp – Time in seconds at which to extract the thumbnail frame
width – Desired width of the thumbnail in pixels
height – Desired height of the thumbnail in pixels
quality – JPEG quality (1-100)
- Returns:
Binary thumbnail data in JPEG format
- get_content_hash() str | None[source]
Get the content hash for externally referenced files.
- Returns:
The content hash if set, None otherwise
- Return type:
str or None
- get_session_id() Dict[str, str] | List[Dict[str, str]] | None[source]
Get the session identifier for this dialog.
- Returns:
The session identifier if set, None otherwise
- Return type:
str or None
- get_video_format_from_mediatype(mediatype: str | None = None) str[source]
Get the video format name from a MIME type.
- Parameters:
mediatype – MIME type of the video (default: this Dialog’s mediatype)
- Returns:
Format name (mp4, mov, etc.)
- has_thumbnail() bool[source]
Check if the video has a thumbnail.
- Returns:
True if the video has a thumbnail, False otherwise
- is_audio() bool[source]
Check if the dialog has audio content. :return: True if the dialog has audio content, False otherwise :rtype: bool
- is_email() bool[source]
Check if the dialog is an email dialog. :return: True if the dialog is an email dialog, False otherwise :rtype: bool
- is_external_data() bool[source]
Check if the dialog is an external data dialog.
- Returns:
True if the dialog is an external data dialog, False otherwise
- Return type:
bool
- is_external_data_changed() bool[source]
Check to see if it’s an external data dialog and verify the content hash.
- Returns:
True if the dialog is an external data dialog and the contents are valid, False otherwise
- Return type:
bool
- is_image() bool[source]
Check if the dialog has image content.
- Returns:
True if the dialog has image content, False otherwise
- Return type:
bool
- is_incomplete() bool[source]
Check if the dialog is an incomplete dialog. :return: True if the dialog is an incomplete dialog, False otherwise :rtype: bool
- is_inline_data() bool[source]
Check if the dialog is an inline data dialog.
- Returns:
True if the dialog is an inline data dialog, False otherwise
- Return type:
bool
- is_pdf() bool[source]
Check if the dialog has PDF content.
- Returns:
True if the dialog has PDF content, False otherwise
- Return type:
bool
- is_recording() bool[source]
Check if the dialog is a recording dialog. :return: True if the dialog is a recording dialog, False otherwise :rtype: bool
- is_text() bool[source]
Check if the dialog is a text dialog. :return: True if the dialog is a text dialog, False otherwise :rtype: bool
- is_transfer() bool[source]
Deprecated: core-05 has no transfer Dialog type, so this is always False.
- is_video(content_type=None) bool[source]
Check if the dialog has video content.
- Parameters:
content_type – Optional content type to check. If None, use the dialog’s mediatype.
- Returns:
True if the content is a video format, False otherwise
- classmethod placeholder() Dialog[source]
Create an empty Dialog Object (core-05 section 4.5.1).
It has no parameters and no meaning; it holds a position in the dialog array so that the indices of the other Dialog Objects, and the references to them, do not change. It serializes as
{}.
- set_content_hash(content_hash: str) None[source]
Set the content hash for externally referenced files.
- Parameters:
content_hash (str) – The content hash value
- Returns:
None
- Return type:
None
- set_session_id(session_id: Dict[str, str] | List[Dict[str, str]]) None[source]
Set the session identifier for this dialog.
- Parameters:
session_id (dict or list) – The session identifier (SessionId or list of SessionId)
- Returns:
None
- Return type:
None
- to_dict()[source]
Returns a dictionary representation of the Dialog object.
- Returns:
a dictionary containing all non-None Dialog object attributes
- Return type:
dict
- to_inline_data() None[source]
Convert the dialog from an external data dialog to an inline data dialog by reading the contents from the URL then adding the contents to the body.
- Returns:
None
- Return type:
None
- transcode_video(target_format, codec=None, bit_rate=None, width=None, height=None) None[source]
Transcode the video to a different format or with different encoding parameters.
- Parameters:
target_format – Target video format (mp4, webm, etc.)
codec – Video codec to use (h264, vp9, etc.)
bit_rate – Target bitrate in bits per second
width – Target width (if resizing)
height – Target height (if resizing)
- Returns:
None - updates the dialog’s content in place
- verify_content_hash(expected_hash: str, algorithm: str | None = None) bool[source]
Verify the content hash against the expected value.
The algorithm is inferred from the
expected_hashprefix ("sha512-"or"sha256-") so values produced by either this or older releases of the library verify correctly. A legacy unprefixed hash is treated as the padded base64url SHA-256 that vcon-lib emitted prior to the algorithm-prefixed format.- Parameters:
expected_hash (str) – The expected hash value
algorithm (str or None) – Optional explicit algorithm override; when omitted the algorithm is taken from the
expected_hashprefix
- Returns:
True if the hash matches, False otherwise
- Return type:
bool
- vcon.dialog.LEGACY_MEDIA_DIALOG_TYPES = ('audio', 'video')
Accepted on input for backward compatibility, normalized to “recording”.
- vcon.dialog.b64url_decode(value: str | bytes) bytes[source]
Base64url-decode
value, accepting padded or unpadded input.base64.urlsafe_b64decoderequires exact padding, which rejects the unpadded strings this library (and -04-conformant producers) now emits. This re-pads before decoding so both padded (legacy) and unpadded (spec-conformant) base64url bodies decode correctly.- Parameters:
value (str or bytes) – the base64url string (or bytes) to decode
- Returns:
the decoded raw bytes
- Return type:
bytes
- vcon.dialog.b64url_encode(data: bytes) str[source]
Base64url-encode
datawithout padding.draft-ietf-vcon-vcon-core-04follows the JWS/RFC 7515 base64url convention: no trailing=padding. Use this (instead of callingbase64.urlsafe_b64encodedirectly) whenever the library writes an inlinebase64url-encoded dialog or attachment body.- Parameters:
data (bytes) – the raw bytes to encode
- Returns:
the unpadded base64url-encoded string
- Return type:
str
- vcon.dialog.compute_content_hash(data: bytes, algorithm: str = 'sha512') str[source]
Compute a spec-formatted content hash for raw bytes.
Returns
"<algorithm>-<base64url-no-padding>"as required by draft-ietf-vcon-vcon-core-02 (e.g."sha512-GLy6IPa...").- Parameters:
data (bytes) – the raw bytes to hash
algorithm (str) – the hash algorithm to use (default:
"sha512");"sha256"is also supported for backwards compatibility
- Returns:
the algorithm-prefixed, unpadded base64url content hash
- Return type:
str
- Raises:
ValueError – if
algorithmis not a supported algorithm
- vcon.dialog.parse_content_hash_algorithm(content_hash: str) str | None[source]
Return the algorithm prefix of
content_hash.- Parameters:
content_hash (str) – a content hash value, optionally prefixed
- Returns:
"sha512"or"sha256"for a prefixed value, orNonefor a legacy unprefixed hash (which this library historically emitted as a padded base64url SHA-256 digest)- Return type:
str or None
vcon.event module
Event Object (draft-ietf-vcon-vcon-core-05, section 4.3) and the events array.
An Event is a point-in-time occurrence inside one or more Sessions: a party joining or dropping, a key press, a call transfer step, or a change of the parties contributing to a recording channel.
The per-type parameter applicability table of section 4.3.1.5 is held in
EVENT_PARAMETER_RULES and enforced by validate_event() and by
Vcon.is_valid().
Rule codes (section 4.3.1.5):
Mthe parameter MUST be presentOthe parameter is optionalSNthe parameter SHOULD NOT be present (reported as a warning)Xthe parameter MUST NOT be present
- vcon.event.CORE_EVENT_TYPES = ('join', 'drop', 'hold', 'unhold', 'mute', 'unmute', 'keydown', 'keyup', 'consultation-start', 'blind-transfer', 'consultative-transfer', 'transfer-abandoned', 'channel-contributors')
Every Event type token defined by core-05 (section 4.3.1).
- vcon.event.EVENT_PARAMETERS = ('type', 'time', 'sessions', 'party', 'dialog', 'channel', 'contributors', 'button', 'transferee', 'transfer_target', 'consultation', 'target_session')
Event parameters other than
typeandtime, in the order of 4.3.
- vcon.event.EVENT_PARAMETER_RULES: Dict[str, Dict[str, str]] = {'blind-transfer': {'button': 'X', 'channel': 'X', 'consultation': 'X', 'contributors': 'X', 'dialog': 'SN', 'party': 'M', 'sessions': 'M', 'target_session': 'M', 'time': 'M', 'transfer_target': 'M', 'transferee': 'M', 'type': 'M'}, 'channel-contributors': {'button': 'X', 'channel': 'M', 'consultation': 'X', 'contributors': 'O', 'dialog': 'M', 'party': 'X', 'sessions': 'X', 'target_session': 'X', 'time': 'M', 'transfer_target': 'X', 'transferee': 'X', 'type': 'M'}, 'consultation-start': {'button': 'X', 'channel': 'X', 'consultation': 'M', 'contributors': 'X', 'dialog': 'SN', 'party': 'M', 'sessions': 'M', 'target_session': 'X', 'time': 'M', 'transfer_target': 'M', 'transferee': 'M', 'type': 'M'}, 'consultative-transfer': {'button': 'X', 'channel': 'X', 'consultation': 'M', 'contributors': 'X', 'dialog': 'SN', 'party': 'M', 'sessions': 'M', 'target_session': 'M', 'time': 'M', 'transfer_target': 'M', 'transferee': 'M', 'type': 'M'}, 'drop': {'button': 'X', 'channel': 'X', 'consultation': 'X', 'contributors': 'X', 'dialog': 'SN', 'party': 'M', 'sessions': 'M', 'target_session': 'X', 'time': 'M', 'transfer_target': 'X', 'transferee': 'X', 'type': 'M'}, 'hold': {'button': 'X', 'channel': 'X', 'consultation': 'X', 'contributors': 'X', 'dialog': 'SN', 'party': 'M', 'sessions': 'M', 'target_session': 'X', 'time': 'M', 'transfer_target': 'X', 'transferee': 'X', 'type': 'M'}, 'join': {'button': 'X', 'channel': 'X', 'consultation': 'X', 'contributors': 'X', 'dialog': 'SN', 'party': 'M', 'sessions': 'M', 'target_session': 'X', 'time': 'M', 'transfer_target': 'X', 'transferee': 'X', 'type': 'M'}, 'keydown': {'button': 'M', 'channel': 'X', 'consultation': 'X', 'contributors': 'X', 'dialog': 'SN', 'party': 'M', 'sessions': 'M', 'target_session': 'X', 'time': 'M', 'transfer_target': 'X', 'transferee': 'X', 'type': 'M'}, 'keyup': {'button': 'M', 'channel': 'X', 'consultation': 'X', 'contributors': 'X', 'dialog': 'SN', 'party': 'M', 'sessions': 'M', 'target_session': 'X', 'time': 'M', 'transfer_target': 'X', 'transferee': 'X', 'type': 'M'}, 'mute': {'button': 'X', 'channel': 'X', 'consultation': 'X', 'contributors': 'X', 'dialog': 'SN', 'party': 'M', 'sessions': 'M', 'target_session': 'X', 'time': 'M', 'transfer_target': 'X', 'transferee': 'X', 'type': 'M'}, 'transfer-abandoned': {'button': 'X', 'channel': 'X', 'consultation': 'O', 'contributors': 'X', 'dialog': 'SN', 'party': 'M', 'sessions': 'M', 'target_session': 'X', 'time': 'M', 'transfer_target': 'O', 'transferee': 'M', 'type': 'M'}, 'unhold': {'button': 'X', 'channel': 'X', 'consultation': 'X', 'contributors': 'X', 'dialog': 'SN', 'party': 'M', 'sessions': 'M', 'target_session': 'X', 'time': 'M', 'transfer_target': 'X', 'transferee': 'X', 'type': 'M'}, 'unmute': {'button': 'X', 'channel': 'X', 'consultation': 'X', 'contributors': 'X', 'dialog': 'SN', 'party': 'M', 'sessions': 'M', 'target_session': 'X', 'time': 'M', 'transfer_target': 'X', 'transferee': 'X', 'type': 'M'}}
Parameter applicability by Event type (section 4.3.1.5 tables).
- class vcon.event.Event(type: str, time: datetime | str, sessions: int | List[int] | None = None, party: int | None = None, dialog: int | List[int] | None = None, channel: int | None = None, contributors: int | List[int] | None = None, button: str | None = None, transferee: int | None = None, transfer_target: int | None = None, consultation: int | None = None, target_session: int | None = None, validate: bool = True, **extra: Any)[source]
Bases:
objectAn Event Object (core-05 section 4.3).
- Parameters:
type – Event type token, for example
"join"or"blind-transfer".time – When the event occurred (
datetimeor ISO 8601 string).sessions – Session index or list of indices (not for channel-contributors).
party – Party index (not for channel-contributors).
dialog – Dialog index (channel-contributors; SHOULD NOT be used otherwise).
channel – Channel index (channel-contributors only).
contributors – Party index, list of indices, or
None(channel-contributors only).button – DTMF digit or key label (keydown and keyup only).
transferee – Party indices (transfer types).
transfer_target – Party indices (transfer types).
consultation – Session indices (transfer types).
target_session – Session indices (transfer types).
validate – Apply the parameter applicability table and raise
ValueErroron anM/Xviolation (default True).**extra – Parameters defined by a vCon extension.
- vcon.event.validate_event(event: Any, *, party_count: int | None = None, dialog_count: int | None = None, session_count: int | None = None, label: str = 'Event') Tuple[List[str], List[str]][source]
Validate one Event Object dict against core-05 section 4.3.
Returns
(errors, warnings).SNviolations are warnings,MandXviolations are errors. An Event whose type is not a core token is only checked fortypeandtime(section 2.5: it belongs to an extension). Index values are range-checked only when the matching count is supplied.
vcon.migration module
Migrate a vCon from syntax 0.4.0 to 0.5.0 (draft-ietf-vcon-vcon-core-05, Appendix A.1).
The migration is table driven. MIGRATION_STEPS holds one MigrationStep
per step T1..T15 of the ordered transform table; each step is one function that
mutates a shared _Context. If a later edit of Appendix A.1 changes one step,
only that function (or its table entry) needs to change.
Execution order (the draft gives none; this order is inferred so that every
dialog index stays valid): the steps that read the 0.4.0 dialog array
run before any array is rewritten, and T10 blanks the removed Dialogs in
place at the end, so the array length and every other index are unchanged.
T13 T15 T1 -> T8 T9 T9b T6 -> T2 T7 T4(+T5) T3 -> T10 T10b T10c -> T11 T12 T14
T4 runs before T3 so that the Sessions T5 creates for a transfer’s original, consultation and target calls are known when T3 builds the party_history Events: an Event lists every Session of the Dialog it came from (AMB-3).
Nothing is invented silently. Every value the draft does not dictate is listed
in the MigrationReport (kind inferred), every field that had to be
filled by a fallback is listed (kind fallback), and every problem the
migration could not resolve is listed (kind unresolved). In strict mode a
fallback raises MigrationError instead.
A signed 0.4.0 vCon is migrated as the unsigned payload. The migration never
signs; the report sets resign_required.
- vcon.migration.FALLBACK = 'fallback'
A MUST field with no source was filled with the documented fallback.
- vcon.migration.INFERRED = 'inferred'
A value the draft does not dictate; a documented default was applied.
- vcon.migration.INFO = 'info'
Informational.
- vcon.migration.MIGRATION_STEPS: List[MigrationStep] = [MigrationStep(id='T13', title='Signed input: migrate the payload, require re-signing', source='A.1 bullet 11; 6.2.2', func=<function _step_t13_unwrap_signed>), MigrationStep(id='T15', title='Duplicate header parameters tolerated on read', source='A.1 bullet 13', func=<function _step_t15_duplicate_headers>), MigrationStep(id='T1', title='vcon 0.4.0 -> 0.5.0', source='A.1 bullet 1', func=<function _step_t1_version>), MigrationStep(id='T8', title='text Dialog parties -> sender; all parties to Session', source='A.1 bullet 6', func=<function _step_t8_text_parties>), MigrationStep(id='T9', title='incomplete Dialog parties -> originator/first', source='A.1 bullet 6', func=<function _step_t9_incomplete_parties>), MigrationStep(id='T9b', title='other Dialog parties kept; union to Session', source='4.5.4 (A.1 silent)', func=<function _step_t9b_recording_parties>), MigrationStep(id='T6', title='Dialog originator -> Session originator', source='A.1 bullet 5', func=<function _step_t6_originator>), MigrationStep(id='T2', title='Add a Session referencing all Dialogs', source='A.1 bullet 2', func=<function _step_t2_sessions>), MigrationStep(id='T7', title='recording-set Dialog -> Session', source='A.1 bullet 9', func=<function _step_t7_recording_sets>), MigrationStep(id='T4', title='transfer Dialog -> transfer Events (with T5 Session references)', source='A.1 bullet 4', func=<function _step_t4_transfers>), MigrationStep(id='T3', title='party_history -> Events', source='A.1 bullet 3', func=<function _step_t3_party_history>), MigrationStep(id='T10', title='Removed Dialogs -> {} in place', source='A.1 bullet 10; 4.5.1', func=<function _step_t10_blank_removed>), MigrationStep(id='T10b', title='Re-point analysis/attachment references to removed Dialogs', source='AMB-2', func=<function _step_t10b_retarget>), MigrationStep(id='T10c', title='Scope unscoped attachments to the only Session', source='4.6.4 (A.1 silent)', func=<function _step_t10c_unscoped_attachments>), MigrationStep(id='T11', title='redacted -> redacted_from', source='A.1 bullet 7', func=<function _step_t11>), MigrationStep(id='T12', title='amended -> amended_from', source='A.1 bullet 8', func=<function _step_t12>), MigrationStep(id='T14', title='extensions lists every extension in use', source='A.1 bullet 12; 4.1.3', func=<function _step_t14_extensions>)]
One entry per step of the ordered transform table (Appendix A.1), in execution order.
- exception vcon.migration.MigrationError[source]
Bases:
ValueErrorThe vCon cannot be migrated (or, in strict mode, a MUST field has no source).
- class vcon.migration.MigrationReport(source_version: str | None = None, target_version: str = '0.5.0', strict: bool = False, resign_required: bool = False, entries: ~typing.List[~vcon.migration.ReportEntry] = <factory>, removed_dialogs: ~typing.Dict[int, ~typing.Dict[str, ~typing.Any]] = <factory>, steps_run: ~typing.List[str] = <factory>)[source]
Bases:
objectWhat a migration did that the draft did not dictate.
- entries: List[ReportEntry]
- property fallbacks: List[ReportEntry]
- property inferred: List[ReportEntry]
- property notes: List[ReportEntry]
- removed_dialogs: Dict[int, Dict[str, Any]]
Original content of every Dialog replaced by
{}, keyed by its (unchanged) index.
- resign_required: bool = False
the signature is dropped and the result is unsigned.
- Type:
True when the input was signed
- source_version: str | None = None
- steps_run: List[str]
Steps that ran, in order.
- strict: bool = False
- target_version: str = '0.5.0'
- property unresolved: List[ReportEntry]
- class vcon.migration.MigrationResult(vcon: Dict[str, Any], report: MigrationReport)[source]
Bases:
NamedTupleResult of a migration. Unpacks as
(vcon, report).- report: MigrationReport
Alias for field number 1
- vcon: Dict[str, Any]
Alias for field number 0
- class vcon.migration.MigrationStep(id: 'str', title: 'str', source: 'str', func: 'Callable[[_Context], None]')[source]
Bases:
object- func: Callable[[_Context], None]
- id: str
- source: str
- title: str
- class vcon.migration.ReportEntry(step: 'str', kind: 'str', message: 'str', code: 'Optional[str]' = None, details: 'Dict[str, Any]' = <factory>)[source]
Bases:
object- code: str | None = None
- details: Dict[str, Any]
- kind: str
- message: str
- step: str
- vcon.migration.UNRESOLVED = 'unresolved'
A problem left for a person to resolve.
- vcon.migration.migrate_0_4_0_to_0_5_0(vcon: Any, *, strict: bool = False) MigrationResult[source]
Migrate a 0.4.0 vCon dict (or JSON string) to 0.5.0.
- Parameters:
vcon – The 0.4.0 vCon as a dict or JSON string. A signed vCon (JWS general form) is migrated as its unsigned payload. The input is not modified.
strict – When True, raise
MigrationErrorinstead of using a fallback for a MUST field that cannot be sourced from the input.
- Returns:
the 0.5.0 dict and the
MigrationReportlisting every inferred value, fallback and unresolved item.- Return type:
MigrationResult(vcon, report)- Raises:
MigrationError – the input is not a 0.4.0 vCon, is encrypted, or (strict) a required field has no source.
vcon.party module
- class vcon.party.Party(tel: str | None = None, stir: str | None = None, mailto: str | None = None, name: str | None = None, validation: str | None = None, gmlpos: str | None = None, civicaddress: CivicAddress | None = None, uuid: str | None = None, role: str | None = None, contact_list: str | None = None, meta: dict | None = None, sip: str | None = None, did: str | None = None, jCard: dict | None = None, timezone: str | None = None, **kwargs)[source]
Bases:
objectA class representing a party (participant) in a vCon conversation.
A party represents a participant in the conversation with various contact and identification information. Parties can be callers, agents, or any other participants in the conversation.
Supported contact methods: - tel: Telephone number - mailto: Email address - sip: SIP URI for VoIP communication - did: Decentralized Identifier for blockchain-based identity
Contact information: - name: Display name of the party - jCard: vCard format contact information (RFC 7095) - timezone: Party’s timezone for temporal context
Location and validation: - civicaddress: Civic address information (GEOPRIV format) - gmlpos: GML position coordinates - validation: Validation information for the party
Additional metadata: - uuid: Unique identifier for the party - role: Role in the conversation (e.g., “caller”, “agent”) - stir: STIR identifier for secure telephony - contact_list: Reference to contact list - meta: Additional metadata
New in vCon 0.4.0: - sip: SIP URI for the party - did: Decentralized Identifier - jCard: vCard format contact information - timezone: Party’s timezone
- __init__(tel: str | None = None, stir: str | None = None, mailto: str | None = None, name: str | None = None, validation: str | None = None, gmlpos: str | None = None, civicaddress: CivicAddress | None = None, uuid: str | None = None, role: str | None = None, contact_list: str | None = None, meta: dict | None = None, sip: str | None = None, did: str | None = None, jCard: dict | None = None, timezone: str | None = None, **kwargs) None[source]
Initialize a new Party object.
- Parameters:
tel (str | None) – Telephone number of the party
stir (str | None) – STIR identifier of the party
mailto (str | None) – Email address of the party
name (str | None) – Display name of the party
validation (str | None) – Validation information of the party
gmlpos (str | None) – GML position of the party
civicaddress (CivicAddress | None) – Civic address of the party
uuid (str | None) – UUID of the party
role (str | None) – Role of the party
contact_list (str | None) – Contact list of the party
sip (str | None) – SIP URI for the party
did (str | None) – Decentralized Identifier
jCard (dict | None) – vCard format contact information
timezone (str | None) – Party’s timezone
kwargs – Additional attributes to be set on the party
- class vcon.party.PartyHistory(party: int, event: str, time: datetime | str, button: str | None = None)[source]
Bases:
objectDeprecated 0.4.0 Party_History Object, kept so old imports keep working.
core-05 replaced Dialog
party_historywith Event Objects. Build anEventdirectly, or convert withto_event(), which needs the Session index (or indices) the event belongs to. APartyHistorycan no longer be attached to a Dialog.- VALID_EVENTS = ['join', 'drop', 'hold', 'unhold', 'mute', 'unmute', 'keydown', 'keyup']
vcon.session module
Session Object and Session_Reference Object (core-05 sections 4.2 and 4.2.8).
A Session groups the Dialog and Event Objects of one conversation (or part of one) and records its receivers. A Session Object with no parameters is allowed.
- vcon.session.SESSION_REFERENCE_TYPES = ('child', 'peer', 'precursor', 'breakout')
Session_Reference
typetokens defined by core-05 (4.2.8.2). Values defined by a vCon extension are also allowed.
- class vcon.session.Session(start: str | datetime | None = None, duration: int | float | None = None, parties: List[int] | None = None, originator: int | None = None, session_id: Dict[str, str] | None = None, sessions: List[SessionReference | Dict[str, Any]] | None = None, dialog: List[int] | None = None)[source]
Bases:
objectA Session Object.
- Parameters:
start – Session start (
datetimeor ISO 8601 string). SHOULD be present.duration – Session duration in seconds. Absent means the session has no end.
parties – Indices of the receivers. The first one is the implied originator.
originator – Index of the originator, only when it is not the first party.
session_id – A SessionId Object (
{"local": ..., "remote": ...}).sessions – Relationships to other Sessions (
SessionReferenceor dicts).dialog – Indices of the Dialog Objects that are part of the session.
vcon.validation module
Structural validation of an unsigned vCon dict against core-05.
validate_vcon_dict is the engine behind Vcon.is_valid(). It works on
plain dicts so the migration code can reuse it.
- vcon.validation.KNOWN_ATTACHMENT_PURPOSE_EXTENSIONS = {'lawful_basis': 'lawful_basis', 'wtf_transcription': 'wtf_transcription'}
Extension names this library knows how to recognise, keyed by how they show up.
- vcon.validation.LEGACY_TOP_LEVEL = {'amended': 'amended_from', 'redacted': 'redacted_from'}
Removed in 0.5.0; their presence means the document is still 0.4.0 shaped.
- vcon.validation.LIBRARY_DIALOG_TYPES = ('audio', 'video')
Dialog types older versions of this library wrote although core-05 does not define them. Accepted on read with a warning; the library never writes them.
- vcon.validation.content_hash_problems(value: Any) List[str][source]
Return why
valueis not a ContentHash or ContentHash[] (empty if it is).
- vcon.validation.encrypted_form(vcon: Any) bool[source]
True for a JWE General JSON Serialization container (section 6.3).
- vcon.validation.extensions_in_use(vcon: Dict[str, Any]) Tuple[Set[str], List[str]][source]
Find the vCon extensions the document uses.
Returns
(names, unnamed).namesholds extension names this library recognises (lawful_basis,wtf_transcription).unnameddescribes each use of a value outside the core vocabulary (an Event type, Dialog type, encoding, disposition or Session_Reference type) whose defining extension cannot be identified from the document alone.
- vcon.validation.mediatype_ok(mediatype: Any, known: List[str]) bool[source]
True if
mediatypeis acceptable for a Dialog.Media type parameters (
; boundary=...) are ignored. Anymultipart/,message/ortext/subtype is accepted, since the draft’s examples usemultipart/alternativeand the list in the draft is open-ended.
- vcon.validation.signed_form(vcon: Any) bool[source]
True for a JWS General JSON Serialization container (section 6.2).
vcon.vcon module
- exception vcon.vcon.AlgorithmNotPermittedError[source]
Bases:
ValueErrorA JWS used
alg“none” (forbidden by core-05) or an unsupported algorithm.
- class vcon.vcon.Attachment(purpose: str, body: Any = None, encoding: str = 'none', mediatype: str | None = None, filename: str | None = None, url: str | None = None, content_hash: str | None = None, start: str | None = None, party: int | None = None, dialog: int | None = None, session: int | List[int] | None = None)[source]
Bases:
objectA class representing an attachment in a vCon.
An attachment consists of a purpose, body content, and an encoding format. The encoding format must be one of the supported formats: base64url, json, or none.
- purpose
The purpose of the attachment
- Type:
str
- body
The content of the attachment
- Type:
Any
- encoding
The encoding format used for the body
- Type:
str
- VALID_ENCODINGS = ['base64url', 'json', 'none']
- __init__(purpose: str, body: Any = None, encoding: str = 'none', mediatype: str | None = None, filename: str | None = None, url: str | None = None, content_hash: str | None = None, start: str | None = None, party: int | None = None, dialog: int | None = None, session: int | List[int] | None = None) None[source]
Initialize an Attachment object.
Under core-05 (section 4.6) an attachment needs
partyand at least one ofdialogorsession.partydefaults to 0. Neitherdialognorsessionis defaulted here, because the right index depends on the vCon;Vcon.add_attachment()defaults it only when the vCon has exactly one Session.- Parameters:
purpose – The purpose of the attachment
body – The content of the attachment
encoding – The encoding format used for the body (default: “none”)
- Raises:
ValueError – If the specified encoding is not supported
- classmethod from_image(image_path: str, purpose: str = 'image') Attachment[source]
Create an Attachment from an image file.
- Parameters:
image_path – Path to the image file
type – The type of the attachment (default: “image”)
- Returns:
An Attachment object containing the image
- Raises:
ValueError – If the image format is not supported
FileNotFoundError – If the image file cannot be found
- vcon.vcon.PERMITTED_JWS_ALGORITHMS = ('RS256', 'RS384', 'RS512', 'PS256', 'PS384', 'PS512', 'ES256', 'ES384', 'ES512', 'EdDSA')
JWS algorithms accepted for signing and verifying. “none” is excluded: core-05 section 6.2.2, “The alg parameter MUST NOT have the value none”.
- class vcon.vcon.Vcon(vcon_dict: Dict[str, Any] = None, property_handling: str = 'default', migrate_legacy: bool = True, strict_migration: bool = False)[source]
Bases:
objectA class representing a vCon (Virtual Conversation) object according to the vCon specification.
A vCon is a standardized format for representing conversations and related metadata. It includes information about participants (parties), dialog content, attachments, and analysis data.
The vCon format supports features such as:
Unique identification via UUID
The
vconsyntax version (written as"0.5.0")Timestamps for creation and updates
Party information with contact details (tel, name, sip, did, jCard, timezone)
Dialog content with media types and session information
Attachments for ancillary documents
Analysis data for conversation insights
Digital signatures and encryption
Extensions and critical for extensibility
Civic address information for location data
Sessions (
sessions) grouping dialog and events, and Events (events) for joins, drops, holds, key presses and transfers
New in vCon 0.5.0 (draft-ietf-vcon-vcon-core-05):
sessionsandeventsarrays;SessionandEventclassesredacted_fromandamended_fromreplaceredactedandamendedAttachments need
partyanddialogorsessionextensionsMUST list every extension in use;alg: "none"is rejectedDialog
partiesare contributors only; empty{}Dialog placeholders0.4.0 input is migrated on load (see
migrate_0_4_0_to_0_5_0)
- vcon_dict
The underlying dictionary containing all vCon data
- Type:
Dict
- property_handling
How non-standard properties are handled
- Type:
str
- WTF_SCHEMA_URL = 'https://datatracker.ietf.org/doc/html/draft-howe-vcon-wtf-extension'
- __init__(vcon_dict: Dict[str, Any] = None, property_handling: str = 'default', migrate_legacy: bool = True, strict_migration: bool = False) None[source]
Initialize a Vcon object from a dictionary.
A dict that declares
"vcon": "0.4.0"is migrated to 0.5.0 here, usingmigrate_0_4_0_to_0_5_0. The report is kept inself.migration_report. A signed vCon whose payload is 0.4.0 is NOT migrated on load, because migrating drops the signature: verify it, then callVcon.migrate_0_4_0_to_0_5_0(). An unmigrated 0.4.0 dict (signed, ormigrate_legacy=False) is kept as is;property_handlingis not applied to it. A dict with any other (or no)vconvalue is taken as is.- Parameters:
vcon_dict – A dictionary representing a vCon. Defaults to an empty dict.
property_handling – How to handle non-standard properties. Options are: - “default”: Keep non-standard properties (default) - “strict”: Remove non-standard properties - “meta”: Move non-standard properties to meta object
migrate_legacy – Migrate 0.4.0 input to 0.5.0 (default True). When False the 0.4.0 dict is kept untouched and
is_valid()will report it as not 0.5.0.strict_migration – Passed to the migration as
strict; raisesMigrationErrorwhen a required field has no source.
Example
>>> vcon = Vcon({"uuid": "123", "custom_field": "value"})
>>> strict_vcon = Vcon({"uuid": "123", "custom_field": "value"}, property_handling="strict") >>> meta_vcon = Vcon({"uuid": "123", "custom_field": "value"}, property_handling="meta")
- add_analysis(*, type: str, vendor: str, body: Dict[str, Any] | List[Any] | str, dialog: int | List[int] | None = None, sessions: int | List[int] | None = None, attachment: int | List[int] | None = None, analysis: int | List[int] | None = None, encoding: str = 'none', mediatype: str | None = None, filename: str | None = None, product: str | None = None, url: str | None = None, content_hash: str | None = None, schema: Dict[str, Any] | None = None, meta: Dict[str, Any] | None = None, **extra) None[source]
Add analysis data to the vCon.
This method adds analysis data with the specified parameters to the vCon’s analysis list. Analysis data can be associated with one or more dialog entries and includes metadata about the vendor who performed the analysis.
- Parameters:
type – The type of analysis
dialog – Index or list of indices of the associated dialog entries (optional)
sessions – Index or list of indices of the Sessions analysed (optional)
attachment – Index or list of indices of the attachments analysed (optional)
analysis – Index or list of indices of other Analysis Objects used (optional)
vendor – The name of the vendor who performed the analysis
body – The analysis data
encoding – The encoding format of the body (default: “none”)
mediatype – Optional media type of the analysis content
filename – Optional filename for the analysis content
product – Optional product name of the vendor
url – Optional URL for external analysis content
content_hash – Optional content hash for external analysis content
schema – Optional schema information about the analysis (default: None)
meta – Optional metadata about the analysis (default: None)
**extra – Additional key-value pairs to include in the analysis
- Raises:
Exception – If the encoding is invalid or if the body format is invalid for the specified encoding
Example
>>> vcon = Vcon.build_new() >>> vcon.add_analysis( ... type="sentiment", ... dialog=[0], ... vendor="acme", ... body={"score": 0.8}, ... encoding="json", ... schema={"version": "1.0"}, ... meta={"confidence": "high"} ... )
- add_attachment(purpose: str, body: Any = None, encoding: str = 'none', mediatype: str | None = None, filename: str | None = None, url: str | None = None, content_hash: str | None = None, start: str | None = None, party: int | None = None, dialog: int | None = None, session: int | List[int] | None = None) Attachment[source]
Add an attachment to the vCon.
This method creates a new attachment with the specified type, body, and encoding and adds it to the vCon’s attachments list.
Core-05 needs
partyplusdialogorsession.partydefaults to 0. If neitherdialognorsessionis given, the attachment is scoped to the only Session when the vCon has exactly one; otherwiseValueErroris raised rather than inventing a scope.- Parameters:
purpose – The purpose of the attachment
body – The content of the attachment
encoding – The encoding format for the body (default: “none”)
mediatype – Optional media type of the attachment
filename – Optional file name of the attachment
url – Optional URL for external attachments
content_hash – Optional content hash for external attachments
start – Optional timestamp for the attachment
party – Optional party index (default 0)
dialog – Optional dialog index
session – Optional Session index or list of indices
- Returns:
The created Attachment object
- Raises:
ValueError – If the specified encoding is not supported
Example
>>> vcon = Vcon.build_new() >>> vcon.add_party(Party(name="Alice")) >>> vcon.add_session() >>> attachment = vcon.add_attachment("metadata", {"version": "1.0"}, "json") >>> print(attachment.purpose) # Prints "metadata"
- add_critical(extension: str) None[source]
Add an extension to the critical list.
- Parameters:
extension – The name of the extension that must be supported
Example
>>> vcon = Vcon.build_new() >>> vcon.add_critical("encryption") >>> vcon.add_critical("video")
- add_dialog(dialog: Dialog, session: int | None = None) int[source]
Add a dialog entry to the vCon.
This method adds a Dialog object to the vCon’s dialog list. A dialog entry represents a segment of the conversation with its associated metadata. Use
Dialog.placeholder()to add an empty Dialog Object ({}) that holds an array position.- Parameters:
dialog – The Dialog object to add
session – Optional index of an existing Session; the new Dialog’s index is appended to that Session’s
dialoglist. Core-05 requires at least one Session when the vCon has Dialogs, so add Sessions withadd_session().
- Returns:
The index of the new Dialog in the
dialogarray.
Example
>>> vcon = Vcon.build_new() >>> dialog = Dialog(type="text", start="2023-01-01T00:00:00Z", parties=[0]) >>> index = vcon.add_dialog(dialog)
- add_event(event: Event | Dict[str, Any]) int[source]
Add an Event Object and return its index in the
eventsarray.An
Eventis checked against the per-type parameter table when it is built; a plain dict is checked byis_valid().Example
>>> vcon = Vcon.build_new() >>> vcon.add_event(Event(type="join", time="2023-01-01T00:00:00Z", sessions=0, party=0))
- add_extension(extension: str) None[source]
Add an extension to the vCon.
- Parameters:
extension – The name of the extension to add
Example
>>> vcon = Vcon.build_new() >>> vcon.add_extension("video") >>> vcon.add_extension("encryption")
- add_image(image_path: str, purpose: str = 'image', party: int | None = None, dialog: int | None = None, session: int | List[int] | None = None) Attachment[source]
Add an image attachment to the vCon.
This method creates a new attachment with the specified image and adds it to the vCon’s attachments list.
- Parameters:
image_path – Path to the image file
purpose – The purpose of the attachment (default: “image”)
party – Party index (default 0)
dialog – Dialog index
session – Session index or list of indices. With neither
dialognorsession, the only Session is used when the vCon has exactly one, as inadd_attachment().
- Returns:
The created Attachment object
- Raises:
FileNotFoundError – If the image file cannot be found
ValueError – If the image format is not supported, or no
dialog/sessionis given and the vCon does not have exactly one Session
Example
>>> vcon = Vcon.build_new() >>> vcon.add_session() >>> attachment = vcon.add_image("document.pdf", "identification") >>> print(attachment.mediatype) # Prints "application/pdf"
- add_incomplete_dialog(start: str | datetime, disposition: str, details: Dict[str, Any] | None = None, parties: List[int] = None, metadata: Dict[str, Any] | None = None, session: int | None = None) int[source]
Add an incomplete dialog entry to the vCon.
This method creates a dialog entry of type “incomplete” for conversations that failed to be set up. Under core-05 an incomplete Dialog has no content (no body, mediatype, filename, encoding, url or content_hash), and its
partiesis the party that attempted the call, the originator.detailsis kept undermetadata["details"].- Parameters:
start – When the attempt occurred (ISO 8601 string or datetime)
disposition – Reason for the incomplete conversation (for example “no-answer”)
details – Additional details about the failure (optional)
parties – The party (or parties) that attempted the conversation (optional)
metadata – Additional metadata (optional)
session – Optional Session index to add the Dialog to
- Returns:
The index of the new Dialog.
Example
>>> vcon = Vcon.build_new() >>> vcon.add_incomplete_dialog( ... start="2023-01-20T14:00:00Z", ... disposition="no-answer", ... details={"ringDuration": 45000}, ... parties=[0] ... )
- add_lawful_basis_attachment(lawful_basis: str, expiration: str, purpose_grants: list, party_index: int | None = None, dialog_index: int | None = None, session_index: int | List[int] | None = None, **kwargs) None[source]
Add a lawful basis attachment to the vCon.
The attachment has
purpose"lawful_basis". Under core-05 it is scoped withpartyplussession: passsession_index(andparty_index, the party that records the basis). The scope is never widened or invented:dialog_indexalone gives a dialog-only scope (a warning is logged, because 0.5.0 scopes a basis to Sessions), and with neither index the only Session is used when the vCon has exactly one; otherwiseValueErroris raised.partydefaults to 0 with a warning. Thelawful_basisextension name is added toextensions.- Parameters:
lawful_basis – The lawful basis type (consent, contract, etc.)
expiration – ISO 8601 timestamp when the lawful basis expires
purpose_grants – List of purpose grant dictionaries
party_index – Index of the party that records the basis (default 0)
dialog_index – Index of the dialog this applies to (optional)
session_index – Session index or list of indices this applies to (optional)
**kwargs – Additional lawful basis parameters
Example
>>> vcon = Vcon.build_new() >>> vcon.add_party(Party(name="Alice")) >>> vcon.add_session() >>> 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"} ... ] ... )
- add_party(party: Party) None[source]
Add a party to the vCon.
This method adds a party object to the vCon’s parties list. A party represents a participant in the conversation.
- Parameters:
party – The Party object to add
Example
>>> vcon = Vcon.build_new() >>> party = Party(type="person", name="John Doe") >>> vcon.add_party(party)
- add_session(session: Session | Dict[str, Any] | None = None) int[source]
Add a Session Object and return its index in the
sessionsarray.With no argument an empty placeholder Session (
{}) is added, which core-05 permits.Example
>>> vcon = Vcon.build_new() >>> s = vcon.add_session(Session(start="2023-01-01T00:00:00Z", parties=[0, 1]))
- add_tag(tag_name: str, tag_value: str, party: int | None = None) None[source]
Add a tag to the vCon.
This method adds a tag with the specified name and value to the vCon’s tags attachment. If no tags attachment exists, it creates one.
Core-05 requires the attachment’s
partyto be a valid party index (the party that adds the tags). It defaults to 0. On a vCon with no parties this still writes party 0 but warns (DeprecationWarning), because the result failsis_valid(); from vcon 1.1 it will raise.- Parameters:
tag_name – The name of the tag
tag_value – The value to associate with the tag
party – Party index for a new tags attachment (default 0)
- Raises:
ValueError – If
partyis given (or the vCon has parties) and it is not a valid party index
Example
>>> vcon = Vcon.build_new() >>> vcon.add_party(Party(name="Acme Corp")) >>> vcon.add_tag("category", "meeting") >>> vcon.add_tag("priority", "high")
- add_transfer_dialog(*args: Any, **kwargs: Any) None[source]
Removed: core-05 has no transfer Dialog type.
Raises
NotImplementedErrorwith the replacement: a transfer is one or two transfer Events (blind-transfer,consultation-startplusconsultative-transfer, ortransfer-abandoned) added withadd_event(Event(...)), whosesessions/consultation/target_sessionreference Sessions for the calls involved.
- add_wtf_transcription_analysis(transcript: Dict[str, Any], segments: List[Dict[str, Any]], metadata: Dict[str, Any], dialog_index: int | None = None, session_index: int | List[int] | None = None, **kwargs) None[source]
Add a WTF transcription as an analysis entry (vs. an attachment).
This is the placement draft-howe-vcon-wtf-extension requires (section 6.1: transcription results MUST be stored as analysis).
add_wtf_transcription_attachmentwrites to attachments[] and is deprecated.Emits the analysis entry defined by draft-howe-vcon-wtf-extension (section 5.3):
type="wtf_transcription",vendorandproducttaken frommetadata["provider"]/metadata["model"],schemaset to the WTF draft URL,encoding="json", andbodyas the WTF document itself (a JSON value, not a serialized string).- Parameters:
transcript – Transcript information dictionary
segments – List of segment dictionaries
metadata – Metadata dictionary;
providerandmodelkeys map tovendorandproducton the analysis entrydialog_index – Index of the dialog this transcription applies to
session_index – Session index or indices this transcription applies to
**kwargs – Additional WTF parameters (words, speakers, quality, etc.)
- add_wtf_transcription_attachment(transcript: Dict[str, Any], segments: List[Dict[str, Any]], metadata: Dict[str, Any], party_index: int | None = None, dialog_index: int | None = None, session_index: int | List[int] | None = None, **kwargs) None[source]
Add a WTF transcription attachment to the vCon.
Deprecated: draft-howe-vcon-wtf-extension stores transcriptions as analysis (section 6.1). Use
add_wtf_transcription_analysis().Scoped by
dialog_indexand/orsession_indexas given; with neither, the only Session when the vCon has exactly one, elseValueError(seeadd_attachment).- Parameters:
transcript – Transcript information dictionary
segments – List of segment dictionaries
metadata – Metadata dictionary
party_index – Index of the party this applies to (optional)
dialog_index – Index of the dialog this applies to (optional)
session_index – Session index or list of indices (optional)
**kwargs – Additional WTF parameters
Example
>>> vcon = Vcon.build_new() >>> vcon.add_party(Party(name="Alice")) >>> vcon.add_session() >>> 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", "processed_at": "2025-01-01T00:00:01Z", ... "provider": "whisper", "model": "whisper-1"} ... )
- property amended
Deprecated 0.4.0 name; returns
amended_from.
- property amended_from
- property analysis: List[Dict[str, Any]]
Get the list of analysis entries in the vCon.
- Returns:
A list of analysis dictionaries
Example
>>> vcon = Vcon.build_new() >>> vcon.add_analysis(type="sentiment", dialog=[0], vendor="acme", body={"score": 0.8}) >>> analysis = vcon.analysis >>> print(analysis[0]["type"]) # Prints "sentiment"
- property attachments: List[Dict[str, Any]]
Get the list of attachments in the vCon.
- Returns:
A list of attachment dictionaries
Example
>>> vcon = Vcon.build_new() >>> vcon.add_party(Party(name="Alice")) >>> vcon.add_session() >>> vcon.add_attachment("metadata", {"version": "1.0"}) >>> attachments = vcon.attachments >>> print(attachments[0]["purpose"]) # Prints "metadata"
- classmethod build_from_json(json_string: str, property_handling: str = 'default', migrate_legacy: bool = True, strict_migration: bool = False) Vcon[source]
Initialize a Vcon object from a JSON string.
This method parses a JSON string representation of a vCon and creates a new Vcon object from it.
- Parameters:
json_string – A JSON string representing a vCon
property_handling – How to handle non-standard properties.
- Returns:
A new Vcon object initialized with the parsed JSON data
- Raises:
json.JSONDecodeError – If the JSON string is invalid
Example
>>> json_str = '{"uuid": "123"}' >>> vcon = Vcon.build_from_json(json_str)
- classmethod build_new(created_at: str | datetime = None, property_handling: str = 'default') Vcon[source]
Initialize a new Vcon object with default values.
This method creates a new vCon with a generated UUID and initialized with empty arrays for groups, parties, dialog, attachments, and analysis.
- Parameters:
created_at (Union[str, datetime], optional) – The timestamp to set for creation, either as a string in ISO format or as a datetime object. Defaults to current time.
property_handling – How to handle non-standard properties.
- Returns:
A new Vcon object with default values
Example
>>> vcon = Vcon.build_new() >>> print(vcon.uuid) # Prints a new UUID8
- check_lawful_basis_permission(purpose: str, party_index: int | None = None) bool[source]
Check if permission is granted for a specific purpose.
- Parameters:
purpose – The purpose to check permission for
party_index – Index of the party to check (optional)
- Returns:
True if permission is granted, False otherwise
- property created_at
- static decoded_body(entry: Dict[str, Any] | None) Any[source]
Return the decoded
bodyof an attachment, analysis, or dialog entry.Under
draft-ietf-vcon-vcon-core-04, a"json"-encoded body is the JSON value itself, not ajson.dumpsstring. This accepts both that shape and the JSON-string bodies written under -02 conventions (or by this library prior to 0.10.0), so callers don’t need to special-case legacy vCons.- Parameters:
entry – An attachment, analysis, or dialog dictionary
- Returns:
The decoded body, or None if there is no body
Example
>>> vcon = Vcon.build_new() >>> vcon.add_party(Party(name="Alice")) >>> vcon.add_session() >>> vcon.add_tag("category", "meeting") >>> Vcon.decoded_body(vcon.tags) # ["category:meeting"]
- property dialog: List[Dict[str, Any]]
Get the list of dialog entries in the vCon.
- Returns:
A list of dialog dictionaries representing the conversation content. These are mutable references to the internal data structure, allowing in-place modifications.
Example
>>> vcon = Vcon.build_new() >>> vcon.add_dialog(Dialog(type="text", start="2023-01-01T00:00:00Z", parties=[0])) >>> dialog = vcon.dialog >>> print(dialog[0]["type"]) # Prints "text" >>> dialog[0]["body"] = "Modified content" # In-place modification works >>> print(vcon.dialog[0]["body"]) # Prints "Modified content"
- dumps() str[source]
Alias for to_json().
This method is an alias for to_json() and converts the vCon object to a JSON string representation.
- Returns:
A JSON string representation of the vCon
Example
>>> vcon = Vcon.build_new() >>> json_str = vcon.dumps() >>> print(type(json_str)) # Prints "<class 'str'>"
- property events: List[Dict[str, Any]]
The
eventsarray (Event Objects).
- find_analysis_by_type(type: str) Dict[str, Any] | None[source]
Find an analysis entry in the vCon by its type.
This method searches through the vCon’s analysis entries and returns the first one matching the specified type.
- Parameters:
type – The type of analysis to find
- Returns:
The matching analysis dictionary if found, None otherwise
Example
>>> vcon = Vcon.build_new() >>> vcon.add_analysis(type="sentiment", dialog=[0], vendor="acme", body={"score": 0.8}) >>> sentiment = vcon.find_analysis_by_type("sentiment")
- find_attachment_by_purpose(purpose: str) Dict[str, Any] | None[source]
Find an attachment in the vCon by its purpose.
This method searches through the vCon’s attachments and returns the first attachment matching the specified type.
- Parameters:
purpose – The purpose of attachment to find
- Returns:
The matching attachment dictionary if found, None otherwise
Example
>>> vcon = Vcon.build_new() >>> vcon.add_party(Party(name="Alice")) >>> vcon.add_session() >>> vcon.add_attachment("metadata", {"version": "1.0"}) >>> metadata = vcon.find_attachment_by_purpose("metadata")
- find_dialog(by: str, val: str) Dialog | None[source]
Find a dialog entry in the vCon by a key-value pair.
This method searches through the dialog list and returns the first dialog entry that matches the specified key-value pair, converted to a Dialog object.
- Parameters:
by – The key to search by (e.g., “type”, “start”)
val – The value to match
- Returns:
A Dialog object if found, None otherwise
Example
>>> vcon = Vcon.build_new() >>> dialog = Dialog(type="text", start="2023-01-01T00:00:00Z", parties=[0]) >>> vcon.add_dialog(dialog) >>> found = vcon.find_dialog("type", "text") >>> print(found.type) # Prints "text"
- find_dialogs_by_type(type: str) List[Dict[str, Any]][source]
Find all dialog entries in the vCon by type. This method searches through the dialog list and returns all dialog entries matching the specified type. :param type: The type of dialogs to find
- Returns:
A list of matching dialog dictionaries
Example
>>> vcon = Vcon.build_new() >>> incomplete = vcon.find_dialogs_by_type("incomplete")
- find_lawful_basis_attachments(party_index: int | None = None) List[Dict[str, Any]][source]
Find lawful basis attachments in the vCon.
- Parameters:
party_index – Filter by party index (optional)
- Returns:
List of lawful basis attachment dictionaries
- find_party_index(by: str, val: str) int | None[source]
Find the index of a party in the vCon’s parties list.
This method searches through the parties list and returns the index of the first party that matches the specified key-value pair.
- Parameters:
by – The key to search by (e.g., “name”, “type”)
val – The value to match
- Returns:
The index of the matching party if found, None otherwise
Example
>>> vcon = Vcon.build_new() >>> vcon.add_party(Party(type="person", name="John Doe")) >>> index = vcon.find_party_index("name", "John Doe") >>> print(index) # Prints 0
- find_wtf_attachments(party_index: int | None = None) List[Dict[str, Any]][source]
Find WTF transcription attachments in the vCon.
- Parameters:
party_index – Filter by party index (optional)
- Returns:
List of WTF attachment dictionaries
- classmethod generate_key_pair() Tuple[RSAPrivateKey, RSAPublicKey][source]
Generate a new RSA key pair for signing vCons.
This method generates a new RSA key pair that can be used for signing and verifying vCons.
- Returns:
A tuple containing the private key and public key
Example
>>> private_key, public_key = Vcon.generate_key_pair() >>> vcon = Vcon.build_new() >>> vcon.sign(private_key) >>> is_valid = vcon.verify(public_key)
- get_critical() List[str][source]
Get the list of critical extensions that must be supported.
- Returns:
List of extension names that must be supported, empty list if none are defined
Example
>>> vcon = Vcon.build_new() >>> vcon.add_critical("encryption") >>> critical = vcon.get_critical() >>> print(critical) # Prints ["encryption"]
- get_extensions() List[str][source]
Get the list of extensions used in this vCon.
- Returns:
List of extension names, empty list if none are defined
Example
>>> vcon = Vcon.build_new() >>> vcon.add_extension("video") >>> extensions = vcon.get_extensions() >>> print(extensions) # Prints ["video"]
- get_party_objects() List[Party][source]
Get the list of parties as Party objects.
This method creates Party objects from the underlying dictionary data. Use this when you need Party objects instead of raw dictionaries.
- Returns:
A list of Party objects representing all participants in the conversation
Example
>>> vcon = Vcon.build_new() >>> vcon.add_party(Party(type="person", name="John Doe")) >>> party_objects = vcon.get_party_objects() >>> print(party_objects[0].name) # Prints "John Doe"
- get_tag(tag_name: str) str | None[source]
Get the value of a specific tag by name.
- Parameters:
tag_name – The name of the tag to retrieve
- Returns:
The value of the tag if found, None otherwise
Example
>>> vcon = Vcon.build_new() >>> vcon.add_party(Party(name="Alice")) >>> vcon.add_session() >>> vcon.add_tag("category", "meeting") >>> value = vcon.get_tag("category") >>> print(value) # Prints "meeting"
- get_validation_warnings() List[str][source]
SHOULD-level findings (for example SHOULD NOT parameters on Events).
- property group
- is_valid() Tuple[bool, List[str]][source]
Validate the vCon against the core-05 rules.
Checks required fields and types, that
vcon(if present) is “0.5.0”, that Sessions, Events, Dialogs, attachments and analysis reference existing objects, the per-event-type parameter table, that at least one Session exists when there are Dialogs or Events, that attachments havepartyanddialogorsession, thatredacted_fromandamended_fromare exclusive, thatextensionslists every extension in use (and everycriticalentry), that every__REDACTED_REF_#has aredacted_stringsentry, that everyurlhas acontent_hashand everycontent_hashis well formed, and the body of everylawful_basisattachment.SHOULD-level findings are not errors; see
get_validation_warnings().- Returns:
A tuple where the first element is True if the vCon is valid and False otherwise, and the second element is a list of error messages.
- Return type:
Tuple[bool, List[str]]
- classmethod load(source: str, property_handling: str = 'default', migrate_legacy: bool = True, strict_migration: bool = False) Vcon[source]
Load a vCon from either a file path or URL.
- Parameters:
source – File path or URL to load the vCon from
property_handling – How to handle non-standard properties. Options are “default”, “strict”, or “meta”
- Returns:
A Vcon object
- Raises:
ValueError – If the source is invalid or cannot be loaded
requests.RequestException – If there is an error fetching from URL
json.JSONDecodeError – If the source contains invalid JSON
- classmethod load_from_file(file_path: str, property_handling: str = 'default', migrate_legacy: bool = True, strict_migration: bool = False) Vcon[source]
Load a vCon from a file.
- Parameters:
file_path – Path to the vCon JSON file
property_handling – How to handle non-standard properties. Options are “default”, “strict”, or “meta”
- Returns:
A Vcon object
- Raises:
FileNotFoundError – If the file does not exist
json.JSONDecodeError – If the file contains invalid JSON
- classmethod load_from_url(url: str, property_handling: str = 'default', migrate_legacy: bool = True, strict_migration: bool = False) Vcon[source]
Load a vCon from a URL.
- Parameters:
url – URL to fetch the vCon JSON from
property_handling – How to handle non-standard properties. Options are “default”, “strict”, or “meta”
- Returns:
A Vcon object
- Raises:
requests.RequestException – If there is an error fetching from URL
json.JSONDecodeError – If the response contains invalid JSON
- property meta
- classmethod migrate_0_4_0_to_0_5_0(source: str | Dict[str, Any], strict: bool = False, property_handling: str = 'default') Vcon[source]
Explicitly migrate a 0.4.0 vCon (dict or JSON string) and return a Vcon.
The migration report is available as
vcon.migration_report. Unlike the implicit migration on load, this also accepts input with novconparameter. Seevcon.migration.migrate_0_4_0_to_0_5_0().
- migration_report: MigrationReport | None
MigrationReport when the input was migrated from 0.4.0, else None.
- property parties: List[Dict[str, Any]]
Get the list of parties in the vCon.
- Returns:
A list of party dictionaries representing all participants in the conversation. These are mutable references to the internal data structure, allowing in-place modifications.
Example
>>> vcon = Vcon.build_new() >>> vcon.add_party(Party(type="person", name="John Doe")) >>> parties = vcon.parties >>> print(parties[0]["name"]) # Prints "John Doe" >>> parties[0]["name"] = "Jane Doe" # In-place modification works >>> print(vcon.parties[0]["name"]) # Prints "Jane Doe"
- post_to_url(url: str, headers: Dict[str, str] | None = None) Response[source]
Post the vCon as JSON to a URL with optional headers.
- Parameters:
url (str) – The URL to post the vCon to
headers (Optional[Dict[str, str]]) – Optional dictionary of HTTP headers (e.g., {‘x-conserver-api-token’: ‘token123’})
- Returns:
The HTTP response from the server
- Return type:
requests.Response
- Raises:
requests.RequestException – If there is an error making the HTTP request
Example
>>> vcon = Vcon.build_new() >>> response = vcon.post_to_url( ... 'https://api.example.com/vcons', ... headers={'x-conserver-api-token': 'your-token-here'} ... ) >>> print(response.status_code) # Prints HTTP status code (e.g., 200 for success)
- process_extensions() Dict[str, Any][source]
Process all extensions in the vCon.
- Returns:
Dictionary with processing results for each extension
- property redacted
Deprecated 0.4.0 name; returns
redacted_from.
- property redacted_from
- property redacted_strings: List[Dict[str, Any]]
- remove_critical(extension: str) None[source]
Remove an extension from the critical list.
- Parameters:
extension – The name of the extension to remove from critical
Example
>>> vcon = Vcon.build_new() >>> vcon.add_critical("encryption") >>> vcon.remove_critical("encryption")
- remove_extension(extension: str) None[source]
Remove an extension from the vCon.
- Parameters:
extension – The name of the extension to remove
Example
>>> vcon = Vcon.build_new() >>> vcon.add_extension("video") >>> vcon.remove_extension("video")
- save_to_file(file_path: str) None[source]
Save the vCon to a JSON file.
- Parameters:
file_path (str) – Path where the vCon JSON should be saved
- Raises:
IOError – If there is an error writing to the file
- property sessions: List[Dict[str, Any]]
The
sessionsarray (Session Objects).
- set_created_at(created_at: str | datetime) None[source]
Set the created_at field in the vCon.
- Parameters:
created_at (Union[str, datetime]) – The timestamp to set, either as a string in ISO format or as a datetime object.
- set_updated_at(timestamp: str | datetime) None[source]
Set the updated_at timestamp.
Args: timestamp: The timestamp to set, either as ISO 8601 string or datetime object
Example: >>> vcon = Vcon.build_new() >>> vcon.set_updated_at(datetime.now(timezone.utc)) >>> vcon.set_updated_at(“2025-02-18T12:00:00Z”)
- sign(private_key: RSAPrivateKey | bytes, alg: str = 'RS256') None[source]
Sign the vCon using JWS (JSON Web Signature).
This method signs the vCon using the provided private key, adding the signature information to the vCon. The signature can later be verified using the corresponding public key.
- Parameters:
private_key – The RSA private key or its PEM representation
alg – JWS algorithm (default “RS256”, the value core-05 says SHOULD be used). “none” is rejected (6.2.2).
- Raises:
AlgorithmNotPermittedError – If
algis “none” (any case) or is not a permitted algorithm.Exception – If there is an error during the signing process
Example
>>> from cryptography.hazmat.primitives.asymmetric import rsa >>> private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048) >>> vcon = Vcon.build_new() >>> vcon.sign(private_key)
- property subject: str | None
- property tags: Dict[str, Any] | None
Get the tags attachment from the vCon.
- Returns:
The tags attachment dictionary if it exists, None otherwise
Example
>>> vcon = Vcon.build_new() >>> vcon.add_party(Party(name="Alice")) >>> vcon.add_session() >>> vcon.add_tag("category", "meeting") >>> tags = vcon.tags >>> print(tags["body"]) # Prints ["category:meeting"]
- to_dict() Dict[str, Any][source]
Convert the vCon to a dictionary.
This method returns a dictionary representation of the vCon object, which can be used for direct manipulation or inspection.
- Returns:
A dictionary representation of the vCon
Example
>>> vcon = Vcon.build_new() >>> vcon_dict = vcon.to_dict() >>> print(vcon_dict["vcon"]) # Prints "0.5.0"
- to_json() str[source]
Serialize the vCon to a JSON string.
This method converts the entire vCon object to a JSON string representation, which can be used for storage or transmission.
- Returns:
A JSON string representation of the vCon
Example
>>> vcon = Vcon.build_new() >>> json_str = vcon.to_json() >>> print(type(json_str)) # Prints "<class 'str'>"
- property updated_at
- property uuid: str
- validate_extensions() Dict[str, Any][source]
Validate all extensions in the vCon.
- Returns:
Dictionary with validation results for each extension
- static validate_file(file_path: str) tuple[bool, list[str]][source]
Validate a vCon file at the given path.
- Parameters:
file_path (str) – Path to the vCon JSON file
- Returns:
A tuple containing (is_valid, list_of_errors)
- Return type:
tuple[bool, list[str]]
- static validate_json(json_str: str) tuple[bool, list[str]][source]
Validate a vCon from a JSON string.
- Parameters:
json_str (str) – JSON string representing a vCon
- Returns:
A tuple containing (is_valid, list_of_errors)
- Return type:
tuple[bool, list[str]]
- property vcon: str | None
- verify(public_key: RSAPublicKey | bytes) bool[source]
Verify the JWS signature of the vCon.
This method verifies the vCon’s signature using the provided public key. The vCon must have been previously signed using the corresponding private key.
- Parameters:
public_key – The RSA public key or its PEM representation
- Returns:
True if the signature is valid, False otherwise
- Raises:
ValueError – If the vCon is not signed
AlgorithmNotPermittedError – If the signature declares
alg“none” (in the protected header or the signature’s header), which core-05 forbids. Verification is refused rather than skipped.
Example
>>> private_key, public_key = Vcon.generate_key_pair() >>> vcon = Vcon.build_new() >>> vcon.sign(private_key) >>> is_valid = vcon.verify(public_key) >>> print(is_valid) # Prints True