adduce 0.1.0__py3-none-any.whl

adduce/__init__.py

@@ -0,0 +1,3 @@
+"""adduce: a reproducibility self-check for ML and research repositories."""
+
+__version__ = "0.1.0"

adduce/cache.py

@@ -0,0 +1,44 @@
+"""Local cache under ``.adduce/cache`` for opt-in online resolutions.
+
+Nothing in the default offline path reads or writes this cache. Online
+commands (``pin-remotes``, ``--online``) store resolved public metadata
+(Hugging Face revisions, GitHub SHAs, URL headers) here so repeated runs do
+not re-query, and so the resolved values are inspectable.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+CACHE_DIR = ".adduce/cache"
+_DEFAULT_TTL_SECONDS = 7 * 24 * 3600
+
+
+class Cache:
+    def __init__(self, root: Path, ttl_seconds: int = _DEFAULT_TTL_SECONDS) -> None:
+        self.directory = root / CACHE_DIR
+        self.ttl_seconds = ttl_seconds
+
+    def _path_for(self, key: str) -> Path:
+        safe = "".join(c if c.isalnum() or c in "-._" else "_" for c in key)
+        return self.directory / f"{safe}.json"
+
+    def get(self, key: str) -> Any | None:
+        target = self._path_for(key)
+        if not target.is_file():
+            return None
+        try:
+            entry = json.loads(target.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            return None
+        if time.time() - entry.get("stored_at", 0) > self.ttl_seconds:
+            return None
+        return entry.get("value")
+
+    def put(self, key: str, value: Any) -> None:
+        self.directory.mkdir(parents=True, exist_ok=True)
+        entry = {"stored_at": time.time(), "value": value}
+        self._path_for(key).write_text(json.dumps(entry, indent=2), encoding="utf-8")

adduce/checklists/__init__.py

@@ -0,0 +1,149 @@
+"""Conference checklist drafting from repository evidence.
+
+Each bundled checklist maps its items to rule IDs. Items are answered from
+finding statuses (all pass → Yes, mixed → Partial, all fail → No); items the
+repository cannot answer are marked for the authors explicitly. The output
+is a draft: honest wording about that is part of the design, not a
+disclaimer bolted on.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from importlib import resources
+from pathlib import Path
+
+import yaml
+
+from ..engine import CheckResult
+from ..rules.base import Finding, Status
+
+
+@dataclass
+class ChecklistItem:
+    id: str
+    question: str
+    rules: list[str] = field(default_factory=list)
+    manual: bool = False
+    guidance: str = ""
+
+
+@dataclass
+class Checklist:
+    name: str
+    key: str
+    preamble: str
+    items: list[ChecklistItem]
+
+
+def available_checklists() -> list[str]:
+    return sorted(
+        entry.name[: -len(".yaml")]
+        for entry in resources.files(__package__).iterdir()
+        if entry.name.endswith(".yaml")
+    )
+
+
+def load_checklist(name_or_path: str) -> Checklist:
+    path = Path(name_or_path)
+    if path.suffix in {".yaml", ".yml"} and path.is_file():
+        text = path.read_text(encoding="utf-8")
+    else:
+        resource = resources.files(__package__).joinpath(f"{name_or_path}.yaml")
+        if not resource.is_file():
+            raise ValueError(
+                f"Unknown checklist '{name_or_path}'. Bundled: {', '.join(available_checklists())}."
+            )
+        text = resource.read_text(encoding="utf-8")
+    data = yaml.safe_load(text)
+    items = [
+        ChecklistItem(
+            id=item["id"],
+            question=item["question"],
+            rules=list(item.get("rules", [])),
+            manual=bool(item.get("manual", False)),
+            guidance=str(item.get("guidance", "")).strip(),
+        )
+        for item in data.get("items", [])
+    ]
+    return Checklist(
+        name=data.get("name", name_or_path),
+        key=data.get("key", name_or_path),
+        preamble=str(data.get("preamble", "")).strip(),
+        items=items,
+    )
+
+
+def _draft_answer(findings: list[Finding]) -> tuple[str, list[str]]:
+    """Derive a draft answer and its supporting evidence lines."""
+    scored = [f for f in findings if f.status.score_value is not None]
+    evidence = []
+    for finding in findings:
+        marker = {Status.PASS: "found", Status.PARTIAL: "partial", Status.FAIL: "missing"}.get(
+            finding.status, "n/a"
+        )
+        evidence.append(f"[{marker}] {finding.rule_id}: {finding.message}")
+    if not scored:
+        return "No repository evidence", evidence
+    values = [f.status.score_value for f in scored]
+    if all(v == 1.0 for v in values):
+        return "Yes (draft)", evidence
+    if all(v == 0.0 for v in values):
+        return "No (draft)", evidence
+    return "Partial (draft)", evidence
+
+
+def render_markdown(
+    checklist: Checklist,
+    result: CheckResult,
+    llm_drafts: dict[str, str] | None = None,
+) -> str:
+    """Render the filled checklist. ``llm_drafts`` optionally carries
+    LLM-phrased justification prose keyed by item id; the yes/no evidence
+    answers stay deterministic regardless."""
+    llm_drafts = llm_drafts or {}
+    findings_by_rule = {f.rule_id: f for f in result.card.findings}
+    lines: list[str] = []
+    lines.append(f"# {checklist.name}")
+    lines.append("")
+    lines.append(f"Repository: `{result.repo.root.name}`"
+                 + (f" at commit `{(result.repo.git.head_commit or '')[:7]}`" if result.repo.git.head_commit else ""))
+    lines.append("")
+    if checklist.preamble:
+        lines.append(f"> {checklist.preamble}")
+        lines.append("")
+
+    for index, item in enumerate(checklist.items, start=1):
+        lines.append(f"## {index}. {item.question}")
+        lines.append("")
+        item_findings = [findings_by_rule[r] for r in item.rules if r in findings_by_rule]
+        if item.manual:
+            lines.append("**Answer:** _requires author input — not derivable from the repository._")
+        else:
+            answer, _ = _draft_answer(item_findings)
+            lines.append(f"**Answer:** {answer}")
+        lines.append("")
+        if item.id in llm_drafts:
+            lines.append("**Draft justification** (LLM-phrased from the evidence below — verify):")
+            lines.append("")
+            lines.append(llm_drafts[item.id])
+            lines.append("")
+        if item_findings:
+            lines.append("**Repository evidence:**")
+            lines.append("")
+            _, evidence = _draft_answer(item_findings)
+            for line in evidence:
+                lines.append(f"- {line}")
+            lines.append("")
+        if item.guidance:
+            lines.append(f"_{item.guidance}_")
+            lines.append("")
+
+    lines.append("---")
+    lines.append("")
+    lines.append(
+        "Drafted from static repository evidence. Verify each answer against the "
+        "paper before submission; answers about the paper text cannot be derived here."
+    )
+    lines.append("")
+    return "\n".join(lines)

adduce/checklists/acl.yaml

@@ -0,0 +1,44 @@
+name: "ACL Rolling Review Responsible Research Checklist (artifact items)"
+key: acl
+preamble: >
+  Draft answers derived from repository evidence. Complete and verify every
+  answer before submission; several items depend on the paper text and on
+  assets the tool cannot inspect.
+items:
+  - id: artifacts-released
+    question: "Did you release the code and models used in your work, with sufficient documentation to use them?"
+    rules: [R-EXEC-002, R-DOC-001, R-LIC-001, R-VER-001]
+    guidance: >
+      Reviewers expect a repository with install and usage documentation and
+      an explicit license.
+  - id: artifacts-cited
+    question: "Did you cite the creators of the artifacts (datasets, models, code) you used?"
+    rules: [R-LIC-002, R-LIC-003]
+    manual: true
+    guidance: >
+      Citation of third-party artifacts lives in the paper; the repository
+      side is a citation section, CITATION.cff, and stated asset licenses.
+  - id: reproducibility-parameters
+    question: "Did you report the number of parameters, total computational budget, and computing infrastructure used?"
+    rules: [R-DOC-001, R-PREC-005, R-RUN-003]
+    guidance: >
+      Add a hardware-and-runtime note to the README and mirror it in the
+      paper; SLURM scripts' resource requests should match.
+  - id: experimental-setup
+    question: "Did you discuss the experimental setup, including hyperparameter search and best-found hyperparameter values?"
+    rules: [R-DOC-002, R-DRIFT-001, R-DRIFT-002]
+    guidance: >
+      Committed config files per reported experiment are the strongest
+      supporting evidence; drift findings mean paper and configs disagree.
+  - id: descriptive-statistics
+    question: "Did you report descriptive statistics about your results (e.g., error bars, summary statistics over multiple runs)?"
+    rules: [R-RES-003]
+    guidance: >
+      Multi-seed run scripts and variance reporting are the repository-side
+      evidence.
+  - id: data-documentation
+    question: "Did you document the data you used or created, including how it can be obtained?"
+    rules: [R-DATA-001, R-DATA-002, R-DATA-003, R-DATA-005]
+    guidance: >
+      A download script or dataset DOI plus checksums makes data access
+      mechanical and verifiable.

adduce/checklists/neurips.yaml

@@ -0,0 +1,44 @@
+name: "NeurIPS Paper Checklist (reproducibility items)"
+key: neurips
+preamble: >
+  Draft answers derived from repository evidence. Every answer must be
+  reviewed and completed by the authors before submission: the tool sees the
+  repository, not the paper, and several checklist items depend on claims
+  made in the paper text.
+items:
+  - id: experimental-reproducibility
+    question: "Does the paper fully disclose all the information needed to reproduce the main experimental results?"
+    rules: [R-DOC-001, R-DOC-002, R-DOC-003, R-DET-001, R-EXEC-003]
+    guidance: >
+      Reviewers look for the experimental setup, hyperparameters, seeds, and
+      the mapping from commands to reported numbers.
+  - id: open-access-code-data
+    question: "Does the paper provide open access to the data and code, with sufficient instructions to faithfully reproduce the main experimental results?"
+    rules: [R-EXEC-002, R-ENV-001, R-DATA-001, R-DATA-002, R-DOC-001]
+    guidance: >
+      An anonymised repository URL with exact run commands and environment
+      specification is the expected supporting material.
+  - id: experimental-details
+    question: "Does the paper specify all the training and test details (data splits, hyperparameters, how they were chosen, optimizer)?"
+    rules: [R-DOC-002, R-DRIFT-001, R-DRIFT-003, R-DATA-001]
+    guidance: >
+      Point to the committed config files for each reported experiment; drift
+      findings indicate paper and configs disagree.
+  - id: error-bars
+    question: "Does the paper report error bars or other information about the statistical significance of the experiments?"
+    rules: [R-RES-003]
+    guidance: >
+      Multi-seed run scripts and variance reporting are the repository-side
+      evidence; the statistical claims themselves live in the paper.
+  - id: compute-resources
+    question: "Does the paper provide sufficient information on the computer resources (type of compute workers, memory, time of execution) needed to reproduce the experiments?"
+    rules: [R-DOC-001, R-PREC-005, R-RUN-003, R-DRIFT-005]
+    guidance: >
+      State GPU/CPU model, count, memory, and approximate wall-clock time per
+      experiment; precision settings (TF32/AMP) belong here too.
+  - id: code-of-ethics-license
+    question: "Are the creators or original owners of assets (code, data, models) properly credited, and are the license and terms of use explicitly mentioned and respected?"
+    rules: [R-LIC-001, R-LIC-002, R-LIC-003]
+    guidance: >
+      License the released code, provide citation metadata, and state the
+      licenses of datasets and pretrained assets you build on.