PaperForge v3: a research OS that gates a paper on its own evidence

The gap PaperForge targets: claims that outrun their evidence

Most paper-writing tools stop at text. You paste results in, the model expands them, and nothing in the system knows whether a sentence in the abstract corresponds to a run that happened. PaperForge v3 takes the opposite position. The README describes it as an evidence-centred research system, and the release rules make that literal: public assertions in the paper must be linked through a claim_id to source code, literature, run results, experiment results or licence evidence. The target user is a researcher or small lab that already runs experiments in code and wants the paper's factual claims to be traceable to files on disk. It is not aimed at someone who wants a drafting assistant for a literature review with no experiments behind it. The v2 to v3 comparison table in the README is explicit about the shift: v2 ran separate entry points (writeup, research_partner, mvp, scientist) each with its own flow, while v3 funnels every entry point through a single PaperForgeService and ResearchOSRuntime. That consolidation is what makes a shared claim database possible in the first place.

One runtime, one SQLite file, four registries

The architecture diagram in the README shows the CLI, a browser front end and the v2 compatibility entry points all landing on PaperForgeService. From there the path splits into ExecutionPolicy and the Workflow Engine, which drives ResearchOSRuntime. The runtime fans out to typed agents, a Provider Registry, compute backends and domain plugins. Two stores sit underneath: SQLite Scientific Memory and the Artifact Registry, both feeding the Publication Engine and then the Release Verifier. The persistent state is per workspace. A workspace holds .paperforge/paperforge.db plus runtime and publication directories and release_manifest.json, alongside artifacts/, dist/, main.tex and references.bib. The database is described as holding workflows, events, approvals, sources, evidence, claims, experiments, artifacts and review results. Writes use version numbers, idempotency keys and transactions, and the README states that an interrupted run can be recovered with paperforge resume. That is the part worth noting for anyone evaluating reliability: recovery is a documented first-class command rather than a manual database repair.

Three execution policies and what writing-only actually blocks

ExecutionPolicy is the mechanism that separates a writing job from a research job. Three levels exist: writing-only, research and full. The README states that writing-only refuses at four layers (policy, tool registration, commands and context) and lists what is blocked: training, inference and experiment commands; SSH, container and remote compute; weight files such as .pt, .pth, .ckpt and .onnx; experimental data in CSV, NumPy or Parquet; and run_* result directories and executable experiment scripts. This is a stronger design than a prompt instruction, because the refusal happens in code paths the agent cannot talk its way past. The experiment path itself is staged: Proposal, then Static Check, then Mini Experiment, then Full Experiment, with approval required. The README says the system saves code, configuration, data, weights, metrics and artifact hashes. Whether the approval step is a human gate or an automated check is not spelled out in the supplied material, and that distinction matters if you intend to run this unattended overnight.

Installing it: extras, credentials and the preflight contract

The install is a standard editable pip install with extras that map to capability. python -m pip install -e . gives the core research OS, state and basic CLI. Adding ".[writing]" brings model calls, literature, PDF and paper writing. ".[research]" adds research providers, ".[experiment]" adds experiment, training and remote compute dependencies, and ".[dev]" adds Pytest, Ruff and Mypy. The README notes that a writing-only user does not need PyTorch, Transformers, Datasets or the training stack. Python 3.10 through 3.12 is the supported range. Credentials live outside the workspace, at ~/.config/paperforge/ on macOS and Linux or C:\Users\<user>\.config\paperforge\ on Windows, in a credentials.json file with a bailu_primary key. On macOS and Linux the file must be chmod 600; on Windows the ACL is checked. The README is direct that PaperForge does not accept plaintext keys as command-line arguments and does not write keys into the workspace. Verification is paperforge preflight --workspace ., with an optional --live-provider flag that sends one minimal real request. The four reported states are CODE_VERIFIED, EXTERNAL_SERVICE_VERIFIED, AUTH_BLOCKED and FAILED. One detail deserves attention: static preflight reports latex_compiler, bibtex and pdftoppm as separate fields, and their absence does not turn the top-level status into FAILED, but publish will later fail the corresponding gate.

The writing model is pinned, and the README says so plainly

This is the constraint most likely to decide an adoption for a team. The README states that the current v3 formal writing path is fixed to the bailu provider and the bailu-turing model, and warns against relying on config.json to switch the production writing model, because the current CLI runtime does not inject provider, model or generation_profile from it into the writing agent. The default base URL is https://bailucode.com/openapi/v1, and a unified request builder strips fields Bailu does not support: reasoning_effort, seed, n and stop. Those rules are applied consistently across single, batch, review, citation, stream and Aider paths. You can override the gateway by exporting OPENAI_BASE_URL, but setting conflicting OPENAI_BASE_URL, OPENAI_WRITEUP_BASE_URL and OPENAI_API_BASE variables causes PaperForge to stop rather than guess. If your institution requires a specific approved model endpoint for text generation, this pinning is a blocker, not a configuration detail. The README also carries a disclaimer that the project is for learning and research use and not for commercial use.

Where the release gate is stricter than most pipelines

Publication is where PaperForge differs most from a LaTeX template with an LLM bolted on. Four templates are supported: Generic, CVPR, IEEE and Elsevier. Compilation runs up to three rounds of compile, render, diagnose and bounded layout repair. Then the gate: the README states a workflow reaches COMPLETED only when claims, PDF, protection blocks, page checks, secret scanning and the release manifest all pass. The protection-block concept is worth flagging for anyone who has watched a model rewrite a table it was not asked to touch. Two limitations are visible in the material. First, the release verifier is described but its individual failure messages are not documented in the supplied README, so diagnosing a blocked release means reading the database and the manifest. Second, the whole verification chain assumes LaTeX and Poppler are installed; a machine without latexmk, BibTeX and pdftoppm can still do research and state management, but cannot finish a formal PDF release. Neither limitation is hidden, but both shape what a working setup looks like.

Compute backends and the honest alternative

The compute layer exposes Local, Docker, SSH, Slurm, Kubernetes and Cloud SSH behind one interface, which is the practical reason a lab with a shared cluster can use this without rewriting its submission scripts. The v2 column of the migration table shows the prior state: local and remote scripts handled separately. The obvious alternative for many teams is a plain LaTeX project plus a general coding agent, or a notebook-driven workflow where you run experiments yourself and paste results into a draft. That alternative has no claim_id linking, no approval stages, no artifact hashes and no release gate, but it also has no pinned provider, no credentials file convention and no SQLite schema to learn. A second alternative is a reference manager plus a static site or Overleaf setup with a CI job that compiles the PDF. The difference in approach is that PaperForge treats the paper and the experiment as one state machine with a single database, while the alternative treats them as two artefacts joined by a human. If your bottleneck is experiment tracking rather than prose, PaperForge's claim database may be more machinery than you need.

Maintenance cost and the licence question

The repository is not archived and the last push recorded is 2026-07-26, with version v3.0.0 and no releases retrieved. The README documents a v2 to v3 migration path, which tells you the project has already made one breaking structural change, and the presence of v2 compatibility entry points routed through the v3 service suggests those legacy paths carry ongoing maintenance weight. Upgrading means re-checking that your claims, experiments and templates still validate against the v3 gate rather than assuming the database migrates silently. On licensing, the repository metadata reports NOASSERTION, which means no standard licence identifier could be determined from the repository. The README itself carries only a disclaimer restricting use to learning and research and excluding commercial use; that is a statement in documentation, not a recognised open source licence, and it is not legal advice to say so. If you need clear redistribution or commercial terms, this is the first thing to resolve, before you invest in a workspace.

Editorial conclusion

Adopt PaperForge if you already produce papers with code and want the claim-to-artifact link enforced by tooling rather than by discipline, and if you accept that the writing path is pinned to the bailu provider and the bailu-turing model in v3. Do not adopt it if you need a portable or self-hosted model endpoint for the writing agent, or if you cannot install latexmk, BibTeX and pdftoppm on the machine that publishes. Before committing a real project, run paperforge preflight with --live-provider, then run a writing-only workspace end to end and inspect .paperforge/paperforge.db to confirm that the claims you care about actually carry evidence rows.

Official sources

1. Issues
2. QJHWC/PaperForge on GitHub
3. README