TaskArc Documentation

The complete reference for building bots with the TaskArc Engine.

TaskArc allows you to write standard Python 3.11 code while leveraging a proprietary engine for Computer Vision and UI Automation. The IDE handles the heavy lifting of environment setup, leaving you to focus on logic.

Engine Note: The functions documented below are wrappers from bot.py. The underlying implementation (cv_engine, win_ocr) is compiled and optimized for Windows.

Installation

TaskArc is fully portable. No installation of Python or libraries is required on the host machine.

Unzip the TaskArc_Alpha.zip package.
Move the folder to a desired location (e.g., C:\TaskArc).
Run TaskArcIDE.exe.

Note: Do not delete the runtime folder. This contains the embedded Python environment required for the bots to execute.

Quick Start: "Hello Notepad"

Follow these steps to build your first automation.

1. Setup

Open TaskArc and go to File > New Project. Name it HelloBot.

2. Write Logic

The IDE pre-imports everything you need from bot. Copy this code:

from bot import *
import subprocess

# 1. Launch Notepad
subprocess.Popen("notepad.exe")
wait(2) # Wait for UI to load

# 2. Type Text
type("Hello from TaskArc!")
type(Key.ENTER)
type("Automating Windows is easy.")

# 3. Save File (Ctrl + S)
type("s", Key.CTRL)
wait(1)

# 4. Handle Save Dialog
type("test_file.txt")
type(Key.ENTER)

3. Execute

Press F5 or click RUN BOT. The IDE will minimize, and you will see Notepad open and type automatically.

Best Practices & Architecture

To ensure your bots are maintainable and commercial-grade, adhere to the following structure.

Project Structure

/MyProject
  ├── /Architecture
  │     ├── db_config.json    # Database Credentials
  │     └── requirements.txt  # External Libraries
  ├── /Assets                 # Visual Anchors (PNGs)
  ├── main.py                 # Entry Point
  └── changelog.json          # Auto-generated History

Visual Anchors vs. UI Elements

TaskArc supports two methods of interaction. Knowing when to use which is key.

Method	Pros	Cons	Use Case
UI Elements	Fastest, 100% Accuracy, works in background.	Can fail on custom/legacy apps (Java/Citrix).	Standard Windows Apps, Web Forms.
Visual Anchors	Works on anything visible (Citrix, RDP, Games).	Slower, sensitive to resolution changes.	Legacy Apps, Remote Desktops.

API Reference: Core Actions

These functions are available globally in your script.

click(target, ...)

Moves the mouse to the target and clicks.

Parameter	Type	Description
target	Union	Can be an Image Path (`"assets/btn.png"`), a Coordinate Tuple `(x, y)`, or a UI Element Object.
offset	tuple	(Optional) Pixel offset `(x, y)` from the center of the target.
confidence	float	(Optional) 0.0 to 1.0. Strictness of image matching. Default: `0.9`.
timeout	int	(Optional) Seconds to wait for target to appear. Default: `10`.

type(*args)

Simulates keyboard input. Automatically pauses if the Watcher detects an interruption.

Usage	Example
String	`type("Hello World")`
Key Constant	`type(Key.ENTER)`, `type(Key.TAB)`
Hotkey	`type("c", Key.CTRL)` (Presses Ctrl+C)

API Reference: Finders

wait_for(target, timeout=10)

Halts script execution until the target is found. Raises TimeoutError if matched failed.

exists(target)

Returns True/False immediately. Useful for conditional logic (e.g., checking if a login screen appeared).

API Reference: OCR Engine

Safeguarded wrapper around the OS-level OCR API.

read_text(x, y, w, h)

Captures the defined screen region and extracts text using Windows Media OCR.

Parameter	Description
x, y	Top-left coordinates of the region.
w, h	Width and Height of the region.
Returns	`str` - The raw text found in the region.

API Reference: Database

Abstracts SQL connections based on the db_config.json file.

db_fetch(alias, query, params=None)

Executes a SELECT query.

Parameter	Description
alias	The name of the DB connection defined in Tools.
query	Standard SQL query string.
Returns	`list[dict]` - Rows as dictionaries.

The Watcher Protocol

The Watcher is a unique feature of TaskArc. It runs a secondary process to handle unexpected system events.

Standard Implementation

Create a file named watcher.py. This script should contain a loop that scans for known error states.

# watcher.py
from bot import *

while True:
    if exists("assets/update_popup.png"):
        request_interrupt()  # Signals main bot to pause
        click("assets/close_btn.png")
        request_resume()     # Signals main bot to continue
    
    wait(1)