paperfigg 0.4.0
Agentic CLI for generating academic figures from research papers
License: MIT
Requires Python: >=3.10

# paperfig
[![CI](https://github.com/oluwafemidiakhoa/paperfigg/actions/workflows/ci.yml/badge.svg)](https://github.com/oluwafemidiakhoa/paperfigg/actions/workflows/ci.yml)
[![Docs Drift](https://github.com/oluwafemidiakhoa/paperfigg/actions/workflows/docs-drift.yml/badge.svg)](https://github.com/oluwafemidiakhoa/paperfigg/actions/workflows/docs-drift.yml)
[![Publish](https://github.com/oluwafemidiakhoa/paperfigg/actions/workflows/publish.yml/badge.svg)](https://github.com/oluwafemidiakhoa/paperfigg/actions/workflows/publish.yml)

`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.

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

## 1-Minute Demo
```bash
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.

```bash
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`

![Sample methodology figure](docs/gallery/sample_paper/fig-21a078a0.svg)

## 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
<!-- AUTO-GEN:START cli-command-catalog -->
- `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`
<!-- AUTO-GEN:END cli-command-catalog -->

## Flow Template Pack
<!-- AUTO-GEN:START flow-template-catalog -->
- `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)
<!-- AUTO-GEN:END flow-template-catalog -->

## 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`