groundguard 0.1.0__py3-none-any.whl

groundguard/__init__.py

@@ -0,0 +1,37 @@
+from groundguard.core.verifier import (
+    verify,
+    averify,
+    verify_batch,
+    averify_batch,
+    verify_batch_async,
+    verify_analysis,
+    averify_analysis,
+    verify_answer,
+    averify_answer,
+    verify_clause,
+    averify_clause,
+    verify_structured,
+)
+from groundguard.models.result import (
+    GroundingResult,
+    ContextualizedClaimUnit,
+    VerificationAuditRecord,
+)
+from groundguard.profiles import (
+    VerificationProfile,
+    STRICT_PROFILE,
+    GENERAL_PROFILE,
+    RESEARCH_PROFILE,
+)
+from groundguard.circuit_breaker import (
+    assert_faithful,
+    assert_grounded,
+    verify_or_retry,
+    GroundingError,
+)
+from groundguard.loaders.accumulator import GroundingAccumulator, SourceAccumulator
+from groundguard.cost_estimate import (
+    CostEstimate,
+    estimate_verify_analysis_cost,
+    estimate_verify_faithfulness_cost,
+)

groundguard/_constants.py

@@ -0,0 +1,14 @@
+"""Shared constants for the groundguard library."""
+from __future__ import annotations
+
+import litellm
+
+# FIX-02: Unified transient error tuple used by both tier3_evaluation.py and verifier.py.
+# Previously tier3_evaluation.py was missing litellm.exceptions.Timeout, meaning timeouts
+# were not retried by the backoff loop — only caught and re-raised by the orchestrator.
+TRANSIENT_LITELLM_ERRORS = (
+    litellm.exceptions.ServiceUnavailableError,
+    litellm.exceptions.RateLimitError,
+    litellm.exceptions.APIConnectionError,
+    litellm.exceptions.Timeout,
+)

groundguard/_log.py

@@ -0,0 +1,4 @@
+"""Library logger."""
+import logging
+
+logger = logging.getLogger("groundguard")

groundguard/adapters/__init__.py

@@ -0,0 +1,4 @@
+"""Model adapter registry for provider-specific LLM quirk handling."""
+from groundguard.adapters.registry import get_adapter, ModelAdapter
+
+__all__ = ["get_adapter", "ModelAdapter"]

groundguard/adapters/registry.py

@@ -0,0 +1,298 @@
+"""Model adapter registry — provider-specific pre/post-processing for litellm calls."""
+from __future__ import annotations
+import re
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from groundguard._log import logger
+from groundguard.exceptions import VerificationFailedError
+
+_THINK_TAG_RE = re.compile(r'<think>.*?</think>', re.DOTALL | re.IGNORECASE)
+# BUG-01: unanchored search so conversational pre/post-text is ignored.
+# Only extract if the fenced content looks like JSON ({...} or [...]).
+_MD_FENCE_RE = re.compile(r'```(?:json)?\s*\n?(.*?)\n?\s*```', re.DOTALL)
+
+
+def _strip_fences(content: str) -> str:
+    """Strip markdown code fences and surrounding whitespace.
+
+    Uses unanchored search so conversational text before/after the fence
+    does not prevent extraction. Only returns the fenced content when it
+    looks like JSON (starts with '{' or '['); otherwise falls through to
+    return the original content stripped.
+    """
+    m = _MD_FENCE_RE.search(content)
+    if m:
+        extracted = m.group(1).strip()
+        if extracted.startswith('{') or extracted.startswith('['):
+            return extracted
+    return content.strip()
+
+
+def _strip_think_tags(content: str) -> str:
+    """
+    Strip chain-of-thought <think> blocks from Ollama thinking-capable models.
+
+    Uses rfind('</think>') split rather than regex-only, because quantized/local
+    LLMs frequently hallucinate malformed closing tags (</thinking>, <\\think>, or
+    omit the closing tag entirely). rfind on the last occurrence is resilient to
+    all of these — it discards everything up to and including the last </think>
+    variant if present, then falls through to regex for well-formed tags.
+
+    Edge case — max_tokens exhaustion mid-thought: if the model emits <think> but
+    hits the token limit before writing </think>, there is no closing tag. In this
+    case rfind returns -1 AND the regex matches nothing, so stripped == content.
+    Detecting a leading <think> opener here returns "" to signal "no usable JSON".
+    """
+    lower = content.lower()
+    # Find the last occurrence of any </think...> closing tag variant
+    think_end = lower.rfind('</think')
+    if think_end != -1:
+        # Advance past the tag's closing >
+        close_bracket = content.find('>', think_end)
+        if close_bracket != -1:
+            return content[close_bracket + 1:].strip()
+    # Fallback: regex for well-formed <think>...</think> blocks
+    stripped = _THINK_TAG_RE.sub('', content).strip()
+    # If regex changed nothing and content opens with <think>, the model hit
+    # max_tokens mid-thought — entire content is reasoning, no JSON present.
+    if stripped == content.strip() and lower.lstrip().startswith('<think'):
+        return ""
+    return stripped
+
+
+@dataclass
+class ModelAdapter:
+    """
+    Protocol for provider-specific LLM quirk handling.
+
+    build_kwargs(base_kwargs: dict) -> dict
+        Takes the base litellm.completion() kwargs dict and returns the final kwargs dict.
+        Adapter is free to add, remove, or modify any key (e.g. OPENAI_REASONING_ADAPTER
+        pops 'temperature' to avoid API errors on o1/o3/o4/gpt-5 models).
+        Default: return base_kwargs unchanged.
+
+    post_process(response, model) -> str
+        Extract normalized content string from a raw LiteLLM response object.
+        Raises VerificationFailedError on unrecoverable content.
+        Content returned here is fed directly into Tier3ResponseModel.model_validate_json().
+    """
+    name: str
+    build_kwargs: Callable[[dict], dict]
+    post_process: Callable[[Any, str], str]
+
+
+# ---------------------------------------------------------------------------
+# DEFAULT_ADAPTER — used for all unrecognized models
+# ---------------------------------------------------------------------------
+def _default_post_process(response: Any, model: str = "") -> str:
+    content = response.choices[0].message.content or ""
+    return _strip_fences(content)
+
+
+DEFAULT_ADAPTER = ModelAdapter(
+    name="default",
+    build_kwargs=lambda base: dict(base),
+    post_process=_default_post_process,
+)
+
+
+# ---------------------------------------------------------------------------
+# OLLAMA_ADAPTER — ollama/ and ollama_chat/ prefixes
+# ---------------------------------------------------------------------------
+def _ollama_build_kwargs(base: dict) -> dict:
+    """Force ollama/ → ollama_chat/ and ensure sufficient context for structured output.
+
+    Two issues this fixes:
+
+    1. litellm routes 'ollama/' to /api/generate, which mishandles structured-output
+       responses from thinking-capable models (qwen3, DeepSeek-R1, etc.): the JSON
+       schema output lands in the 'thinking' field while 'response' is empty.
+       /api/chat correctly splits 'content' (JSON) from 'thinking' (reasoning).
+
+    2. Models with a small default num_ctx (e.g. 4K) exhaust their token budget
+       during the thinking phase, leaving nothing for the JSON output. We override
+       num_ctx to 8192 so thinking-capable models have room to reason AND output
+       the full structured response. This override can be raised further if needed.
+    """
+    base = dict(base)
+    model = base.get("model", "")
+    if model.startswith("ollama/"):
+        base["model"] = "ollama_chat/" + model[len("ollama/"):]
+    # Ensure enough context for thinking + structured JSON output (16K covers full Tier3 prompts)
+    options = base.get("extra_body", {}).get("options", {})
+    options.setdefault("num_ctx", 16384)
+    base.setdefault("extra_body", {})["options"] = options
+    # keep_alive=300 holds the model in memory for 5 min so sequential calls don't reload
+    base.setdefault("extra_body", {}).setdefault("keep_alive", 300)
+    return base
+
+
+def _ollama_post_process(response: Any, model: str = "") -> str:
+    msg = response.choices[0].message
+    content = msg.content
+    if content:
+        content = _strip_think_tags(content)
+    if not content:
+        # litellm may drop content if reasoning_content is present — try fallback
+        fallback = getattr(msg, 'reasoning_content', None) or ""
+        fallback = fallback.strip()
+        if fallback.startswith('{'):
+            content = fallback
+        else:
+            # BUG-02: return "" instead of raising so Tier 3 retry loop catches it
+            # (ValidationError on empty string) and retries rather than propagating.
+            logger.warning(
+                "Ollama returned empty content and reasoning_content has no JSON — "
+                "returning empty string for retry"
+            )
+            return ""
+    return _strip_fences(content)
+
+
+OLLAMA_ADAPTER = ModelAdapter(
+    name="ollama",
+    build_kwargs=_ollama_build_kwargs,
+    post_process=_ollama_post_process,
+)
+
+
+# ---------------------------------------------------------------------------
+# NIM_THINKING_ADAPTER — NIM-hosted thinking models (kimi-k2, gpt-oss, etc.)
+# Uses reasoning_content fallback like OLLAMA_ADAPTER but sends no
+# Ollama-specific extra_body fields (options/keep_alive) to the NIM endpoint.
+# ---------------------------------------------------------------------------
+NIM_THINKING_ADAPTER = ModelAdapter(
+    name="nim_thinking",
+    build_kwargs=lambda base: dict(base),
+    post_process=_ollama_post_process,
+)
+
+
+# ---------------------------------------------------------------------------
+# NEMOTRON_NIM_ADAPTER — nvidia/nemotron-3-super-120b-a12b
+# Requires chat_template_kwargs + reasoning_budget in extra_body, otherwise
+# the server hangs without returning a response.
+# ---------------------------------------------------------------------------
+def _nemotron_build_kwargs(base: dict) -> dict:
+    base = dict(base)
+    extra = base.setdefault("extra_body", {})
+    extra.setdefault("chat_template_kwargs", {"enable_thinking": True})
+    extra.setdefault("reasoning_budget", 16384)
+    return base
+
+
+NEMOTRON_NIM_ADAPTER = ModelAdapter(
+    name="nemotron_nim",
+    build_kwargs=_nemotron_build_kwargs,
+    post_process=_ollama_post_process,
+)
+
+
+# ---------------------------------------------------------------------------
+# OPENAI_REASONING_ADAPTER — o1, o3, o4, gpt-5 series
+# ---------------------------------------------------------------------------
+def _openai_reasoning_build_kwargs(base: dict) -> dict:
+    base = dict(base)
+    base.pop("temperature", None)
+    return base
+
+
+OPENAI_REASONING_ADAPTER = ModelAdapter(
+    name="openai_reasoning",
+    build_kwargs=_openai_reasoning_build_kwargs,
+    post_process=_default_post_process,
+)
+
+
+# ---------------------------------------------------------------------------
+# ANTHROPIC_ADAPTER — anthropic/ prefix and claude- prefix models
+# ---------------------------------------------------------------------------
+def _anthropic_post_process(response: Any, model: str = "") -> str:
+    content = response.choices[0].message.content or ""
+    # Never use message.parsed — force raw content path to avoid litellm #20533
+    return _strip_fences(content)
+
+
+ANTHROPIC_ADAPTER = ModelAdapter(
+    name="anthropic",
+    build_kwargs=lambda base: dict(base),
+    post_process=_anthropic_post_process,
+)
+
+
+# ---------------------------------------------------------------------------
+# GOOGLE_ADAPTER — gemini/ and vertex_ai/gemini prefixes
+# ---------------------------------------------------------------------------
+def _google_post_process(response: Any, model: str = "") -> str:
+    content = response.choices[0].message.content
+    if not content:
+        # BUG-02: return "" instead of raising so Tier 3 retry loop retries.
+        logger.warning(
+            "Gemini returned empty content (possible safety filter) — "
+            "returning empty string for retry"
+        )
+        return ""
+    return _strip_fences(content)
+
+
+GOOGLE_ADAPTER = ModelAdapter(
+    name="google",
+    build_kwargs=lambda base: dict(base),
+    post_process=_google_post_process,
+)
+
+
+# ---------------------------------------------------------------------------
+# JSON_OBJECT_ADAPTER — models that support only json_object (not json_schema)
+# e.g. nvidia_nim/microsoft/phi-4-mini-instruct
+# ---------------------------------------------------------------------------
+def _json_object_build_kwargs(base: dict) -> dict:
+    base = dict(base)
+    base["response_format"] = {"type": "json_object"}
+    return base
+
+
+JSON_OBJECT_ADAPTER = ModelAdapter(
+    name="json_object",
+    build_kwargs=_json_object_build_kwargs,
+    post_process=_default_post_process,
+)
+
+
+# ---------------------------------------------------------------------------
+# Registry & Lookup — ordered most-specific to least-specific prefix
+# ---------------------------------------------------------------------------
+_REGISTRY: list[tuple[str, ModelAdapter]] = [
+    ("ollama_chat/", OLLAMA_ADAPTER),
+    ("ollama/", OLLAMA_ADAPTER),
+    # NIM thinking models — emit reasoning_content
+    ("nvidia_nim/deepseek", NIM_THINKING_ADAPTER),           # DeepSeek-R1/V3 on NIM
+    ("nvidia_nim/nvidia/nemotron-3-super", NEMOTRON_NIM_ADAPTER),  # requires chat_template_kwargs
+    ("nvidia_nim/nvidia/nemotron-3-nano", NEMOTRON_NIM_ADAPTER),   # requires chat_template_kwargs
+    ("nvidia_nim/moonshotai/kimi-k2", NIM_THINKING_ADAPTER),      # Kimi K2 thinking
+    ("nvidia_nim/openai/gpt-oss", NIM_THINKING_ADAPTER),          # GPT-OSS thinking
+    # NIM json_object-only models
+    ("nvidia_nim/microsoft/phi-4-mini", JSON_OBJECT_ADAPTER),
+    ("vertex_ai/gemini", GOOGLE_ADAPTER),
+    ("gemini/", GOOGLE_ADAPTER),
+    ("anthropic/", ANTHROPIC_ADAPTER),
+    ("claude-", ANTHROPIC_ADAPTER),
+    ("o1", OPENAI_REASONING_ADAPTER),
+    ("o3", OPENAI_REASONING_ADAPTER),
+    ("o4", OPENAI_REASONING_ADAPTER),
+    ("gpt-5", OPENAI_REASONING_ADAPTER),
+]
+
+
+def get_adapter(model: str) -> ModelAdapter:
+    """
+    Longest-prefix match against _REGISTRY. Returns DEFAULT_ADAPTER for unrecognized models.
+
+    The registry is ordered by prefix length (longest first) to ensure that
+    'ollama_chat/' matches before 'ollama/' for models like 'ollama_chat/deepseek-r1'.
+    """
+    for prefix, adapter in _REGISTRY:
+        if model.startswith(prefix):
+            return adapter
+    return DEFAULT_ADAPTER

groundguard/circuit_breaker.py

@@ -0,0 +1,32 @@
+"""Assertion-style circuit breakers for grounding verification."""
+from groundguard.models.result import GroundingResult, Source
+from groundguard.core.verifier import verify_answer, verify_analysis
+
+
+class GroundingError(Exception):
+    pass
+
+
+def assert_faithful(output: str, sources: list[Source], **kwargs) -> None:
+    result = verify_answer(output, sources, **kwargs)
+    if not result.is_grounded:
+        raise GroundingError(
+            f"Output not grounded: score={result.score:.2f}, status={result.status}"
+        )
+
+
+def assert_grounded(analysis: str, sources: list[Source], **kwargs) -> None:
+    result = verify_analysis(analysis, sources, **kwargs)
+    if not result.is_grounded:
+        raise GroundingError(
+            f"Analysis not grounded: score={result.score:.2f}"
+        )
+
+
+def verify_or_retry(generator, sources: list[Source], max_retries: int = 3, **kwargs) -> str:
+    for attempt in range(max_retries):
+        output = generator()
+        result = verify_answer(output, sources, **kwargs)
+        if result.is_grounded:
+            return output
+    raise GroundingError(f"Output not grounded after {max_retries} attempts")

groundguard/core/claim_extractor.py

@@ -0,0 +1,85 @@
+"""Claim extraction from free-form text using LLM."""
+from __future__ import annotations
+import secrets
+from typing import TYPE_CHECKING
+
+import pydantic
+
+from groundguard.exceptions import ParseError
+from groundguard.tiers.tier3_evaluation import _completion_with_backoff, _acompletion_with_backoff
+
+if TYPE_CHECKING:
+    from groundguard.models.result import Source
+
+
+CLAIM_EXTRACTION_PROMPT = """Extract all distinct factual claims from the text below.
+Return JSON with key "claims" containing a list of strings.
+Each string is one atomic, self-contained factual claim.
+
+Text (boundary: {boundary}):
+{text}
+
+Sources provided:
+{sources_block}
+
+Return only JSON. Example: {{"claims": ["claim 1", "claim 2"]}}"""
+
+
+class _ClaimList(pydantic.BaseModel):
+    claims: list[str]
+
+
+def extract_claims(
+    text: str,
+    sources: list,
+    model: str,
+    max_spend: float = float("inf"),
+    api_base: str | None = None,
+) -> list[str]:
+    boundary = secrets.token_hex(6)
+    sources_block = "\n".join(f"- {s.source_id}: {s.content[:200]}" for s in sources)
+    prompt = CLAIM_EXTRACTION_PROMPT.format(
+        boundary=boundary, text=text, sources_block=sources_block
+    )
+    for attempt in range(2):
+        try:
+            response = _completion_with_backoff(
+                model=model,
+                messages=[{"role": "user", "content": prompt}],
+                **({"api_base": api_base} if api_base else {}),
+            )
+            content = response.choices[0].message.content
+            parsed = _ClaimList.model_validate_json(content)
+            return parsed.claims
+        except (pydantic.ValidationError, ValueError):
+            if attempt == 1:
+                raise ParseError("claim extraction failed after 2 attempts")
+    return []
+
+
+async def extract_claims_async(
+    text: str,
+    sources: list,
+    model: str,
+    max_spend: float = float("inf"),
+    api_base: str | None = None,
+) -> list[str]:
+    boundary = secrets.token_hex(6)
+    sources_block = "\n".join(f"- {s.source_id}: {s.content[:200]}" for s in sources)
+    prompt = CLAIM_EXTRACTION_PROMPT.format(
+        boundary=boundary, text=text, sources_block=sources_block
+    )
+    for attempt in range(2):
+        try:
+            response = await _acompletion_with_backoff(
+                model=model,
+                messages=[{"role": "user", "content": prompt}],
+                **({"api_base": api_base} if api_base else {}),
+            )
+            content = response.choices[0].message.content
+            parsed = _ClaimList.model_validate_json(content)
+            return parsed.claims
+        except (pydantic.ValidationError, ValueError):
+            if attempt == 1:
+                raise ParseError("claim extraction async failed after 2 attempts")
+    return []

groundguard/core/classifier.py

@@ -0,0 +1,50 @@
+"""Tier 0 classifier — rules-based Extractive/Inferential atom classification."""
+from __future__ import annotations
+import re
+from groundguard.models.internal import ClassifiedAtom
+
+INFERENTIAL_SIGNALS = {
+    "trend", "trajectory", "suggests", "indicates", "on track", "at risk",
+    "appears to", "likely", "projected", "based on", "derived from",
+    "analysis shows", "pattern", "forecast", "outlook", "implies",
+    "consistent with", "points to", "expected to",
+}
+
+# Decimal-safe sentence splitter: splits on [.!?] NOT between two digits, or newlines.
+# Preserves: $4.2M, v2.1, 3.14
+_SENTENCE_SPLIT_RE = re.compile(r'(?<!\d)[.!?](?!\d)\s+|\n+')
+
+
+def parse_and_classify(claim: str) -> list[ClassifiedAtom]:
+    """
+    Zero-cost, zero-LLM heuristic classifier.
+
+    1. Split claim into atomic sentences using decimal-safe regex.
+    2. For each sentence: classify as Inferential if any INFERENTIAL_SIGNALS token
+       appears as a case-insensitive whole-word match; otherwise Extractive.
+
+    Returns:
+        List of ClassifiedAtom objects. Empty string returns empty list.
+        Punctuation-only input returns empty list (no IndexError).
+    """
+    if not claim or not claim.strip():
+        return []
+
+    sentences = [s.strip() for s in _SENTENCE_SPLIT_RE.split(claim) if s.strip()]
+
+    if not sentences:
+        return []
+
+    atoms: list[ClassifiedAtom] = []
+    for sentence in sentences:
+        lower = sentence.lower()
+        is_inferential = any(
+            re.search(rf'\b{re.escape(signal)}\b', lower)
+            for signal in INFERENTIAL_SIGNALS
+        )
+        atoms.append(ClassifiedAtom(
+            claim_text=sentence,
+            claim_type="Inferential" if is_inferential else "Extractive",
+        ))
+
+    return atoms

groundguard/core/result_builder.py

@@ -0,0 +1,60 @@
+"""Phase 23 ResultBuilder — citation extraction and invariant enforcement."""
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+from groundguard.models.result import AtomicClaimResult, Citation
+from groundguard.exceptions import InvariantError
+
+if TYPE_CHECKING:
+    from groundguard.models.result import Source
+    from groundguard.tiers.tier25_preprocessing import Tier25Result
+
+
+class ResultBuilder:
+
+    @staticmethod
+    def build_numerical_fast_exit(claim: str, tier25: Tier25Result, source: Source) -> AtomicClaimResult:
+        citation = tier25.conflict_citation
+        result = AtomicClaimResult(
+            claim_text=claim, claim_type="Extractive", status="CONTRADICTED",
+            source_id=source.source_id, verification_method="tier25_numerical", citation=citation,
+        )
+        ResultBuilder._assert_citation_invariant("CONTRADICTED", citation)
+        return result
+
+    @staticmethod
+    def build_lexical_pass(claim: str, top_chunks: list, score: float, source: Source) -> AtomicClaimResult:
+        if top_chunks:
+            chunk = top_chunks[0]
+            excerpt_text = chunk.text_content
+            char_start = chunk.char_start
+            char_end = chunk.char_end
+        else:
+            excerpt_text = source.content[:100] if source.content else ""
+            char_start, char_end = 0, len(excerpt_text)
+
+        citation = Citation(
+            source_id=source.source_id, excerpt=excerpt_text,
+            excerpt_char_start=char_start, excerpt_char_end=char_end, citation_confidence=1.0,
+        )
+        result = AtomicClaimResult(
+            claim_text=claim, claim_type="Extractive", status="VERIFIED",
+            source_id=source.source_id, verification_method="tier2_lexical", citation=citation,
+        )
+        ResultBuilder._assert_citation_invariant("VERIFIED", citation)
+        return result
+
+    @staticmethod
+    def build_llm_result(claim: str, verdict: str, citation: Citation | None = None) -> AtomicClaimResult:
+        effective_citation = None if verdict == "UNVERIFIABLE" else citation
+        result = AtomicClaimResult(
+            claim_text=claim, claim_type="Extractive", status=verdict,
+            verification_method="tier3_llm", citation=effective_citation,
+        )
+        ResultBuilder._assert_citation_invariant(verdict, result.citation)
+        return result
+
+    @staticmethod
+    def _assert_citation_invariant(verdict: str, citation: Citation | None) -> None:
+        if verdict == "VERIFIED" and citation is None:
+            raise InvariantError("citation must be non-null for VERIFIED results")