audex 1.0.7a3__py3-none-any.whl

audex/service/session/const.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+
+class ErrorMessages:
+    """Error messages in Chinese for session service."""
+
+    # Session errors
+    SESSION_NOT_FOUND = "未找到指定的会话"
+    SESSION_CREATE_FAILED = "创建会话失败，请稍后重试"
+    SESSION_UPDATE_FAILED = "更新会话失败，请稍后重试"
+    SESSION_DELETE_FAILED = "删除会话失败，请稍后重试"
+
+    # Recording errors
+    RECORDING_START_FAILED = "启动录音失败"
+    RECORDING_STOP_FAILED = "停止录音失败"
+    RECORDING_IN_PROGRESS = "录音正在进行中，请先停止当前录音"
+
+    # Segment errors
+    SEGMENT_NOT_FOUND = "未找到音频片段"
+    SEGMENT_CREATE_FAILED = "保存音频片段失败"
+
+    # Utterance errors
+    UTTERANCE_STORE_FAILED = "保存对话记录失败"
+
+    # Transcription errors
+    TRANSCRIPTION_START_FAILED = "启动语音识别失败"
+    TRANSCRIPTION_FAILED = "语音识别失败"
+
+    # VPR errors
+    SPEAKER_VERIFICATION_FAILED = "说话人识别失败"
+    NO_VOICEPRINT_FOUND = "未找到声纹注册，请先注册声纹"
+
+    # Session errors
+    NO_ACTIVE_SESSION = "登录状态已过期，请重新登录"

audex/service/session/exceptions.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import typing as t
+
+from audex.exceptions import AudexError
+from audex.exceptions import InternalError
+
+
+class SessionServiceError(AudexError):
+    """Base exception for session service errors."""
+
+    default_message = "Session service error"
+    code: t.ClassVar[int] = 0x40
+
+
+class InternalSessionServiceError(InternalError):
+    """Internal error in session service."""
+
+    default_message = "Internal session service error"
+    code: t.ClassVar[int] = 0x41
+
+
+class SessionNotFoundError(SessionServiceError):
+    """Raised when session is not found."""
+
+    __slots__ = ("message", "session_id")
+
+    default_message = "Session not found"
+    code: t.ClassVar[int] = 0x42
+
+    def __init__(self, message: str | None = None, *, session_id: str) -> None:
+        """Initialize the exception.
+
+        Args:
+            message: Error message. If None, uses default_message with session_id.
+            session_id: The ID of the session that was not found.
+        """
+        self.session_id = session_id
+        full_message = message or f"{self.default_message}: {session_id}"
+        super().__init__(full_message)
+
+
+class SegmentNotFoundError(SessionServiceError):
+    """Raised when segment is not found."""
+
+    __slots__ = ("message", "segment_id")
+
+    default_message = "Segment not found"
+    code: t.ClassVar[int] = 0x43
+
+    def __init__(self, message: str | None = None, *, segment_id: str) -> None:
+        """Initialize the exception.
+
+        Args:
+            message: Error message. If None, uses default_message with segment_id.
+            segment_id: The ID of the segment that was not found.
+        """
+        self.segment_id = segment_id
+        full_message = message or f"{self.default_message}: {segment_id}"
+        super().__init__(full_message)
+
+
+class RecordingError(SessionServiceError):
+    """Raised for recording-related errors."""
+
+    default_message = "Recording operation failed"
+    code: t.ClassVar[int] = 0x44

audex/service/session/types.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import typing as t
+
+
+class CreateSessionCommand(t.NamedTuple):
+    """Command for creating a new session."""
+
+    doctor_id: str
+    patient_name: str | None = None
+    clinic_number: str | None = None
+    medical_record_number: str | None = None
+    diagnosis: str | None = None
+    notes: str | None = None
+
+
+class UpdateSessionCommand(t.NamedTuple):
+    """Command for updating an existing session."""
+
+    session_id: str
+    patient_name: str | None = None
+    clinic_number: str | None = None
+    medical_record_number: str | None = None
+    diagnosis: str | None = None
+    notes: str | None = None
+
+
+class SessionStats(t.TypedDict):
+    sessions_count_in_this_month: int
+    total_sessions_count: int
+    total_duration_in_minutes: int
+
+
+class Start:
+    """Transcription started event."""
+
+    __slots__ = ("session_id",)
+
+    def __init__(self, *, session_id: str):
+        self.session_id = session_id
+
+
+class Delta:
+    """Transcription delta event with optional sequence number.
+
+    Attributes:
+        session_id: Session ID.
+        from_at: Start timestamp.
+        to_at: End timestamp.
+        text: Transcribed text.
+        interim: Whether this is an interim result.
+        sequence: Utterance sequence number (None for interim results).
+    """
+
+    __slots__ = ("from_at", "interim", "sequence", "session_id", "text", "to_at")
+
+    def __init__(
+        self,
+        *,
+        session_id: str,
+        from_at: float,
+        to_at: float,
+        text: str,
+        interim: bool,
+        sequence: int | None = None,
+    ):
+        self.session_id = session_id
+        self.from_at = from_at
+        self.to_at = to_at
+        self.text = text
+        self.interim = interim
+        self.sequence = sequence
+
+
+class Done:
+    """Transcription completed event with speaker identification.
+
+    Attributes:
+        session_id: Session ID.
+        is_doctor: Whether the speaker is the doctor.
+        full_text: Full transcribed text.
+        sequence: Utterance sequence number.
+    """
+
+    __slots__ = ("full_text", "is_doctor", "sequence", "session_id")
+
+    def __init__(self, *, session_id: str, is_doctor: bool, full_text: str, sequence: int):
+        self.session_id = session_id
+        self.is_doctor = is_doctor
+        self.full_text = full_text
+        self.sequence = sequence

audex/types.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import abc
+import typing as t
+
+
+class AbstractSession(abc.ABC):
+    @abc.abstractmethod
+    async def start(self) -> None: ...
+
+    @abc.abstractmethod
+    async def close(self) -> t.Any: ...
+
+    async def __aenter__(self) -> AbstractSession:
+        await self.start()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: t.Any | None,
+    ) -> None:
+        await self.close()
+
+
+S = t.TypeVar("S")
+R = t.TypeVar("R")
+
+
+class DuplexAbstractSession(AbstractSession, t.Generic[S, R], abc.ABC):
+    @abc.abstractmethod
+    async def finish(self) -> None: ...
+
+    @abc.abstractmethod
+    async def send(self, message: S) -> None: ...
+
+    @abc.abstractmethod
+    def receive(self) -> t.AsyncIterable[R]: ...

audex/utils.py

@@ -0,0 +1,287 @@
+from __future__ import annotations
+
+import datetime
+import enum
+import os
+import sys
+import typing as t
+import uuid
+
+from pydantic import BaseModel
+from pydantic import GetCoreSchemaHandler
+from pydantic_core import CoreSchema
+from pydantic_core.core_schema import no_info_plain_validator_function
+from pydantic_core.core_schema import plain_serializer_function_ser_schema
+
+
+def gen_id(prefix: str = "", suffix: str = "", without_hyphen: bool = True, digis: int = 32) -> str:
+    """Generate a unique identifier (UUID) with optional prefix and
+    suffix.
+
+    Args:
+        prefix: A string to prepend to the generated UUID (default: "").
+        suffix: A string to append to the generated UUID (default: "").
+        without_hyphen: Whether to remove hyphens from the UUID
+            (default: True).
+        digis: Number of digits to include from the UUID (default: 32).
+
+    Returns:
+        A unique identifier string with the specified prefix and suffix.
+    """
+    uid = uuid.uuid4()
+    uid_str = uid.hex if without_hyphen else str(uid)
+    uid_str = uid_str[:digis]
+    return f"{prefix}{uid_str}{suffix}"
+
+
+def utcnow() -> datetime.datetime:
+    """Get the current UTC datetime with timezone info.
+
+    Returns:
+        The current UTC datetime with timezone info.
+    """
+    return datetime.datetime.now(datetime.UTC)
+
+
+class ANSI:
+    """Enhanced formatter for ANSI color and style formatting in console
+    output.
+
+    Provides organized color constants, helper methods, and context
+    managers for applying consistent styling to terminal output.
+    Automatically detects color support in the terminal environment.
+    """
+
+    class FG(enum.StrEnum):
+        """Foreground colors."""
+
+        BLACK = "\033[30m"
+        RED = "\033[31m"
+        GREEN = "\033[32m"
+        YELLOW = "\033[33m"
+        BLUE = "\033[34m"
+        MAGENTA = "\033[35m"
+        CYAN = "\033[36m"
+        WHITE = "\033[37m"
+        GRAY = "\033[90m"
+        BRIGHT_RED = "\033[91m"
+        BRIGHT_GREEN = "\033[92m"
+        BRIGHT_YELLOW = "\033[93m"
+        BRIGHT_BLUE = "\033[94m"
+        BRIGHT_MAGENTA = "\033[95m"
+        BRIGHT_CYAN = "\033[96m"
+        BRIGHT_WHITE = "\033[97m"
+
+    class BG(enum.StrEnum):
+        """Background colors."""
+
+        BLACK = "\033[40m"
+        RED = "\033[41m"
+        GREEN = "\033[42m"
+        YELLOW = "\033[43m"
+        BLUE = "\033[44m"
+        MAGENTA = "\033[45m"
+        CYAN = "\033[46m"
+        WHITE = "\033[47m"
+        GRAY = "\033[100m"
+        BRIGHT_RED = "\033[101m"
+        BRIGHT_GREEN = "\033[102m"
+        BRIGHT_YELLOW = "\033[103m"
+        BRIGHT_BLUE = "\033[104m"
+        BRIGHT_MAGENTA = "\033[105m"
+        BRIGHT_CYAN = "\033[106m"
+        BRIGHT_WHITE = "\033[107m"
+
+    class STYLE(enum.StrEnum):
+        """Text styles."""
+
+        RESET = "\033[0m"
+        BOLD = "\033[1m"
+        DIM = "\033[2m"
+        ITALIC = "\033[3m"
+        UNDERLINE = "\033[4m"
+        BLINK = "\033[5m"
+        REVERSE = "\033[7m"
+        HIDDEN = "\033[8m"
+        STRIKETHROUGH = "\033[9m"
+
+    # For backward compatibility
+    RESET = STYLE.RESET
+    BOLD = STYLE.BOLD
+    UNDERLINE = STYLE.UNDERLINE
+    REVERSED = STYLE.REVERSE
+    RED = FG.BRIGHT_RED
+    GREEN = FG.BRIGHT_GREEN
+    YELLOW = FG.BRIGHT_YELLOW
+    BLUE = FG.BRIGHT_BLUE
+    MAGENTA = FG.BRIGHT_MAGENTA
+    CYAN = FG.BRIGHT_CYAN
+    WHITE = FG.BRIGHT_WHITE
+
+    # Control whether ANSI colors are enabled
+    _enabled = True
+
+    @classmethod
+    def supports_color(cls) -> bool:
+        """Determine if the current terminal supports colors.
+
+        Returns:
+            bool: True if the terminal supports colors, False otherwise.
+        """
+        # Check for NO_COLOR environment variable (https://no-color.org/)
+        if os.environ.get("NO_COLOR", ""):
+            return False
+
+        # Check for explicit color control
+        if os.environ.get("FORCE_COLOR", ""):
+            return True
+
+        # Check if stdout is a TTY
+        return hasattr(sys.stdout, "isatty") or sys.stdout.isatty()
+
+    @classmethod
+    def enable(cls, enabled: bool = True) -> None:
+        """Enable or disable ANSI formatting.
+
+        Args:
+            enabled: True to enable colors, False to disable.
+        """
+        cls._enabled = enabled and cls.supports_color()
+
+    @classmethod
+    def format(cls, text: str, /, *styles: STYLE | FG | BG | None) -> str:
+        """Format text with the specified ANSI styles.
+
+        Intelligently reapplies styles after any reset sequences in the text.
+        If colors are disabled, returns the original text without formatting.
+
+        Args:
+            text: The text to format.
+            *styles: One or more ANSI style codes to apply.
+
+        Returns:
+            The formatted text with ANSI styles applied.
+        """
+        if not cls._enabled or not styles:
+            return text
+        if any(s is None for s in styles):
+            styles = tuple(s for s in styles if s is not None)
+
+        style_str = "".join(styles)  # type: ignore[arg-type]
+
+        # Handle text that already contains reset codes
+        if cls.STYLE.RESET in text:
+            text = text.replace(cls.STYLE.RESET, f"{cls.STYLE.RESET}{style_str}")
+
+        return f"{style_str}{text}{cls.STYLE.RESET}"
+
+    @classmethod
+    def success(cls, text: str, /) -> str:
+        """Format text as a success message (green, bold)."""
+        return cls.format(text, cls.FG.BRIGHT_GREEN, cls.STYLE.BOLD)
+
+    @classmethod
+    def error(cls, text: str, /) -> str:
+        """Format text as an error message (red, bold)."""
+        return cls.format(text, cls.FG.BRIGHT_RED, cls.STYLE.BOLD)
+
+    @classmethod
+    def warning(cls, text: str, /) -> str:
+        """Format text as a warning message (yellow, bold)."""
+        return cls.format(text, cls.FG.BRIGHT_YELLOW, cls.STYLE.BOLD)
+
+    @classmethod
+    def info(cls, text: str, /) -> str:
+        """Format text as an info message (cyan)."""
+        return cls.format(text, cls.FG.BRIGHT_CYAN)
+
+    @classmethod
+    def highlight(cls, text: str, /) -> str:
+        """Format text as highlighted (magenta, bold)."""
+        return cls.format(text, cls.FG.BRIGHT_MAGENTA, cls.STYLE.BOLD)
+
+    @classmethod
+    def rgb(cls, text: str, /, r: int, g: int, b: int, background: bool = False) -> str:
+        """Format text with a specific RGB color.
+
+        Args:
+            text: The text to format
+            r: R
+            g: G
+            b: B
+            background: If True, set as background color instead of foreground
+
+        Returns:
+            Formatted text with the specified RGB color
+        """
+        if not cls._enabled:
+            return text
+
+        code = 48 if background else 38
+        color_seq = f"\033[{code};2;{r};{g};{b}m"
+        return f"{color_seq}{text}{cls.STYLE.RESET}"
+
+
+def flatten_dict(
+    m: t.Mapping[str, t.Any],
+    /,
+    sep: str = ".",
+    _parent: str = "",
+) -> dict[str, t.Any]:
+    """Flatten a nested dictionary into a single-level dictionary with
+    dot-separated keys.
+
+    Args:
+        m: The nested dictionary to flatten.
+        sep: The separator to use between keys (default: '.').
+        _parent: The parent key prefix (used for recursion).
+
+    Returns:
+        A flattened dictionary with dot-separated keys.
+    """
+    items = []  # type: list[tuple[str, t.Any]]
+    for k, v in m.items():
+        key = f"{_parent}{sep}{k}" if _parent else k
+        if isinstance(v, t.Mapping):
+            items.extend(flatten_dict(v, _parent=key, sep=sep).items())
+        else:
+            items.append((key, v))
+    return dict(items)
+
+
+class Unset:
+    """A singleton class representing an unset value, distinct from
+    None.
+
+    This class is used to indicate that a value has not been set or
+    provided, allowing differentiation between an explicit None value
+    and an unset state.
+    """
+
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        return "<UNSET>"
+
+    __str__ = __repr__
+
+    def __bool__(self) -> bool:
+        return False
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, Unset)
+
+    def __hash__(self) -> int:
+        return hash("UNSET")
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls, source: type[BaseModel], handler: GetCoreSchemaHandler, /
+    ) -> CoreSchema:
+        return no_info_plain_validator_function(
+            lambda v: v if isinstance(v, Unset) else UNSET,
+            serialization=plain_serializer_function_ser_schema(lambda v: str(v)),
+        )
+
+
+UNSET = Unset()

audex/valueobj/__init__.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import abc
+import builtins
+import enum
+import typing as t
+
+import pydantic as pyd
+
+from audex.exceptions import ValidationError
+
+
+class BaseValueObject(pyd.BaseModel, abc.ABC):
+    model_config: t.ClassVar[pyd.ConfigDict] = pyd.ConfigDict(
+        validate_assignment=True,  # Validate on assignment
+        extra="forbid",  # Disallow extra fields
+    )
+
+    @pyd.model_validator(mode="wrap")
+    @classmethod
+    def reraise(cls, data: t.Any, handler: pyd.ModelWrapValidatorHandler[t.Self]) -> t.Self:
+        try:
+            return handler(data)
+        except pyd.ValidationError as e:
+            raise ValidationError.from_pydantic_validation_err(e) from e
+
+    def __repr__(self) -> str:
+        field_reprs = ", ".join(
+            f"{field_name}={getattr(self, field_name)!r}"
+            for field_name in self.model_fields  # type: ignore
+        )
+        return f"VALUEOBJECT <{self.__class__.__name__}({field_reprs})>"
+
+
+T = t.TypeVar("T")
+
+
+class SingleValueObject(BaseValueObject, t.Generic[T]):
+    value: T
+
+    @classmethod
+    def parse(cls, value: T, *, validate: bool = True) -> t.Self:
+        return cls(value=value) if validate else cls.model_construct(value=value)
+
+
+class PaginationParams(BaseValueObject):
+    page: int = pyd.Field(
+        default=1,
+        ge=1,
+        description="Page number for pagination, starting from 1",
+    )
+
+    limit: int = pyd.Field(
+        default=10,
+        ge=1,
+        le=100,
+        description="Number of items per page, between 1 and 100",
+    )
+
+
+class EnumValueObject(enum.Enum):
+    @classmethod
+    def parse(cls, value: str) -> t.Self:
+        try:
+            return cls(value)
+        except ValueError as e:
+            raise ValidationError(
+                f"Invalid value '{value}' for enum '{cls.__name__}'. "
+                f"Allowed values are: {cls.list()}",
+                reason="invalid_enum_value",
+            ) from e
+
+    @classmethod
+    def list(cls) -> builtins.list[str]:
+        return [member.value for member in cls]
+
+    def __repr__(self) -> str:
+        return f"ENUM VALUEOBJECT <{self.__class__.__name__}.{self.name}>"
+
+    def __str__(self) -> str:
+        return str(self.value)

audex/valueobj/common/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

audex/valueobj/common/auth.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import math
+import string
+import typing as t
+
+from pydantic import Field
+from pydantic import field_validator
+
+from audex.helper import hash
+from audex.valueobj import SingleValueObject
+
+
+class Password(SingleValueObject[str]):
+    value: str = Field(
+        min_length=8,
+        max_length=64,
+        pattern=r"^[A-Za-z\d]{8,20}$",
+        description="Plain text password, 8-64 characters.",
+    )
+
+    @field_validator("value")
+    @classmethod
+    def validate_password(cls, v: str) -> str:
+        if not any(c.islower() for c in v):
+            raise ValueError("Password must contain at least one lowercase letter.")
+        if not any(c.isupper() for c in v):
+            raise ValueError("Password must contain at least one uppercase letter.")
+        if not any(c.isdigit() for c in v):
+            raise ValueError("Password must contain at least one digit.")
+        return v
+
+    def entropy(self) -> float:
+        charset_size = 0
+        v = self.value
+        if any(c.islower() for c in v):
+            charset_size += 26
+        if any(c.isupper() for c in v):
+            charset_size += 26
+        if any(c.isdigit() for c in v):
+            charset_size += 10
+        if any(c in string.punctuation for c in v):
+            charset_size += len(string.punctuation)
+        if charset_size == 0:
+            charset_size = 1
+        return len(v) * math.log2(charset_size)
+
+    @staticmethod
+    def entropy_to_strength_level(
+        entropy: float,
+    ) -> t.Literal["weak", "medium", "strong", "very_strong"]:
+        if entropy < 40:
+            return "weak"
+        if entropy < 60:
+            return "medium"
+        if entropy < 80:
+            return "strong"
+        return "very_strong"
+
+    def strength_level(self) -> t.Literal["weak", "medium", "strong", "very_strong"]:
+        e = self.entropy()
+        return self.entropy_to_strength_level(e)
+
+    def hash(self) -> HashedPassword:
+        return HashedPassword(value=hash.argon2_hash(self.value))
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Password):
+            return NotImplemented
+        return self.value == other.value
+
+
+class HashedPassword(SingleValueObject[str]):
+    value: str = Field(
+        description="Password hashed by Argon2.",
+    )
+
+    def verify(self, password: Password) -> bool:
+        return hash.argon2_verify(password.value, self.value)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Password):
+            return NotImplemented
+        return hash.argon2_verify(other.value, self.value)

audex/valueobj/common/email.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from pydantic import Field
+
+from audex.valueobj import SingleValueObject
+
+
+class Email(SingleValueObject[str]):
+    value: str = Field(
+        ...,
+        description="A valid email address",
+        pattern=r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$",
+    )
+
+    def __str__(self) -> str:
+        return self.value