seedcode-cli 6.1.5__py3-none-any.whl

seedcode/computer/vision.py

@@ -0,0 +1,327 @@
+"""Vision driver: the agent's eyes on the desktop.
+
+The primary source of truth is the Windows UI Automation tree — real
+elements (buttons, inputs, menus, dialogs) with exact coordinates, described
+as text so EVERY provider can use desktop mode, not just multimodal ones.
+Screenshots complement it for image-capable models, and OCR (pytesseract,
+if the user happens to have it) is a best-effort fallback for windows that
+expose no automation tree (games, some custom-drawn apps).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# Bound the tree walk: deep UIA trees (browsers) can hold thousands of nodes.
+MAX_ELEMENTS = 150
+MAX_DEPTH = 12
+
+# Control types worth reporting to the model (interactive or informative).
+_INTERESTING_TYPES = {
+    "ButtonControl": "button",
+    "EditControl": "input",
+    "ComboBoxControl": "combobox",
+    "CheckBoxControl": "checkbox",
+    "RadioButtonControl": "radio",
+    "HyperlinkControl": "link",
+    "MenuItemControl": "menuitem",
+    "MenuControl": "menu",
+    "TabItemControl": "tab",
+    "ListItemControl": "listitem",
+    "TextControl": "text",
+    "DocumentControl": "document",
+    "WindowControl": "dialog",
+    "TitleBarControl": "titlebar",
+    "ToolBarControl": "toolbar",
+    "TreeItemControl": "treeitem",
+    "SliderControl": "slider",
+}
+
+
+@dataclass(slots=True)
+class UIElement:
+    """One visible UI element with its clickable center point."""
+
+    role: str
+    name: str
+    x: int  # center
+    y: int  # center
+    width: int
+    height: int
+    enabled: bool
+    # Secondary UIA properties for the resolver's tier-2 matching. Empty when
+    # the element (or the platform) does not expose them.
+    automation_id: str = ""
+    value: str = ""
+    help_text: str = ""
+
+    def describe(self) -> str:
+        state = "" if self.enabled else " (disabled)"
+        name = self.name[:80] if self.name else "(unnamed)"
+        return f'{self.role} "{name}" at ({self.x}, {self.y}){state}'
+
+
+def snapshot(window_title: str | None = None) -> tuple[str, list[UIElement]]:
+    """UI-tree snapshot of the active (or named) window.
+
+    Returns (window title, elements). Raises ValueError when the target
+    window cannot be found.
+    """
+    import uiautomation as auto
+
+    if window_title:
+        root = auto.WindowControl(searchDepth=1, SubName=window_title)
+        if not root.Exists(maxSearchSeconds=2):
+            raise ValueError(f"No window found matching '{window_title}'.")
+    else:
+        root = auto.GetForegroundControl()
+        if root is None:
+            raise ValueError("No foreground window to inspect.")
+        top = root.GetTopLevelControl()
+        if top is not None:
+            root = top
+
+    elements: list[UIElement] = []
+    _walk(root, elements, depth=0)
+    return (root.Name or "(untitled window)", elements)
+
+
+def _walk(control, out: list[UIElement], depth: int) -> None:
+    if len(out) >= MAX_ELEMENTS or depth > MAX_DEPTH:
+        return
+    for child in control.GetChildren():
+        if len(out) >= MAX_ELEMENTS:
+            return
+        try:
+            type_name = child.ControlTypeName
+            role = _INTERESTING_TYPES.get(type_name)
+            rect = child.BoundingRectangle
+            visible = rect is not None and rect.width() > 0 and rect.height() > 0
+            if role is not None and visible:
+                name = (child.Name or "").strip()
+                # Skip anonymous static text: it adds noise, not targets.
+                if not (role == "text" and not name):
+                    out.append(
+                        UIElement(
+                            role=role,
+                            name=name,
+                            x=rect.left + rect.width() // 2,
+                            y=rect.top + rect.height() // 2,
+                            width=rect.width(),
+                            height=rect.height(),
+                            enabled=bool(child.IsEnabled),
+                            automation_id=_safe_prop(child, "AutomationId"),
+                            value=_value_of(child),
+                            help_text=_safe_prop(child, "HelpText"),
+                        )
+                    )
+        except Exception:
+            # A single flaky COM element must not kill the whole snapshot.
+            continue
+        _walk(child, out, depth + 1)
+
+
+def _safe_prop(control, attr: str) -> str:
+    """Read a UIA string property, tolerating COM hiccups and absence."""
+    try:
+        val = getattr(control, attr, "")
+        return str(val).strip() if val else ""
+    except Exception:
+        return ""
+
+
+def _value_of(control) -> str:
+    """The ValuePattern text of a control (e.g. an input's contents), if any."""
+    try:
+        pattern = control.GetValuePattern()
+        return str(pattern.Value or "").strip()
+    except Exception:
+        return ""
+
+
+def describe_snapshot(title: str, elements: list[UIElement]) -> str:
+    """Model-facing text rendering of a snapshot."""
+    if not elements:
+        return (
+            f'Window "{title}" exposes no UI Automation elements '
+            "(custom-drawn app?). Use desktop_screenshot and OCR/vision instead."
+        )
+    lines = [f'Window "{title}" — {len(elements)} elements:']
+    lines += [f"  - {el.describe()}" for el in elements]
+    if len(elements) >= MAX_ELEMENTS:
+        lines.append(f"  ... (truncated at {MAX_ELEMENTS} elements)")
+    return "\n".join(lines)
+
+
+def element_at(x: int, y: int) -> str:
+    """Describe the UI element under a point (used to verify actions)."""
+    try:
+        import uiautomation as auto
+
+        control = auto.ControlFromPoint(x, y)
+        if control is None:
+            return "nothing"
+        role = _INTERESTING_TYPES.get(control.ControlTypeName, control.ControlTypeName)
+        name = (control.Name or "").strip()[:80]
+        return f'{role} "{name or "(unnamed)"}"'
+    except Exception:
+        return "unknown"
+
+
+def ocr_available() -> bool:
+    """Whether OCR can genuinely run here.
+
+    Checks the engine, not just the Python wrapper: ``pytesseract`` imports
+    fine without ``tesseract.exe``, and reporting OCR as available on that
+    basis made every call fail at the point of use. See :mod:`.ocr`.
+    """
+    from . import ocr
+
+    return ocr.available()
+
+
+# --- computer vision / image matching (optional, opencv-backed) --------------
+
+def cv_available() -> bool:
+    """Whether OpenCV is importable (the CV and image-match ladder tiers)."""
+    import importlib.util
+
+    return importlib.util.find_spec("cv2") is not None
+
+
+def template_locate(
+    image_path, template_path, threshold: float = 0.87
+) -> tuple[int, int, int, int] | None:
+    """Locate a reference image (``template_path``) inside a screenshot.
+
+    The **image-matching** ladder tier: skills that ship a small reference PNG
+    (an icon, a logo, a button with no accessibility name) can point the
+    resolver at it. Returns the best match's (left, top, width, height) when the
+    normalized-correlation score clears ``threshold``, else None. Uses OpenCV;
+    returns None when OpenCV is unavailable so the resolver falls through.
+    """
+    if not cv_available():
+        return None
+    try:
+        import cv2  # type: ignore
+        import numpy as np  # type: ignore
+
+        haystack = cv2.imread(str(image_path), cv2.IMREAD_GRAYSCALE)
+        needle = cv2.imread(str(template_path), cv2.IMREAD_GRAYSCALE)
+        if haystack is None or needle is None:
+            return None
+        th, tw = needle.shape[:2]
+        if th == 0 or tw == 0 or th > haystack.shape[0] or tw > haystack.shape[1]:
+            return None
+        result = cv2.matchTemplate(haystack, needle, cv2.TM_CCOEFF_NORMED)
+        _min_v, max_v, _min_l, max_l = cv2.minMaxLoc(result)
+        if max_v < threshold:
+            return None
+        left, top = int(max_l[0]), int(max_l[1])
+        return (left, top, int(tw), int(th))
+    except Exception:
+        return None
+
+
+def refine_region_cv(
+    image_path, box: tuple[int, int, int, int]
+) -> tuple[int, int, int, int]:
+    """Snap an OCR text box out to the clickable control that contains it.
+
+    The **computer-vision** ladder tier. Custom-drawn buttons expose no
+    accessibility tree; OCR finds the *label* but its center may sit on text
+    rather than the true hit target. This finds the smallest rectangular
+    contour enclosing the label's center and returns that box, so the click
+    lands on the control body. Falls back to the original box when OpenCV is
+    unavailable or no better contour is found.
+    """
+    if not cv_available():
+        return box
+    try:
+        import cv2  # type: ignore
+
+        img = cv2.imread(str(image_path))
+        if img is None:
+            return box
+        left, top, width, height = box
+        cx, cy = left + width // 2, top + height // 2
+        gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+        edges = cv2.Canny(gray, 50, 150)
+        edges = cv2.dilate(edges, None, iterations=1)
+        contours, _ = cv2.findContours(edges, cv2.RETR_LIST, cv2.CHAIN_APPROX_SIMPLE)
+        best = None
+        best_area = None
+        for cnt in contours:
+            bx, by, bw, bh = cv2.boundingRect(cnt)
+            # Must contain the label center and be at least as large as the text.
+            if bx <= cx <= bx + bw and by <= cy <= by + bh and bw >= width and bh >= height:
+                area = bw * bh
+                if best_area is None or area < best_area:
+                    best, best_area = (bx, by, bw, bh), area
+        return best or box
+    except Exception:
+        return box
+
+
+def ocr_screenshot(image_path) -> str:
+    """Best-effort OCR of a screenshot."""
+    if not ocr_available():
+        from . import ocr as ocr_module
+
+        _ok, reason = ocr_module.status()
+        return (
+            f"OCR is unavailable ({reason}). The UI Automation snapshot "
+            "(computer_see) is the primary way to read the screen."
+        )
+    try:
+        import pytesseract
+        from PIL import Image
+
+        with Image.open(image_path) as img:
+            text = pytesseract.image_to_string(img)
+        return text.strip() or "(no text recognised)"
+    except Exception as exc:
+        return f"OCR failed: {exc}"
+
+
+def ocr_locate(image_path, phrase: str) -> tuple[int, int, int, int] | None:
+    """Find ``phrase`` on a screenshot; return its (left, top, width, height).
+
+    Used by the element resolver as the fallback path for windows that expose
+    no UI Automation tree. Matches a run of consecutive OCR words whose joined
+    text contains the phrase (case-insensitive), and returns the bounding box
+    that spans them. Returns None when the phrase is not found or OCR is
+    unavailable — the resolver then reports the element as unresolvable.
+    """
+    if not ocr_available():
+        return None
+    try:
+        import pytesseract
+        from PIL import Image
+
+        want = " ".join((phrase or "").lower().split())
+        if not want:
+            return None
+        with Image.open(image_path) as img:
+            data = pytesseract.image_to_data(img, output_type=pytesseract.Output.DICT)
+    except Exception:
+        return None
+
+    words = data.get("text", [])
+    n = len(words)
+    # Slide a window of up to the phrase's word-count over the OCR words and
+    # accept the first run whose joined text contains the phrase.
+    span = max(1, len(want.split()))
+    for i in range(n):
+        for length in range(1, span + 1):
+            if i + length > n:
+                break
+            chunk = " ".join(w for w in words[i : i + length] if w).lower().strip()
+            if chunk and want in chunk:
+                lefts = [data["left"][k] for k in range(i, i + length)]
+                tops = [data["top"][k] for k in range(i, i + length)]
+                rights = [data["left"][k] + data["width"][k] for k in range(i, i + length)]
+                bottoms = [data["top"][k] + data["height"][k] for k in range(i, i + length)]
+                left, top = min(lefts), min(tops)
+                return (left, top, max(rights) - left, max(bottoms) - top)
+    return None

seedcode/computer/windows.py

@@ -0,0 +1,217 @@
+"""Window management driver: list, focus, open, and close applications.
+
+Window enumeration and focus use ``pygetwindow`` (Win32 under the hood).
+Opening applications goes through ``os.startfile``/``start`` semantics so
+anything resolvable by the shell (path, registered app, document) works.
+Closing is graceful first (WM_CLOSE) with a ``taskkill`` fallback by name.
+
+**Self-protection:** every lookup skips SeedCode's own console window (see
+:mod:`.selfguard`). Title matching here is substring-based, so without the
+guard a request like "close the browser" could resolve to — and terminate —
+the very terminal SeedCode is running in. Controlling our own window is
+deliberately impossible; closing *SeedCode* is the REPL's /exit decision,
+never a window operation.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from dataclasses import dataclass
+from typing import Any
+
+from . import selfguard
+
+
+@dataclass(slots=True)
+class WindowInfo:
+    """One top-level window as reported to the model."""
+
+    title: str
+    left: int
+    top: int
+    width: int
+    height: int
+    active: bool
+    minimized: bool
+    # Identity metadata (0 when the platform doesn't expose it): the owning
+    # process lets the app controller match windows to launches, and the raw
+    # handle lets semantic actions drive windows precisely. Our own console
+    # is reported with pid=0/hwnd=0 so no matching logic can ever pick it.
+    pid: int = 0
+    hwnd: int = 0
+
+    def describe(self) -> str:
+        state = "active" if self.active else ("minimized" if self.minimized else "open")
+        return (
+            f'"{self.title}" [{state}] at ({self.left}, {self.top}) '
+            f"size {self.width}x{self.height}"
+        )
+
+
+def _gw():
+    import pygetwindow
+
+    return pygetwindow
+
+
+def _window_pid_hwnd(win: Any) -> tuple[int, int]:
+    """Owning process id + handle of a pygetwindow window (0, 0 when unknown).
+
+    ``pygetwindow`` exposes the raw handle as ``_hWnd``; the pid comes from
+    Win32. Failures degrade to (0, 0) — matching code must treat that as
+    "unknown", never as a match.
+    """
+    hwnd = getattr(win, "_hWnd", 0) or 0
+    pid = 0
+    if sys.platform == "win32" and hwnd:
+        try:
+            import ctypes
+
+            pid_val = ctypes.wintypes.DWORD()
+            ctypes.windll.user32.GetWindowThreadProcessId(hwnd, ctypes.byref(pid_val))
+            pid = int(pid_val.value)
+        except Exception:
+            pid = 0
+    return pid, int(hwnd)
+
+
+def list_windows() -> list[WindowInfo]:
+    """All titled top-level windows, active one first."""
+    gw = _gw()
+    active = gw.getActiveWindow()
+    active_handle = getattr(active, "_hWnd", None)
+    windows = []
+    for win in gw.getAllWindows():
+        if not (win.title or "").strip():
+            continue
+        if selfguard.is_own_window(win):
+            continue  # never report the terminal running SeedCode
+        pid, hwnd = _window_pid_hwnd(win)
+        windows.append(
+            WindowInfo(
+                title=win.title,
+                left=int(win.left),
+                top=int(win.top),
+                width=int(win.width),
+                height=int(win.height),
+                active=getattr(win, "_hWnd", None) == active_handle,
+                minimized=bool(win.isMinimized),
+                pid=pid,
+                hwnd=hwnd,
+            )
+        )
+    windows.sort(key=lambda w: not w.active)
+    return windows
+
+
+def active_window() -> WindowInfo | None:
+    """The focused window, or None when nothing is focused."""
+    win = _gw().getActiveWindow()
+    if win is None or not (win.title or "").strip():
+        return None
+    if selfguard.is_own_window(win):
+        return None  # our console is invisible to desktop logic
+    pid, hwnd = _window_pid_hwnd(win)
+    return WindowInfo(
+        title=win.title,
+        left=int(win.left),
+        top=int(win.top),
+        width=int(win.width),
+        height=int(win.height),
+        active=True,
+        minimized=bool(win.isMinimized),
+        pid=pid,
+        hwnd=hwnd,
+    )
+
+
+def _find(title_substring: str):
+    """First window whose title contains ``title_substring`` (case-insensitive).
+
+    SeedCode's own console is invisible to this lookup: focusing, closing, or
+    otherwise acting on the terminal hosting the agent is always a mistake.
+    """
+    needle = title_substring.strip().lower()
+    if not needle:
+        raise ValueError("Window title (or part of it) is required.")
+    for win in _gw().getAllWindows():
+        if selfguard.is_own_window(win):
+            continue  # never target the terminal running SeedCode
+        if needle in (win.title or "").lower():
+            return win
+    raise ValueError(f"No window found matching '{title_substring}'.")
+
+
+def focus_window(title_substring: str) -> WindowInfo | None:
+    """Bring a window to the foreground; returns the new active window."""
+    win = _find(title_substring)
+    if win.isMinimized:
+        win.restore()
+    win.activate()
+    return active_window()
+
+
+def open_app(target: str) -> str:
+    """Launch an application or open a document via the shell.
+
+    ``target`` is anything the Windows shell can resolve: an exe name on
+    PATH, a full path, or a registered app (e.g. "notepad", "calc").
+    ShellExecute via ``os.startfile`` first (documents, App Paths), then a
+    detached ``start`` as fallback — never waiting on the launched process,
+    which would hang until the app exits.
+    """
+    import os
+
+    target = target.strip()
+    if not target:
+        raise ValueError("Application name or path is required.")
+    try:
+        os.startfile(target)  # noqa: S606 - deliberate shell-open semantics
+        return f"Launched '{target}'."
+    except OSError:
+        pass
+    # Fallback: 'start' resolves PATH executables and shell aliases. The
+    # process is detached (no inherited pipes) so this returns immediately.
+    try:
+        subprocess.Popen(
+            f'start "" "{target}"',
+            shell=True,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            stdin=subprocess.DEVNULL,
+        )
+    except OSError as exc:
+        raise RuntimeError(f"Could not open '{target}': {exc}")
+    return f"Launched '{target}'."
+
+
+def close_window(title_substring: str, force: bool = False) -> str:
+    """Close a window gracefully (WM_CLOSE); ``force`` kills the process.
+
+    Refuses outright when the target *is* our own console: closing SeedCode
+    is an explicit /exit decision made by the user in the REPL, never a
+    side effect of a desktop task. The ``taskkill`` fallback is additionally
+    title-guarded so a force-kill can never match our terminal by prefix.
+    """
+    if selfguard.is_own_title(title_substring):
+        raise ValueError(
+            "Refusing to close SeedCode's own terminal. Use /exit in the "
+            "REPL to quit SeedCode."
+        )
+    win = _find(title_substring)
+    title = win.title
+    win.close()
+    if force:
+        # Best-effort process kill for apps that ignore WM_CLOSE. The window
+        # filter is matched as a prefix, so pin it away from our own title.
+        if selfguard.is_own_title(title):
+            return f"Closed '{title}'."  # graceful close succeeded; skip the kill
+        subprocess.run(
+            f'taskkill /FI "WINDOWTITLE eq {title}*" /F',
+            shell=True,
+            capture_output=True,
+            text=True,
+            timeout=15,
+        )
+    return f"Closed '{title}'."

seedcode/config/__init__.py

@@ -0,0 +1,8 @@
+"""Configuration system: load/save the app config and its defaults."""
+
+from __future__ import annotations
+
+from .defaults import CONFIG_FILENAME, ENV_KEYS
+from .manager import load_config, save_config
+
+__all__ = ["CONFIG_FILENAME", "ENV_KEYS", "load_config", "save_config"]

seedcode/config/defaults.py

@@ -0,0 +1,22 @@
+"""Configuration defaults and environment overrides.
+
+Kept import-light (no project imports) so it can be referenced from anywhere
+without risk of an import cycle.
+"""
+
+from __future__ import annotations
+
+# Environment variables that override stored API keys (CI / power users),
+# keyed by provider id. Ollama needs no key so it has no entry. Values are
+# tuples so a provider can accept several variable names if ever needed.
+ENV_KEYS: dict[str, tuple[str, ...]] = {
+    "openrouter": ("OPENROUTER_API_KEY",),
+    # One FreeModel account key works on both FreeModel backends; each
+    # provider still stores it in its OWN config slot.
+    "freemodel_claude": ("FREEMODEL_API_KEY",),
+    "freemodel_codex": ("FREEMODEL_API_KEY",),
+    "aerolink": ("AEROLINK_API_KEY",),
+}
+
+# Filename of the JSON config document within the per-user app directory.
+CONFIG_FILENAME = "config.json"

seedcode/config/manager.py

@@ -0,0 +1,62 @@
+"""Configuration loading and saving for Seed Code.
+
+The config is a single JSON document under ``~/.seedcode/config.json``. Loading
+is fault-tolerant: a missing or corrupt file yields sane defaults rather than a
+crash, honouring the rule "never crash". Saving is best-effort for the same
+reason (a locked or full disk must not kill the session).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+from ..core.models import AppConfig
+from ..utils.helpers import config_path, restrict_permissions
+from ..utils.logger import get_logger
+from .defaults import ENV_KEYS
+
+_log = get_logger("config")
+
+
+def load_config() -> AppConfig:
+    """Load configuration from disk, falling back to defaults on any error."""
+    path = config_path()
+    config = AppConfig()
+
+    if path.exists():
+        try:
+            raw = json.loads(path.read_text(encoding="utf-8"))
+            config = AppConfig.model_validate(raw)
+            _log.info("config loaded from %s", path)
+        except (json.JSONDecodeError, ValueError, OSError) as exc:
+            # Corrupt or unreadable config -> start from defaults instead of dying.
+            _log.warning("config unreadable (%s); using defaults", exc)
+            config = AppConfig()
+    else:
+        _log.info("no config file yet (first run)")
+
+    # Explicit environment variables always win over stored API keys.
+    for provider_id, env_names in ENV_KEYS.items():
+        for env_name in env_names:
+            env_key = os.environ.get(env_name, "").strip()
+            if env_key:
+                config.set_api_key(provider_id, env_key)
+                _log.info("api key for %s taken from %s", provider_id, env_name)
+                break
+
+    return config
+
+
+def save_config(config: AppConfig) -> None:
+    """Persist configuration to disk (best-effort, owner-only permissions)."""
+    path = config_path()
+    try:
+        path.write_text(
+            json.dumps(config.model_dump(), indent=2, ensure_ascii=False),
+            encoding="utf-8",
+        )
+        restrict_permissions(path)
+    except OSError as exc:
+        # Settings still apply for this session; only persistence failed.
+        _log.error("could not save config to %s: %s", path, exc)

seedcode/core/__init__.py

@@ -0,0 +1,31 @@
+"""Core logic: data models, provider backends, chat engine, streaming."""
+
+from __future__ import annotations
+
+from .chat import ChatEngine, ChatError
+from .models import AppConfig, Message
+from .providers import (
+    PROVIDERS,
+    ModelInfo,
+    Provider,
+    ProviderError,
+    ValidationResult,
+    get_provider,
+    provider_label,
+)
+from .streaming import iter_stream
+
+__all__ = [
+    "AppConfig",
+    "ChatEngine",
+    "ChatError",
+    "Message",
+    "ModelInfo",
+    "PROVIDERS",
+    "Provider",
+    "ProviderError",
+    "ValidationResult",
+    "get_provider",
+    "iter_stream",
+    "provider_label",
+]