703 行
29 KiB
Python
703 行
29 KiB
Python
"""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",
|
|
recognition_prompt_config: dict[str, Any] | None = None,
|
|
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.recognition_prompt_config = recognition_prompt_config or {}
|
|
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, self._recognition_instruction(material))
|
|
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 _recognition_instruction(self, material: Material) -> str:
|
|
base = str(self.recognition_prompt_config.get("default_instruction") or "").strip()
|
|
requirements = self.recognition_prompt_config.get("category_requirements")
|
|
if not isinstance(requirements, list):
|
|
return base
|
|
category_name = ""
|
|
if material.category_id:
|
|
category = self.repository.get_category(material.category_id)
|
|
category_name = category.name if category else ""
|
|
additions: list[str] = []
|
|
for item in requirements:
|
|
if not isinstance(item, dict) or item.get("enabled") is False:
|
|
continue
|
|
category = str(item.get("category") or "").strip().lower()
|
|
requirement = str(item.get("requirement") or "").strip()
|
|
if requirement and (not category or category in {str(material.category_id or "").lower(), category_name.lower()}):
|
|
additions.append(requirement)
|
|
return "\n\n".join([part for part in [base, *additions] if part])
|
|
|
|
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, recognition_instruction: str = "") -> 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,
|
|
"recognition_instruction": recognition_instruction,
|
|
"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
|