Metadata-Version: 2.4
Name: paper-toolkit
Version: 0.1.0
Summary: Deterministic Python tools for academic-paper development. No LLM calls.
Author: fib-lab
License: MIT License
        
        Copyright (c) 2026 fib-lab
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: matplotlib>=3.8.0
Requires-Dist: pdf2image>=1.17.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: pypdf>=5.0.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.12; extra == 'dev'
Description-Content-Type: text/markdown

# paper-toolkit

Deterministic Python tooling for the fixed steps of academic-paper development —
workspace setup, evidence-DAG management, structured checks, LaTeX composition,
compile + page introspection, figure rendering, literature search, and an
analysis pipeline that feeds the manuscript.

The toolkit contains **no LLM calls**. All writing, review, and judgment lives
in the companion Claude Code skills, which call into this CLI for everything
that should be reproducible.

## Why

Paper drafts drift between agents, sessions, and editors. The toolkit pins the
mechanical parts — schemas, checks, file layout, LaTeX compose, evidence DAG —
so the agent only owns prose. Two skills ship with the package:

- **`agentsociety-analysis`** — runs the 6-stage analysis pipeline
  (frame → explore → claims → refine → produce → synthesis) against an
  experiment SQLite database, emitting bilingual reports + publication-grade
  figure specs.
- **`agentsociety-generate-paper`** — turns analysis outputs into a
  Springer-Nature-style manuscript: intake, drafting, checks, skeptical review,
  revision loop, and compile.

## Install

Requires Python ≥ 3.11.

```bash
# from a clone (recommended for now)
git clone https://github.com/Yokumii/paper-toolkit.git
cd paper-toolkit
uv sync

# or with pip
pip install .
```

LaTeX (TeX Live / MacTeX) is required for `paper compile-once` and
`paper figure render`. The toolkit shells out to `latexmk` / `bibtex` /
`pdflatex` and parses their logs deterministically.

## Quick start

```bash
# 1. create a workspace
uv run paper init --title "Demo" --venue nature --language en --workspace ./demo

# 2. seed an evidence node + claim
uv run paper evidence add-claim --workspace ./demo \
    --node-id c_warming --label "Mean temperature rose 1.1 K" --strength primary

# 3. render a figure from a JSON spec
uv run paper figure render --spec ./demo/paper/figure_specs/f_trend.json --workspace ./demo

# 4. compose and compile
uv run paper compose pack-figures --workspace ./demo
uv run paper compose write-main --workspace ./demo
uv run paper compile-once --workspace ./demo

# 5. structured checks
uv run paper check style --workspace ./demo
uv run paper check claim-coverage --workspace ./demo
uv run paper check figures --workspace ./demo
uv run paper check figure-qa --workspace ./demo
uv run paper status --workspace ./demo
```

Run `uv run paper <group> --help` for the full verb list in each group, or
see the `dev` branch for the long-form design and plan documents.

## CLI surface

| Group | Purpose |
|---|---|
| `paper init` / `status` / `scan` | Workspace lifecycle and snapshotting |
| `paper evidence` | Evidence DAG: nodes, edges, claim/evidence linking |
| `paper template` | List and expand section templates |
| `paper compose` | Pack figures, write `main.tex`, write `refs.bib` |
| `paper compile-once` / `page` | LaTeX compile + page-metadata inspection |
| `paper check` | `style`, `figures`, `claim-coverage`, `figure-qa` |
| `paper figure` / `table` | Render figures and LaTeX tables from JSON specs |
| `paper lit` | Direct-API search (arXiv / CrossRef / OpenAlex) → `refs.bib` |
| `paper refs` | Inspect and dedup `refs.bib` (DOI + title-Jaccard fallback) |
| `paper analysis` | 6-stage analysis pipeline + lift-to-evidence bridge |

Every command emits a JSON `Envelope` on stdout (success, payload, errors) so
the skills can route on structured results rather than parsing prose.

## Using the Claude Code skills

The skills live under `skills/` and are picked up automatically when
paper-toolkit is installed as a Claude Code plugin.

```jsonc
// in .claude-plugin/marketplace.json
{
  "plugins": [
    {
      "name": "paper-toolkit",
      "source": "https://github.com/Yokumii/paper-toolkit"
    }
  ]
}
```

Inside a Claude Code session:

```
/skill agentsociety-analysis        # run the analysis pipeline
/skill agentsociety-generate-paper  # draft, check, and compile the manuscript
```

Both skills read their `SKILL.md` router first, then dispatch to per-stage
prompts and subagents (`data-explorer`, `claim-extractor`, `figure-reviewer`,
`report-producer`, `skeptical-reviewer`, …). All deterministic steps go through
this CLI; the skills never invent file paths or schemas.

## Repository layout

```
src/paper_toolkit/      # the CLI + library (no LLM calls)
  cli/                  # Typer groups (init, evidence, compose, check, figure, lit, refs, analysis, ...)
  models/               # Pydantic v2 schemas (paper.json, evidence graph, claims, ...)
  analysis/             # 6-stage pipeline: db, state, claims, synthesis, lift
  figures/              # JSON-spec → matplotlib renderer (Arial fallback, pdf.fonttype=42, 89/183mm)
  checkers/             # style, figures, claim-coverage, figure-qa
  refs/                 # bib parser + dedup engine
  lit/                  # arXiv / CrossRef / OpenAlex search
  typeset/              # main.tex composition + LaTeX log parsing
skills/
  agentsociety-analysis/
  agentsociety-generate-paper/
tests/                  # 293 unit + integration tests
```

## Design principles

- **No LLM in the toolkit.** Every CLI verb is pure Python + stdlib + a few
  scientific deps (matplotlib, pypdf, httpx). The agent decides what to write;
  the toolkit decides what's legal.
- **Schemas at every boundary.** Pydantic v2 with `extra="forbid"` on every
  artifact: `paper.json`, evidence graph, claims, figure specs, check reports.
- **Derived state, no phase machines.** State files record facts; stages are
  derived from artifact presence + schema validity, so the agent can't lie
  about progress.
- **Idempotent bridges.** `paper figure register` and
  `paper analysis lift-to-evidence` are safe to re-run — they update existing
  rows in place.

## Development

```bash
uv sync --extra dev
uv run pytest -q
uv run ruff check src tests
```

The full design history and per-phase implementation plans live on the `dev`
branch (`docs/design.md`, `docs/plans/`).

## License

MIT — see `LICENSE`.
