Athesa

State-driven web automation framework for complex workflows

Athesa is a protocol-oriented Python framework for building maintainable web automation processes using state machines, screen detection, and declarative action sequences.

---

✨ Features

• 🎯 State Machine Architecture - Clear workflow definition with explicit state transitions
• 🔍 Smart Screen Detection - Robust page state detection with multiple strategies
• 🔌 Pluggable Adapters - Support for Selenium, Playwright, and custom automation tools
• 📦 Protocol-Oriented - Duck typing with Python protocols, no forced inheritance
• 🎪 Event System - Built-in event emitter (no PyQt/GUI dependencies)
• 🏭 Process Factory - Registry for managing and discovering automation processes
• Testable - Clean separation of concerns, easy to unit test

---

Quick Start

Installation

pip install athesa

Basic Example

from athesa import ProcessRunner, ProcessContext
from athesa.adapters.selenium import SeleniumBridge
from selenium import webdriver

# Setup browser
driver = webdriver.Chrome()
bridge = SeleniumBridge(driver)

# Create context
context = ProcessContext(
    credentials={'username': 'user@example.com', 'password': 'secret'}
)

# Run process
from my_processes import LoginProcess
process = LoginProcess()
runner = ProcessRunner(process, context, bridge)
outcome = runner.run()

print(f"Result: {outcome}")  # 'success', 'failure', or 'retry'
driver.quit()

---

📖 Documentation

• Getting Started - Introduction and setup
• API Reference - Complete API documentation
• Quick Reference - Common patterns and snippets
• Examples - Working examples

---

🎓 Core Concepts

Process

A complete workflow from start to finish. Defines screens, handlers, states, and transitions.

State

A step in your workflow. Each state knows what screens to expect.

Screen

A detectable page state using selectors and verification criteria.

Handler

Actions to perform when a screen is detected.

Bridge

Abstraction layer for browser automation (Selenium, Playwright, custom).

---

💡 Why Athesa?

Problem: Web automation is brittle. Pages change, flows have edge cases, errors are hard to debug.

Solution: Athesa uses explicit state machines and screen detection:

• ✅ Clear state transitions make debugging easy
• ✅ Multiple detection strategies handle dynamic pages
• ✅ Process registry allows flow composition
• ✅ Event system provides observability
• ✅ Protocol-based (no forced inheritance)

---

🏗️ Architecture

┌─────────────────────────────────────────┐
│         Your Process Definition         │
│  (States, Screens, Handlers)           │
└──────────────┬──────────────────────────┘
               │
       ┌───────▼────────┐
       │ ProcessRunner  │
       └───────┬────────┘
               │
    ┌──────────┼──────────┐
    │          │          │
┌───▼───┐  ┌──▼──┐  ┌───▼────┐
│State  │  │Page │  │Action  │
│Machine│  │Det. │  │Executor│
└───┬───┘  └──┬──┘  └───┬────┘
    │         │         │
    └─────────┼─────────┘
              │
        ┌─────▼─────┐
        │  Bridge   │
        │ (Selenium)│
        └───────────┘

---

Contributing

Contributions are welcome! Please read CONTRIBUTING.md first.

---

📝 License

MIT License - see LICENSE file

---

Acknowledgments

Built with ❤️ for the automation community.

---

Athesa - Smooth automation flows, state by state.