eduevidence 5.2.0

package/engine/library.py

@@ -0,0 +1,268 @@
+"""Snapshot-based Shared Research Library.
+
+Reusable research facts (Source/Study/Finding/MethodologyAudit) live in an
+immutable library revision model mirroring the Project GraphStore's
+crash-safe pattern. Projects import snapshots: a Project never evaluates
+directly against library JSONL, and a later library change never silently
+changes an existing Project's conclusions — only an explicit import/sync
+advances the Project graph.
+"""
+
+import hashlib
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+from engine.contracts import validate_record
+from engine.graph_store import GraphStore, GraphMutation, GraphRevision, _atomic_write_text
+
+LIBRARY_TABLES = ("sources", "studies", "findings", "audits")
+_TABLE_SCHEMA = {
+    "sources": "source",
+    "studies": "study",
+    "findings": "finding",
+    "audits": "methodology-audit",
+}
+_TABLE_ID_KEY = {
+    "sources": "source_id",
+    "studies": "study_id",
+    "findings": "finding_id",
+    "audits": "audit_id",
+}
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+class ResearchLibrary:
+    """Shared Research Library under `home/library/`."""
+
+    def __init__(self, home: Path):
+        self.home = Path(home).expanduser().resolve()
+        self.library_dir = self.home / "library"
+        self.revisions_dir = self.library_dir / "revisions"
+        self.head_path = self.library_dir / "HEAD"
+
+    @classmethod
+    def open(cls, home: Path) -> "ResearchLibrary":
+        lib = cls(home)
+        lib.revisions_dir.mkdir(parents=True, exist_ok=True)
+        if not lib.head_path.is_file():
+            _atomic_write_text(lib.head_path, "0")
+        return lib
+
+    def active_revision(self) -> int:
+        return int(self.head_path.read_text(encoding="utf-8").strip())
+
+    def _revision_dir(self, revision: int) -> Path:
+        return self.revisions_dir / f"rev-{revision:06d}"
+
+    def _read_snapshot(self, revision: int) -> dict[str, list[dict]]:
+        if revision == 0:
+            return {t: [] for t in LIBRARY_TABLES}
+        rev_dir = self._revision_dir(revision)
+        snapshot: dict[str, list[dict]] = {}
+        for table in LIBRARY_TABLES:
+            path = rev_dir / f"{table}.jsonl"
+            if not path.is_file():
+                raise FileNotFoundError(f"library revision {revision} missing {path.name}")
+            rows = [json.loads(line) for line in path.read_text(encoding="utf-8").splitlines() if line.strip()]
+            snapshot[table] = rows
+        return snapshot
+
+    def read_table(self, table: str) -> list[dict]:
+        if table not in LIBRARY_TABLES:
+            raise ValueError(f"unknown library table {table!r}")
+        return self._read_snapshot(self.active_revision())[table]
+
+    # ---- mutation --------------------------------------------------------
+
+    def add_verified_bundle(self, *, sources: list[dict], studies: list[dict],
+                            findings: list[dict], audits: list[dict]) -> int:
+        """Append verified facts as a new immutable library revision.
+
+        Returns the new revision number. Existing revisions are never
+        rewritten. Upserts are by entity id within each table.
+        """
+        before_rev = self.active_revision()
+        before = self._read_snapshot(before_rev)
+        after = {t: [dict(r) for r in rows] for t, rows in before.items()}
+        for table, incoming in (
+            ("sources", sources), ("studies", studies),
+            ("findings", findings), ("audits", audits),
+        ):
+            id_key = _TABLE_ID_KEY[table]
+            by_id = {r[id_key]: r for r in after[table]}
+            for rec in incoming:
+                errors = validate_record(_TABLE_SCHEMA[table], rec)
+                if errors:
+                    raise ValueError(f"library {table} {rec.get(id_key, '?')} invalid: {errors}")
+                by_id[rec[id_key]] = dict(rec)
+            after[table] = list(by_id.values())
+
+        next_rev = before_rev + 1
+        tmp_dir = self.revisions_dir / f".tmp-{next_rev:06d}"
+        tmp_dir.mkdir(parents=True, exist_ok=True)
+        try:
+            for table in LIBRARY_TABLES:
+                lines = "".join(
+                    json.dumps(r, sort_keys=True, separators=(",", ":")) + "\n"
+                    for r in after[table]
+                )
+                (tmp_dir / f"{table}.jsonl").write_text(lines, encoding="utf-8")
+            manifest = {
+                "revision": next_rev,
+                "parent_revision": before_rev,
+                "created_at": _now_iso(),
+                "extensions": {},
+            }
+            (tmp_dir / "manifest.json").write_text(
+                json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+            rev_dir = self._revision_dir(next_rev)
+            if rev_dir.exists():
+                raise FileExistsError(f"refusing to rewrite library revision {rev_dir}")
+            os.replace(tmp_dir, rev_dir)
+            _atomic_write_text(self.head_path, str(next_rev))
+        except Exception:
+            if tmp_dir.exists():
+                import shutil
+                shutil.rmtree(tmp_dir)
+            raise
+        return next_rev
+
+    # ---- find ------------------------------------------------------------
+
+    def find_source(self, canonical_locator: str) -> dict | None:
+        for src in self.read_table("sources"):
+            if src["canonical_locator"] == canonical_locator:
+                return src
+        return None
+
+    # ---- snapshot import -------------------------------------------------
+
+    def import_snapshot(self, *, project, source_ids: list[str],
+                        run_id: str) -> GraphRevision:
+        """Import the selected library facts into a Project graph revision.
+
+        Imported entities get `extensions.origin` metadata recording the
+        library revision/entity id/content hash, so the Project never depends
+        on the live library.
+        """
+        snapshot = self._read_snapshot(self.active_revision())
+        requested_ids = set(source_ids)
+        sources = [s for s in snapshot["sources"] if s["source_id"] in requested_ids]
+        if len(sources) != len(requested_ids):
+            missing = requested_ids - {s["source_id"] for s in sources}
+            raise ValueError(f"library has no sources for: {sorted(missing)}")
+        src_ids = {s["source_id"] for s in sources}
+        # a Study citing multiple sources must import them all (transitive
+        # closure) so cross-entity validation never sees a dangling reference
+        studies = [s for s in snapshot["studies"] if set(s["source_ids"]) & src_ids]
+        for s in studies:
+            extra = set(s["source_ids"]) - src_ids
+            if extra:
+                sources.extend(
+                    src for src in snapshot["sources"] if src["source_id"] in extra)
+                src_ids.update(extra)
+        study_ids = {s["study_id"] for s in studies}
+        findings = [f for f in snapshot["findings"] if f["study_id"] in study_ids]
+        audits = [a for a in snapshot["audits"] if a["study_id"] in study_ids]
+
+        lib_rev = self.active_revision()
+
+        # origin metadata per table: record library revision + entity id so the
+        def stamp(table: str, rec: dict) -> dict:
+            out = dict(rec)
+            ext = dict(out.get("extensions") or {})
+            ext["origin"] = {
+                "library_revision": lib_rev,
+                "library_entity_id": out[_TABLE_ID_KEY[table]],
+                "content_hash": hashlib.sha256(
+                    json.dumps(out, sort_keys=True, separators=(",", ":"))
+                    .encode("utf-8")).hexdigest(),
+                "imported_at": _now_iso(),
+            }
+            out["extensions"] = ext
+            return out
+        store = GraphStore.create(project)
+        existing_outcomes = {o["outcome_id"] for o in store.read_table("outcomes")}
+        outcomes: list[dict] = []
+        for f in findings:
+            oid = f["outcome_id"]
+            if oid in existing_outcomes:
+                continue
+            existing_outcomes.add(oid)
+            outcomes.append({
+                "outcome_id": oid,
+                "name": f.get("measure", oid),
+                "outcome_type": (f.get("extensions") or {}).get(
+                    "outcome_type", "learning"),
+                "extensions": {
+                    "auto_created_from_library_import": True,
+                    "library_revision": lib_rev,
+                },
+            })
+        mutation = GraphMutation(
+            upserts={
+                "sources": [stamp("sources", s) for s in sources],
+                "studies": [stamp("studies", s) for s in studies],
+                "findings": [stamp("findings", f) for f in findings],
+                "audits": [stamp("audits", a) for a in audits],
+                "outcomes": outcomes,
+            },
+            retire_ids={},
+        )
+        return store.commit(run_id=run_id, reason="library snapshot import", mutation=mutation)
+
+    def diff_project_snapshot(self, *, project, source_ids: list[str]) -> dict:
+        """Diff imported facts vs the current library revision.
+
+        Compares every library entity reachable from the selected source_ids
+        (sources/studies/findings/audits) against the Project graph's copy
+        (ignoring import origin metadata). Returns added/changed/removed
+        entity ids so the caller can decide whether an explicit sync is
+        warranted.
+        """
+        snapshot = self._read_snapshot(self.active_revision())
+        src_ids = set(source_ids)
+        lib_sources = {s["source_id"]: s for s in snapshot["sources"] if s["source_id"] in src_ids}
+        lib_studies = {s["study_id"]: s for s in snapshot["studies"]
+                       if set(s["source_ids"]) & src_ids}
+        lib_findings = {f["finding_id"]: f for f in snapshot["findings"]
+                        if f["study_id"] in lib_studies}
+        lib_audits = {a["audit_id"]: a for a in snapshot["audits"]
+                      if a["study_id"] in lib_studies}
+        lib_entities: dict[str, tuple[str, dict]] = {}
+        for table, ents in (("sources", lib_sources), ("studies", lib_studies),
+                            ("findings", lib_findings), ("audits", lib_audits)):
+            for eid, rec in ents.items():
+                lib_entities[eid] = (table, rec)
+
+        store = GraphStore.create(project)
+        proj_by_table = {
+            t: {r[_TABLE_ID_KEY[t]]: r for r in store.read_table(t)}
+            for t in LIBRARY_TABLES
+        }
+        diff: dict = {"added": [], "changed": [], "removed": []}
+        for eid, (table, lib_rec) in lib_entities.items():
+            proj_rec = proj_by_table[table].get(eid)
+            if proj_rec is None:
+                diff["added"].append(eid)
+                continue
+            lib_content = {k: v for k, v in lib_rec.items() if k != "extensions"}
+            proj_content = {k: v for k, v in proj_rec.items() if k != "extensions"}
+            if lib_content != proj_content:
+                diff["changed"].append(eid)
+        for table in LIBRARY_TABLES:
+            for eid, rec in proj_by_table[table].items():
+                if eid in lib_entities:
+                    continue
+                # only entities imported FROM this library may be reported
+                # removed; project-local entities are never "removed" by a
+                # library diff
+                origin = ((rec.get("extensions") or {}).get("origin") or {})
+                if origin.get("library_revision") is not None:
+                    diff["removed"].append(eid)
+        return diff

package/engine/library_builtin.py

@@ -0,0 +1,301 @@
+"""Builtin evidence library + offline preliminary verdict (v4).
+
+Two entry points:
+
+  load_builtin_library()      -> read benchmarks/evidence-library.json, validate
+                                 structurally, cache (lru_cache), return a deep
+                                 copy. Raises FileNotFoundError when the library
+                                 has not been built yet and ValueError when the
+                                 shape is invalid.
+
+  preliminary_verdict(question, *, top_k=10)
+                              -> deterministic offline screening verdict. Matching
+                                 is Chinese-keyword / outcome-token based using
+                                 CJK bigram overlap (self-implemented; mirrors the
+                                 logic of scripts/benchmark_evaluator.py without
+                                 importing it): the question is tokenized into CJK
+                                 bigrams + English words, each library entry is
+                                 scored by bigram overlap over
+                                 claim_text + effect_summary + title, and the
+                                 top_k entries above MATCH_THRESHOLD with at least
+                                 MIN_SHARED_BIGRAMS shared tokens count as matched.
+
+Conservative verdict rules (offline preliminary gate):
+    any matched contradict entry -> reject
+    else any matched support  entry -> pilot
+    else                            -> insufficient_evidence
+    adopt is NEVER returned by the preliminary gate.
+
+Output:
+    {"verdict": ..., "coverage": {"matched_entries": [...],
+     "matched_outcome_tokens": [...], "note": "..."},
+     "preliminary": True, "library_version": ...}
+
+This module is stdlib-only (consistent with engine/ "Native Core" policy).
+"""
+from __future__ import annotations
+
+import json
+import re
+from copy import deepcopy
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+ROOT = Path(__file__).resolve().parent.parent
+def _resolve_library_path() -> Path:
+    """Repository layout first; wheel-installed share/ layout as fallback."""
+    repo = ROOT / "benchmarks" / "evidence-library.json"
+    if repo.is_file():
+        return repo
+    import sys
+    share = Path(sys.prefix) / "share" / "eduevidence" / "benchmarks" / "evidence-library.json"
+    if share.is_file():
+        return share
+    return repo
+
+
+LIBRARY_PATH = _resolve_library_path()
+
+# --- matching knobs (conservative) ---
+MATCH_THRESHOLD = 0.30       # min bigram-overlap ratio (intersection / min sizes)
+MIN_SHARED_BIGRAMS = 2       # min absolute shared tokens (blocks tiny-query over-match)
+
+VERDICT_ORDER = ("adopt", "pilot", "reject", "insufficient_evidence")
+DIRECTIONS = ("support", "contradict", "neutral")
+
+# ---------------------------------------------------------------------------
+# tokenization (self-implemented, mirrors scripts/benchmark_evaluator.py)
+# ---------------------------------------------------------------------------
+_ID_RE = re.compile(r"\b([A-Za-z][A-Za-z-]{1,40})\b")
+
+
+def _cjk_bigrams(text: str) -> set[str]:
+    chars = [c for c in text if "\u4e00" <= c <= "\u9fff"]
+    return {chars[i] + chars[i + 1] for i in range(len(chars) - 1)}
+
+
+def _words(text: str) -> set[str]:
+    return {w.lower() for w in _ID_RE.findall(text) if len(w) > 2}
+
+
+def _tokenize(text: str) -> set[str]:
+    return _cjk_bigrams(text) | _words(text)
+
+
+def _overlap_tokens(ta: set[str], tb: set[str]) -> float:
+    if not ta or not tb:
+        return 0.0
+    return len(ta & tb) / max(1, min(len(ta), len(tb)))
+
+
+# ---------------------------------------------------------------------------
+# outcome-token detection (Chinese terms + direct English taxonomy words)
+# ---------------------------------------------------------------------------
+_OUTCOME_TAXONOMY = {
+    "accuracy", "assignment_score", "retention", "transfer",
+    "independent_problem_solving", "completion_time", "cognitive_load",
+    "knowledge_gain", "concept_understanding", "engagement", "motivation",
+    "metacognition", "help_seeking", "code_quality", "ai_dependency",
+    "over_reliance", "reduced_effort", "reduced_transfer",
+    "academic_integrity_risk", "false_confidence",
+}
+
+_CN_OUTCOME_TERMS = {
+    "正确率": "accuracy", "准确率": "accuracy", "正确性": "accuracy",
+    "期末考试成绩": "assignment_score", "考试成绩": "assignment_score",
+    "作业得分": "assignment_score", "作业成绩": "assignment_score",
+    "成绩": "assignment_score", "得分": "assignment_score",
+    "记忆保持": "retention", "保持率": "retention", "保持": "retention",
+    "保留": "retention", "记忆": "retention",
+    "迁移能力": "transfer", "迁移": "transfer",
+    "独立问题解决": "independent_problem_solving",
+    "独立写作": "independent_problem_solving", "独立编程": "independent_problem_solving",
+    "独立解题": "independent_problem_solving", "脱离工具": "independent_problem_solving",
+    "无AI情境": "independent_problem_solving", "独立": "independent_problem_solving",
+    "任务完成时间": "completion_time", "完成时间": "completion_time",
+    "速度": "completion_time",
+    "认知负荷": "cognitive_load", "负荷": "cognitive_load",
+    "知识获得": "knowledge_gain", "知识": "knowledge_gain",
+    "概念理解": "concept_understanding", "概念": "concept_understanding",
+    "参与度": "engagement", "参与": "engagement", "投入": "engagement",
+    "学习动机": "motivation", "动机": "motivation", "兴趣": "motivation",
+    "元认知": "metacognition",
+    "求助行为": "help_seeking", "求助": "help_seeking",
+    "代码质量": "code_quality",
+    "过度依赖": "over_reliance", "AI依赖": "ai_dependency",
+    "依赖": "ai_dependency",
+    "减少努力": "reduced_effort", "努力": "reduced_effort",
+    "迁移受损": "reduced_transfer", "迁移下降": "reduced_transfer",
+    "学术诚信": "academic_integrity_risk", "诚信": "academic_integrity_risk",
+    "作弊": "academic_integrity_risk", "原创性": "academic_integrity_risk",
+    "虚假自信": "false_confidence",
+}
+# longest phrase first so "保持率" wins over "保持", "期末考试成绩" over "成绩", ...
+_CN_OUTCOME_ORDERED = sorted(_CN_OUTCOME_TERMS.items(), key=lambda kv: -len(kv[0]))
+
+
+def _detect_outcome_tokens(question: str) -> set[str]:
+    tokens: set[str] = set()
+    for phrase, outcome in _CN_OUTCOME_ORDERED:
+        if phrase in question:
+            tokens.add(outcome)
+    tokens |= {w for w in _words(question) if w in _OUTCOME_TAXONOMY}
+    return tokens
+
+
+# ---------------------------------------------------------------------------
+# library loading: validate + cache
+# ---------------------------------------------------------------------------
+_TOP_REQUIRED = {"library_id", "version", "generated_at", "entries", "coverage_note"}
+_ENTRY_REQUIRED = {
+    "entry_id", "source_id", "title", "year", "outcome_token", "direction",
+    "study_type", "claim_text", "effect_summary", "confidence_markers", "domains",
+}
+
+
+def _validate_library_shape(lib: dict[str, Any]) -> None:
+    """Structural validation of the builtin library (stdlib-only).
+
+    Keeps the engine dependency-free; the full JSON-Schema check lives in the
+    build script (scripts/build_evidence_library.py -> validate_schema.Validator).
+    """
+    if not isinstance(lib, dict):
+        raise ValueError("builtin library must be a JSON object")
+    missing = _TOP_REQUIRED - lib.keys()
+    if missing:
+        raise ValueError(f"builtin library missing required fields: {sorted(missing)}")
+    entries = lib.get("entries")
+    if not isinstance(entries, list) or not entries:
+        raise ValueError("builtin library entries must be a non-empty list")
+    for idx, entry in enumerate(entries):
+        if not isinstance(entry, dict):
+            raise ValueError(f"entry[{idx}] must be an object")
+        miss = _ENTRY_REQUIRED - entry.keys()
+        if miss:
+            raise ValueError(f"entry[{idx}] missing required fields: {sorted(miss)}")
+        if entry["direction"] not in DIRECTIONS:
+            raise ValueError(
+                f"entry[{idx}] direction {entry['direction']!r} not in {sorted(DIRECTIONS)}"
+            )
+        for field in ("entry_id", "source_id", "title", "outcome_token",
+                      "claim_text", "effect_summary", "study_type"):
+            if not isinstance(entry[field], str) or not entry[field].strip():
+                raise ValueError(f"entry[{idx}] {field!r} must be a non-empty string")
+        if entry["year"] is not None and (
+            not isinstance(entry["year"], int) or isinstance(entry["year"], bool)
+        ):
+            raise ValueError(f"entry[{idx}] year must be integer or null")
+        if not isinstance(entry["confidence_markers"], list):
+            raise ValueError(f"entry[{idx}] confidence_markers must be a list")
+        if not isinstance(entry["domains"], list) or not entry["domains"]:
+            raise ValueError(f"entry[{idx}] domains must be a non-empty list")
+
+
+@lru_cache(maxsize=1)
+def _read_library() -> dict[str, Any]:
+    if not LIBRARY_PATH.is_file():
+        raise FileNotFoundError(
+            f"builtin evidence library not found: {LIBRARY_PATH}; "
+            "run 'python scripts/build_evidence_library.py' first"
+        )
+    lib = json.loads(LIBRARY_PATH.read_text(encoding="utf-8"))
+    _validate_library_shape(lib)
+    return lib
+
+
+def load_builtin_library() -> dict[str, Any]:
+    """Load (validated + cached) builtin library; returns a deep copy."""
+    return deepcopy(_read_library())
+
+
+# ---------------------------------------------------------------------------
+# preliminary verdict
+# ---------------------------------------------------------------------------
+def _entry_text(entry: dict[str, Any]) -> str:
+    return " ".join(
+        str(entry.get(k) or "")
+        for k in ("claim_text", "effect_summary", "title")
+    )
+
+
+def preliminary_verdict(question: str, *, top_k: int = 10) -> dict[str, Any]:
+    """Offline conservative preliminary verdict for a (Chinese) education question.
+
+    Matching: CJK bigram overlap between the question and each entry's
+    claim_text + effect_summary + title; the top_k entries are considered and an
+    entry counts as matched when overlap >= MATCH_THRESHOLD and it shares at
+    least MIN_SHARED_BIGRAMS tokens. Verdict: contradict => reject, else
+    support => pilot, else insufficient_evidence. Never adopt. Never crashes on
+    empty/blank questions.
+    """
+    try:
+        top_k = int(top_k)
+    except (TypeError, ValueError):
+        top_k = 10
+    lib = _read_library()
+    question = (question or "").strip()
+    q_tokens = _tokenize(question)
+    q_outcomes = _detect_outcome_tokens(question)
+
+    scored: list[tuple[float, int, bool, dict[str, Any]]] = []
+    for entry in lib["entries"]:
+        e_tokens = _tokenize(_entry_text(entry))
+        base = _overlap_tokens(q_tokens, e_tokens)
+        shared = len(q_tokens & e_tokens)
+        # multi-outcome entries match when ANY of their tokens is in the question
+        entry_tokens = set(entry.get("outcome_tokens") or [entry.get("outcome_token")])
+        has_outcome = bool(entry_tokens & q_outcomes)
+        scored.append((base, shared, has_outcome, entry))
+
+    scored.sort(key=lambda t: (-t[0], -t[1], -int(t[2]), t[3].get("entry_id", "")))
+    top = scored[: max(0, int(top_k))]
+
+    matched = [
+        entry
+        for base, shared, _has_outcome, entry in top
+        if base >= MATCH_THRESHOLD and shared >= MIN_SHARED_BIGRAMS
+    ]
+
+    directions = {entry["direction"] for entry in matched}
+    if "contradict" in directions:
+        verdict = "reject"
+    elif "support" in directions:
+        verdict = "pilot"
+    else:
+        verdict = "insufficient_evidence"
+
+    note = _build_note(matched, directions, q_outcomes, top_k)
+    return {
+        "verdict": verdict,
+        "coverage": {
+            "matched_entries": [entry["entry_id"] for entry in matched],
+            "matched_outcome_tokens": sorted(q_outcomes),
+            "note": note,
+        },
+        "preliminary": True,
+        "library_version": lib.get("version", ""),
+    }
+
+
+def _build_note(
+    matched: list[dict[str, Any]],
+    directions: set[str],
+    q_outcomes: set[str],
+    top_k: int,
+) -> str:
+    outcome_str = "、".join(sorted(q_outcomes)) or "无"
+    if not matched:
+        return (
+            f"离线初步裁决未匹配到内置证据（阈值：bigram overlap≥{MATCH_THRESHOLD} 且"
+            f"共享 bigram≥{MIN_SHARED_BIGRAMS}）；检测到结局词：{outcome_str}。"
+            "建议进入在线证据检索流程进一步核实。"
+        )
+    counts = {d: sum(1 for e in matched if e["direction"] == d) for d in DIRECTIONS}
+    return (
+        f"离线初步裁决在 top_k={top_k} 内匹配到 {len(matched)} 条内置证据："
+        f"support={counts['support']}、contradict={counts['contradict']}、"
+        f"neutral={counts['neutral']}；匹配结局词：{outcome_str}。"
+        "本裁决为初步（preliminary=true）且保守，从不直接给出 adopt，"
+        "建议结合完整证据库与在线检索复核。"
+    )