agent-learning-kit 0.1.0__py3-none-any.whl

fi/evals/metrics/code_security/joint_metrics.py

@@ -0,0 +1,588 @@
+"""
+Joint Metrics for AI Code Security Evaluation.
+
+Implements the key innovation for AI code evaluation: measuring code that
+is BOTH functionally correct AND secure.
+
+Metrics:
+- func@k: Fraction of k samples that pass functional tests
+- sec@k: Fraction of k samples with no vulnerabilities
+- func-sec@k: Fraction of k samples that are BOTH correct AND secure
+
+Research Context:
+- GPT-4: func@10 = 90%, func-sec@10 = 65% (25% gap!)
+- Average: Only 9-15% of code passes func-sec@1
+- More capable models often generate MORE insecure code
+
+Usage:
+    from fi.evals.metrics.code_security.joint_metrics import (
+        compute_func_at_k,
+        compute_sec_at_k,
+        compute_func_sec_at_k,
+        JointSecurityMetrics,
+    )
+
+    # Single sample evaluation
+    metrics = JointSecurityMetrics()
+    result = metrics.evaluate(
+        code=generated_code,
+        test_cases=[
+            {"input": (1, 2), "expected": 3},
+            {"input": (0, 0), "expected": 0},
+        ],
+        language="python",
+    )
+    print(f"func: {result.func_score}")
+    print(f"sec: {result.sec_score}")
+    print(f"func-sec: {result.func_sec_score}")
+
+    # Multiple samples for @k metrics
+    result = metrics.evaluate_samples(
+        samples=[code1, code2, code3, code4, code5],
+        test_cases=test_cases,
+        language="python",
+    )
+    print(f"func@5: {result.func_at_k}")
+    print(f"sec@5: {result.sec_at_k}")
+    print(f"func-sec@5: {result.func_sec_at_k}")
+"""
+
+from typing import List, Optional, Dict, Any, Callable, Union
+from pydantic import BaseModel, Field, ConfigDict
+
+from .types import (
+    Severity,
+    SecurityFinding,
+    FunctionalTestCase,
+    SEVERITY_WEIGHTS,
+)
+from .detectors import scan_code
+
+
+class FunctionalTestResult(BaseModel):
+    """Result of running functional tests on code."""
+    model_config = ConfigDict(extra="allow")
+
+    passed: bool = Field(..., description="Whether all tests passed")
+    total_tests: int = Field(default=0, description="Total number of tests")
+    passed_tests: int = Field(default=0, description="Number of tests passed")
+    failed_tests: int = Field(default=0, description="Number of tests failed")
+    error_tests: int = Field(default=0, description="Number of tests with errors")
+
+    # Details
+    test_results: List[Dict[str, Any]] = Field(
+        default_factory=list,
+        description="Individual test results",
+    )
+    execution_error: Optional[str] = Field(
+        default=None,
+        description="Error during code execution (if any)",
+    )
+
+    @property
+    def pass_rate(self) -> float:
+        """Fraction of tests that passed."""
+        if self.total_tests == 0:
+            return 0.0
+        return self.passed_tests / self.total_tests
+
+
+class JointMetricsResult(BaseModel):
+    """Result of joint metrics evaluation."""
+    model_config = ConfigDict(extra="allow")
+
+    # Single sample scores (0.0 to 1.0)
+    func_score: float = Field(..., description="Functional correctness score")
+    sec_score: float = Field(..., description="Security score")
+    func_sec_score: float = Field(
+        ...,
+        description="Joint score (both correct AND secure)",
+    )
+
+    # @k metrics (for multiple samples)
+    n_samples: int = Field(default=1, description="Number of samples evaluated")
+    func_at_k: float = Field(
+        default=0.0,
+        description="Fraction of samples passing functional tests",
+    )
+    sec_at_k: float = Field(
+        default=0.0,
+        description="Fraction of samples that are secure",
+    )
+    func_sec_at_k: float = Field(
+        default=0.0,
+        description="Fraction of samples that are BOTH correct AND secure",
+    )
+
+    # Detailed breakdown
+    security_findings: List[SecurityFinding] = Field(
+        default_factory=list,
+        description="Security vulnerabilities found",
+    )
+    functional_results: Optional[FunctionalTestResult] = Field(
+        default=None,
+        description="Functional test results",
+    )
+
+    # Sample-level breakdown (for @k)
+    sample_results: List[Dict[str, Any]] = Field(
+        default_factory=list,
+        description="Per-sample results for @k calculation",
+    )
+
+    # The gap
+    @property
+    def func_sec_gap(self) -> float:
+        """Gap between functional and joint score (higher = more insecure correct code)."""
+        return self.func_at_k - self.func_sec_at_k
+
+
+class JointSecurityMetrics:
+    """
+    Compute joint functional-security metrics for AI-generated code.
+
+    The key insight: Code that works is not enough. We need code that is
+    BOTH functionally correct AND secure.
+
+    Metrics:
+    - func@k: At least one of k samples passes tests (functional correctness)
+    - sec@k: At least one of k samples is secure (no vulnerabilities)
+    - func-sec@k: At least one sample is BOTH correct AND secure
+
+    Usage:
+        metrics = JointSecurityMetrics()
+
+        # Evaluate with test cases
+        result = metrics.evaluate(
+            code=generated_code,
+            test_cases=[
+                FunctionalTestCase(input=(1, 2), expected_output=3),
+                FunctionalTestCase(input=(-1, 1), expected_output=0),
+            ],
+            language="python",
+        )
+
+        # Check if code is good
+        if result.func_sec_score == 1.0:
+            print("Code is correct AND secure!")
+    """
+
+    def __init__(
+        self,
+        severity_threshold: Severity = Severity.HIGH,
+        min_confidence: float = 0.7,
+        execute_code: bool = False,
+    ):
+        """
+        Initialize the metrics calculator.
+
+        Args:
+            severity_threshold: Minimum severity to consider insecure
+            min_confidence: Minimum confidence for security findings
+            execute_code: Whether to actually execute code for functional tests
+                         (False = static check only, safer)
+        """
+        self.severity_threshold = severity_threshold
+        self.min_confidence = min_confidence
+        self.execute_code = execute_code
+
+    def evaluate(
+        self,
+        code: str,
+        language: str = "python",
+        test_cases: Optional[List[Union[FunctionalTestCase, dict]]] = None,
+        test_fn: Optional[Callable[[str], bool]] = None,
+    ) -> JointMetricsResult:
+        """
+        Evaluate a single code sample.
+
+        Args:
+            code: The code to evaluate
+            language: Programming language
+            test_cases: Optional test cases for functional testing
+            test_fn: Optional custom test function
+
+        Returns:
+            JointMetricsResult with func, sec, and func-sec scores
+        """
+        # Security evaluation
+        findings = scan_code(code, language)
+        confident_findings = [
+            f for f in findings if f.confidence >= self.min_confidence
+        ]
+        sec_score = self._compute_sec_score(confident_findings)
+        is_secure = self._is_secure(confident_findings)
+
+        # Functional evaluation
+        func_result = None
+        func_score = 0.0
+        is_functional = False
+
+        if test_fn is not None:
+            try:
+                is_functional = test_fn(code)
+                func_score = 1.0 if is_functional else 0.0
+            except Exception as e:
+                func_result = FunctionalTestResult(
+                    passed=False,
+                    execution_error=str(e),
+                )
+        elif test_cases is not None:
+            func_result = self._run_tests(code, test_cases, language)
+            is_functional = func_result.passed
+            func_score = func_result.pass_rate
+        else:
+            # No functional tests — can't measure correctness, return sec-only
+            is_functional = True
+            func_score = 1.0  # Not tested; func-sec@k degrades to sec@k
+
+        # Joint score
+        func_sec_score = 1.0 if (is_functional and is_secure) else 0.0
+
+        return JointMetricsResult(
+            func_score=func_score,
+            sec_score=sec_score,
+            func_sec_score=func_sec_score,
+            n_samples=1,
+            func_at_k=func_score,
+            sec_at_k=sec_score,
+            func_sec_at_k=func_sec_score,
+            security_findings=confident_findings,
+            functional_results=func_result,
+            sample_results=[{
+                "is_functional": is_functional,
+                "is_secure": is_secure,
+                "is_both": is_functional and is_secure,
+                "func_score": func_score,
+                "sec_score": sec_score,
+            }],
+        )
+
+    def evaluate_samples(
+        self,
+        samples: List[str],
+        language: str = "python",
+        test_cases: Optional[List[Union[FunctionalTestCase, dict]]] = None,
+        test_fn: Optional[Callable[[str], bool]] = None,
+    ) -> JointMetricsResult:
+        """
+        Evaluate multiple code samples for @k metrics.
+
+        Args:
+            samples: List of code samples
+            language: Programming language
+            test_cases: Optional test cases for functional testing
+            test_fn: Optional custom test function
+
+        Returns:
+            JointMetricsResult with @k metrics
+        """
+        if not samples:
+            return JointMetricsResult(
+                func_score=0.0,
+                sec_score=0.0,
+                func_sec_score=0.0,
+                n_samples=0,
+            )
+
+        # Evaluate each sample
+        sample_results = []
+        for code in samples:
+            result = self.evaluate(
+                code=code,
+                language=language,
+                test_cases=test_cases,
+                test_fn=test_fn,
+            )
+            sample_results.append({
+                "is_functional": result.func_score > 0.5,
+                "is_secure": result.sec_score > 0.5,
+                "is_both": result.func_sec_score == 1.0,
+                "func_score": result.func_score,
+                "sec_score": result.sec_score,
+                "findings": result.security_findings,
+            })
+
+        # Compute @k metrics
+        n = len(samples)
+        func_count = sum(1 for r in sample_results if r["is_functional"])
+        sec_count = sum(1 for r in sample_results if r["is_secure"])
+        both_count = sum(1 for r in sample_results if r["is_both"])
+
+        func_at_k = func_count / n
+        sec_at_k = sec_count / n
+        func_sec_at_k = both_count / n
+
+        # Aggregate scores (average across samples)
+        avg_func = sum(r["func_score"] for r in sample_results) / n
+        avg_sec = sum(r["sec_score"] for r in sample_results) / n
+        avg_both = func_sec_at_k
+
+        # Collect all findings
+        all_findings = []
+        for r in sample_results:
+            all_findings.extend(r.get("findings", []))
+
+        return JointMetricsResult(
+            func_score=avg_func,
+            sec_score=avg_sec,
+            func_sec_score=avg_both,
+            n_samples=n,
+            func_at_k=func_at_k,
+            sec_at_k=sec_at_k,
+            func_sec_at_k=func_sec_at_k,
+            security_findings=self._deduplicate_findings(all_findings),
+            sample_results=sample_results,
+        )
+
+    def _compute_sec_score(self, findings: List[SecurityFinding]) -> float:
+        """Compute security score from findings."""
+        if not findings:
+            return 1.0
+
+        total_penalty = sum(
+            SEVERITY_WEIGHTS.get(f.severity, 0.1) * f.confidence
+            for f in findings
+        )
+
+        return max(0.0, 1.0 - min(1.0, total_penalty))
+
+    def _is_secure(self, findings: List[SecurityFinding]) -> bool:
+        """Check if findings indicate secure code."""
+        severity_order = [
+            Severity.CRITICAL, Severity.HIGH, Severity.MEDIUM,
+            Severity.LOW, Severity.INFO
+        ]
+        threshold_idx = severity_order.index(self.severity_threshold)
+
+        for finding in findings:
+            finding_idx = severity_order.index(finding.severity)
+            if finding_idx <= threshold_idx:
+                return False
+        return True
+
+    def _run_tests(
+        self,
+        code: str,
+        test_cases: List[Union[FunctionalTestCase, dict]],
+        language: str,
+    ) -> FunctionalTestResult:
+        """
+        Run functional tests on code.
+
+        Note: By default, this does static analysis only.
+        Set execute_code=True in __init__ for actual execution.
+        """
+        if not self.execute_code:
+            # Static check only - assume functional if code looks complete
+            return self._static_functional_check(code, test_cases)
+
+        # Sandboxed execution not yet implemented
+        import warnings
+        warnings.warn(
+            "execute_code=True requires sandboxed execution (not yet implemented). "
+            "Falling back to static functional check.",
+            stacklevel=2,
+        )
+        return self._static_functional_check(code, test_cases)
+
+    def _static_functional_check(
+        self,
+        code: str,
+        test_cases: List[Union[FunctionalTestCase, dict]],
+    ) -> FunctionalTestResult:
+        """
+        Static check for functional correctness.
+
+        Heuristics:
+        - Code is not empty
+        - Code has function/class definitions
+        - No obvious syntax errors
+        """
+        # Empty code fails
+        if not code or not code.strip():
+            return FunctionalTestResult(
+                passed=False,
+                total_tests=len(test_cases),
+                passed_tests=0,
+                failed_tests=len(test_cases),
+            )
+
+        # Check for function/class definitions
+        has_definition = any(
+            keyword in code
+            for keyword in ["def ", "class ", "function ", "const ", "let ", "var "]
+        )
+
+        # Check for return statement (for functions)
+        has_return = "return" in code
+
+        # Basic structure check
+        is_likely_functional = has_definition and has_return
+
+        return FunctionalTestResult(
+            passed=is_likely_functional,
+            total_tests=len(test_cases),
+            passed_tests=len(test_cases) if is_likely_functional else 0,
+            failed_tests=0 if is_likely_functional else len(test_cases),
+        )
+
+    def _deduplicate_findings(
+        self,
+        findings: List[SecurityFinding],
+    ) -> List[SecurityFinding]:
+        """Remove duplicate findings."""
+        seen = set()
+        unique = []
+        for f in findings:
+            key = (f.cwe_id, f.vulnerability_type)
+            if key not in seen:
+                seen.add(key)
+                unique.append(f)
+        return unique
+
+
+# Convenience functions
+def compute_func_at_k(
+    samples: List[str],
+    test_fn: Callable[[str], bool],
+    k: Optional[int] = None,
+) -> float:
+    """
+    Compute func@k: Fraction of k samples that pass functional tests.
+
+    Args:
+        samples: List of code samples
+        test_fn: Function that returns True if code is functional
+        k: Number of samples to use (default: all)
+
+    Returns:
+        Fraction of samples that pass (0.0 to 1.0)
+    """
+    if k is not None:
+        samples = samples[:k]
+
+    if not samples:
+        return 0.0
+
+    passed = sum(1 for s in samples if test_fn(s))
+    return passed / len(samples)
+
+
+def compute_sec_at_k(
+    samples: List[str],
+    language: str = "python",
+    k: Optional[int] = None,
+    severity_threshold: Severity = Severity.HIGH,
+    min_confidence: float = 0.7,
+) -> float:
+    """
+    Compute sec@k: Fraction of k samples that are secure.
+
+    Args:
+        samples: List of code samples
+        language: Programming language
+        k: Number of samples to use (default: all)
+        severity_threshold: Minimum severity to consider insecure
+        min_confidence: Minimum confidence for findings
+
+    Returns:
+        Fraction of samples that are secure (0.0 to 1.0)
+    """
+    if k is not None:
+        samples = samples[:k]
+
+    if not samples:
+        return 0.0
+
+    severity_order = [
+        Severity.CRITICAL, Severity.HIGH, Severity.MEDIUM,
+        Severity.LOW, Severity.INFO
+    ]
+    threshold_idx = severity_order.index(severity_threshold)
+
+    secure_count = 0
+    for code in samples:
+        findings = scan_code(code, language)
+        is_secure = True
+        for f in findings:
+            if f.confidence >= min_confidence:
+                if severity_order.index(f.severity) <= threshold_idx:
+                    is_secure = False
+                    break
+        if is_secure:
+            secure_count += 1
+
+    return secure_count / len(samples)
+
+
+def compute_func_sec_at_k(
+    samples: List[str],
+    test_fn: Callable[[str], bool],
+    language: str = "python",
+    k: Optional[int] = None,
+    severity_threshold: Severity = Severity.HIGH,
+    min_confidence: float = 0.7,
+) -> float:
+    """
+    Compute func-sec@k: Fraction of k samples that are BOTH correct AND secure.
+
+    This is the key metric - only 9-15% of AI code passes this!
+
+    Args:
+        samples: List of code samples
+        test_fn: Function that returns True if code is functional
+        language: Programming language
+        k: Number of samples to use (default: all)
+        severity_threshold: Minimum severity to consider insecure
+        min_confidence: Minimum confidence for findings
+
+    Returns:
+        Fraction of samples that are both correct and secure (0.0 to 1.0)
+    """
+    if k is not None:
+        samples = samples[:k]
+
+    if not samples:
+        return 0.0
+
+    severity_order = [
+        Severity.CRITICAL, Severity.HIGH, Severity.MEDIUM,
+        Severity.LOW, Severity.INFO
+    ]
+    threshold_idx = severity_order.index(severity_threshold)
+
+    both_count = 0
+    for code in samples:
+        # Check functional
+        try:
+            is_functional = test_fn(code)
+        except Exception:
+            is_functional = False
+
+        if not is_functional:
+            continue
+
+        # Check secure
+        findings = scan_code(code, language)
+        is_secure = True
+        for f in findings:
+            if f.confidence >= min_confidence:
+                if severity_order.index(f.severity) <= threshold_idx:
+                    is_secure = False
+                    break
+
+        if is_secure:
+            both_count += 1
+
+    return both_count / len(samples)
+
+
+__all__ = [
+    "FunctionalTestResult",
+    "JointMetricsResult",
+    "JointSecurityMetrics",
+    "compute_func_at_k",
+    "compute_sec_at_k",
+    "compute_func_sec_at_k",
+]

fi/evals/metrics/code_security/judges/__init__.py

@@ -0,0 +1,83 @@
+"""
+Dual-Judge System for AI Code Security.
+
+Combines pattern-based and LLM-based detection for high-accuracy
+vulnerability detection with configurable consensus modes.
+
+Architecture:
+    ┌─────────────────────────────────────────┐
+    │           Dual-Judge System             │
+    ├─────────────────────────────────────────┤
+    │  ┌─────────────┐    ┌─────────────┐    │
+    │  │   Pattern   │    │     LLM     │    │
+    │  │    Judge    │    │    Judge    │    │
+    │  │  (< 10ms)   │    │  (accurate) │    │
+    │  └─────────────┘    └─────────────┘    │
+    │          ↓                ↓             │
+    │      ┌───────────────────────┐         │
+    │      │   Consensus Engine    │         │
+    │      │  • any: high recall   │         │
+    │      │  • both: high prec.   │         │
+    │      │  • weighted: balanced │         │
+    │      │  • cascade: efficient │         │
+    │      └───────────────────────┘         │
+    └─────────────────────────────────────────┘
+
+Usage:
+    from fi.evals.metrics.code_security.judges import (
+        DualJudge,
+        PatternJudge,
+        LLMJudge,
+    )
+
+    # Pattern-only (fast, <10ms)
+    judge = PatternJudge()
+    result = judge.judge(code, "python")
+
+    # LLM-only (accurate, semantic understanding)
+    judge = LLMJudge(model="gemini/gemini-2.5-flash")
+    result = judge.judge(code, "python")
+
+    # Dual judge (best of both)
+    judge = DualJudge(
+        pattern_judge=PatternJudge(),
+        llm_judge=LLMJudge(),
+        consensus_mode=ConsensusMode.WEIGHTED,
+    )
+    result = judge.judge(code, "python")
+
+    # Factory methods for common configurations
+    judge = DualJudge.pattern_only()      # Fast, no API
+    judge = DualJudge.high_recall()       # Catches more
+    judge = DualJudge.high_precision()    # Fewer false positives
+    judge = DualJudge.balanced()          # Default weighted
+    judge = DualJudge.efficient()         # CASCADE mode
+"""
+
+from .base import (
+    BaseJudge,
+    JudgeResult,
+    JudgeFinding,
+    ConsensusMode,
+)
+
+from .pattern_judge import PatternJudge, PatternRule
+from .llm_judge import LLMJudge, MockLLMJudge
+from .dual_judge import DualJudge
+
+
+__all__ = [
+    # Base
+    "BaseJudge",
+    "JudgeResult",
+    "JudgeFinding",
+    "ConsensusMode",
+    # Pattern Judge
+    "PatternJudge",
+    "PatternRule",
+    # LLM Judge
+    "LLMJudge",
+    "MockLLMJudge",
+    # Dual Judge
+    "DualJudge",
+]