evalwise 0.1.0__py3-none-any.whl

evalwise/text/assertions.py

@@ -0,0 +1,854 @@
+"""
+Text assertions - deterministic checks for LLM text outputs.
+
+These assertions are designed to be:
+1. Deterministic - same input always gives same result
+2. Fast - no LLM calls required
+3. Interpretable - clear pass/fail with explanation
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+from typing import Any
+
+from evalwise.core.context import get_context
+from evalwise.core.result import AssertionResult, Status
+
+
+class Assert:
+    """
+    Deterministic assertions for text outputs.
+    
+    Example:
+        from evalwise import Assert
+        
+        # Basic checks
+        Assert.contains(response, "hello")
+        Assert.word_count(response, min=10, max=100)
+        Assert.json_valid(response)
+        
+        # Factuality
+        Assert.entails(response, source=document)
+        Assert.no_hallucinated_urls(response)
+    """
+    
+    # ==================== Format & Structure ====================
+    
+    @staticmethod
+    def contains(text: str, substring: str, case_sensitive: bool = True) -> bool:
+        """Assert that text contains a substring."""
+        start = time.perf_counter()
+        
+        if case_sensitive:
+            passed = substring in text
+        else:
+            passed = substring.lower() in text.lower()
+        
+        result = AssertionResult(
+            name="contains",
+            status=Status.PASS if passed else Status.FAIL,
+            message=f"Expected to contain: {substring!r}" if not passed else None,
+            expected=substring,
+            actual=text[:200] + "..." if len(text) > 200 else text,
+            duration_ms=(time.perf_counter() - start) * 1000,
+        )
+        get_context().add_assertion(result)
+        return passed
+    
+    @staticmethod
+    def not_contains(text: str, substring: str, case_sensitive: bool = True) -> bool:
+        """Assert that text does NOT contain a substring."""
+        start = time.perf_counter()
+        
+        if case_sensitive:
+            passed = substring not in text
+        else:
+            passed = substring.lower() not in text.lower()
+        
+        result = AssertionResult(
+            name="not_contains",
+            status=Status.PASS if passed else Status.FAIL,
+            message=f"Should not contain: {substring!r}" if not passed else None,
+            expected=f"not {substring!r}",
+            actual=text[:200] + "..." if len(text) > 200 else text,
+            duration_ms=(time.perf_counter() - start) * 1000,
+        )
+        get_context().add_assertion(result)
+        return passed
+    
+    @staticmethod
+    def equals(text: str, expected: str, strip: bool = True) -> bool:
+        """Assert exact string equality."""
+        start = time.perf_counter()
+        
+        actual = text.strip() if strip else text
+        exp = expected.strip() if strip else expected
+        passed = actual == exp
+        
+        result = AssertionResult(
+            name="equals",
+            status=Status.PASS if passed else Status.FAIL,
+            message=f"Expected exact match" if not passed else None,
+            expected=expected,
+            actual=text,
+            duration_ms=(time.perf_counter() - start) * 1000,
+        )
+        get_context().add_assertion(result)
+        return passed
+    
+    @staticmethod
+    def regex(text: str, pattern: str, flags: int = 0) -> bool:
+        """Assert that text matches a regex pattern."""
+        start = time.perf_counter()
+        
+        match = re.search(pattern, text, flags)
+        passed = match is not None
+        
+        result = AssertionResult(
+            name="regex",
+            status=Status.PASS if passed else Status.FAIL,
+            message=f"Pattern not found: {pattern}" if not passed else None,
+            expected=pattern,
+            actual=match.group() if match else None,
+            duration_ms=(time.perf_counter() - start) * 1000,
+        )
+        get_context().add_assertion(result)
+        return passed
+    
+    @staticmethod
+    def starts_with(text: str, prefix: str) -> bool:
+        """Assert that text starts with prefix."""
+        start = time.perf_counter()
+        passed = text.startswith(prefix)
+        
+        result = AssertionResult(
+            name="starts_with",
+            status=Status.PASS if passed else Status.FAIL,
+            message=f"Expected to start with: {prefix!r}" if not passed else None,
+            expected=prefix,
+            actual=text[:len(prefix) + 20],
+            duration_ms=(time.perf_counter() - start) * 1000,
+        )
+        get_context().add_assertion(result)
+        return passed
+    
+    @staticmethod
+    def ends_with(text: str, suffix: str) -> bool:
+        """Assert that text ends with suffix."""
+        start = time.perf_counter()
+        passed = text.endswith(suffix)
+        
+        result = AssertionResult(
+            name="ends_with",
+            status=Status.PASS if passed else Status.FAIL,
+            message=f"Expected to end with: {suffix!r}" if not passed else None,
+            expected=suffix,
+            actual=text[-len(suffix) - 20:],
+            duration_ms=(time.perf_counter() - start) * 1000,
+        )
+        get_context().add_assertion(result)
+        return passed
+    
+    # ==================== JSON & Structured ====================
+    
+    @staticmethod
+    def json_valid(text: str) -> bool:
+        """Assert that text is valid JSON."""
+        start = time.perf_counter()
+        
+        try:
+            json.loads(text)
+            passed = True
+            message = None
+        except json.JSONDecodeError as e:
+            passed = False
+            message = f"Invalid JSON: {e}"
+        
+        result = AssertionResult(
+            name="json_valid",
+            status=Status.PASS if passed else Status.FAIL,
+            message=message,
+            duration_ms=(time.perf_counter() - start) * 1000,
+        )
+        get_context().add_assertion(result)
+        return passed
+    
+    @staticmethod
+    def json_schema(text: str, schema: dict[str, Any]) -> bool:
+        """Assert that JSON text matches a JSON schema."""
+        start = time.perf_counter()
+        
+        try:
+            from jsonschema import validate, ValidationError
+        except ImportError:
+            raise ImportError("jsonschema required: pip install jsonschema")
+        
+        try:
+            data = json.loads(text)
+            validate(instance=data, schema=schema)
+            passed = True
+            message = None
+        except json.JSONDecodeError as e:
+            passed = False
+            message = f"Invalid JSON: {e}"
+        except ValidationError as e:
+            passed = False
+            message = f"Schema validation failed: {e.message}"
+        
+        result = AssertionResult(
+            name="json_schema",
+            status=Status.PASS if passed else Status.FAIL,
+            message=message,
+            expected=schema,
+            duration_ms=(time.perf_counter() - start) * 1000,
+        )
+        get_context().add_assertion(result)
+        return passed
+    
+    @staticmethod
+    def json_has_keys(text: str, keys: list[str]) -> bool:
+        """Assert that JSON object has required keys."""
+        start = time.perf_counter()
+        
+        try:
+            data = json.loads(text)
+            if not isinstance(data, dict):
+                passed = False
+                message = "JSON is not an object"
+                missing = keys
+            else:
+                missing = [k for k in keys if k not in data]
+                passed = len(missing) == 0
+                message = f"Missing keys: {missing}" if missing else None
+        except json.JSONDecodeError as e:
+            passed = False
+            message = f"Invalid JSON: {e}"
+            missing = keys
+        
+        result = AssertionResult(
+            name="json_has_keys",
+            status=Status.PASS if passed else Status.FAIL,
+            message=message,
+            expected=keys,
+            actual=missing if not passed else keys,
+            duration_ms=(time.perf_counter() - start) * 1000,
+        )
+        get_context().add_assertion(result)
+        return passed
+    
+    # ==================== Length & Count ====================
+    
+    @staticmethod
+    def word_count(
+        text: str, 
+        *, 
+        min: int | None = None, 
+        max: int | None = None,
+        exactly: int | None = None,
+    ) -> bool:
+        """Assert word count is within bounds."""
+        start = time.perf_counter()
+        
+        words = len(text.split())
+        
+        if exactly is not None:
+            passed = words == exactly
+            expected = f"exactly {exactly}"
+        elif min is not None and max is not None:
+            passed = min <= words <= max
+            expected = f"{min}-{max}"
+        elif min is not None:
+            passed = words >= min
+            expected = f">= {min}"
+        elif max is not None:
+            passed = words <= max
+            expected = f"<= {max}"
+        else:
+            passed = True
+            expected = "any"
+        
+        result = AssertionResult(
+            name="word_count",
+            status=Status.PASS if passed else Status.FAIL,
+            message=f"Word count {words} not in range {expected}" if not passed else None,
+            expected=expected,
+            actual=words,
+            duration_ms=(time.perf_counter() - start) * 1000,
+        )
+        get_context().add_assertion(result)
+        return passed
+    
+    @staticmethod
+    def char_count(
+        text: str,
+        *,
+        min: int | None = None,
+        max: int | None = None,
+    ) -> bool:
+        """Assert character count is within bounds."""
+        start = time.perf_counter()
+        
+        chars = len(text)
+        
+        if min is not None and max is not None:
+            passed = min <= chars <= max
+            expected = f"{min}-{max}"
+        elif min is not None:
+            passed = chars >= min
+            expected = f">= {min}"
+        elif max is not None:
+            passed = chars <= max
+            expected = f"<= {max}"
+        else:
+            passed = True
+            expected = "any"
+        
+        result = AssertionResult(
+            name="char_count",
+            status=Status.PASS if passed else Status.FAIL,
+            message=f"Char count {chars} not in range {expected}" if not passed else None,
+            expected=expected,
+            actual=chars,
+            duration_ms=(time.perf_counter() - start) * 1000,
+        )
+        get_context().add_assertion(result)
+        return passed
+    
+    @staticmethod
+    def sentence_count(
+        text: str,
+        *,
+        min: int | None = None,
+        max: int | None = None,
+        exactly: int | None = None,
+    ) -> bool:
+        """Assert sentence count is within bounds."""
+        start = time.perf_counter()
+        
+        # Simple sentence splitting on .!?
+        sentences = len(re.findall(r'[.!?]+', text))
+        
+        if exactly is not None:
+            passed = sentences == exactly
+            expected = f"exactly {exactly}"
+        elif min is not None and max is not None:
+            passed = min <= sentences <= max
+            expected = f"{min}-{max}"
+        elif min is not None:
+            passed = sentences >= min
+            expected = f">= {min}"
+        elif max is not None:
+            passed = sentences <= max
+            expected = f"<= {max}"
+        else:
+            passed = True
+            expected = "any"
+        
+        result = AssertionResult(
+            name="sentence_count",
+            status=Status.PASS if passed else Status.FAIL,
+            message=f"Sentence count {sentences} not in range {expected}" if not passed else None,
+            expected=expected,
+            actual=sentences,
+            duration_ms=(time.perf_counter() - start) * 1000,
+        )
+        get_context().add_assertion(result)
+        return passed
+    
+    @staticmethod
+    def line_count(
+        text: str,
+        *,
+        min: int | None = None,
+        max: int | None = None,
+        exactly: int | None = None,
+    ) -> bool:
+        """Assert line count is within bounds."""
+        start = time.perf_counter()
+        
+        lines = len(text.strip().split('\n'))
+        
+        if exactly is not None:
+            passed = lines == exactly
+            expected = f"exactly {exactly}"
+        elif min is not None and max is not None:
+            passed = min <= lines <= max
+            expected = f"{min}-{max}"
+        elif min is not None:
+            passed = lines >= min
+            expected = f">= {min}"
+        elif max is not None:
+            passed = lines <= max
+            expected = f"<= {max}"
+        else:
+            passed = True
+            expected = "any"
+        
+        result = AssertionResult(
+            name="line_count",
+            status=Status.PASS if passed else Status.FAIL,
+            message=f"Line count {lines} not in range {expected}" if not passed else None,
+            expected=expected,
+            actual=lines,
+            duration_ms=(time.perf_counter() - start) * 1000,
+        )
+        get_context().add_assertion(result)
+        return passed
+    
+    @staticmethod
+    def bullet_count(
+        text: str,
+        *,
+        min: int | None = None,
+        max: int | None = None,
+        exactly: int | None = None,
+    ) -> bool:
+        """Assert bullet point count (lines starting with -, *, •, or numbers)."""
+        start = time.perf_counter()
+        
+        bullet_pattern = r'^[\s]*[-*•]|\d+[.\)]'
+        bullets = len(re.findall(bullet_pattern, text, re.MULTILINE))
+        
+        if exactly is not None:
+            passed = bullets == exactly
+            expected = f"exactly {exactly}"
+        elif min is not None and max is not None:
+            passed = min <= bullets <= max
+            expected = f"{min}-{max}"
+        elif min is not None:
+            passed = bullets >= min
+            expected = f">= {min}"
+        elif max is not None:
+            passed = bullets <= max
+            expected = f"<= {max}"
+        else:
+            passed = True
+            expected = "any"
+        
+        result = AssertionResult(
+            name="bullet_count",
+            status=Status.PASS if passed else Status.FAIL,
+            message=f"Bullet count {bullets} not in range {expected}" if not passed else None,
+            expected=expected,
+            actual=bullets,
+            duration_ms=(time.perf_counter() - start) * 1000,
+        )
+        get_context().add_assertion(result)
+        return passed
+    
+    # ==================== Readability ====================
+    
+    @staticmethod
+    def readability(text: str, *, min_score: float | None = None, max_score: float | None = None) -> bool:
+        """
+        Assert Flesch Reading Ease score is within bounds.
+        
+        Scores: 0-30 (very difficult) to 90-100 (very easy)
+        - 60-70: Standard / Plain English
+        - 70-80: Fairly easy
+        - 80-90: Easy
+        """
+        start = time.perf_counter()
+        
+        try:
+            import textstat
+        except ImportError:
+            raise ImportError("textstat required: pip install textstat")
+        
+        score = textstat.flesch_reading_ease(text)
+        
+        if min_score is not None and max_score is not None:
+            passed = min_score <= score <= max_score
+            expected = f"{min_score}-{max_score}"
+        elif min_score is not None:
+            passed = score >= min_score
+            expected = f">= {min_score}"
+        elif max_score is not None:
+            passed = score <= max_score
+            expected = f"<= {max_score}"
+        else:
+            passed = True
+            expected = "any"
+        
+        result = AssertionResult(
+            name="readability",
+            status=Status.PASS if passed else Status.FAIL,
+            message=f"Flesch score {score:.1f} not in range {expected}" if not passed else None,
+            expected=expected,
+            actual=round(score, 1),
+            duration_ms=(time.perf_counter() - start) * 1000,
+        )
+        get_context().add_assertion(result)
+        return passed
+    
+    @staticmethod
+    def grade_level(text: str, *, min_grade: float | None = None, max_grade: float | None = None) -> bool:
+        """
+        Assert Flesch-Kincaid Grade Level is within bounds.
+        
+        Score represents US school grade level needed to understand the text.
+        """
+        start = time.perf_counter()
+        
+        try:
+            import textstat
+        except ImportError:
+            raise ImportError("textstat required: pip install textstat")
+        
+        grade = textstat.flesch_kincaid_grade(text)
+        
+        if min_grade is not None and max_grade is not None:
+            passed = min_grade <= grade <= max_grade
+            expected = f"grade {min_grade}-{max_grade}"
+        elif min_grade is not None:
+            passed = grade >= min_grade
+            expected = f">= grade {min_grade}"
+        elif max_grade is not None:
+            passed = grade <= max_grade
+            expected = f"<= grade {max_grade}"
+        else:
+            passed = True
+            expected = "any"
+        
+        result = AssertionResult(
+            name="grade_level",
+            status=Status.PASS if passed else Status.FAIL,
+            message=f"Grade level {grade:.1f} not in range {expected}" if not passed else None,
+            expected=expected,
+            actual=round(grade, 1),
+            duration_ms=(time.perf_counter() - start) * 1000,
+        )
+        get_context().add_assertion(result)
+        return passed
+    
+    # ==================== Language ====================
+    
+    @staticmethod
+    def language_is(text: str, expected_lang: str) -> bool:
+        """Assert text is in expected language (ISO 639-1 code like 'en', 'es', 'fr')."""
+        start = time.perf_counter()
+        
+        try:
+            from langdetect import detect, LangDetectException
+        except ImportError:
+            raise ImportError("langdetect required: pip install langdetect")
+        
+        try:
+            detected = detect(text)
+            passed = detected == expected_lang
+            message = f"Detected '{detected}', expected '{expected_lang}'" if not passed else None
+        except LangDetectException as e:
+            passed = False
+            detected = None
+            message = f"Language detection failed: {e}"
+        
+        result = AssertionResult(
+            name="language_is",
+            status=Status.PASS if passed else Status.FAIL,
+            message=message,
+            expected=expected_lang,
+            actual=detected,
+            duration_ms=(time.perf_counter() - start) * 1000,
+        )
+        get_context().add_assertion(result)
+        return passed
+    
+    # ==================== URLs & Links ====================
+    
+    @staticmethod
+    def no_urls(text: str) -> bool:
+        """Assert text contains no URLs."""
+        start = time.perf_counter()
+        
+        url_pattern = r'https?://[^\s<>"{}|\\^`\[\]]+'
+        urls = re.findall(url_pattern, text)
+        passed = len(urls) == 0
+        
+        result = AssertionResult(
+            name="no_urls",
+            status=Status.PASS if passed else Status.FAIL,
+            message=f"Found URLs: {urls[:3]}" if not passed else None,
+            actual=urls if urls else None,
+            duration_ms=(time.perf_counter() - start) * 1000,
+        )
+        get_context().add_assertion(result)
+        return passed
+    
+    @staticmethod
+    def urls_valid(text: str, timeout: float = 5.0) -> bool:
+        """Assert all URLs in text return 2xx status (no hallucinated URLs)."""
+        start = time.perf_counter()
+        
+        try:
+            import httpx
+        except ImportError:
+            raise ImportError("httpx required: pip install httpx")
+        
+        url_pattern = r'https?://[^\s<>"{}|\\^`\[\]]+'
+        urls = re.findall(url_pattern, text)
+        
+        if not urls:
+            passed = True
+            invalid = []
+        else:
+            invalid = []
+            for url in urls[:10]:  # Limit to 10 URLs
+                try:
+                    resp = httpx.head(url, timeout=timeout, follow_redirects=True)
+                    if resp.status_code >= 400:
+                        invalid.append((url, resp.status_code))
+                except Exception as e:
+                    invalid.append((url, str(e)))
+            
+            passed = len(invalid) == 0
+        
+        result = AssertionResult(
+            name="urls_valid",
+            status=Status.PASS if passed else Status.FAIL,
+            message=f"Invalid URLs: {invalid}" if invalid else None,
+            expected="all URLs return 2xx",
+            actual=invalid if invalid else f"{len(urls)} URLs valid",
+            duration_ms=(time.perf_counter() - start) * 1000,
+        )
+        get_context().add_assertion(result)
+        return passed
+    
+    # ==================== Code ====================
+    
+    @staticmethod
+    def code_parses(text: str, language: str = "python") -> bool:
+        """Assert code is syntactically valid."""
+        start = time.perf_counter()
+        
+        # Extract code from markdown blocks if present
+        code = text
+        code_block = re.search(r'```(?:\w+)?\n(.*?)```', text, re.DOTALL)
+        if code_block:
+            code = code_block.group(1)
+        
+        if language == "python":
+            try:
+                import ast
+                ast.parse(code)
+                passed = True
+                message = None
+            except SyntaxError as e:
+                passed = False
+                message = f"Syntax error: {e}"
+        elif language == "json":
+            try:
+                json.loads(code)
+                passed = True
+                message = None
+            except json.JSONDecodeError as e:
+                passed = False
+                message = f"JSON error: {e}"
+        else:
+            passed = True
+            message = f"Language '{language}' validation not implemented"
+        
+        result = AssertionResult(
+            name="code_parses",
+            status=Status.PASS if passed else Status.FAIL,
+            message=message,
+            expected=f"valid {language}",
+            duration_ms=(time.perf_counter() - start) * 1000,
+        )
+        get_context().add_assertion(result)
+        return passed
+    
+    @staticmethod
+    def code_runs(text: str, timeout: float = 5.0) -> bool:
+        """Assert Python code executes without error."""
+        start = time.perf_counter()
+        
+        # Extract code from markdown blocks if present
+        code = text
+        code_block = re.search(r'```(?:python)?\n(.*?)```', text, re.DOTALL)
+        if code_block:
+            code = code_block.group(1)
+        
+        try:
+            exec(compile(code, '<string>', 'exec'), {'__builtins__': __builtins__})
+            passed = True
+            message = None
+        except Exception as e:
+            passed = False
+            message = f"{type(e).__name__}: {e}"
+        
+        result = AssertionResult(
+            name="code_runs",
+            status=Status.PASS if passed else Status.FAIL,
+            message=message,
+            expected="executes without error",
+            duration_ms=(time.perf_counter() - start) * 1000,
+        )
+        get_context().add_assertion(result)
+        return passed
+    
+    # ==================== Semantic (using embeddings) ====================
+    
+    @staticmethod
+    def embedding_similarity(
+        text: str, 
+        reference: str, 
+        *, 
+        threshold: float = 0.8,
+        model: str = "all-MiniLM-L6-v2",
+    ) -> bool:
+        """Assert text is semantically similar to reference (cosine similarity)."""
+        start = time.perf_counter()
+        
+        try:
+            from sentence_transformers import SentenceTransformer
+            import numpy as np
+        except ImportError:
+            raise ImportError(
+                "sentence-transformers required: pip install sentence-transformers"
+            )
+        
+        # Load model (cached after first call)
+        encoder = SentenceTransformer(model)
+        
+        # Compute embeddings
+        embeddings = encoder.encode([text, reference])
+        
+        # Cosine similarity
+        similarity = float(np.dot(embeddings[0], embeddings[1]) / (
+            np.linalg.norm(embeddings[0]) * np.linalg.norm(embeddings[1])
+        ))
+        
+        passed = similarity >= threshold
+        
+        result = AssertionResult(
+            name="embedding_similarity",
+            status=Status.PASS if passed else Status.FAIL,
+            message=f"Similarity {similarity:.3f} < threshold {threshold}" if not passed else None,
+            expected=f">= {threshold}",
+            actual=round(similarity, 3),
+            duration_ms=(time.perf_counter() - start) * 1000,
+        )
+        get_context().add_assertion(result)
+        return passed
+    
+    # ==================== Factuality (NLI-based) ====================
+    
+    @staticmethod
+    def entails(text: str, *, source: str, threshold: float = 0.7) -> bool:
+        """
+        Assert text is entailed by (follows from) the source.
+        Uses NLI model - deterministic given the model.
+        """
+        start = time.perf_counter()
+        
+        try:
+            import torch
+            from transformers import pipeline
+        except ImportError as e:
+            if "torch" in str(e) or "torch" not in dir():
+                raise ImportError(
+                    "torch required for NLI: pip install torch transformers"
+                )
+            raise ImportError("transformers required: pip install transformers")
+        
+        # Load NLI model (cached after first call)
+        nli = pipeline(
+            "text-classification", 
+            model="facebook/bart-large-mnli",
+            device=-1,  # CPU
+        )
+        
+        # Check if source entails text
+        result_nli = nli(f"{source}</s></s>{text}", top_k=3)
+        
+        # Find entailment score
+        entailment_score = 0.0
+        for r in result_nli:
+            if r["label"] == "entailment":
+                entailment_score = r["score"]
+                break
+        
+        passed = entailment_score >= threshold
+        
+        result = AssertionResult(
+            name="entails",
+            status=Status.PASS if passed else Status.FAIL,
+            message=f"Entailment score {entailment_score:.3f} < threshold {threshold}" if not passed else None,
+            expected=f">= {threshold}",
+            actual=round(entailment_score, 3),
+            duration_ms=(time.perf_counter() - start) * 1000,
+        )
+        get_context().add_assertion(result)
+        return passed
+    
+    @staticmethod
+    def no_contradiction(text: str, *, source: str, threshold: float = 0.3) -> bool:
+        """
+        Assert text does not contradict the source.
+        Uses NLI model - deterministic given the model.
+        """
+        start = time.perf_counter()
+        
+        try:
+            import torch
+            from transformers import pipeline
+        except ImportError as e:
+            if "torch" in str(e) or "torch" not in dir():
+                raise ImportError(
+                    "torch required for NLI: pip install torch transformers"
+                )
+            raise ImportError("transformers required: pip install transformers")
+        
+        nli = pipeline(
+            "text-classification",
+            model="facebook/bart-large-mnli", 
+            device=-1,
+        )
+        
+        result_nli = nli(f"{source}</s></s>{text}", top_k=3)
+        
+        contradiction_score = 0.0
+        for r in result_nli:
+            if r["label"] == "contradiction":
+                contradiction_score = r["score"]
+                break
+        
+        passed = contradiction_score < threshold
+        
+        result = AssertionResult(
+            name="no_contradiction",
+            status=Status.PASS if passed else Status.FAIL,
+            message=f"Contradiction score {contradiction_score:.3f} >= threshold {threshold}" if not passed else None,
+            expected=f"< {threshold}",
+            actual=round(contradiction_score, 3),
+            duration_ms=(time.perf_counter() - start) * 1000,
+        )
+        get_context().add_assertion(result)
+        return passed
+    
+    # ==================== Custom ====================
+    
+    @staticmethod
+    def custom(
+        passed: bool,
+        name: str = "custom",
+        message: str | None = None,
+        expected: Any = None,
+        actual: Any = None,
+    ) -> bool:
+        """Register a custom assertion result."""
+        start = time.perf_counter()
+        
+        result = AssertionResult(
+            name=name,
+            status=Status.PASS if passed else Status.FAIL,
+            message=message if not passed else None,
+            expected=expected,
+            actual=actual,
+            duration_ms=(time.perf_counter() - start) * 1000,
+        )
+        get_context().add_assertion(result)
+        return passed