smithy-engine 0.6.0__tar.gz

smithy_engine-0.6.0/.github/workflows/ci.yml

@@ -0,0 +1,75 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+    branches: [master, main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.11"
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+      - run: uv pip install --system ruff
+      - name: Ruff check
+        run: ruff check src/ tests/ examples/
+      - name: Ruff format check
+        run: ruff format --check src/ tests/ examples/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.11"
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+      - run: uv pip install --system -e ".[dev]"
+      - name: Mypy strict
+        run: mypy src/smithy --strict
+
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.11", "3.14"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.11"
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install (with windows extras on windows runners)
+        run: uv pip install --system -e ".[dev,windows]"
+      - name: Pytest
+        run: pytest tests/ -q
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.11"
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+      - name: Build sdist and wheel
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

smithy_engine-0.6.0/.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  id-token: write # PyPI trusted publishing
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "0.11"
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+      - name: Build sdist and wheel
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

smithy_engine-0.6.0/.gitignore

@@ -0,0 +1,25 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.venv/
+venv/
+*.egg
+.env
+
+# Test artifacts
+selectors.json
+selectors1.json
+selectors2.json
+selectors3.json
+test_output.txt
+
+# Lockfile (library, not app)
+uv.lock
+
+# Smith Studio (private, paid product)
+apps/smith-studio/

smithy_engine-0.6.0/CHANGELOG.md

@@ -0,0 +1,144 @@
+# Changelog
+
+## 0.5.0
+
+Playwright-style codegen: recorded flows render as runnable bot scripts.
+
+### Added
+
+- Code generation (`windows/tools/selector_capture/emit.py`): any
+  capture file (`single`/`series`/`record` — same `nodes` shape)
+  renders as a `Smithy(tools=windows_tools())` script with one
+  `await bot.*` call per node. New `emit` CLI subcommand
+  (`emit -i flow.json -o bot.py [--clip]`) plus `--emit BOT.py` on
+  every record mode for one-pass record-to-code.
+- Honest placeholders instead of silent gaps: a `TODO` header for the
+  unseen app launch (`process_run` + PID scoping), `text="TODO: fill
+  in"` for series-mode `input_text` (keys are never captured), and
+  `WARNING` comments from static selector-fragility scoring.
+
+## 0.4.1
+
+Unified capture output: every recorder mode writes the same flow shape.
+
+### Changed
+
+- `single` mode now writes `{"tool": "selector-capture", "nodes":
+  [...]}` with one ranked node (same shape as `series`/`record`)
+  instead of the divergent `captures`/`best_selector` format. The node
+  `args` is the ranked minimal selector, `full_path` is attached, and
+  numeric control types are translated — previously `best_selector`
+  carried the raw `"50011"` the runtime rejects. The `-d`/
+  `--description` flag is still accepted but only logged, not persisted.
+
+### Fixed
+
+- Series-mode `windows.input_text` nodes were missing `full_path`
+  (keyboard flushes built nodes without the last clicked element's
+  path) — now every node carries it. Known limitation, now documented:
+  series mode captures the input *target*, not the typed text itself.
+
+## 0.4.0
+
+Playwright-style selector engine for the desktop: ranked selectors with
+uniqueness checks and honest confidence instead of all-fields dumps.
+
+### Added
+
+- Selector ranking (`windows/selector_rank.py`): candidate generation in
+  priority order (automation ID → name + type → class + type, minimal
+  first), static stability scoring (dynamic digits/dates, wildcards, hex
+  runs, long names), live-desktop uniqueness check, `high`/`medium`/`low`
+  confidence with warnings. Low confidence means "add an anchor", never
+  a made-up stable selector.
+- `ElementSelector.count_from_desktop(limit)` — bounded tree walk for
+  counting matches (strict-mode primitive; dev-time helper, not a runtime
+  search path).
+- `resolve_element(..., strict=True)` — fail on ambiguous selectors
+  (2+ matches → `InvalidInput`) instead of silently taking the first.
+- `generate_nodes_from_config()` — flow nodes from an already-ranked
+  minimal config.
+- Record mode now ranks every capture: logs the winning selector,
+  confidence, and warnings, and emits nodes from the ranked config
+  (falls back to the unranked dump if the UIA walk fails).
+
+### Fixed
+
+- Real captures carry numeric control types (`"50000"`) which the
+  runtime rejects — `build_inline_selector` now translates them to names
+  (`"button"`) and drops untranslatable ones.
+
+## 0.3.0
+
+GUI batch: comfortable desktop automation on top of the 0.2.0 core.
+
+### Added
+
+- Ten new Windows tools: `windows.scroll` (wheel over element/point),
+  `windows.hover` (menus, tooltips), `windows.exists` (single-lookup
+  boolean), `windows.get_text` (ValuePattern → Name fallback),
+  `windows.window` (activate/minimize/maximize/restore/move/close by PID
+  via Win32), `windows.select` (dropdown/combobox/list via
+  SelectionItemPattern), `windows.drag` (two endpoints, coordinates or
+  `from_*`/`to_*` selectors), `windows.clipboard` (get/set via
+  `pyperclip`), `windows.list_elements` (direct-children dump for
+  discovering automation IDs), `windows.highlight` (colored rectangle
+  flash for debugging selectors).
+- `Smithy` facade methods for every new tool (`scroll`, `hover`,
+  `exists`, `get_text`, `window`, `select`, `drag`, `clipboard`,
+  `list_elements`, `highlight`), all accepting an optional `handle` for
+  PID scoping.
+- Shared `_resolve.py` helpers: `resolve_point` (coordinates win over
+  selectors) and `resolve_element`.
+
+### Changed
+
+- `windows.click` now takes `button` (left/right), `clicks` (1/2), and
+  `x`/`y` coordinate clicks (double right-click = two `RightClick`
+  calls; no module-level `DoubleClick` exists in `uiautomation`).
+- `windows.wait` now takes `wait_for` (`appear`/`disappear`) with a
+  symmetric poll loop; `PlatformError` mid-poll counts as still present.
+- `smithy[windows]` extra now includes `pyperclip` (clipboard support).
+
+## 0.2.0
+
+First minor release: transactions, config, and hardening on top of the
+0.1.x tool core.
+
+### Added
+
+- Transactional queue model (`core/queue.py`): `Queue` protocol,
+  `InMemoryQueue` / `SqliteQueue` with atomic FIFO claim, lease expiry,
+  `max_attempts` requeue, idempotent add, `run_id` ownership; `HttpQueue`
+  client for the orchestrator (stdlib only, retries on 502–504).
+- REFramework-style runner (`core/transactions.py`): `run_transactions` /
+  `run_transactions_async`, `BusinessError` vs `InfrastructureError`
+  contract, `Cancelled` cooperative stop, background lease heartbeat
+  (capped at 30 min), `on_progress` hook, `TransactionReport`.
+- TOML robot config (`core/config.py`): `load_config` with fail-fast
+  validation (`required` / `must_exist`), frozen attribute-style `Config`,
+  `SMITHY_*` env overlay (`__` nests, TOML-typed values).
+- Schema validation (`core/schema.py`): `ToolRegistry.execute` validates
+  configs against `schema()` (hand-rolled subset, no new deps).
+- Tool-level retries (`core/retry.py`): `RetryTool` wrapper
+  (`attempts` / `delay_ms` / `retry_on`, defaults to `ElementNotFound`).
+- JSONL audit log (`core/logging.py`): `JsonlEventLogger` middleware with
+  `transaction_id`, duration, and error stamped per event.
+- `windows_tools()` factory (`windows/tools/__init__.py`): default tool
+  set in one call, UIA imports stay lazy.
+- `ProcessTool` allowlist is now configurable: constructor param,
+  `SMITHY_ALLOWED_COMMANDS` env override, `allowed_commands` introspection.
+- `parse_control_type()` is public (`windows/selector.py`).
+- Examples: `reframework_bot.py` (dispatcher + performer skeleton),
+  `config_demo.py` with good/broken TOMLs.
+
+### Changed
+
+- Error model consolidated to the single `ToolError` family; the unused
+  legacy `SmithError` / `InvalidParams` / `ContextError` were removed.
+
+## 0.1.1
+
+- Windows UI tools (process, click, wait, delay, screenshot, input_text,
+  keyboard, set_text, get_element), selector capture CLI, middleware
+  event bus, `@tool` decorator, `Smithy` facade.

smithy_engine-0.6.0/PKG-INFO

@@ -0,0 +1,372 @@
+Metadata-Version: 2.5
+Name: smithy-engine
+Version: 0.6.0
+Summary: Free Python RPA engine — create automation bots with simple API
+Author: as-kurosss
+License-Expression: MIT
+Requires-Python: >=3.11
+Provides-Extra: all
+Requires-Dist: mss>=9; extra == 'all'
+Requires-Dist: pillow>=10; extra == 'all'
+Requires-Dist: pynput>=1.7; extra == 'all'
+Requires-Dist: pyperclip>=1.8; extra == 'all'
+Requires-Dist: uiautomation>=2.0.29; extra == 'all'
+Provides-Extra: capture
+Requires-Dist: pynput>=1.7; extra == 'capture'
+Requires-Dist: pyperclip>=1.8; extra == 'capture'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.18; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.0; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.12; extra == 'dev'
+Provides-Extra: windows
+Requires-Dist: mss>=9; extra == 'windows'
+Requires-Dist: pillow>=10; extra == 'windows'
+Requires-Dist: pyperclip>=1.8; extra == 'windows'
+Requires-Dist: uiautomation>=2.0.29; extra == 'windows'
+Description-Content-Type: text/markdown
+
+# Smithy
+
+Free Python RPA engine — create automation bots with simple async API.
+
+## Quick Start
+
+```python
+import asyncio
+from smithy import Smithy
+from smithy.windows.tools import windows_tools
+
+bot = Smithy(tools=windows_tools())
+
+
+async def main() -> None:
+    app = await bot.process_run("notepad.exe")
+    await bot.wait(app, class_name="Notepad", name="*Notepad")
+    await bot.click(app, name="File")
+    await bot.delay(duration_ms=300)
+    await bot.click(app, name="Save As...")
+    await bot.input_text(app, text="hello world")
+    await bot.keyboard(keys="[CTRL]S")
+    await bot.screenshot("notepad.png")
+    await bot.process_stop(app)
+
+
+asyncio.run(main())
+```
+
+## Built-in Tools
+
+- **ProcessTool** (`windows.process`) — launch and stop Windows processes by name
+- **ClickTool** (`windows.click`) — click a UI element or coordinates; `button` (left/right), `clicks` (1/2)
+- **WaitTool** (`windows.wait`) — poll until a UI element appears or disappears (`wait_for`, with timeout)
+- **DelayTool** (`windows.delay`) — pause execution for a fixed duration
+- **ScreenshotTool** (`windows.screenshot`) — capture the screen or a window to a file
+- **InputTextTool** (`windows.input_text`) — type plain text into a UI element
+- **KeyboardTool** (`windows.keyboard`) — send key combos and presses (e.g. `"[CTRL]S"`, `"[CTRL!]"`, `"[ENTER]"`)
+- **SetTextTool** (`windows.set_text`) — replace a UI element's text programmatically (ValuePattern / WM_SETTEXT)
+- **GetElementTool** (`windows.get_element`) — read a UI element's attributes as a dict
+- **ScrollTool** (`windows.scroll`) — scroll the wheel over an element or point (`direction`, `wheel_clicks`)
+- **HoverTool** (`windows.hover`) — move the mouse over an element (menus, tooltips)
+- **ExistsTool** (`windows.exists`) — single-lookup boolean check (no waiting, no raising)
+- **GetTextTool** (`windows.get_text`) — read an element's visible text (ValuePattern → Name)
+- **WindowTool** (`windows.window`) — activate/minimize/maximize/restore/move/close a window by PID
+- **SelectTool** (`windows.select`) — select an item in a dropdown, combobox, or list
+- **DragTool** (`windows.drag`) — drag between two endpoints (coordinates or `from_*`/`to_*` selectors)
+- **ClipboardTool** (`windows.clipboard`) — read/write clipboard text (needs `pyperclip`)
+- **ListElementsTool** (`windows.list_elements`) — list direct children to discover automation IDs
+- **HighlightTool** (`windows.highlight`) — flash a colored rectangle for debugging selectors
+
+All UI tools accept optional `pid` (or a `ProcessHandle`) to scope element search to a specific window.
+
+`ProcessTool` only starts executables from its allowlist — pass
+`windows_tools(allowed_commands=["myapp.exe"])` or set
+`SMITHY_ALLOWED_COMMANDS="myapp.exe,other.exe"` to override the demo list.
+
+## Custom Tools
+
+Create tools from simple async functions:
+
+```python
+from smithy import Smithy, tool
+
+
+@tool("greet", description="Greet a person")
+async def greet(config: dict) -> dict:
+    name = config.get("name", "World")
+    return {"message": f"Hello, {name}!"}
+
+
+bot = Smithy(tools=[greet])
+
+
+async def main() -> None:
+    result = await bot.call("greet", name="Alice")
+    print(result["message"])  # Hello, Alice!
+
+
+asyncio.run(main())
+```
+
+## Transactions (REFramework-style)
+
+The framework owns the Init → Get → Process → SetStatus → End loop over a
+queue (local SQLite file or orchestrator via `HttpQueue`):
+
+```python
+import asyncio
+from smithy import InMemoryQueue, run_transactions_async
+from smithy.core.errors import BusinessError
+
+queue = InMemoryQueue()
+queue.get_or_create_queue("invoices", max_attempts=3)
+
+
+async def process(item) -> dict:
+    if not item.payload.get("number"):
+        raise BusinessError("invoice has no number")  # terminal, no retry
+    return {"posted": True}
+
+
+async def main() -> None:
+    report = await run_transactions_async(queue, "invoices", process)
+    print(report.processed, report.succeeded, report.business_failed)
+
+
+asyncio.run(main())
+```
+
+`BusinessError` marks an item terminally failed; `InfrastructureError` (or
+any unexpected exception) requeues it within the `max_attempts` budget;
+`Cancelled` stops the loop cooperatively. Long items get a background
+lease heartbeat (capped at 30 minutes). See
+[`examples/reframework_bot.py`](examples/reframework_bot.py) for a full
+dispatcher + performer skeleton.
+
+## Robot Config (TOML)
+
+One TOML per robot (replaces the two-column Excel sheet), validated up
+front — the bot fails in Init, never mid-run:
+
+```python
+from smithy import load_config
+
+CONFIG = load_config(
+    "reframework_bot.toml",
+    required=["robot.queue", "paths.workdir"],
+    must_exist=["paths.workdir"],
+)
+print(CONFIG.robot.queue)  # attribute access, frozen after load
+```
+
+Per-environment tweaks without editing TOML via `SMITHY_*` env vars:
+`SMITHY_ROBOT__QUEUE=invoices-prod` overrides `robot.queue` (`__` nests,
+values are TOML-typed). Secrets never live here — only references to
+orchestrator assets. See [`examples/config_demo.py`](examples/config_demo.py).
+
+## Error Handling
+
+```python
+from smithy.core.errors import InvalidInput, ElementNotFound, PlatformError
+
+try:
+    await bot.click(app, name="Nonexistent")
+except ElementNotFound:
+    print("Element not found")
+except PlatformError as e:
+    print(f"Platform error: {e}")
+```
+
+## Selector Ranking (Playwright-style)
+
+Record mode (`record` below) ranks every captured element like
+Playwright's codegen: candidates in priority order (automation ID →
+name + type → class + type), stability scoring, and a live uniqueness
+check. The winning selector ships with `high`/`medium`/`low` confidence
+plus warnings — `low` means the element needs an anchor, not blind trust:
+
+```python
+from smithy.windows.selector_rank import rank_best_selector
+from smithy.windows.tools.selector_capture.capture import capture_at_point
+
+_, sel = capture_at_point(400, 300)
+ranked = rank_best_selector(sel)
+print(ranked.config)  # e.g. {"automation_id": "btnOk"}
+print(ranked.confidence, ranked.warnings)
+```
+
+`resolve_element(..., strict=True)` fails on ambiguous selectors (2+
+matches) instead of taking the first — the desktop equivalent of strict
+mode. Numeric control types from real captures (`"50000"`) are
+translated to names automatically.
+
+## Selector Capture
+
+A dev utility for inspecting UI elements at screen coordinates and generating tool configs:
+
+```bash
+    pip install smithy-engine[capture]
+
+# Single capture mode — one flow node
+python -m smithy.windows.tools.selector_capture single -o selectors.json
+
+# Series mode — auto-record clicks and typing
+python -m smithy.windows.tools.selector_capture series -o recording.json
+
+# Interactive record mode
+python -m smithy.windows.tools.selector_capture record -o flow.json
+```
+
+All three modes write the same shape — `{"tool": "selector-capture",
+"nodes": [{"tool", "args", "full_path"}]}` (`single` is just a
+one-node flow). `args` holds the ranked minimal selector (the
+`best_selector` equivalent), `full_path` the full UIA path for debugging
+and anchors. Note: series mode records click targets with full paths,
+but keyboard input captures only the target element, not the typed text
+itself — fill in `text` afterwards or use record mode.
+
+## Codegen (Playwright-style code recording)
+
+Any capture file renders as a replayable bot script — record once, get
+runnable code:
+
+```bash
+python -m smithy.windows.tools.selector_capture emit -i flow.json -o bot.py
+
+# ...or in one pass, straight from recording:
+python -m smithy.windows.tools.selector_capture record -o flow.json --emit bot.py
+```
+
+The script uses `Smithy(tools=windows_tools())` with one `await bot.*`
+call per node. No magic: the recorder never sees the launched process
+(so there's a `TODO` showing `process_run` + PID scoping), uncaptured
+`input_text` gets an explicit `text="TODO: fill in"` placeholder, and
+fragile selectors ship with `WARNING` comments. Open `bot.py` in your
+editor, fill in the TODOs, run.
+
+## Visual Editor
+
+The flow is built in [smithy-designer](https://github.com/as-kurosss/smithy-engine-designer) —
+a separate visual editor (MIT): drag-and-drop canvas, step debugger with
+breakpoints, XML-like selectors, typed variables.
+
+```bash
+pip install smithy-designer
+smithy-designer flow.json
+```
+
+## Flow format (v2)
+
+The flow file is a versioned JSON document — the contract between the
+designer, the file on disk, and the execution engine. The schema lives in
+[`schemas/flow-v2.schema.json`](schemas/flow-v2.schema.json).
+
+Compatibility rules:
+
+- **adding optional fields does not bump the version** — unknown keys are
+  ignored by older readers (`label`, `breakpoints` were added this way);
+- **removing/renaming fields or changing semantics requires v3** and a
+  migration path; readers must reject unknown versions with an explicit error;
+- the engine and the designer both validate `version` on load and never
+  silently overwrite a file of a different version.
+
+Example:
+
+```json
+{
+  "version": 2,
+  "nodes": [
+    { "id": "start", "kind": "start", "config": {}, "position": [120, 160] },
+    { "id": "a1", "kind": "tool", "tool": "windows.click",
+      "config": { "name": "OK", "control_type": "Button" },
+      "save_as": "result", "position": [340, 160] }
+  ],
+  "edges": [
+    { "id": "e1", "source": "start", "source_handle": "out", "target": "a1" }
+  ]
+}
+```
+
+## Install
+
+```bash
+pip install smithy-engine             # core (no deps)
+pip install smithy-engine[windows]     # Windows UIA tools
+pip install smithy-engine[capture]     # selector capture (pynput + pyperclip)
+pip install smithy-engine[all]         # everything
+pip install -e ".[dev]"            # development
+```
+
+## Development
+
+```bash
+# Using uv (recommended)
+uv venv .venv
+.venv\Scripts\activate
+uv pip install -e ".[dev,windows,capture]"
+
+# Or with pip
+python -m venv .venv
+.venv\Scripts\activate
+pip install -e ".[dev,windows,capture]"
+
+pytest                    # run tests
+ruff check src/ tests/    # linter
+mypy src/smithy --strict  # type check
+```
+
+## Project Structure
+
+```
+src/smithy/
+├── __init__.py          — Public API: Smithy, ProcessHandle, Tool, errors
+├── facade.py            — Smithy facade (async tool dispatch)
+├── core/
+│   ├── tool.py          — Tool protocol, AbstractTool, @tool decorator
+│   ├── registry.py      — ToolRegistry (name → tool dispatch, schema validation)
+│   ├── schema.py        — Hand-rolled JSON Schema subset validator
+│   ├── retry.py         — RetryTool (attempts / delay / retry_on)
+│   ├── logging.py       — JsonlEventLogger (JSONL audit log middleware)
+│   ├── config.py        — TOML robot config + SMITHY_* env overlay
+│   ├── queue.py         — Queue protocol, InMemoryQueue, SqliteQueue
+│   ├── http_queue.py    — HttpQueue client for the orchestrator
+│   ├── transactions.py  — REFramework-style runner + heartbeat
+│   ├── events.py        — EventBus, ToolEvent, Middleware
+│   └── errors.py        — Error hierarchy (ToolError, ElementNotFound, etc.)└── windows/
+    ├── element.py       — SafeUIElement (thread-safe COM wrapper)
+    ├── selector.py      — ElementSelector (UIA tree search + match counting)
+    ├── selector_rank.py — Selector ranking (candidates, scoring, confidence)
+    └── tools/
+        ├── process.py          — ProcessTool
+        ├── click.py            — ClickTool (button/clicks/coordinates)
+        ├── wait.py             — WaitTool (appear/disappear)
+        ├── delay.py            — DelayTool
+        ├── screenshot.py       — ScreenshotTool
+        ├── input_text.py       — InputTextTool
+        ├── keyboard.py         — KeyboardTool
+        ├── set_text.py         — SetTextTool
+        ├── get_element.py      — GetElementTool
+        ├── scroll.py           — ScrollTool
+        ├── hover.py            — HoverTool
+        ├── exists.py           — ExistsTool
+        ├── get_text.py         — GetTextTool
+        ├── window.py           — WindowTool
+        ├── select.py           — SelectTool
+        ├── drag.py             — DragTool
+        ├── clipboard.py        — ClipboardTool
+        ├── list_elements.py    — ListElementsTool
+        ├── highlight.py        — HighlightTool
+        ├── _resolve.py         — Shared element/point resolution helpers
+        └── selector_capture/   — Dev tool for UI inspection + codegen
+```
+
+## Examples
+
+- [`examples/basic_bot.py`](examples/basic_bot.py) — Launch Notepad and interact with its UI
+- [`examples/custom_tool.py`](examples/custom_tool.py) — Create and use custom tools
+- [`examples/reframework_bot.py`](examples/reframework_bot.py) — REFramework skeleton: dispatcher + performer over a queue
+- [`examples/config_demo.py`](examples/config_demo.py) — Load and validate a TOML robot config
+
+## License
+
+MIT