agenteval-toolkit 0.1.0__py3-none-any.whl

agenteval/evaluation/models.py

@@ -0,0 +1,174 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 The AgentEval Authors
+"""AI agent evaluation: models for papers, cases and results."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+AssertionType = Literal[
+    "contains", "contains_any", "contains_all", "not_contains",
+    "regex", "not_regex",
+    "tool_called", "tool_not_called",
+    "max_latency_ms", "min_chars", "max_chars",
+]
+
+
+# ---------------- Exam papers ----------------
+
+class Dimension(BaseModel):
+    id: str
+    name: str
+    weight: float
+    description: str = ""
+
+
+class Assertion(BaseModel):
+    type: AssertionType
+    value: Any = None
+    dimension: str
+    weight: float = 1.0
+    critical: bool = False          # critical: failing it scores the whole case 0 (veto)
+    args_contains: dict[str, Any] | None = None  # optional argument check for tool_called
+    description: str = ""
+
+
+class Turn(BaseModel):
+    user: str
+    expect: list[Assertion] = Field(default_factory=list)
+
+
+class RubricItem(BaseModel):
+    id: str
+    dimension: str
+    criterion: str
+    weight: float = 1.0
+    # Reference signal words for the offline heuristic judge (LLM judges use them as reference points)
+    signals: list[str] = Field(default_factory=list)
+
+
+class Case(BaseModel):
+    id: str
+    title: str
+    category: str
+    difficulty: Literal["easy", "medium", "hard"] = "medium"
+    weight: float = 1.0
+    tags: list[str] = Field(default_factory=list)
+    tool_mocks: dict[str, Any] = Field(default_factory=dict)
+    turns: list[Turn]
+    rubric: list[RubricItem] = Field(default_factory=list)
+
+
+class ExamPaper(BaseModel):
+    id: str
+    title: str
+    domain: str
+    version: str
+    language: str = "en"
+    description: str = ""
+    passing_score: float = 75.0
+    case_passing_score: float = 70.0
+    dimensions: list[Dimension]
+    context: str = ""               # Business context (e.g. policies, FAQ); optionally injected into the agent's system prompt
+    tools: list[dict[str, Any]] = Field(default_factory=list)  # OpenAI function format
+    cases: list[Case]
+
+
+# ---------------- Run results ----------------
+
+class ToolCall(BaseModel):
+    name: str
+    arguments: dict[str, Any] = Field(default_factory=dict)
+
+
+class AgentReply(BaseModel):
+    text: str
+    tool_calls: list[ToolCall] = Field(default_factory=list)
+    latency_ms: float = 0.0
+
+
+class TranscriptEntry(BaseModel):
+    role: Literal["user", "agent"]
+    content: str
+    tool_calls: list[ToolCall] = Field(default_factory=list)
+    latency_ms: float | None = None
+
+
+class AssertionResult(BaseModel):
+    turn: int
+    type: str
+    value: Any = None
+    dimension: str
+    weight: float
+    critical: bool
+    passed: bool
+    detail: str = ""
+    detail_code: str = ""
+    detail_params: dict[str, Any] = Field(default_factory=dict)
+
+
+class RubricResult(BaseModel):
+    id: str
+    dimension: str
+    criterion: str
+    weight: float
+    score: int | None = None        # 1–5; None means the judge failed
+    rationale: str = ""             # LLM judge's verbatim rationale, or the default Chinese text of a system message
+    rationale_code: str = ""        # system-generated rationales (heuristic/errors) use a code for multilingual rendering
+    rationale_params: dict[str, Any] = Field(default_factory=dict)
+
+
+class CaseResult(BaseModel):
+    id: str
+    title: str
+    category: str
+    difficulty: str
+    weight: float
+    score: float = 0.0
+    passed: bool = False
+    critical_failures: list[str] = Field(default_factory=list)
+    error: str | None = None
+    error_code: str = ""
+    error_params: dict[str, Any] = Field(default_factory=dict)
+    transcript: list[TranscriptEntry] = Field(default_factory=list)
+    assertions: list[AssertionResult] = Field(default_factory=list)
+    rubric: list[RubricResult] = Field(default_factory=list)
+
+
+class DimensionScore(BaseModel):
+    id: str
+    name: str
+    weight: float
+    score: float | None = None      # None means the dimension has no scorable items
+    items: int = 0
+
+
+class EvalStats(BaseModel):
+    cases: int = 0
+    cases_passed: int = 0
+    pass_rate: float = 0.0
+    critical_failures: int = 0
+    errors: int = 0
+    latency_p50_ms: float | None = None
+    latency_p95_ms: float | None = None
+
+
+class EvalRun(BaseModel):
+    run_id: str
+    paper_id: str
+    paper_title: str
+    paper_version: str
+    agent_name: str
+    judge: str
+    started_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    finished_at: datetime | None = None
+    overall_score: float = 0.0
+    grade: str = "F"
+    passed: bool = False
+    passing_score: float = 75.0
+    dimensions: list[DimensionScore] = Field(default_factory=list)
+    cases: list[CaseResult] = Field(default_factory=list)
+    stats: EvalStats = Field(default_factory=EvalStats)

agenteval/evaluation/papers.py

@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 The AgentEval Authors
+"""Exam paper library: loading, schema validation and consistency checks."""
+
+from __future__ import annotations
+
+import json
+from importlib import resources
+from pathlib import Path
+
+import yaml
+from jsonschema import Draft202012Validator
+
+from agenteval.config import content_dir
+
+from .models import ExamPaper
+
+
+class PaperError(Exception):
+    def __init__(self, errors: list[str]):
+        self.errors = errors
+        super().__init__("Exam paper validation failed:\n  " + "\n  ".join(errors))
+
+
+def default_exams_dir() -> Path:
+    return content_dir("exams", "AGENTEVAL_EXAMS_DIR")
+
+
+def _validator() -> Draft202012Validator:
+    text = resources.files("agenteval").joinpath("schemas/exam.schema.json").read_text(encoding="utf-8")
+    return Draft202012Validator(json.loads(text))
+
+
+def _consistency(p: ExamPaper) -> list[str]:
+    errs: list[str] = []
+    dims = {d.id for d in p.dimensions}
+    tools = {t.get("name") for t in p.tools}
+    seen: set[str] = set()
+    for c in p.cases:
+        if c.id in seen:
+            errs.append(f"{p.id}: duplicate case ID {c.id}")
+        seen.add(c.id)
+        rub_ids = [r.id for r in c.rubric]
+        if len(rub_ids) != len(set(rub_ids)):
+            errs.append(f"{p.id}/{c.id}: rubric id 重复")
+        for i, t in enumerate(c.turns):
+            for a in t.expect:
+                if a.dimension not in dims:
+                    errs.append(f"{p.id}/{c.id} turn {i + 1}: unknown dimension {a.dimension}")
+                if a.type in ("tool_called", "tool_not_called") and tools and a.value not in tools:
+                    errs.append(f"{p.id}/{c.id} turn {i + 1}: tool not declared by the paper {a.value}")
+                if a.type in ("contains_any", "contains_all") and not isinstance(a.value, list):
+                    errs.append(f"{p.id}/{c.id} turn {i + 1}: value of {a.type} must be a list")
+        for r in c.rubric:
+            if r.dimension not in dims:
+                errs.append(f"{p.id}/{c.id}: rubric {r.id} has unknown dimension {r.dimension}")
+        if not c.rubric and not any(t.expect for t in c.turns):
+            errs.append(f"{p.id}/{c.id}: no assertions or rubric items")
+    return errs
+
+
+def load_paper(path: str | Path) -> ExamPaper:
+    path = Path(path)
+    with path.open(encoding="utf-8") as fh:
+        doc = yaml.safe_load(fh)
+    errs = [f"{path.name} {'/'.join(map(str, e.path)) or '<root>'}: {e.message}"
+            for e in sorted(_validator().iter_errors(doc), key=lambda e: list(e.path))]
+    if errs:
+        raise PaperError(errs)
+    paper = ExamPaper.model_validate(doc)
+    errs = _consistency(paper)
+    if errs:
+        raise PaperError(errs)
+    return paper
+
+
+def load_papers(directory: str | Path | None = None) -> dict[str, ExamPaper]:
+    directory = Path(directory or default_exams_dir())
+    papers: dict[str, ExamPaper] = {}
+    errors: list[str] = []
+    for f in sorted(directory.rglob("*.y*ml")):
+        try:
+            p = load_paper(f)
+        except PaperError as e:
+            errors.extend(e.errors)
+            continue
+        if p.id in papers:
+            errors.append(f"{f.name}: 试卷 ID 重复 {p.id}")
+        papers[p.id] = p
+    if errors:
+        raise PaperError(errors)
+    return papers
+
+
+def resolve_paper(ref: str, directory: str | Path | None = None) -> ExamPaper:
+    """ref may be a paper file path or a paper ID from the library."""
+    p = Path(ref)
+    if p.suffix in (".yaml", ".yml") and p.exists():
+        return load_paper(p)
+    papers = load_papers(directory)
+    if ref not in papers:
+        raise PaperError([f"Exam paper not found: {ref} (available: {', '.join(sorted(papers))})"])
+    return papers[ref]

agenteval/evaluation/report.py

@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 The AgentEval Authors
+"""Evaluation report: JSON / HTML (zh/en UI). Paper content is shown as-is in the language it was written in."""
+
+from __future__ import annotations
+
+import json
+from importlib import resources
+
+from jinja2 import Environment, select_autoescape
+
+from .messages import fmt
+from .models import EvalRun
+
+UI = {
+    "zh": {
+        "html_lang": "zh-CN", "title": "AI Agent 评测报告", "paper": "试卷", "agent": "被测 Agent",
+        "judge": "裁判", "run": "评测 ID", "overall": "综合得分", "grade": "等级", "passed": "通过",
+        "not_passed": "未通过", "passing": "及格线", "cases": "样本", "case_pass_rate": "样本通过率",
+        "critical": "关键项失败", "latency": "延迟 p50 / p95", "dimensions": "维度得分", "dimension": "维度",
+        "weight": "权重", "score": "得分", "items_label": "评分项", "case_results": "样本明细",
+        "category": "类别", "difficulty": "难度", "status": "状态", "transcript": "对话记录",
+        "assertions": "断言", "rubric": "评分细则", "user": "用户", "agent_role": "Agent", "tools": "工具调用",
+        "error": "错误", "na": "无评分项", "case_pass": "通过", "case_fail": "未通过",
+        "heuristic_note": "本次使用离线启发式裁判（按参考信号词打分），主观维度仅供冒烟参考；正式评测请使用 LLM 裁判。",
+        "disclaimer": "评测结果反映被测 Agent 在本试卷样本上的表现，不代表其在所有真实场景中的表现。",
+    },
+    "en": {
+        "html_lang": "en", "title": "AI Agent Evaluation Report", "paper": "Exam", "agent": "Agent under test",
+        "judge": "Judge", "run": "Run ID", "overall": "Overall score", "grade": "Grade", "passed": "Passed",
+        "not_passed": "Not passed", "passing": "Passing score", "cases": "Cases", "case_pass_rate": "Case pass rate",
+        "critical": "Critical failures", "latency": "Latency p50 / p95", "dimensions": "Dimension scores",
+        "dimension": "Dimension", "weight": "Weight", "score": "Score", "items_label": "items",
+        "case_results": "Case results", "category": "Category", "difficulty": "Difficulty", "status": "Status",
+        "transcript": "Transcript", "assertions": "Assertions", "rubric": "Rubric", "user": "User",
+        "agent_role": "Agent", "tools": "Tool calls", "error": "Error", "na": "no scored items",
+        "case_pass": "Pass", "case_fail": "Fail",
+        "heuristic_note": ("This run used the offline heuristic judge (reference-signal matching). Subjective "
+                           "dimensions are a smoke-test signal only; use an LLM judge for formal evaluation."),
+        "disclaimer": ("Results reflect the agent's performance on this exam's samples and do not guarantee "
+                       "performance in all real-world scenarios."),
+    },
+}
+
+
+def to_json(run: EvalRun) -> str:
+    return run.model_dump_json(indent=2)
+
+
+def localize(run: EvalRun, lang: str) -> EvalRun:
+    """Re-format system-generated messages (assertion details, errors, heuristic rationales) for a language; returns a copy."""
+    if lang not in UI:
+        raise ValueError(f"Unsupported language: {lang}")
+    out = run.model_copy(deep=True)
+    for c in out.cases:
+        if c.error_code:
+            c.error = fmt(c.error_code, c.error_params, lang)
+        for a in c.assertions:
+            if a.detail_code:
+                a.detail = fmt(a.detail_code, a.detail_params, lang)
+        for g in c.rubric:
+            if g.rationale_code:
+                g.rationale = fmt(g.rationale_code, g.rationale_params, lang)
+    return out
+
+
+def to_html(run: EvalRun, lang: str = "zh") -> str:
+    run = localize(run, lang)
+    env = Environment(autoescape=select_autoescape(default=True, default_for_string=True))
+    env.filters["tojson"] = lambda v: json.dumps(v, ensure_ascii=False, default=str)
+    tpl = resources.files("agenteval").joinpath("reports/templates/eval_report.html.j2").read_text(encoding="utf-8")
+    return env.from_string(tpl).render(r=run, t=UI[lang])
+
+
+def render(run: EvalRun, fmt: str = "html", lang: str = "zh") -> str:
+    if fmt == "json":
+        return to_json(localize(run, lang))
+    if fmt == "html":
+        return to_html(run, lang)
+    raise ValueError(f"Unsupported format: {fmt}")

agenteval/evaluation/runner.py

@@ -0,0 +1,154 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 The AgentEval Authors
+"""Evaluation execution and overall scoring.
+
+Scoring rules:
+  - each item is normalized to [0, 1]: assertion pass = 1, fail = 0; rubric scores 1–5 map to (score-1)/4;
+  - case score = 100 × Σ(item weight × item score) / Σ item weight; a failed critical assertion sets the case score to 0;
+  - dimension score = 100 × Σ(case weight × item weight × item score) / Σ(case weight × item weight), over that dimension's items only;
+  - overall score = weighted mean of dimension scores by the paper's dimension weights (dimensions without items are excluded and weights re-normalized);
+  - pass condition: overall score ≥ passing_score and no critical failures.
+"""
+
+from __future__ import annotations
+
+import statistics
+import uuid
+from concurrent.futures import ThreadPoolExecutor
+from datetime import datetime, timezone
+
+from .adapters import Agent, AdapterError
+from .assertions import check
+from .judges import Judge
+from .messages import fmt
+from .models import (
+    AssertionResult, CaseResult, DimensionScore, EvalRun, EvalStats, ExamPaper, RubricResult, TranscriptEntry,
+)
+
+
+def grade_for(score: float) -> str:
+    for g, cut in (("A", 90), ("B", 80), ("C", 70), ("D", 60)):
+        if score >= cut:
+            return g
+    return "F"
+
+
+def _items(cr: CaseResult) -> list[tuple[str, float, float]]:
+    """List of (dimension, weight, normalized score); rubric items whose judge failed (score=None) are excluded."""
+    out = [(a.dimension, a.weight, 1.0 if a.passed else 0.0) for a in cr.assertions]
+    out += [(r.dimension, r.weight, (r.score - 1) / 4) for r in cr.rubric if r.score is not None]
+    return out
+
+
+def run_case(paper: ExamPaper, case, agent: Agent, judge: Judge) -> CaseResult:
+    cr = CaseResult(id=case.id, title=case.title, category=case.category,
+                    difficulty=case.difficulty, weight=case.weight)
+    session = None
+    try:
+        session = agent.new_session(paper, case)
+        for i, turn in enumerate(case.turns, start=1):
+            cr.transcript.append(TranscriptEntry(role="user", content=turn.user))
+            reply = session.send(turn.user)
+            cr.transcript.append(TranscriptEntry(role="agent", content=reply.text,
+                                                 tool_calls=reply.tool_calls, latency_ms=reply.latency_ms))
+            cr.assertions += [check(a, reply, i) for a in turn.expect]
+    except AdapterError as e:
+        cr.error, cr.error_code, cr.error_params = str(e), e.code, e.params
+        # Assertions that never ran count as failures, so an erroring agent is not penalized less
+        done = {(a.turn, a.type, str(a.value)) for a in cr.assertions}
+        for i, turn in enumerate(case.turns, start=1):
+            for a in turn.expect:
+                if (i, a.type, str(a.value)) not in done:
+                    cr.assertions.append(AssertionResult(
+                        turn=i, type=a.type, value=a.value, dimension=a.dimension, weight=a.weight,
+                        critical=a.critical, passed=False, detail=fmt("not_executed", {}),
+                        detail_code="not_executed"))
+    finally:
+        if session is not None:
+            session.close()
+
+    if case.rubric:
+        if cr.error:
+            cr.rubric = [RubricResult(id=r.id, dimension=r.dimension, criterion=r.criterion, weight=r.weight,
+                                      score=1, rationale=fmt("agent_error_min", {}), rationale_code="agent_error_min")
+                        for r in case.rubric]
+        else:
+            cr.rubric = judge.score(paper, case, cr.transcript, case.rubric)
+
+    cr.critical_failures = [f"T{a.turn}:{a.type}:{a.value}" for a in cr.assertions if a.critical and not a.passed]
+    items = _items(cr)
+    total_w = sum(w for _, w, _ in items)
+    cr.score = round(100 * sum(w * s for _, w, s in items) / total_w, 1) if total_w else 0.0
+    if cr.critical_failures or cr.error:
+        cr.score = 0.0
+    cr.passed = cr.score >= paper.case_passing_score
+    return cr
+
+
+def score_run(paper: ExamPaper, cases: list[CaseResult]) -> tuple[list[DimensionScore], float]:
+    dims = []
+    for d in paper.dimensions:
+        num = den = 0.0
+        n = 0
+        for cr in cases:
+            for dim, w, s in _items(cr):
+                if dim == d.id:
+                    num += cr.weight * w * s
+                    den += cr.weight * w
+                    n += 1
+        dims.append(DimensionScore(id=d.id, name=d.name, weight=d.weight,
+                                   score=round(100 * num / den, 1) if den else None, items=n))
+    scored = [d for d in dims if d.score is not None]
+    wsum = sum(d.weight for d in scored)
+    overall = round(sum(d.weight * d.score for d in scored) / wsum, 1) if wsum else 0.0
+    return dims, overall
+
+
+def _pct(values: list[float], q: float) -> float | None:
+    if not values:
+        return None
+    if len(values) == 1:
+        return round(values[0], 1)
+    return round(statistics.quantiles(values, n=100, method="inclusive")[int(q) - 1], 1)
+
+
+def run_exam(paper: ExamPaper, agent: Agent, judge: Judge, concurrency: int = 1,
+             case_ids: list[str] | None = None) -> EvalRun:
+    started = datetime.now(timezone.utc)
+    cases = [c for c in paper.cases if not case_ids or c.id in case_ids]
+    with ThreadPoolExecutor(max_workers=max(1, concurrency)) as pool:
+        results = list(pool.map(lambda c: run_case(paper, c, agent, judge), cases))
+
+    dims, overall = score_run(paper, results)
+    latencies = [t.latency_ms for r in results for t in r.transcript if t.role == "agent" and t.latency_ms is not None]
+    crit = sum(len(r.critical_failures) for r in results)
+    passed_cases = sum(1 for r in results if r.passed)
+    stats = EvalStats(
+        cases=len(results), cases_passed=passed_cases,
+        pass_rate=round(100 * passed_cases / len(results), 1) if results else 0.0,
+        critical_failures=crit, errors=sum(1 for r in results if r.error),
+        latency_p50_ms=_pct(latencies, 50), latency_p95_ms=_pct(latencies, 95),
+    )
+    return EvalRun(
+        run_id=uuid.uuid4().hex[:12], paper_id=paper.id, paper_title=paper.title, paper_version=paper.version,
+        agent_name=agent.name, judge=judge.name, started_at=started, finished_at=datetime.now(timezone.utc),
+        overall_score=overall, grade=grade_for(overall), passed=overall >= paper.passing_score and crit == 0,
+        passing_score=paper.passing_score, dimensions=dims, cases=results, stats=stats,
+    )
+
+
+def to_attestation(run: EvalRun, asset_id: str, rule_id: str = "FED-GOV-A02",
+                   attested_by: str = "agenteval-eval") -> dict:
+    """Turn a passing evaluation into an attestation entry usable by the compliance scan (as pre_deployment_testing evidence)."""
+    if not run.passed:
+        raise ValueError("Evaluation did not pass and cannot serve as pre-deployment testing attestation")
+    return {
+        "rule_id": rule_id,
+        "asset_id": asset_id,
+        "attested_by": attested_by,
+        "attested_at": run.finished_at.date().isoformat() if run.finished_at else None,
+        "evidence": {
+            "pre_deployment_testing": (f"agenteval-eval run {run.run_id}: {run.paper_id}@{run.paper_version} "
+                                       f"score={run.overall_score} grade={run.grade} judge={run.judge}"),
+        },
+    }

agenteval/i18n.py

@@ -0,0 +1,118 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 The AgentEval Authors
+"""Multilingual report support (zh / en).
+
+- Engine-generated messages are stored as message_code + message_params and formatted per language at render time;
+- rule titles, descriptions, remediation and source references come from rules/**/i18n/<lang>.yaml;
+- missing translations fall back to the source (English) text.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agenteval.models import ScanResult
+
+LANGS = ("zh", "en")
+DEFAULT_LANG = "en"  # source language of rules and engine messages
+
+MESSAGES: dict[str, dict[str, str]] = {
+    "ok": {"zh": "符合要求", "en": "Compliant"},
+    "check_failed": {"zh": "不符合: {title}", "en": "Non-compliant: {title}"},
+    "not_applicable": {"zh": "前置条件不满足，规则不适用", "en": "Precondition not met; rule not applicable"},
+    "att_missing": {"zh": "等待人工证明，需提供: {required}",
+                    "en": "Awaiting manual attestation; required evidence: {required}"},
+    "att_incomplete": {"zh": "证明材料不完整，缺少: {missing}",
+                       "en": "Attestation incomplete; missing: {missing}"},
+    "att_expired": {"zh": "证明已过期（{age} 天 > {max_age} 天），需重新评估",
+                    "en": "Attestation expired ({age} days > {max_age} days); re-assessment required"},
+    "att_no_date": {"zh": "证明缺少 attested_at 日期，无法判断有效期",
+                    "en": "Attestation has no attested_at date; validity cannot be determined"},
+    "att_ok": {"zh": "已提供有效的人工证明", "en": "Valid manual attestation provided"},
+    "eval_error": {"zh": "规则求值错误: {error}", "en": "Rule evaluation error: {error}"},
+}
+
+DISCLAIMER = {
+    "zh": "本报告为基于证据的技术控制项评估，不构成法律意见或合规认定。规则与法规的映射需经法务/合规团队审核。",
+    "en": ("This report is an evidence-based assessment of technical controls and does not constitute legal "
+           "advice or a determination of regulatory compliance. Rule-to-regulation mappings must be reviewed "
+           "by your legal/compliance team."),
+}
+
+UI: dict[str, dict[str, str]] = {
+    "zh": {
+        "html_lang": "zh-CN", "title": "AI 合规扫描报告", "scan_id": "扫描 ID", "source": "来源",
+        "rules_version": "规则集", "score": "自动项通过率", "assets": "资产", "failed": "不通过",
+        "manual": "待人工证明", "passed": "通过", "col_status": "状态", "col_severity": "严重度",
+        "col_rule": "规则", "col_asset": "资产", "col_detail": "说明与整改",
+        "remediation": "整改建议与依据", "evidence": "证据", "unverified": "（映射待审核）",
+        "status_fail": "不通过", "status_pass": "通过", "status_manual": "待证明",
+        "status_not_applicable": "不适用", "status_error": "错误",
+        "sev_critical": "严重", "sev_high": "高", "sev_medium": "中", "sev_low": "低", "sev_info": "信息",
+        "list_sep": "、",
+    },
+    "en": {
+        "html_lang": "en", "title": "AI Compliance Scan Report", "scan_id": "Scan ID", "source": "Source",
+        "rules_version": "Rule set", "score": "Automated pass rate", "assets": "Assets", "failed": "Failed",
+        "manual": "Awaiting attestation", "passed": "Passed", "col_status": "Status", "col_severity": "Severity",
+        "col_rule": "Rule", "col_asset": "Asset", "col_detail": "Details & remediation",
+        "remediation": "Remediation & basis", "evidence": "Evidence", "unverified": " (mapping pending review)",
+        "status_fail": "Fail", "status_pass": "Pass", "status_manual": "Pending",
+        "status_not_applicable": "N/A", "status_error": "Error",
+        "sev_critical": "Critical", "sev_high": "High", "sev_medium": "Medium", "sev_low": "Low", "sev_info": "Info",
+        "list_sep": ", ",
+    },
+}
+
+
+def check_lang(lang: str) -> str:
+    if lang not in LANGS:
+        raise ValueError(f"Unsupported language: {lang} (choose from: {', '.join(LANGS)})")
+    return lang
+
+
+def format_message(code: str, params: dict[str, Any], lang: str, title: str = "") -> str:
+    tpl = MESSAGES.get(code, {}).get(lang) or MESSAGES.get(code, {}).get(DEFAULT_LANG)
+    if not tpl:
+        return ""
+    sep = UI[lang]["list_sep"]
+    p = {k: (sep.join(map(str, v)) if isinstance(v, list) else v) for k, v in params.items()}
+    return tpl.format(title=title, **p)
+
+
+def localize_rule(rule_dict: dict, translations: dict, lang: str) -> dict:
+    """Replace a rule's (model_dump dict) title, description, remediation and sources with the target language."""
+    check_lang(lang)
+    if lang == DEFAULT_LANG:
+        return rule_dict
+    tr = translations.get(lang) or {}
+    out = dict(rule_dict)
+    for k in ("title", "description", "remediation"):
+        if tr.get(k):
+            out[k] = tr[k]
+    refs = tr.get("sources") or []
+    out["sources"] = [{**s, "reference": refs[i]} if i < len(refs) and refs[i] else s
+                      for i, s in enumerate(rule_dict.get("sources", []))]
+    return out
+
+
+def localize_result(result: ScanResult, lang: str) -> ScanResult:
+    """Return a copy with fields replaced by the target language (the original is not modified)."""
+    check_lang(lang)
+    if lang == DEFAULT_LANG:
+        return result
+    out = result.model_copy(deep=True)
+    out.disclaimer = DISCLAIMER[lang]
+    for f in out.findings:
+        tr = f.translations.get(lang) or {}
+        if tr.get("title"):
+            f.rule_title = tr["title"]
+        if tr.get("remediation"):
+            f.remediation = tr["remediation"]
+        refs = tr.get("sources") or []
+        for i, s in enumerate(f.sources):
+            if i < len(refs) and refs[i]:
+                s.reference = refs[i]
+        if f.message_code:
+            f.message = format_message(f.message_code, f.message_params, lang, f.rule_title)
+    return out