lm-flow

English | 简体中文

A dataflow-graph engine: computation is described as a directed graph — nodes are kernels, and timestamped packets flow along the edges. The engine is written in Rust (scheduling, threads, queues, topology) and exposes a single stable C ABI; kernels can be written in C++ or Python.

  Host (Rust / C++ / Python) ── drives the graph
        │  C ABI  (lmflow/include/flow.h)
        ▼
  Engine (Rust): scheduler · executors · edge queues · topology · YAML
        │  C ABI  (callbacks)
        ▼
  Kernels: C++ (flow.hpp sugar)  /  Python

Layout

First-party source lives under lmflow/; build files and the vendored submodule sit at the repo root (which is also the Python project root, so wheels bundle everything they need).

lm-flow/
├── lmflow/                    All first-party source
│   ├── flow-core/             Engine — standalone Rust crate (lib + staticlib + cdylib)
│   │   ├── build.rs           Compiles ../cpp via `cc` and links it in
│   │   ├── Cargo.toml · Cargo.lock
│   │   ├── src/ · tests/ (ABI layout consistency) · examples/ (Rust hosts)
│   ├── include/               Public headers (authoritative C ABI + optional C++ sugar)
│   │   ├── flow.h             C ABI — the only stable interface
│   │   └── flow.hpp           C++ kernel sugar (header-only, not ABI)
│   ├── cpp/                    C++ kernels
│   │   ├── kernels/            Built-in sample kernels (11, one file per kernel + register.cc)
│   │   ├── abi_assert.cc       Compile-time checks of the cross-boundary struct layout
│   │   └── tests/              C++ test executables (flow.hpp unit test, CV conversion test)
│   ├── python/                pybind11 bindings (src/) + the lmflow package + CMakeLists
│   └── examples/              each example is self-contained: examples/<lang>/<name>/
│       ├── cpp/hello_world/    standalone C++ project (find_package or build-from-source)
│       ├── python/             hello_world/, realtime_pipeline/, opencv_pipeline/
│       └── {android,ios,harmonyos}/hello_world/   mobile integration examples
├── third_party/pybind11/      vendored git submodule (only used to build the Python wheel)
├── cmake/                     engine.cmake · install-sdk.cmake · find_package config
├── docs/design.md             Design document (authoritative)
├── CMakeLists.txt             Top-level build (drives cargo; C/C++ SDK + Python extension)
└── pyproject.toml             Python wheel (scikit-build-core → the same CMake)

Core concepts

Quick start

The engine is a standalone Rust crate under lmflow/flow-core (Rust developers work there directly):

cd lmflow/flow-core
cargo build                       # build the engine + C++ kernels
cargo test                        # unit tests + ABI layout consistency
cargo run --example hello_world   # two-stage passthrough pipeline, prints 0..9

Python:

pip install lm-lmflow               # prebuilt wheels (Linux manylinux / macOS)

import lmflow

lmflow.register_builtin_kernels()

@lmflow.kernel("Double")
class Double(lmflow.Kernel):
    def process(self, cc):
        cc.emit(0, cc.input(0).as_int() * 2)

g = lmflow.Graph.from_yaml("""
nodes:
  - { name: d, kernel: Double, input_ports: [in], output_ports: [out] }
input_ports: [in]
output_ports: [out]
""")
out = g.add_poller("out")
g.start()
g.input("in").send(21, ts=0)
print(out.next(timeout=5.0).as_int())   # 42
g.close_all_inputs(); g.wait_done(timeout=5.0)

Only prebuilt wheels are published — if no wheel matches your platform, pip install fails rather than compiling on your machine. To build locally instead, clone with submodules and build the wheel from source (needs a Rust toolchain + CMake):

git clone --recursive https://github.com/laomou/lm-flow
pip install ./lm-flow          # scikit-build-core drives CMake → cargo + pybind11

A kernel looks like this (C++, using the sugar layer):

class PassThroughKernel : public lmflow::Kernel {
 public:
  static void GetContract(lmflow::Contract& c) { c.InputSetAny(0); c.OutputSetAny(0); }
  lmflow::Status Process(lmflow::Context& cc) override {
    cc.Forward(0, 0);                      // zero-copy passthrough
    return lmflow::Status::Ok();
  }
};

A graph looks like this (YAML):

nodes:
  - name: "scale"
    kernel: "ScaleKernel"
    input_ports: ["in"]
    output_ports: ["out"]
    options: { factor: 3 }
input_ports: ["in"]
output_ports: ["out"]

See docs/design.md for the full design.

Native SDK (C / C++ / mobile)

C/C++ and mobile hosts don't use pip — they use the headers + library directly. Each tagged GitHub Release ships per-platform lmflow-<version>-<platform>.tar.gz (Linux x86_64/aarch64, macOS arm64, iOS arm64, Android arm64):

lmflow-v0.1.0-linux-x86_64/
├── include/   flow.h · flow.hpp · flow_cv.hpp · flow_platform_log.hpp
└── lib/       libflow_core.a (static, self-contained, preferred) · libflow_core.so (shared)

# Link the static library (recommended, especially for mobile embedding):
g++ -std=c++17 -Iinclude my_host.cc lib/libflow_core.a -lpthread -ldl -lm -o my_host

Or build one yourself locally:

cd lmflow/flow-core
cargo build --release          # → lmflow/flow-core/target/release/libflow_core.{a,so}
# the headers are the three under lmflow/include

Build & consume with CMake

CMake is the top-level build for the C++/native side; it lives at the repo root and drives cargo (which builds the Rust engine + C++ kernels into libflow_core), builds the C++ examples/tests, and installs a find_package config:

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
ctest --test-dir build                       # flow.hpp test; CV test if OpenCV is present
cmake --install build --prefix /opt/lmflow   # → headers + lib + lib/cmake/lmflow

Consumers then just:

find_package(lmflow REQUIRED)
target_link_libraries(my_app PRIVATE lmflow::flow_core)   # headers + libflow_core.a + system libs

Rust developers use cargo in lmflow/flow-core; Python users just pip install lm-lmflow (prebuilt wheels). The wheel is built by scikit-build-core driving this same root CMake (-DLMFLOW_BUILD_PYTHON=ON), so there is one build definition, not three.

The C ABI is the only stable interface (lmflow/include/flow.h); flow.hpp is the optional C++ kernel sugar, flow_cv.hpp is OpenCV interop, and flow_platform_log.hpp bridges engine logs to the platform logger (logcat / os_log / HiLog) in one call — lmflow::InstallPlatformLogSink().

Mobile integration examples: lmflow/examples/android/hello_world (JNI), lmflow/examples/ios/hello_world (Swift), lmflow/examples/harmonyos/hello_world (NAPI).