# SDK Python

{% hint style="success" %}
Explore our GitHub repository <https://github.com/LumiTeh-hub> and star us!
{% endhint %}

## Overview

`The LumiTeh Python SDK offers a full suite of tools for working with the LumiTeh API. In this guide, you’ll learn how to install the SDK, set up your API key, and begin using it to manage browser sessions, web agents, and website interactions.`

{% hint style="info" %}
We highly recommend using the Python SDK for all your automation tasks. It provides the most efficient way to interact with the LumiTeh API.
{% endhint %}

### Quickstart

{% stepper %}
{% step %}
**Install the latest version of the SDK (requires \`python >= 3.11\`)**

```yang
pip install --upgrade lumiteh-sdk
```

{% endstep %}

{% step %}
**Configure your API key as an environment variable**

{% code fullWidth="false" %}

```erb
export LUMITEH_API_KEY=
```

{% endcode %}
{% endstep %}

{% step %}
**Run your first agent**

```python
import os
from lumiteh_sdk import LumiTehClient

lumiteh = LumiTehClient(api_key=os.getenv("LUMITEH_API_KEY"))
with lumiteh.Session() as session:
    agent = lumiteh.Agent(session=session, max_steps=5)
    response = agent.run(
        task="Find the latest job openings on lumiteh.io",
    )
```

{% endstep %}
{% endstepper %}

***

## Explore what the **LumiTeh** Python SDK can do for you

The SDK provides a comprehensive set of tools for interacting with the LumiTeh API.

{% tabs %}
{% tab title="Web Agents" %}
**Run a Web Agent**

```python
from lumiteh_sdk import LumiTehClient

lumiteh = LumiTehClient()
with lumiteh.Session() as session:
    agent = lumiteh.Agent(session=session, max_steps=10)
    response = agent.run(task="Find the best Italian restaurant in SF and book a table for 2 at 7pm today")
    print(f"Agent terminated with status: {response.success} and answer: {response.answer}")
    
    from lumiteh_sdk import LumiTehClient
```

**How to get visual insights about your sessions & agents**

At any time during the execution of a session or an agent, you can retrieve a replay of the execution so far as a `WebP` image.

```python
lumiteh = LumiTehClient()

with lumiteh.Session() as session:
    _ = session.observe(url="https://duckduckgo.com")
# Save the replay to a file
replay = session.replay()
replay.save("replay.webp")
```

{% endtab %}

{% tab title="Browser Sesions" %}

### Manage your browser sessions

```python
from lumiteh_sdk import LumiTehClient

lumiteh = LumiTehClient()

# The session is automatically stopped when the context manager is exited
with lumiteh.Session(timeout_minutes=2) as session:
    status = session.status()
    print(status)

```

you can also always list all your sessions using the `sessions.list` method:

```python
from lumiteh_sdk import LumiTehClient

lumiteh = LumiTehClient()

# list only active sessions
sessions = lumiteh.sessions.list()

# list all sessions
sessions = lumiteh.sessions.list(only_active=False)

```

### How to get visual insights about your sessions & agents

During the execution of a session or an agent, you can capture a replay of the progress so far as a WebP image at any time.

```python
from lumiteh_sdk import LumiTehClient

lumiteh = LumiTehClient()

with lumiteh.Session() as session:
    _ = session.observe(url="https://duckduckgo.com")
# Save the replay to a file
replay = session.replay()
replay.save("replay.webp")
```

{% endtab %}

{% tab title="Page Interactions" %}

### Take control and execute actions in a session

The LumiTeh SDK also lets you monitor a web page and its interactions, extract page content, and perform actions within an active session:

* **Observe:** track the actions available on a webpage
* **Step:** perform an action on the page (e.g., click a button, fill out a form, etc.)
* **Scrape:** extract page content in Markdown format or in a structured format using BaseModel from pydantic<br>

```python
from lumiteh_sdk import LumiTehClient

lumiteh = LumiTehClient()
with lumiteh.Session(timeout_minutes=10) as session:
    # Observe the state of a webpage
    obs = session.observe(url="https://google.com/travel/flights")
    print("Page Title:", obs.metadata.title)
    print("Available Actions:\n", obs.space.markdown)
    # # Example Output:
    # # Flight Search
    # * I1: Enter departure location (departureLocation: str = "San Francisco")
    # * I3: Select departure date (departureDate: date)
    # * I6: Select trip type (tripType: str = "round-trip", allowed=["round-trip", "one-way", "multi-city"])
    #
    # # Website Navigation
    # * B5: Open Google apps menu
    # ...

    # Then you can take actions on the page
    _ = session.execute(obs.space.sample(type="click"))
    obs = session.observe()

    # You scrape the final page data
    markdown = session.scrape()
    print("Scraped Data:", markdown)
    # Example Output:
    # Flight Search inputs
    # - Where from?: Paris
    # - Where to?: London
    # - Departure: Sun, April 6
    #
    # Flight Search Results
    # | Airline       | Departure  | Arrival  | Duration   | Stops     | Price |
    # |---------------|------------|----------|------------|-----------|-------|
    # | easyJet       | 12:15 AM   | 14:35 AM | 2 hr 20 min| Nonstop   | $38   |
    # | Air France    | 7:15 PM    | 15:30 PM  | 8 hr 15 min| Nonstop   | $227  |
    # ...

```

### How to gain visual insights into your sessions and agents

At any time during the execution of a session or an agent, you can retrieve a replay of the execution so far as a `WebP` image.

```python
from lumiteh_sdk import LumiTehClient

lumiteh = LumiTehClient()

with lumiteh.Session() as session:
    _ = session.observe(url="https://duckduckgo.com")
# Save the replay to a file
replay = session.replay()
replay.save("replay.webp")

```

{% endtab %}

{% tab title="Secrets & Vaults" %}

### Manage your credentials in a secure vault

The Notte SDK allows you to securely store and access your credentials in a secure vault.

```python
from lumiteh_sdk import LumiTehClient

lumiteh = LumiTehClient()
# Get your vault id from the LumiTeh dashboard
vault = lumiteh.Vault(vault_id="my_vault_id")
# Add your credentials securely
_ = vault.add_credentials(
    url="https://github.com/",
    email="my_email@gmail.com",
    password="my_password",
    # Check https://github.com/scito/extract_otp_secrets to extract your MFA secret
    # from your authenticator app
    mfa_secret="PYNT7I67RFS2EPR5",
)
# Run an agent with secure credential access
with lumiteh.Session() as session:
    agent = lumiteh.Agent(vault=vault, session=session, max_step_

```

### How to gain visual insights into your sessions and agents

At any time during the execution of a session or an agent, you can retrieve a replay of the execution so far as a `WebP` image.

```python
from lumiteh_sdk import LumiTehClient

lumiteh = LumiTehClient()

with lumiteh.Session() as session:
    _ = session.observe(url="https://duckduckgo.com")
# Save the replay to a file
replay = session.replay()
replay.save("replay.webp")

```

{% endtab %}

{% tab title="Scrape" %}
**LumiTeh** makes it simple to scrape a webpage and extract structured data using pydantic models.

```python
from pydantic import BaseModel
from lumiteh_sdk import LumiTehClient

class JobPosting(BaseModel):
    jobTitle: str

lumiteh = LumiTehClient()
job_title = lumiteh.scrape(
    url="https://linkedin.com",
    instructions="Extract the job title from the job posting",
    response_format=JobPosting,
)

```

### How to get visual insights about your sessions & agents

At any time during the execution of a session or an agent, you can retrieve a replay of the execution so far as a `WebP` image.

```python
from lumiteh_sdk import LumiTehClient

lumiteh = LumiTehClient()

with lumiteh.Session() as session:
    _ = session.observe(url="https://duckduckgo.com")
# Save the replay to a file
replay = session.replay()
replay.save("replay.webp")

```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.lumiteh.com/intro/sdk-python.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.