@ngocsangairvds/vsaf 3.2.14 → 3.2.16

package/tools/vds-scripts/audit_orchestrator/src/vds_audit_orchestrator/agents/pydantic_base.py

@@ -1,1227 +0,0 @@
-"""PydanticAI agent foundation (Phase 8).
-
-This module provides the foundation for PydanticAI-based agents in the audit orchestrator.
-It includes:
-- AuditDeps: Dependency injection dataclass for agents
-- Output models: Structured output schemas for each agent type
-- Agent factory: Standardized agent creation with validation
-- Output validators: Confidence-based retry logic
-
-Reference: design.md Section 8.5
-"""
-
-from __future__ import annotations
-
-import json
-import math
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import TYPE_CHECKING, Any, TypeVar, cast
-
-from pydantic import BaseModel, Field, model_validator
-from structlog import get_logger
-from vds_agent_core.config import LLMProtocolType
-from vds_platform_core.credentials import resolve_secret
-from vds_platform_core.serialization import safe_dump
-
-from vds_audit_orchestrator.config import LLMConfig, get_config
-from vds_audit_orchestrator.models.enums import MaturityLevel
-
-if TYPE_CHECKING:
-    from vds_audit_orchestrator.evidence.corpus import EvidenceCorpus
-    from vds_audit_orchestrator.models.evidence import EvidenceBundle
-
-OutputType = TypeVar("OutputType")
-logger = get_logger(__name__)
-
-OPENAI_DUMMY_API_KEY = "no-key-required"
-OPENAI_CODEX_PROTOCOL = "openai-codex"
-OPENAI_CODEX_BASELINE_MODELS: frozenset[str] = frozenset({"gpt-5.4", "gpt-5.3-codex", "gpt-5.2-codex"})
-_PROVIDER_HTTP_CLIENTS: dict[tuple[str, float], Any] = {}
-
-
-def _protocol_value(protocol: Any) -> str:
-    return str(getattr(protocol, "value", protocol) or "").strip().lower()
-
-
-def _is_openai_codex_protocol(protocol: Any) -> bool:
-    return _protocol_value(protocol) == OPENAI_CODEX_PROTOCOL
-
-
-def _normalize_codex_base_url(raw_base_url: str) -> str:
-    normalized = raw_base_url.rstrip("/")
-    if normalized.endswith("/responses"):
-        normalized = normalized[: -len("/responses")]
-    return normalized
-
-
-def _resolve_base_url(llm_config: LLMConfig, protocol: LLMProtocolType) -> str | None:
-    from vds_audit_orchestrator.llm.provider import resolve_protocol_base_url
-
-    return resolve_protocol_base_url(llm_config, protocol)
-
-
-def _build_structured_output_extra_body_for_protocol(
-    base_url: Any,
-    protocol: LLMProtocolType | str | None,
-) -> dict[str, Any] | None:
-    from vds_audit_orchestrator.llm.provider import build_structured_output_extra_body
-
-    return build_structured_output_extra_body(base_url, protocol)
-
-
-def _resolve_api_key_or_dummy(llm_config: LLMConfig, dummy: str = OPENAI_DUMMY_API_KEY) -> str:
-    if llm_config.api_key:
-        return resolve_secret(llm_config.api_key) or dummy
-    return dummy
-
-
-def _resolve_api_key(llm_config: LLMConfig, protocol: LLMProtocolType) -> str:
-    if llm_config.api_key:
-        return resolve_secret(llm_config.api_key) or ""
-    raise ValueError(f"VDS_AUDIT_LLM__API_KEY is required for {protocol.value}")
-
-
-def _read_credential_field(credentials: Any, *field_names: str) -> str | None:
-    for field_name in field_names:
-        if isinstance(credentials, dict):
-            raw_value = credentials.get(field_name)
-        else:
-            raw_value = getattr(credentials, field_name, None)
-        value = str(raw_value or "").strip()
-        if value:
-            return value
-    return None
-
-
-def _resolve_codex_access_token(credentials: Any) -> str:
-    access_token = _read_credential_field(credentials, "access_token", "token")
-    if not access_token:
-        raise ValueError("Codex OAuth credentials missing access token")
-    return access_token
-
-
-def _resolve_codex_account_id(credentials: Any) -> str | None:
-    return _read_credential_field(credentials, "chatgpt_account_id", "account_id")
-
-
-def _warn_if_unvalidated_codex_model(model_name: str) -> None:
-    normalized = str(model_name).strip().lower()
-    if normalized in OPENAI_CODEX_BASELINE_MODELS:
-        return
-    logger.warning(
-        "codex_unsupported_model_name",
-        model_name=model_name,
-        baseline_models=sorted(OPENAI_CODEX_BASELINE_MODELS),
-    )
-
-
-def _resolve_agent_request_timeout_seconds(llm_config: LLMConfig) -> float:
-    raw_timeout = getattr(llm_config, "agent_timeout_seconds", 600.0)
-    try:
-        timeout_seconds = float(raw_timeout)
-    except (TypeError, ValueError):
-        timeout_seconds = 600.0
-    if not math.isfinite(timeout_seconds):
-        timeout_seconds = 600.0
-    return max(0.05, timeout_seconds)
-
-
-def _build_provider_http_client(llm_config: LLMConfig) -> Any:
-    import httpx
-
-    timeout_seconds = _resolve_agent_request_timeout_seconds(llm_config)
-    cache_key = ("provider-http", round(timeout_seconds, 3))
-    cached = _PROVIDER_HTTP_CLIENTS.get(cache_key)
-    if cached is not None:
-        return cached
-    client = httpx.AsyncClient(timeout=httpx.Timeout(timeout_seconds))
-    _PROVIDER_HTTP_CLIENTS[cache_key] = client
-    return client
-
-
-def _safe_float(value: Any, default: float) -> float:
-    try:
-        return float(value)
-    except (TypeError, ValueError):
-        return default
-
-
-def _safe_int(value: Any, default: int) -> int:
-    try:
-        return int(value)
-    except (TypeError, ValueError):
-        return default
-
-
-def _safe_str(value: Any, default: str = "") -> str:
-    if value is None:
-        return default
-    text = str(value).strip()
-    return text if text else default
-
-
-def _normalize_confidence(value: Any, default: float = 0.8) -> float:
-    """Normalize confidence to [0,1], accepting common 0-10 model outputs."""
-    confidence = _safe_float(value, default)
-    if confidence > 1.0 and confidence <= 10.0:
-        confidence = confidence / 10.0
-    return max(0.0, min(confidence, 1.0))
-
-
-def _normalize_severity(value: Any, default: str = "medium") -> str:
-    normalized = _safe_str(value, default).lower()
-    alias_map = {
-        "blocker": "critical",
-        "major": "high",
-        "minor": "medium",
-        "warning": "medium",
-        "warn": "medium",
-        "informational": "low",
-        "info": "low",
-    }
-    normalized = alias_map.get(normalized, normalized)
-    return normalized if normalized in {"critical", "high", "medium", "low"} else default
-
-
-def _coerce_string_list(value: Any) -> list[str]:
-    if isinstance(value, list):
-        return [_safe_str(item) for item in value if _safe_str(item)]
-    if isinstance(value, str):
-        return [part.strip() for part in value.split(",") if part.strip()]
-    return []
-
-
-def _coerce_json_mapping(value: Any) -> dict[str, Any]:
-    """Best-effort conversion of model output payloads into a mapping."""
-    if isinstance(value, dict):
-        return dict(value)
-    if isinstance(value, str):
-        text = value.strip()
-        if not text:
-            return {}
-        try:
-            decoded = json.loads(text)
-        except Exception:
-            return {"reasoning": text}
-        if isinstance(decoded, dict):
-            return decoded
-        if isinstance(decoded, list):
-            return {"issues": decoded}
-        return {}
-    if isinstance(value, list):
-        return {"issues": value}
-    return {}
-
-
-# =============================================================================
-# Dependency Injection
-# =============================================================================
-
-
-@dataclass(slots=True)
-class AuditDeps:
-    """Dependencies injected into PydanticAI agents.
-
-    This dataclass provides all context needed by audit agents during execution.
-    It is passed to agents via PydanticAI's dependency injection mechanism.
-
-    Attributes:
-        profile: Project profile dictionary containing domain, criticality, etc.
-        evidence: Collected evidence bundle for the repository.
-        settings: LLM configuration settings.
-        repo_path: Absolute path to the repository being audited.
-        project_id: Unique identifier for the project/repository.
-        evidence_corpus: Optional corpus of extracted materials (Phase 15).
-    """
-
-    profile: dict[str, Any] = field(default_factory=dict)
-    evidence: dict[str, Any] = field(default_factory=dict)
-    settings: dict[str, Any] = field(default_factory=dict)
-    repo_path: str = ""
-    project_id: str = ""
-    evidence_corpus: EvidenceCorpus | None = None
-
-    @classmethod
-    def from_evidence_bundle(
-        cls,
-        evidence: EvidenceBundle,
-        profile: dict[str, Any] | None = None,
-        settings: LLMConfig | None = None,
-        evidence_corpus: EvidenceCorpus | None = None,
-    ) -> AuditDeps:
-        """Create AuditDeps from an EvidenceBundle.
-
-        Args:
-            evidence: The evidence bundle to extract data from.
-            profile: Optional project profile dictionary.
-            settings: Optional LLM configuration.
-            evidence_corpus: Optional extracted evidence corpus.
-
-        Returns:
-            AuditDeps instance with extracted evidence data.
-        """
-        evidence_dict = evidence.model_dump() if evidence else {}
-        settings_dict = safe_dump(settings) if settings else {}
-        return cls(
-            profile=profile or {},
-            evidence=evidence_dict,
-            settings=settings_dict,
-            repo_path=str(evidence.repository) if evidence else "",
-            project_id=evidence_dict.get("repository", ""),
-            evidence_corpus=evidence_corpus,
-        )
-
-
-# =============================================================================
-# Output Models for Each Agent Type
-# =============================================================================
-
-
-class CodeIssue(BaseModel):
-    """A single code quality or security issue."""
-
-    file_path: str = Field(..., description="Path to the file containing the issue")
-    line_number: int | None = Field(None, description="Line number if applicable")
-    severity: str = Field(..., description="Issue severity: critical, high, medium, low")
-    category: str = Field(..., description="Issue category: security, quality, maintainability")
-    description: str = Field(..., description="Description of the issue")
-    recommendation: str = Field("", description="Recommended fix or action")
-
-    @model_validator(mode="before")
-    @classmethod
-    def _normalize_shape(cls, data: Any) -> Any:
-        if not isinstance(data, dict):
-            text = _safe_str(data)
-            return {
-                "file_path": "unknown",
-                "line_number": None,
-                "severity": "medium",
-                "category": "quality",
-                "description": text or "Issue detected by analysis.",
-                "recommendation": "",
-            }
-        payload = dict(data)
-        payload["file_path"] = _safe_str(
-            payload.get("file_path") or payload.get("path") or payload.get("file"), "unknown"
-        )
-        payload["line_number"] = _safe_int(payload.get("line_number") or payload.get("line"), 0) or None
-        payload["severity"] = _normalize_severity(payload.get("severity"), "medium")
-        payload["category"] = _safe_str(payload.get("category") or payload.get("type"), "quality").lower()
-        payload["description"] = _safe_str(
-            payload.get("description") or payload.get("message") or payload.get("issue"),
-            "Issue detected by analysis.",
-        )
-        payload["recommendation"] = _safe_str(
-            payload.get("recommendation") or payload.get("remediation") or payload.get("fix"),
-            "",
-        )
-        return payload
-
-
-class CodePattern(BaseModel):
-    """A detected code pattern (positive or negative)."""
-
-    name: str = Field(..., description="Name of the pattern")
-    occurrences: int = Field(1, description="Number of times pattern was found")
-    is_positive: bool = Field(True, description="True if this is a good practice")
-    description: str = Field("", description="Description of the pattern")
-    examples: list[str] = Field(default_factory=list, description="Example file paths")
-
-    @model_validator(mode="before")
-    @classmethod
-    def _normalize_shape(cls, data: Any) -> Any:
-        if isinstance(data, str):
-            label = _safe_str(data, "Pattern")
-            return {
-                "name": label,
-                "occurrences": 1,
-                "is_positive": True,
-                "description": label,
-                "examples": [],
-            }
-        if not isinstance(data, dict):
-            return {
-                "name": "Pattern",
-                "occurrences": 1,
-                "is_positive": True,
-                "description": "",
-                "examples": [],
-            }
-        payload = dict(data)
-        payload["name"] = _safe_str(payload.get("name") or payload.get("pattern"), "Pattern")
-        payload["occurrences"] = max(1, _safe_int(payload.get("occurrences") or payload.get("count"), 1))
-        polarity = payload.get("is_positive")
-        if polarity is None:
-            polarity = payload.get("positive")
-        payload["is_positive"] = (
-            bool(polarity)
-            if not isinstance(polarity, str)
-            else polarity.strip().lower()
-            in {
-                "true",
-                "1",
-                "yes",
-                "positive",
-                "good",
-            }
-        )
-        payload["description"] = _safe_str(payload.get("description") or payload.get("details"), payload["name"])
-        payload["examples"] = _coerce_string_list(payload.get("examples") or payload.get("files"))
-        return payload
-
-
-class CodeFindings(BaseModel):
-    """Output model for CodeAnalysisAgent.
-
-    Contains structured findings from code quality and security analysis.
-    """
-
-    score: float = Field(
-        ...,
-        ge=0.0,
-        le=10.0,
-        description="Overall code quality score (0-10)",
-    )
-    score_missing: bool = Field(
-        default=False,
-        exclude=True,
-        description="True when score was absent in raw model output and normalized by fallback.",
-    )
-    issues: list[CodeIssue] = Field(
-        default_factory=list,
-        description="List of identified code issues",
-    )
-    patterns: list[CodePattern] = Field(
-        default_factory=list,
-        description="Detected code patterns (positive and negative)",
-    )
-    confidence: float = Field(
-        default=0.8,
-        ge=0.0,
-        le=1.0,
-        description="Confidence level of the analysis (0-1)",
-    )
-    reasoning: str = Field(
-        "",
-        description="Explanation of the analysis and scoring",
-    )
-    files_analyzed: int = Field(
-        0,
-        description="Number of files analyzed",
-    )
-    tech_stack: list[str] = Field(
-        default_factory=list,
-        description="Detected technology stack",
-    )
-
-    @model_validator(mode="before")
-    @classmethod
-    def _normalize_shape(cls, data: Any) -> Any:
-        payload = _coerce_json_mapping(data)
-        raw_score = payload.get("score")
-        if raw_score is None:
-            raw_score = payload.get("overall_score")
-        if raw_score is None:
-            raw_score = payload.get("quality_score")
-        payload["score_missing"] = raw_score is None or (isinstance(raw_score, str) and not raw_score.strip())
-        payload["score"] = _safe_float(raw_score, 0.0)
-        issues = payload.get("issues") or payload.get("findings") or []
-        if isinstance(issues, (dict, str)):
-            issues = [issues]
-        elif not isinstance(issues, list):
-            issues = []
-        payload["issues"] = issues
-
-        patterns = payload.get("patterns") or []
-        if isinstance(patterns, (dict, str)):
-            patterns = [patterns]
-        elif not isinstance(patterns, list):
-            patterns = []
-        payload["patterns"] = patterns
-
-        payload["confidence"] = _normalize_confidence(payload.get("confidence"), 0.8)
-        payload["reasoning"] = _safe_str(
-            payload.get("reasoning") or payload.get("analysis") or payload.get("summary"),
-            "",
-        )
-        payload["files_analyzed"] = _safe_int(
-            payload.get("files_analyzed") or payload.get("analyzed_files") or len(payload.get("issues", [])),
-            0,
-        )
-        payload["tech_stack"] = _coerce_string_list(payload.get("tech_stack"))
-        return payload
-
-
-class DocFindings(BaseModel):
-    """Output model for DocumentationAgent.
-
-    Contains structured findings from documentation quality analysis.
-    """
-
-    readme_score: float = Field(
-        ...,
-        ge=0.0,
-        le=10.0,
-        description="README quality score (0-10)",
-    )
-    confluence_score: float = Field(
-        default=0.0,
-        ge=0.0,
-        le=10.0,
-        description="Confluence documentation score (0-10)",
-    )
-    api_docs_score: float = Field(
-        default=0.0,
-        ge=0.0,
-        le=10.0,
-        description="API documentation score (0-10)",
-    )
-    notes: list[str] = Field(
-        default_factory=list,
-        description="Observations and notes about documentation quality",
-    )
-    confidence: float = Field(
-        default=0.8,
-        ge=0.0,
-        le=1.0,
-        description="Confidence level of the analysis (0-1)",
-    )
-    missing_sections: list[str] = Field(
-        default_factory=list,
-        description="Required sections that are missing from documentation",
-    )
-    strengths: list[str] = Field(
-        default_factory=list,
-        description="Documentation strengths identified",
-    )
-    recommendations: list[str] = Field(
-        default_factory=list,
-        description="Recommendations for documentation improvement",
-    )
-
-    @model_validator(mode="before")
-    @classmethod
-    def _normalize_shape(cls, data: Any) -> Any:
-        payload = _coerce_json_mapping(data)
-        payload["readme_score"] = _safe_float(
-            payload.get("readme_score")
-            or payload.get("readme_quality")
-            or payload.get("readme")
-            or payload.get("score"),
-            0.0,
-        )
-        payload["confluence_score"] = _safe_float(
-            payload.get("confluence_score") or payload.get("confluence_quality") or payload.get("confluence"),
-            0.0,
-        )
-        payload["api_docs_score"] = _safe_float(
-            payload.get("api_docs_score")
-            or payload.get("api_score")
-            or payload.get("api_docs")
-            or payload.get("api_documentation"),
-            0.0,
-        )
-        payload["notes"] = _coerce_string_list(payload.get("notes"))
-        payload["confidence"] = _normalize_confidence(payload.get("confidence"), 0.8)
-        payload["missing_sections"] = _coerce_string_list(payload.get("missing_sections") or payload.get("gaps"))
-        payload["strengths"] = _coerce_string_list(payload.get("strengths"))
-        payload["recommendations"] = _coerce_string_list(payload.get("recommendations") or payload.get("actions"))
-        return payload
-
-    @property
-    def overall_score(self) -> float:
-        """Calculate weighted overall documentation score."""
-        weights = {"readme": 0.4, "confluence": 0.35, "api_docs": 0.25}
-        return (
-            self.readme_score * weights["readme"]
-            + self.confluence_score * weights["confluence"]
-            + self.api_docs_score * weights["api_docs"]
-        )
-
-
-class Vulnerability(BaseModel):
-    """A security vulnerability finding."""
-
-    id: str = Field(..., description="Vulnerability identifier (e.g., CVE, CWE)")
-    severity: str = Field(..., description="Severity: critical, high, medium, low")
-    category: str = Field(..., description="Category: dependency, code, configuration")
-    title: str = Field(..., description="Brief title of the vulnerability")
-    description: str = Field(..., description="Detailed description")
-    affected_component: str = Field("", description="Affected component or file")
-    remediation: str = Field("", description="Recommended remediation steps")
-    cvss_score: float | None = Field(None, description="CVSS score if available")
-
-    @model_validator(mode="before")
-    @classmethod
-    def _normalize_shape(cls, data: Any) -> Any:
-        if not isinstance(data, dict):
-            return data
-        payload = dict(data)
-        payload["title"] = _safe_str(payload.get("title") or payload.get("name"), "Unspecified vulnerability")
-        payload["id"] = _safe_str(
-            payload.get("id") or payload.get("vulnerability_id") or payload.get("cve") or payload.get("cwe"),
-            f"SEC-{abs(hash(payload['title'])) % 100000:05d}",
-        )
-        payload["severity"] = _normalize_severity(payload.get("severity"), "medium")
-        payload["category"] = _safe_str(payload.get("category") or payload.get("type"), "code").lower()
-        payload["description"] = _safe_str(
-            payload.get("description") or payload.get("details") or payload.get("summary"),
-            payload["title"],
-        )
-        payload["affected_component"] = _safe_str(
-            payload.get("affected_component")
-            or payload.get("component")
-            or payload.get("file_path")
-            or payload.get("location"),
-            "",
-        )
-        payload["remediation"] = _safe_str(
-            payload.get("remediation") or payload.get("recommendation") or payload.get("fix"),
-            "",
-        )
-        cvss_score = payload.get("cvss_score") or payload.get("cvss")
-        payload["cvss_score"] = _safe_float(cvss_score, 0.0) if cvss_score not in (None, "") else None
-        return payload
-
-
-class SecurityFindings(BaseModel):
-    """Output model for SecurityAgent.
-
-    Contains structured findings from security posture analysis.
-    """
-
-    vulnerabilities: list[Vulnerability] = Field(
-        default_factory=list,
-        description="List of identified vulnerabilities",
-    )
-    posture_score: float = Field(
-        ...,
-        ge=0.0,
-        le=10.0,
-        description="Overall security posture score (0-10)",
-    )
-    recommendations: list[str] = Field(
-        default_factory=list,
-        description="Security recommendations",
-    )
-    confidence: float = Field(
-        default=0.8,
-        ge=0.0,
-        le=1.0,
-        description="Confidence level of the analysis (0-1)",
-    )
-    sonarqube_issues: int = Field(
-        0,
-        description="Number of SonarQube security issues",
-    )
-    dependency_vulnerabilities: int = Field(
-        0,
-        description="Number of dependency vulnerabilities",
-    )
-    security_controls: list[str] = Field(
-        default_factory=list,
-        description="Security controls detected (auth, encryption, etc.)",
-    )
-
-    @model_validator(mode="before")
-    @classmethod
-    def _normalize_shape(cls, data: Any) -> Any:
-        if not isinstance(data, dict):
-            return data
-        payload = dict(data)
-        payload["vulnerabilities"] = (
-            payload.get("vulnerabilities") or payload.get("findings") or payload.get("issues") or []
-        )
-        payload["posture_score"] = _safe_float(
-            payload.get("posture_score") or payload.get("security_score") or payload.get("score"),
-            0.0,
-        )
-        payload["recommendations"] = _coerce_string_list(
-            payload.get("recommendations") or payload.get("actions") or payload.get("next_steps")
-        )
-        payload["confidence"] = _normalize_confidence(payload.get("confidence"), 0.8)
-        payload["sonarqube_issues"] = _safe_int(payload.get("sonarqube_issues"), 0)
-        payload["dependency_vulnerabilities"] = _safe_int(payload.get("dependency_vulnerabilities"), 0)
-        payload["security_controls"] = _coerce_string_list(payload.get("security_controls") or payload.get("controls"))
-        return payload
-
-    @property
-    def critical_count(self) -> int:
-        """Count of critical vulnerabilities."""
-        return sum(1 for v in self.vulnerabilities if v.severity.lower() == "critical")
-
-    @property
-    def high_count(self) -> int:
-        """Count of high severity vulnerabilities."""
-        return sum(1 for v in self.vulnerabilities if v.severity.lower() == "high")
-
-
-class GapSummary(BaseModel):
-    """Summary of a gap for synthesis reporting."""
-
-    check_id: str = Field(..., description="ID of the check that identified this gap")
-    severity: str = Field(..., description="Gap severity: critical, high, medium, low")
-    category: str = Field(..., description="Gap category")
-    description: str = Field(..., description="Brief description of the gap")
-    recommendation: str = Field("", description="Recommended action")
-    location: str | None = Field(None, description="Location for the gap, if available")
-
-
-class AlignedPracticeSummary(BaseModel):
-    """Summary of an aligned practice for synthesis reporting."""
-
-    check_id: str = Field(..., description="ID of the check")
-    description: str = Field(..., description="Description of the aligned practice")
-    level: str = Field("Good", description="Practice level: Basic, Good, Excellent, Exemplary")
-
-
-class SynthesisResult(BaseModel):
-    """Output model for SynthesisAgent.
-
-    Contains the synthesized analysis across all agents.
-    """
-
-    overall_score: float = Field(
-        ...,
-        ge=0.0,
-        le=100.0,
-        description="Overall audit score (0-100)",
-    )
-    maturity_level: str = Field(
-        ...,
-        description="Maturity level: Initial, Repeatable, Defined, Managed, Optimizing",
-    )
-    gaps: list[GapSummary] = Field(
-        default_factory=list,
-        description="Consolidated list of gaps across all agents",
-    )
-    aligned_practices: list[dict[str, Any]] = Field(
-        default_factory=list,
-        description="Consolidated list of aligned practices",
-    )
-    recommendations: list[dict[str, Any]] = Field(
-        default_factory=list,
-        description="Prioritized recommendations for improvement",
-    )
-    confidence: float = Field(
-        default=0.8,
-        ge=0.0,
-        le=1.0,
-        description="Confidence level of the synthesis (0-1)",
-    )
-    executive_summary: str = Field(
-        "",
-        description="Executive summary of audit findings",
-    )
-    component_scores: dict[str, float] = Field(
-        default_factory=dict,
-        description="Individual scores from each agent (code, docs, security)",
-    )
-    cross_cutting_concerns: list[dict[str, Any]] = Field(
-        default_factory=list,
-        description="Cross-cutting concerns identified across multiple agents",
-    )
-
-    @property
-    def maturity_level_enum(self) -> MaturityLevel:
-        """Convert maturity level string to MaturityLevel enum."""
-        level_map = {
-            "initial": MaturityLevel.INITIAL,
-            "repeatable": MaturityLevel.REPEATABLE,
-            "defined": MaturityLevel.DEFINED,
-            "managed": MaturityLevel.MANAGED,
-            "optimizing": MaturityLevel.OPTIMIZING,
-        }
-        return level_map.get(self.maturity_level.lower(), MaturityLevel.INITIAL)
-
-    @property
-    def agent_scores(self) -> dict[str, float]:
-        """Get component scores as a dictionary."""
-        return dict(self.component_scores)
-
-    @property
-    def critical_gaps(self) -> list[dict[str, Any]]:
-        """Get critical gaps as a list of dictionaries."""
-        gaps: list[dict[str, Any]] = []
-        for gap in self.gaps:
-            payload = gap.model_dump()
-            payload.setdefault("type", gap.category)
-            gaps.append(payload)
-        return gaps
-
-    def to_dict(self) -> dict[str, Any]:
-        """Return a dictionary representation of the synthesis result."""
-        return {
-            "overall_score": self.overall_score,
-            "maturity_level": self.maturity_level,
-            "agent_scores": self.agent_scores,
-            "critical_gaps": self.critical_gaps,
-            "aligned_practices": list(self.aligned_practices),
-            "recommendations": list(self.recommendations),
-            "executive_summary": self.executive_summary,
-            "cross_cutting_concerns": list(self.cross_cutting_concerns),
-        }
-
-    @property
-    def critical_gap_count(self) -> int:
-        """Count of critical gaps."""
-        return sum(1 for g in self.gaps if g.severity.lower() == "critical")
-
-    @property
-    def has_blocking_issues(self) -> bool:
-        """Check if there are blocking issues (critical gaps)."""
-        return self.critical_gap_count > 0
-
-
-# =============================================================================
-# Helper Functions
-# =============================================================================
-
-
-def _build_model(llm_config: LLMConfig, model_name: str) -> Any:
-    """Create a PydanticAI model instance from configuration.
-
-    Args:
-        llm_config: LLM configuration.
-        model_name: Name of the model to instantiate.
-
-    Returns:
-        PydanticAI model instance.
-
-    Raises:
-        ValueError: If provider is unsupported or API key is missing.
-    """
-    from pydantic_ai.models.anthropic import AnthropicModel
-    from pydantic_ai.models.openai import OpenAIChatModel, OpenAIResponsesModel
-    from pydantic_ai.providers.openai import OpenAIProvider
-
-    protocol = llm_config.protocol
-    protocol_value = _protocol_value(protocol)
-    if protocol_value == "gemini":
-        from pydantic_ai.models.google import GoogleModel
-        from pydantic_ai.providers.google import GoogleProvider
-
-        api_key = _resolve_api_key(llm_config, protocol)
-        provider = GoogleProvider(
-            api_key=api_key,
-            base_url=_resolve_base_url(llm_config, protocol),
-            http_client=_build_provider_http_client(llm_config),
-        )
-        return GoogleModel(model_name, provider=provider)
-
-    if protocol_value == "anthropic":
-        from pydantic_ai.providers.anthropic import AnthropicProvider
-
-        from vds_audit_orchestrator.llm.provider import should_suppress_anthropic_tool_choice
-
-        api_key = _resolve_api_key(llm_config, protocol)
-        base_url = _resolve_base_url(llm_config, protocol)
-        provider = AnthropicProvider(
-            api_key=api_key,
-            base_url=base_url,
-            http_client=_build_provider_http_client(llm_config),
-        )
-        if should_suppress_anthropic_tool_choice(base_url, protocol):
-            provider_client = getattr(provider, "client", None)
-            if provider_client is not None:
-                provider_client.auth_token = None
-        return AnthropicModel(model_name, provider=provider)
-    if _is_openai_codex_protocol(protocol):
-        from openai import AsyncOpenAI
-
-        try:
-            from vds_audit_orchestrator.llm.codex_oauth import get_codex_credentials
-        except ImportError as exc:  # pragma: no cover - guarded by protocol path
-            raise RuntimeError("openai-codex protocol requires llm.codex_oauth.get_codex_credentials") from exc
-
-        base_url = _resolve_base_url(llm_config, protocol)
-        if not base_url:
-            raise ValueError("openai-codex protocol requires VDS_AUDIT_LLM__BASE_URL")
-        credentials = get_codex_credentials()
-        access_token = _resolve_codex_access_token(credentials)
-        chatgpt_account_id = _resolve_codex_account_id(credentials)
-        _warn_if_unvalidated_codex_model(model_name)
-        default_headers = {"ChatGPT-Account-Id": chatgpt_account_id} if chatgpt_account_id else None
-        openai_client = AsyncOpenAI(
-            api_key=access_token,
-            base_url=base_url,
-            default_headers=default_headers,
-        )
-        provider = OpenAIProvider(openai_client=openai_client)
-        return OpenAIResponsesModel(model_name, provider=provider, settings={"openai_store": False})
-    if protocol_value == "openai":
-        base_url = _resolve_base_url(llm_config, protocol)
-        provider = OpenAIProvider(api_key=_resolve_api_key_or_dummy(llm_config), base_url=base_url)
-        return OpenAIChatModel(model_name, provider=provider)
-    raise ValueError(f"Unsupported protocol: {protocol_value or protocol}")
-
-
-def _load_mcp_config(path: str) -> dict[str, Any]:
-    """Load MCP configuration from file.
-
-    Args:
-        path: Path to MCP config file (YAML or JSON).
-
-    Returns:
-        Parsed configuration dictionary.
-
-    Raises:
-        FileNotFoundError: If config file doesn't exist.
-    """
-    config_path = Path(path)
-    if not config_path.exists():
-        raise FileNotFoundError(f"MCP config not found: {config_path}")
-    if config_path.suffix in {".yaml", ".yml"}:
-        import yaml
-
-        return dict(yaml.safe_load(config_path.read_text(encoding="utf-8")) or {})
-    import json
-
-    return dict(json.loads(config_path.read_text(encoding="utf-8")))
-
-
-def _build_toolsets(llm_config: LLMConfig) -> list[Any]:
-    """Build toolsets from LLM configuration.
-
-    Args:
-        llm_config: LLM configuration with toolset settings.
-
-    Returns:
-        List of configured toolsets.
-
-    Raises:
-        ValueError: If required configuration is missing.
-    """
-    toolsets: list[Any] = []
-
-    if llm_config.mcp_toolsets_enabled:
-        if not llm_config.mcp_config_path:
-            raise ValueError("mcp_config_path is required when mcp_toolsets_enabled is true")
-        try:
-            mcp_config = _load_mcp_config(llm_config.mcp_config_path)
-            if llm_config.mcp_toolset_type == "fastmcp":
-                from pydantic_ai.toolsets.fastmcp import FastMCPToolset
-
-                toolsets.append(FastMCPToolset(mcp_config))
-            elif llm_config.mcp_toolset_type == "mcp":
-                toolsets.extend(_build_mcp_servers(mcp_config))
-            else:
-                raise ValueError(f"Unknown mcp_toolset_type: {llm_config.mcp_toolset_type}")
-        except Exception as exc:
-            logger.warning(
-                "mcp_toolset_build_failed",
-                toolset_type=llm_config.mcp_toolset_type,
-                config_path=llm_config.mcp_config_path,
-                error=str(exc),
-            )
-
-    if llm_config.skills_toolset_enabled:
-        try:
-            toolsets.append(_build_skills_toolset(llm_config))
-        except Exception as exc:
-            logger.warning(
-                "skills_toolset_build_failed",
-                directories=llm_config.skills_directories,
-                error=str(exc),
-            )
-
-    return toolsets
-
-
-# =============================================================================
-# Output Validator
-# =============================================================================
-
-
-def validate_confidence(output: Any, min_confidence: float = 0.4) -> None:
-    """Validate that output has sufficient confidence.
-
-    This validator is used by the agent factory to ensure outputs meet
-    minimum confidence thresholds before being accepted.
-
-    Args:
-        output: The output object to validate.
-        min_confidence: Minimum acceptable confidence (default: 0.4).
-
-    Raises:
-        ModelRetry: If confidence is below threshold.
-    """
-    from pydantic_ai import ModelRetry
-
-    confidence = getattr(output, "confidence", None)
-    if confidence is not None and confidence < min_confidence:
-        raise ModelRetry(
-            f"Low confidence output ({confidence:.2f} < {min_confidence}); "
-            "retry with more detailed analysis or additional evidence."
-        )
-
-
-def _build_mcp_servers(config: dict[str, Any]) -> list[Any]:
-    """Build MCP toolset servers from config.
-
-    Prefers MCPServer if available, otherwise creates individual server instances.
-    """
-    try:
-        from pydantic_ai.mcp import MCPServer
-    except Exception:
-        MCPServer = None
-
-    if MCPServer is not None:
-        import inspect
-
-        if inspect.isabstract(MCPServer):
-            MCPServer = None
-
-    # PydanticAI < 0.0.24 used MCPServer(config). Newer versions are abstract.
-    # We skip direct instantiation if abstract.
-    if MCPServer is not None:
-        return [MCPServer(config)]  # type: ignore[abstract, arg-type]
-
-    from pydantic_ai.mcp import MCPServerSSE, MCPServerStdio, MCPServerStreamableHTTP
-
-    servers = config.get("mcpServers", {})
-    toolsets: list[Any] = []
-    for _name, server in servers.items():
-        if not isinstance(server, dict):
-            continue
-        url = server.get("url")
-        if url:
-            if str(url).rstrip("/").endswith("/sse"):
-                toolsets.append(MCPServerSSE(url))
-            else:
-                toolsets.append(MCPServerStreamableHTTP(url))
-            continue
-        command = server.get("command")
-        if command:
-            toolsets.append(
-                MCPServerStdio(
-                    command=command,
-                    args=list(server.get("args", [])),
-                    env=dict(server.get("env", {})),
-                )
-            )
-    return toolsets
-
-
-def _build_skills_toolset(llm_config: LLMConfig) -> Any:
-    resolved_directories: list[str] = []
-    seen: set[str] = set()
-
-    def _append_if_valid(raw_path: str) -> None:
-        value = str(raw_path).strip()
-        if not value:
-            return
-        try:
-            resolved = str(Path(value).expanduser().resolve(strict=False))
-        except Exception:
-            resolved = value
-        if resolved in seen:
-            return
-        seen.add(resolved)
-        if Path(resolved).is_dir():
-            resolved_directories.append(resolved)
-
-    for raw_path in list(llm_config.skills_directories or []):
-        _append_if_valid(str(raw_path))
-
-    if not resolved_directories:
-        try:
-            from vds_audit_orchestrator.agents.toolsets.skills_toolset import DEFAULT_AUDIT_SKILLS
-        except Exception:
-            DEFAULT_AUDIT_SKILLS = []
-        for raw_path in list(DEFAULT_AUDIT_SKILLS or []):
-            _append_if_valid(str(raw_path))
-
-    if not resolved_directories:
-        raise ValueError("skills_directories is required when skills_toolset_enabled is true")
-    from vds_audit_orchestrator.agents.toolsets import (
-        SkillsToolsetConfig,
-        create_skills_toolset_from_config,
-    )
-
-    toolset_config = SkillsToolsetConfig(
-        directories=resolved_directories,
-        allowlist=llm_config.skills_allowlist,
-        allow_script_execution=llm_config.skills_allow_script_execution,
-        allowed_trust_tiers=llm_config.skills_allowed_trust_tiers,
-        default_trust_tier=llm_config.skills_default_trust_tier,
-        trust_tiers=llm_config.skills_trust_tiers,
-    )
-    return create_skills_toolset_from_config(toolset_config)
-
-
-def _attach_toolset_instructions(_agent: Any, toolsets: list[Any]) -> None:
-    for toolset in toolsets:
-        get_instructions = getattr(toolset, "get_instructions", None)
-        if get_instructions is None:
-            continue
-
-        # We attach the instructions directly to the agent instance
-        # This part depends on how PydanticAI exposes instruction hooking
-        # For now, we assume agent.instructions is a decorator
-        pass
-
-
-# =============================================================================
-# Agent Factory
-# =============================================================================
-
-
-def create_audit_agent[OutputType](
-    name: str,
-    output_type: type[OutputType],
-    system_prompt: str,
-    model: str | None = None,  # Use config.model_standard if None
-    retries: int = 2,
-    output_retries: int = 2,
-) -> Any:
-    """Create a configured PydanticAI Agent for audit tasks.
-
-    This is the primary factory function for creating audit agents. It provides
-    standardized configuration including:
-    - Dependency injection via AuditDeps
-    - Automatic output validation with confidence checking
-    - Configurable retry logic
-        - Model selection based on protocol prefix
-
-    Args:
-        name: Name identifier for the agent.
-        output_type: Pydantic model class for structured output.
-        system_prompt: System prompt/instructions for the agent.
-            model: Model identifier (e.g., "anthropic:claude-sonnet-4-5").
-            If None, uses model_standard from the effective audit config file resolved through the shared VDS path/config layer.
-            Supports prefixes: anthropic:, openai:, gemini:
-        retries: Number of retries for failed requests (default: 2).
-        output_retries: Number of retries for output validation failures (default: 2).
-
-    Returns:
-        Configured PydanticAI Agent instance.
-
-    Example:
-        ```python
-        from vds_audit_orchestrator.agents.pydantic_base import (
-            create_audit_agent,
-            AuditDeps,
-            CodeFindings,
-        )
-
-        # Uses model from config
-        code_agent = create_audit_agent(
-            name="code_analysis",
-            output_type=CodeFindings,
-            system_prompt="Analyze code quality and security...",
-        )
-
-        deps = AuditDeps(
-            profile={"domain": "insurance"},
-            evidence={"files": [...]},
-            repo_path="/path/to/repo",
-            project_id="my-service",
-        )
-
-        result = await code_agent.run("Analyze the codebase", deps=deps)
-        print(result.output.score)
-        ```
-    """
-    from pydantic_ai import Agent
-    from pydantic_ai.settings import ModelSettings
-
-    config = get_config().llm
-
-    # Use config model_standard if no model specified
-    if model is None:
-        model = config.model_standard
-        protocol_prefix = config.protocol.value
-        model_name = model
-    elif ":" in model:
-        protocol_prefix, model_name = model.split(":", 1)
-    else:
-        protocol_prefix = "anthropic"
-        model_name = model
-
-    # Build model based on protocol prefix
-    protocol_map = {
-        "anthropic": LLMProtocolType.ANTHROPIC,
-        "openai": LLMProtocolType.OPENAI,
-        "gemini": LLMProtocolType.GEMINI,
-        OPENAI_CODEX_PROTOCOL: getattr(LLMProtocolType, "OPENAI_CODEX", OPENAI_CODEX_PROTOCOL),
-    }
-
-    # Override config protocol temporarily for model building
-    original_protocol = config.protocol
-    selected_protocol = protocol_map.get(protocol_prefix, original_protocol)
-    if protocol_prefix in protocol_map:
-        config.protocol = selected_protocol
-
-    try:
-        pydantic_model = _build_model(config, cast("str", model_name))
-    finally:
-        config.protocol = original_protocol
-
-    # Build toolsets
-    toolsets = _build_toolsets(config)
-
-    # Create agent
-    model_settings: dict[str, Any] = {
-        "temperature": 0.0,
-        "max_tokens": config.max_tokens_per_request,
-    }
-    from vds_audit_orchestrator.config import inject_reasoning_effort
-
-    inject_reasoning_effort(model_settings, config.reasoning_effort, selected_protocol)
-    extra_body = _build_structured_output_extra_body_for_protocol(getattr(config, "base_url", None), selected_protocol)
-    if extra_body is not None:
-        model_settings["extra_body"] = extra_body
-    if _is_openai_codex_protocol(selected_protocol):
-        model_settings["openai_store"] = False
-
-    agent = Agent(
-        model=pydantic_model,
-        name=name,
-        deps_type=AuditDeps,
-        output_type=output_type,
-        instructions=system_prompt,
-        tools=[],
-        toolsets=toolsets,
-        retries=retries,
-        output_retries=output_retries,
-        model_settings=ModelSettings(**model_settings),
-    )
-
-    _attach_toolset_instructions(agent, toolsets)
-
-    return agent
-
-
-def build_deps(
-    *,
-    evidence: EvidenceBundle | None = None,
-    profile: dict[str, Any] | None = None,
-    settings: LLMConfig | None = None,
-    repo_path: str = "",
-    project_id: str = "",
-    evidence_corpus: EvidenceCorpus | None = None,
-) -> AuditDeps:
-    """Build AuditDeps with current config defaults.
-
-    Args:
-        evidence: Optional evidence bundle.
-        profile: Optional project profile dictionary.
-        settings: Optional LLM configuration.
-        repo_path: Path to the repository.
-        project_id: Project identifier.
-
-    Returns:
-        Configured AuditDeps instance.
-    """
-    evidence_dict = evidence.model_dump() if evidence else {}
-    settings_dict = safe_dump(settings) if settings else safe_dump(get_config().llm)
-    return AuditDeps(
-        evidence=evidence_dict,
-        profile=profile or {},
-        settings=settings_dict,
-        repo_path=repo_path or evidence_dict.get("repository", ""),
-        project_id=project_id or evidence_dict.get("repository", ""),
-        evidence_corpus=evidence_corpus,
-    )