fuaran-ui 0.7.0__py3-none-any.whl

fuaran_ui/__init__.py

@@ -0,0 +1,113 @@
+"""fuaran-ui — a headless Python host of the Fuaran UI wire format.
+
+A dependency-light, idiomatic-Python reference implementation of the canonical
+Fuaran UI wire format (``WIRE_FORMAT.md``): decode / encode for the ``Node`` tree
+and the ``TreeOp`` algebra, plus a pre-emit validator. It is a *sibling*
+reference implementation built to the language-neutral spec + conformance
+corpus, not a transpile of any other host.
+
+Canonical imports::
+
+    from fuaran_ui import decode_node, encode_node, decode_op, encode_op
+    from fuaran_ui import decode_dag_record, encode_dag_record   # branching op-stream
+    from fuaran_ui import Ok, Err, DecodeError
+    from fuaran_ui.renderer import render_html      # optional headless renderer
+    from fuaran_ui.client import FuaranClient, FuaranSession   # generation-endpoint client
+"""
+
+from __future__ import annotations
+
+from .dag import DagOpRecord, DagResultEnvelope, decode_dag_record, encode_dag_record
+from .function import (
+    EXACT,
+    SUBSUMES,
+    ComposePath,
+    FunctionEntry,
+    FunctionRegistry,
+    NoPath,
+    SigEntry,
+    Signature,
+    SignatureQuery,
+    function_entry,
+    slot_hole,
+    value_hole,
+)
+from .merge import (
+    MergeAuthor,
+    MergeConflict,
+    MergeConflicts,
+    MergeOk,
+    MergeResult,
+    MergeSide,
+    Primary,
+    Secondary,
+    encode_envelope,
+    merge3,
+    merge3_way_lenient,
+    merge3_way_with_author,
+    merge_3way,
+)
+from .model import Arr, Node, Obj, from_json
+from .ops import decode_op, diff, encode_op
+from .result import (
+    CODES,
+    DecodeError,
+    DecodeResult,
+    Err,
+    Ok,
+)
+from .schema import decode_node, encode_node
+from .validator import Finding, validate_node
+
+#: Distribution version. Kept in step with ``pyproject.toml``; the packaging-contract
+#: test in ``tests/`` fails if the two disagree, so this is a pin rather than a copy.
+__version__ = "0.7.0"
+
+__all__ = [
+    "decode_node",
+    "encode_node",
+    "decode_op",
+    "encode_op",
+    "decode_dag_record",
+    "encode_dag_record",
+    "DagOpRecord",
+    "DagResultEnvelope",
+    "merge_3way",
+    "merge3",
+    "merge3_way_with_author",
+    "merge3_way_lenient",
+    "MergeOk",
+    "MergeConflicts",
+    "MergeConflict",
+    "MergeSide",
+    "MergeResult",
+    "encode_envelope",
+    "MergeAuthor",
+    "Primary",
+    "Secondary",
+    "diff",
+    "FunctionRegistry",
+    "FunctionEntry",
+    "SigEntry",
+    "Signature",
+    "SignatureQuery",
+    "ComposePath",
+    "NoPath",
+    "value_hole",
+    "slot_hole",
+    "function_entry",
+    "SUBSUMES",
+    "EXACT",
+    "validate_node",
+    "Finding",
+    "Node",
+    "Obj",
+    "Arr",
+    "from_json",
+    "Ok",
+    "Err",
+    "DecodeError",
+    "DecodeResult",
+    "CODES",
+    "__version__",
+]

fuaran_ui/ai_tools/__init__.py

@@ -0,0 +1,86 @@
+"""``fuaran_ui.ai_tools`` — the AI-tools introspection surface.
+
+The runtime introspection an orchestrator/agent needs to drive the Fuaran tree
+natively from Python (the language AI agents are written in), over the Phase 234
+headless codec and typed surface. Three parts, all provider-agnostic and
+standard-library-only:
+
+* :mod:`~fuaran_ui.ai_tools.surface` — the **emittable-surface catalog**: what an
+  agent may emit (recognised kinds / bindings / actions / text-sources), the
+  bounded **value-space** projections, provider-agnostic **tool/function schemas**
+  it registers, and :func:`~fuaran_ui.ai_tools.surface.validate_emission` to check
+  an emission against the typed surface.
+* :mod:`~fuaran_ui.ai_tools.introspect` — read-only **tree introspection**: kind,
+  bound binding slots (with their canonical wire-form expression), and structure.
+* :mod:`~fuaran_ui.ai_tools.dispatch` — the **default-deny-by-shape dispatch gate**
+  (FGP 3): an effect shape the host has not permitted is refused.
+"""
+
+from __future__ import annotations
+
+from .dispatch import (
+    GATED_EFFECT_SHAPES,
+    INERT_SHAPES,
+    DispatchDecision,
+    DispatchGate,
+    is_gated_effect,
+)
+from .introspect import (
+    BindingSlot,
+    NodeIntrospection,
+    TreeIntrospection,
+    binding_expression,
+    binding_slots,
+    child_ids,
+    child_nodes,
+    find_node,
+    inspect_tree,
+    kind_name,
+    node_state,
+    walk_nodes,
+)
+from .surface import (
+    ValidationResult,
+    action_cases,
+    binding_cases,
+    describe_surface,
+    emit_tool_schema,
+    emittable_kinds,
+    text_source_cases,
+    tool_schemas,
+    validate_emission,
+    value_space,
+)
+
+__all__ = [
+    # surface
+    "emittable_kinds",
+    "binding_cases",
+    "action_cases",
+    "text_source_cases",
+    "value_space",
+    "describe_surface",
+    "validate_emission",
+    "ValidationResult",
+    "tool_schemas",
+    "emit_tool_schema",
+    # introspect
+    "kind_name",
+    "binding_expression",
+    "binding_slots",
+    "child_nodes",
+    "child_ids",
+    "walk_nodes",
+    "find_node",
+    "node_state",
+    "inspect_tree",
+    "BindingSlot",
+    "NodeIntrospection",
+    "TreeIntrospection",
+    # dispatch
+    "DispatchGate",
+    "DispatchDecision",
+    "is_gated_effect",
+    "GATED_EFFECT_SHAPES",
+    "INERT_SHAPES",
+]

fuaran_ui/ai_tools/dispatch.py

@@ -0,0 +1,99 @@
+"""Default-deny-by-shape dispatch gate (FGP 3).
+
+An agent driving the tree proposes ``Action`` effects; the host decides whether
+each may run. This is the policy gate the introspection/dispatch path consults
+**by shape** — the action's wire discriminator (`$type`) — before any effectful
+action is dispatched. It is **default-deny**: an effect shape the host has not
+explicitly permitted is refused, so a new or unexpected effect can never fire by
+omission (the same posture as the reference tier's runtime dispatch gate and the
+capability seam's default-deny-by-shape validation).
+
+The gate is a *policy* only — it never executes an action (a Python host executes
+the permitted effect downstream). It classifies an action's shape and returns an
+allow/deny decision with a reason.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from ..model import Obj
+from ..schema.decode import ACTION_CASES
+
+# Effectful shapes that reach outside the pure state-update loop — they require
+# explicit host permission (mirrors the reference runtime's gated set:
+# call/navigate/ai-tool/read-file-body, plus the host-effect notify / clipboard /
+# capability-invoke). An effect not in this set is still default-denied unless
+# permitted; this set is what a host reasons about when granting.
+GATED_EFFECT_SHAPES = frozenset(
+    {"Dispatch", "Navigate", "AiTool", "ReadFileBody", "Notify", "WriteToClipboard", "Invoke", "Call"}
+)
+# `Call` joined the set in 0.3.0. It was named FIRST in the comment above from the
+# day this module was written ("call/navigate/ai-tool/read-file-body") and absent
+# from the set itself — a transcription slip rather than a policy, and one nothing
+# caught because `authorize` default-denies an unclassified shape anyway, so the
+# gate's VERDICT was already right. What was wrong is what a host reasoning with
+# `is_gated_effect` was told: that an HTTP call to a host endpoint is not an
+# outward effect it must decide about. A permission model is only as good as the
+# question it is asked, and that one was being asked wrong.
+
+# Structural, side-effect-free composition — safe to permit broadly. ``Chain`` is
+# a sequence (its members are gated individually); ``SetState`` mutates only the
+# local MVU state.
+INERT_SHAPES = frozenset({"Chain", "SetState"})
+
+
+@dataclass(frozen=True)
+class DispatchDecision:
+    """The gate's verdict for one action shape."""
+
+    shape: str
+    allowed: bool
+    reason: str
+
+
+def is_gated_effect(shape: str) -> bool:
+    """Whether a shape is an outward/host effect that must be explicitly permitted."""
+    return shape in GATED_EFFECT_SHAPES
+
+
+@dataclass(frozen=True)
+class DispatchGate:
+    """A default-deny-by-shape policy gate.
+
+    ``DispatchGate()`` denies every action shape. A host opts shapes in explicitly
+    with :meth:`permitting`; :meth:`permissive_inert` grants only the side-effect-free
+    structural shapes (``Chain`` / ``SetState``), leaving every outward effect denied.
+    """
+
+    allowed: frozenset[str] = field(default_factory=frozenset)
+
+    @classmethod
+    def deny_all(cls) -> DispatchGate:
+        return cls(frozenset())
+
+    @classmethod
+    def permitting(cls, *shapes: str) -> DispatchGate:
+        return cls(frozenset(shapes))
+
+    @classmethod
+    def permissive_inert(cls) -> DispatchGate:
+        """Permit only the inert structural shapes; every gated effect stays denied."""
+        return cls(frozenset(INERT_SHAPES))
+
+    def with_permitted(self, *shapes: str) -> DispatchGate:
+        return DispatchGate(self.allowed | frozenset(shapes))
+
+    def authorize_shape(self, shape: str) -> DispatchDecision:
+        """The verdict for a bare action-shape string (default-deny)."""
+        if shape not in ACTION_CASES:
+            return DispatchDecision(shape, False, f"unknown action shape {shape!r}")
+        if shape in self.allowed:
+            return DispatchDecision(shape, True, "explicitly permitted")
+        return DispatchDecision(shape, False, "default-deny by shape (not permitted)")
+
+    def authorize(self, action: Obj) -> DispatchDecision:
+        """The verdict for a decoded ``Action`` object (reads its ``$type`` tag)."""
+        if not isinstance(action, Obj) or action.tag is None:
+            return DispatchDecision("<malformed>", False, "not a discriminated action object")
+        return self.authorize_shape(action.tag)

fuaran_ui/ai_tools/introspect.py

@@ -0,0 +1,190 @@
+"""Tree introspection — walk a decoded ``Node`` tree and report each node's kind,
+its bound binding slots (with the canonical wire-form expression), and its
+structural children.
+
+The Python analogue of the reference tier's read-only introspection surface: the
+*static* view an agent uses to inspect a tree it (or the model) emitted — kind
+discriminator, which slots are data-bound and how (`$state.<key>` / `$queries.<name>`
+/ …), and the structural shape. Value resolution against a live host + geometry
+probing are a renderer-side concern and are deliberately out of scope here (this
+is the source-side static surface, matching the reference tier's split).
+
+It walks the generic decoded model (``Node`` / ``Obj`` / ``Arr``) rather than a
+per-kind table, so a new ``NodeKind`` needs no change here — a bound slot is any
+field whose value is a ``Binding``-tagged object, discovered structurally.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..model import Arr, Node, Obj
+from ..model import Value as WireValue
+from ..schema.decode import BINDING_CASES
+
+
+@dataclass(frozen=True)
+class BindingSlot:
+    """One data-bound slot on a node: its dotted field path within the kind, the
+    ``Binding`` case that produced it, and the canonical wire-form expression."""
+
+    slot: str
+    source: str
+    expression: str
+
+
+@dataclass(frozen=True)
+class NodeIntrospection:
+    """The per-node introspection envelope."""
+
+    id: str
+    kind: str
+    bindings: tuple[BindingSlot, ...]
+    child_ids: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class TreeIntrospection:
+    """A recursive structural snapshot of a whole tree."""
+
+    id: str
+    kind: str
+    bindings: tuple[BindingSlot, ...]
+    child_ids: tuple[str, ...]
+    children: tuple[TreeIntrospection, ...]
+
+
+def kind_name(node: Node) -> str:
+    """The wire discriminator for a node's kind (the ``$type`` tag) — e.g. ``Box``,
+    ``Metric``, ``DataGrid``."""
+    return node.kind.tag or "<untagged>"
+
+
+def binding_expression(binding: Obj) -> tuple[str, str]:
+    """Classify a ``Binding``-tagged object into ``(source, expression)`` — the
+    canonical wire-form accessor the reference tier reports (`$state.<key>`, …)."""
+    tag = binding.tag or ""
+    fields = binding.fields
+    if tag == "Static":
+        return ("Static", "$static")
+    if tag == "Query":
+        return ("Query", f"$queries.{fields.get('name', '')}")
+    if tag == "Filter":
+        return ("Filter", f"$filters.{fields.get('name', '')}")
+    if tag == "Selection":
+        return ("Selection", f"$selection.{fields.get('nodeId', fields.get('sourceId', ''))}")
+    if tag == "State":
+        return ("State", f"$state.{fields.get('key', '')}")
+    if tag == "I18n":
+        return ("I18n", f"$i18n.{fields.get('key', '')}")
+    if tag == "Local":
+        return ("Computed", "$local")
+    if tag == "Format":
+        return ("Computed", "$format")
+    if tag == "Transform":
+        return ("Computed", "$transform")
+    if tag == "Invoke":
+        return ("Computed", "$invoke")
+    # Computed + any future value-computing case.
+    return ("Computed", "$computed")
+
+
+def _is_binding(value: WireValue) -> bool:
+    return isinstance(value, Obj) and value.tag in BINDING_CASES
+
+
+def binding_slots(node: Node) -> tuple[BindingSlot, ...]:
+    """Every data-bound slot in the node's kind, in document order, with a dotted
+    field path (e.g. ``source``, ``spec.activeIndex``). Recurses through record
+    objects + arrays but **not** into a nested ``Node`` (those belong to the child)."""
+    slots: list[BindingSlot] = []
+
+    def walk(value: WireValue, path: str) -> None:
+        if isinstance(value, Node):
+            return  # a child node's bindings are the child's, not this node's
+        if isinstance(value, Obj):
+            if _is_binding(value):
+                source, expr = binding_expression(value)
+                slots.append(BindingSlot(slot=path, source=source, expression=expr))
+                return
+            for name, field_value in value.fields.items():
+                walk(field_value, f"{path}.{name}" if path else name)
+        elif isinstance(value, Arr):
+            for i, item in enumerate(value.items):
+                walk(item, f"{path}[{i}]")
+
+    for name, field_value in node.kind.fields.items():
+        walk(field_value, name)
+    return tuple(slots)
+
+
+def child_nodes(node: Node) -> tuple[Node, ...]:
+    """The immediate structural child nodes — every ``Node`` reachable within the
+    kind without passing through another ``Node`` (so grandchildren are excluded)."""
+    children: list[Node] = []
+
+    def walk(value: WireValue) -> None:
+        if isinstance(value, Node):
+            children.append(value)  # stop — its own children are its concern
+        elif isinstance(value, Obj):
+            for field_value in value.fields.values():
+                walk(field_value)
+        elif isinstance(value, Arr):
+            for item in value.items:
+                walk(item)
+
+    for field_value in node.kind.fields.values():
+        walk(field_value)
+    return tuple(children)
+
+
+def child_ids(node: Node) -> tuple[str, ...]:
+    return tuple(c.id for c in child_nodes(node))
+
+
+def walk_nodes(tree: Node) -> list[Node]:
+    """Depth-first walk of every node in the tree, root first."""
+    acc: list[Node] = []
+
+    def visit(node: Node) -> None:
+        acc.append(node)
+        for child in child_nodes(node):
+            visit(child)
+
+    visit(tree)
+    return acc
+
+
+def find_node(tree: Node, node_id: str) -> Node | None:
+    """The first node with ``node_id`` (depth-first), or ``None``."""
+    for node in walk_nodes(tree):
+        if node.id == node_id:
+            return node
+    return None
+
+
+def _introspect(node: Node) -> NodeIntrospection:
+    return NodeIntrospection(
+        id=node.id,
+        kind=kind_name(node),
+        bindings=binding_slots(node),
+        child_ids=child_ids(node),
+    )
+
+
+def node_state(tree: Node, node_id: str) -> NodeIntrospection | None:
+    """The introspection envelope for a single node by id, or ``None``."""
+    node = find_node(tree, node_id)
+    return None if node is None else _introspect(node)
+
+
+def inspect_tree(tree: Node) -> TreeIntrospection:
+    """A recursive structural snapshot of the whole tree."""
+    base = _introspect(tree)
+    return TreeIntrospection(
+        id=base.id,
+        kind=base.kind,
+        bindings=base.bindings,
+        child_ids=base.child_ids,
+        children=tuple(inspect_tree(c) for c in child_nodes(tree)),
+    )

fuaran_ui/ai_tools/surface.py

@@ -0,0 +1,194 @@
+"""The emittable-surface catalog + provider-agnostic tool schemas.
+
+So a Python agent can **discover what it may emit** (the recognised ``NodeKind`` /
+``Binding`` / ``Action`` / ``TextSource`` cases and the bounded value-space
+projections) and **validate its intent** against the typed surface, instead of
+blind-emitting JSON. The catalog is derived from the codec's own recognised-case
+sets + the bounded ``Literal`` enums, so it can never drift from what the decoder
+accepts.
+
+The tool schemas are **provider-agnostic** function/tool definitions (``name`` +
+``description`` + JSON-Schema ``parameters``) an agent registers with any provider.
+The primary constrained-emission tool takes the caller-supplied canonical wire
+schema (``schema.json``) as its input schema, so the package stays corpus-free and
+standard-library-only at import time.
+"""
+
+from __future__ import annotations
+
+import typing
+from dataclasses import dataclass
+from typing import Any
+
+from ..result import Err
+from ..schema import types as t
+from ..schema.decode import ACTION_CASES, BINDING_CASES, KNOWN_KINDS, TEXT_SOURCE_CASES, decode_node
+
+# The bounded value-space projections — each bare-string ``Literal`` enum an agent
+# must pick within (WIRE_FORMAT §3.5). Derived from the typed surface via
+# ``typing.get_args`` so the projection cannot drift from the codec.
+_VALUE_SPACE_ENUMS: dict[str, Any] = {
+    "Tone": t.Tone,
+    "Weight": t.Weight,
+    "Emphasis": t.Emphasis,
+    "Orientation": t.Orientation,
+    "BadgeVariant": t.BadgeVariant,
+    "HeadingVariant": t.HeadingVariant,
+    "ButtonVariant": t.ButtonVariant,
+    "ChartKind": t.ChartKind,
+    "StyleRole": t.StyleRole,
+    "FontVoice": t.FontVoice,
+    "LiveRegion": t.LiveRegion,
+    "ImageVariant": t.ImageVariant,
+    # fuaran#1077 — the three presentation token vocabularies. Offered as value
+    # spaces precisely because they are CLOSED: an agent handed the projection
+    # cannot reach for a CSS ratio the decoder refuses.
+    "ImageFit": t.ImageFit,
+    "ImageAspect": t.ImageAspect,
+    "ImageLoading": t.ImageLoading,
+    "ScrollOrientation": t.ScrollOrientation,
+    "DateVariant": t.DateVariant,
+    "MathDisplay": t.MathDisplay,
+    # fuaran#867 — the two-case polarity enum. `Neutral` is reserved and is
+    # deliberately absent from the alias, so an agent offered this projection
+    # cannot pick a case the decoder refuses.
+    "TrendPolarity": t.TrendPolarity,
+    "BoxRole": t.BoxRole,
+    "FileReadEncoding": t.FileReadEncoding,
+}
+
+
+def emittable_kinds() -> list[str]:
+    """The recognised ``NodeKind`` discriminators an agent may emit."""
+    return sorted(KNOWN_KINDS)
+
+
+def binding_cases() -> list[str]:
+    """The recognised ``Binding`` value-source discriminators."""
+    return sorted(BINDING_CASES)
+
+
+def action_cases() -> list[str]:
+    """The recognised ``Action`` effect discriminators."""
+    return sorted(ACTION_CASES)
+
+
+def text_source_cases() -> list[str]:
+    """The recognised ``TextSource`` discriminators."""
+    return sorted(TEXT_SOURCE_CASES)
+
+
+def value_space() -> dict[str, list[str]]:
+    """Each bounded ``Literal`` enum → its allowed values (the within-bounds
+    choices an agent picks from), derived from the typed surface."""
+    return {name: list(typing.get_args(alias)) for name, alias in _VALUE_SPACE_ENUMS.items()}
+
+
+def describe_surface() -> dict[str, Any]:
+    """A machine-readable snapshot of the whole emittable surface — the payload the
+    ``list_surface`` tool returns to an agent."""
+    return {
+        "kinds": emittable_kinds(),
+        "bindings": binding_cases(),
+        "actions": action_cases(),
+        "textSources": text_source_cases(),
+        "valueSpace": value_space(),
+    }
+
+
+# ── Validation of an agent's emission against the typed surface ───────────────
+
+
+@dataclass(frozen=True)
+class ValidationResult:
+    """The verdict for a candidate wire tree: ``ok`` plus the canonical decode
+    error (code / path / message) when it is rejected."""
+
+    ok: bool
+    code: str | None = None
+    path: str | None = None
+    message: str | None = None
+
+
+def validate_emission(wire_json: str) -> ValidationResult:
+    """Validate an agent's candidate ``Node`` wire JSON against the typed surface via
+    the Phase 234 codec — the canonical accept/reject decision + error location, so
+    the agent repairs intent instead of shipping malformed JSON downstream."""
+    result = decode_node(wire_json)
+    if isinstance(result, Err):
+        e = result.error
+        return ValidationResult(ok=False, code=e.code, path=e.path, message=e.message)
+    return ValidationResult(ok=True)
+
+
+# ── Provider-agnostic tool/function-call schemas ─────────────────────────────
+
+
+def emit_tool_schema(wire_schema: dict[str, Any]) -> dict[str, Any]:
+    """The constrained-emission tool: emit a canonical Fuaran wire tree. Takes the
+    caller-supplied canonical wire schema (``wire-format-fixtures/schema.json``) as
+    its ``parameters`` so a provider constrains generation to schema-valid wire.
+    Passed in (not bundled) so this package stays corpus-free + stdlib-only."""
+    return {
+        "name": "fuaran_emit_tree",
+        "description": (
+            "Emit a Fuaran UI as a canonical wire-format JSON tree (a Node). The tree "
+            "renders on any conformant host. Emit only recognised kinds/bindings/actions "
+            "and pick bounded enum values within their value-space (call fuaran_list_surface)."
+        ),
+        "parameters": wire_schema,
+    }
+
+
+def tool_schemas() -> list[dict[str, Any]]:
+    """The provider-agnostic discovery/validation tool definitions an agent registers.
+    (The constrained-emission tool is :func:`emit_tool_schema` — it needs the wire
+    schema passed in.) Each is a neutral ``{name, description, parameters}`` object
+    usable with any provider's function-calling API."""
+    return [
+        {
+            "name": "fuaran_list_surface",
+            "description": (
+                "List the emittable Fuaran surface: recognised NodeKind / Binding / Action / "
+                "TextSource discriminators and the bounded value-space (enum -> allowed values). "
+                "Call before emitting to stay within the typed surface."
+            ),
+            "parameters": {"type": "object", "properties": {}, "additionalProperties": False},
+        },
+        {
+            "name": "fuaran_validate_tree",
+            "description": (
+                "Validate a candidate Fuaran wire tree against the typed surface. Returns ok, or "
+                "the canonical decode error code + path so the emission can be repaired."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "tree": {
+                        "type": "string",
+                        "description": "The candidate Node wire JSON to validate.",
+                    }
+                },
+                "required": ["tree"],
+                "additionalProperties": False,
+            },
+        },
+        {
+            "name": "fuaran_inspect_tree",
+            "description": (
+                "Introspect an emitted Fuaran wire tree: report each node's id, kind, bound "
+                "binding slots (with their $state/$queries/... expression), and structural children."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "tree": {
+                        "type": "string",
+                        "description": "The Node wire JSON to introspect.",
+                    }
+                },
+                "required": ["tree"],
+                "additionalProperties": False,
+            },
+        },
+    ]