2026-07-12 02:54:45 +08:00
""" Prompt translation, semantic normalization, moderation and route governance.
The services are provider - neutral . Optional callables can connect configured LLM / VLM
routes , while deterministic validation and conservative fallbacks remain available
when an external reviewer is unavailable .
"""
from __future__ import annotations
import re
from dataclasses import dataclass
from datetime import datetime , timezone
from typing import Any , Callable , Mapping
RISK_LEVELS = (
" safe " , " sensitive " , " adult_allowed " , " uncertain " ,
" violence_prohibited " , " terror_prohibited " , " prohibited " ,
)
RISK_PRIORITY = { level : index for index , level in enumerate ( RISK_LEVELS ) }
ENTRYPOINTS = { " web " , " qq " , " telegram " , " discord " , " api " , " unknown " }
TranslationCallable = Callable [ [ dict [ str , Any ] ] , Mapping [ str , Any ] | str ]
ModerationCallable = Callable [ [ dict [ str , Any ] ] , Mapping [ str , Any ] ]
ImageModerationCallable = Callable [ [ dict [ str , Any ] ] , Mapping [ str , Any ] ]
@dataclass ( frozen = True )
class PromptTranslationResult :
original_text : str
translated_text : str
status : str
enabled : bool
accepted : bool
model_route : str | None
template_version : str
created_at : str
sections : dict [ str , Any ]
difference_summary : list [ str ]
error : str | None = None
def to_dict ( self ) - > dict [ str , Any ] :
return dict ( self . __dict__ )
class PromptTranslationService :
def __init__ ( self , config : Mapping [ str , Any ] | None = None , translator : TranslationCallable | None = None ) :
self . config = dict ( config or { } )
self . translator = translator
def translate ( self , text : str , * , entrypoint : str = " web " , user_allowed : bool = False , model_family : str = " natural_language " , locked_terms : list [ str ] | None = None , budget : int | None = None ) - > PromptTranslationResult :
original = _text ( text )
enabled = bool ( self . config . get ( " enabled " , False ) )
entrypoint = entrypoint if entrypoint in ENTRYPOINTS else " unknown "
entrypoint_allowed = bool ( ( self . config . get ( " entrypoints " ) or { } ) . get ( entrypoint , entrypoint == " web " ) )
allowed = enabled and user_allowed and entrypoint_allowed
now = _utc_now ( )
route = _optional_text ( self . config . get ( " model_route " ) )
version = _text ( self . config . get ( " template_version " ) ) or " 1.0 "
if not original or not allowed :
return PromptTranslationResult ( original , original , " bypassed " , enabled , False , route , version , now , { } , [ ] )
if _is_english_only ( original ) :
return PromptTranslationResult ( original , original , " english_passthrough " , True , True , route , version , now , { " prompt " : original } , [ ] )
request = {
" text " : original ,
" target_language " : " English " ,
" model_family " : model_family ,
" locked_terms " : list ( locked_terms or [ ] ) ,
" budget " : budget ,
" requirements " : [
" preserve the user ' s visual intent " ,
" separate subject, appearance, clothing, action, composition, scene, style, lighting, camera and negative constraints " ,
" do not hide or encode safety-relevant meaning " ,
" do not change age or identity " ,
] ,
}
if self . translator is None :
return PromptTranslationResult ( original , original , " unavailable_fallback " , True , False , route , version , now , { } , [ ] , " translation model is unavailable " )
try :
response = self . translator ( request )
if isinstance ( response , str ) :
translated , sections = _text ( response ) , { " prompt " : _text ( response ) }
elif isinstance ( response , Mapping ) :
translated = _text ( response . get ( " translated_text " ) or response . get ( " prompt " ) )
sections = dict ( response . get ( " sections " ) or { } )
else :
translated , sections = " " , { }
if not translated :
raise ValueError ( " translator returned an empty prompt " )
translated = _restore_locked_terms ( original , translated , locked_terms or [ ] )
if budget and len ( translated ) > budget :
translated = _budget_text ( translated , budget , locked_terms or [ ] )
return PromptTranslationResult ( original , translated , " translated " , True , True , route , version , now , sections , _difference_summary ( original , translated ) )
except Exception as exc :
return PromptTranslationResult ( original , original , " failed_fallback " , True , False , route , version , now , { } , [ ] , exc . __class__ . __name__ )
class PromptSemanticNormalizer :
VERSION = " 1.0 "
def normalize ( self , text : str , * , locked_terms : list [ str ] | None = None ) - > dict [ str , Any ] :
original = _text ( text )
normalized = original
changes : list [ dict [ str , str ] ] = [ ]
replacements = {
r " (?i) \ b(girl|boy) \ b " : " adult woman " if re . search ( r " (?i) \ bgirl \ b " , normalized ) else " adult man " ,
r " 少女 " : " 成年女性 " ,
r " 少年 " : " 成年男性 " ,
}
# Age-disambiguation is only added for otherwise lawful adult contexts.
if _contains_any ( normalized , ADULT_TERMS ) and not _contains_any ( normalized , MINOR_TERMS ) :
if not _contains_any ( normalized , ADULT_AGE_TERMS ) :
normalized = f " adult subject, { normalized } "
changes . append ( { " from " : " implicit age " , " to " : " adult subject " , " reason " : " adult_age_disambiguation " } )
for pattern , replacement in replacements . items ( ) :
if re . search ( pattern , normalized ) and _contains_any ( normalized , ADULT_TERMS ) :
before = normalized
normalized = re . sub ( pattern , replacement , normalized )
if normalized != before :
changes . append ( { " from " : pattern , " to " : replacement , " reason " : " age_disambiguation " } )
normalized = _restore_locked_terms ( original , normalized , locked_terms or [ ] )
return {
" original_text " : original ,
" normalized_text " : normalized ,
" changed_terms " : changes ,
" reason " : " reduce ambiguity without concealing safety meaning " if changes else " no_change " ,
" meaning_preserved " : True ,
" requires_confirmation " : False ,
" version " : self . VERSION ,
" created_at " : _utc_now ( ) ,
}
@dataclass ( frozen = True )
class PromptModerationDecision :
level : str
confidence : float
categories : list [ str ]
reason_codes : list [ str ]
action : str
warning : str | None
rules_version : str
model_route : str | None
created_at : str
@property
def allowed ( self ) - > bool :
return self . level in { " safe " , " sensitive " , " adult_allowed " }
def to_dict ( self ) - > dict [ str , Any ] :
return { * * self . __dict__ , " allowed " : self . allowed }
class PromptModerationService :
RULES_VERSION = " 1.0 "
def __init__ ( self , config : Mapping [ str , Any ] | None = None , reviewer : ModerationCallable | None = None ) :
self . config = dict ( config or { } )
self . reviewer = reviewer
def moderate ( self , * , original_prompt : str , translated_prompt : str = " " , final_prompt : str = " " , negative_prompt : str = " " , reference_bindings : list [ dict [ str , Any ] ] | None = None ) - > PromptModerationDecision :
2026-07-18 23:20:06 +08:00
positive_text = " \n " . join (
_text ( value )
for value in ( original_prompt , translated_prompt , final_prompt )
if _text ( value )
)
# Negative prompts describe content that should be excluded. Treating
# words such as "nudity", "gore" or "child" there as requested
# content creates false adult/prohibited decisions.
rule = self . _rule_decision ( positive_text )
review_text = positive_text
if negative := _text ( negative_prompt ) :
review_text = f " { positive_text } \n \n Negative constraints (must be excluded): \n { negative } "
model = self . _model_decision ( review_text , reference_bindings or [ ] )
2026-07-12 02:54:45 +08:00
return _stricter_decision ( rule , model )
def _rule_decision ( self , text : str ) - > PromptModerationDecision :
lower = text . casefold ( )
if _contains_any ( lower , TERROR_TERMS ) :
return _decision ( " terror_prohibited " , 0.96 , [ " terrorism " ] , [ " terrorism_or_extremism " ] , " reject_warn " , " 请求涉及恐怖主义或极端主义内容,已禁止生成。 " )
if _contains_any ( lower , VIOLENCE_PROHIBITED_TERMS ) :
return _decision ( " violence_prohibited " , 0.94 , [ " high_risk_violence " ] , [ " violent_harm_or_extreme_gore " ] , " reject_warn " , " 请求涉及高危暴力、现实伤害或极端血腥内容,已禁止生成。 " )
adult = _contains_any ( lower , ADULT_TERMS )
minor = _contains_any ( lower , MINOR_TERMS )
if adult and minor :
return _decision ( " prohibited " , 0.98 , [ " sexual_minors " ] , [ " adult_content_with_minor_or_ambiguous_age " ] , " reject_warn " , " 成人内容中的人物年龄不明确或涉及未成年人,已禁止生成。 " )
if _contains_any ( lower , OTHER_PROHIBITED_TERMS ) :
return _decision ( " prohibited " , 0.93 , [ " prohibited " ] , [ " prohibited_content " ] , " reject " , " 请求包含禁止生成的内容。 " )
if adult :
if not _contains_any ( lower , ADULT_AGE_TERMS ) :
return _decision ( " uncertain " , 0.72 , [ " adult " , " ambiguous_age " ] , [ " adult_age_not_explicit " ] , " confirm_or_reject " , " 请先明确所有人物均为成年人。 " )
return _decision ( " adult_allowed " , 0.90 , [ " adult " ] , [ " lawful_adult_content " ] , " route_nsfw " , None )
if _contains_any ( lower , SENSITIVE_TERMS ) :
return _decision ( " sensitive " , 0.75 , [ " sensitive " ] , [ " sensitive_but_allowed " ] , " allow " , None )
return _decision ( " safe " , 0.85 , [ ] , [ " no_risk_signal " ] , " allow " , None )
def _model_decision ( self , text : str , references : list [ dict [ str , Any ] ] ) - > PromptModerationDecision | None :
2026-07-18 23:20:06 +08:00
if not bool ( self . config . get ( " llm_review_enabled " , False ) ) :
2026-07-12 02:54:45 +08:00
return None
2026-07-18 23:20:06 +08:00
if self . reviewer is None :
fallback = _text ( self . config . get ( " failure_policy " ) or " fail_closed " )
return _decision (
" uncertain " if fallback == " confirm " else " prohibited " ,
0.5 ,
[ " review_unavailable " ] ,
[ " moderation_service_unavailable " ] ,
" confirm_or_reject " if fallback == " confirm " else " reject " ,
" 内容审核模型不可用,已采用保守策略。 " ,
)
2026-07-12 02:54:45 +08:00
try :
response = self . reviewer ( { " text " : text , " reference_bindings " : references , " levels " : list ( RISK_LEVELS ) , " rules_version " : self . RULES_VERSION } )
level = _text ( response . get ( " level " ) )
if level not in RISK_LEVELS :
raise ValueError ( " invalid moderation level " )
return PromptModerationDecision (
level = level ,
confidence = _bounded_float ( response . get ( " confidence " ) , 0.5 ) ,
categories = _string_list ( response . get ( " categories " ) ) ,
reason_codes = _string_list ( response . get ( " reason_codes " ) ) or [ " model_review " ] ,
action = _text ( response . get ( " action " ) ) or _action_for_level ( level ) ,
warning = _optional_text ( response . get ( " warning " ) ) ,
rules_version = _text ( response . get ( " rules_version " ) ) or self . RULES_VERSION ,
model_route = _optional_text ( self . config . get ( " model_route " ) ) ,
created_at = _utc_now ( ) ,
)
except Exception :
fallback = _text ( self . config . get ( " failure_policy " ) or " fail_closed " )
return _decision ( " uncertain " if fallback == " confirm " else " prohibited " , 0.5 , [ " review_unavailable " ] , [ " moderation_service_failure " ] , " confirm_or_reject " if fallback == " confirm " else " reject " , " 内容审核暂时不可用,已采用保守策略。 " )
@dataclass ( frozen = True )
class GenerationRouteDecision :
requested_route : str
moderation_level : str
selected_route : str | None
reason : str
fallback_route : str | None
allowed : bool
requires_confirmation : bool
created_at : str
def to_dict ( self ) - > dict [ str , Any ] :
return dict ( self . __dict__ )
class GenerationRouteService :
def __init__ ( self , config : Mapping [ str , Any ] | None = None ) :
self . config = dict ( config or { } )
def decide ( self , requested_route : str , moderation : PromptModerationDecision , * , entrypoint : str , user_id : str | None , group_id : str | None , permission_context : Mapping [ str , Any ] | None = None ) - > GenerationRouteDecision :
permissions = dict ( permission_context or { } )
level = moderation . level
if level in { " violence_prohibited " , " terror_prohibited " , " prohibited " } :
return self . _decision ( requested_route , level , None , " content_prohibited " , None , False , False )
if level == " uncertain " :
return self . _decision ( requested_route , level , None , " moderation_confirmation_required " , None , False , True )
safe_route = _optional_text ( self . config . get ( " safe_route " ) ) or requested_route
nsfw_route = _optional_text ( self . config . get ( " nsfw_route " ) )
if level != " adult_allowed " :
return self . _decision ( requested_route , level , safe_route , " safe_or_sensitive_content " , nsfw_route , True , False )
enabled = bool ( self . config . get ( " adult_auto_route_enabled " , False ) )
entry_allowed = bool ( ( self . config . get ( " entrypoints " ) or { } ) . get ( entrypoint , False ) )
user_allowed = bool ( permissions . get ( " adult_user_allowed " , False ) )
group_allowed = bool ( permissions . get ( " adult_group_allowed " , group_id is None ) )
quota_allowed = bool ( permissions . get ( " quota_allowed " , True ) )
if not all ( ( enabled , entry_allowed , user_allowed , group_allowed , quota_allowed ) ) :
return self . _decision ( requested_route , level , None , " adult_route_permission_denied " , nsfw_route , False , False )
if not nsfw_route :
return self . _decision ( requested_route , level , None , " nsfw_route_not_configured " , None , False , False )
return self . _decision ( requested_route , level , nsfw_route , " adult_content_auto_routed " , None , True , False )
def _decision ( self , requested : str , level : str , selected : str | None , reason : str , fallback : str | None , allowed : bool , confirm : bool ) - > GenerationRouteDecision :
return GenerationRouteDecision ( requested , level , selected , reason , fallback , allowed , confirm , _utc_now ( ) )
class GenerationFailureClassifier :
2026-07-18 23:20:06 +08:00
CONTENT_SIGNALS = (
" nsfw " ,
" safety " ,
" content policy " ,
" moderation " ,
" sexual content " ,
" adult content " ,
" blocked prompt " ,
" underage " ,
" child sexual " ,
" violence " ,
" gore " ,
" terror " ,
" extremism " ,
" 内容审核 " ,
" 敏感内容 " ,
)
ADULT_SAFETY_SIGNALS = ( " nsfw " , " sexual content " , " adult content " , " nudity " , " erotic " , " porn " )
MINOR_SAFETY_SIGNALS = ( " minor " , " underage " , " child sexual " , " csam " )
VIOLENCE_SAFETY_SIGNALS = ( " violence " , " violent " , " gore " , " dismember " , " beheading " , " torture " )
TERROR_SAFETY_SIGNALS = ( " terror " , " extremism " , " extremist " )
2026-07-12 02:54:45 +08:00
def classify ( self , failure : Mapping [ str , Any ] | BaseException ) - > dict [ str , Any ] :
if isinstance ( failure , Mapping ) :
status = failure . get ( " status_code " )
error_type = _text ( failure . get ( " error_type " ) or failure . get ( " category " ) )
detail = _text ( failure . get ( " message " ) ) + " " + _text ( failure . get ( " details " ) )
provider_id = _optional_text ( failure . get ( " provider_id " ) )
else :
status = getattr ( failure , " status_code " , None )
error_type = _text ( getattr ( failure , " error_type " , failure . __class__ . __name__ ) )
details = getattr ( failure , " details " , { } )
detail = f " { failure } { details } "
provider_id = _optional_text ( getattr ( failure , " provider_id " , None ) )
lower = f " { error_type } { detail } " . casefold ( )
2026-07-18 23:20:06 +08:00
safety_reason = None
2026-07-12 02:54:45 +08:00
if any ( signal in lower for signal in self . CONTENT_SIGNALS ) :
category = " content_safety_rejection "
2026-07-18 23:20:06 +08:00
if any ( signal in lower for signal in self . MINOR_SAFETY_SIGNALS ) :
safety_reason = " minor "
elif any ( signal in lower for signal in self . TERROR_SAFETY_SIGNALS ) :
safety_reason = " terror "
elif any ( signal in lower for signal in self . VIOLENCE_SAFETY_SIGNALS ) :
safety_reason = " violence "
elif any ( signal in lower for signal in self . ADULT_SAFETY_SIGNALS ) :
safety_reason = " adult "
else :
safety_reason = " unknown "
2026-07-12 02:54:45 +08:00
elif " quota " in lower or " credit " in lower or " balance " in lower :
category = " quota_exhausted "
elif status == 429 or " rate " in lower :
category = " rate_limit "
elif status in { 401 , 403 } or " auth " in lower or " credential " in lower :
category = " authentication "
elif " timeout " in lower or status in { 408 , 504 } :
category = " timeout "
elif " unsupported " in lower or " capability " in lower :
category = " unsupported_capability "
elif status is not None and 400 < = int ( status ) < 500 :
category = " invalid_request "
elif " network " in lower or ( status is not None and int ( status ) > = 500 ) :
category = " upstream_error "
else :
category = " unknown "
2026-07-18 23:20:06 +08:00
return {
" failure_class " : category ,
" safety_reason " : safety_reason ,
" provider_id " : provider_id ,
" status_code " : status ,
" error_type " : error_type ,
" summary " : _redact ( detail ) [ : 500 ] ,
}
2026-07-12 02:54:45 +08:00
class ImageModerationService :
def __init__ ( self , config : Mapping [ str , Any ] | None = None , reviewer : ImageModerationCallable | None = None ) :
self . config = dict ( config or { } )
self . reviewer = reviewer
def moderate ( self , image : Mapping [ str , Any ] , * , requested_level : str , route_kind : str ) - > dict [ str , Any ] :
if self . reviewer is None or not bool ( self . config . get ( " enabled " , False ) ) :
return { " status " : " not_configured " , " action " : " allow " , " requested_level " : requested_level , " route_kind " : route_kind , " version " : " 1.0 " }
try :
result = dict ( self . reviewer ( { " image " : dict ( image ) , " requested_level " : requested_level , " route_kind " : route_kind } ) )
except Exception :
return { " status " : " review_failed " , " action " : " quarantine " , " requested_level " : requested_level , " route_kind " : route_kind , " version " : " 1.0 " }
action = _text ( result . get ( " action " ) )
if action not in { " allow " , " warn " , " quarantine " , " regenerate " , " reject " } :
action = " quarantine "
return { * * result , " action " : action , " status " : " reviewed " , " version " : _text ( result . get ( " version " ) ) or " 1.0 " }
TERROR_TERMS = ( " terrorist propaganda " , " terror recruitment " , " join isis " , " join al qaeda " , " 恐怖组织宣传 " , " 恐怖主义招募 " , " 加入恐怖组织 " , " 极端主义行动 " )
VIOLENCE_PROHIBITED_TERMS = ( " how to kill " , " murder a real " , " bomb attack " , " dismemberment " , " torture gore " , " beheading gore " , " 如何杀害 " , " 现实伤害威胁 " , " 炸弹袭击 " , " 肢解 " , " 酷刑血腥 " , " 斩首血腥 " )
ADULT_TERMS = ( " nsfw " , " nude " , " nudity " , " explicit sexual " , " erotic " , " lingerie " , " 裸露 " , " 裸体 " , " 裸像 " , " 色情 " , " 成人内容 " , " 情趣内衣 " )
ADULT_AGE_TERMS = ( " adult " , " 18+ " , " over 18 " , " 成年 " , " 成年人 " )
MINOR_TERMS = ( " minor " , " underage " , " child " , " kid " , " schoolgirl " , " schoolboy " , " 幼女 " , " 幼童 " , " 未成年 " , " 儿童 " , " 小学生 " , " 初中生 " )
OTHER_PROHIBITED_TERMS = ( " sexual assault " , " rape scene " , " non-consensual explicit " , " 性侵 " , " 强奸场景 " , " 非自愿色情 " )
SENSITIVE_TERMS = ( " blood " , " weapon " , " swimsuit " , " medical " , " 内衣写真 " , " 泳装 " , " 武器 " , " 少量血迹 " )
def _stricter_decision ( left : PromptModerationDecision , right : PromptModerationDecision | None ) - > PromptModerationDecision :
if right is None :
return left
return right if RISK_PRIORITY [ right . level ] > RISK_PRIORITY [ left . level ] else left
def _decision ( level : str , confidence : float , categories : list [ str ] , reasons : list [ str ] , action : str , warning : str | None ) - > PromptModerationDecision :
return PromptModerationDecision ( level , confidence , categories , reasons , action , warning , PromptModerationService . RULES_VERSION , None , _utc_now ( ) )
def _action_for_level ( level : str ) - > str :
return { " safe " : " allow " , " sensitive " : " allow " , " adult_allowed " : " route_nsfw " , " uncertain " : " confirm_or_reject " , " violence_prohibited " : " reject_warn " , " terror_prohibited " : " reject_warn " , " prohibited " : " reject " } [ level ]
def _contains_any ( text : str , terms : tuple [ str , . . . ] ) - > bool :
lowered = text . casefold ( )
return any ( term . casefold ( ) in lowered for term in terms )
def _is_english_only ( value : str ) - > bool :
return not bool ( re . search ( r " [ \ u3400- \ u9fff] " , value ) )
def _restore_locked_terms ( original : str , translated : str , locked_terms : list [ str ] ) - > str :
result = translated
for term in locked_terms :
text = _text ( term )
if text and text in original and text not in result :
result = f " { result } , { text } "
return result
def _budget_text ( value : str , budget : int , locked_terms : list [ str ] ) - > str :
parts = _split_prompt ( value )
locked = { _text ( item ) . casefold ( ) for item in locked_terms }
while len ( " , " . join ( parts ) ) > budget and parts :
removable = next ( ( index for index in range ( len ( parts ) - 1 , - 1 , - 1 ) if parts [ index ] . casefold ( ) not in locked ) , None )
if removable is None :
break
parts . pop ( removable )
return " , " . join ( parts )
def _difference_summary ( original : str , translated : str ) - > list [ str ] :
summary = [ " language: source -> English " ] if not _is_english_only ( original ) and _is_english_only ( translated ) else [ ]
if len ( translated ) > len ( original ) * 1.5 :
summary . append ( " structured visual details expanded " )
return summary
def _split_prompt ( value : Any ) - > list [ str ] :
return [ part . strip ( ) for part in _text ( value ) . replace ( " ; " , " , " ) . split ( " , " ) if part . strip ( ) ]
def _string_list ( value : Any ) - > list [ str ] :
if isinstance ( value , str ) :
return _split_prompt ( value )
if not isinstance ( value , ( list , tuple , set ) ) :
return [ ]
return [ _text ( item ) for item in value if _text ( item ) ]
def _bounded_float ( value : Any , default : float ) - > float :
try :
return min ( max ( float ( value ) , 0.0 ) , 1.0 )
except ( TypeError , ValueError ) :
return default
def _redact ( value : str ) - > str :
text = re . sub ( r " (?i)bearer \ s+ \ S+ " , " Bearer [REDACTED] " , value )
return re . sub ( r " \ bsk-[A-Za-z0-9_-] { 8,} \ b " , " [REDACTED] " , text )
def _optional_text ( value : Any ) - > str | None :
text = _text ( value )
return text or None
def _text ( value : Any ) - > str :
return str ( value or " " ) . strip ( )
def _utc_now ( ) - > str :
return datetime . now ( timezone . utc ) . isoformat ( )