"""Conversational feedback planning for the existing workflow round pool. The service is intentionally persistence-free. It gives Web and AstrBot one shared interpretation contract while the owning ``WorkflowRoundService`` keeps authorization, transactions and next-round creation server-side. """ from __future__ import annotations from collections.abc import Callable, Mapping from dataclasses import replace import json import re from typing import Any from backend.dto.workflow_feedback_dto import WorkflowFeedbackInterpretation from backend.services.workflow_feedback_interpreter import ( WorkflowFeedbackInterpretationError, WorkflowFeedbackInterpreter, ) StructuredFeedbackCallable = Callable[[dict[str, Any]], dict[str, Any] | str] MAX_FEEDBACK_TEXT_LENGTH = 12_000 MAX_PATCH_LENGTH = 4_000 MAX_MATERIAL_INTENT_LENGTH = 2_000 class WorkflowRoundFeedbackService: """Use the configured text model when available, with a safe local fallback.""" def __init__( self, *, interpreter: WorkflowFeedbackInterpreter | None = None, structured_text_callable: StructuredFeedbackCallable | None = None, model_route: str | None = None, ) -> None: self.interpreter = interpreter or WorkflowFeedbackInterpreter() self.structured_text_callable = structured_text_callable self.model_route = str(model_route or "").strip() or None def interpret( self, text: str, *, candidate_whitelist: Mapping[str, str], candidate_context: Mapping[str, Mapping[str, Any]] | None = None, ) -> WorkflowFeedbackInterpretation: source_text = _bounded_text(text, field="feedback_text", maximum=MAX_FEEDBACK_TEXT_LENGTH) if not source_text: raise WorkflowFeedbackInterpretationError( "feedback_text_required", "feedback_text is required", {"field": "feedback_text"}, ) fallback_reason: str | None = None if self.structured_text_callable is not None: try: raw = self.structured_text_callable( _model_request( source_text, candidate_whitelist, self.model_route, candidate_context=candidate_context, ) ) payload = _normalize_model_payload(raw) interpretation = self.interpreter.validate_llm_result( payload, candidate_whitelist=candidate_whitelist, source_text=source_text, ) return _bounded_interpretation( replace( interpretation, metadata={ "model_attempted": True, "model_route": self.model_route, "fallback_used": False, }, ) ) except Exception as exc: # Never expose provider messages here: they can contain URLs, # headers or vendor-specific request fragments. The caller # receives only a stable error class and then the deterministic # parser evaluates the original user text from scratch. fallback_reason = _safe_failure_code(exc) elif self.model_route: fallback_reason = "model_callable_unavailable" interpretation = self.interpreter.interpret( source_text, candidate_whitelist=candidate_whitelist, ) return _bounded_interpretation( replace( interpretation, positive_patch=interpretation.positive_patch or interpretation.next_round_prompt_patch, source="deterministic_fallback" if fallback_reason else "deterministic", metadata={ "model_attempted": self.structured_text_callable is not None, "model_route": self.model_route, "fallback_used": bool(fallback_reason), **({"fallback_reason": fallback_reason} if fallback_reason else {}), }, ) ) def _model_request( source_text: str, candidate_whitelist: Mapping[str, str], model_route: str | None, *, candidate_context: Mapping[str, Mapping[str, Any]] | None, ) -> dict[str, Any]: # Opaque candidate IDs deliberately never cross the model boundary. display_codes = [str(code).strip() for code in candidate_whitelist if str(code).strip()] context = candidate_context if isinstance(candidate_context, Mapping) else {} return { "purpose": "workflow candidate feedback interpretation and next-round prompt patch planning", "user_text": source_text, "candidate_whitelist": [ { "display_code": code, "ordinal": index, "positive_prompt": _bounded_context_text( (context.get(code) or {}).get("positive_prompt"), maximum=4_000, ), "negative_prompt": _bounded_context_text( (context.get(code) or {}).get("negative_prompt"), maximum=2_000, ), "model_label": _bounded_context_text( (context.get(code) or {}).get("model_label"), maximum=200, ), } for index, code in enumerate(display_codes, start=1) ], "response_schema": { "feedback": { "liked": ["display_code"], "rejected": ["display_code"], "strict_rejected": ["display_code"], "final": "display_code|null", }, "positive_patch": "string|null", "negative_patch": "string|null", "material_intent": "string|null", }, "rules": [ "Use only display_code values from candidate_whitelist.", "Never return opaque server identifiers.", "Keep strict rejections in negative_patch.", "Do not invent visual details absent from user_text.", ], **({"model_route": model_route} if model_route else {}), } def _normalize_model_payload(value: dict[str, Any] | str) -> dict[str, Any]: if isinstance(value, str): cleaned = re.sub(r"^```(?:json)?\s*|\s*```$", "", value.strip(), flags=re.IGNORECASE) parsed = json.loads(cleaned) else: parsed = value if not isinstance(parsed, Mapping): raise WorkflowFeedbackInterpretationError( "invalid_llm_result", "LLM feedback result must be an object", ) _reject_opaque_identifier_keys(parsed) feedback = parsed.get("feedback") feedback = dict(feedback) if isinstance(feedback, Mapping) else {} merged = { **feedback, "positive_patch": parsed.get( "positive_patch", feedback.get("positive_patch", parsed.get("next_round_prompt_patch")), ), "negative_patch": parsed.get("negative_patch", feedback.get("negative_patch")), "material_intent": parsed.get("material_intent", feedback.get("material_intent")), } return merged def _bounded_interpretation( interpretation: WorkflowFeedbackInterpretation, ) -> WorkflowFeedbackInterpretation: positive = _bounded_optional( interpretation.positive_patch or interpretation.next_round_prompt_patch, field="positive_patch", maximum=MAX_PATCH_LENGTH, ) negative = _bounded_optional( interpretation.negative_patch, field="negative_patch", maximum=MAX_PATCH_LENGTH, ) material = _bounded_optional( interpretation.material_intent, field="material_intent", maximum=MAX_MATERIAL_INTENT_LENGTH, ) return replace( interpretation, next_round_prompt_patch=positive, positive_patch=positive, negative_patch=negative, material_intent=material, ) def _bounded_optional(value: Any, *, field: str, maximum: int) -> str | None: if value is None: return None return _bounded_text(value, field=field, maximum=maximum) or None def _bounded_text(value: Any, *, field: str, maximum: int) -> str: if not isinstance(value, str): raise WorkflowFeedbackInterpretationError( "invalid_feedback_text", f"{field} must be text", {"field": field}, ) normalized = value.strip() if len(normalized) > maximum: raise WorkflowFeedbackInterpretationError( "feedback_text_too_long", f"{field} is too long", {"field": field, "maximum": maximum}, ) return normalized def _safe_failure_code(exc: Exception) -> str: if isinstance(exc, WorkflowFeedbackInterpretationError): return exc.reason return type(exc).__name__[:80] def _bounded_context_text(value: Any, *, maximum: int) -> str | None: text = " ".join(str(value or "").split()) return text[:maximum] or None def _reject_opaque_identifier_keys(value: Any, *, path: str = "$") -> None: if isinstance(value, Mapping): for key, item in value.items(): if str(key).strip().lower() in {"candidate_id", "candidate_ids"}: raise WorkflowFeedbackInterpretationError( "invalid_llm_result", "LLM feedback must reference candidates by display_code only", {"field": f"{path}.{key}", "reason": "llm_candidate_id_forbidden"}, ) _reject_opaque_identifier_keys(item, path=f"{path}.{key}") elif isinstance(value, (list, tuple)): for index, item in enumerate(value): _reject_opaque_identifier_keys(item, path=f"{path}[{index}]")