zigraf-ir 0.1.0__py3-none-any.whl

graph_ir/__init__.py

@@ -0,0 +1,35 @@
+"""graph-ir: the shared graph.yaml intermediate representation.
+
+Primitives -> concepts -> applications, with typed dependency edges, a structural
+validator, and graph transforms reused by every ZiNets back-end (spl3, mg, cba, gfc, solver).
+"""
+
+from .dag import CycleError, ancestors, topological_order
+from .io import dump_graph, load_graph, to_yaml
+from .render import render, to_dot, to_mermaid
+from .schema import EdgeType, Graph, Layer, Node
+from .transforms import GraphDiff, diff_graphs, slice_to
+from .validator import Issue, validate
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CycleError",
+    "EdgeType",
+    "Graph",
+    "GraphDiff",
+    "Issue",
+    "Layer",
+    "Node",
+    "ancestors",
+    "diff_graphs",
+    "dump_graph",
+    "load_graph",
+    "render",
+    "slice_to",
+    "to_dot",
+    "to_mermaid",
+    "to_yaml",
+    "topological_order",
+    "validate",
+]

graph_ir/cli.py

@@ -0,0 +1,151 @@
+"""`gir` command-line tool: validate, diff, slice, render, prettify, and schema for graph.yaml files.
+
+Exit codes: 0 success, 1 validation errors, differences found, or a file needing prettify,
+2 usage, load, or render failure.
+"""
+
+from __future__ import annotations
+
+import argparse
+import difflib
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from . import __version__
+from .io import dump_graph, load_graph, to_yaml
+from .prettify import prettify_file
+from .render import BINARY_FORMATS, FORMATS, render
+from .schema import json_schema_text
+from .transforms import diff_graphs, slice_to
+from .validator import validate
+
+
+def _cmd_validate(args: argparse.Namespace) -> int:
+    graph = load_graph(args.file, resolve_imports=not args.no_imports)
+    issues = validate(graph)
+    for issue in issues:
+        print(f"{args.file}: {issue}")
+    if not issues:
+        print(f"{args.file}: ok ({len(graph.nodes())} nodes)")
+    return 1 if any(issue.severity == "error" for issue in issues) else 0
+
+
+def _cmd_diff(args: argparse.Namespace) -> int:
+    result = diff_graphs(load_graph(args.old), load_graph(args.new))
+    if result.is_empty:
+        print("no differences")
+        return 0
+    for node_id in result.added:
+        print(f"+ {node_id}")
+    for node_id in result.removed:
+        print(f"- {node_id}")
+    for node_id, delta in result.changed.items():
+        for name, (old, new) in delta.items():
+            print(f"~ {node_id}.{name}: {old!r} -> {new!r}")
+    return 1
+
+
+def _cmd_slice(args: argparse.Namespace) -> int:
+    graph = slice_to(load_graph(args.file), args.target)
+    if args.output:
+        dump_graph(graph, args.output)
+    else:
+        sys.stdout.write(to_yaml(graph))
+    return 0
+
+
+def _cmd_render(args: argparse.Namespace) -> int:
+    if args.format in BINARY_FORMATS and not args.output:
+        raise ValueError(f"--format {args.format} is binary; pass -o FILE")
+    graph = load_graph(args.file, resolve_imports=not args.no_imports)
+    data = render(graph, args.format)
+    if args.output:
+        Path(args.output).write_bytes(data)
+    else:
+        sys.stdout.buffer.write(data)
+    return 0
+
+
+def _cmd_prettify(args: argparse.Namespace) -> int:
+    result = prettify_file(args.file)
+    if not result.changed:
+        print(f"{args.file}: already formatted")
+        return 0
+    if args.write:
+        if result.has_comments:
+            raise ValueError(f"{args.file} has comments; prettify would drop them, so it was not rewritten")
+        Path(args.file).write_text(result.formatted, encoding="utf-8")
+        print(f"{args.file}: rewritten")
+        return 0
+    if result.has_comments:
+        print(f"note: {args.file} has comments; --write would drop them", file=sys.stderr)
+    sys.stdout.writelines(
+        difflib.unified_diff(
+            result.original.splitlines(keepends=True),
+            result.formatted.splitlines(keepends=True),
+            fromfile=args.file,
+            tofile=f"{args.file} (prettified)",
+        )
+    )
+    return 1
+
+
+def _cmd_schema(args: argparse.Namespace) -> int:
+    text = json_schema_text()
+    if args.output:
+        Path(args.output).write_text(text, encoding="utf-8")
+    else:
+        sys.stdout.write(text)
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="gir", description="graph.yaml intermediate representation tools")
+    parser.add_argument("--version", action="version", version=f"gir {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_diff = sub.add_parser("diff", help="show node-level differences between two graphs")
+    p_diff.add_argument("old")
+    p_diff.add_argument("new")
+    p_diff.set_defaults(handler=_cmd_diff)
+
+    p_prettify = sub.add_parser("prettify", help="show or apply the canonical formatting of a graph.yaml")
+    p_prettify.add_argument("file")
+    p_prettify.add_argument("--write", action="store_true", help="rewrite the file in place instead of printing a diff")
+    p_prettify.set_defaults(handler=_cmd_prettify)
+
+    p_render = sub.add_parser("render", help="visualize a graph as svg, png, pdf, or mermaid")
+    p_render.add_argument("file")
+    p_render.add_argument("--format", choices=FORMATS, default="svg", help="output format (default: svg)")
+    p_render.add_argument("-o", "--output", help="write to this file instead of stdout")
+    p_render.add_argument("--no-imports", action="store_true", help="do not resolve imports")
+    p_render.set_defaults(handler=_cmd_render)
+
+    p_schema = sub.add_parser("schema", help="print the JSON Schema for graph.yaml")
+    p_schema.add_argument("-o", "--output", help="write to this file instead of stdout")
+    p_schema.set_defaults(handler=_cmd_schema)
+
+    p_slice = sub.add_parser("slice", help="extract a target node and its prerequisites")
+    p_slice.add_argument("file")
+    p_slice.add_argument("target")
+    p_slice.add_argument("-o", "--output", help="write to this file instead of stdout")
+    p_slice.set_defaults(handler=_cmd_slice)
+
+    p_validate = sub.add_parser("validate", help="check a graph.yaml for structural errors")
+    p_validate.add_argument("file")
+    p_validate.add_argument("--no-imports", action="store_true", help="do not resolve imports")
+    p_validate.set_defaults(handler=_cmd_validate)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+    try:
+        return args.handler(args)
+    except KeyError as exc:
+        print(f"gir: error: {exc.args[0]}", file=sys.stderr)
+        return 2
+    except (OSError, ValueError, RuntimeError) as exc:
+        print(f"gir: error: {exc}", file=sys.stderr)
+        return 2

graph_ir/dag.py

@@ -0,0 +1,54 @@
+"""DAG algorithms over an id -> dependency-ids mapping, built on networkx.
+
+Kept free of node types so any domain back-end can reuse them.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+
+import networkx as nx
+
+
+class CycleError(ValueError):
+    """Raised when a dependency cycle exists. `members` lists nodes stuck in or behind it."""
+
+    def __init__(self, members: list[str]):
+        self.members = members
+        super().__init__(f"dependency cycle among: {', '.join(members)}")
+
+
+def _dependency_graph(deps: Mapping[str, Iterable[str]]) -> nx.DiGraph:
+    """Edges run dependency -> dependent, so a topological order lists dependencies first."""
+    graph = nx.DiGraph()
+    graph.add_nodes_from(deps)
+    for node, parents in deps.items():
+        graph.add_edges_from((parent, node) for parent in parents)
+    return graph
+
+
+def _cycle_members(graph: nx.DiGraph) -> list[str]:
+    """Nodes that sit on a cycle: members of a multi-node strongly connected component, or self-loops."""
+    members = {node for scc in nx.strongly_connected_components(graph) if len(scc) > 1 for node in scc}
+    members |= {node for node in graph if graph.has_edge(node, node)}
+    return sorted(members)
+
+
+def topological_order(deps: Mapping[str, Iterable[str]]) -> list[str]:
+    """Return every id with its dependencies before it. Ties break alphabetically.
+
+    Every dependency id must itself be a key of `deps`; callers filter unknown ids first.
+    Raises CycleError when the mapping is not a DAG.
+    """
+    graph = _dependency_graph(deps)
+    try:
+        return list(nx.lexicographical_topological_sort(graph))
+    except nx.NetworkXUnfeasible:
+        raise CycleError(_cycle_members(graph)) from None
+
+
+def ancestors(deps: Mapping[str, Iterable[str]], target: str) -> set[str]:
+    """All ids `target` transitively depends on (excluding `target` itself)."""
+    if target not in deps:
+        raise KeyError(target)
+    return set(nx.ancestors(_dependency_graph(deps), target))

graph_ir/io.py

@@ -0,0 +1,88 @@
+"""Load, resolve, and dump graph.yaml files."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+from pydantic import ValidationError
+
+from .schema import Graph, Layer
+
+
+def load_graph(path: str | Path, resolve_imports: bool = True) -> Graph:
+    """Load a graph.yaml. With `resolve_imports`, merge every file listed under `imports:`.
+
+    Import paths are relative to the importing file. Imported nodes keep their ids (no
+    namespacing); a duplicate id across files is an error. The returned graph has no `imports`.
+    This does not run `validate`; call that separately for structural checks.
+    """
+    source = Path(path)
+    graph = _read(source)
+    if resolve_imports:
+        graph = _resolve(graph, source, stack=())
+    return graph
+
+
+class _IndentedDumper(yaml.SafeDumper):
+    """Indents list items under their parent key ("  - id: a") instead of PyYAML's flush style."""
+
+    def increase_indent(self, flow: bool = False, indentless: bool = False) -> None:
+        return super().increase_indent(flow, False)
+
+
+def to_yaml(graph: Graph) -> str:
+    data = graph.model_dump(mode="json", exclude_defaults=True)
+    data = {"version": graph.version, **data}  # always written, first, even when default
+    return yaml.dump(data, Dumper=_IndentedDumper, sort_keys=False, allow_unicode=True)
+
+
+def dump_graph(graph: Graph, path: str | Path) -> None:
+    Path(path).write_text(to_yaml(graph), encoding="utf-8")
+
+
+SUPPORTED_VERSIONS = ("1.0",)
+
+
+def _read(path: Path) -> Graph:
+    data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    if not isinstance(data, dict):
+        raise ValueError(f"{path}: top level must be a mapping")
+    if str(data.get("version", "1.0")) not in SUPPORTED_VERSIONS:
+        raise ValueError(f"{path}: unsupported graph version {data['version']!r}; supported: {', '.join(SUPPORTED_VERSIONS)}")
+    try:
+        return Graph.model_validate(data)
+    except ValidationError as exc:
+        raise ValueError(f"{path}: {exc}") from exc
+
+
+def _resolve(graph: Graph, source: Path, stack: tuple[Path, ...]) -> Graph:
+    key = source.resolve()
+    if key in stack:
+        chain = " -> ".join(str(p) for p in (*stack, key))
+        raise ValueError(f"import cycle: {chain}")
+
+    merged: dict[Layer, list] = {layer: [] for layer in Layer}
+    origin: dict[str, Path] = {}
+
+    def add(layer: Layer, node, where: Path) -> None:
+        if node.id in origin:
+            raise ValueError(f"duplicate node id {node.id!r}: defined in {origin[node.id]} and {where}")
+        origin[node.id] = where
+        merged[layer].append(node)
+
+    base = source.parent
+    for imp in graph.imports:
+        child_path = base / imp
+        child = _resolve(_read(child_path), child_path, stack=(*stack, key))
+        for layer, node in child.layered_nodes():
+            add(layer, node, child_path)
+    for layer, node in graph.layered_nodes():
+        add(layer, node, source)
+
+    return Graph(
+        version=graph.version,
+        primitives=merged[Layer.PRIMITIVES],
+        concepts=merged[Layer.CONCEPTS],
+        applications=merged[Layer.APPLICATIONS],
+    )

graph_ir/prettify.py

@@ -0,0 +1,43 @@
+"""Canonical formatting for graph.yaml files (`gir prettify`).
+
+The canonical form is what `to_yaml` writes: `version` first, layers in order, keys in model
+field order, and defaults omitted. Formatting works on one file only and never resolves imports,
+so imported nodes are not copied into the file being formatted.
+
+YAML comments are not preserved, because PyYAML does not expose them. `has_comments` lets the
+CLI refuse to rewrite a file that would lose them.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from .io import load_graph, to_yaml
+
+_INLINE_COMMENT = re.compile(r"(^|\s)#")
+
+
+@dataclass(frozen=True)
+class Prettified:
+    original: str
+    formatted: str
+    has_comments: bool
+
+    @property
+    def changed(self) -> bool:
+        return self.original != self.formatted
+
+
+def has_comments(text: str) -> bool:
+    """True if any line looks like it carries a YAML comment. Conservative: a `#` inside a quoted
+    string also counts, which only makes the check refuse more often, never less."""
+    return any(_INLINE_COMMENT.search(line) for line in text.splitlines())
+
+
+def prettify_file(path: str | Path) -> Prettified:
+    source = Path(path)
+    original = source.read_text(encoding="utf-8")
+    graph = load_graph(source, resolve_imports=False)
+    return Prettified(original=original, formatted=to_yaml(graph), has_comments=has_comments(original))

graph_ir/render.py

@@ -0,0 +1,116 @@
+"""Visualization: graph.yaml -> Graphviz DOT, Mermaid, and (via `dot`) SVG / PNG / PDF.
+
+Mermaid is pure text and needs nothing installed. SVG, PNG, and PDF shell out to the
+Graphviz `dot` binary, which must be on PATH.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+
+from .schema import EdgeType, Graph, Layer
+
+FORMATS = ("svg", "png", "pdf", "mermaid")
+BINARY_FORMATS = ("png", "pdf")
+_GRAPHVIZ_FORMATS = ("svg", "png", "pdf")
+
+_DOT_SHAPE = {
+    Layer.PRIMITIVES: "ellipse",
+    Layer.CONCEPTS: "box",
+    Layer.APPLICATIONS: "doubleoctagon",
+}
+
+
+def _dot_quote(text: str) -> str:
+    return '"' + text.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def _mermaid_text(text: str) -> str:
+    return text.replace('"', "#quot;")
+
+
+def to_dot(graph: Graph) -> str:
+    """Graphviz DOT source: one cluster per layer, edges point from dependency to dependent."""
+    lines = [
+        "digraph graph_ir {",
+        "  rankdir=LR;",
+        '  node [fontname="Helvetica"];',
+    ]
+    for layer in Layer:
+        nodes = getattr(graph, layer.value)
+        if not nodes:
+            continue
+        lines.append(f'  subgraph "cluster_{layer.value}" {{')
+        lines.append(f'    label={_dot_quote(layer.value)}; style=rounded; color=gray;')
+        for node in nodes:
+            label = node.label or node.id
+            lines.append(f"    {_dot_quote(node.id)} [label={_dot_quote(label)} shape={_DOT_SHAPE[layer]}];")
+        lines.append("  }")
+
+    for node in graph.nodes():
+        for dep in node.deps:
+            kind = node.edge_types.get(dep)
+            attrs = f" [label={_dot_quote(kind.value)}]" if kind and kind is not EdgeType.DEPENDS_ON else ""
+            lines.append(f"  {_dot_quote(dep)} -> {_dot_quote(node.id)}{attrs};")
+    lines.append("}")
+    return "\n".join(lines) + "\n"
+
+
+_MERMAID_BRACKETS = {
+    Layer.PRIMITIVES: ("([", "])"),
+    Layer.CONCEPTS: ("[", "]"),
+    Layer.APPLICATIONS: ("{{", "}}"),
+}
+
+
+def to_mermaid(graph: Graph) -> str:
+    """Mermaid flowchart (LR), one subgraph per layer. Renders in GitHub and most Markdown viewers."""
+    names: dict[str, str] = {}
+    for index, (_, node) in enumerate(graph.layered_nodes()):
+        names.setdefault(node.id, f"n{index}")
+
+    lines = ["flowchart LR"]
+    for layer in Layer:
+        nodes = getattr(graph, layer.value)
+        if not nodes:
+            continue
+        lines.append(f"  subgraph {layer.value}")
+        open_, close = _MERMAID_BRACKETS[layer]
+        for node in nodes:
+            label = _mermaid_text(node.label or node.id)
+            lines.append(f'    {names[node.id]}{open_}"{label}"{close}')
+        lines.append("  end")
+
+    for node in graph.nodes():
+        for dep in node.deps:
+            if dep not in names:  # dangling reference: declare it so the edge still draws
+                names[dep] = f"n{len(names)}"
+                lines.append(f'  {names[dep]}["{_mermaid_text(dep)}"]')
+            kind = node.edge_types.get(dep)
+            arrow = f"-->|{kind.value}|" if kind and kind is not EdgeType.DEPENDS_ON else "-->"
+            lines.append(f"  {names[dep]} {arrow} {names[node.id]}")
+    return "\n".join(lines) + "\n"
+
+
+def render(graph: Graph, fmt: str) -> bytes:
+    """Render `graph` in `fmt` and return the raw bytes (UTF-8 text for svg and mermaid)."""
+    if fmt == "mermaid":
+        return to_mermaid(graph).encode("utf-8")
+    if fmt not in _GRAPHVIZ_FORMATS:
+        raise ValueError(f"unknown format {fmt!r}; choose from {', '.join(FORMATS)}")
+    return _run_dot(to_dot(graph), fmt)
+
+
+def _run_dot(source: str, fmt: str) -> bytes:
+    if shutil.which("dot") is None:
+        raise RuntimeError("Graphviz 'dot' not found on PATH; install graphviz (e.g. apt install graphviz)")
+    proc = subprocess.run(
+        ["dot", f"-T{fmt}"],
+        input=source.encode("utf-8"),
+        capture_output=True,
+        check=False,
+    )
+    if proc.returncode != 0:
+        raise RuntimeError(f"dot failed: {proc.stderr.decode('utf-8', 'replace').strip()}")
+    return proc.stdout

graph_ir/schema.py

@@ -0,0 +1,81 @@
+"""Pydantic models for graph.yaml: a three-layer DAG (primitives -> concepts -> applications)."""
+
+from __future__ import annotations
+
+import json
+from enum import Enum
+from typing import Any, Iterator
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class Layer(str, Enum):
+    """Layer a node lives in. Values are the top-level YAML keys."""
+
+    PRIMITIVES = "primitives"
+    CONCEPTS = "concepts"
+    APPLICATIONS = "applications"
+
+
+class EdgeType(str, Enum):
+    """Optional semantics for a dependency edge. Unannotated edges are DEPENDS_ON."""
+
+    DEPENDS_ON = "depends_on"
+    DATA_FLOW = "data_flow"
+    PREREQUISITE = "prerequisite"
+    CONSTRAINT = "constraint"
+    INHERITANCE = "inheritance"
+
+
+class Node(BaseModel):
+    """A graph node. `deps` lists the ids it depends on, i.e. its incoming edges."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    id: str = Field(min_length=1)
+    label: str | None = None
+    deps: list[str] = Field(default_factory=list)
+    edge_types: dict[str, EdgeType] = Field(default_factory=dict)  # dep id -> edge type
+    meta: dict[str, Any] = Field(default_factory=dict)  # domain payload, opaque to the core
+
+    @model_validator(mode="after")
+    def _typed_edges_must_be_deps(self) -> Node:
+        stray = sorted(set(self.edge_types) - set(self.deps))
+        if stray:
+            raise ValueError(f"edge_types given for non-dependencies: {stray}")
+        return self
+
+
+class Graph(BaseModel):
+    """A whole graph.yaml document. Unknown top-level keys are rejected to catch typos."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    version: str = "1.0"
+    imports: list[str] = Field(default_factory=list)  # relative paths, resolved by io.load_graph
+    primitives: list[Node] = Field(default_factory=list)
+    concepts: list[Node] = Field(default_factory=list)
+    applications: list[Node] = Field(default_factory=list)
+
+    def layered_nodes(self) -> Iterator[tuple[Layer, Node]]:
+        """Yield (layer, node) pairs in layer order, then file order."""
+        for layer in Layer:
+            for node in getattr(self, layer.value):
+                yield layer, node
+
+    def nodes(self) -> list[Node]:
+        return [node for _, node in self.layered_nodes()]
+
+    def index(self) -> dict[str, tuple[Layer, Node]]:
+        """Map node id -> (layer, node). Raises ValueError on duplicate ids."""
+        index: dict[str, tuple[Layer, Node]] = {}
+        for layer, node in self.layered_nodes():
+            if node.id in index:
+                raise ValueError(f"duplicate node id: {node.id!r}")
+            index[node.id] = (layer, node)
+        return index
+
+
+def json_schema_text() -> str:
+    """JSON Schema (draft 2020-12, as generated by Pydantic) for a graph.yaml document."""
+    return json.dumps(Graph.model_json_schema(), indent=2, ensure_ascii=False) + "\n"

graph_ir/transforms/__init__.py

@@ -0,0 +1,6 @@
+"""Graph-level operations shared by all back-ends."""
+
+from .diff import GraphDiff, diff_graphs
+from .slice import slice_to
+
+__all__ = ["GraphDiff", "diff_graphs", "slice_to"]

graph_ir/transforms/diff.py

@@ -0,0 +1,55 @@
+"""Semantic diff between two graphs, matched by node id."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from ..schema import Graph
+
+_FIELDS = ("layer", "label", "deps", "edge_types", "meta")
+
+
+@dataclass(frozen=True)
+class GraphDiff:
+    added: list[str] = field(default_factory=list)
+    removed: list[str] = field(default_factory=list)
+    # node id -> {field name: (old value, new value)}
+    changed: dict[str, dict[str, tuple[Any, Any]]] = field(default_factory=dict)
+
+    @property
+    def is_empty(self) -> bool:
+        return not (self.added or self.removed or self.changed)
+
+
+def diff_graphs(old: Graph, new: Graph) -> GraphDiff:
+    """Compare two graphs node by node. Dependency order is ignored; only the set matters."""
+    before = _describe(old)
+    after = _describe(new)
+    changed: dict[str, dict[str, tuple[Any, Any]]] = {}
+    for node_id in sorted(before.keys() & after.keys()):
+        delta = {
+            name: (before[node_id][name], after[node_id][name])
+            for name in _FIELDS
+            if before[node_id][name] != after[node_id][name]
+        }
+        if delta:
+            changed[node_id] = delta
+    return GraphDiff(
+        added=sorted(after.keys() - before.keys()),
+        removed=sorted(before.keys() - after.keys()),
+        changed=changed,
+    )
+
+
+def _describe(graph: Graph) -> dict[str, dict[str, Any]]:
+    return {
+        node_id: {
+            "layer": layer.value,
+            "label": node.label,
+            "deps": sorted(node.deps),
+            "edge_types": {dep: kind.value for dep, kind in node.edge_types.items()},
+            "meta": node.meta,
+        }
+        for node_id, (layer, node) in graph.index().items()
+    }

graph_ir/transforms/slice.py

@@ -0,0 +1,26 @@
+"""Subgraph extraction."""
+
+from __future__ import annotations
+
+from ..dag import ancestors
+from ..schema import Graph, Layer
+
+
+def slice_to(graph: Graph, target: str) -> Graph:
+    """Return the subgraph made of `target` and everything it transitively depends on.
+
+    For a concept-graph this is the prerequisite closure of the target. Raises KeyError
+    if `target` is not a node id.
+    """
+    index = graph.index()
+    if target not in index:
+        raise KeyError(f"unknown node: {target!r}")
+    deps = {node_id: node.deps for node_id, (_, node) in index.items()}
+    keep = ancestors(deps, target) | {target}
+    return Graph(
+        version=graph.version,
+        **{
+            layer.value: [node for node in getattr(graph, layer.value) if node.id in keep]
+            for layer in Layer
+        },
+    )

graph_ir/validator.py

@@ -0,0 +1,69 @@
+"""Structural checks that apply to any domain's graph.yaml, with no domain logic."""
+
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass
+from typing import Literal
+
+from .dag import CycleError, topological_order
+from .schema import Graph, Layer
+
+Severity = Literal["error", "warning"]
+
+
+@dataclass(frozen=True)
+class Issue:
+    severity: Severity
+    code: str
+    message: str
+    node: str | None = None
+
+    def __str__(self) -> str:
+        where = f" [{self.node}]" if self.node else ""
+        return f"{self.severity}: {self.code}{where}: {self.message}"
+
+
+def validate(graph: Graph) -> list[Issue]:
+    """Return all structural problems. Errors make a graph invalid; warnings are advisory.
+
+    Errors: duplicate_id, unknown_dep, primitive_has_deps, layer_violation, cycle.
+    Warnings: orphan (a node with no dependencies and no dependents).
+    """
+    issues: list[Issue] = []
+    nodes = graph.nodes()
+
+    for node_id, count in Counter(node.id for node in nodes).items():
+        if count > 1:
+            issues.append(Issue("error", "duplicate_id", f"id appears {count} times", node_id))
+
+    layer_of: dict[str, Layer] = {}
+    for layer, node in graph.layered_nodes():
+        layer_of.setdefault(node.id, layer)
+
+    for layer, node in graph.layered_nodes():
+        if layer is Layer.PRIMITIVES and node.deps:
+            issues.append(
+                Issue("error", "primitive_has_deps", f"primitives are leaves but depend on {node.deps}", node.id)
+            )
+        for dep in node.deps:
+            if dep not in layer_of:
+                issues.append(Issue("error", "unknown_dep", f"depends on undefined id {dep!r}", node.id))
+            elif layer_of[dep] is Layer.APPLICATIONS:
+                issues.append(
+                    Issue("error", "layer_violation", f"depends on application {dep!r}; applications are capstones", node.id)
+                )
+
+    known_deps = {node.id: [dep for dep in node.deps if dep in layer_of] for node in nodes}
+    try:
+        topological_order(known_deps)
+    except CycleError as exc:
+        issues.append(Issue("error", "cycle", str(exc)))
+
+    referenced = {dep for node in nodes for dep in node.deps}
+    if len(nodes) > 1:
+        for node in nodes:
+            if not node.deps and node.id not in referenced:
+                issues.append(Issue("warning", "orphan", "not connected to any other node", node.id))
+
+    return issues

zigraf_ir-0.1.0.dist-info/METADATA

@@ -0,0 +1,349 @@
+Metadata-Version: 2.5
+Name: zigraf-ir
+Version: 0.1.0
+Summary: graph.yaml intermediate representation: schema, validator and graph transforms shared across the ZiNets ecosystem
+Project-URL: Homepage, https://github.com/digital-duck/graph-ir
+Project-URL: Repository, https://github.com/digital-duck/graph-ir
+Project-URL: Bug Tracker, https://github.com/digital-duck/graph-ir/issues
+Author-email: "Gong, Wen" <lucywang1049@gmail.com>
+License:                                  Apache License
+                                   Version 2.0, January 2004
+                                http://www.apache.org/licenses/
+        
+           TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+        
+           1. Definitions.
+        
+              "License" shall mean the terms and conditions for use, reproduction,
+              and distribution as defined by Sections 1 through 9 of this document.
+        
+              "Licensor" shall mean the copyright owner or entity authorized by
+              the copyright owner that is granting the License.
+        
+              "Legal Entity" shall mean the union of the acting entity and all
+              other entities that control, are controlled by, or are under common
+              control with that entity. For the purposes of this definition,
+              "control" means (i) the power, direct or indirect, to cause the
+              direction or management of such entity, whether by contract or
+              otherwise, or (ii) ownership of fifty percent (50%) or more of the
+              outstanding shares, or (iii) beneficial ownership of such entity.
+        
+              "You" (or "Your") shall mean an individual or Legal Entity
+              exercising permissions granted by this License.
+        
+              "Source" form shall mean the preferred form for making modifications,
+              including but not limited to software source code, documentation
+              source, and configuration files.
+        
+              "Object" form shall mean any form resulting from mechanical
+              transformation or translation of a Source form, including but
+              not limited to compiled object code, generated documentation,
+              and conversions to other media types.
+        
+              "Work" shall mean the work of authorship, whether in Source or
+              Object form, made available under the License, as indicated by a
+              copyright notice that is included in or attached to the work
+              (an example is provided in the Appendix below).
+        
+              "Derivative Works" shall mean any work, whether in Source or Object
+              form, that is based on (or derived from) the Work and for which the
+              editorial revisions, annotations, elaborations, or other modifications
+              represent, as a whole, an original work of authorship. For the purposes
+              of this License, Derivative Works shall not include works that remain
+              separable from, or merely link (or bind by name) to the interfaces of,
+              the Work and Derivative Works thereof.
+        
+              "Contribution" shall mean any work of authorship, including
+              the original version of the Work and any modifications or additions
+              to that Work or Derivative Works thereof, that is intentionally
+              submitted to Licensor for inclusion in the Work by the copyright owner
+              or by an individual or Legal Entity authorized to submit on behalf of
+              the copyright owner. For the purposes of this definition, "submitted"
+              means any form of electronic, verbal, or written communication sent
+              to the Licensor or its representatives, including but not limited to
+              communication on electronic mailing lists, source code control systems,
+              and issue tracking systems that are managed by, or on behalf of, the
+              Licensor for the purpose of discussing and improving the Work, but
+              excluding communication that is conspicuously marked or otherwise
+              designated in writing by the copyright owner as "Not a Contribution."
+        
+              "Contributor" shall mean Licensor and any individual or Legal Entity
+              on behalf of whom a Contribution has been received by Licensor and
+              subsequently incorporated within the Work.
+        
+           2. Grant of Copyright License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              copyright license to reproduce, prepare Derivative Works of,
+              publicly display, publicly perform, sublicense, and distribute the
+              Work and such Derivative Works in Source or Object form.
+        
+           3. Grant of Patent License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              (except as stated in this section) patent license to make, have made,
+              use, offer to sell, sell, import, and otherwise transfer the Work,
+              where such license applies only to those patent claims licensable
+              by such Contributor that are necessarily infringed by their
+              Contribution(s) alone or by combination of their Contribution(s)
+              with the Work to which such Contribution(s) was submitted. If You
+              institute patent litigation against any entity (including a
+              cross-claim or counterclaim in a lawsuit) alleging that the Work
+              or a Contribution incorporated within the Work constitutes direct
+              or contributory patent infringement, then any patent licenses
+              granted to You under this License for that Work shall terminate
+              as of the date such litigation is filed.
+        
+           4. Redistribution. You may reproduce and distribute copies of the
+              Work or Derivative Works thereof in any medium, with or without
+              modifications, and in Source or Object form, provided that You
+              meet the following conditions:
+        
+              (a) You must give any other recipients of the Work or
+                  Derivative Works a copy of this License; and
+        
+              (b) You must cause any modified files to carry prominent notices
+                  stating that You changed the files; and
+        
+              (c) You must retain, in the Source form of any Derivative Works
+                  that You distribute, all copyright, patent, trademark, and
+                  attribution notices from the Source form of the Work,
+                  excluding those notices that do not pertain to any part of
+                  the Derivative Works; and
+        
+              (d) If the Work includes a "NOTICE" text file as part of its
+                  distribution, then any Derivative Works that You distribute must
+                  include a readable copy of the attribution notices contained
+                  within such NOTICE file, excluding those notices that do not
+                  pertain to any part of the Derivative Works, in at least one
+                  of the following places: within a NOTICE text file distributed
+                  as part of the Derivative Works; within the Source form or
+                  documentation, if provided along with the Derivative Works; or,
+                  within a display generated by the Derivative Works, if and
+                  wherever such third-party notices normally appear. The contents
+                  of the NOTICE file are for informational purposes only and
+                  do not modify the License. You may add Your own attribution
+                  notices within Derivative Works that You distribute, alongside
+                  or as an addendum to the NOTICE text from the Work, provided
+                  that such additional attribution notices cannot be construed
+                  as modifying the License.
+        
+              You may add Your own copyright statement to Your modifications and
+              may provide additional or different license terms and conditions
+              for use, reproduction, or distribution of Your modifications, or
+              for any such Derivative Works as a whole, provided Your use,
+              reproduction, and distribution of the Work otherwise complies with
+              the conditions stated in this License.
+        
+           5. Submission of Contributions. Unless You explicitly state otherwise,
+              any Contribution intentionally submitted for inclusion in the Work
+              by You to the Licensor shall be under the terms and conditions of
+              this License, without any additional terms or conditions.
+              Notwithstanding the above, nothing herein shall supersede or modify
+              the terms of any separate license agreement you may have executed
+              with Licensor regarding such Contributions.
+        
+           6. Trademarks. This License does not grant permission to use the trade
+              names, trademarks, service marks, or product names of the Licensor,
+              except as required for reasonable and customary use in describing the
+              origin of the Work and reproducing the content of the NOTICE file.
+        
+           7. Disclaimer of Warranty. Unless required by applicable law or
+              agreed to in writing, Licensor provides the Work (and each
+              Contributor provides its Contributions) on an "AS IS" BASIS,
+              WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+              implied, including, without limitation, any warranties or conditions
+              of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+              PARTICULAR PURPOSE. You are solely responsible for determining the
+              appropriateness of using or redistributing the Work and assume any
+              risks associated with Your exercise of permissions under this License.
+        
+           8. Limitation of Liability. In no event and under no legal theory,
+              whether in tort (including negligence), contract, or otherwise,
+              unless required by applicable law (such as deliberate and grossly
+              negligent acts) or agreed to in writing, shall any Contributor be
+              liable to You for damages, including any direct, indirect, special,
+              incidental, or consequential damages of any character arising as a
+              result of this License or out of the use or inability to use the
+              Work (including but not limited to damages for loss of goodwill,
+              work stoppage, computer failure or malfunction, or any and all
+              other commercial damages or losses), even if such Contributor
+              has been advised of the possibility of such damages.
+        
+           9. Accepting Warranty or Additional Liability. While redistributing
+              the Work or Derivative Works thereof, You may choose to offer,
+              and charge a fee for, acceptance of support, warranty, indemnity,
+              or other liability obligations and/or rights consistent with this
+              License. However, in accepting such obligations, You may act only
+              on Your own behalf and on Your sole responsibility, not on behalf
+              of any other Contributor, and only if You agree to indemnify,
+              defend, and hold each Contributor harmless for any liability
+              incurred by, or claims asserted against, such Contributor by reason
+              of your accepting any such warranty or additional liability.
+        
+           END OF TERMS AND CONDITIONS
+        
+           APPENDIX: How to apply the Apache License to your work.
+        
+              To apply the Apache License to your work, attach the following
+              boilerplate notice, with the fields enclosed by brackets "[]"
+              replaced with your own identifying information. (Don't include
+              the brackets!)  The text should be enclosed in the appropriate
+              comment syntax for the file format. We also recommend that a
+              file or class name and description of purpose be included on the
+              same "printed page" as the copyright notice for easier
+              identification within third-party archives.
+        
+           Copyright [yyyy] [name of copyright owner]
+        
+           Licensed under the Apache License, Version 2.0 (the "License");
+           you may not use this file except in compliance with the License.
+           You may obtain a copy of the License at
+        
+               http://www.apache.org/licenses/LICENSE-2.0
+        
+           Unless required by applicable law or agreed to in writing, software
+           distributed under the License is distributed on an "AS IS" BASIS,
+           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+           See the License for the specific language governing permissions and
+           limitations under the License.
+License-File: LICENSE
+Keywords: dag,graph,intermediate-representation,ir,knowledge-graph,validation,yaml
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: networkx>=3.2
+Requires-Dist: pydantic>=2.5
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# graph-ir
+
+Graph IR core package shared across SPL, ConceptBook, Graph-Code, Momagrid, and Solver domains.
+
+`graph.yaml` is the common intermediate representation of the ZiNets ecosystem, the way LLVM IR
+is for compilers: front-ends emit it, back-ends consume it, and the shared validator and
+transforms live here once.
+
+## The format
+
+Every graph has three layers, each a list of nodes:
+
+```yaml
+version: "1.0"
+imports: [./shared/tools.yaml]   # optional; resolved relative to this file
+primitives:                      # leaves: must not have deps
+  - id: x_units
+    meta: {type: variable}
+concepts:                        # composed from primitives and other concepts
+  - id: capacity_constraint
+    deps: [x_units, max_units]
+    edge_types: {max_units: constraint}
+    meta: {expression: "x_units <= max_units"}
+applications:                    # capstones: nothing may depend on these
+  - id: minimize_cost
+    deps: [capacity_constraint]
+```
+
+- `deps` are the ids a node depends on (incoming edges).
+- `edge_types` optionally types a dependency: `depends_on` (default), `data_flow`,
+  `prerequisite`, `constraint`, `inheritance`.
+- `meta` is an opaque domain payload that the core never interprets.
+
+## Install
+
+```bash
+uv venv .venv && uv pip install -p .venv/bin/python -e ".[dev]"
+```
+
+## CLI: `gir`
+
+```bash
+gir validate graph.yaml            # exit 1 on errors; warnings are printed but do not fail
+gir diff old.yaml new.yaml         # exit 1 when the graphs differ
+gir slice graph.yaml target_id -o part.yaml   # target plus its prerequisite closure
+gir render graph.yaml                              # svg to stdout (default)
+gir render graph.yaml --format mermaid             # mermaid flowchart text
+gir render graph.yaml --format png -o graph.png    # png and pdf need -o
+gir prettify graph.yaml                            # diff against canonical formatting (exit 1 if it would change)
+gir prettify graph.yaml --write                    # rewrite in place (refuses files with comments)
+gir schema -o schemas/graph.schema.json            # JSON Schema for editors and other tools
+```
+
+`render` supports `svg`, `png`, `pdf`, and `mermaid`. Mermaid needs nothing installed. The
+other formats need Graphviz's `dot` on PATH (`apt install graphviz`).
+
+Exit code 2 means a usage, load, or render error. `prettify` exits 1 when a file is not in
+canonical form, so it can run in CI.
+
+## Specification
+
+The format is specified in [docs/SPECIFICATION.md](docs/SPECIFICATION.md). The machine-readable
+JSON Schema is [schemas/graph.schema.json](schemas/graph.schema.json), regenerated with
+`gir schema -o schemas/graph.schema.json`. A test fails if the committed schema is out of date.
+
+## Python API
+
+```python
+from graph_ir import load_graph, validate, diff_graphs, slice_to, dump_graph
+
+graph = load_graph("solver_pipeline.yaml")   # resolves imports
+for issue in validate(graph):
+    print(issue)
+prereqs = slice_to(graph, "minimize_cost")
+```
+
+## Checks
+
+| Code | Severity | Meaning |
+|---|---|---|
+| `duplicate_id` | error | an id is defined more than once |
+| `unknown_dep` | error | a dep names an id that does not exist |
+| `primitive_has_deps` | error | a primitive depends on something |
+| `layer_violation` | error | a node depends on an application |
+| `cycle` | error | the dependency graph is not a DAG |
+| `orphan` | warning | a node with no deps and no dependents |
+
+## Layout
+
+```text
+src/graph_ir/
+  schema.py       Pydantic models: Graph, Node, Layer, EdgeType
+  dag.py          topological order, ancestors (domain-agnostic)
+  validator.py    structural checks -> Issue list
+  io.py           load_graph (with imports), dump_graph, to_yaml
+  prettify.py     canonical formatting for `gir prettify`
+  transforms/     diff_graphs, slice_to
+  render.py       DOT and Mermaid generation, svg/png/pdf via `dot`
+  cli.py          the `gir` command
+docs/SPECIFICATION.md   the graph.yaml format specification
+schemas/graph.schema.json   generated JSON Schema
+tests/            pytest suite; tests/fixtures holds one graph per domain
+```
+
+## Design decisions
+
+- Imports merge nodes without namespacing, so ids must be unique across the whole import tree.
+- `load_graph` does not validate. Run `validate` separately for structural checks.
+- Unknown top-level and node keys are rejected, so typos fail loudly. Domain data goes in `meta`.
+- Only the core checks are here. Domain rules (for example, solver bounds) belong in the back-end.
+
+## Not yet implemented
+
+- Domain-specific JSON Schema overlays (solver, spl, cba).
+- `graph.html` interactive explorer (belongs to `cba`).
+- Comment-preserving formatting. `prettify --write` refuses files with comments.
+- `spl3` integration, which is the next step: SPL scripts compiling to `GraphIR`.

zigraf_ir-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+graph_ir/__init__.py,sha256=jRD-lJfe2hWc01xKM9-ECJMG7JLDEcs9FNJRskqDX10,874
+graph_ir/cli.py,sha256=3rmReKtgfgNK-k24194bcddVl2EI-YCVx6txFzyTkG0,5722
+graph_ir/dag.py,sha256=r9PgURDeR3mmC7x-36CbKsBosjKcmRgp2vN92j9SoKY,2019
+graph_ir/io.py,sha256=Fkf_KE0yWhjrZAe7FohLfuAz_lYkNn-1KUbIHuCfcRg,3126
+graph_ir/prettify.py,sha256=TrqfqoSwgRXwds0Q-nXCtVqWHElobKs-tpEVnUpKvl0,1432
+graph_ir/render.py,sha256=MrVfHhS6QPf7254KeWcug2PByYieq1TbmfAH0OXeVsI,4049
+graph_ir/schema.py,sha256=O9_FTNezcmq0mcEhuj-I_uUeiJoAs17LV0NPOOSn78o,2855
+graph_ir/validator.py,sha256=guPTv0FmEhfIUirQLtcJyebMItaGEFk82j0mb39Vp18,2458
+graph_ir/transforms/__init__.py,sha256=WUlzfblDa1WAoKCfliIRUkhll8vxo57yTzzlBuhbH6A,176
+graph_ir/transforms/diff.py,sha256=4KKZi6H-PsprgqVPbGqQR0u0LmsXfExLMyL77rouh6w,1750
+graph_ir/transforms/slice.py,sha256=z4wE8fNpk4pS2V9b55cNVtCvuYMYv4Hj0Ajiqx6bMC0,820
+zigraf_ir-0.1.0.dist-info/METADATA,sha256=Rd-Ezp1T_BjM9_yULegPeBpGvMzToeDnO4QUNB4GHrM,19135
+zigraf_ir-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+zigraf_ir-0.1.0.dist-info/entry_points.txt,sha256=Ync47gFXz-MpqvTIny11Ht5KkhQqNn-hh0ZTccPiAZk,42
+zigraf_ir-0.1.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+zigraf_ir-0.1.0.dist-info/RECORD,,

zigraf_ir-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

zigraf_ir-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gir = graph_ir.cli:main

zigraf_ir-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.