### Setup Python Package Environment

Source: https://github.com/alumnium-hq/alumnium/blob/main/CONTRIBUTING.md

Install dependencies for the Python package using poetry.

```bash
cd packages/python
pipx install poetry
poetry install
```

--------------------------------

### Install Server Dependencies

Source: https://github.com/alumnium-hq/alumnium/blob/main/packages/python/src/alumnium/server/README.md

Use this command from the project root to install necessary dependencies.

```bash
# Install server dependencies
make install-server
```

--------------------------------

### Install Dependencies (Root)

Source: https://github.com/alumnium-hq/alumnium/blob/main/CLAUDE.md

Run this command in the root directory to install all project dependencies.

```bash
make install
```

--------------------------------

### Start Alumnium Server (Python)

Source: https://github.com/alumnium-hq/alumnium/blob/main/CLAUDE.md

Start the main Alumnium AI server.

```bash
poetry run alumnium-server
```

--------------------------------

### Add Training Example

Source: https://github.com/alumnium-hq/alumnium/blob/main/packages/python/src/alumnium/server/README.md

Provide a successful execution example to improve the planner's future performance.

```bash
curl -X POST http://localhost:8013/v1/sessions/{session_id}/examples \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "complete user registration",
    "actions": ["Fill name field", "Fill email field", "Fill password field", "Click register button"]
  }'
# Response: {"success": true, "message": "Example added successfully", "api_version": "v1"}
```

--------------------------------

### Setup TypeScript Package Environment

Source: https://github.com/alumnium-hq/alumnium/blob/main/CONTRIBUTING.md

Install dependencies for the TypeScript package using npm.

```bash
cd packages/typescript
npm install
```

--------------------------------

### Run Appium Example Tests (TypeScript)

Source: https://github.com/alumnium-hq/alumnium/blob/main/CLAUDE.md

Execute example tests using the Appium driver.

```bash
npm run examples:appium
```

--------------------------------

### Start the Server

Source: https://github.com/alumnium-hq/alumnium/blob/main/packages/python/src/alumnium/server/README.md

Launch the server using the provided make command or directly via poetry.

```bash
make start-server
# Or directly with main.py
poetry run python -m alumnium.server.main
```

--------------------------------

### Run Selenium Example Tests (TypeScript)

Source: https://github.com/alumnium-hq/alumnium/blob/main/CLAUDE.md

Execute example tests using the Selenium driver.

```bash
npm run examples:selenium
```

--------------------------------

### POST /v1/sessions/{session_id}/examples

Source: https://github.com/alumnium-hq/alumnium/blob/main/packages/python/src/alumnium/server/README.md

Adds a training example to the planner agent for a specific session.

```APIDOC
## POST /v1/sessions/{session_id}/examples

### Description
Add training examples to the planner.

### Method
POST

### Endpoint
/v1/sessions/{session_id}/examples

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The ID of the session

### Request Body
- **goal** (string) - Required - The goal achieved
- **actions** (array) - Required - The sequence of actions taken

### Response
#### Success Response (200)
- **success** (boolean) - Operation status
- **message** (string) - Status message
- **api_version** (string) - API version identifier
```

--------------------------------

### Install Alumnium MCP

Source: https://github.com/alumnium-hq/alumnium/blob/main/README.md

Install the Alumnium MCP server using the Claude CLI.

```bash
claude mcp add alumnium --env OPENAI_API_KEY=... -- uvx --from alumnium alumnium-mcp
```

--------------------------------

### Install Monorepo Dependencies

Source: https://github.com/alumnium-hq/alumnium/blob/main/CONTRIBUTING.md

Install dependencies for both packages from the root directory.

```bash
# Install dependencies for both packages
make install
```

--------------------------------

### Install Alumnium with Pip

Source: https://github.com/alumnium-hq/alumnium/blob/main/packages/python/README.md

Use this command to install the Alumnium Python package. Ensure you have pip installed.

```bash
pip install alumnium
```

--------------------------------

### Run Pytest Examples (Python)

Source: https://github.com/alumnium-hq/alumnium/blob/main/CLAUDE.md

Execute example Pytest tests. Use the ALUMNIUM_DRIVER environment variable to switch between drivers.

```bash
poetry run pytest examples/
```

--------------------------------

### Start Alumnium MCP (Python)

Source: https://github.com/alumnium-hq/alumnium/blob/main/CLAUDE.md

Launch the Alumnium Message Control Plane server.

```bash
poetry run alumnium-mcp
```

--------------------------------

### Run Playwright Example Tests (TypeScript)

Source: https://github.com/alumnium-hq/alumnium/blob/main/CLAUDE.md

Execute example tests using the Playwright driver.

```bash
npm run examples:playwright
```

--------------------------------

### Python Development Commands

Source: https://github.com/alumnium-hq/alumnium/blob/main/CONTRIBUTING.md

Commands for testing, running examples, and formatting the Python package.

```bash
cd packages/python

# Quick testing with REPL
poetry run python -i demo.py

# Run BDD examples
poetry run behave

# Run pytest examples
poetry run pytest examples/

# Run unit tests
poetry poe test

# Format code
poetry poe format
```

--------------------------------

### Run BDD Tests (Python)

Source: https://github.com/alumnium-hq/alumnium/blob/main/CLAUDE.md

Execute example Behavior-Driven Development tests using Poetry.

```bash
poetry run behave
```

--------------------------------

### Install Alumnium via NPM

Source: https://github.com/alumnium-hq/alumnium/blob/main/packages/typescript/README.md

Install the Alumnium package using the Node Package Manager.

```bash
npm install alumnium
```

--------------------------------

### Run Alumnium Server via Docker

Source: https://github.com/alumnium-hq/alumnium/blob/main/packages/typescript/README.md

Start the Alumnium server container with the required OpenAI API key.

```sh
docker run --rm -p 8013:8013 -e OPENAI_API_KEY=... alumnium/alumnium
```

--------------------------------

### Quick Start with Alumnium and Selenium

Source: https://github.com/alumnium-hq/alumnium/blob/main/packages/python/README.md

This Python snippet demonstrates initializing Alumnium with a Selenium WebDriver, performing actions like typing and pressing Enter, checking for text on the page, and asserting specific data. Requires an OpenAI API key set as an environment variable.

```python
import os
from alumnium import Alumni
from selenium.webdriver import Chrome

os.environ["OPENAI_API_KEY"] = "..."

driver = Chrome()
driver.get("https://search.brave.com")

al = Alumni(driver)
al.do("type 'selenium' into the search field, then press 'Enter'")
al.check("page title contains selenium")
al.check("search results contain selenium.dev")
assert al.get("atomic number") == 34
```

--------------------------------

### Data Extraction with get()

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Explains how to use the get() method to extract various types of data from a web page using natural language.

```APIDOC
## get() - Extract Data from Page

### Description
Extracts requested data from the page using AI to interpret and locate the information. It can return strings, numbers, lists, or other data types based on the query.

### Method
`al.get(query, vision=False)`

### Parameters
- **query** (string) - Required - A natural language description of the data to extract.
- **vision** (boolean) - Optional - Set to `True` to enable vision-based extraction using screenshots.

### Request Example
```python
# Extract simple values
atomic_number = al.get("atomic number")

# Extract text content
heading = al.get("heading")

# Extract lists
product_titles = al.get("titles of products")
product_prices = al.get("prices of products (without money sign)")

# Extract from specific context
shipping_info = al.get("shipping information value")

# Extract cart data
cart_items = al.get("titles of products in cart")

# Extract calculated values
item_total = al.get("item total without tax (without money sign)")
tax_amount = al.get("tax amount (without money sign)")
total = al.get("total amount with tax (without money sign)")

# Vision-based extraction using screenshot
square_order = al.get("titles of squares ordered from left to right", vision=True)

# Extract from tables
due_amount = al.get("Jason Doe's due amount")

# Handle unavailable data (returns explanation string)
result = al.get("atomic number of Selenium")
```

### Response
Returns the extracted data (string, number, list, etc.) or an explanation string if the data is not found.
```

--------------------------------

### MCP Server Tools: get

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Extracts data from the page using a specified driver ID. 'vision' can be set to False to disable visual extraction.

```json
{
    "name": "get",
    "driver_id": "driver-123",
    "data": "product prices",
    "vision": False
}
```

--------------------------------

### Extract data with get()

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Extracts various data types from a page using AI interpretation. Returns an explanation string if the requested data is unavailable.

```python
from alumnium import Alumni
from selenium.webdriver import Chrome

driver = Chrome()
al = Alumni(driver)
driver.get("https://search.brave.com")

al.do("type 'selenium' into the search field, then press 'Enter'")

# Extract simple values
atomic_number = al.get("atomic number")
assert atomic_number == 34

# Extract text content
heading = al.get("heading")
assert heading == "File Uploaded!"

# Extract lists
product_titles = al.get("titles of products")
assert product_titles == ["Sauce Labs Backpack", "Sauce Labs Bike Light", ...]

product_prices = al.get("prices of products (without money sign)")
assert product_prices == [7.99, 9.99, 15.99, 15.99, 29.99, 49.99]

# Extract from specific context
shipping_info = al.get("shipping information value")
assert shipping_info == "Free Pony Express Delivery!"

# Extract cart data
cart_items = al.get("titles of products in cart")
assert cart_items == ["Sauce Labs Onesie", "Sauce Labs Backpack"]

# Extract calculated values
item_total = al.get("item total without tax (without money sign)")
tax_amount = al.get("tax amount (without money sign)")
total = al.get("total amount with tax (without money sign)")

# Vision-based extraction using screenshot
square_order = al.get("titles of squares ordered from left to right", vision=True)
assert square_order == ["A", "B"]

# Extract from tables
due_amount = al.get("Jason Doe's due amount")
assert due_amount == "$100.00"

# Handle unavailable data (returns explanation string)
result = al.get("atomic number of Selenium")
assert isinstance(result, str) and "34" not in result  # Data not on page
```

--------------------------------

### Open and Auto-Close Popup Window

Source: https://github.com/alumnium-hq/alumnium/blob/main/packages/python/examples/support/pages/multi_tab_page.html

Use this function to open a new popup window and automatically close it after a specified delay. Ensure the popup content is written before the close timer starts.

```javascript
function openPopup() {
 var popup = window.open('', 'popup', 'width=400,height=300');
 popup.document.write('<html><head><title>Popup Window</title></head>');
 popup.document.write('<body><h1>Popup Content</h1>');
 popup.document.write('<p>This popup will close in 2 seconds...</p></body></html>');
 setTimeout(function() {
 popup.close();
 }, 2000);
}
```

--------------------------------

### Create Session with Standard Tools

Source: https://github.com/alumnium-hq/alumnium/blob/main/packages/python/src/alumnium/server/README.md

Initialize a new LLM session by specifying the provider, model, and available tools.

```bash
curl -X POST http://localhost:8013/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "anthropic",
    "name": "claude-haiku-4-5-20251001",
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "ClickTool",
          "description": "Click an element.",
          "parameters": {
            "type": "object",
            "properties": {
              "id": {"type": "integer", "description": "Element identifier (ID)"}
            },
            "required": ["id"]
          }
        }
      }
    ]
  }'
# Response: {"session_id": "uuid-here", "api_version": "v1"}
```

--------------------------------

### MCP Server Tools: start_driver

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Initializes a browser driver for automated testing. Specify platformName and optionally a server_url for remote drivers.

```json
{
    "name": "start_driver",
    "capabilities": "{\"platformName\": \"chrome\"}",
    "server_url": "http://localhost:4723"  # Optional for remote drivers
}
```

--------------------------------

### Initialize File Upload Logic

Source: https://github.com/alumnium-hq/alumnium/blob/main/packages/python/examples/support/pages/multiple_file_upload.html

Sets up event listeners and state management for handling multiple file inputs and updating the UI accordingly.

```javascript
const fileInput = document.getElementById("fileInput"); const fileList = document.getElementById("fileList"); const fileCountContainer = document.getElementById("fileCountContainer"); const uploadBtn = document.getElementById("uploadBtn"); const successContainer = document.getElementById("successContainer"); const successCount = document.getElementById("successCount"); const uploadedFilesList = document.getElementById("uploadedFilesList"); let selectedFiles = []; // Handle file selection fileInput.addEventListener("change", (e) => { selectedFiles = Array.from(e.target.files); displayFiles(selectedFiles); updateFileCount(selectedFiles.length); // Enable upload button if files are selected uploadBtn.disabled = selectedFiles.length === 0; }); // Display selected files function displayFiles(files) { fileList.innerHTML = ""; if (files.length === 0) { fileList.innerHTML = "<p>No files selected</p>"; return; } const heading = document.createElement("h3"); heading.textContent = "Selected Files:"; fileList.appendChild(heading); files.forEach((file, index) => { const fileItem = document.createElement("div"); fileItem.className = "file-item"; const fileName = document.createElement("span"); fileName.className = "file-name"; fileName.textContent = `${index + 1}. ${file.name}`; const fileSize = document.createElement("span"); fileSize.className = "file-size"; fileSize.textContent = formatBytes(file.size); fileItem.appendChild(fileName); fileItem.appendChild(fileSize); fileList.appendChild(fileItem); }); } // Update file count badge function updateFileCount(count) { if (count === 0) { fileCountContainer.innerHTML = ""; return; } fileCountContainer.innerHTML = `<div class="file-count">${count} file${ count > 1 ? "s" : "" } selected</div>`; } // Format file size function formatBytes(bytes) { if (bytes === 0) return "0 Bytes"; const k = 1024; const sizes = ["Bytes", "KB", "MB", "GB"]; const i = Math.floor(Math.log(bytes) / Math.log(k)); return ( Math.round((bytes / Math.pow(k, i)) * 100) / 100 + " " + sizes[i] ); } // Handle upload uploadBtn.addEventListener("click", () => { // Simulate upload process uploadBtn.disabled = true; uploadBtn.textContent = "Uploading..."; // Simulate delay setTimeout(() => { showSuccess(selectedFiles); }, 500); }); // Show success message function showSuccess(files) { successContainer.classList.add("show"); successCount.textContent = `${files.length} file${ files.length > 1 ? "s" : "" } uploaded successfully`; // List uploaded files uploadedFilesList.innerHTML = "<h4>Uploaded Files:</h4>"; files.forEach((file, index) => { const uploadedFile = document.createElement("div"); uploadedFile.className = "uploaded-file"; uploadedFile.textContent = `${index + 1}. ${file.name} (${formatBytes( file.size )})`; uploadedF
```

--------------------------------

### Teaching Custom Actions with learn()

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Explains how to use the learn() method to teach Alumnium custom action sequences for complex or ambiguous tasks.

```APIDOC
## learn() - Teach Custom Actions

### Description
Allows you to teach Alumnium specific action sequences for goals that may be ambiguous or require precise steps. This is useful for complex workflows or provider-specific behaviors.

### Method
`al.learn(goal, steps)`

### Parameters
- **goal** (string) - Required - The natural language description of the goal the custom action achieves.
- **steps** (list of strings) - Required - A list of natural language steps that define the action sequence.

### Request Example
```python
al.learn("log in to the application", [
  "type 'username' into the username field",
  "type 'password' into the password field",
  "click the login button"
])

# After learning, you can use the custom action like any other command:
al.do("log in to the application")
```

### Response
This method is used for teaching and does not return a direct value in the context of a single call. Once learned, the action can be invoked using `al.do()`.
```

--------------------------------

### Teach and Perform Actions in Python

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Learn specific action sequences or multi-step workflows using natural language. Use 'al.do' to execute learned actions and 'al.clear_learn_examples' to reset.

```python
al.learn("add laptop to cart", ["click button 'Add to cart' next to 'laptop' product"])
al.learn("go to shopping cart", ["click link after 'Swag Labs' with a number text in it"])
al.learn("sort products by lowest shipping cost", [
    "click combobox with options",
    'click option "Shipping (low to high)"',
    ]
)
al.learn("sort products by lowest shipping cost", [
    "click generic element after 'Products' text",
    'click "Shipping (low to high)"'
    ]
)
al.do("add laptop to cart")
al.do("go to shopping cart")
al.do("sort products by lowest shipping cost")
al.clear_learn_examples()
```

--------------------------------

### Enable Multiple Extra Tools

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Initialize Alumnium with a list of desired extra tools, such as navigation, JavaScript execution, and PDF printing.

```python
from alumnium import Alumni
from alumnium.tools import (
    NavigateBackTool,
    ExecuteJavascriptTool,
    PrintToPdfTool,
)
from selenium.webdriver import Chrome

driver = Chrome()

# Enable multiple extra tools
al = Alumni(driver, extra_tools=[
    NavigateBackTool,
    ExecuteJavascriptTool,
    PrintToPdfTool,
])
```

--------------------------------

### Execute Step Actions

Source: https://github.com/alumnium-hq/alumnium/blob/main/packages/python/src/alumnium/server/README.md

Generate specific tool interactions for a single step within a goal.

```bash
curl -X POST http://localhost:8013/v1/sessions/{session_id}/steps \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "log in to the application",
    "step": "Fill username field",
    "accessibility_tree": "<accessibility_tree>...</accessibility_tree>"
  }'
# Response: {"actions": [{"tool": "type", "args": {"id": "username", "text": "user@example.com"}}], "api_version": "v1"}
```

--------------------------------

### Enable Navigation History Tool

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Initialize Alumnium with the NavigateBackTool to enable navigation history. Use 'navigate back' commands to go to previous pages.

```python
from alumnium import Alumni
from alumnium.tools import NavigateBackTool
from selenium.webdriver import Chrome

driver = Chrome()

# Enable navigation history
al = Alumni(driver, extra_tools=[NavigateBackTool])
al.do("open typos")
al.do("navigate back to the previous page")
```

--------------------------------

### Run Tests (Root)

Source: https://github.com/alumnium-hq/alumnium/blob/main/CLAUDE.md

Execute all tests for the project from the root directory.

```bash
make test
```

--------------------------------

### Initialize Alumnium with Default Model

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Initialize the Alumnium client in Python using the default model (OpenAI) and a Selenium WebDriver.

```python
from alumnium import Alumni, Model, Provider
from selenium.webdriver import Chrome

driver = Chrome()

# Use default model (OpenAI)
al = Alumni(driver)
```

--------------------------------

### MCP Server Tools: do

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Executes natural language goals using a specified driver ID.

```json
{
    "name": "do",
    "driver_id": "driver-123",
    "goal": "click login button"
}
```

--------------------------------

### Build Project (TypeScript)

Source: https://github.com/alumnium-hq/alumnium/blob/main/CLAUDE.md

Compile the TypeScript project.

```bash
npm run build
```

--------------------------------

### Alumnium Python API - Learning Actions

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Demonstrates how to teach Alumnium specific action sequences and multi-step workflows using the `learn` method, and how to execute them with `do`.

```APIDOC
## Alumnium Python API - Learning Actions

### Description
Teach Alumnium specific action sequences and multi-step workflows.

### Method
`al.learn(action_name: str, steps: list[str])`
`al.do(action_name: str)`
`al.clear_learn_examples()`

### Parameters
#### `learn` method:
- **action_name** (string) - Required - The name of the action to teach.
- **steps** (list of strings) - Required - A list of natural language steps to perform the action.

#### `do` method:
- **action_name** (string) - Required - The name of the learned action to execute.

### Request Example
```python
# Teach specific action sequences
al.learn("add laptop to cart", ["click button 'Add to cart' next to 'laptop' product"])

# Teach multi-step workflows
al.learn(
    "sort products by lowest shipping cost",
    [
        "click combobox with options",
        'click option "Shipping (low to high)"'
    ],
)

# Now use the learned actions
al.do("add laptop to cart")
al.do("sort products by lowest shipping cost")

# Clear learned examples when done
al.clear_learn_examples()
```
```

--------------------------------

### Plan Actions

Source: https://github.com/alumnium-hq/alumnium/blob/main/packages/python/src/alumnium/server/README.md

Request the planner to break down a high-level goal into actionable steps based on the current page state.

```bash
curl -X POST http://localhost:8013/v1/sessions/{session_id}/plans \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "log in to the application",
    "accessibility_tree": "<accessibility_tree>...</accessibility_tree>",
    "url": "https://example.com/login",
    "title": "Login Page"
  }'
# Response: {"steps": ["Fill username field", "Fill password field", "Click login button"], "api_version": "v1"}
```

--------------------------------

### Teach custom actions with learn()

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Defines specific action sequences for complex or ambiguous workflows.

```python
from alumnium import Alumni
from selenium.webdriver import Chrome

driver = Chrome()
al = Alumni(driver)
```

--------------------------------

### Monorepo Make Commands

Source: https://github.com/alumnium-hq/alumnium/blob/main/CONTRIBUTING.md

Utility commands available from the root directory for managing the monorepo.

```bash
make format       # Format both packages
make test         # Run Python tests
make build        # Build both packages
make clean        # Clean both packages
make start-server # Start the Alumnium server
```

--------------------------------

### Run Unit Tests (Python)

Source: https://github.com/alumnium-hq/alumnium/blob/main/CLAUDE.md

Execute Python unit tests using Poetry.

```bash
poetry poe test
```

--------------------------------

### Execute Natural Language Actions with do()

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Use the `do()` method to execute a series of natural language steps for interacting with web applications, including typing, clicking, navigating, and form filling.

```python
from alumnium import Alumni
from selenium.webdriver import Chrome

driver = Chrome()
al = Alumni(driver)
driver.get("https://www.saucedemo.com/")

# Type into fields
al.do("type 'standard_user' into username field")
al.do("type 'secret_sauce' into password field")

# Click buttons
al.do("click login button")

# Complex multi-step actions
al.do("type 'selenium' into the search field, then press 'Enter'")

# Navigate and interact
al.do("open typos")
al.do("navigate back to the previous page")

# Form interactions
al.do("select 'Option 1'")
al.do("fill in first name - Al, last name - Um, ZIP - 95122")

# Sorting and filtering
al.do("sort products by lowest price")
al.do("sort products in descending alphabetical order")

# Shopping cart actions
al.do("add onesie to cart")
al.do("go to shopping cart")
al.do("go to checkout")
al.do("finish checkout")

# File upload
al.do("upload '/path/to/file.txt'")

# Drag and drop
al.do("move square A to square B")

# Returns DoResult with explanation and executed steps
result = al.do("click login button")
print(f"Explanation: {result.explanation}")
print(f"Steps executed: {[step.name for step in result.steps]}")
```

--------------------------------

### Configure API Keys

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Set environment variables for API keys required by AI model providers.

```bash
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GOOGLE_API_KEY="..."
```

--------------------------------

### TypeScript Development Commands

Source: https://github.com/alumnium-hq/alumnium/blob/main/CONTRIBUTING.md

Commands for building, testing, and formatting the TypeScript package.

```bash
cd packages/typescript

# Build the package
npm run build

# Run all examples
npm run examples

# Run specific driver examples
npm run examples:selenium
npm run examples:playwright
npm run examples:appium

# Format code
npm run format
```

--------------------------------

### POST /v1/sessions/{session_id}/steps

Source: https://github.com/alumnium-hq/alumnium/blob/main/packages/python/src/alumnium/server/README.md

Generates specific tool actions for a given high-level step.

```APIDOC
## POST /v1/sessions/{session_id}/steps

### Description
Generate specific actions for a step.

### Method
POST

### Endpoint
/v1/sessions/{session_id}/steps

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The ID of the session

### Request Body
- **goal** (string) - Required - The overall goal
- **step** (string) - Required - The specific step to execute
- **accessibility_tree** (string) - Required - Current page accessibility tree

### Response
#### Success Response (200)
- **actions** (array) - List of tool actions to perform
- **api_version** (string) - API version identifier
```

--------------------------------

### POST /v1/sessions/{session_id}/plans

Source: https://github.com/alumnium-hq/alumnium/blob/main/packages/python/src/alumnium/server/README.md

Generates a sequence of high-level steps to achieve a specific goal based on the current page state.

```APIDOC
## POST /v1/sessions/{session_id}/plans

### Description
Plan high-level steps to achieve a goal.

### Method
POST

### Endpoint
/v1/sessions/{session_id}/plans

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The ID of the session

### Request Body
- **goal** (string) - Required - The objective to achieve
- **accessibility_tree** (string) - Required - Current page accessibility tree
- **url** (string) - Required - Current page URL
- **title** (string) - Required - Current page title

### Response
#### Success Response (200)
- **steps** (array) - List of planned steps
- **api_version** (string) - API version identifier
```

--------------------------------

### Clone the Alumnium Repository

Source: https://github.com/alumnium-hq/alumnium/blob/main/CONTRIBUTING.md

Initial step to fork and clone the repository to your local machine.

```bash
# Fork and clone the repository
git clone https://github.com/your-username/alumnium.git
cd alumnium
```

--------------------------------

### Format Code with Ruff

Source: https://github.com/alumnium-hq/alumnium/blob/main/packages/python/src/alumnium/server/README.md

Automatically format the codebase according to defined style guidelines using Ruff. This ensures consistent code style across the project.

```bash
poetry run ruff format .
```

--------------------------------

### Access Current Model Information

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Retrieve and print the provider and name of the currently configured AI model.

```python
print(f"Provider: {al.model.provider.value}")
print(f"Model: {al.model.name}")
```

--------------------------------

### Configure Feature Flags

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Enable or disable Alumnium features like planning agent, change analysis, and full page screenshots using environment variables.

```bash
export ALUMNIUM_PLANNER="true"  # Enable planning agent
export ALUMNIUM_CHANGE_ANALYSIS="false"  # Enable change analysis
export ALUMNIUM_FULL_PAGE_SCREENSHOT="false"  # Full page screenshots
```

--------------------------------

### Run Tests (TypeScript)

Source: https://github.com/alumnium-hq/alumnium/blob/main/CLAUDE.md

Execute tests for the TypeScript client implementation.

```bash
npm run examples
```

--------------------------------

### POST /v1/sessions

Source: https://github.com/alumnium-hq/alumnium/blob/main/packages/python/src/alumnium/server/README.md

Creates a new LLM session with a specified provider, model, and tool schema.

```APIDOC
## POST /v1/sessions

### Description
Creates a new session with specific provider and model.

### Method
POST

### Endpoint
/v1/sessions

### Request Body
- **provider** (string) - Required - The AI provider (e.g., anthropic)
- **name** (string) - Required - The model name
- **tools** (array) - Optional - List of tool definitions

### Response
#### Success Response (200)
- **session_id** (string) - Unique identifier for the session
- **api_version** (string) - API version identifier
```

--------------------------------

### Check Code Quality with Ruff

Source: https://github.com/alumnium-hq/alumnium/blob/main/packages/python/src/alumnium/server/README.md

Use Ruff to check the codebase for style and potential errors. This command helps identify issues before committing code.

```bash
poetry run ruff check .
```

--------------------------------

### Enable JavaScript Execution Tool

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Initialize Alumnium with the ExecuteJavascriptTool to run custom JavaScript code. Useful for actions not directly supported by standard commands.

```python
from alumnium import Alumni
from alumnium.tools import ExecuteJavascriptTool
from selenium.webdriver import Chrome

driver = Chrome()

# Enable JavaScript execution
al = Alumni(driver, extra_tools=[ExecuteJavascriptTool])
al.do("execute javascript 'window.scrollTo(0, document.body.scrollHeight)'")
```

--------------------------------

### Vision-based Verification

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Demonstrates how to use the check() method with the vision=True parameter for screenshot-based verification.

```APIDOC
## Vision-based Verification

### Description
Verifies elements on the page using visual AI analysis of screenshots.

### Method
`al.check(description, vision=True)`

### Parameters
- **description** (string) - Required - A natural language description of the element or condition to verify.
- **vision** (boolean) - Required - Set to `True` to enable vision-based verification.

### Request Example
```python
al.check("big green checkmark is shown", vision=True)
al.check("'Powered by Elemental Selenium' is present", vision=True)
```

### Response
Returns a boolean indicating if the verification passed.
```

--------------------------------

### MCP Server Tools: check

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Verifies statements, with an option to use vision. Set 'vision' to False to disable visual verification.

```json
{
    "name": "check",
    "driver_id": "driver-123",
    "statement": "page title contains Dashboard",
    "vision": False
}
```

--------------------------------

### Configure Alumnium Model

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Set the Alumnium model using environment variables. Supports various providers like OpenAI, Anthropic, and Google.

```bash
export ALUMNIUM_MODEL="openai/gpt-5-nano-2025-08-07"
export ALUMNIUM_MODEL="anthropic/claude-haiku-4-5-20251001"
export ALUMNIUM_MODEL="google/gemini-3.1-flash-lite-preview"
```

--------------------------------

### Specify AI Provider and Model

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Initialize Alumnium with a specific AI provider and model. Supports OpenAI, Anthropic, Google, MistralAI, Deepseek, Ollama, XAI, Azure OpenAI, AWS Bedrock, and GitHub Models.

```python
al = Alumni(driver, model=Model(Provider.OPENAI, "gpt-5-nano-2025-08-07"))
```

```python
al = Alumni(driver, model=Model(Provider.ANTHROPIC, "claude-haiku-4-5-20251001"))
```

```python
al = Alumni(driver, model=Model(Provider.GOOGLE, "gemini-3.1-flash-lite-preview"))
```

```python
al = Alumni(driver, model=Model(Provider.MISTRALAI, "mistral-medium-2505"))
```

```python
al = Alumni(driver, model=Model(Provider.DEEPSEEK, "deepseek-reasoner"))
```

```python
al = Alumni(driver, model=Model(Provider.OLLAMA, "mistral-small3.1"))
```

```python
al = Alumni(driver, model=Model(Provider.XAI, "grok-4-1-fast-reasoning"))
```

```python
al = Alumni(driver, model=Model(Provider.AZURE_OPENAI, "gpt-5-nano"))
```

```python
al = Alumni(driver, model=Model(Provider.AWS_ANTHROPIC, "us.anthropic.claude-haiku-4-5-20251001-v1:0"))
```

```python
al = Alumni(driver, model=Model(Provider.AWS_META, "us.meta.llama4-maverick-17b-instruct-v1:0"))
```

```python
al = Alumni(driver, model=Model(Provider.GITHUB, "gpt-4o-mini"))
```

--------------------------------

### Configure Retries and Delay

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Set the number of retries on failure and the delay in seconds between retries using environment variables.

```bash
export ALUMNIUM_RETRIES=2  # Number of retries on failure
export ALUMNIUM_DELAY=0.5  # Delay between retries in seconds
```

--------------------------------

### Initialize Alumni Class with Drivers

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Initialize the Alumni class, the core interface for AI-powered test automation. Supports Selenium, Playwright, and custom model configurations.

```python
import os
from alumnium import Alumni, Model, Provider
from selenium.webdriver import Chrome
from playwright.sync_api import sync_playwright

os.environ["OPENAI_API_KEY"] = "your-api-key"

# Using Selenium
driver = Chrome()
al = Alumni(driver)

# Using Playwright
with sync_playwright() as playwright:
    browser = playwright.chromium.launch()
    page = browser.new_page()
    al = Alumni(page)

# Using custom model configuration
al = Alumni(driver, model=Model(Provider.ANTHROPIC, "claude-haiku-4-5-20251001"))

# Using remote server
al = Alumni(driver, url="http://localhost:8013")

# With extra tools enabled
from alumnium.tools import NavigateBackTool, ExecuteJavascriptTool
al = Alumni(driver, extra_tools=[NavigateBackTool, ExecuteJavascriptTool])

# Clean up when done
al.quit()
```

--------------------------------

### Verify page state with check()

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Uses natural language to verify page elements or state, optionally utilizing vision-based analysis.

```python
al.check("big green checkmark is shown", vision=True)
al.check("'Powered by Elemental Selenium' is present", vision=True)

# Returns explanation string on success
explanation = al.check("page title contains selenium")
print(f"Verification: {explanation}")
```

--------------------------------

### MCP Server Tools

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Tools exposed by the MCP server for AI coding agents to control browsers via the Model Context Protocol.

```APIDOC
## MCP Server Tools

### Description
Tools exposed by the MCP server for AI coding agents to enable automated browser control through the Model Context Protocol.

### MCP Tool: `start_driver`
Initialize a browser driver for automated testing.
```json
{
    "name": "start_driver",
    "capabilities": "{\"platformName\": \"chrome\"}",
    "server_url": "http://localhost:4723"  # Optional for remote drivers
}
```

### MCP Tool: `do`
Execute natural language goals.
```json
{
    "name": "do",
    "driver_id": "driver-123",
    "goal": "click login button"
}
```

### MCP Tool: `check`
Verify statements with optional vision.
```json
{
    "name": "check",
    "driver_id": "driver-123",
    "statement": "page title contains Dashboard",
    "vision": false
}
```

### MCP Tool: `get`
Extract data from the page.
```json
{
    "name": "get",
    "driver_id": "driver-123",
    "data": "product prices",
    "vision": false
}
```

### MCP Tool: `wait`
Wait for a specified time or condition.
```json
{
    "name": "wait",
    "driver_id": "driver-123",
    "for": 5  # Wait 5 seconds
}
```
```json
{
    "name": "wait",
    "driver_id": "driver-123",
    "for": "user is logged in",  # Wait for condition
    "timeout": 10
}
```

### MCP Tool: `fetch_accessibility_tree`
Get the page structure for debugging.
```json
{
    "name": "fetch_accessibility_tree",
    "driver_id": "driver-123"
}
```

### MCP Tool: `stop_driver`
Close the browser and perform cleanup.
```json
{
    "name": "stop_driver",
    "driver_id": "driver-123",
    "save_cache": true
}
```
```

--------------------------------

### Run Pytest for Alumnium

Source: https://github.com/alumnium-hq/alumnium/blob/main/packages/python/src/alumnium/server/README.md

Execute all tests defined in the project using the pytest framework. This command is typically run from the project's root directory.

```bash
poetry run pytest
```

--------------------------------

### Format Code (Root)

Source: https://github.com/alumnium-hq/alumnium/blob/main/CLAUDE.md

Format code across both Python and TypeScript packages.

```bash
make format
```

--------------------------------

### Configure Alumnium Server URL

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Set the Alumnium server URL for the TypeScript client using an environment variable.

```bash
export ALUMNIUM_SERVER_URL="http://localhost:8013"
```

--------------------------------

### Element Location with find()

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Details how to use the find() method to locate web elements using natural language descriptions.

```APIDOC
## find() - Locate Elements with Natural Language

### Description
Locates elements on the page using natural language descriptions and returns the native driver element (WebElement for Selenium, Locator for Playwright, WebElement for Appium).

### Method
`al.find(description)`

### Parameters
- **description** (string) - Required - A natural language description of the element to find.

### Request Example
```python
text_input = al.find("text input")
text_input.send_keys("Hello Alumnium!")

textarea = al.find("textarea")
textarea.send_keys("Testing the LocatorAgent")

submit_button = al.find("submit button")
submit_button.click()
```

### Response
Returns the native driver element corresponding to the description. Returns `None` if the element is not found.
```

--------------------------------

### Model and Provider Configuration

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Configure Alumnium to use multiple AI providers and models programmatically or via environment variables.

```APIDOC
## Model and Provider Configuration

### Description
Alumnium supports multiple AI providers. Configure the model programmatically or through environment variables.

### Programmatic Configuration
```python
from alumnium import Alumni, Model, Provider
from selenium.webdriver import Chrome

driver = Chrome()

# Use default model (OpenAI)
al = Alumni(driver)

# Example using a specific model and provider
# al = Alumni(driver, model=Model(provider=Provider.ANTHROPIC, name="claude-3-opus-20240229"))
```
```

--------------------------------

### Configuration - Environment Variables

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Customize Alumnium behavior through environment variables for model selection, retries, and feature flags.

```APIDOC
## Configuration - Environment Variables

### Description
Alumnium behavior can be customized through environment variables for model selection, retries, and feature flags.

### Model Configuration
```bash
# Model configuration (provider/model-name)
export ALUMNIUM_MODEL="openai/gpt-5-nano-2025-08-07"
export ALUMNIUM_MODEL="anthropic/claude-haiku-4-5-20251001"
export ALUMNIUM_MODEL="google/gemini-3.1-flash-lite-preview"

# API keys for providers
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GOOGLE_API_KEY="..."
```

### Retry Configuration
```bash
export ALUMNIUM_RETRIES=2  # Number of retries on failure
export ALUMNIUM_DELAY=0.5  # Delay between retries in seconds
```

### Feature Flags
```bash
export ALUMNIUM_PLANNER="true"  # Enable planning agent
export ALUMNIUM_CHANGE_ANALYSIS="false"  # Enable change analysis
export ALUMNIUM_FULL_PAGE_SCREENSHOT="false"  # Full page screenshots
```

### Accessibility Tree Configuration
```bash
export ALUMNIUM_EXCLUDE_ATTRIBUTES="class,style"  # Exclude attributes from tree
```

### Server Configuration (TypeScript)
```bash
export ALUMNIUM_SERVER_URL="http://localhost:8013"
```
```

--------------------------------

### Execute AI-Powered Tests with Selenium

Source: https://github.com/alumnium-hq/alumnium/blob/main/packages/typescript/README.md

Initialize an Alumnium instance with a Selenium driver to perform natural language interactions and assertions.

```javascript
import { Alumni } from "alumnium";
import { Builder } from "selenium-webdriver";

const driver = await new Builder().forBrowser("chrome").build();
const al = new Alumni(driver);

await driver.get("https://search.brave.com");
await al.do("type 'selenium' into the search field, then press 'Enter'");
await al.check("page title contains selenium");
await al.check("search results contain selenium.dev");
console.log("Atomic number:", await al.get("atomic number")); // 34

await al.quit();
```

--------------------------------

### Locate elements with find()

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Locates elements using natural language and returns the native driver element for direct interaction.

```python
from alumnium import Alumni
from selenium.webdriver import Chrome

driver = Chrome()
al = Alumni(driver)
driver.get("https://bonigarcia.dev/selenium-webdriver-java/web-form.html")

# Find elements by description
text_input = al.find("text input")
assert text_input is not None
text_input.send_keys("Hello Alumnium!")

textarea = al.find("textarea")
assert textarea is not None
textarea.send_keys("Testing the LocatorAgent")

submit_button = al.find("submit button")
assert submit_button is not None
submit_button.click()
```

--------------------------------

### Format Code (Python)

Source: https://github.com/alumnium-hq/alumnium/blob/main/CLAUDE.md

Format Python code using Poetry.

```bash
poetry poe format
```

--------------------------------

### Track Usage Statistics

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Access and print usage statistics (token counts) via the 'stats' property after performing actions. Useful for monitoring and cost analysis.

```python
from alumnium import Alumni
from selenium.webdriver import Chrome

driver = Chrome()
al = Alumni(driver)
driver.get("https://example.com")

al.do("click button")
al.check("page loaded")
al.get("heading text")

# Get usage statistics
stats = al.stats
print(f"Statistics: {stats}")
```

--------------------------------

### Format Code (TypeScript)

Source: https://github.com/alumnium-hq/alumnium/blob/main/CLAUDE.md

Format TypeScript code.

```bash
npm run format
```

--------------------------------

### JavaScript for File Upload

Source: https://github.com/alumnium-hq/alumnium/blob/main/packages/python/examples/support/pages/hidden_file_upload.html

Handles file selection, display, and simulated submission. Requires elements with IDs: fileInput, chooseFileBtn, fileList, submitBtn, successMessage. The formatBytes function is included for file size display.

```javascript
const fileInput = document.getElementById("fileInput");
const chooseFileBtn = document.getElementById("chooseFileBtn");
const fileList = document.getElementById("fileList");
const submitBtn = document.getElementById("submitBtn");
const successMessage = document.getElementById("successMessage");

// Trigger file input when custom button is clicked
chooseFileBtn.addEventListener("click", () => {
  fileInput.click();
});

// Handle file selection
fileInput.addEventListener("change", (e) => {
  const files = e.target.files;
  displayFiles(files);
  // Enable submit button if files are selected
  submitBtn.disabled = files.length === 0;
});

// Display selected files
function displayFiles(files) {
  fileList.innerHTML = "";
  if (files.length === 0) {
    fileList.innerHTML = "<p>No files selected</p>";
    return;
  }
  Array.from(files).forEach((file) => {
    const fileItem = document.createElement("div");
    fileItem.className = "file-item";
    fileItem.textContent = `📄 ${file.name} (${formatBytes(file.size)})`;
    fileList.appendChild(fileItem);
  });
}

// Format file size
function formatBytes(bytes) {
  if (bytes === 0) return "0 Bytes";
  const k = 1024;
  const sizes = ["Bytes", "KB", "MB", "GB"];
  const i = Math.floor(Math.log(bytes) / Math.log(k));
  return (
    Math.round((bytes / Math.pow(k, i)) * 100) / 100 + " " + sizes[i]
  );
}

// Handle form submission
submitBtn.addEventListener("click", () => {
  // Simulate upload
  successMessage.style.display = "block";
  submitBtn.disabled = true;
});
```

--------------------------------

### Verify Statement

Source: https://github.com/alumnium-hq/alumnium/blob/main/packages/python/src/alumnium/server/README.md

Validate an assertion against the current page state, optionally including a screenshot for context.

```bash
curl -X POST http://localhost:8013/v1/sessions/{session_id}/statements \
  -H "Content-Type: application/json" \
  -d '{
    "statement": "user is logged in successfully",
    "accessibility_tree": "<accessibility_tree>...</accessibility_tree>",
    "url": "https://example.com/dashboard",
    "title": "Dashboard",
    "screenshot": "iVBORw0KGgoAAAANSUhEU..."
  }'
# Response: {"result": "true", "explanation": "Dashboard page is visible with user menu", "api_version": "v1"}
```

--------------------------------

### MCP Server Tools: wait (condition)

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Waits for a specific condition to be met, with an optional timeout.

```json
{
    "name": "wait",
    "driver_id": "driver-123",
    "for": "user is logged in",  # Wait for condition
    "timeout": 10
}
```

--------------------------------

### Scoped Testing with area()

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Illustrates the use of the area() method to create a focused testing context within a specific part of a web page.

```APIDOC
## area() - Scoped Testing Context

### Description
Creates a scoped testing context for working within a specific region of the page. This is useful for tables, forms, or other distinct UI sections where you want to limit the AI's focus.

### Method
`al.area(description)`

### Parameters
- **description** (string) - Required - A natural language description of the area to focus on.

### Request Example
```python
# Create area for first table
table1 = al.area("first table")

# Extract data from specific table
assert table1.get("Jason Doe's due amount") == "$100.00"

# Perform actions within the area
table1.do("sort by last name")

# Area supports do(), check(), get(), and find() methods
area = al.area("login form")
area.do("fill username")
area.check("username field is populated")
element = area.find("submit button")
```

### Response
Returns an Area object that provides methods like `do()`, `check()`, `get()`, and `find()` scoped to the specified area.
```

--------------------------------

### Scope testing with area()

Source: https://context7.com/alumnium-hq/alumnium/llms.txt

Creates a scoped context to limit AI focus to specific UI regions like tables or forms.

```python
from alumnium import Alumni
from selenium.webdriver import Chrome

driver = Chrome()
al = Alumni(driver)
driver.get("https://the-internet.herokuapp.com/tables")

# Create area for first table
table1 = al.area("first table")
print(f"Area description: {table1.description}")

# Extract data from specific table
assert table1.get("Jason Doe's due amount") == "$100.00"
assert table1.get("Frank Bach's due amount") == "$51.00"
assert table1.get("first names") == ["John", "Frank", "Jason", "Tim"]

# Perform actions within the area
table1.do("sort by last name")

# Refresh area after page changes
table1 = al.area("first table")
assert table1.get("last names") == ["Bach", "Conway", "Doe", "Smith"]

# Work with second table independently
table2 = al.area("second table")
assert table2.get("first names") == ["John", "Frank", "Jason", "Tim"]
table2.do("sort by first name")

# Verify tables are independent
table2 = al.area("second table")
assert table2.get("first names") == ["Frank", "Jason", "John", "Tim"]
table1 = al.area("first table")
assert table1.get("first names") == ["Frank", "Tim", "Jason", "John"]  # Unchanged

# Area supports do(), check(), get(), and find() methods
area = al.area("login form")
area.do("fill username")
area.check("username field is populated")
element = area.find("submit button")
```