Flora：AIと共に、AIのために構築されたダイアグラムライブラリ

10日前、著者はゼロからダイアグラムライブラリの構築を始め、本日 Flora をリリースしました。Flora は Mermaid 互換のフォールトトレラントなライブラリで、不完全な入力から洗練されたインタラクティブな SVG をレンダリングします。この記事では Flora 自体を紹介するだけでなく、その構築プロセスについても語ります。なぜなら、そのプロセスは製品以上に驚きを与えてくれたからです。

なぜ別のダイアグラムライブラリなのか？

データエンジニアとして、アーキテクチャ設計は仕事の大きな部分を占めます。データパイプラインを構築する前には必ず図があります：データの流れ、保存場所、各コンポーネントの関係。図は思考の手段であり、自分の考えが正しいことを他者に納得させるためのツールでもあります。

AI ネイティブな世界では、Mermaid は「コードとしての図」の共通言語となっています。LLM が図を生成し、GitHub がレンダリングし、著者もここ数年愛用してきました。コードとしての図というコアアイデアは素晴らしい：図はリポジトリに保存され、プルリクエストでレビューされ、誰かの放棄された Lucidchart アカウントで腐ることはありません。しかし、二つの点が常に気になっていました。

第一に、見た目の問題。図の外観を特定のスタイルにしたいとき（例えば、ドキュメントサイト全体で一貫した色使い、ラベルを圧縮しない円柱など）、壁にぶつかります。同僚が構築した図デザインツールは本当に美しい出力を生成しますが、すべてハードコードされた SVG でした。1つのノードを変更するだけで全体を再生成する必要があり、Mermaid の宣言的パワーを犠牲にした結果、すぐに後悔しました。

第二に、これは意外なものでしたが、LLM は常に Mermaid を生成します。AI ツールが図を表現するデフォルトの方法となっています。そして、それらはほぼ正しいものの、完全ではありません。1行が不正な形式だと、Mermaid はパースエラーを投げ、UI は空白のボックスを表示します。図がテキストとして AI と人間の間のインターフェースであるなら、レンダラーはテキストが95%正しいときに倒れるべきではありません。

Flora の答え：Mermaid の構文を使用し、より良い出力を提供し、壊れる代わりに曲がるパーサーを備える。

機能概要

Flora は既に使い慣れたフローチャート構文を理解します。例：

flowchart LR events[[Kafka: events]] --> enrich[Enrichment] enrich --> wh[(Snowflake)] wh --> dash([Dashboard])

上記のコードはデフォルトテーマでレンダリングされ、スケッチテーマを使用すると「ホワイトボードの下書き」スタイルになります。

図はデフォルトでインタラクティブ：ズーム、パン、そして著者お気に入りの機能 — 任意のノードをクリックして上流・下流の系統を追跡できます。

フォールトトレランスは最も重視した設計判断です。Mermaid がパースできない行に遭遇すると、例外を投げて空白ボックスを表示します — 図が40行あり39行が正常でも同様です。Flora は理解できない行をスキップし、残りをレンダリングし、スキップした行を行番号付きの診断情報として報告します。さらに重要なのは、決して推測しないこと：不正な行は削除してフラグを立て、あなたが書いていないノードとして再解釈することはありません。CI などで厳格に失敗させたい場合は、strict: true オプションでベストエフォートではなく例外を投げます。

利用方法

Flora はいくつかの方法で使用できます：

• JavaScript/TypeScript：npm install @topspinj/flora で完全なAPIを取得。
• プレーンHTML（ビルド不要）：CDNバンドルがWebコンポーネントを登録し、スクリプトタグを追加するだけで図をマークアップとして記述可能。
• React：ラッパーコンポーネントを提供。
• Markdown ドキュメント：rehype プラグインがビルド時に Flora コードブロックをレンダリングし、デフォルトで壊れた図でビルドを失敗させます。
• Python/Jupyter：pip install florajs で Jupyter/marimo ノートブックおよびヘッドレスSVGエクスポートに対応。
• ブログやスクリプト不要のプラットフォーム：ホステッド /embed ルートが iframe をサポートするあらゆる場所で使用可能（Ghost、Substack、Notion など）。
• Webブラウザ（インストール不要）：プレイグラウンドがライブレンダリングし、図を共有可能なURLにエンコード。

構築プロセス：GitHub Issue をプロンプトとして

著者が本当に振り返りたいのはこの部分です。著者は TypeScript をほとんど書きません。キャリアは React と NodeJS で始まりましたが、それは10年前で、その後は Python と SQL の世界に住んでいます。このプロジェクト以前は、npm パッケージを公開したことも、TypeScript ビルドを設定したことも、パーサー設計について深く考えたこともありませんでした。10日間で、これら全てを達成し、Python ラッパーは空のディレクトリから PyPI への公開まで30分もかかりませんでした。

このワークフローを可能にしたのは、GitHub Issue をプロンプトとして使うことでした。将来の自分や貢献者向けに Issue を書く代わりに、エージェントが拾うことを意図して Issue を書きました。「プロフェッショナルな疑似コーディングのすすめ」で、著者は曖昧な意図を正確な仕様に変換することが仕事の核になりつつあると主張しました。このプロジェクトはそのアイデアを論理的な結論に導いたものです。「パーサーが壊れている」ではなく、「パーサーが理解できない行は丸ごとスキップし、行と列を含む診断として報告する。余分なノードとして再解釈しない。有効なものはすべてレンダリングする。不正な固定値を使った回帰テストを追加する。」

Issue トラッカーが通信プロトコルとなりました。夜に Issue をキューに入れ、翌日取り組むと、プロンプトというよりは非常に速い同僚にチケットを割り当てる感覚でした。

そして Fable が登場

水曜日の夜、一通のメールが届きました：Claude Fable 5 が利用可能になりました。通常ならモデル発表を「後で」見るためにファイルにしまいます。しかし今回は、進行中のプロジェクト、エージェント対応の Issue リスト、そして新モデルをテストする完璧な理由がありました。メール到着から2時間後、Fable は Flora の React ラッパーを出荷しました。

Flora のコミット履歴の約半分は、その後の48時間に集中しています。CDNバンドル、Webコンポーネント、パーサー診断、厳格モード、Pythonパッケージ、ホステッドプレイグラウンド：すべて2日間で完了しました。

しかし、速度が興味深い部分ではありません。Fable は私が頼んでいないバグを発見し、私のアイデアに反論しました。テーマにノード間隔を制御させようとしたとき、Fable は「テーマは図の見た目を変えるべきであり、配置方法を変えるべきではない」と主張し、それは正しかったのです。オートコンプリートというよりはコードレビューに近く、議論に負けて嬉しい気持ちになりました。

v0.1 リリース

まだ初期段階であり、粗い部分があります。Issue トラッカーは正直にそれらをリストアップしています。

最高の部分は？すぐに自分で実践投入できることです。仕事ではオープンソースツールを自由に使えるため、Flora を日常業務に直接投入します。実際のユースケースほどライブラリを試すものはなく、その結果を報告します。

Mermaid を愛用していながら、見た目がより良く、壊れにくいものを望んでいたなら、Flora を試してみてください。