astrbot_plugin_imagestudio/backend/services/material_service.py

682 行
27 KiB
Python

2026-07-05 09:52:13 +08:00
"""Material library service."""
from __future__ import annotations
import base64
2026-07-06 03:28:34 +08:00
from pathlib import PurePosixPath
2026-07-06 03:37:17 +08:00
from typing import Any, Callable
2026-07-05 09:52:13 +08:00
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,
)
2026-07-05 09:52:13 +08:00
from core.identity import RequestContext
from core.storage import VfsStorage
2026-07-05 09:52:13 +08:00
from database.repositories.material_repository import MaterialRepository
2026-07-06 03:37:17 +08:00
from engines.vision_provider import (
VisionProvider,
VisionProviderError,
VisionRecognitionRequest,
VisionRecognitionResult,
)
2026-07-05 09:52:13 +08:00
MATERIAL_STATUSES = {"pending_upload", "pending_recognition", "pending_confirm", "confirmed", "archived"}
2026-07-06 03:28:34 +08:00
MAX_UPLOAD_BYTES = 20 * 1024 * 1024
UPLOAD_SIZE_FIELDS = ("size_bytes", "content_length", "file_size", "size")
UPLOAD_ALLOWED_EXTENSIONS = set(SUPPORTED_IMAGE_EXTENSIONS)
2026-07-06 03:28:34 +08:00
UPLOAD_ALLOWED_CONTENT_TYPES = {
mime_type: set(extensions) for mime_type, extensions in IMAGE_EXTENSIONS_BY_MIME.items()
2026-07-06 03:28:34 +08:00
}
2026-07-05 09:52:13 +08:00
class MaterialService:
2026-07-06 03:37:17 +08:00
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,
2026-07-06 03:37:17 +08:00
):
2026-07-05 09:52:13 +08:00
self.repository = repository
self.audit_service = audit_service
2026-07-06 03:37:17 +08:00
self.vision_provider_factory = vision_provider_factory
self.default_recognition_route = default_recognition_route
self.storage = storage or VfsStorage()
2026-07-05 09:52:13 +08:00
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})
2026-07-05 09:52:13 +08:00
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)
2026-07-05 09:52:13 +08:00
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)
2026-07-05 09:52:13 +08:00
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"))
2026-07-05 09:52:13 +08:00
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:
2026-07-06 03:28:34 +08:00
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"})
2026-07-06 03:28:34 +08:00
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"))
2026-07-06 03:37:17 +08:00
recognition_route = _optional_text(payload.get("recognition_model_route"))
if recognition_route:
upload_metadata["recognition_model_route"] = recognition_route
2026-07-06 03:28:34 +08:00
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,
2026-07-06 03:28:34 +08:00
"thumbnail_uri": thumbnail_uri,
"recognition_status": "pending_recognition",
"metadata": {
2026-07-06 03:28:34 +08:00
**upload_metadata,
"upload": {
2026-07-06 03:28:34 +08:00
"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
2026-07-05 17:24:35 +08:00
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
2026-07-06 03:37:17 +08:00
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(
2026-07-05 17:24:35 +08:00
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",
2026-07-06 03:37:17 +08:00
"metadata": {
**metadata,
2026-07-06 03:37:17 +08:00
"recognition": _recognition_metadata(
recognition,
route_name=route_name,
),
},
},
ctx,
)
self.audit_service.record(
ctx=ctx,
action="recognize_material",
target_type="material",
2026-07-05 17:24:35 +08:00
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(
2026-07-06 03:37:17 +08:00
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
2026-07-06 03:37:17 +08:00
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
2026-07-05 09:52:13 +08:00
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,
)
2026-07-06 03:37:17 +08:00
return VisionRecognitionRequest(
display_name=material.display_name,
image_uri=image_data_url,
thumbnail_uri=None,
2026-07-06 03:37:17 +08:00
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,
},
},
2026-07-06 03:37:17 +08:00
)
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
2026-07-06 03:37:17 +08:00
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,
2026-07-06 03:37:17 +08:00
"description": recognition.description,
"raw_metadata": recognition.raw_metadata,
}
return metadata
def _vision_provider_error(exc: VisionProviderError) -> dict[str, Any]:
failure = {
2026-07-06 03:37:17 +08:00
"source": "vision_provider",
"provider_id": _optional_text(exc.provider_id) or "unknown",
2026-07-06 03:37:17 +08:00
"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"),
2026-07-06 03:37:17 +08:00
}
if "retryable" in failure:
details["retryable"] = failure["retryable"]
return ApiError(
ErrorCode.GENERATION_FAILED,
"material vision provider request failed",
details,
)
2026-07-06 03:37:17 +08:00
2026-07-06 03:28:34 +08:00
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
2026-07-06 03:37:17 +08:00
def _optional_text(value: Any) -> str | None:
text = str(value or "").strip()
return text or None