refactor(agent/agent_init): wip checkpoint — phase-helper split of init, param tables, header factory table, compression parse helpers; mixin compaction

agent/backend_identity.py

@@ -1,27 +1,11 @@
 """Single owner for backend identity and failure-scoped skip decisions.
 
-Every fallback / dedup / skip / quarantine decision asks one question: **"is
-this candidate the same backend as the one that failed, along the axis that
-failure invalidated?"** Answering it inline at each call site (comparing
-whatever string was locally convenient) repeatedly reintroduced the same bugs:
-same-shim aliases treated as distinct, sibling models skipped for one model's
-timeout, dedup ignoring ``base_url`` and stranding multi-endpoint pools.
-
-"provider" conflates three independent identity axes, each invalidated by a
-different failure class:
-
-* **credential surface** — auth 401 / payment 402 kill everything sharing the
-  credential (every model, every host reached with that key/token).
-* **endpoint** — DNS failure / connection refused kill everything behind the
-  URL, regardless of model or credential.
-* **model deployment** — timeout / overload / rate limit / model-incompatible
-  kill ONE model's deployment. A sibling model behind the same URL is an
-  independent deployment (one model hung while another on the identical
-  endpoint kept serving).
-
-Call sites build :class:`BackendIdentity` values and ask
-:func:`should_skip_candidate`. Do not re-implement any comparison inline —
-extend THIS module instead.
+Every fallback / dedup / skip / quarantine decision asks: "is this candidate the same backend
+as the one that failed, along the axis that failure invalidated?" Answering inline at each
+call site kept reintroducing the same bugs (same-shim aliases treated as distinct, sibling
+models skipped for one model's timeout, dedup ignoring ``base_url``). "provider" conflates
+three axes — credential surface (401/402), endpoint (DNS/refused), model deployment
+(timeout/overload/429). Build :class:`BackendIdentity` values, ask :func:`should_skip_candidate`.
 """
 
 from __future__ import annotations
@@ -37,8 +21,8 @@ logger = logging.getLogger(__name__)
 class FailureScope(Enum):
     """Which identity axis a failure invalidates."""
 
-    #: Timeout, overload/429, connection blip, model-incompatible, invalid
-    #: response: evidence against ONE model deployment only.
+    #: Timeout, overload/429, connection blip, model-incompatible, invalid response:
+    #: evidence against ONE model deployment only.
     MODEL = "model"
     #: Auth 401 / payment 402: evidence against the shared credential.
     CREDENTIAL = "credential"
@@ -54,8 +38,8 @@ def _norm(value: Optional[str]) -> str:
 class BackendIdentity:
     """Normalized identity of one (provider, model, endpoint) deployment.
 
-    Empty fields mean "unknown" — an unknown axis can neither prove sameness
-    nor difference on its own; the remaining axes decide."""
+    Empty fields mean "unknown" — an unknown axis can neither prove sameness nor difference
+    on its own; the remaining axes decide."""
 
     provider: str = ""
     model: str = ""
@@ -63,25 +47,20 @@ class BackendIdentity:
 
     @classmethod
     def build(
-        cls,
-        provider: Optional[str] = None,
-        model: Optional[str] = None,
+        cls, provider: Optional[str] = None, model: Optional[str] = None,
         base_url: Optional[str] = None,
     ) -> "BackendIdentity":
         return cls(
-            provider=_norm(provider),
-            model=_norm(model),
-            base_url=_norm(base_url).rstrip("/"),
+            provider=_norm(provider), model=_norm(model), base_url=_norm(base_url).rstrip("/"),
         )
 
 
 def _both_first_class(a: BackendIdentity, b: BackendIdentity) -> bool:
     """True when both providers are distinct registered first-class providers.
 
-    Two different registry providers have distinct credential surfaces even
-    when they share an inference host (xai-oauth vs xai, openai-codex vs
-    openai-api). Custom/shim aliases are NOT in the registry, so two aliases
-    pointing at one URL still count as the same backend."""
+    Two different registry providers have distinct credential surfaces even when they share an
+    inference host (xai-oauth vs xai). Custom/shim aliases are NOT in the registry, so two
+    aliases pointing at one URL still count as the same backend."""
     if not a.provider or not b.provider or a.provider == b.provider:
         return False
     try:
@@ -95,11 +74,9 @@ def _both_first_class(a: BackendIdentity, b: BackendIdentity) -> bool:
 def same_credential_surface(a: BackendIdentity, b: BackendIdentity) -> bool:
     """Do two identities share the credential a 401/402 just invalidated?
 
-    Conservative on purpose: an unprovable axis answers "different" (one wasted
-    RTT) rather than "same" (stranded failover). Same label = same configured
-    credential; different labels = different credential config (custom entries
-    can each carry their own api_key, so a shared URL alone never proves a
-    shared credential — it is only a weak signal when a label is missing)."""
+    Conservative: an unprovable axis answers "different" (one wasted RTT) rather than "same"
+    (stranded failover). Same label = same configured credential; custom entries can each carry
+    their own api_key, so a shared URL alone is only a weak signal when a label is missing."""
     if a.provider and b.provider:
         return a.provider == b.provider
     return bool(a.base_url and a.base_url == b.base_url)
@@ -107,8 +84,7 @@ def same_credential_surface(a: BackendIdentity, b: BackendIdentity) -> bool:
 
 def same_endpoint(a: BackendIdentity, b: BackendIdentity) -> bool:
     """Do two identities sit behind the endpoint that just went unreachable?
-    An unknown base_url inherits the provider default, so a shared provider
-    label implies the same default endpoint."""
+    An unknown base_url inherits the provider default, so a shared label implies the same endpoint."""
     if a.base_url and b.base_url:
         return a.base_url == b.base_url
     return bool(a.provider and a.provider == b.provider)
@@ -117,11 +93,10 @@ def same_endpoint(a: BackendIdentity, b: BackendIdentity) -> bool:
 def same_deployment(a: BackendIdentity, b: BackendIdentity) -> bool:
     """Are these the exact same model deployment (the thing a timeout kills)?
 
-    Provider+model must match; base_url distinguishes only when BOTH sides carry
-    an explicit URL (same provider+model on two explicit URLs is a pool, not a
-    dup). Different labels with the same URL + model are still one deployment
-    (same-host shim aliases) — unless both labels are first-class registry
-    providers."""
+    Provider+model must match; base_url distinguishes only when BOTH sides carry an explicit URL
+    (same provider+model on two explicit URLs is a pool, not a dup). Different labels with the
+    same URL + model are still one deployment (same-host shim aliases) — unless both labels are
+    first-class registry providers."""
     if not (a.provider and b.provider and a.provider == b.provider):
         return bool(
             a.base_url
@@ -135,16 +110,16 @@ def same_deployment(a: BackendIdentity, b: BackendIdentity) -> bool:
     return not (a.base_url and b.base_url and a.base_url != b.base_url)
 
 
+_SCOPE_PREDICATES = {
+    FailureScope.CREDENTIAL: same_credential_surface, FailureScope.ENDPOINT: same_endpoint,
+    FailureScope.MODEL: same_deployment,
+}
+
+
 def should_skip_candidate(
-    candidate: BackendIdentity,
-    failed: BackendIdentity,
-    scope: FailureScope = FailureScope.MODEL,
+    candidate: BackendIdentity, failed: BackendIdentity, scope: FailureScope = FailureScope.MODEL
 ) -> bool:
     """THE skip predicate: would trying ``candidate`` just repeat the failure?
-    True when it is the same backend as ``failed`` along the axis ``scope``
-    invalidated. Every fallback/dedup/skip site must call this."""
-    if scope is FailureScope.CREDENTIAL:
-        return same_credential_surface(candidate, failed)
-    if scope is FailureScope.ENDPOINT:
-        return same_endpoint(candidate, failed)
-    return same_deployment(candidate, failed)
+    True when it is the same backend as ``failed`` along the axis ``scope`` invalidated.
+    Every fallback/dedup/skip site must call this."""
+    return _SCOPE_PREDICATES.get(scope, same_deployment)(candidate, failed)