scroot 0.2.0__py3-none-any.whl

scroot/context/pii.py

@@ -0,0 +1,101 @@
+"""PII detection and scrubbing for context content.
+
+Regex-based, fully local - no external API call, consistent with
+scroot's zero-external-dependency principle. Detected entities are
+replaced with typed placeholders (e.g. ``[EMAIL]``); the scrub summary
+records counts by entity type only, never the original values.
+
+Detection is best-effort: regex catches structured PII (emails, phones,
+SSNs, cards, IPs, secrets, dates, street addresses) reliably, and person
+names via honorifics and a common-first-name heuristic. For regulated
+workloads, layer a dedicated NER scrubber in front and pass pre-scrubbed
+text in with ``pii_scrub=False``.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+
+@dataclass
+class ScrubResult:
+    """Result of scrubbing one piece of text.
+
+    Attributes:
+        scrubbed_text: Text with PII replaced by typed placeholders.
+        summary: Counts by entity type plus ``total_entities_scrubbed``.
+            Never contains original values.
+        was_scrubbed: True if at least one entity was replaced.
+    """
+    scrubbed_text: str
+    summary: dict[str, int]
+    was_scrubbed: bool
+
+
+# Common first names used for best-effort [PERSON] detection when no
+# honorific is present. Matches "<FirstName> <Capitalized Surname>".
+_COMMON_FIRST_NAMES = (
+    "James|John|Robert|Michael|William|David|Richard|Joseph|Thomas|Charles|"
+    "Christopher|Daniel|Matthew|Anthony|Mark|Donald|Steven|Paul|Andrew|Joshua|"
+    "Kenneth|Kevin|Brian|George|Timothy|Ronald|Edward|Jason|Jeffrey|Ryan|"
+    "Mary|Patricia|Jennifer|Linda|Elizabeth|Barbara|Susan|Jessica|Sarah|Karen|"
+    "Lisa|Nancy|Betty|Margaret|Sandra|Ashley|Kimberly|Emily|Donna|Michelle|"
+    "Carol|Amanda|Dorothy|Melissa|Deborah|Stephanie|Rebecca|Sharon|Laura|"
+    "Jane|Emma|Olivia|Sophia|Alice|Anna|Maria|Rachel|Hannah|Grace"
+)
+
+# Ordered by priority - earlier patterns run first so that, e.g., an API
+# key is redacted as [SECRET] before the generic patterns see it.
+_PATTERNS: dict[str, re.Pattern] = {
+    "SECRET": re.compile(
+        r'\b(?:sk-ant-[a-zA-Z0-9-]{20,}|sk-[a-zA-Z0-9]{20,}|'
+        r'AKIA[A-Z0-9]{16}|ghp_[a-zA-Z0-9]{36}|[a-f0-9]{32,})\b'
+    ),
+    "EMAIL": re.compile(r'\b[\w.+-]+@[\w-]+\.[a-zA-Z]{2,}\b'),
+    "CARD": re.compile(r'\b(?:\d[ -]?){13,16}\b'),
+    "SSN": re.compile(r'\b\d{3}-\d{2}-\d{4}\b'),
+    "IP": re.compile(r'\b\d{1,3}(?:\.\d{1,3}){3}\b'),
+    "PHONE": re.compile(
+        r'(?:\+?\d{1,2}[-.\s])?\(?\d{3}\)?[-.\s]\d{3,4}[-.\s]?\d{0,4}\b'
+        r'|\b\d{3}[-.\s]\d{3}[-.\s]\d{4}\b'
+    ),
+    "DOB": re.compile(
+        r'\b(?:Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)?|May|'
+        r'Jun(?:e)?|Jul(?:y)?|Aug(?:ust)?|Sep(?:tember)?|Oct(?:ober)?|'
+        r'Nov(?:ember)?|Dec(?:ember)?)\.?\s+\d{1,2},?\s+\d{4}\b'
+        r'|\b\d{1,2}/\d{1,2}/\d{4}\b'
+    ),
+    "ADDRESS": re.compile(
+        r'\b\d{1,5}\s+(?:[A-Z][a-zA-Z]+\s+){1,3}'
+        r'(?:St|Street|Ave|Avenue|Rd|Road|Blvd|Boulevard|Ln|Lane|'
+        r'Dr|Drive|Ct|Court|Way|Pl|Place)\b\.?'
+    ),
+    "PERSON": re.compile(
+        r'\b(?:Mr|Mrs|Ms|Dr|Prof)\.?\s+[A-Z][a-z]+(?:\s+[A-Z][a-z]+)?'
+        rf'|\b(?:{_COMMON_FIRST_NAMES})\s+[A-Z][a-z]+\b'
+    ),
+}
+
+
+def scrub(text: str) -> ScrubResult:
+    """Replace detected PII entities with typed placeholders.
+
+    Args:
+        text: Raw text that may contain PII.
+
+    Returns:
+        ScrubResult with the scrubbed text and a count-only summary.
+        The original values are not retained anywhere.
+    """
+    summary = {k: 0 for k in _PATTERNS}
+    result = text
+    for entity_type, pattern in _PATTERNS.items():
+        result, n = pattern.subn(f'[{entity_type}]', result)
+        summary[entity_type] = n
+    total = sum(summary.values())
+    return ScrubResult(
+        scrubbed_text=result,
+        summary={**summary, "total_entities_scrubbed": total},
+        was_scrubbed=total > 0,
+    )

scroot/context/tokenizer.py

@@ -0,0 +1,42 @@
+"""Token counting for context budgeting.
+
+Uses tiktoken when installed (accurate for OpenAI-family tokenisers);
+falls back to a character-based estimate (~4 chars per token) otherwise.
+The fallback intentionally over-estimates slightly so the max_tokens
+budget errs on the safe side.
+"""
+
+from __future__ import annotations
+
+_encoder = None
+_tiktoken_checked = False
+
+
+def _get_encoder():
+    global _encoder, _tiktoken_checked
+    if not _tiktoken_checked:
+        _tiktoken_checked = True
+        try:
+            import tiktoken
+            _encoder = tiktoken.get_encoding("cl100k_base")
+        except Exception:
+            _encoder = None
+    return _encoder
+
+
+def count_tokens(text: str) -> int:
+    """Count tokens in text.
+
+    Args:
+        text: Input string.
+
+    Returns:
+        Token count via tiktoken if available, otherwise
+        ``max(1, ceil(len(text) / 4))`` for non-empty text.
+    """
+    if not text:
+        return 0
+    encoder = _get_encoder()
+    if encoder is not None:
+        return len(encoder.encode(text))
+    return max(1, -(-len(text) // 4))

scroot/core.py

@@ -0,0 +1,349 @@
+"""Auditor: main orchestrator class.
+
+Loads models once, runs all metrics, computes IQS, returns result.
+"""
+
+from __future__ import annotations
+
+import logging
+import warnings
+
+from .result import EntailmentResult
+from .context.payload import ContextPayload
+from .evidence import build_evidence_map
+from .exceptions import GroundednessComputationError, NoContextWarning
+from .metrics.groundedness import score_groundedness
+from .metrics.completeness import score_completeness
+from .metrics.relevance import score_relevance
+from .metrics.consistency import score_consistency
+from .metrics.confidence import score_confidence
+from .composite import DEFAULT_WEIGHTS, compute_iqs_detailed
+from .flags import detect_flags
+
+logger = logging.getLogger(__name__)
+
+
+class Auditor:
+    """LLM-free response quality scorer.
+
+    Scores LLM responses using NLI models and embedding similarity.
+    No LLM API calls required. Runs locally, deterministic, fast.
+
+    Args:
+        nli_model: NLI cross-encoder model name or pre-instantiated instance.
+            Upgrade to ``cross-encoder/nli-deberta-v3-large`` for ~4% better
+            accuracy at the cost of ~2x latency.
+        embedding_model: Sentence-transformers model name or instance.
+        device: Inference device. ``"cpu"`` or ``"cuda"``.
+        weights: Optional custom IQS component weights dict. Missing keys
+            default to the standard weights. Use ``scroot.RAG_WEIGHTS``
+            for RAG-optimised scoring (higher groundedness weight).
+        iqs_mode: IQS formula. ``"harmonic"`` (default) uses the weighted
+            harmonic mean: ``IQS = n / sum(w_i / s_i)``. Any metric near
+            zero drives IQS to zero. ``"geometric"`` uses weighted geometric
+            mean - does not collapse to zero on partial hallucination.
+        atomic_claims: If True (default), split compound sentences into
+            sub-claims before groundedness scoring. Prevents one wrong fact
+            from zeroing an entire multi-fact sentence.
+        similarity_fallback: If True (default), use bi-encoder cosine
+            similarity as a fallback when NLI confidence is uncertain (0.3-0.7).
+            Catches paraphrases that exact NLI entailment misses.
+        similarity_threshold: Cosine similarity threshold for paraphrase
+            credit in the similarity fallback. Default 0.82.
+        max_query_length: Truncate query to this many characters (H-3).
+        max_response_length: Truncate response to this many characters (H-3).
+        max_context_items: Maximum number of context chunks (H-3).
+        max_context_item_length: Truncate each context chunk to this length (H-3).
+        max_batch_size: ``score_batch()`` raises ValueError above this limit (H-3).
+        entailment_threshold: Minimum entailment probability for a claim to
+            be grounded. Default 0.5.
+        coverage_threshold: Minimum embedding similarity for a query segment
+            to be considered covered by the response. Default 0.45.
+        contradiction_threshold: Minimum contradiction probability to flag a
+            sentence pair as contradictory. Default 0.7.
+        max_sentences: Maximum sentences evaluated by consistency scorer. Default 25.
+        compute_evidence_map: If True (default) and context is provided,
+            attach a sentence-level :class:`~scroot.EvidenceMap` to
+            ``result.evidence_map`` showing which response sentences are
+            supported, contradicted, or ungrounded.
+        evidence_entailment_threshold: Minimum entailment probability for a
+            sentence to be marked "supported" in the evidence map. Default
+            0.70 (stricter than the groundedness ``entailment_threshold``).
+        evidence_contradiction_threshold: Minimum contradiction probability
+            for a sentence to be marked "contradicted" in the evidence map.
+            Default 0.30.
+    """
+
+    def __init__(
+        self,
+        nli_model: str = "cross-encoder/nli-deberta-v3-base",
+        embedding_model: str = "all-MiniLM-L6-v2",
+        device: str = "cpu",
+        weights: dict | None = None,
+        iqs_mode: str = "harmonic",
+        atomic_claims: bool = True,
+        similarity_fallback: bool = True,
+        similarity_threshold: float = 0.82,
+        top_k_chunks: int = 3,
+        bidirectional_consistency: bool = True,
+        nli_completeness: bool = True,
+        max_query_length: int = 10_000,
+        max_response_length: int = 50_000,
+        max_context_items: int = 50,
+        max_context_item_length: int = 10_000,
+        max_batch_size: int = 1_000,
+        entailment_threshold: float = 0.5,
+        coverage_threshold: float = 0.45,
+        contradiction_threshold: float = 0.7,
+        max_sentences: int = 25,
+        compute_evidence_map: bool = True,
+        evidence_entailment_threshold: float = 0.70,
+        evidence_contradiction_threshold: float = 0.30,
+    ):
+        self.nli_model = nli_model
+        self.embedding_model = embedding_model
+        self.device = device
+        self.weights = weights
+        self.iqs_mode = iqs_mode
+        self.atomic_claims = atomic_claims
+        self.similarity_fallback = similarity_fallback
+        self.similarity_threshold = similarity_threshold
+        self.top_k_chunks = top_k_chunks
+        self.bidirectional_consistency = bidirectional_consistency
+        self.nli_completeness = nli_completeness
+        self.max_query_length = max_query_length
+        self.max_response_length = max_response_length
+        self.max_context_items = max_context_items
+        self.max_context_item_length = max_context_item_length
+        self.max_batch_size = max_batch_size
+        self.entailment_threshold = entailment_threshold
+        self.coverage_threshold = coverage_threshold
+        self.contradiction_threshold = contradiction_threshold
+        self.max_sentences = max_sentences
+        self.compute_evidence_map = compute_evidence_map
+        self.evidence_entailment_threshold = evidence_entailment_threshold
+        self.evidence_contradiction_threshold = evidence_contradiction_threshold
+
+    def score(
+        self,
+        query: str,
+        response: str,
+        context: "ContextPayload | str | list[str] | None" = None,
+    ) -> EntailmentResult:
+        """Score a single LLM response.
+
+        Inputs are silently truncated to the configured length limits before
+        processing. Non-string context items are coerced to ``str``; ``None``
+        items are dropped.
+
+        Args:
+            query: The user's query/question.
+            response: The LLM-generated response.
+            context: Grounding context. Accepts:
+
+                - :class:`~scroot.context.ContextPayload` - built by
+                  :class:`~scroot.ContextBuilder`. Consumed here: the
+                  assembled chunks feed the NLI scorer locally and the
+                  payload is not retained. Only ``session_id`` and
+                  ``checksum`` flow into ``details["context"]`` for the
+                  audit trail.
+                - ``str`` - a single grounding string.
+                - ``list[str]`` - source context chunks.
+                - ``None`` - groundedness is skipped entirely.
+
+                If provided (even an empty list), groundedness is scored.
+
+        Returns:
+            :class:`EntailmentResult` with all metric scores and flags.
+            ``result.iqs`` is computed as ``IQS = n / sum(w_i / s_i)``
+            (the weighted harmonic mean of the five metrics, where
+            ``n = sum(w_i)``) by default; see ``iqs_mode``.
+        """
+        context_audit: dict | None = None
+        chunk_sources: list[str | None] | None = None
+        if isinstance(context, ContextPayload):
+            payload = context
+            # Per-source chunks preserve top-k retrieval behaviour in the
+            # groundedness scorer; the payload itself is consumed here.
+            context = [e.content for e in payload.sources] or None
+            chunk_sources = [e.source for e in payload.sources] or None
+            context_audit = {
+                "session_id": payload.session_id,
+                "checksum": payload.checksum,
+                "total_tokens": payload.total_tokens,
+                "was_truncated": payload.was_truncated,
+                "pii_scrubbed": payload.pii_scrubbed,
+            }
+        elif isinstance(context, str):
+            context = [context]
+
+        query = query[: self.max_query_length]
+        response = response[: self.max_response_length]
+        if context is not None:
+            context = context[: self.max_context_items]
+            context = [
+                str(c)[: self.max_context_item_length]
+                for c in context
+                if c is not None and str(c).strip()  # drop empty/whitespace chunks
+            ]
+            if chunk_sources is not None:
+                chunk_sources = chunk_sources[: self.max_context_items]
+            # Empty / whitespace-only context is equivalent to no context:
+            # groundedness cannot be computed (spec: treat "", "  ", [], None
+            # identically).
+            if not context:
+                context = None
+                chunk_sources = None
+
+        details = {}
+        if context_audit is not None:
+            details["context"] = context_audit
+
+        if context is not None:
+            try:
+                groundedness, g_details = score_groundedness(
+                    response, context,
+                    nli_model=self.nli_model,
+                    embedding_model=self.embedding_model,
+                    device=self.device,
+                    entailment_threshold=self.entailment_threshold,
+                    atomic_claims=self.atomic_claims,
+                    similarity_fallback=self.similarity_fallback,
+                    similarity_threshold=self.similarity_threshold,
+                    top_k_chunks=self.top_k_chunks,
+                )
+                details["groundedness"] = g_details
+            except Exception as e:
+                # Context was provided but groundedness scoring failed
+                # unexpectedly. Degrade gracefully: exclude groundedness from
+                # IQS rather than failing the whole call.
+                logger.error("Groundedness computation failed: %s", e)
+                groundedness = None
+                warnings.warn(
+                    f"Groundedness computation failed due to an unexpected "
+                    f"error. IQS will be computed from the remaining metrics. "
+                    f"Error: {e}",
+                    GroundednessComputationError,
+                    stacklevel=2,
+                )
+        else:
+            groundedness = None
+            # Encourage adding context - but stay silent if the caller has
+            # explicitly opted out by zeroing the groundedness weight.
+            ground_weight = (self.weights or DEFAULT_WEIGHTS).get(
+                "groundedness", DEFAULT_WEIGHTS["groundedness"]
+            )
+            if ground_weight > 0.0:
+                warnings.warn(
+                    "auditor.score() called without context. groundedness "
+                    "will be None and is excluded from IQS (the remaining "
+                    "metrics' weights are redistributed). To score "
+                    "groundedness, pass context= or use ContextBuilder.",
+                    NoContextWarning,
+                    stacklevel=2,
+                )
+
+        evidence_map = None
+        if context is not None and self.compute_evidence_map:
+            evidence_map = build_evidence_map(
+                response, context,
+                nli_model=self.nli_model,
+                embedding_model=self.embedding_model,
+                device=self.device,
+                entailment_threshold=self.evidence_entailment_threshold,
+                contradiction_threshold=self.evidence_contradiction_threshold,
+                top_k_chunks=self.top_k_chunks,
+                chunk_sources=chunk_sources,
+                atomic_claims=self.atomic_claims,
+            )
+
+        completeness, c_details = score_completeness(
+            query, response,
+            embedding_model=self.embedding_model,
+            nli_model=self.nli_model if self.nli_completeness else None,
+            device=self.device,
+            coverage_threshold=self.coverage_threshold,
+        )
+        details["completeness"] = c_details
+
+        relevance, r_details = score_relevance(
+            query, response,
+            embedding_model=self.embedding_model,
+            device=self.device,
+        )
+        details["relevance"] = r_details
+
+        consistency, cons_details = score_consistency(
+            response,
+            nli_model=self.nli_model,
+            device=self.device,
+            contradiction_threshold=self.contradiction_threshold,
+            max_sentences=self.max_sentences,
+            bidirectional=self.bidirectional_consistency,
+        )
+        details["consistency"] = cons_details
+
+        confidence, conf_details = score_confidence(response)
+        details["confidence"] = conf_details
+
+        iqs_scores: dict = {
+            "completeness": completeness,
+            "relevance": relevance,
+            "consistency": consistency,
+            "confidence": confidence,
+        }
+        if groundedness is not None:
+            iqs_scores["groundedness"] = groundedness
+        iqs, effective_weights = compute_iqs_detailed(
+            iqs_scores, weights=self.weights, mode=self.iqs_mode,
+        )
+
+        flags = detect_flags(
+            groundedness, completeness, relevance,
+            consistency, confidence,
+        )
+
+        return EntailmentResult(
+            groundedness=groundedness,
+            completeness=completeness,
+            relevance=relevance,
+            consistency=consistency,
+            confidence=confidence,
+            iqs=iqs,
+            flags=flags,
+            details=details,
+            evidence_map=evidence_map,
+            effective_weights=effective_weights,
+            context_used=(groundedness is not None),
+            iqs_metric_count=len(effective_weights),
+        )
+
+    def score_batch(
+        self,
+        items: list[dict],
+    ) -> list[EntailmentResult]:
+        """Score a batch of responses.
+
+        Args:
+            items: List of dicts with keys ``"query"``, ``"response"``,
+                and optionally ``"context"`` (list[str]).
+
+        Returns:
+            List of :class:`EntailmentResult`, one per item, in order.
+
+        Raises:
+            ValueError: If ``len(items)`` exceeds ``max_batch_size`` (H-3).
+        """
+        if len(items) > self.max_batch_size:
+            raise ValueError(
+                f"Batch size {len(items)} exceeds max_batch_size={self.max_batch_size}. "
+                f"Split into smaller batches or increase max_batch_size."
+            )
+        return [
+            self.score(
+                query=item["query"],
+                response=item["response"],
+                context=item.get("context"),
+            )
+            for item in items
+        ]

scroot/corrector/__init__.py

@@ -0,0 +1,38 @@
+"""Corrector provider factory."""
+from __future__ import annotations
+
+from scroot.corrector.base import BaseCorrector
+from scroot.corrector.disabled import NullCorrector
+
+_active_corrector: BaseCorrector | None = None
+
+
+def get_corrector(config) -> BaseCorrector:
+    """
+    Return the active corrector for the current config.
+    Unloads LocalLLMCorrector from RAM when switching away from local mode.
+    """
+    global _active_corrector
+
+    mode = config.mode
+
+    if mode == "disabled":
+        _active_corrector = NullCorrector()
+
+    elif mode == "local":
+        from scroot.corrector.local import LocalLLMCorrector
+        if (
+            isinstance(_active_corrector, LocalLLMCorrector)
+            and _active_corrector.model_spec.id != config.local.model_id
+        ):
+            _active_corrector.unload()
+        _active_corrector = LocalLLMCorrector(config.local)
+
+    elif mode == "api":
+        from scroot.corrector.api import APICorrector
+        _active_corrector = APICorrector(config.api)
+
+    else:
+        _active_corrector = NullCorrector()
+
+    return _active_corrector

scroot/corrector/api.py

@@ -0,0 +1,145 @@
+"""APICorrector - OpenAI-compatible endpoint, provider auto-detected from key.
+
+Design rationale: why ``api_key`` alone is not enough
+-----------------------------------------------------
+
+A common assumption is that an API key fully identifies an LLM connection, so
+``model`` and ``base_url`` should be unnecessary. They are not. An LLM request is::
+
+    POST {base_url}/chat/completions
+    Headers: {auth_header}: {api_key}
+    Body:    {"model": "<name>", "messages": [...]}
+
+The key only fills the **auth header** - it proves *who you are*. It does not
+carry the two other things every request needs:
+
+1. **Where to send it (``base_url``).** Each provider has a different endpoint
+   and even a different auth-header name (Anthropic uses ``x-api-key``; OpenAI
+   uses ``Authorization: Bearer``). This *is* derivable from the key, because the
+   key prefix is provider-specific - that is exactly what ``detect_provider``
+   does (``sk-ant-`` -> Anthropic, ``AIza`` -> Gemini, ``sk-`` -> OpenAI, else
+   OpenRouter). So ``base_url`` can stay optional/advanced: leave it blank for the
+   four known providers, set it only for Groq / OpenRouter / a custom gateway.
+
+2. **Which model to run (``model``).** This is a *mandatory* field in the
+   request body and it is **not derivable from anything**. The key is tied to an
+   *account*, not a model: the same Anthropic key calls Opus, Sonnet, and Haiku.
+   There is no way to infer "the user wants Haiku" from the key, the endpoint, or
+   the header. The specific model is a **decision** (a cost/quality trade-off),
+   not data - so it cannot be auto-detected the way ``base_url`` can. It can only
+   be (a) defaulted to an opinionated pick, or (b) chosen by the user.
+
+Consequence for the architecture / UI:
+
+* ``base_url`` - safe to hide behind "Advanced"; auto-detected from the key.
+* ``model`` - must remain a real (optional) field. Today it defaults to
+  ``gpt-4o-mini`` (see ``draft_correction``), which is only correct for OpenAI;
+  a non-OpenAI key with a blank model will send ``gpt-4o-mini`` to the wrong
+  provider and fail. The intended improvement is a **per-provider default map**
+  (OpenAI -> ``gpt-4o-mini``, Anthropic -> ``claude-haiku-4-5``, Gemini ->
+  ``gemini-2.0-flash``), deliberately the cheap/fast tier since this is response
+  correction, not frontier reasoning - so "paste key, leave model blank" works
+  for every provider while power users can still override.
+
+See also: ``validate_base_url`` in ``scroot.dashboard.security`` (M-2), which
+restricts ``base_url`` to allowlisted provider hosts to prevent key exfiltration
+and SSRF.
+"""
+from __future__ import annotations
+
+from scroot.corrector.base import BaseCorrector
+
+_KEY_PREFIX_MAP = {
+    "sk-ant-": {
+        "base_url": "https://api.anthropic.com/v1",
+        "auth_header": "x-api-key",
+        "provider_name": "Anthropic",
+    },
+    "AIza": {
+        "base_url": "https://generativelanguage.googleapis.com/v1beta/openai",
+        "auth_header": "Authorization",
+        "provider_name": "Google Gemini",
+    },
+}
+_OPENROUTER_BASE = "https://openrouter.ai/api/v1"
+_OPENAI_BASE = "https://api.openai.com/v1"
+
+
+def detect_provider(api_key: str, base_url_override: str = "") -> tuple[str, str, str]:
+    """Returns (base_url, auth_header, provider_name)."""
+    if base_url_override:
+        name = "Custom"
+        if "groq" in base_url_override:
+            name = "Groq"
+        elif "openrouter" in base_url_override:
+            name = "OpenRouter"
+        elif "anthropic" in base_url_override:
+            name = "Anthropic"
+        return base_url_override, "Authorization", name
+    for prefix, cfg in _KEY_PREFIX_MAP.items():
+        if api_key.startswith(prefix):
+            return cfg["base_url"], cfg["auth_header"], cfg["provider_name"]
+    if api_key.startswith("sk-"):
+        return _OPENAI_BASE, "Authorization", "OpenAI"
+    return _OPENROUTER_BASE, "Authorization", "OpenRouter"
+
+
+class APICorrector(BaseCorrector):
+    def __init__(self, config) -> None:
+        self._config = config
+
+    @property
+    def is_available(self) -> bool:
+        return bool(self._config.api_key)
+
+    def draft_correction(
+        self,
+        query: str,
+        response: str,
+        context: str | None,
+    ) -> str:
+        try:
+            import httpx
+        except ImportError:
+            raise RuntimeError(
+                "httpx is not installed. Run: pip install 'scroot[api]'"
+            )
+
+        base_url, auth_header, _ = detect_provider(
+            self._config.api_key, self._config.base_url
+        )
+        # M-2: refuse to send the API key to an unvetted/internal endpoint.
+        from scroot.dashboard.security import validate_base_url
+        validate_base_url(base_url)
+        headers = {
+            "Content-Type": "application/json",
+            auth_header: (
+                self._config.api_key
+                if auth_header == "x-api-key"
+                else f"Bearer {self._config.api_key}"
+            ),
+        }
+        payload = {
+            "model": self._config.model or "gpt-4o-mini",
+            "messages": [
+                {"role": "system", "content": self._config.system_prompt},
+                {"role": "user", "content": self._build_prompt(query, response, context)},
+            ],
+            "max_tokens": 512,
+            "temperature": 0.3,
+        }
+        resp = httpx.post(
+            f"{base_url}/chat/completions",
+            json=payload,
+            headers=headers,
+            timeout=30.0,
+        )
+        resp.raise_for_status()
+        return resp.json()["choices"][0]["message"]["content"].strip()
+
+    def _build_prompt(self, query: str, response: str, context: str | None) -> str:
+        parts = [f"Query:\n{query}", f"\nOriginal response:\n{response}"]
+        if context:
+            parts.append(f"\nContext:\n{context}")
+        parts.append("\nRewrite the response to be more accurate and complete.")
+        return "\n".join(parts)