Metadata-Version: 2.4
Name: figio-tools
Version: 0.1.0
Summary: Declarative build orchestrator for reproducible scientific figures
Author-email: Arash Shahidi <A.Shahidi@campus.lmu.de>
License-Expression: MIT
Project-URL: Homepage, https://github.com/arashshahidi1997/figio
Project-URL: Documentation, https://arashshahidi1997.github.io/figio/
Project-URL: Repository, https://github.com/arashshahidi1997/figio
Project-URL: Issues, https://github.com/arashshahidi1997/figio/issues
Keywords: figure,scientific,svg,matplotlib,reproducible,composition
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: mpl
Requires-Dist: matplotlib>=3.7; extra == "mpl"
Provides-Extra: export
Requires-Dist: cairosvg>=2.7; extra == "export"
Provides-Extra: all
Requires-Dist: figio-tools[mpl]; extra == "all"
Requires-Dist: figio-tools[export]; extra == "all"
Dynamic: license-file

# figio

Declarative build orchestrator for reproducible scientific figures.

Distribution name: `figio`
Import package: `figio`
CLI: `figio`

figio coordinates existing plotting libraries (Matplotlib, Vega-Lite, etc.) through a YAML manifest (FigureSpec) that describes panels, layout, annotations, and style tokens — then assembles them into a single, validated SVG suitable for journal submission.

figio is an **orchestration system**, not a rendering engine. Panels are opaque — figio doesn't reach inside them. It coordinates their output into a composed figure with validated positioning, annotations, and journal compliance checks.

## Install

```bash
pip install figio                # core orchestrator
pip install "figio[mpl]"         # + Matplotlib adapter
pip install "figio[export]"      # + PDF/PNG export via CairoSVG
pip install "figio[all]"         # everything
```

## Quick start

```bash
# Scaffold a figure spec
figio init

# Build a figure from spec
figio build figures/fig1.yaml

# Validate against journal target
figio validate figures/fig1.yaml --target nature

# Inspect spec metadata
figio inspect figures/fig1.yaml
```

## Architecture

```
FigureSpec (YAML) → Adapters → Panel SVGs → Composer → Composed SVG → Export (PDF/PNG)
```

| Layer | What it does |
|-------|-------------|
| **Schema** | Pydantic models: FigureSpec, PanelSpec, LayoutSpec, AnnotationSpec |
| **Targets** | Built-in journal profiles (Nature, default) with size/font constraints |
| **Adapters** | Protocol + backends: Matplotlib renders panels to SVG |
| **Composer** | Grid solver, constraint application, SVG assembly, annotation placement |
| **Validate** | Checks against target profile (width, height, font size, overflow) |
| **Export** | SVG → PDF/PNG via CairoSVG (optional dependency) |
| **Cache** | SHA-256 content hashing for incremental rebuilds |

## Part of the projio ecosystem

figio integrates with [projio](https://github.com/arashshahidi1997/projio) as the figure orchestration layer. When used through projio's MCP server, it exposes tools for AI-assisted figure authoring: `figio_build`, `figio_inspect`, `figio_validate`, `figio_edit_spec`, `figio_query_output`.

## License

MIT
