feat(classifier): optional GigaChat-2-Lite hybrid tier classify

LLM classify via LiteLLM gigachat-classifier when heuristic confidence
is low. CLASSIFIER_MODE=heuristic|hybrid|llm. Metrics classifier_source.

router/classifier_llm.py

@@ -0,0 +1,126 @@
+"""Optional LLM tier classifier via LiteLLM (GigaChat-2-Lite)."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+from typing import Any
+
+import httpx
+
+from rules_loader import load_orchestration
+
+log = logging.getLogger("classifier_llm")
+
+TEXT_TIERS = frozenset(
+    {"SIMPLE", "MEDIUM_OPS", "MEDIUM_CODE", "COMPLEX", "REASONING"},
+)
+
+CLASSIFY_SYSTEM = """You classify coding-assistant requests into exactly one tier.
+Reply with ONLY valid JSON, no markdown:
+{"tier":"SIMPLE|MEDIUM_OPS|MEDIUM_CODE|COMPLEX|REASONING","confidence":0.0-1.0}
+
+SIMPLE — greetings, definitions, short questions
+MEDIUM_OPS — bash, docker, devops, infrastructure
+MEDIUM_CODE — write/refactor code, functions, bugs
+COMPLEX — architecture, migrations, system design
+REASONING — step-by-step proof, deep analysis"""
+
+
+class LlmClassifier:
+    def __init__(self) -> None:
+        orch = load_orchestration()
+        clf = orch.get("classifier", {})
+        self.mode = os.environ.get("CLASSIFIER_MODE", clf.get("mode", "hybrid")).lower()
+        self.model = os.environ.get(
+            "CLASSIFIER_LLM_MODEL",
+            clf.get("llm_model", "gigachat-classifier"),
+        )
+        self.low_conf = float(clf.get("low_confidence_threshold", 0.6))
+        self.litellm_url = os.environ.get("LITELLM_INTERNAL_URL", "http://litellm:4000").rstrip("/")
+        self.litellm_key = os.environ.get("LITELLM_MASTER_KEY", "")
+        self.timeout = float(clf.get("timeout_sec", 15))
+        self.max_tokens = int(clf.get("max_tokens", 64))
+        self.enabled = self.mode in ("hybrid", "llm") and bool(self.litellm_key)
+
+    def should_use_llm(self, tier_value: str, confidence: float, has_image: bool) -> bool:
+        if not self.enabled or has_image:
+            return False
+        if tier_value.startswith("VISION"):
+            return False
+        if self.mode == "llm":
+            return True
+        if self.mode == "hybrid":
+            return confidence < self.low_conf
+        return False
+
+    @staticmethod
+    def _parse_json(content: str) -> dict[str, Any] | None:
+        text = content.strip()
+        fence = re.search(r"```(?:json)?\s*([\s\S]*?)```", text)
+        if fence:
+            text = fence.group(1).strip()
+        try:
+            data = json.loads(text)
+            return data if isinstance(data, dict) else None
+        except json.JSONDecodeError:
+            match = re.search(r"\{[\s\S]*\}", text)
+            if not match:
+                return None
+            try:
+                data = json.loads(match.group(0))
+                return data if isinstance(data, dict) else None
+            except json.JSONDecodeError:
+                return None
+
+    async def classify(self, text: str) -> tuple[str, float] | None:
+        snippet = text.strip()[:4000]
+        if not snippet:
+            return None
+
+        payload = {
+            "model": self.model,
+            "max_tokens": self.max_tokens,
+            "temperature": 0,
+            "messages": [
+                {"role": "system", "content": CLASSIFY_SYSTEM},
+                {"role": "user", "content": snippet},
+            ],
+        }
+        headers = {
+            "Authorization": f"Bearer {self.litellm_key}",
+            "Content-Type": "application/json",
+        }
+
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout) as client:
+                resp = await client.post(
+                    f"{self.litellm_url}/v1/chat/completions",
+                    headers=headers,
+                    json=payload,
+                )
+            if resp.status_code >= 400:
+                log.warning("LLM classify HTTP %s: %s", resp.status_code, resp.text[:200])
+                return None
+            data = resp.json()
+            content = (
+                data.get("choices", [{}])[0]
+                .get("message", {})
+                .get("content", "")
+            )
+            parsed = self._parse_json(content)
+            if not parsed:
+                log.warning("LLM classify: invalid JSON in response: %s", content[:120])
+                return None
+            tier_raw = str(parsed.get("tier", "")).upper().replace("-", "_")
+            if tier_raw not in TEXT_TIERS:
+                log.warning("LLM classify: unknown tier %s", tier_raw)
+                return None
+            confidence = float(parsed.get("confidence", 0.75))
+            confidence = max(0.0, min(1.0, confidence))
+            return tier_raw, confidence
+        except Exception as exc:  # noqa: BLE001
+            log.warning("LLM classify failed: %s", exc)
+            return None

router/metrics.py

@@ -19,6 +19,11 @@ CLASSIFY = Counter(
     "Classification results",
     ["tier"],
 )
+CLASSIFY_LLM = Counter(
+    "ai_router_classify_llm_total",
+    "LLM classifier invocations (GigaChat)",
+    ["tier", "status"],
+)
 DURATION = Histogram(
     "ai_router_request_duration_seconds",
     "Request duration",

router/orchestrator.py

@@ -11,6 +11,7 @@ from dataclasses import dataclass, field
 from enum import Enum
 from typing import Any
 
+from classifier_llm import LlmClassifier
 from rules_loader import load_model_matrix, load_orchestration, load_routing_rules
 
 log = logging.getLogger("orchestrator")
@@ -54,6 +55,7 @@ class RouteDecision:
     escalation_level: int
     confidence: float
     delegated_internal: bool = False
+    classifier_source: str = "heuristic"
 
 
 class SessionStore:
@@ -172,6 +174,7 @@ class Orchestrator:
     def __init__(self, session_store: SessionStore) -> None:
         self.sessions = session_store
         self.classifier = Classifier()
+        self.llm_classifier = LlmClassifier()
         self._orch = load_orchestration()
         self._matrix = load_model_matrix()
         self._models: dict[str, dict] = self._matrix.get("models", {})
@@ -217,7 +220,7 @@ class Orchestrator:
         suffix = TIER_SUFFIX[tier]
         return f"{prefix}-{suffix}"
 
-    def resolve(
+    async def resolve(
         self,
         messages: list[dict[str, Any]],
         *,
@@ -229,6 +232,17 @@ class Orchestrator:
     ) -> RouteDecision:
         mode = quality_mode or self.default_quality
         tier, confidence = self.classifier.classify(messages, has_image=has_image, text=text)
+        classifier_source = "heuristic"
+
+        if self.llm_classifier.should_use_llm(tier.value, confidence, has_image):
+            llm_result = await self.llm_classifier.classify(text)
+            if llm_result:
+                tier = Tier(llm_result[0])
+                confidence = llm_result[1]
+                classifier_source = "gigachat"
+            elif self.llm_classifier.mode == "llm":
+                classifier_source = "heuristic_fallback"
+
         ctx = self.sessions.get(session_id)
         prompt_hash = hashlib.sha256(text.encode()).hexdigest()[:16]
 
@@ -263,11 +277,13 @@ class Orchestrator:
                 escalation_level=escalation,
                 confidence=confidence,
                 delegated_internal=True,
+                classifier_source=classifier_source,
             )
 
-        delegated = confidence < self.classifier._low_conf and tier in (
-            Tier.MEDIUM_OPS,
-            Tier.SIMPLE,
+        delegated = (
+            classifier_source == "heuristic"
+            and confidence < self.classifier._low_conf
+            and tier in (Tier.MEDIUM_OPS, Tier.SIMPLE)
         )
 
         return RouteDecision(
@@ -278,6 +294,7 @@ class Orchestrator:
             escalation_level=escalation,
             confidence=confidence,
             delegated_internal=delegated,
+            classifier_source=classifier_source,
         )
 
     def after_request(

router/router.py

@@ -15,7 +15,7 @@ import httpx
 from fastapi import FastAPI, Header, HTTPException, Request, Response
 from fastapi.responses import JSONResponse, StreamingResponse
 
-from metrics import CLASSIFY, DURATION, ESCALATIONS, REQUESTS, metrics_payload
+from metrics import CLASSIFY, CLASSIFY_LLM, DURATION, ESCALATIONS, REQUESTS, metrics_payload
 from orchestrator import Orchestrator, SessionStore, Tier
 from rules_loader import reload_configs
 
@@ -104,6 +104,7 @@ def _router_meta(decision, *, requested: str) -> dict[str, Any]:
         "confidence": round(decision.confidence, 3),
         "requested_model": requested,
         "delegated_internal": decision.delegated_internal,
+        "classifier_source": decision.classifier_source,
     }
 
 
@@ -150,7 +151,7 @@ async def classify_debug(
     body = await request.json()
     messages = body.get("messages") or []
     text = _extract_text(messages)
-    decision = orchestrator.resolve(
+    decision = await orchestrator.resolve(
         messages,
         quality_mode=_quality_mode(x_ai_quality, body),
         session_id=_session_id(body),
@@ -159,6 +160,8 @@ async def classify_debug(
         token_estimate=_estimate_tokens(text),
     )
     CLASSIFY.labels(tier=decision.tier.value).inc()
+    if decision.classifier_source == "gigachat":
+        CLASSIFY_LLM.labels(tier=decision.tier.value, status="ok").inc()
     return {
         "tier": decision.tier.value,
         "lane": decision.lane,
@@ -243,7 +246,7 @@ async def chat_completions(
 
     requested_model = body.get("model", DEFAULT_MODEL)
     if requested_model in ("smart-router", "auto", ""):
-        decision = orchestrator.resolve(
+        decision = await orchestrator.resolve(
             messages,
             quality_mode=_quality_mode(x_ai_quality, body),
             session_id=session_id,
@@ -251,6 +254,8 @@ async def chat_completions(
             has_image=has_image,
             token_estimate=_estimate_tokens(text),
         )
+        if decision.classifier_source == "gigachat":
+            CLASSIFY_LLM.labels(tier=decision.tier.value, status="ok").inc()
         target_model = decision.model
         meta = _router_meta(decision, requested=requested_model)
     else: