Fireworks Tech Graph turns one prompt into SVG, PNG, GIF or offline HTML

Four output formats behind one script, and a SKILL_ROOT you supply

The CLI is a Python entry point, scripts/fireworks.py, reached through a path the host provides. Two commands show the shape of it:

python3 "$SKILL_ROOT/scripts/fireworks.py" version
python3 "$SKILL_ROOT/scripts/fireworks.py" export-png diagram.svg diagram.png --width 1920

The $SKILL_ROOT variable is the part that trips people up. It is not defined by the project; it is whatever root the agent skill host has mounted, so a plain shell session needs it set before either command resolves. The version subcommand reports the package, the actual skill root, and the Git state when available, which makes it the fastest way to tell whether you are pointing at the copy you think you are. PNG export is where the strictness lives: it checks the root canvas, bounds the image size, writes atomically, and reads the resulting pixel dimensions back off disk. A separate browser-based exporter stays available when you need Chromium rendering fidelity.

Twelve styles, and a repository description that still says seven

The style list runs from Style 1 through Style 12, each entry paired with a fixed scenario used as a regression case: Flat Icon, Dark Terminal, Blueprint, Notion Clean, Glassmorphism, Claude Official, OpenAI Official, Dark Luxury, C4 Review Canvas, Cloud Fabric, Event Transit, and Ops Pulse.

The breakdown matters more than the count. Eleven are described as generator-backed, and Dark Luxury is labelled AI-authored. The four styles above it are described as engineering-first, carrying executable contracts for C4 reviews, cloud deployments, event streams, and reliability investigations, which lines up with the Checkout Container, Active-Active Deployment, Event Line, and Reliability Pulse scenarios named under Styles 9 to 12. So one visual theme in the set did not come out of the same deterministic path as the other eleven.

The repository description field is the loose end: it advertises 7 styles, while the style list and the overview both count twelve. If you are choosing a style by what the metadata promises, you will look at barely over half of the set. Test Dark Luxury first if reproducibility is what you care about, since it is the one the project itself flags as authored rather than generated.

text_policy strict fails the run instead of shipping a truncated label

Text fit is treated as a defect class rather than a cosmetic detail. Add "text_policy": "strict" to the configuration and visible truncation is rejected before output is written, so the run fails instead of producing a diagram with a clipped label. The reports preserve the full source label and explain how to recover, which means the information survives in the log even when the rendered box does not fit it.

Two related details. Chinese descriptions use the available second line, so bilingual text gets a real layout slot rather than a squeezed first line. And theme-specific guidance plus measurement limits live in references/visual-quality.md, a reference file rather than README prose.

The practical choice is a trade with a real cost. Strict mode protects the diagram and taxes your pipeline, since a label that used to render truncated now aborts the export, and any batch job that renders hundreds of diagrams will surface these as failures instead of images. Leave it off while exploring, turn it on for anything a human will read.

The GIF contract is 115 frames at 20fps, and the samples predate the checkout

Motion is not open-ended. The animated previews run a user-approved 5.75-second settled-flow timeline: routes draw in first, then the final topology keeps live data moving for two additional seconds. Each full-size GIF is 960 pixels wide at 20fps across 115 frames, and the overview strip is an optimized 1200 pixel preview. Lossless 1920 pixel PNGs sit in assets/samples/ as static regression baselines, which is what makes the style comparison in the README reproducible.

There is a version caveat in plain sight. The animated previews in the README are the published 1.2.0 references, and the project states that the current checkout is an unreleased upgrade that preserves their motion contracts. In other words the tree you clone is ahead of the artifacts you are comparing against.

For a reader this narrows what a diff can prove. If your own output diverges from assets/samples/, you cannot tell from the samples alone whether the checkout changed the contract or your generation did, because the published frames predate the unreleased work. A 115 frame budget also means a denser diagram gets less live-motion time, since the draw-in phase has to finish inside the same fixed length.

An npm package with a Python entry point and a Node 22 engine gate

The distribution is unusual in a way worth knowing before you install it. package.json names the package @yizhiyanhua-ai/fireworks-tech-graph at version 1.2.0, and its bin entry points at a Python file:

"bin": {
  "fireworks-tech-graph": "scripts/fireworks.py"
}

The same manifest also declares engines node >=22.12.0, in a repository whose primary language is Python. So an npm install of a Python tool puts a Node version requirement on the npm install, and the bin name reads like a JavaScript executable while resolving to a script you would otherwise invoke with python3.

Two more manifest details carry weight. The files array ships SKILL.md, both READMEs, LICENSE, CHANGELOG.md, CONTRIBUTING.md, SECURITY.md, and the agents/, docs/, examples/, references/, schemas/, scripts/, tests/, fixtures/, templates/ and assets/ directories, while excluding __pycache__ and *.pyc. The homepage points at a GitHub Pages site that the package does not include.

The published tarball omits tools/, so the consistency check only runs in a clone

The manifest ships three scripts and the test suite is stdlib only. Rendering the bundled examples is a single call:

python3 scripts/fireworks.py examples

Tests run through unittest discovery, with no third-party test runner in the command:

python3 -m unittest discover -s tests -v

Now the gap. The check script is:

python3 tools/check_project_consistency.py && python3 tools/distribution.py --check

Both files live in tools/, and tools/ appears nowhere in the files array. The same is true of index.html, robots.txt, sitemap.xml, site.webmanifest, .github/ and skills/ at the repository root. So the project's own consistency and distribution checks cannot run from an installed copy of the package. If your pipeline wants them as a release gate, you need a clone of the repository, and the distribution check you would want to run against a published tarball is exactly the one the tarball cannot perform. A second consequence for CI: the Node 22 engine gate applies to the npm path, and the test path above assumes a Python 3 shell, so the two halves have different prerequisites.

The README doubles as a consulting pitch, with two sponsor blocks above it

Between the Sponsors table and the Work With the Builder section, a good share of this README is not about diagrams. The sponsorship table carries AIGoCode with its own referral bonus and service terms, which are the sponsor's claims rather than the project's, and a contact address for sponsorship sits underneath. The Work With the Builder section describes the project as a proof surface for turning vague AI and devtool workflows into constrained systems, and offers scoped paid sprints, design-partner work, and founding engineer conversations, with links to a personal profile, a commercial case study, and a contact page.

That context changes how you read the roadmap. The manifest lists a single author, and the release history is a tight sequence: v1.1.0 on 2026-07-15, then v1.2.0 and v1.0.5 both dated 2026-07-17, with the patch landing on the older line minutes after the minor. So the 1.0 branch is still being patched while 1.2.0 is the headline, and the last push on the default branch was on 2026-10-21.

Nothing here says the project will be abandoned. It says the work is steered by one maintainer who is also selling time on it, which is a reason to pin a release and vendor the output rather than to plan around upstream changes.

Editorial conclusion

Use it if you want one prompt to produce a checked SVG plus a PNG export and you already run Codex or Claude Code, since the install story is a skill root rather than a library. Do not adopt it expecting the twelve styles to be equally reproducible, because eleven come from a generator and Dark Luxury is AI-authored, and do not expect the npm tarball to carry the project's own checks, since tools/ is excluded from the published files. Before you wire it into a docs pipeline, run version and doctor, confirm your Node version clears >=22.12.0 if you install through npm, decide whether strict text_policy is worth the failed runs, and pin to a release, since the checkout carries changes the published 1.2.0 samples do not.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes