1- """Pinned model roles for the knowledge service, with no silent fallback.
1+ """Pinned model roles with an explicitly configured generator fallback.
22
33The generator drafts knowledge changes; the judge (a different model family)
44grades them. Both are pinned by (provider, model, reasoning effort) and
5- recorded on every call. An unavailable backend, a timeout, a call stopped
6- at its spend cap or an unparseable reply raises ``ModelUnavailable``; the caller leaves the work queued. It never
7- switches to a weaker model: a verdict must always say which model made it.
5+ recorded on every call. ``KB_GENERATOR_FALLBACK`` may name one pinned model
6+ to try when generation is unavailable. Judges never fall back, and schema
7+ repair and spend limits retain their existing behavior. If both generators
8+ are unavailable, the caller leaves the work queued.
89"""
910
1011from __future__ import annotations
1112
1213import json
14+ import logging
1315import os
1416import re
1517import time
16- from dataclasses import dataclass
18+ from dataclasses import dataclass , replace
1719from typing import Any , Callable
1820
1921GENERATOR_ENV = "KB_GENERATOR" # "provider:model[:effort]"
22+ GENERATOR_FALLBACK_ENV = "KB_GENERATOR_FALLBACK"
2023JUDGE_ENV = "KB_JUDGE"
2124DEFAULT_GENERATOR = "claude-code:claude-opus-5-5"
2225DEFAULT_JUDGE = "codex:gpt-6-sol:medium"
2326_JSON_FENCE = re .compile (r"```(?:json)?\s*(\{.*\})\s*```" , re .DOTALL )
27+ logger = logging .getLogger (__name__ )
2428
2529
2630class ModelUnavailable (RuntimeError ):
2731 """The pinned backend could not produce a usable reply; work stays queued."""
2832
33+ def __init__ (self , message : str , * , allow_fallback : bool = True ):
34+ super ().__init__ (message )
35+ self .allow_fallback = allow_fallback
36+
2937
3038@dataclass (frozen = True )
3139class ModelRole :
3240 name : str
3341 provider : str
3442 model : str
3543 effort : str = ""
44+ fallback : ModelRole | None = None
3645
3746 @classmethod
3847 def parse (cls , name : str , spec : str ) -> "ModelRole" :
@@ -48,8 +57,16 @@ def label(self) -> str:
4857def roles_from_env () -> tuple [ModelRole , ModelRole ]:
4958 generator = ModelRole .parse ("generator" , os .environ .get (GENERATOR_ENV , DEFAULT_GENERATOR ))
5059 judge = ModelRole .parse ("judge" , os .environ .get (JUDGE_ENV , DEFAULT_JUDGE ))
51- if generator .provider == judge .provider and generator .model .split ("-" )[0 ] == judge .model .split ("-" )[0 ]:
52- raise ValueError ("the judge must come from a different model family than the generator" )
60+ fallback_spec = os .environ .get (GENERATOR_FALLBACK_ENV , "" ).strip ()
61+ if fallback_spec :
62+ fallback = ModelRole .parse ("generator" , fallback_spec )
63+ if fallback .label ().casefold () == generator .label ().casefold ():
64+ raise ValueError ("the generator fallback must differ from the primary generator" )
65+ generator = replace (generator , fallback = fallback )
66+ for candidate in (generator , generator .fallback ):
67+ if candidate is not None and candidate .provider == judge .provider \
68+ and candidate .model .casefold ().split ("-" )[0 ] == judge .model .casefold ().split ("-" )[0 ]:
69+ raise ValueError ("the judge must come from a different model family than every generator" )
5370 return generator , judge
5471
5572
@@ -108,27 +125,56 @@ def _transport(self, provider: str):
108125 def call_json (self , role : ModelRole , * , system : str , prompt : str ,
109126 validate : Callable [[dict ], None ] | None = None ,
110127 max_budget_usd : float | None = None , record_payload : bool = True ) -> ModelReply :
128+ """Try the primary, then one configured generator on unavailability.
129+
130+ Both attempts use the same validation and payload policy. Calls with
131+ a spend threshold and schema errors never trigger a second model call:
132+ the caller has reserved for one model, and Zcode cannot enforce a cap.
133+ """
134+ kwargs = dict (system = system , prompt = prompt , validate = validate ,
135+ max_budget_usd = max_budget_usd , record_payload = record_payload )
136+ try :
137+ return self ._call_json (role , ** kwargs )
138+ except ModelUnavailable as primary_error :
139+ if role .name != "generator" or role .fallback is None \
140+ or max_budget_usd is not None or not primary_error .allow_fallback :
141+ raise
142+ logger .warning ("Knowledge generator %s unavailable; trying configured fallback %s" ,
143+ role .label (), role .fallback .label ())
144+ try :
145+ return self ._call_json (role .fallback , fallback_from = role .label (), ** kwargs )
146+ except ModelUnavailable as fallback_error :
147+ raise ModelUnavailable (
148+ f"{ role .label ()} { primary_error }
149+ f"fallback { role .fallback .label ()} { fallback_error } ,
150+ allow_fallback = False ) from fallback_error
151+
152+ def _call_json (self , role : ModelRole , * , system : str , prompt : str ,
153+ validate : Callable [[dict ], None ] | None = None ,
154+ max_budget_usd : float | None = None , record_payload : bool = True ,
155+ fallback_from : str = "" ) -> ModelReply :
111156 """``max_budget_usd`` is a per-call STOP THRESHOLD, not a hard cap:
112157 the transport starts no further API request once the call's spend
113158 reaches it, but the request that crosses it is billed in full. A
114159 caller enforcing a hard ceiling must reserve the threshold plus one
115160 request's worst case before calling. Requesting a threshold from a
116161 transport that cannot stop at one (``stops_at_spend`` False) is
117162 refused before dispatch; it is never approximated with ``max_tokens``."""
118- transport = self ._subscription_transports .pop (role .label (), None )
119- if transport is None :
120- transport = self ._transport (role .provider )
121- cap : dict = {}
122- if max_budget_usd is not None :
123- if not max_budget_usd > 0 :
124- raise ModelUnavailable (f"{ role .label ()} )
125- if not getattr (transport , "stops_at_spend" , False ):
126- raise ModelUnavailable (f"{ role .provider } )
127- cap = {"max_budget_usd" : max_budget_usd }
128163 started = time .time ()
129164 identity = {"role" : role .name , "requested" : role .label (), "provider" : role .provider ,
130- "model" : role .model , "effort" : role .effort }
165+ "model" : role .model , "effort" : role .effort , "fallback_from" : fallback_from }
131166 try :
167+ transport = self ._subscription_transports .pop (role .label (), None )
168+ if transport is None :
169+ transport = self ._transport (role .provider )
170+ cap : dict = {}
171+ if max_budget_usd is not None :
172+ if not max_budget_usd > 0 :
173+ raise ModelUnavailable (f"{ role .label ()} , allow_fallback = False )
174+ if not getattr (transport , "stops_at_spend" , False ):
175+ raise ModelUnavailable (f"{ role .provider } ,
176+ allow_fallback = False )
177+ cap = {"max_budget_usd" : max_budget_usd }
132178 reply = transport .complete (
133179 system = system , messages = [{"role" : "user" , "content" : prompt }],
134180 model = role .model , effort = role .effort , role = role .name , ** cap )
@@ -140,6 +186,8 @@ def call_json(self, role: ModelRole, *, system: str, prompt: str,
140186 "system" : system if record_payload else "" ,
141187 "prompt" : prompt if record_payload else "" , "reply" : "" ,
142188 "error" : str (exc )[:2000 ] if record_payload else "transport failed (payload omitted)" })
189+ if isinstance (exc , ModelUnavailable ):
190+ raise
143191 raise ModelUnavailable (f"{ role .label ()} { exc } ) from exc
144192 seconds = time .time () - started
145193 text = "" .join (getattr (block , "text" , "" ) or "" for block in getattr (reply , "blocks" , []))
@@ -160,7 +208,8 @@ def call_json(self, role: ModelRole, *, system: str, prompt: str,
160208 failure : ModelUnavailable | None = None
161209 data : dict = {}
162210 if getattr (reply , "stop_reason" , "" ) == "max_budget" :
163- failure = ModelUnavailable (f"{ role .label ()} { max_budget_usd } )
211+ failure = ModelUnavailable (f"{ role .label ()} { max_budget_usd } ,
212+ allow_fallback = False )
164213 elif getattr (reply , "stop_reason" , "" ) == "max_tokens" or not text .strip ():
165214 failure = ModelUnavailable (f"{ role .label ()} )
166215 else :
@@ -170,7 +219,8 @@ def call_json(self, role: ModelRole, *, system: str, prompt: str,
170219 try :
171220 validate (data )
172221 except Exception as exc : # any malformed shape is a controlled refusal
173- raise ModelUnavailable (f"{ role .label ()} { exc !r} ) from exc
222+ raise ModelUnavailable (f"{ role .label ()} { exc !r} ,
223+ allow_fallback = False ) from exc
174224 except ModelUnavailable as exc :
175225 failure = exc
176226 if self ._recorder is not None :
0 commit comments