2026-07-05 10:07:12 +08:00
""" Safe API discovery and render-plan validation. """
from __future__ import annotations
2026-07-11 21:50:34 +08:00
import json
import os
2026-07-12 23:14:55 +08:00
import re
2026-07-11 21:50:34 +08:00
import urllib . error
import urllib . request
2026-07-05 10:07:12 +08:00
from typing import Any
from uuid import uuid4
from backend . dto . common import ApiError , ErrorCode
2026-07-05 15:54:48 +08:00
from core . model_router import SUPPORTED , UNSUPPORTED , route_from_capability_profile , select_model_route
2026-07-12 23:59:14 +08:00
from database . db_helper import load_config_payload
2026-07-05 10:07:12 +08:00
from database . repositories . capability_repository import CapabilityRepository
DIALECTS = [
{
" dialect " : " openai_images " ,
" label " : " OpenAI Images compatible " ,
" capabilities " : [ " text_to_image " , " image_edit " , " mask_edit " ] ,
} ,
{
" dialect " : " comfyui " ,
" label " : " ComfyUI workflow " ,
" capabilities " : [ " text_to_image " , " workflow_graph " ] ,
} ,
{
" dialect " : " unknown " ,
" label " : " Unconfirmed backend " ,
" capabilities " : [ ] ,
} ,
]
class ApiDiscoveryService :
def __init__ ( self , repository : CapabilityRepository ) :
self . repository = repository
def dialects ( self ) - > list [ dict [ str , Any ] ] :
return DIALECTS
def probe_provider ( self , payload : dict [ str , Any ] ) - > dict [ str , Any ] :
2026-07-12 23:59:14 +08:00
if payload . get ( " use_saved_provider " ) :
payload = _saved_provider_probe_payload ( payload )
2026-07-05 10:07:12 +08:00
provider_id = str ( payload . get ( " provider_id " ) or " " ) . strip ( )
model_id = str ( payload . get ( " model_id " ) or " " ) . strip ( )
if not provider_id :
raise ApiError ( ErrorCode . VALIDATION_FAILED , " provider_id is required " , { " field " : " provider_id " } )
if not model_id :
raise ApiError ( ErrorCode . VALIDATION_FAILED , " model_id is required " , { " field " : " model_id " } )
dialect = str ( payload . get ( " dialect " ) or " unknown " )
2026-07-11 21:50:34 +08:00
live_result = _live_probe ( payload ) if payload . get ( " live_probe " ) else {
" mode " : " safe " ,
" message " : " safe probe recorded metadata only; no external API call was made " ,
}
capabilities = dict ( payload . get ( " capabilities " ) or { } )
if live_result . get ( " models " ) :
capabilities [ " discovered_models " ] = live_result [ " models " ]
if live_result . get ( " supported_sizes " ) :
capabilities [ " supported_sizes " ] = live_result [ " supported_sizes " ]
capabilities [ " max_tested_size " ] = live_result [ " supported_sizes " ] [ - 1 ]
2026-07-05 10:07:12 +08:00
profile = self . repository . upsert_profile (
{
" capability_profile_id " : payload . get ( " capability_profile_id " ) or new_capability_profile_id ( ) ,
" provider_id " : provider_id ,
" model_id " : model_id ,
" dialect " : dialect ,
2026-07-11 21:50:34 +08:00
" status " : " confirmed_supported " if live_result . get ( " connected " ) else " unconfirmed " ,
" capabilities " : capabilities ,
" probe_result " : live_result ,
2026-07-05 10:07:12 +08:00
}
)
return profile
2026-07-05 11:00:49 +08:00
def probe_model ( self , payload : dict [ str , Any ] ) - > dict [ str , Any ] :
profile = self . probe_provider ( payload )
profile [ " probe_result " ] = {
* * profile . get ( " probe_result " , { } ) ,
" model_probe " : " safe_metadata_only " ,
}
return self . repository . update_profile (
profile [ " capability_profile_id " ] ,
{ " probe_result " : profile [ " probe_result " ] } ,
) or profile
def manual_override ( self , payload : dict [ str , Any ] ) - > dict [ str , Any ] :
provider_id = str ( payload . get ( " provider_id " ) or " " ) . strip ( )
model_id = str ( payload . get ( " model_id " ) or " " ) . strip ( )
status = str ( payload . get ( " status " ) or " " ) . strip ( )
if status not in { " confirmed_supported " , " confirmed_unsupported " , " unconfirmed " } :
raise ApiError (
ErrorCode . VALIDATION_FAILED ,
" unsupported capability status " ,
{ " field " : " status " } ,
)
profile = self . repository . get_profile ( provider_id , model_id )
if profile is None :
profile = self . repository . upsert_profile (
{
" capability_profile_id " : payload . get ( " capability_profile_id " ) or new_capability_profile_id ( ) ,
" provider_id " : provider_id ,
" model_id " : model_id ,
" dialect " : payload . get ( " dialect " , " unknown " ) ,
" status " : status ,
" capabilities " : payload . get ( " capabilities " ) or { } ,
" probe_result " : { " manual " : True } ,
}
)
return self . repository . update_profile (
profile [ " capability_profile_id " ] ,
{
" status " : status ,
" dialect " : payload . get ( " dialect " , profile [ " dialect " ] ) ,
" capabilities " : payload . get ( " capabilities " , profile [ " capabilities " ] ) ,
" probe_result " : { * * profile . get ( " probe_result " , { } ) , " manual_override " : True } ,
} ,
) or profile
2026-07-05 10:07:12 +08:00
def capabilities ( self ) - > list [ dict [ str , Any ] ] :
return self . repository . list_profiles ( )
def validate_render_plan ( self , payload : dict [ str , Any ] ) - > dict [ str , Any ] :
provider_id = str ( payload . get ( " provider_id " ) or " " ) . strip ( )
model_id = str ( payload . get ( " model_id " ) or " " ) . strip ( )
required = [ str ( item ) for item in payload . get ( " required_capabilities " ) or [ ] ]
profile = self . repository . get_profile ( provider_id , model_id ) if provider_id and model_id else None
if profile is None :
return {
" valid " : False ,
" status " : " unconfirmed " ,
" errors " : [
{
" code " : ErrorCode . MODEL_CAPABILITY_UNCONFIRMED . value ,
" message " : " model capability profile is unconfirmed " ,
}
] ,
" warnings " : [ ] ,
}
2026-07-05 15:54:48 +08:00
route = route_from_capability_profile ( profile )
selection = select_model_route ( [ route ] )
if selection . status != SUPPORTED :
code = (
ErrorCode . MODEL_CAPABILITY_UNSUPPORTED
if selection . status == UNSUPPORTED
else ErrorCode . MODEL_CAPABILITY_UNCONFIRMED
)
2026-07-05 10:07:12 +08:00
return {
" valid " : False ,
2026-07-05 15:54:48 +08:00
" status " : selection . status ,
2026-07-05 10:07:12 +08:00
" errors " : [
{
2026-07-05 15:54:48 +08:00
" code " : code . value ,
" message " : selection . reason or " model capabilities are not confirmed " ,
2026-07-05 10:07:12 +08:00
}
] ,
" warnings " : [ ] ,
" profile " : profile ,
}
2026-07-05 15:54:48 +08:00
missing = [ capability for capability in required if capability not in route . capabilities ]
2026-07-05 10:07:12 +08:00
return {
" valid " : not missing ,
2026-07-05 15:54:48 +08:00
" status " : selection . status ,
2026-07-05 10:07:12 +08:00
" errors " : [
{
" code " : ErrorCode . MODEL_CAPABILITY_UNSUPPORTED . value ,
" message " : " required capability is not supported " ,
" capability " : capability ,
}
for capability in missing
] ,
" warnings " : [ ] ,
" profile " : profile ,
}
def new_capability_profile_id ( ) - > str :
return f " cap_ { uuid4 ( ) . hex } "
2026-07-11 21:50:34 +08:00
2026-07-12 23:59:14 +08:00
def _saved_provider_probe_payload ( payload : dict [ str , Any ] ) - > dict [ str , Any ] :
provider_id = str ( payload . get ( " provider_id " ) or " " ) . strip ( )
config = load_config_payload ( )
generation = config . get ( " generation " ) if isinstance ( config . get ( " generation " ) , dict ) else { }
adapters = generation . get ( " adapters " ) if isinstance ( generation , dict ) else [ ]
saved : dict [ str , Any ] | None = None
if isinstance ( adapters , list ) :
saved = next (
(
dict ( item )
for item in adapters
if isinstance ( item , dict )
and str ( item . get ( " id " ) or item . get ( " provider_id " ) or " " ) . strip ( ) == provider_id
) ,
None ,
)
if saved is None and isinstance ( generation , dict ) :
provider = generation . get ( " provider " )
if isinstance ( provider , dict ) :
candidate_id = str ( provider . get ( " id " ) or provider . get ( " provider_id " ) or " " ) . strip ( )
if not provider_id or candidate_id == provider_id :
saved = dict ( provider )
if saved is None :
raise ApiError (
ErrorCode . VALIDATION_FAILED ,
" saved generation adapter was not found " ,
{ " provider_id " : provider_id } ,
)
return {
* * saved ,
" provider_id " : provider_id or str ( saved . get ( " id " ) or saved . get ( " provider_id " ) or " " ) . strip ( ) ,
" model_id " : str ( saved . get ( " model_id " ) or payload . get ( " model_id " ) or " auto-discovery " ) ,
" dialect " : payload . get ( " dialect " ) or " openai_images " ,
" live_probe " : True ,
" allow_lightweight_test " : bool ( payload . get ( " allow_lightweight_test " ) ) ,
" use_saved_provider " : True ,
}
2026-07-11 21:50:34 +08:00
def _live_probe ( payload : dict [ str , Any ] ) - > dict [ str , Any ] :
base_url = str ( payload . get ( " base_url " ) or " " ) . strip ( ) . rstrip ( " / " )
if not base_url . startswith ( ( " http:// " , " https:// " ) ) :
raise ApiError ( ErrorCode . VALIDATION_FAILED , " valid base_url is required " , { " field " : " base_url " } )
timeout = min ( max ( int ( payload . get ( " timeout_seconds " ) or 20 ) , 3 ) , 60 )
env_name = str ( payload . get ( " api_key_env_var " ) or " " ) . strip ( )
2026-07-12 23:59:14 +08:00
literal_api_key = str ( payload . get ( " api_key_plaintext " ) or payload . get ( " api_key " ) or " " ) . strip ( )
2026-07-12 23:14:55 +08:00
api_key = literal_api_key or ( os . getenv ( env_name , " " ) if env_name else " " )
custom_headers = payload . get ( " custom_headers " )
custom_headers = custom_headers if isinstance ( custom_headers , dict ) else { }
headers = {
" Accept " : " application/json " ,
* * { str ( key ) : str ( value ) for key , value in custom_headers . items ( ) } ,
* * ( { " Authorization " : f " Bearer { api_key } " } if api_key else { } ) ,
}
result : dict [ str , Any ] = {
" mode " : " live " ,
" connected " : False ,
" models " : [ ] ,
" supported_sizes " : [ ] ,
" warnings " : [ ] ,
" auth_source " : " request " if literal_api_key else " environment " if env_name else " none " ,
}
2026-07-11 21:50:34 +08:00
api_prefix = base_url if base_url . lower ( ) . endswith ( " /v1 " ) else f " { base_url } /v1 "
models_url = f " { api_prefix } /models "
result [ " resolved_api_base " ] = api_prefix
result [ " image_endpoint " ] = " /images/generations " if base_url . lower ( ) . endswith ( " /v1 " ) else " /v1/images/generations "
try :
request = urllib . request . Request ( models_url , headers = headers , method = " GET " )
with urllib . request . urlopen ( request , timeout = timeout ) as response :
body = response . read ( 2 * 1024 * 1024 ) . decode ( " utf-8-sig " )
parsed = json . loads ( body )
items = parsed . get ( " data " , [ ] ) if isinstance ( parsed , dict ) else [ ]
result [ " models " ] = [ str ( item . get ( " id " ) ) for item in items if isinstance ( item , dict ) and item . get ( " id " ) ] [ : 200 ]
result [ " connected " ] = True
result [ " http_status " ] = response . status
except urllib . error . HTTPError as exc :
2026-07-12 23:14:55 +08:00
try :
error_body = exc . read ( 4096 ) . decode ( " utf-8-sig " , errors = " replace " )
except Exception :
error_body = " "
result . update (
{
" http_status " : exc . code ,
" error " : f " models endpoint returned HTTP { exc . code } " ,
" error_body " : _redact_probe_error ( error_body [ : 500 ] ) ,
}
)
2026-07-11 21:50:34 +08:00
except ( urllib . error . URLError , TimeoutError , json . JSONDecodeError , UnicodeDecodeError ) as exc :
result [ " error " ] = str ( exc )
if payload . get ( " allow_lightweight_test " ) and result [ " connected " ] :
endpoint = str ( payload . get ( " image_endpoint " ) or result [ " image_endpoint " ] )
if base_url . lower ( ) . endswith ( " /v1 " ) and endpoint . lower ( ) . startswith ( " /v1/ " ) :
endpoint = endpoint [ 3 : ]
endpoint_url = f " { base_url } { endpoint if endpoint . startswith ( ' / ' ) else ' / ' + endpoint } "
model_id = str ( payload . get ( " model_id " ) or " " ) . strip ( )
for size in ( " 1920x1080 " , " 2560x1440 " , " 3840x2160 " ) :
data = json . dumps ( { " model " : model_id , " prompt " : " A plain gray circle on white background, capability test " , " size " : size , " n " : 1 , " response_format " : " b64_json " } ) . encode ( " utf-8 " )
request = urllib . request . Request ( endpoint_url , data = data , headers = { * * headers , " Content-Type " : " application/json " } , method = " POST " )
try :
with urllib . request . urlopen ( request , timeout = timeout ) as response :
response . read ( 1024 )
result [ " supported_sizes " ] . append ( size )
except Exception as exc : # Provider dialects expose inconsistent errors; retain a short diagnostic only.
result [ " warnings " ] . append ( { " size " : size , " message " : str ( exc ) [ : 180 ] } )
return result
2026-07-12 23:14:55 +08:00
def _redact_probe_error ( value : str ) - > str :
redacted = re . sub ( r " (?i)bearer \ s+[a-z0-9._-]+ " , " Bearer *** " , value )
return re . sub ( r " (?i)sk[-_][a-z0-9._-] { 8,} " , " sk-*** " , redacted )