Skip to content

goatinahat/papervizagent

v0.5.0Apache-2.0

Scientific figures with upstream PaperVizAgent, separate roles, configurable model providers and Codex subscription fallback. Host-native defaults where tools are available.

GitHubOpen Website

PaperVizAgent

Scientific figures using Google Research’s official PaperVizAgent pipeline, with separate roles and configurable inference on every surface. This is an independent distribution, not an official Google Research release.

The Python processor, seven agent implementations and complete style guides are reused from pinned upstream source. ToolFactory generates the integrations and release packages from that one runtime.

Release status: GitHub/source installation is available; the PyPI, npm, ClawHub and browser-store commands below require the publisher setup described in RELEASING.md. Until PyPI is published, run the runtime from source:

uvx --from git+https://github.com/GoatInAHat/PaperVizAgent@main papervizagent mcp

Install

Agent Skill

  • Agent Skill — npx skills add GoatInAHat/PaperVizAgent
  • MCP server — uvx papervizagent mcp Install in VS Code Install in Cursor
  • Claude Desktop extension — download papervizagent.mcpb from the GitHub Release and double-click to install
  • Claude Code plugin — claude plugin marketplace add GoatInAHat/PaperVizAgent, then claude plugin install papervizagent@papervizagent
  • Codex plugin — codex plugin marketplace add GoatInAHat/PaperVizAgent, then codex plugin add papervizagent@papervizagent
  • Gemini CLI extension — gemini extensions install https://github.com/GoatInAHat/PaperVizAgent
  • OpenClaw plugin — openclaw plugins install --link hosts/openclaw from a checkout; published: openclaw plugins install clawhub:openclaw-plugin-papervizagent
  • Hermes plugin — hermes plugins install https://github.com/GoatInAHat/PaperVizAgent#hosts/hermes/papervizagent_hermes
  • DSH plugin (experimental) — dsh plugin --profile <profile> add ./hosts/dsh from a checkout, or the release tarball papervizagent-dsh-0.5.0.tgz
  • Browser extension — from a checkout: npm --prefix hosts/browser install && npm --prefix hosts/browser exec --no -- wxt build, then chrome://extensions → developer mode → Load unpacked → hosts/browser/.output/chrome-mv3 (Firefox: npm --prefix hosts/browser exec --no -- web-ext run). Each GitHub Release attaches the store uploads papervizagent-0.5.0-chrome.zip, papervizagent-0.5.0-firefox.zip, papervizagent-0.5.0-edge.zip. When Firefox signing credentials are configured, it also attaches a Mozilla-signed .xpi; the Chrome Web Store, Firefox Add-ons and Edge Add-ons listings appear once the release's submit step has each store's credentials. Then pair it: uvx papervizagent mcp --http --pair prints the <url>#<token> the extension's options page accepts.
  • Web app — uvx papervizagent mcp --http --open serves the operations page beside the MCP endpoint on one port and opens it; over MCP or a skill, the web operation does the same and returns the URL.
  • npm package — npm install papervizagent; requires uv, and papervizagent delegates to uvx --from papervizagent==0.5.0 papervizagent
  • PyPI package — uv add papervizagent

The npm package is a small launcher for the same version on PyPI and requires uv. MCPB uses its host’s supported uv runtime. Downloadable bundles and registry listings are separate: see release status.

Defaults and model choice

The skill resolves each role independently: explicit role setting → modality setting → available host tool → Codex fallback. It checks actual tools; a host name does not guarantee vision or image generation.

The shared model_policy defaults to balanced: native roles use a current mid-tier alias or live catalog, and Codex selects from its current account catalog with a recorded reason. Claude Code uses sonnet for planning and image inspection, keeping Codex fallback confined to missing image generation. Choose quality for a highest-quality request (opus in Claude); explicit model and effort choices still win. Catalog tier labels are advisory, with transparent provider-default fallbacks. See configuration.

On Codex, the skill uses native subagents, vision and image generation without API keys or a Python server. The Codex plugin does not eagerly start MCP. Custom overrides use the optional runtime through the CLI or an explicitly connected MCP server.

On other hosts, use available native capabilities and supply CODEX_OAUTH_TOKEN for missing capabilities, or use an existing Codex sign-in. CODEX_ACCOUNT_ID is needed only if the supplied token does not contain its account identifier. Tokens stay in environment/host secret settings or an explicitly selected token file; never paste them into prompts or tool arguments. Static access tokens expire: their owner must refresh them. The SDK manages refresh for its own sign-in.

A standalone CLI/MCP/web server cannot directly invoke another app’s private tools. Its generate operation uses configured SDK providers or Codex. The portable skill is the bridge to host-native tools; embedded Python integrations can also supply native callbacks to Backend(native={...}). A callback is awaited with keyword arguments role, modality, system, contents, options, model, and model_policy; it must apply a configured model when present and return the role output. An unavailable capability produces an error.

The official Codex SDK discovers subscription models and starts a fresh, ephemeral thread for every role call. models.image.model selects the Codex coordinating model; Codex manages the built-in image generator. Arbitrary image-model selection uses an image API provider. Codex does not expose API controls such as temperature or maximum output tokens; explicit unsupported overrides fail, and unavailable upstream defaults are listed in the trace. Aspect/size requests are prompt guidance on Codex. See configuration.

Use

In an agent host:

Use $papervizagent to turn these methods and this caption into a scientific diagram.

With the runtime installed:

papervizagent status --json '{"native":["llm","vlm"]}'
papervizagent models
papervizagent generate --json '{"data":{"content":"Encode the input, retrieve evidence, then decode the answer.","visual_intent":"Overview of the inference pipeline"},"settings":{"exp_mode":"demo_full","retrieval_setting":"none","max_critic_rounds":3}}'
papervizagent mcp

status only resolves configuration. models verifies the Codex account catalog without inference. infer runs one isolated role and returns text or an image path plus its trace. generate runs the upstream pipeline, retaining intermediate descriptions, code, image data and role traces under the tool’s data directory. Set PAPERVIZAGENT_DATA_DIR to choose it.

Both diagrams and Matplotlib plots support vanilla, planner, planner+stylist, planner+critic, full, retrieval-only and polish modes. Candidate count, concurrency, critic rounds, retrieval mode, aspect ratio, style guides and provider options remain configurable. The skill defaults to automatic reference retrieval; the standalone runtime defaults to none until a reference dataset or supplied examples are provided. The runtime defaults to one full candidate and three critic rounds; upstream’s ten-candidate demo is a selectable configuration, not an implied default.

Original prompt constants and style guides remain unchanged. Each native role has a fresh subagent; each runtime role makes an isolated provider request or Codex thread. Critic revisions produce fresh renders; polish is a separate editing workflow. Plot execution runs generated Python in a temporary child process with a configurable timeout and 300 DPI output. This isolates plotting state and hangs; it is not an OS security sandbox. Use the host’s execution sandbox for untrusted inputs.

Background execution

In hosts with background completion notifications, the skill dispatches one coordinator to own generation, isolated roles, critique and review. The main conversation receives the completion or failure event. It does not schedule check-ins or repeatedly poll files for progress.

Runtime integrations keep one awaited CLI process or MCP request. Embedded Python hosts can use papervizagent.ops.generate_events for run, candidate and role lifecycle events, or supply an async on_event callback to generate. The host owns the background task and delivers the result when it completes; there is no additional daemon or scheduler. Hosts without a background completion channel use one awaited call. See completion events for the event contract and cancellation behavior.

Development and fidelity

uv sync
make build
make check
make validate
make package

FIDELITY.md records historical gaps and current adaptations. UPSTREAM.json and the runtime’s own provenance manifest pin reused source. Configuration documents provider and pipeline settings. Release status distinguishes packaged integrations from published listings. This port does not inherit upstream’s benchmark scores and is not an official Google or OpenAI integration.