PyDecisionGraph 0.3.2.post1__cp315-cp315-win_amd64.whl

decision_graph/decision_tree/bake/c_hierarchy.pxd

@@ -0,0 +1,71 @@
+from libc.stdint cimport uint64_t
+from libcpp cimport bool as c_bool
+
+from cbase.allocator_protocol cimport allocator_protocol
+
+from .c_node cimport LogicNode, dcg_logic_group_manager, dcg_node
+from .c_var cimport dcg_ret_code, dcg_var_t
+
+
+cdef extern from "decision_graph/decision_tree/bake/c_logic_group.h":
+    ctypedef struct dcg_logic_group:
+        pass
+
+    int c_dcg_lgm_install_breakpoint(dcg_logic_group_manager* mgr, dcg_breakpoint_node* breakpoint) noexcept nogil
+
+
+cdef extern from "decision_graph/decision_tree/bake/c_hierarchy.h":
+    ctypedef struct dcg_node_eval_path:
+        dcg_node** node
+        dcg_var_t* eval_val
+        size_t capacity
+        size_t  n_nodes
+        dcg_ret_code code
+        dcg_node* leaf
+        dcg_node* failed
+        uint64_t seq_id
+
+    ctypedef struct dcg_root_node:
+        dcg_node base
+        dcg_node_eval_path eval_path
+        c_bool inherit_contexts
+
+    ctypedef struct dcg_breakpoint_node:
+        dcg_node base
+        dcg_logic_group* break_from
+        c_bool await_connection
+
+    dcg_root_node* c_dcg_node_new_root(const char* repr, allocator_protocol* allocator) noexcept nogil
+    dcg_breakpoint_node* c_dcg_node_new_breakpoint(dcg_logic_group* break_from, const char* repr, allocator_protocol* allocator) noexcept nogil
+    int c_dcg_node_ctx_enter_breakpoint(dcg_node* node, dcg_logic_group_manager* mgr) noexcept nogil
+    dcg_breakpoint_node* c_dcg_node_get_breakpoint(const dcg_node* node) noexcept nogil
+    void c_dcg_node_free_root(dcg_root_node* node) noexcept nogil
+    void c_dcg_node_free_breakpoint(dcg_breakpoint_node* node) noexcept nogil
+
+    void c_dcg_node_free_generic(dcg_node* node) noexcept nogil
+    int c_dcg_node_teardown_root(dcg_node* node) noexcept nogil
+    int c_dcg_node_remove(dcg_node* node) noexcept nogil
+    int c_dcg_node_clear_children(dcg_node* node) noexcept nogil
+    int c_dcg_node_clean(dcg_node* node) noexcept nogil
+
+
+cdef extern from "decision_graph/decision_tree/bake/c_eval.h":
+    int c_dcg_root_node_eval(dcg_root_node* root) noexcept nogil
+
+
+cdef class NodeEvalPathView:
+    cdef const dcg_node_eval_path* header
+
+    @staticmethod
+    cdef inline NodeEvalPathView c_from_header(const dcg_node_eval_path* path)
+
+
+cdef class RootLogicNode(LogicNode):
+    cdef readonly str name
+    cdef readonly NodeEvalPathView eval_path
+
+    cpdef object bake(self, bint validate_only=?)
+
+
+cdef class BreakpointNode(LogicNode):
+    cdef readonly object break_from

decision_graph/decision_tree/bake/c_hierarchy.pyi

@@ -0,0 +1,409 @@
+"""The hierarchy layer: the graph's entry point, and the inspection sink.
+
+Two nodes that are not part of the decision the graph computes. A root is where
+a graph is entered: it takes one branch, and entering it opens a context of its
+own - the scopes around it are shelved while a build is inside. A breakpoint is
+where an inspection stops: it breaks out of a group, and it resumes into the
+next node entered outside it.
+"""
+
+from collections.abc import Iterator
+from typing import Any
+
+from .c_bake import BakeReport
+from .c_logic_group import LogicGroup
+from .c_node import LogicNode
+
+
+class RootLogicNode(LogicNode):
+    """The graph's entry point: the only node that has no parent.
+
+    A root takes exactly ONE branch - its single arm is the entry edge - and
+    entering it shelves the contexts around it, so the graph a build enters is
+    built in a context of its own.
+
+    It is also where evaluating a graph starts: ``eval`` walks from here to a
+    single leaf and keeps the record of how it got there, so the root is what a
+    caller asks to make a decision.
+
+    Attributes:
+        name: The root's name, as the build gave it.
+    """
+
+    def __init__(self, *, name: str = 'Entry Point', inherit_contexts: bool = False, **kwargs: Any) -> None:
+        """Build a root.
+
+        Args:
+            name: The root's name.
+            inherit_contexts: Whether it takes the contexts of the groups around
+                it rather than shelving them.
+
+        Raises:
+            MemoryError: When the block cannot be allocated.
+        """
+        ...
+
+    def eval(self) -> Any:
+        """Evaluate the graph from this root, and record how it decided.
+
+        The whole walk, not one node - which is what a root does differently
+        from every other node, whose ``eval`` runs its own rule and nothing else.
+        Every node on the way is evaluated, the record of the last walk is
+        replaced, and the answer is where the walk came to rest: the leaf itself
+        when that leaf is an action, because the action IS the decision, and the
+        value in the leaf's slot otherwise.
+
+        The value a walk reads is the value AT THE MOMENT OF THE WALK: a read is
+        live, so the same graph decides differently when the store it reads
+        changes, and evaluating again is how a caller asks it to. What a walk
+        pins is the TYPE: a read is resolved to its entry's type at its first
+        evaluation, and a value of another type written to that entry afterwards
+        is not one it reports.
+
+        Returns:
+            The leaf's wrapper when the walk landed on an action, else the value
+            that leaf holds.
+
+        Raises:
+            EvalFailureError: When the walk could not reach a leaf - a read of an
+                entry with no value in it, a branch whose value selected no arm
+                and which has no fallback, or a node a hook refused. It names the
+                node that refused, with the code, the stage and what was running
+                (``node`` is the node the record reports as ``failed``), and a
+                hook's own exception travels as its cause. The record still holds
+                the nodes reached before it stopped.
+        """
+        ...
+
+    def __call__(self) -> Any:
+        """Evaluate the graph - the same walk ``eval`` runs, written as a call.
+
+        A root is what a caller asks to make a decision, and asking it is the
+        call: ``root()`` and ``root.eval()`` answer with the same value for the
+        same graph and leave the same record. The call form is what a graph reads
+        as at the place a decision is wanted, and it is the one door the two
+        layers spell the same way.
+
+        Returns:
+            The leaf's wrapper when the walk landed on an action, else the value
+            that leaf holds.
+
+        Raises:
+            EvalFailureError: When the walk could not reach a leaf - the same
+                failures, reported the same way, as ``eval``.
+        """
+        ...
+
+    def bake(self, validate_only: bool = False) -> BakeReport:
+        """Bake the graph: verify what an evaluation assumes, lock it, prepare it.
+
+        The last thing done to a graph before it is walked, and the pass every
+        evaluation is written assuming has run. What an evaluation assumes is
+        established here and nowhere else, because the hot path carries no check
+        for a malformed node:
+
+        - the graph's STRUCTURE - one parentless root, the arms in reading order,
+          an else last, an action below nothing, no cycles;
+        - every operand an operator takes has a component bound to it, and its
+          operand array is exactly as long as its arity - the rules run their
+          operands and read the workspace they filled with nothing checked in
+          between;
+        - every operator belongs to its node's arity, and no node in the graph is
+          one that has no evaluation at all (a call).
+
+        What the pass then does is hold the graph to what it verified: every node
+        it walked is frozen, so the structure is what it was, and every store the
+        graph reads is sealed, so no entry can appear in it afterwards. That
+        second half is the one an evaluation depends on - a resolved read holds a
+        reference into its store's block, and a block moves only when the store
+        grows. A store is sealed in SHAPE and not in contents: the entries it has
+        are the entries it will have, and a caller goes on writing values into
+        them, because a graph is baked once and fed many times.
+
+        Finally the record a walk fills has its room made in advance, sized for
+        what a walk from this root can need, so evaluating a baked graph
+        allocates nothing.
+
+        A bake is all or nothing: a graph that fails is not locked and not
+        prepared, so nothing about it changes. A bake that succeeds is
+        idempotent - asked again it locks nothing and seals nothing, which the
+        report says.
+
+        Args:
+            validate_only: Whether to verify the graph and report without
+                locking or preparing it - the question "would this bake?" asked
+                without the commitment. Nothing about the graph changes.
+
+        Returns:
+            The report: what the pass found, and what it affected.
+
+        Raises:
+            BakeFailureError: When the graph cannot be baked - the code, the node
+                that produced it and the problems found are in the report the
+                failure carries, and nothing was locked or prepared.
+        """
+        ...
+
+    def get_breakpoint(self) -> BreakpointNode | None:
+        """The breakpoint this graph left waiting, or None if it left none.
+
+        A breakpoint that has not resumed into anything yet IS a leaf - it is
+        where a branch stopped - so what this looks for is the first breakpoint
+        among the leaves: the one a build can enter to carry the graph on from
+        where it broke out.
+
+        That is what makes a graph assemblable from several places. One function
+        builds up to a break, this hands the break back, and the next function
+        takes it and builds the rest - so the two halves never have to be in the
+        same scope, or even the same function.
+
+        Returns:
+            The waiting breakpoint, or None when the graph has none.
+        """
+        ...
+
+    def to_html(self, file_name: str | None = None, with_eval: bool = True) -> None:
+        """Render this graph to a standalone HTML file.
+
+        The file carries the stylesheet, the script and D3 inside it, so it
+        opens anywhere with no server and no network.
+
+        Args:
+            file_name: Output HTML file name; when omitted, the file is named
+                after the root's ``repr``.
+            with_eval: Whether to include the last evaluation in the rendering.
+        """
+        ...
+
+    def show(self, **kwargs: Any) -> None:
+        """Serve this graph in the layer's own web viewer and open a browser.
+
+        Arguments:
+            **kwargs: keyword arguments passed into ``decision_graph.webui.bake.show`` method.
+        """
+        ...
+
+    def watch(self, **kwargs: Any) -> None:
+        """Stream this graph's changes to the layer's own web viewer.
+
+        The root is re-evaluated on a timer, and what changed between runs is
+        sent to the page as it happens.
+
+        Arguments:
+            **kwargs: keyword arguments passed into ``decision_graph.webui.bake.watch`` method.
+        """
+        ...
+
+    @property
+    def inherit_contexts(self) -> bool:
+        """Whether this root takes the groups around it rather than shelving them.
+
+        Recorded on the root when it is built, and read back off the block. Note
+        that this layer's root does not shelve yet - its entering reserves its arm
+        and nothing else - so the flag is carried and reported but has no effect
+        on a build. The capi's root does shelve, which is where the two differ.
+        """
+        ...
+
+    @property
+    def name(self) -> str | None:
+        """The root's name - None for a root rebuilt from C, which carries none."""
+        ...
+
+    @property
+    def eval_path(self) -> NodeEvalPathView:
+        """The record of how the last decision was made, as a view over it.
+
+        The root first and the leaf it came to rest on last, with every branch it
+        descended through in between - the very wrappers the build made, not
+        fresh views of them - plus the outcome: which code the walk ended with,
+        where it landed, what failed if anything did, and which run wrote it. It
+        is replaced by each walk, so what it holds is the last one; a walk that
+        could not finish leaves the nodes it got through and no leaf.
+
+        The view is taken once, when the root is built, and it reads the record
+        the root holds - so a root rebuilt from C carries one too, over the very
+        record the block has. It is a field rather than a computed value: asking
+        for it twice answers with the same view.
+        """
+        ...
+
+
+class NodeEvalPathView:
+    """A read-only window onto ``dcg_node_eval_path``: the record of a walk.
+
+    A view is an ADDRESS, not a copy: it holds the record it was taken over, and
+    every read answers for what that record holds now. The record belongs to the
+    root whose walk wrote it - it is embedded in that root and its blocks are
+    nested under it - so the view must not outlive the root, which the layer
+    guarantees by handing one out only from the root it belongs to
+    (``RootLogicNode.eval_path``).
+
+    It cannot write: the view holds the record **const**, and every reader it
+    exposes reads through that pointer, so a write through a view does not
+    compile.
+
+    Attributes:
+        _header: The C record this view reads through.
+    """
+
+    def __init__(self, address: int) -> None:
+        """View the record at an address.
+
+        Args:
+            address: Address of a ``dcg_node_eval_path``. The layer hands these
+                out itself (``RootLogicNode.eval_path``); nothing here checks that
+                the address is a record, and the view keeps nothing alive.
+        """
+        ...
+
+    def __repr__(self) -> str:
+        """The view's own text: the count, the outcome and where the walk landed."""
+        ...
+
+    def __len__(self) -> int:
+        """How many nodes the walk reached."""
+        ...
+
+    def __iter__(self) -> Iterator[LogicNode]:
+        """Walk the entries: the nodes, in the order the walk reached them."""
+        ...
+
+    def __getitem__(self, index: int) -> LogicNode:
+        """The entry at an index, counting from the front or the back.
+
+        Args:
+            index: Which entry; negative counts from the end.
+
+        Returns:
+            The wrapper for the node the walk reached there.
+
+        Raises:
+            IndexError: When there is no such entry.
+        """
+        ...
+
+    @property
+    def address(self) -> int:
+        """The record's address - what this view reads through."""
+        ...
+
+    @property
+    def nodes(self) -> list[LogicNode]:
+        """Every entry, as a list: the nodes in the order the walk reached them."""
+        ...
+
+    @property
+    def capacity(self) -> int:
+        """The room the record has - how many entries it can hold before it grows."""
+        ...
+
+    @property
+    def code(self) -> int:
+        """The outcome, as the ``DCG_ERR_*`` code the walk ended with."""
+        ...
+
+    @property
+    def code_name(self) -> str:
+        """The outcome's stable name: ``'OK'``, ``'UNBOUND'``, ``'NO_MATCH'``, ..."""
+        ...
+
+    @property
+    def leaf(self) -> LogicNode | None:
+        """The node the walk came to rest on, or None when it never landed."""
+        ...
+
+    @property
+    def failed(self) -> LogicNode | None:
+        """The node that reported the failure, or None when nothing failed.
+
+        In a walk this is the node whose own evaluation refused - the one whose
+        stages say how far it got - which need not be the node a caller asked to
+        evaluate: a root that reached a branch which then failed did not fail.
+        """
+        ...
+
+    @property
+    def seq_id(self) -> int:
+        """The id of the run the record belongs to: which walk wrote it."""
+        ...
+
+
+class BreakpointNode(LogicNode):
+    """An inspection sink: evaluation stops here and resumes outside the group.
+
+    It borrows the group it breaks out of, and this wrapper is what holds that
+    group alive while the breakpoint stands - which is why a reconstruction
+    restores the group with it.
+    """
+
+    def __init__(self, *, break_from: LogicGroup | None = None, repr: str | None = None, autogen: bool = True, **kwargs: Any) -> None:
+        """Build a breakpoint.
+
+        Args:
+            break_from: The group it breaks out of, if any.
+            repr: Display text to copy.
+            autogen: Whether the builder generated it rather than a caller.
+
+        Raises:
+            MemoryError: When the block cannot be allocated.
+        """
+        ...
+
+    @classmethod
+    def break_(cls, break_from: LogicGroup, **kwargs: Any) -> BreakpointNode:
+        """Break out of a group, and hand back the breakpoint that did it.
+
+        A break is a node: it takes the arm the build was about to fill, and the
+        build continues from IT rather than from the group it left. That is what
+        makes this the door for assembling a graph in pieces - one function
+        builds up to the break and returns, and the break it made is taken here
+        to carry on outside the group.
+
+        The breakpoint is built first and then installed, rather than made by the
+        install: the block that lands in the graph has to be the one this wrapper
+        holds, or the caller is handed a handle on a node that is not in the
+        graph.
+
+        Args:
+            break_from: The group being broken out of.
+            **kwargs: Passed to the constructor.
+
+        Returns:
+            The breakpoint, now in the graph and waiting to resume into the next
+            node built.
+
+        Raises:
+            RuntimeError: When the C layer cannot place it.
+            MemoryError: When the block cannot be allocated.
+        """
+        ...
+
+    def connect(self, child: LogicNode) -> None:
+        """Connect a node as what this breakpoint resumes into.
+
+        A breakpoint resumes into exactly one node - which is what its arm is
+        for - so a second connection is refused rather than replacing the first.
+
+        Args:
+            child: Node to connect.
+
+        Raises:
+            RuntimeError: When the C layer refuses the link.
+        """
+        ...
+
+    @property
+    def linked_to(self) -> LogicNode | None:
+        """The node this breakpoint resumes into, or None while it waits."""
+        ...
+
+    @property
+    def break_from(self) -> LogicGroup | None:
+        """The group this breakpoint breaks out of, or None when it names none."""
+        ...
+
+    @property
+    def await_connection(self) -> bool:
+        """Whether the breakpoint is waiting for the node it resumes into."""
+        ...