meltygui 0.1.0__py3-none-any.whl

meltygui/core/automation/query_core.py

@@ -0,0 +1,124 @@
+"""MCP Query window — the mcp_query.py collectors, run live in the studio.
+
+The five MCP tools (`find_views`, `describe_view`, `hit_test`,
+`param_sources`, `tile_cache`) are thin wrappers around one collector each:
+the server hands `mcp_eval.request_call` a no-arg closure, the render thread
+runs it between frames, and the answer is JSON-dumped back to the client.
+This window is a second front end onto exactly those collectors — a
+render_func body ALREADY runs on the render thread, so it calls
+`mcp_query.collect_*` directly, with no queue and no server in the way. What
+you read here is what an MCP client reads: the JSON tab dumps the answer the
+way `run_query` does, so its bytes are the tool's bytes.
+
+Pick a tool, edit its arguments, and the answer re-collects on every edit
+(and on every Run press, since the studio moves under a fixed set of
+arguments). The collector is looked up by NAME per run, so a hotswap of
+mcp_query.py lands on the next frame — this window is the fast loop for
+iterating on the collectors themselves.
+
+`follow pointer` (hit_test only) re-collects at the live mouse position
+every frame, which is the quickest way to sanity-check the BVH stack and the
+subscription table: park the pointer over anything and read what claims it.
+"""
+
+import json
+import time
+import traceback
+
+import meltygui_imgui as imgui
+
+import meltygui.core.automation.mcp_query as mcp_query
+from meltygui.core.melty import Melty
+from meltygui.core.conversion.dict_conversion import DictConversion
+from meltygui.core.rendering.render_funcs import RenderFuncs
+from meltygui.core.core_render import render_func
+from meltygui.core.rendering.window_decoration import window
+
+# Tool name -> its arguments and their defaults, in the order the real tool
+# declares them. This table IS the API: an argument dict is rendered by
+# draw_collection, so adding an argument to a collector means adding it here
+# and nothing else. The collector itself is resolved by name at call time
+# (`collect_<tool>`), never bound here, so hotswapping mcp_query.py takes
+# effect immediately instead of pinning the function objects this module
+# imported. Same reason studio_data.py keeps _SOURCES module-level: a
+# dictionary the window reads, not a tuning constant (those live in Toggles).
+_TOOL_ARGS = {
+    "find_views": {"func": "", "name": "", "window": "", "include_closed": False,
+                   "limit": 50},
+    "describe_view": {"view": "", "children_depth": 1},
+    "hit_test": {"x": 0.0, "y": 0.0},
+    "param_sources": {"view": "", "param": ""},
+    "tile_cache": {"view": "", "history_frames": 200, "limit": 50},
+}
+
+
+def _seed_args(panel_state):
+    """Reconcile the persisted arguments against `_TOOL_ARGS`.
+
+    A tool or an argument added since the state was saved appears with its
+    default; one that no longer exists is dropped. This is what lets a
+    hotswap that adds an argument show it on the next frame.
+    """
+    args = panel_state.args
+    for tool, defaults in _TOOL_ARGS.items():
+        current = args.get(tool)
+        if not isinstance(current, dict):
+            current = args[tool] = {}
+        for key, value in defaults.items():
+            current.setdefault(key, value)
+        for key in [key for key in current if key not in defaults]:
+            del current[key]
+    for tool in [tool for tool in args if tool not in _TOOL_ARGS]:
+        del args[tool]
+    if panel_state.tool not in _TOOL_ARGS:
+        panel_state.tool = next(iter(_TOOL_ARGS))
+
+
+def _pointer():
+    """Where the input handler thinks the mouse is.
+
+    The same numbers `collect_hit_test` reports as `pointer`, so a followed
+    point reads `pointer_matches_point: true` and the subscription table is
+    populated. imgui's own mouse position is the fallback for a frame before
+    the handler has one.
+    """
+    handler = getattr(Melty, "event_handler", None)
+    x = getattr(handler, "_cursor_x", None) if handler is not None else None
+    y = getattr(handler, "_cursor_y", None) if handler is not None else None
+    if x is None or y is None:
+        x, y = imgui.get_mouse_pos()
+    return round(float(x), 1), round(float(y), 1)
+
+
+def _run(panel_state, tool, args):
+    """Collect once, into the SAME result dict.
+
+    The answer is copied into the held dict rather than replacing it so the
+    result tree keeps its identity across runs — expanded rows stay expanded
+    while you edit an argument, which is the whole point of following the
+    "mutate in place" rule here. A collector that raises is reported in the
+    window instead of taking the frame down with it: these walk live state
+    and a half-built draw_state is exactly the case worth seeing.
+    """
+    collect = getattr(mcp_query, "collect_" + tool, None)
+    started = time.perf_counter()
+    if collect is None:
+        answer, error = {}, f"mcp_query has no collect_{tool}"
+    else:
+        try:
+            answer, error = collect(**args), None
+        except Exception:
+            answer, error = {}, traceback.format_exc()
+    elapsed_ms = (time.perf_counter() - started) * 1000.0
+    panel_state._result.clear()
+    panel_state._result.update(answer)
+    panel_state._error = error
+    panel_state._json = json.dumps(answer, indent=1, default=str)
+    panel_state._stamp = (f"{elapsed_ms:.2f} ms   ·   {len(panel_state._json)} B"
+                          f"   ·   frame {Melty.frame_count}")
+
+
+# disable_scroll=False: the window is a scrolling box of panes, and the
+# @window code path defaults it to True.
+from meltygui.view.query_view import draw_mcp_query
+draw_mcp_query = window(icon='\uf188', display_name='MCP Query', tint=(0.1, 0.2, 0.28), initial={'width': 820, 'height': 700}, disable_scroll=False)(draw_mcp_query)

meltygui/core/automation/search_core.py

@@ -0,0 +1,26 @@
+"""Search core functions and supporting definitions."""
+import types
+
+
+def search_activate_target(node):
+    """The draw_state Ctrl+Enter should 'click' for the current search match
+    `node` (meltygui.search_current_node). When the match is one of a collection's
+    keys, that's the child at the current key; for a leaf content match it's the
+    node itself."""
+    if node is None:
+        return None
+    key = getattr(node, '_search_current_key', None)
+    if key is not None:
+        child = node._children.get(key)
+        if child is not None:
+            return child
+    # Views that draw their matches as raw draw-list items (no child draw_states
+    # - e.g. the Fast Dock) publish the current match's row rect instead; hand
+    # back a geometry shim so the caller's center-of-rect click lands on the
+    # row rather than the view's center.
+    rect = getattr(node, '_search_current_rect', None)
+    if rect is not None:
+        return types.SimpleNamespace(abs_left=rect[0], abs_top=rect[1],
+                                     width=rect[2], height=rect[3],
+                                     _tile_id=node._tile_id)
+    return node

meltygui/core/automation/selector_core.py

@@ -0,0 +1,340 @@
+"""The UI path language: leaf-anchored selectors over the live draw_state
+tree, used by change_value / orchestration cues to name a target the way a
+person would — by the minimal distinguishing tail of its ancestry.
+
+A PATH is a sequence of SEGMENTS matched as a SUBSEQUENCE of the target's
+ancestor chain, anchored at the leaf: the last segment matches the target
+itself, the earlier ones match ancestors in order with any depth of
+unnamed/unmatched levels between (descendant matching is the default, so
+nesting is never the caller's problem unless it is the distinguisher).
+
+Segment kinds — each one is a data-description level:
+    "alpha"          name (display name, the "##"-stripped str(ds.name))
+    1                ordinal: the nth match (visual order: abs_top, abs_left)
+                     of the REMAINING path within the current scope —
+                     "Loras/[1]/alpha" = the 2nd alpha under Loras. (A
+                     per-node "nth child of its parent" reading was tried
+                     and rejected: single-child wrapper levels made it
+                     match nearly everything.)
+    Key("33071d")    exact full name (no "##" strip) — collection keys
+    Lora             type of the value the draw_state renders
+    callable         predicate fn(ds) -> bool
+
+Resolution requires UNIQUENESS: zero matches raise NoMatch, several raise
+Ambiguous listing each candidate's minimal_path — the error is the
+disambiguation. String sugar: "Loras/[1]/alpha" parses to ("Loras", 1,
+"alpha"); tuples are the full-power form (Key/type/callable segments).
+
+Everything takes an optional `universe` (iterable of draw_states) so the
+resolver is headless-testable on fakes; the default universe is the live
+cache (Melty.cache.key_to_draw_state), with draw_states under a CLOSED
+window filtered out (their tiles persist across sessions but are not on
+screen). Persisted-but-collapsed subtrees DO resolve — deciding whether a
+resolved target is actually hittable is the gate check's job, not the
+resolver's.
+"""
+
+
+class Key:
+    """Exact full-name segment (collection keys): matches str(ds.name)
+    verbatim, no "##" stripping."""
+
+    __slots__ = ("key",)
+
+    def __init__(self, key):
+        self.key = key
+
+    def __repr__(self):
+        return f"Key({self.key!r})"
+
+
+class NoMatch(LookupError):
+    def __init__(self, path, hint=""):
+        self.path = path
+        super().__init__(f"no draw_state matches {format_path(path)}"
+                         + (f" ({hint})" if hint else ""))
+
+
+class Ambiguous(LookupError):
+    def __init__(self, path, candidates):
+        self.path = path
+        self.candidates = candidates
+        options = ", ".join(format_path(c) for c in candidates[:8])
+        super().__init__(f"{format_path(path)} matches {len(candidates)} targets — "
+                         f"use one of: {options}")
+
+
+def format_path(path):
+    if isinstance(path, str):
+        return repr(path)
+    parts = []
+    for segment in path:
+        if isinstance(segment, int):
+            parts.append(f"[{segment}]")
+        elif isinstance(segment, Key):
+            parts.append(f"{{{segment.key}}}")
+        elif isinstance(segment, type):
+            parts.append(segment.__name__)
+        elif callable(segment):
+            parts.append(getattr(segment, "__name__", "<predicate>"))
+        else:
+            parts.append(str(segment))
+    return "/".join(parts)
+
+
+def parse(path):
+    """String sugar -> segment tuple. "Loras/[1]/alpha" -> ("Loras", 1,
+    "alpha"). Tuples/lists pass through. Key/type/callable segments exist
+    only in tuple form."""
+    if not isinstance(path, str):
+        return tuple(path)
+    segments = []
+    for raw in path.split("/"):
+        raw = raw.strip()
+        if not raw:
+            continue
+        if raw.startswith("[") and raw.endswith("]"):
+            segments.append(int(raw[1:-1]))
+        elif raw.startswith("{") and raw.endswith("}"):
+            segments.append(Key(raw[1:-1]))
+        else:
+            segments.append(raw)
+    if not segments:
+        raise ValueError("empty path")
+    return tuple(segments)
+
+
+def display_name(ds):
+    name = getattr(ds, "name", None)
+    return str(name).split("##")[0] if name is not None else ""
+
+
+def full_name(ds):
+    name = getattr(ds, "name", None)
+    return str(name) if name is not None else ""
+
+
+def ancestor_chain(ds, cap=64):
+    """ds's ancestors, nearest first (ds itself excluded). Follows `_parent`;
+    the root's _parent is ITSELF, which terminates the walk."""
+    chain = []
+    node = getattr(ds, "_parent", None)
+    while node is not None and node is not ds and len(chain) < cap:
+        chain.append(node)
+        parent = getattr(node, "_parent", None)
+        if parent is node:
+            break
+        node, ds = parent, node
+    return chain
+
+
+def _under_closed_window(ds):
+    node, steps = ds, 0
+    while node is not None and steps < 64:
+        if getattr(node, "closed", False):
+            return True
+        window = getattr(node, "parent_window", None)
+        if window is None or window is node:
+            return False
+        node, steps = window, steps + 1
+    return False
+
+
+# Per-frame memo of the live universe and its name index:
+# (frame_count, cache size, nodes, index). The orchestrator's precondition
+# refresh resolves a few hundred paths per pass (minimal_path tries every
+# suffix of every candidate), and each used to build the universe (an
+# _under_closed_window walk per draw_state) and scan it once per segment
+# until it - ~5.6 M segment_matches, 480 ms every 20 frames on a session
+# with 5.5k draw_states (profiled 09-01). Now: one build per frame, and a
+# name segment is a dict lookup.
+_UNIVERSE_MEMO = None
+
+
+class _Index:
+    """Name lookups over one universe list: display name (the "##"-stripped
+    str(ds.name)) and full name → the nodes carrying it, in universe order.
+    Type / predicate segments still scan the nodes."""
+    __slots__ = ("nodes", "by_display", "by_full")
+
+    def __init__(self, nodes):
+        self.nodes = nodes
+        by_display, by_full = {}, {}
+        for ds in nodes:
+            name = getattr(ds, "name", None)
+            if name is None:
+                continue
+            full = str(name)
+            by_full.setdefault(full, []).append(ds)
+            by_display.setdefault(full.split("##")[0], []).append(ds)
+        self.by_display, self.by_full = by_display, by_full
+
+
+def default_universe():
+    global _UNIVERSE_MEMO
+    from meltygui.core.melty import Melty
+    cache = getattr(Melty, "cache", None)
+    if cache is None:
+        return []
+    key = (Melty.frame_count, len(cache.key_to_draw_state))
+    memo = _UNIVERSE_MEMO
+    if memo is not None and memo[0] == key:
+        return memo[2]
+    nodes = [ds for ds in cache.key_to_draw_state.values()
+             if ds is not None and not _under_closed_window(ds)]
+    _UNIVERSE_MEMO = (key, None, nodes, None)
+    return nodes
+
+
+def _index_for(universe):
+    """The _Index over `universe` — memoized beside the per-frame default
+    universe (identity match), built per call for a caller-supplied list."""
+    global _UNIVERSE_MEMO
+    memo = _UNIVERSE_MEMO
+    if memo is not None and memo[2] is universe:
+        if memo[3] is None:
+            _UNIVERSE_MEMO = memo = (memo[0], None, universe, _Index(universe))
+        return memo[3]
+    return _Index(universe)
+
+
+def segment_matches(segment, ds):
+    if isinstance(segment, str):
+        return display_name(ds) == segment
+    if isinstance(segment, (bool, int)):   # ordinals are handled by the caller
+        return False
+    if isinstance(segment, Key):
+        return full_name(ds) == segment.key
+    if isinstance(segment, type):
+        value = getattr(ds, "_raw_input_value", None)
+        return value is not None and isinstance(value, segment)
+    if callable(segment):
+        try:
+            return bool(segment(ds))
+        except Exception:
+            return False
+    return False
+
+
+def _visual_order(matches):
+    return sorted(matches, key=lambda ds: (getattr(ds, "abs_top", 0) or 0,
+                                           getattr(ds, "abs_left", 0) or 0))
+
+
+def _matches_in_scope(segment, scope, universe, index=None):
+    """Every universe node matching `segment` with `scope` among its
+    ancestors (scope None = anywhere). One hop of the path = descendant
+    matching at any depth, which is what makes nesting the caller's
+    non-problem. With an `index`, a name / Key segment reads its
+    candidates off the name tables instead of scanning the universe."""
+    found = []
+    if index is not None and isinstance(segment, str):
+        candidates = index.by_display.get(segment, ())
+    elif index is not None and isinstance(segment, Key):
+        candidates = index.by_full.get(segment.key, ())
+    else:
+        candidates = universe
+    for ds in candidates:
+        if not segment_matches(segment, ds):
+            continue
+        # STRICT descendants only: a scope never matches its own next
+        # segment. A path is a subsequence of the ANCESTOR chain (module
+        # docstring), so "name/name" names a child called name below a
+        # parent called name - draw_str's row "name" wrapping the editor
+        # "name##innder" - and must not also match the parent alone (it
+        # did, and the text field's chain resolved byously, 09-01).
+        if scope is not None and not any(a is scope for a in ancestor_chain(ds)):
+            continue
+        found.append(ds)
+    return found
+
+
+def _resolve_set(segments, scopes, universe, index=None):
+    """Segment-at-a-time descent (equivalent to subsequence matching for
+    named segments). An int segment indexes the VISUALLY-ORDERED result of
+    the remaining path within the current scopes and returns that single
+    node — "the nth ⟨rest⟩ here"."""
+    if not segments:
+        return scopes
+    head, rest = segments[0], segments[1:]
+    if isinstance(head, int) and not isinstance(head, bool):
+        results = _visual_order(_resolve_set(rest, scopes, universe, index))
+        return [results[head]] if 0 <= head < len(results) else []
+    next_scopes, seen = [], set()
+    for scope in scopes:
+        for ds in _matches_in_scope(head, scope, universe, index):
+            if id(ds) not in seen:
+                seen.add(id(ds))
+                next_scopes.append(ds)
+    return _resolve_set(rest, next_scopes, universe, index)
+
+
+def find_all(path, within=None, universe=None):
+    segments = parse(path)
+    if universe is None:
+        universe = default_universe()
+    elif not isinstance(universe, list):
+        universe = list(universe)
+    return _resolve_set(segments, [within], universe, _index_for(universe))
+
+
+def resolve(path, within=None, universe=None):
+    """The path's unique live target, or a teaching error: NoMatch names the
+    path, Ambiguous lists each candidate as its own minimal_path so the
+    error message IS the disambiguation."""
+    matches = find_all(path, within=within, universe=universe)
+    if len(matches) == 1:
+        return matches[0]
+    if not matches:
+        raise NoMatch(parse(path))
+    exact = _exact_chain_matches(parse(path), matches)
+    if len(exact) == 1:
+        return exact[0]
+    if universe is None:
+        universe = default_universe()
+    raise Ambiguous(parse(path),
+                    [minimal_path(ds, universe=universe) for ds in matches])
+
+
+def _exact_chain_matches(segments, matches):
+    """The tie-break behind an ambiguous path: candidates whose name chain
+    ends with the path CONTIGUOUSLY (no skipped levels). A recorded chain
+    is a node's MAXIMAL capture, so a live node whose chain is exactly
+    that is the node it was captured from — while a same-named descendant
+    (a live-view window `scores` holding a voxel view `scores`: the
+    window's own chain also matches the child as a subsequence) is only a
+    loose match. Name segments only; a path with an ordinal / Key / type
+    segment has no chain to compare and gets no tie-break."""
+    if not segments or not all(isinstance(seg, str) for seg in segments):
+        return []
+    tail = tuple(segments)
+    return [ds for ds in matches if name_chain(ds)[-len(tail):] == tail]
+
+
+def name_chain(ds, cap=64):
+    """Root-first display names of ds's ancestry + itself, unnamed levels
+    skipped. This is what cues CAPTURE (maximal); minimal_path trims LATE."""
+    names = [display_name(node) for node in reversed(ancestor_chain(ds, cap))]
+    names.append(display_name(ds))
+    return tuple(name for name in names if name)
+
+
+def minimal_path(ds, universe=None):
+    """Shortest name-suffix of ds's chain that resolves uniquely in
+    `universe` — computed against the tree it must disambiguate within,
+    never at capture time. Falls back to the full chain when even that is
+    ambiguous (twins: caller needs an ordinal segment)."""
+    if universe is None:
+        universe = default_universe()
+    elif not isinstance(universe, list):
+        universe = list(universe)
+    chain = name_chain(ds)
+    if not chain:
+        return chain
+    index = _index_for(universe)     # same index for every suffix tried
+    for length in range(1, len(chain) + 1):
+        suffix = chain[-length:]
+        matches = _resolve_set(suffix, [None], universe, index)
+        if len(matches) == 1:
+            return suffix
+    return chain