"""Verified advanced-material import and validation workflow. Advanced materials intentionally use their own tables and VFS root. The source image is recognized first, then the recognized text (and only that text) is rendered once so a human can judge whether the description is faithful enough to seal into the high-priority material catalog. """ from __future__ import annotations from dataclasses import replace from pathlib import Path, PurePosixPath from typing import Any from uuid import uuid4 from backend.dto.common import ApiError, ErrorCode from backend.dto.job_dto import GenerationTask from backend.dto.material_dto import Material from backend.dto.workflow_dto import WorkflowNode from backend.services.event_stream_service import get_default_event_bus from backend.services.cost_guard_service import CostGuardService from backend.services.cost_service import CostService from backend.services.material_normalization_service import ( MaterialNormalizationError, MaterialNormalizationService, ) from backend.services.material_service import ( MAX_UPLOAD_BYTES, _decode_upload_data_url, _display_name_from_filename, _normalize_upload_content_type, _normalize_upload_filename, _normalize_upload_metadata, _normalize_upload_size, _recognition_metadata, _storage_image_data_url, _suffix, _vision_provider_error, ) from backend.services.model_provider_bootstrap import ( sync_generation_provider_from_config, sync_vision_provider_from_config, ) from backend.services.model_provider_runtime import ModelProviderRuntime from backend.services.model_provider_service import ModelProviderService from backend.services.queue_service import QueueService from backend.services.prompt_governance_service import ( GenerationFailureClassifier, GenerationRouteService, PromptModerationDecision, PromptModerationService, ) from backend.services.worker_service import WorkerTaskUpdate from backend.services.advanced_style_set_service import AdvancedStyleSetService from core.audit_service import AuditService from core.astrbot_provider_bridge import astrbot_structured_text_callable from core.identity import RequestContext from core.image_formats import detect_image_format from core.storage import VfsStorage from database.db_helper import Database, load_config_file_payload, load_config_payload, load_database_settings from database.repositories.advanced_material_repository import AdvancedMaterialRepository from database.repositories.job_repository import JobRepository from database.repositories.material_repository import MaterialRepository from database.repositories.model_provider_repository import ModelProviderRepository from engines.image_provider import ImageProviderError from engines.single_flow import SingleFlowEngine from engines.vision_provider import VisionProviderError, VisionRecognitionRequest from core.text_utils import optional_text as _optional_text IMPORT_ACTIVE_STATUSES = {"recognition_queued", "recognizing", "validation_queued", "validating"} IMPORT_REVIEW_STATUSES = {"awaiting_review", "adjustment_required"} ATTEMPT_ACTIVE_STATUSES = {"queued", "running"} ADVANCED_MATERIAL_PRIORITY = 100 DEFAULT_VALIDATION_SEED = 240719 class AdvancedMaterialTaskCancelled(RuntimeError): """Raised when a late provider result no longer owns its import.""" class AdvancedMaterialService: def __init__( self, repository: AdvancedMaterialRepository, material_repository: MaterialRepository, queue_service: QueueService, audit_service: AuditService, model_provider_service: ModelProviderService, model_provider_runtime: ModelProviderRuntime, *, config: dict[str, Any] | None = None, storage: VfsStorage | None = None, normalization_service: MaterialNormalizationService | None = None, single_flow_engine: SingleFlowEngine | None = None, prompt_moderation_service: PromptModerationService | None = None, generation_route_service: GenerationRouteService | None = None, cost_guard_service: CostGuardService | None = None, failure_classifier: GenerationFailureClassifier | None = None, ): self.repository = repository self.material_repository = material_repository self.queue_service = queue_service self.audit_service = audit_service self.model_provider_service = model_provider_service self.model_provider_runtime = model_provider_runtime self.config = config or {} self.storage = storage or VfsStorage() self.normalization_service = normalization_service or MaterialNormalizationService() self.prompt_moderation_service = prompt_moderation_service self.generation_route_service = generation_route_service self.cost_guard_service = cost_guard_service self.failure_classifier = failure_classifier or GenerationFailureClassifier() self.single_flow_engine = single_flow_engine or SingleFlowEngine( storage=self.storage, image_provider_factory=self.model_provider_runtime.image_provider_for_route, allow_mock_fallback=False, ) self.style_sets = AdvancedStyleSetService(self) def upload(self, payload: dict[str, Any], ctx: RequestContext) -> dict[str, Any]: import_id = f"advimp_{uuid4().hex}" 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")) source_uri, detected_type, size_bytes, original_filename = self._persist_source( import_id=import_id, image_data_url=str(payload.get("image_data_url") or "").strip(), image_uri=str(payload.get("image_uri") or "").strip(), filename=filename, declared_content_type=content_type, declared_size=declared_size, ) display_name = str( payload.get("display_name") or _display_name_from_filename(original_filename) or "进阶素材" ).strip() category_id = _optional_text(payload.get("category_id")) if category_id and self.material_repository.get_category(category_id) is None: self._remove_uri(source_uri) raise ApiError( ErrorCode.RESOURCE_NOT_FOUND, "material category not found", {"category_id": category_id}, ) recognition_route = _optional_text(payload.get("recognition_model_route")) or self._recognition_route() generation_route = _optional_text(payload.get("generation_model_route")) or self._generation_route() try: record = self.repository.create_import( { "import_id": import_id, "category_id": category_id, "display_name": display_name, "source_image_uri": source_uri, "source_thumbnail_uri": source_uri, "status": "recognition_queued", "recognition_model_route": recognition_route, "prompt_revision": 0, "created_by": ctx.actor_id, "metadata": { "upload": { **upload_metadata, "filename": original_filename, "content_type": detected_type, "size_bytes": size_bytes, "source": str(payload.get("upload_source") or "file"), "storage_root": "advanced_materials", }, "generation_model_route": generation_route, "governance_context": _governance_context(self.config, ctx), "material_tier": "advanced_pending", }, } ) except Exception: self._remove_uri(source_uri) raise try: task = self._queue_recognition(record, ctx) except Exception as exc: self.repository.update_import( record.import_id, {"status": "recognition_failed", "error": _safe_failure(exc)}, ) raise self.audit_service.record( ctx=ctx, action="upload_advanced_material", target_type="advanced_material_import", target_id=record.import_id, after_snapshot=record.to_dict(), metadata={"task_id": task.task_id}, ) return {"import": self.repository.get_import(record.import_id).to_dict(), "task": task.to_dict()} def upload_style_set(self, payload: dict[str, Any], ctx: RequestContext) -> dict[str, Any]: return self.style_sets.upload(payload, ctx) def list_imports( self, *, status: str | None = None, page: int = 1, page_size: int = 30, ) -> dict[str, Any]: items, total = self.repository.list_imports( status=status, page=max(int(page or 1), 1), page_size=min(max(int(page_size or 30), 1), 100), ) reconciled = [self._reconcile_import_task(item) for item in items] return { "items": [item.to_dict() for item in reconciled], "total": total, "page": max(int(page or 1), 1), "page_size": min(max(int(page_size or 30), 1), 100), } def get_import(self, import_id: str) -> dict[str, Any]: record = self._reconcile_import_task(self._require_import(import_id)) attempts = self.repository.list_attempts(import_id) is_style_set = self.style_sets.is_style_set(record) style_detail = self.style_sets.detail(record) if is_style_set else {} attempt_payloads = [ { **attempt.to_dict(), **( { "validation_cases": [ case.to_dict() for case in self.repository.list_style_validation_cases(attempt.attempt_id) ] } if is_style_set else {} ), } for attempt in attempts ] import_payload = { **record.to_dict(), **( { "style_set": True, "sources": style_detail.get("sources", []), "consensus": style_detail.get("consensus"), "consensus_history": style_detail.get("consensus_history", []), "validation_cases": style_detail.get("validation_cases", []), } if style_detail else {} ), } return { **style_detail, "import": import_payload, "attempts": attempt_payloads, "accepted_material": ( self.repository.get_material(record.accepted_material_id).to_dict() if record.accepted_material_id and self.repository.get_material(record.accepted_material_id) else None ), } def retry_style_source(self, import_id: str, source_id: str, ctx: RequestContext) -> dict[str, Any]: return self.style_sets.retry_source(import_id, source_id, ctx) def exclude_style_source( self, import_id: str, source_id: str, excluded: bool, ctx: RequestContext, ) -> dict[str, Any]: return self.style_sets.exclude_source(import_id, source_id, excluded, ctx) def create_style_consensus( self, import_id: str, payload: dict[str, Any], ctx: RequestContext, ) -> dict[str, Any]: return self.style_sets.create_consensus(import_id, payload, ctx) def retry_style_validation_case(self, import_id: str, case_id: str, ctx: RequestContext) -> dict[str, Any]: return self.style_sets.retry_validation_case(import_id, case_id, ctx) def list_attempts(self, import_id: str) -> list[dict[str, Any]]: record = self._require_import(import_id) is_style_set = self.style_sets.is_style_set(record) return [ { **attempt.to_dict(), **( { "validation_cases": [ case.to_dict() for case in self.repository.list_style_validation_cases(attempt.attempt_id) ] } if is_style_set else {} ), } for attempt in self.repository.list_attempts(import_id) ] def create_validation_attempt( self, import_id: str, payload: dict[str, Any], ctx: RequestContext, ) -> dict[str, Any]: record = self._require_import(import_id) if self.style_sets.is_style_set(record): return self.style_sets.ensure_validation(record, payload, ctx) record = self.repository.update_import( import_id, {"metadata": {**record.metadata, "governance_context": _governance_context(self.config, ctx)}}, ) or record adjustment = _optional_text(payload.get("adjustment_text")) if adjustment: record = self._apply_adjustment(record, adjustment, ctx) attempt, task = self._queue_validation(record, ctx) return {"import": self._require_import(import_id).to_dict(), "attempt": attempt.to_dict(), "task": task.to_dict()} def reject_attempt( self, import_id: str, attempt_id: str, payload: dict[str, Any], ctx: RequestContext, ) -> dict[str, Any]: record = self._require_import(import_id) attempt = self._require_attempt(import_id, attempt_id) if self.style_sets.is_style_set(record): return self.style_sets.reject_and_rebuild(record, attempt, payload, ctx) if record.current_attempt_id != attempt.attempt_id or record.status != "awaiting_review" or attempt.status != "awaiting_review": raise ApiError( ErrorCode.VALIDATION_FAILED, "only the current completed verification attempt can be rejected", {"import_id": import_id, "attempt_id": attempt_id, "status": attempt.status}, ) adjustment = _optional_text(payload.get("adjustment_text")) if not adjustment: raise ApiError( ErrorCode.VALIDATION_FAILED, "adjustment_text is required when the verification image is not faithful", {"field": "adjustment_text"}, ) before = attempt.to_dict() updated_attempt = self.repository.update_attempt( attempt_id, { "status": "rejected", "decision": "rejected", "decision_notes": _optional_text(payload.get("decision_notes")) or adjustment, "fidelity_score": _optional_score(payload.get("fidelity_score")), "metadata": {**attempt.metadata, "rejected_by": ctx.actor_id}, }, ) self.repository.update_import(import_id, {"status": "adjustment_required"}) adjusted = self._apply_adjustment(self._require_import(import_id), adjustment, ctx) next_attempt, task = self._queue_validation(adjusted, ctx) self.audit_service.record( ctx=ctx, action="reject_advanced_material_attempt", target_type="advanced_material_validation_attempt", target_id=attempt_id, before_snapshot=before, after_snapshot=updated_attempt.to_dict(), metadata={"next_attempt_id": next_attempt.attempt_id, "task_id": task.task_id}, ) return { "import": self._require_import(import_id).to_dict(), "attempt": updated_attempt.to_dict(), "next_attempt": next_attempt.to_dict(), "task": task.to_dict(), } def accept_attempt( self, import_id: str, attempt_id: str, payload: dict[str, Any], ctx: RequestContext, ) -> dict[str, Any]: record = self._require_import(import_id) attempt = self._require_attempt(import_id, attempt_id) if self.style_sets.is_style_set(record): return self.style_sets.accept(record, attempt, payload, ctx) if record.accepted_material_id: existing = self.repository.get_material(record.accepted_material_id) if existing is not None: return {"import": record.to_dict(), "attempt": attempt.to_dict(), "material": existing.to_dict()} if record.current_attempt_id != attempt_id or record.status != "awaiting_review" or attempt.status != "awaiting_review": raise ApiError( ErrorCode.VALIDATION_FAILED, "only the current completed verification attempt can be sealed", {"import_id": import_id, "attempt_id": attempt_id, "status": attempt.status}, ) if not attempt.validation_image_uri: raise ApiError( ErrorCode.VALIDATION_FAILED, "verification image is missing", {"attempt_id": attempt_id}, ) material_id = f"advmat_{uuid4().hex}" recognition = record.recognition_result if isinstance(record.recognition_result, dict) else {} profile = recognition.get("normalized_asset_profile") if isinstance(recognition.get("normalized_asset_profile"), dict) else {} capsules = recognition.get("generation_capsules") if isinstance(recognition.get("generation_capsules"), dict) else {} fidelity_score = _optional_score(payload.get("fidelity_score")) decision_notes = _optional_text(payload.get("decision_notes")) attempt = self.repository.update_attempt( attempt_id, {"fidelity_score": fidelity_score, "decision_notes": decision_notes}, ) or attempt metadata = { "library_kind": "advanced", "priority_class": "advanced_verified", "material_priority": ADVANCED_MATERIAL_PRIORITY, "verification": { "import_id": import_id, "attempt_id": attempt_id, "attempt_number": attempt.attempt_number, "fidelity_score": fidelity_score, "decision_notes": decision_notes, "validation_image_uri": attempt.validation_image_uri, "prompt_revision": record.prompt_revision, }, "recognition": recognition.get("recognition") or {}, "raw_analysis": recognition.get("raw_analysis") or {}, "normalized_asset_profile": {**profile, "confirmed": True}, "generation_capsules": capsules, "confirmed": True, } material = self.repository.accept_attempt( import_id, attempt_id, { "material_id": material_id, "category_id": record.category_id, "display_name": record.display_name, "source_image_uri": record.source_image_uri, "source_thumbnail_uri": record.source_thumbnail_uri, "validation_image_uri": attempt.validation_image_uri, "validation_thumbnail_uri": attempt.validation_thumbnail_uri, "prompt": attempt.prompt or record.recognition_prompt, "negative_prompt": attempt.negative_prompt or record.recognition_negative_prompt, "tags": record.recognition_tags, "priority": ADVANCED_MATERIAL_PRIORITY, "status": "active", "capsule": capsules, "fidelity_score": fidelity_score, "created_by": ctx.actor_id, "decision_notes": decision_notes, "metadata": metadata, }, ) self.audit_service.record( ctx=ctx, action="seal_advanced_material", target_type="advanced_material", target_id=material.material_id, before_snapshot={"import": record.to_dict(), "attempt": attempt.to_dict()}, after_snapshot=material.to_dict(), ) return { "import": self._require_import(import_id).to_dict(), "attempt": self._require_attempt(import_id, attempt_id).to_dict(), "material": material.to_dict(), } def retry_import(self, import_id: str, ctx: RequestContext) -> dict[str, Any]: record = self._reconcile_import_task(self._require_import(import_id)) record = self.repository.update_import( import_id, {"metadata": {**record.metadata, "governance_context": _governance_context(self.config, ctx)}}, ) or record if self.style_sets.is_style_set(record): if record.status == "style_consensus_failed": return self.style_sets.create_consensus(import_id, {}, ctx) if record.status in {"ready_for_validation", "validation_failed"}: return self.style_sets.ensure_validation(record, {}, ctx) raise ApiError( ErrorCode.VALIDATION_FAILED, "retry the failed style source or validation case directly", {"import_id": import_id, "status": record.status}, ) if record.status == "recognition_failed": task = self._queue_recognition(record, ctx) return {"import": self._require_import(import_id).to_dict(), "task": task.to_dict()} if record.status == "validation_failed": attempt, task = self._queue_validation(record, ctx) return {"import": self._require_import(import_id).to_dict(), "attempt": attempt.to_dict(), "task": task.to_dict()} raise ApiError( ErrorCode.VALIDATION_FAILED, "advanced material import is not in a retryable state", {"import_id": import_id, "status": record.status}, ) def cancel_import(self, import_id: str, ctx: RequestContext) -> dict[str, Any]: record = self._require_import(import_id) if record.status in {"accepted", "archived", "cancelled"}: return record.to_dict() if self.style_sets.is_style_set(record): self.style_sets.cancel(record, ctx) active_task_id = _optional_text(record.metadata.get("active_task_id")) if active_task_id: try: self.queue_service.cancel_job(active_task_id, ctx, reason="advanced material import cancelled") except ApiError: pass attempt = self.repository.get_active_attempt(import_id) if attempt is not None: self.repository.update_attempt(attempt.attempt_id, {"status": "cancelled", "decision": "cancelled"}) updated = self.repository.update_import( import_id, {"status": "cancelled", "metadata": {**record.metadata, "active_task_id": None}}, ) self.audit_service.record( ctx=ctx, action="cancel_advanced_material_import", target_type="advanced_material_import", target_id=import_id, before_snapshot=record.to_dict(), after_snapshot=updated.to_dict(), ) return updated.to_dict() def delete_import(self, import_id: str, ctx: RequestContext) -> dict[str, Any]: record = self._require_import(import_id) if record.accepted_material_id or self.repository.get_material_by_import(import_id) is not None: raise ApiError( ErrorCode.VALIDATION_FAILED, "sealed advanced material imports cannot be deleted; archive the material instead", {"import_id": import_id, "accepted_material_id": record.accepted_material_id}, ) media_uris = self._import_media_uris(record) if record.status not in {"cancelled", "failed", "recognition_failed", "validation_failed"}: self.cancel_import(import_id, ctx) record = self._require_import(import_id) before = record.to_dict() try: deleted = self.repository.delete_import(import_id) except ValueError as exc: raise ApiError( ErrorCode.VALIDATION_FAILED, str(exc), {"import_id": import_id}, ) from None if deleted is None: raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "advanced material import not found", {"import_id": import_id}) for uri in media_uris: self._remove_uri(uri) result = { "import_id": import_id, "deleted": True, "previous_status": before.get("status"), "removed_media_count": len(media_uris), } self.audit_service.record( ctx=ctx, action="delete_advanced_material_import", target_type="advanced_material_import", target_id=import_id, before_snapshot=before, metadata=result, ) return result def list_materials(self, *, page: int = 1, page_size: int = 30) -> dict[str, Any]: normalized_page = max(int(page or 1), 1) normalized_size = min(max(int(page_size or 30), 1), 100) items, total = self.repository.list_materials(page=normalized_page, page_size=normalized_size) return { "items": [item.to_dict() for item in items], "total": total, "page": normalized_page, "page_size": normalized_size, } def get_material(self, material_id: str): material = self.repository.get_material(material_id) if material is None or material.status == "archived": raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "advanced material not found", {"material_id": material_id}) return material def archive_material(self, material_id: str, ctx: RequestContext): before = self.get_material(material_id) after = self.repository.archive_material(material_id) if after is None: raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "advanced material not found", {"material_id": material_id}) self.audit_service.record( ctx=ctx, action="archive_advanced_material", target_type="advanced_material", target_id=material_id, before_snapshot=before.to_dict(), after_snapshot=after.to_dict(), ) return after def list_catalog(self, *, page: int = 1, page_size: int = 100) -> dict[str, Any]: normalized_page = max(int(page or 1), 1) normalized_size = min(max(int(page_size or 100), 1), 200) advanced = self._all_advanced_materials() advanced_total = len(advanced) standard = self._all_standard_materials() advanced_items = [ {**item.to_dict(), "library_kind": "advanced", "priority": ADVANCED_MATERIAL_PRIORITY} for item in advanced if item.status == "active" ] standard_items = [ { **item.to_dict(), "library_kind": "standard", "priority": 0, } for item in standard if item.recognition_status == "confirmed" ] merged = [*advanced_items, *standard_items] offset = (normalized_page - 1) * normalized_size return { "items": merged[offset : offset + normalized_size], "total": len(merged), "page": normalized_page, "page_size": normalized_size, "advanced_total": advanced_total, "standard_total": sum(1 for item in standard if item.recognition_status == "confirmed"), } def _all_advanced_materials(self) -> list[Any]: result: list[Any] = [] page = 1 while True: items, total = self.repository.list_materials(page=page, page_size=200) result.extend(items) if len(result) >= total or not items: return result page += 1 def _all_standard_materials(self) -> list[Material]: result: list[Material] = [] page = 1 while True: items, total = self.material_repository.list_materials(page=page, page_size=100) result.extend(items) if len(result) >= total or not items: return result page += 1 def execute_task(self, task: GenerationTask, ctx: RequestContext) -> WorkerTaskUpdate: if task.task_type in { "advanced_style_source_recognition", "advanced_style_consensus", "advanced_style_validation_generation", }: return self.style_sets.execute_task(task, ctx) if task.task_type == "advanced_material_recognition": return self._execute_recognition(task, ctx) if task.task_type == "advanced_material_validation_generation": return self._execute_validation(task, ctx) raise RuntimeError(f"unsupported advanced material task type: {task.task_type}") def handle_task_failure(self, task: GenerationTask, exc: Exception, ctx: RequestContext) -> None: if task.task_type in { "advanced_style_source_recognition", "advanced_style_consensus", "advanced_style_validation_generation", }: self.style_sets.handle_failure(task, exc, ctx) return import_id = _optional_text(task.metadata.get("advanced_material_import_id")) if not import_id: return failure = _safe_failure(exc) record = self.repository.get_import(import_id) if record is None: return if record.status in {"cancelled", "accepted", "archived"}: return if task.task_type == "advanced_material_recognition": self.repository.update_import( import_id, { "status": "recognition_failed", "error": failure, "metadata": {**record.metadata, "active_task_id": None}, }, ) elif task.task_type == "advanced_material_validation_generation": attempt_id = _optional_text(task.metadata.get("advanced_material_attempt_id")) if attempt_id: attempt = self.repository.get_attempt(attempt_id) if attempt is not None and attempt.status in ATTEMPT_ACTIVE_STATUSES: self.repository.update_attempt(attempt_id, {"status": "failed", "error": failure}) self.repository.update_import( import_id, { "status": "validation_failed", "error": failure, "metadata": {**record.metadata, "active_task_id": None}, }, ) self.audit_service.record( ctx=ctx, action="advanced_material_task_failed", target_type="advanced_material_import", target_id=import_id, metadata={"task_id": task.task_id, "task_type": task.task_type, "failure": failure}, ) def _execute_recognition(self, task: GenerationTask, ctx: RequestContext) -> WorkerTaskUpdate: import_id = str(task.metadata.get("advanced_material_import_id") or "").strip() record = self._require_import(import_id) if record.status not in {"recognition_queued", "recognizing"}: return WorkerTaskUpdate(result={"import_id": import_id, "status": record.status}) self._ensure_task_active(task, record) record = self.repository.update_import_if_status( import_id, {"recognition_queued", "recognizing"}, {"status": "recognizing", "error": None}, ) if record is None: raise AdvancedMaterialTaskCancelled("advanced material recognition no longer owns the import") route_name = record.recognition_model_route or self._recognition_route() provider = self.model_provider_runtime.vision_provider_for_route( { "route_name": route_name, "modality": "vision_recognition", "material_id": import_id, "image_uri": record.source_image_uri, } ) if provider is None: raise ApiError( ErrorCode.MODEL_CAPABILITY_UNCONFIRMED, "advanced material vision route is not configured or unavailable", {"route_name": route_name, "modality": "vision_recognition"}, ) material = Material( material_id=import_id, category_id=record.category_id, display_name=record.display_name, image_uri=record.source_image_uri, thumbnail_uri=record.source_thumbnail_uri, prompt=None, negative_prompt=None, tags=[], recognition_status="pending_recognition", metadata={"advanced_material": True}, created_at=record.created_at, updated_at=record.updated_at, ) image_data_url, content_type, size_bytes = _storage_image_data_url( record.source_image_uri, material.metadata, self.storage, ) request = VisionRecognitionRequest( display_name=record.display_name, image_uri=image_data_url, thumbnail_uri=None, prompt=None, negative_prompt=None, tags=(), metadata={ "advanced_material": True, "recognition_instruction": self._recognition_instruction(record), "vision_input": { "source_uri": record.source_image_uri, "content_type": content_type, "size_bytes": size_bytes, }, }, ) try: recognition = provider.recognize_material(request) except VisionProviderError as exc: raise ApiError( ErrorCode.GENERATION_FAILED, "advanced material recognition failed", {**_vision_provider_error(exc), "route_name": route_name}, ) from None category = self.material_repository.get_category(record.category_id) if record.category_id else None try: structures = self.normalization_service.normalize_recognition( recognition.structured_data, prompt=recognition.prompt, negative_prompt=recognition.negative_prompt, tags=recognition.tags, confidence=recognition.confidence, provider_id=recognition.provider_id, model=recognition.model, route_name=route_name, category_hint=category.name if category else None, ) except MaterialNormalizationError as exc: raise ApiError( ErrorCode.GENERATION_FAILED, "advanced material recognition returned an invalid structured result", {"route_name": route_name, "error_type": "invalid_structured_analysis"}, ) from exc result = { "recognition": _recognition_metadata(recognition, route_name=route_name), **structures, } self._ensure_task_active(task, self._require_import(import_id)) updated = self.repository.update_import_if_status( import_id, {"recognizing"}, { "status": "ready_for_validation", "recognition_prompt": recognition.prompt, "recognition_negative_prompt": recognition.negative_prompt, "recognition_tags": recognition.tags, "recognition_result": result, "error": None, "metadata": {**record.metadata, "active_task_id": None}, }, ) if updated is None: raise AdvancedMaterialTaskCancelled("advanced material recognition result arrived after cancellation") try: attempt, next_task = self._queue_validation(updated, ctx) except Exception as exc: self.repository.update_import( import_id, { "status": "validation_failed", "error": _safe_failure(exc), "metadata": {**updated.metadata, "active_task_id": None}, }, ) return WorkerTaskUpdate( result={ "import_id": import_id, "recognition_status": "completed", "validation_queue_status": "failed", }, metadata={"pipeline_stage": "validation_queue_failed"}, ) return WorkerTaskUpdate( result={ "import_id": import_id, "recognition_status": "completed", "attempt_id": attempt.attempt_id, "next_task_id": next_task.task_id, }, metadata={"pipeline_stage": "recognition_completed"}, ) def _execute_validation(self, task: GenerationTask, ctx: RequestContext) -> WorkerTaskUpdate: import_id = str(task.metadata.get("advanced_material_import_id") or "").strip() attempt_id = str(task.metadata.get("advanced_material_attempt_id") or "").strip() record = self._require_import(import_id) attempt = self._require_attempt(import_id, attempt_id) if attempt.status == "awaiting_review" and attempt.validation_image_uri: return WorkerTaskUpdate(result={"import_id": import_id, "attempt_id": attempt_id, "status": "awaiting_review"}) if attempt.status not in {"queued", "running"}: raise ApiError( ErrorCode.VALIDATION_FAILED, "advanced material validation attempt is not executable", {"attempt_id": attempt_id, "status": attempt.status}, ) self._ensure_task_active(task, record, attempt=attempt) claimed = self.repository.mark_attempt_running(import_id, attempt_id) if claimed is None: raise AdvancedMaterialTaskCancelled("advanced material validation no longer owns the import") record, attempt = claimed requested_route = attempt.model_route or self._generation_route() governance = self._govern_validation_prompt( record=record, attempt=attempt, requested_route=requested_route, ctx=ctx, ) route_name = str(governance["selected_route"]) resolved_route = self._resolve_generation_route(route_name) cost_guard = self._check_validation_budget(route_name, resolved_route) attempt_metadata = { **attempt.metadata, "prompt_governance": governance["snapshot"], **({"cost_guard": cost_guard} if cost_guard else {}), } self.repository.update_attempt(attempt_id, {"metadata": attempt_metadata}) node = WorkflowNode( node_id=f"advanced-material:{attempt_id}", workflow_id=f"advanced-material:{import_id}", node_key="advanced_material_validation", title="进阶素材还原验证", description=None, step_name="validation", node_type="generation", status="running", branch_name="main", prompt=governance["prompt"], negative_prompt=governance["negative_prompt"], model_route=route_name, selected_image_id=None, sort_order=0, metadata={"advanced_material": True}, created_at=attempt.created_at, updated_at=attempt.updated_at, ) request = { "count": 1, "aspect_ratio": "1:1", "quality": "standard", "seed": int(attempt.seed or DEFAULT_VALIDATION_SEED), "model_route": route_name, "resolved_model_route": resolved_route, "allow_provider_fallback": False, "expanded_prompt": governance["prompt"], "expanded_negative_prompt": governance["negative_prompt"], "prompt_governance": governance["snapshot"], **({"cost_guard": cost_guard} if cost_guard else {}), # Deliberately no input_images/image field: the validation render # measures the text description rather than image-to-image copying. "output_scope": { "kind": "advanced_material_validation", "import_id": import_id, "attempt_id": attempt_id, "attempt_number": attempt.attempt_number, }, } assets: list[Any] = [] try: try: assets = self.single_flow_engine.generate(node, task, request) except ImageProviderError as exc: fallback = self._content_safety_fallback( exc=exc, runtime_request=request, governance=governance, requested_route=requested_route, record=record, ctx=ctx, ) if fallback is None: raise route_name = fallback["model_route"] resolved_route = fallback["resolved_model_route"] request = fallback["request"] attempt_metadata = { **attempt_metadata, "route_fallback": fallback["route_fallback"], **({"fallback_cost_guard": fallback["cost_guard"]} if fallback.get("cost_guard") else {}), } self.repository.update_attempt(attempt_id, {"metadata": attempt_metadata}) assets = self.single_flow_engine.generate(node, task, request) except Exception: for asset in assets: self._remove_uri(str(getattr(asset, "image_uri", "") or "")) self._remove_uri(str(getattr(asset, "thumbnail_uri", "") or "")) raise if len(assets) != 1: raise ImageProviderError( "advanced material validation must return exactly one image", provider_id=str(resolved_route.get("provider_id") or "unknown"), error_type="invalid_response", ) asset = assets[0] route_provider = resolved_route.get("provider") if isinstance(resolved_route.get("provider"), dict) else {} provider_id = asset.metadata.get("provider_id") or resolved_route.get("provider_id") provider_model = asset.metadata.get("provider_model") or resolved_route.get("model_id") usage = asset.metadata.get("usage") or {} latest_attempt = self.repository.get_attempt(attempt_id) or attempt billable_metadata = { **latest_attempt.metadata, **attempt_metadata, "generation": asset.metadata, "provider_base_url_present": bool(route_provider.get("base_url")), "effective_model_route": route_name, } # Persist billable attribution before the publication CAS. If the # user cancelled while the provider was running, the usage remains # auditable even though the late image is deleted instead of revived. self.repository.update_attempt( attempt_id, { "model_route": route_name, "provider_id": provider_id, "provider_model": provider_model, "width": asset.width, "height": asset.height, "usage": usage, "metadata": billable_metadata, }, ) completed = self.repository.complete_attempt_if_active( import_id, attempt_id, attempt_payload={ "model_route": route_name, "validation_image_uri": asset.image_uri, "validation_thumbnail_uri": asset.thumbnail_uri, "provider_id": provider_id, "provider_model": provider_model, "width": asset.width, "height": asset.height, "usage": usage, "metadata": billable_metadata, }, import_payload={ "metadata": { **record.metadata, "active_task_id": None, "last_validation_governance": governance["snapshot"], }, }, ) if completed is None: self._remove_uri(asset.image_uri) self._remove_uri(asset.thumbnail_uri) raise AdvancedMaterialTaskCancelled("advanced material validation result arrived after cancellation") updated_import, updated_attempt = completed self.audit_service.record( ctx=ctx, action="complete_advanced_material_validation", target_type="advanced_material_validation_attempt", target_id=attempt_id, after_snapshot=updated_attempt.to_dict(), metadata={"import_id": import_id, "task_id": task.task_id}, ) return WorkerTaskUpdate( result={ "import_id": import_id, "attempt_id": attempt_id, "status": updated_import.status, "validation_image_uri": asset.image_uri, "validation_thumbnail_uri": asset.thumbnail_uri, }, metadata={"pipeline_stage": "awaiting_human_review"}, ) def _govern_validation_prompt( self, *, record: Any, attempt: Any, requested_route: str, ctx: RequestContext, ) -> dict[str, Any]: prompt = str(attempt.prompt or record.recognition_prompt or "").strip() negative_prompt = str(attempt.negative_prompt or record.recognition_negative_prompt or "").strip() if not prompt: raise ApiError( ErrorCode.VALIDATION_FAILED, "advanced material validation prompt is empty", {"import_id": record.import_id, "attempt_id": attempt.attempt_id}, ) routing_context = self._validation_routing_context(record, ctx) if self.prompt_moderation_service: moderation = self.prompt_moderation_service.moderate( original_prompt=prompt, translated_prompt=prompt, final_prompt=prompt, negative_prompt=negative_prompt, reference_bindings=[], ) else: moderation = PromptModerationDecision( "safe", 1.0, [], ["moderation_not_configured"], "allow", None, "none", None, "", ) if self.generation_route_service: route = self.generation_route_service.decide( requested_route, moderation, entrypoint=routing_context["entrypoint"], user_id=routing_context["user_id"], group_id=routing_context["group_id"], permission_context=routing_context["content_permissions"], ) route_snapshot = route.to_dict() selected_route = route.selected_route allowed = route.allowed requires_confirmation = route.requires_confirmation route_reason = route.reason # The dedicated advanced-material assignment is intentionally # stronger than the global safe route. Only adult content may # leave the requested validation route for the configured NSFW # route. if allowed and moderation.level in {"safe", "sensitive"}: if selected_route != requested_route: route_snapshot["global_safe_route_ignored"] = selected_route selected_route = requested_route route_snapshot["selected_route"] = requested_route route_snapshot["reason"] = "advanced_material_requested_route" route_reason = "advanced_material_requested_route" else: selected_route = requested_route if moderation.allowed else None allowed = moderation.allowed requires_confirmation = moderation.level == "uncertain" route_reason = "static_route" route_snapshot = { "requested_route": requested_route, "moderation_level": moderation.level, "selected_route": selected_route, "reason": route_reason, "fallback_route": None, "allowed": allowed, "requires_confirmation": requires_confirmation, } snapshot = { "moderation": moderation.to_dict(), "route_decision": route_snapshot, "entrypoint": routing_context["entrypoint"], } if not allowed or not selected_route: if moderation.level in {"terror_prohibited", "violence_prohibited", "prohibited"}: try: self.audit_service.record( ctx=ctx, action="advanced_material_content_safety_blocked", target_type="advanced_material_validation_attempt", target_id=attempt.attempt_id, metadata={ "import_id": record.import_id, "priority": "high" if moderation.level in {"terror_prohibited", "violence_prohibited"} else "normal", "moderation_level": moderation.level, "reason_codes": moderation.reason_codes, "rules_version": moderation.rules_version, "entrypoint": routing_context["entrypoint"], }, ) except Exception: pass self.repository.update_attempt(attempt.attempt_id, {"metadata": {**attempt.metadata, "prompt_governance": snapshot}}) raise ApiError( ErrorCode.VALIDATION_FAILED, moderation.warning or ("内容需要确认后才能生成" if requires_confirmation else "内容审核未通过,未创建验证图任务"), { "moderation_level": moderation.level, "reason_codes": moderation.reason_codes, "route_reason": route_reason, "requires_confirmation": requires_confirmation, "warning": moderation.warning, }, ) return { "prompt": prompt, "negative_prompt": negative_prompt, "selected_route": selected_route, "moderation": moderation, "snapshot": snapshot, "routing_context": routing_context, } def _content_safety_fallback( self, *, exc: ImageProviderError, runtime_request: dict[str, Any], governance: dict[str, Any], requested_route: str, record: Any, ctx: RequestContext, ) -> dict[str, Any] | None: failure = self.failure_classifier.classify(exc) if failure.get("failure_class") != "content_safety_rejection": return None if not self.prompt_moderation_service or not self.generation_route_service: return None if isinstance(runtime_request.get("route_fallback"), dict) and runtime_request["route_fallback"].get("attempted"): return None prompt = str(runtime_request.get("expanded_prompt") or "").strip() negative_prompt = str(runtime_request.get("expanded_negative_prompt") or "").strip() moderation = self.prompt_moderation_service.moderate( original_prompt=prompt, translated_prompt=prompt, final_prompt=prompt, negative_prompt=negative_prompt, reference_bindings=[], ) if moderation.level in {"terror_prohibited", "violence_prohibited", "prohibited", "uncertain"}: return None if moderation.level != "adult_allowed" and failure.get("safety_reason") != "adult": return None provider_signal_moderation = moderation if moderation.level != "adult_allowed": provider_signal_moderation = replace( moderation, level="adult_allowed", categories=[*moderation.categories, "provider_content_safety_rejection"], reason_codes=[*moderation.reason_codes, "provider_classified_prompt_as_adult"], action="route_nsfw", warning=None, ) routing_context = self._validation_routing_context(record, ctx) route = self.generation_route_service.decide( requested_route, provider_signal_moderation, entrypoint=routing_context["entrypoint"], user_id=routing_context["user_id"], group_id=routing_context["group_id"], permission_context=routing_context["content_permissions"], ) current_route = str(runtime_request.get("model_route") or "").strip() if not route.allowed or not route.selected_route or route.selected_route == current_route: return None resolved_route = self._resolve_generation_route(route.selected_route) # The first provider may already have accepted and billed the request # before returning a content-safety rejection. Reserve two requests # for the fallback check so the budget cannot be bypassed by the # automatic second call. cost_guard = self._check_validation_budget( route.selected_route, resolved_route, planned_task_count=2, ) fallback_record = { "attempted": True, "initial_route": current_route, "failure_class": failure, "moderation_recheck": moderation.to_dict(), "provider_signal_moderation": provider_signal_moderation.to_dict(), "fallback_route": route.selected_route, "fallback_reason": route.reason, } return { "model_route": route.selected_route, "resolved_model_route": resolved_route, "route_fallback": fallback_record, "cost_guard": cost_guard, "request": { **runtime_request, "model_route": route.selected_route, "resolved_model_route": resolved_route, "route_fallback": fallback_record, "allow_provider_fallback": False, **({"cost_guard": cost_guard} if cost_guard else {}), }, } def _resolve_generation_route(self, route_name: str) -> dict[str, Any]: resolution = self.model_provider_service.resolve_route(route_name, modality="image_generation") if not resolution: raise ApiError( ErrorCode.MODEL_CAPABILITY_UNCONFIRMED, "advanced material validation image route is not configured", {"route_name": route_name, "modality": "image_generation"}, ) return { **resolution, "status": "resolved", "route_name": str(resolution.get("route_name") or route_name), } def _check_validation_budget( self, route_name: str, resolved_route: dict[str, Any], *, planned_task_count: int = 1, ) -> dict[str, Any] | None: advanced_config = self.config.get("advanced_materials") if isinstance(self.config.get("advanced_materials"), dict) else {} cost_guard_config = self.config.get("cost_guard") if isinstance(self.config.get("cost_guard"), dict) else {} budget = advanced_config.get("cost_budget") if isinstance(advanced_config.get("cost_budget"), dict) else None if budget is None and isinstance(cost_guard_config.get("advanced_materials"), dict): budget = cost_guard_config["advanced_materials"] if not budget or not self.cost_guard_service or not bool(budget.get("enabled", True)): return None unit_prices = budget.get("unit_prices") if isinstance(budget.get("unit_prices"), dict) else None price_key = str(budget.get("price_key") or "").strip() if unit_prices is None and price_key: unit_prices = { price_key: { "per_request": _optional_nonnegative_float(budget.get("per_request")), "per_image": _optional_nonnegative_float(budget.get("per_image")), "per_1k_tokens": _optional_nonnegative_float(budget.get("per_1k_tokens")), } } guard = self.cost_guard_service.check_generation_budget( provider_id=resolved_route.get("provider_id"), provider_model=resolved_route.get("model_id") or route_name, model_route=route_name, planned_task_count=max(int(planned_task_count), 1), planned_image_count=1, planned_total_tokens=int(budget.get("planned_total_tokens") or 0), max_task_count=budget.get("max_task_count"), max_image_count=budget.get("max_image_count"), max_estimated_cost=budget.get("max_estimated_cost"), days=budget.get("days"), unit_prices=unit_prices, ) if not guard.get("allowed"): raise ApiError(ErrorCode.VALIDATION_FAILED, "advanced material validation budget exceeded", guard) return guard def _validation_routing_context(self, record: Any, ctx: RequestContext) -> dict[str, Any]: stored = record.metadata.get("governance_context") if isinstance(record.metadata.get("governance_context"), dict) else {} permissions = stored.get("content_permissions") if isinstance(stored.get("content_permissions"), dict) else {} user_id = _optional_text(stored.get("user_id")) or ctx.actor_id group_id = _optional_text(stored.get("group_id")) access = self.config.get("chat_access") if isinstance(self.config.get("chat_access"), dict) else {} adult_users = {str(value).strip() for value in access.get("adult_user_allowlist", []) if str(value).strip()} adult_groups = {str(value).strip() for value in access.get("adult_group_allowlist", []) if str(value).strip()} return { "entrypoint": str(stored.get("entrypoint") or _entrypoint_from_context(ctx)), "user_id": user_id, "group_id": group_id, "content_permissions": { "adult_user_allowed": bool(user_id and user_id in adult_users), **({"adult_group_allowed": bool(group_id in adult_groups)} if group_id else {}), "quota_allowed": bool(permissions.get("quota_allowed", True)), }, } def _queue_recognition(self, record, ctx: RequestContext) -> GenerationTask: if record.status in IMPORT_ACTIVE_STATUSES and _optional_text(record.metadata.get("active_task_id")): try: existing = self.queue_service.get_job(str(record.metadata["active_task_id"])) except ApiError: existing = None if existing is not None and existing.status in {"queued", "running"}: return existing task = self.queue_service.create_task( { "task_type": "advanced_material_recognition", "status": "queued", "model_route": record.recognition_model_route or self._recognition_route(), "idempotency_key": f"advanced-material-recognition:{record.import_id}:{record.prompt_revision}", "request": {"import_id": record.import_id, "operation": "recognize"}, "metadata": { "source": "advanced_material", "advanced_material_import_id": record.import_id, "stage": "recognition", "task_summary": f"进阶素材/{record.display_name}/识别", }, }, ctx, ) self.repository.update_import( record.import_id, { "status": "recognition_queued", "error": None, "metadata": {**record.metadata, "active_task_id": task.task_id}, }, ) return task def _queue_validation(self, record, ctx: RequestContext): if record.status in IMPORT_ACTIVE_STATUSES: active = self.repository.get_active_attempt(record.import_id) if active is not None and active.task_id: task = self.queue_service.get_job(active.task_id) if task.status in {"queued", "running"}: return active, task if not record.recognition_prompt: raise ApiError( ErrorCode.VALIDATION_FAILED, "advanced material must be recognized before validation generation", {"import_id": record.import_id, "status": record.status}, ) if record.status not in {"ready_for_validation", "adjustment_required", "validation_failed"}: raise ApiError( ErrorCode.VALIDATION_FAILED, "advanced material is not ready to create a validation attempt", {"import_id": record.import_id, "status": record.status}, ) attempt_id = f"advattempt_{uuid4().hex}" route_name = _optional_text(record.metadata.get("generation_model_route")) or self._generation_route() attempt = self.repository.create_attempt( { "attempt_id": attempt_id, "import_id": record.import_id, "status": "queued", "adjustment_text": _latest_adjustment(record.metadata), "prompt": record.recognition_prompt, "negative_prompt": record.recognition_negative_prompt, "model_route": route_name, "seed": DEFAULT_VALIDATION_SEED, "width": 1024, "height": 1024, "metadata": {"prompt_revision": record.prompt_revision}, } ) attempt_number = attempt.attempt_number try: task = self.queue_service.create_task( { "task_type": "advanced_material_validation_generation", "status": "queued", "model_route": route_name, "idempotency_key": f"advanced-material-validation:{attempt_id}", "request": {"import_id": record.import_id, "attempt_id": attempt_id, "operation": "validate"}, "metadata": { "source": "advanced_material", "advanced_material_import_id": record.import_id, "advanced_material_attempt_id": attempt_id, "attempt_number": attempt_number, "stage": "validation_generation", "task_summary": f"进阶素材/{record.display_name}/第{attempt_number}轮验证", }, }, ctx, ) attempt = self.repository.update_attempt(attempt_id, {"task_id": task.task_id}) self.repository.update_import( record.import_id, { "status": "validation_queued", "current_attempt_id": attempt_id, "error": None, "metadata": {**record.metadata, "active_task_id": task.task_id}, }, ) except Exception as exc: self.repository.update_attempt(attempt_id, {"status": "failed", "error": _safe_failure(exc)}) self.repository.update_import( record.import_id, { "status": "validation_failed", "error": _safe_failure(exc), "metadata": {**record.metadata, "active_task_id": None}, }, ) raise return attempt, task def _apply_adjustment(self, record, adjustment: str, ctx: RequestContext): prompt = _append_adjustment(record.recognition_prompt, adjustment) history = list(record.metadata.get("adjustment_history") or []) history.append( { "revision": int(record.prompt_revision or 0) + 1, "text": adjustment, "actor_id": ctx.actor_id, } ) return self.repository.update_import( record.import_id, { "status": "adjustment_required", "recognition_prompt": prompt, "prompt_revision": int(record.prompt_revision or 0) + 1, "metadata": { **record.metadata, "adjustment_history": history[-20:], "governance_context": _governance_context(self.config, ctx), }, }, ) def _recognition_instruction(self, record) -> str: prompts = self.config.get("recognition_prompts") if isinstance(self.config.get("recognition_prompts"), dict) else {} base = str(prompts.get("default_instruction") or "").strip() category = self.material_repository.get_category(record.category_id) if record.category_id else None category_hint = f"User selected category: {category.name}." if category else "" return "\n\n".join( part for part in ( base, category_hint, "Extract observable colors, material, texture, silhouette, construction, patterns, trim and small details as faithfully as possible.", "Produce a standalone text-to-image prompt. Do not assume the source image will be supplied to the image generator.", ) if part ) def _recognition_route(self) -> str: assignments = self.config.get("model_assignments") if isinstance(self.config.get("model_assignments"), dict) else {} vision = self.config.get("vision") if isinstance(self.config.get("vision"), dict) else {} provider = vision.get("provider") if isinstance(vision.get("provider"), dict) else {} return str( assignments.get("advanced_material_recognition") or assignments.get("material_recognition") or provider.get("route_name") or vision.get("default_route") or "material_vlm" ).strip() def _consensus_route(self) -> str: assignments = self.config.get("model_assignments") if isinstance(self.config.get("model_assignments"), dict) else {} return str( assignments.get("advanced_style_consensus") or assignments.get("advanced_material_recognition") or assignments.get("material_recognition") or self._recognition_route() or "material_vlm" ).strip() def _generation_route(self) -> str: assignments = self.config.get("model_assignments") if isinstance(self.config.get("model_assignments"), dict) else {} generation = self.config.get("generation") if isinstance(self.config.get("generation"), dict) else {} provider = generation.get("provider") if isinstance(generation.get("provider"), dict) else {} return str( assignments.get("advanced_material_validation_generation") or assignments.get("quick_generation") or generation.get("default_model") or provider.get("route_name") or "image_default" ).strip() def _persist_source( self, *, import_id: str, image_data_url: str, image_uri: str, filename: str | None, declared_content_type: str | None, declared_size: int | None, ) -> tuple[str, str, int, str]: if image_data_url: content, detected_type, detected_extension = _decode_upload_data_url(image_data_url) elif image_uri: source_path = self.storage.ensure_file(image_uri) try: reported_size = source_path.stat().st_size if reported_size > MAX_UPLOAD_BYTES: raise ApiError( ErrorCode.UPLOAD_TOO_LARGE, "advanced material source exceeds the size limit", {"size_bytes": reported_size, "max_size_bytes": MAX_UPLOAD_BYTES}, ) with source_path.open("rb") as handle: content = handle.read(MAX_UPLOAD_BYTES + 1) except ApiError: raise except OSError as exc: raise ApiError( ErrorCode.MEDIA_NOT_FOUND, "advanced material source image could not be read", {"uri": image_uri, "exception_type": exc.__class__.__name__}, ) from None detected = detect_image_format(content) if detected is None: raise ApiError(ErrorCode.UNSUPPORTED_FILE_TYPE, "advanced material source is not a supported image") detected_type = detected.mime_type detected_extension = detected.extension filename = filename or source_path.name else: raise ApiError( ErrorCode.VALIDATION_FAILED, "image_data_url or image_uri is required", {"fields": ["image_data_url", "image_uri"]}, ) if len(content) > MAX_UPLOAD_BYTES: raise ApiError( ErrorCode.UPLOAD_TOO_LARGE, "advanced material upload exceeds the size limit", {"size_bytes": len(content), "max_size_bytes": MAX_UPLOAD_BYTES}, ) if declared_size is not None and declared_size != len(content): raise ApiError( ErrorCode.VALIDATION_FAILED, "declared upload size does not match image bytes", {"declared_size_bytes": declared_size, "actual_size_bytes": len(content)}, ) if declared_content_type and declared_content_type != detected_type: raise ApiError( ErrorCode.UNSUPPORTED_FILE_TYPE, "upload content type does not match image bytes", {"content_type": declared_content_type, "detected_content_type": detected_type}, ) filename_extension = _suffix(filename) if filename_extension and filename_extension != detected_extension: aliases = {(".jpg", ".jpeg"), (".jpeg", ".jpg")} if (filename_extension, detected_extension) not in aliases: raise ApiError( ErrorCode.UNSUPPORTED_FILE_TYPE, "upload filename extension does not match image bytes", {"filename": filename, "detected_content_type": detected_type}, ) safe_name = filename or f"advanced-material{detected_extension}" stem = PurePosixPath(safe_name).stem or "source" destination_uri = f"storage://advanced_materials/sources/{import_id}/{uuid4().hex}-{stem}{detected_extension}" path = self.storage.resolve_uri(destination_uri) try: path.parent.mkdir(parents=True, exist_ok=True) temporary = path.with_suffix(f"{path.suffix}.part") temporary.write_bytes(content) temporary.replace(path) except OSError as exc: raise ApiError( ErrorCode.STORAGE_WRITE_FAILED, "advanced material source image could not be stored", {"uri": destination_uri, "exception_type": exc.__class__.__name__}, ) from None return destination_uri, detected_type, len(content), safe_name def _remove_uri(self, uri: str) -> None: if not uri: return try: self.storage.resolve_uri(uri).unlink(missing_ok=True) except (ApiError, OSError): pass def _reconcile_import_task(self, record: Any) -> Any: if self.style_sets.is_style_set(record): return self.style_sets.reconcile_missing_tasks(record) if record.status not in IMPORT_ACTIVE_STATUSES: return record task_id = _optional_text(record.metadata.get("active_task_id")) task_missing = not task_id if task_id: try: self.queue_service.get_job(task_id) except ApiError: task_missing = True if not task_missing: return record stage = "validation_generation" if record.status in {"validation_queued", "validating"} else "recognition" failure = { "error_type": "queue_task_missing", "message": "关联的队列记录已被删除;可重新入队或删除整个导入。", "stage": stage, "task_id": task_id, "retryable": True, } if stage == "validation_generation": attempt = self.repository.get_active_attempt(record.import_id) if attempt is not None: self.repository.update_attempt( attempt.attempt_id, {"status": "failed", "task_id": None, "error": failure}, ) status = "validation_failed" else: status = "recognition_failed" return self.repository.update_import( record.import_id, { "status": status, "error": failure, "metadata": {**record.metadata, "active_task_id": None}, }, ) or record def _import_media_uris(self, record: Any) -> set[str]: values: set[str] = set() def add(*items: Any) -> None: for item in items: uri = str(item or "").strip() if uri.startswith("storage://advanced_materials/"): values.add(uri) add(record.source_image_uri, record.source_thumbnail_uri) if self.style_sets.is_style_set(record): for source in self.repository.list_style_sources(record.import_id): add(source.source_image_uri, source.source_thumbnail_uri) for attempt in self.repository.list_attempts(record.import_id): add(attempt.validation_image_uri, attempt.validation_thumbnail_uri) for case in self.repository.list_style_validation_cases(attempt.attempt_id): add(case.validation_image_uri, case.validation_thumbnail_uri) return values def _ensure_task_active(self, task: GenerationTask, record: Any, *, attempt: Any | None = None) -> None: if record.status in {"cancelled", "accepted", "archived"}: raise AdvancedMaterialTaskCancelled( f"advanced material import is no longer active: {record.status}" ) active_task_id = _optional_text(record.metadata.get("active_task_id")) if active_task_id and active_task_id != task.task_id: raise AdvancedMaterialTaskCancelled("advanced material task was superseded") if attempt is not None: if attempt.status in {"cancelled", "accepted", "rejected", "failed"}: raise AdvancedMaterialTaskCancelled( f"advanced material validation attempt is no longer active: {attempt.status}" ) if attempt.task_id and attempt.task_id != task.task_id: raise AdvancedMaterialTaskCancelled("advanced material validation task was superseded") try: queued_task = self.queue_service.get_job(task.task_id) except ApiError as exc: raise AdvancedMaterialTaskCancelled("advanced material queue task no longer exists") from exc if queued_task.status not in {"queued", "running", "retrying"}: raise AdvancedMaterialTaskCancelled( f"advanced material queue task is no longer active: {queued_task.status}" ) def _require_import(self, import_id: str): record = self.repository.get_import(import_id) if record is None or record.status == "archived": raise ApiError(ErrorCode.RESOURCE_NOT_FOUND, "advanced material import not found", {"import_id": import_id}) return record def _require_attempt(self, import_id: str, attempt_id: str): attempt = self.repository.get_attempt(attempt_id) if attempt is None or attempt.import_id != import_id: raise ApiError( ErrorCode.RESOURCE_NOT_FOUND, "advanced material validation attempt not found", {"import_id": import_id, "attempt_id": attempt_id}, ) return attempt def create_advanced_material_service() -> AdvancedMaterialService: database = Database(load_database_settings()) audit = AuditService(database) config = load_config_payload() # AstrBot may expose a stale/blank runtime default for newly-added plugin # fields. The writable plugin-data config is the source of truth for this # dedicated route because the settings page persists it there. file_config = load_config_file_payload() file_assignments = file_config.get("model_assignments") if isinstance(file_config.get("model_assignments"), dict) else {} persisted_consensus_route = str(file_assignments.get("advanced_style_consensus") or "").strip() if persisted_consensus_route: config = { **config, "model_assignments": { **(config.get("model_assignments") if isinstance(config.get("model_assignments"), dict) else {}), "advanced_style_consensus": persisted_consensus_route, }, } model_service = ModelProviderService(ModelProviderRepository(database)) sync_generation_provider_from_config(model_service, config) sync_vision_provider_from_config(model_service, config) runtime = ModelProviderRuntime(model_service) storage = VfsStorage() model_assignments = config.get("model_assignments") if isinstance(config.get("model_assignments"), dict) else {} governance_config = config.get("prompt_governance") if isinstance(config.get("prompt_governance"), dict) else {} moderation_config = governance_config.get("moderation") if isinstance(governance_config.get("moderation"), dict) else {} routing_config = governance_config.get("routing") if isinstance(governance_config.get("routing"), dict) else {} moderation_route = str( moderation_config.get("model_route") or model_assignments.get("cross_review_primary") or "" ).strip() moderation_callable = ( runtime.structured_text_callable(moderation_route) or astrbot_structured_text_callable(moderation_route) ) if moderation_route else None if moderation_callable: raw_moderation_callable = moderation_callable moderation_callable = lambda request: raw_moderation_callable( {**request, "purpose": "advanced material validation prompt content risk classification"} ) return AdvancedMaterialService( repository=AdvancedMaterialRepository(database), material_repository=MaterialRepository(database), queue_service=QueueService(JobRepository(database), audit, get_default_event_bus()), audit_service=audit, model_provider_service=model_service, model_provider_runtime=runtime, config=config, storage=storage, single_flow_engine=SingleFlowEngine( storage=storage, image_provider_factory=runtime.image_provider_for_route, allow_mock_fallback=False, ), prompt_moderation_service=PromptModerationService(moderation_config, moderation_callable), generation_route_service=GenerationRouteService(routing_config), cost_guard_service=CostGuardService(CostService(database)), ) def _governance_context(config: dict[str, Any], ctx: RequestContext) -> dict[str, Any]: access = config.get("chat_access") if isinstance(config.get("chat_access"), dict) else {} adult_users = { str(value).strip() for value in access.get("adult_user_allowlist", []) if str(value).strip() } actor_id = _optional_text(ctx.actor_id) return { "entrypoint": _entrypoint_from_context(ctx), "user_id": actor_id, "group_id": None, "content_permissions": { "adult_user_allowed": bool(actor_id and actor_id in adult_users), "quota_allowed": True, }, } def _entrypoint_from_context(ctx: RequestContext) -> str: value = f"{ctx.platform} {ctx.source}".lower() if "qq" in value or "onebot" in value: return "qq" if "telegram" in value: return "telegram" if "discord" in value: return "discord" if "api" in value: return "api" return "web" def _optional_score(value: Any) -> float | None: if value in (None, ""): return None try: score = float(value) except (TypeError, ValueError): raise ApiError(ErrorCode.VALIDATION_FAILED, "fidelity_score must be a number", {"field": "fidelity_score"}) from None if score > 1.0: score /= 100.0 return min(max(score, 0.0), 1.0) def _optional_nonnegative_float(value: Any) -> float: try: return max(float(value or 0), 0.0) except (TypeError, ValueError): return 0.0 def _append_adjustment(prompt: str | None, adjustment: str) -> str: base = str(prompt or "").strip() requirement = adjustment.strip() marker = "User fidelity adjustment" return "\n\n".join(part for part in (base, f"{marker}: {requirement}") if part) def _latest_adjustment(metadata: dict[str, Any]) -> str | None: history = metadata.get("adjustment_history") if not isinstance(history, list) or not history: return None last = history[-1] return _optional_text(last.get("text")) if isinstance(last, dict) else None def _safe_failure(exc: Exception) -> dict[str, Any]: failure: dict[str, Any] = { "error_type": exc.__class__.__name__, "exception_type": exc.__class__.__name__, "message": " ".join(str(exc).split())[:500] or exc.__class__.__name__, } if isinstance(exc, ApiError): failure.update({"error_code": exc.error_code.value, "details": exc.details}) elif isinstance(exc, ImageProviderError): failure.update( { "provider_id": exc.provider_id, "status_code": exc.status_code, "provider_error_type": exc.error_type, } ) return failure