paperfigg 0.4.0

Agentic CLI for generating academic figures from research papers

paperfig

paperfig is a production-grade CLI that converts research papers (PDF or Markdown) into publication-ready academic figures using an agentic planning -> generation -> critique pipeline.

The core differentiator is that agent reasoning and architecture decisions are stored as versioned repo artifacts (architecture docs, flows, Mermaid diagrams, templates, audits) so humans and agents can evolve the system together.

Install

Warning paperfig on PyPI is a different project; install paperfigg. The CLI command remains paperfig.

• Standard CLI + PNG export:
  • pip install "paperfigg[cli,png]"
• Developer tooling:
  • pip install "paperfigg[cli,png,dev,yaml,pdf,mcp]"
• CLI-first local install:
  • pipx install .
  • uv tool install .
  • Published package name is paperfigg; CLI command remains paperfig.

Quickstart (Mock Mode, No Keys)

Mock mode is designed for instant local runs and realistic output artifacts.

pip install "paperfigg[cli,png]"
paperfig doctor
paperfig generate examples/sample_paper.md --mode mock
paperfig docs check

1-Minute Demo

pip install "paperfigg[cli,png]"
paperfig doctor
paperfig generate examples/sample_paper.md --mode mock
ls runs/*/figures/*/final/figure.svg

Full Mode (PaperBanana MCP)

Use full mode when you want real PaperBanana generation via MCP.

pip install "paperfigg[cli,png,mcp]"
export PAPERFIG_MCP_SERVER=paperbanana
export PAPERFIG_MCP_COMMAND="python -m your_mcp_server"
paperfig doctor --probe-mcp
paperfig generate examples/sample_paper.md --mode real

What's New In v0.4.0

• Figure contracts:
  • Each figure emits contract.json and is validated during critique and export.
• Static HTML inspector:
  • paperfig inspect --html builds a self-contained inspector per run.
• Plugin registry:
  • paperfig plugins list and paperfig plugins validate surface critique and repro plugins.
• Regression detection:
  • paperfig regress <paper_v1> <paper_v2> produces regression_report.json.
• Journal mode:
  • paperfig generate ... --mode journal:neurips enforces stricter gates and required figure kinds.

What You Get

• Generated figures (SVG and optional transparent PNG)
• LaTeX include snippets
• Captions and figure plans
• Traceability mapping from figure elements to source text spans
• Figure contracts (contract.json) per figure
• Static HTML inspector (runs/<run_id>/inspect/index.html) per run
• Governance artifacts (docs_drift_report.json, architecture_critique.json, repro_audit.json)

Sample proof assets are committed in docs/gallery/sample_paper:

• docs/gallery/sample_paper/fig-21a078a0.svg
• docs/gallery/sample_paper/plan.json
• docs/gallery/sample_paper/repro_audit.json
• docs/gallery/sample_paper/architecture_critique.json

What It Does

• Parses papers and extracts methodology, system description, and results sections.
• Plans figures through reusable flow templates and fallback heuristics.
• Generates figures via PaperBanana MCP and iterates with critique feedback loops.
• Regenerates docs and gates on drift for architecture governance.
• Runs reproducibility audits and architecture critiques as first-class run artifacts.
• Provides a constrained autonomous lab scaffold for iterative research experiments.

How The Agentic System Works

The system uses specialized agents:

• PlannerAgent chooses figures and template-aligned abstractions.
• GeneratorAgent calls PaperBanana via MCP and emits traceable figure elements.
• CriticAgent scores faithfulness, readability, conciseness, and aesthetics.
• ArchitectureCriticAgent audits run-level architecture quality and governance completeness.

Full architecture documentation and flow diagrams live in docs/architecture.

CLI Usage

• paperfig generate
• paperfig rerun
• paperfig diff
• paperfig regress
• paperfig critique
• paperfig export
• paperfig doctor
• paperfig inspect
• paperfig inspect --html
• paperfig docs regenerate
• paperfig docs check
• paperfig templates list
• paperfig templates validate
• paperfig templates lint
• paperfig plugins list
• paperfig plugins validate
• paperfig critique-architecture
• paperfig audit
• paperfig lab init
• paperfig lab propose
• paperfig lab run
• paperfig lab review
• paperfig lab status

Flow Template Pack

• ablation_matrix (ablation)
• dataset_characteristics (dataset_overview)
• error_analysis_breakdown (error_analysis)
• limitations_threats_to_validity (limitations)
• methodology_pipeline (methodology)
• results_summary_plot (results_plot)
• system_overview (system_overview)
• training_compute_profile (compute_profile)

Outputs

Each run creates a runs/<run_id>/ workspace containing:

• figures/<figure_id>/figure.svg
• figures/<figure_id>/traceability.json
• figures/<figure_id>/contract.json
• captions.txt
• inspect.json
• inspect/index.html and inspect/manifest.json when paperfig inspect --html is used
• docs_drift_report.json
• architecture_critique.json
• repro_audit.json
• plugins.json
• journal_profile.json when journal mode is enabled
• planner_notes.md, CONTRIBUTING_NOTES.md, and contrib.log when --contrib is enabled
• exports/ with PNG, SVG, LaTeX snippets, and export_report.json

Regression reports are written to runs/<regress_run_id>/regression_report.json.

Configuration

Default config lives in paperfig.yaml:

• docs scope and manifest path (docs/docs_manifest.yaml)
• architecture critique mode and severity gate
• reproducibility audit mode (soft by default)
• template pack (expanded_v1)
• lab registry path and sandbox policy (config/lab_policy.yaml)

Verification

• Run unit/integration tests: python3 -m unittest discover -s tests -v
• Run docs drift check: ./scripts/check_docs_drift.sh
• Run full quality checks: ./scripts/check_quality.sh

CI

• GitHub Actions pipeline: .github/workflows/ci.yml
• GitHub Actions docs drift gate: .github/workflows/docs-drift.yml
• GitHub Actions PyPI publish: .github/workflows/publish.yml
• Publish workflow uses PyPI Trusted Publishing (OIDC) with GitHub environment pypi.
• Manual publish.yml runs are dry-run by default; set workflow input publish=true to actually upload.
• GitLab pipeline: .gitlab-ci.yml
• All wrappers call shared scripts in scripts/ (no duplicated CI logic in YAML)

Community

• Changelog: CHANGELOG.md
• Contributing: CONTRIBUTING.md
• Code of conduct: CODE_OF_CONDUCT.md
• Citation metadata: CITATION.cff

Architecture Docs

See:

• docs/architecture/AI-Architecture-Analysis.md
• docs/architecture/flows/index.md
• docs/templates/HOW_TO_ADD_A_FLOW.md
• docs/templates/DOMAIN_PACKS.md
• docs/platform/WINDOWS_PNG.md
• docs/features/FIGURE_CONTRACTS.md
• docs/features/HTML_INSPECTOR.md
• docs/features/PLUGINS.md
• docs/features/REGRESSION.md
• docs/features/JOURNAL_MODE.md

Publish Troubleshooting

• Package name on PyPI is paperfigg (not paperfig).
• If publish fails with "file already exists", rerun is safe because publish uses skip-existing: true.
• If publish fails with OIDC/token project mismatch:
  • verify Trusted Publisher is configured for project paperfigg
  • owner/repo must be oluwafemidiakhoa/paperfigg
  • workflow must be publish.yml
  • environment name must be pypi