"""Material library service.""" from __future__ import annotations import base64 from pathlib import PurePosixPath from typing import Any, Callable from uuid import uuid4 from backend.dto.common import ApiError, ErrorCode from backend.dto.material_dto import Material, MaterialCategory, MaterialListResult from core.audit_service import AuditService from core.image_formats import ( IMAGE_EXTENSIONS_BY_MIME, SUPPORTED_IMAGE_EXTENSIONS, detect_image_format, ) from core.identity import RequestContext from core.storage import VfsStorage from database.repositories.material_repository import MaterialRepository from engines.vision_provider import ( VisionProvider, VisionProviderError, VisionRecognitionRequest, VisionRecognitionResult, ) MATERIAL_STATUSES = {"pending_upload", "pending_recognition", "pending_confirm", "confirmed", "archived"} MAX_UPLOAD_BYTES = 20 * 1024 * 1024 UPLOAD_SIZE_FIELDS = ("size_bytes", "content_length", "file_size", "size") UPLOAD_ALLOWED_EXTENSIONS = set(SUPPORTED_IMAGE_EXTENSIONS) UPLOAD_ALLOWED_CONTENT_TYPES = { mime_type: set(extensions) for mime_type, extensions in IMAGE_EXTENSIONS_BY_MIME.items() } class MaterialService: def __init__( self, repository: MaterialRepository, audit_service: AuditService, *, vision_provider_factory: Callable[[dict[str, Any]], VisionProvider | None] | None = None, default_recognition_route: str = "material_vlm", storage: VfsStorage | None = None, ): self.repository = repository self.audit_service = audit_service self.vision_provider_factory = vision_provider_factory self.default_recognition_route = default_recognition_route self.storage = storage or VfsStorage() def create_category(self, payload: dict[str, Any], ctx: RequestContext) -> MaterialCategory: name = str(payload.get("name") or "").strip() if not name: raise ApiError(ErrorCode.VALIDATION_FAILED, "category name is required", {"field": "name"}) parent_id = payload.get("parent_id") if parent_id and self.repository.get_category(parent_id) is None: raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "parent category not found", {"parent_id": parent_id}) category = self.repository.create_category( { "category_id": payload.get("category_id") or new_category_id(), "name": name, "parent_id": parent_id, "category_type": payload.get("category_type", "material"), "sort_order": payload.get("sort_order", 0), "metadata": payload.get("metadata") or {}, } ) self.audit_service.record( ctx=ctx, action="create_material_category", target_type="material_category", target_id=category.category_id, after_snapshot=category.to_dict(), ) return category def list_categories(self) -> list[MaterialCategory]: return self.repository.list_categories() def update_category(self, category_id: str, payload: dict[str, Any], ctx: RequestContext) -> MaterialCategory: before = self.get_category(category_id) if "name" in payload and not str(payload["name"]).strip(): raise ApiError(ErrorCode.VALIDATION_FAILED, "category name is required", {"field": "name"}) parent_id = payload.get("parent_id") if "parent_id" in payload else None if parent_id: if parent_id == category_id: raise ApiError(ErrorCode.VALIDATION_FAILED, "category cannot be its own parent", {"field": "parent_id"}) if self.repository.get_category(parent_id) is None: raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "parent category not found", {"parent_id": parent_id}) after = self.repository.update_category(category_id, payload) if after is None: raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "category not found", {"category_id": category_id}) self.audit_service.record( ctx=ctx, action="update_material_category", target_type="material_category", target_id=category_id, before_snapshot=before.to_dict(), after_snapshot=after.to_dict(), ) return after def delete_category(self, category_id: str, ctx: RequestContext) -> MaterialCategory: before = self.repository.delete_category(category_id) if before is None: raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "category not found", {"category_id": category_id}) self.audit_service.record( ctx=ctx, action="delete_material_category", target_type="material_category", target_id=category_id, before_snapshot=before.to_dict(), ) return before def get_category(self, category_id: str) -> MaterialCategory: category = self.repository.get_category(category_id) if category is None: raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "category not found", {"category_id": category_id}) return category def create_material(self, payload: dict[str, Any], ctx: RequestContext) -> Material: self.validate_material_payload(payload, creating=True) display_name = str(payload.get("display_name") or "").strip() status = payload.get("recognition_status", "pending_upload") material = self.repository.create_material( { "material_id": payload.get("material_id") or new_material_id(), "category_id": payload.get("category_id"), "display_name": display_name, "image_uri": payload.get("image_uri"), "thumbnail_uri": payload.get("thumbnail_uri"), "prompt": payload.get("prompt"), "negative_prompt": payload.get("negative_prompt"), "tags": payload.get("tags") or [], "recognition_status": status, "metadata": payload.get("metadata") or {}, } ) self.audit_service.record( ctx=ctx, action="create_material", target_type="material", target_id=material.material_id, after_snapshot=material.to_dict(), ) return material def list_materials( self, *, category_id: str | None = None, keyword: str | None = None, page: int = 1, page_size: int = 30, ) -> MaterialListResult: normalized_page = max(page, 1) normalized_page_size = min(max(page_size, 1), 100) items, total = self.repository.list_materials( category_id=category_id, keyword=keyword, page=normalized_page, page_size=normalized_page_size, ) return MaterialListResult(items=items, total=total, page=normalized_page, page_size=normalized_page_size) def get_material(self, material_id: str) -> Material: material = self.repository.get_material(material_id) if material is None or material.recognition_status == "archived": raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "material not found", {"material_id": material_id}) return material def update_material(self, material_id: str, payload: dict[str, Any], ctx: RequestContext) -> Material: before = self.get_material(material_id) self.validate_material_payload(payload, creating=False) update_payload = dict(payload) if "display_name" in update_payload: update_payload["display_name"] = str(update_payload["display_name"]).strip() after = self.repository.update_material(material_id, update_payload) if after is None: raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "material not found", {"material_id": material_id}) self.audit_service.record( ctx=ctx, action="update_material", target_type="material", target_id=material_id, before_snapshot=before.to_dict(), after_snapshot=after.to_dict(), ) return after def validate_material_payload(self, payload: dict[str, Any], *, creating: bool) -> None: if creating or "display_name" in payload: if not str(payload.get("display_name") or "").strip(): raise ApiError(ErrorCode.VALIDATION_FAILED, "display_name is required", {"field": "display_name"}) if creating or "category_id" in payload: self._validate_category(payload.get("category_id")) if creating or "image_uri" in payload: self._validate_storage_uri(payload.get("image_uri"), "image_uri") if creating or "thumbnail_uri" in payload: self._validate_storage_uri(payload.get("thumbnail_uri"), "thumbnail_uri") if creating or "recognition_status" in payload: self._validate_status(payload.get("recognition_status", "pending_upload")) def delete_material(self, material_id: str, ctx: RequestContext) -> Material: return self.update_material(material_id, {"recognition_status": "archived"}, ctx) def upload_material(self, payload: dict[str, Any], ctx: RequestContext) -> Material: image_uri = str(payload.get("image_uri") or "").strip() if not image_uri: raise ApiError(ErrorCode.VALIDATION_FAILED, "image_uri is required", {"field": "image_uri"}) filename = _normalize_upload_filename(payload.get("filename")) content_type = _normalize_upload_content_type(payload.get("content_type")) declared_size = _normalize_upload_size(payload) upload_metadata = _normalize_upload_metadata(payload.get("metadata")) recognition_route = _optional_text(payload.get("recognition_model_route")) if recognition_route: upload_metadata["recognition_model_route"] = recognition_route extension = _validate_upload_file_type(filename=filename, image_uri=image_uri, content_type=content_type) display_name = str(payload.get("display_name") or _display_name_from_filename(filename) or "Uploaded material").strip() thumbnail_uri = str(payload.get("thumbnail_uri") or image_uri).strip() return self.create_material( { "category_id": payload.get("category_id"), "display_name": display_name, "image_uri": image_uri, "thumbnail_uri": thumbnail_uri, "recognition_status": "pending_recognition", "metadata": { **upload_metadata, "upload": { "filename": filename, "content_type": content_type, "extension": extension, "size_bytes": declared_size, "max_size_bytes": MAX_UPLOAD_BYTES, "storage_reference_only": True, } }, }, ctx, ) def recognize_material(self, material_id: str, ctx: RequestContext) -> Material: material = self.get_material(material_id) if material.recognition_status == "confirmed": return material return self._recognize_material(material, ctx) def re_recognize_material(self, material_id: str, ctx: RequestContext) -> Material: material = self.get_material(material_id) return self._recognize_material(material, ctx) def _recognize_material(self, material: Material, ctx: RequestContext) -> Material: route_name = _recognition_route(material.metadata, self.default_recognition_route) provider = self._vision_provider(material, route_name) if provider is None: raise ApiError( ErrorCode.MODEL_CAPABILITY_UNCONFIRMED, "material vision route is not configured or its credentials are unavailable", { "material_id": material.material_id, "route_name": route_name, "modality": "vision_recognition", }, ) request = _vision_request(material, self.storage) try: recognition = provider.recognize_material(request) except VisionProviderError as exc: failure = _vision_provider_error(exc) self._record_recognition_failure(material, route_name, failure, ctx) raise _vision_api_error(material.material_id, route_name, failure) from None except Exception as exc: failure = _unexpected_vision_provider_error(provider, exc) self._record_recognition_failure(material, route_name, failure, ctx) raise _vision_api_error(material.material_id, route_name, failure) from None generated_tags = recognition.tags metadata = { key: value for key, value in material.metadata.items() if key not in {"confirmed", "recognition", "recognition_failure"} } after = self.update_material( material.material_id, { "prompt": material.prompt or recognition.prompt, "negative_prompt": material.negative_prompt or recognition.negative_prompt, "tags": sorted(set(material.tags + generated_tags)), "recognition_status": "pending_confirm", "metadata": { **metadata, "recognition": _recognition_metadata( recognition, route_name=route_name, ), }, }, ctx, ) self.audit_service.record( ctx=ctx, action="recognize_material", target_type="material", target_id=material.material_id, before_snapshot=material.to_dict(), after_snapshot=after.to_dict(), ) return after def _vision_provider(self, material: Material, route_name: str) -> VisionProvider | None: if self.vision_provider_factory is None: return None return self.vision_provider_factory( { "route_name": route_name, "modality": "vision_recognition", "material_id": material.material_id, "image_uri": material.image_uri, "thumbnail_uri": material.thumbnail_uri, } ) def _record_recognition_failure( self, material: Material, route_name: str, failure: dict[str, Any], ctx: RequestContext, ) -> Material: metadata = { key: value for key, value in material.metadata.items() if key not in {"confirmed", "recognition", "recognition_failure"} } after = self.update_material( material.material_id, { "recognition_status": "pending_recognition", "metadata": { **metadata, "recognition_failure": {**failure, "route_name": route_name}, }, }, ctx, ) self.audit_service.record( ctx=ctx, action="recognize_material_failed", target_type="material", target_id=material.material_id, before_snapshot=material.to_dict(), after_snapshot=after.to_dict(), metadata={"route_name": route_name, "error_type": failure.get("error_type")}, ) return after def confirm_material(self, material_id: str, payload: dict[str, Any], ctx: RequestContext) -> Material: material = self.get_material(material_id) if material.recognition_status not in {"pending_confirm", "confirmed"}: raise ApiError( ErrorCode.VALIDATION_FAILED, "material must have a successful recognition result before confirmation", { "material_id": material_id, "recognition_status": material.recognition_status, "required_status": "pending_confirm", }, ) update_payload = { "recognition_status": "confirmed", "display_name": payload.get("display_name", material.display_name), "prompt": payload.get("prompt", material.prompt), "negative_prompt": payload.get("negative_prompt", material.negative_prompt), "tags": payload.get("tags", material.tags), "metadata": {**material.metadata, "confirmed": True}, } after = self.update_material(material_id, update_payload, ctx) self.audit_service.record( ctx=ctx, action="confirm_material", target_type="material", target_id=material_id, before_snapshot=material.to_dict(), after_snapshot=after.to_dict(), ) return after def _validate_category(self, category_id: Any) -> None: if category_id and self.repository.get_category(str(category_id)) is None: raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "category not found", {"category_id": category_id}) def _validate_status(self, status: Any) -> None: if status not in MATERIAL_STATUSES: raise ApiError( ErrorCode.VALIDATION_FAILED, "unsupported material status", {"field": "recognition_status", "allowed": sorted(MATERIAL_STATUSES)}, ) def _validate_storage_uri(self, uri: Any, field: str) -> None: if uri is None: return if not str(uri).startswith("storage://"): raise ApiError(ErrorCode.VALIDATION_FAILED, f"{field} must use storage://", {"field": field}) def new_category_id() -> str: return f"cat_{uuid4().hex}" def new_material_id() -> str: return f"mat_{uuid4().hex}" def _vision_request(material: Material, storage: VfsStorage) -> VisionRecognitionRequest: image_data_url, content_type, size_bytes = _storage_image_data_url( str(material.image_uri or ""), material.metadata, storage, ) return VisionRecognitionRequest( display_name=material.display_name, image_uri=image_data_url, thumbnail_uri=None, prompt=material.prompt, negative_prompt=material.negative_prompt, tags=tuple(material.tags), metadata={ **material.metadata, "vision_input": { "source_uri": material.image_uri, "content_type": content_type, "size_bytes": size_bytes, }, }, ) def _storage_image_data_url( image_uri: str, metadata: dict[str, Any], storage: VfsStorage, ) -> tuple[str, str, int]: if not image_uri: raise ApiError( ErrorCode.VALIDATION_FAILED, "material image_uri is required for recognition", {"field": "image_uri"}, ) path = storage.ensure_file(image_uri) try: reported_size = path.stat().st_size except OSError: raise ApiError(ErrorCode.MEDIA_NOT_FOUND, "material image could not be inspected", {"uri": image_uri}) from None if reported_size > MAX_UPLOAD_BYTES: raise ApiError( ErrorCode.UPLOAD_TOO_LARGE, "material image exceeds the recognition size limit", {"uri": image_uri, "size_bytes": reported_size, "max_size_bytes": MAX_UPLOAD_BYTES}, ) try: with path.open("rb") as handle: content = handle.read(MAX_UPLOAD_BYTES + 1) except OSError: raise ApiError(ErrorCode.MEDIA_NOT_FOUND, "material image could not be read", {"uri": image_uri}) from None if len(content) > MAX_UPLOAD_BYTES: raise ApiError( ErrorCode.UPLOAD_TOO_LARGE, "material image exceeds the recognition size limit", {"uri": image_uri, "size_bytes": len(content), "max_size_bytes": MAX_UPLOAD_BYTES}, ) content_type = _image_content_type(content) if content_type is None: raise ApiError( ErrorCode.UNSUPPORTED_FILE_TYPE, "material image bytes do not match a supported image format", {"uri": image_uri, "allowed": sorted(UPLOAD_ALLOWED_CONTENT_TYPES)}, ) extension = _suffix(image_uri) if extension and extension not in UPLOAD_ALLOWED_CONTENT_TYPES[content_type]: raise ApiError( ErrorCode.UNSUPPORTED_FILE_TYPE, "material image extension does not match its file signature", {"uri": image_uri, "extension": extension, "detected_content_type": content_type}, ) upload = metadata.get("upload") if isinstance(metadata.get("upload"), dict) else {} declared_content_type = _optional_text(upload.get("content_type")) if declared_content_type and declared_content_type != content_type: raise ApiError( ErrorCode.UNSUPPORTED_FILE_TYPE, "material image content type does not match its file signature", { "uri": image_uri, "declared_content_type": declared_content_type, "detected_content_type": content_type, }, ) encoded = base64.b64encode(content).decode("ascii") return f"data:{content_type};base64,{encoded}", content_type, len(content) def _image_content_type(content: bytes) -> str | None: image_format = detect_image_format(content) return image_format.mime_type if image_format is not None else None def _recognition_route(metadata: dict[str, Any], default_route: str) -> str: upload = metadata.get("upload") if isinstance(metadata.get("upload"), dict) else {} return ( _optional_text(metadata.get("recognition_model_route")) or _optional_text(metadata.get("recognition_route")) or _optional_text(upload.get("recognition_model_route")) or default_route ) def _recognition_metadata( recognition: VisionRecognitionResult, *, route_name: str, ) -> dict[str, Any]: metadata = { "engine": "mock_vlm" if recognition.provider_id == "mock" else "vlm_adapter", "provider_id": recognition.provider_id, "model": recognition.model, "confidence": recognition.confidence, "route_name": route_name, "fallback_used": False, "description": recognition.description, "raw_metadata": recognition.raw_metadata, } return metadata def _vision_provider_error(exc: VisionProviderError) -> dict[str, Any]: failure = { "source": "vision_provider", "provider_id": _optional_text(exc.provider_id) or "unknown", "status_code": exc.status_code, "error_type": _optional_text(exc.error_type) or "provider_error", } if isinstance(exc.details.get("retryable"), bool): failure["retryable"] = exc.details["retryable"] return failure def _unexpected_vision_provider_error(provider: VisionProvider, exc: Exception) -> dict[str, Any]: return { "source": "vision_provider", "provider_id": _optional_text(getattr(provider, "provider_id", None)) or "unknown", "status_code": None, "error_type": "unexpected_provider_error", "exception_type": exc.__class__.__name__, } def _vision_api_error(material_id: str, route_name: str, failure: dict[str, Any]) -> ApiError: details = { "material_id": material_id, "route_name": route_name, "provider_id": failure.get("provider_id"), "status_code": failure.get("status_code"), "error_type": failure.get("error_type"), } if "retryable" in failure: details["retryable"] = failure["retryable"] return ApiError( ErrorCode.GENERATION_FAILED, "material vision provider request failed", details, ) def _normalize_upload_filename(value: Any) -> str | None: if value is None: return None filename = str(value).strip() if not filename: return None if len(filename) > 255 or filename in {".", ".."} or any(marker in filename for marker in ("/", "\\", "\x00", ":")): raise ApiError( ErrorCode.VALIDATION_FAILED, "filename must be a safe basename", {"field": "filename"}, ) return filename def _normalize_upload_content_type(value: Any) -> str | None: if value is None: return None content_type = str(value).split(";", 1)[0].strip().lower() if not content_type: return None if content_type not in UPLOAD_ALLOWED_CONTENT_TYPES: raise ApiError( ErrorCode.UNSUPPORTED_FILE_TYPE, "unsupported upload content type", { "field": "content_type", "content_type": content_type, "allowed": sorted(UPLOAD_ALLOWED_CONTENT_TYPES), }, ) return content_type def _normalize_upload_size(payload: dict[str, Any]) -> int | None: for field in UPLOAD_SIZE_FIELDS: if field not in payload or payload[field] in (None, ""): continue try: size = int(payload[field]) except (TypeError, ValueError): raise ApiError(ErrorCode.VALIDATION_FAILED, "upload size must be an integer", {"field": field}) from None if size < 0: raise ApiError(ErrorCode.VALIDATION_FAILED, "upload size must not be negative", {"field": field}) if size > MAX_UPLOAD_BYTES: raise ApiError( ErrorCode.UPLOAD_TOO_LARGE, "upload exceeds maximum allowed size", {"field": field, "size_bytes": size, "max_size_bytes": MAX_UPLOAD_BYTES}, ) return size return None def _normalize_upload_metadata(value: Any) -> dict[str, Any]: if value in (None, ""): return {} if not isinstance(value, dict): raise ApiError(ErrorCode.VALIDATION_FAILED, "metadata must be an object", {"field": "metadata"}) return dict(value) def _validate_upload_file_type(*, filename: str | None, image_uri: str, content_type: str | None) -> str: extension = _suffix(filename) or _suffix(image_uri) if not extension: raise ApiError( ErrorCode.UNSUPPORTED_FILE_TYPE, "upload filename or image_uri must include a supported image extension", {"field": "filename", "allowed": sorted(UPLOAD_ALLOWED_EXTENSIONS)}, ) if extension not in UPLOAD_ALLOWED_EXTENSIONS: raise ApiError( ErrorCode.UNSUPPORTED_FILE_TYPE, "unsupported upload file extension", {"field": "filename", "extension": extension, "allowed": sorted(UPLOAD_ALLOWED_EXTENSIONS)}, ) if content_type and extension not in UPLOAD_ALLOWED_CONTENT_TYPES[content_type]: raise ApiError( ErrorCode.UNSUPPORTED_FILE_TYPE, "upload extension does not match content type", {"field": "content_type", "extension": extension, "content_type": content_type}, ) return extension def _suffix(value: str | None) -> str | None: if not value: return None suffix = PurePosixPath(str(value).split("?", 1)[0]).suffix.lower() return suffix or None def _display_name_from_filename(filename: str | None) -> str | None: if not filename: return None return PurePosixPath(filename).stem.replace("_", " ").strip() or None def _optional_text(value: Any) -> str | None: text = str(value or "").strip() return text or None