convez.ai
SkillAutomaçãoIntermediário
julioccorderoc

Doc Generator

julioccorderoc/doc-generator

Gera PDFs profissionais (POs, invoices, RFQs) a partir de conversa natural

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill Claude que transforma requisições em linguagem natural em documentos PDF profissionais (Pedidos de Compra, Notas Fiscais, RFQs). Claude coleta dados via conversa; um script determinístico renderiza o PDF, garantindo saída consistente. Sem formulários, sem SaaS, sem copiar-colar.

Instalação

$npx convez-ai julioccorderoc/doc-generator

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
6

Casos de uso

  • Gerar pedidos de compra automaticamente a partir de requisição verbal
  • Criar notas fiscais e invoices sem software de contabilidade
  • Produzir cotações e RFQs para fornecedores em segundos

Veredito

Solução bem-arquitetada para automação de documentos comerciais. Separação clara entre orquestração Claude (conversa) e renderização determinística (CLI Python) evita hallucinations no PDF. Útil para fluxos de procurement, mas limitado a três tipos de documento por enquanto.

README

A tradução para o português deste README ainda está na fila.

doc-generator

Python License Stars

A Claude skill and CLI tool that turns a natural language request into a professional PDF business document. Claude handles the conversation; a deterministic script handles rendering. Same input always produces the same PDF.

# Install the skill — one command
npx skills add julioccorderoc/doc-generator

Then just ask Claude:

"I need a PO for PureSource — 250kg whey protein at $8.40/kg, net 30, FedEx Ground."

Claude collects what it needs, confirms, and drops a clean PDF in your output/ folder. No forms, no SaaS, no copy-paste.

New doc type ideas or contributions welcome — adding one requires five files, nothing else.


What it looks like

Replace placeholders above with screenshots from your output/ folder once generated.


Supported Document Types

SlugDocumentDescription
purchase_orderPurchase OrderBuyer-to-vendor authorization for goods or services at agreed prices and terms
invoiceInvoiceIssuer-to-client payment request for goods delivered or services rendered
request_for_quotationRequest for Quotation (RFQ)Buyer-to-vendor specification document requesting a price; no monetary values

On the roadmap: delivery notes, packing slip, quotes.


How It Works

  1. Claude collects data — asks for required fields in a single pass, applies smart defaults, never asks for computed values.
  2. Claude writes a payload file — JSON at a temp path. No inline JSON, no shell quoting issues.
  3. Claude invokes the CLI — uv run python scripts/generate.py --doc_type <type> --payload <path>.
  4. The script renders the PDF — Pydantic validates, Python computes, Jinja2 renders, WeasyPrint writes. No model in the render path.
  5. Claude reports the result — output path, grand total, balance due, or a plain-language validation error.

Claude Code Skill

Install the skill so Claude can orchestrate the workflow:

npx skills add julioccorderoc/doc-generator

To update after changes:

npx skills update -g

See SKILL.md for the full skill definition: trigger conditions, data collection protocol, and output presentation format.

Manual Setup

The CLI is what actually renders the PDF — it needs to be on your machine.

git clone https://github.com/julioccorderoc/doc-generator.git
cd doc-generator
uv sync
brew install pango   # macOS only — required by WeasyPrint
# Ubuntu/Debian: sudo apt-get install libpango-1.0-0 libharfbuzz0b libpangoft2-1.0-0

Stack

LibraryRole
WeasyPrintHTML/CSS → PDF renderer. No headless browser, no Chromium.
Jinja2Templating engine. Templates receive pre-formatted strings — no logic inside.
Pydantic v2Schema validation and computed fields (subtotal, grand_total, etc.).
uvDependency management and script runner. Reproducible environments with a lockfile.

CLI Reference

For agents or direct use:

uv run python scripts/generate.py --doc_type <type> --payload <path> [--preview] [--output_name <stem>] [--output_dir <dir>] [--save_payload]
ArgumentRequiredDescription
--doc_typeYesDocument type slug (purchase_order, invoice, request_for_quotation).
--payloadYesPath to a JSON file. File path only — not inline JSON.
--previewNoOpens the PDF with the OS default viewer after generation. Silent no-op in headless environments.
--output_nameNoCustom filename stem. Output becomes <PREFIX>_<name>.pdf (e.g. --output_name NS39 → PO_NS39.pdf). Defaults to date + sequential counter.
--output_dirNoDirectory to save the generated PDF. Defaults to <project_root>/output/. Pass $(pwd) to save in the caller's working directory.
--save_payloadNoSaves the validated payload (with all computed fields) as a .json file alongside the PDF, using the same filename stem.

Exit codes:

OutcomeExit codestdout
Success0Absolute output path, e.g. /path/to/doc-generator/output/PO_20260316_0001.pdf
Validation error1Structured error — which fields failed and why
Unknown doc_type1List of registered doc type slugs

No interactive prompts. No assumed environment variables. Agents capture stdout and check the exit code.

Full platform-agnostic interface contract: CLAUDE.md.


Running Locally

macOS / Linux prerequisites:

uv sync
brew install pango   # macOS system dependency — once only
# Ubuntu/Debian: sudo apt-get install libpango-1.0-0 libharfbuzz0b libpangoft2-1.0-0

Generate a document:

DYLD_LIBRARY_PATH=/opt/homebrew/lib uv run python scripts/generate.py \
  --doc_type purchase_order \
  --payload tests/fixtures/sample_po.json \
  --preview

Test validation error output:

DYLD_LIBRARY_PATH=/opt/homebrew/lib uv run python scripts/generate.py \
  --doc_type purchase_order \
  --payload tests/fixtures/invalid_po.json

Run the test suite (no Pango or display needed):

uv run pytest

Full field references — all optional fields, validation rules, and example payloads:


Extending

Adding a new document type requires five files — nothing else changes:

1. references/<doc_type>.md      — field definitions, validation rules, computed fields, layout notes
2. schemas/<doc_type>.py         — Pydantic v2 model derived from the reference
3. templates/<doc_type>.html     — Jinja2 template extending base.html
4. builders/<doc_type>.py        — context builder function
5. builders/__init__.py          — one DocTypeConfig entry added to REGISTRY

generate.py, base.html, style.css, and the core generation engine are never modified when adding a doc type.

See references/EXTENDING.md for the full developer guide.


Why This Skill Is Safe to Install

PropertyDetail
DeterministicSame JSON input always produces the same PDF. No randomness, no model calls in the render path.
Fully localRuns on your machine. No outbound network calls at generation time.
No paid servicesWeasyPrint, Jinja2, and Pydantic are all open-source. No API keys required.
No credential accessThe script reads only the payload file you pass it. It does not touch environment variables, secrets, or system files.
AuditableThe render path is a single script: scripts/generate.py. Templates: templates/. Schemas: schemas/.

Project Structure

Key directories — full detail in CLAUDE.md:

doc-generator/
├── CLAUDE.md          ← Agent entry point: CLI contract, conventions, design decisions
├── SKILL.md           ← Claude skill definition
├── scripts/           ← CLI entrypoint (generate.py)
├── schemas/           ← Pydantic v2 models per doc type
├── builders/          ← Context builders + REGISTRY
├── templates/         ← Jinja2 templates extending base.html
├── assets/            ← style.css + per-doc-type CSS
├── references/        ← Source-of-truth specs + EXTENDING.md + DESIGN_SYSTEM.md
└── tests/fixtures/    ← Valid and invalid sample payloads

Contributing

Contributions welcome. The most useful things to add:

  • New document types — follow the five-step pattern in references/EXTENDING.md. Each doc type is self-contained.
  • Bug fixes — check docs/decisions/ before changing any architectural pattern; a decision record may explain the constraint.

When in doubt, read the reference file for the doc type you are modifying first. The reference is the source of truth — not the code.

Ver o original no GitHub

Bom para

Relacionados