# patchy631/stagehand architecture

> Architecture diagram of the GitHub repository patchy631/stagehand, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/patchy631/stagehand
- Repository: https://github.com/patchy631/stagehand

## Overview

##### Main Components and Their Roles
- Core Automation Layer: Represent the “Stagehand” core that extends Playwright functionality. This resides in the lib folder (with files such as StagehandPage.ts, api.ts, inference.ts, prompt.ts, etc.) which encapsulates the core APIs (act, extract, observe).
- AI & LLM Integration: Highlight the LLM clients (OpenAIClient, AnthropicClient, CerebrasClient) found in lib/llm. This is where natural language understanding is integrated into your automation APIs.
- Evaluation and Testing Suite: Illustrate the “evals” directory (including deterministic tests, tasks, and configuration files) which is used to ensure the reliability and determinism of the automation flows.
- Task Modules: In “evals/tasks” you have a set of task scripts (e.g., amazon_add_to_cart.ts, simple_google_search.ts, etc.). Represent these as specific automation workflows or use cases that are built on top of the core functionalities.
- Examples and External Clients: Represent the “examples” directory and “external_clients” as sample implementations that demonstrate how to integrate Stagehand’s capabilities (including integration with tools like Langchain and Ollama).

##### Architectural Patterns and Design Principles
- Layered Architecture: Emphasize the separation between the core automation logic (the “lib” folder), testing and task orchestration (the “evals” folder), and integration/demos (the “examples” folder).
- Modularity & Extensibility: Show how different AI clients and task modules are decoupled. This modular design is vital for adding new functionalities, like additional LLM providers or new tasks, without impacting the core.
- Determinism and Testing: Call out the role of deterministic test configurations present in “evals/deterministic” to enforce repeatability and self-healing automation routines.

##### Relevant Technologies, Frameworks, and Libraries
- Node.js (runtime environment)
- Playwright (for browser automation)
- Zod (for schema validation, as referenced in the examples and indirectly in the “extract” API)
- Various LLM provider SDKs (OpenAI, Anthropic, Cerebras)
- Testing frameworks integrated via Playwright configurations

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global User
    UC["User Code/Script\n(Writes automation instructions)"]:::user

    %% Core Automation Layer Subgraph
    subgraph "Core Automation Layer"
        SP["StagehandPage (extends Playwright's Page)"]:::core
        API["API (act, extract, observe)"]:::core
        INF["Inference"]:::core
        PMT["Prompt"]:::core
    end

    %% Playwright Integration Subgraph
    subgraph "Playwright Engine"
        PW["Browser Automation"]:::engine
        PC["Playwright Config"]:::engine
    end

    %% AI & LLM Integration Subgraph
    subgraph "LLM Clients"
        OA["OpenAIClient"]:::llm
        AC["AnthropicClient"]:::llm
        CC["CerebrasClient"]:::llm
    end

    %% Evaluation and Testing Suite Subgraph
    subgraph "Evaluation & Task Modules"
        DS["Deterministic Suite"]:::eval
        TM["Task Modules"]:::eval
    end

    %% Examples and External Clients Subgraph
    subgraph "Examples & External Clients"
        EX["Examples"]:::examples
        EC["External Clients"]:::examples
    end

    %% Relationships
    UC -->|"writes"| API
    API -->|"triggers-browser-actions"| PW
    API -->|"processes"| OA
    API -->|"processes"| AC
    API -->|"processes"| CC
    API -->|"feedback"| DS
    API -->|"feedback"| TM
    UC -->|"uses-demonstrated"| EX
    EX -->|"integrates-with"| EC
    EC -->|"interfaces with"| API

    %% Click Events for Core Automation Layer
    click SP "https://github.com/patchy631/stagehand/blob/main/lib/StagehandPage.ts"
    click API "https://github.com/patchy631/stagehand/blob/main/lib/api.ts"
    click INF "https://github.com/patchy631/stagehand/blob/main/lib/inference.ts"
    click PMT "https://github.com/patchy631/stagehand/blob/main/lib/prompt.ts"

    %% Click Event for Playwright Integration
    click PW "https://github.com/patchy631/stagehand/blob/main/lib/StagehandPage.ts"
    click PC "https://github.com/patchy631/stagehand/blob/main/evals/deterministic/bb.playwright.config.ts"

    %% Click Events for AI & LLM Integration
    click OA "https://github.com/patchy631/stagehand/blob/main/lib/llm/OpenAIClient.ts"
    click AC "https://github.com/patchy631/stagehand/blob/main/lib/llm/AnthropicClient.ts"
    click CC "https://github.com/patchy631/stagehand/blob/main/lib/llm/CerebrasClient.ts"

    %% Click Events for Evaluation and Testing Suite
    click DS "https://github.com/patchy631/stagehand/tree/main/evals/deterministic"
    click TM "https://github.com/patchy631/stagehand/tree/main/evals/tasks"

    %% Click Events for Examples and External Clients
    click EX "https://github.com/patchy631/stagehand/tree/main/examples"
    click EC "https://github.com/patchy631/stagehand/tree/main/examples/external_clients"

    %% Styles
    classDef user fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef core fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef engine fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef llm fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef eval fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef examples fill:#ffe6b3,stroke:#b36b00,stroke-width:2px;
```
