# Docs Generate Schematics

> Use when a document, paper, poster, or README needs a scientific schematic, flowchart, block diagram, or architecture figure GENERATED as an image from a text description via an AI image model - CONSORT participant flows, neural-network architectures, pipeline diagrams - using OpenRouter (OPENROUTER_API_KEY) with an automated quality-review loop. Not for converting existing documents (bitranox:docs-convert-markitdown) or code-rendered graphs (graphviz/matplotlib).

- Skill: `bitranox/docs-generate-schematics` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add bitranox/docs-generate-schematics`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bitranox/docs-generate-schematics/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: bitranox (https://skillmd.com/u/bitranox)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bitranox/docs-generate-schematics

---


# Generating scientific schematics with an AI image model

> Adapted from the MarkItDown skill in K-Dense-AI/claude-scientific-skills (MIT). See THIRD_PARTY_NOTICES.md.

Generate publication-style schematic images (flowcharts, block diagrams, architecture
figures) from a text description. The AI variant runs an iterative quality loop: generate,
have a vision model critique the result against the document type, regenerate until the
quality threshold or the iteration cap is hit.

## Requirements

- `OPENROUTER_API_KEY` in the environment (both scripts talk to OpenRouter).
- `httpx2` for the AI script: run it with `uv run`, which reads the script's PEP 723 block
  and fetches the dependency. Plain `python3` only works if httpx2 is already installed. The
  wrapper script imports only stdlib, but it re-launches the AI script with the SAME
  interpreter (`sys.executable`), so it needs `httpx2` just as much - run it under
  `uv run --with httpx2` too, or the child exits 1 on its first import.

## Usage

```bash
# AI generation with quality-review loop
uv run scripts/generate_schematic_ai.py "CONSORT participant flow for a two-arm RCT" -o flow.png
uv run scripts/generate_schematic_ai.py "Neural network architecture diagram" -o arch.png --iterations 2
uv run scripts/generate_schematic_ai.py "Simple block diagram" -o diagram.png --doc-type poster

# Wrapper: same quality-review loop, with the iteration cap clamped to 2
uv run --with httpx2 scripts/generate_schematic.py "Data pipeline overview" -o pipeline.png
```

`--doc-type` tunes the acceptance threshold (a poster tolerates less detail than a paper
figure); `--iterations` caps the regenerate loop.

## Common mistakes

- Expecting deterministic output - image models vary run to run; keep the prompt specific
  (name the boxes, arrows, and labels you need) and review the result yourself.
- Using this for graphs that should be code-rendered - reproducible plots and graphs belong
  in graphviz/matplotlib, not an image model; this skill is for illustrative schematics.
- Committing the generated image without checking the labels - vision-model review catches
  layout problems, not domain wording.
- Running without `OPENROUTER_API_KEY` - both scripts fail fast; set it in the environment,
  never on the command line.