eduevidence 6.2.0 → 6.3.0

package/integrations/semantic_decide.py

@@ -0,0 +1,286 @@
+"""SemDecide CLI integration (experimental mode 2 / hybrid 3).
+
+Exit 2/3/4 never resolve silently — escalate to the host large model.
+Secrets stay in env files; never passed on argv.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any
+
+SEMDECIDE_ENV_FILE = os.environ.get("JEV_ENV_FILE", "~/.eduevidence/env")
+SEMDECIDE_BIN_ENV = "SEMDECIDE_BIN"
+SEMDECIDE_UNAVAILABLE = "SEMDECIDE_UNAVAILABLE"
+SEMDECIDE_APPROVAL_REQUIRED = "SEMDECIDE_APPROVAL_REQUIRED"
+ESCALATE_TO_LLM = "ESCALATE_TO_LLM"
+DEFAULT_THRESHOLD = 0.7
+DEFAULT_TIMEOUT = 10.0
+DEFAULT_MIN_CONFIDENCE = 0.0
+SEMDECIDE_TIMEOUT = DEFAULT_TIMEOUT
+EXIT_OK = 0
+EXIT_FALSE = 1
+ESCALATE_EXIT_CODES = frozenset({2, 3, 4})
+EXIT_MEANINGS = {
+    0: "true/selected/match",
+    1: "false/no match",
+    2: "invalid input",
+    3: "uncertain",
+    4: "provider failure",
+}
+WRAPPED_COMMANDS = ("is", "filter", "choose", "score", "guard")
+
+def _env_file_values(path: str | Path | None = None) -> dict[str, str]:
+    try:
+        text = Path(os.path.expanduser(path or SEMDECIDE_ENV_FILE)).read_text(
+            encoding="utf-8")
+    except OSError:
+        return {}
+    values: dict[str, str] = {}
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        if line.startswith("export "):
+            line = line[len("export "):]
+        key, _, value = line.partition("=")
+        values[key.strip()] = value.strip().strip("\"'")
+    return values
+
+
+def binary_path() -> str | None:
+    override = os.environ.get(SEMDECIDE_BIN_ENV)
+    if override and os.path.exists(os.path.expanduser(override)):
+        return os.path.expanduser(override)
+    return shutil.which("semdecide")
+
+
+def detect_semdecide() -> dict[str, Any]:
+    """Probe the local semdecide CLI (never the network)."""
+    path = binary_path()
+    env_values = _env_file_values()
+    has_key = bool(
+        os.environ.get("TYPESAFE_API_KEY")
+        or env_values.get("TYPESAFE_API_KEY")
+        or os.environ.get("AI_GATEWAY_API_KEY")
+        or env_values.get("AI_GATEWAY_API_KEY")
+    )
+    available = path is not None
+    reasons: list[str] = []
+    if not available:
+        reasons.append("semdecide binary not on PATH (pipx/uv tool install "
+                       "from sharziki/semdecide release wheel)")
+    if not has_key:
+        reasons.append("TYPESAFE_API_KEY / AI_GATEWAY_API_KEY not set — "
+                       "semdecide will exit 4 (provider_failure)")
+    return {
+        "available": available,
+        "state": "available" if available else "unavailable",
+        "mode": "semdecide" if available else "none",
+        "binary": path,
+        "credentials_declared": has_key,
+        "reason": "; ".join(reasons) or "semdecide on PATH",
+        "reasons": reasons,
+        "hint": ("install: pipx install "
+                 "https://github.com/sharziki/semdecide/releases/download/"
+                 "v0.2.1/semdecide-0.2.1-py3-none-any.whl"
+                 if not available else ""),
+        "commands": list(WRAPPED_COMMANDS),
+        "escalate_exit_codes": sorted(ESCALATE_EXIT_CODES),
+    }
+
+
+
+def requires_llm_escalation(result: dict[str, Any]) -> bool:
+    """True for exit 2 / 3 / 4 (and missing binary)."""
+    if result.get("status") == SEMDECIDE_UNAVAILABLE:
+        return True
+    return result.get("exit_code") in ESCALATE_EXIT_CODES
+
+
+def _run(argv: list[str], *, stdin_text: str | None = None,
+         timeout: float = DEFAULT_TIMEOUT) -> dict[str, Any]:
+    path = binary_path()
+    if not path:
+        return {
+            "status": SEMDECIDE_UNAVAILABLE,
+            "exit_code": None,
+            "escalate": ESCALATE_TO_LLM,
+            "reason": "semdecide binary not found",
+        }
+    # Credentials come from the process env / credentials.env — never argv.
+    env = os.environ.copy()
+    for key, value in _env_file_values().items():
+        env.setdefault(key, value)
+    try:
+        proc = subprocess.run(
+            [path, *argv],
+            input=stdin_text if stdin_text is not None else "",
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            env=env,
+        )
+    except subprocess.TimeoutExpired:
+        return {
+            "status": "SEMDECIDE_TIMEOUT",
+            "exit_code": None,
+            "escalate": ESCALATE_TO_LLM,
+            "reason": f"semdecide timed out after {timeout}s",
+        }
+    except OSError as exc:
+        return {
+            "status": SEMDECIDE_UNAVAILABLE,
+            "exit_code": None,
+            "escalate": ESCALATE_TO_LLM,
+            "reason": f"semdecide spawn failed: {type(exc).__name__}",
+        }
+
+    code = proc.returncode
+    stdout = proc.stdout or ""
+    stderr = proc.stderr or ""
+    payload: Any = None
+    if stdout.strip().startswith("{") or stdout.strip().startswith("["):
+        try:
+            payload = json.loads(stdout)
+        except json.JSONDecodeError:
+            payload = None
+
+    escalate = code in ESCALATE_EXIT_CODES
+    return {
+        "status": "ok" if code in (EXIT_OK, EXIT_FALSE) else EXIT_MEANINGS.get(
+            code, "unknown_exit"),
+        "exit_code": code,
+        "exit_meaning": EXIT_MEANINGS.get(code, "unknown_exit"),
+        "stdout": stdout,
+        "stderr": stderr[-2000:],
+        "json": payload,
+        "escalate": ESCALATE_TO_LLM if escalate else None,
+        "requires_llm": escalate,
+    }
+
+
+
+def is_predicate(text: str, predicate: str, *, threshold: float = DEFAULT_THRESHOLD,
+                 uncertainty_margin: float = 0.0, use_json: bool = True,
+                 timeout: float = DEFAULT_TIMEOUT) -> dict[str, Any]:
+    """`semdecide is` — semantic predicate. Exit 2/3/4 escalate to the LLM."""
+    argv = ["is", predicate, f"--threshold={threshold}",
+            f"--uncertainty-margin={uncertainty_margin}"]
+    if use_json:
+        argv.append("--json")
+    result = _run(argv, stdin_text=text, timeout=timeout)
+    result["command"] = "is"
+    result["predicate"] = predicate
+    if isinstance(result.get("json"), dict):
+        result["verdict"] = result["json"].get("verdict")
+        result["probability"] = result["json"].get("probability")
+        result["confidence"] = result["json"].get("confidence")
+    return result
+
+
+def filter_records(records: list[dict[str, Any]] | str, predicate: str, *,
+                   field: str | None = "text", raw: bool = False,
+                   max_records: int | None = None,
+                   timeout: float = DEFAULT_TIMEOUT) -> dict[str, Any]:
+    """`semdecide filter` — semantic JSONL filtering (order preserved)."""
+    if isinstance(records, str):
+        jsonl = records
+    else:
+        jsonl = "\n".join(json.dumps(r, ensure_ascii=False) for r in records)
+    argv = ["filter", predicate]
+    if field:
+        argv.extend(["--field", field])
+    if raw:
+        argv.append("--raw")
+    if max_records is not None:
+        argv.extend(["--max-records", str(int(max_records))])
+    result = _run(argv, stdin_text=jsonl + ("\n" if jsonl else ""), timeout=timeout)
+    result["command"] = "filter"
+    result["predicate"] = predicate
+    matched: list[Any] = []
+    for line in (result.get("stdout") or "").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            matched.append(json.loads(line))
+        except json.JSONDecodeError:
+            matched.append(line)
+    result["matched"] = matched
+    result["match_count"] = len(matched)
+    # filter: exit 1 means no definite match — not an escalation by itself.
+    if result.get("exit_code") == EXIT_FALSE:
+        result["escalate"] = None
+        result["requires_llm"] = False
+    return result
+
+
+def choose_route(text: str, question: str,
+                 options: dict[str, str], *,
+                 min_confidence: float = DEFAULT_MIN_CONFIDENCE,
+                 use_json: bool = True,
+                 timeout: float = DEFAULT_TIMEOUT) -> dict[str, Any]:
+    """`semdecide choose` — route among named options. Exit 2/3/4 escalate."""
+    argv = ["choose", question, f"--min-confidence={min_confidence}"]
+    for key, description in options.items():
+        argv.append(f"--option={key}={description}")
+    if use_json:
+        argv.append("--json")
+    result = _run(argv, stdin_text=text, timeout=timeout)
+    result["command"] = "choose"
+    result["question"] = question
+    if isinstance(result.get("json"), dict):
+        result["selected"] = result["json"].get("selected") or result["json"].get("choice")
+        result["probabilities"] = result["json"].get("probabilities")
+        result["confidence"] = result["json"].get("confidence")
+    return result
+
+
+def escalate_plan(result: dict[str, Any], *, stage: str = "") -> dict[str, Any]:
+    """Build the fail-closed hand-off when exit is 2/3/4 (or binary missing)."""
+    code = result.get("exit_code")
+    meaning = result.get("exit_meaning") or EXIT_MEANINGS.get(code, "unknown")
+    return {
+        "action": ESCALATE_TO_LLM,
+        "reason": meaning,
+        "exit_code": code,
+        "stage": stage,
+        "policy": {
+            2: "invalid input — repair inputs and re-run, or hand the whole "
+               "decision to the large model (never invent a verdict)",
+            3: "uncertain under margin — route to large model / human; do not "
+               "force true/false",
+            4: "provider failure — degrade to large model for this call only; "
+               "record the attempt",
+        }.get(code if isinstance(code, int) else -1,
+              "unavailable — use Platform Native / large model path"),
+        "raw_status": result.get("status"),
+    }
+
+
+
+__all__ = [
+    "DEFAULT_THRESHOLD", "DEFAULT_TIMEOUT", "ESCALATE_TO_LLM",
+    "SEMDECIDE_APPROVAL_REQUIRED", "SEMDECIDE_BIN_ENV", "SEMDECIDE_ENV_FILE",
+    "SEMDECIDE_UNAVAILABLE", "binary_path", "choose_route", "detect_semdecide",
+    "escalate_plan", "filter_records", "is_predicate", "requires_llm_escalation",
+]
+
+
+if __name__ == "__main__":
+    # `python3 integrations/semantic_decide.py ...` runs this file as a script,
+    # so the repository root must be importable before `integrations.*` is used.
+    # The CLI itself lives in integrations/semdecide_cli.py (file-size budget).
+    import sys as _sys
+
+    _ROOT = Path(__file__).resolve().parent.parent
+    if str(_ROOT) not in _sys.path:
+        _sys.path.insert(0, str(_ROOT))
+
+    from integrations.semdecide_cli import main as _cli_main
+
+    raise SystemExit(_cli_main())

package/integrations/semdecide_cli.py

@@ -0,0 +1,55 @@
+"""SemDecide detect CLI: the documented `--experimental <mode>` entry point.
+
+Kept separate from `integrations/semantic_decide.py` so the wrapper module stays
+inside the repository's 300-line file budget, the same way the Jev layer keeps
+its CLI in `integrations/jev/cli.py`.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+from typing import Any
+
+from integrations.semantic_decide import (
+    ESCALATE_EXIT_CODES,
+    WRAPPED_COMMANDS,
+    detect_semdecide,
+)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Detect probe: local binary/credential state plus the resolved mode plan."""
+    parser = argparse.ArgumentParser(
+        description="SemDecide experimental detect probe (never calls the network)")
+    parser.add_argument("--experimental", nargs="?", const="1", default=None,
+                        metavar="MODE",
+                        help="enable experimental mode 0|1|2|3 (default 1) and "
+                             "print the resolved plan")
+    args = parser.parse_args(argv)
+
+    out: dict[str, Any] = {"detect": detect_semdecide()}
+    if args.experimental is not None:
+        from integrations.jev.config import MODE_HYBRID, MODE_SEMDECIDE, MODE_STANDARD
+        from integrations.jev.modes import resolve_experimental_mode
+
+        mode = resolve_experimental_mode(args.experimental)
+        out["experimental"] = {
+            "mode": mode,
+            "mode_name": {0: "standard", 1: "jev-mcp", 2: "semdecide",
+                          3: "hybrid"}.get(mode, str(mode)),
+            "enabled": mode in (MODE_SEMDECIDE, MODE_HYBRID),
+            "active": mode != MODE_STANDARD,
+            "commands": list(WRAPPED_COMMANDS),
+            "escalate_exit_codes": sorted(ESCALATE_EXIT_CODES),
+            "fail_closed": ("exit 2/3/4 and a missing binary escalate to the "
+                            "large model; filter exit 1 alone does not"),
+        }
+    print(json.dumps(out, ensure_ascii=False, indent=2))
+    return 0
+
+
+__all__ = ["main"]
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eduevidence",
-  "version": "6.2.0",
+  "version": "6.3.0",
   "description": "Evidence research and decision skill with education and organizational policy domains.",
   "license": "MIT",
   "author": "EduEvidence Contributors",
@@ -40,6 +40,9 @@
     "references/",
     "schemas/",
     "scripts/",
+    "!scripts/build_esl_artifacts.py",
+    "!scripts/generate_new_projects.py",
+    "!scripts/enrich_projects_human_and_lieflat.py",
     "retrieval/",
     "integrations/",
     "visualization/eduevidence-report/",
@@ -52,6 +55,9 @@
     "setup.py",
     "docs/architecture.md",
     "docs/sciverse-api.md",
+    "docs/reproducibility.md",
+    "docs/j-ev-experimental.md",
+    "CHANGELOG.md",
     "CONTRIBUTING.md",
     "web/architecture.html",
     "docs/install-guide.md",
@@ -69,9 +75,11 @@
     "examples/ai-coding-assistant-evidence/reports-5themes/*.html",
     "examples/workplace-ai-assistant/*.json",
     "examples/workplace-ai-assistant/*.jsonl",
+    "examples/workplace-ai-assistant/*.html",
     "examples/workplace-ai-assistant/reports-5themes/*.html",
     "examples/spaced-retrieval-practice/*.json",
     "examples/spaced-retrieval-practice/*.jsonl",
+    "examples/spaced-retrieval-practice/*.html",
     "examples/spaced-retrieval-practice/reports-5themes/*.html",
     "docs/demo-workplace-ai.md",
     "docs/demo.md",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "eduevidence"
-version = "6.2.0"
+version = "6.3.0"
 description = "Evidence research and decision skill with education and organizational policy domains."
 readme = "README.md"
 requires-python = ">=3.10"

package/references/report-copy-style.md

@@ -32,7 +32,47 @@
 
 英文字数上限按等义折算（约为中文字数 ÷ 3 个单词）。
 
-## 4. 术语对照
+## 4. 按域选文案（Domain copy packs）
+
+报告层**不得**再写死教育域用语。面向读者的研究文案、章节标题、模块标签与框架枚举一律从领域文案包读取：
+
+```
+domains/<domain_id>/copy/
+  framing_lexicon.json   # frame 枚举 + 字段/子字段标签
+  section_titles.json    # 01–12 章节标题与引导语、默认章节大纲、摘要块标题
+  module_labels.json     # 域敏感 UI 模块标签（干预/评价/护栏/分组）
+  terminology.json       # 方法学项标签 + 字段展示名
+  risk_constructs.json   # 结果分组、结果分离标题/注、构念护栏
+  few_shots.json         # 四态（adopt / pilot / reject / insufficient_evidence）各 1 例文案
+```
+
+中性 UI 词典在 `domains/_neutral/copy/`（`module_labels*.json` 按主题拆分；渲染器 chrome，无研究口吻）。大词典允许主题拆伴文件：`framing_enums.json`、`module_labels_*.json`，加载时并入上述六件套视图。加载与合并：`visualization/eduevidence-report/scripts/report_copy_pack.py`。
+
+**域名解析**：`result.meta.domain` → `result.research_frame.extensions.domain`。缺省按 `education`（引擎惯例）并告警；未知域中性回退 + 告警（`strict=True` 则 fail-clear）。
+
+**域差异（写作时对照）**：
+
+| 概念 | education | policy |
+|---|---|---|
+| 干预 | AI 干预 / 教学干预 | **干预方案**（禁止「AI 干预」） |
+| target_learners | 目标学习者 | **目标人群** |
+| 结果分离 | 任务表现 ≠ 学习效果 | 过程产出 ≠ 政策效果 |
+| 评价指标 | 过程 / **学习** / 风险 | 过程 / **效果** / 风险 |
+| 构念护栏 | 任务 vs 学习护栏 | 产出 vs 效果护栏 |
+| 章节 09 | 教学干预 | 干预方案 |
+
+**policy 词典硬约束**：`python3 domains/check_copy_packs.py` 断言 policy 文案包不含教学词（教学/学习者/学习指标/AI 干预/…）；`report_copy_pack.assert_policy_copy_clean` 在加载时同样 fail-clear。`build_infographics` 遗留的教育 SVG 标题由 `retitle_infographics()` 按域改写，不改适配器本体。
+
+**新增第三域（例如 workplace / health）**：
+
+1. 在 `domains/manifest.json` 注册 `id` / frame_schema / outcome_taxonomy / methodology_checklist（沿用 v4 领域契约）。
+2. 新建 `domains/<id>/copy/`，写入上述 6 个 JSON（`domain` 字段必须等于 `<id>`）。
+3. 口吻：从 policy 包复制结构，换成该域构念词；禁止混入其他域硬词（用 `check_copy_packs.py` 的词表扩展后自检）。
+4. `few_shots.json` 四态各写 1 例该域决策口吻（≤ 规范字数上限）。
+5. 结果分组：在 `risk_constructs.json` 的 `outcome_groups` 把该域 outcome token 映射到 `task` / `learning` / `risk`（内部桶名不变，展示名由 `module_labels` 决定）。
+6. 跑 `python3 domains/check_copy_packs.py` + 用该域 `result.json` 跑一次 `build_report.py`，确认 HTML 无外域硬词。
+
+## 5. 术语对照
 
 同一概念全文只用一个说法：
 
@@ -49,7 +89,7 @@
 | `transfer` | 迁移 | transfer |
 | `applicability` | 适用性 | applicability |
 
-## 5. 禁止
+## 6. 禁止
 
 - 内部字段名与存储标识（`effect_direction`、`first_programming_course_...`）出现在叙述句里；它们只能出现在「原始标识」提示或溯源展开区。
 - 证据 ID 堆砌（`E-001、E-006`）出现在决策叙事里；引用研究用「作者-年份 + 人话描述」。
@@ -57,7 +97,7 @@
 - 半句截断、`null` 残留、中英夹生。
 - 用兜底句掩盖缺失：字段没产出就如实说没产出。
 
-## 6. 门禁如何执行
+## 7. 门禁如何执行
 
 - `check_language_parallel()`：叙述字段必须为对应语言、双语不得完全相同、不得含内部键名。
 - 原始标识检查：`research_frame` 与决策字段中的多词串若含未注册的 `snake_case`，记为缺陷。

package/schemas/v2/decision-snapshot.schema.json

@@ -2,14 +2,21 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://eduevidence.dev/schemas/v2/decision-snapshot.schema.json",
   "title": "DecisionSnapshot",
-  "description": "A revision-bound adjudication. Snapshots are immutable: changing the graph later never mutates an old snapshot file.",
   "type": "object",
   "additionalProperties": false,
   "required": [
-    "decision_snapshot_id", "decision", "confidence_label",
-    "confidence_score_internal", "claim_assessments", "key_evidence_links",
-    "key_risks", "applicability_boundary", "missing_evidence",
-    "graph_revision", "policy_versions", "created_at", "extensions"
+    "decision_snapshot_id",
+    "decision",
+    "confidence_label",
+    "confidence_score_internal",
+    "claim_assessments",
+    "key_evidence_links",
+    "key_risks",
+    "applicability_boundary",
+    "missing_evidence",
+    "graph_revision",
+    "policy_versions",
+    "created_at"
   ],
   "properties": {
     "decision_snapshot_id": { "type": "string", "pattern": "^DEC-" },
@@ -17,6 +24,7 @@
       "type": "string",
       "enum": ["ADOPT", "PILOT", "REJECT", "INSUFFICIENT_EVIDENCE"]
     },
+    "downgrade_reason": { "type": ["string", "null"] },
     "confidence_label": {
       "type": "string",
       "enum": ["High", "Moderate", "Low", "Insufficient"]
@@ -37,17 +45,20 @@
       "type": "array",
       "items": { "type": "string" }
     },
-    "applicability_boundary": { "type": "string", "minLength": 1 },
+    "applicability_boundary": { "type": "string" },
     "missing_evidence": {
       "type": "array",
       "items": { "type": "string" }
     },
-    "graph_revision": { "type": "integer", "minimum": 1 },
+    "graph_revision": { "type": ["string", "integer"] },
     "policy_versions": {
       "type": "object",
       "additionalProperties": { "type": "string" }
     },
-    "created_at": { "type": "string", "format": "date-time" },
-    "extensions": { "type": "object" }
+    "created_at": { "type": "string" },
+    "extensions": {
+      "type": "object",
+      "additionalProperties": true
+    }
   }
 }