forgegraph 0.0.1__tar.gz → 0.2.0__tar.gz

{forgegraph-0.0.1 → forgegraph-0.2.0}/.gitignore

@@ -18,3 +18,4 @@ dist/
 .coverage
 htmlcov/
 .ipynb_checkpoints/
+.cache/

{forgegraph-0.0.1 → forgegraph-0.2.0}/.pre-commit-config.yaml

@@ -5,11 +5,12 @@ repos:
       - id: check-yaml
       - id: check-toml
       - id: end-of-file-fixer
-        exclude: \.md$
+        exclude: \.md$|^(review|catalog)/
       - id: trailing-whitespace
-        exclude: \.md$
+        exclude: \.md$|^(review|catalog)/
       - id: check-added-large-files
         args: [--maxkb=600]
+        exclude: ^(review|catalog)/  # self-contained HTML pages embed their images
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.17.1
     hooks:

forgegraph-0.2.0/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+ForgeGraph follows [semantic versioning](https://semver.org). Before 1.0, a minor version may change how graphs look or how specs are written. From 0.1.0 on, each release's entry links its visual changelog: before and after images of every catalog card and regression graph that changed, made with `scripts/visual_changelog.py`.
+
+## 0.2.0 (2026-10-24)
+
+Images that changed: the [visual changelog](review/visual-changelog/0.2.0.html).
+
+### Changed
+
+- Error bars are black by default in both built-in themes, and their color (`layer.error_bar.color`) is a variable parameter: a GraphSpec may set `series` or any hex color.
+- Three internal modules are renamed so none shares a name with the API: `forgegraph.render` is `forgegraph.drawing`, `forgegraph.layout` is `forgegraph.layouts` and `forgegraph.blank` is `forgegraph.canvas`. `import forgegraph.layouts as m` now gives the module, not `fg.layout`. The API is unchanged.
+
+### Fixed
+
+- `forgegraph --version` and `--help` no longer load matplotlib and pandas, so they answer at once, even on a new install. The API loads on first use.
+- The README and the skill's reference say when the main config is written: the first time a command reads the configs, such as `catalog` or `render`.
+- Error bars on side-by-side bars (`series.offset: side_by_side`) are drawn on their own bars. Before, every series but the middle one had its error bars drawn where they were first placed, before layout, usually off the axes.
+
+## 0.1.0 (2026-10-24)
+
+The first public release.
+
+### Added
+
+- **GraphSpecs:** a graph described in YAML or as a Python dict, drawn with `forgegraph render` or `fg.render`; `fg.xy` draws straight from a DataFrame.
+- **The `xy` graph type:**
+  - lines, markers and bars: grouped, stacked, 100 % stacked and horizontal;
+  - dates and log axes, value labels, a benchmark series;
+  - series named beside their lines or in a key.
+- **Layers:** reference lines, notes and error bars, from the data or given.
+- **Themes and formats:** a theme fixes what must stay the same and gives defaults for the rest; a format sets size, base font size, file types and resolution.
+- **Packs and configs:**
+  - every named spec comes from a pack, named `pack/name`; ForgeGraph's own is `forgegraph_base`, and `forgegraph_base_2` is a second look in this repository;
+  - the main config (written on first use, or named by `FORGEGRAPH_CONFIG`) and folder configs (`forgegraph.toml`) say which packs may be used;
+  - a pack only a folder config lists is non-standard: it works, and what's drawn with it is watermarked.
+- **Lint on every render:** overlapping or clipped text, a key covering data, fonts too small for the format, missing fonts, dropped rows and more.
+- **Provenance:** every saved file (PNG, JPEG, TIFF, SVG, PDF and HTML) records its GraphSpec and the specs it was drawn with, at the format's provenance level; `forgegraph load` reads it back.
+- **Layouts:** several GraphSpecs in one figure, with spanning tiles, blank cells and set widths; tabs, and HTML dashboards.
+- **Scheduled renders:** schedule files, `forgegraph job run`, a status file, `on_failure` and `on_success` hooks, a "data as of" footnote and a stale banner.
+- **The themed canvas:** `forgegraph.blank(theme, format)` for what no graph type can draw, always watermarked as non-standard.
+- **The agent skill** for Claude Code, installed with `forgegraph skill install`, with reference notes for themes, formats and configs, and for filing requests.
+- **Commands:** `render`, `explain`, `catalog`, `schema`, `pack-notes`, `load`, `job run` and `skill install`, each with `--json`.
+- **Catalogs:** a page for each pack in this repository, with a card for every parameter.
+
+## 0.0.1 (2026-10-17)
+
+The name, reserved on PyPI. No functionality.

forgegraph-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing
+
+Contributions are welcome. For a bug or a feature request, open an [issue](https://github.com/sskaye/forgegraph/issues). For a change, open a pull request with tests, after running the checks below.
+
+## Development setup
+
+```bash
+uv sync
+uv run pre-commit install
+```
+
+While you work, `uv run pytest` runs the development suite: every test not marked slow, in parallel. The full suite adds the slow ones (every catalog card drawn, the image baselines, the catalog pages, and any test over a second). CI runs it on every pull request, and it's the one to run before a release:
+
+```bash
+uv run pytest --full && uv run ruff check . && uv run pyright
+```
+
+Mark a new test `@pytest.mark.slow` if it takes over a second (`uv run pytest --durations=20` lists the slowest).
+
+## After changing a definition or how graphs are drawn
+
+A new or changed parameter needs its card in the matching catalog file under `src/forgegraph/catalogs/`; the build refuses a catalog that misses one.
+
+
+Rebuild the review catalog (it keeps its review comments; Node 18+ is needed once it has some), and the image baselines if graphs look different on purpose:
+
+```bash
+uv run forgegraph catalog build
+uv run forgegraph catalog build --pack forgegraph_base_2
+uv run python scripts/mirror_specs.py
+uv run python scripts/build_recreations.py --baselines
+```
+
+`uv run python scripts/visual_changelog.py main` then shows every image that changed.
+
+## Requesting a chart type
+
+Open a GitHub issue describing the graph you need, ideally with an example image or sketch and a little sample data. No code is needed.
+

forgegraph-0.2.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.5
+Name: forgegraph
+Version: 0.2.0
+Summary: Consistent, high-quality graphs from pandas DataFrames, for people and AI agents. Early development.
+Project-URL: Repository, https://github.com/sskaye/forgegraph
+Author: Steven Kaye
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.12
+Requires-Dist: matplotlib>=3.9
+Requires-Dist: packaging>=23
+Requires-Dist: pandas>=2.2
+Requires-Dist: pyarrow>=17
+Requires-Dist: pydantic>=2.7
+Requires-Dist: ruamel-yaml>=0.18
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# ForgeGraph
+
+Fast, consistent, publication-quality graphs from pandas DataFrames, useable by people and AI agents.
+
+You describe a graph in a **GraphSpec**. ForgeGraph draws it in a house style set by a **theme** and a **format**. It checks what it drew, and records how the graph was made inside the saved file. An agent skill lets agents make and revise graphs the same way.
+
+**<u>Key Features</u>**
+
+- **Themes:** fixes the look of the graph (fonts, palette, lines, keys, etc.).
+- **Formats:** sets the destination: figure size, base font size, file types and resolution, e.g. a slide, a journal column or a dashboard tile.
+- **GraphTypes:** defines the type of graph and its parameters. E.g. `xy` (lines, markers and bars).
+- **Layers:** features drawn over a graph. E.g. reference lines, notes, & error bars.
+- **GraphSpecs:** specify the data, theme, format, and all customizable properties.
+- **Layouts:** combine multiple graphs into a larger figure or multi-tab dashboard.
+- **Scheduled renders:** re-render graphs and dashboards on a schedule set with cron, launchd, or by an agent.
+- **Provenance:** every saved file contains its specifications as metadata, enabling inspection of how the graph was made and reproduction of it.
+- **Packs:** collect together a set of themes and formats for different use cases. E.g. a company or lab’s standard style, journal requirements, etc.
+- **Configs:** control which packs may be used, per user or folder. Used to enforce use of style pack(s) and watermark non-standard graphs.
+- **Lint:** Graphs are linted on rendering, with warnings for issues including overlapping or clipped text, a key covering data, or fonts too small.
+
+**Status:** 0.x.  `xy` graph type (lines, markers, & bars), reference lines, error bars, and notes layers, initial style packs. More graph types coming soon. If there’s specific ones you want, [open an issue](https://github.com/sskaye/forgegraph/issues).
+
+## Install
+
+ForgeGraph needs Python 3.12 or later.
+
+```bash
+pip install forgegraph
+```
+
+For the `forgegraph` command on its own, `uv tool install forgegraph` works too. To install the skill for Claude Code:
+
+```bash
+forgegraph skill install
+```
+
+For another agent, give the folder it reads skills from:
+
+```bash
+forgegraph skill install --dest <skills folder>
+```
+
+Then ask your agent for a graph: the skill takes it from your data to a finished graph, saving the GraphSpec beside it.
+
+## Quick start
+
+In Python:
+
+```python
+import pandas as pd
+import forgegraph as fg
+
+runs = pd.DataFrame({
+    "hours": [0, 1, 2, 3, 0, 1, 2, 3],
+    "voltage": [0.72, 0.71, 0.70, 0.69, 0.73, 0.73, 0.72, 0.72],
+    "cell": ["A", "A", "A", "A", "B", "B", "B", "B"],
+})
+g = fg.xy(runs, x="hours", y="voltage", color="cell", title="Cell voltage")
+g.save("voltage")  # voltage.png, with its GraphSpec inside
+```
+
+From the command line, with the DataFrame saved as runs.parquet and a GraphSpec, voltage.yaml:
+
+```yaml
+name: voltage
+version: 0
+description: Cell voltage over a test, one line per cell.
+extends: None
+fixed_parameters: None
+variable_parameters:
+    specifications:
+        graph_type: xy
+        theme: forgegraph_base/base_theme
+        format: forgegraph_base/base_format
+    text:
+        title: Cell voltage
+    data:
+        file: runs.parquet
+        preprocessing: None
+    axis:
+        x:
+            data:
+                column: hours
+        y:
+            data:
+                column: voltage
+    encoding:
+        color: cell
+```
+
+```bash
+forgegraph render voltage.yaml
+```
+
+## Packs and configs
+
+Every named theme, format, GraphSpec, layout and schedule comes from a **pack**, a folder or pip package of specs, and is named `pack/name`. The initial built-in packs are `forgegraph_base` and `forgegraph_base_2`, stored in src/forgegraph/packs.
+
+A **config** lists the packs that may be used:
+
+- The main config, `~/.config/forgegraph/config.toml` (or the file `FORGEGRAPH_CONFIG` names), applies to all work. ForgeGraph writes it, listing the built-in packs, the first time a command reads the configs, such as `catalog` or `render`.
+- A folder config, `forgegraph.toml`, applies to the files in its folder and every folder below it. A file may use only the packs it lists.
+- A pack that a folder config lists but the main config doesn't still works, but it's non-standard: graphs drawn with it are watermarked, and ForgeGraph's commands say so. That way you can make and try a pack without changing an organization's main config.
+
+## Commands
+
+- `forgegraph render <graphspec or layout>`: draw and save, and report lint.
+- `forgegraph explain <graphspec or layout>`: every value it's drawn with, and which file set it.
+- `forgegraph catalog`: the packs, graph types, layer types, themes, formats and reference notes available here.
+- `forgegraph schema graphspec --graph-type <type> --theme <theme> --format <format>`: every parameter a GraphSpec can set.
+- `forgegraph schema <kind>`: every parameter of a theme, format, layer, layout, schedule, pack or config.
+- `forgegraph pack-notes`: the reference notes of the packs available here.
+- `forgegraph load <file>`: a saved graph's record, and its GraphSpec.
+- `forgegraph job run <schedule>`: render a schedule's GraphSpecs and layouts once.
+- `forgegraph skill install`: install the agent skill.
+
+Every command takes `--help`, and `--json` for agents.
+
+## Catalogs
+
+Each pack in this repository has a catalog: a page with a card for each parameter, showing what changing it does.
+
+- forgegraph_base: ForgeGraph's own pack, with its graph types and layer types.
+- forgegraph_base_2: its own theme and format, and the same graph types and layer types drawn in them.
+
+## Your graphs are yours
+
+ForgeGraph is [MIT-licensed](LICENSE). Graphs and other output you make with it are yours: no attribution or licence terms apply to them. See TRADEMARKS.md for use of the name.
+
+## Documentation
+
+- Architecture: how ForgeGraph is designed, and why.
+- Decisions: decisions that refine the architecture.
+- Specifications: every spec, a folder per kind.
+- [Changelog](CHANGELOG.md).
+- Build plan: how ForgeGraph is being built, phase by phase.
+
+## Contributing
+
+Feature requests and bug reports go to [GitHub issues](https://github.com/sskaye/forgegraph/issues); the skill can file them for you. CONTRIBUTING.md covers working on ForgeGraph itself. In short:
+
+```bash
+uv sync && uv run pre-commit install
+```
+
+```bash
+uv run pytest --full && uv run ruff check . && uv run pyright
+```
+
+## Repository map
+
+- **src/forgegraph/**: the package.
+  - `graph.py`: the Python API (`fg.xy`, `fg.render`, `fg.graphspec`, `fg.load`) and the `Graph` object; `canvas.py`: the themed canvas.
+  - **cli/**: the `forgegraph` command.
+  - **spec/**: reading, checking and resolving specs, and the provenance record.
+  - **drawing/**: drawing, layout and lint. **layouts/**: layouts. **jobs/**: scheduled renders.
+  - **packs/**: packs and configs, and the built-in packs `forgegraph_base` and `forgegraph_base_2`. **fonts/**: bundled fonts and their licences.
+  - **graph_types/**, **layers/**: the graph type and layer type definitions. **catalog/**, **catalogs/**: the catalog builder, and each definition's catalog file.
+  - **skill/forgegraph/**: the agent skill.
+- **catalog/**: the generated catalog pages.
+- **examples/**: sample data, and `packs/acme`, an example pack in a deliberately different style.
+- **evals/skill/**: the skill's eval cases, run by `scripts/run_skill_evals.py`.
+- **tests/**, **scripts/**: tests, and build and maintenance scripts.
+- **docs/**: the documents above. **review/**: each build phase's review pages.
+

forgegraph-0.2.0/README.md

@@ -0,0 +1,165 @@
+# ForgeGraph
+
+Fast, consistent, publication-quality graphs from pandas DataFrames, useable by people and AI agents.
+
+You describe a graph in a **GraphSpec**. ForgeGraph draws it in a house style set by a **theme** and a **format**. It checks what it drew, and records how the graph was made inside the saved file. An agent skill lets agents make and revise graphs the same way.
+
+**<u>Key Features</u>**
+
+- **Themes:** fixes the look of the graph (fonts, palette, lines, keys, etc.).
+- **Formats:** sets the destination: figure size, base font size, file types and resolution, e.g. a slide, a journal column or a dashboard tile.
+- **GraphTypes:** defines the type of graph and its parameters. E.g. `xy` (lines, markers and bars).
+- **Layers:** features drawn over a graph. E.g. reference lines, notes, & error bars.
+- **GraphSpecs:** specify the data, theme, format, and all customizable properties.
+- **Layouts:** combine multiple graphs into a larger figure or multi-tab dashboard.
+- **Scheduled renders:** re-render graphs and dashboards on a schedule set with cron, launchd, or by an agent.
+- **Provenance:** every saved file contains its specifications as metadata, enabling inspection of how the graph was made and reproduction of it.
+- **Packs:** collect together a set of themes and formats for different use cases. E.g. a company or lab’s standard style, journal requirements, etc.
+- **Configs:** control which packs may be used, per user or folder. Used to enforce use of style pack(s) and watermark non-standard graphs.
+- **Lint:** Graphs are linted on rendering, with warnings for issues including overlapping or clipped text, a key covering data, or fonts too small.
+
+**Status:** 0.x.  `xy` graph type (lines, markers, & bars), reference lines, error bars, and notes layers, initial style packs. More graph types coming soon. If there’s specific ones you want, [open an issue](https://github.com/sskaye/forgegraph/issues).
+
+## Install
+
+ForgeGraph needs Python 3.12 or later.
+
+```bash
+pip install forgegraph
+```
+
+For the `forgegraph` command on its own, `uv tool install forgegraph` works too. To install the skill for Claude Code:
+
+```bash
+forgegraph skill install
+```
+
+For another agent, give the folder it reads skills from:
+
+```bash
+forgegraph skill install --dest <skills folder>
+```
+
+Then ask your agent for a graph: the skill takes it from your data to a finished graph, saving the GraphSpec beside it.
+
+## Quick start
+
+In Python:
+
+```python
+import pandas as pd
+import forgegraph as fg
+
+runs = pd.DataFrame({
+    "hours": [0, 1, 2, 3, 0, 1, 2, 3],
+    "voltage": [0.72, 0.71, 0.70, 0.69, 0.73, 0.73, 0.72, 0.72],
+    "cell": ["A", "A", "A", "A", "B", "B", "B", "B"],
+})
+g = fg.xy(runs, x="hours", y="voltage", color="cell", title="Cell voltage")
+g.save("voltage")  # voltage.png, with its GraphSpec inside
+```
+
+From the command line, with the DataFrame saved as runs.parquet and a GraphSpec, voltage.yaml:
+
+```yaml
+name: voltage
+version: 0
+description: Cell voltage over a test, one line per cell.
+extends: None
+fixed_parameters: None
+variable_parameters:
+    specifications:
+        graph_type: xy
+        theme: forgegraph_base/base_theme
+        format: forgegraph_base/base_format
+    text:
+        title: Cell voltage
+    data:
+        file: runs.parquet
+        preprocessing: None
+    axis:
+        x:
+            data:
+                column: hours
+        y:
+            data:
+                column: voltage
+    encoding:
+        color: cell
+```
+
+```bash
+forgegraph render voltage.yaml
+```
+
+## Packs and configs
+
+Every named theme, format, GraphSpec, layout and schedule comes from a **pack**, a folder or pip package of specs, and is named `pack/name`. The initial built-in packs are `forgegraph_base` and `forgegraph_base_2`, stored in src/forgegraph/packs.
+
+A **config** lists the packs that may be used:
+
+- The main config, `~/.config/forgegraph/config.toml` (or the file `FORGEGRAPH_CONFIG` names), applies to all work. ForgeGraph writes it, listing the built-in packs, the first time a command reads the configs, such as `catalog` or `render`.
+- A folder config, `forgegraph.toml`, applies to the files in its folder and every folder below it. A file may use only the packs it lists.
+- A pack that a folder config lists but the main config doesn't still works, but it's non-standard: graphs drawn with it are watermarked, and ForgeGraph's commands say so. That way you can make and try a pack without changing an organization's main config.
+
+## Commands
+
+- `forgegraph render <graphspec or layout>`: draw and save, and report lint.
+- `forgegraph explain <graphspec or layout>`: every value it's drawn with, and which file set it.
+- `forgegraph catalog`: the packs, graph types, layer types, themes, formats and reference notes available here.
+- `forgegraph schema graphspec --graph-type <type> --theme <theme> --format <format>`: every parameter a GraphSpec can set.
+- `forgegraph schema <kind>`: every parameter of a theme, format, layer, layout, schedule, pack or config.
+- `forgegraph pack-notes`: the reference notes of the packs available here.
+- `forgegraph load <file>`: a saved graph's record, and its GraphSpec.
+- `forgegraph job run <schedule>`: render a schedule's GraphSpecs and layouts once.
+- `forgegraph skill install`: install the agent skill.
+
+Every command takes `--help`, and `--json` for agents.
+
+## Catalogs
+
+Each pack in this repository has a catalog: a page with a card for each parameter, showing what changing it does.
+
+- forgegraph_base: ForgeGraph's own pack, with its graph types and layer types.
+- forgegraph_base_2: its own theme and format, and the same graph types and layer types drawn in them.
+
+## Your graphs are yours
+
+ForgeGraph is [MIT-licensed](LICENSE). Graphs and other output you make with it are yours: no attribution or licence terms apply to them. See TRADEMARKS.md for use of the name.
+
+## Documentation
+
+- Architecture: how ForgeGraph is designed, and why.
+- Decisions: decisions that refine the architecture.
+- Specifications: every spec, a folder per kind.
+- [Changelog](CHANGELOG.md).
+- Build plan: how ForgeGraph is being built, phase by phase.
+
+## Contributing
+
+Feature requests and bug reports go to [GitHub issues](https://github.com/sskaye/forgegraph/issues); the skill can file them for you. CONTRIBUTING.md covers working on ForgeGraph itself. In short:
+
+```bash
+uv sync && uv run pre-commit install
+```
+
+```bash
+uv run pytest --full && uv run ruff check . && uv run pyright
+```
+
+## Repository map
+
+- **src/forgegraph/**: the package.
+  - `graph.py`: the Python API (`fg.xy`, `fg.render`, `fg.graphspec`, `fg.load`) and the `Graph` object; `canvas.py`: the themed canvas.
+  - **cli/**: the `forgegraph` command.
+  - **spec/**: reading, checking and resolving specs, and the provenance record.
+  - **drawing/**: drawing, layout and lint. **layouts/**: layouts. **jobs/**: scheduled renders.
+  - **packs/**: packs and configs, and the built-in packs `forgegraph_base` and `forgegraph_base_2`. **fonts/**: bundled fonts and their licences.
+  - **graph_types/**, **layers/**: the graph type and layer type definitions. **catalog/**, **catalogs/**: the catalog builder, and each definition's catalog file.
+  - **skill/forgegraph/**: the agent skill.
+- **catalog/**: the generated catalog pages.
+- **examples/**: sample data, and `packs/acme`, an example pack in a deliberately different style.
+- **evals/skill/**: the skill's eval cases, run by `scripts/run_skill_evals.py`.
+- **tests/**, **scripts/**: tests, and build and maintenance scripts.
+- **docs/**: the documents above. **review/**: each build phase's review pages.
+

{forgegraph-0.0.1 → forgegraph-0.2.0}/TRADEMARKS.md

@@ -9,4 +9,4 @@ The code is MIT-licensed, but the licence covers the code, not the name. You are
 
 Please don't use "ForgeGraph", or a confusingly similar name, as the name of a fork, product, package or service. Give your project its own name.
 
-Bundled fonts carry their own licences and trademarks: "Source" is a trademark of Adobe (see `src/forgegraph/themes/fonts/OFL-SourceSans3.md`).
+Bundled fonts carry their own licences and trademarks: "Source" is a trademark of Adobe (see `src/forgegraph/fonts/OFL-SourceSans3.md`), and "Plex" is a Reserved Font Name of IBM (see `src/forgegraph/fonts/OFL-IBMPlexSerif.txt`).