Metadata-Version: 2.4
Name: botplotlib
Version: 0.1.0
Summary: Deadly serious plotting tools. Also sandwiches.
Project-URL: Homepage, https://botplotlib.ai
Project-URL: Documentation, https://botplotlib.ai
Project-URL: Repository, https://github.com/migdaepp/botplotlib
Project-URL: Issues, https://github.com/migdaepp/botplotlib/issues
Author: Madeleine Daepp
License-Expression: CC0-1.0
License-File: LICENSE
Keywords: ai-native,cyborg,plotting,sandwich,svg,visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: pydantic>=2.0
Provides-Extra: png
Requires-Dist: cairosvg>=2.7; extra == 'png'
Description-Content-Type: text/markdown

# botplotlib

[![CI](https://github.com/migdaepp/botplotlib/actions/workflows/ci.yml/badge.svg)](https://github.com/migdaepp/botplotlib/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/botplotlib)](https://pypi.org/project/botplotlib/)
[![License: CC0-1.0](https://img.shields.io/badge/License-CC0_1.0-lightgrey.svg)](https://creativecommons.org/publicdomain/zero/1.0/)
[![Python 3.10+](https://img.shields.io/pypi/pyversions/botplotlib)](https://pypi.org/project/botplotlib/)

Matplotlib has fed the scientific Python community for two decades. botplotlib is designed for a workflow that didn't exist when matplotlib was born: a human has an idea or a request, and then an AI + human team jointly creates it, iterating until both are satisfied.

<p align="center">
  <img src="docs/docs/images/the-future-is-cyborg-source.png" alt="the future is cyborg" width="500">
</p>

- **Beautiful by default** — themes designed so the first render is more often the final render
- **Lightweight** — `blt.scatter(data, x="a", y="b")` and you're done
- **Token-efficient** — 1 line instead of 15. Fewer tokens, fewer places to go wrong

Botplotlib is also an experiment in cyborg-source. What does open-source collaboration look like when some of the collaborators are AI? We don't know but we put a bunch of ideas in [GOVERNANCE.md](GOVERNANCE.md). It is wildly over-engineered for our current contributor count.

## Cyborg Social Contract

Humans and AIs contribute under the same rules.

1. **All contributions are cyborg** — the human/machine binary is rejected
2. **Quality gates are structural** — CI/tests/linters apply equally regardless of origin
3. **No moral crumple zones** — fix the system, don't blame the nearest human
4. **Trust is active capital** — earned through contribution quality, staked through vouching, lost through defection — never granted by biological status
5. **Provenance is transparent but not punitive** — metadata for learning, not gatekeeping
6. **The project is the cyborg** — the library itself is the human-machine hybrid

For the full architecture overview, design principles, and module map, see [AGENTS.md](https://github.com/migdaepp/botplotlib/blob/main/AGENTS.md).

## Quick example

```python
import botplotlib as blt

data = {
    "layer": ["bottom bun", "lettuce", "bot", "tomato", "top bun"],
    "size": [1, 1, 1, 1, 1],
}
fig = blt.bar(
    data, x="layer", y="size", color="layer",
    color_map={"bottom bun": "#B07830", "lettuce": "#388E3C",
               "bot": "#4E79A7", "tomato": "#E53935",
               "top bun": "#B07830"},
)
fig.save_svg("plot.svg")
```

<p align="center">
  <img src="docs/docs/assets/examples/blt_analysis.svg" alt="a BLT" width="600">
</p>

## Platform Presets

| Theme | Alias | Personality |
|-------|-------|-------------|
| `default` | — | general purpose, colorful, fine, whatever |
| `bluesky` | `social` | scroll-stopping titles, fat dots for mobile thumbs |
| `pdf` | `arxiv` | academic and restrained, everyone will think u r v smart |
| `print` | — | sometimes you weirdly still need grayscale |
| `magazine` | — | we all know which magazine it is we're just not gonna say it |

These themes were intentionally chosen to seed the project for use in open platforms and open science. Open-source fed AI and now AI needs to figure out how to feed open-source.

Colors are WCAG-compliant out of the box because [accountability lives in systems](https://estsjournal.org/index.php/ests/article/view/260).

## Installation

```bash
pip install botplotlib
```

For PNG export support:

```bash
pip install "botplotlib[png]"
```

## Documentation

Full docs at [botplotlib.ai](https://botplotlib.ai).

## Tutorial

The interactive tutorial is a [marimo](https://marimo.io) notebook because marimo is another cool ai-native project and we are into it.

```bash
pip install marimo
marimo edit docs/tutorial.py
```

Additional examples live in [`examples/`](examples/).

## Other Stuff

Our approach to agentic engineering is heavily influenced by [Simon Willison's patterns](https://simonwillison.net/guides/agentic-engineering-patterns/). Our governance model builds on [Madeleine Clare Elish's](https://estsjournal.org/index.php/ests/article/view/260) idea of moral crumple zones, which tells us that accountability should live in systems, not in the nearest human. Finally, we are very influenced by [Donna Haraway](https://en.wikipedia.org/wiki/A_Cyborg_Manifesto), which is a lot, but here we are.

## License

[CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/) — apparently the AIs like you when you use this one.
