tiergraph

Ordered tiers, declared relations, and an algebra over them

tiergraph holds parallel ordered sequences and the declared links between them as one immutable graph, checked when it is built. Every view — selection, traversal, containment, timing, folds — is computed from that one graph, so no view can disagree with the store.

The shape is the track view of an audio or video editor: rows of items, ordered within a row, aligned across rows, with links between rows. Aligned annotations over a signal have it; so do layered timelines and structured documents whose parts reference each other.

You have this problem already if:

• you can construct a state your own code treats as invalid;
• you keep a derived index beside the store and must remember to update both; or
• your serialized format breaks when you add a field.

The package requires Python 3.12 or later. A PyPI release is not yet available; install it from a source checkout:

git clone https://github.com/lenzo-ka/tiergraph.git
cd tiergraph
python -m pip install .
tiergraph --version

See an alignment

This caption graph links each word to its phones. Select cat, walk the declared alignment, and the answer is visible in the input:

from tiergraph import ItemSelector, Walk, WalkDirection, select
from tiergraph.build import document

builder = document("https://example.com/captions", prefix="caption")
words = builder.tier(
    "words",
    ("a", "cat", "sat"),
    item_type="word",
    membership="word-membership",
)
phones = builder.tier(
    "phones",
    ("AH", "K", "AE", "T", "S", "AE-2", "T-2"),
    item_type="phone",
    membership="phone-membership",
)
aligns = builder.link(
    "aligns",
    words,
    phones,
    ((0, 0), (1, 1), (1, 2), (1, 3), (2, 4), (2, 5), (2, 6)),
    acyclic=True,
)
graph = builder.build()

cat = select(graph, (ItemSelector(graph, words.ref(1)),))
reached = Walk(cat, aligns.name, WalkDirection.FORWARD).evaluate().nodes
assert [node.reference for node in reached.nodes] == [
    phones.ref(1),
    phones.ref(2),
    phones.ref(3),
]

The complete runnable example keeps the displayed phone labels separate from their durable ids and prints ['K', 'AE', 'T']; see examples/caption_alignment.py.

The model learned from Paul Hertz's Delta representation and the heterogeneous relation graphs (HRGs) of the Festival Speech Synthesis System. tiergraph keeps their emphasis on explicit tiered structure while defining a typed, immutable model and a versioned interchange format.

Downstream migration (ipakit). ipakit is migrating onto tiergraph: Form's timed representation — units, intervals, positional lookup, and DOT rendering — is authoritative on the tiergraph library via a containment projection, with graph-independent identity hashing. The remaining backend subsystem graphs (such as pronunciation/CMU, mora, pinyin, gesture, and rewrite) and their JSON wire are still on ipakit's embedded graph engine and are being migrated to the library; when that completes the embedded engine is removed.

What you can do with it

• Build a graph directly, or record an ordered edit stream as a Program and run it — see construction.
• Select and traverse the structure, including ordered containment — see selection and traversal.
• Fold a dependency graph with a semiring to measure or recognize it — see folding and recognize and act.
• Attach a clock profile and resolve physical timing — see timing.
• Serialize to canonical JSON or render Graphviz DOT — see serialization.
• Project segmentation graphs into deterministic span views for JSON, JSON Lines, text, HTML, or DOT — see span views.

Documentation

Start with the documentation map, then concepts for the data model and getting started for a worked walkthrough. The API reference covers every top-level export; the CLI reference is generated from the parser.

The companion tiergraph_dot package renders a graph as deterministic Graphviz DOT and ships in the same distribution:

import tiergraph_dot

dot = tiergraph_dot.dumps(graph)

Stability

tiergraph 0.1.x is alpha software. The public Python API may change before 1.0; where possible, changes will be additive, but compatibility is not yet promised. The JSON wire format, construction machine format, and span-view JSON format carry explicit version stamps so a reader can identify the format it receives. A format stamp identifies a contract; it does not imply that every version can read or migrate every older format.

After 1.0, the intended policy is to announce a deprecated public Python API in a minor release, retain it with a warning for at least one subsequent minor release, and remove it only in a later release. Security, correctness, or otherwise impractical compatibility constraints may require a faster change, which will be documented in the release. This is an intended post-1.0 policy, not a compatibility promise for the current alpha series.