nexo-schemas 0.0.16__py3-none-any.whl

nexo/schemas/application.py

@@ -0,0 +1,292 @@
+import socket
+from Crypto.PublicKey.RSA import RsaKey
+from enum import StrEnum
+from functools import cached_property
+from pathlib import Path
+from pydantic import BaseModel, Field, computed_field, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from typing import Annotated, ClassVar, Self, TypeVar, overload
+from uuid import UUID
+from nexo.enums.environment import Environment
+from nexo.enums.system import SystemRole, ListOfSystemRoles
+from nexo.enums.user import UserType
+from nexo.types.boolean import OptBool
+from nexo.types.dict import StrToAnyDict
+from nexo.types.misc import BytesOrStr
+from nexo.types.string import ListOfStrs, OptStr
+from .mixins.identity import EntityIdentifier
+from .operation.enums import ListOfOperationTypes
+from .security.api_key import validate
+from .security.authentication import SystemCredentials, SystemUser, SystemAuthentication
+from .security.authorization import APIKeyAuthorization
+from .security.enums import Domain
+from .security.token import SystemToken
+
+
+class Execution(StrEnum):
+    CONTAINER = "container"
+    DIRECT = "direct"
+
+    @classmethod
+    def choices(cls) -> ListOfStrs:
+        return [e.value for e in cls]
+
+
+class ApplicationContext(BaseSettings):
+    model_config: ClassVar[SettingsConfigDict] = SettingsConfigDict(extra="ignore")
+
+    name: Annotated[str, Field(..., validation_alias="NAME")]
+    environment: Annotated[Environment, Field(..., validation_alias="ENVIRONMENT")]
+    service_key: Annotated[str, Field(..., validation_alias="SERVICE_KEY")]
+
+    @computed_field
+    @cached_property
+    def instance_id(self) -> str:
+        return socket.gethostname()
+
+    @classmethod
+    def new(cls) -> Self:
+        return cls()  # type: ignore
+
+
+OptApplicationContext = ApplicationContext | None
+
+
+class ApplicationContextMixin(BaseModel):
+    application_context: ApplicationContext = Field(
+        default_factory=ApplicationContext.new,
+        description="Application's context",
+    )
+
+
+class ApplicationSettings(BaseSettings):
+    model_config: ClassVar[SettingsConfigDict] = SettingsConfigDict(extra="ignore")
+
+    @computed_field
+    @cached_property
+    def instance_id(self) -> str:
+        return socket.gethostname()
+
+    # Application related settings
+    NAME: Annotated[str, Field(..., description="Application's name")]
+    # Service related settings
+    ENVIRONMENT: Annotated[Environment, Field(..., description="Environment")]
+    SERVICE_KEY: Annotated[str, Field(..., description="Service's key")]
+    SERVICE_NAME: Annotated[str, Field(..., description="Service's name")]
+
+    @cached_property
+    def context(self) -> ApplicationContext:
+        return ApplicationContext(
+            name=self.NAME, environment=self.ENVIRONMENT, service_key=self.SERVICE_KEY
+        )
+
+    CLIENT_ID: Annotated[UUID, Field(..., description="Client's ID")]
+    CLIENT_SECRET: Annotated[UUID, Field(..., description="Client's Secret")]
+
+    # Serving related settings
+    EXECUTION: Annotated[
+        Execution, Field(Execution.CONTAINER, description="Execution mode")
+    ] = Execution.CONTAINER
+    RELOAD: Annotated[OptBool, Field(None, description="Reload")] = None
+
+    @cached_property
+    def reload(self) -> bool:
+        if self.RELOAD is not None:
+            return self.RELOAD
+        else:
+            return (
+                self.EXECUTION is Execution.DIRECT
+                and self.ENVIRONMENT is Environment.LOCAL
+            )
+
+    HOST: Annotated[str, Field("127.0.0.1", description="Application's host")] = (
+        "127.0.0.1"
+    )
+    PORT: Annotated[int, Field(8000, description="Application's port")] = 8000
+    HOST_PORT: Annotated[int, Field(8000, description="Host's port")] = 8000
+
+    @cached_property
+    def port(self) -> int:
+        if self.EXECUTION is Execution.DIRECT and self.ENVIRONMENT is Environment.LOCAL:
+            return self.HOST_PORT
+        else:
+            return self.PORT
+
+    DOCKER_NETWORK: Annotated[str, Field(..., description="Docker's network")]
+
+    @model_validator(mode="before")
+    def define_default_docker_network(cls, data: StrToAnyDict):
+        if "DOCKER_NETWORK" not in data:
+            data["DOCKER_NETWORK"] = data["NAME"]
+        return data
+
+    ROOT_PATH: Annotated[str, Field("", description="Application's root path")] = ""
+
+    # Configuration related settings
+    USE_LOCAL_CONFIG: Annotated[
+        bool, Field(False, description="Whether to use locally stored config")
+    ] = False
+    CONFIG_PATH: Annotated[OptStr, Field(None, description="Config path")] = None
+
+    @model_validator(mode="after")
+    def validate_config_path(self) -> Self:
+        if self.USE_LOCAL_CONFIG:
+            if self.CONFIG_PATH is None:
+                self.CONFIG_PATH = f"/etc/{self.NAME}/config/{self.SERVICE_KEY}/{self.ENVIRONMENT}.yaml"
+            config_path = Path(self.CONFIG_PATH)
+            if not config_path.exists() or not config_path.is_file():
+                raise ValueError(
+                    f"Config path '{self.CONFIG_PATH}' either did not exist or is not a file"
+                )
+
+        return self
+
+    # Credential related settings
+    GOOGLE_APPLICATION_CREDENTIALS: Annotated[
+        str,
+        Field(
+            ...,
+            description="Google application credential's file path",
+        ),
+    ]
+
+    @model_validator(mode="before")
+    def define_default_google_aplication_credentials(cls, data: StrToAnyDict):
+        if "GOOGLE_APPLICATION_CREDENTIALS" not in data:
+            name: str = data["NAME"]
+            credentials = f"/etc/{name}/credentials/google-service-account.json"
+            data["GOOGLE_APPLICATION_CREDENTIALS"] = credentials
+        return data
+
+    API_KEY: Annotated[str, Field(..., description="Maleo's API Key")]
+
+    @model_validator(mode="after")
+    def validate_api_key(self) -> Self:
+        validate(self.API_KEY, self.NAME, self.ENVIRONMENT)
+        return self
+
+    @cached_property
+    def authorization(self) -> APIKeyAuthorization:
+        return APIKeyAuthorization(credentials=self.API_KEY)
+
+    SA_ID: Annotated[int, Field(..., description="SA's ID", ge=1)]
+    SA_UUID: Annotated[UUID, Field(..., description="SA's UUID")]
+    SA_ROLES: Annotated[
+        ListOfSystemRoles,
+        Field([SystemRole.ADMINISTRATOR], description="SA's Roles", min_length=1),
+    ] = [SystemRole.ADMINISTRATOR]
+    SA_USERNAME: Annotated[str, Field(..., description="SA's Username")]
+    SA_EMAIL: Annotated[str, Field(..., description="SA's Email")]
+
+    @cached_property
+    def authentication(self) -> SystemAuthentication:
+        return SystemAuthentication(
+            credentials=SystemCredentials(
+                user=EntityIdentifier[UserType](
+                    id=self.SA_ID, uuid=self.SA_UUID, type=UserType.SERVICE
+                ),
+                domain_roles=self.SA_ROLES,
+                scopes=["authenticated"]
+                + [f"{Domain.SYSTEM}:{role.value}" for role in self.SA_ROLES],
+            ),
+            user=SystemUser(display_name=self.SA_USERNAME, identity=self.SA_EMAIL),
+        )
+
+    @property
+    def token(self) -> SystemToken:
+        return SystemToken.new(sub=self.SA_UUID)
+
+    @overload
+    def generate_token_string(
+        self,
+        key: RsaKey,
+    ) -> str: ...
+    @overload
+    def generate_token_string(
+        self,
+        key: BytesOrStr,
+        *,
+        password: OptStr = None,
+    ) -> str: ...
+    def generate_token_string(
+        self,
+        key: BytesOrStr | RsaKey,
+        *,
+        password: OptStr = None,
+    ) -> str:
+        return self.token.to_string(key, password=password)
+
+    # Infra related settings
+    PUBLISH_HEARTBEAT: Annotated[
+        OptBool, Field(None, description="Whether to publish heartbeat")
+    ] = None
+
+    @cached_property
+    def publish_heartbeat(self) -> bool:
+        if self.PUBLISH_HEARTBEAT is not None:
+            return self.PUBLISH_HEARTBEAT
+        else:
+            return self.ENVIRONMENT in (Environment.STAGING, Environment.PRODUCTION)
+
+    PUBLISH_RESOURCE_MEASUREMENT: Annotated[
+        OptBool, Field(None, description="Whether to publish resource measurement")
+    ] = None
+
+    @cached_property
+    def publish_resource_measurement(self) -> bool:
+        if self.PUBLISH_RESOURCE_MEASUREMENT is not None:
+            return self.PUBLISH_RESOURCE_MEASUREMENT
+        else:
+            return self.ENVIRONMENT in (Environment.STAGING, Environment.PRODUCTION)
+
+    # Operation related settings
+    PUBLISHABLE_OPERATIONS: Annotated[
+        ListOfOperationTypes, Field([], description="Publishable operations")
+    ] = []
+
+    # Security related settings
+    USE_LOCAL_KEY: Annotated[
+        bool, Field(False, description="Whether to use locally stored key")
+    ] = False
+    PRIVATE_KEY_PASSWORD: Annotated[
+        OptStr, Field(None, description="Private key's password")
+    ] = None
+    PRIVATE_KEY_PATH: Annotated[str, Field(..., description="Private key's path")]
+
+    @model_validator(mode="before")
+    def define_default_private_key_path(cls, data: StrToAnyDict):
+        if "PRIVATE_KEY_PATH" not in data:
+            name: str = data["NAME"]
+            keys = f"/etc/{name}/keys/private.pem"
+            data["PRIVATE_KEY_PATH"] = keys
+        return data
+
+    PUBLIC_KEY_PATH: Annotated[str, Field(..., description="Public key's path")]
+
+    @model_validator(mode="before")
+    def define_default_public_key_path(cls, data: StrToAnyDict):
+        if "PUBLIC_KEY_PATH" not in data:
+            name: str = data["NAME"]
+            keys = f"/etc/{name}/keys/public.pem"
+            data["PUBLIC_KEY_PATH"] = keys
+        return data
+
+    @model_validator(mode="after")
+    def validate_keys_path(self) -> Self:
+        if self.USE_LOCAL_KEY:
+            private_key_path = Path(self.PRIVATE_KEY_PATH)
+            if not private_key_path.exists() or not private_key_path.is_file():
+                raise ValueError(
+                    f"Private key path: '{self.PRIVATE_KEY_PATH}' either did not exist or is not a file"
+                )
+
+            public_key_path = Path(self.PUBLIC_KEY_PATH)
+            if not public_key_path.exists() or not public_key_path.is_file():
+                raise ValueError(
+                    f"Public key path: '{self.PUBLIC_KEY_PATH}' either did not exist or is not a file"
+                )
+
+        return self
+
+
+ApplicationSettingsT = TypeVar("ApplicationSettingsT", bound=ApplicationSettings)

nexo/schemas/connection.py

@@ -0,0 +1,134 @@
+from datetime import datetime, timezone
+from pydantic import BaseModel, Field
+from starlette.requests import HTTPConnection
+from typing import Annotated, Callable, Generic, TypeVar
+from uuid import UUID, uuid4
+from nexo.enums.connection import Scheme, Header
+from nexo.types.boolean import OptBool
+from nexo.types.dict import OptStrToStrDict
+from nexo.types.string import OptStr, OptListOfDoubleStrs
+from .user_agent import UserAgent, OptUserAgent
+
+
+class ConnectionContext(BaseModel):
+    id: Annotated[UUID, Field(uuid4(), description="Connection's ID")] = uuid4()
+
+    executed_at: Annotated[
+        datetime,
+        Field(datetime.now(tz=timezone.utc), description="Executed At Timestamp"),
+    ] = datetime.now(tz=timezone.utc)
+
+    scheme: Annotated[Scheme, Field(..., description="Connection's scheme (http/ws)")]
+
+    method: Annotated[
+        OptStr, Field(None, description="HTTP method (None for WebSocket)")
+    ] = None
+
+    url: Annotated[str, Field(..., description="Connection URL")]
+    ip_address: Annotated[str, Field("unknown", description="Client's IP address")] = (
+        "unknown"
+    )
+    is_internal: Annotated[
+        OptBool, Field(None, description="True if IP is internal")
+    ] = None
+
+    headers: Annotated[
+        OptListOfDoubleStrs, Field(None, description="Connection's headers")
+    ] = None
+
+    path_params: Annotated[
+        OptStrToStrDict, Field(None, description="Path parameters")
+    ] = None
+
+    query_params: Annotated[OptStr, Field(None, description="Query parameters")] = None
+
+    user_agent: Annotated[OptUserAgent, Field(None, description="User agent")] = None
+
+    referer: Annotated[OptStr, Field(None, description="Referrer URL")] = None
+
+    origin: Annotated[OptStr, Field(None, description="Origin header")] = None
+
+    host: Annotated[OptStr, Field(None, description="Host header")] = None
+
+    forwarded_proto: Annotated[
+        OptStr, Field(None, description="Forwarded protocol")
+    ] = None
+
+    language: Annotated[OptStr, Field(None, description="Accepted languages")] = None
+
+    @classmethod
+    def extract_client_ip(cls, conn: HTTPConnection) -> str:
+        x_forwarded_for = conn.headers.get(Header.X_FORWARDED_FOR)
+        if x_forwarded_for:
+            ips = [ip.strip() for ip in x_forwarded_for.split(",")]
+            return ips[0]
+
+        x_real_ip = conn.headers.get(Header.X_REAL_IP)
+        if x_real_ip:
+            return x_real_ip
+
+        return conn.client.host if conn.client else "unknown"
+
+    @classmethod
+    def from_connection(cls, conn: HTTPConnection) -> "ConnectionContext":
+        id = getattr(conn.state, "connection_id", None)
+        if not id or not isinstance(id, UUID):
+            id = uuid4()
+            conn.state.connection_id = id
+
+        executed_at = getattr(conn.state, "executed_at", None)
+        if not executed_at or not isinstance(executed_at, datetime):
+            executed_at = datetime.now(tz=timezone.utc)
+            conn.state.executed_at = executed_at
+
+        ip_address = cls.extract_client_ip(conn)
+
+        ua_string = conn.headers.get(Header.USER_AGENT, "")
+        user_agent = (
+            UserAgent.from_string(user_agent_string=ua_string) if ua_string else None
+        )
+
+        return cls(
+            id=id,
+            executed_at=executed_at,
+            scheme=Scheme(conn.url.scheme),
+            method=getattr(conn, "method", None),  # WebSocket doesn’t have method
+            url=str(conn.url),
+            ip_address=ip_address,
+            is_internal=(
+                None
+                if ip_address == "unknown"
+                else (
+                    ip_address.startswith("10.")
+                    or ip_address.startswith("192.168.")
+                    or ip_address.startswith("172.")
+                    or ip_address.startswith("127.")
+                )
+            ),
+            headers=conn.headers.items(),
+            path_params=conn.path_params,
+            query_params=(None if not conn.query_params else str(conn.query_params)),
+            user_agent=user_agent,
+            referer=conn.headers.get(Header.REFERER),
+            origin=conn.headers.get(Header.ORIGIN),
+            host=conn.headers.get(Header.HOST),
+            forwarded_proto=conn.headers.get(Header.X_FORWARDED_PROTO),
+            language=conn.headers.get(Header.ACCEPT_LANGUAGE),
+        )
+
+    @classmethod
+    def as_dependency(cls) -> Callable[[HTTPConnection], "ConnectionContext"]:
+        def dependency(conn: HTTPConnection) -> "ConnectionContext":
+            return cls.from_connection(conn)
+
+        return dependency
+
+
+OptConnectionContext = ConnectionContext | None
+OptConnectionContextT = TypeVar("OptConnectionContextT", bound=OptConnectionContext)
+
+
+class ConnectionContextMixin(BaseModel, Generic[OptConnectionContextT]):
+    connection_context: OptConnectionContextT = Field(
+        ..., description="Connection context"
+    )

nexo/schemas/data.py

@@ -0,0 +1,27 @@
+from pydantic import BaseModel, Field
+from typing import Annotated, Generic, Literal, TypeVar
+
+
+OldDataT = TypeVar("OldDataT")
+NewDataT = TypeVar("NewDataT")
+
+
+class DataPair(BaseModel, Generic[OldDataT, NewDataT]):
+    old: OldDataT = Field(..., description="Old data")
+    new: NewDataT = Field(..., description="New data")
+
+
+AnyDataT = TypeVar("AnyDataT")
+
+
+class DataMixin(BaseModel, Generic[AnyDataT]):
+    data: AnyDataT = Field(..., description="Data")
+
+
+ModelDataT = TypeVar("ModelDataT", bound=BaseModel)
+
+
+class PingData(BaseModel):
+    ping: Annotated[Literal["pong"], Field("pong", description="Ping response")] = (
+        "pong"
+    )

nexo/schemas/document.py

@@ -0,0 +1,237 @@
+import csv
+from io import StringIO
+from fastapi import UploadFile
+from pydantic import BaseModel, Field, PrivateAttr, computed_field, model_validator
+from typing import Annotated, ClassVar, Generic, Self, TypeVar
+from nexo.types.integer import OptInt
+from nexo.types.string import OptStr, OptStrT, SeqOfStrs
+from .error.enums import ErrorCode
+
+
+class Document(BaseModel):
+    _raw: UploadFile | None = PrivateAttr(None)
+    content: Annotated[bytes, Field(..., description="Content", exclude=True)]
+    content_type: Annotated[str, Field(..., description="Content Type")]
+    filename: Annotated[str, Field(..., description="Filename")]
+    size: Annotated[int, Field(..., description="Size", gt=0)]
+
+    @classmethod
+    async def from_file(
+        cls,
+        file: UploadFile,
+        *,
+        max_size: OptInt = None,
+        valid_content_types: SeqOfStrs | str | None = None,
+        valid_extensions: SeqOfStrs | str | None = None,
+    ) -> Self:
+        content = await file.read()
+        if not content:
+            raise ValueError(ErrorCode.BAD_REQUEST, "Content can not be empty")
+
+        size = file.size
+        if size is None or size <= 0:
+            raise ValueError(
+                ErrorCode.BAD_REQUEST, "Size can not be None and must be larger than 0"
+            )
+        if max_size is not None:
+            if size > max_size:
+                raise ValueError(
+                    ErrorCode.BAD_REQUEST,
+                    f"Size of {size} exceeds set maximum of {max_size}",
+                )
+
+        content_type = file.content_type
+        if content_type is None:
+            raise ValueError("Content type can not be None")
+        if valid_content_types is not None:
+            if isinstance(valid_content_types, str):
+                if content_type != valid_content_types:
+                    raise ValueError(
+                        ErrorCode.BAD_REQUEST,
+                        f"Invalid content type of '{content_type}'. Must be '{valid_content_types}'",
+                    )
+            else:
+                if content_type not in valid_content_types:
+                    raise ValueError(
+                        ErrorCode.BAD_REQUEST,
+                        f"Invalid content type of '{content_type}'. Must be one of {valid_content_types}",
+                    )
+
+        filename = file.filename
+        if filename is None:
+            raise ValueError("Filename can not be None")
+        if valid_extensions is not None:
+            if isinstance(valid_extensions, str):
+                if not filename.endswith(valid_extensions):
+                    raise ValueError(
+                        ErrorCode.BAD_REQUEST,
+                        f"Invalid extension. Must be '{valid_extensions}'",
+                    )
+            else:
+                if not any(filename.endswith(ext) for ext in valid_extensions):
+                    raise ValueError(
+                        ErrorCode.BAD_REQUEST,
+                        f"Invalid extension. Must be one of {valid_extensions}",
+                    )
+
+        filename = filename.replace(" ", "_")
+
+        document = cls(
+            content=content, content_type=content_type, filename=filename, size=size
+        )
+        document._raw = file
+
+        return document
+
+
+class CSVDocument(Document):
+    _content_type: ClassVar[str] = "text/csv"
+
+    def _validate_content_type(self):
+        if self.content_type != self._content_type:
+            raise TypeError(
+                ErrorCode.BAD_REQUEST,
+                f"CSV Document content type must be {self._content_type}",
+            )
+
+    @model_validator(mode="after")
+    def validate_content_type(self) -> Self:
+        self._validate_content_type()
+        return self
+
+    @classmethod
+    def from_document(cls, document: Document) -> Self:
+        csv_document = cls(
+            content=document.content,
+            content_type=document.content_type,
+            filename=document.filename,
+            size=document.size,
+        )
+        csv_document._raw = document._raw
+        return csv_document
+
+    @classmethod
+    async def from_file(
+        cls,
+        file: UploadFile,
+        *,
+        max_size: OptInt = None,
+        valid_content_types: SeqOfStrs | str | None = "text/csv",
+        valid_extensions: SeqOfStrs | str | None = ".csv",
+    ) -> Self:
+        return await super().from_file(
+            file,
+            max_size=max_size,
+            valid_content_types=valid_content_types,
+            valid_extensions=valid_extensions,
+        )
+
+    def _validate_no_duplicate_rows(self, rows: list[dict[str, OptStr]]) -> None:
+        seen = set()
+        for index, row in enumerate(rows):
+            row_tuple = tuple(sorted(row.items()))
+            if row_tuple in seen:
+                raise ValueError(
+                    ErrorCode.BAD_REQUEST,
+                    f"Duplicate row found at index {index}: {row}",
+                )
+            seen.add(row_tuple)
+
+    @computed_field
+    @property
+    def rows(self) -> list[dict[str, OptStr]]:
+        self._validate_content_type()
+        text = self.content.decode(encoding="utf-8-sig")
+        reader = csv.DictReader(StringIO(text), skipinitialspace=True)
+        raw_rows = list(reader)
+        new_rows: list[dict[str, OptStr]] = []
+
+        for row in raw_rows:
+            cleaned: dict[str, OptStr] = {}
+            for key, value in row.items():
+                cleaned[key] = value.strip() if value else None
+            new_rows.append(cleaned)
+
+        # Run duplicate validation here
+        self._validate_no_duplicate_rows(new_rows)
+
+        return new_rows
+
+
+class PDFDocument(Document):
+    _content_type: ClassVar[str] = "application/pdf"
+
+    def _validate_content_type(self):
+        if self.content_type != self._content_type:
+            raise TypeError(f"PDF Document content type must be {self._content_type}")
+
+    @model_validator(mode="after")
+    def validate_content_type(self) -> Self:
+        self._validate_content_type()
+        return self
+
+    @classmethod
+    def from_document(cls, document: Document) -> Self:
+        pdf_document = cls(
+            content=document.content,
+            content_type=document.content_type,
+            filename=document.filename,
+            size=document.size,
+        )
+        pdf_document._raw = document._raw
+        return pdf_document
+
+    @classmethod
+    async def from_file(
+        cls,
+        file: UploadFile,
+        *,
+        max_size: OptInt = None,
+        valid_content_types: SeqOfStrs | str | None = "application/pdf",
+        valid_extensions: SeqOfStrs | str | None = ".pdf",
+    ) -> Self:
+        return await super().from_file(
+            file,
+            max_size=max_size,
+            valid_content_types=valid_content_types,
+            valid_extensions=valid_extensions,
+        )
+
+
+DocumentT = TypeVar("DocumentT", bound=Document)
+OptDocument = Document | None
+OptDocumentT = TypeVar("OptDocumentT", bound=OptDocument)
+ListOfDocuments = list[Document]
+ListOfDocumentsT = TypeVar("ListOfDocumentsT", bound=ListOfDocuments)
+OptListOfDocuments = ListOfDocuments | None
+OptListOfDocumentsT = TypeVar("OptListOfDocumentsT", bound=OptListOfDocuments)
+
+
+class DocumentMixin(BaseModel, Generic[OptDocumentT]):
+    document: Annotated[OptDocumentT, Field(..., description="Document")]
+
+
+class HeterogenousDocumentsMixin(BaseModel, Generic[OptListOfDocumentsT]):
+    documents: Annotated[
+        OptListOfDocumentsT, Field(..., description="Documents", min_length=1)
+    ]
+
+
+class HomogenousDocumentsMixin(BaseModel, Generic[DocumentT]):
+    documents: Annotated[
+        list[DocumentT], Field(..., description="Documents", min_length=1)
+    ]
+
+
+class OptHomogenousDocumentsMixin(BaseModel, Generic[DocumentT]):
+    documents: Annotated[
+        list[DocumentT] | None, Field(None, description="Documents", min_length=1)
+    ] = None
+
+
+class DocumentName(BaseModel, Generic[OptStrT]):
+    document_name: Annotated[OptStrT, Field(..., description="Document's name")]
+
+
+class DocumentURL(BaseModel, Generic[OptStrT]):
+    document_url: Annotated[OptStrT, Field(..., description="Document's URL")]