Skip to content

Python ‐ 2. AWP Tool

Jump to bottom
Bluera Team edited this page May 28, 2025 · 1 revision

AWP Tool

This project also shares a Universal Tool for your agents to be able reliably understand and interact with the AWP compliant Web pages and APIs.

For more information about Universal Tools, see ◉ Universal Intelligence

Installation

pip install awp

# (if using universal tool) Choose relevant UIN install for your device
pip install "universal-intelligence[community,mps]" # Apple
pip install "universal-intelligence[community,cuda]" # NVIDIA

Usage

Standard

import awp

# Get HTML documentation
html_doc = awp.parse_html(html)

# Get API documentation
api_doc = awp.parse_api(url)
Method Parameters Return Type Description
parse_html • html: str: HTML page to parse
• format: str | None = "YAML": Output format		 Any Parses all AWP ai-* and accessibility attributes on the page and returns a documentation in the requested format (YAML, JSON), usable by any AI agent to reliably understand and interact with that web page
parse_api • url: str: URL of the API to parse
• authorization: str | None = None: Authentication header if required
• format: str | None = "YAML": Output format		 Any Calls the standard /ai-handshake endpoint of that API and returns an OpenAPI compliant documentation of that API in the requested format (YAML, JSON), usable by any AI agent to reliably understand and interact with that API

As Universal Tool 

from awp import UniversalTool as AWP

# Get HTML documentation
html_doc, logs = AWP().parse_html(html)

# Get API documentation
api_doc, logs = AWP().parse_api(url)
Method Parameters Return Type Description
__init__ • verbose: bool | str = "DEFAULT": Enable/Disable logs, or set a specific log level None Initialize a Universal Tool
parse_html • html: str: HTML page to parse
• format: str | None = "YAML": Output format		 Tuple[Any, Dict] Parses all AWP ai-* and accessibility attributes on the page and returns a documentation in the requested format (YAML, JSON), usable by any AI agent to reliably understand and interact with that web page
parse_api • url: str: URL of the API to parse
• authorization: str | None = None: Authentication header if required
• format: str | None = "YAML": Output format		 Tuple[Any, Dict] Calls the standard /ai-handshake endpoint of that API and returns an OpenAPI compliant documentation of that API in the requested format (YAML, JSON), usable by any AI agent to reliably understand and interact with that API
(class).contract None Contract Tool description and interface specification
(class).requirements None List[Requirement] Tool configuration requirements

Example Output

Parse HTML
Input
<html ai-description="Travel site to book flights and trains">
  <body>
    <form 
      ai-description="Form to book a flight" 
      ai-state="pending"
      class="form-booking-flight">
      <h1>
        Book a flight
      </h1>
      <label>
        Where to?
      </label>
      <input
        ai-ref="<input-ai-ref>"
        ai-description="Form input where to enter the destination"
        ai-interactions="input: enables the form confirmation button, given certain constraints;"
        role="destination-input"
        aria-required="true"
        alt="destination input"
        type="text"
        id="destination"
        name="destination"
        required
        minlength="3"
        maxlength="30"
        size="10" />
      <div>
        <button
          ai-description="Confirmation button to proceed with booking a flight"
          ai-interactions="click: proceed; hover: diplay additonal information about possible flights;"
          ai-prerequisite-click="<input-ai-ref>: input destination;"
          ai-next-click="list of available flights; book a flight; login;"
          aria-disabled="true"
          disabled>
          See available flights
        </button>
        <button
          ai-description="Cancel button to get back to the home page"
          ai-interactions="click: dismiss form and return to home page;"
          ai-next-click="access forms to book trains; access forms to book flights;">
          Back
        </button>
      </div>
    </form>
  </body>
</html>
Output
elements:
- selector: html
  description: Travel site to book flights and trains
  contains:
  - selector: html body form.form-booking-flight
    description: Form to book a flight
    state: pending
    content: Book a flight Where to?
    contains:
    - selector: html body form.form-booking-flight input#destination[name='destination'][type='text'][role='destination-input']
      description: Form input where to enter the destination
      available_interactions:
      - type: input
        description: enables the form confirmation button, given certain constraints
      attributes:
        name: destination
        role: destination-input
        alt: destination input
        aria-required: 'true'
        maxlength: 30
        minlength: 3
        required: true
        type: text
    - selector: html body form.form-booking-flight div button
      description: Confirmation button to proceed with booking a flight
      content: See available flights
      available_interactions:
      - type: click
        description: proceed
        prerequisites:
        - selector: html body form.form-booking-flight input#destination[name='destination'][type='text'][role='destination-input']
          interaction: input destination
        next_features:
        - list of available flights
        - book a flight
        - login
      - type: hover
        description: diplay additonal information about possible flights
      attributes:
        aria-disabled: 'true'
    - selector: html body form.form-booking-flight div button:nth-of-type(2)
      description: Cancel button to get back to the home page
      content: Back
      available_interactions:
      - type: click
        description: dismiss form and return to home page
        next_features:
        - access forms to book trains
        - access forms to book flights

YAML (default) or JSON per requested format.

YAML recommended for improved token efficiency and stability.

Parse API
Input

GET https//example.api.com/ai-handshake

Output

OpenAPI compliant documentation, YAML (default) or JSON per requested format.

Example available here.

Tip: Tools like Swagger can automatically generate a OpenAPI compliant documentation for your API which you may serve at /ai-handshake. They usually also provide no-code UIs to display and interact wich that documentation on the web (eg. Swagger UI).

Playground

A ready-made playground is available to help familiarize yourself with the AWP protocols and tools.

# Install project dependencies
pip install -r requirements.txt 
# Choose relevant UIN install for your device
pip install "universal-intelligence[community,mps]" # Apple
pip install "universal-intelligence[community,cuda]" # NVIDIA

# Run
python -m playground.example

Cross-Platform Support

lng_icon lng_icon The AWP tool can be used across all platforms (cloud, desktop, web, mobile).

Clone this wiki locally