Source code for vcon.extensions.wtf.validation

"""
Validation for WTF Extension

This module implements validation logic for WTF transcription attachments
according to the draft specification.
"""

from typing import Dict, List, Any, Optional
import logging
from ..base import ExtensionValidator, ValidationResult
from ...body import decode_body
from .attachment import WTFAttachment, WTFProvider

logger = logging.getLogger(__name__)


[docs]class WTFValidator(ExtensionValidator): """Validator for WTF extension.""" def __init__(self): self.supported_providers = {provider.value for provider in WTFProvider} self.valid_audio_qualities = ["high", "medium", "low"]
[docs] def validate_attachment(self, attachment: Dict[str, Any]) -> ValidationResult: """Validate a WTF transcription attachment.""" result = ValidationResult(True) # Check attachment type if attachment.get("purpose") != "wtf_transcription": result.add_error("Invalid attachment purpose for WTF extension") return result # Check encoding if attachment.get("encoding") != "json": result.add_error("WTF transcription attachment must use 'json' encoding") # Validate body structure. Accept both the -04 shape (body already # the decoded object) and a legacy JSON-string body. body = decode_body(attachment) if not isinstance(body, dict): result.add_error("WTF transcription attachment body must be a dictionary") return result # Validate required fields body_result = self._validate_wtf_body(body) if not body_result.is_valid: result.errors.extend(body_result.errors) result.warnings.extend(body_result.warnings) result.is_valid = False return result
[docs] def validate_extension_usage(self, vcon_dict: Dict[str, Any]) -> ValidationResult: """Validate WTF extension usage in a vCon.""" result = ValidationResult(True) # Check if extension is declared extensions = vcon_dict.get("extensions", []) if "wtf_transcription" not in extensions: result.add_warning("WTF transcription extension not declared in extensions array") # Validate all WTF transcription attachments attachments = vcon_dict.get("attachments", []) wtf_attachments = [ att for att in attachments if att.get("purpose") == "wtf_transcription" ] for i, attachment in enumerate(wtf_attachments): att_result = self.validate_attachment(attachment) if not att_result.is_valid: result.add_error(f"WTF transcription attachment {i}: {', '.join(att_result.errors)}") result.is_valid = False result.warnings.extend([f"Attachment {i}: {w}" for w in att_result.warnings]) return result
def _validate_wtf_body(self, body: Dict[str, Any]) -> ValidationResult: """Validate the body of a WTF transcription attachment.""" result = ValidationResult(True) # Validate required fields required_fields = ["transcript", "segments", "metadata"] for field in required_fields: if field not in body: result.add_error(f"Missing required field: {field}") # Validate transcript if "transcript" in body: transcript_result = self._validate_transcript(body["transcript"]) if not transcript_result.is_valid: result.add_error(f"Transcript validation failed: {', '.join(transcript_result.errors)}") result.is_valid = False # Validate segments if "segments" in body: segments_result = self._validate_segments(body["segments"]) if not segments_result.is_valid: result.add_error(f"Segments validation failed: {', '.join(segments_result.errors)}") result.is_valid = False # Validate metadata if "metadata" in body: metadata_result = self._validate_metadata(body["metadata"]) if not metadata_result.is_valid: result.add_error(f"Metadata validation failed: {', '.join(metadata_result.errors)}") result.is_valid = False # Validate optional fields if "words" in body: words_result = self._validate_words(body["words"]) if not words_result.is_valid: result.add_error(f"Words validation failed: {', '.join(words_result.errors)}") result.is_valid = False if "speakers" in body: speakers_result = self._validate_speakers(body["speakers"]) if not speakers_result.is_valid: result.add_error(f"Speakers validation failed: {', '.join(speakers_result.errors)}") result.is_valid = False if "quality" in body: quality_result = self._validate_quality(body["quality"]) if not quality_result.is_valid: result.add_error(f"Quality validation failed: {', '.join(quality_result.errors)}") result.is_valid = False return result def _validate_transcript(self, transcript: Dict[str, Any]) -> ValidationResult: """Validate transcript object.""" result = ValidationResult(True) required_fields = ["text", "language", "duration", "confidence"] for field in required_fields: if field not in transcript: result.add_error(f"Missing required field in transcript: {field}") # Validate text if "text" in transcript: if not isinstance(transcript["text"], str): result.add_error("Transcript text must be a string") # Validate language (BCP-47 format) if "language" in transcript: language = transcript["language"] if not isinstance(language, str) or len(language) < 2: result.add_error("Invalid language code format") # Validate duration if "duration" in transcript: duration = transcript["duration"] if not isinstance(duration, (int, float)) or duration < 0: result.add_error("Duration must be a non-negative number") # Validate confidence if "confidence" in transcript: confidence = transcript["confidence"] if not isinstance(confidence, (int, float)) or not (0.0 <= confidence <= 1.0): result.add_error("Confidence must be a number between 0.0 and 1.0") return result def _validate_segments(self, segments: List[Dict[str, Any]]) -> ValidationResult: """Validate segments array.""" result = ValidationResult(True) if not isinstance(segments, list): result.add_error("Segments must be a list") return result if not segments: result.add_error("At least one segment is required") return result # Validate each segment for i, segment in enumerate(segments): segment_result = self._validate_segment(segment) if not segment_result.is_valid: result.add_error(f"Segment {i}: {', '.join(segment_result.errors)}") result.is_valid = False return result def _validate_segment(self, segment: Dict[str, Any]) -> ValidationResult: """Validate a single segment.""" result = ValidationResult(True) required_fields = ["id", "start", "end", "text", "confidence"] for field in required_fields: if field not in segment: result.add_error(f"Missing required field in segment: {field}") # Validate id if "id" in segment: if not isinstance(segment["id"], int): result.add_error("Segment id must be an integer") # Validate timestamps if "start" in segment and "end" in segment: start = segment["start"] end = segment["end"] if not isinstance(start, (int, float)) or not isinstance(end, (int, float)): result.add_error("Segment start and end must be numbers") elif start >= end: result.add_error("Segment start must be less than end") # Validate text if "text" in segment: if not isinstance(segment["text"], str): result.add_error("Segment text must be a string") # Validate confidence if "confidence" in segment: confidence = segment["confidence"] if not isinstance(confidence, (int, float)) or not (0.0 <= confidence <= 1.0): result.add_error("Segment confidence must be a number between 0.0 and 1.0") return result def _validate_metadata(self, metadata: Dict[str, Any]) -> ValidationResult: """Validate metadata object.""" result = ValidationResult(True) required_fields = ["created_at", "processed_at", "provider", "model"] for field in required_fields: if field not in metadata: result.add_error(f"Missing required field in metadata: {field}") # Validate timestamps for field in ["created_at", "processed_at"]: if field in metadata: try: from datetime import datetime datetime.fromisoformat(metadata[field].replace('Z', '+00:00')) except ValueError: result.add_error(f"Invalid timestamp format in {field}") # Validate provider if "provider" in metadata: provider = metadata["provider"] if provider not in self.supported_providers: result.add_warning(f"Unknown provider: {provider}") # Validate model if "model" in metadata: if not isinstance(metadata["model"], str): result.add_error("Model must be a string") return result def _validate_words(self, words: List[Dict[str, Any]]) -> ValidationResult: """Validate words array.""" result = ValidationResult(True) if not isinstance(words, list): result.add_error("Words must be a list") return result # Validate each word for i, word in enumerate(words): word_result = self._validate_word(word) if not word_result.is_valid: result.add_error(f"Word {i}: {', '.join(word_result.errors)}") result.is_valid = False return result def _validate_word(self, word: Dict[str, Any]) -> ValidationResult: """Validate a single word.""" result = ValidationResult(True) required_fields = ["id", "start", "end", "text", "confidence"] for field in required_fields: if field not in word: result.add_error(f"Missing required field in word: {field}") # Validate id if "id" in word: if not isinstance(word["id"], int): result.add_error("Word id must be an integer") # Validate timestamps if "start" in word and "end" in word: start = word["start"] end = word["end"] if not isinstance(start, (int, float)) or not isinstance(end, (int, float)): result.add_error("Word start and end must be numbers") elif start >= end: result.add_error("Word start must be less than end") # Validate text if "text" in word: if not isinstance(word["text"], str): result.add_error("Word text must be a string") # Validate confidence if "confidence" in word: confidence = word["confidence"] if not isinstance(confidence, (int, float)) or not (0.0 <= confidence <= 1.0): result.add_error("Word confidence must be a number between 0.0 and 1.0") return result def _validate_speakers(self, speakers: Dict[str, Any]) -> ValidationResult: """Validate speakers object.""" result = ValidationResult(True) if not isinstance(speakers, dict): result.add_error("Speakers must be a dictionary") return result # Validate each speaker for speaker_id, speaker_data in speakers.items(): speaker_result = self._validate_speaker(speaker_data) if not speaker_result.is_valid: result.add_error(f"Speaker {speaker_id}: {', '.join(speaker_result.errors)}") result.is_valid = False return result def _validate_speaker(self, speaker: Dict[str, Any]) -> ValidationResult: """Validate a single speaker.""" result = ValidationResult(True) required_fields = ["id", "label", "segments", "total_time", "confidence"] for field in required_fields: if field not in speaker: result.add_error(f"Missing required field in speaker: {field}") # Validate segments if "segments" in speaker: if not isinstance(speaker["segments"], list): result.add_error("Speaker segments must be a list") # Validate total_time if "total_time" in speaker: total_time = speaker["total_time"] if not isinstance(total_time, (int, float)) or total_time < 0: result.add_error("Speaker total_time must be a non-negative number") # Validate confidence if "confidence" in speaker: confidence = speaker["confidence"] if not isinstance(confidence, (int, float)) or not (0.0 <= confidence <= 1.0): result.add_error("Speaker confidence must be a number between 0.0 and 1.0") return result def _validate_quality(self, quality: Dict[str, Any]) -> ValidationResult: """Validate quality object.""" result = ValidationResult(True) required_fields = [ "audio_quality", "background_noise", "multiple_speakers", "overlapping_speech", "silence_ratio", "average_confidence", "low_confidence_words", "processing_warnings" ] for field in required_fields: if field not in quality: result.add_error(f"Missing required field in quality: {field}") # Validate audio_quality if "audio_quality" in quality: audio_quality = quality["audio_quality"] if audio_quality not in self.valid_audio_qualities: result.add_error(f"Invalid audio_quality: {audio_quality}") # Validate background_noise if "background_noise" in quality: noise = quality["background_noise"] if not isinstance(noise, (int, float)) or not (0.0 <= noise <= 1.0): result.add_error("Background noise must be a number between 0.0 and 1.0") # Validate boolean fields for field in ["multiple_speakers", "overlapping_speech"]: if field in quality: if not isinstance(quality[field], bool): result.add_error(f"{field} must be a boolean") # Validate silence_ratio if "silence_ratio" in quality: ratio = quality["silence_ratio"] if not isinstance(ratio, (int, float)) or not (0.0 <= ratio <= 1.0): result.add_error("Silence ratio must be a number between 0.0 and 1.0") # Validate average_confidence if "average_confidence" in quality: confidence = quality["average_confidence"] if not isinstance(confidence, (int, float)) or not (0.0 <= confidence <= 1.0): result.add_error("Average confidence must be a number between 0.0 and 1.0") # Validate low_confidence_words if "low_confidence_words" in quality: count = quality["low_confidence_words"] if not isinstance(count, int) or count < 0: result.add_error("Low confidence words count must be a non-negative integer") # Validate processing_warnings if "processing_warnings" in quality: warnings = quality["processing_warnings"] if not isinstance(warnings, list): result.add_error("Processing warnings must be a list") elif not all(isinstance(w, str) for w in warnings): result.add_error("All processing warnings must be strings") return result
[docs] def validate_wtf_attachment(self, attachment: WTFAttachment) -> ValidationResult: """Validate a WTFAttachment object.""" result = ValidationResult(True) # Validate transcript if not attachment.transcript.text: result.add_error("Transcript text cannot be empty") if attachment.transcript.duration <= 0: result.add_error("Transcript duration must be positive") if not (0.0 <= attachment.transcript.confidence <= 1.0): result.add_error("Transcript confidence must be between 0.0 and 1.0") # Validate segments if not attachment.segments: result.add_error("At least one segment is required") # Check segment consistency for i, segment in enumerate(attachment.segments): if segment.start >= segment.end: result.add_error(f"Segment {i}: start time must be less than end time") if not (0.0 <= segment.confidence <= 1.0): result.add_error(f"Segment {i}: confidence must be between 0.0 and 1.0") # Validate words if present if attachment.words: for i, word in enumerate(attachment.words): if word.start >= word.end: result.add_error(f"Word {i}: start time must be less than end time") if not (0.0 <= word.confidence <= 1.0): result.add_error(f"Word {i}: confidence must be between 0.0 and 1.0") return result