Supervised by Prof. Meerk — a meerkat who never stops watching over your research.
English · 简体中文 · 日本語 · Español · Français · Deutsch · Italiano · Português · Русский · 한국어 · العربية
Inside Prof. Meerk's studio — curious minds + shared knowledge + relentless iteration = real impact.
Most "AI paper writers" hallucinate citations and numbers. Paperfessor is built with guardrails that make that hard — a paper should be earned, not invented:
- 📊 Experiments produce the numbers — it downloads real public datasets, runs
the proposed method and baselines itself (k = 3 seeds, mean ± 95% CI), and the
table is filled from the measured
results.json, not from the language model. - 📚 Citations are resolved against real indexes — arXiv / OpenAlex / Semantic Scholar; citations that can't be verified are removed.
- 🔍 Self-inspecting — the PhD agent re-reads the whole paper against the measured results, flags defects (unmeasured numbers, missing references, layout problems), fixes them, and re-checks page by page until clean.
- 🔒 Private by design — your API key lives in the OS keychain; a redaction pass strips local paths, filenames, and machine info from the paper.
- 🖥️ Runs on your machine, your key — cloud LLMs or local Ollama / llama.cpp.
A note on honesty. These guardrails constrain the machinery around the model — real data, verified citations, a measured results table, layout gates. They cannot guarantee the prose an LLM writes is accurate or free of subtle errors; that depends on the model you plug in, and no wrapper can make a language model truthful. Always review the generated paper before any real use — treat Paperfessor as a fast, well-supervised first-draft assistant, not an oracle.
A recent end-to-end run on "anomaly detection in multivariate time series" produced a 10-page KDD-formatted PDF where the proposed method won best-F1 on 2 of 3 datasets (e.g. F1 0.703, AUROC 0.946 on SMD vs the strongest baseline at 0.595) — every number traceable to
results.json, all 10 pages passing the layout inspector, and the one dataset it lost on stated plainly.
Paperfessor is a three-agent research assistant. Give it a research direction — one sentence is enough — and its agent group works the way a small lab does:
| Agent | Role | Status API |
|---|---|---|
| 🎓 PhD student | Invents the method, dispatches tasks, supervises, writes and inspects the paper | planning / dispatching / monitoring / reviewing / writing / archiving |
| 📚 Master's student | Broad literature search (arXiv + OpenAlex + Scholar), rigorous full-text reading, evidence extraction, venue-requirements investigation | websearch / reading / analyzing / reporting / idle / stopped |
| 💻 Undergraduate | Implements the method against a strict contract, downloads and preprocesses real datasets, runs k-seed experiments | coding / thinking / reporting / idle / stopped |
Numbers in the results table come from a measured results.json, not from
the language model: datasets are real public downloads (loaders refuse synthetic
stand-ins), the proposed method is verified by actually running it, and each
rendered page passes an automated layout inspection before the run is accepted.
The surrounding prose is still written by an LLM — see the honesty note above and
verify it yourself.
flowchart LR
U[You: research direction] --> P[🎓 PhD plans<br/>+ checks archive]
P -->|research_guide.md| M[📚 MS surveys<br/>real papers]
M -->|research_log.md| P
P -->|code_guide.md| G[💻 UG implements<br/>+ runs experiments]
G -->|code_log.md + results.json| P
P --> W[🎓 PhD writes paper<br/>section by section]
W <-->|evidence requests,<br/>venue questions| M
W <-->|comparison figures,<br/>figure regeneration| G
W --> S{Self-inspection loop<br/>+ Article 19}
S -->|defects| W
S -->|clean| A[📦 Archive + PDF]
The PhD reviews the workers passively (on every report) and actively
(any worker silent for 2 minutes gets checked). All coordination flows through
plain-Markdown guides and logs in workspace/ — you can watch the lab work in
real time with nothing more than a text editor.
# 1. Install (Python 3.11+; add [gui] for the desktop app)
pip install paperfessor
# 2. Store your LLM key (kept in the OS keychain, never on disk)
paperfessor key set minimax --key "sk-..." # or openai / anthropic / google
# 3. Write a paper
paperfessor run "anomaly detection in multivariate time series"That's it — the three agents plan, survey, code, experiment, write, and
self-inspect, then drop a venue-formatted PDF in workspace/paper/body/.
| Component | Requirement | Needed for |
|---|---|---|
| Python | 3.11 or 3.12 | Required — the whole tool |
| An LLM key or local model | one provider (MiniMax / OpenAI / Anthropic / Google) or local Ollama / llama.cpp | Required — the agents call an LLM |
| ~1–2 GB disk + network | for dataset/paper downloads | Required at run time |
| LaTeX | TeX Live / MiKTeX / MacTeX with acmart |
Recommended — real PDF; without it, .docx/Markdown fallback |
| Pandoc | any recent version | Optional — enables the .docx fallback when LaTeX is absent |
| PyQt6 | paperfessor[gui] |
Optional — the desktop GUI |
| Playwright | paperfessor[web] + playwright install |
Optional — browser-driven full-text retrieval |
| GPU (CUDA) + PyTorch | any | Optional — only used for heavy or speed-topic experiments; everything runs on CPU by default |
Works on Windows, macOS, and Linux.
pip install paperfessor # core
pip install "paperfessor[gui]" # + desktop GUI (PyQt6)
pip install "paperfessor[gui,web]" # + Playwright browsing for full-textFrom a clone (for development): pip install -e ".[gui,web,dev]", or
pip install -r requirements.txt for just the core runtime.
⚠️ Version drift.pip install paperfessorandpip install -r requirements.txtinstall into the active environment and may upgrade or downgrade packages you already have (litellm,numpy,matplotlib, andpydanticpull large dependency trees). Install into a fresh virtualenv or conda env to avoid disturbing other projects:python -m venv .venv && . .venv/bin/activate(orconda create -n paperfessor python=3.11), then install.
LaTeX (TeX Live / MiKTeX / MacTeX with the acmart class) is recommended
for PDF output; without it Paperfessor falls back to .docx (pandoc) or
Markdown. Works on Windows, macOS, and Linux.
API keys live in the OS keychain (Windows Credential Manager / macOS Keychain / Secret Service) — never on disk, never in logs, never in the paper.
paperfessor key set minimax --key "sk-..." # or openai / anthropic / google
paperfessor key test minimax # keychain + LLM round-trip
paperfessor models list # discover live modelsLocal models work too: point the provider at ollama or llamacpp and no
key is needed.
paperfessor run "anomaly detection in multivariate time series"What you get in workspace/:
paper/body/paper.pdf # venue-formatted PDF (acmart two-column)
paper/body/paper.md # canonical Markdown source
src/results/results.json # measured metrics (k = 3 seeds, mean ± 95% CI)
src/figures/ # results chart, dataset sample, block diagram
shared/*.md # the agents' guides and work logs
archived/<slug>/<run id>/ # permanent record of the attempt
The CLI in action (real output from a completed run):
Prefer a window? paperfessor-gui launches the desktop app with the same
pipeline, live agent status, token usage, and a built-in paper preview:
Everything is settable via .env (prefix PAPERFESSOR_), CLI flags on
paperfessor run, or the GUI Settings tab — you have full control over each
agent's model, reasoning, and permissions.
Models & reasoning
| Variable | Default | Meaning |
|---|---|---|
PAPERFESSOR_PROVIDER |
minimax |
LLM provider slug (minimax/openai/anthropic/google/ollama/llamacpp) |
PAPERFESSOR_MODEL |
MiniMax-M3 |
Project-wide default model |
PAPERFESSOR_PHD_MODEL / MS_MODEL / UG_MODEL |
MiniMax-M3 |
Per-agent model overrides |
PAPERFESSOR_THINKING_MODE |
true |
Extended-reasoning prefill |
PAPERFESSOR_MAX_INPUT_TOKENS |
1000000 |
Input cap per call (lower for local models with small context) |
PAPERFESSOR_LANGUAGE |
en |
Interface language en / zh-CN / ja |
Coordination budgets (bound every agent loop; raise for quality, lower for cost)
| Variable | Default | Meaning |
|---|---|---|
PAPERFESSOR_MAX_METHOD_ROUNDS |
3 |
Improvement rounds before a method is abandoned |
PAPERFESSOR_MAX_UG_ROUNDS |
5 |
UG implement→verify→fix attempts |
PAPERFESSOR_MAX_INSPECTION_ROUNDS |
3 |
Whole-paper self-inspection cycles |
PAPERFESSOR_MAX_LLM_CALLS |
85 |
Hard per-run LLM-call budget |
UG permissions (see the safety section below)
| Variable | Default | Meaning |
|---|---|---|
PAPERFESSOR_UG_ALLOW_LOCAL_TOOLS |
true |
UG may run local CLI tools (MATLAB/R/office/etc.) |
PAPERFESSOR_UG_ALLOW_INSTALLS |
true |
UG may pip install packages |
PAPERFESSOR_UG_ALLOW_GPU |
true |
UG may use CUDA for heavy/speed-topic experiments |
Full list in .env.example. Per-agent model picking:
paperfessor models pick --group phd.
Paperfessor runs real code and can touch your machine. Two protection layers:
ug_allow_installs and
ug_allow_local_tools default to true) so experiments "just work." If you do
not want that, turn it off before running:
# Lock the UG down: no installs, no external tools, no GPU
PAPERFESSOR_UG_ALLOW_INSTALLS=false \
PAPERFESSOR_UG_ALLOW_LOCAL_TOOLS=false \
PAPERFESSOR_UG_ALLOW_GPU=false \
paperfessor run "your direction"or set them in .env / the GUI Settings tab. Every install is logged to
workspace/src/tools/installed.txt and every tool call to
workspace/shared/code_log.md for audit. Note that LLM-generated model
code always runs in a strict sandbox — no network, no file I/O, no shell —
regardless of these settings; the permissions above govern only the UG agent's
own toolbelt.
Hard folder scope. Each agent may only create, modify, download, or install inside its assigned folders — enforced in code, not just prompted:
| Agent | May write to | Never touches |
|---|---|---|
| 🎓 PhD | workspace/paper/, workspace/archived/, workspace/doc_memo.md, workspace/article_memo.md, workspace/shared/*_guide.md |
source code, datasets, the work logs |
| 📚 Master's | workspace/shared/research_log.md, downloaded papers under workspace/src/papers/ |
everything else |
| 💻 Undergraduate | workspace/src/ only — code/, tmp/ (scratch), datasets/ (downloads), tools/ (installs), results/, figures/ — and workspace/shared/code_log.md |
anything outside workspace/src/ (path-guarded; escapes are refused) |
Nothing is written outside workspace/. Downloads land in
workspace/src/datasets/, installed tools are recorded in
workspace/src/tools/, temporary scripts go to workspace/src/tmp/ (cleared
each run), and only files the PhD explicitly copies into workspace/paper/
reach the paper.
paperfessor run [DIRECTION] [--venue ... --depth ... --provider ... --model ...]
paperfessor key {set,list,delete,test} # keychain-backed key management
paperfessor models {list,pick} # live model discovery
paperfessor memory {stats,runs,archived} # long-term run memory (SQLite)
paperfessor config show | paperfessor doctor
paperfessor-gui # desktop appBy default Paperfessor pursues state-of-the-art: the proposed method must beat the baselines, or the run is marked failed and the next attempt tries a different method. Tell it otherwise when your paper isn't chasing a win:
paperfessor run "..." --goal comparison # fair benchmark; no win required
paperfessor run "..." --goal experiments # empirical study; report what happens
paperfessor run "..." --goal review # literature review / survey
paperfessor run "..." --goal exploration # open-ended; findings as-is
# --goal sota (default): iterate until competitiveA single paperfessor run is one method attempt. To let the PhD pursue the
goal across many attempts — improve the same method (UG model changes,
hyperparameter tuning, minor theory edits) up to --max-method-rounds times,
then abandon it and design a different one, and when all planned methods are
exhausted start a fresh planning phase that keeps memory but clears the
article, experiments, and datasets — run a campaign:
paperfessor run "..." --campaign --max-campaign-attempts 6Retry depth is yours to set: --max-method-rounds accepts 1 to effectively
unbounded (default 3). In non-SOTA goals a campaign stops at the first clean,
honestly-reported paper.
⚠️ Optional packages may be auto-installed. Some topics need libraries beyond the core (e.g.torch,opencv-python,pandas,scipy,networkx). With the default UG install permission, the agent installs any it needs during generation into the active environment (logged toworkspace/src/tools/installed.txt). Use a dedicated venv/conda env, or setPAPERFESSOR_UG_ALLOW_INSTALLS=falseto forbid it.
- Honesty guardrails (not a guarantee). If the survey is thin, the model fails verification, or a dataset cannot be downloaded, the run is marked failed and archived as such, and the results table is filled only from measured data. These checks make fabrication hard, but the LLM's prose can still contain mistakes — the guardrails reduce risk, they do not remove the need to review.
- Everything is inspectable. The PhD's private memos
(
doc_memo.md,article_memo.md), both work logs, and the archive record every decision with timestamps. - Datasets ship with licenses. Each downloaded dataset records its source URL, license, SHA-256, and split manifest; respect the upstream licenses (e.g. NAB is AGPL-3.0).
- Cost control. One end-to-end run is roughly 200–250K input tokens with MiniMax-M3. Use per-agent model overrides to put a cheaper model on the UG.
- Only registered benchmark domains get experiments. Currently:
time-series anomaly detection (SMD, NAB). Other domains produce a paper
with the experiment section honestly marked pending — extend
paperfessor/research/datasets.pyto add your domain.
Paperfessor is built for research purposes only — as a study of multi-agent scientific workflows and an assistant for early-stage drafts.
- Do not submit its output to conferences, journals, or classes as your own unassisted work, and never in violation of the venue's AI-assistance, authorship, or plagiarism policies. Disclose AI assistance where required.
- Verify everything. Generated text, citations, code, and numbers must be checked by a human before any real-world use.
- Do not use it for fabricated research, citation manipulation, paper mills, or any illegal or deceptive purpose.
The authors and contributors of this repository accept no responsibility or liability for any misuse of this software or for any consequences arising from its use. Use of Paperfessor implies acceptance of these terms and of the MIT license's no-warranty clause.
MIT — free for research and commercial use, no warranty.
The Prof. Meerk mascot (assets/Prof_Meerk.png) is part of this
repository's branding.