lattifai 1.2.1__py3-none-any.whl → 1.3.0__py3-none-any.whl

lattifai/cli/youtube.py

@@ -11,6 +11,7 @@ from lattifai.config import (
     CaptionConfig,
     ClientConfig,
     DiarizationConfig,
+    EventConfig,
     MediaConfig,
     TranscriptionConfig,
 )
@@ -25,6 +26,7 @@ def youtube(
     caption: Annotated[Optional[CaptionConfig], run.Config[CaptionConfig]] = None,
     transcription: Annotated[Optional[TranscriptionConfig], run.Config[TranscriptionConfig]] = None,
     diarization: Annotated[Optional[DiarizationConfig], run.Config[DiarizationConfig]] = None,
+    event: Annotated[Optional[EventConfig], run.Config[EventConfig]] = None,
     use_transcription: bool = False,
 ):
     """
@@ -44,7 +46,8 @@ def youtube(
     Args:
         yt_url: YouTube video URL (can be provided as positional argument)
         media: Media configuration for controlling formats and output directories.
-            Fields: input_path (YouTube URL), output_dir, output_format, force_overwrite
+            Fields: input_path (YouTube URL), output_dir, output_format, force_overwrite,
+                    audio_track_id (default: "original"), quality (default: "best")
         client: API client configuration.
             Fields: api_key, timeout, max_retries
         alignment: Alignment configuration (model selection and inference settings).
@@ -113,6 +116,7 @@ def youtube(
         caption_config=caption_config,
         transcription_config=transcription,
         diarization_config=diarization,
+        event_config=event,
     )
 
     # Call the client's youtube method
@@ -129,6 +133,8 @@ def youtube(
         channel_selector=media_config.channel_selector,
         streaming_chunk_secs=media_config.streaming_chunk_secs,
         use_transcription=use_transcription,
+        audio_track_id=media_config.audio_track_id,
+        quality=media_config.quality,
     )
 
 

lattifai/client.py

@@ -9,8 +9,16 @@ from lhotse.utils import Pathlike
 
 from lattifai.alignment import Lattice1Aligner, Segmenter
 from lattifai.audio2 import AudioData, AudioLoader
-from lattifai.caption import Caption, InputCaptionFormat
-from lattifai.config import AlignmentConfig, CaptionConfig, ClientConfig, DiarizationConfig, TranscriptionConfig
+from lattifai.caption import InputCaptionFormat
+from lattifai.config import (
+    AlignmentConfig,
+    CaptionConfig,
+    ClientConfig,
+    DiarizationConfig,
+    EventConfig,
+    TranscriptionConfig,
+)
+from lattifai.data import Caption
 from lattifai.errors import (
     AlignmentError,
     CaptionProcessingError,
@@ -22,6 +30,7 @@ from lattifai.utils import safe_print
 
 if TYPE_CHECKING:
     from lattifai.diarization import LattifAIDiarizer  # noqa: F401
+    from lattifai.event import LattifAIEventDetector  # noqa: F401
 
 
 class LattifAI(LattifAIClientMixin, SyncAPIClient):
@@ -41,6 +50,7 @@ class LattifAI(LattifAIClientMixin, SyncAPIClient):
         caption_config: Optional[CaptionConfig] = None,
         transcription_config: Optional[TranscriptionConfig] = None,
         diarization_config: Optional[DiarizationConfig] = None,
+        event_config: Optional[EventConfig] = None,
     ) -> None:
         __doc__ = LattifAIClientMixin._INIT_DOC.format(
             client_class="LattifAI",
@@ -59,8 +69,8 @@ class LattifAI(LattifAIClientMixin, SyncAPIClient):
         self.config = client_config
 
         # Initialize all configs with defaults
-        alignment_config, transcription_config, diarization_config = self._init_configs(
-            alignment_config, transcription_config, diarization_config
+        alignment_config, transcription_config, diarization_config, event_config = self._init_configs(
+            alignment_config, transcription_config, diarization_config, event_config
         )
 
         # Store configs
@@ -82,6 +92,14 @@ class LattifAI(LattifAIClientMixin, SyncAPIClient):
 
             self.diarizer = LattifAIDiarizer(config=self.diarization_config)
 
+        # Initialize event detector if enabled
+        self.event_config = event_config
+        self.event_detector: Optional["LattifAIEventDetector"] = None
+        if self.event_config.enabled:
+            from lattifai.event import LattifAIEventDetector  # noqa: F811
+
+            self.event_detector = LattifAIEventDetector(config=self.event_config)
+
         # Initialize shared components (transcriber, downloader)
         self._init_shared_components(transcription_config)
 
@@ -123,9 +141,16 @@ class LattifAI(LattifAIClientMixin, SyncAPIClient):
             alignment_strategy = self.aligner.config.strategy
 
             if alignment_strategy != "entire" or caption.transcription:
-                safe_print(colorful.cyan(f"🔄 Using segmented alignment strategy: {alignment_strategy}"))
+                safe_print(colorful.cyan(f"🔄   Using segmented alignment strategy: {alignment_strategy}"))
 
                 if caption.supervisions and alignment_strategy == "transcription":
+                    from lattifai.alignment.text_align import align_supervisions_and_transcription
+
+                    if "gemini" in self.transcriber.name.lower():
+                        raise ValueError(
+                            f"Transcription-based alignment is not supported for {self.transcriber.name} "
+                            "(Gemini's timestamp is not reliable)."
+                        )
                     if not caption.transcription:
                         transcript = self._transcribe(
                             media_audio,
@@ -134,118 +159,30 @@ class LattifAI(LattifAIClientMixin, SyncAPIClient):
                             output_dir=Path(str(output_caption_path)).parent if output_caption_path else None,
                         )
                         caption.transcription = transcript.supervisions or transcript.transcription
-                        caption.audio_events = transcript.audio_events
-                    assert caption.transcription, "Transcription is empty after transcription step."
-
-                    # Align caption.supervisions with transcription to get segments
-                    import regex
-                    from error_align import error_align  # noqa: F401
-                    from error_align.utils import DELIMITERS, NUMERIC_TOKEN, STANDARD_TOKEN, OpType
-
-                    JOIN_TOKEN = "❄"
-                    if JOIN_TOKEN not in DELIMITERS:
-                        DELIMITERS.add(JOIN_TOKEN)
-
-                    def custom_tokenizer(text: str) -> list:
-                        """Default tokenizer that splits text into words based on whitespace.
-
-                        Args:
-                            text (str): The input text to tokenize.
-
-                        Returns:
-                            list: A list of tokens (words).
-
-                        """
-                        # Escape JOIN_TOKEN for use in regex pattern
-                        escaped_join_token = regex.escape(JOIN_TOKEN)
-                        return list(
-                            regex.finditer(
-                                rf"({NUMERIC_TOKEN})|({STANDARD_TOKEN}|{escaped_join_token})",
-                                text,
-                                regex.UNICODE | regex.VERBOSE,
-                            )
-                        )
+                        caption.event = transcript.event
+                    if not caption.transcription:
+                        raise ValueError("Transcription is empty after transcription step.")
 
                     if split_sentence or self.caption_config.split_sentence:
                         caption.supervisions = self.aligner.tokenizer.split_sentences(caption.supervisions)
 
-                    ref = f"{JOIN_TOKEN}".join(sup.text for sup in caption.supervisions)
-                    hyp = f"{JOIN_TOKEN}".join(sup.text for sup in caption.transcription)
-                    alignments = error_align(ref, hyp, tokenizer=custom_tokenizer)
-
-                    idx = 0
-                    for k, align in enumerate(alignments):
-                        if align.hyp == JOIN_TOKEN and align.op_type == OpType.MATCH:
-                            # safe_print(f"Segment {k}: JOIN_TOKEN detected, creating segment.")
-
-                            # Find first non-None ref_slice starting from idx
-                            ref_start = 0
-                            for i in range(idx, k + 1):
-                                if i < len(alignments) and alignments[i].ref_slice is not None:
-                                    ref_start = alignments[i].ref_slice.start
-                                    break
-
-                            # Find last non-None ref_slice up to current position
-                            ref_stop = len(ref)
-                            for i in range(k, idx - 1, -1):
-                                if i < len(alignments) and alignments[i].ref_slice is not None:
-                                    ref_stop = alignments[i].ref_slice.stop
-                                    break
-
-                            # Find first non-None hyp_slice starting from idx
-                            hyp_start = 0
-                            for i in range(idx, k + 1):
-                                if i < len(alignments) and alignments[i].hyp_slice is not None:
-                                    hyp_start = alignments[i].hyp_slice.start
-                                    break
-
-                            # Find last non-None hyp_slice up to current position
-                            hyp_stop = len(hyp)
-                            for i in range(k, idx - 1, -1):
-                                if i < len(alignments) and alignments[i].hyp_slice is not None:
-                                    hyp_stop = alignments[i].hyp_slice.stop
-                                    break
-
-                            safe_print(f"[REF]: {ref[ref_start:ref_stop]}")
-                            safe_print(f"[HYP]: {hyp[hyp_start:hyp_stop]}\n")
-                            idx = k + 1
-
-                    # last part - handle remaining alignments after last JOIN_TOKEN
-                    if idx < len(alignments):
-                        # Find first non-None ref_slice starting from idx
-                        ref_start = 0
-                        for i in range(idx, len(alignments)):
-                            if alignments[i].ref_slice is not None:
-                                ref_start = alignments[i].ref_slice.start
-                                break
-
-                        # Find last non-None ref_slice from end
-                        ref_stop = len(ref)
-                        for i in range(len(alignments) - 1, idx - 1, -1):
-                            if alignments[i].ref_slice is not None:
-                                ref_stop = alignments[i].ref_slice.stop
-                                break
-
-                        # Find first non-None hyp_slice starting from idx
-                        hyp_start = 0
-                        for i in range(idx, len(alignments)):
-                            if alignments[i].hyp_slice is not None:
-                                hyp_start = alignments[i].hyp_slice.start
-                                break
-
-                        # Find last non-None hyp_slice from end
-                        hyp_stop = len(hyp)
-                        for i in range(len(alignments) - 1, idx - 1, -1):
-                            if alignments[i].hyp_slice is not None:
-                                hyp_stop = alignments[i].hyp_slice.stop
-                                break
-
-                        safe_print(f"[REF]: {ref[ref_start:ref_stop + 1]}")
-                        safe_print(f"[HYP]: {hyp[hyp_start:hyp_stop + 1]}\n")
-
-                    raise NotImplementedError("Transcription-based segmentation is not yet implemented.")
+                    matches = align_supervisions_and_transcription(
+                        caption, max_duration=media_audio.duration, verbose=True
+                    )
+
+                    skipalign = False
+                    matches = sorted(matches, key=lambda x: x[2].WER.WER)  # sort by WER
+                    segments = [(m[3].start[1], m[3].end[1], m, skipalign) for m in matches]
+                    for segment in segments:
+                        # transcription segments -> sentence splitting
+                        segment[2][1] = self.aligner.tokenizer.split_sentences(segment[2][1])
                 else:
                     if caption.transcription:
+                        if "gemini" in self.transcriber.name.lower():
+                            raise ValueError(
+                                f"Transcription-based alignment is not supported for {self.transcriber.name} "
+                                "(Gemini's timestamp is not reliable)."
+                            )
                         if not caption.supervisions:  # youtube + transcription case
                             segments = [(sup.start, sup.end, [sup], not sup.text) for sup in caption.transcription]
                         else:
@@ -266,7 +203,7 @@ class LattifAI(LattifAIClientMixin, SyncAPIClient):
                 sr = media_audio.sampling_rate
                 supervisions, alignments = [], []
                 for i, (start, end, _supervisions, skipalign) in enumerate(segments, 1):
-                    print(
+                    safe_print(
                         colorful.green(
                             f"  ⏩ aligning segment {i:04d}/{len(segments):04d}: {start:8.2f}s - {end:8.2f}s"
                         )
@@ -286,8 +223,7 @@ class LattifAI(LattifAIClientMixin, SyncAPIClient):
                         media_audio,
                         _supervisions,
                         split_sentence=split_sentence or self.caption_config.split_sentence,
-                        return_details=self.caption_config.word_level
-                        or (output_caption_path and str(output_caption_path).endswith(".TextGrid")),
+                        return_details=True,
                         emission=emission,
                         offset=offset,
                         verbose=False,
@@ -295,14 +231,16 @@ class LattifAI(LattifAIClientMixin, SyncAPIClient):
 
                     supervisions.extend(_supervisions)
                     alignments.extend(_alignments)
+
+                # sort by start
+                alignments = sorted(alignments, key=lambda x: x.start)
             else:
                 # Step 2-4: Standard single-pass alignment
                 supervisions, alignments = self.aligner.alignment(
                     media_audio,
                     caption.supervisions,
                     split_sentence=split_sentence or self.caption_config.split_sentence,
-                    return_details=self.caption_config.word_level
-                    or (output_caption_path and str(output_caption_path).endswith(".TextGrid")),
+                    return_details=True,
                 )
 
             # Update caption with aligned results
@@ -316,13 +254,15 @@ class LattifAI(LattifAIClientMixin, SyncAPIClient):
             if self.config.profile:
                 self.aligner.profile()
 
-        except (CaptionProcessingError, LatticeEncodingError, AlignmentError, LatticeDecodingError):
+        except (CaptionProcessingError, LatticeEncodingError) as e:
             # Re-raise our specific errors as-is
-            raise
+            raise e
+        except LatticeDecodingError as e:
+            raise e
         except Exception as e:
             # Catch any unexpected errors and wrap them
             raise AlignmentError(
-                "Unexpected error during alignment process",
+                message="Unexpected error during alignment process",
                 media_path=str(input_media),
                 caption_path=str(input_caption),
                 context={"original_error": str(e), "error_type": e.__class__.__name__},
@@ -337,6 +277,13 @@ class LattifAI(LattifAIClientMixin, SyncAPIClient):
                 output_caption_path=output_caption_path,
             )
 
+        # Step 6: Event detection
+        if self.event_config.enabled and self.event_detector:
+            safe_print(colorful.cyan("🔊 Performing audio event detection..."))
+            caption = self.event_detector.detect_and_update_caption(caption, media_audio)
+            if output_caption_path:
+                self._write_caption(caption, output_caption_path)
+
         return caption
 
     def speaker_diarization(
@@ -367,12 +314,12 @@ class LattifAI(LattifAIClientMixin, SyncAPIClient):
             diarization_file = Path(str(output_caption_path)).with_suffix(".SpkDiar")
             if diarization_file.exists():
                 safe_print(colorful.cyan(f"Reading existing speaker diarization from {diarization_file}"))
-                caption.read_speaker_diarization(diarization_file)
+                caption.read_diarization(diarization_file)
 
         diarization, alignments = self.diarizer.diarize_with_alignments(
             input_media,
             caption.alignments,
-            diarization=caption.speaker_diarization,
+            diarization=caption.diarization,
             alignment_fn=self.aligner.alignment,
             transcribe_fn=self.transcriber.transcribe_numpy if self.transcriber else None,
             separate_fn=self.aligner.separate if self.aligner.worker.separator_ort else None,
@@ -380,7 +327,7 @@ class LattifAI(LattifAIClientMixin, SyncAPIClient):
             output_path=output_caption_path,
         )
         caption.alignments = alignments
-        caption.speaker_diarization = diarization
+        caption.diarization = diarization
 
         # Write output if requested
         if output_caption_path:
@@ -400,6 +347,8 @@ class LattifAI(LattifAIClientMixin, SyncAPIClient):
         use_transcription: bool = False,
         channel_selector: Optional[str | int] = "average",
         streaming_chunk_secs: Optional[float] = None,
+        audio_track_id: Optional[str] = "original",
+        quality: str = "best",
     ) -> Caption:
         # Prepare output directory and media format
         output_dir = self._prepare_youtube_output_dir(output_dir)
@@ -408,7 +357,7 @@ class LattifAI(LattifAIClientMixin, SyncAPIClient):
         safe_print(colorful.cyan(f"🎬 Starting YouTube workflow for: {url}"))
 
         # Step 1: Download media
-        media_file = self._download_media_sync(url, output_dir, media_format, force_overwrite)
+        media_file = self._download_media_sync(url, output_dir, media_format, force_overwrite, audio_track_id, quality)
 
         media_audio = self.audio_loader(
             media_file, channel_selector=channel_selector, streaming_chunk_secs=streaming_chunk_secs

lattifai/config/__init__.py

@@ -1,16 +1,44 @@
 """Configuration system for LattifAI using nemo_run."""
 
+# Re-export caption config classes from lattifai-captions package
+from lattifai.caption.config import (
+    ALL_CAPTION_FORMATS,
+    CAPTION_FORMATS,
+    INPUT_CAPTION_FORMATS,
+    OUTPUT_CAPTION_FORMATS,
+    CaptionFonts,
+    CaptionStyle,
+    InputCaptionFormat,
+    KaraokeConfig,
+    OutputCaptionFormat,
+    StandardizationConfig,
+)
+
 from .alignment import AlignmentConfig
+
+# CaptionConfig is defined in lattifai-python (workflow config)
 from .caption import CaptionConfig
 from .client import ClientConfig
 from .diarization import DiarizationConfig
+from .event import EventConfig
 from .media import AUDIO_FORMATS, MEDIA_FORMATS, VIDEO_FORMATS, MediaConfig
 from .transcription import TranscriptionConfig
 
 __all__ = [
+    "EventConfig",
     "ClientConfig",
     "AlignmentConfig",
     "CaptionConfig",
+    "CaptionFonts",
+    "CaptionStyle",
+    "KaraokeConfig",
+    "StandardizationConfig",
+    "InputCaptionFormat",
+    "OutputCaptionFormat",
+    "INPUT_CAPTION_FORMATS",
+    "OUTPUT_CAPTION_FORMATS",
+    "ALL_CAPTION_FORMATS",
+    "CAPTION_FORMATS",
     "TranscriptionConfig",
     "DiarizationConfig",
     "MediaConfig",

lattifai/config/alignment.py

@@ -93,6 +93,20 @@ class AlignmentConfig:
     Default: 0.20. Typical range: 0.0-0.5.
     """
 
+    boost: float = 5.0
+    """Boost for preferring supervisions over transcription in diff alignment decoding graph.
+    A positive value encourages the decoder to prefer supervision text over ASR transcription.
+    Only effective when strategy='transcription'. Has no effect with 'entire' or 'caption' strategies.
+    Default: 5.0. Typical range: 0.0-10.0.
+    """
+
+    transition_penalty: float = 0.0
+    """Penalty for token transitions in the decoding graph to discourage duration=1 tokens.
+    A negative value penalizes transitions (moving to next token), making the model prefer
+    self-loops (staying on current token longer). This helps prevent spurious short-duration alignments.
+    Default: 0.0 (no penalty). Typical range: -1.0 to 0.0 (e.g., -0.5).
+    """
+
     client_wrapper: Optional["SyncAPIClient"] = field(default=None, repr=False)
     """Reference to the SyncAPIClient instance. Auto-set during client initialization."""
 

lattifai/config/caption.py

@@ -1,28 +1,18 @@
-"""Caption I/O configuration for LattifAI."""
+"""Caption I/O configuration for LattifAI SDK."""
 
 from dataclasses import dataclass
 from pathlib import Path
-from typing import TYPE_CHECKING, Literal, Optional
+from typing import Optional
 
-from lhotse.utils import Pathlike
-
-# Supported caption formats for reading/writing
-CAPTION_FORMATS = ["srt", "vtt", "ass", "ssa", "sub", "sbv", "txt", "md", "ttml", "sami", "smi"]
-
-# Input caption formats (includes special formats like 'auto' and 'gemini')
-INPUT_CAPTION_FORMATS = ["srt", "vtt", "ass", "ssa", "sub", "sbv", "txt", "ttml", "sami", "smi", "auto", "gemini"]
-
-# Output caption formats (includes special formats like 'TextGrid' and 'json')
-OUTPUT_CAPTION_FORMATS = ["srt", "vtt", "ass", "ssa", "sub", "sbv", "txt", "ttml", "sami", "smi", "TextGrid", "json"]
-
-# All caption formats combined (for file detection)
-ALL_CAPTION_FORMATS = list(set(CAPTION_FORMATS + ["TextGrid", "json", "gemini"]))
-
-# Type aliases for better type hints
-InputCaptionFormat = Literal["auto", "srt", "vtt", "ass", "ssa", "sub", "sbv", "txt", "ttml", "sami", "smi", "gemini"]
-OutputCaptionFormat = Literal[
-    "srt", "vtt", "ass", "ssa", "sub", "sbv", "txt", "ttml", "sami", "smi", "TextGrid", "json"
-]
+from lattifai.caption.config import (
+    INPUT_CAPTION_FORMATS,
+    OUTPUT_CAPTION_FORMATS,
+    InputCaptionFormat,
+    KaraokeConfig,
+    OutputCaptionFormat,
+    StandardizationConfig,
+)
+from lattifai.caption.supervision import Pathlike
 
 
 @dataclass
@@ -34,13 +24,20 @@ class CaptionConfig:
     """
 
     input_format: InputCaptionFormat = "auto"
-    """Input caption format: 'auto', 'srt', 'vtt', 'ass', 'txt', or 'json'."""
+    """Input caption format. Supports: 'auto' (detect),
+        standard formats (srt, vtt, ass, ssa, sub, sbv, txt, sami, smi),
+        tabular (csv, tsv, aud, json),
+        specialized (textgrid, gemini),
+        NLE (avid_ds, fcpxml, premiere_xml, audition_csv).
+        Note: VTT format auto-detects YouTube VTT with word-level timestamps.
+    """
 
     input_path: Optional[str] = None
     """Path to input caption file."""
 
     output_format: OutputCaptionFormat = "srt"
-    """Output caption format: 'srt', 'vtt', 'ass', 'txt', or 'json'."""
+    """Output caption format. Supports: standard formats, tabular, specialized, TTML profiles (ttml, imsc1, ebu_tt_d),
+    NLE (avid_ds, fcpxml, premiere_xml, audition_csv, edimarker_csv)."""
 
     output_path: Optional[str] = None
     """Path to output caption file."""
@@ -57,12 +54,21 @@ class CaptionConfig:
     word_level: bool = False
     """Include word-level timestamps in alignment results (useful for karaoke, dubbing)."""
 
+    karaoke: Optional[KaraokeConfig] = None
+    """Karaoke configuration when word_level=True (e.g., ASS \\kf tags, enhanced LRC).
+    When None with word_level=True, outputs word-per-segment instead of karaoke styling.
+    When provided, karaoke.enabled controls whether karaoke styling is applied."""
+
     encoding: str = "utf-8"
     """Character encoding for reading/writing caption files (default: utf-8)."""
 
     source_lang: Optional[str] = None
     """Source language code for the caption content (e.g., 'en', 'zh', 'de')."""
 
+    standardization: Optional[StandardizationConfig] = None
+    """Standardization configuration for broadcast-grade captions.
+    When provided, captions will be standardized according to Netflix/BBC guidelines."""
+
     def __post_init__(self):
         """Validate configuration after initialization."""
         self._normalize_paths()
@@ -86,14 +92,17 @@ class CaptionConfig:
         return True
 
     def _normalize_paths(self) -> None:
-        """Normalize and expand input/output paths."""
+        """Normalize and expand input/output paths.
+
+        Uses Path.resolve() to get absolute paths and prevent path traversal issues.
+        """
         # Expand and normalize input path if provided, but don't require it to exist yet
         # (it might be set later after downloading captions)
         if self.input_path is not None:
-            self.input_path = str(Path(self.input_path).expanduser())
+            self.input_path = str(Path(self.input_path).expanduser().resolve())
 
         if self.output_path is not None:
-            self.output_path = str(Path(self.output_path).expanduser())
+            self.output_path = str(Path(self.output_path).expanduser().resolve())
             output_dir = Path(self.output_path).parent
             output_dir.mkdir(parents=True, exist_ok=True)
 
@@ -154,7 +163,7 @@ class CaptionConfig:
         if not self.input_path:
             raise ValueError("input_path is required but not set in CaptionConfig")
 
-        input_file = Path(self.input_path).expanduser()
+        input_file = Path(self.input_path).expanduser().resolve()
         if not input_file.exists():
             raise FileNotFoundError(
                 f"Input caption file does not exist: '{input_file}'. " "Please check the path and try again."
@@ -164,15 +173,20 @@ class CaptionConfig:
                 f"Input caption path is not a file: '{input_file}'. " "Expected a valid caption file path."
             )
 
-    def check_sanity(self) -> bool:
-        """Perform sanity checks on the configuration."""
-        assert self.is_input_path_existed(), "Input caption path must be provided and exist."
+    def check_sanity(self) -> None:
+        """Perform sanity checks on the configuration.
+
+        Raises:
+            ValueError: If input path is not provided or does not exist.
+        """
+        if not self.is_input_path_existed():
+            raise ValueError("Input caption path must be provided and exist.")
 
     def is_input_path_existed(self) -> bool:
         """Check if input caption path is provided and exists."""
         if self.input_path is None:
             return False
 
-        input_file = Path(self.input_path).expanduser()
+        input_file = Path(self.input_path).expanduser().resolve()
         self.input_path = str(input_file)
         return input_file.exists() and input_file.is_file()

lattifai/config/client.py

@@ -31,6 +31,13 @@ class ClientConfig:
     When True, prints detailed timing information for various stages of the process.
     """
 
+    # Client identification for usage tracking
+    client_name: Optional[str] = field(default="python-sdk")
+    """Client identifier for usage tracking (e.g., 'python-sdk', 'claude-plugin')."""
+
+    client_version: Optional[str] = field(default=None)
+    """Client version for usage tracking. If None, uses lattifai package version."""
+
     def __post_init__(self):
         """Validate and auto-populate configuration after initialization."""
 
@@ -44,6 +51,15 @@ class ClientConfig:
         if self.api_key is None:
             object.__setattr__(self, "api_key", os.environ.get("LATTIFAI_API_KEY"))
 
+        # Auto-load client version from package if not provided
+        if self.client_version is None:
+            try:
+                from importlib.metadata import version
+
+                object.__setattr__(self, "client_version", version("lattifai"))
+            except Exception:
+                object.__setattr__(self, "client_version", "unknown")
+
         # Validate API parameters
         if self.timeout <= 0:
             raise ValueError("timeout must be greater than 0")