audex 1.0.7a3__py3-none-any.whl

audex/entity/session.pyi

@@ -0,0 +1,47 @@
+# This file is auto-generated by PrototypeX stub generator.
+# Do not edit manually - changes will be overwritten.
+# Regenerate using: python -m scripts.genstubs gen
+
+from __future__ import annotations
+
+import datetime
+
+from audex.entity import BaseEntity
+from audex.valueobj.session import SessionStatus
+
+class Session(BaseEntity):
+    id: str
+    created_at: datetime.datetime
+    updated_at: datetime.datetime | None
+    doctor_id: str
+    patient_name: str | None
+    clinic_number: str | None
+    medical_record_number: str | None
+    diagnosis: str | None
+    status: SessionStatus
+    started_at: datetime.datetime | None
+    ended_at: datetime.datetime | None
+    notes: str | None
+    def __init__(
+        self,
+        *,
+        id: str = ...,
+        created_at: datetime.datetime = ...,
+        updated_at: datetime.datetime | None = None,
+        doctor_id: str,
+        patient_name: str | None = None,
+        clinic_number: str | None = None,
+        medical_record_number: str | None = None,
+        diagnosis: str | None = None,
+        status: SessionStatus = ...,
+        started_at: datetime.datetime | None = None,
+        ended_at: datetime.datetime | None = None,
+        notes: str | None = None,
+    ) -> None: ...
+    @property
+    def is_active(self) -> bool: ...
+    @property
+    def is_finished(self) -> bool: ...
+    def cancel(self) -> None: ...
+    def complete(self) -> None: ...
+    def start(self) -> None: ...

audex/entity/utterance.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import datetime
+
+from audex import utils
+from audex.entity import BaseEntity
+from audex.entity import touch_after
+from audex.entity.fields import DateTimeField
+from audex.entity.fields import FloatField
+from audex.entity.fields import IntegerField
+from audex.entity.fields import StringBackedField
+from audex.entity.fields import StringField
+from audex.valueobj.utterance import Speaker
+
+
+class Utterance(BaseEntity):
+    """Utterance entity representing a single speech utterance in
+    conversation.
+
+    Represents one continuous speech segment from either the doctor or patient,
+    as recognized by ASR (Automatic Speech Recognition) and speaker verification.
+    Each utterance contains the transcribed text, speaker identification,
+    timing information, and confidence scores.
+
+    Attributes:
+        id: The unique identifier of the utterance. Auto-generated with
+            "utterance-" prefix.
+        session_id: The ID of the session this utterance belongs to. Foreign
+            key reference to Session entity.
+        segment_id: The ID of the audio segment containing this utterance.
+            Foreign key reference to Segment entity.
+        sequence: The sequence number of this utterance within the session.
+            Starts from 1 and increments for each new utterance.
+        speaker: The identified speaker (DOCTOR or PATIENT). Determined by
+            voiceprint verification against doctor's registered voiceprint.
+        text: The transcribed text content from ASR.
+        confidence: ASR confidence score, typically between 0.0 and 1.0.
+            Higher values indicate more confident transcription.
+        start_time_ms: Start time of the utterance within the audio segment,
+            in milliseconds from segment start.
+        end_time_ms: End time of the utterance within the audio segment,
+            in milliseconds from segment start.
+        timestamp: Absolute timestamp when the utterance occurred in the
+            session timeline.
+
+    Inherited Attributes:
+        created_at: Timestamp when the utterance was created.
+        updated_at: Timestamp when the utterance was last updated.
+
+    Example:
+        ```python
+        # Create doctor utterance
+        utterance = Utterance(
+            session_id="session-xyz789",
+            segment_id="segment-abc123",
+            sequence=1,
+            speaker=Speaker.DOCTOR,
+            text="您好，今天哪里不舒服？",
+            confidence=0.95,
+            start_time_ms=1000,
+            end_time_ms=3500,
+            timestamp=utils.utcnow(),
+        )
+
+        # Create patient utterance
+        utterance2 = Utterance(
+            session_id="session-xyz789",
+            segment_id="segment-abc123",
+            sequence=2,
+            speaker=Speaker.PATIENT,
+            text="医生，我最近总是头疼。",
+            confidence=0.88,
+            start_time_ms=4000,
+            end_time_ms=6800,
+            timestamp=utils.utcnow(),
+        )
+
+        # Check speaker
+        if utterance.is_doctor:
+            print("This is doctor speaking")
+        if utterance2.is_patient:
+            print("This is patient speaking")
+        ```
+    """
+
+    id: str = StringField(default_factory=lambda: utils.gen_id(prefix="utterance-"))
+    session_id: str = StringField()
+    segment_id: str = StringField()
+    sequence: int = IntegerField()
+    speaker: Speaker = StringBackedField(Speaker)
+    text: str = StringField()
+    confidence: float | None = FloatField(nullable=True)
+    start_time_ms: int = IntegerField()
+    end_time_ms: int = IntegerField()
+    timestamp: datetime.datetime = DateTimeField(default_factory=utils.utcnow)
+
+    @property
+    def duration_ms(self) -> int:
+        """Calculate the duration of this utterance in milliseconds.
+
+        Returns:
+            Duration in milliseconds.
+        """
+        return self.end_time_ms - self.start_time_ms
+
+    @property
+    def is_doctor(self) -> bool:
+        """Check if the speaker is the doctor.
+
+        Returns:
+            True if speaker is DOCTOR, False otherwise.
+        """
+        return self.speaker == Speaker.DOCTOR
+
+    @property
+    def is_patient(self) -> bool:
+        """Check if the speaker is the patient.
+
+        Returns:
+            True if speaker is PATIENT, False otherwise.
+        """
+        return self.speaker == Speaker.PATIENT
+
+    @touch_after
+    def incr(self) -> None:
+        """Increment the sequence number of this utterance by 1.
+
+        Note:
+            The updated_at timestamp is automatically updated.
+        """
+        self.sequence += 1
+
+    @touch_after
+    def decr(self) -> None:
+        """Decrement the sequence number of this utterance by 1.
+
+        Note:
+            The updated_at timestamp is automatically updated.
+        """
+        if self.sequence > 1:
+            self.sequence -= 1
+        raise ValueError("Sequence number cannot be less than 1.")

audex/entity/utterance.pyi

@@ -0,0 +1,48 @@
+# This file is auto-generated by PrototypeX stub generator.
+# Do not edit manually - changes will be overwritten.
+# Regenerate using: python -m scripts.genstubs gen
+
+from __future__ import annotations
+
+import datetime
+
+from audex.entity import BaseEntity
+from audex.valueobj.utterance import Speaker
+
+class Utterance(BaseEntity):
+    id: str
+    created_at: datetime.datetime
+    updated_at: datetime.datetime | None
+    session_id: str
+    segment_id: str
+    sequence: int
+    speaker: Speaker
+    text: str
+    confidence: float | None
+    start_time_ms: int
+    end_time_ms: int
+    timestamp: datetime.datetime
+    def __init__(
+        self,
+        *,
+        id: str = ...,
+        created_at: datetime.datetime = ...,
+        updated_at: datetime.datetime | None = None,
+        session_id: str,
+        segment_id: str,
+        sequence: int,
+        speaker: Speaker,
+        text: str,
+        confidence: float | None = None,
+        start_time_ms: int,
+        end_time_ms: int,
+        timestamp: datetime.datetime = ...,
+    ) -> None: ...
+    @property
+    def duration_ms(self) -> int: ...
+    @property
+    def is_doctor(self) -> bool: ...
+    @property
+    def is_patient(self) -> bool: ...
+    def decr(self) -> None: ...
+    def incr(self) -> None: ...

audex/entity/vp.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from audex import utils
+from audex.entity import BaseEntity
+from audex.entity.fields import BoolField
+from audex.entity.fields import IntegerField
+from audex.entity.fields import StringField
+
+
+class VP(BaseEntity):
+    """Voiceprint registration record entity.
+
+    Represents a voiceprint registration in the VPR system. Links a doctor
+    to their registered voiceprint in the external VPR service, storing
+    both the local audio reference and remote VPR identifiers.
+
+    This entity allows for VPR system migration without requiring doctors
+    to re-register their voiceprints - the local audio can be re-uploaded
+    to a new VPR system.
+
+    Attributes:
+        id: The unique identifier of the registration. Auto-generated with
+            "vp_reg-" prefix.
+        doctor_id: The ID of the doctor who owns this voiceprint. Foreign
+            key reference to Doctor entity.
+        vpr_uid: The unique identifier in the VPR system for this voiceprint.
+            Used for 1:1 speaker verification.
+        vpr_group_id: The group ID in the VPR system. Optional for organizing
+            voiceprints (e.g., by hospital or department).
+        audio_key: Local storage key for the voiceprint audio file. Preserved
+            for potential re-registration with different VPR systems.
+        text_content: The text that was read during voiceprint registration.
+            Stored for potential re-registration requirements.
+        sample_rate: Audio sample rate used for registration (8000 or 16000 Hz).
+        is_active: Whether this registration is currently active. Only one
+            active registration per doctor should exist.
+
+    Inherited Attributes:
+        created_at: Timestamp when the registration was created.
+        updated_at: Timestamp when the registration was last updated.
+
+    Example:
+        ```python
+        # Create voiceprint registration after VPR API call
+        registration = VPRegistration(
+            doctor_id="doctor-abc123",
+            vpr_uid="vpr_user_xyz789",
+            vpr_group_id="hospital_001",
+            audio_key="vp/doctor-abc123/registration.wav",
+            text_content="请朗读以下文本进行声纹注册...",
+            sample_rate=16000,
+            is_active=True,
+        )
+
+        # Check if active
+        if registration.is_active:
+            print(f"Active VPR UID: {registration.vpr_uid}")
+        ```
+    """
+
+    id: str = StringField(default_factory=lambda: utils.gen_id(prefix="vp_reg-"))
+    doctor_id: str = StringField()
+    vpr_uid: str = StringField()
+    vpr_group_id: str = StringField()
+    audio_key: str = StringField()
+    text_content: str = StringField()
+    sample_rate: int = IntegerField()
+    is_active: bool = BoolField(default=True)

audex/entity/vp.pyi

@@ -0,0 +1,35 @@
+# This file is auto-generated by PrototypeX stub generator.
+# Do not edit manually - changes will be overwritten.
+# Regenerate using: python -m scripts.genstubs gen
+
+from __future__ import annotations
+
+import datetime
+
+from audex.entity import BaseEntity
+
+class VP(BaseEntity):
+    id: str
+    created_at: datetime.datetime
+    updated_at: datetime.datetime | None
+    doctor_id: str
+    vpr_uid: str
+    vpr_group_id: str
+    audio_key: str
+    text_content: str
+    sample_rate: int
+    is_active: bool
+    def __init__(
+        self,
+        *,
+        id: str = ...,
+        created_at: datetime.datetime = ...,
+        updated_at: datetime.datetime | None = None,
+        doctor_id: str,
+        vpr_uid: str,
+        vpr_group_id: str,
+        audio_key: str,
+        text_content: str,
+        sample_rate: int,
+        is_active: bool = True,
+    ) -> None: ...

audex/exceptions.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import typing as t
+
+import pydantic as pyd
+
+
+class AudexError(Exception):
+    """Base exception for all Audex-related errors.
+
+    Attributes:
+        default_message: Default error message for this exception type.
+        code: Unique error code identifying this exception type.
+        message: The actual error message for this instance.
+    """
+
+    __slots__ = ("message",)
+
+    default_message: t.ClassVar[str] = "An error occurred in Audex."
+    code: t.ClassVar[int] = 0x01
+
+    def __init__(self, message: str | None = None) -> None:
+        """Initialize the exception.
+
+        Args:
+            message: Custom error message. If None, uses default_message.
+        """
+        self.message = message or self.default_message
+        super().__init__(self.message)
+
+    def __str__(self) -> str:
+        """Return formatted error string with code."""
+        return f"[Error {self.code}] {self.message}"
+
+    def __repr__(self) -> str:
+        """Return detailed representation of the exception."""
+        return f"{self.__class__.__name__}(code={self.code}, message={self.message!r})"
+
+    def as_dict(self) -> dict[str, t.Any]:
+        """Convert exception to dictionary with all slots."""
+        data: dict[str, t.Any] = {}
+        for slot in getattr(self, "__slots__", []):
+            data[slot] = getattr(self, slot, None)
+        return data
+
+
+class InternalError(AudexError):
+    """Base exception for internal system errors.
+
+    These errors should NOT expose technical details to users. Frontend
+    should display a generic error message and ask users to contact
+    support with the error code.
+    """
+
+    __slots__ = ("details", "message")
+
+    default_message = "Internal system error occurred"
+    code: t.ClassVar[int] = 0x10
+
+    def __init__(self, message: str | None = None, **details: t.Any) -> None:
+        """Initialize the exception.
+
+        Args:
+            message: Custom error message. If None, uses default_message.
+            **details: Additional technical details for logging/debugging.
+        """
+        self.details = details
+        full_message = message or self.default_message
+        super().__init__(full_message)
+
+
+class RequiredModuleNotFoundError(InternalError):
+    """Exception raised when a required module is not found."""
+
+    __slots__ = ("details", "message", "module_name")
+
+    default_message = "Required module not found"
+    code: t.ClassVar[int] = 0x11
+
+    def __init__(self, *module_name: str, message: str | None = None, **details: t.Any) -> None:
+        """Initialize the exception.
+
+        Args:
+            *module_name: One or more names of missing modules.
+            message: Custom error message. If None, uses formatted
+                default_message.
+            **details: Additional technical details for logging/debugging.
+        """
+        self.module_name = module_name
+        full_message = message or f"{self.default_message}: {', '.join(module_name)}"
+        super().__init__(full_message, **details)
+
+
+class ConfigurationError(InternalError):
+    """Exception raised for configuration errors."""
+
+    __slots__ = ("config_key", "details", "message")
+
+    default_message = "Configuration error occurred"
+    code: t.ClassVar[int] = 0x13
+
+    def __init__(
+        self, message: str | None = None, *, config_key: str, reason: str, **details: t.Any
+    ) -> None:
+        """Initialize the exception.
+
+        Args:
+            message: Custom error message. If None, uses formatted
+                default_message.
+            config_key: The configuration key that caused the error.
+            reason: Description of the configuration error.
+            **details: Additional technical details for logging/debugging.
+        """
+        self.config_key = config_key
+        self.reason = reason
+        full_message = message or f"{self.default_message}: [{config_key}] {reason}"
+        super().__init__(full_message, **details)
+
+
+class ValidationError(AudexError):
+    """Exception raised for validation errors."""
+
+    __slots__ = ("message", "reason")
+
+    default_message = "Validation failed"
+    code: t.ClassVar[int] = 0x12
+
+    def __init__(self, message: str | None = None, *, reason: str) -> None:
+        """Initialize the exception.
+
+        Args:
+            reason: Description of what failed validation.
+            message: Custom error message. If None, uses formatted default_message.
+        """
+        self.reason = reason
+        full_message = message or f"{self.default_message}: {reason}"
+        super().__init__(full_message)
+
+    @classmethod
+    def from_pydantic_validation_err(cls, err: pyd.ValidationError) -> t.Self:
+        """Create ValidationError from a Pydantic ValidationError."""
+        reason = "; ".join(f"{e['loc']}: {e['msg']}" for e in err.errors())
+        return cls(reason=reason)
+
+
+class NoActiveSessionError(AudexError):
+    """Exception raised when there is no active session."""
+
+    default_message = "No active session found. Please re-login to continue."
+    code: t.ClassVar[int] = 0x20
+
+
+class PermissionDeniedError(AudexError):
+    """Exception raised for permission denied errors."""
+
+    default_message = "Permission denied. You do not have access to this resource."
+    code: t.ClassVar[int] = 0x21