pylier

See the data moving through your Python pipeline.

Decorate the functions you already have. pylier infers the data handoffs and renders the pipeline that actually ran—no graph DSL or manual edge wiring.

Application Flow Direct argument, return, and exception handoffs between callers and callees. Use it to understand how the application executes.	Data Flow Producer-to-consumer value provenance. Links each returned value directly to every decorated consumer. Use it to understand where data goes and what moves through the pipeline.

Why pylier?

Try demos

• Document ingestion demo
• Fulfillment workflow demo

Quick start: document ingestion

The ingestion example is the fastest way to see pylier's value: a document branches into text and image paths, then concurrently embeds both branches before they converge at an indexing stage.

git clone https://github.com/theMladyPan/pylier.git
cd pylier
uv sync
uv run python -m examples.ingest html

Open pylier-ingest.html in a browser. It is a self-contained file—no server required. To watch the graph grow as work happens instead:

uv run python -m examples.ingest serve
# viewer: http://localhost:8765

The whole API in one flow

import pylier


@pylier.node
def load_document(path: str) -> dict: ...


@pylier.node(_tags=["document", "text"])
def extract_text(document: dict) -> list[str]: ...


@pylier.node
def embed(chunks: list[str]) -> list[dict]: ...


with pylier.trace("document-ingest"):
    document = load_document("report.pdf")
    vectors = embed(extract_text(document))

pylier.render("document-ingest.html")  # interactive, standalone HTML

Notes

For a plain-Python transformation or join that loses value provenance, preserve its sources explicitly:

vectors = pylier.derive(text_vectors + image_vectors, from_=[text_vectors, image_vectors])

derive() returns the original value unchanged; its only job is to keep the branch lineage visible in the next decorated stage. See docs/records/derive-lineage.md for its exact behavior.

Built for useful traces

• Signal over noise — use core, info, debug, and trace capture levels to control both captured nodes and metadata detail.
• Useful inspection — filter by node tags; click graph nodes and edges for payload type, size, preview, and optional captured values. Full values require PYLIER_CAPTURE_VALUES=1 and remain bounded FIFO by count and bytes. To make an intentionally shareable debug bundle, use pylier.render("debug.html", embed_payloads=True); the bundled data is readable by anyone with the HTML file, so the default static render remains metadata-only. The published examples use this opt-in only because their data is synthetic.
• Share or stream — pylier.render() creates a portable HTML file; pylier.serve() streams updates to a local viewer with SSE.
• Keep an audit trail — pylier.trace(..., sidecar="trace.jsonl") writes already-resolved events to JSONL for offline consumers.

Coexistence with other tracers

pylier has no OpenTelemetry, Logfire, FastAPI, or cloud dependency. It records its own local decorator traces and does not mutate ambient tracing context, so another tracer can instrument the same process independently.

Development

uv run pytest
uv run ruff format src tests examples
uv run ruff check src tests examples

Contributing

Issues and pull requests are welcome at theMladyPan/pylier.