manul-engine 0.0.5__py3-none-any.whl

manul_engine/__init__.py

@@ -0,0 +1,27 @@
+# manul_engine/__init__.py
+"""
+ManulEngine — AI-powered browser automation engine.
+
+Package structure:
+    manul_engine/
+        __init__.py    — public API (re-exports ManulEngine)
+        prompts.py     — configuration, thresholds, LLM prompts
+        helpers.py     — pure utility functions and timing constants
+        js_scripts.py  — JavaScript injected into the browser page
+        scoring.py     — heuristic element-scoring algorithm
+        cache.py       — persistent per-site controls cache mixin
+        core.py        — ManulEngine class (LLM, resolution, mission runner)
+        actions.py     — action execution mixin (click, type, select, hover, drag…)
+        test/
+            test_*.py  — synthetic DOM unit tests
+
+Usage:
+    from manul_engine import ManulEngine
+
+    manul = ManulEngine()
+    await manul.run_mission("1. Navigate to ...")
+"""
+
+from .core import ManulEngine
+
+__all__ = ["ManulEngine"]

manul_engine/__main__.py

@@ -0,0 +1,6 @@
+# manul_engine/__main__.py
+"""Entry point for `python -m manul_engine`."""
+
+from manul_engine.cli import sync_main
+
+sync_main()

manul_engine/_test_runner.py

@@ -0,0 +1,143 @@
+# manul_engine/_test_runner.py
+"""
+Internal synthetic DOM test runner (developer tool — not part of the public CLI).
+
+Invoked from the repository dev launcher::
+
+    python manul.py test
+
+Runs all test_*.py suites inside manul_engine/test/ against locally rendered
+HTML pages (no real websites, no internet required).
+
+End users of the installed package do not have access to this command.
+"""
+
+import importlib
+import io
+import os
+import re
+import sys
+
+
+# Directory that holds synthetic test_*.py suites (available when running from
+# a source checkout; these tests are not packaged into the installed wheel).
+_PKG_DIR = os.path.dirname(os.path.abspath(__file__))
+_TEST_DIR = os.path.join(_PKG_DIR, "test")
+
+
+class _Tee:
+    """Duplicate stdout to a log file."""
+
+    def __init__(self, path: str) -> None:
+        self._term = sys.stdout
+        self._file = open(path, "w", encoding="utf-8")
+
+    def write(self, msg: str) -> None:
+        self._term.write(msg)
+        self._file.write(msg)
+
+    def flush(self) -> None:
+        self._term.flush()
+        self._file.flush()
+
+    def isatty(self) -> bool:
+        return False
+
+    @property
+    def term(self):
+        return self._term
+
+    def close(self) -> None:
+        self._file.close()
+
+
+async def run_tests(log_path: str) -> bool:
+    """
+    Discover and run all test_*.py suites in manul_engine/test/.
+
+    Returns True if every suite passed, False otherwise.
+    Writes a full log to *log_path*.
+    """
+    # Force heuristics-only, deterministic execution for the synthetic suite.
+    # MANUL_AI_THRESHOLD=0 prevents any LLM calls even if the developer has
+    # MANUL_MODEL set in their shell.
+    os.environ["MANUL_CONTROLS_CACHE_ENABLED"] = "False"
+    os.environ["MANUL_AI_THRESHOLD"] = "0"
+    try:
+        from manul_engine import prompts as _prompts
+        _prompts.CONTROLS_CACHE_ENABLED = False
+        _prompts.ENV_AI_THRESHOLD = 0
+    except Exception:
+        pass
+
+    # Ensure UTF-8 output on Windows / misconfigured terminals.
+    if sys.stdout.encoding and sys.stdout.encoding.lower() != "utf-8":
+        sys.stdout = io.TextIOWrapper(
+            sys.stdout.detach(), encoding="utf-8", errors="replace", line_buffering=True
+        )
+
+    tee = _Tee(log_path)
+    real_stdout = sys.stdout
+    score_lines: list[str] = []
+
+    class _ScoreTee:
+        def write(self, msg: str) -> None:
+            real_stdout.write(msg)
+            tee._file.write(msg)
+            for line in msg.splitlines():
+                if "SCORE:" in line:
+                    score_lines.append(line.strip())
+
+        def flush(self) -> None:
+            real_stdout.flush()
+            tee._file.flush()
+
+        def isatty(self) -> bool:
+            return False
+
+    sys.stdout = _ScoreTee()
+
+    test_files = sorted(
+        f[:-3]
+        for f in os.listdir(_TEST_DIR)
+        if f.startswith("test_") and f.endswith(".py")
+    )
+
+    all_ok = True
+    suite_results: list[tuple[str, int, int]] = []
+
+    try:
+        for mod_name in test_files:
+            mod = importlib.import_module(f"manul_engine.test.{mod_name}")
+            runner = getattr(mod, "run_laboratory", None) or getattr(mod, "run_suite", None)
+            if runner is None:
+                continue
+            before = len(score_lines)
+            ok = await runner()
+            if not ok:
+                all_ok = False
+            for sl in score_lines[before:]:
+                m = re.search(r"(\d+)/(\d+)", sl)
+                if m:
+                    suite_results.append((mod_name, int(m.group(1)), int(m.group(2))))
+
+        total_passed = sum(p for _, p, _ in suite_results)
+        total_tests = sum(t for _, _, t in suite_results)
+
+        print(f"\n\n{'=' * 70}")
+        print("🐾 SYNTHETIC DOM LABORATORY SUMMARY")
+        print(f"{'=' * 70}")
+        for name, p, t in suite_results:
+            icon = "✅" if p == t else "❌"
+            label = name.replace("test_", "").replace("_", " ").upper()
+            print(f"   {icon} {label:<30} {p:>4}/{t}")
+        print(f"{'─' * 70}")
+        print(f"   {'TOTAL':<30} {total_passed:>4}/{total_tests}")
+        if total_passed == total_tests:
+            print("\n🏆 ALL TESTS PASSED — THE ENGINE IS UNBREAKABLE!")
+        print(f"{'=' * 70}")
+    finally:
+        sys.stdout = real_stdout
+        tee.close()
+
+    return all_ok

manul_engine/actions.py

@@ -0,0 +1,400 @@
+# manul_engine/actions.py
+import asyncio
+import re
+from .helpers import extract_quoted, compact_log_field, SCROLL_WAIT, ACTION_WAIT, NAV_WAIT
+from .js_scripts import VISIBLE_TEXT_JS, EXTRACT_DATA_JS, DEEP_TEXT_JS, STATE_CHECK_JS
+from . import prompts
+
+class _ActionsMixin:
+    def _fmt_el_name(self, name: object) -> str:
+        return compact_log_field(name, "MANUL_LOG_NAME_MAXLEN")
+
+    def _remember_resolved_control(
+        self,
+        *,
+        page,
+        cache_key: tuple,
+        mode: str,
+        search_texts: list[str],
+        target_field: str | None,
+        element: dict,
+    ) -> None:
+        self.learned_elements[cache_key] = {
+            "name": str(element.get("name", "")),
+            "tag": str(element.get("tag_name", "")),
+        }
+        persist = getattr(self, "_persist_control_cache_entry", None)
+        if callable(persist):
+            try:
+                persist(
+                    page=page,
+                    mode=mode,
+                    search_texts=search_texts,
+                    target_field=target_field,
+                    element=element,
+                )
+            except (OSError, ValueError, TypeError) as exc:
+                print(f"    ⚠️  CONTROL CACHE: persist skipped ({type(exc).__name__})")
+
+    async def _handle_navigate(self, page, step: str) -> bool:
+        url = re.search(r'(https?://[^\s\'"<>]+)', step)
+        if not url: return False
+        await page.goto(url.group(1), wait_until="domcontentloaded", timeout=prompts.NAV_TIMEOUT)
+        self.last_xpath = None
+        await asyncio.sleep(NAV_WAIT)
+        return True
+
+    async def _handle_scroll(self, page, step: str):
+        step_l = step.lower()
+        if "inside" in step_l or "list" in step_l:
+            await page.evaluate("const d=document.querySelector('#dropdown')||document.querySelector('[class*=\"dropdown\"]');if(d)d.scrollTop=d.scrollHeight;")
+        else:
+            await page.evaluate("window.scrollBy(0, window.innerHeight)")
+        await asyncio.sleep(SCROLL_WAIT)
+
+    async def _handle_extract(self, page, step: str) -> bool:
+        var_m  = re.search(r'\{(.*?)\}', step)
+        target = (extract_quoted(step) or [""])[0].replace("'", "")
+        print("    ⚙️  DOM HEURISTICS: Extracting data via JS…")
+
+        step_lower = step.lower()
+        hint = ""
+        m_hint = re.search(r'extract\s+(.+?)\s+into\b', step_lower)
+        if m_hint:
+            raw = m_hint.group(1)
+            raw = re.sub(r"'[^']*'", "", raw).strip()
+            for w in ("the", "of", "from", "a", "an", "text", "value"):
+                raw = re.sub(rf'\b{w}\b', '', raw).strip()
+            hint = raw.strip()
+        
+        currency_hint = ""
+        curr_m = re.search(r'([$€£₴¥₹])', step)
+        if curr_m:
+            currency_hint = curr_m.group(1)
+        for cw, cs in [("uah", "UAH"), ("pln", "PLN"), ("eur", "€"), ("gbp", "£"), ("usd", "$")]:
+            if cw in step_lower.split():
+                currency_hint = cs
+                break
+
+        val = await page.evaluate(EXTRACT_DATA_JS, [target.lower(), hint, currency_hint])
+
+        if val and var_m:
+            val = val.strip()
+            if hint and ':' in val:
+                m_lbl = re.match(r'^([A-Za-z][A-Za-z0-9 ]+?)\s*:\s+(.+)$', val)
+                if m_lbl:
+                    label_part = m_lbl.group(1).lower()
+                    value_part = m_lbl.group(2).strip()
+                    hint_ws = set(re.findall(r'[a-z]{3,}', hint.lower()))
+                    label_ws = set(re.findall(r'[a-z]{3,}', label_part))
+                    if hint_ws & label_ws:
+                        val = value_part
+            
+            self.memory[var_m.group(1)] = val
+            print(f"    📦 COLLECTED: {val}")
+            return True
+        return False
+
+    async def _handle_verify(self, page, step: str) -> bool:
+        expected = extract_quoted(step)
+        step_no_quotes = re.sub(r"'[^']*'", "", step)
+        is_negative = bool(re.search(r'\b(NOT|HIDDEN|ABSENT)\b', step_no_quotes.upper()))
+        state_check = "disabled" if re.search(r'\bDISABLED\b', step.upper()) else "enabled" if re.search(r'\bENABLED\b', step.upper()) else None
+        is_checked_verify = bool(re.search(r'\bchecked\b', step.lower()))
+
+        msg = f"    ⚙️  DOM HEURISTICS: Scanning for {expected}"
+        if is_negative: msg += " [MUST BE ABSENT]"
+        if state_check: msg += f" [{state_check.upper()}]"
+        if is_checked_verify: msg += " [CHECKED]"
+        print(msg)
+
+        for retry in range(15):
+            if is_checked_verify:
+                raw_els = await self._snapshot(page, "clickable", [t.lower() for t in expected])
+                scored  = self._score_elements(raw_els, step, "clickable", expected, None, False)
+                if scored:
+                    best   = scored[0]
+                    xpath  = best["xpath"]
+                    loc    = page.locator(f"xpath={xpath}").first
+                    try: checked = await loc.is_checked(timeout=2000)
+                    except Exception: checked = False
+                    if is_negative:
+                        ok = not checked
+                        if ok:
+                            print(f"    {'✅' if ok else '❌'} Checkbox not-checked={ok}")
+                            return ok
+                    else:
+                        if checked:
+                            print(f"    {'✅' if checked else '❌'} Checkbox checked={checked}")
+                            return checked
+                if retry < 14:
+                    await asyncio.sleep(1)
+                    continue
+                return False
+
+            if state_check:
+                search_text = expected[0] if expected else ""
+                disabled_result = await page.evaluate(STATE_CHECK_JS, [search_text, state_check])
+                
+                if disabled_result is not None:
+                    icon = '✅' if disabled_result else '❌'
+                    print(f"    {icon} Element {state_check}={disabled_result}")
+                    return disabled_result
+                if retry < 14:
+                    await asyncio.sleep(1)
+                    continue
+                return False
+
+            text = await page.evaluate(VISIBLE_TEXT_JS)
+            found = all(t.lower() in text for t in expected) if expected else bool(text)
+            
+            if not found and not is_negative:
+                text2 = await page.evaluate(DEEP_TEXT_JS)
+                found = all(t.lower() in text2 for t in expected) if expected else bool(text2)
+                
+            if is_negative:
+                if not found:
+                    print(f"    ✅ Verified ABSENT — OK")
+                    return True
+                if retry < 14:
+                    await asyncio.sleep(1)
+                    continue
+                print(f"    ❌ Text still present after retries")
+                return False
+            else:
+                if found:
+                    print(f"    ✅ Verified — OK")
+                    return True
+                if retry < 14:
+                    await asyncio.sleep(1.5)
+                    continue
+                print(f"    ❌ Not found after retries: {expected}")
+                return False
+        return False
+
+    async def _do_drag(self, page, step: str, expected: list[str], source_id: int) -> bool:
+        step_l = step.lower()
+        target_text = ""
+        m_to = re.search(r"to\s+['\"](.+?)['\"]", step_l)
+        if m_to: target_text = m_to.group(1)
+        elif len(expected) >= 2: target_text = expected[-1]
+
+        raw_els = await self._snapshot(page, "drag", [target_text])
+        dest = next((el for el in raw_els if el["id"] != source_id and target_text.lower() in el["name"].lower()), None)
+        if not dest: return False
+
+        src_el = next((el for el in raw_els if el["id"] == source_id), raw_els[0])
+        src_loc  = page.locator(f"xpath={src_el['xpath']}").first
+        dest_loc = page.locator(f"xpath={dest['xpath']}").first
+
+        try:
+            await src_loc.drag_to(dest_loc, timeout=5000)
+        except Exception:
+            sb = await src_loc.bounding_box()
+            db = await dest_loc.bounding_box()
+            if sb and db:
+                await page.mouse.move(sb["x"] + sb["width"]/2, sb["y"] + sb["height"]/2)
+                await page.mouse.down()
+                await asyncio.sleep(0.3)
+                await page.mouse.move(db["x"] + db["width"]/2, db["y"] + db["height"]/2, steps=20)
+                await page.mouse.up()
+
+        print(f"    🖱️  Dragged → '{self._fmt_el_name(dest.get('name', ''))}'")
+        await asyncio.sleep(ACTION_WAIT)
+        return True
+
+    async def _execute_step(self, page, step: str, strategic_context: str = "") -> bool:
+        step_l = step.lower()
+        words  = set(re.findall(r'\b[a-z]+\b', step_l))
+
+        if   "drag" in words and "drop" in words:              mode = "drag"
+        elif "select" in words or "choose" in words:           mode = "select"
+        elif any(w in words for w in ("type","fill","enter")): mode = "input"
+        elif any(w in words for w in ("click","double","check","uncheck")): mode = "clickable"
+        elif "hover" in words:                                  mode = "hover"
+        else:                                                   mode = "locate"
+
+        preserve = mode in ("input", "select")
+        expected = extract_quoted(step, preserve_case=preserve)
+
+        target_field = None
+        txt_to_type  = ""
+        search_texts = []
+
+        if mode == "input" and expected:
+            txt_to_type  = expected[-1]
+            search_texts = expected[:-1]
+            m = re.search(r'(?:into\s+the\s+|into\s+)([a-zA-Z0-9_]+)\s*field', step_l)
+            if m and m.group(1) not in ("that", "the", "a", "an"): target_field = m.group(1).lower()
+        else:
+            search_texts = expected
+
+        if search_texts or target_field:
+            self.last_xpath = None
+
+        is_optional = bool(re.search(r'\bif\s+exists\b|\boptional\b', re.sub(r'''["'][^"']*["']''', '', step_l)))
+        cache_key = (mode, tuple(t.lower() for t in search_texts), target_field)
+        failed_ids = set()
+
+        for attempt in range(3):
+            try:
+                el = await self._resolve_element(page, step, mode, search_texts, target_field, strategic_context, failed_ids=failed_ids)
+            except Exception:
+                if is_optional: return True
+                raise
+
+            if el is None:
+                if is_optional: return True
+                if attempt < 2:
+                    print("    🔄 Target not found or rejected by AI. Scrolling and retrying...")
+                    await page.evaluate("window.scrollBy(0, window.innerHeight / 2)")
+                    await asyncio.sleep(1)
+                    continue
+                else:
+                    if mode != "locate":
+                        print("    💀 SELF-HEALING FAILED: No valid elements found after retries.")
+                    return False
+
+            if el["id"] in failed_ids: continue
+
+            self.last_xpath = el["xpath"]
+            name, xpath, is_sel, is_shad, el_id, tag, itype = el["name"], el["xpath"], el.get("is_select"), el.get("is_shadow"), el["id"], el.get("tag_name", ""), el.get("input_type", "")
+
+            if mode == "input" and itype in ("radio", "checkbox", "button", "submit", "image"):
+                failed_ids.add(el_id)
+                self.last_xpath = None
+                continue
+
+            if mode == "locate":
+                try:
+                    loc = page.locator(f"xpath={xpath}").first
+                    if not is_shad: 
+                        await loc.scroll_into_view_if_needed(timeout=2000)
+                        await self._highlight(page, loc)
+                    else:
+                        await self._highlight(page, el_id, by_js_id=True)
+                except Exception: pass
+                print(f"    🔍 Located '{self._fmt_el_name(name)}'")
+                return True
+
+            if mode == "drag": return await self._do_drag(page, step, expected, el_id)
+
+            loc = page.locator(f"xpath={xpath}").first
+            try:
+                if not is_shad: 
+                    await loc.scroll_into_view_if_needed(timeout=2000)
+                    await self._highlight(page, loc)
+                else:
+                    await self._highlight(page, el_id, by_js_id=True)
+            except Exception: pass
+
+            try:
+                if mode == "input":
+                    print(f"    ⌨️  Typed '{txt_to_type}' → '{self._fmt_el_name(name)}'")
+                    if is_shad: await page.evaluate(f"window.manulType({el_id}, '{txt_to_type}')")
+                    else:
+                        is_readonly = await loc.evaluate("el => el.readOnly || el.hasAttribute('readonly')")
+                        if is_readonly:
+                            escaped = txt_to_type.replace("'", "\\'")
+                            await page.evaluate(f"el => {{ el.removeAttribute('readonly'); el.value = '{escaped}'; el.dispatchEvent(new Event('input', {{bubbles:true}})); el.dispatchEvent(new Event('change', {{bubbles:true}})); }}", await loc.element_handle())
+                        else:
+                            await loc.fill("", timeout=3000)
+                            await loc.type(txt_to_type, delay=50, timeout=3000)
+                    if "enter" in step_l:
+                        await page.keyboard.press("Enter")
+                        await asyncio.sleep(4)
+                    self._remember_resolved_control(
+                        page=page,
+                        cache_key=cache_key,
+                        mode=mode,
+                        search_texts=search_texts,
+                        target_field=target_field,
+                        element=el,
+                    )
+                    self.last_xpath = None
+                    return True
+
+                elif mode == "select":
+                    if is_sel:
+                        opts = [expected[0]] if expected else [list(set(re.findall(r'\b[a-z0-9]{3,}\b', step_l)))[0]]
+                        try: await loc.select_option(label=opts, timeout=3000)
+                        except Exception: await loc.select_option(value=[o.lower() for o in opts], timeout=3000)
+                    else: 
+                        print(f"    🖱️  Clicked (Custom Select) '{self._fmt_el_name(name)}'")
+                        try:
+                            await loc.click(force=True, timeout=3000)
+                        except Exception:
+                            await page.evaluate(f"window.manulClick({el_id})")
+                        
+                        if expected:
+                            await asyncio.sleep(0.5) 
+                            option_text = expected[0]
+                            print(f"    🖱️  Selecting option '{option_text}'")
+                            try:
+                                opt_loc = page.locator(f"[role='option']:has-text('{option_text}'), [role='menuitem']:has-text('{option_text}')").first
+                                await opt_loc.click(timeout=3000)
+                            except Exception:
+                                try:
+                                    opt_loc = page.locator(f"text='{option_text}'").last
+                                    await opt_loc.click(timeout=3000)
+                                except Exception: pass
+                                
+                    self._remember_resolved_control(
+                        page=page,
+                        cache_key=cache_key,
+                        mode=mode,
+                        search_texts=search_texts,
+                        target_field=target_field,
+                        element=el,
+                    )
+                    await asyncio.sleep(ACTION_WAIT)
+                    return True
+
+                elif mode == "hover":
+                    print(f"    🚁  Hovered '{self._fmt_el_name(name)}'")
+                    if is_shad: await page.evaluate(f"window.manulElements[{el_id}].dispatchEvent(new MouseEvent('mouseover',{{bubbles:true,cancelable:true,view:window}}))")
+                    else: await loc.hover(force=True, timeout=3000)
+                    self._remember_resolved_control(
+                        page=page,
+                        cache_key=cache_key,
+                        mode=mode,
+                        search_texts=search_texts,
+                        target_field=target_field,
+                        element=el,
+                    )
+                    await asyncio.sleep(ACTION_WAIT)
+                    return True
+
+                else:
+                    print(f"    🖱️  Clicked '{self._fmt_el_name(name)}'")
+                    if is_shad:
+                        fn = "manulDoubleClick" if "double" in step_l else "manulClick"
+                        await page.evaluate(f"window.{fn}({el_id})")
+                        await asyncio.sleep(ACTION_WAIT)
+                    else:
+                        if "double" in step_l:
+                            await loc.dblclick(force=True, timeout=3000)
+                        elif itype in ("checkbox", "radio", "file"):
+                            await loc.evaluate("el => el.click()")
+                        else:
+                            await loc.click(force=True, timeout=3000)
+                            if itype == "submit" or (tag == "button" and itype in ("", "submit")):
+                                try: await page.wait_for_load_state("networkidle", timeout=10_000)
+                                except Exception: await asyncio.sleep(3.0)
+                        await asyncio.sleep(ACTION_WAIT)
+                    self._remember_resolved_control(
+                        page=page,
+                        cache_key=cache_key,
+                        mode=mode,
+                        search_texts=search_texts,
+                        target_field=target_field,
+                        element=el,
+                    )
+                    return True
+
+            except Exception as ex:
+                failed_ids.add(el_id)
+                self.last_xpath = None
+                await asyncio.sleep(1)
+
+        return False