audex 1.0.7a3__py3-none-any.whl

audex/lib/repos/vp.py

@@ -0,0 +1,286 @@
+from __future__ import annotations
+
+import builtins
+import typing as t
+
+import sqlalchemy as sa
+import sqlmodel as sqlm
+
+from audex.entity.vp import VP
+from audex.filters import Filter
+from audex.lib.database.sqlite import SQLite
+from audex.lib.repos.database.sqlite import SQLiteRepository
+from audex.lib.repos.tables.vp import VPTable
+
+
+class VPRepository(SQLiteRepository[VP]):
+    """SQLite implementation of VP repository.
+
+    Provides CRUD operations for VP entities with additional specialized
+    query methods for utterance management by session and segment.
+    """
+
+    __table__ = VPTable
+    __tablename__ = VPTable.__tablename__
+
+    def __init__(self, sqlite: SQLite) -> None:
+        super().__init__(sqlite)
+
+    async def create(self, data: VP, /) -> str:
+        """Create a new utterance in the database.
+
+        Args:
+            data: The utterance entity to create.
+
+        Returns:
+            The ID of the created utterance.
+        """
+        async with self.sqlite.session() as session:
+            utterance_table = VPTable.from_entity(data)
+            session.add(utterance_table)
+            await session.commit()
+            await session.refresh(utterance_table)
+            return utterance_table.id
+
+    async def read(self, id: str, /) -> VP | None:
+        """Read an utterance by ID.
+
+        Args:
+            id: The ID (id) of the utterance to retrieve.
+
+        Returns:
+            The utterance entity if found, None otherwise.
+        """
+        async with self.sqlite.session() as session:
+            stmt = sqlm.select(VPTable).where(VPTable.id == id)
+            result = await session.execute(stmt)
+            utterance_obj = result.scalar_one_or_none()
+
+            if utterance_obj is None:
+                return None
+
+            return utterance_obj.to_entity()
+
+    async def first(self, filter: Filter) -> VP | None:
+        """Retrieve the first utterance matching the filter.
+
+        Args:
+            filter: Filter to apply when searching for the utterance.
+
+        Returns:
+            The first utterance entity matching the filter, or None if no match.
+        """
+        spec = self.build_query_spec(filter)
+
+        async with self.sqlite.session() as session:
+            stmt = sqlm.select(VPTable)
+
+            for clause in spec.where:
+                stmt = stmt.where(clause)
+
+            for order in spec.order_by:
+                stmt = stmt.order_by(order)
+
+            stmt = stmt.limit(1)
+
+            result = await session.execute(stmt)
+            utterance_obj = result.scalar_one_or_none()
+
+            if utterance_obj is None:
+                return None
+
+            return utterance_obj.to_entity()
+
+    async def list(
+        self,
+        arg: builtins.list[str] | t.Optional[Filter] = None,  # noqa
+        *,
+        page_index: int = 0,
+        page_size: int = 100,
+    ) -> builtins.list[VP]:
+        """List utterances by IDs or with optional filtering and
+        pagination.
+
+        Args:
+            arg: Either a list of IDs to retrieve, or an optional filter.
+            page_index: Zero-based page index for pagination.
+            page_size: Number of items per page.
+
+        Returns:
+            List of utterance entities matching the criteria.
+        """
+        async with self.sqlite.session() as session:
+            if isinstance(arg, list):
+                if not arg:
+                    return []
+
+                stmt = sqlm.select(VPTable).where(sqlm.col(VPTable.id).in_(arg))
+                result = await session.execute(stmt)
+                utterance_objs = result.scalars().all()
+                return [obj.to_entity() for obj in utterance_objs]
+
+            spec = self.build_query_spec(arg)
+            stmt = sqlm.select(VPTable)
+
+            for clause in spec.where:
+                stmt = stmt.where(clause)
+
+            for order in spec.order_by:
+                stmt = stmt.order_by(order)
+
+            stmt = stmt.offset(page_index * page_size).limit(page_size)
+
+            result = await session.execute(stmt)
+            utterance_objs = result.scalars().all()
+            return [obj.to_entity() for obj in utterance_objs]
+
+    async def update(self, data: VP, /) -> str:
+        """Update an existing utterance.
+
+        Args:
+            data: The utterance entity with updated values.
+
+        Returns:
+            The ID of the updated utterance.
+
+        Raises:
+            ValueError: If the utterance with the given ID does not exist.
+        """
+        async with self.sqlite.session() as session:
+            stmt = sqlm.select(VPTable).where(VPTable.id == data.id)
+            result = await session.execute(stmt)
+            utterance_obj = result.scalar_one_or_none()
+
+            if utterance_obj is None:
+                raise ValueError(f"VP with id {data.id} not found")
+
+            utterance_obj.update(data)
+            session.add(utterance_obj)
+            await session.commit()
+            await session.refresh(utterance_obj)
+            return utterance_obj.id
+
+    async def update_many(self, datas: builtins.list[VP]) -> builtins.list[str]:
+        """Update multiple utterances in the database.
+
+        Args:
+            datas: List of utterance entities with updated values.
+
+        Returns:
+            List of IDs of the updated utterances.
+
+        Raises:
+            ValueError: If any utterance with the given ID does not exist.
+        """
+        if not datas:
+            return []
+
+        updated_ids: builtins.list[str] = []
+        async with self.sqlite.session() as session:
+            ids = [data.id for data in datas]
+            stmt = sqlm.select(VPTable).where(sqlm.col(VPTable.id).in_(ids))
+            result = await session.execute(stmt)
+            table_objs = {obj.id: obj for obj in result.scalars().all()}
+
+            missing_ids = set(ids) - set(table_objs.keys())
+            if missing_ids:
+                raise ValueError(f"VPs with IDs {missing_ids} not found")
+
+            for data in datas:
+                utterance_obj = table_objs[data.id]
+                utterance_obj.update(data)
+                session.add(utterance_obj)
+                updated_ids.append(utterance_obj.id)
+
+            await session.commit()
+            return updated_ids
+
+    async def delete(self, id: str, /) -> bool:
+        """Delete an utterance by ID.
+
+        Args:
+            id: The ID (id) of the utterance to delete.
+
+        Returns:
+            True if the utterance was deleted, False if not found.
+        """
+        async with self.sqlite.session() as session:
+            stmt = sqlm.select(VPTable).where(VPTable.id == id)
+            result = await session.execute(stmt)
+            utterance_obj = result.scalar_one_or_none()
+
+            if utterance_obj is None:
+                return False
+
+            await session.delete(utterance_obj)
+            await session.commit()
+            return True
+
+    async def delete_many(
+        self,
+        arg: builtins.list[str] | t.Optional[Filter] = None,  # noqa
+    ) -> builtins.list[str]:
+        """Delete multiple utterances by IDs or matching a filter.
+
+        Args:
+            arg: Either a list of IDs to delete, or an optional filter.
+
+        Returns:
+            If deleting by IDs, returns list of deleted IDs.
+            If deleting by filter, returns count of deleted records.
+        """
+        async with self.sqlite.session() as session:
+            if isinstance(arg, list):
+                if not arg:
+                    return []
+
+                stmt = sqlm.select(VPTable).where(sqlm.col(VPTable.id).in_(arg))
+                result = await session.execute(stmt)
+                utterance_objs = result.scalars().all()
+
+                if not utterance_objs:
+                    return []
+
+                utterance_ids = [obj.id for obj in utterance_objs]
+                for obj in utterance_objs:
+                    await session.delete(obj)
+
+                await session.commit()
+                return utterance_ids
+
+            spec = self.build_query_spec(arg)
+            stmt = sqlm.select(VPTable.id)  # type: ignore
+            for clause in spec.where:
+                stmt = stmt.where(clause)
+
+            result = await session.execute(stmt)
+            utterance_ids = [row[0] for row in result.all()]
+
+            if not utterance_ids:
+                return []
+
+            delete_stmt = sa.delete(VPTable).where(sqlm.col(VPTable.id).in_(utterance_ids))
+            await session.execute(delete_stmt)
+            await session.commit()
+
+            return utterance_ids
+
+    async def count(self, filter: t.Optional[Filter] = None) -> int:  # noqa
+        """Count utterances matching the filter.
+
+        Args:
+            filter: Optional filter to apply. If None, counts all utterances.
+
+        Returns:
+            Number of utterances matching the filter.
+        """
+        spec = self.build_query_spec(filter)
+
+        async with self.sqlite.session() as session:
+            stmt = sqlm.select(sa.func.count()).select_from(VPTable)
+
+            for clause in spec.where:
+                stmt = stmt.where(clause)
+
+            result = await session.execute(stmt)
+            return result.scalar_one()

audex/lib/restful.py

@@ -0,0 +1,251 @@
+from __future__ import annotations
+
+import typing as t
+
+import httpx
+import pydantic as pyd
+import tenacity
+
+from audex.helper.mixin import AsyncContextMixin
+
+RespT = t.TypeVar("RespT", bound=pyd.BaseModel)
+
+
+class BearerAuth(httpx.Auth):
+    """HTTP Bearer token authentication handler for httpx.
+
+    Implements the httpx.Auth interface to automatically add Bearer token
+    authentication to requests.
+
+    Args:
+        token: The bearer token to use for authentication.
+    """
+
+    def __init__(self, token: str):
+        self.token = token
+
+    def auth_flow(self, request: httpx.Request) -> t.Generator[httpx.Request, httpx.Response, None]:
+        """Add Bearer token to request Authorization header.
+
+        Args:
+            request: The HTTP request to authenticate.
+
+        Yields:
+            The authenticated request with Authorization header.
+        """
+        request.headers["Authorization"] = f"Bearer {self.token}"
+        yield request
+
+
+class RESTfulMixin(AsyncContextMixin):
+    """Abstract base class for RESTful API clients with async support.
+
+    Provides a high-level interface for making HTTP requests to RESTful APIs
+    with automatic retry logic, response validation using Pydantic models,
+    and built-in error handling.
+
+    Features:
+    - Automatic retry with configurable attempts and wait time
+    - Response validation and parsing using Pydantic models
+    - Support for Bearer token and custom authentication
+    - Proxy support
+    - Configurable timeouts and default headers/params
+    - Async context manager support
+
+    Attributes:
+        url: The base URL for the API.
+        http_client: The underlying httpx AsyncClient instance.
+
+    Args:
+        base_url: Base URL for all API requests.
+        auth: Optional httpx authentication handler.
+        proxy: Optional proxy URL.
+        timeout: Request timeout in seconds. Defaults to 10.0.
+        http_client: Optional pre-configured httpx.AsyncClient. If not provided,
+            a new client will be created.
+        default_headers: Optional default headers for all requests.
+        default_params: Optional default query parameters for all requests.
+
+    Example:
+        ```python
+        class MyAPIResponse(pyd.BaseModel):
+            id: str
+            name: str
+
+
+        class MyAPI(RESTful):
+            async def get_item(self, item_id: str) -> MyAPIResponse:
+                return await self.request(
+                    f"/items/{item_id}",
+                    method="GET",
+                    cast_to=MyAPIResponse,
+                )
+
+
+        # Usage
+        async with MyAPI(
+            "https://api.example.com", auth=BearerAuth("token")
+        ) as api:
+            item = await api.get_item("123")
+            print(item.name)
+        ```
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        auth: httpx.Auth | None = None,
+        proxy: str | httpx.URL | None = None,
+        timeout: float = 10.0,
+        http_client: httpx.AsyncClient | None = None,
+        default_headers: dict[str, str] | None = None,
+        default_params: dict[str, t.Any] | None = None,
+    ):
+        self.url = base_url
+        self.http_client = http_client or httpx.AsyncClient(
+            base_url=base_url,
+            auth=auth,
+            proxy=proxy,
+            timeout=timeout,
+            headers=default_headers,
+            params=default_params,
+        )
+
+    async def request(
+        self,
+        endpoint: str,
+        *,
+        method: t.Literal["GET", "POST", "PUT", "DELETE"] = "GET",
+        headers: t.Mapping[str, str] | None = None,
+        params: t.Mapping[str, t.Any] | None = None,
+        json: t.Mapping[str, t.Any] | None = None,
+        cast_to: type[RespT],
+        validate: bool = True,
+        strict: bool = True,
+        raise_for_status: bool = True,
+        max_retries: int = 3,
+        retry_wait: float = 2.0,
+    ) -> RespT:
+        """Make an HTTP request with automatic retry and response
+        validation.
+
+        Sends an HTTP request to the specified endpoint and parses the response
+        into the specified Pydantic model. Automatically retries on failure and
+        validates the response data.
+
+        Args:
+            endpoint: API endpoint path (relative to base_url).
+            method: HTTP method to use. Defaults to "GET".
+            headers: Optional request headers to merge with default headers.
+            params: Optional query parameters to merge with default params.
+            json: Optional JSON body for POST/PUT requests.
+            cast_to: Pydantic model class to parse the response into.
+            validate: Whether to validate response data. Defaults to True.
+            strict: Whether to use strict validation (reject extra fields).
+                Defaults to True.
+            raise_for_status: Whether to raise an exception for HTTP error
+                status codes. Defaults to True.
+            max_retries: Maximum number of retry attempts. Defaults to 3.
+            retry_wait: Wait time in seconds between retries. Defaults to 2.0.
+
+        Returns:
+            Parsed response as an instance of cast_to model.
+
+        Raises:
+            httpx.HTTPStatusError: If the response status indicates an error
+                after all retries.
+            pyd.ValidationError: If response validation fails.
+            tenacity.RetryError: If all retry attempts are exhausted.
+
+        Example:
+            ```python
+            class UserResponse(pyd.BaseModel):
+                user_id: str
+                username: str
+                email: str
+
+
+            # GET request
+            user = await api.request(
+                "/users/123", method="GET", cast_to=UserResponse
+            )
+
+            # POST request with retry
+            new_user = await api.request(
+                "/users",
+                method="POST",
+                json={"username": "john", "email": "john@example.com"},
+                cast_to=UserResponse,
+                max_retries=5,
+                retry_wait=3.0,
+            )
+            ```
+        """
+
+        @tenacity.retry(
+            stop=tenacity.stop_after_attempt(max_retries),
+            wait=tenacity.wait_fixed(retry_wait),
+            reraise=True,
+        )
+        async def _do_request(
+            method: str,
+            endpoint: str,
+            headers: t.Mapping[str, str] | None,
+            params: t.Mapping[str, t.Any] | None,
+            json: t.Mapping[str, t.Any] | None,
+        ) -> httpx.Response:
+            response = await self.http_client.request(
+                method,
+                endpoint,
+                headers=headers,
+                params=params,
+                json=json,
+            )
+            if raise_for_status:
+                response.raise_for_status()
+            return response
+
+        response = await _do_request(method, endpoint, headers, params, json)
+        if validate:
+            return cast_to.model_validate(response.json(), strict=strict)
+        return cast_to.model_construct(**response.json())
+
+    async def close(self) -> None:
+        """Close the HTTP client and cleanup resources.
+
+        Should be called when the API client is no longer needed to properly
+        close all connections. Automatically called when using as a context manager.
+
+        Example:
+            ```python
+            api = MyAPI("https://api.example.com")
+            try:
+                await api.get_data()
+            finally:
+                await api.close()
+
+            # Or use as context manager
+            async with MyAPI("https://api.example.com") as api:
+                await api.get_data()
+            ```
+        """
+        await self.http_client.aclose()
+
+    def __repr__(self) -> str:
+        return f"RESTFUL <{self.__class__.__name__} base_url={self.url}>"
+
+
+class BaseModel(pyd.BaseModel):
+    """Base Pydantic model with common configuration.
+
+    Sets common configurations for all derived models, such as allowing
+    arbitrary types and enabling ORM mode.
+    """
+
+    model_config = pyd.ConfigDict(
+        arbitrary_types_allowed=True,  # Allow arbitrary types
+        serialize_by_alias=True,  # Use alias names when serializing
+        validate_by_alias=True,  # Use alias names when validating
+        extra="ignore",
+    )

audex/lib/server/__init__.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import importlib.resources
+import pathlib
+import typing as t
+
+from starlette.applications import Starlette
+from starlette.middleware import Middleware
+from starlette.routing import Mount
+from starlette.routing import Route
+from starlette.staticfiles import StaticFiles
+from starlette.templating import Jinja2Templates
+
+from audex.helper.mixin import LoggingMixin
+from audex.lib.server.auth import AuthMiddleware
+from audex.lib.server.handlers import RequestHandlers
+
+if t.TYPE_CHECKING:
+    from audex.lib.exporter import Exporter
+    from audex.lib.repos.doctor import DoctorRepository
+
+
+class Server(LoggingMixin):
+    __logtag__ = "audex.lib.http"
+
+    def __init__(self, doctor_repo: DoctorRepository, exporter: Exporter):
+        super().__init__()
+        self.doctor_repo = doctor_repo
+        self.exporter = exporter
+
+        # Get template directory (relative to this file)
+        template_dir = importlib.resources.files("audex.lib.server").joinpath("templates")
+        self.templates = Jinja2Templates(directory=str(template_dir))
+
+        # Create handlers
+        self.handlers = RequestHandlers(
+            templates=self.templates,
+            doctor_repo=doctor_repo,
+            exporter=exporter,
+        )
+
+        # Create app
+        self.app = self._create_app()
+        self.server: t.Any = None
+
+    def _create_app(self) -> Starlette:
+        """Create Starlette application."""
+        routes = [
+            # Pages
+            Route("/login", self.handlers.login_page, methods=["GET"]),
+            Route("/", self.handlers.index_page, methods=["GET"]),
+            # API
+            Route("/api/login", self.handlers.api_login, methods=["POST"]),
+            Route("/api/logout", self.handlers.api_logout, methods=["POST"]),
+            Route("/api/sessions", self.handlers.api_list_sessions, methods=["GET"]),
+            Route(
+                "/api/sessions/{session_id}/export",
+                self.handlers.api_export_session,
+                methods=["GET"],
+            ),
+            Route(
+                "/api/sessions/export-multiple",
+                self.handlers.api_export_multiple,
+                methods=["POST"],
+            ),
+            # Static files
+            Mount(
+                "/static",
+                StaticFiles(directory=str(pathlib.Path(__file__).parent / "templates" / "static")),
+                name="static",
+            ),
+        ]
+
+        middleware = [
+            Middleware(AuthMiddleware, doctor_repo=self.doctor_repo),
+        ]
+
+        return Starlette(
+            debug=False,
+            routes=routes,
+            middleware=middleware,
+        )
+
+    async def start(self, host: str, port: int) -> None:
+        import uvicorn
+
+        self.logger.info(f"Starting HTTP server on {host}:{port}")
+
+        config = uvicorn.Config(self.app, host=host, port=port, log_level="info")
+
+        self.server = uvicorn.Server(config)
+        await self.server.serve()
+
+    async def close(self) -> None:
+        if self.server:
+            self.server.should_exit = True
+        self.logger.info("HTTP server stopped")