Skip to main content
Glama
io.github.xngg1021/academic-research-kernel

io.github.xngg1021/academic-research-kernel

by xngg1021

academic-research-kernel (v3.0.0)

English · 简体中文

Standalone scholarly verification, LaTeX submission gates, and transactional evidence state (CLI + MCP + 7 Agent Skills).

Large language models summarize papers fluently yet fail predictably on exact arithmetic and external ground truth: they repeat miscalculated $p$-values, miss rounding-impossible percentages, cite retracted or fabricated DOIs, leave author metadata inside double-blind PDFs, and lose track of which source table backs which claim.

academic-research-kernel (3.0.0) separates semantic reading from deterministic checks. Run it directly from your terminal or wire it into any MCP / SKILL.md agent workflow:

uv tool install "academic-research-kernel[research]==3.0.0"
academic-research-kernel verify-work "10.1038/nature14539" --normalize-only
# -> {"input": "10.1038/nature14539", "type": "doi", "value": "10.1038/nature14539", "canonical": "https://doi.org/10.1038/nature14539"}

Empirical case study included: Reproducible SHA-256 receipts across four AI conference series and five frozen public snapshots (74,637 primary-cohort submissions across 75,574 raw mirror submissions, 248,174 official reviews; see Section 4 and peer-review-forensics-2025-2027-v1.json).

Author: Junfu Shi (SJF, xngg1021). License: Source Lineage License 1.0. Architecture: docs/kernel-architecture.md.


1. Two-Minute Quick Start: Three Entry Modes & Dependencies

Install uv, then choose how you want to invoke the kernel (Python 3.10–3.14, ~25 ms CLI cold start):

Mode A: Direct Command-Line Tool (Human Researchers, CI & Shell Scripts)

uv tool install "academic-research-kernel[research]==3.0.0"
academic-research-kernel doctor
academic-research-kernel lint-submission ./manuscript/main.tex --venue iclr --phase submission

Mode B: Universal stdio MCP Server (Claude Code, Codex, Cursor, Gemini CLI)

Exposes 24 deterministic MCP tools over bounded-frame stdio JSON-RPC 2.0 (2024-11-05 through 2026-07-28):

# Claude Code CLI
claude mcp add academic-research-kernel -- uvx --from "academic-research-kernel[research]==3.0.0" academic-research-kernel mcp

# OpenAI Codex CLI
codex mcp add academic-research-kernel -- uvx --from "academic-research-kernel[research]==3.0.0" academic-research-kernel mcp

Mode C: Agent Skills (Hermes Agent or Any SKILL.md-Compatible Harness)

# Install the 7-skill plugin in Hermes Agent
hermes plugins install xngg1021/academic-research-kernel --no-enable
hermes plugins enable academic-skills

# Or export the standalone audit-paper skill + JSON schemas to any local folder
academic-research-kernel research skill --output ./audit-paper

Dependency layout: State management (SQLite STRICT + WAL), CLI dispatch, and MCP protocol control use Python's standard library, importing declared scientific and schema packages (jsonschema, numpy, scipy, statsmodels) lazily on demand. The [research] extra installs pypdf==7.0.0 and fonttools==4.65.0 for isolated subprocess PDF text/metadata scanning; details in docs/distribution-release.md.


Related MCP server: Warranted

2. Seven Workflow Skills & Task Routing

v3.0.0 consolidates all 14 legacy v2.4.2 skill directories into seven task-oriented skills:

Skill Directory

Concrete Task & Scope Boundary

Key CLI Commands & MCP Tools

skills/audit-paper

Check statistics, tables, source locators, and reproducibility checklists in an external/paired paper (emits item-level checks, not blanket truth verdicts)

research, table-forensics, repro-checklist, ledger, academic_recompute_statistics

skills/verify-citations

Verify DOIs/metadata, monitor Crossref/OpenAlex retractions in SQLite, merge corpora, and locate legal OA PDFs (existence $\neq$ claim support)

verify-work, retraction-watch, literature-watch, collect-corpus, locate-oa

skills/audit-peer-review

Analyze offline OpenReview score/length/unanimity distributions and companion repos (descriptive forensics, not AI-authorship proof)

openreview-audit, repo-forensics --github-repo, academic_openreview_audit

skills/meta-analysis

Pool fixed/random effects (DL), run subgroup $Q_{\text{between}}$ & WLS meta-regression, Egger/trim-and-fill, and build citation matrices

meta-analyze, bibliography, academic_meta_analyze

skills/check-submission

Gate your own draft before submission: multi-file LaTeX, venue limits, double-blind PDF/source anonymity, CEG anchors, and booktabs tables

lint-submission, sanitize-submission, generate-table, check-venue

skills/cross-review

Coordinate live multi-model blind review, anonymous Proposal-N challenge, and minority-protected synthesis under a strict single-line verdict grammar

cross-review, academic_cross_review

skills/compute-math

Probe CPU/GPU/BLAS/thread environments, emit schema-validated ComputeReceipt, and route tasks to installed scientific Python packages

compute-probe, academic_scfabric_hardware_probe

Quick Disambiguation: Which Review/Check Skill Do I Need?

Object in Hand

Entry Skill

Primary Output

An external paper you want to audit

audit-paper

Locator-bound statistical, table, and reproducibility check results

Your own manuscript draft before submission

check-submission

Format, page-limit, anonymity, and CEG grounding gate report

Published OpenReview conference records

audit-peer-review

Cohort score/word-count distributions and screening statistics

A claim/spec needing live multi-model review

cross-review

Clustered findings and SHA-bound challenge synthesis receipt

How academic-research-kernel fits alongside peer open-source tools: Broad domain skill collections (such as Scientific Agent Skills) and discovery/RAG systems (AI-Scientist, PaperQA) focus on literature synthesis and draft generation, while specialized verifiers focus on single axes such as multi-provider bibliography GUI/CLI validation (RefChecker, evaluated on benchmarks like HALLMARK), APA test-statistic rounding (statcheck), or Claude-Code/Codex reviewer workflows (Anti-Autoresearch). academic-research-kernel focuses on a host-neutral CLI/MCP verification & SQLite state kernel that links author-side multi-file LaTeX/anonymity submission gates and auditor-side statistical, retraction, meta-analysis, and OpenReview snapshot receipts under a single transactional schema contract.


3. End-to-End Workflows, Verified Scope & Known Limits

Workflow A: Audit an External Paper, Citation List, or Meta-Analysis

# 1. Prepare a PDF/LaTeX bundle, validate extracted stats, and check table partition conservation
academic-research-kernel research prepare ./paper.pdf --project ./paper-state
academic-research-kernel research finish --project ./paper-state --candidate ./candidate.json
academic-research-kernel table-forensics --input ./table-spec.json

# 2. Verify citations, locate legal Open Access full text, and monitor retractions in SQLite
academic-research-kernel verify-work "10.1038/nature14539" --check-updates
academic-research-kernel locate-oa "10.1038/nature14539" --email "you@example.edu" --fallback-openalex
academic-research-kernel retraction-watch --dois "10.1038/nature14539" --state-db ./watch.sqlite3 --live

# 3. Pool multi-study effect sizes (fixed & DerSimonian-Laird random effects + Q / I^2 / tau^2 + Egger + trim-and-fill)
academic-research-kernel meta-analyze --input ./studies.json

Workflow B: Pre-Submission Gate for Your Own LaTeX & PDF Manuscript

# 1. Inspect venue rules (ICLR, NeurIPS, ICML, ACL, etc.) or export verified CEG claim anchors
academic-research-kernel check-venue --list-venues
academic-research-kernel check-venue --export-ceg-anchors ./ceg.json

# 2. Render verified JSON experiment receipts into Decimal-rounded booktabs LaTeX tables
academic-research-kernel generate-table ./results-receipt.json --caption "Main Results" --label "tab:main"

# 3. Scan multi-file TeX, BibTeX, and compiled PDF (/Info + XMP streams in isolated worker) for anonymity leaks
academic-research-kernel sanitize-submission ./submission-dir --forbidden-token "Alice Smith"

# 4. Run full pre-submission gate (nested \input/\subfile/\import, declared .bib scope, shared-page limit, CEG binding)
academic-research-kernel lint-submission ./submission-dir/main.tex \
  --venue iclr --phase submission --pdf ./submission-dir/main.pdf \
  --ceg ./ceg.json --require-ceg-binding --check-academic-style

Development regression summary & known limitations:

  • On the 30-case offline development regression suite (real-world-audit-benchmark-v1.json: 16 frozen-snapshot DOI/retraction cases + 12 published Nuijten/Bakker statistical cases + 2 repository gate cases), v3.0.0 replays TP = 10, TN = 6, FP = 0, FN = 0 on bibliographic/retraction checks and TP = 8, TN = 5, FP = 1, FN = 0 (TP = 18, TN = 11, FP = 1, FN = 0 overall).

  • Disclosed rounding limitation (S14): recompute.py currently evaluates exact reported test statistics against reported $p$-value rounding intervals rather than intervalizing coarse 1-decimal test statistics (t(15) = 2.3, p = .033 yields the single disclosed FP), so numerical flags require human verification of input rounding before claiming a manuscript error. In double-blind checks, generic third-party repository URLs emit review warning items rather than hard blocks unless paired with --forbidden-token or explicit self-repository phrasing.


4. Case Study: OpenReview Snapshots Across Four AI Conference Series (2025–2027)

Running run_peer_review_and_incidence_benchmarks.py over frozen papercopilot/paperlists@181a85021c63ab26745c42ed70a9d9ea7b57ad7e metadata mirrors (74,637 unique submissions in explicit primary cohorts across 75,574 total mirror submissions, 72,289 scored papers, and 248,174 positive official reviews; full SHA-256 receipt and excluded-track breakdowns in peer-review-forensics-2025-2027-v1.json) surfaces three descriptive snapshot patterns:

Snapshot & Explicit Primary Cohort (181a8502)

Scored Papers ($N$)

Positive Reviews (Mean / Paper)

Paper Mean Score (Valid Scale)

Review Words Median (conf=2 vs conf=4)

Unanimous Rate (i.i.d. Marginal Baseline)

ICLR 2026 (all public; 19,813 unique; 1,319 rating=0 isolated)

19,454

74,540 (3.83)

4.26 (2,4,6,8,10)

391 (328 vs 409)

8.13% (1,578/19,412; base 5.07%)

ICLR 2027 (public rebuttal snapshot; 42,790 total)

40,801

126,369 (3.10)

2.06 (1–4 int; 57.4% at 2)

429 (405 vs 451)

23.90% (9,752/40,801; base 19.80%)

ICML 2026 (main accepted public; 334 ratings of 6)

6,341

24,378 (3.84)

4.15 (1–6 int rec.)

345 (298 vs 364)

16.53% (1,048/6,341; base 12.35%)

NeurIPS 2025 (main Oral/Spotlight/Poster; raw mirror 6,212*)

5,275

21,301 (4.04)

4.34 (1–6 int rating)

389 (330.5 vs 409.5)

14.01% (739/5,275; base 8.97%)

COLM 2025 (main Poster accepted; word counts absent in mirror)

418

1,586 (3.79)

6.50 (1–10 int rating)

— (not in mirror)

7.89% (33/418; base 5.46%)

*Cohort transparency: The raw nips/nips2025.json mirror (6,212 records) mixes main (5,526, including 251 opted-in public Reject), Datasets & Benchmarks (591, including 94 Reject), and Position (95, including 55 Reject and all 125 ratings > 6 across 74 Position papers); all 937 non-primary records are preserved in mirror_cohort_breakdown inside the receipt rather than dropped silently.

  1. Scale compression, reviewer-count shift & unanimity: In ICLR 2027 (42,790 submissions), compressing the scale to 1–4 (57.36% at score 2) alongside a lower mean review count per scored paper (3.10, modal 3, vs. 3.83, modal 4 in ICLR 2026) shifts the empirical-marginal independent-sampling unanimity baseline $\sum_k p_k^m$ from 5.07% to 19.80% under that null model alongside the observed change from 8.13% to 23.90%. This null-model comparison provides a structural reference rather than causal attribution of cross-year differences, and unanimous-score rates must not be equated with AI-reviewing or collusion rates.

  2. Self-reported confidence & review length: Across all four snapshots with word counts, self-reported confidence = 2 reviews have lower median word counts than confidence = 4 reviews (328 vs 409 in ICLR 2026, 298 vs 364 in ICML 2026, 330.5 vs 409.5 in NeurIPS 2025 main accepted, and 405 vs 451 in ICLR 2027). Separately, ICML 2026 program chairs officially sanctioned 398 reciprocal-review LLM-policy violators (497 desk rejections).

  3. Polarity-blind topic-mention screening (ICLR 2026): Across 19,473 joined scored ICLR 2026 submissions and 75,769 official reviews (iclr2026-openreview-incidence-receipt.json, verified against insomnia7/iclr2026_stats@50507ab3), regex topic screening over Weaknesses and Questions matches at least one of five check families in 48.2% of Oral, 54.0% of Poster, 59.8% of Rejected, and 63.6% of Desk-Rejected papers (59.0% overall; measures topic-term mention prevalence rather than confirmed defect rate).


5. Architecture, Security Guardrails, Local QA & License

  1. Transactional SQLite STRICT + WAL state (state_db.py, _stdlib.py, mcp_server.py): Replaces legacy multi-file JSON lockfiles with foreign-keyed STRICT tables, SAVEPOINT atomic batches, application_id = 0x41524B33 / user_version = 4 migration guards, mandatory schema validation across all 26 artifact kinds, single-claim outer binding target verification on quantitative_audit / evidence_receipt ingestion, cycle-checked provenance graphs, and dual-sequence (applied_seq + confirmed_seq) retraction state.

  2. Untrusted PDF & network isolation (research/sources.py, double_blind_sanitizer.py): Every PDF read executes inside a bounded python -I -c worker subprocess (pypdf==7.0.0, fonttools==4.65.0). Outbound HTTP (controlled_urlopen) disables ambient proxies, pins resolved public DNS addresses to block DNS-rebinding TOCTOU attacks, and enforces byte caps. MCP academic_double_blind_sanitize redacts matched strings (matched="[REDACTED]").

  3. External API etiquette & local QA gates: doctor never makes network calls (OPENALEX_API_KEY optional for higher quotas; Unpaywall uses --email / UNPAYWALL_EMAIL or --fallback-openalex). Legacy 2.4.x CLI aliases remain supported (retraction-watch --import-legacy-json old-watch.json --state-db watch.sqlite3 migrates watch files; see CHANGELOG.md).

uv lock --check
uv run --frozen --extra qa --extra research pytest -q tests
uv build --no-create-gitignore
uv run --frozen --extra qa --no-editable python -m twine check --strict dist/*
PYTHONPATH=src python -m academic_research_kernel.release_gate --package-acceptance --dist dist

License

Covered material in this repository is licensed under the Source Lineage License 1.0 (LicenseRef-Source-Lineage-1.0) within the scope stated in LICENSE-APPLICATION.md; provenance and preserved-MIT upstream boundaries (SLL-APPLICATION.json) are documented in SOURCE-LINEAGE.md, LICENSE-HISTORY.md, and REPOSITORY-IDENTITY.md. SLL 1.0 permits free academic and commercial use, modification, redistribution, and proprietary extensions provided required license and lineage notices are preserved; network service use without distributing copies does not trigger attribution obligations, and third-party files such as tests/upstream/LICENSE remain under their original licenses.

Available Tools

18 tools
academic_check_percentageC

Check if a reported percentage and count can mathematically arise from a sample size.

Inputs: count (required), percent (required), sample_size.

academic_double_blind_sanitizeA

Read-only scan of a manuscript or reproduction directory for double-blind anonymity leaks (PDF metadata, local paths, Git credentials, unblinded acks, forbidden tokens). Never modifies files and redacts matched forbidden tokens in output.

Inputs: target_path (required), forbidden_tokens.

academic_meta_analyzeC

Run deterministic fixed-effect and DerSimonian-Laird random-effects meta-analysis, heterogeneity (Q, I2, tau2), leave-one-out sensitivity, Egger regression, and Duval-Tweedie trim-and-fill.

Inputs: studies (required).

academic_openreview_auditB

Audit OpenReview submission status, ratings, review word counts, or macro venue acceptance/rating distributions from offline notes or mirror records.

Inputs: notes, forum_id, topic_regex, venue_records.

academic_pre_submission_lintB

Audit a LaTeX manuscript against venue formatting rules, required sections, double-blind package options, statistical dispersion, CEG claim bindings, and optional academic prose style checks.

Inputs: tex_path (required), phase, venue, ceg_path, +4 more.

academic_recompute_statisticsB

Recompute t/F/chi2/z p-values, two-group Cohen's d and Hedges' g, 2x2 OR/RR, CI consistency, statistical power, SD bounds, and df-implied sample sizes. Optional reported p-value comparison uses decimal round-half-up intervals; input or partial execution failures are tool errors, statistical mismatches are successful results.

Inputs: df, n1, n2, se, +61 more.

academic_scfabric_hardware_probeB

Probe local hardware accelerators (CUDA, ROCm, MPS, XPU) and execution environments.

Inputs: no named parameters.

academic_table_forensicsC

Audit AI/CS paper tables for partition conservation, constant-offset ablation regularity, and physical storage/bandwidth lower bounds.

Inputs: partition, ablation_tol, ablation_matrix, ablation_min_rows, +2 more.

academic_verify_sourceB

Normalize scholarly identifiers (DOI, arXiv, PMID, PMCID, OpenAlex) and cross-verify metadata across OpenAlex and Crossref records.

Inputs: identifier (required), offline, normalize_only, crossref_record, +1 more.

claim_evidence_traceB

Trace all supporting and refuting evidence anchors and attached receipts for a given claim.

Inputs: graph (required), claim_id (required), receipts, content_payloads.

claim_evidence_validateB

Validate the structural integrity, cycles, and cryptographic receipt bindings of a ClaimEvidenceGraph snapshot.

Inputs: graph (required), receipts, content_payloads.

decision_ledger_validateC

Execute complete four-gate verification over a Decision Ledger export dictionary.

Inputs: ledger (required), receipts, content_payloads.

decision_traceB

Trace causal ancestry, basis dependencies, outcome corrections, and lifecycle state history for a decision.

Inputs: ledger (required), decision_id (required), receipts, content_payloads.

research_artifact_ingestC

Deterministically ingest a scholarly artifact envelope into kernel state (ResearchObjects, CEG, and Ledger).

Inputs: envelope (required), state, dry_run, bindings, +1 more.

research_artifact_validateC

Validate a ResearchArtifactEnvelope against its schema and verify its cryptographic payload SHA-256 without side effects.

Inputs: envelope (required), state, bindings, receipts, +1 more.

research_lineage_traceC

Trace backward provenance ancestry for a specified entity within a LineageGraph snapshot.

Inputs: lineage_graph (required), target_entity_id (required).

research_object_resolveC

Resolve and aggregate candidate bibliographic/identity records into discrete five-state equivalence judgments.

Inputs: records (required).

research_receipt_verifyC

Verify an AcademicEvidenceReceipt or LineageReceipt against a strongly typed ReceiptRef.

Inputs: receipt_ref (required), receipt_payload (required), content_payloads.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 18 tools

    Disambiguation4/5

    Most tools are clearly separated by target resource: artifacts, receipts, objects, lineage graphs, claim-evidence graphs, decision ledgers, and academic auditing tasks. There is some conceptual overlap between research_artifact_validate, claim_evidence_validate, and decision_ledger_validate, and between the various trace tools, but the descriptions make the distinct domains reasonably clear.

    Naming Consistency4/5

    Names consistently use snake_case with domain-prefixed namespaces such as research_, claim_evidence_, decision_, and academic_. The pattern is generally predictable, though action ordering varies slightly between entity_action forms like research_artifact_validate and academic_verify_source.

    Tool Count4/5

    Eighteen tools is slightly above the ideal compact range, but the server covers a broad academic research kernel with validation, lineage, statistics, manuscript auditing, and meta-analysis. Each tool appears to serve a distinct purpose rather than duplicating functionality.

    Completeness4/5

    The surface covers validation, ingestion, tracing, receipt verification, statistical recomputation, manuscript linting, source verification, and meta-analysis, which is substantial for the apparent verification/audit domain. There are minor gaps around creation/update/query utilities for research objects, but the core lifecycle is well represented.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      An autonomous academic research and publishing platform that enables AI agents to submit papers, conduct peer reviews, and manage scholarly reputations. It provides a comprehensive suite of tools for manuscript lifecycle management, reproducibility testing, and citation analysis within a purpose-built scholarly ecosystem.
      25
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Makes AI research agents accountable by giving every conclusion a traceable argument graph. Provides a persistent argument graph where claims require grounds and warrants for auditable, verifiable reasoning.
      3
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables creation and invocation of reusable research workflow programs derived from demonstrations, with live scholarly data search and workspace automation via multiple protocols.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Gives existing agents controlled access to a local Neo4j research memory, letting them import papers and notes, record models, experiments, evidence and decisions, search full text plus graph neighbors, and resume bounded research sessions with checkpoints and provenance. Twelve stdio tools and seven companion skills turn reading, extraction and handoffs into auditable, revision-checked records.
      3
      MIT