ai-locators 0.1.0

AI-powered locators for Playwright

AI Selectors for Playwright

AI-powered selectors for Playwright, available for both Python and Node.js. These packages allow you to use natural language descriptions to locate elements on a webpage using LLM (Large Language Model) technology.

// 👎 Complex XPath with multiple conditions
page.locator("//div[contains(@class, 'header')]//button[contains(@class, 'login') and not(@disabled) and contains(text(), 'Sign In')]");

// 😎 Using ai-locators
page.locator("ai=the login button in the header that says Sign In");

The AI selector understands your intent and generates the appropriate complex selector for you.

Python Package

Installation

pip install ai-locators

Usage

from playwright.sync_api import sync_playwright
from ai_locators import register_ai_selector

api_key = os.getenv("OPENAI_API_KEY")
base_url = os.getenv("OPENAI_BASE_URL")
model = "gpt-4o"

with sync_playwright() as p:
    # Need to disable web security for browser to make LLM requests work
    browser = p.chromium.launch(headless=False, args=["--disable-web-security"])
    page = browser.new_page()
    
    # Register the AI selector
    register_ai_selector(p, api_key, base_url, model)
    
    # Navigate to a page
    page.goto("https://playwright.dev/")
    
    # Use the AI selector with natural language
    element = page.locator("ai=get started button")
    element.click()
    
    browser.close()

Node.js Package

Installation

npm install ai-locators

Usage

const { chromium } = require('playwright');
const { registerAISelector } = require('ai-locators');

const apiKey = process.env.OPENAI_API_KEY;
const baseUrl = process.env.OPENAI_BASE_URL;
const model = "gpt-4o";

(async () => {
  const browser = await chromium.launch({
    headless: false,
    args: ["--disable-web-security"]
  });
  const page = await browser.newPage();
  
    await registerAISelector({
      apiKey: apiKey,
      model: model,
      baseUrl: baseUrl,
    });
    console.log("Registered AI selector");
  
  // Navigate to a page
  await page.goto("https://playwright.dev/")
  
  // Use the AI selector with natural language
  const element = page.locator("ai=get started button")
  await element.click();
  console.log("Clicked get started button");
  
  await browser.close();
})();

Plug in your LLM

The packages work with any OpenAI-compatible LLM endpoint. You just need to pass model, api_key and base_url when registering the selector.

For example:

In Python

# OpenAI
register_ai_selector(p, 
    api_key="sk-...",
    base_url="https://api.openai.com/v1",
    model="gpt-4"
)

# Anthropic
register_ai_selector(p,
    api_key="sk-ant-...",
    base_url="https://api.anthropic.com/v1",
    model="claude-3-sonnet-20240229"
)

# Ollama
register_ai_selector(p,
    api_key="ollama",  # not used but required
    base_url="http://localhost:11434/v1",
    model="llama2"
)

# Basically any OpenAI compatible endpoint

In Node.js

// OpenAI
await registerAISelector({
    apiKey: "sk-...",
    baseUrl: "https://api.openai.com/v1",
    model: "gpt-4"
});

// Anthropic
await registerAISelector({
    apiKey: "sk-ant-...",
    baseUrl: "https://api.anthropic.com/v1",
    model: "claude-3-sonnet-20240229"
});

// Ollama
await registerAISelector({
    apiKey: "ollama",  // not used but required
    baseUrl: "http://localhost:11434/v1",
    model: "llama2"
});

// Basically any OpenAI compatible endpoint