Examples

The snippets below use symbols exported directly from the qontinui package. Action methods are asynchronous coroutines, so they run inside an async function driven by asyncio.

The Action class is the central dispatcher for GUI operations. Its convenience helpers find() and click() accept StateImage targets and return an ActionResult:

import asyncio
from qontinui import Action, StateImage, Image


async def main():
    action = Action()

    # A StateImage wraps the image used to identify an element
    login_button = StateImage(
        image=Image.from_file("images/login_button.png"),
        name="login_button",
    )

    # Find returns an ActionResult with the matches that were located
    result = await action.find(login_button)
    if result.success:
        print(f"Found {len(result.matches)} match(es)")

    # Click chains Find -> Click for StateImage targets
    await action.click(login_button)


asyncio.run(main())

FindOptions controls how matching behaves — the similarity threshold, whether to return all matches, and an optional search region to constrain the search:

from qontinui import FindOptions, Region

options = FindOptions(
    similarity=0.85,        # 0.0-1.0; higher means a stricter match
    find_all=True,          # return every match, not just the first
    search_region=Region(   # limit the search to a rectangular area
        x=0, y=0, width=800, height=600, name="top_left_quadrant"
    ),
    timeout=5.0,            # seconds to keep retrying before giving up
)

print(options.similarity, options.find_all, options.search_region.width)

Qontinui includes a self-healing system that recovers from element lookup failures using action caching, multi-scale visual search, and optional LLM assistance. Configure it once, then opt in per find via FindOptions:

from qontinui import configure_healing, HealingConfig, FindOptions

# Configure the self-healing system (call once at startup)
configure_healing(HealingConfig.with_ollama())

# Opt in to healing for a specific find
options = FindOptions(
    similarity=0.85,
    enable_healing=True,
    healing_context_description="Submit button",
    use_cache=True,
    store_in_cache=True,
)

For websites that publish an AI Web Action Standard (AWAS) manifest, Qontinui can discover and execute typed actions directly over HTTP — no visual templates required:

import asyncio
from qontinui.awas.discovery import AwasDiscoveryService
from qontinui.awas.executor import AwasExecutor


async def main():
    # Discover the AWAS manifest for a site
    discovery = AwasDiscoveryService()
    manifest = await discovery.discover("https://example.com")

    # List the actions the site exposes
    for action in manifest.actions:
        print(f"{action.method} {action.endpoint}: {action.intent}")

    # Execute a typed action with parameters
    executor = AwasExecutor()
    result = await executor.execute(
        manifest=manifest,
        action_id="list_items",
        params={"limit": 10},
    )
    print(result)


asyncio.run(main())