🌸 Flowillower 柳暗花明

“山重水复疑无路，柳暗花明又一村。”——宋·陆游 《游山西村》

“Through layered peaks and winding flows, no path seems in sight; /

Beyond shadowed willows, blooming flowers—a village comes to light”

(Lu You, 1167 AD in the Song Dynasty, “Travel to a Village West of the Mountains”, as translated by the library author in 2025).

A graceful, distributed, and Git-powered experiment tracking and model explanation tool for AI researchers. See through every forward pass. Flow will over — and flowers will bloom.

✨ What is flowillower?

flowillower(willow + flower = flo -willow- er = flowillower = flow-will-over ) is a lightweight, decentralized alternative to experiment tracking tools like Weights & Biases or TensorBoard — built for researchers who care not just about metrics, but about meaning.

It enables you to:

• 🌱 Track metrics, models, and forward flows
• 🧠 Visualize PyTorch model structures and internal tensor paths
• 🌍 Store all logs in a Git-powered directory (local-first, push-optional)
• 🚀 Deploy visualizations to Hugging Face or ModelScope Spaces via a template app
• 🔐 Keep your data — your data (No central server required)

Whether you’re blocked in a thicket of non-converging experiments or wandering in a maze of parameter sweeps — flowillower aims to be the “bright flowers from dark willows” of your research journey.

🚀 Quickstart

Installation

Install latest from the GitHub repository:

$ pip install git+https://github.com/THU-CVML/flowillower.git

or from conda

$ conda install -c THU-CVML flowillower

or from pypi

$ pip install flowillower

Documentation

Documentation can be found hosted on this GitHub repository’s pages. Additionally you can find package manager specific guidelines on conda and pypi respectively.

Basic usage

Fill me in please! Don’t forget code examples:

from flowillower import init, log_metrics, log_model, push
import torch.nn as nn

# Initialize an experiment (creates a local Git repo)
init(project_name="my_cool_exp")

# Log your model architecture
model = nn.Sequential(nn.Linear(10, 32), nn.ReLU(), nn.Linear(32, 1))
log_model(model)

# Log some fake metrics
log_metrics(step=1, metrics={"loss": 0.234, "accuracy": 0.89})
log_metrics(step=2, metrics={"loss": 0.123, "accuracy": 0.91})

# Optional: push to a remote Git repo for team sharing or cloud viewing
push("https://huggingface.co/spaces/yourname/yourapp")

🙌 Contributing

We welcome contributions, ideas, and issues! See CONTRIBUTING.md or open a discussion to share your thoughts.

📜 License: Apache 2.0

Install flowillower in Development mode

# make sure flowillower package is installed in development mode
$ pip install -e .

# make changes under nbs/ directory
# ...

# compile to have changes apply to flowillower
$ nbdev_prepare

📂 Project Structure

🧠 Why the name “flowillower”?

It’s a blend of “willow” + “flower”, inspired by the Chinese idiom “柳暗花明又一村” (Liǔ àn huā míng yòu yī cūn) — light at the end of the tunnel.

Even deeper: flow + will + over → “flow will over” → Break free from rigid workflows, discover breakthroughs, and bloom.