@ngocsangairvds/vsaf 3.2.13 → 3.2.15

package/tools/vds-scripts/audit_orchestrator/src/vds_audit_orchestrator/dspy_modules/runtime.py

@@ -1,836 +0,0 @@
-"""Runtime loader abstractions for optional DSPy evaluation backend."""
-
-from __future__ import annotations
-
-import asyncio
-import importlib
-import json
-import os
-from collections.abc import Callable
-from dataclasses import dataclass
-from pathlib import Path
-from typing import TYPE_CHECKING, Any, Protocol
-from urllib.parse import urlparse
-
-import structlog
-from vds_platform_core.credentials import resolve_secret
-
-from vds_audit_orchestrator.config import LLMConfig, get_config
-from vds_audit_orchestrator.dspy_modules.modules import DSPyRowEvaluationModule
-from vds_audit_orchestrator.dspy_modules.signatures import DSPyRowEvaluationInput
-from vds_audit_orchestrator.llm.provider import normalize_codex_base_url, normalize_openai_base_url
-
-if TYPE_CHECKING:
-    from vds_audit_orchestrator.llm.audit_schemas import RowEvaluationRequest, RowEvaluationResponse
-
-DSPY_RUNTIME_SUPPORTED_PROTOCOLS: frozenset[str] = frozenset({"anthropic", "openai", "gemini", "openai-codex"})
-
-_logger = structlog.get_logger(__name__)
-
-
-class DSPyRuntime(Protocol):
-    """Runtime contract consumed by row evaluator."""
-
-    def evaluate_row(self, request: RowEvaluationRequest) -> RowEvaluationResponse:
-        """Evaluate a row request synchronously."""
-        ...
-
-    async def aevaluate_row(self, request: RowEvaluationRequest) -> RowEvaluationResponse:
-        """Evaluate a row request asynchronously."""
-        ...
-
-
-class DefaultDSPyRuntime:
-    """Default runtime implementation for DSPy backend."""
-
-    def __init__(self, module: DSPyRowEvaluationModule):
-        self._module = module
-
-    def evaluate_row(self, request: RowEvaluationRequest) -> RowEvaluationResponse:
-        payload = DSPyRowEvaluationInput.from_request(request)
-        return self._module.evaluate(payload)
-
-    async def aevaluate_row(self, request: RowEvaluationRequest) -> RowEvaluationResponse:
-        return await asyncio.to_thread(self.evaluate_row, request)
-
-
-@dataclass(frozen=True, slots=True)
-class RuntimeArtifactContract:
-    """Validated optimized artifact contract consumed by runtime."""
-
-    path: Path
-    model: str
-    artifact_version: str
-    optimizer_backend: str
-    rulebook: dict[str, str]
-
-
-def _env_flag(name: str) -> bool:
-    raw = os.getenv(name, "").strip().lower()
-    return raw in {"1", "true", "yes", "on"}
-
-
-def _load_runtime_artifact_contract(model: str) -> RuntimeArtifactContract | None:
-    """Load and validate optimized runtime artifact contract from env."""
-    artifact_path_raw = os.getenv("VDS_AUDIT_DSPY_RUNTIME_ARTIFACT", "").strip()
-    if not artifact_path_raw:
-        return None
-
-    artifact_path = Path(artifact_path_raw).expanduser()
-    if not artifact_path.exists() or not artifact_path.is_file():
-        raise RuntimeError(f"dspy_runtime_artifact_not_found: {artifact_path}")
-
-    try:
-        payload = json.loads(artifact_path.read_text(encoding="utf-8"))
-    except Exception as exc:
-        raise RuntimeError(f"dspy_runtime_artifact_invalid_json: {artifact_path}: {exc}") from exc
-
-    if not isinstance(payload, dict):
-        raise RuntimeError("dspy_runtime_artifact_invalid_payload: expected object")
-
-    kind = str(payload.get("kind") or "").strip()
-    if kind != "audit_judge_optimized":
-        raise RuntimeError(
-            f"dspy_runtime_artifact_invalid_kind: expected 'audit_judge_optimized', got '{kind or 'missing'}'"
-        )
-
-    artifact_version = str(payload.get("artifact_version") or "").strip()
-    if not artifact_version:
-        raise RuntimeError("dspy_runtime_artifact_missing_version")
-
-    artifact_model = str(payload.get("model") or "").strip()
-    if not artifact_model:
-        raise RuntimeError("dspy_runtime_artifact_missing_model")
-    if artifact_model != model:
-        raise RuntimeError(
-            f"dspy_runtime_artifact_model_mismatch: artifact_model='{artifact_model}' runtime_model='{model}'"
-        )
-
-    rulebook_raw = payload.get("rulebook")
-    if not isinstance(rulebook_raw, dict) or not rulebook_raw:
-        raise RuntimeError("dspy_runtime_artifact_missing_rulebook")
-    rulebook: dict[str, str] = {
-        str(key).strip(): str(value).strip().upper()
-        for key, value in rulebook_raw.items()
-        if str(key).strip() and str(value).strip()
-    }
-    if not rulebook:
-        raise RuntimeError("dspy_runtime_artifact_empty_rulebook")
-
-    optimizer_backend = str(payload.get("optimizer_backend") or "").strip() or "unknown"
-    return RuntimeArtifactContract(
-        path=artifact_path,
-        model=artifact_model,
-        artifact_version=artifact_version,
-        optimizer_backend=optimizer_backend,
-        rulebook=rulebook,
-    )
-
-
-def _rulebook_predictor(contract: RuntimeArtifactContract) -> Callable[[DSPyRowEvaluationInput], Any]:
-    """Deterministic predictor backed by validated optimized rulebook artifact."""
-    valid_statuses = {"PASS", "PARTIAL", "FAIL", "ERROR", "N/A"}
-
-    def _predict(payload: DSPyRowEvaluationInput) -> Any:
-        candidates = [
-            payload.requirement_category or "",
-            payload.checklist_main,
-            payload.checklist_rule,
-            "uncategorized",
-        ]
-        mapped_status = "PARTIAL"
-        for key in candidates:
-            if key in contract.rulebook:
-                mapped_status = contract.rulebook[key]
-                break
-        status = mapped_status if mapped_status in valid_statuses else "PARTIAL"
-
-        return {
-            "status": status,
-            "reason_vn": (
-                "Đánh giá theo artifact tối ưu DSPy "
-                f"(v{contract.artifact_version}, backend={contract.optimizer_backend})."
-            ),
-            "finding_vn": (
-                payload.checklist_eval_guide
-                or "Kết quả được suy ra theo rulebook tối ưu; cần bổ sung đối chiếu thủ công khi cần."
-            ),
-            "score": 95 if status == "PASS" else 65 if status == "PARTIAL" else 20 if status == "FAIL" else 0,
-            "confidence": 0.75,
-            "evidence_refs": list(payload.evidence_refs),
-            "evidence_anchors": [
-                {"ref_type": "doc_path", "ref_value": ref, "excerpt": ""} for ref in payload.evidence_refs
-            ],
-        }
-
-    return _predict
-
-
-def _load_compiled_predictor(artifact_path: Path) -> Callable[[DSPyRowEvaluationInput], Any] | None:
-    """Load a BootstrapFewShot-compiled DSPy JSON state artifact.
-
-    Recreates ``ChainOfThought(RowEvaluationSignature)`` and calls ``.load()``
-    on it.  Returns a predictor wrapper on success or ``None`` when the file is
-    missing, not valid JSON, or not a compiled DSPy state artifact (graceful
-    degradation -- the caller falls back to the default LLM-backed predictor).
-
-    Only JSON state-only serialization is supported (``save_program=False``).
-    """
-    if not artifact_path.exists() or not artifact_path.is_file():
-        _logger.info(
-            "dspy_compiled_artifact_not_found",
-            path=str(artifact_path),
-        )
-        return None
-
-    # Quick validation: must be valid JSON with DSPy state structure
-    try:
-        payload = json.loads(artifact_path.read_text(encoding="utf-8"))
-    except Exception:
-        _logger.warning(
-            "dspy_compiled_artifact_invalid_json",
-            path=str(artifact_path),
-        )
-        return None
-
-    if not isinstance(payload, dict):
-        _logger.warning(
-            "dspy_compiled_artifact_unexpected_format",
-            path=str(artifact_path),
-        )
-        return None
-
-    # Reject rulebook artifacts -- those are handled by _load_runtime_artifact_contract
-    if payload.get("kind") == "audit_judge_optimized":
-        _logger.debug(
-            "dspy_compiled_artifact_skipped_rulebook",
-            path=str(artifact_path),
-        )
-        return None
-
-    try:
-        import dspy
-
-        class RowEvaluationSignature(dspy.Signature):
-            """Evaluate one checklist row with evidence-grounded Vietnamese outputs.
-
-            Requirements:
-            - `reason_vn` and `finding_vn` must be specific for this row, not generic template text.
-            - Cite at least one `evidence_refs` value in `evidence_anchors.ref_value` when refs are provided.
-            - Keep `reason_vn` concise and requirement-scoped.
-            """
-
-            requirement_text = dspy.InputField()
-            requirement_intent = dspy.InputField(desc="The core business/technical intent of the requirement")
-            control_objective = dspy.InputField(desc="The overarching objective/category being tested")
-            acceptance_signals = dspy.InputField(desc="Specific keywords or indicators required for a PASS")
-            requirement_category = dspy.InputField()
-            requirement_guidance = dspy.InputField()
-            checklist_rule = dspy.InputField()
-            checklist_main = dspy.InputField()
-            checklist_sub_criterion = dspy.InputField()
-            checklist_eval_guide = dspy.InputField()
-            checklist_evidence_hint = dspy.InputField()
-            evidence_context = dspy.InputField()
-            evidence_refs = dspy.InputField()
-            status = dspy.OutputField(desc="One of PASS, PARTIAL, FAIL, ERROR, N/A")
-            reason_vn = dspy.OutputField(desc="Giải thích ngắn gọn bằng tiếng Việt")
-            finding_vn = dspy.OutputField(desc="Phát hiện chính bằng tiếng Việt")
-            evidence_anchors = dspy.OutputField(
-                desc="Danh sách các trích dẫn bằng chứng dạng JSON array [{ref_type, ref_value, excerpt}]"
-            )
-            score = dspy.OutputField(desc="Điểm 0-100")
-            confidence = dspy.OutputField(desc="Độ tin cậy 0-1")
-
-        compiled_predictor = dspy.ChainOfThought(RowEvaluationSignature)
-        compiled_predictor.load(path=str(artifact_path))
-    except Exception as exc:
-        _logger.warning(
-            "dspy_compiled_artifact_load_failed",
-            path=str(artifact_path),
-            error=str(exc),
-        )
-        return None
-
-    _logger.info(
-        "dspy_compiled_artifact_loaded",
-        path=str(artifact_path),
-    )
-
-    def _predict(payload: DSPyRowEvaluationInput) -> Any:
-        refs_preview = payload.evidence_refs[:12]
-        refs_text = "\n".join(f"- {ref}" for ref in refs_preview)
-
-        acceptance_signals_str = (
-            "\n".join(f"- {s}" for s in payload.acceptance_signals)
-            if payload.acceptance_signals
-            else "(none explicitly defined)"
-        )
-
-        return compiled_predictor(
-            requirement_text=payload.requirement_text,
-            requirement_intent=payload.requirement_intent or "",
-            control_objective=payload.control_objective or "",
-            acceptance_signals=acceptance_signals_str,
-            requirement_category=payload.requirement_category or "uncategorized",
-            requirement_guidance=payload.requirement_guidance or "",
-            checklist_rule=payload.checklist_rule,
-            checklist_main=payload.checklist_main,
-            checklist_sub_criterion=payload.checklist_sub_criterion,
-            checklist_eval_guide=payload.checklist_eval_guide,
-            checklist_evidence_hint=payload.checklist_evidence_hint,
-            evidence_context=payload.evidence_context,
-            evidence_refs=refs_text or "(no evidence refs)",
-        )
-
-    return _predict
-
-
-def _is_gemini_native_api_base(api_base: str) -> bool:
-    parsed = urlparse(api_base)
-    host = (parsed.hostname or "").lower()
-    return host.endswith("googleapis.com") or host.endswith("google.com")
-
-
-def _normalize_openai_proxy_base(api_base: str) -> str:
-    normalized = str(api_base).strip().rstrip("/")
-    if normalized.endswith("/v1beta"):
-        return f"{normalized[:-7]}/v1"
-    return normalize_openai_base_url(normalized) or normalized
-
-
-def _resolve_dspy_protocol(llm: LLMConfig) -> str:
-    protocol_raw = os.getenv("VDS_AUDIT_DSPY_PROTOCOL", "").strip().lower()
-    if protocol_raw:
-        if protocol_raw not in DSPY_RUNTIME_SUPPORTED_PROTOCOLS:
-            raise RuntimeError(f"Unsupported DSPy runtime protocol: {protocol_raw}")
-        return protocol_raw
-    protocol = llm.protocol.value.strip().lower()
-    if protocol not in DSPY_RUNTIME_SUPPORTED_PROTOCOLS:
-        raise RuntimeError(f"Unsupported DSPy runtime protocol: {protocol}")
-    return protocol
-
-
-def _resolve_dspy_model_and_kwargs() -> tuple[str, dict[str, Any], str]:
-    """Resolve DSPy model + auth kwargs from centralized runtime config."""
-    llm = get_config().llm
-    protocol = _resolve_dspy_protocol(llm)
-    raw_model = os.getenv("VDS_AUDIT_DSPY_MODEL", "").strip() or llm.model_standard
-    model = _normalize_dspy_model_name(raw_model)
-    kwargs = _dspy_provider_kwargs(protocol=protocol, llm=llm)
-    runtime_protocol = "openai" if protocol == "openai-codex" else protocol
-
-    # Codex-backed profiles should use the native Responses transport by default.
-    # Keep split DSPy endpoints available only when an explicit override base URL
-    # is configured and it is not the copied Codex backend itself.
-    llm_protocol = str(llm.protocol.value or "").strip().lower()
-    dspy_base_url = str(os.getenv("VDS_AUDIT_DSPY_BASE_URL", "")).strip()
-    if llm_protocol == "openai-codex":
-        normalized_override = str(normalize_codex_base_url(dspy_base_url) or "").strip().lower()
-        if not normalized_override or normalized_override.endswith("/backend-api/codex"):
-            runtime_protocol = "openai-codex"
-
-    # Codex-backed profiles still execute through OpenAI-compatible DSPy transport.
-    if protocol == "openai-codex" and "/" not in model:
-        model = f"openai/{model}"
-
-    # DSPy/LiteLLM Gemini transport requires Google-native API semantics.
-    # When a non-Google proxy URL is configured, route through OpenAI-compatible
-    # transport while keeping Gemini model selection.
-    if runtime_protocol == "gemini":
-        api_base = str(kwargs.get("api_base", "")).strip()
-        if api_base and not _is_gemini_native_api_base(api_base):
-            kwargs["api_base"] = _normalize_openai_proxy_base(api_base)
-            model_suffix = model.split("/", 1)[1] if "/" in model else model
-            model = f"openai/{model_suffix}"
-            runtime_protocol = "openai"
-
-    return model, kwargs, runtime_protocol
-
-
-def _normalize_dspy_model_name(model: str) -> str:
-    normalized = model.strip()
-    if not normalized:
-        raise RuntimeError("DSPy runtime model is empty")
-    if normalized.startswith("google/"):
-        return f"gemini/{normalized.split('/', 1)[1]}"
-    return normalized
-
-
-def _normalize_codex_dspy_model_name(model: str) -> str:
-    normalized = _normalize_dspy_model_name(model)
-    if "/" in normalized:
-        return normalized.split("/", 1)[1]
-    return normalized
-
-
-def _flatten_response_message_text(content: Any) -> str:
-    if isinstance(content, str):
-        return content.strip()
-    if not isinstance(content, list):
-        return ""
-    chunks: list[str] = []
-    for item in content:
-        if isinstance(item, str):
-            text = item.strip()
-            if text:
-                chunks.append(text)
-            continue
-        if not isinstance(item, dict):
-            continue
-        item_type = str(item.get("type") or "").strip().lower()
-        if item_type in {"text", "input_text", "output_text"}:
-            text = str(item.get("text") or "").strip()
-            if text:
-                chunks.append(text)
-    return "\n".join(chunk for chunk in chunks if chunk)
-
-
-def _build_codex_responses_request(
-    *,
-    model: str,
-    prompt: str | None,
-    messages: list[dict[str, Any]] | None,
-    timeout: float | None,
-    kwargs: dict[str, Any],
-) -> dict[str, Any]:
-    request_kwargs = dict(kwargs)
-    request_kwargs.pop("rollout_id", None)
-    reasoning_effort = request_kwargs.pop("reasoning_effort", None)
-    request_kwargs.pop("temperature", None)
-    request_kwargs.pop("max_tokens", None)
-    request_kwargs.pop("max_output_tokens", None)
-    request_kwargs.pop("max_completion_tokens", None)
-    request_kwargs.pop("response_format", None)
-    request_kwargs.pop("headers", None)
-
-    response_input: list[dict[str, Any]] = []
-    instructions: list[str] = []
-    normalized_messages = messages or [{"role": "user", "content": prompt or ""}]
-    for message in normalized_messages:
-        role = str(message.get("role") or "user").strip().lower()
-        text = _flatten_response_message_text(message.get("content"))
-        if not text:
-            continue
-        if role in {"system", "developer"}:
-            instructions.append(text)
-            continue
-        if role not in {"user", "assistant"}:
-            role = "user"
-        response_input.append({"role": role, "content": [{"type": "input_text", "text": text}]})
-
-    if not response_input:
-        fallback_prompt = str(prompt or "").strip() or "Respond to the provided instructions."
-        response_input.append({"role": "user", "content": [{"type": "input_text", "text": fallback_prompt}]})
-
-    request: dict[str, Any] = {
-        "model": _normalize_codex_dspy_model_name(model),
-        "instructions": "\n\n".join(instructions) if instructions else "You are a helpful assistant.",
-        "input": response_input,
-        "store": False,
-    }
-    if timeout is not None and timeout > 0:
-        request["timeout"] = timeout
-    if reasoning_effort:
-        request["reasoning"] = {"effort": reasoning_effort, "summary": "auto"}
-    return request
-
-
-def _create_codex_dspy_lm(model: str, *, cache: bool, num_retries: int, **model_kwargs: Any) -> Any:
-    import dspy
-    from dspy import settings as dspy_settings
-    from openai import AsyncOpenAI, OpenAI
-
-    from vds_audit_orchestrator.llm.codex_oauth import force_refresh_codex_credentials, get_codex_credentials
-
-    class CodexResponsesLM(dspy.LM):
-        def __init__(self, model_name: str, *, timeout: float | None = None):
-            super().__init__(
-                model=_normalize_codex_dspy_model_name(model_name),
-                model_type="responses",
-                cache=cache,
-                num_retries=num_retries,
-            )
-            llm = get_config().llm
-            base_url = normalize_codex_base_url(
-                str(os.getenv("VDS_AUDIT_LLM__BASE_URL", "")).strip() or resolve_secret(llm.base_url)
-            )
-            if not base_url:
-                raise RuntimeError("Codex DSPy transport requires VDS_AUDIT_LLM__BASE_URL")
-            self._codex_timeout = timeout
-            self._codex_api_base = base_url
-            self._codex_headers: dict[str, str] | None = None
-            self._sync_client: Any | None = None
-            self._async_client: Any | None = None
-            self._refresh_credentials(force=False)
-
-        def copy(self, **kwargs: Any) -> Any:
-            timeout = kwargs.pop("timeout", self._codex_timeout)
-            model_name = kwargs.pop("model", self.model)
-            return type(self)(model_name, timeout=timeout)
-
-        @staticmethod
-        def _is_auth_error(exc: Exception) -> bool:
-            message = str(exc).lower()
-            cause = getattr(exc, "__cause__", None)
-            cause_message = str(cause).lower() if cause is not None else ""
-            combined = f"{message}\n{cause_message}"
-            return (
-                "status_code: 401" in combined
-                or "401 unauthorized" in combined
-                or "status_code: 403" in combined
-                or "403 forbidden" in combined
-                or "authentication_error" in combined
-                or "invalid_api_key" in combined
-                or "invalid api key" in combined
-                or "incorrect api key" in combined
-                or "token expired" in combined
-                or "expired token" in combined
-            )
-
-        def _refresh_credentials(self, *, force: bool) -> None:
-            credentials = force_refresh_codex_credentials() if force else get_codex_credentials()
-            default_headers = {"ChatGPT-Account-Id": credentials.account_id}
-            self._codex_headers = default_headers
-            self._sync_client = OpenAI(
-                api_key=credentials.access_token,
-                base_url=self._codex_api_base,
-                default_headers=default_headers,
-            )
-            self._async_client = AsyncOpenAI(
-                api_key=credentials.access_token,
-                base_url=self._codex_api_base,
-                default_headers=default_headers,
-            )
-
-        def forward(
-            self,
-            prompt: str | None = None,
-            messages: list[dict[str, Any]] | None = None,
-            **kwargs: Any,
-        ) -> Any:
-            request = _build_codex_responses_request(
-                model=self.model,
-                prompt=prompt,
-                messages=messages,
-                timeout=self._codex_timeout,
-                kwargs=kwargs,
-            )
-            for attempt in range(2):
-                try:
-                    assert self._sync_client is not None
-                    with self._sync_client.responses.stream(**request) as stream:
-                        response = stream.get_final_response()
-                    if dspy_settings.usage_tracker and hasattr(response, "usage"):
-                        dspy_settings.usage_tracker.add_usage(self.model, dict(response.usage))
-                    return response
-                except Exception as exc:
-                    if attempt == 0 and self._is_auth_error(exc):
-                        _logger.warning("dspy_codex_auth_retry", model=self.model, error=str(exc), retry_attempt=1)
-                        self._refresh_credentials(force=True)
-                        continue
-                    raise
-
-        async def aforward(
-            self,
-            prompt: str | None = None,
-            messages: list[dict[str, Any]] | None = None,
-            **kwargs: Any,
-        ) -> Any:
-            request = _build_codex_responses_request(
-                model=self.model,
-                prompt=prompt,
-                messages=messages,
-                timeout=self._codex_timeout,
-                kwargs=kwargs,
-            )
-            for attempt in range(2):
-                try:
-                    assert self._async_client is not None
-                    async with self._async_client.responses.stream(**request) as stream:
-                        response = await stream.get_final_response()
-                    if dspy_settings.usage_tracker and hasattr(response, "usage"):
-                        dspy_settings.usage_tracker.add_usage(self.model, dict(response.usage))
-                    return response
-                except Exception as exc:
-                    if attempt == 0 and self._is_auth_error(exc):
-                        _logger.warning("dspy_codex_auth_retry", model=self.model, error=str(exc), retry_attempt=1)
-                        self._refresh_credentials(force=True)
-                        continue
-                    raise
-
-    timeout = model_kwargs.get("timeout")
-    return CodexResponsesLM(model, timeout=timeout)
-
-
-def _rewrite_system_messages_for_gemini(messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
-    """Rewrite system-role messages to user-role for Gemini-proxy compatibility."""
-    rewritten: list[dict[str, Any]] = []
-    for message in messages:
-        role = str(message.get("role", ""))
-        if role != "system":
-            rewritten.append(message)
-            continue
-        transformed = dict(message)
-        transformed["role"] = "user"
-        content = transformed.get("content")
-        if isinstance(content, str):
-            transformed["content"] = f"[SYSTEM]\n{content}"
-        rewritten.append(transformed)
-    return rewritten
-
-
-def _gemini_dspy_system_role_compat_enabled() -> bool:
-    raw = os.getenv("VDS_AUDIT_DSPY_SYSTEM_ROLE_COMPAT", "1").strip().lower()
-    return raw in {"1", "true", "yes", "on"}
-
-
-def _dspy_provider_kwargs(*, protocol: str, llm: LLMConfig) -> dict[str, Any]:
-    kwargs: dict[str, Any] = {}
-    if protocol not in DSPY_RUNTIME_SUPPORTED_PROTOCOLS:
-        raise RuntimeError(f"Unsupported DSPy runtime protocol: {protocol}")
-    if llm.base_url:
-        kwargs["api_base"] = llm.base_url.rstrip("/")
-    if llm.api_key:
-        kwargs["api_key"] = resolve_secret(llm.api_key) or ""
-
-    dspy_api_key = os.getenv("VDS_AUDIT_DSPY_API_KEY", "").strip()
-    if dspy_api_key:
-        kwargs["api_key"] = dspy_api_key
-
-    dspy_base_url = os.getenv("VDS_AUDIT_DSPY_BASE_URL", "").strip()
-    if dspy_base_url:
-        kwargs["api_base"] = dspy_base_url.rstrip("/")
-
-    dspy_timeout_raw = os.getenv("VDS_AUDIT_DSPY_TIMEOUT_SECONDS", "").strip()
-    if dspy_timeout_raw:
-        try:
-            dspy_timeout = float(dspy_timeout_raw)
-        except ValueError:
-            dspy_timeout = 0.0
-        if dspy_timeout > 0:
-            kwargs["timeout"] = dspy_timeout
-
-    if protocol == "openai" and not str(kwargs.get("api_key", "")).strip():
-        kwargs["api_key"] = "no-key-required"
-
-    return kwargs
-
-
-def _dspy_generation_kwargs(protocol: str, max_tokens: int) -> dict[str, Any]:
-    """Return provider-safe generation kwargs for DSPy LM construction.
-
-    Gemini transport can reject requests when max token limits are duplicated across
-    translated request fields. Keep Google payload minimal and rely on provider defaults.
-    """
-    if protocol == "gemini":
-        return {}
-    return {"max_tokens": max_tokens}
-
-
-def _dspy_temperature_kwargs(model: str, temperature: float) -> dict[str, Any]:
-    """Return provider-safe temperature kwargs for DSPy LM construction.
-
-    GPT-5 family models reject `temperature` on many reasoning-capable surfaces,
-    including the Codex-backed OpenAI transport used by `codex-chatgpt`.
-    Omit the field entirely for GPT-5-family judge models and rely on the
-    provider default instead of hard-failing arbitration.
-    """
-    normalized = str(model or "").strip().lower()
-    if "/" in normalized:
-        normalized = normalized.split("/", 1)[1]
-    if normalized.startswith("gpt-5"):
-        _logger.info(
-            "dspy_temperature_omitted_for_gpt5_family",
-            model=model,
-            temperature=temperature,
-        )
-        return {}
-    return {"temperature": temperature}
-
-
-def _build_default_predictor() -> Callable[[DSPyRowEvaluationInput], Any]:
-    model, model_kwargs, runtime_protocol = _resolve_dspy_model_and_kwargs()
-    default_max_tokens = int(get_config().llm.max_tokens_per_request or 4096)
-    configured_max_tokens = int(os.getenv("VDS_AUDIT_DSPY_MAX_TOKENS", str(default_max_tokens)))
-    max_tokens_floor = int(os.getenv("VDS_AUDIT_DSPY_MIN_MAX_TOKENS", "4096"))
-    max_tokens = max(configured_max_tokens, max_tokens_floor)
-    temperature = float(os.getenv("VDS_AUDIT_DSPY_TEMPERATURE", "0.0"))
-    runtime_artifact = _load_runtime_artifact_contract(model=model)
-
-    if runtime_artifact is not None:
-        return _rulebook_predictor(runtime_artifact)
-
-    # Check for BootstrapFewShot-compiled JSON state artifact (optional enhancement).
-    compiled_artifact_raw = os.getenv("VDS_AUDIT_DSPY_COMPILED_ARTIFACT", "").strip()
-    if compiled_artifact_raw:
-        compiled_path = Path(compiled_artifact_raw).expanduser()
-        compiled_pred = _load_compiled_predictor(compiled_path)
-        if compiled_pred is not None:
-            return compiled_pred
-        _logger.info(
-            "dspy_compiled_artifact_fallback",
-            path=str(compiled_path),
-            reason="falling back to default LLM-backed predictor",
-        )
-
-    import dspy
-
-    class RowEvaluationSignature(dspy.Signature):
-        """Evaluate one checklist row with evidence-grounded Vietnamese outputs.
-
-        Requirements:
-        - `reason_vn` and `finding_vn` must be specific for this row, not generic template text.
-        - Cite at least one `evidence_refs` value in `evidence_anchors.ref_value` when refs are provided.
-        - Keep `reason_vn` concise and requirement-scoped.
-        """
-
-        requirement_text = dspy.InputField()
-        requirement_intent = dspy.InputField(desc="The core business/technical intent of the requirement")
-        control_objective = dspy.InputField(desc="The overarching objective/category being tested")
-        acceptance_signals = dspy.InputField(desc="Specific keywords or indicators required for a PASS")
-        requirement_category = dspy.InputField()
-        requirement_guidance = dspy.InputField()
-        checklist_rule = dspy.InputField()
-        checklist_main = dspy.InputField()
-        checklist_sub_criterion = dspy.InputField()
-        checklist_eval_guide = dspy.InputField()
-        checklist_evidence_hint = dspy.InputField()
-        evidence_context = dspy.InputField()
-        evidence_refs = dspy.InputField()
-        status = dspy.OutputField(desc="One of PASS, PARTIAL, FAIL, ERROR, N/A")
-        reason_vn = dspy.OutputField(desc="Giải thích ngắn gọn bằng tiếng Việt")
-        finding_vn = dspy.OutputField(desc="Phát hiện chính bằng tiếng Việt")
-        evidence_anchors = dspy.OutputField(
-            desc="Danh sách các trích dẫn bằng chứng dạng JSON array [{ref_type, ref_value, excerpt}]"
-        )
-        score = dspy.OutputField(desc="Điểm 0-100")
-        confidence = dspy.OutputField(desc="Độ tin cậy 0-1")
-
-    if runtime_protocol == "openai-codex":
-        lm = _create_codex_dspy_lm(
-            model,
-            cache=False,
-            num_retries=3,
-            **model_kwargs,
-        )
-    else:
-        lm = dspy.LM(
-            model=model,
-            cache=False,
-            **_dspy_temperature_kwargs(model, temperature),
-            **_dspy_generation_kwargs(runtime_protocol, max_tokens),
-            **model_kwargs,
-        )
-    adapter_instance: Any | None = None
-    if runtime_protocol == "gemini" and _gemini_dspy_system_role_compat_enabled():
-        from dspy.adapters.json_adapter import JSONAdapter
-
-        class GeminiCompatJSONAdapter(JSONAdapter):
-            def format(
-                self,
-                signature: type[Any],
-                demos: list[dict[str, Any]],
-                inputs: dict[str, Any],
-            ) -> list[dict[str, Any]]:
-                messages = super().format(signature=signature, demos=demos, inputs=inputs)
-                return _rewrite_system_messages_for_gemini(messages)
-
-        adapter_instance = GeminiCompatJSONAdapter()
-
-    # Track whether we need to use dspy.context() for each predictor call.
-    # DSPy 3.x+ enforces that only the async task that first called dspy.configure()
-    # can call it again. For other async contexts, we must use dspy.context() as
-    # a context manager wrapping the actual predictor call.
-    # See: https://dspy.ai/api/utils/configure (Thread safety section)
-    _use_context_fallback = False
-
-    if adapter_instance is None:
-        try:
-            dspy.configure(lm=lm)
-        except RuntimeError as exc:
-            if "dspy.configure(...) can only be called from the same async task" in str(exc):
-                _logger.info(
-                    "dspy_configure_async_context_fallback",
-                    reason="async_task_boundary_crossed",
-                    fallback="using_dspy_context_per_call",
-                )
-                _use_context_fallback = True
-            else:
-                raise
-    else:
-        try:
-            dspy.configure(lm=lm, adapter=adapter_instance)
-        except RuntimeError as exc:
-            if "dspy.configure(...) can only be called from the same async task" in str(exc):
-                _logger.info(
-                    "dspy_configure_async_context_fallback",
-                    reason="async_task_boundary_crossed",
-                    fallback="using_dspy_context_per_call",
-                )
-                _use_context_fallback = True
-            else:
-                raise
-
-    predictor = dspy.ChainOfThought(RowEvaluationSignature)
-
-    def _predict(payload: DSPyRowEvaluationInput) -> Any:
-        refs_preview = payload.evidence_refs[:12]
-        refs_text = "\n".join(f"- {ref}" for ref in refs_preview)
-
-        acceptance_signals_str = (
-            "\n".join(f"- {s}" for s in payload.acceptance_signals)
-            if payload.acceptance_signals
-            else "(none explicitly defined)"
-        )
-
-        predict_kwargs = {
-            "requirement_text": payload.requirement_text,
-            "requirement_intent": payload.requirement_intent or "",
-            "control_objective": payload.control_objective or "",
-            "acceptance_signals": acceptance_signals_str,
-            "requirement_category": payload.requirement_category or "uncategorized",
-            "requirement_guidance": payload.requirement_guidance or "",
-            "checklist_rule": payload.checklist_rule,
-            "checklist_main": payload.checklist_main,
-            "checklist_sub_criterion": payload.checklist_sub_criterion,
-            "checklist_eval_guide": payload.checklist_eval_guide,
-            "checklist_evidence_hint": payload.checklist_evidence_hint,
-            "evidence_context": payload.evidence_context,
-            "evidence_refs": refs_text or "(no evidence refs)",
-        }
-
-        # Use dspy.context() as proper context manager when we couldn't use dspy.configure()
-        # This is the DSPy 3.x+ recommended pattern for cross-async-task configuration.
-        if _use_context_fallback:
-            context_kwargs = {"lm": lm}
-            if adapter_instance is not None:
-                context_kwargs["adapter"] = adapter_instance
-            with dspy.context(**context_kwargs):
-                return predictor(**predict_kwargs)
-        else:
-            return predictor(**predict_kwargs)
-
-    return _predict
-
-
-def load_dspy_runtime() -> DSPyRuntime:
-    """Load optional DSPy runtime.
-
-    Raises:
-        RuntimeError: When DSPy is not installed.
-    """
-    try:
-        importlib.import_module("dspy")
-    except ModuleNotFoundError as exc:
-        raise RuntimeError("DSPy backend requested but `dspy` is not installed") from exc
-
-    if _env_flag("VDS_AUDIT_DSPY_REQUIRE_RUNTIME_ARTIFACT"):
-        model, _, _ = _resolve_dspy_model_and_kwargs()
-        contract = _load_runtime_artifact_contract(model=model)
-        if contract is None:
-            raise RuntimeError(
-                "dspy_runtime_artifact_required_missing: set VDS_AUDIT_DSPY_RUNTIME_ARTIFACT to a valid artifact path"
-            )
-    predictor = _build_default_predictor()
-    return DefaultDSPyRuntime(module=DSPyRowEvaluationModule(predictor=predictor))