PaperForge Research OS v3 – A Structured AI‑augmented Research Assistant

What it is

PaperForge is an open‑source “Research Operating System” that ties together large‑language‑model (LLM)‑based writing agents, experiment management, and a reproducible publication pipeline. It is built in Python (3.10‑3.12) and stores every claim, piece of evidence, code artifact and experiment result in a SQLite‑backed scientific memory. The system can be driven from a command‑line interface (CLI) or a lightweight browser UI, but all actions funnel through a single runtime service (PaperForgeService).

Core ideas & why they matter

Idea	What it does	Why it matters
Unified Research OS	One runtime (ResearchOSRuntime) handles writing, planning, experiments, analysis, visualization, and release.	Removes the “tool‑chain hopping” that typically forces researchers to juggle separate scripts, notebooks, and LaTeX tools.
Evidence‑first workflow	Every public statement in a paper must have a claim_id that links to a stored piece of evidence (code, data, metric, license, etc.).	Guarantees traceability and makes it easier for reviewers or auditors to verify results.
Controlled experiment lifecycle	Proposals → static checks → mini‑experiments → full experiments, each requiring explicit approval.	Prevents accidental resource waste and enforces a review gate before costly training or large‑scale compute.
Multi‑backend compute	Local, Docker, SSH, Slurm, Kubernetes, Cloud‑SSH back‑ends are accessed through a single interface.	Researchers can move from a laptop to a cluster or cloud without rewriting scripts.
Policy‑driven execution profiles	writing-only, research, full – each profile disables a set of actions (e.g., weight loading, remote compute).	Provides a safety net for environments where only certain capabilities are allowed (e.g., a secure workstation).
Publication engine with claim gate	LaTeX compile → PDF render → layout diagnose → constrained repair → invariant verification.	Automates the tedious “compile‑check‑fix” loop and ensures the final PDF matches the recorded claims.

Main components (high‑level view)

CLI / UI  →  PaperForgeService
                ├─ ExecutionPolicy (profiles)
                ├─ WorkflowEngine
                │    └─ ResearchOSRuntime
                │          ├─ Typed Agents (LLM writers, reviewers, etc.)
                │          ├─ Provider Registry (model/key handling)
                │          ├─ Compute Backends (Docker, Slurm, …)
                │          └─ Domain Plugins (CV, NLP, RL, Bio, …)
                ├─ SQLite Scientific Memory (claims, evidence, runs)
                ├─ Artifact Registry (datasets, checkpoints, figures)
                └─ Publication Engine → Release Verifier

All persistent data lives under <workspace>/.paperforge/ (SQLite DB, runtime state, release manifest, etc.).

Typical workflow

1. Create a workspace – a folder that contains your LaTeX source, bibliography and an optional writing-job.json manifest.
2. Run a profile – e.g. paperforge run --profile writing-only … to let the LLM draft sections, insert citations and compile the PDF.
3. Research profile – adds literature search, proposal creation and a proposal object that must be approved before any experiment runs.
4. Full profile – after approval you can launch experiments on any supported backend, automatically logging code, data, hyper‑parameters and SHA‑256 hashes of every artifact.
5. Publish – paperforge publish runs the Claim Gate, LaTeX compile, PDF render and layout diagnostics. The output lives in dist/.
6. Release – paperforge release re‑verifies every gate (secret scan, artifact hashes, claim coverage) and marks the workflow COMPLETED.

How it uses AI

• LLM agents (the “writing‑only” and “research” agents) call a provider named bailu‑turing via an OpenAI‑compatible API. The system strips unsupported fields (e.g., seed, n) and can be pointed at a custom gateway via OPENAI_BASE_URL.
• The agents are typed – the runtime knows whether an agent is allowed to request a model, run code, or only read evidence, based on the selected execution profile.
• Prompt engineering is hidden behind the paperforge run command; users only supply high‑level instructions (title, abstract, etc.).

Installation & getting started (quick recap)

# clone and checkout v3 tag
git clone https://github.com/QJHWC/PaperForge.git && cd PaperForge && git checkout v3.0.0

# create a venv and install the writing extras
python3.12 -m venv .venv && source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e "[writing]"

# optional: add experiment/research extras if you need compute back‑ends
python -m pip install -e "[research,experiment]"

Configure your model key in ~/.config/paperforge/credentials.json (chmod 600). The only supported provider out‑of‑the‑box is bailu‑turing.

Safety & licensing notes

• The project is research‑only – the README includes a disclaimer that it must not be used commercially.
• All secrets are redacted before logging; Docker/SSH uploads are whitelisted and scanned for secrets.
• License: PaperForge License 1.0 – free for personal, academic, non‑commercial use; commercial SaaS or profit‑making redistribution is prohibited.

---

TL;DR

PaperForge v3 is a Python‑based research OS that combines LLM‑driven paper drafting with a rigorously audited experiment‑tracking and publication pipeline. It stores every claim and its evidence in a SQLite database, enforces approval‑gated compute, and can publish LaTeX papers through a reproducible, claim‑checked release process. Ideal for teams that want a single, auditable workflow from idea to a verified PDF.