signalsafe-tree-spec (Python)

Current source and planned customer-subdomain impact: current-state summary.

Python implementation of the TreeSpec wire contract: Pydantic models, parsing, lint, patch helpers, and constants. Backend counterpart to @signalsafe/tree-spec on npm.

License: MIT — see LICENSE. See SECURITY.md for vulnerability reporting.

What this package does

• Validate and parse TreeSpec wire JSON into typed Pydantic models (TreeSpec, Node, Transition, …).
• Lint wire payloads (lint_tree_spec) with structured issues, including duplicate choices, invalid references, unreachable nodes, and reachable paths that cannot reach END.
• Build wire documents programmatically (TreeSpecBuilder).
• Apply JSON patches to wire dicts (apply_patch_to_spec_dict).
• Expose wire constants (END_NODE_ID, TREESPEC_WIRE_VERSION).

See docs/compatibility.md for how unknown JSON fields are handled (extra="ignore") and how that compares to TypeScript compile/decompile.

What this package does not do

• HTTP APIs, authentication, persistence, or training UI.
• Scenario simulation (use @signalsafe/simulator-core / simulator-react in TypeScript stacks).
• Graph editor UI (use @signalsafe/tree-spec-editor-* packages).
• General sandboxing or authorization — contract validation only; host apps decide trust and access control.

Install

pip install signalsafe-tree-spec

Development (this repo uses uv):

uv sync --extra dev
uv run pytest

Distribution name vs import path

pip install signalsafe-tree-spec

import tree_spec
from tree_spec import TreeSpec, lint_tree_spec, TreeSpecBuilder

Install the PyPI distribution signalsafe-tree-spec; import its generic tree_spec package.

Quick start

from tree_spec import (
    END_NODE_ID,
    TREESPEC_WIRE_VERSION,
    TreeSpec,
    TreeSpecBuilder,
    lint_tree_spec,
)

wire = {
    "wire_version": TREESPEC_WIRE_VERSION,
    "start_node": "start",
    "nodes": {
        "start": {
            "type": "prompt",
            "prompt": "Verify the sender before clicking?",
            "choices": [{"id": "inspect", "label": "Inspect sender"}],
        }
    },
    "transitions": [
        {"from": ["start", "inspect"], "to": END_NODE_ID, "outcome": "safe"},
    ],
}

issues = lint_tree_spec(wire)
assert not issues

spec = TreeSpec.model_validate(wire)
builder = TreeSpecBuilder()
# builder.add_node(...) — see tests/ for full builder flows

Public API

All symbols below are exported from the top-level tree_spec package:

The top-level tree_spec package exposes common helpers; submodules such as tree_spec.models and tree_spec.patch remain available.

Wire contract (high level)

• wire_version: optional; omit for implicit v1. Constant TREESPEC_WIRE_VERSION documents the current version string.
• start_node: entry node id.
• nodes: map of node id → node object (type, prompt, choices or legacy options, optional render_hints).
• transitions: list of { from: [nodeId, choiceId], to, outcome? }. Terminal transitions target END_NODE_ID and require outcome.
• _meta: optional tree-level metadata (for example graph-editor viewport persisted by editor packages).

Legacy payloads may use options instead of choices and legacy terminal ids; both implementations normalize these to canonical choices and END on read. Python lint validates the wire shape your backend accepts.

Python / TypeScript parity

Keep fixture JSON in sync when changing wire rules in either language. Graph diagnostics use the same canonical codes and JSON-like paths in both languages; Python exposes the legacy level field and the equivalent read-only severity property. Full compile/decompile parity lives in TypeScript today; Python focuses on validation, lint, builder, and patch flows used by backends.

Development

uv sync --extra dev
uv run pytest
uv run ruff check .
uv run python -m build
uv run python scripts/smoke_package.py

Security

See SECURITY.md. TreeSpec parsing is contract validation, not a sandbox. Validate and authorize TreeSpec JSON in your application layer before treating content as trusted.

Changelog and releases

• CHANGELOG.md
• RELEASING.md

Related packages

• @signalsafe/tree-spec — TypeScript wire contract and compile/lint.
• tree-spec-editor-* — authoring UI (TypeScript/React).

Python 0.4 migration

Replace former product-specific imports with tree_spec (including submodules). The PyPI distribution remains signalsafe-tree-spec; upgrade consumers to 0.4.x. No compatibility alias is provided.

Source layout

Runtime code and the packaged version/typing markers live in src/tree_spec/. Tests, developer scripts and release metadata remain outside src/. Run uv sync --frozen --extra dev before local checks; tests use the installed editable package rather than adding src to PYTHONPATH. Wheel and source archives are built into dist/.