audex 1.0.7a3__py3-none-any.whl

audex/lib/database/sqlite.py

@@ -0,0 +1,406 @@
+from __future__ import annotations
+
+import typing as t
+
+import sqlalchemy as sa
+import sqlalchemy.event as saevent
+import sqlalchemy.ext.asyncio as aiosa
+import sqlmodel as sqlm
+
+from audex.lib.database import Database
+
+
+class SQLitePoolConfig(t.TypedDict):
+    echo: bool
+    """Whether to log all SQL statements."""
+
+    pool_size: int
+    """Number of connections to maintain in the pool."""
+
+    max_overflow: int
+    """Max number of connections beyond pool_size."""
+
+    pool_timeout: float
+    """Seconds to wait before timing out on connection."""
+
+    pool_recycle: int
+    """Seconds after which to recycle connections."""
+
+    pool_pre_ping: bool
+    """Test connections before using them."""
+
+    create_all: bool
+    """Whether to create all tables on init."""
+
+
+class SQLite(Database):
+    """SQLite database container with async SQLModel/SQLAlchemy support.
+
+    This class provides a high-level interface for SQLite database
+    operations with the following features:
+
+    1. Async engine and session management for repository pattern
+    2. Connection pooling with configurable parameters
+    3. Raw SQL execution with transaction control
+    4. Schema management utilities (create_all/drop_all)
+    5. Unified lifecycle management through AsyncContextMixin
+
+    Attributes:
+        uri: SQLite connection URI.
+        engine: SQLAlchemy async engine (initialized after init()).
+        sessionmaker: Async session factory (initialized after init()).
+        cfg: Connection pool configuration.
+
+    Args:
+        uri: SQLite connection URI (must use aiosqlite driver).
+            Example: "sqlite+aiosqlite:///./database.db" (relative path)
+            Example: "sqlite+aiosqlite:////absolute/path/database.db" (absolute
+                path)
+            Example: "sqlite+aiosqlite:///:memory:" (in-memory database)
+        tables: List of SQLModel classes to manage. Used for
+            create_all/drop_all.
+        echo: Whether to log all SQL statements (useful for debugging).
+        pool_size: Number of connections to maintain in the pool.
+            Note: SQLite with aiosqlite uses NullPool by default in async mode.
+        max_overflow: Max number of connections beyond pool_size.
+        pool_timeout: Seconds to wait before timing out on connection.
+        pool_recycle: Seconds after which to recycle connections.
+            Set to -1 to disable recycling.
+        pool_pre_ping: Test connections before using them. Recommended
+            for production to handle stale connections.
+        create_all: Whether to create all tables on init().
+
+    Example:
+        ```python
+        # Setup with file-based database
+        sqlite = SQLite(
+            uri="sqlite+aiosqlite:///./app.db",
+            tables=[User, Post],
+            echo=True,
+        )
+
+        # Setup with in-memory database (useful for testing)
+        sqlite = SQLite(
+            uri="sqlite+aiosqlite:///:memory:",
+            tables=[User, Post],
+        )
+
+        # Initialize
+        await sqlite.init()
+
+        # Create tables
+        await sqlite.create_all()
+
+        # Use session for ORM operations
+        async with sqlite.session() as session:
+            user = await session.get(User, user_id)
+            user.username = "new_name"
+            await session.commit()
+
+        # Execute raw SQL
+        result = await sqlite.exec(
+            "SELECT * FROM users WHERE age > :age",
+            readonly=True,
+            age=21,
+        )
+
+        # Cleanup
+        await sqlite.close()
+        ```
+
+    Note:
+        - The URI must use the aiosqlite driver for async support.
+        - SQLite doesn't support some PostgreSQL features (e.g., JSONB operators).
+        - Use JSON1 extension for JSON operations (enabled by default).
+        - File path format: Use three slashes for relative paths, four for absolute.
+    """
+
+    def __init__(
+        self,
+        uri: str,
+        *,
+        tables: list[type[sqlm.SQLModel]] | None = None,
+        echo: bool = False,
+        pool_size: int = 20,
+        max_overflow: int = 10,
+        pool_timeout: float = 30.0,
+        pool_recycle: int = 3600,
+        pool_pre_ping: bool = True,
+        create_all: bool = True,
+    ) -> None:
+        self.uri = uri
+        self.tables = tables or []
+        self.engine: aiosa.AsyncEngine | None = None
+        self.sessionmaker: aiosa.async_sessionmaker[aiosa.AsyncSession] | None = None
+        self.cfg = SQLitePoolConfig(
+            echo=echo,
+            pool_size=pool_size,
+            max_overflow=max_overflow,
+            pool_timeout=pool_timeout,
+            pool_recycle=pool_recycle,
+            pool_pre_ping=pool_pre_ping,
+            create_all=create_all,
+        )
+
+    async def init(self) -> None:
+        """Initialize the database engine and session factory.
+
+        This method creates the async engine with connection pooling and
+        sets up the session factory. It should be called during application
+        startup, typically in a lifespan context manager.
+
+        For SQLite, this also enables foreign key constraints and loads
+        the JSON1 extension if available.
+
+        Raises:
+            Exception: If engine creation fails (e.g., invalid URI).
+        """
+        # Create engine with SQLite-specific configuration
+        self.engine = aiosa.create_async_engine(
+            self.uri,
+            echo=self.cfg["echo"],
+            # SQLite-specific: Use NullPool for better async compatibility
+            # or StaticPool for in-memory databases
+            poolclass=sa.pool.NullPool if ":memory:" not in self.uri else sa.pool.StaticPool,
+            connect_args={
+                "check_same_thread": False,  # Required for async SQLite
+            },
+        )
+
+        # Configure SQLite settings
+        @saevent.listens_for(self.engine.sync_engine, "connect")
+        def set_sqlite_pragma(dbapi_conn: t.Any, _connection_record: t.Any) -> None:
+            """Set SQLite-specific pragmas on connection."""
+            cursor = dbapi_conn.cursor()
+            # Enable foreign key constraints
+            cursor.execute("PRAGMA foreign_keys=ON")
+            # Enable WAL mode for better concurrency
+            cursor.execute("PRAGMA journal_mode=WAL")
+            cursor.close()
+
+        self.sessionmaker = aiosa.async_sessionmaker(
+            self.engine,
+            class_=aiosa.AsyncSession,
+            expire_on_commit=False,
+        )
+
+        if self.cfg["create_all"]:
+            await self.create_all()
+
+    async def close(self) -> None:
+        """Close the database engine and clean up resources.
+
+        This method disposes of the connection pool and resets the engine
+        and session factory. It should be called during application shutdown.
+
+        Note:
+            This method is idempotent and safe to call multiple times.
+        """
+        if self.engine:
+            await self.engine.dispose()
+            self.engine = None
+            self.sessionmaker = None
+
+    def session(self) -> aiosa.AsyncSession:
+        """Create a new async database session.
+
+        Returns:
+            An async session context manager.
+
+        Raises:
+            RuntimeError: If sessionmaker is not initialized (call init() first).
+
+        Example:
+            ```python
+            async with sqlite.session() as session:
+                # Start a transaction
+                user = await session.get(User, user_id)
+                user.username = "new_name"
+                await session.commit()
+            ```
+
+        Note:
+            The session is automatically committed on successful exit and
+            rolled back on exception. You can also manually commit/rollback
+            within the context.
+        """
+        if not self.sessionmaker:
+            raise RuntimeError("Sessionmaker not initialized. Call init() first.")
+
+        return self.sessionmaker()
+
+    async def exec(self, sql: str, /, readonly: bool = False, **params: t.Any) -> sa.Result[t.Any]:
+        """Execute a raw SQL statement.
+
+        This method provides direct SQL execution for cases where ORM
+        abstractions are insufficient or when specific optimizations
+        are needed.
+
+        Args:
+            sql: Raw SQL string to execute. Use named parameters with
+                colon prefix.
+            readonly: If True, does not commit the transaction. Use this
+                for SELECT queries to avoid unnecessary commits.
+            **params: Named parameters for the SQL statement.
+
+        Returns:
+            SQLAlchemy Result object containing query results.
+
+        Raises:
+            RuntimeError: If execution fails, with the original exception
+                as the cause.
+
+        Example:
+            ```python
+            # Read-only query
+            result = await sqlite.exec(
+                "SELECT * FROM users WHERE age > :age",
+                readonly=True,
+                age=21,
+            )
+            users = result.fetchall()
+
+            # Write query
+            await sqlite.exec(
+                "UPDATE users SET status = :status WHERE id = :id",
+                readonly=False,
+                status="active",
+                id=123,
+            )
+
+            # Using JSON1 extension
+            result = await sqlite.exec(
+                "SELECT * FROM users WHERE json_extract(tags, '$.premium') = 1",
+                readonly=True,
+            )
+            ```
+
+        Warning:
+            Be careful with SQL injection. Always use parameterized queries
+            with named parameters instead of string formatting.
+        """
+        async with self.session() as session, session.begin():
+            result = await session.execute(sa.text(sql), params=params or None)
+            if not readonly:
+                await session.commit()
+            return result
+
+    async def ping(self) -> bool:
+        """Check database connectivity.
+
+        This method attempts to execute a simple query to verify that
+        the database is reachable and responsive.
+
+        Returns:
+            True if database is reachable, False otherwise.
+
+        Note:
+            This method does not raise exceptions. It catches all errors
+            and returns False instead.
+        """
+        if not self.engine:
+            return False
+
+        try:
+            async with self.engine.connect() as conn:
+                await conn.execute(sa.text("SELECT 1"))
+            return True
+        except Exception:
+            return False
+
+    async def create_all(self) -> None:
+        """Create all database tables.
+
+        This method creates tables for the specified SQLModel classes, or
+        all tables in the SQLModel metadata if no models are specified.
+
+        Raises:
+            RuntimeError: If engine is not initialized.
+
+        Example:
+            ```python
+            # Create specific tables
+            sqlite = SQLite(
+                uri="sqlite+aiosqlite:///./app.db",
+                tables=[User, Post, Comment],
+            )
+            await sqlite.init()
+            await sqlite.create_all()
+
+            # Create all tables
+            sqlite = SQLite(uri="sqlite+aiosqlite:///./app.db")
+            await sqlite.init()
+            await sqlite.create_all()
+            ```
+
+        Warning:
+            This is typically used for development/testing. In production,
+            use proper migration tools like Alembic to manage schema changes.
+        """
+        if not self.engine:
+            raise RuntimeError("Engine not initialized. Call init() first.")
+
+        async with self.engine.begin() as conn:
+            if self.tables:
+
+                def _create_tables(sync_conn: sa.Connection) -> None:
+                    for model in self.tables:
+                        model.metadata.create_all(bind=sync_conn)
+
+                await conn.run_sync(_create_tables)
+            else:
+                await conn.run_sync(sqlm.SQLModel.metadata.create_all)
+
+    async def drop_all(self) -> None:
+        """Drop all database tables.
+
+        This method drops all tables defined in the SQLModel metadata.
+
+        Raises:
+            RuntimeError: If engine is not initialized.
+
+        Example:
+            ```python
+            await sqlite.drop_all()  # Be careful!
+            ```
+
+        Warning:
+            This is destructive and should only be used in development/testing.
+            All data will be lost. There is no confirmation prompt.
+        """
+        if not self.engine:
+            raise RuntimeError("Engine not initialized. Call init() first.")
+
+        async with self.engine.begin() as conn:
+            await conn.run_sync(sqlm.SQLModel.metadata.drop_all)
+
+    async def vacuum(self) -> None:
+        """Run VACUUM command to optimize the database file.
+
+        This command rebuilds the database file, repacking it into a minimal
+        amount of disk space. It's useful after deleting large amounts of data.
+
+        Raises:
+            RuntimeError: If engine is not initialized.
+
+        Example:
+            ```python
+            # After bulk deletions
+            await sqlite.exec(
+                "DELETE FROM old_logs WHERE created_at < :date",
+                date=cutoff_date,
+            )
+            await sqlite.vacuum()  # Reclaim disk space
+            ```
+
+        Note:
+            VACUUM requires exclusive access to the database and may take
+            significant time on large databases.
+        """
+        if not self.engine:
+            raise RuntimeError("Engine not initialized. Call init() first.")
+
+        # VACUUM must be run outside a transaction
+        async with self.engine.connect() as conn:
+            await conn.execute(sa.text("VACUUM"))
+            await conn.commit()

audex/lib/exporter.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+import io
+import json
+import pathlib
+import zipfile
+
+from audex.entity.segment import Segment
+from audex.entity.session import Session
+from audex.entity.utterance import Utterance
+from audex.filters.generated import segment_filter
+from audex.filters.generated import utterance_filter
+from audex.helper.mixin import LoggingMixin
+from audex.lib.repos.segment import SegmentRepository
+from audex.lib.repos.session import SessionRepository
+from audex.lib.repos.utterance import UtteranceRepository
+from audex.lib.server.types import AudioMetadataItem
+from audex.lib.server.types import AudioMetadataJSON
+from audex.lib.server.types import ConversationJSON
+from audex.lib.server.types import SegmentDict
+from audex.lib.server.types import SessionDict
+from audex.lib.server.types import SessionExportData
+from audex.lib.server.types import UtteranceDict
+from audex.lib.store import Store
+
+
+class Exporter(LoggingMixin):
+    """Exporter for packaging session data and audio files."""
+
+    __logtag__ = "audex.lib.exporter"
+
+    def __init__(
+        self,
+        session_repo: SessionRepository,
+        segment_repo: SegmentRepository,
+        utterance_repo: UtteranceRepository,
+        store: Store,
+    ):
+        super().__init__()
+        self.session_repo = session_repo
+        self.segment_repo = segment_repo
+        self.utterance_repo = utterance_repo
+        self.store = store
+
+    async def export_session_data(self, session_id: str) -> SessionExportData:
+        """Export session data as structured format."""
+        # Get session
+        session = await self.session_repo.read(session_id)
+        if not session:
+            raise ValueError(f"Session {session_id} not found")
+
+        # Get utterances
+        utt_filter = utterance_filter().session_id.eq(session_id).sequence.asc()
+        utterances = await self.utterance_repo.list(utt_filter.build())
+
+        # Get segments
+        seg_filter = segment_filter().session_id.eq(session_id).sequence.asc()
+        segments = await self.segment_repo.list(seg_filter.build())
+
+        # Convert to typed dicts
+        return SessionExportData(
+            session=self._session_to_dict(session),
+            utterances=[self._utterance_to_dict(u) for u in utterances],
+            segments=[self._segment_to_dict(s) for s in segments],
+        )
+
+    async def export_session_zip(self, session_id: str) -> bytes:
+        """Export session as ZIP package."""
+        export_data = await self.export_session_data(session_id)
+        zip_buffer = io.BytesIO()
+
+        with zipfile.ZipFile(zip_buffer, "w", zipfile.ZIP_DEFLATED) as zipf:
+            # Add conversation.json
+            conversation: ConversationJSON = {
+                "session": export_data["session"],
+                "utterances": export_data["utterances"],
+                "total_utterances": len(export_data["utterances"]),
+                "total_segments": len(export_data["segments"]),
+            }
+            zipf.writestr(
+                "conversation.json",
+                json.dumps(conversation, ensure_ascii=False, indent=2),
+            )
+
+            # Add audio files
+            audio_metadata_items: list[AudioMetadataItem] = []
+
+            for idx, segment_dict in enumerate(export_data["segments"], start=1):
+                audio_key = segment_dict["audio_key"]
+
+                try:
+                    audio_data = await self.store.download(audio_key)
+                    ext = pathlib.Path(audio_key).suffix or ".mp3"
+                    filename = f"segment_{idx:03d}{ext}"
+
+                    zipf.writestr(f"audio/{filename}", audio_data)
+
+                    audio_metadata_items.append(
+                        AudioMetadataItem(
+                            filename=filename,
+                            sequence=segment_dict["sequence"],
+                            duration_ms=segment_dict["duration_ms"],
+                            started_at=segment_dict["started_at"],
+                            ended_at=segment_dict["ended_at"],
+                        )
+                    )
+
+                    self.logger.debug(f"Added audio file: {filename}")
+
+                except Exception as e:
+                    self.logger.error(f"Failed to add audio {audio_key}: {e}")
+
+            # Add audio metadata
+            if audio_metadata_items:
+                audio_metadata: AudioMetadataJSON = {
+                    "session_id": session_id,
+                    "total_segments": len(audio_metadata_items),
+                    "segments": audio_metadata_items,
+                }
+                zipf.writestr(
+                    "audio/metadata.json",
+                    json.dumps(audio_metadata, ensure_ascii=False, indent=2),
+                )
+
+        zip_buffer.seek(0)
+        return zip_buffer.getvalue()
+
+    async def export_multiple_sessions_zip(self, session_ids: list[str]) -> bytes:
+        """Export multiple sessions as ZIP package."""
+        zip_buffer = io.BytesIO()
+
+        with zipfile.ZipFile(zip_buffer, "w", zipfile.ZIP_DEFLATED) as zipf:
+            for session_id in session_ids:
+                try:
+                    session_zip_data = await self.export_session_zip(session_id)
+
+                    with zipfile.ZipFile(io.BytesIO(session_zip_data), "r") as session_zipf:
+                        for file_info in session_zipf.infolist():
+                            file_data = session_zipf.read(file_info.filename)
+                            new_path = f"{session_id}/{file_info.filename}"
+                            zipf.writestr(new_path, file_data)
+
+                    self.logger.info(f"Added session {session_id} to export")
+
+                except Exception as e:
+                    self.logger.error(f"Failed to export session {session_id}: {e}")
+
+        zip_buffer.seek(0)
+        return zip_buffer.getvalue()
+
+    def _session_to_dict(self, session: Session) -> SessionDict:
+        """Convert Session to typed dict."""
+        return SessionDict(
+            id=session.id,
+            doctor_id=session.doctor_id,
+            patient_name=session.patient_name,
+            clinic_number=session.clinic_number,
+            medical_record_number=session.medical_record_number,
+            diagnosis=session.diagnosis,
+            status=session.status.value,
+            started_at=session.started_at.isoformat() if session.started_at else None,
+            ended_at=session.ended_at.isoformat() if session.ended_at else None,
+            created_at=session.created_at.isoformat(),
+        )
+
+    def _utterance_to_dict(self, utterance: Utterance) -> UtteranceDict:
+        """Convert Utterance to typed dict."""
+        return UtteranceDict(
+            id=utterance.id,
+            sequence=utterance.sequence,
+            speaker=utterance.speaker.value,
+            text=utterance.text,
+            confidence=utterance.confidence,
+            start_time_ms=utterance.start_time_ms,
+            end_time_ms=utterance.end_time_ms,
+            duration_ms=utterance.duration_ms,
+            timestamp=utterance.timestamp.isoformat(),
+        )
+
+    def _segment_to_dict(self, segment: Segment) -> SegmentDict:
+        """Convert Segment to typed dict."""
+        return SegmentDict(
+            id=segment.id,
+            sequence=segment.sequence,
+            audio_key=segment.audio_key,
+            started_at=segment.started_at.isoformat(),
+            ended_at=segment.ended_at.isoformat() if segment.ended_at else None,
+            duration_ms=segment.duration_ms,
+        )

audex/lib/injectors/__init__.py

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

audex/lib/injectors/cache.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import typing as t
+
+if t.TYPE_CHECKING:
+    from audex.config import Config
+    from audex.lib.cache import KVCache
+
+
+def make_cache(config: Config) -> KVCache:
+    from audex.lib.cache import KeyBuilder
+    from audex.lib.cache.inmemory import InmemoryCache
+
+    key_builder = KeyBuilder(
+        split_char=config.infrastructure.cache.split_char,
+        prefix=config.infrastructure.cache.prefix,
+    )
+
+    return InmemoryCache(
+        key_builder=key_builder,
+        cache_type=config.infrastructure.cache.inmemory.cache_type,
+        maxsize=config.infrastructure.cache.inmemory.max_size,
+        default_ttl=config.infrastructure.cache.inmemory.default_ttl,
+        negative_ttl=config.infrastructure.cache.inmemory.negative_ttl,
+    )

audex/lib/injectors/container.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from dependency_injector import containers
+from dependency_injector import providers
+
+from audex.config import Config
+from audex.lib.injectors.cache import make_cache
+from audex.lib.injectors.exporter import make_exporter
+from audex.lib.injectors.recorder import make_recorder
+from audex.lib.injectors.server import make_server
+from audex.lib.injectors.session import make_session_manager
+from audex.lib.injectors.sqlite import make_sqlite
+from audex.lib.injectors.store import make_store
+from audex.lib.injectors.transcription import make_transcription
+from audex.lib.injectors.usb import make_usb_manager
+from audex.lib.injectors.vpr import make_vpr
+from audex.lib.injectors.wifi import make_wifi_manager
+from audex.lib.repos.container import RepositoryContainer
+
+
+class InfrastructureContainer(containers.DeclarativeContainer):
+    # Dependencies
+    config = providers.Dependency(instance_of=Config)
+
+    # Components
+    session_manager = providers.Singleton(make_session_manager, config=config)
+    cache = providers.Singleton(make_cache, config=config)
+    usb = providers.Singleton(make_usb_manager)
+    wifi = providers.Singleton(make_wifi_manager)
+    sqlite = providers.Singleton(make_sqlite, config=config)
+    store = providers.Singleton(make_store, config=config)
+    vpr = providers.Singleton(make_vpr, config=config)
+    recorder = providers.Singleton(make_recorder, config=config, store=store)
+    transcription = providers.Singleton(make_transcription, config=config)
+    repository = providers.Container(RepositoryContainer, sqlite=sqlite)
+    exporter = providers.Factory(
+        make_exporter,
+        session_repo=repository.session,
+        segment_repo=repository.segment,
+        utterance_repo=repository.utterance,
+        store=store,
+    )
+    server = providers.Factory(
+        make_server,
+        doctor_repo=repository.doctor,
+        exporter=exporter,
+    )

audex/lib/injectors/exporter.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import typing as t
+
+if t.TYPE_CHECKING:
+    from audex.lib.exporter import Exporter
+    from audex.lib.repos.segment import SegmentRepository
+    from audex.lib.repos.session import SessionRepository
+    from audex.lib.repos.utterance import UtteranceRepository
+    from audex.lib.store import Store
+
+
+def make_exporter(
+    session_repo: SessionRepository,
+    segment_repo: SegmentRepository,
+    utterance_repo: UtteranceRepository,
+    store: Store,
+) -> Exporter:
+    from audex.lib.exporter import Exporter
+
+    return Exporter(
+        session_repo=session_repo,
+        segment_repo=segment_repo,
+        utterance_repo=utterance_repo,
+        store=store,
+    )