lattifai 1.2.2__py3-none-any.whl → 1.3.1__py3-none-any.whl

lattifai/config/__init__.py

@@ -1,19 +1,31 @@
 """Configuration system for LattifAI using nemo_run."""
 
-from .alignment import AlignmentConfig
-from .caption import (
-    CaptionConfig,
+# 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",
@@ -21,6 +33,12 @@ __all__ = [
     "CaptionStyle",
     "KaraokeConfig",
     "StandardizationConfig",
+    "InputCaptionFormat",
+    "OutputCaptionFormat",
+    "INPUT_CAPTION_FORMATS",
+    "OUTPUT_CAPTION_FORMATS",
+    "ALL_CAPTION_FORMATS",
+    "CAPTION_FORMATS",
     "TranscriptionConfig",
     "DiarizationConfig",
     "MediaConfig",

lattifai/config/alignment.py

@@ -100,6 +100,13 @@ class AlignmentConfig:
     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,248 +1,18 @@
-"""Caption I/O configuration for LattifAI."""
+"""Caption I/O configuration for LattifAI SDK."""
 
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from pathlib import Path
-from typing import TYPE_CHECKING, Dict, Literal, Optional, get_args
-
-from lhotse.utils import Pathlike
-
-# =============================================================================
-# Caption Style Configuration Classes
-# =============================================================================
-
-
-class CaptionFonts:
-    """Common caption font constants.
-
-    These are reference constants for popular fonts. You can use any
-    system font name as the font_name parameter in CaptionStyle.
-    """
-
-    # Western fonts
-    ARIAL = "Arial"
-    IMPACT = "Impact"
-    VERDANA = "Verdana"
-    HELVETICA = "Helvetica"
-
-    # Chinese fonts
-    NOTO_SANS_SC = "Noto Sans SC"
-    MICROSOFT_YAHEI = "Microsoft YaHei"
-    PINGFANG_SC = "PingFang SC"
-    SIMHEI = "SimHei"
-
-    # Japanese fonts
-    NOTO_SANS_JP = "Noto Sans JP"
-    MEIRYO = "Meiryo"
-    HIRAGINO_SANS = "Hiragino Sans"
-
-    # Korean fonts
-    NOTO_SANS_KR = "Noto Sans KR"
-    MALGUN_GOTHIC = "Malgun Gothic"
-
-
-@dataclass
-class CaptionStyle:
-    """Caption style configuration for ASS/TTML formats.
-
-    Attributes:
-        primary_color: Main text color (#RRGGBB)
-        secondary_color: Secondary/highlight color (#RRGGBB)
-        outline_color: Text outline color (#RRGGBB)
-        back_color: Shadow color (#RRGGBB)
-        font_name: Font family name (use CaptionFonts constants or any system font)
-        font_size: Font size in points
-        bold: Enable bold text
-        italic: Enable italic text
-        outline_width: Outline thickness
-        shadow_depth: Shadow distance
-        alignment: ASS alignment (1-9, numpad style), 2=bottom-center
-        margin_l: Left margin in pixels
-        margin_r: Right margin in pixels
-        margin_v: Vertical margin in pixels
-    """
-
-    # Colors (#RRGGBB format)
-    primary_color: str = "#FFFFFF"
-    secondary_color: str = "#00FFFF"
-    outline_color: str = "#000000"
-    back_color: str = "#000000"
-
-    # Font
-    font_name: str = CaptionFonts.ARIAL
-    font_size: int = 48
-    bold: bool = False
-    italic: bool = False
-
-    # Border and shadow
-    outline_width: float = 2.0
-    shadow_depth: float = 1.0
-
-    # Position
-    alignment: int = 2
-    margin_l: int = 20
-    margin_r: int = 20
-    margin_v: int = 20
-
-
-@dataclass
-class KaraokeConfig:
-    """Karaoke export configuration.
-
-    Attributes:
-        enabled: Whether karaoke mode is enabled
-        effect: Karaoke effect type
-            - "sweep": Gradual fill from left to right (ASS \\kf tag)
-            - "instant": Instant highlight (ASS \\k tag)
-            - "outline": Outline then fill (ASS \\ko tag)
-        style: Caption style configuration (font, colors, position)
-        lrc_precision: LRC time precision ("centisecond" or "millisecond")
-        lrc_metadata: LRC metadata dict (ar, ti, al, etc.)
-        ttml_timing_mode: TTML timing attribute ("Word" or "Line")
-    """
-
-    enabled: bool = False
-    effect: Literal["sweep", "instant", "outline"] = "sweep"
-    style: CaptionStyle = field(default_factory=CaptionStyle)
-
-    # LRC specific
-    lrc_precision: Literal["centisecond", "millisecond"] = "millisecond"
-    lrc_metadata: Dict[str, str] = field(default_factory=dict)
-
-    # TTML specific
-    ttml_timing_mode: Literal["Word", "Line"] = "Word"
-
-
-@dataclass
-class StandardizationConfig:
-    """Caption standardization configuration following broadcast guidelines.
-
-    Reference Standards:
-    - Netflix Timed Text Style Guide
-    - BBC Subtitle Guidelines
-    - EBU-TT-D Standard
-
-    Attributes:
-        min_duration: Minimum segment duration (seconds). Netflix recommends 5/6s, BBC 0.3s
-        max_duration: Maximum segment duration (seconds). Netflix/BBC recommends 7s
-        min_gap: Minimum gap between segments (seconds). 80ms prevents subtitle flicker
-        max_lines: Maximum lines per segment. Broadcast standard is typically 2
-        max_chars_per_line: Maximum characters per line. CJK auto-adjusted by ÷2 (e.g., 42 → 21)
-        optimal_cps: Optimal reading speed (chars/sec). Netflix recommends 17-20 CPS
-        start_margin: Start margin (seconds) before first word. None = no adjustment (default)
-        end_margin: End margin (seconds) after last word. None = no adjustment (default)
-        margin_collision_mode: How to handle collisions: 'trim' (reduce margin) or 'gap' (maintain min_gap)
-    """
-
-    min_duration: float = 0.8
-    max_duration: float = 7.0
-    min_gap: float = 0.08
-    max_lines: int = 2
-    max_chars_per_line: int = 42
-    optimal_cps: float = 17.0
-    start_margin: Optional[float] = None
-    end_margin: Optional[float] = None
-    margin_collision_mode: Literal["trim", "gap"] = "trim"
-
-    def __post_init__(self):
-        """Validate configuration parameters."""
-        if self.min_duration <= 0:
-            raise ValueError("min_duration must be positive")
-        if self.max_duration <= self.min_duration:
-            raise ValueError("max_duration must be greater than min_duration")
-        if self.min_gap < 0:
-            raise ValueError("min_gap cannot be negative")
-        if self.max_lines < 1:
-            raise ValueError("max_lines must be at least 1")
-        if self.max_chars_per_line < 10:
-            raise ValueError("max_chars_per_line must be at least 10")
-        if self.start_margin is not None and self.start_margin < 0:
-            raise ValueError("start_margin cannot be negative")
-        if self.end_margin is not None and self.end_margin < 0:
-            raise ValueError("end_margin cannot be negative")
-        if self.margin_collision_mode not in ("trim", "gap"):
-            raise ValueError("margin_collision_mode must be 'trim' or 'gap'")
-
-
-# =============================================================================
-# Format Type Definitions (Single Source of Truth)
-# =============================================================================
-
-# Type alias for input caption formats (all formats with registered readers)
-InputCaptionFormat = Literal[
-    # Standard subtitle formats
-    "srt",
-    "vtt",  # WebVTT (auto-detects YouTube VTT with word-level timestamps)
-    "ass",
-    "ssa",
-    "sub",
-    "sbv",
-    "txt",
-    "sami",
-    "smi",
-    # Tabular formats
-    "csv",
-    "tsv",
-    "aud",
-    "json",
-    # Specialized formats
-    "textgrid",  # Praat TextGrid
-    "gemini",  # Gemini/YouTube transcript format
-    # Professional NLE formats
-    "avid_ds",
-    "fcpxml",
-    "premiere_xml",
-    "audition_csv",
-    # Special
-    "auto",  # Auto-detect format
-]
-
-# Type alias for output caption formats (all formats with registered writers)
-OutputCaptionFormat = Literal[
-    # Standard subtitle formats
-    "srt",
-    "vtt",  # WebVTT (use karaoke_config.enabled=True for YouTube VTT style output)
-    "ass",
-    "ssa",
-    "sub",
-    "sbv",
-    "txt",
-    "sami",
-    "smi",
-    # Tabular formats
-    "csv",
-    "tsv",
-    "aud",
-    "json",
-    # Specialized formats
-    "textgrid",  # Praat TextGrid
-    "gemini",  # Gemini/YouTube transcript format
-    # TTML profiles (write-only)
-    "ttml",  # Generic TTML
-    "imsc1",  # IMSC1 (Netflix/streaming) TTML profile
-    "ebu_tt_d",  # EBU-TT-D (European broadcast) TTML profile
-    # Professional NLE formats
-    "avid_ds",  # Avid Media Composer SubCap format
-    "fcpxml",  # Final Cut Pro XML
-    "premiere_xml",  # Adobe Premiere Pro XML (graphic clips)
-    "audition_csv",  # Adobe Audition markers
-    "edimarker_csv",  # Pro Tools (via EdiMarker) markers
-]
-
-# =============================================================================
-# Runtime Format Lists (Derived from Type Definitions)
-# =============================================================================
-
-# Input caption formats list (derived from InputCaptionFormat)
-INPUT_CAPTION_FORMATS: list[str] = list(get_args(InputCaptionFormat))
-
-# Output caption formats list (derived from OutputCaptionFormat)
-OUTPUT_CAPTION_FORMATS: list[str] = list(get_args(OutputCaptionFormat))
-
-# Standard caption formats (formats with both reader and writer)
-CAPTION_FORMATS: list[str] = ["srt", "vtt", "ass", "ssa", "sub", "sbv", "txt", "sami", "smi"]
-
-# All caption formats combined (for file detection, excludes "auto")
-ALL_CAPTION_FORMATS: list[str] = list(set(INPUT_CAPTION_FORMATS + OUTPUT_CAPTION_FORMATS) - {"auto"})
+from typing import Optional
+
+from lattifai.caption.config import (
+    INPUT_CAPTION_FORMATS,
+    OUTPUT_CAPTION_FORMATS,
+    InputCaptionFormat,
+    KaraokeConfig,
+    OutputCaptionFormat,
+    StandardizationConfig,
+)
+from lattifai.caption.supervision import Pathlike
 
 
 @dataclass

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")

lattifai/config/event.py

@@ -0,0 +1,102 @@
+"""Audio Event Detection configuration for LattifAI."""
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Dict, List, Literal, Optional
+
+from ..utils import _select_device
+
+if TYPE_CHECKING:
+    from ..client import SyncAPIClient
+
+
+@dataclass
+class EventConfig:
+    """
+    Audio Event Detection configuration.
+
+    Settings for detecting audio events (Speech, Music, Male, Female...) in audio files using the AED model.
+
+    Event Matching:
+        When event_matching is enabled, the AED system will:
+        1. Parse [Event] markers from input captions (e.g., [Music], [Applause])
+        2. Match caption events to AED labels using semantic matching
+        3. Force detection of matched labels even if not in top_k
+        4. Update caption timestamps based on AED detection results
+
+        Event matching logic is implemented in lattifai_core.event.EventMatcher.
+    """
+
+    enabled: bool = False
+    """Enable audio event detection."""
+
+    device: Literal["cpu", "cuda", "mps", "auto"] = "auto"
+    """Computation device for Event Detection models."""
+
+    vad_chunk_size: float = 30.0
+    """VAD chunk size in seconds for speech segmentation."""
+
+    vad_max_gap: float = 2.0
+    """Maximum gap in seconds between VAD segments to merge."""
+
+    fast_mode: bool = True
+    """Enable fast mode (only detect top_k classes, skip others)."""
+
+    model_path: str = ""
+    """Path to pretrained model. If empty, uses default bundled model."""
+
+    event_matching: bool = True
+    """Whether update events in the alignment"""
+
+    extra_events: List[str] = field(default_factory=list)
+    """Additional event types to always detect, even if not in top_k.
+    Example: ["Applause", "Laughter", "Music"]
+    """
+
+    event_aliases: Dict[str, List[str]] = field(default_factory=dict)
+    """Custom aliases mapping [Event] markers to AED labels.
+
+    Core AED labels (14 types):
+        [Applause], [Baby cry], [Battle cry], [Bellow], [Children shouting],
+        [Laughter], [Music], [Shout], [Singing], [Sound effect],
+        [Speech], [Whoop], [Yell]
+
+    Custom aliases extend built-ins (not replace):
+        {"[Audience reaction]": ["[Applause]", "[Cheering]"]}
+    """
+
+    time_tolerance: float = 20.0
+    """Max time (seconds) non-Speech events can extend beyond supervision boundaries."""
+
+    update_timestamps: bool = True
+    """Whether to update caption event timestamps based on AED detections."""
+
+    duplicate_strategy: Literal["keep_all", "merge_first", "split"] = "merge_first"
+    """Strategy for handling multiple [Event] markers mapped to same AED interval.
+    - keep_all: Update all events to same time range (may cause overlapping)
+    - merge_first: Keep only first event per interval, skip duplicates
+    - split: Split interval at speech boundaries (not yet implemented)
+    """
+
+    client_wrapper: Optional["SyncAPIClient"] = field(default=None, repr=False)
+    """Reference to the SyncAPIClient instance. Auto-set during client initialization."""
+
+    def __post_init__(self):
+        """Validate and auto-populate configuration after initialization."""
+        # Validate device
+        if self.device not in ("cpu", "cuda", "mps", "auto") and not self.device.startswith("cuda:"):
+            raise ValueError(f"device must be one of ('cpu', 'cuda', 'mps', 'auto'), got '{self.device}'")
+
+        if self.device == "auto":
+            self.device = _select_device(self.device)
+
+        # Validate vad_chunk_size
+        if self.vad_chunk_size < 0:
+            raise ValueError("vad_chunk_size must be non-negative")
+
+        # Validate vad_max_gap
+        if self.vad_max_gap < 0:
+            raise ValueError("vad_max_gap must be non-negative")
+
+        # Validate time_tolerance
+        if self.time_tolerance < 0:
+            raise ValueError("time_tolerance must be non-negative")

lattifai/config/transcription.py

@@ -7,7 +7,7 @@ from typing import TYPE_CHECKING, Literal, Optional
 from ..utils import _select_device
 
 if TYPE_CHECKING:
-    from ..base_client import SyncAPIClient
+    from ..client import SyncAPIClient
 
 SUPPORTED_TRANSCRIPTION_MODELS = Literal[
     "gemini-2.5-pro",
@@ -48,6 +48,30 @@ class TranscriptionConfig:
     language: Optional[str] = None
     """Target language code for transcription (e.g., 'en', 'zh', 'ja')."""
 
+    prompt: Optional[str] = None
+    """Custom prompt text or path to prompt file for transcription.
+    If the value is an existing file path, the file contents will be used.
+    Otherwise, the value is used directly as the prompt text."""
+
+    description: Optional[str] = None
+    """Media description from platforms like YouTube, Xiaoyuzhou (小宇宙), etc.
+    Used to provide context for transcription."""
+
+    thinking: bool = True
+    """Enable Gemini's thinking mode (Gemini models only). Set to False to disable thinking."""
+
+    include_thoughts: bool = False
+    """Include Gemini's thinking process in the output (Gemini models only). Requires thinking=True."""
+
+    temperature: Optional[float] = None
+    """Sampling temperature for generation. Higher values increase randomness."""
+
+    top_k: Optional[float] = None
+    """Top-k sampling parameter. Limits token selection to top k candidates."""
+
+    top_p: Optional[float] = None
+    """Nucleus sampling parameter. Limits token selection by cumulative probability."""
+
     lattice_model_path: Optional[str] = None
     """Path to local LattifAI model. Will be auto-set in LattifAI client."""
 

lattifai/data/__init__.py

@@ -0,0 +1,8 @@
+"""Data types for LattifAI.
+
+Provides extended Caption class with transcription/alignment/diarization support.
+"""
+
+from .caption import Caption
+
+__all__ = ["Caption"]