Metadata-Version: 2.1
Name: flowillower
Version: 0.0.3
Summary: 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. 一个优雅、分布式的 AI 实验记录与可视化工具，致力于打破模型训练中的“黑盒”迷雾，让每一次 forward 都可见、可溯、可协作 —— 柳暗花明，终见曙光。
Home-page: https://github.com/THU-CVML/flowillower
Author: 叶璨铭 (Ye Canming)
Author-email: ycm24@mails.tsinghua.edu.cn
License: Apache Software License 2.0
Keywords: nbdev jupyter notebook python tensorboard wandb
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastcore
Requires-Dist: decorator
Requires-Dist: pydantic
Requires-Dist: mkinit
Requires-Dist: lazy_loader
Requires-Dist: loguru
Requires-Dist: bigmodelvis
Requires-Dist: richuru
Requires-Dist: optuna
Requires-Dist: GitPython
Requires-Dist: tomli-w
Requires-Dist: tomli
Provides-Extra: dev
Requires-Dist: nbdev; extra == "dev"
Requires-Dist: ipykernel; extra == "dev"

# 🌸 Flowillower 柳暗花明


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

![](logo.png)

> “山重水复疑无路，**柳暗花明**又一村。”——宋·陆游 《游山西村》
>
> “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](https://github.com/THU-CVML/flowillower):

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

or from [conda](https://anaconda.org/THU-CVML/flowillower)

``` sh
$ conda install -c THU-CVML flowillower
```

or from [pypi](https://pypi.org/project/flowillower/)

``` sh
$ pip install flowillower
```

### Documentation

Documentation can be found hosted on this GitHub
[repository](https://github.com/THU-CVML/flowillower)’s
[pages](https://THU-CVML.github.io/flowillower/). Additionally you can
find package manager specific guidelines on
[conda](https://anaconda.org/THU-CVML/flowillower) and
[pypi](https://pypi.org/project/flowillower/) respectively.

### Basic usage

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

``` python
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

``` sh
# 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.
